RGBASM-OLD(5)

πŸ“¦
version 1.0.4 Β· 4 versions
, in arch rolling, nixpkgs unstable

πŸŽ€ NAME πŸŽ€

rgbasm-old β€” obsolete language documentation πŸ’…

πŸ’– DESCRIPTION πŸ’–

Okay bestie, this is the lore drop: it’s the list of features that have been removed from the rgbasm(5) assembly language over its decades of evolution, along with their modern alternatives. Its whole goal is to be a reference for backwards incompatibility when you’re upgrading an old assembly codebase to work with the latest RGBDS release. It does not attempt to list every syntax bug that was ever fixed (with some notable exceptions), nor new reserved keywords that may conflict with old identifiers. No cap. ✨

πŸ—‘οΈ REMOVED πŸ—‘οΈ

These are features which have been completely removed, without any direct alternatives. Usually these features were limiting the addition of other features, or had awkward limits on their own intended effects. 😭

🚫 Automatic LD to LDH conversion (rgbasm -l)

Deprecated in 0.7.0, removed in 0.8.0.

rgbasm(1) used to automatically treat LD as LDH if the address was known to be in the $FF00-$FFFF range, with the -L flag to opt out. rgbasm(1) 0.6.0 added a -l flag to opt in instead.

Instead, use LDH, and remove the -L and -l flags from rgbasm(1). Slay. πŸ’…

🚫 Automatic NOP after HALT (rgbasm -H)

Deprecated in 0.7.0, removed in 0.8.0.

rgbasm(1) used to automatically insert a NOP after HALT, with the -h flag to opt out. rgbasm(1) 0.6.0 added a -H flag to opt in instead.

Instead, use an explicit NOP after HALT, and remove the -h and -H flags from rgbasm(1). 🫢

🧩 Nested macro definitions

Removed in 0.4.2.

Instead, put the nested macro definition inside a quoted string (making sure that none of its lines start with ENDM), then interpolate that string. For example:

             MACRO outer
                 DEF definition EQUS """
                     MACRO inner
                         println (\1) - (\\1)
                     \nENDM"""
                 {definition}
                 PURGE definition
             ENDM
                 outer 10
                 inner 3 ; prints 7

βͺ Negative DS

Removed in 0.3.2.

This was used to "rewind" the value of @ in RAM sections, allowing labeled space allocations to overlap.

Instead, use UNION. πŸ’œ

πŸ—‚οΈ Section-local charmaps

Deprecated in 0.3.9, removed in 0.4.0.

Defining a CHARMAP inside a SECTION when the current global charmap was the main one used to only define that character mapping within that SECTION.

Instead, use PUSHC and POPC and switch to a different character mapping for that section. πŸŽ€

πŸ“ __FILE__ and __LINE__

Deprecated in 0.6.0, removed in 0.7.0.

Instead, use WARN or FAIL to print a complete trace of filenames and line numbers.

πŸ₯§ _PI

Deprecated in 0.5.0, removed in 0.6.0.

Instead, use 3.141592653. Iconic. ✨

πŸ“… __DATE__ and __TIME__

Deprecated in 1.0.0.

Instead, use __ISO_8601_LOCAL__.

πŸ”’ Treating multi-character strings as numbers

Deprecated in 0.9.0, removed in 1.0.0.

Instead, use a multi-value CHARMAP, or explicitly combine the values of individual characters.

For example, instead of a multi-character string like:

                 CHARMAP "X", $12
                 CHARMAP "Y", $34
                 LD BC, "XY"

Either use a multi-value CHARMAP:

                 CHARMAP "X", $12
                 CHARMAP "Y", $34
                 CHARMAP "<XY>", 'X', 'Y'
                 LD BC, CHARVAL("<XY>", 0) << 8 | CHARVAL("<XY>", 1)

Or combine the individual characters:

                 CHARMAP "X", $12
                 CHARMAP "Y", $34
                 LD BC, 'X' << 8 | 'Y'

Or use a single-value character:

                 CHARMAP "X", $12
                 CHARMAP "Y", $34
                 CHARMAP "<XY>", 'X' << 8 | 'Y'
                 LD BC, '<XY>'

πŸ”€ Treating strings as numbers

Deprecated in 1.0.0.

Instead, use character constants or the CHARVAL function.

For example, instead of a string literal like LD A, "R", use a numeric character literal LD A, 'R'.

And instead of a string expression like CP STRUPR("\1"), use a numeric CHARVAL expression CP CHARVAL(STRUPR("\1")). πŸ¦‹

🎨 rgbgfx -f/--fix and -F/--fix-and-save

Removed in 0.6.0.

Instead, use rgbgfx -c/--colors to explicitly specify a color palette. If using -c embedded, arrange the PNG's indexed palette in a separate graphics editor.

🎨 rgbgfx -D/--debug

Removed in 0.6.0.

♻️ REPLACED ♻️

These are features whose syntax has been changed without affecting functionality. They can generally be updated with a single search-and-replace. πŸ”

🏷️ Defining constants and variables without DEF

Deprecated in 0.7.0, removed in 0.8.0.

EQU, EQUS, =, RB, RW, and RL definitions used to just start with the symbol name, but had to be typed in column 1.

Instead, use DEF before constant and variable definitions.

🫢 Note: EQUS expansion does not occur for the symbol name, so you have to use explicit {interpolation}.

🏷️ Defining macros like labels

Deprecated in 0.6.0, removed in 0.7.0.

Macros used to be defined as name: MACRO.

Instead, use MACRO name.

🫢 Note: EQUS expansion does not occur for the macro name, so you have to use explicit {interpolation}.

🏷️ Defining variables with SET

Deprecated in 0.5.2, removed in 0.6.0.

Variables used to be defined as name SET value.

Instead, use DEF name = value.

🏷️ Global labels without colons

Deprecated in 0.4.0, removed in 0.5.0.

Labels used to be definable with just a name, but had to be typed in column 1.

Instead, use explicit colons; for example, Label: or exported Label::. πŸ’…

πŸͺ„ '\,' in strings within macro arguments

Deprecated in 0.5.0, removed in 0.7.0.

Macro arguments now handle quoted strings and parenthesized expressions as single arguments, so commas inside them are not argument separators and do not need escaping.

Instead, just use commas without backslashes.

πŸ’¬ '*' comments

Deprecated in 0.4.1, removed in 0.5.0.

These comments had to have the * typed in column 1.

Instead, use ; comments.

πŸ”Ž STRIN, STRRIN, STRSUB, and CHARSUB

Deprecated in 1.0.0.

These functions used 1-based indexing of string characters, which was inconsistent with the 0-based indexing used more often in programming.

Instead of STRIN, use STRFIND; instead of STRRIN, use STRRFIND; instead of STRSUB, use STRSLICE; and instead of CHARSUB, use STRCHAR.

🫢 Note: STRSLICE takes a start and end index instead of a start index and a length.

πŸ–¨οΈ PRINTT, PRINTI, PRINTV, and PRINTF

Deprecated in 0.5.0, removed in 0.6.0.

These directives were each specific to one type of value.

Instead, use PRINT and PRINTLN, with STRFMT or {interpolation} for type-specific formatting.

πŸ”— IMPORT and XREF

Removed in 0.4.0.

Symbols are now automatically resolved if they were exported from elsewhere.

Instead, just remove these directives.

🌍 GLOBAL and XDEF

Deprecated in 0.4.2, removed in 0.5.0.

Instead, use EXPORT.

🏠 HOME, CODE, DATA, and BSS

Deprecated in 0.3.0, removed in 0.4.0.

Instead of HOME, use ROM0; instead of CODE and DATA, use ROMX; and instead of BSS, use WRAM0.

πŸ•ΉοΈ JP [HL]

Deprecated in 0.3.0, removed in 0.4.0.

Instead, use JP HL.

πŸ•ΉοΈ LDI A, HL and LDD A, HL

Deprecated in 0.3.0, removed in 0.4.0.

Instead, use LDI A, [HL] and LDD A, [HL] (or LD A, [HLI] and LD A, [HLD]; or LD A, [HL+] and LD A, [HL-]). πŸ”₯

πŸ•ΉοΈ LDIO

Deprecated in 0.9.0, removed in 1.0.0.

Instead, use LDH.

πŸ•ΉοΈ LD [C], A and LD A, [C]

Deprecated in 0.9.0, removed in 1.0.0.

Instead, use LDH [C], A and LDH A, [C].

🫢 Note: LD [$FF00+C], A and LD A, [$FF00+C] were also deprecated in 0.9.0, but were undeprecated in 0.9.1.

πŸ•ΉοΈ LDH [n8], A and LDH A, [n8]

Deprecated in 0.9.0, removed in 1.0.0.

LDH used to treat "addresses" from $00 to $FF as if they were the low byte of an address from $FF00 to $FFFF.

Instead, use LDH [n16], A and LDH A, [n16].

πŸ•ΉοΈ LD HL, [SP + e8]

Deprecated in 0.3.0, removed in 0.4.0.

Instead, use LD HL, SP + e8.

πŸ•ΉοΈ LDHL SP, e8

Supported in ASMotor, removed in RGBDS.

Instead, use LD HL, SP + e8.

βš™οΈ OPT z

Deprecated in 0.4.0, removed in 0.5.0.

Instead, use OPT p.

βš™οΈ rgbasm -i

Deprecated in 0.6.0, removed in 0.8.0.

Instead, use -I or --include.

βš™οΈ rgbfix -O/--overwrite

Deprecated in 1.0.0.

Instead, use -Wno-overwrite.

βš™οΈ rgbgfx -h/--horizontal

Removed in 0.6.0.

Instead, use -Z or --columns.

βš™οΈ rgbgfx --output-*

Deprecated in 0.7.0, removed in 0.8.0.

Instead, use --auto-*.

πŸ”₯ CHANGED πŸ”₯

These are breaking changes that did not alter syntax, and so could not practically be deprecated. πŸ’€

πŸ“ Trigonometry function units

Changed in 0.6.0.

Instead of dividing a circle into 65536.0 "binary degrees", it is now divided into 1.0 "turns".

For example, previously we had:

  • SIN(0.25) == 0.00002, because 0.25 binary degrees = 0.25/65536.0 turns = 0.000004Ο„ radians = 0.000008Ο€ radians, and sin(0.000008Ο€)=0.00002
  • SIN(16384.0) == 1.0, because 16384.0 binary degrees = 16384.0/65536.0 turns = 0.25Ο„ radians = Ο€/2 radians, and sin(Ο€/2)=1
  • ASIN(1.0) == 16384.0

Instead, now we have:

  • SIN(0.25) == 1.0, because 0.25 turns = 0.25Ο„ radians = Ο€/2 radians, and sin(Ο€/2)=1
  • SIN(16384.0) == 0.0, because 16384 turns = 16384Ο„ radians = 32768Ο€ radians, and sin(32768Ο€)=0
  • ASIN(1.0) == 0.25

βž— % operator behavior with negative dividend or divisor

Changed in 0.5.0.

Instead of having the same sign as the dividend (a remainder operation), % has the same sign as the divisor (a modulo operation).

For example, previously we had:

  • 13 % 10 == 3
  • -13 % 10 == -3
  • 13 % -10 == 3
  • -13 % -10 == -3

Instead, now we have:

  • 13 % 10 == 3
  • -13 % 10 == 7
  • 13 % -10 == -7
  • -13 % -10 == -3

✨ ** operator associativity

Changed in 0.9.0.

Instead of being left-associative, ** is now right-associative.

Previously we had p ** q ** r == (p ** q) ** r.

Instead, now we have p ** q ** r == p ** (q ** r).

🫢 BUGS 🫢

Okay so these are the misfeatures that may have been possible by mistake β€” they do not get deprecated, just fixed. periodt. πŸ’…

πŸ’… Space between exported labels' colons

Fixed in 0.7.0.

Labels with two colons used to ignore a space between them; for example, Label: :.

Instead, use Label::.

πŸ¦‹ Space between label and colon

Fixed in 0.9.0.

Space between a label and its colon(s) used to be ignored; for example, Label : and Label ::. Now they are treated as invocations of the Label macro with : and :: as arguments.

Instead, use Label: and Label::.

🌸 Extra underscores in integer constants

Fixed in 1.0.0.

Underscores, the optional digit separators in integer constants, used to allow more than one in sequence, or trailing without digits on either side. Now only one underscore is allowed between two digits, or between the base prefix and a digit, or between a digit and the q fixed-point precision suffix.

⭐ ADD r16 with implicit first HL operand

Fixed in 0.5.0.

For example, ADD BC used to be treated as ADD HL, BC, and likewise for DE, HL, and SP.

Instead, use an explicit first HL operand.

πŸ’€ = instead of SET

Fixed in 0.4.0.

The = operator used to be an alias for the SET keyword, which included using = for the SET instruction.

Instead, just use SET for the instruction.

πŸ‘€ SEE ALSO πŸ‘€

Go check out rgbasm(1), gbz80(7), rgbds(5), and rgbds(7) β€” bestie cross-reference slay. ✨

🧚 HISTORY 🧚

rgbasm(1) was originally written by Carsten SΓΈrensen as part of the ASMotor package, and was later repackaged in RGBDS by Justin Lloyd. It is now maintained by a number of contributors at https://github.com/gbdev/rgbds.

This page is from the Debian source, version RGBASM-OLD(5), dated September 22, 2026. Byeee πŸ’–

πŸ“¦ where this page comes from