Merge pull request #43 from xCrystal/master

Disassembly and documentation of code related to text engine, menus and lists, and retreating Pokemon cards in a duel

13 files changed, 1125 insertions, 481 deletions

diff --git a/src/constants/text_constants.asm b/src/constants/text_constants.asm
index 92554af..b5e6e22 100644
--- a/src/constants/text_constants.asm
+++ b/src/constants/text_constants.asm
@@ -21,52 +21,52 @@ done EQUS "db TX_END"
 
 	charmap "<", TX_SYMBOL
 	const_def
-	txsymbol SPACE
-	txsymbol FIRE
-	txsymbol GRASS
-	txsymbol LIGHTNING
-	txsymbol WATER
-	txsymbol FIGHTING
-	txsymbol PSYCHIC
-	txsymbol COLORLESS
-	txsymbol POISONED
-	txsymbol ASLEEP
-	txsymbol CONFUSED
-	txsymbol PARALYZED
-	txsymbol CURSOR_U
-	txsymbol POKEMON
-	txsymbol UNKNOWN_0E
-	txsymbol CURSOR_R
-	txsymbol HP
-	txsymbol Lv
-	txsymbol E
-	txsymbol No
-	txsymbol PLUSPOWER
-	txsymbol DEFENDER
-	txsymbol HP_OK
-	txsymbol HP_NOK
-	txsymbol BOX_TOP_L
-	txsymbol BOX_TOP_R
-	txsymbol BOX_BTM_L
-	txsymbol BOX_BTM_R
-	txsymbol BOX_TOP
-	txsymbol BOX_BOTTOM
-	txsymbol BOX_LEFT
-	txsymbol BOX_RIGHT
-	txsymbol 0
-	txsymbol 1
-	txsymbol 2
-	txsymbol 3
-	txsymbol 4
-	txsymbol 5
-	txsymbol 6
-	txsymbol 7
-	txsymbol 8
-	txsymbol 9
-	txsymbol DOT
-	txsymbol PLUS
-	txsymbol MINUS
-	txsymbol x
-	txsymbol SLASH
-	txsymbol CURSOR_D
-	txsymbol PRIZE
+	txsymbol SPACE      ; $00
+	txsymbol FIRE       ; $01
+	txsymbol GRASS      ; $02
+	txsymbol LIGHTNING  ; $03
+	txsymbol WATER      ; $04
+	txsymbol FIGHTING   ; $05
+	txsymbol PSYCHIC    ; $06
+	txsymbol COLORLESS  ; $07
+	txsymbol POISONED   ; $08
+	txsymbol ASLEEP     ; $09
+	txsymbol CONFUSED   ; $0a
+	txsymbol PARALYZED  ; $0b
+	txsymbol CURSOR_U   ; $0c
+	txsymbol POKEMON    ; $0d
+	txsymbol UNKNOWN_0E ; $0e
+	txsymbol CURSOR_R   ; $0f
+	txsymbol HP         ; $10
+	txsymbol Lv         ; $11
+	txsymbol E          ; $12
+	txsymbol No         ; $13
+	txsymbol PLUSPOWER  ; $14
+	txsymbol DEFENDER   ; $15
+	txsymbol HP_OK      ; $16
+	txsymbol HP_NOK     ; $17
+	txsymbol BOX_TOP_L  ; $18
+	txsymbol BOX_TOP_R  ; $19
+	txsymbol BOX_BTM_L  ; $1a
+	txsymbol BOX_BTM_R  ; $1b
+	txsymbol BOX_TOP    ; $1c
+	txsymbol BOX_BOTTOM ; $1d
+	txsymbol BOX_LEFT   ; $1e
+	txsymbol BOX_RIGHT  ; $1f
+	txsymbol 0          ; $20
+	txsymbol 1          ; $21
+	txsymbol 2          ; $22
+	txsymbol 3          ; $23
+	txsymbol 4          ; $24
+	txsymbol 5          ; $25
+	txsymbol 6          ; $26
+	txsymbol 7          ; $27
+	txsymbol 8          ; $28
+	txsymbol 9          ; $29
+	txsymbol DOT        ; $2a
+	txsymbol PLUS       ; $2b
+	txsymbol MINUS      ; $2c
+	txsymbol x          ; $2d
+	txsymbol SLASH      ; $2e
+	txsymbol CURSOR_D   ; $2f
+	txsymbol PRIZE      ; $30
diff --git a/src/engine/bank01.asm b/src/engine/bank01.asm
index 800e82c..97fe32a 100644
--- a/src/engine/bank01.asm
+++ b/src/engine/bank01.asm
@@ -13,7 +13,7 @@ GameLoop: ; 4000 (1:4000)
 	ld [wccf2], a
 	call DisableSRAM
 	ld a, 1
-	ld [wUppercaseFlag], a
+	ld [wUppercaseVWFLetters], a
 	ei
 	farcall CommentedOut_1a6cc
 	ldh a, [hButtonsHeld]
@@ -38,7 +38,7 @@ GameLoop: ; 4000 (1:4000)
 Func_4050: ; 4050 (1:4050)
 	farcall Func_1996e
 	ld a, 1
-	ld [wUppercaseFlag], a
+	ld [wUppercaseVWFLetters], a
 	ret
 
 Func_405a: ; 405a (1:405a)
@@ -357,8 +357,8 @@ DuelMainInterface: ; 426d (1:426d)
 
 PrintDuelMenu: ; 4295 (1:4295)
 	call DrawWideTextBox
-	ld hl, $54e9
-	call Func_2c08
+	ld hl, DuelMenuData
+	call PlaceTextItems
 .asm_429e
 	call $669d
 	ld a, [wDuelFinished]
@@ -398,7 +398,7 @@ PrintDuelMenu: ; 4295 (1:4295)
 	ld a, e
 	ld [wCurrentDuelMenuItem], a
 	jr nc, .handle_input
-	ldh a, [hCurrentMenuItem]
+	ldh a, [hCurMenuItem]
 	ld hl, DuelMenuFunctionTable
 	jp JumpToFunctionInTable
 
@@ -534,37 +534,43 @@ DuelMenu_Retreat: ; 43ab (1:43ab)
 	and CNF_SLP_PRZ
 	cp CONFUSED
 	ldh [hTemp_ffa0], a
-	jr nz, Func_43f1
-	ld a, [wcc0c]
+	jr nz, .not_confused
+	ld a, [wGotHeadsFromConfusionCheckDuringRetreat]
 	or a
-	jr nz, Func_43e8
-	call $45bb
-	jr c, Func_441f
-	call $4611
-	jr c, Func_441c
+	jr nz, .unable_due_to_confusion
+	call CheckAbleToRetreat
+	jr c, .unable_to_retreat
+	call Func_4611
+	jr c, .done
 	ldtx hl, SelectPkmnOnBenchToSwitchWithActiveText
 	call DrawWideTextBox_WaitForInput
 	call OpenPlayAreaScreenForSelection
-	jr c, Func_441c
+	jr c, .done
 	ld [wBenchSelectedPokemon], a
 	ld a, [wBenchSelectedPokemon]
 	ldh [hTempPlayAreaLocationOffset_ffa1], a
 	ld a, $04
 	call SetDuelAIAction
 	call AttemptRetreat
-	jr nc, Func_441c
+	jr nc, .done
 	call DrawDuelMainScene
 
-Func_43e8: ; 43e8
+.unable_due_to_confusion
 	ldtx hl, UnableToRetreatText
 	call DrawWideTextBox_WaitForInput
 	jp PrintDuelMenu
 
-Func_43f1: ; 43f1 (1:43f1)
-	call $45bb
-	jr c, Func_441f
-	call $4611
-	jr c, Func_441c
+.not_confused
+	; note that the energy cards are discarded (DiscardRetreatCostCards), then returned
+	; (ReturnRetreatCostCardsToArena), then discarded again for good (AttemptRetreat).
+	; It's done this way so that the retreating Pokemon is listed with its energies updated
+	; when the Play Area screen is shown to select the Pokemon to switch to. The reason why
+	; AttemptRetreat is responsible for discarding the energy cards is because, if the
+	; Pokemon is confused, it may not be able to retreat, so they cannot be discarded earlier.
+	call CheckAbleToRetreat
+	jr c, .unable_to_retreat
+	call Func_4611
+	jr c, .done
 	call DiscardRetreatCostCards
 	ldtx hl, SelectPkmnOnBenchToSwitchWithActiveText
 	call DrawWideTextBox_WaitForInput
@@ -572,17 +578,17 @@ Func_43f1: ; 43f1 (1:43f1)
 	ld [wBenchSelectedPokemon], a
 	ldh [hTempPlayAreaLocationOffset_ffa1], a
 	push af
-	call $6564
+	call ReturnRetreatCostCardsToArena
 	pop af
 	jp c, DuelMainInterface
 	ld a, $04
 	call SetDuelAIAction
 	call AttemptRetreat
 
-Func_441c: ; 441c (1:441c)
+.done
 	jp DuelMainInterface
 
-Func_441f: ; 441f (1:441f)
+.unable_to_retreat
 	call DrawWideTextBox_WaitForInput
 	jp PrintDuelMenu
 
@@ -795,7 +801,7 @@ DuelMenu_Check: ; 4585 (1:4585)
 	jp DuelMainInterface
 
 ; triggered by pressing SELECT in the duel menu
-DuelMenuShortcut_BothActivePokemon:: ; 458e (1:458e)
+DuelMenuShortcut_BothActivePokemon: ; 458e (1:458e)
 	call Func_3b31
 	call Func_4597
 	jp DuelMainInterface
@@ -824,7 +830,190 @@ Func_45a9: ; 45a9 (1:45a9)
 	ret
 ; 0x45bb
 
-	INCROM $45bb,  $46fc
+; check if the turn holder's arena Pokemon is unable to retreat due to
+; some status condition or due the bench containing no alive Pokemon.
+; return carry if unable, nc if able.
+CheckAbleToRetreat: ; 45bb (1:45bb)
+	call CheckCantRetreatDueToAcid
+	ret c
+	call CheckIfActiveCardParalyzedOrAsleep
+	ret c
+	call HasAlivePokemonOnBench
+	jr c, .unable_to_retreat
+	ld a, DUELVARS_ARENA_CARD
+	call GetTurnDuelistVariable
+	call GetCardIDFromDeckIndex
+	call LoadCardDataToBuffer1_FromCardID
+	ld a, [wLoadedCard1Type]
+	cp TYPE_TRAINER
+	jr z, .unable_to_retreat
+	call CheckIfEnoughEnergiesToRetreat
+	jr c, .not_enough_energies
+	or a
+	ret
+.not_enough_energies
+	ld a, [wEnergyCardsRequiredToRetreat]
+	ld l, a
+	ld h, $00
+	call LoadTxRam3
+	ldtx hl, EnergyCardsRequiredToRetreatText
+	jr .done
+.unable_to_retreat
+	ldtx hl, UnableToRetreatText
+.done
+	scf
+	ret
+; 0x45f4
+
+; check if the turn holder's arena Pokemon has enough energies attached to it
+; in order to retreat. Return carry if it doesn't.
+; load amount of energies required to wEnergyCardsRequiredToRetreat.
+CheckIfEnoughEnergiesToRetreat: ; 45f4 (1:45f4)
+	ld e, PLAY_AREA_ARENA
+	call GetPlayAreaCardAttachedEnergies
+	xor a
+	ldh [hTempPlayAreaLocationOffset_ff9d], a
+	call GetPlayAreaCardRetreatCost
+	ld [wEnergyCardsRequiredToRetreat], a
+	ld c, a
+	ld a, [wTotalAttachedEnergies]
+	cp c
+	ret c
+	ld [wcbcd], a
+	ld a, c
+	ld [wEnergyCardsRequiredToRetreat], a
+	or a
+	ret
+; 0x4611
+
+Func_4611: ; 4611 (1:4611)
+	ld a, $ff
+	ldh [hTempRetreatCostCards], a
+	ld a, [wEnergyCardsRequiredToRetreat]
+	or a
+	ret z
+	xor a
+	ld [wcbcd], a
+	call CreateArenaOrBenchEnergyCardList
+	call SortCardsInDuelTempListByID
+	ld a, LOW(hTempRetreatCostCards)
+	ld [wcbd5], a
+	xor a
+	call Func_4673
+	ld a, [wEnergyCardsRequiredToRetreat]
+	ld [wcbfa], a
+.asm_4633
+	ld a, [wcbcd]
+	ld [wcbfb], a
+	call Func_46b7
+	ret c
+	ldh a, [hTempCardIndex_ff98]
+	call LoadCardDataToBuffer2_FromDeckIndex
+	ld hl, wcbd5
+	ld c, [hl]
+	inc [hl]
+	ldh a, [hTempCardIndex_ff98]
+	ld [$ff00+c], a
+	ld c, $01
+	ld a, [wLoadedCard2Type]
+	cp TYPE_ENERGY_DOUBLE_COLORLESS
+	jr nz, .not_double
+	inc c
+.not_double
+	ld hl, wcbcd
+	ld a, [hl]
+	add c
+	ld [hl], a
+	ld hl, wEnergyCardsRequiredToRetreat
+	cp [hl]
+	jr nc, .asm_466a
+	ldh a, [hTempCardIndex_ff98]
+	call RemoveCardFromDuelTempList
+	call Func_4693
+	jr .asm_4633
+.asm_466a
+	ld a, [wcbd5]
+	ld c, a
+	ld a, $ff
+	ld [$ff00+c], a
+	or a
+	ret
+; 0x4673
+
+Func_4673: ; 4673 (1:4673)
+	ld [wcbe0], a
+	call EmptyScreen
+	call LoadDuelCardSymbolTiles
+	call LoadDuelFaceDownCardTiles
+	ld a, [wcbe0]
+	ld hl, wcbc9
+	ld [hli], a
+	ld [hl], $00
+	call Func_627c
+	xor a
+	ld [wcbfb], a
+	inc a
+	ld [wcbfa], a
+;	fallthrough
+
+Func_4693: ; 4693 (1:4693)
+	lb de, 0, 3
+	lb bc, 20, 10
+	call DrawRegularTextBox
+	ldtx hl, ChooseEnergyCardToDiscardText
+	call DrawWideTextBox_PrintTextNoDelay
+	call EnableLCD
+	call CountCardsInDuelTempList
+	ld hl, EnergyDiscardCardListParameters
+	lb de, 0, 0 ; initial page scroll offset, initial item (in the visible page)
+	call PrintCardListItems
+	ld a, 4
+	ld [wCardListIndicatorYPosition], a
+	ret
+; 0x46b7
+
+Func_46b7: ; 46b7 (1:46b7)
+	lb bc, $10, $10
+	ld a, [wcbfa]
+	or a
+	jr z, .asm_46d9
+	ld a, [wcbfb]
+	add SYM_0
+	call WriteByteToBGMap0
+	inc b
+	ld a, SYM_SLASH
+	call WriteByteToBGMap0
+	inc b
+	ld a, [wcbfa]
+	add SYM_0
+	call WriteByteToBGMap0
+	jr .asm_46e0
+.asm_46d9
+	ld a, [wcbfb]
+	inc b
+	call $65b7
+.asm_46e0
+	call DoFrame
+	call HandleCardListInput
+	jr nc, .asm_46e0
+	cp $ff
+	jr z, .asm_46f1
+	call GetCardInDuelTempList_OnlyDeckIndex
+	or a
+	ret
+.asm_46f1
+	scf
+	ret
+; 0x46f3
+
+EnergyDiscardCardListParameters:
+	db 1, 5 ; cursor x, cursor y
+	db 4 ; item x
+	db 14 ; maximum length, in tiles, occupied by the name and level string of each card in the list
+	db 4 ; number of items selectable without scrolling
+	db SYM_CURSOR_R ; cursor tile number
+	db SYM_SPACE ; tile behind cursor
+	dw $0000 ; function pointer if non-0
 
 ; triggered by selecting the "Attack" item in the duel menu
 DuelMenu_Attack: ; 46fc (1:46fc)
@@ -870,20 +1059,20 @@ DuelMenu_Attack: ; 46fc (1:46fc)
 	cp -1 ; was B pressed?
 	jp z, PrintDuelMenu
 	ld [wSelectedDuelSubMenuItem], a
-	call CheckIfEnoughEnergies
+	call CheckIfEnoughEnergiesToMove
 	jr nc, .enough_energy
 	ldtx hl, NotEnoughEnergyCardsText
 	call DrawWideTextBox_WaitForInput
 	jr .try_open_attack_menu
 
 .enough_energy
-	ldh a, [hCurrentMenuItem]
+	ldh a, [hCurMenuItem]
 	add a
 	ld e, a
 	ld d, $00
 	ld hl, wDuelTempList
 	add hl, de
-	ld d, [hl] ; card index within the deck (0 to 59)
+	ld d, [hl] ; card's deck index (0 to 59)
 	inc hl
 	ld e, [hl] ; attack index (0 or 1)
 	call CopyMoveDataAndDamage_FromDeckIndex
@@ -921,7 +1110,7 @@ Func_478b: ; 478b (1:478b)
 	call PlaceCardImageOAM
 	lb de, 6, 4
 	call ApplyBGP6OrSGB3ToCardImage
-	ldh a, [hCurrentMenuItem]
+	ldh a, [hCurMenuItem]
 	ld [wSelectedDuelSubMenuItem], a
 	add a
 	ld e, a
@@ -958,8 +1147,8 @@ AttackMenuParameters:
 	db 1, 13 ; cursor x, cursor y
 	db 2 ; y displacement between items
 	db 2 ; number of items
-	db $0f ; cursor tile number
-	db $00 ; tile behind cursor
+	db SYM_CURSOR_R ; cursor tile number
+	db SYM_SPACE ; tile behind cursor
 	dw $0000 ; function pointer if non-0
 
 Func_47ec: ; $47ec (1:47ec)
@@ -1087,22 +1276,22 @@ CheckIfMoveExists: ; 4872 (1:4872)
 ; check if the arena pokemon card has enough energy attached to it
 ; in order to use the selected move.
 ; returns: carry if not enough energy, nc if enough energy.
-CheckIfEnoughEnergies: ; 488f (1:488f)
+CheckIfEnoughEnergiesToMove: ; 488f (1:488f)
 	push hl
 	push bc
-	ld e, $0
+	ld e, PLAY_AREA_ARENA
 	call GetPlayAreaCardAttachedEnergies
 	call HandleEnergyBurn
-	ldh a, [hCurrentMenuItem]
+	ldh a, [hCurMenuItem]
 	add a
 	ld e, a
 	ld d, $0
 	ld hl, wDuelTempList
 	add hl, de
-	ld d, [hl] ; card index within the deck (0 to 59)
+	ld d, [hl] ; card's deck index (0 to 59)
 	inc hl
 	ld e, [hl] ; attack index (0 or 1)
-	call _CheckIfEnoughEnergies
+	call _CheckIfEnoughEnergiesToMove
 	pop bc
 	pop hl
 	ret
@@ -1110,11 +1299,11 @@ CheckIfEnoughEnergies: ; 488f (1:488f)
 
 ; check if a pokemon card has enough energy attached to it in order to use a move
 ; input:
-;   d = card index within the deck (0 to 59)
+;   d = deck index of card (0 to 59)
 ;   e = attack index (0 or 1)
 ;   wAttachedEnergies and wTotalAttachedEnergies
 ; returns: carry if not enough energy, nc if enough energy.
-_CheckIfEnoughEnergies: ; 48ac (1:48ac)
+_CheckIfEnoughEnergiesToMove: ; 48ac (1:48ac)
 	push de
 	ld a, d
 	call LoadCardDataToBuffer1_FromDeckIndex
@@ -1746,7 +1935,7 @@ Func_4f2d: ; 4f2d (1:4f2d)
 	ld a, DECK_SIZE
 	sub [hl]
 	cp $02
-	jr c, .asm_4f83
+	jr c, .one_card_in_deck
 	ldtx hl, ShufflesTheDeckText
 	call DrawWideTextBox_PrintText
 	call EnableLCD
@@ -1773,7 +1962,7 @@ Func_4f2d: ; 4f2d (1:4f2d)
 	call Func_3b31
 	ld a, $01
 	ret
-.asm_4f83
+.one_card_in_deck
 	ld l, a
 	ld h, $00
 	call LoadTxRam3
@@ -2096,7 +2285,7 @@ DoPracticeDuelAction: ; 51e7 (1:51e7)
 	jp JumpToFunctionInTable
 ; 0x51f8
 
-PracticeDuelActionTable:: ; 51f8 (1:51f8)
+PracticeDuelActionTable: ; 51f8 (1:51f8)
 	dw $0000
 	dw Func_520e
 	dw Func_521a
@@ -2207,7 +2396,7 @@ Func_52b0: ; 52b0 (1:52b0)
 	ldh a, [hTempPlayAreaLocationOffset_ff9d]
 	cp PLAY_AREA_BENCH_1
 	ret z
-	call $5fd9
+	call HasAlivePokemonOnBench
 	ldtx hl, Text01d7
 	scf
 ;	fallthrough
@@ -2220,7 +2409,20 @@ Func_52bc: ; 52bc (1:52bc)
 	ret
 ; 0x52c5
 
-	INCROM $52c5,  $5550
+	INCROM $52c5,  $54e9
+
+DuelMenuData: ; 54e9 (1:54e9)
+	; x, y, text id
+	textitem 3,  14, HandText
+	textitem 9,  14, CheckText
+	textitem 15, 14, RetreatText
+	textitem 3,  16, AttackText
+	textitem 9,  16, PKMNPowerText
+	textitem 15, 16, DoneText
+	db $ff
+; 0x5502
+
+	INCROM $5502,  $5550
 
 ; draw the turn holder's discard pile screen
 OpenDiscardPileScreen: ; 5550 (1:5550)
@@ -2336,7 +2538,7 @@ Func_55f0: ; 55f0 (1:55f0)
 	ld d, [hl] ; initial page scroll offset
 	ld hl, CardListParameters ; other list params
 	call PrintCardListItems
-	call DrawSelectedCard
+	call LoadSelectedCardGfx
 	call EnableLCD
 .asm_560b
 	call DoFrame
@@ -2356,7 +2558,7 @@ Func_55f0: ; 55f0 (1:55f0)
 	ld a, [wcbd6]
 	and b
 	jr nz, .asm_5654
-	ldh a, [hCurrentMenuItem]
+	ldh a, [hCurMenuItem]
 	call GetCardInDuelTempList_OnlyDeckIndex
 	call $56c2
 	jr c, Func_55f0
@@ -2377,10 +2579,10 @@ Func_55f0: ; 55f0 (1:55f0)
 	call EraseCursor
 	jr .asm_55f6
 .asm_5654
-	ldh a, [hCurrentMenuItem]
+	ldh a, [hCurMenuItem]
 	call GetCardInDuelTempList
 	call LoadCardDataToBuffer1_FromDeckIndex
-	call $5762
+	call Func_5762
 	ldh a, [hButtonsPressed2]
 	bit D_UP_F, a
 	jr nz, .asm_566f
@@ -2389,7 +2591,7 @@ Func_55f0: ; 55f0 (1:55f0)
 	call DrawCardListScreenLayout.draw
 	jp Func_55f0
 .asm_566f
-	ldh a, [hCurrentMenuItem]
+	ldh a, [hCurMenuItem]
 	or a
 	jr z, .asm_5654
 	dec a
@@ -2397,19 +2599,19 @@ Func_55f0: ; 55f0 (1:55f0)
 .asm_5677
 	call CountCardsInDuelTempList
 	ld b, a
-	ldh a, [hCurrentMenuItem]
+	ldh a, [hCurMenuItem]
 	inc a
 	cp b
 	jr nc, .asm_5654
 .asm_5681
-	ldh [hCurrentMenuItem], a
+	ldh [hCurMenuItem], a
 	ld hl, wSelectedDuelSubMenuItem
 	ld [hl], $00
 	inc hl
 	ld [hl], a
 	jr .asm_5654
 .asm_568c
-	ldh a, [hCurrentMenuItem]
+	ldh a, [hCurMenuItem]
 	scf
 	ret
 ; 0x5690
@@ -2428,7 +2630,7 @@ Func_5690: ; 5690 (1:5690)
 
 Func_56a0: ; 56a0 (1:56a0)
 	lb de, 1, 14
-	call AdjustCoordinatesForWindow
+	call AdjustCoordinatesForBGScroll
 	call Func_22ae
 	ld hl, wCardListInfoBoxText
 	ld a, [hli]
@@ -2452,19 +2654,74 @@ CardListParameters: ; 5710 (1;5710)
 	db 4 ; item x
 	db 14 ; maximum length, in tiles, occupied by the name and level string of each card in the list
 	db 5 ; number of items selectable without scrolling
-	db $0f ; cursor tile number
-	db $00 ; tile behind cursor
-	dw $5719 ; function pointer if non-0
+	db SYM_CURSOR_R ; cursor tile number
+	db SYM_SPACE ; tile behind cursor
+	dw CardListFunction ; function pointer if non-0
 ; 0x5719
 
-	INCROM $5719,  $5744
+CardListFunction: ; 5719 (1:5719)
+	ldh a, [hButtonsPressed]
+	bit B_BUTTON_F, a
+	jr nz, .exit
+	and A_BUTTON | SELECT | START
+	jr nz, .action_button
+	ldh a, [hButtonsReleased]
+	and D_PAD
+	jr nz, .reload_card_image ; jump if the D_PAD button was released this frame
+	ret
+.exit
+	ld a, $ff
+	ldh [hCurMenuItem], a
+.action_button
+	scf
+	ret
+.reload_card_image
+	call LoadSelectedCardGfx
+	or a
+	ret
+; 0x5735
+
+Func_5735: ; 5735 (1:5735)
+	ld hl, wcbd8
+	ld de, Func_574a
+	ld [hl], e
+	inc hl
+	ld [hl], d
+	ld a, 1
+	ld [wSortCardListByID], a
+	ret
+; 0x5744
 
 Func_5744: ; 5744 (1:5744)
 	ld hl, wcbd8
 	jp CallIndirect
 ; 0x574a
 
-	INCROM $574a,  $576a
+Func_574a: ; 574a (1:574a)
+	lb bc, 1, 2
+	ld hl, wDuelTempList + 10
+.next
+	ld a, [hli]
+	cp $ff
+	jr z, .done
+	or a ; SYM_SPACE
+	jr z, .space
+	add SYM_0
+.space
+	call WriteByteToBGMap0
+	; move two lines down
+	inc c
+	inc c
+	jr .next
+.done
+	ret
+; 0x5762
+
+Func_5762: ; 5762 (1:5762)
+	ld a, B_BUTTON | D_UP | D_DOWN
+	ld [wcbd7], a
+	xor a
+	jr Func_5779
 
 Func_576a: ; 576a (1:576a)
 	ld a, B_BUTTON
@@ -2507,10 +2764,10 @@ Func_5779: ; 5779 (1:5779)
 	and b
 	jr nz, .asm_57cc
 	ldh a, [hButtonsPressed]
-	and START + A_BUTTON
+	and START | A_BUTTON
 	jr nz, .asm_57a7
 	ldh a, [hButtonsPressed]
-	and D_RIGHT + D_LEFT
+	and D_RIGHT | D_LEFT
 	jr z, .asm_57af
 	call Func_57cd
 	jr .asm_57af
@@ -2553,8 +2810,8 @@ Func_589c: ; 589c (1:589c)
 ; 0x58aa
 
 ; load the tiles and palette of the card selected in card list screen
-DrawSelectedCard: ; 58aa (1:58aa)
-	ldh a, [hCurrentMenuItem]
+LoadSelectedCardGfx: ; 58aa (1:58aa)
+	ldh a, [hCurMenuItem]
 	call GetCardInDuelTempList
 	call LoadCardDataToBuffer1_FromCardID
 	ld de, v0Tiles1 + $20 tiles
@@ -3100,7 +3357,7 @@ LargeCardTileData: ; 5eb7 (1:5eb7)
 Func_5f4a: ; 5f4a (1:5f4a)
 	ld a, $01
 Func_5f4c: ; 5f4c (1:5f4c)
-	ld [wcd08], a
+	ld [wLineSeparation], a
 	ret
 ; 0x5f50
 
@@ -3123,7 +3380,7 @@ HasAlivePokemonOnBench: ; 5fd9 (1:5fd9)
 HasAlivePokemonInPlayArea: ; 5fdd (1:5fdd)
 	xor a
 _HasAlivePokemonInPlayArea: ; 5fde (1:5fde)
-	ld [wcbd2], a
+	ld [wExcludeArenaPokemon], a
 	ld b, a
 	ld a, DUELVARS_NUMBER_OF_POKEMON_IN_PLAY_AREA
 	call GetTurnDuelistVariable
@@ -3180,11 +3437,11 @@ _OpenPlayAreaScreen: ; 600e (1:600e)
 	call $61c7
 	call EnableLCD
 .asm_6034
-	ld hl, MenuParameters_60be
-	ld a, [wcbd2]
+	ld hl, PlayAreaScreenMenuParameters_ActivePokemonIncluded
+	ld a, [wExcludeArenaPokemon]
 	or a
 	jr z, .asm_6040
-	ld hl, MenuParameters_60c6
+	ld hl, PlayAreaScreenMenuParameters_ActivePokemonExcluded
 .asm_6040
 	ld a, [wSelectedDuelSubMenuItem]
 	call InitializeMenuParameters
@@ -3198,14 +3455,14 @@ _OpenPlayAreaScreen: ; 600e (1:600e)
 	jp z, $60ac
 	pop af
 	ldh [hTempCardIndex_ff98], a
-	ld a, [wcbd4]
+	ld a, [wcbd4] ; useless
 	jr OpenPlayAreaScreenForSelection
 .asm_6061
 	call HandleMenuInput
 	jr nc, .asm_604c
 	ld a, e
 	ld [wSelectedDuelSubMenuItem], a
-	ld a, [wcbd2]
+	ld a, [wExcludeArenaPokemon]
 	add e
 	ld [wcbc9], a
 	ld a, [wcbd6]
@@ -3223,12 +3480,12 @@ _OpenPlayAreaScreen: ; 600e (1:600e)
 	call Func_576a
 	jr .asm_6022
 .asm_6091
-	ld a, [wcbd2]
+	ld a, [wExcludeArenaPokemon]
 	ld c, a
-	ldh a, [hCurrentMenuItem]
+	ldh a, [hCurMenuItem]
 	add c
 	ldh [hTempPlayAreaLocationOffset_ff9d], a
-	ldh a, [hCurrentMenuItem]
+	ldh a, [hCurMenuItem]
 	cp $ff
 	jr z, .asm_60b5
 	ldh a, [hTempPlayAreaLocationOffset_ff9d]
@@ -3241,41 +3498,54 @@ _OpenPlayAreaScreen: ; 600e (1:600e)
 	pop af
 	ldh [hTempCardIndex_ff98], a
 	ldh a, [hTempPlayAreaLocationOffset_ff9d]
-	ldh [hCurrentMenuItem], a
+	ldh [hCurMenuItem], a
 	or a
 	ret
 .asm_60b5
 	pop af
 	ldh [hTempCardIndex_ff98], a
 	ldh a, [hTempPlayAreaLocationOffset_ff9d]
-	ldh [hCurrentMenuItem], a
+	ldh [hCurMenuItem], a
 	scf
 	ret
 ; 0x60be
 
-MenuParameters_60be: ; 60be (1:60be)
+PlayAreaScreenMenuParameters_ActivePokemonIncluded: ; 60be (1:60be)
 	db 0, 0 ; cursor x, cursor y
 	db 3 ; y displacement between items
 	db 6 ; number of items
-	db $0f ; cursor tile number
-	db $00 ; tile behind cursor
-	dw $60ce ; function pointer if non-0
+	db SYM_CURSOR_R ; cursor tile number
+	db SYM_SPACE ; tile behind cursor
+	dw PlayAreaScreenMenuFunction ; function pointer if non-0
 
-MenuParameters_60c6: ; 60c6 (1:60c6)
+PlayAreaScreenMenuParameters_ActivePokemonExcluded: ; 60c6 (1:60c6)
 	db 0, 3 ; cursor x, cursor y
 	db 3 ; y displacement between items
 	db 6 ; number of items
-	db $0f ; cursor tile number
-	db $00 ; tile behind cursor
-	dw $60ce ; function pointer if non-0
+	db SYM_CURSOR_R ; cursor tile number
+	db SYM_SPACE ; tile behind cursor
+	dw PlayAreaScreenMenuFunction ; function pointer if non-0
 
-	INCROM $60ce, $622a
+PlayAreaScreenMenuFunction: ; 60ce (1:60ce)
+	ldh a, [hButtonsPressed]
+	and A_BUTTON | B_BUTTON | START
+	ret z
+	bit B_BUTTON_F, a
+	jr z, .start_or_a
+	ld a, $ff
+	ldh [hCurMenuItem], a
+.start_or_a
+	scf
+	ret
+; 0x60dd
+
+	INCROM $60dd, $622a
 
 Func_622a: ; 622a (1:622a)
 	ld a, [wcbc9]
 	add DUELVARS_ARENA_CARD
 	call GetTurnDuelistVariable
-	cp $ff
+	cp -1
 	ret z
 	call Func_627c
 	ld a, [wcbc9]
@@ -3290,7 +3560,7 @@ Func_622a: ; 622a (1:622a)
 	jr z, .asm_624c
 	ld d, $0a
 .asm_624c
-	ld a, [$cbca]
+	ld a, [wcbc9 + 1]
 	ld b, $01
 	ld c, a
 	ld a, [hli]
@@ -3416,11 +3686,11 @@ Func_6510: ; 6510 (1:6510)
 	call LoadDuelCardSymbolTiles
 	call LoadDuelCheckPokemonScreenTiles
 	call Func_622a
-	ld de, $104
+	lb de, 1, 4
 	call Func_22ae
 	ld hl, wLoadedCard1Move1Name
 	call Func_2c20
-	ld de, $106
+	lb de, 1, 6
 	ld hl, wLoadedCard1Move1Description
 	call Func_653e
 	ret
@@ -3436,27 +3706,44 @@ Func_653e: ; 653e (1:653e)
 	jr c, .asm_654c
 	dec e
 .asm_654c
-	ld a, $13
+	ld a, 19
 	call Func_22a6
 	call Func_2c29
 	call Func_5f50
 	ret
 ; 0x6558
 
+; moves the cards loaded by deck index at hTempRetreatCostCards to the discard pile
 DiscardRetreatCostCards: ; 6558 (1:6558)
 	ld hl, hTempRetreatCostCards
-.discardLoop
+.discard_loop
 	ld a, [hli]
 	cp $ff
 	ret z
 	call PutCardInDiscardPile
-	jr .discardLoop
+	jr .discard_loop
 ; 0x6564
 
-	INCROM $6564, $657a
+; moves the discard pile cards that were loaded to hTempRetreatCostCards back to the active Pokemon.
+; this exists because they will be discarded again during the call to AttemptRetreat, so
+; it prevents the energy cards from being discarded twice.
+ReturnRetreatCostCardsToArena: ; 6564 (1:6564)
+	ld hl, hTempRetreatCostCards
+.loop
+	ld a, [hli]
+	cp $ff
+	ret z
+	push hl
+	call MoveDiscardPileCardToHand
+	call AddCardToHand
+	ld e, PLAY_AREA_ARENA
+	call PutHandCardInPlayArea
+	pop hl
+	jr .loop
+; 0x657a
 
-; discard retreat cost energy cards and attempt retreat
-; return carry on failure
+; discard retreat cost energy cards and attempt retreat.
+; return carry if unable to retreat this turn due to unsuccessful confusion check
 AttemptRetreat: ; 657a (1:657a)
 	call DiscardRetreatCostCards
 	ldh a, [hTemp_ffa0]
@@ -3466,8 +3753,8 @@ AttemptRetreat: ; 657a (1:657a)
 	ldtx de, ConfusionCheckRetreatText
 	call TossCoin
 	jr c, .success
-	ld a, $01
-	ld [wcc0c], a
+	ld a, 1
+	ld [wGotHeadsFromConfusionCheckDuringRetreat], a
 	scf
 	ret
 .success
@@ -3475,7 +3762,7 @@ AttemptRetreat: ; 657a (1:657a)
 	ld e, a
 	call SwapArenaWithBenchPokemon
 	xor a
-	ld [wcc0c], a
+	ld [wGotHeadsFromConfusionCheckDuringRetreat], a
 	ret
 ; 0x659f
 
@@ -3517,17 +3804,17 @@ Func_6635: ; 6635 (1:6635)
 	ld e, a
 	ld d, $00
 	call LoadCardDataToBuffer1_FromCardID
-	ld a, $01
+	ld a, CARDPAGE_POKEMON_OVERVIEW
 	ld [wCardPageNumber], a
 	ld hl, wLoadedCard1Move1Name
 	ld a, [wSelectedMoveIndex]
 	or a
-	jr z, .move_one
+	jr z, .first_move
 	ld hl, wLoadedCard1Move2Name
-.move_one
+.first_move
 	ld e, $01
 	call Func_5c33
-	ld de, $104
+	lb de, 1, 4
 	ld hl, wLoadedMoveDescription
 	call Func_653e
 	ret
@@ -3543,12 +3830,12 @@ Func_666a: ; 666a (1:666a)
 Func_6673: ; 6673 (1:6673)
 	call EmptyScreen
 	call Func_5f4a
-	ld de, $101
+	lb de, 1, 1
 	call Func_22ae
 	ld hl, wLoadedCard1Name
 	call Func_2c23
-	ld a, $13
-	ld de, $103
+	ld a, 19
+	lb de, 1, 3
 	call Func_22a6
 	ld hl, wLoadedCard1NonPokemonDescription
 	call Func_2c23
@@ -4048,7 +4335,7 @@ ConvertSpecialTrainerCardToPokemon: ; 6d84 (1:6d84)
 Func_70e6: ; 70e6 (1:70e6)
 	xor a
 	ld [wAlreadyPlayedEnergy], a
-	ld [wcc0c], a
+	ld [wGotHeadsFromConfusionCheckDuringRetreat], a
 	ld [wGotHeadsFromSandAttackOrSmokescreenCheck], a
 	ldh a, [hWhoseTurn]
 	ld [wcc05], a
@@ -4152,8 +4439,8 @@ _TossCoin: ; 71ad (1:71ad)
 	ld hl, $0000
 	call DrawLabeledTextBox
 	call EnableLCD
-	ld de, $010e
-	ld a, $13
+	lb de, 1, 14
+	ld a, 19
 	call Func_22a6
 	ld hl, wCoinTossScreenTextID
 	ld a, [hli]
diff --git a/src/engine/bank02.asm b/src/engine/bank02.asm
index e9f2868..87810fa 100644
--- a/src/engine/bank02.asm
+++ b/src/engine/bank02.asm
@@ -90,7 +90,7 @@ Func_8dbc: ; 8dbc (2:4dbc)
 	jr c, Func_8dbc
 	call HandleMenuInput
 	jr nc, .asm_8dc8
-	ldh a, [hCurrentMenuItem]
+	ldh a, [hCurMenuItem]
 	cp $ff
 	ret z
 	ld [wceb1], a
@@ -147,7 +147,7 @@ Func_8e1f: ; 8e1f (2:4e1f)
 Func_8e42: ; 8e42 (2:4e42)
 	call DrawWideTextBox
 	ld hl, Unknown_9027
-	call Func_2c08
+	call PlaceTextItems
 	call Func_905a
 .asm_8e4e
 	call DoFrame
@@ -580,7 +580,7 @@ Func_9168: ; 9168 (2:5168)
 	ld bc, $1404
 	call DrawRegularTextBox
 	ld hl, Unknown_9242
-	call Func_2c08
+	call PlaceTextItems
 	ld a, $4
 	ld hl, wceb2
 	call Func_9843
@@ -819,7 +819,7 @@ Func_b19d: ; b19d (2:719d)
 	call Func_905a
 	call DrawWideTextBox
 	ld hl, $7274
-	call Func_2c08
+	call PlaceTextItems
 	call DoFrame
 	call Func_9065
 	jp nc, $71e7
@@ -980,7 +980,7 @@ Func_ba04: ; ba04 (2:7a04)
 	ld [wd087], a
 	ld a, [wCurMenuItem]
 	ld [wd086], a
-	ldh a, [hCurrentMenuItem]
+	ldh a, [hCurMenuItem]
 	cp $ff
 	jp z, $7b0d
 	ld [wd088], a
@@ -989,7 +989,7 @@ Func_ba04: ; ba04 (2:7a04)
 	ld [wce5e], a
 	call DrawWideTextBox
 	ld hl, $7b76
-	call Func_2c08
+	call PlaceTextItems
 	call DoFrame
 	call $46ac
 	jp nc, $7acc
diff --git a/src/engine/bank03.asm b/src/engine/bank03.asm
index 8979d23..865cc5b 100644
--- a/src/engine/bank03.asm
+++ b/src/engine/bank03.asm
@@ -17,7 +17,7 @@ LoadMap: ; c000 (3:4000)
 	call LoadDuelHUDTiles
 	call Set_OBJ_8x8
 	xor a
-	ld [wcd08], a
+	ld [wLineSeparation], a
 	xor a
 	ld [wd291], a
 .asm_c037
@@ -990,7 +990,7 @@ MainMenu_c75a: ; c75a (3:475a)
 	jr nc, .asm_c76a
 	ld a, e
 	ld [wd0b8], a
-	ldh a, [hCurrentMenuItem]
+	ldh a, [hCurMenuItem]
 	cp e
 	jr nz, .asm_c793
 	cp $5
@@ -1074,7 +1074,7 @@ PC_c7ea: ; c7ea (3:47ea)
 	jr nc, .asm_c806
 	ld a, e
 	ld [wd0b9], a
-	ldh a, [hCurrentMenuItem]
+	ldh a, [hCurMenuItem]
 	cp e
 	jr nz, .asm_c82f
 	cp $4
@@ -1194,7 +1194,7 @@ Func_c915: ; c915 (3:4915)
 	push de
 	ld de, $000c
 	ld bc, $1406
-	call AdjustCoordinatesForWindow
+	call AdjustCoordinatesForBGScroll
 	call $43ca
 	pop de
 	pop bc
@@ -1723,7 +1723,7 @@ OWScript_AskQuestionJump: ; cce9 (3:4ce9)
 	ld l, c
 	ld h, b
 	call Func_c8ed
-	ld a, [hCurrentMenuItem]
+	ld a, [hCurMenuItem]
 	ld [wd415], a
 	jr c, .asm_ccfe
 	call GetOWSArgs3AfterPointer
@@ -2578,14 +2578,14 @@ Func_d28c: ; d28c (3:528c)
 	call DoFrameIfLCDEnabled
 	call HandleMenuInput
 	jr nc, .asm_d2c1
-	ld a, [hCurrentMenuItem]
+	ld a, [hCurMenuItem]
 	cp e
 	jr z, .asm_d2d9
 	ld a, [wd417]
 	or a
 	jr z, .asm_d2c1
 	ld e, a
-	ld [hCurrentMenuItem], a
+	ld [hCurMenuItem], a
 
 .asm_d2d9
 	pop hl
diff --git a/src/engine/bank04.asm b/src/engine/bank04.asm
index 3656e52..215132c 100644
--- a/src/engine/bank04.asm
+++ b/src/engine/bank04.asm
@@ -322,7 +322,7 @@ Func_10dba: ; 10dba (4:4dba)
 	jr nc, .asm_10dca
 	ld a, e
 	ld [wd0ba], a
-	ldh a, [hCurrentMenuItem]
+	ldh a, [hCurMenuItem]
 	cp e
 	jr z, .asm_10ddd
 	ld a, $4
diff --git a/src/engine/bank07.asm b/src/engine/bank07.asm
index 725b51b..1ebffa2 100644
--- a/src/engine/bank07.asm
+++ b/src/engine/bank07.asm
@@ -447,7 +447,7 @@ Func_1d11c: ; 1d11c (7:511c)
 	call Func_2275
 	call Func_3ca0
 	xor a
-	ld [wcd08], a
+	ld [wLineSeparation], a
 	call $51e1
 	call $517f
 	ld a, $ff
@@ -471,7 +471,7 @@ Func_1d11c: ; 1d11c (7:511c)
 	call $51e9
 	pop af
 	jr nc, .asm_1d15a
-	ldh a, [hCurrentMenuItem]
+	ldh a, [hCurMenuItem]
 	cp e
 	jr nz, .asm_1d15a
 	ld [wd627], a
diff --git a/src/engine/effect_functions.asm b/src/engine/effect_functions.asm
index 0d7a910..0f9bd72 100644
--- a/src/engine/effect_functions.asm
+++ b/src/engine/effect_functions.asm
@@ -97,14 +97,14 @@ CommentedOut_2c086: ; 2c086 (b:4086)
 	ret
 ; 0x2c087
 
-Func_2c087: ; 2c087 (b:4087)
+PlaceTextItems7: ; 2c087 (b:4087)
 	xor a
-	jr Func_2c08c
+	jr PlaceTextItemsc
 
-Func_2c08a: ; 2c08a (b:408a)
+PlaceTextItemsa: ; 2c08a (b:408a)
 	ld a, $1
 
-Func_2c08c:
+PlaceTextItemsc:
 	push de
 	push af
 	ld a, $11
diff --git a/src/engine/home.asm b/src/engine/home.asm
index 343ca14..29c9de2 100644
--- a/src/engine/home.asm
+++ b/src/engine/home.asm
@@ -20,7 +20,7 @@ SECTION "rst38", ROM0
 SECTION "vblank", ROM0
 	jp VBlankHandler
 SECTION "lcdc", ROM0
-	call wLCDCFunctiontrampoline
+	call wLCDCFunctionTrampoline
 	reti
 SECTION "timer", ROM0
 	jp TimerHandler
@@ -339,7 +339,7 @@ SetupLCD: ; 030b (0:030b)
 	xor a
 	ld [wReentrancyFlag], a
 	ld a, $c3            ; $c3 = jp nn
-	ld [wLCDCFunctiontrampoline], a
+	ld [wLCDCFunctionTrampoline], a
 	ld [wVBlankFunctionTrampoline], a
 	ld hl, wVBlankFunctionTrampoline + 1
 	ld [hl], LOW(NopF)   ;
@@ -2644,7 +2644,64 @@ Func_0ed5: ; 0ed5 (0:0ed5)
 	ret
 ; 0xef1
 
-	INCROM $0ef1, $0f35
+Func_0ef1: ; 0ef1 (0:0ef1)
+	ld de, wcb79
+	ld hl, sp+$fe
+	ld a, l
+	ld [de], a
+	inc de
+	ld a, h
+	ld [de], a
+	inc de
+	pop hl
+	push hl
+	ld a, l
+	ld [de], a
+	inc de
+	ld a, h
+	ld [de], a
+	or a
+	ret
+; 0xf05
+
+Func_0f05: ; 0f05 (0:0f05)
+	push hl
+	ld hl, wcb7b
+	ld a, [hli]
+	or [hl]
+	pop hl
+	ret z
+	ld hl, wcb79
+	ld a, [hli]
+	ld h, a
+	ld l, a
+	ld sp, hl
+	ld hl, wcb7b
+	ld a, [hli]
+	ld h, [hl]
+	ld l, a
+	push hl
+	scf
+	ret
+; 0xf1d
+
+Func_0f1d: ; 0f1d (0:0f1d)
+	ld a, [wSerialFlags]
+	or a
+	jr nz, .asm_f27
+	call Func_0e32
+	ret nc
+.asm_f27
+	ld a, $01
+	call BankswitchHome
+	ld hl, wcbf7
+	ld a, [hli]
+	ld h, [hl]
+	ld l, a
+	ld sp, hl
+	scf
+	ret
+; 0xf35
 
 DuelTransmissionError: ; 0f35 (0:0f35)
 	ld a, [wSerialFlags]
@@ -2936,7 +2993,7 @@ ShuffleDeck: ; 10bc (0:10bc)
 	ret
 
 ; draw a card from the turn holder's deck, saving its location as CARD_LOCATION_JUST_DRAWN
-; returns c if deck is empty, nc if a card was succesfully drawn
+; returns carry if deck is empty, nc if a card was succesfully drawn
 DrawCardFromDeck: ; 10cf (0:10cf)
 	push hl
 	ld a, DUELVARS_NUMBER_OF_CARDS_NOT_IN_DECK
@@ -2960,7 +3017,7 @@ DrawCardFromDeck: ; 10cf (0:10cf)
 ; 0x10e8
 
 ; add a card to the top of the turn holder's deck
-; the card is identified by register a, which contains the card number within the deck (0-59)
+; the card is identified by register a, which contains the deck index (0-59) of the card
 ReturnCardToDeck: ; 10e8 (0:10e8)
 	push hl
 	push af
@@ -2979,8 +3036,9 @@ ReturnCardToDeck: ; 10e8 (0:10e8)
 	ret
 ; 0x10fc
 
-; search a card in the turn holder's deck, extract it, and add it to the hand
-; the card is identified by register a, which contains the card number within the deck (0-59)
+; search a card in the turn holder's deck, extract it, and set its location to
+; CARD_LOCATION_JUST_DRAWN. AddCardToHand is meant to be called next.
+; the card is identified by register a, which contains the deck index (0-59) of the card
 SearchCardInDeckAndAddToHand: ; 10fc (0:10fc)
 	push af
 	push hl
@@ -3017,7 +3075,7 @@ SearchCardInDeckAndAddToHand: ; 10fc (0:10fc)
 ; 0x1123
 
 ; adds a card to the turn holder's hand and increments the number of cards in the hand
-; the card is identified by register a, which contains the card number within the deck (0-59)
+; the card is identified by register a, which contains the deck index (0-59) of the card
 AddCardToHand: ; 1123 (0:1123)
 	push af
 	push hl
@@ -3043,7 +3101,7 @@ AddCardToHand: ; 1123 (0:1123)
 ; 0x1139
 
 ; removes a card from the turn holder's hand and decrements the number of cards in the hand
-; the card is identified by register a, which contains the card number within the deck (0-59)
+; the card is identified by register a, which contains the deck index (0-59) of the card
 RemoveCardFromHand: ; 1139 (0:1139)
 	push af
 	push hl
@@ -3082,7 +3140,7 @@ RemoveCardFromHand: ; 1139 (0:1139)
 ; 0x1160
 
 ; moves a card to the turn holder's discard pile, as long as it is in the hand
-; the card is identified by register a, which contains the card number within the deck (0-59)
+; the card is identified by register a, which contains the deck index (0-59) of the card
 MoveHandCardToDiscardPile: ; 1160 (0:1160)
 	call GetTurnDuelistVariable
 	ld a, [hl]
@@ -3113,8 +3171,9 @@ PutCardInDiscardPile: ; 116a (0:116a)
 	ret
 ; 0x1182
 
-; search a card in the turn holder's discard pile, extract it, and add it to the hand
-; the card is identified by register a, which contains the card number within the deck (0-59)
+; search a card in the turn holder's discard pile, extract it, and set its location to
+; CARD_LOCATION_JUST_DRAWN. AddCardToHand is meant to be called next.
+; the card is identified by register a, which contains the deck index (0-59) of the card
 MoveDiscardPileCardToHand: ; 1182 (0:1182)
 	push hl
 	push de
@@ -3404,7 +3463,6 @@ SortCardsInListByID: ; 12ad (0:12ad)
 	ld l, a
 	ld e, l
 	ld d, h
-
 	; get ID of card with deck index at [de]
 	ld a, [de]
 	call GetCardIDFromDeckIndex_bc
@@ -3412,7 +3470,6 @@ SortCardsInListByID: ; 12ad (0:12ad)
 	ldh [hTempCardID_ff9b], a
 	ld a, b
 	ldh [hTempCardID_ff9b + 1], a ; 0
-
 	; hl = [hTempListPtr_ff99] + 1
 	inc hl
 	jr .check_list_end
@@ -3425,10 +3482,8 @@ SortCardsInListByID: ; 12ad (0:12ad)
 	jr nz, .go
 	ldh a, [hTempCardID_ff9b]
 	cp c
-
 .go
 	jr c, .not_lower_id
-
 	; this card has the lowest ID of those checked so far
 	ld e, l
 	ld d, h
@@ -3436,14 +3491,11 @@ SortCardsInListByID: ; 12ad (0:12ad)
 	ldh [hTempCardID_ff9b], a
 	ld a, b
 	ldh [hTempCardID_ff9b + 1], a
-
 .not_lower_id
 	inc hl
-
 .check_list_end
 	bit 7, [hl] ; $ff is the list terminator
 	jr z, .next_card_in_list
-
 	; reached list terminator
 	ld hl, hTempListPtr_ff99
 	push hl
@@ -3694,7 +3746,7 @@ EvolvePokemonCard: ; 13a2 (0:13a2)
 	ret
 ; 0x13f7
 
-; check if the turn holder's Pokemon card e can evolve into the turn holder's Pokemon card d.
+; check if the turn holder's Pokemon card at e can evolve into the turn holder's Pokemon card d.
 ; e is the play area location offset (PLAY_AREA_*) of the Pokemon trying to evolve.
 ; d is the deck index (0-59) of the Pokemon card that was selected to be the evolution target.
 ; return carry if can't evolve, plus nz if the reason for it is the card was played this turn.
@@ -4044,7 +4096,7 @@ SwapPlayAreaPokemon: ; 1548 (0:1548)
 
 ; Find which and how many energy cards are attached to the turn holder's Pokemon card in the arena,
 ; or a Pokemon card in the bench, depending on the value of register e.
-; input: e (location to check) = CARD_LOCATION_* - CARD_LOCATION_PLAY_AREA
+; input: e = location to check, i.e. PLAY_AREA_*
 ; Feedback is returned in wAttachedEnergies and wTotalAttachedEnergies.
 GetPlayAreaCardAttachedEnergies: ; 159f (0:159f)
 	push hl
@@ -4251,7 +4303,7 @@ CopyMoveDataAndDamage_FromCardID: ; 16ad (0:16ad)
 	ld d, $00
 	call LoadCardDataToBuffer1_FromCardID
 	pop de
-	jr CopyMoveDataAndDamage_FromDeckIndex.card_loaded
+	jr CopyMoveDataAndDamage
 
 ; copies, given a card identified by register d (0-59 deck index):
 ; - e into wSelectedMoveIndex and d into hTempCardIndex_ff9f
@@ -4263,7 +4315,9 @@ CopyMoveDataAndDamage_FromDeckIndex: ; 16c0 (0:16c0)
 	ld a, d
 	ldh [hTempCardIndex_ff9f], a
 	call LoadCardDataToBuffer1_FromDeckIndex
-.card_loaded
+;	fallthrough
+
+CopyMoveDataAndDamage:
 	ld a, [wLoadedCard1ID]
 	ld [wTempCardID_ccc2], a
 	ld hl, wLoadedCard1Move1
@@ -5107,7 +5161,9 @@ SubstractHPFromCard: ; 1c35 (0:1c35)
 ; 0x1c50
 
 ; check if a flag of wLoadedMove is set
-; input: a = %fffffbbb, where f = flag address counting from wLoadedMoveFlag1, and b = flag bit
+; input:
+	; a = %fffffbbb, where f = flag address counting from wLoadedMoveFlag1
+	; b = flag bit
 ; return carry if the flag is set
 CheckLoadedMoveFlag: ; 1c50 (0:1c50)
 	push hl
@@ -5451,8 +5507,8 @@ DECoordToBGMap0Address: ; 1ddb (0:1ddb)
 	ld h, a
 	ret
 
-; Apply window correction to xy coordinates at de
-AdjustCoordinatesForWindow: ; 1deb (0:1deb)
+; Apply SCX and SCY correction to xy coordinates at de
+AdjustCoordinatesForBGScroll: ; 1deb (0:1deb)
 	push af
 	ldh a, [hSCX]
 	rra
@@ -5579,8 +5635,8 @@ DrawRegularTextBox: ; 1e7c (0:1e7c)
 DrawRegularTextBoxDMG: ; 1e88 (0:1e88)
 	call DECoordToBGMap0Address
 	; top line (border) of the text box
-	ld a, $1c
-	lb de, $18, $19
+	ld a, SYM_BOX_TOP
+	lb de, SYM_BOX_TOP_L, SYM_BOX_TOP_R
 	call CopyLine
 ;	fallthrough
 
@@ -5588,14 +5644,14 @@ ContinueDrawingTextBoxDMGorSGB:
 	dec c
 	dec c
 .draw_text_box_body_loop
-	ld a, $0
-	lb de, $1e, $1f
+	ld a, SYM_SPACE
+	lb de, SYM_BOX_LEFT, SYM_BOX_RIGHT
 	call CopyLine
 	dec c
 	jr nz, .draw_text_box_body_loop
 	; bottom line (border) of the text box
-	ld a, $1d
-	lb de, $1a, $1b
+	ld a, SYM_BOX_BOTTOM
+	lb de, SYM_BOX_BTM_L, SYM_BOX_BTM_R
 ;	fallthrough
 
 ; copies b bytes of data to sp-$1f and to hl, and returns hl += BG_MAP_WIDTH
@@ -5637,8 +5693,8 @@ CopyLine: ; 1ea5 (0:1ea5)
 DrawRegularTextBoxCGB:
 	call DECoordToBGMap0Address
 	; top line (border) of the text box
-	ld a, $1c
-	lb de, $18, $19
+	ld a, SYM_BOX_TOP
+	lb de, SYM_BOX_TOP_L, SYM_BOX_TOP_R
 	call CopyCurrentLineTilesAndAttrCGB
 ;	fallthrough
 
@@ -5646,8 +5702,8 @@ ContinueDrawingTextBoxCGB:
 	dec c
 	dec c
 .draw_text_box_body_loop
-	ld a, $0
-	lb de, $1e, $1f
+	ld a, SYM_SPACE
+	lb de, SYM_BOX_LEFT, SYM_BOX_RIGHT
 	push hl
 	call CopyLine
 	pop hl
@@ -5661,8 +5717,8 @@ ContinueDrawingTextBoxCGB:
 	dec c
 	jr nz, .draw_text_box_body_loop
 	; bottom line (border) of the text box
-	ld a, $1d
-	lb de, $1a, $1b
+	ld a, SYM_BOX_BOTTOM
+	lb de, SYM_BOX_BTM_L, SYM_BOX_BTM_R
 	call CopyCurrentLineTilesAndAttrCGB
 	ret
 
@@ -5993,7 +6049,7 @@ Func_21f2: ; 21f2 (0:21f2)
 	cp $f
 	jr z, .asm_2221
 	cp $a
-	jr z, .asm_224d
+	jr z, .reached_line_length
 	cp TX_SYMBOL
 	jr z, .asm_2225
 	cp TX_START
@@ -6004,12 +6060,12 @@ Func_21f2: ; 21f2 (0:21f2)
 	ret
 .asm_220f
 	ld a, $1
-	ld [wcd0a], a
+	ld [wRegularFontOrVWF], a
 	ret
 .asm_2215
 	call Func_230f
 	xor a
-	ld [wcd0a], a
+	ld [wRegularFontOrVWF], a
 	ld a, $f
 	ldh [hffaf], a
 	ret
@@ -6018,53 +6074,55 @@ Func_21f2: ; 21f2 (0:21f2)
 	xor a
 	ret
 .asm_2225
-	ld a, [wcd0a]
+	ld a, [wRegularFontOrVWF]
 	push af
 	ld a, $1
-	ld [wcd0a], a
+	ld [wRegularFontOrVWF], a
 	call Func_230f
 	pop af
-	ld [wcd0a], a
+	ld [wRegularFontOrVWF], a
 	ldh a, [hffb0]
 	or a
 	jr nz, .asm_2240
 	ld a, [hl]
 	push hl
-	call Func_22f2
+	call PlaceNextTextTile
 	pop hl
 .asm_2240
 	inc hl
 .asm_2241
-	ldh a, [hffae]
+	ldh a, [hTextLineLength]
 	or a
 	ret z
 	ld b, a
-	ldh a, [hffac]
+	ldh a, [hTextLineCurPos]
 	cp b
-	jr z, .asm_224d
+	jr z, .reached_line_length
 	xor a
 	ret
-.asm_224d
+.reached_line_length
 	call Func_230f
-	ld a, [wcd08]
+	ld a, [wLineSeparation]
 	or a
-	call z, .asm_2257
-.asm_2257
+	call z, .next_line
+.next_line
 	xor a
-	ldh [hffac], a
-	ldh a, [hffad]
-	add $20
+	ldh [hTextLineCurPos], a
+	ldh a, [hTextHorizontalAlign]
+	add BG_MAP_WIDTH
 	ld b, a
-	ldh a, [hffaa]
+	; get current line's starting BGMap0 address
+	ldh a, [hTextBGMap0Address]
 	and $e0
-	add b
-	ldh [hffaa], a
-	ldh a, [hffab]
+	; advance to next line
+	add b ; apply background scroll correction
+	ldh [hTextBGMap0Address], a
+	ldh a, [hTextBGMap0Address + 1]
 	adc $0
-	ldh [hffab], a
-	ld a, [wcd09]
+	ldh [hTextBGMap0Address + 1], a
+	ld a, [wCurTextLine]
 	inc a
-	ld [wcd09], a
+	ld [wCurTextLine], a
 	xor a
 	ret
 
@@ -6079,9 +6137,9 @@ Func_2275: ; 2275 (0:2275)
 	ldh [hffb0], a
 	ldh [hffa9], a
 	ld a, $88
-	ld [wcd06], a
+	ld [wTilePatternSelector], a
 	ld a, $80
-	ld [wcd07], a
+	ld [wTilePatternSelectorCorrection], a
 	ld hl, wc600
 .asm_2292
 	xor a
@@ -6090,47 +6148,47 @@ Func_2275: ; 2275 (0:2275)
 	jr nz, .asm_2292
 	ret
 
-; wcd0a <- 0
-; hffac <- 0
+; wRegularFontOrVWF <- 0
+; hTextLineCurPos <- 0
 ; wcd0b <- 0
 ; hffaf <- $f
 Func_2298: ; 2298 (0:2298)
 	xor a
-	ld [wcd0a], a
-	ldh [hffac], a
+	ld [wRegularFontOrVWF], a
+	ldh [hTextLineCurPos], a
 	ld [wcd0b], a
 	ld a, $f
 	ldh [hffaf], a
 	ret
 
 ; Func_22ae
-; hffae <- a
+; hTextLineLength <- a
 Func_22a6: ; 22a6 (0:22a6)
 	push af
 	call Func_22ae
 	pop af
-	ldh [hffae], a
+	ldh [hTextLineLength], a
 	ret
 
-; hffad <- d
-; hffae <- 0
-; wcd09 <- 0
-; hffaa <- BGMap0(e)
-; hffab <- BGMap0(d)
+; hTextHorizontalAlign <- d
+; hTextLineLength <- 0
+; wCurTextLine <- 0
+; hTextBGMap0Address <- BGMap0(e)
+; hTextBGMap0Address + 1 <- BGMap0(d)
 ; Func_2298
-;; writes BGMap0-translated DE to (hffab,hffaa)
+;; writes BGMap0-translated DE to hTextBGMap0Address
 Func_22ae: ; 22ae (0:22ae)
 	push hl
 	ld a, d
-	ldh [hffad], a
+	ldh [hTextHorizontalAlign], a
 	xor a
-	ldh [hffae], a
-	ld [wcd09], a
+	ldh [hTextLineLength], a
+	ld [wCurTextLine], a
 	call DECoordToBGMap0Address
 	ld a, l
-	ldh [hffaa], a
+	ldh [hTextBGMap0Address], a
 	ld a, h
-	ldh [hffab], a
+	ldh [hTextBGMap0Address + 1], a
 	call Func_2298
 	xor a
 	ld [wcd0b], a
@@ -6145,33 +6203,30 @@ Func_22ca: ; 22ca (0:22ca)
 	and $1
 	jr nz, .asm_22ed
 	call Func_2325
-	jr c, .asm_22de
+	jr c, .tile_already_exists
 	or a
-	jr nz, .asm_22e9
-	call Func_24ac
-.asm_22de
+	jr nz, .done
+	call GenerateTextTile
+.tile_already_exists
 	ldh a, [hffb0]
 	and $2
-	jr nz, .asm_22e9
+	jr nz, .done
 	ldh a, [hffa9]
-	call Func_22f2
-.asm_22e9
+	call PlaceNextTextTile
+.done
 	pop bc
 	pop de
 	pop hl
 	ret
 .asm_22ed
 	call Func_235e
-	jr .asm_22e9
-
-; wcd05 <- a
-; &(hffab,hffaa) <- a
-; (hffab,hffaa) ++
-; hffac ++
-;; writes a to addr pointed to by (hffab,hffaa), then increments (hffab,hffaa) and hffac
-Func_22f2: ; 22f2 (0:22f2)
-	ld [wcd05], a
-	ld hl, hffaa
+	jr .done
+
+; writes a to wCurTextTile and to the tile pointed to by hTextBGMap0Address,
+; then increments hTextBGMap0Address and hTextLineCurPos
+PlaceNextTextTile: ; 22f2 (0:22f2)
+	ld [wCurTextTile], a
+	ld hl, hTextBGMap0Address
 	ld e, [hl]
 	inc hl
 	ld d, [hl]
@@ -6182,15 +6237,15 @@ Func_22f2: ; 22f2 (0:22f2)
 	dec de
 	ld l, e
 	ld h, d
-	ld de, wcd05
+	ld de, wCurTextTile
 	ld c, 1
 	call SafeCopyDataDEtoHL
-	ld hl, hffac
+	ld hl, hTextLineCurPos
 	inc [hl]
 	ret
 
 Func_230f: ; 230f (0:230f)
-	ld a, [wcd0a]
+	ld a, [wRegularFontOrVWF]
 	or a
 	ret z
 	ld a, [wcd0b]
@@ -6245,21 +6300,21 @@ Func_2325: ; 2325 (0:2325)
 	ld [hl], c
 	ld h, $c6
 	ld [hl], e
-	inc h
+	inc h ; $c7
 	ld [hl], d
 	ld b, l
 	xor a
 	ret
 
-; search linked-list for letters e/d (regisers), if found hoist the result to
-; head of list and return it. carry flag denotes success.
+; search linked-list for text characters e/d (registers), if found hoist
+; the result to head of list and return it. carry flag denotes success.
 Func_235e: ; 235e (0:235e)
-	ld a, [wcd0a]        ;
+	ld a, [wRegularFontOrVWF]
 	or a                 ;
-	jr z, .asm_2376      ; if [wcd0a] nonzero:
-	call Uppercase       ;   uppercase e
+	jr z, .asm_2376      ; if [wRegularFontOrVWF] nonzero:
+	call CaseVWFLetter   ;   uppercase e if wUppercaseVWFLetters != 0
 	ld a, [wcd0b]
-	ld d, a
+	ld d, a              ;   d ← [wcd0b]
 	or a
 	jr nz, .asm_2376     ;   if [wcd0b] is zero:
 	ld a, e              ;
@@ -6279,9 +6334,9 @@ Func_235e: ; 235e (0:235e)
 	ret z                ; if NULL, return a = 0  ;
 	cp e                                          ; loop for e/d key in
 	jr nz, .asm_238a     ;                        ; linked list
-	inc h                ;                        ;
+	inc h ; $c7          ;                        ;
 	ld a, [hl]           ; if key1[l] == e and    ;
-	cp d                 ;    key2[l] == d:       ;
+	cp d                 ;   key2[l] == d:        ;
 	jr z, .asm_238f      ;   break                ;
 .asm_238a
 	ld h, $c8            ;                        ;
@@ -6315,9 +6370,9 @@ Func_235e: ; 235e (0:235e)
 	scf                  ; set carry to indicate success
 	ret                  ; (return new linked-list head in a)
 
-; uppercases e if [wUppercaseFlag] is nonzero
-Uppercase: ; 23b1 (0:23b1)
-	ld a, [wUppercaseFlag]
+; uppercases e if [wUppercaseVWFLetters] is nonzero
+CaseVWFLetter: ; 23b1 (0:23b1)
+	ld a, [wUppercaseVWFLetters]
 	or a
 	ret z
 	ld a, e
@@ -6341,7 +6396,7 @@ Func_23c1: ; 23c1 (0:23c1)
 	ret
 .asm_23cf
 	xor a
-	ld [wcd0a], a
+	ld [wRegularFontOrVWF], a
 Func_23d3: ; 23d3 (0:23d3)
 	push hl
 	push de
@@ -6380,7 +6435,7 @@ Func_23d3: ; 23d3 (0:23d3)
 	INCROM $23fd, $245d
 
 ; convert the number at hl to TX_SYMBOL text format and write it to wcaa0
-; replace leading zeros with $00
+; replace leading zeros with SYM_SPACE
 TwoByteNumberToTxSymbol_TrimLeadingZeros: ; 245d (0:245d)
 	push de
 	push bc
@@ -6436,43 +6491,55 @@ TwoByteNumberToTxSymbol_TrimLeadingZeros: ; 245d (0:245d)
 	ld h, a
 	ret
 
-Func_24ac: ; 24ac (0:24ac)
+; generates a text tile and copies it to VRAM
+; if wRegularFontOrVWF == 0
+	; de = regular font tile number (d = $e and d = $f are treated differently)
+; if wRegularFontOrVWF != 0
+	; d = VWF character 1 (left)
+	; e = VWF character 2 (right)
+; b = destination VRAM tile number
+GenerateTextTile: ; 24ac (0:24ac)
 	push hl
 	push de
 	push bc
-	ld a, [wcd0a]
+	ld a, [wRegularFontOrVWF]
 	or a
-	jr nz, .asm_24bf
-	call Func_2510
+	jr nz, .vwf
+;.regular_font
+	call CreateRegularFontTile_ConvertToTileDataAddress
 	call SafeCopyDataDEtoHL
-.asm_24bb
+.done
 	pop bc
 	pop de
 	pop hl
 	ret
-.asm_24bf
-	call Func_24ca
-	call Func_2518
+.vwf
+	call CreateVWFTile
+	call ConvertTileNumberToTileDataAddress
 	call SafeCopyDataDEtoHL
-	jr .asm_24bb
+	jr .done
 
-Func_24ca: ; 24ca (0:24ca)
+; create, at wVWFOrRegularFontTile, a VWF tile made from the ascii characters given in d and e
+CreateVWFTile: ; 24ca (0:24ca)
 	push bc
 	ldh a, [hBankROM]
 	push af
 	ld a, BANK(VWF)
 	call BankswitchHome
+	; write the right half of the VWF tile (first character) to wVWFOrRegularFontTile + 2n
 	push de
 	ld a, e
-	ld de, wccf4
-	call Func_24fa
+	ld de, wVWFOrRegularFontTile
+	call CopyVWFCharacterToDE
 	pop de
+	; write the left half of the VWF tile (second character) to wVWFOrRegularFontTile + 2n+1
 	ld a, d
-	ld de, wccf5
-	call Func_24fa
-	ld hl, wccf4
-	ld b, $8
-.asm_24e8
+	ld de, wVWFOrRegularFontTile + 1
+	call CopyVWFCharacterToDE
+	; construct the resulting VWF tile
+	ld hl, wVWFOrRegularFontTile
+	ld b, TILE_SIZE / 2
+.loop
 	ld a, [hli]
 	swap a
 	or [hl]
@@ -6480,14 +6547,17 @@ Func_24ca: ; 24ca (0:24ca)
 	ld [hli], a
 	ld [hli], a
 	dec b
-	jr nz, .asm_24e8
+	jr nz, .loop
 	call BankpopHome
 	pop bc
-	ld de, wccf4
+	ld de, wVWFOrRegularFontTile
 	ret
 
-Func_24fa: ; 24fa (0:24fa)
-	sub $20
+; copies a half-tile corresponding to a VWF character to de
+; the ascii value of the character to copy is provided in a
+; assumes BANK(VWF) is already loaded
+CopyVWFCharacterToDE: ; 24fa (0:24fa)
+	sub $20 ; VWF begins at ascii $20
 	ld l, a
 	ld h, $0
 	add hl, hl
@@ -6495,23 +6565,32 @@ Func_24fa: ; 24fa (0:24fa)
 	add hl, hl
 	ld bc, VWF
 	add hl, bc
-	ld b, $8
-.set_timer8
+	ld b, TILE_SIZE / 2
+.loop
 	ld a, [hli]
 	ld [de], a
 	inc de
-	inc de
+	inc de ; skip the other half of the tile
 	dec b
-	jr nz, .set_timer8
+	jr nz, .loop
 	ret
 
-Func_2510: ; 2510 (0:2510)
+; create, at wVWFOrRegularFontTile, a regular font tile
+; given its tile number within the regular font graphics in de.
+; return its v*Tiles address in hl, and return c = TILE_SIZE.
+CreateRegularFontTile_ConvertToTileDataAddress: ; 2510 (0:2510)
 	push bc
-	call Func_256d
-	call Func_252e
+	call GetRegularFontTileOffset
+	call CreateRegularFontTile
 	pop bc
-Func_2518: ; 2518 (0:2518)
-	ld hl, wcd07
+;	fallthrough
+
+; given a tile number in b, return its v*Tiles address in hl, and return c = TILE_SIZE
+; wTilePatternSelector and wTilePatternSelectorCorrection are used to select the source:
+; - if wTilePatternSelector == $80 and wTilePatternSelectorCorrection == $00 -> $8000-$8FFF
+; - if wTilePatternSelector == $88 and wTilePatternSelectorCorrection == $80 -> $8800-$97FF
+ConvertTileNumberToTileDataAddress: ; 2518 (0:2518)
+	ld hl, wTilePatternSelectorCorrection
 	ld a, b
 	xor [hl]
 	ld h, $0
@@ -6520,33 +6599,35 @@ Func_2518: ; 2518 (0:2518)
 	add hl, hl
 	add hl, hl
 	add hl, hl
-	ld a, [wcd06]
+	ld a, [wTilePatternSelector]
 	ld b, a
 	ld c, $0
 	add hl, bc
-	ld c, $10
+	ld c, TILE_SIZE
 	ret
 
-Func_252e: ; 252e (0:252e)
+; create, at wVWFOrRegularFontTile, a regular font tile
+; given its offset within the font graphics in hl
+CreateRegularFontTile: ; 252e (0:252e)
 	ld a, BANK(Fonts); BANK(DuelGraphics); BANK(VWF)
 	call BankpushHome
-	ld de, wccf4
+	ld de, wVWFOrRegularFontTile
 	push de
-	ld c, $8
-.asm_2539
+	ld c, TILE_SIZE / 2
+.loop
 	ld a, [hli]
 	ld [de], a
 	inc de
 	ld [de], a
 	inc de
 	dec c
-	jr nz, .asm_2539
+	jr nz, .loop
 	pop de
 	call BankpopHome
 	ret
 
 Func_2546: ; 2546 (0:2546)
-	ld a, [wcd0a]
+	ld a, [wRegularFontOrVWF]
 	or a
 	jr nz, .asm_255f
 	ld a, e
@@ -6576,20 +6657,23 @@ Func_2546: ; 2546 (0:2546)
 	scf
 	ret
 
-Func_256d: ; 256d (0:256d)
-	ld bc, $0280
+; convert the regular font tile number at de to the
+; equivalent offset within the font tile graphics.
+; d = $e and d = $f are treated differently
+GetRegularFontTileOffset: ; 256d (0:256d)
+	ld bc, 40 tiles
 	ld a, d
 	cp $e
 	jr z, .asm_2580
 	cp $f
-	jr nz, .asm_2582
+	jr nz, .get_address
 	ld bc, $0000
 	ld a, e
 	sub $10
 	ld e, a
 .asm_2580
 	ld d, $0
-.asm_2582
+.get_address
 	ld l, e
 	ld h, d
 	add hl, hl
@@ -6602,8 +6686,10 @@ Func_256d: ; 256d (0:256d)
 	INCROM $2589, $25ea
 
 ; initializes parameters for a card list (e.g. list of hand cards in a duel or booster pack cards)
-; input: a = list length, de = initial page scroll offset, initial item (in the visible page)
-; hl: 9 bytes with the rest of the parameters
+; input:
+	; a = list length
+	; de = initial page scroll offset, initial item (in the visible page)
+	; hl: 9 bytes with the rest of the parameters
 InitializeCardListParameters: ; 25ea (0:25ea)
 	ld [wNumListItems], a
 	ld a, d
@@ -6611,7 +6697,7 @@ InitializeCardListParameters: ; 25ea (0:25ea)
 	ld a, e
 	ld [wCurMenuItem], a
 	add d
-	ldh [hCurrentMenuItem], a
+	ldh [hCurMenuItem], a
 	ld a, [hli]
 	ld [wCursorXPosition], a
 	ld a, [hli]
@@ -6648,7 +6734,7 @@ HandleCardListInput: ; 2626 (0:2626)
 	ld d, a
 	ld a, [wCurMenuItem]
 	ld e, a
-	ldh a, [hCurrentMenuItem]
+	ldh a, [hCurMenuItem]
 	scf
 	ret
 ; 0x2636
@@ -6660,7 +6746,7 @@ HandleCardListInput: ; 2626 (0:2626)
 ; also sets the current menu item to the one specified in register a
 InitializeMenuParameters: ; 2636 (0:2636)
 	ld [wCurMenuItem], a
-	ldh [hCurrentMenuItem], a
+	ldh [hCurMenuItem], a
 	ld de, wCursorXPosition
 	ld b, $8
 .loop
@@ -6711,7 +6797,7 @@ HandleMenuInput: ; 264b (0:264b)
 	ld [wCursorBlinkCounter], a
 .up_down_done
 	ld a, [wCurMenuItem]
-	ldh [hCurrentMenuItem], a
+	ldh [hCurMenuItem], a
 	ld hl, wMenuFunctionPointer ; call the function if non-0 (periodically)
 	ld a, [hli]
 	or [hl]
@@ -6719,7 +6805,7 @@ HandleMenuInput: ; 264b (0:264b)
 	ld a, [hld]
 	ld l, [hl]
 	ld h, a
-	ldh a, [hCurrentMenuItem]
+	ldh a, [hCurMenuItem]
 	call CallHL
 	jr nc, RefreshMenuCursor_CheckPlaySFX
 .A_pressed_draw_cursor
@@ -6728,7 +6814,7 @@ HandleMenuInput: ; 264b (0:264b)
 	call PlayOpenOrExitScreenSFX
 	ld a, [wCurMenuItem]
 	ld e, a
-	ldh a, [hCurrentMenuItem]
+	ldh a, [hCurMenuItem]
 	scf
 	ret
 .check_A_or_B
@@ -6741,16 +6827,16 @@ HandleMenuInput: ; 264b (0:264b)
 	ld a, [wCurMenuItem]
 	ld e, a
 	ld a, $ff
-	ldh [hCurrentMenuItem], a
+	ldh [hCurMenuItem], a
 	call PlayOpenOrExitScreenSFX
 	scf
 	ret
 
-; plays an "open screen" sound if [hCurrentMenuItem] != 0xff
-; plays an "exit screen" sound if [hCurrentMenuItem] == 0xff
+; plays an "open screen" sound if [hCurMenuItem] != 0xff
+; plays an "exit screen" sound if [hCurMenuItem] == 0xff
 PlayOpenOrExitScreenSFX: ; 26c0 (0:26c0)
 	push af
-	ldh a, [hCurrentMenuItem]
+	ldh a, [hCurMenuItem]
 	inc a
 	jr z, .play_exit_sfx
 	ld a, $2
@@ -6793,7 +6879,7 @@ DrawCursor:
 	inc hl
 	add [hl]
 	ld e, a
-	call AdjustCoordinatesForWindow
+	call AdjustCoordinatesForBGScroll
 	ld a, c
 	ld c, e
 	ld b, d
@@ -6808,7 +6894,7 @@ DrawCursor2: ; 270b (0:270b)
 
 SetMenuItem: ; 2710 (0:2710)
 	ld [wCurMenuItem], a
-	ldh [hCurrentMenuItem], a
+	ldh [hCurMenuItem], a
 	xor a
 	ld [wCursorBlinkCounter], a
 	ret
@@ -6816,7 +6902,7 @@ SetMenuItem: ; 2710 (0:2710)
 ; handle input for the 2-row 3-column duel menu.
 ; only handles input not involving the B, START, or SELECT buttons, that is,
 ; navigating through the menu or selecting an item with the A button.
-; other input in handled by HandleDuelMenuInputAndShortcuts.
+; other input in handled by PrintDuelMenu.handle_input
 HandleDuelMenuInput: ; 271a (0:271a)
 	ldh a, [hButtonsPressed2]
 	or a
@@ -6854,7 +6940,7 @@ HandleDuelMenuInput: ; 271a (0:271a)
 	call .asm_2772
 	pop af
 	ld [wCurMenuItem], a
-	ldh [hCurrentMenuItem], a
+	ldh [hCurMenuItem], a
 	xor a
 	ld [wCursorBlinkCounter], a
 	jr .blink_cursor
@@ -6906,14 +6992,15 @@ DuelMenuCursorCoords: ; 278d (0:278d)
 PrintCardListItems: ; 2799 (0:2799)
 	call InitializeCardListParameters
 	ld hl, wMenuFunctionPointer
-	ld a, LOW($283f)
+	ld a, LOW(CardListMenuFunction)
 	ld [hli], a
-	ld a, HIGH($283f)
+	ld a, HIGH(CardListMenuFunction)
 	ld [hli], a
 	ld a, 2
 	ld [wYDisplacementBetweenMenuItems], a
-	ld a, $01
-	ld [wcd97], a
+	ld a, 1
+	ld [wCardListIndicatorYPosition], a
+.reload
 	ld e, $00
 	ld a, [wListScrollOffset]
 	or a
@@ -6985,8 +7072,229 @@ PrintCardListItems: ; 2799 (0:2799)
 	ret
 ; 0x2827
 
-	INCROM $2827, $2988
+Func_2827: ; 2827 (0:2827)
+	ld a, $01
+	ldh [hffb0], a
+	call PrintCardListItems.reload
+	xor a
+	ldh [hffb0], a
+	ret
+; 0x2832
+
+; convert the number at a to TX_SYMBOL text format and write it to wDefaultText
+; if the first digit is a 0, delete it and shift the number one tile to the left
+OneByteNumberToTxSymbol_TrimLeadingZerosAndAlign: ; 2832 (0:2832)
+	call OneByteNumberToTxSymbol
+	ld a, [hli]
+	cp SYM_0
+	jr nz, .not_zero
+	; shift number one tile to the left
+	ld a, [hld]
+	ld [hli], a
+	ld [hl], $00
+.not_zero
+	ret
+; 0x283f
+
+; takes care of things like handling page scrolling and calling the function at wListFunctionPointer
+CardListMenuFunction: ; 283f (0:283f)
+	ldh a, [hButtonsPressed2]
+	ld b, a
+	ld a, [wNumMenuItems]
+	dec a
+	ld c, a
+	ld a, [wCurMenuItem]
+	bit D_UP_F, b
+	jr z, .not_up
+	cp c
+	jp nz, .continue
+	; we're at the top of the page
+	xor a
+	ld [wCurMenuItem], a ; set to first item
+	ld hl, wListScrollOffset
+	ld a, [hl]
+	or a ; can we scroll up?
+	jr z, .no_more_items
+	dec [hl] ; scroll page up
+	call PrintCardListItems.reload
+	jp .continue
+.not_up
+	bit D_DOWN_F, b
+	jr z, .not_down
+	or a
+	jr nz, .not_last_visible_item
+	; we're at the bottom of the page
+	ld a, c
+	ld [wCurMenuItem], a ; set to last item
+	ld a, [wListScrollOffset]
+	add c
+	inc a
+	ld hl, wNumListItems
+	cp [hl] ; can we scroll down?
+	jr z, .no_more_items
+	ld hl, wListScrollOffset
+	inc [hl] ; scroll page down
+	call PrintCardListItems.reload
+	jp .continue
+.not_last_visible_item
+	; this appears to be a redundant check
+	ld hl, wListScrollOffset
+	add [hl]
+	ld hl, wNumListItems
+	cp [hl]
+	jp c, .continue ; should always jump
+	ld hl, wCurMenuItem
+	dec [hl]
+.no_more_items
+	xor a
+	ld [wRefreshMenuCursorSFX], a
+	jp .continue
+.not_down
+	bit D_LEFT_F, b
+	jr z, .not_left
+	ld a, [wListScrollOffset]
+	or a
+	jr z, .continue
+	ld hl, wNumMenuItems
+	sub [hl]
+	jr c, .top_of_page_reached
+	ld [wListScrollOffset], a
+	call PrintCardListItems.reload
+	jr .continue
+.top_of_page_reached
+	call EraseCursor
+	ld a, [wListScrollOffset]
+	ld hl, wCurMenuItem
+	add [hl]
+	ld c, a
+	ld hl, wNumMenuItems
+	sub [hl]
+	jr nc, .asm_28c4
+	add [hl]
+.asm_28c4
+	ld [wCurMenuItem], a
+	xor a
+	ld [wListScrollOffset], a
+	ld [wRefreshMenuCursorSFX], a
+	call PrintCardListItems.reload
+	jr .continue
+.not_left
+	bit D_RIGHT_F, b
+	jr z, .continue
+	ld a, [wNumMenuItems]
+	ld hl, wNumListItems
+	cp [hl]
+	jr nc, .continue
+	ld a, [wListScrollOffset]
+	ld hl, wNumMenuItems
+	add [hl]
+	ld c, a
+	add [hl]
+	dec a
+	ld hl, wNumListItems
+	cp [hl]
+	jr nc, .asm_28f9
+	ld a, c
+	ld [wListScrollOffset], a
+	call PrintCardListItems.reload
+	jr .continue
+.asm_28f9
+	call EraseCursor
+	ld a, [wListScrollOffset]
+	ld hl, wCurMenuItem
+	add [hl]
+	ld c, a
+	ld a, [wNumListItems]
+	ld hl, wNumMenuItems
+	sub [hl]
+	ld [wListScrollOffset], a
+	ld b, a
+	ld a, c
+	sub b
+	jr nc, .asm_2914
+	add [hl]
+.asm_2914
+	ld [wCurMenuItem], a
+	call PrintCardListItems.reload
+.continue
+	ld a, [wListScrollOffset]
+	ld hl, wCurMenuItem
+	add [hl]
+	ldh [hCurMenuItem], a
+	ld a, [wCardListIndicatorYPosition]
+	cp $ff
+	jr z, .skip_printing_indicator
+	; print <sel_item>/<num_items>
+	ld c, a
+	ldh a, [hCurMenuItem]
+	inc a
+	call OneByteNumberToTxSymbol_TrimLeadingZeros
+	ld b, 13
+	ld a, 2
+	call CopyDataToBGMap0
+	ld b, 15
+	ld a, SYM_SLASH
+	call WriteByteToBGMap0
+	ld a, [wNumListItems]
+	call OneByteNumberToTxSymbol_TrimLeadingZeros
+	ld b, 16
+	ld a, 2
+	call CopyDataToBGMap0
+.skip_printing_indicator
+	ld hl, wListFunctionPointer
+	ld a, [hli]
+	or [hl]
+	jr z, .no_list_function
+	ld a, [hld]
+	ld l, [hl]
+	ld h, a
+	ldh a, [hCurMenuItem]
+	jp hl ; execute the function at wListFunctionPointer
+.no_list_function
+	ldh a, [hButtonsPressed]
+	and A_BUTTON | B_BUTTON
+	ret z
+	and B_BUTTON
+	jr nz, .pressed_b
+	scf
+	ret
+.pressed_b
+	ld a, $ff
+	ldh [hCurMenuItem], a
+	scf
+	ret
+; 0x296a
+
+; convert the number at a to TX_SYMBOL text format and write it to wDefaultText
+; replace leading zeros with SYM_SPACE
+OneByteNumberToTxSymbol_TrimLeadingZeros: ; 296a (0:296a)
+	call OneByteNumberToTxSymbol
+	ld a, [hl]
+	cp SYM_0
+	ret nz
+	ld [hl], SYM_SPACE
+	ret
+; 0x2974
+
+; convert the number at a to TX_SYMBOL text format and write it to wDefaultText
+OneByteNumberToTxSymbol: ; 2974 (0:2974)
+	ld hl, wDefaultText
+	push hl
+	ld e, SYM_0 - 1
+.first_digit_loop
+	inc e
+	sub 10
+	jr nc, .first_digit_loop
+	ld [hl], e ; first digit
+	inc hl
+	add SYM_0 + 10
+	ld [hli], a ; second digit
+	ld [hl], SYM_SPACE
+	pop hl
+	ret
+; 0x2988
 
+; translate the TYPE_* constant in wLoadedCard1Type to an index for CardSymbolTable
 CardTypeToSymbolID: ; 2988 (0:2988)
 	ld a, [wLoadedCard1Type]
 	cp TYPE_TRAINER
@@ -7005,6 +7313,8 @@ CardTypeToSymbolID: ; 2988 (0:2988)
 	ret
 ; 0x299f
 
+; return the entry in CardSymbolTable of the TYPE_* constant in wLoadedCard1Type
+; also return the first byte of said entry (starting tile number) in a
 GetCardSymbolData: ; 299f (0:299f)
 	call CardTypeToSymbolID
 	add a
@@ -7016,6 +7326,7 @@ GetCardSymbolData: ; 299f (0:299f)
 	ret
 ; 0x29ac
 
+; draw, at de, the 2x2 tile card symbol associated to the TYPE_* constant in wLoadedCard1Type
 DrawCardSymbol: ; 29ac (0:29ac)
 	push hl
 	push de
@@ -7049,7 +7360,7 @@ DrawCardSymbol: ; 29ac (0:29ac)
 ; 0x29dd
 
 CardSymbolTable:
-; starting tile, cgb palette (grey, red, blue, pink)
+; starting tile number, cgb palette (grey, red, blue, pink)
 	db $e0, $01 ; TYPE_ENERGY_FIRE
 	db $e4, $02 ; TYPE_ENERGY_GRASS
 	db $e8, $01 ; TYPE_ENERGY_LIGHTNING
@@ -7071,7 +7382,7 @@ CopyCardNameAndLevel: ; 29f5 (0:29f5)
 ; 0x29fa
 
 Func_29fa: ; 29fa (0:29fa)
-	lb bc, $0f, $00 ; cursor tile, tile behind cursor
+	lb bc, SYM_CURSOR_R, SYM_SPACE ; cursor tile, tile behind cursor
 	call SetCursorParametersForTextBox
 WaitForButtonAorB: ; 2a00 (0:2a00)
 	call DoFrame
@@ -7122,12 +7433,12 @@ DrawWideTextBox_PrintTextNoDelay: ; 2a36 (0:2a36)
 DrawNarrowTextBox_PrintTextNoDelay: ; 2a3e (0:2a3e)
 	push hl
 	call DrawNarrowTextBox
-	ld a, $b
+	ld a, 11
 ;	fallthrough
 
 Func_2a44: ; 2a44 (0:2a44)
 	lb de, 1, 14
-	call AdjustCoordinatesForWindow
+	call AdjustCoordinatesForBGScroll
 	call Func_22a6
 	pop hl
 	ld a, l
@@ -7139,9 +7450,9 @@ Func_2a44: ; 2a44 (0:2a44)
 DrawWideTextBox_PrintText: ; 2a59 (0:2a59)
 	push hl
 	call DrawWideTextBox
-	ld a, $13
+	ld a, 19
 	lb de, 1, 14
-	call AdjustCoordinatesForWindow
+	call AdjustCoordinatesForBGScroll
 	call Func_22a6
 	call EnableLCD
 	pop hl
@@ -7151,7 +7462,7 @@ DrawWideTextBox_PrintText: ; 2a59 (0:2a59)
 DrawNarrowTextBox: ; 2a6f (0:2a6f)
 	lb de, 0, 12
 	lb bc, 12, 6
-	call AdjustCoordinatesForWindow
+	call AdjustCoordinatesForBGScroll
 	call DrawRegularTextBox
 	ret
 
@@ -7173,15 +7484,15 @@ NarrowTextBoxMenuParameters: ; 2a96 (0:2a96)
 	db 10, 17 ; corsor x, cursor y
 	db 1 ; y displacement between items
 	db 1 ; number of items
-	db $2f ; cursor tile number
-	db $1d ; tile behind cursor
+	db SYM_CURSOR_D ; cursor tile number
+	db SYM_BOX_BOTTOM ; tile behind cursor
 	dw $0000 ; function pointer if non-0
 
 ; draws a 20x6 text box aligned to the bottom of the screen
 DrawWideTextBox: ; 2a9e (0:2a9e)
 	lb de, 0, 12
 	lb bc, 20, 6
-	call AdjustCoordinatesForWindow
+	call AdjustCoordinatesForBGScroll
 	call DrawRegularTextBox
 	ret
 
@@ -7206,8 +7517,8 @@ WideTextBoxMenuParameters: ; 2ac8 (0:2ac8)
 	db 18, 17 ; cursor x, cursor y
 	db 1 ; y displacement between items
 	db 1 ; number of items
-	db $2f ; cursor tile number
-	db $1d ; tile behind cursor
+	db SYM_CURSOR_D ; cursor tile number
+	db SYM_BOX_BOTTOM ; tile behind cursor
 	dw $0000 ; function pointer if non-0
 
 TwoItemHorizontalMenu: ; 2ad0 (0:2ad0)
@@ -7215,7 +7526,7 @@ TwoItemHorizontalMenu: ; 2ad0 (0:2ad0)
 	lb de, 6, 16 ; x, y
 	ld a, d
 	ld [wLeftmostItemCursorX], a
-	lb bc, $0f, $00 ; cursor tile, tile behind cursor
+	lb bc, SYM_CURSOR_R, SYM_SPACE ; cursor tile, tile behind cursor
 	call SetCursorParametersForTextBox
 	ld a, 1
 	ld [wCurMenuItem], a
@@ -7248,7 +7559,7 @@ YesOrNoMenuWithText_LeftAligned: ; 2afe (0:2afe)
 HandleYesOrNoMenu:
 	ld a, d
 	ld [wLeftmostItemCursorX], a
-	lb bc, $0f, $00 ; cursor tile, tile behind cursor
+	lb bc, SYM_CURSOR_R, SYM_SPACE ; cursor tile, tile behind cursor
 	call SetCursorParametersForTextBox
 	ld a, [wcd9a]
 	ld [wCurMenuItem], a
@@ -7285,7 +7596,7 @@ HandleYesOrNoMenu:
 	jr .wait_button_loop
 .a_pressed
 	ld a, [wCurMenuItem]
-	ldh [hCurrentMenuItem], a
+	ldh [hCurMenuItem], a
 	or a
 	jr nz, .no
 ;.yes
@@ -7295,13 +7606,13 @@ HandleYesOrNoMenu:
 	xor a
 	ld [wcd9a], a ; 0
 	ld a, 1
-	ldh [hCurrentMenuItem], a
+	ldh [hCurMenuItem], a
 	scf
 	ret
 
 ; prints YES NO at de
 PrintYesOrNoItems: ; 2b66 (0:2b66)
-	call AdjustCoordinatesForWindow
+	call AdjustCoordinatesForBGScroll
 	ldtx hl, YesOrNoText
 	call Func_2c1b
 	ret
@@ -7418,20 +7729,23 @@ Func_2bdb: ; 2bdb (0:2bdb)
 	ld a, c
 	ret
 
-Func_2c08: ; 2c08 (0:2c08)
-	ld d, [hl]
+; writes n items of text each given in the following format in hl:
+; x coord, y coord, text id
+; $ff-terminated
+PlaceTextItems: ; 2c08 (0:2c08)
+	ld d, [hl] ; x coord
 	inc hl
 	bit 7, d
-	ret nz
-	ld e, [hl]
-	inc hl
+	ret nz ; return if no more items of text
+	ld e, [hl] ; y coord
+	inc hl ; hl = text id
 	call Func_22ae
 	push hl
 	call Func_2c23
 	pop hl
 	inc hl
 	inc hl
-	jr Func_2c08
+	jr PlaceTextItems ; do next item
 
 Func_2c1b: ; 2c1b (0:2c1b)
 	call Func_22ae
@@ -7495,7 +7809,7 @@ Func_2c62: ; 2c62 (0:2c62)
 	jr Func_2c77
 .asm_2c67
 	push hl
-	ld hl, wce4c
+	ld hl, wTextBoxLabel
 	ld [hl], e
 	inc hl
 	ld [hl], d
@@ -7508,14 +7822,14 @@ Func_2c73: ; 2c73 (0:2c73)
 	call Func_2c84
 
 Func_2c77: ; 2c77 (0:2c77)
-	lb bc, $2f, $1d ; cursor tile, tile behind cursor
+	lb bc, SYM_CURSOR_D, SYM_BOX_BOTTOM ; cursor tile, tile behind cursor
 	lb de, 18, 17 ; x, y
 	call SetCursorParametersForTextBox
 	call WaitForButtonAorB
 	ret
 
 Func_2c84: ; 2c84 (0:2c84)
-	ld [wce4b], a
+	ld [wIsTextBoxLabeled], a
 	ldh a, [hBankROM]
 	push af
 	call ReadTextOffset
@@ -7543,8 +7857,8 @@ Func_2c84: ; 2c84 (0:2c84)
 .asm_2caf
 	call Func_2d43
 	jr c, .asm_2cc3
-	ld a, [wcd09]
-	cp $3
+	ld a, [wCurTextLine]
+	cp 3
 	jr c, .asm_2c93
 	call Func_2c77
 	call Func_2d15
@@ -7567,7 +7881,7 @@ Func_2cd7: ; 2cd7 (0:2cd7)
 	pop bc
 	ld a, [hffaf]
 	ld [hli], a
-	ld a, [wcd0a]
+	ld a, [wRegularFontOrVWF]
 	ld [hli], a
 	ldh a, [hBankROM]
 	ld [hli], a
@@ -7587,7 +7901,7 @@ Func_2cf3: ; 2cf3 (0:2cf3)
 	ld a, [hli]
 	ld [hffaf], a
 	ld a, [hli]
-	ld [wcd0a], a
+	ld [wRegularFontOrVWF], a
 	ld a, [hli]
 	call BankswitchHome
 	ld a, [hli]
@@ -7611,23 +7925,23 @@ Func_2d15: ; 2d15 (0:2d15)
 	push hl
 	lb de, 0, 12
 	lb bc, 20, 6
-	call AdjustCoordinatesForWindow
-	ld a, [wce4b]
+	call AdjustCoordinatesForBGScroll
+	ld a, [wIsTextBoxLabeled]
 	or a
-	jr nz, .asm_2d2d
+	jr nz, .labeled
 	call DrawRegularTextBox
 	call EnableLCD
 	jr .asm_2d36
-.asm_2d2d
-	ld hl, wce4c
+.labeled
+	ld hl, wTextBoxLabel
 	ld a, [hli]
 	ld h, [hl]
 	ld l, a
 	call DrawLabeledTextBox
 .asm_2d36
 	lb de, 1, 14
-	call AdjustCoordinatesForWindow
-	ld a, $13
+	call AdjustCoordinatesForBGScroll
+	ld a, 19
 	call Func_22a6
 	pop hl
 	ret
@@ -7637,7 +7951,7 @@ Func_2d43: ; 2d43 (0:2d43)
 	ld a, [hli]
 	or a ; TX_END
 	jr z, .asm_2d79
-	cp TX_SYMBOL
+	cp $5
 	jr c, .asm_2d65
 	cp $10
 	jr nc, .asm_2d65
@@ -7680,7 +7994,7 @@ Func_2d43: ; 2d43 (0:2d43)
 	ld a, $f
 	ld [hffaf], a
 	xor a
-	ld [wcd0a], a
+	ld [wRegularFontOrVWF], a
 	ld de, wTxRam2
 	ld hl, wce49
 	call Func_2de0
@@ -7760,14 +8074,14 @@ ReadTextOffset: ; 2ded (0:2ded)
 	pop de
 	ret
 
-; if [wcd0a] != 0:
+; if [wRegularFontOrVWF] != 0:
 ;   convert the number at hl to text (ascii) format and write it to wcaa0
 ;   return c = 4 - leading_zeros
-; if [wcd0a] == 0:
+; if [wRegularFontOrVWF] == 0:
 ;   convert the number at hl to TX_SYMBOL text format and write it to wcaa0
-;   replace leading zeros with $00
+;   replace leading zeros with SYM_SPACE
 TwoByteNumberToText_CountLeadingZeros: ; 2e12 (0:2e12)
-	ld a, [wcd0a]
+	ld a, [wRegularFontOrVWF]
 	or a
 	jp z, TwoByteNumberToTxSymbol_TrimLeadingZeros
 	ld de, wcaa0
@@ -7888,7 +8202,7 @@ Func_2ea9: ; 2ea9 (0:2ea9)
 	ret
 ; 0x2ebb
 
-; text pointer (usually of a card name) for TX_RAM2
+; text id (usually of a card name) for TX_RAM2
 LoadTxRam2: ; 2ebb (0:2ebb)
 	ld a, l
 	ld [wTxRam2], a
@@ -8030,8 +8344,10 @@ GetCardPointer: ; 2f7c (0:2f7c)
 	pop de
 	ret
 
-; input: hl = card_gfx_index, de = where to load the card gfx to
-; bc are supposed to be $30 and TILE_SIZE
+; input:
+	; hl = card_gfx_index
+	; de = where to load the card gfx to
+	; bc are supposed to be $30 (number of tiles of a card gfx) and TILE_SIZE respectively
 ; card_gfx_index = (<Name>CardGfx - CardGraphics) / 8 ; using absolute ROM addresses
 ; also copies the card's palette to wCardPalette
 LoadCardGfx: ; 2fa0 (0:2fa0)
@@ -8113,13 +8429,13 @@ TryExecuteEffectCommandFunction: ; 2fd9 (0:2fd9)
 ; input:
   ; a = command type to check
   ; hl = list of commands of current move or trainer card
-; return nc if command type matching a is found, c otherwise
+; return nc if command type matching a is found, carry otherwise
 CheckMatchingCommand: ; 2ffe (0:2ffe)
 	ld c, a
 	ld a, l
 	or h
 	jr nz, .not_null_pointer
-; return c if pointer is $0000
+; return carry if pointer is $0000
 	scf
 	ret
 
@@ -8954,7 +9270,7 @@ HandleTransparency: ; 348a (0:348a)
 	ret
 ; 0x34b7
 
-; return carry and return the appropriate text pointer in hl if the target has an
+; return carry and return the appropriate text id in hl if the target has an
 ; special status or power that prevents any damage or effect done to it this turn
 CheckNoDamageOrEffect: ; 34b7 (0:34b7)
 	ld a, [wNoDamageOrEffect]
diff --git a/src/hram.asm b/src/hram.asm
index 9fa125a..25f8f10 100644
--- a/src/hram.asm
+++ b/src/hram.asm
@@ -1,121 +1,126 @@
 SECTION "HRAM", HRAM
 
 hBankROM:: ; ff80
-	ds 1
+	ds $1
 
 hBankSRAM:: ; ff81
-	ds 1
+	ds $1
 
 hBankVRAM:: ; ff82
-	ds 1
+	ds $1
 
 hDMAFunction:: ; ff83
-	ds 10
+	ds $a
 
 hDPadRepeat:: ; ff8d
-	ds 1
+	ds $1
 
 hButtonsReleased:: ; ff8e
-	ds 1
+	ds $1
 
 hButtonsPressed2:: ; ff8f
-	ds 1
+	ds $1
 
 hButtonsHeld:: ; ff90
-	ds 1
+	ds $1
 
 hButtonsPressed:: ; ff91
-	ds 1
+	ds $1
 
 hSCX:: ; ff92
-	ds 1
+	ds $1
 
 hSCY:: ; ff93
-	ds 1
+	ds $1
 
 hWX:: ; ff94
-	ds 1
+	ds $1
 
 hWY:: ; ff95
-	ds 1
+	ds $1
 
 hff96:: ; ff96
-	ds 1
+	ds $1
 
 ; $c2 = player ; $c3 = opponent
 hWhoseTurn:: ; ff97
-	ds 1
+	ds $1
 
 ; deck index of a card (0-59)
 hTempCardIndex_ff98:: ; ff98
-	ds 1
+	ds $1
 
 ; used in SortCardsInListByID
 hTempListPtr_ff99:: ; ff99
-	ds 2
+	ds $2
 
 ; used in SortCardsInListByID
 ; this function supports 16-bit card IDs
 hTempCardID_ff9b:: ; ff9b
-	ds 2
+	ds $2
 
 ; a PLAY_AREA_ARENA constant (0: arena card, 1-5: bench card)
 hTempPlayAreaLocationOffset_ff9d:: ; ff9d
-	ds 1
+	ds $1
 
 hAIActionTableIndex:: ; ff9e
-	ds 1
+	ds $1
 
 hTempCardIndex_ff9f:: ; ff9f
-	ds 1
+	ds $1
 
 ; multipurpose temp storage
 hTemp_ffa0:: ; ffa0
-	ds 1
+	ds $1
 
 hTempPlayAreaLocationOffset_ffa1:: ; ffa1
-	ds 1
+	ds $1
 
-; FF-terminated list of cards to be discarded upon retreat
+; FF-terminated list of cards $to be discarded upon retreat
 hTempRetreatCostCards:: ; ffa2
-	ds 6
+	ds $6
 
 ; hffa8 through hffb0 appear to be related to text processing
 hffa8:: ; ffa8
-	ds 1
+	ds $1
 
 hffa9:: ; ffa9
-	ds 1
+	ds $1
 
-hffaa:: ; ffaa
-	ds 1
+; Address within v*BGMap0 where text is currently being written to
+hTextBGMap0Address:: ; ffaa
+	ds $2
 
-hffab:: ; ffab
-	ds 1
+; position within a line of text where text is currently being placed at
+; ranges between 0 and [hTextLineLength]
+hTextLineCurPos:: ; ffac
+	ds $1
 
-hffac:: ; ffac
-	ds 1
+; used as an x coordinate offset when printing text, in order to align
+; the text's starting position and/or adjust for the BG scroll registers
+hTextHorizontalAlign:: ; ffad
+	ds $1
 
-hffad:: ; ffad
-	ds 1
-
-hffae:: ; ffae
-	ds 1
+; how many tiles can be fit per line in the current text area
+; for example, 11 for a narrow text box and 19 for a wide text box
+hTextLineLength:: ; ffae
+	ds $1
 
 hffaf:: ; ffaf
-	ds 1
+	ds $1
 
 hffb0:: ; ffb0
-	ds 1
+	ds $1
 
-hCurrentMenuItem:: ; ffb1
-	ds 1
+; unlike wCurMenuItem, this accounts for the scroll offset (wListScrollOffset)
+hCurMenuItem:: ; ffb1
+	ds $1
 
-	ds 3
+	ds $3
 
 hffb5:: ; ffb5
-	ds 1
+	ds $1
 
 ; used in DivideBCbyDE
 hffb6:: ; ffb6
-	ds 1
+	ds $1
diff --git a/src/macros/data.asm b/src/macros/data.asm
index 7028636..ddb7443 100644
--- a/src/macros/data.asm
+++ b/src/macros/data.asm
@@ -89,3 +89,8 @@ txsymbol: MACRO
 	const SYM_\1
 	charmap "\1>", const_value + -1
 ENDM
+
+textitem: MACRO
+	db \1, \2
+	tx \3
+ENDM
diff --git a/src/text/text1.asm b/src/text/text1.asm
index 504dba0..4274caf 100644
--- a/src/text/text1.asm
+++ b/src/text/text1.asm
@@ -339,7 +339,7 @@ DamageToSelfDueToConfusionText: ; 3686c (d:686c)
 	text "20 damage to Self due to Confusion."
 	done
 
-Text0050: ; 36891 (d:6891)
+ChooseEnergyCardToDiscardText: ; 36891 (d:6891)
 	text "Choose the Energy card"
 	line "you wish to discard."
 	done
@@ -891,7 +891,7 @@ Text00be: ; 37715 (d:7715)
 	line "in your opponent's Play Area."
 	done
 
-Text00bf: ; 37758 (d:7758)
+EnergyCardsRequiredToRetreatText: ; 37758 (d:7758)
 	text TX_RAM3, " Energy cards"
 	line "are required to Retreat."
 	done
diff --git a/src/text/text_offsets.asm b/src/text/text_offsets.asm
index bef7afe..7838e80 100644
--- a/src/text/text_offsets.asm
+++ b/src/text/text_offsets.asm
@@ -81,7 +81,7 @@ TextOffsets:: ; 34000 (d:4000)
 	textpointer Text004d                                 ; 0x004d
 	textpointer Text004e                                 ; 0x004e
 	textpointer DamageToSelfDueToConfusionText           ; 0x004f
-	textpointer Text0050                                 ; 0x0050
+	textpointer ChooseEnergyCardToDiscardText                                 ; 0x0050
 	textpointer Text0051                                 ; 0x0051
 	textpointer Text0052                                 ; 0x0052
 	textpointer YouPlayFirstText                         ; 0x0053
@@ -192,7 +192,7 @@ TextOffsets:: ; 34000 (d:4000)
 	textpointer Text00bc                                 ; 0x00bc
 	textpointer Text00bd                                 ; 0x00bd
 	textpointer Text00be                                 ; 0x00be
-	textpointer Text00bf                                 ; 0x00bf
+	textpointer EnergyCardsRequiredToRetreatText                                 ; 0x00bf
 	textpointer NotEnoughEnergyCardsText                 ; 0x00c0
 	textpointer Text00c1                                 ; 0x00c1
 	textpointer Text00c2                                 ; 0x00c2
diff --git a/src/wram.asm b/src/wram.asm
index 0aec374..9289a0f 100644
--- a/src/wram.asm
+++ b/src/wram.asm
@@ -461,7 +461,7 @@ wCounter:: ; cacc
 	ds $1
 
 ; the LCDC status interrupt is always disabled and this always reads as jp $0000
-wLCDCFunctiontrampoline:: ; cacd
+wLCDCFunctionTrampoline:: ; cacd
 	ds $3
 
 wVBlankFunctionTrampoline:: ; cad0
@@ -536,7 +536,14 @@ wSerialCounter2:: ; cb77
 wSerialTimeoutCounter:: ; cb78
 	ds $1
 
-	ds $4
+wcb79:: ; cb79
+	ds $1
+
+wcb7a:: ; cb7a
+	ds $1
+
+wcb7b:: ; cb7b
+	ds $2
 
 wSerialSendSave:: ; cb7d
 	ds $1
@@ -595,9 +602,13 @@ wcbc9:: ; cbc9
 wBenchSelectedPokemon:: ; cbcb
 	ds $1
 
-	ds $2
+wEnergyCardsRequiredToRetreat:: ; cbcc
+	ds $1
+
+wcbcd:: ; cbcd
+	ds $1
 
-; used in CheckIfEnoughEnergies for the calculation
+; used in CheckIfEnoughEnergiesToMove for the calculation
 wAttachedEnergiesAccum:: ; cbce
 	ds $1
 
@@ -612,7 +623,9 @@ wSelectedDuelSubMenuScrollOffset:: ; cbd0
 wcbd1:: ; cbd1
 	ds $1
 
-wcbd2:: ; cbd2
+; when processing or displaying the play area Pokemon cards of a duelist,
+; whether to account for only the benched Pokemon ($01) or also the arena Pokemon ($00).
+wExcludeArenaPokemon:: ; cbd2
 	ds $1
 
 wcbd3:: ; cbd3
@@ -679,12 +692,21 @@ wcbe9:: ; cbe9
 wcbed:: ; cbed
 	ds $8
 
-	ds $4
+	ds $2
+
+wcbf7:: ; cbf7
+	ds $2
 
 wcbf9:: ; cbf9
 	ds $1
 
-	ds $4
+wcbfa:: ; cbfa
+	ds $1
+
+wcbfb:: ; cbfb
+	ds $1
+
+	ds $2
 
 ; during a practice duel, identifies an entry of PracticeDuelActionTable
 wPracticeDuelAction:: ; cbfe
@@ -731,7 +753,7 @@ wGotHeadsFromSandAttackOrSmokescreenCheck:: ; cc0a
 wAlreadyPlayedEnergy:: ; cc0b
 	ds $1
 
-wcc0c:: ; cc0c
+wGotHeadsFromConfusionCheckDuringRetreat:: ; cc0c
 	ds $1
 
 ; DUELIST_TYPE_* of the turn holder
@@ -890,44 +912,50 @@ SECTION "WRAM Engine 2", WRAM0
 wTextBoxFrameType:: ; ccf3
 	ds $1
 
-wccf4:: ; ccf4
-	ds $1
-
-wccf5:: ; ccf5
-	ds $1
-
-	ds $e
+wVWFOrRegularFontTile:: ; ccf4
+	ds $10
 
 wcd04:: ; cd04
 	ds $1
 
-wcd05:: ; cd05
+wCurTextTile:: ; cd05
 	ds $1
 
-wcd06:: ; cd06
+; VRAM tile patterns selector for text tiles
+; if wTilePatternSelector == $80 and wTilePatternSelectorCorrection == $00 -> select tiles at $8000-$8FFF
+; if wTilePatternSelector == $88 and wTilePatternSelectorCorrection == $80 -> select tiles at $8800-$97FF
+wTilePatternSelector:: ; cd06
 	ds $1
 
-wcd07:: ; cd07
+; complements wTilePatternSelector by correcting the VRAM tile order when $8800-$97FF is selected
+; a value of $80 in wTilePatternSelectorCorrection reflects tiles $00-$7f being located after tiles $80-$ff
+wTilePatternSelectorCorrection:: ; cd07
 	ds $1
 
-wcd08:: ; cd08
+; if 0, text lines are separated by a blank line
+wLineSeparation:: ; cd08
 	ds $1
 
-wcd09:: ; cd09
+; line number in which text is being printed as an offset to
+; the topmost line, including separator lines
+wCurTextLine:: ; cd09
 	ds $1
 
-wcd0a:: ; cd0a
+; how to process the current text tile
+; 0: regular font | non-0: VWF
+wRegularFontOrVWF:: ; cd0a
 	ds $1
 
 wcd0b:: ; cd0b
 	ds $2
 
-wUppercaseFlag:: ; cd0d
+; VWF letters become uppercase if non-0, lowercase if 0
+wUppercaseVWFLetters:: ; cd0d
 	ds $1
 
 	ds $1
 
-; Handles timing of (horizontal or vertical) arrow blinking while waiting for user input.
+; handles timing of (horizontal or vertical) arrow blinking while waiting for user input.
 wCursorBlinkCounter:: ; cd0f
 	ds $1
 
@@ -952,6 +980,7 @@ wCursorTileNumber:: ; cd15
 wTileBehindCursor:: ; cd16
 	ds $1
 
+; if non-$0000, the function loaded here is called once per frame by HandleMenuInput
 wMenuFunctionPointer:: ; cd17
 	ds $2
 
@@ -967,12 +996,16 @@ wNumListItems:: ; cd1b
 wListItemNameMaxLength:: ; cd1c
 	ds $1
 
+; if non-$0000, the function loaded here is called once per frame by CardListMenuFunction,
+; which is the function loaded to wMenuFunctionPointer for card lists
 wListFunctionPointer:: ; cd1d
 	ds $2
 
 	ds $78
 
-wcd97:: ; cd97
+; in a card list, the Y position where the <sel_item>/<num_items> indicator is placed
+; if wCardListIndicatorYPosition == $ff, no indicator is displayed
+wCardListIndicatorYPosition:: ; cd97
 	ds $1
 
 ; x coord of the leftmost item in a horizontal menu
@@ -1064,12 +1097,12 @@ wce2b:: ; ce2b
 
 	ds $13
 
-; text pointer for the first TX_RAM2 of a text
+; text id for the first TX_RAM2 of a text
 ; prints from wDefaultText if $0000
 wTxRam2:: ; cd3f
 	ds $2
 
-; text pointer for the second TX_RAM2 of a text
+; text id for the second TX_RAM2 of a text
 wTxRam2_b:: ; ce41
 	ds $2
 
@@ -1092,10 +1125,10 @@ wce49:: ; ce49
 wce4a:: ; ce4a
 	ds $1
 
-wce4b:: ; ce4b
+wIsTextBoxLabeled:: ; ce4b
 	ds $1
 
-wce4c:: ; ce4c
+wTextBoxLabel:: ; ce4c
 	ds $2
 
 wCoinTossScreenTextID:: ; ce4e
@@ -1926,7 +1959,7 @@ wd697:: ; d697
 
 	ds $6e8
 
-SECTION "WRAM Music", WRAMX
+SECTION "WRAM Audio", WRAMX
 
 ; bit 7 is set once the song has been started
 wCurSongID:: ; dd80
@@ -2096,8 +2129,6 @@ wMusicCh3Stack:: ; de13
 wMusicCh4Stack:: ; de1f
 	ds $c
 
-SECTION "WRAM Sfx", WRAMX
-
 wde2b:: ; de2b
 	ds $3