More hw constants and various clean up/documentation

21 files changed, 392 insertions, 298 deletions

diff --git a/src/constants.asm b/src/constants.asm
index c3af333..926f8d6 100644
--- a/src/constants.asm
+++ b/src/constants.asm
@@ -11,5 +11,6 @@ INCLUDE "constants/misc_constants.asm"
 INCLUDE "constants/music_constants.asm"
 INCLUDE "constants/npc_constants.asm"
 INCLUDE "constants/sgb_constants.asm"
+INCLUDE "constants/sprite_constants.asm"
 INCLUDE "constants/text_constants.asm"
 INCLUDE "constants/charmaps.asm"
diff --git a/src/constants/card_data_constants.asm b/src/constants/card_data_constants.asm
index c110a69..c5159e7 100644
--- a/src/constants/card_data_constants.asm
+++ b/src/constants/card_data_constants.asm
@@ -75,15 +75,15 @@ PKMN_CARD_DATA_LENGTH EQU $41
 
 ; generic type (color) constants
 	const_def
-	const FIRE        ; $0
-	const GRASS       ; $1
-	const LIGHTNING   ; $2
-	const WATER       ; $3
-	const FIGHTING    ; $4
-	const PSYCHIC     ; $5
+	const FIRE        ; $00
+	const GRASS       ; $01
+	const LIGHTNING   ; $02
+	const WATER       ; $03
+	const FIGHTING    ; $04
+	const PSYCHIC     ; $05
 NUM_COLORED_TYPES EQU const_value
-	const COLORLESS   ; $6
-	const UNUSED_TYPE ; $7
+	const COLORLESS   ; $06
+	const UNUSED_TYPE ; $07
 NUM_TYPES EQU const_value
 
 ; CARD_DATA_TYPE constants
@@ -120,12 +120,12 @@ STAR      EQU $2
 PROMOSTAR EQU $ff
 
 ; CARD_DATA_SET constants (set 1)
-COLOSSEUM   EQU $00
-EVOLUTION   EQU $10
-MYSTERY     EQU $20
-LABORATORY  EQU $30
-PROMOTIONAL EQU $40
-ENERGY      EQU $50
+COLOSSEUM   EQU $0 << 4
+EVOLUTION   EQU $1 << 4
+MYSTERY     EQU $2 << 4
+LABORATORY  EQU $3 << 4
+PROMOTIONAL EQU $4 << 4
+ENERGY      EQU $5 << 4
 
 ; CARD_DATA_SET constants (set 2)
 JUNGLE EQU $1
@@ -134,9 +134,9 @@ GB     EQU $7
 PRO    EQU $8
 
 ; CARD_DATA_STAGE constants
-BASIC  EQU $0
-STAGE1 EQU $1
-STAGE2 EQU $2
+BASIC  EQU $00
+STAGE1 EQU $01
+STAGE2 EQU $02
 
 ; CARD_DATA_WEAKNESS and CARD_DATA_RESISTANCE constants
 WR_FIRE      EQU $80
@@ -147,13 +147,13 @@ WR_FIGHTING  EQU $08
 WR_PSYCHIC   EQU $04
 
 ; CARD_DATA_MOVE*_CATEGORY constants
-DAMAGE_NORMAL EQU $0
-DAMAGE_PLUS   EQU $1
-DAMAGE_MINUS  EQU $2
-DAMAGE_X      EQU $3
-POKEMON_POWER EQU $4
-RESIDUAL_F    EQU  7
-RESIDUAL      EQU  1 << RESIDUAL_F
+DAMAGE_NORMAL EQU $00
+DAMAGE_PLUS   EQU $01
+DAMAGE_MINUS  EQU $02
+DAMAGE_X      EQU $03
+POKEMON_POWER EQU $04
+RESIDUAL_F    EQU 7
+RESIDUAL      EQU 1 << RESIDUAL_F
 
 ; CARD_DATA_MOVE*_FLAG1 constants
 INFLICT_POISON           EQU %00000001
diff --git a/src/constants/charmaps.asm b/src/constants/charmaps.asm
index 5bd21be..b2be006 100644
--- a/src/constants/charmaps.asm
+++ b/src/constants/charmaps.asm
@@ -9,6 +9,10 @@
 	charmap "♀", "%"
 	charmap "”", "\""
 
+fwcharmap: MACRO
+	charmap STRCAT("FW\1_", \2), \3
+ENDM
+
 ; TX_FULLWIDTH3
 	fwcharmap 3, "A", $30
 	fwcharmap 3, "B", $31
@@ -310,6 +314,11 @@
 
 FW_SPACE EQU $70
 
+txsymbol: MACRO
+	const SYM_\1
+	charmap "\1>", const_value + -1
+ENDM
+
 ; TX_SYMBOL
 ; TODO: If user-defined functions ever become a thing a symbol(*) syntax
 ;       would probably be preferred over SYM_*
diff --git a/src/constants/deck_constants.asm b/src/constants/deck_constants.asm
index 6b16d63..4105242 100644
--- a/src/constants/deck_constants.asm
+++ b/src/constants/deck_constants.asm
@@ -1,3 +1,10 @@
+deck_const: MACRO
+if const_value >= 2
+\1_ID EQU const_value + -2
+endc
+	const \1
+ENDM
+
 ; Both *_DECK and *_DECK_ID constants are defined here.
 ; *_DECK constants are to be used with LoadDeck and related routines.
 ; *_DECK_ID constants are specific to be loaded into wOpponentDeckID.
diff --git a/src/constants/gfx_constants.asm b/src/constants/gfx_constants.asm
index 4ab84d2..61f49b8 100644
--- a/src/constants/gfx_constants.asm
+++ b/src/constants/gfx_constants.asm
@@ -16,31 +16,3 @@ tiles EQUS "* TILE_SIZE"
 
 TILE_SIZE_1BPP EQU 8 ; bytes
 tiles_1bpp EQUS "* TILE_SIZE_1BPP"
-
-; wFlushPaletteFlags constants
-FLUSH_ONE EQU %10000000
-FLUSH_ALL EQU %11000000
-FLUSH_ALL_F EQU 6
-
-; wSpriteAnimBuffer
-SPRITE_ANIM_BUFFER_CAPACITY EQU 16 ; sprites
-
-; sprite_anim_struct constants
-	const_def
-	const SPRITE_ANIM_FIELD_00
-	const SPRITE_ANIM_FIELD_01
-	const SPRITE_ANIM_COORD_X
-	const SPRITE_ANIM_COORD_Y
-	const SPRITE_ANIM_TILE_ID
-	const SPRITE_ANIM_FIELD_05
-	const SPRITE_ANIM_FIELD_06
-	const SPRITE_ANIM_FIELD_07
-	const SPRITE_ANIM_FIELD_08
-	const SPRITE_ANIM_FIELD_09
-	const SPRITE_ANIM_FIELD_0A
-	const SPRITE_ANIM_FIELD_0B
-	const SPRITE_ANIM_FIELD_0C
-	const SPRITE_ANIM_FIELD_0D
-	const SPRITE_ANIM_MOVEMENT_COUNTER
-	const SPRITE_ANIM_FIELD_0F
-SPRITE_ANIM_LENGTH EQU const_value
diff --git a/src/constants/hardware_constants.asm b/src/constants/hardware_constants.asm
index fe2731f..4a9c253 100644
--- a/src/constants/hardware_constants.asm
+++ b/src/constants/hardware_constants.asm
@@ -1,4 +1,4 @@
-; From http://bgb.bircd.org/pandocs.htm
+; From http://bgb.bircd.org/pandocs.htm and https://github.com/tobiasvl/hardware.inc
 
 GBC EQU $11
 
@@ -24,11 +24,11 @@ RTC_DH EQU $0c ; Upper 1 bit of Day Counter, Carry Bit, Halt Flag
         ; Bit 7  Day Counter Carry Bit (1=Counter Overflow)
 
 ; interrupt flags
-VBLANK   EQU 0
-LCD_STAT EQU 1
-TIMER    EQU 2
-SERIAL   EQU 3
-JOYPAD   EQU 4
+INT_VBLANK   EQU 0
+INT_LCD_STAT EQU 1
+INT_TIMER    EQU 2
+INT_SERIAL   EQU 3
+INT_JOYPAD   EQU 4
 
 ; OAM attribute flags
 OAM_PALETTE   EQU %111
@@ -40,74 +40,133 @@ OAM_PRIORITY  EQU 7 ; 0: OBJ above BG, 1: OBJ behind BG (colors 1-3)
 
 ; Hardware registers
 rJOYP       EQU $ff00 ; Joypad (R/W)
+
 rSB         EQU $ff01 ; Serial transfer data (R/W)
 rSC         EQU $ff02 ; Serial Transfer Control (R/W)
-SC_ON    EQU 7
-SC_CGB   EQU 1
-SC_CLOCK EQU 0
+SC_START    EQU $80
+SC_INTERNAL EQU $01
+SC_EXTERNAL EQU $00
+
 rDIV        EQU $ff04 ; Divider Register (R/W)
 rTIMA       EQU $ff05 ; Timer counter (R/W)
 rTMA        EQU $ff06 ; Timer Modulo (R/W)
 rTAC        EQU $ff07 ; Timer Control (R/W)
-TAC_ON        EQU 2
-TAC_4096_HZ   EQU 0
-TAC_262144_HZ EQU 1
-TAC_65536_HZ  EQU 2
-TAC_16384_HZ  EQU 3
+TAC_START     EQU $04
+TAC_STOP      EQU $00
+TAC_4096_HZ   EQU $00
+TAC_262144_HZ EQU $01
+TAC_65536_HZ  EQU $02
+TAC_16384_HZ  EQU $03
+
 rIF         EQU $ff0f ; Interrupt Flag (R/W)
+
 rNR10       EQU $ff10 ; Channel 1 Sweep register (R/W)
 rNR11       EQU $ff11 ; Channel 1 Sound length/Wave pattern duty (R/W)
 rNR12       EQU $ff12 ; Channel 1 Volume Envelope (R/W)
 rNR13       EQU $ff13 ; Channel 1 Frequency lo (Write Only)
 rNR14       EQU $ff14 ; Channel 1 Frequency hi (R/W)
+
 rNR21       EQU $ff16 ; Channel 2 Sound Length/Wave Pattern Duty (R/W)
 rNR22       EQU $ff17 ; Channel 2 Volume Envelope (R/W)
 rNR23       EQU $ff18 ; Channel 2 Frequency lo data (W)
 rNR24       EQU $ff19 ; Channel 2 Frequency hi data (R/W)
+
 rNR30       EQU $ff1a ; Channel 3 Sound on/off (R/W)
 rNR31       EQU $ff1b ; Channel 3 Sound Length
 rNR32       EQU $ff1c ; Channel 3 Select output level (R/W)
 rNR33       EQU $ff1d ; Channel 3 Frequency's lower data (W)
 rNR34       EQU $ff1e ; Channel 3 Frequency's higher data (R/W)
+
 rNR41       EQU $ff20 ; Channel 4 Sound Length (R/W)
 rNR42       EQU $ff21 ; Channel 4 Volume Envelope (R/W)
 rNR43       EQU $ff22 ; Channel 4 Polynomial Counter (R/W)
 rNR44       EQU $ff23 ; Channel 4 Counter/consecutive; Inital (R/W)
+
 rNR50       EQU $ff24 ; Channel control / ON-OFF / Volume (R/W)
 rNR51       EQU $ff25 ; Selection of Sound output terminal (R/W)
 rNR52       EQU $ff26 ; Sound on/off
+
 rLCDC       EQU $ff40 ; LCD Control (R/W)
-LCDC_ON EQU 7
+LCDC_OFF        EQU %01111111 ; LCD Control Operation (and)
+LCDC_ON         EQU %10000000 ; LCD Control Operation (ld/or)
+LCDC_ENABLE_F   EQU 7
+LCDC_WIN9800    EQU %10111111 ; Window Tile Map Display Select (and)
+LCDC_WIN9C00    EQU %01000000 ; Window Tile Map Display Select (ld/or)
+LCDC_WINSELECT  EQU LCDC_WIN9C00
+LCDC_WINOFF     EQU %11011111 ; Window Display (and)
+LCDC_WINON      EQU %00100000 ; Window Display (ld/or)
+LCDC_WINENABLE  EQU LCDC_WINON
+LCDC_BG8800     EQU %11101111 ; BG & Window Tile Data Select (and)
+LCDC_BG8000     EQU %00010000 ; BG & Window Tile Data Select (ld/or)
+LCDC_BGTILEDATA EQU LCDC_BG8000
+LCDC_BG9800     EQU %11110111 ; BG Tile Map Display Select (and)
+LCDC_BG9C00     EQU %00001000 ; BG Tile Map Display Select (ld/or)
+LCDC_BGTILEMAP  EQU LCDC_BG9C00
+LCDC_OBJ8       EQU %11111011 ; OBJ Construction (and)
+LCDC_OBJ16      EQU %00000100 ; OBJ Construction (ld/or)
+LCDC_OBJSIZE    EQU LCDC_OBJ16
+LCDC_OBJOFF     EQU %11111101 ; OBJ Display (and)
+LCDC_OBJON      EQU %00000010 ; OBJ Display (ld/or)
+LCDC_OBJENABLE  EQU LCDC_OBJON
+LCDC_BGOFF      EQU %11111110 ; BG Display (and)
+LCDC_BGON       EQU %00000001 ; BG Display (ld/or)
+LCDC_BGENABLE   EQU LCDC_BGON
+
 rSTAT       EQU $ff41 ; LCDC Status (R/W)
+STAT_LYC          EQU 6 ; LYC=LY Coincidence
+STAT_MODE_OAM     EQU 5 ; Mode 10 (OAM)
+STAT_MODE_VBLANK  EQU 4 ; Mode 01 (V-Blank)
+STAT_MODE_HBLANK  EQU 3 ; Mode 00 (H-Blank)
+STAT_LYCFLAG      EQU 2 ; 0:LYC<>LY, 1:LYC=LY
+STAT_LCDC_STATUS  EQU %00000011
+STAT_ON_HBLANK    EQU %00000000 ; H-Blank
+STAT_ON_VBLANK    EQU %00000001 ; V-Blank
+STAT_ON_OAM       EQU %00000010 ; OAM-RAM is used by system
+STAT_ON_LCD       EQU %00000011 ; Both OAM and VRAM used by system
+STAT_BUSY         EQU 1 ; When set, VRAM and OAM access is unsafe
+
 rSCY        EQU $ff42 ; Scroll Y (R/W)
 rSCX        EQU $ff43 ; Scroll X (R/W)
+
 rLY         EQU $ff44 ; LCDC Y-Coordinate (R)
 LY_VBLANK EQU 145
 rLYC        EQU $ff45 ; LY Compare (R/W)
+
 rDMA        EQU $ff46 ; DMA Transfer and Start Address (W)
+
 rBGP        EQU $ff47 ; BG Palette Data (R/W) - Non CGB Mode Only
 rOBP0       EQU $ff48 ; Object Palette 0 Data (R/W) - Non CGB Mode Only
 rOBP1       EQU $ff49 ; Object Palette 1 Data (R/W) - Non CGB Mode Only
+
 rWY         EQU $ff4a ; Window Y Position (R/W)
 rWX         EQU $ff4b ; Window X Position minus 7 (R/W)
+
 rKEY1       EQU $ff4d ; CGB Mode Only - Prepare Speed Switch
+
 rVBK        EQU $ff4f ; CGB Mode Only - VRAM Bank
+
 rHDMA1      EQU $ff51 ; CGB Mode Only - New DMA Source, High
 rHDMA2      EQU $ff52 ; CGB Mode Only - New DMA Source, Low
 rHDMA3      EQU $ff53 ; CGB Mode Only - New DMA Destination, High
 rHDMA4      EQU $ff54 ; CGB Mode Only - New DMA Destination, Low
 rHDMA5      EQU $ff55 ; CGB Mode Only - New DMA Length/Mode/Start
+
 rRP         EQU $ff56 ; CGB Mode Only - Infrared Communications Port
+
 rBGPI       EQU $ff68 ; CGB Mode Only - Background Palette Index
 rBGPD       EQU $ff69 ; CGB Mode Only - Background Palette Data
 rOBPI       EQU $ff6a ; CGB Mode Only - Sprite Palette Index
 rOBPD       EQU $ff6b ; CGB Mode Only - Sprite Palette Data
+
 rUNKNOWN1   EQU $ff6c ; (FEh) Bit 0 (Read/Write) - CGB Mode Only
+
 rSVBK       EQU $ff70 ; CGB Mode Only - WRAM Bank
+
 rUNKNOWN2   EQU $ff72 ; (00h) - Bit 0-7 (Read/Write)
 rUNKNOWN3   EQU $ff73 ; (00h) - Bit 0-7 (Read/Write)
 rUNKNOWN4   EQU $ff74 ; (00h) - Bit 0-7 (Read/Write) - CGB Mode Only
 rUNKNOWN5   EQU $ff75 ; (8Fh) - Bit 4-6 (Read/Write)
 rUNKNOWN6   EQU $ff76 ; (00h) - Always 00h (Read Only)
 rUNKNOWN7   EQU $ff77 ; (00h) - Always 00h (Read Only)
+
 rIE         EQU $ffff ; Interrupt Enable (R/W)
diff --git a/src/constants/misc_constants.asm b/src/constants/misc_constants.asm
index a6511df..b31631a 100644
--- a/src/constants/misc_constants.asm
+++ b/src/constants/misc_constants.asm
@@ -1,17 +1,12 @@
-; console types (wConsole)
-CONSOLE_DMG EQU $00
-CONSOLE_SGB EQU $01
-CONSOLE_CGB EQU $02
-
 ; buttons
-A_BUTTON_F EQU $0
-B_BUTTON_F EQU $1
-SELECT_F   EQU $2
-START_F    EQU $3
-D_RIGHT_F  EQU $4
-D_LEFT_F   EQU $5
-D_UP_F     EQU $6
-D_DOWN_F   EQU $7
+A_BUTTON_F EQU 0
+B_BUTTON_F EQU 1
+SELECT_F   EQU 2
+START_F    EQU 3
+D_RIGHT_F  EQU 4
+D_LEFT_F   EQU 5
+D_UP_F     EQU 6
+D_DOWN_F   EQU 7
 
 A_BUTTON   EQU 1 << A_BUTTON_F ; $01
 B_BUTTON   EQU 1 << B_BUTTON_F ; $02
@@ -25,6 +20,20 @@ D_DOWN     EQU 1 << D_DOWN_F   ; $80
 BUTTONS    EQU A_BUTTON | B_BUTTON | SELECT | START  ; $0f
 D_PAD      EQU D_RIGHT  | D_LEFT   | D_UP   | D_DOWN ; $f0
 
+; console types (wConsole)
+CONSOLE_DMG EQU $00
+CONSOLE_SGB EQU $01
+CONSOLE_CGB EQU $02
+
+; wReentrancyFlag bits
+IN_VBLANK EQU 0
+IN_TIMER EQU 1
+
+; wFlushPaletteFlags constants
+FLUSH_ONE_PAL    EQU %10000000
+FLUSH_ALL_PALS   EQU %11000000
+FLUSH_ALL_PALS_F EQU 6
+
 ; Game event constants (wGameEvent)
 	const_def
 	const GAME_EVENT_OVERWORLD         ; $0
diff --git a/src/constants/sprite_constants.asm b/src/constants/sprite_constants.asm
new file mode 100644
index 0000000..dc051d9
--- /dev/null
+++ b/src/constants/sprite_constants.asm
@@ -0,0 +1,22 @@
+; wSpriteAnimBuffer
+SPRITE_ANIM_BUFFER_CAPACITY EQU 16 ; sprites
+
+; sprite_anim_struct constants
+	const_def
+	const SPRITE_ANIM_FIELD_00
+	const SPRITE_ANIM_FIELD_01
+	const SPRITE_ANIM_COORD_X
+	const SPRITE_ANIM_COORD_Y
+	const SPRITE_ANIM_TILE_ID
+	const SPRITE_ANIM_FIELD_05
+	const SPRITE_ANIM_FIELD_06
+	const SPRITE_ANIM_FIELD_07
+	const SPRITE_ANIM_FIELD_08
+	const SPRITE_ANIM_FIELD_09
+	const SPRITE_ANIM_FIELD_0A
+	const SPRITE_ANIM_FIELD_0B
+	const SPRITE_ANIM_FIELD_0C
+	const SPRITE_ANIM_FIELD_0D
+	const SPRITE_ANIM_MOVEMENT_COUNTER
+	const SPRITE_ANIM_FIELD_0F
+SPRITE_ANIM_LENGTH EQU const_value
diff --git a/src/data/booster_packs.asm b/src/data/booster_packs.asm
index 03b64ee..7d1090c 100644
--- a/src/data/booster_packs.asm
+++ b/src/data/booster_packs.asm
@@ -1,5 +1,5 @@
 BoosterSetRarityAmountsTable: ; 1e4d4 (7::64d4)
-; energies, commons, uncommons, rares
+;	db energies, commons, uncommons, rares
 ; commons + uncommons + rares needs to be equal to 10 minus the number of energy cards
 ; defined in the pack's data below; otherwise, the number of cards in the pack won't be 10.
 	db 1, 5, 3, 1 ; COLOSSEUM
diff --git a/src/data/decks.asm b/src/data/decks.asm
index 129b6d9..424874b 100644
--- a/src/data/decks.asm
+++ b/src/data/decks.asm
@@ -655,7 +655,7 @@ CharmanderExtraDeck: ; 30465 (c:4465)
 	db 2, ABRA
 	db 1, KADABRA
 	db 1, GASTLY1
-	db 30, GRASS_ENERGY
+	db 30, GRASS_ENERGY ; irrelevant
 	db 0 ; end
 	tx CharmanderExtraDeckName
 
@@ -715,7 +715,7 @@ SquirtleExtraDeck: ; 304cf (c:44cf)
 	db 1, MAGNEMITE1
 	db 1, MAGNETON1
 	db 1, ELECTABUZZ2
-	db 30, GRASS_ENERGY
+	db 30, GRASS_ENERGY ; irrelevant
 	db 0 ; end
 	tx SquirtleExtraDeckName
 
@@ -773,7 +773,7 @@ BulbasaurExtraDeck: ; 3053b (c:453b)
 	db 1, BILL
 	db 2, POTION
 	db 1, GUST_OF_WIND
-	db 30, GRASS_ENERGY
+	db 30, GRASS_ENERGY ; irrelevant
 	db 0 ; end
 	tx BulbasaurExtraDeckName
 
diff --git a/src/data/map_songs.asm b/src/data/map_headers.asm
index 4012452..7f57a06 100644
--- a/src/data/map_songs.asm
+++ b/src/data/map_headers.asm
@@ -1,6 +1,6 @@
-; todo: figure out the rest of the data for each map
+; TODO: figure out the rest of the data for each map
 ; related to the table at 20:4e5d
-MapSongs: ; 1c374 (7:4374)
+MapHeaders: ; 1c374 (7:4374)
 	db $00,$01,$00,$01,$01,MUSIC_OVERWORLD   ; OVERWORLD_MAP
 	db $02,$03,$00,$02,$02,MUSIC_OVERWORLD   ; MASON_LABORATORY
 	db $06,$07,$00,$02,$02,MUSIC_OVERWORLD   ; DECK_MACHINE_ROOM
diff --git a/src/engine/bank01.asm b/src/engine/bank01.asm
index 9ca9c10..bce3839 100644
--- a/src/engine/bank01.asm
+++ b/src/engine/bank01.asm
@@ -42,7 +42,7 @@ Func_4050: ; 4050 (1:4050)
 	ret
 
 Func_405a: ; 405a (1:405a)
-	xor a
+	xor a ; SYM_SPACE
 	ld [wTileMapFill], a
 	call DisableLCD
 	call LoadSymbolsFont
@@ -277,7 +277,7 @@ MainDuelLoop ; 40ee (1:40ee)
 ; 0x420b
 
 Func_420b: ; 420b (1:420b)
-	xor a
+	xor a ; SYM_SPACE
 	ld [wTileMapFill], a
 	call ZeroObjectPositionsAndToggleOAMCopy
 	call EmptyScreen
@@ -3061,7 +3061,7 @@ FlushAllPalettesOrSendPal23Packet: ; 5a34 (1:5a34)
 	ret z
 	cp CONSOLE_SGB
 	jr z, .sgb
-	call SetFlushAllPalettes
+	call FlushAllPalettes
 	ret
 .sgb
 ; sgb PAL23, 1 ; sgb_command, length
@@ -3203,7 +3203,7 @@ SetDefaultPalettes: ; 5aeb (1:5aeb)
 	ld a, $e4
 	ld [wOBP0], a
 	ld [wBGP], a
-	ld a, $01 ; equivalent to FLUSH_ONE
+	ld a, $01 ; equivalent to FLUSH_ONE_PAL
 	ld [wFlushPaletteFlags], a
 	ret
 .cgb
@@ -3217,7 +3217,7 @@ SetDefaultPalettes: ; 5aeb (1:5aeb)
 	ld hl, wObjectPalettesCGB
 	ld c, CGB_PAL_SIZE
 	call .copy_de_to_hl
-	call SetFlushAllPalettes
+	call FlushAllPalettes
 	ret
 .sgb
 	ld a, $04
diff --git a/src/engine/bank03.asm b/src/engine/bank03.asm
index 744a3ef..9c189aa 100644
--- a/src/engine/bank03.asm
+++ b/src/engine/bank03.asm
@@ -452,7 +452,7 @@ Func_c34e: ; c34e (3:434e)
 	ld de, wObjectPalettesCGB
 	ld bc, 8 palettes
 	call CopyDataHLtoDE_SaveRegisters
-	call SetFlushAllPalettes
+	call FlushAllPalettes
 	ret
 
 Func_c36a: ; c36a (3:436a)
diff --git a/src/engine/bank04.asm b/src/engine/bank04.asm
index 28108fb..d30f460 100644
--- a/src/engine/bank04.asm
+++ b/src/engine/bank04.asm
@@ -10,7 +10,7 @@ Func_10000: ; 10000 (4:4000)
 	ldh [hSCX], a
 	ldh [hSCY], a
 	ld a, [wLCDC]
-	bit LCDC_ON, a
+	bit LCDC_ENABLE_F, a
 	jr nz, .asm_10025
 	xor a
 	ld [rSCX], a
@@ -31,11 +31,11 @@ Func_10031: ; 10031 (4:4031)
 	call $4cbb
 	call DisableSRAM
 	call $4b28
-	call SetFlushAllPalettes
+	call FlushAllPalettes
 	call EnableLCD
 	call DoFrameIfLCDEnabled
 	call $4cea
-	call SetFlushAllPalettes
+	call FlushAllPalettes
 	pop af
 	call BankswitchSRAM
 	call DisableSRAM
diff --git a/src/engine/bank07.asm b/src/engine/bank07.asm
index 1ebffa2..bb8c800 100644
--- a/src/engine/bank07.asm
+++ b/src/engine/bank07.asm
@@ -61,7 +61,7 @@ Func_1c33b: ; 1c33b (7:433b)
 	add c
 	ld c, a
 	ld b, $0
-	ld hl, MapSongs
+	ld hl, MapHeaders
 	add hl, bc
 	ld a, [hli]
 	ld [wd131], a
@@ -88,7 +88,7 @@ Func_1c33b: ; 1c33b (7:433b)
 	pop hl
 	ret
 
-INCLUDE "data/map_songs.asm"
+INCLUDE "data/map_headers.asm"
 
 Func_1c440: ; 1c440 (7:4440)
 	INCROM $1c440, $1c455
diff --git a/src/engine/bank1c.asm b/src/engine/bank1c.asm
index 333ef53..7b5cbc5 100644
--- a/src/engine/bank1c.asm
+++ b/src/engine/bank1c.asm
@@ -173,10 +173,10 @@ Func_70136: ; 70136 (1c:4136)
 	call SendSGB
 	call DisableLCD
 	ld a, [wLCDC]
-	and $41
-	or $1
+	and LCDC_BGENABLE | LCDC_WINSELECT
+	or LCDC_BGON
 	ld [wLCDC], a
-	ld a, $e4
+	ld a, %11100100
 	ld [rBGP], a
 	call SetBGP
 	xor a
diff --git a/src/engine/booster_packs.asm b/src/engine/booster_packs.asm
index fc24355..040e612 100644
--- a/src/engine/booster_packs.asm
+++ b/src/engine/booster_packs.asm
@@ -1,4 +1,4 @@
-; generate a booster pack identified by a,
+; generate a booster pack identified by its BOOSTER_* constant in a,
 ; and add the drawn cards to the player's collection (sCardCollection).
 GenerateBoosterPack: ; 1e1c4 (7:61c4)
 	push hl
@@ -18,11 +18,12 @@ GenerateBoosterPack: ; 1e1c4 (7:61c4)
 	ret
 
 ; generate all Pokemon or Trainer cards (if any) for the current booster pack
+; return carry if ran out of cards to add to the booster pack
 GenerateBoosterNonEnergies: ; 1e1df (7:61df)
 	ld a, STAR
 	ld [wBoosterCurrentRarity], a
 .generate_card_loop
-	call FindCurrentRarityChance
+	call GetCurrentRarityAmount
 	ld a, [hl]
 	or a
 	jr z, .no_more_of_current_rarity
@@ -35,8 +36,8 @@ GenerateBoosterNonEnergies: ; 1e1df (7:61df)
 	call DetermineBoosterCard
 	call UpdateBoosterCardTypesChanceByte
 	call AddBoosterCardToDrawnNonEnergies
-	call FindCurrentRarityChance
-	dec [hl]
+	call GetCurrentRarityAmount
+	dec [hl] ; decrement amount left of current rarity
 	jr .generate_card_loop
 .no_more_of_current_rarity
 	ld a, [wBoosterCurrentRarity]
@@ -51,10 +52,11 @@ GenerateBoosterNonEnergies: ; 1e1df (7:61df)
 	scf
 	ret
 
-; return hl pointing to wBoosterData<Rarity>Amount[wBoosterCurrentRarity]
-FindCurrentRarityChance: ; 1e219 (7:6219)
+; return hl pointing to wBoosterData_CommonAmount, wBoosterData_UncommonAmount,
+; or wBoosterData_RareAmount, depending on the value at [wBoosterCurrentRarity]
+GetCurrentRarityAmount: ; 1e219 (7:6219)
 	push bc
-	ld hl, wBoosterDataCommonAmount
+	ld hl, wBoosterData_CommonAmount
 	ld a, [wBoosterCurrentRarity]
 	ld c, a
 	ld b, $0
@@ -63,8 +65,8 @@ FindCurrentRarityChance: ; 1e219 (7:6219)
 	ret
 
 ; loop through all existing cards to see which ones belong to the current set and rarity,
-; and add them wBoosterViableCardList. Also fill wBoosterAmountOfCardTypeTable with the amount of
-; available cards of each type, for the current set and rarity.
+; and add them to wBoosterViableCardList. Also fill wBoosterAmountOfCardTypeTable with
+; the amount of available cards of each type, for the current set and rarity.
 ; Skip any card already drawn in the current pack.
 FindCardsInSetAndRarity: ; 1e226 (7:6226)
 	ld c, NUM_BOOSTER_CARD_TYPES
@@ -133,7 +135,7 @@ CheckCardInSetAndRarity: ; 1e268 (7:6268)
 	swap a
 	and $0f
 	ld c, a
-	ld a, [wBoosterDataSet]
+	ld a, [wBoosterData_Set]
 	cp c
 	jr nz, .invalid_card
 .return_valid_card
@@ -145,7 +147,8 @@ CheckCardInSetAndRarity: ; 1e268 (7:6268)
 	pop bc
 	ret
 
-; Return a card's TYPE_* constant given in a to its BOOSTER_CARD_TYPE_* constant
+; Convert a card's TYPE_* constant given in a to its BOOSTER_CARD_TYPE_* constant
+; return the result in a
 GetBoosterCardType: ; 1e2a0 (7:62a0)
 	push hl
 	push bc
@@ -180,8 +183,8 @@ CardTypeTable:  ; 1e2b1 (7:62b1)
 	db BOOSTER_CARD_TYPE_TRAINER   ; TYPE_ENERGY_UNUSED
 	db BOOSTER_CARD_TYPE_TRAINER   ; TYPE_TRAINER
 
-; calculate the chance of each type for the next card
-; return [wd4ca] = sum of all chances
+; calculate the chance of each type (BOOSTER_CARD_TYPE_*) for the next card
+; return a = [wd4ca]: sum of all chances
 CalculateTypeChances: ; 1e2c2 (7:62c2)
 	ld c, NUM_BOOSTER_CARD_TYPES
 	xor a
@@ -199,7 +202,7 @@ CalculateTypeChances: ; 1e2c2 (7:62c2)
 	ld a, [hl]
 	or a
 	jr z, .amount_of_type_or_chance_zero
-	ld hl, wBoosterDataTypeChances
+	ld hl, wBoosterData_TypeChances
 	add hl, bc
 	ld a, [hl]
 	or a
@@ -245,7 +248,9 @@ DetermineBoosterCardType: ; 1e2fa (7:62fa)
 	ld [wBoosterJustDrawnCardType], a
 	ret
 
-; generate a random available card of the booster card type at [wBoosterJustDrawnCardType]
+; generate a random number between 0 and the amount of cards matching the current type.
+; use that number to determine the card to draw from the booster pack.
+; return the card in a.
 DetermineBoosterCard: ; 1e31d (7:631d)
 	ld a, [wBoosterJustDrawnCardType]
 	ld c, a
@@ -266,13 +271,13 @@ DetermineBoosterCard: ; 1e31d (7:631d)
 	jr nz, .card_incorrect_type
 	ld a, [wd4ca]
 	or a
-	jr z, .return_with_current_card
+	jr z, .got_valid_card
 	dec a
 	ld [wd4ca], a
 .card_incorrect_type
 	inc hl
 	jr .find_matching_card_loop
-.return_with_current_card
+.got_valid_card
 	or a
 	ret
 .no_valid_card_found
@@ -282,14 +287,14 @@ DetermineBoosterCard: ; 1e31d (7:631d)
 
 ; lowers the chance of getting the same type of card multiple times.
 ; more specifically, when a card of type T is drawn, T's new chances become
-; min (1, [wBoosterDataTypeChances[T]] - [wBoosterAveragedTypeChances]).
+; max (1, [wBoosterData_TypeChances[T]] - [wBoosterAveragedTypeChances]).
 UpdateBoosterCardTypesChanceByte: ; 1e350 (7:6350)
 	push hl
 	push bc
 	ld a, [wBoosterJustDrawnCardType]
 	ld c, a
 	ld b, $00
-	ld hl, wBoosterDataTypeChances
+	ld hl, wBoosterData_TypeChances
 	add hl, bc
 	ld a, [wBoosterAveragedTypeChances]
 	ld c, a
@@ -309,7 +314,7 @@ UpdateBoosterCardTypesChanceByte: ; 1e350 (7:6350)
 ; generates between 0 and 10 energy cards for the current booster.
 ; the amount of energies and their probabilities vary with each booster.
 GenerateBoosterEnergies: ; 1e3db (7:63db)
-	ld hl, wBoosterDataEnergyFunctionPointer + 1
+	ld hl, wBoosterData_EnergyFunctionPointer + 1
 	ld a, [hld]
 	or a
 	jr z, .no_function_pointer
@@ -385,9 +390,9 @@ GenerateTwoTypesEnergyBooster:  ; 1e3ab (7:63ab)
 
 ZeroBoosterRarityData:
 	xor a
-	ld [wBoosterDataCommonAmount], a
-	ld [wBoosterDataUncommonAmount], a
-	ld [wBoosterDataRareAmount], a
+	ld [wBoosterData_CommonAmount], a
+	ld [wBoosterData_UncommonAmount], a
+	ld [wBoosterData_RareAmount], a
 	ret
 
 EnergyBoosterLightningFireData:
@@ -403,7 +408,7 @@ EnergyBoosterGrassPsychicData:
 AddBoosterCardToDrawnEnergies: ; 1e3cf (7:63cf)
 	push hl
 	ld hl, wBoosterTempEnergiesDrawn
-	call AppendCardToHL
+	call AppendCurrentCardToHL
 	call AddBoosterCardToTempCardCollection
 	pop hl
 	ret
@@ -412,15 +417,16 @@ AddBoosterCardToDrawnEnergies: ; 1e3cf (7:63cf)
 AddBoosterCardToDrawnNonEnergies: ; 1e3db (7:63db)
 	push hl
 	ld hl, wBoosterTempNonEnergiesDrawn
-	call AppendCardToHL
+	call AppendCurrentCardToHL
 	call AddBoosterCardToTempCardCollection
 	pop hl
 	ret
 
-AppendCardToHL: ; 1e3e7 (7:63e7)
+; put the card at [wBoosterCurrentCard] at the end of the booster card list at hl
+AppendCurrentCardToHL: ; 1e3e7 (7:63e7)
 	ld a, [hli]
 	or a
-	jr nz, AppendCardToHL
+	jr nz, AppendCurrentCardToHL
 	dec hl
 	ld a, [wBoosterCurrentCard]
 	ld [hli], a
@@ -428,7 +434,7 @@ AppendCardToHL: ; 1e3e7 (7:63e7)
 	ld [hl], a
 	ret
 
-; trim empty slots in wBoosterCardsDrawn between regular cards and energies
+; trim empty slots in wBoosterCardsDrawn between non-energy cards and energies
 PutEnergiesAndNonEnergiesTogether: ; 1e3f3 (7:63f3)
 	push hl
 	ld hl, wBoosterTempEnergiesDrawn
@@ -439,7 +445,7 @@ PutEnergiesAndNonEnergiesTogether: ; 1e3f3 (7:63f3)
 	ld [wBoosterCurrentCard], a
 	push hl
 	ld hl, wBoosterTempNonEnergiesDrawn
-	call AppendCardToHL
+	call AppendCurrentCardToHL
 	pop hl
 	jr .loop_through_extra_cards
 .end_of_cards
@@ -483,7 +489,7 @@ CheckCardAlreadyDrawn: ; 1e423 (7:6423)
 	ret
 
 ; clears wBoosterCardsDrawn and wTempCardCollection.
-; copies booster data to wBoosterDataCurSet, wBoosterDataEnergyFunctionPointer, and wBoosterDataTypeChances.
+; copies booster data to wBoosterDataCurSet, wBoosterData_EnergyFunctionPointer, and wBoosterData_TypeChances.
 ; copies rarity amounts to wBoosterData*Amount and averages them into wBoosterAveragedTypeChances.
 InitBoosterData: ; 1e430 (7:6430)
 	ld c, wBoosterCardsDrawnEnd - wBoosterCardsDrawn
@@ -501,14 +507,14 @@ InitBoosterData: ; 1e430 (7:6430)
 	dec c
 	jr nz, .clear_temp_card_collection_loop
 	call FindBoosterDataPointer
-	ld de, wBoosterDataSet
-	ld bc, wBoosterDataTypeChances - wBoosterDataSet + NUM_BOOSTER_CARD_TYPES ; Pack2 - Pack1
+	ld de, wBoosterData_Set
+	ld bc, wBoosterData_TypeChances - wBoosterData_Set + NUM_BOOSTER_CARD_TYPES ; Pack2 - Pack1
 	call CopyDataHLtoDE	; load booster pack data to wram
 	call LoadRarityAmountsToWram
 	ld bc, $0
 	ld d, NUM_BOOSTER_CARD_TYPES
 	ld e, $0
-	ld hl, wBoosterDataTypeChances
+	ld hl, wBoosterData_TypeChances
 .add_chance_bytes_loop
 	ld a, [hli]
 	or a
@@ -570,9 +576,9 @@ BoosterDataJumptable: ; 1e480 (7:6480)
 	dw BoosterPack_EnergyGrassPsychic
 	dw BoosterPack_RandomEnergies
 
-; load rarity amounts of the booster pack set at [wBoosterDataSet] to wBoosterData*Amount
+; load rarity amounts of the booster pack set at [wBoosterData_Set] to wBoosterData*Amount
 LoadRarityAmountsToWram: ; 1e4ba (7:64ba)
-	ld a, [wBoosterDataSet]
+	ld a, [wBoosterData_Set]
 	add a
 	add a
 	ld c, a
@@ -581,11 +587,11 @@ LoadRarityAmountsToWram: ; 1e4ba (7:64ba)
 	add hl, bc
 	inc hl
 	ld a, [hli]
-	ld [wBoosterDataCommonAmount], a
+	ld [wBoosterData_CommonAmount], a
 	ld a, [hli]
-	ld [wBoosterDataUncommonAmount], a
+	ld [wBoosterData_UncommonAmount], a
 	ld a, [hli]
-	ld [wBoosterDataRareAmount], a
+	ld [wBoosterData_RareAmount], a
 	ret
 
 INCLUDE "data/booster_packs.asm"
diff --git a/src/engine/home.asm b/src/engine/home.asm
index a922861..4b58180 100644
--- a/src/engine/home.asm
+++ b/src/engine/home.asm
@@ -51,10 +51,10 @@ Start: ; 0150 (0:0150)
 	pop af
 	ld [wInitialA], a
 	call DetectConsole
-	ld a, " "
+	ld a, $20
 	ld [wTileMapFill], a
 	call SetupVRAM
-	call SetupLCD
+	call SetupRegisters
 	call SetupPalettes
 	call SetupSound
 	call SetupTimer
@@ -66,6 +66,7 @@ Start: ; 0150 (0:0150)
 	ld sp, $e000
 	jp GameLoop
 
+; vblank interrupt handler
 VBlankHandler: ; 019b (0:019b)
 	push af
 	push bc
@@ -74,9 +75,9 @@ VBlankHandler: ; 019b (0:019b)
 	ldh a, [hBankROM]
 	push af
 	ld hl, wReentrancyFlag
-	bit 0, [hl]
+	bit IN_VBLANK, [hl]
 	jr nz, .done
-	set 0, [hl]
+	set IN_VBLANK, [hl]
 	ld a, [wVBlankOAMCopyToggle]
 	or a
 	jr z, .no_oam_copy
@@ -98,11 +99,11 @@ VBlankHandler: ; 019b (0:019b)
 	ld [rLCDC], a
 	ei
 	call wVBlankFunctionTrampoline
-	call FlushPalettes
+	call FlushPalettesIfRequested
 	ld hl, wVBlankCounter
 	inc [hl]
 	ld hl, wReentrancyFlag
-	res 0, [hl]
+	res IN_VBLANK, [hl]
 .done
 	pop af
 	call BankswitchHome
@@ -112,6 +113,7 @@ VBlankHandler: ; 019b (0:019b)
 	pop af
 	reti
 
+; timer interrupt handler
 TimerHandler: ; 01e6 (0:01e6)
 	push af
 	push hl
@@ -129,9 +131,9 @@ TimerHandler: ; 01e6 (0:01e6)
 	call IncrementPlayTimeCounter
 	; check in-timer flag
 	ld hl, wReentrancyFlag
-	bit 1, [hl]
+	bit IN_TIMER, [hl]
 	jr nz, .done
-	set 1, [hl]
+	set IN_TIMER, [hl]
 	ldh a, [hBankROM]
 	push af
 	ld a, BANK(SoundTimerHandler)
@@ -141,7 +143,7 @@ TimerHandler: ; 01e6 (0:01e6)
 	call BankswitchHome
 	; clear in-timer flag
 	ld hl, wReentrancyFlag
-	res 1, [hl]
+	res IN_TIMER, [hl]
 .done
 	pop bc
 	pop de
@@ -149,7 +151,7 @@ TimerHandler: ; 01e6 (0:01e6)
 	pop af
 	reti
 
-; increment timer counter by a tick
+; increment play time counter by a tick
 IncrementPlayTimeCounter: ; 021c (0:021c)
 	ld a, [wPlayTimeCounterEnable]
 	or a
@@ -193,7 +195,7 @@ SetupTimer: ; 0241 (0:0241)
 	ld [rTMA], a
 	ld a, TAC_16384_HZ
 	ld [rTAC], a
-	ld a, TAC_16384_HZ | 1 << TAC_ON
+	ld a, TAC_START | TAC_16384_HZ
 	ld [rTAC], a
 	ret
 
@@ -205,11 +207,11 @@ CheckForCGB: ; 025c (0:025c)
 	scf
 	ret
 
-; wait for vblank
+; wait for VBlankHandler to finish unless lcd is off
 WaitForVBlank: ; 0264 (0:0264)
 	push hl
 	ld a, [wLCDC]
-	bit LCDC_ON, a
+	bit LCDC_ENABLE_F, a
 	jr z, .lcd_off
 	ld hl, wVBlankCounter
 	ld a, [hl]
@@ -224,34 +226,34 @@ WaitForVBlank: ; 0264 (0:0264)
 
 ; turn LCD on
 EnableLCD: ; 0277 (0:0277)
-	ld a, [wLCDC]      ;
-	bit LCDC_ON, a     ;
-	ret nz             ; assert that LCD is off
-	or 1 << LCDC_ON    ;
-	ld [wLCDC], a      ;
-	ld [rLCDC], a      ; turn LCD on
-	ld a, FLUSH_ALL
+	ld a, [wLCDC]        ;
+	bit LCDC_ENABLE_F, a ;
+	ret nz               ; assert that LCD is off
+	or LCDC_ON           ;
+	ld [wLCDC], a        ;
+	ld [rLCDC], a        ; turn LCD on
+	ld a, FLUSH_ALL_PALS
 	ld [wFlushPaletteFlags], a
 	ret
 
 ; wait for vblank, then turn LCD off
 DisableLCD: ; 028a (0:028a)
 	ld a, [rLCDC]        ;
-	bit LCDC_ON, a  ;
+	bit LCDC_ENABLE_F, a ;
 	ret z                ; assert that LCD is on
 	ld a, [rIE]
 	ld [wIE], a
-	res 0, a             ;
+	res INT_VBLANK, a    ;
 	ld [rIE], a          ; disable vblank interrupt
-.asm_298
+.wait_vblank
 	ld a, [rLY]          ;
 	cp LY_VBLANK         ;
-	jr nz, .asm_298      ; wait for vblank
+	jr nz, .wait_vblank  ; wait for vblank
 	ld a, [rLCDC]        ;
-	and $7f              ;
+	and LCDC_OFF         ;
 	ld [rLCDC], a        ;
 	ld a, [wLCDC]        ;
-	and $7f              ;
+	and LCDC_OFF         ;
 	ld [wLCDC], a        ; turn LCD off
 	xor a
 	ld [rBGP], a
@@ -264,66 +266,72 @@ DisableLCD: ; 028a (0:028a)
 ; set OBJ size: 8x8
 Set_OBJ_8x8: ; 02b9 (0:02b9)
 	ld a, [wLCDC]
-	and $fb
+	and LCDC_OBJ8
 	ld [wLCDC], a
 	ret
 
 ; set OBJ size: 8x16
 Set_OBJ_8x16: ; 02c2 (0:02c2)
 	ld a, [wLCDC]
-	or $4
+	or LCDC_OBJ16
 	ld [wLCDC], a
 	ret
 
 ; set Window Display on
 Set_WD_on: ; 02cb (0:02cb)
 	ld a, [wLCDC]
-	or $20
+	or LCDC_WINON
 	ld [wLCDC], a
 	ret
 
 ; set Window Display off
 Set_WD_off: ; 02d4 (0:02d4)
 	ld a, [wLCDC]
-	and $df
+	and LCDC_WINOFF
 	ld [wLCDC], a
 	ret
 
+; enable timer interrupt
 EnableInt_Timer: ; 02dd (0:02dd)
 	ld a, [rIE]
-	or $4
+	or 1 << INT_TIMER
 	ld [rIE], a
 	ret
 
+; enable vblank interrupt
 EnableInt_VBlank: ; 02e4 (0:02e4)
 	ld a, [rIE]
-	or $1
+	or 1 << INT_VBLANK
 	ld [rIE], a
 	ret
 
+; enable lcdc interrupt on hblank mode
 EnableInt_HBlank: ; 02eb (0:02eb)
 	ld a, [rSTAT]
-	or $8
+	or 1 << STAT_MODE_HBLANK
 	ld [rSTAT], a
 	xor a
 	ld [rIF], a
 	ld a, [rIE]
-	or $2
+	or 1 << INT_LCD_STAT
 	ld [rIE], a
 	ret
 
+; disable lcdc interrupt and the hblank mode trigger
 DisableInt_HBlank: ; 02fb (0:02fb)
 	ld a, [rSTAT]
-	and $f7
+	and ~(1 << STAT_MODE_HBLANK)
 	ld [rSTAT], a
 	xor a
 	ld [rIF], a
 	ld a, [rIE]
-	and $fd
+	and ~(1 << INT_LCD_STAT)
 	ld [rIE], a
 	ret
 
-SetupLCD: ; 030b (0:030b)
+; initialize scroll, window, and lcdc registers, set trampoline functions
+; for the lcdc and vblank interrupts, latch clock data, and enable SRAM/RTC
+SetupRegisters: ; 030b (0:030b)
 	xor a
 	ld [rSCY], a
 	ld [rSCX], a
@@ -342,33 +350,34 @@ SetupLCD: ; 030b (0:030b)
 	ld [wLCDCFunctionTrampoline], a
 	ld [wVBlankFunctionTrampoline], a
 	ld hl, wVBlankFunctionTrampoline + 1
-	ld [hl], LOW(NopF)   ;
-	inc hl               ; load `jp NopF`
-	ld [hl], HIGH(NopF)  ;
-	ld a, $47
+	ld [hl], LOW(NoOp)   ;
+	inc hl               ; load `jp NoOp`
+	ld [hl], HIGH(NoOp)  ;
+	ld a, LCDC_BGON | LCDC_OBJON | LCDC_OBJ16 | LCDC_WIN9C00
 	ld [wLCDC], a
 	ld a, $1
 	ld [MBC3LatchClock], a
 	ld a, SRAM_ENABLE
 	ld [MBC3SRamEnable], a
-NopF: ; 0348 (0:0348)
+NoOp: ; 0348 (0:0348)
 	ret
 
+; sets wConsole and, if CGB, selects WRAM bank 1 and switches to double speed mode
 DetectConsole: ; 0349 (0:0349)
 	ld b, CONSOLE_CGB
 	cp GBC
-	jr z, .asm_35b
+	jr z, .got_console
 	call DetectSGB
 	ld b, CONSOLE_DMG
-	jr nc, .asm_35b
+	jr nc, .got_console
 	call InitSGB
 	ld b, CONSOLE_SGB
-.asm_35b
+.got_console
 	ld a, b
 	ld [wConsole], a
 	cp CONSOLE_CGB
 	ret nz
-	ld a, CONSOLE_SGB
+	ld a, $01
 	ld [rSVBK], a
 	call SwitchToCGBDoubleSpeed
 	ret
@@ -410,7 +419,7 @@ InitialPalette: ; 0399 (0:0399)
 	rgb 10,10,08
 	rgb 00,00,00
 
-; clear VRAM tile data
+; clear VRAM tile data ([wTileMapFill] should be an empty tile)
 SetupVRAM: ; 03a1 (0:03a1)
 	call FillTileMap
 	call CheckForCGB
@@ -458,7 +467,7 @@ FillTileMap: ; 03c0 (0:03c0)
 	call BankswitchVRAM0
 	ret
 
-; zero work RAM, stack area & high RAM ($C000-$DFFF, $FF80-$FFEF)
+; zero work RAM, stack area, and high RAM ($C000-$DFFF, $FF80-$FFEF)
 ZeroRAM: ; 03ec (0:03ec)
 	ld hl, $c000
 	ld bc, $e000 - $c000
@@ -480,24 +489,25 @@ ZeroRAM: ; 03ec (0:03ec)
 	ret
 
 ; Flush all non-CGB and CGB palettes
-SetFlushAllPalettes: ; 0404 (0:0404)
-	ld a, FLUSH_ALL
-	jr SetFlushPalettes
+FlushAllPalettes: ; 0404 (0:0404)
+	ld a, FLUSH_ALL_PALS
+	jr FlushPalettes
 
 ; Flush non-CGB palettes and a single CGB palette,
 ; provided in a as an index between 0-7 (BGP) or 8-15 (OBP)
-SetFlushPalette: ; 0408 (0:0408)
-	or FLUSH_ONE
-	jr SetFlushPalettes
+FlushPalette: ; 0408 (0:0408)
+	or FLUSH_ONE_PAL
+	jr FlushPalettes
 
 ; Set wBGP to the specified value, flush non-CGB palettes, and the first CGB palette.
 SetBGP: ; 040c (0:040c)
 	ld [wBGP], a
 
-SetFlushPalette0:
-	ld a, FLUSH_ONE
+; Flush non-CGB palettes and the first CGB palette
+FlushPalette0:
+	ld a, FLUSH_ONE_PAL
 
-SetFlushPalettes:
+FlushPalettes:
 	ld [wFlushPaletteFlags], a
 	ld a, [wLCDC]
 	rla
@@ -505,7 +515,7 @@ SetFlushPalettes:
 	push hl
 	push de
 	push bc
-	call FlushPalettes
+	call FlushPalettesIfRequested
 	pop bc
 	pop de
 	pop hl
@@ -514,19 +524,19 @@ SetFlushPalettes:
 ; Set wOBP0 to the specified value, flush non-CGB palettes, and the first CGB palette.
 SetOBP0: ; 0423 (0:0423)
 	ld [wOBP0], a
-	jr SetFlushPalette0
+	jr FlushPalette0
 
 ; Set wOBP1 to the specified value, flush non-CGB palettes, and the first CGB palette.
 SetOBP1: ; 0428 (0:0428)
 	ld [wOBP1], a
-	jr SetFlushPalette0
+	jr FlushPalette0
 
 ; Flushes non-CGB palettes from [wBGP], [wOBP0], [wOBP1] as well as CGB
 ; palettes from [wBackgroundPalettesCGB..wBackgroundPalettesCGB+$3f] (BG palette)
 ; and [wObjectPalettesCGB+$00..wObjectPalettesCGB+$3f] (sprite palette).
 ; Only flushes if [wFlushPaletteFlags] is nonzero, and only flushes
 ; a single CGB palette if bit6 of that location is reset.
-FlushPalettes: ; 042d (0:042d)
+FlushPalettesIfRequested: ; 042d (0:042d)
 	ld a, [wFlushPaletteFlags]
 	or a
 	ret z
@@ -547,9 +557,9 @@ FlushPalettes: ; 042d (0:042d)
 	ret
 .CGB
 	; flush a single CGB BG or OB palette
-	; if bit6 (FLUSH_ALL_F) of [wFlushPaletteFlags] is set, flush all 16 of them
+	; if bit6 (FLUSH_ALL_PALS_F) of [wFlushPaletteFlags] is set, flush all 16 of them
 	ld a, [wFlushPaletteFlags]
-	bit FLUSH_ALL_F, a
+	bit FLUSH_ALL_PALS_F, a
 	jr nz, FlushAllCGBPalettes
 	ld b, CGB_PAL_SIZE
 	call CopyCGBPalettes
@@ -564,10 +574,10 @@ FlushAllCGBPalettes: ; 0458 (0:0458)
 	ld a, CGB_PAL_SIZE
 	ld b, 8 palettes
 	call CopyCGBPalettes
-	jr FlushPalettes.done
+	jr FlushPalettesIfRequested.done
 
 ; copy b bytes of CGB palette data starting at
-; wBackgroundPalettesCGB + a palettes into rBGPD or rOGPD.
+; (wBackgroundPalettesCGB + a palettes) into rBGPD or rOGPD.
 CopyCGBPalettes: ; 0467 (0:0467)
 	add a
 	add a
@@ -589,7 +599,7 @@ CopyCGBPalettes: ; 0467 (0:0467)
 	inc c
 .wait
 	ld a, [rSTAT]
-	and $2
+	and 1 << STAT_BUSY ; wait until hblank or vblank
 	jr nz, .wait
 	ld a, [hl]
 	ld [$ff00+c], a
@@ -603,20 +613,24 @@ CopyCGBPalettes: ; 0467 (0:0467)
 	jr nz, .next_byte
 	ret
 
-Func_0492: ; 0492 (0:0492)
+; reads struct:
+;   x (1 byte), y (1 byte), data (n bytes), $00
+; writes data to BGMap0-translated x,y
+; important: make sure VRAM can be accessed first, else use WriteDataBlockToBGMap0
+UnsafeWriteDataBlockToBGMap0: ; 0492 (0:0492)
 	ld a, [hli]
 	ld b, a
 	ld a, [hli]
 	ld c, a
 	call BCCoordToBGMap0Address
-	jr .asm_49d
-.asm_49b
+	jr .next
+.loop
 	ld [de], a
 	inc de
-.asm_49d
+.next
 	ld a, [hli]
 	or a
-	jr nz, .asm_49b
+	jr nz, .loop
 	ret
 
 EmptyScreen: ; 04a2 (0:04a2)
@@ -2010,7 +2024,7 @@ Func_0bcb: ; 0bcb (0:0bcb)
 	ld a, [rLY]
 	cp LY_VBLANK + 3
 	jr nz, .wait_vbalnk
-	ld a, $43
+	ld a, LCDC_BGON | LCDC_OBJON | LCDC_WIN9C00
 	ld [rLCDC], a
 	ld a, %11100100
 	ld [rBGP], a
@@ -2038,7 +2052,7 @@ Func_0bcb: ; 0bcb (0:0bcb)
 	add hl, de
 	dec c
 	jr nz, .asm_bf3
-	ld a, $c3
+	ld a, LCDC_BGON | LCDC_OBJON | LCDC_WIN9C00 | LCDC_ON
 	ld [rLCDC], a
 	pop hl
 	call SendSGB
@@ -2070,12 +2084,12 @@ HblankCopyDataHLtoDE: ; 0c19 (0:0c19)
 	ei
 	di
 	ld a, [rSTAT]        ;
-	and $3               ;
+	and STAT_LCDC_STATUS ;
 	jr nz, .loop         ; assert hblank
 	ld a, [hl]
 	ld [de], a
 	ld a, [rSTAT]        ;
-	and $3               ;
+	and STAT_LCDC_STATUS ;
 	jr nz, .loop         ; assert still in hblank
 	ei
 	inc hl
@@ -2091,14 +2105,14 @@ HblankCopyDataDEtoHL: ; 0c32 (0:0c32)
 .loop
 	ei
 	di
-	ld a, [rSTAT]
-	and $3
-	jr nz, .loop
+	ld a, [rSTAT]        ;
+	and STAT_LCDC_STATUS ;
+	jr nz, .loop         ; assert hblank
 	ld a, [de]
 	ld [hl], a
-	ld a, [rSTAT]
-	and $3
-	jr nz, .loop
+	ld a, [rSTAT]        ;
+	and STAT_LCDC_STATUS ;
+	jr nz, .loop         ; assert still in hblank
 	ei
 	inc hl
 	inc de
@@ -2209,9 +2223,9 @@ SerialTimerHandler: ; 0c91 (0:0c91)
 	ld a, [rSC]          ;
 	add a                ; make sure that no serial transfer is active
 	ret c                ;
-	ld a, $1
+	ld a, SC_INTERNAL
 	ld [rSC], a          ; use internal clock
-	ld a, $81
+	ld a, SC_START | SC_INTERNAL
 	ld [rSC], a          ; use internal clock, set transfer start flag
 	ret
 .check_for_timeout
@@ -2253,9 +2267,9 @@ Func_0cc5: ; 0cc5 (0:0cc5)
 .asm_cdc
 	ld a, $29
 	ld [rSB], a
-	ld a, $01
+	ld a, SC_INTERNAL
 	ld [rSC], a
-	ld a, $81
+	ld a, SC_START | SC_INTERNAL
 	ld [rSC], a
 .asm_ce8
 	ld a, [hl]
@@ -2336,7 +2350,7 @@ SerialHandler: ; 0d26 (0:0d26)
 	cp $12               ; if [wSerialRecvBuf] != $12, use external clock
 	jr z, .done          ; and prepare for next byte.  either way, return
 .asm_d6a
-	ld a, $80            ;
+	ld a, SC_START | SC_EXTERNAL
 	ld [rSC], a          ; transfer start, use external clock
 .done
 	ld hl, wSerialCounter
@@ -2571,19 +2585,19 @@ Func_0e8e: ; 0e8e (0:0e8e)
 	call ClearSerialData
 	ld a, $12
 	ld [rSB], a          ; send $12
-	ld a, $80
+	ld a, SC_START | SC_EXTERNAL
 	ld [rSC], a          ; use external clock, set transfer start flag
 	ld a, [rIF]
-	and $f7
+	and ~(1 << INT_SERIAL)
 	ld [rIF], a          ; clear serial interrupt flag
 	ld a, [rIE]
-	or $8                ; enable serial interrupt
+	or 1 << INT_SERIAL   ; enable serial interrupt
 	ld [rIE], a
 	ret
 
 ResetSerial: ; 0ea6 (0:0ea6)
 	ld a, [rIE]
-	and $f7
+	and ~(1 << INT_SERIAL)
 	ld [rIE], a
 	xor a
 	ld [rSB], a
@@ -5486,7 +5500,7 @@ GetCardAlbumProgress: ; 1da4 (0:1da4)
 ; if LCD on, copy during h-blank only
 SafeCopyDataDEtoHL: ; 1dca (0:1dca)
 	ld a, [wLCDC]        ;
-	bit LCDC_ON, a  ;
+	bit LCDC_ENABLE_F, a ;
 	jr nz, .lcd_on       ; assert that LCD is on
 .lcd_off_loop
 	ld a, [de]
@@ -9344,9 +9358,9 @@ Func_31fc: ; 31fc (0:31fc)
 
 Func_3212: ; 3212 (0:3212)
 	ld [rSB], a
-	ld a, $1
+	ld a, SC_INTERNAL
 	ld [rSC], a
-	ld a, $81
+	ld a, SC_START | SC_INTERNAL
 	ld [rSC], a
 	ret
 
@@ -10529,7 +10543,7 @@ GameEvent_BattleCenter: ; 38a3 (0:38a3)
 	ld [wd112], a
 	ld a, -1
 	ld [wDuelResult], a
-	ld a, $2
+	ld a, MUSIC_DUEL_THEME_1
 	ld [wDuelTheme], a
 	ld a, MUSIC_CARD_POP
 	call PlaySong
@@ -10996,7 +11010,7 @@ Func_3b31: ; 3b31 (0:3b31)
 	jr c, .asm_3b45
 	xor a
 	ld [wDoFrameFunction], a
-	ld [wcad4], a
+	ld [wDoFrameFunction + 1], a
 .asm_3b45
 	call ZeroObjectPositions
 	ld a, 1
@@ -11198,7 +11212,7 @@ PushBC_Ret: ; 3c46 (0:3c46)
 DoFrameIfLCDEnabled: ; 3c48 (0:3c48)
 	push af
 	ld a, [rLCDC]
-	bit LCDC_ON, a
+	bit LCDC_ENABLE_F, a
 	jr z, .done
 	push bc
 	push de
@@ -11518,7 +11532,7 @@ Func_3df3: ; 3df3 (0:3df3)
 	ld hl, sp+$5
 	ld a, [hl]
 	call Func_12c7f
-	call SetFlushAllPalettes
+	call FlushAllPalettes
 	pop hl
 	pop af
 	call BankswitchHome
@@ -11625,7 +11639,7 @@ ApplyBackgroundScroll: ; 3ea6 (0:3ea6)
 	push hl
 	call DisableInt_LYCoincidence
 	ld hl, rSTAT
-	res 2, [hl] ; reset coincidence flag
+	res STAT_LYCFLAG, [hl] ; reset coincidence flag
 	ei
 	ld hl, wApplyBGScroll
 	ld a, [hl]
@@ -11648,7 +11662,7 @@ ApplyBackgroundScroll: ; 3ea6 (0:3ea6)
 	call GetNextBackgroundScroll
 	ld hl, rSTAT
 .wait_hblank_or_vblank
-	bit 1, [hl]
+	bit STAT_BUSY, [hl]
 	jr nz, .wait_hblank_or_vblank
 	ldh [rSCX], a
 	ldh a, [rLY]
@@ -11709,24 +11723,26 @@ GetNextBackgroundScroll: ; 3f38 (0:3f38)
 	ret
 ; 0x3f5a
 
+; enable lcdc interrupt on LYC=LC coincidence
 EnableInt_LYCoincidence: ; 3f5a (0:3f5a)
 	push hl
 	ld hl, rSTAT
-	set 6, [hl]
+	set STAT_LYC, [hl]
 	xor a
 	ld hl, rIE
-	set 1, [hl]
+	set INT_LCD_STAT, [hl]
 	pop hl
 	ret
 ; 0x3f68
 
+; disable lcdc interrupt and the LYC=LC coincidence trigger
 DisableInt_LYCoincidence: ; 3f68 (0:3f68)
 	push hl
 	ld hl, rSTAT
-	res 6, [hl]
+	res STAT_LYC, [hl]
 	xor a
 	ld hl, rIE
-	res 1, [hl]
+	res INT_LCD_STAT, [hl]
 	pop hl
 	ret
 ; 0x3f76
diff --git a/src/macros/constants.asm b/src/macros/constants.asm
index ceb0c7f..177fcd6 100644
--- a/src/macros/constants.asm
+++ b/src/macros/constants.asm
@@ -10,10 +10,3 @@ const: MACRO
 \1 EQU const_value
 const_value = const_value + 1
 ENDM
-
-deck_const: MACRO
-if const_value >= 2
-\1_ID EQU const_value + -2
-endc
-	const \1
-ENDM
diff --git a/src/macros/data.asm b/src/macros/data.asm
index 80c4ba2..53926da 100644
--- a/src/macros/data.asm
+++ b/src/macros/data.asm
@@ -85,15 +85,6 @@ tx: MACRO
 	dw \1_
 ENDM
 
-txsymbol: MACRO
-	const SYM_\1
-	charmap "\1>", const_value + -1
-ENDM
-
-fwcharmap: MACRO
-	charmap STRCAT("FW\1_", \2), \3
-ENDM
-
 textitem: MACRO
 	db \1, \2
 	tx \3
diff --git a/src/wram.asm b/src/wram.asm
index e40d382..6aed631 100644
--- a/src/wram.asm
+++ b/src/wram.asm
@@ -19,7 +19,7 @@ ENDU
 
 	ds $100
 
-SECTION "WRAM Duels 1", WRAM0
+SECTION "WRAM0 Duels 1", WRAM0
 
 ; In order to be identified during a duel, the 60 cards of each duelist are given an index between 0 and 59.
 ; These indexes are assigned following the order of the card list in wPlayerDeck or wOpponentDeck,
@@ -45,7 +45,7 @@ wPlayerCardLocations:: ; c200
 
 	ds $6
 
-; Which cards are in player's hand, as numbers 0 to 59
+; Deck indexes of the cards that are in the player's hand
 wPlayerHand:: ; c242
 	ds DECK_SIZE
 
@@ -61,12 +61,12 @@ wPlayerDeckCards:: ; c27e
 wPlayerNumberOfCardsNotInDeck:: ; c2ba
 	ds $1
 
-; Which card is in player's side of the field, as number 0 to 59
+; Deck index of the card that is in player's side of the field
 ; -1 indicates no pokemon
 wPlayerArenaCard:: ; c2bb
 	ds $1
 
-; Which cards are in player's bench, as numbers 0 to 59, plus an $ff (-1) terminator
+; Deck indexes of the cards that are in player's bench, plus an $ff (-1) terminator
 ; -1 indicates no pokemon
 wPlayerBench:: ; c2bc
 	ds MAX_BENCH_POKEMON + 1
@@ -323,6 +323,7 @@ wOpponentArenaCardDisabledMoveIndex:: ; c3f2
 
 UNION
 
+; temporary list of the cards drawn from a booster pack
 wBoosterCardsDrawn:: ; c400
 wBoosterTempNonEnergiesDrawn:: ; c400
 	ds $b
@@ -354,7 +355,7 @@ wDuelTempList:: ; c510
 wDefaultText:: ; c590
 	ds $70
 
-SECTION "WRAM Text Engine", WRAM0
+SECTION "WRAM0 Text Engine", WRAM0
 
 wc600:: ; c600
 	ds $100
@@ -368,11 +369,13 @@ wc800:: ; c800
 wc900:: ; c900
 	ds $100
 
-SECTION "WRAM Engine 1", WRAM0
+SECTION "WRAM0 1", WRAM0
 
 wOAM:: ; ca00
 	ds $a0
 
+; 16-byte buffer to store text, usually a name or a number
+; used by TX_RAM1 but not exclusively
 wTextBuf:: ; caa0
 	ds $10
 
@@ -385,7 +388,7 @@ wcab1:: ; cab1
 wcab2:: ; cab2
 	ds $1
 
-; initial value of the A register--used to tell the console when reset
+; initial value of the A register. used to tell the console when reset
 wInitialA:: ; cab3
 	ds $1
 
@@ -398,12 +401,14 @@ wConsole:: ; cab4
 wOAMOffset:: ; cab5
 	ds $1
 
+; FillTileMap fills VRAM0 BG Maps with the tile stored here
 wTileMapFill:: ; cab6
 	ds $1
 
 wIE:: ; cab7
 	ds $1
 
+; incremented whenever the vblank handler ends. used to wait for it to end
 wVBlankCounter:: ; cab8
 	ds $1
 
@@ -426,9 +431,12 @@ wOBP0:: ; cabd
 wOBP1:: ; cabe
 	ds $1
 
+; used to request palette(s) to be flushed by FlushPalettes from wBGP, wOBP0, wOBP1,
+; wBackgroundPalettesCGB, and/or wBackgroundPalettesCGB to the corresponding hw registers
 wFlushPaletteFlags:: ; cabf
 	ds $1
 
+; set to non-0 to request OAM copy during vblank
 wVBlankOAMCopyToggle:: ; cac0
 	ds $1
 
@@ -467,14 +475,13 @@ wRNGCounter:: ; cacc
 wLCDCFunctionTrampoline:: ; cacd
 	ds $3
 
+; a jp $nnnn instruction called by the vblank handler. calls a single ret by default
 wVBlankFunctionTrampoline:: ; cad0
 	ds $3
 
+; pointer to a function to be called by DoFrame
 wDoFrameFunction:: ; cad3
-	ds $1
-
-wcad4:: ; cad4
-	ds $1
+	ds $2
 
 wcad5:: ; cad5
 	ds $1
@@ -508,10 +515,11 @@ wcade:: ; cade
 wTempSGBPacket:: ; cae0
 	ds $10
 
-; temporal CGB palette data buffer to eventually save into BGPD or OBPD registers.
+; temporary CGB palette data buffer to eventually save into BGPD registers.
 wBackgroundPalettesCGB:: ; caf0
 	ds 8 palettes
 
+; temporary CGB palette data buffer to eventually save into OBPD registers.
 wObjectPalettesCGB:: ; cb30
 	ds 8 palettes
 
@@ -522,7 +530,7 @@ wObjectPalettesCGB:: ; cb30
 wListPointer:: ; cb72
 	ds $2
 
-SECTION "WRAM Serial Transfer", WRAM0
+SECTION "WRAM0 Serial Transfer", WRAM0
 
 wSerialOp:: ; cb74
 	ds $1
@@ -580,14 +588,14 @@ wSerialRecvBuf:: ; cba5
 
 	ds $1
 
-SECTION "WRAM Duels 2", WRAM0
+SECTION "WRAM0 Duels 2", WRAM0
 
 ; In a duel, the main menu current or last selected menu item
 ; From 0 to 5: Hand, Attack, Check, Pkmn Power, Retreat, Done
 wCurrentDuelMenuItem:: ; cbc6
 	ds $1
 
-; When we're viewing a card's information, the page we are currently at
+; When we're viewing a card's information, the page we are currently at.
 ; For Pokemon cards, values from $1 to $6 (two pages for move descriptions)
 ; For Energy cards, it's always $9
 ; For Trainer cards, $d or $e (two pages for trainer card descriptions)
@@ -605,6 +613,7 @@ wcbc9:: ; cbc9
 wBenchSelectedPokemon:: ; cbcb
 	ds $1
 
+; used by CheckIfEnoughEnergiesToRetreat and Func_4611
 wEnergyCardsRequiredToRetreat:: ; cbcc
 	ds $1
 
@@ -745,7 +754,7 @@ wDuelFinished:: ; cc07
 wDuelInitialPrizes:: ; cc08
 	ds $1
 
-; note that for a practice duel, wIsPracticeDuel must also be set to $1
+; a DUELTYPE_* constant. note that for a practice duel, wIsPracticeDuel must also be set to $1
 wDuelType:: ; cc09
 	ds $1
 
@@ -765,7 +774,7 @@ wDuelistType:: ; cc0d
 	ds $1
 
 ; this holds the current opponent's deck minus 2 (that is, a *_DECK_ID constant),
-; perhaps to account for the two unused pointers at the beginning of DeckPointers.
+; in order to account for the two unused pointers at the beginning of DeckPointers.
 wOpponentDeckID:: ; cc0e
 	ds $1
 
@@ -801,11 +810,12 @@ wcc18:: ; cc18
 wcc19:: ; cc19
 	ds $1
 
+; song played during a duel
 wDuelTheme:: ; cc1a
 	ds $1
 
 ; holds the energies attached to a given pokemon card. 1 byte for each of the
-; 8 energy types (including the unused one that shares byte with the colorless energy)
+; 8 energy types (includes the unused one that shares byte with the colorless energy)
 wAttachedEnergies:: ; cc1b
 	ds NUM_TYPES
 
@@ -813,17 +823,15 @@ wAttachedEnergies:: ; cc1b
 wTotalAttachedEnergies:: ; cc23
 	ds $1
 
-; Used as temporary storage for a loaded card's data
+; Used as temporary storage for a card's data
 wLoadedCard1:: ; cc24
 	card_data_struct wLoadedCard1
-
 wLoadedCard2:: ; cc65
 	card_data_struct wLoadedCard2
-
 wLoadedMove:: ; cca6
 	move_data_struct wLoadedMove
 
-; big-endian
+; damage dealt by an attack. little-endian
 wDamage:: ; ccb9
 	ds $2
 
@@ -839,6 +847,7 @@ wccbc:: ; ccbc
 wTempDamage_ccbf:: ; ccbf
 	ds $2
 
+; WEAKNESS and RESISTANCE flags	for a damaging attack
 wDamageEffectiveness:: ; ccc1
 	ds $1
 
@@ -910,19 +919,22 @@ wccf1:: ; ccf1
 wccf2:: ; ccf2
 	ds $1
 
-SECTION "WRAM Engine 2", WRAM0
+SECTION "WRAM0 2", WRAM0
 
 ; on CGB, attributes of the text box borders. (values 0-7? so only affects palette?)
 ; on SGB, colorize text box border with SGB1 if non-0
 wTextBoxFrameType:: ; ccf3
 	ds $1
 
+; pixel data of a tile used for text
+; either a combination of two half-width characters or a full-width character
 wTextTileBuffer:: ; ccf4
 	ds TILE_SIZE
 
 wcd04:: ; cd04
 	ds $1
 
+; used by PlaceNextTextTile
 wCurTextTile:: ; cd05
 	ds $1
 
@@ -1098,6 +1110,7 @@ wce21:: ; ce21
 ; During a duel, this is always $b after the first attack.
 ; $b is the bank where the functions associated to card or effect commands are.
 ; Its only purpose seems to be store this value to be read by TryExecuteEffectCommandFunction.
+; possibly used in other contexts too
 wce22:: ; ce22
 	ds $1
 
@@ -1155,6 +1168,7 @@ wWhichTxRam3:: ; ce4a
 wIsTextBoxLabeled:: ; ce4b
 	ds $1
 
+; text id of a text box's label
 wTextBoxLabel:: ; ce4c
 	ds $2
 
@@ -1413,7 +1427,7 @@ wd0c1:: ; d0c1
 wd0c2:: ; d0c2
 	ds $1
 
-; stores the player's result in a duel (0: loss, 1: win, 2: ???, -1: transmission error? )
+; stores the player's result in a duel (0: loss, 1: win, 2: ???, -1: transmission error?)
 ; to be read by the overworld caller
 wDuelResult:: ; d0c3
 	ds $1
@@ -1516,6 +1530,7 @@ wd132:: ; d132
 
 UNION
 
+; when opening a booster pack, list of cards available in the booster pack of a specific rarity
 wBoosterViableCardList:: ; d133
 	ds $100
 
@@ -1965,7 +1980,7 @@ wBoosterPackID:: ; d669
 wBoosterCurrentCard:: ; d66a
 	ds $1
 
-; booster card type of the card that has just been drawn from the pack
+; BOOSTER_CARD_TYPE_* of the card that has just been drawn from the pack
 wBoosterJustDrawnCardType:: ; d66b
 	ds $1
 
@@ -1973,26 +1988,24 @@ wBoosterJustDrawnCardType:: ; d66b
 wBoosterCurrentRarity:: ; d66c
 	ds $1
 
-; the averaged value of all values in wBoosterDataTypeChances
+; the averaged value of all values in wBoosterData_TypeChances
 ; used to recalculate the chances of a booster card type when a card of said type is drawn from the pack
 wBoosterAveragedTypeChances:: ; d66d
 	ds $1
 
 ; data of the booster pack copied from the corresponding BoosterSetRarityAmountsTable entry
-wBoosterDataCommonAmount:: ; d66e
+wBoosterData_CommonAmount:: ; d66e
 	ds $1
-
-wBoosterDataUncommonAmount:: ; d66f
+wBoosterData_UncommonAmount:: ; d66f
 	ds $1
-
-wBoosterDataRareAmount:: ; d670
+wBoosterData_RareAmount:: ; d670
 	ds $1
 
 ; how many cards of each type are available of a certain rarity in the booster pack's set
 wBoosterAmountOfCardTypeTable:: ; d671
 	ds NUM_BOOSTER_CARD_TYPES
 
-; holds information similar to wBoosterDataTypeChances, except that it contains 00 on any type
+; holds information similar to wBoosterData_TypeChances, except that it contains 00 on any type
 ; of which there are no cards remaining in the set for the current rarity
 wBoosterTempTypeChancesTable:: ; d67a
 	ds NUM_BOOSTER_CARD_TYPES
@@ -2000,22 +2013,18 @@ wBoosterTempTypeChancesTable:: ; d67a
 ; properties of the card being currently processed by the booster pack engine functions
 wBoosterCurrentCardType:: ; d683
 	ds $1
-
 wBoosterCurrentCardRarity:: ; d684
 	ds $1
-
 wBoosterCurrentCardSet:: ; d685
 	ds $1
 
 ; data of the booster pack copied from the corresponding BoosterPack_* structure.
-; wBoosterDataTypeChances is updated after each card is drawn, to re-balance the type chances.
-wBoosterDataSet:: ; d686
+; wBoosterData_TypeChances is updated after each card is drawn, to re-balance the type chances.
+wBoosterData_Set:: ; d686
 	ds $1
-
-wBoosterDataEnergyFunctionPointer:: ; d687
+wBoosterData_EnergyFunctionPointer:: ; d687
 	ds $2
-
-wBoosterDataTypeChances:: ; d689
+wBoosterData_TypeChances:: ; d689
 	ds NUM_BOOSTER_CARD_TYPES
 
 	ds $1
@@ -2037,7 +2046,7 @@ wd697:: ; d697
 
 	ds $6e8
 
-SECTION "WRAM Audio", WRAMX
+SECTION "WRAM1 Audio", WRAMX
 
 ; bit 7 is set once the song has been started
 wCurSongID:: ; dd80