RGBASM(5) File Formats Manual RGBASM(5) rgbasm - Game Boy (DESCRIPTION) rgbasm(1) . Game Boy gbz80(7) . Game Boy . RGBDS Game Boy . Game Boy . "" rgblink(1) RGBDS ( rgbds(5)) . (SYNTAX) . : o [label:] [directive] [; comment] o [label:] [instruction [:: instruction ...]] [; comment] (Directives) PRINTLN SECTION OPT. ( Labels ). IF ELIF ELSE ENDC REPT FOR ENDR MACRO ENDM . Game Boy () . ( Defining constant data in ROM ) `::' . gbz80(7) . r8 HIGH(r16) r16 HIGH(HL) H LOW(r16) LOW(HL) L ( LOW(AF ) F ). cc !cc !nz z. ( ) (case- insensitive) ( ) (case-sensitive). (Comments) . . : . `;' . `/*' `*/' . : SECTION "My Code", ROM0 ; a directive MyFunction: ; a label push hl ; an instruction /* ...and multiple instructions, with mixed case */ ld a, [hli] :: LD H, [HL] :: Ld l, a pop /*wait for it*/ hl ret . : DB 1, 2, 3, \ 4, 5, 6, \ ; Put it before any comments 7, 8, 9 DB "Hello, \ ; Space before the \ is included world!" ; Any leading space is included (Symbol interpolation) `{braces}' "" (interpolated). . . `$' . . DEF topic EQUS "life, the universe, and \"everything\"" DEF meaning EQUS "answer" ; Defines answer = 42 DEF {meaning} = 42 ; Prints "The answer to life, the universe, and "everything" is $2A" PRINTLN "The {meaning} to {topic} is {{meaning}}" PURGE topic, meaning, {meaning} : `name' `DEF({name}) ' `DEF {name} EQU/=/EQUS/etc ... ' `REDEF {name} EQU/=/EQUS/etc ... ' `FOR {name}, ... ' `PURGE {name} ' `MACRO {name}' `DEF(name) ' `PURGE {name}' . : `{fmt:symbol}'. `fmt' : `'. `' . : Part Meaning `' `+' `.' . `' `#' ( ). <<>> : (`$' `&' `%') (`x' / `X' `o' `b' ) `q' `\' ( ) . `' `-' . . `' `0' . . `' `0' - `9' . . `' `.' `0' - `9' . . . ( `.' `0' - `9' .) `' `q' `0' - `9' . . -Q . `' . : Type Format Example `d' -42 `u' 4294967254 `x' 2a `X' 2A `b' () 101010 `o' () 52 `f' 1234.56789 `s' string contents : SECTION "Test", ROM0[2] X: ; This works with labels **whose address is known** DEF Y = 3 ; This also works with variables DEF SUM EQU X + Y ; And likewise with numeric constants ; Prints "%0010 + $3 == 5" PRINTLN "{#05b:X} + {#x:Y} == {d:SUM}" rsset 32 DEF PERCENT rb 1 ; Same with offset constants DEF VALUE = 20 DEF RESULT = MUL(20.0, 0.32) ; Prints "32% of 20 = 6.40" PRINTLN "{d:PERCENT}% of {d:VALUE} = {f:RESULT}" DEF WHO EQUS STRLWR("WORLD") ; Prints "Hello world!" PRINTLN "Hello {s:WHO}!" STRFMT String expressions . (EXPRESSIONS) : . . <<>> (false) ( ) <<>> (true) . <<>> . SYMBOLS . Operators . : REPT (assembly time) . (Numeric literals) . Format type Prefixes Accepted characters 0123456789 $, 0x, 0X 0123456789ABCDEF &, 0o, 0O 01234567 %, 0b, 0B 01 01234.56789 12.34q8 'A' Game Boy ` 0123 (_) . `123_456' `%1100_1001'. << >> (charmap) . ( ascii(7) ) `'A'' . . Character maps String expressions . Game Boy . . ``01012323' `$0F55' . . (Operators) ( ): Operator Meaning ( ) FUNC() ** + - ~ ! () ( ) * / % ( ) () << >> >>> ( ) & | ^ AND/OR/XOR + - == != < > <= >= && AND || OR `**' . `p ** q ** r' `p ** (q ** r) ' `(p ** q) ** r'. . `~' . `%' `x / y * y + x % y == x' . . `x % y' `(x + y) % y' `(x - y) % y' . (`<<') (`>>') . . `a << b' `a >> b' b . . `&&' `||' . `&&' `&' `||' . `!' . . (Integer functions) : Name Operation HIGH(n) `(n & $FF00) >> 8'. LOW(n) `n & $FF'. BITWIDTH(n) n . : BITWIDTH(n) - 1 |_ log_2 (n) _| BITWIDTH(n - 1) |~ log_2 (n) ~| 32 - BITWIDTH(n) clz (n) n . TZCOUNT(n) ctz (n) n . (Fixed-point expressions) ( ). ( ). (65536ths) . . -Q / OPT Q ( Changing options while assembling ). "q" : `789.25q8' $000315_40 (= 789.25 * 2^8) . . . (truncate). . . `123.0 / 1.0 == 123 ' `123 * 1.0 == 123.0'. TZCOUNT(1.0) . ( ): Name Operation DIV(x, y) MUL(x, y) FMOD(x, y) POW(x, y) x^y LOG(x, y) x y ROUND(x) x ( ) CEIL(x) x FLOOR(x) x SIN(x) x COS(x) x TAN(x) x ASIN(x) x ACOS(x) x ATAN(x) x ATAN2(y, x) (x, y) (1, 0) `+' `-' . . `2.0 * 3' `MUL(2.0, 3.0)' `6.0 / 2' `DIV(6.0, 2.0)' . . . `MUL(6.0q8, 7.0q8, 8)' Q `42.0q8' . `MUL(4.2q8, 6.9q12, 16)' ( ) : " (garbage in, garbage out)". FMOD . `%' ! (SIN COS TAN ) . " (turn)" ( 2 ) . . : ; Generate a table of 128 sine values ; from sin(0.0) included to sin(0.5) excluded, ; with amplitude scaled from [-1.0, 1.0] to [0.0, 128.0], ; then divided by 1.0 to round down to integer values. FOR angle, 0.0, 0.5, 0.5 / 128 db MUL(SIN(angle) + 1.0, 128.0 / 2) / 1.0 ENDR (String expressions) : (`"for instance"'). `\' " (escaped) " . : Sequence Meaning `\\' ( ) `\"' ( ) `\'' ( ) `\{' ( ) `\}' ( ) `\n' (ASCII $0A) `\r' (Carriage return) (ASCII $0D) `\t' (ASCII $09) `\0' (ASCII $00) (`"""for instance"""'). `\r' `\n'. `#' . . `#"\t\1{s}\"' `"\\t\\1\{s}\\"' . ( .) ( ). `++' . `"str" ++ "ing"' `"string" ' `STRCAT("str", "ing")' . `===' `!==' . `"str" === "ing"' `STRCMP("str", "ing") == 0 ' `"str" !== "ing"' `STRCMP("str", "ing") != 0' . : Name Operation STRCAT(strs...) strs . STRUPR(str) str (`a-z') . STRLWR(str) str (`A-Z') . STRSLICE(str, start, stop) str start stop () . stop str . STRRPL(str, old, new) str old new . STRFMT(fmt, args...) fmt `%spec' spec ( Symbol interpolation) args (`%%' `%' ). STRCHAR(str, idx) str idx . (idx .) : REVCHAR(vals...) vals . vals . READFILE(name, max) name . max max . include -I - rgbasm(1) . : Name Operation STRLEN(str) str . STRCMP(str1, str2) str1 str2 . str1 str2 -1 str1 str2 1 0 . STRFIND(str, sub) sub str -1 . STRRFIND(str, sub) sub str -1 . BYTELEN(str) str . ( .) STRBYTE(str, idx) idx str . INCHARMAP(str) str 1 0 . CHARLEN(str) str . CHARCMP(str1, str2) str1 str2 . str1 str2 -1 str1 str2 1 0 . CHARSIZE(char) char . CHARVAL(char, idx) idx char . idx char . - . `STRLEN ' `CHARLEN ' `CHARSIZE' . (Character maps) Game Boy ROM . . : CHARMAP "A", 42 CHARMAP ':)', 39 CHARMAP "
", 13, 10 CHARMAP '€', $20ac `db "Amen :)
"' `db 42, 109, 101, 110, 32, 39, 13, 10 ' `dw "25€"' `dw 50, 53, $20ac' . (greedily) . . . . `main' . . Command Meaning NEWCHARMAP name name . NEWCHARMAP name, basename name basename . SETCHARMAP name name . PUSHC (push). PUSHC name name . POPC (pop) . : . (Other functions) : Name Operation DEF(symbol) symbol . . ISCONST(arg) arg RGBASM ( IF ) RGBLINK . BANK(arg) . arg @ . arg . arg . . SECTION(symbol) symbol . symbol . arg @ . SIZEOF(arg) arg arg . arg . RGBLINK . arg . STARTOF(arg) arg arg . arg . RGBLINK . (SECTIONS) . . SECTION name, type SECTION name, type, options SECTION name, type[addr] SECTION name, type[addr], options name . . . type : ROM0 ROM. addr $0000 $3FFF $0000 $7FFF tiny ROM . ROMX ROM (banked). addr $4000 $7FFF . tiny ROM ROM0 . VRAM (VRAM) . addr $8000 $9FFF . bank DMG . SRAM () . addr $A000 $BFFF . WRAM0 (general-purpose RAM). addr $C000 $CFFF $C000 $DFFF WRAM0 . WRAMX . addr $D000 $DFFF . bank . WRAM0 WRAM0 . OAM (OAM). addr $FE00 $FE9F . HRAM (High RAM). addr $FF80 $FFFE . RGBDS (ROMs) ROM0 ROMX . RAM . RAM ROM RAM . LOAD RAM code . option : BANK[bank] bank . bank type . ALIGN[align, offset] align offset . ALIGN[align] ALIGN[align, 0] . [addr] . Requesting alignment . [addr] " (floating)" . BANK[bank] . . rgblink(5) . . . : SECTION "Cool Stuff", ROMX "Cool Stuff" . ROM . . : SECTION "Cool Stuff", ROMX[$4567] : SECTION "Cool Stuff", ROMX[$4567], BANK[3] : SECTION "Cool Stuff", ROMX, BANK[7] : OAM DMA . GBC HDMA . SECTION "OAM Data", WRAM0, ALIGN[8] ; align to 256 bytes SECTION "VRAM Data", ROMX, BANK[2], ALIGN[4] ; align to 16 bytes ENDSECTION . . . (Section stack) POPS PUSHS . . PUSHS (push). POPS . include include . PUSHS SECTION : SECTION "Code", ROM0 Function: ld a, 42 PUSHS "Variables", WRAM0 wAnswer: db POPS ld [wAnswer], a (RAM code) ( ) RAM (self-modifying code). RAM ROM RAM . . LOAD . : SECTION "LOAD example", ROMX CopyCode: ld de, RAMCode ld hl, RAMLocation ld c, RAMCode.end - RAMCode .loop ld a, [de] inc de ld [hli], a dec c jr nz, .loop ret RAMCode: LOAD "RAM code", WRAM0 RAMLocation: ld hl, .string ld de, $9864 .copy ld a, [hli] ld [de], a inc de and a jr nz, .copy ret .string db "Hello World!\0" ENDL .end LOAD SECTION . . "LOAD example" . `RAMCode' `RAMLocation' . ROM RAM . LOAD . LOAD ENDL . ROM . LOAD SECTION ENDSECTION POPS LOAD . LOAD UNION FRAGMENT Unionized sections . (Unionized sections) RAM Allocating overlapping spaces in RAM . UNION . (Unionized sections) . UNION SECTION . : o ( ) . . o . o . -w rgblink(1) WRAM0 WRAMX . o ( ) . . o ROM0 ROMX . Allocating overlapping spaces in RAM . . (Section fragments) (Section fragments) : . ( <<>> ) . FRAGMENT SECTION . Unionized sections : o . o . -w rgblink(1) WRAM0 WRAMX . o ( ) . . o (unionized) . RGBASM . RGBLINK . `bar.o ' `baz.o ' `foo.o' rgblink -o rom.gb baz.o foo.o bar.o `baz.o ' `foo.o ' `bar.o' . (Fragment literals) (Fragment literals) . `[[' `]]' SECTION FRAGMENT. SECTION FRAGMENT ROM . FRAGMENT . RGBLINK . `n16' gbz80(7) DW . . CALL JP . : DataTable: dw First dw Second dw Third First: db 1 Second: db 4 Third: db 9 Routine: push hl ld hl, Left jr z, .got_it ld hl, Right .got_it call .print pop hl ret .print: ld de, $1003 ld bc, STARTOF(VRAM) jp Print Left: db "left\0" Right: db "right\0" : DataTable: dw [[ db 1 ]] dw [[ db 4 ]] dw [[ db 9 ]] Routine: push hl ld hl, [[ db "left\0" ]] jr z, .got_it ld hl, [[ db "right\0" ]] .got_it call [[ ld de, $1003 ld bc, STARTOF(VRAM) jp Print ]] pop hl ret . . : dw FortyTwo FortyTwo: call Sub1 jr Sub2 Sub1: ld a, [Twenty] ret Twenty: db 20 Sub2: jp Sub3 Sub3: call Sub1 inc a add a ret : dw [[ call [[ Sub1: ld a, [ [[db 20]] ] :: ret ]] jr [[ jp [[ call Sub1 :: inc a :: add a :: ret ]] ]] ]] (SYMBOLS) RGBDS : (Label) . . (Constant) . (Macro) . (String) . `_ ' `# ' `$ ' `@' . . `.' . " " `#' . `#load' `load' `#LOAD' `LOAD' `#' LOAD . (Labels) "" . : . ( ). (). ( ) `::' (EXPORT) . ( (Exporting and importing symbols) ). . `.' ( " " (Exporting and importing symbols) ). . : ( ) " " . " " . : GlobalLabel: AnotherGlobal: .locallabel ; This defines "AnotherGlobal.locallabel" .another_local: AnotherGlobal.with_another_local: ThisWillBeExported:: ; Note the two colons ThisWillBeExported.too:: . ( `BANK()' Other functions ). `ld de, vPlayerTiles' `ld de, $80C0' $80C0 : SECTION "Player tiles", VRAM vPlayerTiles: ds 6 * 16 .end ( ) . . `PlayerTiles' `PlayerTiles.end' . (Anonymous labels) . . . `:' `+' `-' . :+ :++ :- . ld hl, :++ : ld a, [hli] ; referenced by "jr nz" ldh [c], a dec c jr nz, :- ret : ; referenced by "ld hl" dw $7FFF, $1061, $03E0, $58A5 (Variables) `=' . . . DEF ARRAY_SIZE EQU 4 DEF COUNT = 2 DEF COUNT = 3 DEF COUNT = ARRAY_SIZE + COUNT DEF COUNT *= 2 ; COUNT now has the value 14 `:' . C : += -= / *= /= %= // <<= >>= / &= = ^= and/or/xor : DEF x = 10 DEF x += 1 ; x == 11 DEF y = x - 1 ; y == 10 DEF y *= 2 ; y == 20 DEF y >>= 1 ; y == 10 DEF x ^= y ; x == 1 EXPORT DEF EXPORT REDEF (EXPORT) . ( (Exporting and importing symbols) ). (Numeric constants) EQU . `=' . . def SCREEN_WIDTH equ 160 ; In pixels def SCREEN_HEIGHT equ 144 `:' . REDEF . ( .) . def NUM_ITEMS equ 0 MACRO add_item redef NUM_ITEMS equ NUM_ITEMS + 1 def ITEM_{02x:NUM_ITEMS} equ \1 ENDM add_item 1 add_item 4 add_item 9 add_item 16 assert NUM_ITEMS == 4 assert ITEM_04 == 16 EXPORT DEF EXPORT REDEF (EXPORT) . ( (Exporting and importing symbols) ). (Offset constants) RS : RSRESET DEF str_pStuff RW 1 DEF str_tData RB 256 DEF str_bCount RB 1 DEF str_SIZEOF RB 0 : DEF str_pStuff EQU 0 DEF str_tData EQU 2 DEF str_bCount EQU 258 DEF str_SIZEOF EQU 259 RS : RSRESET `RSSET 0'. RSSET constexpr _RS constexpr . DEF name RB constexpr name _RS constexpr _RS . DEF name RW constexpr name _RS constexpr * 2 _RS . DEF name RL constexpr name _RS constexpr * 4 _RS . constexpr RB RW RL 1 . `:' . EXPORT DEF (EXPORT) . ( (Exporting and importing symbols) ). (String constants) EQUS . : #define C. : `DEF(name) ' `DEF name EQU/=/EQUS/etc ... ' `REDEF name EQU/=/EQUS/etc ... ' `FOR name, ... ' `PURGE name ' `MACRO name' . `#' . DEF COUNTREG EQUS "[hl+]" ld a, COUNTREG DEF PLAYER_NAME EQUS "\"John\"" db PLAYER_NAME : ld a, [hl+] db "John" : DEF pusha EQUS "push af\npush bc\npush de\npush hl\n" `:' . . REDEF . : DEF s EQUS "Hello, " REDEF s EQUS "{s}world!" ; prints "Hello, world!" PRINTLN "{s}\n" . : . ( -r rgbasm(1) ). . (Macros) . IF . MACRO my_macro ld a, 80 call MyFunc ENDM `my_macro' . . . : MACRO outer MACRO inner PRINTLN "Hello!" ENDM ; this actually ends the 'outer' macro... ENDM ; ...and then this is a syntax error! EQUS : MACRO outer DEF definition EQUS "MACRO inner\nPRINTLN \"Hello!\"\nENDM" definition PURGE definition ENDM (THE MACRO LANGUAGE) . (Exporting and importing symbols) . . symbol1 symbol2 : EXPORT symbol1 [, symbol2, ...] : `a.asm': SECTION "a", WRAM0 LabelA: `b.asm': SECTION "b", WRAM0 ExportedLabelB1:: ExportedLabelB2: EXPORT ExportedLabelB2 `c.asm': SECTION "C", ROM0[0] dw LabelA dw ExportedLabelB1 dw ExportedLabelB2 `c.asm' `ExportedLabelB1' `ExportedLabelB2' `LabelA' : $ rgbasm -o a.o a.asm $ rgbasm -o b.o b.asm $ rgbasm -o c.o c.asm $ rgblink a.o b.o c.o error: Undefined symbol "LabelA" at c.asm(2) Linking failed with 1 error (Purging symbols) PURGE . DEF value EQU 42 PURGE value DEF value EQUS "I'm a string now" ASSERT DEF(value) PURGE value ASSERT !DEF(value) ( ) . . . (Predeclared symbols) : @ EQU PC ( ) . EQUS .. EQUS __SCOPE__ EQUS (. ..) _RS = _RS _NARG EQU SHIFT __ISO_8601_LOCAL__ EQUS ISO 8601 () __ISO_8601_UTC__ EQUS ISO 8601 (UTC) __UTC_YEAR__ EQU __UTC_MONTH__ EQU 1-12 __UTC_DAY__ EQU 1-31 __UTC_HOUR__ EQU 0-23 __UTC_MINUTE__ EQU 0-59 __UTC_SECOND__ EQU 0-59 __RGBDS_MAJOR__ EQU RGBDS __RGBDS_MINOR__ EQU RGBDS __RGBDS_PATCH__ EQU RGBDS __RGBDS_RC__ EQU RGBDS __RGBDS_VERSION__ EQUS RGBDS `rgbasm --version ' SOURCE_DATE_EPOCH . reproducible-builds.org: https://reproducible-builds.org/docs/source-date-epoch . (DEFINING DATA) ROM (Defining constant data in ROM) DB . . DB 1,2,3,4,"This is a string" DW (16 ) DL / (32 ) . (little- endian) `dw $CAFE' `db $FE, $CA' `db $CA, $FE'. : ( Character maps ) . : DW "Hello!" DW "H", "e", "l", "l", "o", "!" . DS . : ; outputs 3 bytes: $AA, $AA, $AA DS 3, $AA ; outputs 7 bytes: $BB, $CC, $BB, $CC, $BB, $CC, $BB DS 7, $BB, $CC DB DW DL . DS 1 DS 2 DS 4 . DB DW DL WRAM0 / WRAMX / HRAM / VRAM / SRAM . (Including binary data files) . INCBIN . -I rgbasm(1) . INCBIN "titlepic.bin" INCBIN "sprites/hero.bin" INCBIN . 256 data.bin 78 . INCBIN "data.bin", 78, 256 . . RAM (Statically allocating space in RAM) DS . RAM . DB DW DL ( ROM (Defining constant data in ROM) ). DS 42 ; Allocates 42 bytes RAM . ROM -p -O. ALIGN[align, offset] . `DS ALIGN[align, offset], ...' `DS n, ...' `ALIGN[align, offset]' n ALIGN ( (Requesting alignment) ). ALIGN[align] ALIGN[align, 0] . RAM (Allocating overlapping spaces in RAM) union C. . UNION ENDU . NEXTU . ; Let's say PC == $C0DE here UNION ; Here, PC == $C0DE wName:: ds 10 ; Now, PC == $C0E8 wNickname:: ds 10 ; PC == $C0F2 NEXTU ; PC is back to $C0DE wHealth:: dw ; PC == $C0E0 wLives:: db ; PC == $C0E1 ds 7 ; PC == $C0E8 wBonus:: db ; PC == $C0E9 NEXTU ; PC is back to $C0DE again wVideoBuffer: ds 16 ; PC == $C0EE ENDU ; Afterward, PC == $C0F2 `wName wHealth ' `wVideoBuffer' `wNickname' `wBonus'. `ld [wHealth], a' `ld [wName], a' . 20 ( `wName' `wNickname'). . DS ( RAM (Statically allocating space in RAM) ). (Requesting alignment) ALIGN SECTIONS ( ) . ALIGN align, offset . ALIGN align offset . ( ) . ALIGN align ALIGN align, 0 . . DS ALIGN[align, offset] . . ALIGN[align] ALIGN[align, 0] . (THE MACRO LANGUAGE) (Invoking macros) . add a, b ld sp, hl my_macro ; This will be expanded sub a, 87 my_macro 42 ; So will this ret c my_macro 1, 2 ; And this ( MACRO ENDM) . : . ( -r rgbasm(1) ). . ! MACRO lb ld \1, (\2) << 8 | (\3) ENDM lb hl, 20, 18 ; Expands to "ld hl, ((20) << 8) | (18)" lb de, 3 + 1, NUM**2 ; Expands to "ld de, ((3 + 1) << 8) | (NUM**2)" \1 \9 \1 \2 . . \<10>. . `\<_NARG>' `\<-1>' . . `\1' `13' `\<\1>' `\<13>' . `DEF v10 = 42' `DEF x = 10' `\' `\<42>' . . . ( String expressions ) : `\,' ( ) `\(' ( ) `\)' ( ) . : MACRO PrintMacro1 PRINTLN STRCAT(\1) ENDM PrintMacro1 "Hello "\, \ "world" MACRO PrintMacro2 PRINT \1 ENDM PrintMacro2 STRCAT("Hello ", \ "world\n") `PrintMacro1' . `PrintMacro2' C. `\n' . . : MACRO print_double PRINTLN \1 * 3 ENDM print_double 1 + 2 `PRINTLN 1 + 2 * 3' 7 9 . SHIFT . \2 \1 \3 \2 . ( \1 _NARG 1 .) SHIFT . . SHIFT REPT . : `\1' - `\9' - `\<...>' `\#' _NARG `\@' ( ) \@ . : MACRO loop_c_times xor a, a .loop ld [hl+], a dec c jr nz, .loop ENDM `.loop' . \@ : MACRO loop_c_times_fixed xor a, a .loop\@ ld [hl+], a dec c jr nz, .loop\@ ENDM gensym Lisp. \@ REPT . (Automatically repeating blocks of code) (unroll ). REPT . REPT ENDR / . `add a, c' : REPT 4 add a, c ENDR REPT : ; Generate a table of square values from 0**2 = 0 to 100**2 = 10000 DEF x = 0 REPT 101 dw x * x DEF x += 1 ENDR \@ . REPT . . FOR REPT . FOR ENDR . . 0 255 : FOR N, 256 dw N * N ENDR : DEF N = 0 dw N * N DEF N = 1 dw N * N DEF N = 2 dw N * N ; ... DEF N = 255 dw N * N DEF N = 256 FOR `range' Python: FOR V, stop V 0 stop FOR V, start, stop V start stop FOR V, start, stop, step V start stop step FOR step stop start () stop () . V FOR . V FOR ( (Variables)) . : FOR V, 4, 25, 5 PRINT "{d:V} " DEF V *= 2 ENDR PRINTLN "done {d:V}" : 4 9 14 19 24 done 29 REPT \@ FOR . BREAK . BREAK REPT FOR . ENDR . : FOR V, 1, 100 PRINT "{d:V}" IF V == 5 PRINT " stop! " BREAK ENDC PRINT ", " ENDR PRINTLN "done {d:V}" : 1, 2, 3, 4, 5 stop! done 5 (Conditionally assembling blocks of code) IF ELIF ELSE ENDC . . IF NUM < 0 PRINTLN "NUM < 0" ELIF NUM == 0 PRINTLN "NUM == 0" ELSE PRINTLN "NUM > 0" ENDC ELIF ( "else if") ELSE . IF / ELIF / ELSE / ENDC . ELSE ELIF ELIF . ELIF ELSE . ELSE . (Including other source files) INCLUDE . -I rgbasm(1) . INCLUDE ( ). INCLUDE "irq.inc" -P rgbasm(1) (INCLUDE) . (Printing things during assembly) PRINT PRINTLN . . PRINT "Hello world!\n" PRINTLN "Hello world!" PRINT _NARG, " arguments\n" PRINTLN "sum: ", 2+3, " product: ", 2*3 PRINTLN STRFMT("E = %f", 2.718) PRINT . `$' . STRFMT . PRINTLN (`\n') . (Aborting the assembly process) FAIL WARN . . FAIL WARN . FAIL WARN . ASSERT STATIC_ASSERT . : Function: xor a ASSERT LOW(MyByte) == 0 ld h, HIGH(MyByte) ld l, a ld a, [hli] ; You can also indent this! ASSERT BANK(OtherFunction) == BANK(Function) call OtherFunction ; Lowercase also works ld hl, FirstByte ld a, [hli] assert FirstByte + 1 == SecondByte ld b, [hl] ret .end ; If you specify one, a message will be printed STATIC_ASSERT .end - Function < 256, "Function is too large!" ASSERT STATIC_ASSERT RGBASM RGBLINK RGBASM . RGBASM STATIC_ASSERT . (assertion) . WARN FAIL FATAL ASSERT STATIC_ASSERT . WARN ( -Wassert rgbasm(1)) FAIL ( ) FATAL . (MISCELLANEOUS) (Changing options while assembling) OPT . (rgbasm(1) ). OPT : PUSHO OPT g.oOX, Wdiv ; acts like command-line `-g.oOX -Wdiv` OPT -Wdiv ; dashes before the options are optional DW `..ooOOXX ; uses the graphics constant characters from OPT g PRINTLN $80000000/-1 ; prints a warning about division POPO DW `00112233 ; uses the default graphics constant characters PRINTLN $80000000/-1 ; no warning by default OPT b g p Q r W . POPO PUSHO . PUSHO (push ). POPO . . . PUSHO : PUSHO b.#, g.oO# DB %..####.. DW `..ooOO## POPO (Excluding locations from backtraces) (backtraces) REPT FOR MACRO INCLUDE . INCLUDE . `?' (token) : `REPT? ' `FOR? ' `MACRO?' `INCLUDE? ' `?' . `example.asm' : MACRO lb assert -128 <= (\2) && (\2) < 256, "\2 is not a byte" assert -128 <= (\3) && (\3) < 256, "\3 is not a byte" ld \1, (LOW(\2) << 8) | LOW(\3) ENDM SECTION "Code", ROM0 lb hl, $123, $45 : error: Assertion failed: $123 is not a byte at example.asm::lb(2) <- example.asm(7) `MACRO' `MACRO?' `lb hl' `lb? hl' `lb' : error: Assertion failed: $123 is not a byte at example.asm(7) (SEE ALSO) rgbasm(1), rgblink(1), rgblink(5), rgbfix(1), rgbgfx(1), gbz80(7), rgbasm-old(5), rgbds(5), rgbds(7) (HISTORY) rgbasm(1) Carsten Sorensen ASMotor RGBDS Justin Lloyd . https://github.com/gbdev/rgbds . Linux 6.12.107+deb13-amd64 August 1, 2026 Linux 6.12.107+deb13-amd64