Improvements thanks to upcoming rgbds versions

[mid-kid]

Features we should use as of rgbds 0.9.0:

• CHARMAP can map characters to sequences of multiple 32-bit values (might be useful to replace always-together sequences of character bytes)
• A string constant . (period) which expands to the current global label scope (useful in macros/asserts.asm)
• BITWIDTH and TZCOUNT functions (useful in some calculations, e.g. maskbits)
• EXPORT DEF defines and exports a numeric symbol in a single line
• PUSHC name acts like PUSHC followed by SETCHARMAP name
• PUSHS ... acts like PUSHS followed by SECTION ...
• PUSHO ... acts like PUSHO followed by OPT ...
• rgbgfx -X and -Y (can replace tools/gfx --remove-xflip and --remove-yflip)
• rgbfix -m MBC3+TIMER+RAM+BATTERY instead of -m $10

Features to consider using:

• Underscores in numeric literals (e.g. %11_10_01_00 or 9_999_999)

Features we should avoid (for simplicity and consistency):

• /* block comments */
• """multi-line strings"""
• #"raw strings" that don't process any escapes
• #raw identifiers that can have the same names as reserved keywords
• :: to separate multiple instructions on one line
• 0x, 0b, and 0o prefixes for hex, binary, and octal numbers (just use $, %, and &)
• DS ALIGN (use explicit DS number)
• Anonymous labels (not visible in the .sym file for debuggers)
• Un-indented macro invocations

Features we should use that don't exist yet:

• rgbgfx --background (can replace tools/gfx --remove-whitespace)
• User-defined functions for things like coordinates ([Feature request] User-defined functions gbdev/rgbds#201)
• Short-circuit &&/|| instead of some nested ifs

[ISSOtm]

* [ ]  `ds $0150 - $0104` can become `ds $0150 - @` in home/header.asm

Well, considering hacks could choose to put anything there but 0 should be the default value for the header (as RGBFIX just patches over instead of overwriting the whole region), that'd be one of the places where ds $150 - @, 0 would make sense.

[ISSOtm]

2-arg ds added in gbdev/rgbds@4cc24f4.

[ISSOtm]

https://github.com/rednex/rgbds/releases/tag/v0.4.0

[Rangi42]

User-defined functions are under development, which will allow replacing the coord macros:

def coord(x, y) = coord(x, y, wTilemap)
def coord(x, y, origin) = y * SCREEN_WIDTH + x + origin

def bgcoord(x, y) = bgcoord(x, y, vBGMap0)
def bgcoord(x, y, origin) = y * BG_MAP_WIDTH + x + origin

Old:

	hlcoord 1, 2
	debgcoord 3, 4, wAttrmap
	dwcoord 5, 6
	ldcoord_a 7, 8
	lda_coord 9, 10

New:

	ld hl, coord(1, 2)
	ld de, bgcoord(3, 4, wAttrmap)
	dw coord(5, 6)
	ld [coord(7, 8)], a
	ld a, [coord(9, 10)]

If a ternary operator is added later, then maskbits n can become ld a, bitmask(n):

def bitmask(n) = n > 0 ? bitmask(n, 1) : 0
def bitmask(n, x) = n <= x+1 ? x : bitmask(n, x*2+1)

[ISSOtm]

Features I think we should avoid (generally because they make it harder to process .asm files via regular expressions, as with optimize.py):

* New `MACRO name` and `DEF name EQU value` syntax (the old syntaxes are more familiar and not deprecated)

Be careful, as the changelog states:

The old syntax will still be supported for a couple versions, but may eventually be phased out.

(Emphasis added.) The syntax change is to get rid of the newbie trap that is "column 1", and it hasn't been deprecated as a courtesy due to the wide usage; but you're still strongly advised to prepare for an eventual deprecation.

[Rangi42]

def rgb555(r, g, b) = (r << 0) | (g << 5) | (b << 10)

RGB: MACRO
rept _NARG / 3
	assert_valid_rgb \1, \2, \3
	dw rgb555(\1, \2, \3)
	shift 3
endr
ENDM

[Rangi42]

BASE_TMHM rb (NUM_TM_HM_TUTOR + 7) / 8
for n, (NUM_TM_HM_TUTOR + 7) / 8
	ds ((\1) + 7) / 8

def nb_flags(n) := (n + 7) / 8

BASE_TMHM rb nb_flags(NUM_TM_HM_TUTOR)
for n, nb_flags(NUM_TM_HM_TUTOR)
	ds nb_flags(\1)

[rawr51919]

This issue I presume is meant to be a tracker for RGBDS updates and the syntax that goes along with them for pokecrystal adoption

[Rangi42]

 MACRO maskbits
 ; masks just enough bits to cover values 0 to \1 - 1
 ; \2 is an optional shift amount
 ; e.g. "maskbits 26" becomes "and %00011111" (since 26 - 1 = %00011001)
 ; and "maskbits 3, 2" becomes "and %00001100" (since "maskbits 3" becomes %00000011)
 ; example usage in rejection sampling:
 ; .loop
 ; 	call Random
 ; 	maskbits 26
 ; 	cp 26
 ; 	jr nc, .loop
 	assert 0 < (\1) && (\1) <= $100, "bitmask must be 8-bit"
-	DEF x = 1
-	rept 8
-		if x + 1 < (\1)
-			DEF x = (x << 1) | 1
-		endc
-	endr
+	DEF x = (1 << BITWIDTH((\1) - 1)) - 1
+	if !x
+		DEF x = 1
+	endc
 	if _NARG == 2
 		and x << (\2)
 	else
 		and x
 	endc
 ENDM

(I can't wait for user-defined functions, so we can just declare DEF bitmask(n) := n == 1 ? 1 : (1 << BITWIDTH(n - 1)) - 1, and then do and bitmask(NUM_THINGS) or and bitmask(NUM_THINGS) << 2.)

[Rangi42]

We could also just hard-code that formula every time, e.g.:

	; maskbits BATTLETOWER_NUM_UNIQUE_TRAINERS
	and (1 << BITWIDTH(BATTLETOWER_NUM_UNIQUE_TRAINERS - 1)) - 1

	; maskbits NUM_DIRECTIONS, 2
	and ((1 << BITWIDTH(NUM_DIRECTIONS - 1)) - 1) << 2 

That would be comparable to how we currently repeat the formula for "number of bits in a byte":

DEF BASE_TMHM rb (NUM_TM_HM + 7) / 8

	for n, (NUM_TM_HM + 7) / 8

MACRO flag_array
	ds ((\1) + 7) / 8
ENDM

But I think that's a significantly simpler case. (And even then I'd use a DEF bytes_for_bits(n) := (n + 7) / 8 function if it were possible.)