Merge pull request #48 from xCrystal/master

More home and bank1 progress
author: xCrystal <rgr.crystal@gmail.com> 2018-08-13 14:54:31 +0200
committer: GitHub <noreply@github.com> 2018-08-13 14:54:31 +0200
commit: f5330d15daed2d77ff48360554a36162843fe199 (patch)
tree: f8142591ea01c720be6d6b979b2fadb84e3018f0 /src
parent: 783f5fe610c69006742b4976ab4f183f39512d89 (diff)
parent: 3581a4baed71f596eedb9c234b910f1d6a7736be (diff)
36 files changed, 5444 insertions, 2104 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_constants.asm b/src/constants/card_constants.asm
index 30560c2..df6da6b 100644
--- a/src/constants/card_constants.asm
+++ b/src/constants/card_constants.asm
@@ -8,12 +8,12 @@
 	const DOUBLE_COLORLESS_ENERGY ; $07
 	const BULBASAUR               ; $08
 	const IVYSAUR                 ; $09
-	const VENUSAUR1               ; $0A
-	const VENUSAUR2               ; $0B
-	const CATERPIE                ; $0C
-	const METAPOD                 ; $0D
-	const BUTTERFREE              ; $0E
-	const WEEDLE                  ; $0F
+	const VENUSAUR1               ; $0a
+	const VENUSAUR2               ; $0b
+	const CATERPIE                ; $0c
+	const METAPOD                 ; $0d
+	const BUTTERFREE              ; $0e
+	const WEEDLE                  ; $0f
 	const KAKUNA                  ; $10
 	const BEEDRILL                ; $11
 	const EKANS                   ; $12
@@ -24,12 +24,12 @@
 	const NIDORANM                ; $17
 	const NIDORINO                ; $18
 	const NIDOKING                ; $19
-	const ZUBAT                   ; $1A
-	const GOLBAT                  ; $1B
-	const ODDISH                  ; $1C
-	const GLOOM                   ; $1D
-	const VILEPLUME               ; $1E
-	const PARAS                   ; $1F
+	const ZUBAT                   ; $1a
+	const GOLBAT                  ; $1b
+	const ODDISH                  ; $1c
+	const GLOOM                   ; $1d
+	const VILEPLUME               ; $1e
+	const PARAS                   ; $1f
 	const PARASECT                ; $20
 	const VENONAT                 ; $21
 	const VENOMOTH                ; $22
@@ -40,12 +40,12 @@
 	const MUK                     ; $27
 	const EXEGGCUTE               ; $28
 	const EXEGGUTOR               ; $29
-	const KOFFING                 ; $2A
-	const WEEZING                 ; $2B
-	const TANGELA1                ; $2C
-	const TANGELA2                ; $2D
-	const SCYTHER                 ; $2E
-	const PINSIR                  ; $2F
+	const KOFFING                 ; $2a
+	const WEEZING                 ; $2b
+	const TANGELA1                ; $2c
+	const TANGELA2                ; $2d
+	const SCYTHER                 ; $2e
+	const PINSIR                  ; $2f
 	const CHARMANDER              ; $30
 	const CHARMELEON              ; $31
 	const CHARIZARD               ; $32
@@ -56,12 +56,12 @@
 	const ARCANINE1               ; $37
 	const ARCANINE2               ; $38
 	const PONYTA                  ; $39
-	const RAPIDASH                ; $3A
-	const MAGMAR1                 ; $3B
-	const MAGMAR2                 ; $3C
-	const FLAREON1                ; $3D
-	const FLAREON2                ; $3E
-	const MOLTRES1                ; $3F
+	const RAPIDASH                ; $3a
+	const MAGMAR1                 ; $3b
+	const MAGMAR2                 ; $3c
+	const FLAREON1                ; $3d
+	const FLAREON2                ; $3e
+	const MOLTRES1                ; $3f
 	const MOLTRES2                ; $40
 	const SQUIRTLE                ; $41
 	const WARTORTLE               ; $42
@@ -72,12 +72,12 @@
 	const POLIWHIRL               ; $47
 	const POLIWRATH               ; $48
 	const TENTACOOL               ; $49
-	const TENTACRUEL              ; $4A
-	const SEEL                    ; $4B
-	const DEWGONG                 ; $4C
-	const SHELLDER                ; $4D
-	const CLOYSTER                ; $4E
-	const KRABBY                  ; $4F
+	const TENTACRUEL              ; $4a
+	const SEEL                    ; $4b
+	const DEWGONG                 ; $4c
+	const SHELLDER                ; $4d
+	const CLOYSTER                ; $4e
+	const KRABBY                  ; $4f
 	const KINGLER                 ; $50
 	const HORSEA                  ; $51
 	const SEADRA                  ; $52
@@ -88,12 +88,12 @@
 	const MAGIKARP                ; $57
 	const GYARADOS                ; $58
 	const LAPRAS                  ; $59
-	const VAPOREON1               ; $5A
-	const VAPOREON2               ; $5B
-	const OMANYTE                 ; $5C
-	const OMASTAR                 ; $5D
-	const ARTICUNO1               ; $5E
-	const ARTICUNO2               ; $5F
+	const VAPOREON1               ; $5a
+	const VAPOREON2               ; $5b
+	const OMANYTE                 ; $5c
+	const OMASTAR                 ; $5d
+	const ARTICUNO1               ; $5e
+	const ARTICUNO2               ; $5f
 	const PIKACHU1                ; $60
 	const PIKACHU2                ; $61
 	const PIKACHU3                ; $62
@@ -104,12 +104,12 @@
 	const RAICHU1                 ; $67
 	const RAICHU2                 ; $68
 	const MAGNEMITE1              ; $69
-	const MAGNEMITE2              ; $6A
-	const MAGNETON1               ; $6B
-	const MAGNETON2               ; $6C
-	const VOLTORB                 ; $6D
-	const ELECTRODE1              ; $6E
-	const ELECTRODE2              ; $6F
+	const MAGNEMITE2              ; $6a
+	const MAGNETON1               ; $6b
+	const MAGNETON2               ; $6c
+	const VOLTORB                 ; $6d
+	const ELECTRODE1              ; $6e
+	const ELECTRODE2              ; $6f
 	const ELECTABUZZ1             ; $70
 	const ELECTABUZZ2             ; $71
 	const JOLTEON1                ; $72
@@ -120,12 +120,12 @@
 	const SANDSHREW               ; $77
 	const SANDSLASH               ; $78
 	const DIGLETT                 ; $79
-	const DUGTRIO                 ; $7A
-	const MANKEY                  ; $7B
-	const PRIMEAPE                ; $7C
-	const MACHOP                  ; $7D
-	const MACHOKE                 ; $7E
-	const MACHAMP                 ; $7F
+	const DUGTRIO                 ; $7a
+	const MANKEY                  ; $7b
+	const PRIMEAPE                ; $7c
+	const MACHOP                  ; $7d
+	const MACHOKE                 ; $7e
+	const MACHAMP                 ; $7f
 	const GEODUDE                 ; $80
 	const GRAVELER                ; $81
 	const GOLEM                   ; $82
@@ -136,12 +136,12 @@
 	const HITMONLEE               ; $87
 	const HITMONCHAN              ; $88
 	const RHYHORN                 ; $89
-	const RHYDON                  ; $8A
-	const KABUTO                  ; $8B
-	const KABUTOPS                ; $8C
-	const AERODACTYL              ; $8D
-	const ABRA                    ; $8E
-	const KADABRA                 ; $8F
+	const RHYDON                  ; $8a
+	const KABUTO                  ; $8b
+	const KABUTOPS                ; $8c
+	const AERODACTYL              ; $8d
+	const ABRA                    ; $8e
+	const KADABRA                 ; $8f
 	const ALAKAZAM                ; $90
 	const SLOWPOKE1               ; $91
 	const SLOWPOKE2               ; $92
@@ -152,79 +152,79 @@
 	const HAUNTER2                ; $97
 	const GENGAR                  ; $98
 	const DROWZEE                 ; $99
-	const HYPNO                   ; $9A
-	const MR_MIME                 ; $9B
-	const JYNX                    ; $9C
-	const MEWTWO1                 ; $9D
-	const MEWTWO2                 ; $9E
-	const MEWTWO3                 ; $9F
-	const MEW1                    ; $A0
-	const MEW2                    ; $A1
-	const MEW3                    ; $A2
-	const PIDGEY                  ; $A3
-	const PIDGEOTTO               ; $A4
-	const PIDGEOT1                ; $A5
-	const PIDGEOT2                ; $A6
-	const RATTATA                 ; $A7
-	const RATICATE                ; $A8
-	const SPEAROW                 ; $A9
-	const FEAROW                  ; $AA
-	const CLEFAIRY                ; $AB
-	const CLEFABLE                ; $AC
-	const JIGGLYPUFF1             ; $AD
-	const JIGGLYPUFF2             ; $AE
-	const JIGGLYPUFF3             ; $AF
-	const WIGGLYTUFF              ; $B0
-	const MEOWTH1                 ; $B1
-	const MEOWTH2                 ; $B2
-	const PERSIAN                 ; $B3
-	const FARFETCHD               ; $B4
-	const DODUO                   ; $B5
-	const DODRIO                  ; $B6
-	const LICKITUNG               ; $B7
-	const CHANSEY                 ; $B8
-	const KANGASKHAN              ; $B9
-	const TAUROS                  ; $BA
-	const DITTO                   ; $BB
-	const EEVEE                   ; $BC
-	const PORYGON                 ; $BD
-	const SNORLAX                 ; $BE
-	const DRATINI                 ; $BF
-	const DRAGONAIR               ; $C0
-	const DRAGONITE1              ; $C1
-	const DRAGONITE2              ; $C2
-	const PROFESSOR_OAK           ; $C3
-	const IMPOSTER_PROFESSOR_OAK  ; $C4
-	const BILL                    ; $C5
-	const MR_FUJI                 ; $C6
-	const LASS                    ; $C7
-	const IMAKUNI_CARD            ; $C8
-	const POKEMON_TRADER          ; $C9
-	const POKEMON_BREEDER         ; $CA
-	const CLEFAIRY_DOLL           ; $CB
-	const MYSTERIOUS_FOSSIL       ; $CC
-	const ENERGY_RETRIEVAL        ; $CD
-	const SUPER_ENERGY_RETRIEVAL  ; $CE
-	const ENERGY_SEARCH           ; $CF
-	const ENERGY_REMOVAL          ; $D0
-	const SUPER_ENERGY_REMOVAL    ; $D1
-	const SWITCH                  ; $D2
-	const POKEMON_CENTER          ; $D3
-	const POKE_BALL               ; $D4
-	const SCOOP_UP                ; $D5
-	const COMPUTER_SEARCH         ; $D6
-	const POKEDEX                 ; $D7
-	const PLUSPOWER               ; $D8
-	const DEFENDER                ; $D9
-	const ITEM_FINDER             ; $DA
-	const GUST_OF_WIND            ; $DB
-	const DEVOLUTION_SPRAY        ; $DC
-	const POTION                  ; $DD
-	const SUPER_POTION            ; $DE
-	const FULL_HEAL               ; $DF
-	const REVIVE                  ; $E0
-	const MAINTENANCE             ; $E1
-	const POKEMON_FLUTE           ; $E2
-	const GAMBLER                 ; $E3
-	const RECYCLE                 ; $E4
+	const HYPNO                   ; $9a
+	const MR_MIME                 ; $9b
+	const JYNX                    ; $9c
+	const MEWTWO1                 ; $9d
+	const MEWTWO2                 ; $9e
+	const MEWTWO3                 ; $9f
+	const MEW1                    ; $a0
+	const MEW2                    ; $a1
+	const MEW3                    ; $a2
+	const PIDGEY                  ; $a3
+	const PIDGEOTTO               ; $a4
+	const PIDGEOT1                ; $a5
+	const PIDGEOT2                ; $a6
+	const RATTATA                 ; $a7
+	const RATICATE                ; $a8
+	const SPEAROW                 ; $a9
+	const FEAROW                  ; $aa
+	const CLEFAIRY                ; $ab
+	const CLEFABLE                ; $ac
+	const JIGGLYPUFF1             ; $ad
+	const JIGGLYPUFF2             ; $ae
+	const JIGGLYPUFF3             ; $af
+	const WIGGLYTUFF              ; $b0
+	const MEOWTH1                 ; $b1
+	const MEOWTH2                 ; $b2
+	const PERSIAN                 ; $b3
+	const FARFETCHD               ; $b4
+	const DODUO                   ; $b5
+	const DODRIO                  ; $b6
+	const LICKITUNG               ; $b7
+	const CHANSEY                 ; $b8
+	const KANGASKHAN              ; $b9
+	const TAUROS                  ; $ba
+	const DITTO                   ; $bb
+	const EEVEE                   ; $bc
+	const PORYGON                 ; $bd
+	const SNORLAX                 ; $be
+	const DRATINI                 ; $bf
+	const DRAGONAIR               ; $c0
+	const DRAGONITE1              ; $c1
+	const DRAGONITE2              ; $c2
+	const PROFESSOR_OAK           ; $c3
+	const IMPOSTER_PROFESSOR_OAK  ; $c4
+	const BILL                    ; $c5
+	const MR_FUJI                 ; $c6
+	const LASS                    ; $c7
+	const IMAKUNI_CARD            ; $c8
+	const POKEMON_TRADER          ; $c9
+	const POKEMON_BREEDER         ; $ca
+	const CLEFAIRY_DOLL           ; $cb
+	const MYSTERIOUS_FOSSIL       ; $cc
+	const ENERGY_RETRIEVAL        ; $cd
+	const SUPER_ENERGY_RETRIEVAL  ; $ce
+	const ENERGY_SEARCH           ; $cf
+	const ENERGY_REMOVAL          ; $d0
+	const SUPER_ENERGY_REMOVAL    ; $d1
+	const SWITCH                  ; $d2
+	const POKEMON_CENTER          ; $d3
+	const POKE_BALL               ; $d4
+	const SCOOP_UP                ; $d5
+	const COMPUTER_SEARCH         ; $d6
+	const POKEDEX                 ; $d7
+	const PLUSPOWER               ; $d8
+	const DEFENDER                ; $d9
+	const ITEM_FINDER             ; $da
+	const GUST_OF_WIND            ; $db
+	const DEVOLUTION_SPRAY        ; $dc
+	const POTION                  ; $dd
+	const SUPER_POTION            ; $de
+	const FULL_HEAL               ; $df
+	const REVIVE                  ; $e0
+	const MAINTENANCE             ; $e1
+	const POKEMON_FLUTE           ; $e2
+	const GAMBLER                 ; $e3
+	const RECYCLE                 ; $e4
 NUM_CARDS EQU const_value + -1
diff --git a/src/constants/card_data_constants.asm b/src/constants/card_data_constants.asm
index c110a69..4840171 100644
--- a/src/constants/card_data_constants.asm
+++ b/src/constants/card_data_constants.asm
@@ -32,7 +32,7 @@ ENERGY_CARD_DATA_LENGTH EQU $0e
 
 ; TYPE_PKMN card only
 CARD_DATA_MOVE1                 EQU $0c
-CARD_DATA_MOVE1_ENERGY          EQU $0c
+CARD_DATA_MOVE1_ENERGY_COST     EQU $0c
 CARD_DATA_MOVE1_NAME            EQU $10
 CARD_DATA_MOVE1_DESCRIPTION     EQU $12
 CARD_DATA_MOVE1_DAMAGE          EQU $16
@@ -46,7 +46,7 @@ CARD_DATA_MOVE1_ANIMATION       EQU $1e
 
 ; TYPE_PKMN card only
 CARD_DATA_MOVE2                 EQU $1f
-CARD_DATA_MOVE2_ENERGY          EQU $1f
+CARD_DATA_MOVE2_ENERGY_COST     EQU $1f
 CARD_DATA_MOVE2_NAME            EQU $23
 CARD_DATA_MOVE2_DESCRIPTION     EQU $25
 CARD_DATA_MOVE2_DAMAGE          EQU $29
@@ -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
@@ -196,6 +196,16 @@ CARDPAGE_ENERGY              EQU $09
 CARDPAGE_TRAINER_1           EQU $0d
 CARDPAGE_TRAINER_2           EQU $0e
 
+; wMovePageNumber constants
+MOVEPAGE_MOVE1_1 EQU $00
+MOVEPAGE_MOVE1_2 EQU $01
+MOVEPAGE_MOVE2_1 EQU $02
+MOVEPAGE_MOVE2_2 EQU $03
+
+; wCardPageType constants
+CARDPAGETYPE_NOT_PLAY_AREA EQU $00
+CARDPAGETYPE_PLAY_AREA     EQU $01
+
 ; card type header constants ($10-tile headers in DuelCardHeaderGraphics)
 HEADER_TRAINER EQU $00
 HEADER_ENERGY  EQU $01
diff --git a/src/constants/charmaps.asm b/src/constants/charmaps.asm
index 5bd21be..baa3f46 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_*
@@ -329,7 +338,7 @@ FW_SPACE EQU $70
 	txsymbol PARALYZED  ; $0b
 	txsymbol CURSOR_U   ; $0c
 	txsymbol POKEMON    ; $0d
-	txsymbol UNKNOWN_0E ; $0e
+	txsymbol MOVE_DESCR ; $0e
 	txsymbol CURSOR_R   ; $0f
 	txsymbol HP         ; $10
 	txsymbol Lv         ; $11
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/duel_constants.asm b/src/constants/duel_constants.asm
index eaa9a65..ee6b940 100644
--- a/src/constants/duel_constants.asm
+++ b/src/constants/duel_constants.asm
@@ -21,18 +21,9 @@ TURN_PLAYER_TIED EQU $3
 DUEL_WIN  EQU $0
 DUEL_LOSS EQU $1
 
-; Box message id's
-	const_def
-	const BOXMSG_PLAYERS_TURN
-	const BOXMSG_OPPONENTS_TURN
-	const BOXMSG_BETWEEN_TURNS
-	const BOXMSG_DECISION
-	const BOXMSG_BENCH_POKEMON
-	const BOXMSG_ARENA_POKEMON
-	const BOXMSG_COIN_TOSS
-
 ; wPlayerDuelVariables or wOpponentDuelVariables constants
 DUELVARS_CARD_LOCATIONS                  EQUS "LOW(wPlayerCardLocations)"               ; 00
+DUELVARS_PRIZE_CARDS                     EQUS "LOW(wPlayerPrizeCards)"                  ; 3c
 DUELVARS_HAND                            EQUS "LOW(wPlayerHand)"                        ; 42
 DUELVARS_DECK_CARDS                      EQUS "LOW(wPlayerDeckCards)"                   ; 7e
 DUELVARS_NUMBER_OF_CARDS_NOT_IN_DECK     EQUS "LOW(wPlayerNumberOfCardsNotInDeck)"      ; ba
@@ -81,6 +72,8 @@ DUELVARS_NUMBER_OF_POKEMON_IN_PLAY_AREA  EQUS "LOW(wPlayerNumberOfPokemonInPlayA
 DUELVARS_ARENA_CARD_STATUS               EQUS "LOW(wPlayerArenaCardStatus)"             ; f0
 DUELVARS_DUELIST_TYPE                    EQUS "LOW(wPlayerDuelistType)"                 ; f1
 DUELVARS_ARENA_CARD_DISABLED_MOVE_INDEX  EQUS "LOW(wPlayerArenaCardDisabledMoveIndex)"  ; f2
+DUELVARS_ARENA_CARD_LAST_TURN_DAMAGE     EQUS "LOW(wPlayerArenaCardLastTurnDamage)"     ; f3
+DUELVARS_ARENA_CARD_LAST_TURN_STATUS     EQUS "LOW(wPlayerArenaCardLastTurnStatus)"     ; f5
 
 ; card location constants (DUELVARS_CARD_LOCATIONS)
 CARD_LOCATION_DECK         EQU $00
@@ -123,8 +116,11 @@ POISONED        EQU $80
 DOUBLE_POISONED EQU $c0
 
 CNF_SLP_PRZ  EQU $0f ; confused, asleep or paralyzed
+PSN_DBLPSN   EQU $f0 ; poisoned or double poisoned
 
 ; substatus conditions (DUELVARS_ARENA_CARD_SUBSTATUS*)
+
+; SUBSTATUS1 are checked on a defending Pokemon
 SUBSTATUS1_AGILITY      EQU $0c
 SUBSTATUS1_FLY          EQU $0d
 SUBSTATUS1_HARDEN       EQU $0e
@@ -139,6 +135,7 @@ SUBSTATUS1_NO_DAMAGE_17 EQU $17
 SUBSTATUS1_NEXT_TURN_DOUBLE_DAMAGE EQU $19
 SUBSTATUS1_REDUCE_BY_10 EQU $1e
 
+; SUBSTATUS2 are checked on an attacking Pokemon
 SUBSTATUS2_SMOKESCREEN    EQU $01
 SUBSTATUS2_SAND_ATTACK    EQU $02
 SUBSTATUS2_REDUCE_BY_20   EQU $03
@@ -167,3 +164,27 @@ NO_DAMAGE_OR_EFFECT_NSHIELD      EQU $05
 ; wDamageEffectiveness constants
 WEAKNESS   EQU 1
 RESISTANCE EQU 2
+
+; Box message id's
+	const_def
+	const BOXMSG_PLAYERS_TURN
+	const BOXMSG_OPPONENTS_TURN
+	const BOXMSG_BETWEEN_TURNS
+	const BOXMSG_DECISION
+	const BOXMSG_BENCH_POKEMON
+	const BOXMSG_ARENA_POKEMON
+	const BOXMSG_COIN_TOSS
+
+; wDuelDisplayedScreen constants
+DUEL_MAIN_SCENE     EQU $01
+PLAY_AREA_CARD_LIST EQU $02
+COIN_TOSS           EQU $06
+DRAW_CARDS          EQU $07
+LARGE_CARD_PICTURE  EQU $08
+SHUFFLE_DECK        EQU $09
+CHECK_PLAY_AREA     EQU $0a
+
+; wCardListItemSelectionMenuType constants
+;NONE        EQU $00
+PLAY_CHECK   EQU $01
+SELECT_CHECK EQU $02
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..3b36a9d 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,154 @@ OAM_PRIORITY  EQU 7 ; 0: OBJ above BG, 1: OBJ behind BG (colors 1-3)
 
 ; Hardware registers
 rJOYP       EQU $ff00 ; Joypad (R/W)
+P15              EQU %00100000
+JOY_BTNS_SELECT  EQU P15
+P14              EQU %00010000
+JOY_DPAD_SELECT  EQU P14
+JOY_INPUT_MASK   EQU %00001111
+P13              EQU %00001000
+P12              EQU %00000100
+P11              EQU %00000010
+P10              EQU %00000001
+JOY_INPUT_DOWN   EQU P13
+JOY_INPUT_UP     EQU P12
+JOY_INPUT_LEFT   EQU P11
+JOY_INPUT_RIGHT  EQU P10
+JOY_INPUT_START  EQU P13
+JOY_INPUT_SELECT EQU P12
+JOY_INPUT_B      EQU P11
+JOY_INPUT_A      EQU P10
+SNES_JOYPAD1     EQU $3 ; lower two bits
+SNES_JOYPAD2     EQU $2 ; lower two bits
+SNES_JOYPAD3     EQU $1 ; lower two bits
+SNES_JOYPAD4     EQU $0 ; lower two bits
+
 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/sgb_constants.asm b/src/constants/sgb_constants.asm
index 6ba250e..a6a58af 100644
--- a/src/constants/sgb_constants.asm
+++ b/src/constants/sgb_constants.asm
@@ -1,3 +1,5 @@
+SGB_PACKET_SIZE EQU $10 ; bytes
+
 PAL01    EQU $00 ; Set SGB Palette 0,1 Data
 PAL23    EQU $01 ; Set SGB Palette 2,3 Data
 PAL03    EQU $02 ; Set SGB Palette 0,3 Data
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/constants/text_constants.asm b/src/constants/text_constants.asm
index 3a50b59..97c8313 100644
--- a/src/constants/text_constants.asm
+++ b/src/constants/text_constants.asm
@@ -14,6 +14,8 @@ TX_CTRL_START EQU $05
 
 ; usage: TX_SYMBOL, char1, TX_SYMBOL, char2, ...
 ; source: gfx/fonts/symbols.2bpp
+; note: precede each symbol with TX_SYMBOL only when it's going to be processed as text.
+; if copying directly to VRAM, don't precede symbols with TX_SYMBOL as they are just tile numbers.
 TX_SYMBOL     EQU $05
 
 ; usage: TX_HALFWIDTH, char1, char2, ...
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/data/npcs.asm b/src/data/npcs.asm
index d7a3a61..caa11af 100644
--- a/src/data/npcs.asm
+++ b/src/data/npcs.asm
@@ -1,4 +1,4 @@
-; When you press the a button in front of something it will find a data entry somewhere on this list
+; When you press the A button in front of something it will find a data entry somewhere on this list
 ; it will then jump to the pointer in the data item. All jumps lead to an RST20 operation.
 PointerTable_118f5:
 	dw Data_119dd
diff --git a/src/engine/bank01.asm b/src/engine/bank01.asm
index 9ca9c10..dc01bb7 100644
--- a/src/engine/bank01.asm
+++ b/src/engine/bank01.asm
@@ -1,5 +1,5 @@
 ; continuation of Bank0 Start
-; supposed to be the main loop, but the game never returns from _GameLoop anyway
+; meant as the main loop, but the game never returns from _GameLoop anyway
 GameLoop: ; 4000 (1:4000)
 	di
 	ld sp, $e000
@@ -7,22 +7,22 @@ GameLoop: ; 4000 (1:4000)
 	call EnableInt_VBlank
 	call EnableInt_Timer
 	call EnableSRAM
-	ld a, [sa006]
+	ld a, [s0a006]
 	ld [wTextSpeed], a
-	ld a, [sa009]
-	ld [wccf2], a
+	ld a, [s0a009]
+	ld [wSkipDelayAllowed], a
 	call DisableSRAM
 	ld a, 1
 	ld [wUppercaseHalfWidthLetters], a
 	ei
 	farcall CommentedOut_1a6cc
-	ldh a, [hButtonsHeld]
+	ldh a, [hKeysHeld]
 	cp A_BUTTON | B_BUTTON
 	jr z, .ask_erase_backup_ram
 	farcall _GameLoop
 	jr GameLoop
 .ask_erase_backup_ram
-	call Func_405a
+	call SetupResetBackUpRamScreen
 	call EmptyScreen
 	ldtx hl, ResetBackUpRamText
 	call YesOrNoMenuWithText
@@ -30,7 +30,7 @@ GameLoop: ; 4000 (1:4000)
 ; erase sram
 	call EnableSRAM
 	xor a
-	ld [sa000], a
+	ld [s0a000], a
 	call DisableSRAM
 .reset_game
 	jp Reset
@@ -41,14 +41,15 @@ Func_4050: ; 4050 (1:4050)
 	ld [wUppercaseHalfWidthLetters], a
 	ret
 
-Func_405a: ; 405a (1:405a)
-	xor a
+; basic setup to be able to print the ResetBackUpRamText in an empty screen
+SetupResetBackUpRamScreen: ; 405a (1:405a)
+	xor a ; SYM_SPACE
 	ld [wTileMapFill], a
 	call DisableLCD
 	call LoadSymbolsFont
 	call SetDefaultPalettes
-	ld de, $387f
-	call Func_2275
+	lb de, $38, $7f
+	call SetupText
 	ret
 ; 0x406e
 
@@ -58,13 +59,13 @@ CommentedOut_406e: ; 406e (1:406e)
 
 ; try to resume a saved duel from the main menu
 TryContinueDuel: ; 406f (1:406f)
-	call Func_420b
-	call $66e9
+	call SetupDuel
+	call Func_66e9
 	ldtx hl, BackUpIsBrokenText
-	jr c, FailedToContinueDuel
+	jr c, HandleFailedToContinueDuel
 ;	fallthrough
 
-ContinueDuel: ; 407a (1:407a)
+_ContinueDuel: ; 407a (1:407a)
 	ld hl, sp+$00
 	ld a, l
 	ld [wDuelReturnAddress], a
@@ -76,18 +77,18 @@ ContinueDuel: ; 407a (1:407a)
 	xor a
 	ld [wDuelFinished], a
 	call DuelMainInterface
-	jp MainDuelLoop.begin_turn
+	jp MainDuelLoop.between_turns
 ; 0x4097
 
-FailedToContinueDuel: ; 4097 (1:4097)
+HandleFailedToContinueDuel: ; 4097 (1:4097)
 	call DrawWideTextBox_WaitForInput
 	call ResetSerial
 	scf
 	ret
 ; 0x409f
 
-; this function begins the duel after the opponent's
-; graphics, name and deck have been introduced
+; this function begins the duel after the opponent's graphics, name and deck have been introduced
+; loads both player's decks and sets up the variables and resources required to begin a duel.
 StartDuel: ; 409f (1:409f)
 	ld a, PLAYER_TURN
 	ldh [hWhoseTurn], a
@@ -99,8 +100,9 @@ StartDuel: ; 409f (1:409f)
 	call SwapTurn
 	call LoadOpponentDeck
 	call SwapTurn
-	jr .continue
+	jr .decks_loaded
 
+; unreferenced?
 	ld a, MUSIC_DUEL_THEME_1
 	ld [wDuelTheme], a
 	ld hl, wOpponentName
@@ -109,7 +111,7 @@ StartDuel: ; 409f (1:409f)
 	ld [hl], a
 	ld [wIsPracticeDuel], a
 
-.continue
+.decks_loaded
 	ld hl, sp+$0
 	ld a, l
 	ld [wDuelReturnAddress], a
@@ -117,10 +119,10 @@ StartDuel: ; 409f (1:409f)
 	ld [wDuelReturnAddress + 1], a
 	xor a
 	ld [wCurrentDuelMenuItem], a
-	call Func_420b
+	call SetupDuel
 	ld a, [wcc18]
 	ld [wDuelInitialPrizes], a
-	call $70aa
+	call InitVariablesToBeginDuel
 	ld a, [wDuelTheme]
 	call PlaySong
 	call Func_4b60
@@ -132,18 +134,18 @@ MainDuelLoop ; 40ee (1:40ee)
 	xor a
 	ld [wCurrentDuelMenuItem], a
 	call UpdateSubstatusConditions_StartOfTurn
-	call $54c8
+	call DisplayDuelistTurnScreen
 	call HandleTurn
 
-.begin_turn
-	call Func_0f58
+.between_turns
+	call ExchangeRNG
 	ld a, [wDuelFinished]
 	or a
 	jr nz, .duel_finished
 	call UpdateSubstatusConditions_EndOfTurn
-	call $6baf
+	call HandleBetweenTurnsEvents
 	call Func_3b31
-	call Func_0f58
+	call ExchangeRNG
 	ld a, [wDuelFinished]
 	or a
 	jr nz, .duel_finished
@@ -180,8 +182,8 @@ MainDuelLoop ; 40ee (1:40ee)
 	push af
 	ld a, PLAYER_TURN
 	ldh [hWhoseTurn], a
-	call Func_4a97
-	call Func_4ad6
+	call DrawDuelistPortraitsAndNames
+	call PrintDuelResultStats
 	pop af
 	ldh [hWhoseTurn], a
 	call Func_3b21
@@ -251,7 +253,7 @@ MainDuelLoop ; 40ee (1:40ee)
 	call DrawWideTextBox_WaitForInput
 	ld a, 1
 	ld [wDuelInitialPrizes], a
-	call $70aa
+	call InitVariablesToBeginDuel
 	ld a, [wDuelType]
 	cp DUELTYPE_LINK
 	jr z, .link_duel
@@ -259,15 +261,13 @@ MainDuelLoop ; 40ee (1:40ee)
 	ldh [hWhoseTurn], a
 	call Func_4b60
 	jp MainDuelLoop
-
 .link_duel
-	call Func_0f58
+	call ExchangeRNG
 	ld h, PLAYER_TURN
 	ld a, [wSerialOp]
 	cp $29
 	jr z, .got_turn
 	ld h, OPPONENT_TURN
-
 .got_turn
 	ld a, h
 	ldh [hWhoseTurn], a
@@ -276,20 +276,23 @@ MainDuelLoop ; 40ee (1:40ee)
 	ret
 ; 0x420b
 
-Func_420b: ; 420b (1:420b)
-	xor a
+; empty the screen, and setup text and graphics for a duel
+SetupDuel: ; 420b (1:420b)
+	xor a ; SYM_SPACE
 	ld [wTileMapFill], a
 	call ZeroObjectPositionsAndToggleOAMCopy
 	call EmptyScreen
 	call LoadSymbolsFont
 	call SetDefaultPalettes
-	ld de, $389f
-	call Func_2275
+	lb de, $38, $9f
+	call SetupText
 	call EnableLCD
 	ret
 ; 0x4225
 
-; handle the turn of the duelist identified by hWhoseTurn
+; handle the turn of the duelist identified by hWhoseTurn.
+; if player's turn, display the animation of the player drawing the card at
+; hTempCardIndex_ff98, and save the duel state to SRAM.
 HandleTurn: ; 4225 (1:4225)
 	ld a, DUELVARS_DUELIST_TYPE
 	call GetTurnDuelistVariable
@@ -298,10 +301,9 @@ HandleTurn: ; 4225 (1:4225)
 	cp 2
 	jr c, .skip_let_evolve ; jump if it's the turn holder's first turn
 	call SetAllPlayAreaPokemonCanEvolve
-
 .skip_let_evolve
-	call Func_70e6
-	call Func_4933
+	call InitVariablesToBeginTurn
+	call DisplayDrawOneCardScreen
 	call DrawCardFromDeck
 	jr nc, .deck_not_empty
 	ld a, TURN_PLAYER_LOST
@@ -313,17 +315,17 @@ HandleTurn: ; 4225 (1:4225)
 	call AddCardToHand
 	ld a, [wDuelistType]
 	cp DUELIST_TYPE_PLAYER
-	jr z, HandleTurn_PlayerDrewCard
+	jr z, .player_turn
+
+; opponent's turn
 	call SwapTurn
 	call IsClairvoyanceActive
 	call SwapTurn
 	call c, DisplayPlayerDrawCardScreen
 	jr DuelMainInterface
 
-; display the animation of the player drawing the card at hTempCardIndex_ff98,
-; save duel state to SRAM, and fall through to DuelMainInterface
-; to effectively begin the turn
-HandleTurn_PlayerDrewCard:
+; player's turn
+.player_turn
 	call DisplayPlayerDrawCardScreen
 	call SaveDuelStateToSRAM
 ;	fallthrough
@@ -340,27 +342,27 @@ DuelMainInterface: ; 426d (1:426d)
 	call DrawDuelMainScene
 	ld a, [wDuelistType]
 	cp DUELIST_TYPE_PLAYER
-	jr z, PrintDuelMenu
+	jr z, PrintDuelMenuAndHandleInput
 	cp DUELIST_TYPE_LINK_OPP
-	jp z, $6911
+	jp z, Func_6911
 	; DUELIST_TYPE_AI_OPP
 	xor a
 	ld [wVBlankCounter], a
-	ld [wcbf9], a
+	ld [wSkipDuelistIsThinkingDelay], a
 	ldtx hl, DuelistIsThinkingText
 	call DrawWideTextBox_PrintTextNoDelay
 	call Func_2bbf
 	ld a, $ff
-	ld [wcc11], a
-	ld [wcc10], a
+	ld [wPlayerAttackingCardIndex], a
+	ld [wPlayerAttackingMoveIndex], a
 	ret
 
-PrintDuelMenu: ; 4295 (1:4295)
+PrintDuelMenuAndHandleInput: ; 4295 (1:4295)
 	call DrawWideTextBox
 	ld hl, DuelMenuData
 	call PlaceTextItems
-.asm_429e
-	call $669d
+.menu_items_printed
+	call SaveDuelData
 	ld a, [wDuelFinished]
 	or a
 	ret nz
@@ -369,10 +371,10 @@ PrintDuelMenu: ; 4295 (1:4295)
 
 .handle_input
 	call DoFrame
-	ldh a, [hButtonsHeld]
+	ldh a, [hKeysHeld]
 	and B_BUTTON
 	jr z, .b_not_held
-	ldh a, [hButtonsPressed]
+	ldh a, [hKeysPressed]
 	bit D_UP_F, a
 	jr nz, DuelMenuShortcut_OpponentPlayArea
 	bit D_DOWN_F, a
@@ -385,10 +387,10 @@ PrintDuelMenu: ; 4295 (1:4295)
 	jp nz, DuelMenuShortcut_OpponentActivePokemon
 
 .b_not_held
-	ldh a, [hButtonsPressed]
+	ldh a, [hKeysPressed]
 	and START
 	jp nz, DuelMenuShortcut_PlayerActivePokemon
-	ldh a, [hButtonsPressed]
+	ldh a, [hKeysPressed]
 	bit SELECT_F, a
 	jp nz, DuelMenuShortcut_BothActivePokemon
 	ld a, [wcbe7]
@@ -414,8 +416,8 @@ Func_42fd: ; 42fd (1:42fd)
 	call DrawCardFromDeck
 	call nc, AddCardToHand
 	ld a, $0b
-	call SetDuelAIAction
-	jp PrintDuelMenu.asm_429e
+	call SetAIAction_SerialSendDuelData
+	jp PrintDuelMenuAndHandleInput.menu_items_printed
 ; 0x430b
 
 ; triggered by pressing B + UP in the duel menu
@@ -428,16 +430,16 @@ DuelMenuShortcut_PlayerPlayArea: ; 4311 (1:4311)
 	call OpenPlayAreaScreen
 	jp DuelMainInterface
 
-; triggered by pressing B + LEFT in the duel menu
+; triggered by pressing B + RIGHT in the duel menu
 DuelMenuShortcut_OpponentDiscardPile: ; 4317 (1:4317)
 	call OpenOpponentDiscardPileScreen
-	jp c, PrintDuelMenu
+	jp c, PrintDuelMenuAndHandleInput
 	jp DuelMainInterface
 
-; triggered by pressing B + RIGHT in the duel menu
+; triggered by pressing B + LEFT in the duel menu
 DuelMenuShortcut_PlayerDiscardPile: ; 4320 (1:4320)
 	call OpenPlayerDiscardPileScreen
-	jp c, PrintDuelMenu
+	jp c, PrintDuelMenuAndHandleInput
 	jp DuelMainInterface
 
 ; draw the opponent's play area screen
@@ -471,10 +473,10 @@ Func_4345: ; 4345 (1:4345)
 Func_434e: ; 434e (1:434e)
 	call CreateHandCardList
 	jr c, .no_cards_in_hand
-	call DrawCardListScreenLayout
+	call InitAndDrawCardListScreenLayout
 	ld a, START + A_BUTTON
-	ld [wcbd6], a
-	jp Func_55f0
+	ld [wNoItemSelectionMenuKeys], a
+	jp DisplayCardList
 .no_cards_in_hand
 	ldtx hl, NoCardsInHandText
 	jp DrawWideTextBox_WaitForInput
@@ -502,11 +504,11 @@ OpenActivePokemonScreen: ; 4376 (1:4376)
 	ret z
 	call GetCardIDFromDeckIndex
 	call LoadCardDataToBuffer1_FromCardID
-	ld hl, wcbc9
+	ld hl, wCurPlayAreaSlot
 	xor a
 	ld [hli], a
-	ld [hl], a
-	call Func_576a
+	ld [hl], a ; wCurPlayAreaY
+	call OpenCardPage_FromCheckPlayArea
 	ret
 ; 0x438e
 
@@ -514,7 +516,7 @@ OpenActivePokemonScreen: ; 4376 (1:4376)
 DuelMenu_PkmnPower: ; 438e (1:438e)
 	call $6431
 	jp c, DuelMainInterface
-	call Func_1730
+	call UseAttackOrPokemonPower
 	jp DuelMainInterface
 
 ; triggered by selecting the "Done" item in the duel menu
@@ -523,8 +525,8 @@ DuelMenu_Done: ; 439a (1:439a)
 	call DoPracticeDuelAction
 	jp c, Func_4268
 	ld a, $05
-	call SetDuelAIAction
-	call Func_717a
+	call SetAIAction_SerialSendDuelData
+	call ClearNonTurnTemporaryDuelvars
 	ret
 
 ; triggered by selecting the "Retreat" item in the duel menu
@@ -540,7 +542,7 @@ DuelMenu_Retreat: ; 43ab (1:43ab)
 	jr nz, .unable_due_to_confusion
 	call CheckAbleToRetreat
 	jr c, .unable_to_retreat
-	call Func_4611
+	call DisplayRetreatScreen
 	jr c, .done
 	ldtx hl, SelectPkmnOnBenchToSwitchWithActiveText
 	call DrawWideTextBox_WaitForInput
@@ -548,9 +550,9 @@ DuelMenu_Retreat: ; 43ab (1:43ab)
 	jr c, .done
 	ld [wBenchSelectedPokemon], a
 	ld a, [wBenchSelectedPokemon]
-	ldh [hTempPlayAreaLocationOffset_ffa1], a
+	ldh [hTempPlayAreaLocation_ffa1], a
 	ld a, $04
-	call SetDuelAIAction
+	call SetAIAction_SerialSendDuelData
 	call AttemptRetreat
 	jr nc, .done
 	call DrawDuelMainScene
@@ -558,7 +560,7 @@ DuelMenu_Retreat: ; 43ab (1:43ab)
 .unable_due_to_confusion
 	ldtx hl, UnableToRetreatText
 	call DrawWideTextBox_WaitForInput
-	jp PrintDuelMenu
+	jp PrintDuelMenuAndHandleInput
 
 .not_confused
 	; note that the energy cards are discarded (DiscardRetreatCostCards), then returned
@@ -569,20 +571,20 @@ DuelMenu_Retreat: ; 43ab (1:43ab)
 	; 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
+	call DisplayRetreatScreen
 	jr c, .done
 	call DiscardRetreatCostCards
 	ldtx hl, SelectPkmnOnBenchToSwitchWithActiveText
 	call DrawWideTextBox_WaitForInput
 	call OpenPlayAreaScreenForSelection
 	ld [wBenchSelectedPokemon], a
-	ldh [hTempPlayAreaLocationOffset_ffa1], a
+	ldh [hTempPlayAreaLocation_ffa1], a
 	push af
 	call ReturnRetreatCostCardsToArena
 	pop af
 	jp c, DuelMainInterface
 	ld a, $04
-	call SetDuelAIAction
+	call SetAIAction_SerialSendDuelData
 	call AttemptRetreat
 
 .done
@@ -590,7 +592,7 @@ DuelMenu_Retreat: ; 43ab (1:43ab)
 
 .unable_to_retreat
 	call DrawWideTextBox_WaitForInput
-	jp PrintDuelMenu
+	jp PrintDuelMenuAndHandleInput
 
 ; triggered by selecting the "Hand" item in the duel menu
 DuelMenu_Hand: ; 4425 (1:4425)
@@ -600,19 +602,19 @@ DuelMenu_Hand: ; 4425 (1:4425)
 	jr nz, OpenPlayerHandScreen
 	ldtx hl, NoCardsInHandText
 	call DrawWideTextBox_WaitForInput
-	jp PrintDuelMenu
+	jp PrintDuelMenuAndHandleInput
 
 ; draw the screen for the player's hand and handle user input to for example check
 ; a card or attempt to use a card, playing the card if possible in that case.
 OpenPlayerHandScreen: ; 4436 (1:4436)
 	call CreateHandCardList
-	call DrawCardListScreenLayout
+	call InitAndDrawCardListScreenLayout
 	ldtx hl, PleaseSelectHandText
 	call SetCardListInfoBoxText
-	ld a, $1
-	ld [wcbde], a
+	ld a, PLAY_CHECK
+	ld [wCardListItemSelectionMenuType], a
 .handle_input
-	call Func_55f0
+	call DisplayCardList
 	push af
 	ld a, [wSortCardListByID]
 	or a
@@ -655,16 +657,16 @@ UseEnergyCard: ; 4477 (1:4477)
 	ld a, 1
 	ld [wAlreadyPlayedEnergy], a
 .play_energy
-	ldh a, [hTempPlayAreaLocationOffset_ff9d]
-	ldh [hTempPlayAreaLocationOffset_ffa1], a
+	ldh a, [hTempPlayAreaLocation_ff9d]
+	ldh [hTempPlayAreaLocation_ffa1], a
 	ld e, a
 	ldh a, [hTempCardIndex_ff98]
 	ldh [hTemp_ffa0], a
 	call PutHandCardInPlayArea
-	call $61b8
-	ld a, $3
-	call SetDuelAIAction
-	call Func_68e4
+	call PrintPlayAreaCardList_EnableLCD
+	ld a, $03
+	call SetAIAction_SerialSendDuelData
+	call PrintAttachedEnergyToPokemon
 	jp DuelMainInterface
 
 .rain_dance_active
@@ -689,7 +691,7 @@ UseEnergyCard: ; 4477 (1:4477)
 ReloadCardListScreen: ; 44d2 (1:44d2)
 	call CreateHandCardList
 	; skip doing the things that have already been done when initially opened
-	call DrawCardListScreenLayout.draw
+	call DrawCardListScreenLayout
 	jp OpenPlayerHandScreen.handle_input
 ; 0x44db
 
@@ -708,12 +710,12 @@ UsePokemonCard: ; 44db (1:44db)
 	ldh a, [hTempCardIndex_ff98]
 	ldh [hTemp_ffa0], a
 	call PutHandPokemonCardInPlayArea
-	ldh [hTempPlayAreaLocationOffset_ff9d], a
+	ldh [hTempPlayAreaLocation_ff9d], a
 	add DUELVARS_ARENA_CARD_STAGE
 	call GetTurnDuelistVariable
 	ld [hl], BASIC
 	ld a, $01
-	call SetDuelAIAction
+	call SetAIAction_SerialSendDuelData
 	ldh a, [hTempCardIndex_ff98]
 	call LoadCardDataToBuffer1_FromDeckIndex
 	ld a, 20
@@ -726,11 +728,13 @@ UsePokemonCard: ; 44db (1:44db)
 	call Func_161e
 	or a
 	ret
+
 .no_space
 	ldtx hl, NoSpaceOnTheBenchText
 	call DrawWideTextBox_WaitForInput
 	scf
 	ret
+
 .try_evolve
 	ld a, DUELVARS_NUMBER_OF_POKEMON_IN_PLAY_AREA
 	call GetTurnDuelistVariable
@@ -765,6 +769,7 @@ UsePokemonCard: ; 44db (1:44db)
 	call DrawWideTextBox_WaitForInput
 	scf
 	ret
+
 .can_evolve
 	pop bc
 	pop de
@@ -776,18 +781,19 @@ UsePokemonCard: ; 44db (1:44db)
 	jr c, .done
 	ldh a, [hTempCardIndex_ff98]
 	ldh [hTemp_ffa0], a
-	ldh a, [hTempPlayAreaLocationOffset_ff9d]
-	ldh [hTempPlayAreaLocationOffset_ffa1], a
+	ldh a, [hTempPlayAreaLocation_ff9d]
+	ldh [hTempPlayAreaLocation_ffa1], a
 	call EvolvePokemonCard
 	jr c, .try_evolve_loop ; jump if evolution wasn't successsful somehow
 	ld a, $02
-	call SetDuelAIAction
-	call $61b8
-	call Func_68fa
+	call SetAIAction_SerialSendDuelData
+	call PrintPlayAreaCardList_EnableLCD
+	call PrintPokemonEvolvedIntoPokemon
 	call Func_161e
 .done
 	or a
 	ret
+
 .prehistoric_power
 	call DrawWideTextBox_WaitForInput
 	scf
@@ -823,7 +829,7 @@ Func_45a9: ; 45a9 (1:45a9)
 	ld a, $02
 	ld [wcbd4], a
 	call OpenPlayAreaScreenForViewing
-	ldh a, [hButtonsPressed]
+	ldh a, [hKeysPressed]
 	and B_BUTTON
 	ret z
 	scf
@@ -872,7 +878,7 @@ CheckIfEnoughEnergiesToRetreat: ; 45f4 (1:45f4)
 	ld e, PLAY_AREA_ARENA
 	call GetPlayAreaCardAttachedEnergies
 	xor a
-	ldh [hTempPlayAreaLocationOffset_ff9d], a
+	ldh [hTempPlayAreaLocation_ff9d], a
 	call GetPlayAreaCardRetreatCost
 	ld [wEnergyCardsRequiredToRetreat], a
 	ld c, a
@@ -886,12 +892,16 @@ CheckIfEnoughEnergiesToRetreat: ; 45f4 (1:45f4)
 	ret
 ; 0x4611
 
-Func_4611: ; 4611 (1:4611)
+; display the screen that prompts the player to select energy cards to discard
+; in order to retreat a Pokemon card. also handle input in order to display
+; the amount of energy cards already selected, and return whenever enough
+; energy cards have been selected or if the player declines to retreat.
+DisplayRetreatScreen: ; 4611 (1:4611)
 	ld a, $ff
 	ldh [hTempRetreatCostCards], a
 	ld a, [wEnergyCardsRequiredToRetreat]
 	or a
-	ret z
+	ret z ; return if no energy cards are required at all
 	xor a
 	ld [wcbcd], a
 	call CreateArenaOrBenchEnergyCardList
@@ -899,22 +909,24 @@ Func_4611: ; 4611 (1:4611)
 	ld a, LOW(hTempRetreatCostCards)
 	ld [wcbd5], a
 	xor a
-	call Func_4673
+	call DisplayEnergyDiscardScreen
 	ld a, [wEnergyCardsRequiredToRetreat]
 	ld [wcbfa], a
-.asm_4633
+.select_energies_loop
 	ld a, [wcbcd]
 	ld [wcbfb], a
-	call Func_46b7
+	call HandleEnergyDiscardMenuInput
 	ret c
 	ldh a, [hTempCardIndex_ff98]
 	call LoadCardDataToBuffer2_FromDeckIndex
+	; append selected energy card to hTempRetreatCostCards
 	ld hl, wcbd5
 	ld c, [hl]
 	inc [hl]
 	ldh a, [hTempCardIndex_ff98]
 	ld [$ff00+c], a
-	ld c, $01
+	; accumulate selected energy card
+	ld c, 1
 	ld a, [wLoadedCard2Type]
 	cp TYPE_ENERGY_DOUBLE_COLORLESS
 	jr nz, .not_double
@@ -926,12 +938,14 @@ Func_4611: ; 4611 (1:4611)
 	ld [hl], a
 	ld hl, wEnergyCardsRequiredToRetreat
 	cp [hl]
-	jr nc, .asm_466a
+	jr nc, .enough
+	; not enough energies selected yet
 	ldh a, [hTempCardIndex_ff98]
 	call RemoveCardFromDuelTempList
-	call DisplayEnergyDiscardScreen
-	jr .asm_4633
-.asm_466a
+	call DisplayEnergyDiscardMenu
+	jr .select_energies_loop
+.enough
+	; terminate hTempRetreatCostCards array with $ff
 	ld a, [wcbd5]
 	ld c, a
 	ld a, $ff
@@ -940,25 +954,30 @@ Func_4611: ; 4611 (1:4611)
 	ret
 ; 0x4673
 
-Func_4673: ; 4673 (1:4673)
+; display the screen that prompts the player to select energy cards to discard
+; in order to retreat a Pokemon card or use an attack like Ember. includes the
+; card's information and a menu to select the attached energy cards to discard.
+; input: a = PLAY_AREA_* of the Pokemon trying to discard energies from.
+DisplayEnergyDiscardScreen: ; 4673 (1:4673)
 	ld [wcbe0], a
 	call EmptyScreen
 	call LoadDuelCardSymbolTiles
 	call LoadDuelFaceDownCardTiles
 	ld a, [wcbe0]
-	ld hl, wcbc9
+	ld hl, wCurPlayAreaSlot
 	ld [hli], a
-	ld [hl], $00
-	call Func_627c
+	ld [hl], 0 ; wCurPlayAreaY
+	call PrintPlayAreaCardInformation
 	xor a
 	ld [wcbfb], a
 	inc a
 	ld [wcbfa], a
 ;	fallthrough
 
-; display the screen that prompts the player to select energy cards to discard
-; in order to retreat a Pokemon card
-DisplayEnergyDiscardScreen: ; 4693 (1:4693)
+; display the menu that belongs to the energy discard screen that lets the player
+; select energy cards attached to a Pokemon card in order to retreat it or use
+; an attack like Ember, Flamethrower...
+DisplayEnergyDiscardMenu: ; 4693 (1:4693)
 	lb de, 0, 3
 	lb bc, 20, 10
 	call DrawRegularTextBox
@@ -974,11 +993,17 @@ DisplayEnergyDiscardScreen: ; 4693 (1:4693)
 	ret
 ; 0x46b7
 
-Func_46b7: ; 46b7 (1:46b7)
-	lb bc, $10, $10
+; if [wcbfa] non-0:
+   ; prints "[wcbfb]/[wcbfa]" at 16,16, where [wcbfb] is the total amount
+   ; of energy cards already selected to discard, and [wcbfa] is the total
+   ; amount of energies that are required to discard.
+; if [wcbfa] == 0:
+	; prints only "[wcbfb]"
+HandleEnergyDiscardMenuInput: ; 46b7 (1:46b7)
+	lb bc, 16, 16
 	ld a, [wcbfa]
 	or a
-	jr z, .asm_46d9
+	jr z, .print_single_number
 	ld a, [wcbfb]
 	add SYM_0
 	call WriteByteToBGMap0
@@ -989,21 +1014,21 @@ Func_46b7: ; 46b7 (1:46b7)
 	ld a, [wcbfa]
 	add SYM_0
 	call WriteByteToBGMap0
-	jr .asm_46e0
-.asm_46d9
+	jr .wait_input
+.print_single_number
 	ld a, [wcbfb]
 	inc b
-	call $65b7
-.asm_46e0
+	call WriteTwoDigitNumberInTxSymbolFormat
+.wait_input
 	call DoFrame
 	call HandleCardListInput
-	jr nc, .asm_46e0
-	cp $ff
-	jr z, .asm_46f1
+	jr nc, .wait_input
+	cp $ff ; B pressed?
+	jr z, .return_carry
 	call GetCardInDuelTempList_OnlyDeckIndex
 	or a
 	ret
-.asm_46f1
+.return_carry
 	scf
 	ret
 ; 0x46f3
@@ -1025,18 +1050,18 @@ DuelMenu_Attack: ; 46fc (1:46fc)
 	jr nc, .can_attack
 .alert_cant_attack_and_cancel_menu
 	call DrawWideTextBox_WaitForInput
-	jp PrintDuelMenu
+	jp PrintDuelMenuAndHandleInput
 
 .can_attack
 	xor a
 	ld [wSelectedDuelSubMenuItem], a
 .try_open_attack_menu
-	call LoadPokemonMovesToDuelTempList
+	call PrintAndLoadMovesToDuelTempList
 	or a
 	jr nz, .open_attack_menu
 	ldtx hl, NoSelectableAttackText
 	call DrawWideTextBox_WaitForInput
-	jp PrintDuelMenu
+	jp PrintDuelMenuAndHandleInput
 
 .open_attack_menu
 	push af
@@ -1053,13 +1078,13 @@ DuelMenu_Attack: ; 46fc (1:46fc)
 
 .wait_for_input
 	call DoFrame
-	ldh a, [hButtonsPressed]
+	ldh a, [hKeysPressed]
 	and START
 	jr nz, .display_selected_move_info
 	call HandleMenuInput
 	jr nc, .wait_for_input
 	cp -1 ; was B pressed?
-	jp z, PrintDuelMenu
+	jp z, PrintDuelMenuAndHandleInput
 	ld [wSelectedDuelSubMenuItem], a
 	call CheckIfEnoughEnergiesToMove
 	jr nc, .enough_energy
@@ -1083,7 +1108,7 @@ DuelMenu_Attack: ; 46fc (1:46fc)
 	ld a, $07
 	call DoPracticeDuelAction
 	jp c, Func_4268
-	call Func_1730
+	call UseAttackOrPokemonPower
 	jp c, DuelMainInterface
 	ret
 
@@ -1092,15 +1117,17 @@ DuelMenu_Attack: ; 46fc (1:46fc)
 	jr .try_open_attack_menu
 
 .display_selected_move_info
-	call Func_478b
+	call OpenMovePage
 	call DrawDuelMainScene
 	jp .try_open_attack_menu
 
-Func_478b: ; 478b (1:478b)
+; draw the move page of the card at wLoadedCard1 and of the move selected in the Attack
+; menu by hCurMenuItem, and listen for input in order to switch the page or to exit.
+OpenMovePage: ; 478b (1:478b)
 	ld a, CARDPAGE_POKEMON_OVERVIEW
 	ld [wCardPageNumber], a
 	xor a
-	ld [wcbc9], a
+	ld [wCurPlayAreaSlot], a
 	call EmptyScreen
 	call Func_3b31
 	ld de, v0Tiles1 + $20 tiles
@@ -1121,28 +1148,30 @@ Func_478b: ; 478b (1:478b)
 	add hl, de
 	ld a, [hl]
 	or a
-	jr nz, .asm_47c9
-	xor a
-	jr .asm_47cb
+	jr nz, .move_2
+	xor a ; MOVEPAGE_MOVE1_1
+	jr .move_1
 
-.asm_47c9
-	ld a, $02
+.move_2
+	ld a, MOVEPAGE_MOVE2_1
 
-.asm_47cb
-	ld [wcc04], a
+.move_1
+	ld [wMovePageNumber], a
 
-.asm_47ce
-	call Func_47ec
+.open_page
+	call DisplayMovePage
 	call EnableLCD
 
-.asm_47d4
+.loop
 	call DoFrame
-	ldh a, [hButtonsPressed2]
+	; switch page (see SwitchMovePage) if Right or Left pressed
+	ldh a, [hDPadHeld]
 	and D_RIGHT | D_LEFT
-	jr nz, .asm_47ce
-	ldh a, [hButtonsPressed]
+	jr nz, .open_page
+	; return to Attack menu if A or B pressed
+	ldh a, [hKeysPressed]
 	and A_BUTTON | B_BUTTON
-	jr z, .asm_47d4
+	jr z, .loop
 	ret
 
 AttackMenuParameters:
@@ -1153,64 +1182,77 @@ AttackMenuParameters:
 	db SYM_SPACE ; tile behind cursor
 	dw $0000 ; function pointer if non-0
 
-Func_47ec: ; $47ec (1:47ec)
-	ld a, [wcc04]
-	ld hl, $47f5
+; display the card page with id at wMovePageNumber of wLoadedCard1
+DisplayMovePage: ; $47ec (1:47ec)
+	ld a, [wMovePageNumber]
+	ld hl, MovePageDisplayPointerTable
 	jp JumpToFunctionInTable
 
-PtrTable_47f5: ; $47f5 (1:47f5)
-	dw Func_47fd
-	dw Func_4802
-	dw Func_480d
-	dw Func_4812
+MovePageDisplayPointerTable: ; $47f5 (1:47f5)
+	dw DisplayMovePage_Move1Page1 ; MOVEPAGE_MOVE1_1
+	dw DisplayMovePage_Move1Page2 ; MOVEPAGE_MOVE1_2
+	dw DisplayMovePage_Move2Page1 ; MOVEPAGE_MOVE2_1
+	dw DisplayMovePage_Move2Page2 ; MOVEPAGE_MOVE2_2
 
-Func_47fd: ; $47fd (1:47fd)
-	call $5d1f
-	jr Func_481b
+; display MOVEPAGE_MOVE1_1
+DisplayMovePage_Move1Page1: ; $47fd (1:47fd)
+	call DisplayCardPage_PokemonMove1Page1
+	jr SwitchMovePage
 
-Func_4802: ; $4802 (1:4802)
+; display MOVEPAGE_MOVE1_2 if it exists. otherwise return in order
+; to switch back to MOVEPAGE_MOVE1_1 and display it instead.
+DisplayMovePage_Move1Page2: ; $4802 (1:4802)
 	ld hl, wLoadedCard1Move1Description + 2
 	ld a, [hli]
 	or [hl]
 	ret z
-	call $5d27
-	jr Func_481b
+	call DisplayCardPage_PokemonMove1Page2
+	jr SwitchMovePage
 
-Func_480d: ; $480d (1:480d)
-	call $5d2f
-	jr Func_481b
+; display MOVEPAGE_MOVE2_1
+DisplayMovePage_Move2Page1: ; $480d (1:480d)
+	call DisplayCardPage_PokemonMove2Page1
+	jr SwitchMovePage
 
-Func_4812: ; $4812 (1:4812)
+; display MOVEPAGE_MOVE2_2 if it exists. otherwise return in order
+; to switch back to MOVEPAGE_MOVE2_1 and display it instead.
+DisplayMovePage_Move2Page2: ; $4812 (1:4812)
 	ld hl, wLoadedCard1Move2Description + 2
 	ld a, [hli]
 	or [hl]
 	ret z
-	call $5d37
+	call DisplayCardPage_PokemonMove2Page2
+;	fallthrough
 
-Func_481b: ; $481b (1:481b)
-	ld hl, wcc04
+; switch to MOVEPAGE_MOVE*_2 if in MOVEPAGE_MOVE*_1 and vice versa.
+; sets the next move page to switch to if Right or Left are pressed.
+SwitchMovePage: ; $481b (1:481b)
+	ld hl, wMovePageNumber
 	ld a, $01
 	xor [hl]
 	ld [hl], a
 	ret
 
-; copies the following to the wDuelTempList buffer:
-;   if pokemon's second moveslot is empty: <card_no>, 0
-;   else: <card_no>, 0, <card_no>, 1
-LoadPokemonMovesToDuelTempList: ; 4823 (1:4823)
+; given the card at hTempCardIndex_ff98, for each non-empty, non-Pokemon Power moveslot,
+; prints its information at lines 13 (first move, if any), and 15 (second move, if any)
+; also, copies zero, one, or both of the following to wDuelTempList, $ff terminated:
+;   if pokemon's first moveslot isn't empty or a Pokemon Power: <card_index>, 0
+;   if pokemon's second moveslot isn't empty or a Pokemon Power: <card_index>, 1
+; return the amount of non-empty, non-Pokemon Power attacks in a.
+PrintAndLoadMovesToDuelTempList: ; 4823 (1:4823)
 	call DrawWideTextBox
 	ld a, DUELVARS_ARENA_CARD
 	call GetTurnDuelistVariable
 	ldh [hTempCardIndex_ff98], a
 	call LoadCardDataToBuffer1_FromDeckIndex
-	ld c, $00
-	ld b, $0d
+	ld c, 0
+	ld b, 13
 	ld hl, wDuelTempList
 	xor a
 	ld [wCardPageNumber], a
 	ld de, wLoadedCard1Move1Name
-	call CheckIfMoveExists
-	jr c, .check_for_second_attack_slot
+	call CheckMoveslotEmptyOrPokemonPower
+	jr c, .check_second_moveslot
 	ldh a, [hTempCardIndex_ff98]
 	ld [hli], a
 	xor a
@@ -1220,16 +1262,16 @@ LoadPokemonMovesToDuelTempList: ; 4823 (1:4823)
 	push bc
 	ld e, b
 	ld hl, wLoadedCard1Move1Name
-	call Func_5c33
+	call PrintMoveOrPkmnPowerInformation
 	pop bc
 	pop hl
 	inc b
-	inc b
+	inc b ; 15
 
-.check_for_second_attack_slot
+.check_second_moveslot
 	ld de, wLoadedCard1Move2Name
-	call CheckIfMoveExists
-	jr c, .finish_loading_attacks
+	call CheckMoveslotEmptyOrPokemonPower
+	jr c, .done
 	ldh a, [hTempCardIndex_ff98]
 	ld [hli], a
 	ld a, $01
@@ -1239,17 +1281,17 @@ LoadPokemonMovesToDuelTempList: ; 4823 (1:4823)
 	push bc
 	ld e, b
 	ld hl, wLoadedCard1Move2Name
-	call Func_5c33
+	call PrintMoveOrPkmnPowerInformation
 	pop bc
 	pop hl
 
-.finish_loading_attacks
+.done
 	ld a, c
 	ret
 
 ; given de = wLoadedCard*Move*Name, return carry if the move is a
-; Pkmn Power or the moveslot is empty.
-CheckIfMoveExists: ; 4872 (1:4872)
+; Pkmn Power or if the moveslot is empty.
+CheckMoveslotEmptyOrPokemonPower: ; 4872 (1:4872)
 	push hl
 	push de
 	push bc
@@ -1311,19 +1353,19 @@ _CheckIfEnoughEnergiesToMove: ; 48ac (1:48ac)
 	call LoadCardDataToBuffer1_FromDeckIndex
 	pop bc
 	push bc
-	ld de, wLoadedCard1Move1Energy
+	ld de, wLoadedCard1Move1EnergyCost
 	ld a, c
 	or a
 	jr z, .got_move
-	ld de, wLoadedCard1Move2Energy
+	ld de, wLoadedCard1Move2EnergyCost
 
 .got_move
-	ld hl, CARD_DATA_MOVE1_NAME - CARD_DATA_MOVE1_ENERGY
+	ld hl, CARD_DATA_MOVE1_NAME - CARD_DATA_MOVE1_ENERGY_COST
 	add hl, de
 	ld a, [hli]
 	or [hl]
 	jr z, .not_usable_or_not_enough_energies
-	ld hl, CARD_DATA_MOVE1_CATEGORY - CARD_DATA_MOVE1_ENERGY
+	ld hl, CARD_DATA_MOVE1_CATEGORY - CARD_DATA_MOVE1_ENERGY_COST
 	add hl, de
 	ld a, [hl]
 	cp POKEMON_POWER
@@ -1412,64 +1454,67 @@ CheckIfActiveCardParalyzedOrAsleep: ; 4918 (1:4918)
 	scf
 	ret
 
-; this handles drawing a card at the beginning of the turn among other things
-Func_4933: ; 4933 (1:4933)
-	ld a, $01
+; display the animation of the turn duelist drawing a card at the beginning of the turn
+; if there isn't any card left in the deck, let the player know with a text message
+DisplayDrawOneCardScreen: ; 4933 (1:4933)
+	ld a, 1
 	push hl
 	push de
 	push bc
-	ld [wcbe8], a
+	ld [wNumCardsTryingToDraw], a
 	xor a
-	ld [wcbe9], a
+	ld [wNumCardsBeingDrawn], a
 	ld a, DUELVARS_NUMBER_OF_CARDS_NOT_IN_DECK
 	call GetTurnDuelistVariable
 	ld a, DECK_SIZE
 	sub [hl]
-	ld hl, wcbe8
+	ld hl, wNumCardsTryingToDraw
 	cp [hl]
 	jr nc, .has_cards_left
-	ld [hl], a
+	; trying to draw more cards than there are left in the deck
+	ld [hl], a ; 0
 .has_cards_left
-	ld a, [wcac2]
-	cp $07
-	jr z, .asm_495f
-	cp $09
-	jr z, .asm_495f
+	ld a, [wDuelDisplayedScreen]
+	cp DRAW_CARDS
+	jr z, .portraits_drawn
+	cp SHUFFLE_DECK
+	jr z, .portraits_drawn
 	call EmptyScreen
-	call Func_4a97
-.asm_495f
-	ld a, $07
-	ld [wcac2], a
-	call Func_49ca
-	ld a, [wcbe8]
+	call DrawDuelistPortraitsAndNames
+.portraits_drawn
+	ld a, DRAW_CARDS
+	ld [wDuelDisplayedScreen], a
+	call PrintDeckAndHandIconsAndNumberOfCards
+	ld a, [wNumCardsTryingToDraw]
 	or a
 	jr nz, .can_draw
-	ldtx hl, NoCardsInDeckCannotDraw
+	; if wNumCardsTryingToDraw set to 0 before, it's because not enough cards in deck
+	ldtx hl, CannotDrawCardBecauseNoCardsInDeckText
 	call DrawWideTextBox_WaitForInput
 	jr .done
 .can_draw
 	ld l, a
 	ld h, 0
 	call LoadTxRam3
-	ldtx hl, DrawCardsFromTheDeck
+	ldtx hl, DrawCardsFromTheDeckText
 	call DrawWideTextBox_PrintText
 	call EnableLCD
-.asm_4984
+.anim_drawing_cards_loop
 	call Func_49a8
-	ld hl, wcbe9
+	ld hl, wNumCardsBeingDrawn
 	inc [hl]
-	call Func_49ed
-	ld a, [wcbe9]
-	ld hl, wcbe8
+	call PrintNumberOfHandAndDeckCards
+	ld a, [wNumCardsBeingDrawn]
+	ld hl, wNumCardsTryingToDraw
 	cp [hl]
-	jr c, .asm_4984
+	jr c, .anim_drawing_cards_loop
 	ld c, 30
-.asm_4999
+.wait_loop
 	call DoFrame
-	call Func_67b2
+	call CheckSkipDelayAllowed
 	jr c, .done
 	dec c
-	jr nz, .asm_4999
+	jr nz, .wait_loop
 .done
 	pop bc
 	pop de
@@ -1489,7 +1534,7 @@ Func_49a8: ; 49a8 (1:49a8)
 	call Func_3b6a
 .asm_49b9
 	call DoFrame
-	call Func_67b2
+	call CheckSkipDelayAllowed
 	jr c, .asm_49c6
 	call Func_3b52
 	jr c, .asm_49b9
@@ -1498,67 +1543,106 @@ Func_49a8: ; 49a8 (1:49a8)
 	ret
 ; 0x49ca
 
-Func_49ca: ; 49ca (1:49ca)
+; prints, for each duelist, the number of cards in the hand along with the
+; hand icon, and the number of cards in the deck, along with the deck icon,
+; according to each element's placement in the draw card(s) screen.
+PrintDeckAndHandIconsAndNumberOfCards: ; 49ca (1:49ca)
 	call LoadDuelDrawCardsScreenTiles
-	ld hl, $4a35
+	ld hl, DeckAndHandIconsTileData
 	call WriteDataBlocksToBGMap0
 	ld a, [wConsole]
 	cp CONSOLE_CGB
 	jr nz, .not_cgb
 	call BankswitchVRAM1
-	ld hl, $4a6e
+	ld hl, DeckAndHandIconsCGBPalData
 	call WriteDataBlocksToBGMap0
 	call BankswitchVRAM0
 .not_cgb
-	call Func_49ed.player_turn
-	call Func_49ed.opponent_turn
+	call PrintPlayerNumberOfHandAndDeckCards
+	call PrintOpponentNumberOfHandAndDeckCards
 	ret
 ; 0x49ed
 
-Func_49ed: ; 49ed (1:49ed)
+; prints, for each duelist, the number of cards in the hand, and the number
+; of cards in the deck, according to their placement in the draw card(s) screen.
+; input: wNumCardsBeingDrawn = number of cards being drawn (in order to add
+; them to the hand cards and substract them from the deck cards).
+PrintNumberOfHandAndDeckCards: ; 49ed (1:49ed)
 	ldh a, [hWhoseTurn]
 	cp PLAYER_TURN
-	jr nz, .opponent_turn
-.player_turn
+	jr nz, PrintOpponentNumberOfHandAndDeckCards
+;	fallthrough
+
+PrintPlayerNumberOfHandAndDeckCards:
 	ld a, [wPlayerNumberOfCardsInHand]
-	ld hl, wcbe9
+	ld hl, wNumCardsBeingDrawn
 	add [hl]
 	ld d, a
 	ld a, DECK_SIZE
 	ld hl, wPlayerNumberOfCardsNotInDeck
 	sub [hl]
-	ld hl, wcbe9
+	ld hl, wNumCardsBeingDrawn
 	sub [hl]
 	ld e, a
 	ld a, d
 	lb bc, 16, 10
-	call $65b7
+	call WriteTwoDigitNumberInTxSymbolFormat
 	ld a, e
 	lb bc, 10, 10
-	jp $65b7
-.opponent_turn
+	jp WriteTwoDigitNumberInTxSymbolFormat
+
+PrintOpponentNumberOfHandAndDeckCards:
 	ld a, [wOpponentNumberOfCardsInHand]
-	ld hl, wcbe9
+	ld hl, wNumCardsBeingDrawn
 	add [hl]
 	ld d, a
 	ld a, DECK_SIZE
 	ld hl, wOpponentNumberOfCardsNotInDeck
 	sub [hl]
-	ld hl, wcbe9
+	ld hl, wNumCardsBeingDrawn
 	sub [hl]
 	ld e, a
 	ld a, d
 	lb bc, 5, 3
-	call $65b7
+	call WriteTwoDigitNumberInTxSymbolFormat
 	ld a, e
 	lb bc, 11, 3
-	jp $65b7
+	jp WriteTwoDigitNumberInTxSymbolFormat
 ; 0x4a35
 
-	INCROM $4a35, $4a97
+DeckAndHandIconsTileData:
+; x, y, tiles[], 0
+	db  4,  3, SYM_CROSS, 0 ; x for opponent's hand
+	db 10,  3, SYM_CROSS, 0 ; x for opponent's deck
+	db  8,  2, $f4, $f5,  0 ; opponent's deck icon
+	db  8,  3, $f6, $f7,  0 ; opponent's deck icon
+	db  2,  2, $f8, $f9,  0 ; opponent's hand icon
+	db  2,  3, $fa, $fb,  0 ; opponent's hand icon
+	db  9, 10, SYM_CROSS, 0 ; x for player's deck
+	db 15, 10, SYM_CROSS, 0 ; x for player's hand
+	db  7,  9, $f4, $f5,  0 ; player's deck icon
+	db  7, 10, $f6, $f7,  0 ; player's deck icon
+	db 13,  9, $f8, $f9,  0 ; player's hand icon
+	db 13, 10, $fa, $fb,  0 ; player's hand icon
+	db $ff
+
+DeckAndHandIconsCGBPalData:
+; x, y, pals[], 0
+	db  8,  2, $02, $02, 0
+	db  8,  3, $02, $02, 0
+	db  2,  2, $02, $02, 0
+	db  2,  3, $02, $02, 0
+	db  7,  9, $02, $02, 0
+	db  7, 10, $02, $02, 0
+	db 13,  9, $02, $02, 0
+	db 13, 10, $02, $02, 0
+	db $ff
 
-Func_4a97: ; 4a97 (1:4a97)
+; draw the portraits of the two duelists and print their names.
+; also draw an horizontal line separating the two sides.
+DrawDuelistPortraitsAndNames: ; 4a97 (1:4a97)
 	call LoadSymbolsFont
+	; player's name
 	ld de, wDefaultText
 	push de
 	call CopyPlayerName
@@ -1566,8 +1650,10 @@ Func_4a97: ; 4a97 (1:4a97)
 	call InitTextPrinting
 	pop hl
 	call ProcessText
-	ld bc, $5
+	; player's portrait
+	lb bc, 0, 5
 	call Func_3e10
+	; opponent's name (aligned to the right)
 	ld de, wDefaultText
 	push de
 	call CopyOpponentName
@@ -1580,48 +1666,55 @@ Func_4a97: ; 4a97 (1:4a97)
 	call InitTextPrinting
 	pop hl
 	call ProcessText
+	; opponent's portrait
 	ld a, [wOpponentPortrait]
-	ld bc, $d01
+	lb bc, 13, 1
 	call Func_3e2a
+	; middle line
 	call DrawDuelHorizontalSeparator
 	ret
 ; 0x4ad6
 
-Func_4ad6: ; 4ad6 (1:4ad6)
+; print the number of prizes left, of active Pokemon, and of cards left in the deck
+; of both duelists. this is called when the duel ends.
+PrintDuelResultStats: ; 4ad6 (1:4ad6)
 	lb de, 8, 8
-	call Func_4ae9
+	call PrintDuelistResultStats
 	call SwapTurn
 	lb de, 1, 1
-	call Func_4ae9
+	call PrintDuelistResultStats
 	call SwapTurn
 	ret
 ; 0x4ae9
 
-Func_4ae9: ; 4ae9 (1:4ae9)
-	call $5f4a
-	ld hl, $7b
-	call Func_2c1b
-	call $5f50
+; print, at d,e, the number of prizes left, of active Pokemon, and of cards left in
+; the deck of the turn duelist. b,c are used throughout as input coords for
+; WriteTwoDigitNumberInTxSymbolFormat, and d,e for InitTextPrinting_ProcessTextFromID.
+PrintDuelistResultStats: ; 4ae9 (1:4ae9)
+	call SetNoLineSeparation
+	ldtx hl, PrizesLeftActivePokemonCardsInDeckText
+	call InitTextPrinting_ProcessTextFromID
+	call SetOneLineSeparation
 	ld c, e
 	ld a, d
-	add $07
+	add 7
 	ld b, a
 	inc a
 	inc a
 	ld d, a
 	call CountPrizes
-	call .asm_4b22
+	call .print_x_cards
 	inc e
 	inc c
 	ld a, DUELVARS_NUMBER_OF_POKEMON_IN_PLAY_AREA
 	call GetTurnDuelistVariable
-	ld hl, $7d
+	ldtx hl, YesText
 	or a
 	jr nz, .pkmn_in_play_area
-	ld hl, $7c
+	ldtx hl, NoneText
 .pkmn_in_play_area
 	dec d
-	call Func_2c1b
+	call InitTextPrinting_ProcessTextFromID
 	inc e
 	inc d
 	inc c
@@ -1629,10 +1722,10 @@ Func_4ae9: ; 4ae9 (1:4ae9)
 	call GetTurnDuelistVariable
 	ld a, DECK_SIZE
 	sub [hl]
-.asm_4b22
-	call $65b7
-	ld hl, $7e
-	call Func_2c1b
+.print_x_cards
+	call WriteTwoDigitNumberInTxSymbolFormat
+	ldtx hl, CardsText
+	call InitTextPrinting_ProcessTextFromID
 	ret
 ; 0x4b2c
 
@@ -1644,7 +1737,7 @@ DisplayPlayerDrawCardScreen: ; 4b2c (1:4b2c)
 
 ; display card detail when a card is drawn or played
 ; hl is text to display
-; a is card index
+; a is the card's deck index
 DisplayCardDetailScreen: ; 4b31 (1:4b31)
 	call LoadCardDataToBuffer1_FromDeckIndex
 	call _DisplayCardDetailScreen
@@ -1655,7 +1748,7 @@ Func_4b38: ; 4b38 (1:4b38)
 	ld a, [wDuelTempList]
 	cp $ff
 	ret z
-	call DrawCardListScreenLayout
+	call InitAndDrawCardListScreenLayout
 	call CountCardsInDuelTempList ; list length
 	ld hl, CardListParameters ; other list params
 	lb de, 0, 0 ; initial page scroll offset, initial item (in the visible page)
@@ -1670,59 +1763,61 @@ Func_4b38: ; 4b38 (1:4b38)
 ; 0x4b60
 
 Func_4b60: ; 4b60 (1:4b60)
-	call $7107
+	call InitializeDuelVariables
 	call SwapTurn
-	call $7107
+	call InitializeDuelVariables
 	call SwapTurn
-	call $4e84
-	call $4d97
+	call Func_4e84
+	call ShuffleDeckAndDrawSevenCards
 	ldh [hTemp_ffa0], a
 	call SwapTurn
-	call $4d97
+	call ShuffleDeckAndDrawSevenCards
 	call SwapTurn
 	ld c, a
 	ldh a, [hTemp_ffa0]
 	ld b, a
 	and c
-	jr nz, .asm_4bd0
+	jr nz, .hand_cards_ok
 	ld a, b
 	or c
-	jr z, .asm_4bb2
+	jr z, .neither_drew_basic_pkmn
 	ld a, b
 	or a
-	jr nz, .asm_4b9c
-.asm_4b8c
-	call $4df3
-	call $7107
-	call $4e6e
-	call $4d97
-	jr c, .asm_4b8c
-	jr .asm_4bd0
-
-.asm_4b9c
+	jr nz, .opp_drew_no_basic_pkmn
+
+;.player_drew_no_basic_pkmn
+.ensure_player_basic_pkmn_loop
+	call DisplayNoBasicPokemonInHandScreenAndText
+	call InitializeDuelVariables
+	call Func_4e6e
+	call ShuffleDeckAndDrawSevenCards
+	jr c, .ensure_player_basic_pkmn_loop
+	jr .hand_cards_ok
+
+.opp_drew_no_basic_pkmn
 	call SwapTurn
-.asm_4b9f
-	call $4df3
-	call $7107
-	call $4e6e
-	call $4d97
-	jr c, .asm_4b9f
+.ensure_opp_basic_pkmn_loop
+	call DisplayNoBasicPokemonInHandScreenAndText
+	call InitializeDuelVariables
+	call Func_4e6e
+	call ShuffleDeckAndDrawSevenCards
+	jr c, .ensure_opp_basic_pkmn_loop
 	call SwapTurn
-	jr .asm_4bd0
+	jr .hand_cards_ok
 
-.asm_4bb2
+.neither_drew_basic_pkmn
 	ldtx hl, NeitherPlayerHasBasicPkmnText
 	call DrawWideTextBox_WaitForInput
-	call $4e06
-	call $7107
+	call DisplayNoBasicPokemonInHandScreen
+	call InitializeDuelVariables
 	call SwapTurn
-	call $4e06
-	call $7107
+	call DisplayNoBasicPokemonInHandScreen
+	call InitializeDuelVariables
 	call SwapTurn
-	call $4dfc
+	call PrintReturnCardsToDeckDrawAgain
 	jp Func_4b60
 
-.asm_4bd0
+.hand_cards_ok
 	ldh a, [hWhoseTurn]
 	push af
 	ld a, PLAYER_TURN
@@ -1731,11 +1826,11 @@ Func_4b60: ; 4b60 (1:4b60)
 	call SwapTurn
 	call Func_4cd5
 	call SwapTurn
-	jp c, $4c77
+	jp c, .asm_4c77
 	call Func_311d
 	ldtx hl, PlacingThePrizesText
 	call DrawWideTextBox_WaitForInput
-	call Func_0f58
+	call ExchangeRNG
 	ld a, [wDuelInitialPrizes]
 	ld l, a
 	ld h, 0
@@ -1743,68 +1838,118 @@ Func_4b60: ; 4b60 (1:4b60)
 	ldtx hl, PleasePlacePrizesText
 	call DrawWideTextBox_PrintText
 	call EnableLCD
-	call $4c7c
+	call .asm_4c7c
 	call WaitForWideTextBoxInput
 	pop af
 	ldh [hWhoseTurn], a
-	call $7133
+	call InitTurnDuelistPrizes
 	call SwapTurn
-	call $7133
+	call InitTurnDuelistPrizes
 	call SwapTurn
 	call EmptyScreen
 	ld a, BOXMSG_COIN_TOSS
 	call DrawDuelBoxMessage
-	ldtx hl, CoinTossToDetermineWhoFirstText
+	ldtx hl, CoinTossToDecideWhoPlaysFirstText
 	call DrawWideTextBox_WaitForInput
 	ldh a, [hWhoseTurn]
 	cp PLAYER_TURN
-	jr nz, .asm_4c52
+	jr nz, .opponent_turn
 	ld de, wDefaultText
 	call CopyPlayerName
 	ld hl, $0000
 	call LoadTxRam2
 	ldtx hl, YouPlayFirstText
-	ldtx de, IfHeadPlayerPlaysFirstText
+	ldtx de, IfHeadsDuelistPlaysFirstText
 	call TossCoin
-	jr c, .asm_4c4a
+	jr c, .play_first
 	call SwapTurn
 	ldtx hl, YouPlaySecondText
-
-.asm_4c4a
+.play_first
 	call DrawWideTextBox_WaitForInput
-	call Func_0f58
+	call ExchangeRNG
 	or a
 	ret
 
-.asm_4c52
+.opponent_turn
 	ld de, wDefaultText
 	call CopyOpponentName
 	ld hl, $0000
 	call LoadTxRam2
 	ldtx hl, YouPlaySecondText
-	ldtx de, IfHeadPlayerPlaysFirstText
+	ldtx de, IfHeadsDuelistPlaysFirstText
 	call TossCoin
-	jr c, .asm_4c6f
+	jr c, .play_second
 	call SwapTurn
 	ldtx hl, YouPlayFirstText
-
-.asm_4c6f
+.play_second
 	call DrawWideTextBox_WaitForInput
-	call Func_0f58
+	call ExchangeRNG
 	or a
 	ret
-; 0x4c77
 
-	INCROM $4c77,  $4cd5
+.asm_4c77
+	pop af
+	ldh [hWhoseTurn], a
+	scf
+	ret
+
+.asm_4c7c
+	ld hl, .data_4cbd
+	ld e, $34
+	ld a, [wDuelInitialPrizes]
+	ld d, a
+.asm_4c85
+	push de
+	ld b, $14
+.asm_4c88
+	call DoFrame
+	call CheckSkipDelayAllowed
+	jr c, .asm_4c93
+	dec b
+	jr nz, .asm_4c88
+.asm_4c93
+	call .asm_4cb4
+	call .asm_4cb4
+	push hl
+	ld a, $08
+	call PlaySFX
+	lb bc, 3, 5
+	ld a, e
+	call WriteTwoDigitNumberInTxSymbolFormat
+	lb bc, 18, 7
+	ld a, e
+	call WriteTwoDigitNumberInTxSymbolFormat
+	pop hl
+	pop de
+	dec e
+	dec d
+	jr nz, .asm_4c85
+	ret
+
+.asm_4cb4
+	ld b, [hl]
+	inc hl
+	ld c, [hl]
+	inc hl
+	ld a, $ac
+	jp WriteByteToBGMap0
+
+.data_4cbd
+	db $05, $06, $0e, $05
+	db $06, $06, $0d, $05
+	db $05, $07, $0e, $04
+	db $06, $07, $0d, $04
+	db $05, $08, $0e, $03
+	db $06, $08, $0d, $03
+; 0x4cd5
 
-; Select Basic Pokemon From Hand
 Func_4cd5: ; 4cd5 (1:4cd5)
 	ld a, DUELVARS_DUELIST_TYPE
 	call GetTurnDuelistVariable
 	cp DUELIST_TYPE_PLAYER
-	jr z, .asm_4d15
+	jr z, .player_choose_arena
 	cp DUELIST_TYPE_LINK_OPP
-	jr z, .asm_4cec
+	jr z, .exchange_duelvars
 	push af
 	push hl
 	call Func_2bc3
@@ -1814,28 +1959,27 @@ Func_4cd5: ; 4cd5 (1:4cd5)
 	or a
 	ret
 
-.asm_4cec
+.exchange_duelvars
 	ldtx hl, TransmitingDataText
 	call DrawWideTextBox_PrintText
-	call Func_0f58
-	ld hl, wPlayerCardLocations
-	ld de, wOpponentCardLocations
-	ld c, $80
-	call Func_0e63
-	jr c, .asm_4d12
-	ld c, $80
-	call Func_0e63
-	jr c, .asm_4d12
+	call ExchangeRNG
+	ld hl, wPlayerDuelVariables
+	ld de, wOpponentDuelVariables
+	ld c, (wOpponentDuelVariables - wPlayerDuelVariables) / 2
+	call SerialExchangeBytes
+	jr c, .error
+	ld c, (wOpponentDuelVariables - wPlayerDuelVariables) / 2
+	call SerialExchangeBytes
+	jr c, .error
 	ld a, DUELVARS_DUELIST_TYPE
 	call GetTurnDuelistVariable
 	ld [hl], DUELIST_TYPE_LINK_OPP
 	or a
 	ret
-
-.asm_4d12
+.error
 	jp DuelTransmissionError
 
-.asm_4d15
+.player_choose_arena
 	call EmptyScreen
 	ld a, BOXMSG_ARENA_POKEMON
 	call DrawDuelBoxMessage
@@ -1845,8 +1989,8 @@ Func_4cd5: ; 4cd5 (1:4cd5)
 	call DoPracticeDuelAction
 .asm_4d28
 	xor a
-	ld hl, $006e
-	call $5502
+	ldtx hl, PleaseChooseAnActivePokemonText
+	call Func_5502
 	jr c, .asm_4d28
 	ldh a, [hTempCardIndex_ff98]
 	call LoadCardDataToBuffer1_FromDeckIndex
@@ -1858,25 +2002,25 @@ Func_4cd5: ; 4cd5 (1:4cd5)
 	ldh a, [hTempCardIndex_ff98]
 	ldtx hl, PlacedInTheArenaText
 	call DisplayCardDetailScreen
-	jr .asm_4d4c
+	jr .choose_bench
 
-.asm_4d4c
+.choose_bench
 	call EmptyScreen
 	ld a, BOXMSG_BENCH_POKEMON
 	call DrawDuelBoxMessage
 	ldtx hl, ChooseUpTo5BasicPkmnToPlaceOnBenchText
-	call Func_2c73
+	call PrintScrollableText_NoTextBoxLabel
 	ld a, $3
 	call DoPracticeDuelAction
-.asm_4d5f
+.bench_loop
 	ld a, $1
-	ld hl, $006f
-	call $5502
+	ldtx hl, ChooseYourBenchPokemonText
+	call Func_5502
 	jr c, .asm_4d8e
 	ld a, DUELVARS_NUMBER_OF_POKEMON_IN_PLAY_AREA
 	call GetTurnDuelistVariable
 	cp MAX_PLAY_AREA_POKEMON
-	jr nc, .asm_4d86
+	jr nc, .no_space
 	ldh a, [hTempCardIndex_ff98]
 	call PutHandPokemonCardInPlayArea
 	ldh a, [hTempCardIndex_ff98]
@@ -1884,22 +2028,131 @@ Func_4cd5: ; 4cd5 (1:4cd5)
 	call DisplayCardDetailScreen
 	ld a, $5
 	call DoPracticeDuelAction
-	jr .asm_4d5f
+	jr .bench_loop
 
-.asm_4d86
+.no_space
 	ldtx hl, NoSpaceOnTheBenchText
 	call DrawWideTextBox_WaitForInput
-	jr .asm_4d5f
+	jr .bench_loop
 
 .asm_4d8e
 	ld a, $4
 	call DoPracticeDuelAction
-	jr c, .asm_4d5f
+	jr c, .bench_loop
 	or a
 	ret
 ; 0x4d97
 
-	INCROM $4d97,  $4e40
+; the turn duelist shuffles the deck unless it's a practice duel, then draws 7 cards
+; returns $00 in a and carry if no basic Pokemon cards are drawn, and $01 in a otherwise
+ShuffleDeckAndDrawSevenCards: ; 4d97 (1:4d97)
+	call InitializeDuelVariables
+	ld a, [wDuelType]
+	cp DUELTYPE_PRACTICE
+	jr z, .deck_ready
+	call ShuffleDeck
+	call ShuffleDeck
+.deck_ready
+	ld b, 7
+.draw_loop
+	call DrawCardFromDeck
+	call AddCardToHand
+	dec b
+	jr nz, .draw_loop
+	ld a, DUELVARS_HAND
+	call GetTurnDuelistVariable
+	ld b, $00
+	ld c, 7
+.cards_loop
+	ld a, [hli]
+	push hl
+	push bc
+	call LoadCardDataToBuffer1_FromDeckIndex
+	call .check_basic_pokemon
+	pop bc
+	pop hl
+	or b
+	ld b, a
+	dec c
+	jr nz, .cards_loop
+	ld a, b
+	or a
+	ret nz
+	xor a
+	scf
+	ret
+
+.asm_4dd1
+	ld a, [wLoadedCard1ID]
+	cp MYSTERIOUS_FOSSIL
+	jr z, .basic
+	cp CLEFAIRY_DOLL
+	jr z, .basic
+.check_basic_pokemon
+	ld a, [wLoadedCard1Type]
+	cp TYPE_ENERGY
+	jr nc, .energy_trainer_nonbasic
+	ld a, [wLoadedCard1Stage]
+	or a
+	jr nz, .energy_trainer_nonbasic
+
+; basic
+	ld a, $01
+	ret
+.energy_trainer_nonbasic
+	xor a
+	scf
+	ret
+.basic
+	ld a, $01
+	or a
+	ret
+; 0x4df3
+
+DisplayNoBasicPokemonInHandScreenAndText: ; 4df3 (1:4df3)
+	ldtx hl, ThereAreNoBasicPokemonInHand
+	call DrawWideTextBox_WaitForInput
+	call DisplayNoBasicPokemonInHandScreen
+;	fallthrough
+
+; prints ReturnCardsToDeckAndDrawAgainText in a textbox and calls ExchangeRNG
+PrintReturnCardsToDeckDrawAgain: ; 4dfc (1:4dfc)
+	ldtx hl, ReturnCardsToDeckAndDrawAgainText
+	call DrawWideTextBox_WaitForInput
+	call ExchangeRNG
+	ret
+; 0x4e06
+
+; display a bare list of seven hand cards of the turn duelist, and the duelist's name above
+; used to let the player know that there are no basic Pokemon in the hand and need to redraw
+DisplayNoBasicPokemonInHandScreen: ; 4e06 (1:4e06)
+	call EmptyScreen
+	call LoadDuelCardSymbolTiles
+	lb de, 0, 0
+	lb bc, 20, 18
+	call DrawRegularTextBox
+	call CreateHandCardList
+	call CountCardsInDuelTempList
+	ld hl, NoBasicPokemonCardListParameters
+	lb de, 0, 0
+	call PrintCardListItems
+	ldtx hl, DuelistHandText
+	lb de, 1, 1
+	call InitTextPrinting
+	call PrintTextNoDelay
+	call EnableLCD
+	call WaitForWideTextBoxInput
+	ret
+; 0x4e37
+
+NoBasicPokemonCardListParameters:
+	db 1, 3 ; 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 7 ; 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
 
 Func_4e40: ; 4e40 (1:4e40)
 	call CreateHandCardList
@@ -1920,23 +2173,124 @@ Func_4e40: ; 4e40 (1:4e40)
 	ret
 ; 0x4e6e
 
-	INCROM $4e6e,  $4f2d
+Func_4e6e: ; 4e6e (1:4e6e)
+	ld b, $51
+	ld c, $56
+	ldh a, [hWhoseTurn]
+	cp PLAYER_TURN
+	jr z, .asm_4e7c
+	ld b, $52
+	ld c, $57
+.asm_4e7c
+	ld hl, $63
+	ld de, $67
+	jr Func_4e98
+
+Func_4e84: ; 4e84 (1:4e84)
+	ld b, $53
+	ld c, $55
+	ld hl, $65
+	ld de, $66
+	ld a, [wDuelType]
+	cp DUELTYPE_PRACTICE
+	jr nz, Func_4e98
+	ld hl, $64
+;	fallthrough
+
+Func_4e98: ; 4e98 (1:4e98)
+	push bc
+	push de
+	push hl
+	call ZeroObjectPositionsAndToggleOAMCopy
+	call EmptyScreen
+	call DrawDuelistPortraitsAndNames
+	call LoadDuelDrawCardsScreenTiles
+	ld a, SHUFFLE_DECK
+	ld [wDuelDisplayedScreen], a
+	pop hl
+	call DrawWideTextBox_PrintText
+	call EnableLCD
+	ld a, [wDuelType]
+	cp DUELTYPE_PRACTICE
+	jr nz, .asm_4ebf
+	call WaitForWideTextBoxInput
+	jr .asm_4ee0
+.asm_4ebf
+	call Func_3b21
+	ld hl, sp+$03
+	ld a, [hl]
+	call Func_3b6a
+	ld a, [hl]
+	call Func_3b6a
+	ld a, [hl]
+	call Func_3b6a
+.asm_4ed0
+	call DoFrame
+	call CheckSkipDelayAllowed
+	jr c, .asm_4edd
+	call Func_3b52
+	jr c, .asm_4ed0
+.asm_4edd
+	call Func_3b31
+.asm_4ee0
+	xor a
+	ld [wNumCardsBeingDrawn], a
+	call PrintDeckAndHandIconsAndNumberOfCards
+	call Func_3b21
+	pop hl
+	call DrawWideTextBox_PrintText
+.asm_4eee
+	ld hl, sp+$00
+	ld a, [hl]
+	call Func_3b6a
+.asm_4ef4
+	call DoFrame
+	call CheckSkipDelayAllowed
+	jr c, .asm_4f28
+	call Func_3b52
+	jr c, .asm_4ef4
+	ld hl, wNumCardsBeingDrawn
+	inc [hl]
+	ld hl, sp+$00
+	ld a, [hl]
+	cp $55
+	jr nz, .asm_4f11
+	call PrintDeckAndHandIconsAndNumberOfCards.not_cgb
+	jr .asm_4f14
+.asm_4f11
+	call PrintNumberOfHandAndDeckCards
+.asm_4f14
+	ld a, [wNumCardsBeingDrawn]
+	cp 7
+	jr c, .asm_4eee
+	ld c, 30
+.wait_loop
+	call DoFrame
+	call CheckSkipDelayAllowed
+	jr c, .asm_4f28
+	dec c
+	jr nz, .wait_loop
+.asm_4f28
+	call Func_3b31
+	pop bc
+	ret
+; 0x4f2d
 
 Func_4f2d: ; 4f2d (1:4f2d)
-	ld a, [wcac2]
-	cp $09
+	ld a, [wDuelDisplayedScreen]
+	cp SHUFFLE_DECK
 	jr z, .asm_4f3d
 	call ZeroObjectPositionsAndToggleOAMCopy
 	call EmptyScreen
-	call Func_4a97
+	call DrawDuelistPortraitsAndNames
 .asm_4f3d
-	ld a, $09
-	ld [wcac2], a
+	ld a, SHUFFLE_DECK
+	ld [wDuelDisplayedScreen], a
 	ld a, DUELVARS_NUMBER_OF_CARDS_NOT_IN_DECK
 	call GetTurnDuelistVariable
 	ld a, DECK_SIZE
 	sub [hl]
-	cp $02
+	cp 2
 	jr c, .one_card_in_deck
 	ldtx hl, ShufflesTheDeckText
 	call DrawWideTextBox_PrintText
@@ -1956,7 +2310,7 @@ Func_4f2d: ; 4f2d (1:4f2d)
 	call Func_3b6a
 .asm_4f70
 	call DoFrame
-	call Func_67b2
+	call CheckSkipDelayAllowed
 	jr c, .asm_4f7d
 	call Func_3b52
 	jr c, .asm_4f70
@@ -1998,14 +2352,14 @@ DrawDuelMainScene: ; 4f9d (1:4f9d)
 	ret
 .draw
 ; first, load the graphics and draw the background scene
-	ld a, [wcac2]
-	cp $01
+	ld a, [wDuelDisplayedScreen]
+	cp DUEL_MAIN_SCENE
 	ret z
 	call ZeroObjectPositionsAndToggleOAMCopy
 	call EmptyScreen
 	call LoadSymbolsFont
-	ld a, $01
-	ld [wcac2], a
+	ld a, DUEL_MAIN_SCENE
+	ld [wDuelDisplayedScreen], a
 	ld a, DUELVARS_ARENA_CARD
 	call GetTurnDuelistVariable
 	ld de, v0Tiles1 + $50 tiles
@@ -2099,11 +2453,11 @@ DrawDuelHUDs: ; 503a (1:503a)
 ; 0x5093
 
 DrawDuelHUD: ; 5093 (1:5093)
-	ld hl, wcbc9
+	ld hl, wHUDEnergyAndHPBarsX
 	ld [hl], b
 	inc hl
-	ld [hl], c ; save coordinates for the HP bar
-	push de ; save coordinates for the arena card name
+	ld [hl], c ; wHUDEnergyAndHPBarsY
+	push de ; push coordinates for the arena card name
 	ld d, 1 ; opponent's info icons start in the second tile to the right
 	ld a, e
 	or a
@@ -2164,10 +2518,10 @@ DrawDuelHUD: ; 5093 (1:5093)
 	call JPWriteByteToBGMap0
 
 	; print attached energies
-	ld hl, wcbc9
+	ld hl, wHUDEnergyAndHPBarsX
 	ld b, [hl]
 	inc hl
-	ld c, [hl]
+	ld c, [hl] ; wHUDEnergyAndHPBarsY
 	lb de, 9, PLAY_AREA_ARENA
 	call PrintPlayAreaCardAttachedEnergies
 
@@ -2181,11 +2535,11 @@ DrawDuelHUD: ; 5093 (1:5093)
 	call GetTurnDuelistVariable
 	ld e, a ; cur HP
 	call DrawHPBar
-	ld hl, wcbc9
+	ld hl, wHUDEnergyAndHPBarsX
 	ld b, [hl]
 	inc hl
-	ld c, [hl]
-	inc c
+	ld c, [hl] ; wHUDEnergyAndHPBarsY
+	inc c ; [wHUDEnergyAndHPBarsY] + 1
 	call BCCoordToBGMap0Address
 	push de
 	ld hl, wDefaultText
@@ -2201,11 +2555,11 @@ DrawDuelHUD: ; 5093 (1:5093)
 	call SafeCopyDataHLtoDE
 
 	; print number of attached Pluspower and Defender with respective icon, if any
-	ld hl, wcbc9
+	ld hl, wHUDEnergyAndHPBarsX
 	ld a, [hli]
 	add 6
 	ld b, a
-	ld c, [hl]
+	ld c, [hl] ; wHUDEnergyAndHPBarsY
 	inc c
 	ld a, DUELVARS_ARENA_CARD_ATTACHED_PLUSPOWER
 	call GetTurnDuelistVariable
@@ -2268,7 +2622,7 @@ DuelHorizontalSeparatorTileData: ; 5199 (1:5199)
 ; 0x51c0
 
 DuelHorizontalSeparatorCGBPalData: ; 51c0 (1:51c0)
-; x, y, tiles[], 0
+; x, y, pals[], 0
 	db 0, 4, $02, $02, $02, $02, $02, $02, $02, $02, $02, $02, $02, 0
 	db 9, 5, $02, $02, 0
 	db 9, 6, $02, $02, 0
@@ -2355,7 +2709,7 @@ Func_5256: ; 5256 (1:5256)
 	jp nz, $5382
 	ldtx de, DrMasonText
 	ldtx hl, Text01d9
-	call Func_2c62.asm_2c67
+	call PrintScrollableText_WithTextBoxLabel_NoWait
 	call YesOrNoMenu
 	jp $5382
 ; 0x5278
@@ -2373,7 +2727,7 @@ Func_5284: ; 5284 (1:5284)
 	call Func_52bc
 	ld a, $02
 	call BankswitchSRAM
-	ld de, $bc00
+	ld de, sCurrentDuel
 	call $66ff
 	xor a
 	call BankswitchSRAM
@@ -2395,7 +2749,7 @@ Func_529b: ; 529b (1:529b)
 ; 0x52b0
 
 Func_52b0: ; 52b0 (1:52b0)
-	ldh a, [hTempPlayAreaLocationOffset_ff9d]
+	ldh a, [hTempPlayAreaLocation_ff9d]
 	cp PLAY_AREA_BENCH_1
 	ret z
 	call HasAlivePokemonOnBench
@@ -2406,12 +2760,35 @@ Func_52b0: ; 52b0 (1:52b0)
 Func_52bc: ; 52bc (1:52bc)
 	push af
 	ldtx de, DrMasonText
-	call Func_2c62
+	call PrintScrollableText_WithTextBoxLabel
 	pop af
 	ret
 ; 0x52c5
 
-	INCROM $52c5,  $54e9
+	INCROM $52c5,  $54c8
+
+; display BOXMSG_PLAYERS_TURN or BOXMSG_OPPONENTS_TURN and print
+; DuelistsTurnText in a textbox. also call ExchangeRNG.
+DisplayDuelistTurnScreen: ; 54c8 (1:54c8)
+	call EmptyScreen
+	ld c, BOXMSG_PLAYERS_TURN
+	ldh a, [hWhoseTurn]
+	cp PLAYER_TURN
+	jr z, .got_turn
+	inc c ; BOXMSG_OPPONENTS_TURN
+.got_turn
+	ld a, c
+	call DrawDuelBoxMessage
+	ldtx hl, DuelistsTurnText
+	call DrawWideTextBox_WaitForInput
+	call ExchangeRNG
+	ret
+; 0x54e2
+
+Unknown_54e2: ; 54e2 (1:54e2)
+; ???
+	db $00, $0c, $06, $0f, $00, $00, $00
+; 0x54e9
 
 DuelMenuData: ; 54e9 (1:54e9)
 	; x, y, text id
@@ -2424,17 +2801,59 @@ DuelMenuData: ; 54e9 (1:54e9)
 	db $ff
 ; 0x5502
 
-	INCROM $5502,  $5550
+Func_5502: ; 5502 (1:5502)
+	ld [wcbfd], a
+	push hl
+	call CreateHandCardList
+	call InitAndDrawCardListScreenLayout
+	pop hl
+	call SetCardListInfoBoxText
+	ld a, PLAY_CHECK
+	ld [wCardListItemSelectionMenuType], a
+.asm_5515
+	call DisplayCardList
+	jr nc, .asm_5523
+	ld a, [wcbfd]
+	or a
+	jr z, .asm_5515
+	scf
+	jr .asm_5538
+.asm_5523
+	ldh a, [hTempCardIndex_ff98]
+	call LoadCardDataToBuffer1_FromDeckIndex
+	call Func_4dd1
+	jr nc, .asm_5538
+	ldtx hl, YouCannotSelectThisCardText
+	call DrawWideTextBox_WaitForInput
+	call DrawCardListScreenLayout
+	jr .asm_5515
+.asm_5538
+	push af
+	ld a, [wSortCardListByID]
+	or a
+	call nz, SortHandCardsByID
+	pop af
+	ret
+; 0x5542
+
+Func_5542: ; 5542 (1:5542)
+	call CreateDiscardPileCardList
+	ret c
+	call InitAndDrawCardListScreenLayout
+	call SetDiscardPileScreenTexts
+	call DisplayCardList
+	ret
+; 0x5550
 
 ; draw the turn holder's discard pile screen
 OpenDiscardPileScreen: ; 5550 (1:5550)
 	call CreateDiscardPileCardList
 	jr c, .discard_pile_empty
-	call DrawCardListScreenLayout
+	call InitAndDrawCardListScreenLayout
 	call SetDiscardPileScreenTexts
 	ld a, START + A_BUTTON
-	ld [wcbd6], a
-	call Func_55f0
+	ld [wNoItemSelectionMenuKeys], a
+	call DisplayCardList
 	or a
 	ret
 .discard_pile_empty
@@ -2474,9 +2893,9 @@ SetCardListInfoBoxText: ; 5588 (1:5588)
 ; 0x5591
 
 Func_5591: ; 5591 (1:5591)
-	call DrawCardListScreenLayout
-	ld a, $02
-	ld [wcbde], a
+	call InitAndDrawCardListScreenLayout
+	ld a, SELECT_CHECK
+	ld [wCardListItemSelectionMenuType], a
 	ret
 ; 0x559a
 
@@ -2484,7 +2903,7 @@ Func_5591: ; 5591 (1:5591)
 ; Discard Pile card list, including a bottom-right image of the current card.
 ; since this loads the text for the Hand card list screen, SetDiscardPileScreenTexts
 ; is called after this if the screen corresponds to a Discard Pile list.
-DrawCardListScreenLayout: ; 559a (1:559a)
+InitAndDrawCardListScreenLayout: ; 559a (1:559a)
 	xor a
 	ld hl, wSelectedDuelSubMenuItem
 	ld [hli], a
@@ -2493,9 +2912,9 @@ DrawCardListScreenLayout: ; 559a (1:559a)
 	ld hl, wcbd8
 	ld [hli], a
 	ld [hl], a
-	ld [wcbde], a
+	ld [wCardListItemSelectionMenuType], a
 	ld a, START
-	ld [wcbd6], a
+	ld [wNoItemSelectionMenuKeys], a
 	ld hl, wCardListInfoBoxText
 	ldtx [hl], PleaseSelectHandText, & $ff
 	inc hl
@@ -2504,7 +2923,11 @@ DrawCardListScreenLayout: ; 559a (1:559a)
 	ldtx [hl], DuelistHandText, & $ff
 	inc hl
 	ldtx [hl], DuelistHandText, >> 8
-.draw
+; fallthrough
+
+; same as InitAndDrawCardListScreenLayout, except that variables like wSelectedDuelSubMenuItem,
+; wNoItemSelectionMenuKeys, wCardListInfoBoxText, wCardListHeaderText, etc already set by caller.
+DrawCardListScreenLayout:
 	call ZeroObjectPositionsAndToggleOAMCopy
 	call EmptyScreen
 	call LoadSymbolsFont
@@ -2529,11 +2952,22 @@ DrawCardListScreenLayout: ; 559a (1:559a)
 	ret
 ; 0x55f0
 
-Func_55f0: ; 55f0 (1:55f0)
+; displays a list of cards and handles input in order to navigate through the list,
+; select a card, open a card page...
+; input:
+   ; - text IDs at wCardListInfoBoxText and wCardListHeaderText
+   ; - $ff-terminated list of cards to display at wDuelTempList
+   ; - wSelectedDuelSubMenuItem (initial item) and wSelectedDuelSubMenuScrollOffset
+   ;   (initial page scroll offset). Usually both 0 to begin with the first card.
+; returns carry if B is pressed to exit the card list screen, or the selected
+; card at hTempCardIndex_ff98 and at a.
+DisplayCardList: ; 55f0 (1:55f0)
 	call DrawNarrowTextBox
-	call Func_56a0
-.asm_55f6
-	call CountCardsInDuelTempList ; list length
+	call PrintCardListHeaderAndInfoBoxTexts
+.reload_list
+	; get the list length
+	call CountCardsInDuelTempList
+	; get the position and scroll within the list
 	ld hl, wSelectedDuelSubMenuItem
 	ld e, [hl] ; initial item (in the visible page)
 	inc hl
@@ -2542,35 +2976,41 @@ Func_55f0: ; 55f0 (1:55f0)
 	call PrintCardListItems
 	call LoadSelectedCardGfx
 	call EnableLCD
-.asm_560b
+.wait_button
 	call DoFrame
 	call Func_5690
 	call HandleCardListInput
-	jr nc, .asm_560b
+	jr nc, .wait_button
+	; refresh the position of the last checked card of the list, so that
+	; the cursor points to said card when the list is reloaded
 	ld hl, wSelectedDuelSubMenuItem
 	ld [hl], e
 	inc hl
 	ld [hl], d
-	ldh a, [hButtonsPressed]
+	ldh a, [hKeysPressed]
 	ld b, a
 	bit SELECT_F, b
-	jr nz, .asm_563b
+	jr nz, .select_pressed
 	bit B_BUTTON_F, b
-	jr nz, .asm_568c
-	ld a, [wcbd6]
+	jr nz, .b_pressed
+	ld a, [wNoItemSelectionMenuKeys]
 	and b
-	jr nz, .asm_5654
+	jr nz, .open_card_page
+	; display the item selection menu (PLAY|CHECK or SELECT|CHECK) for the selected card
+	; open the card page if CHECK is selected
 	ldh a, [hCurMenuItem]
 	call GetCardInDuelTempList_OnlyDeckIndex
-	call $56c2
-	jr c, Func_55f0
+	call CardListItemSelectionMenu
+	; jump back if B pressed to exit the item selection menu
+	jr c, DisplayCardList
 	ldh a, [hTempCardIndex_ff98]
 	or a
 	ret
-.asm_563b
+.select_pressed
+	; sort cards by ID if SELECT is pressed and return to the first item
 	ld a, [wSortCardListByID]
 	or a
-	jr nz, .asm_560b
+	jr nz, .wait_button
 	call SortCardsInDuelTempListByID
 	xor a
 	ld hl, wSelectedDuelSubMenuItem
@@ -2579,58 +3019,67 @@ Func_55f0: ; 55f0 (1:55f0)
 	ld a, 1
 	ld [wSortCardListByID], a
 	call EraseCursor
-	jr .asm_55f6
-.asm_5654
+	jr .reload_list
+.open_card_page
+	; open the card page directly, without an item selection menu
+	; in this mode, D_UP and D_DOWN can be used to open the card page
+	; of the card above and below the current card
 	ldh a, [hCurMenuItem]
 	call GetCardInDuelTempList
 	call LoadCardDataToBuffer1_FromDeckIndex
-	call Func_5762
-	ldh a, [hButtonsPressed2]
+	call OpenCardPage_FromCheckHandOrDiscardPile
+	ldh a, [hDPadHeld]
 	bit D_UP_F, a
-	jr nz, .asm_566f
+	jr nz, .up_pressed
 	bit D_DOWN_F, a
-	jr nz, .asm_5677
-	call DrawCardListScreenLayout.draw
-	jp Func_55f0
-.asm_566f
+	jr nz, .down_pressed
+	; if B pressed, exit card page and reload the card list
+	call DrawCardListScreenLayout
+	jp DisplayCardList
+.up_pressed
 	ldh a, [hCurMenuItem]
 	or a
-	jr z, .asm_5654
+	jr z, .open_card_page ; if can't go up, reload card page of current card
 	dec a
-	jr .asm_5681
-.asm_5677
+	jr .move_to_another_card
+.down_pressed
 	call CountCardsInDuelTempList
 	ld b, a
 	ldh a, [hCurMenuItem]
 	inc a
 	cp b
-	jr nc, .asm_5654
-.asm_5681
+	jr nc, .open_card_page ; if can't go down, reload card page of current card
+.move_to_another_card
+	; update hCurMenuItem, and wSelectedDuelSubMenuScrollOffset.
+	; this means that when navigating up/down through card pages, the page is
+	; scrolled to reflect the movement, rather than the cursor going up/down.
 	ldh [hCurMenuItem], a
 	ld hl, wSelectedDuelSubMenuItem
 	ld [hl], $00
 	inc hl
 	ld [hl], a
-	jr .asm_5654
-.asm_568c
+	jr .open_card_page
+.b_pressed
 	ldh a, [hCurMenuItem]
 	scf
 	ret
 ; 0x5690
 
 Func_5690: ; 5690 (1:5690)
-	ldh a, [hButtonsPressed2]
+	ldh a, [hDPadHeld]
 	and D_PAD
 	ret z
 	ld a, $01
 	ldh [hffb0], a
-	call Func_56a0
+	call PrintCardListHeaderAndInfoBoxTexts
 	xor a
 	ldh [hffb0], a
 	ret
 ; 0x56a0
 
-Func_56a0: ; 56a0 (1:56a0)
+; prints the text ID at wCardListHeaderText at 1,1
+; and the text ID at wCardListInfoBoxText at 1,14
+PrintCardListHeaderAndInfoBoxTexts: ; 56a0 (1:56a0)
 	lb de, 1, 14
 	call AdjustCoordinatesForBGScroll
 	call InitTextPrinting
@@ -2649,9 +3098,58 @@ Func_56a0: ; 56a0 (1:56a0)
 	ret
 ; 0x56c2
 
-	INCROM $56c2,  $5710
+; display the SELECT|CHECK or PLAY|CHECK menu when a card of a list is selected
+; and handle input. return carry if b is pressed.
+; input: wCardListItemSelectionMenuType
+CardListItemSelectionMenu: ; 56c2 (1:56c2)
+	ld a, [wCardListItemSelectionMenuType]
+	or a
+	ret z
+	ldtx hl, SelectCheckText
+	ld a, [wCardListItemSelectionMenuType]
+	cp PLAY_CHECK
+	jr nz, .got_text
+	ldh a, [hTempCardIndex_ff98]
+	call LoadCardDataToBuffer1_FromDeckIndex
+	ldtx hl, PlayCheck2Text ; identical to PlayCheck1Text
+	ld a, [wLoadedCard1Type]
+	cp TYPE_TRAINER
+	jr nz, .got_text
+	ldtx hl, PlayCheck1Text
+.got_text
+	call DrawNarrowTextBox_PrintTextNoDelay
+	ld hl, ItemSelectionMenuParamenters
+	xor a
+	call InitializeMenuParameters
+.wait_a_or_b
+	call DoFrame
+	call HandleMenuInput
+	jr nc, .wait_a_or_b
+	cp -1
+	jr z, .b_pressed
+	; A pressed
+	or a
+	ret z
+	; CHECK option selected: open the card page
+	ldh a, [hTempCardIndex_ff98]
+	call LoadCardDataToBuffer1_FromDeckIndex
+	call OpenCardPage_FromHand
+	call DrawCardListScreenLayout
+.b_pressed
+	scf
+	ret
+; 0x5708
+
+ItemSelectionMenuParamenters ; 5708 (1:5708)
+	db 1, 14 ; corsor x, cursor y
+	db 2 ; y displacement between items
+	db 2 ; number of items
+	db SYM_CURSOR_R ; cursor tile number
+	db SYM_SPACE ; tile behind cursor
+	dw $0000 ; function pointer if non-0
+; 0x5710
 
-CardListParameters: ; 5710 (1;5710)
+CardListParameters: ; 5710 (1:5710)
 	db 1, 3 ; 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
@@ -2661,15 +3159,18 @@ CardListParameters: ; 5710 (1;5710)
 	dw CardListFunction ; function pointer if non-0
 ; 0x5719
 
+; return carry if any of the buttons is pressed, and load the graphics
+; of the card pointed to by the cursor whenever a d-pad key is released.
+; also return $ff unto hCurMenuItem if B is pressed.
 CardListFunction: ; 5719 (1:5719)
-	ldh a, [hButtonsPressed]
+	ldh a, [hKeysPressed]
 	bit B_BUTTON_F, a
 	jr nz, .exit
 	and A_BUTTON | SELECT | START
 	jr nz, .action_button
-	ldh a, [hButtonsReleased]
+	ldh a, [hKeysReleased]
 	and D_PAD
-	jr nz, .reload_card_image ; jump if the D_PAD button was released this frame
+	jr nz, .reload_card_image ; jump if the D_PAD key was released this frame
 	ret
 .exit
 	ld a, $ff
@@ -2719,29 +3220,43 @@ Func_574a: ; 574a (1:574a)
 	ret
 ; 0x5762
 
-Func_5762: ; 5762 (1:5762)
+; draw the card page of the card at wLoadedCard1 and listen for input
+; in order to switch the page or to exit.
+; triggered by checking a hand card or a discard pile card in the Check menu.
+; D_UP and D_DOWN exit the card page allowing the caller to load the card page
+; of the card above or below in the list.
+OpenCardPage_FromCheckHandOrDiscardPile: ; 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 [wCardPageExitKeys], a
+	xor a ; CARDPAGETYPE_NOT_PLAY_AREA
+	jr OpenCardPage
+
+; draw the card page of the card at wLoadedCard1 and listen for input
+; in order to switch the page or to exit.
+; triggered by checking an arena card or a bench card in the Check menu.
+OpenCardPage_FromCheckPlayArea: ; 576a (1:576a)
 	ld a, B_BUTTON
-	ld [wcbd7], a
-	ld a, $01
-	jr Func_5779
-
-Func_5773: ; 5773 (1:5773)
+	ld [wCardPageExitKeys], a
+	ld a, CARDPAGETYPE_PLAY_AREA
+	jr OpenCardPage
+
+; draw the card page of the card at wLoadedCard1 and listen for input
+; in order to switch the page or to exit.
+; triggered by checking a card in the Hand menu.
+OpenCardPage_FromHand: ; 5773 (1:5773)
 	ld a, B_BUTTON
-	ld [wcbd7], a
-	xor a
+	ld [wCardPageExitKeys], a
+	xor a ; CARDPAGETYPE_NOT_PLAY_AREA
 ;	fallthrough
 
-Func_5779: ; 5779 (1:5779)
-	ld [wcbd1], a
+; draw the card page of the card at wLoadedCard1 and listen for input
+; in order to switch the page or to exit.
+OpenCardPage: ; 5779 (1:5779)
+	ld [wCardPageType], a
 	call ZeroObjectPositionsAndToggleOAMCopy
 	call EmptyScreen
 	call Func_3b31
+	; load the graphics and display the card image of wLoadedCard1
 	call LoadDuelCardSymbolTiles
 	ld de, v0Tiles1 + $20 tiles
 	call LoadLoaded1CardGfx
@@ -2752,59 +3267,73 @@ Func_5779: ; 5779 (1:5779)
 	call PlaceCardImageOAM
 	lb de, 6, 4
 	call ApplyBGP6OrSGB3ToCardImage
+	; display the initial card page for the card at wLoadedCard1
 	xor a
 	ld [wCardPageNumber], a
-.asm_57a7
-	call Func_5898
-	jr c, .asm_57cc
+.load_next
+	call DisplayFirstOrNextCardPage
+	jr c, .done ; done if trying to advance past the last page with START or A_BUTTON
 	call EnableLCD
-.asm_57af
+.input_loop
 	call DoFrame
-	ldh a, [hButtonsPressed2]
+	ldh a, [hDPadHeld]
 	ld b, a
-	ld a, [wcbd7]
+	ld a, [wCardPageExitKeys]
 	and b
-	jr nz, .asm_57cc
-	ldh a, [hButtonsPressed]
+	jr nz, .done
+	; START and A_BUTTON advance to the next valid card page, but close it
+	; after trying to advance from the last page
+	ldh a, [hKeysPressed]
 	and START | A_BUTTON
-	jr nz, .asm_57a7
-	ldh a, [hButtonsPressed]
+	jr nz, .load_next
+	; D_RIGHT and D_LEFT advance to the next and previous valid card page respectively.
+	; however, unlike START and A_BUTTON, D_RIGHT past the last page goes back to the start.
+	ldh a, [hKeysPressed]
 	and D_RIGHT | D_LEFT
-	jr z, .asm_57af
-	call Func_57cd
-	jr .asm_57af
-.asm_57cc
+	jr z, .input_loop
+	call DisplayCardPageOnLeftOrRightPressed
+	jr .input_loop
+.done
 	ret
 ; 0x57cd
 
-Func_57cd: ; 57cd (1:57cd)
+; display the previous valid card page of the card at wLoadedCard1 if bit D_LEFT_F
+; of a is set, and the first or next valid card page otherwise.
+; DisplayFirstOrNextCardPage and DisplayPreviousCardPage only call DisplayCardPage
+; when GoToFirstOrNextCardPage and GoToPreviousCardPage respectively return nc
+; so the "call c, DisplayCardPage" instructions makes sure the card page switched
+; to is always displayed.
+DisplayCardPageOnLeftOrRightPressed: ; 57cd (1:57cd)
 	bit D_LEFT_F, a
 	jr nz, .left
 ;.right
-	call Func_5898
-	call c, Func_589c
+	call DisplayFirstOrNextCardPage
+	call c, DisplayCardPage
 	ret
 .left
-	call Func_5892
-	call c, Func_589c
+	call DisplayPreviousCardPage
+	call c, DisplayCardPage
 	ret
 ; 0x57df
 
 	INCROM $57df,  $5892
 
-Func_5892: ; 5892 (1:5892)
-	call Func_5911
-	jr nc, Func_589c
+; display the previous valid card page
+DisplayPreviousCardPage: ; 5892 (1:5892)
+	call GoToPreviousCardPage
+	jr nc, DisplayCardPage
 	ret
 
-Func_5898: ; 5898 (1:5898)
-	call Func_58e2
+; display the next valid card page or load the first valid card page if [wCardPageNumber] == 0
+DisplayFirstOrNextCardPage: ; 5898 (1:5898)
+	call GoToFirstOrNextCardPage
 	ret c
 ;	fallthrough
 
-Func_589c: ; 589c (1:589c)
+; display the card page with id at wCardPageNumber of wLoadedCard1
+DisplayCardPage: ; 589c (1:589c)
 	ld a, [wCardPageNumber]
-	ld hl, CardPagePointerTable
+	ld hl, CardPageDisplayPointerTable
 	call JumpToFunctionInTable
 	call EnableLCD
 	or a
@@ -2824,104 +3353,209 @@ LoadSelectedCardGfx: ; 58aa (1:58aa)
 	ret
 ; 0x58c2
 
-CardPagePointerTable: ; 58c2 (1:58c2)
+CardPageDisplayPointerTable: ; 58c2 (1:58c2)
 	dw DrawDuelMainScene
-	dw $5b7d ; CARDPAGE_POKEMON_OVERVIEW
-	dw $5d1f ; CARDPAGE_POKEMON_MOVE1_1
-	dw $5d27 ; CARDPAGE_POKEMON_MOVE1_2
-	dw $5d2f ; CARDPAGE_POKEMON_MOVE2_1
-	dw $5d37 ; CARDPAGE_POKEMON_MOVE2_2
-	dw $5d54 ; CARDPAGE_POKEMON_DESCRIPTION
+	dw DisplayCardPage_PokemonOverview    ; CARDPAGE_POKEMON_OVERVIEW
+	dw DisplayCardPage_PokemonMove1Page1  ; CARDPAGE_POKEMON_MOVE1_1
+	dw DisplayCardPage_PokemonMove1Page2  ; CARDPAGE_POKEMON_MOVE1_2
+	dw DisplayCardPage_PokemonMove2Page1  ; CARDPAGE_POKEMON_MOVE2_1
+	dw DisplayCardPage_PokemonMove2Page2  ; CARDPAGE_POKEMON_MOVE2_2
+	dw DisplayCardPage_PokemonDescription ; CARDPAGE_POKEMON_DESCRIPTION
 	dw DrawDuelMainScene
 	dw DrawDuelMainScene
-	dw $5e28 ; CARDPAGE_ENERGY
-	dw $5e28 ; CARDPAGE_ENERGY + 1
+	dw DisplayCardPage_Energy ; CARDPAGE_ENERGY
+	dw DisplayCardPage_Energy ; CARDPAGE_ENERGY + 1
 	dw DrawDuelMainScene
 	dw DrawDuelMainScene
-	dw $5e1c ; CARDPAGE_TRAINER_1
-	dw $5e22 ; CARDPAGE_TRAINER_2
+	dw DisplayCardPage_TrainerPage1 ; CARDPAGE_TRAINER_1
+	dw DisplayCardPage_TrainerPage2 ; CARDPAGE_TRAINER_2
 	dw DrawDuelMainScene
 ; 0x58e2
 
-Func_58e2: ; 58e2 (1:58e2)
+; given the current card page at [wCardPageNumber], go to the next valid card page or load
+; the first valid card page of the current card at wLoadedCard1 if [wCardPageNumber] == 0
+GoToFirstOrNextCardPage: ; 58e2 (1:58e2)
 	ld a, [wCardPageNumber]
 	or a
-	jr nz, .asm_58ff
+	jr nz, .advance_page
+	; load the first page for this type of card
 	ld a, [wLoadedCard1Type]
 	ld b, a
 	ld a, CARDPAGE_ENERGY
 	bit TYPE_ENERGY_F, b
-	jr nz, .set_card_page_nc
+	jr nz, .set_initial_page
 	ld a, CARDPAGE_TRAINER_1
 	bit TYPE_TRAINER_F, b
-	jr nz, .set_card_page_nc
+	jr nz, .set_initial_page
 	ld a, CARDPAGE_POKEMON_OVERVIEW
-.set_card_page_nc
+.set_initial_page
 	ld [wCardPageNumber], a
 	or a
 	ret
-.asm_58ff
+.advance_page
 	ld hl, wCardPageNumber
 	inc [hl]
 	ld a, [hl]
-	call Func_5930
-	jr c, .set_card_page_c
+	call SwitchCardPage
+	jr c, .set_card_page
+	; stay in this page if it exists, or skip to previous page if it doesn't
 	or a
 	ret nz
-	jr .asm_58ff
-.set_card_page_c
+	; non-existant page: skip to next
+	jr .advance_page
+.set_card_page
 	ld [wCardPageNumber], a
 	ret
 ; 0x5911
 
-Func_5911: ; 5911 (1:5911)
+; given the current card page at [wCardPageNumber], go to the previous
+; valid card page for the current card at wLoadedCard1
+GoToPreviousCardPage: ; 5911 (1:5911)
 	ld hl, wCardPageNumber
 	dec [hl]
 	ld a, [hl]
-	call Func_5930
-	jr c, .asm_591f
+	call SwitchCardPage
+	jr c, .set_card_page
+	; stay in this page if it exists, or skip to previous page if it doesn't
 	or a
 	ret nz
-	jr Func_5911
-.asm_591f
+	; non-existant page: skip to previous
+	jr GoToPreviousCardPage
+.set_card_page
 	ld [wCardPageNumber], a
-.asm_5922
-	call Func_5930
+.previous_page_loop
+	call SwitchCardPage
 	or a
-	jr nz, .asm_592e
+	jr nz, .stay
 	ld hl, wCardPageNumber
 	dec [hl]
-	jr .asm_5922
-.asm_592e
+	jr .previous_page_loop
+.stay
 	scf
 	ret
 ; 0x5930
 
-Func_5930: ; 5930 (1:5930)
-	ld hl, CardPagePointerTable2
+; check if the card page trying to switch to is valid for the card at wLoadedCard1
+; return with the equivalent to one of these three actions:
+   ; stay in card page trying to switch to (nc, nz)
+   ; change to card page returned in a if D_LEFT/D_RIGHT pressed, or exit if A_BUTTON/START pressed (c)
+   ; non-existant page, so skip to next/previous (nc, z)
+SwitchCardPage: ; 5930 (1:5930)
+	ld hl, CardPageSwitchPointerTable
 	jp JumpToFunctionInTable
 ; 0x5936
 
-CardPagePointerTable2: ; 5936 (1:5936)
-	dw $5956
-	dw $595a ; CARDPAGE_POKEMON_OVERVIEW
-	dw $595e ; CARDPAGE_POKEMON_MOVE1_1
-	dw $5963 ; CARDPAGE_POKEMON_MOVE1_2
-	dw $5968 ; CARDPAGE_POKEMON_MOVE2_1
-	dw $596d ; CARDPAGE_POKEMON_MOVE2_2
-	dw $595a ; CARDPAGE_POKEMON_DESCRIPTION
-	dw $5973
-	dw $5977
-	dw $597b ; CARDPAGE_ENERGY
-	dw $597f ; CARDPAGE_ENERGY + 1
-	dw $5984
-	dw $5988
-	dw $597b ; CARDPAGE_TRAINER_1
-	dw $597f ; CARDPAGE_TRAINER_2
-	dw $598c
+CardPageSwitchPointerTable: ; 5936 (1:5936)
+	dw CardPageSwitch_00
+	dw CardPageSwitch_PokemonOverviewOrDescription ; CARDPAGE_POKEMON_OVERVIEW
+	dw CardPageSwitch_PokemonMove1Page1 ; CARDPAGE_POKEMON_MOVE1_1
+	dw CardPageSwitch_PokemonMove1Page2 ; CARDPAGE_POKEMON_MOVE1_2
+	dw CardPageSwitch_PokemonMove2Page1 ; CARDPAGE_POKEMON_MOVE2_1
+	dw CardPageSwitch_PokemonMove2Page2 ; CARDPAGE_POKEMON_MOVE2_2
+	dw CardPageSwitch_PokemonOverviewOrDescription ; CARDPAGE_POKEMON_DESCRIPTION
+	dw CardPageSwitch_PokemonEnd
+	dw CardPageSwitch_08
+	dw CardPageSwitch_EnergyOrTrainerPage1 ; CARDPAGE_ENERGY
+	dw CardPageSwitch_TrainerPage2 ; CARDPAGE_ENERGY + 1
+	dw CardPageSwitch_EnergyEnd
+	dw CardPageSwitch_0c
+	dw CardPageSwitch_EnergyOrTrainerPage1 ; CARDPAGE_TRAINER_1
+	dw CardPageSwitch_TrainerPage2 ; CARDPAGE_TRAINER_2
+	dw CardPageSwitch_TrainerEnd
 ; 0x5956
 
-	INCROM $5956,  $5990
+; return with CARDPAGE_POKEMON_DESCRIPTION
+CardPageSwitch_00: ; 5956 (1:5956)
+	ld a, CARDPAGE_POKEMON_DESCRIPTION
+	scf
+	ret
+; 0x595a
+
+; return with current page
+CardPageSwitch_PokemonOverviewOrDescription: ; 595a (1:595a)
+	ld a, $1
+	or a
+	ret ; nz
+; 0x595e
+
+; return with current page if [wLoadedCard1Move1Name] non-0
+; (if card has at least one move)
+CardPageSwitch_PokemonMove1Page1: ; 595e (1:595e)
+	ld hl, wLoadedCard1Move1Name
+	jr CheckCardPageExists
+
+; return with current page if [wLoadedCard1Move1Description + 2] non-0
+; (if card's first move has a two-page description)
+CardPageSwitch_PokemonMove1Page2: ; 5963 (1:5963)
+	ld hl, wLoadedCard1Move1Description + 2
+	jr CheckCardPageExists
+
+; return with current page if [wLoadedCard1Move2Name] non-0
+; (if card has two moves)
+CardPageSwitch_PokemonMove2Page1: ; 5968 (1:5968)
+	ld hl, wLoadedCard1Move2Name
+	jr CheckCardPageExists
+
+; return with current page if [wLoadedCard1Move1Description + 2] non-0
+; (if card's second move has a two-page description)
+CardPageSwitch_PokemonMove2Page2: ; 596d (1:596d)
+	ld hl, wLoadedCard1Move2Description + 2
+;	fallthrough
+
+CheckCardPageExists: ; 5970 (1:5970)
+	ld a, [hli]
+	or [hl]
+	ret
+; 0x5973
+
+; return with CARDPAGE_POKEMON_OVERVIEW
+CardPageSwitch_PokemonEnd: ; 5973 (1:5973)
+	ld a, CARDPAGE_POKEMON_OVERVIEW
+	scf
+	ret
+; 0x5977
+
+; return with CARDPAGE_ENERGY + 1
+CardPageSwitch_08: ; 5977 (1:5977)
+	ld a, CARDPAGE_ENERGY + 1
+	scf
+	ret
+; 0x597b
+
+; return with current page
+CardPageSwitch_EnergyOrTrainerPage1: ; 597b (1:597b)
+	ld a, $1
+	or a
+	ret ; nz
+; 0x597f
+
+; return with current page if [wLoadedCard1NonPokemonDescription + 2] non-0
+; (if this trainer card has a two-page description)
+CardPageSwitch_TrainerPage2: ; 597f (1:597f)
+	ld hl, wLoadedCard1NonPokemonDescription + 2
+	jr CheckCardPageExists
+; 0x5984
+
+; return with CARDPAGE_ENERGY
+CardPageSwitch_EnergyEnd: ; 5984 (1:5984)
+	ld a, CARDPAGE_ENERGY
+	scf
+	ret
+; 0x5988
+
+; return with CARDPAGE_TRAINER_2
+CardPageSwitch_0c: ; 5988 (1:5988)
+	ld a, CARDPAGE_TRAINER_2
+	scf
+	ret
+; 0x598c
+
+; return with CARDPAGE_TRAINER_1
+CardPageSwitch_TrainerEnd: ; 598c (1:598c)
+	ld a, CARDPAGE_TRAINER_1
+	scf
+	ret
+; 0x5990
 
 ZeroObjectPositionsAndToggleOAMCopy: ; 5990 (1:5990)
 	call ZeroObjectPositions
@@ -3061,7 +3695,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 +3837,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 +3851,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
@@ -3286,12 +3920,500 @@ JPWriteByteToBGMap0: ; 5b7a (1:5b7a)
 	jp WriteByteToBGMap0
 ; 0x5b7d
 
-	INCROM $5b7d, $5c33
+DisplayCardPage_PokemonOverview: ; 5b7d (1:5b7d)
+	ld a, [wCardPageType]
+	or a ; CARDPAGETYPE_NOT_PLAY_AREA
+	jr nz, .play_area_card_page
+
+; CARDPAGETYPE_NOT_PLAY_AREA
+	; print surrounding box, card name at 5,1, type, set 2, and rarity
+	call PrintPokemonCardPageGenericInformation
+	; print fixed text and draw the card symbol associated to its TYPE_*
+	ld hl, CardPageRetreatWRTextData
+	call PlaceTextItems
+	ld hl, CardPageLvHPNoTextTileData
+	call WriteDataBlocksToBGMap0
+	lb de, 3, 2
+	call DrawCardSymbol
+	; print pre-evolution's name (if any)
+	ld a, [wLoadedCard1Stage]
+	or a
+	jr z, .basic
+	ld hl, wLoadedCard1PreEvoName
+	lb de, 1, 3
+	call ProcessTextFromPointerToID_InitTextPrinting
+.basic
+	; print card level and maximum HP
+	lb bc, 12, 2
+	ld a, [wLoadedCard1Level]
+	call WriteTwoDigitNumberInTxSymbolFormat
+	lb bc, 16, 2
+	ld a, [wLoadedCard1HP]
+	call WriteTwoByteNumberInTxSymbolFormat
+	jr .print_numbers_and_energies
+
+; CARDPAGETYPE_PLAY_AREA
+.play_area_card_page
+	; draw the surrounding box, and print fixed text
+	call DrawCardPageSurroundingBox
+	call LoadDuelCheckPokemonScreenTiles
+	ld hl, CardPageRetreatWRTextData
+	call PlaceTextItems
+	ld hl, CardPageNoTextTileData
+	call WriteDataBlocksToBGMap0
+	ld a, 1
+	ld [wCurPlayAreaY], a
+	; print set 2 icon and rarity symbol at fixed positions
+	call DrawCardPageSet2AndRarityIcons
+	; print (Y coord at [wCurPlayAreaY]) card name, level, type, energies, HP, location...
+	call PrintPlayAreaCardInformationAndLocation
+
+; common for both card page types
+.print_numbers_and_energies
+	; print Pokedex number in the bottom right corner (16,16)
+	lb bc, 16, 16
+	ld a, [wLoadedCard1PokedexNumber]
+	call WriteTwoByteNumberInTxSymbolFormat
+	; print the name, damage, and energy cost of each move and/or Pokemon power that exists
+	; first move at 5,10 and second at 5,12
+	lb bc, 5, 10
+	ld e, c
+	ld hl, wLoadedCard1Move1Name
+	call PrintMoveOrPkmnPowerInformation
+	inc c
+	inc c ; 12
+	ld e, c
+	ld hl, wLoadedCard1Move2Name
+	call PrintMoveOrPkmnPowerInformation
+	; print the retreat cost (some amount of colorless energies) at 8,14
+	inc c
+	inc c ; 14
+	ld b, 8
+	ld a, [wLoadedCard1RetreatCost]
+	ld e, a
+	inc e
+.retreat_cost_loop
+	dec e
+	jr z, .retreat_cost_done
+	ld a, SYM_COLORLESS
+	call JPWriteByteToBGMap0
+	inc b
+	jr .retreat_cost_loop
+.retreat_cost_done
+	; print the colors (energies) of the weakness(es) and resistance(s)
+	inc c ; 15
+	ld a, [wCardPageType]
+	or a
+	jr z, .wr_from_loaded_card
+	ld a, [wCurPlayAreaSlot]
+	or a
+	jr nz, .wr_from_loaded_card
+	call GetArenaCardWeakness
+	ld d, a
+	call GetArenaCardResistance
+	ld e, a
+	jr .got_wr
+.wr_from_loaded_card
+	ld a, [wLoadedCard1Weakness]
+	ld d, a
+	ld a, [wLoadedCard1Resistance]
+	ld e, a
+.got_wr
+	ld a, d
+	ld b, 8
+	call PrintCardPageWeaknessesOrResistances
+	inc c ; 16
+	ld a, e
+	call PrintCardPageWeaknessesOrResistances
+	ret
+; 0x5c33
+
+; displays the name, damage, and energy cost of a move or Pokemon power.
+; used in the Attack menu and in the card page of a Pokemon.
+; input:
+   ; hl: pointer to move 1 name in a move_data_struct (which can be inside at card_data_struct)
+   ; e: Y coordinate to start printing the data at
+PrintMoveOrPkmnPowerInformation: ; 5c33 (1:5c33)
+	ld a, [hli]
+	or [hl]
+	ret z
+	push bc
+	push hl
+	dec hl
+	; print text ID pointed to by hl at 7,e
+	ld d, 7
+	call ProcessTextFromPointerToID_InitTextPrinting
+	pop hl
+	inc hl
+	inc hl
+	ld a, [wCardPageNumber]
+	or a
+	jr nz, .print_damage
+	dec hl
+	ld a, [hli]
+	or [hl]
+	jr z, .print_damage
+	; if in Attack menu and move 1 description exists, print at 18,e:
+	ld b, 18
+	ld c, e
+	ld a, SYM_MOVE_DESCR
+	call WriteByteToBGMap0
+.print_damage
+	inc hl
+	inc hl
+	inc hl
+	push hl
+	ld a, [hl]
+	or a
+	jr z, .print_category
+	; print move damage at 15,(e+1) if non-0
+	ld b, 15 ; unless damage has three digits, this is effectively 16
+	ld c, e
+	inc c
+	call WriteTwoByteNumberInTxSymbolFormat
+.print_category
+	pop hl
+	inc hl
+	ld a, [hl]
+	and $ff ^ RESIDUAL
+	jr z, .print_energy_cost
+	cp POKEMON_POWER
+	jr z, .print_pokemon_power
+	; register a is DAMAGE_PLUS, DAMAGE_MINUS, or DAMAGE_X
+	; print the damage modifier (+, -, x) at 18,(e+1) (after the damage value)
+	add SYM_PLUS - DAMAGE_PLUS
+	ld b, 18
+	ld c, e
+	inc c
+	call WriteByteToBGMap0
+	jr .print_energy_cost
+.print_energy_cost
+	ld bc, CARD_DATA_MOVE1_ENERGY_COST - CARD_DATA_MOVE1_CATEGORY
+	add hl, bc
+	ld c, e
+	ld b, 2 ; bc = 2, e
+	lb de, NUM_TYPES / 2, 0
+.energy_loop
+	ld a, [hl]
+	swap a
+	call PrintEnergiesOfColor
+	ld a, [hli]
+	call PrintEnergiesOfColor
+	dec d
+	jr nz, .energy_loop
+	pop bc
+	ret
+.print_pokemon_power
+	; print "PKMN PWR" at 2,e
+	ld d, 2
+	ldtx hl, PKMNPWRText
+	call InitTextPrinting_ProcessTextFromID
+	pop bc
+	ret
+; 0x5c9c
+
+; print the number of energies required of color (type) e, and return e ++ (next color).
+; the requirement of the current color is provided as input in the lower nybble of a.
+PrintEnergiesOfColor: ; 5c9c (1:5c9c)
+	inc e
+	and $0f
+	ret z
+	push de
+	ld d, a
+.print_energies_loop
+	ld a, e
+	call JPWriteByteToBGMap0
+	inc b
+	dec d
+	jr nz, .print_energies_loop
+	pop de
+	ret
+; 0x5cac
+
+; print the weaknesses or resistances of a Pokemon card, given in a, at b,c
+PrintCardPageWeaknessesOrResistances: ; 5cac (1:5cac)
+	push bc
+	push de
+	ld d, a
+	xor a ; FIRE
+.loop
+	; each WR_* constant is a different bit. rotate the value to find out
+	; which bits are set and therefore which WR_* values are active.
+	; a is kept updated with the equivalent TYPE_* constant.
+	inc a
+	cp 8
+	jr nc, .done
+	rl d
+	jr nc, .loop
+	push af
+	call JPWriteByteToBGMap0
+	inc b
+	pop af
+	jr .loop
+.done
+	pop de
+	pop bc
+	ret
+; 0x5cc4
+
+; prints surrounding box, card name at 5,1, type, set 2, and rarity.
+; used in all CARDPAGE_POKEMON_* and MOVEPAGE_*, except in
+; CARDPAGE_POKEMON_OVERVIEW when wCardPageType is CARDPAGETYPE_PLAY_AREA.
+PrintPokemonCardPageGenericInformation: ; 5cc4 (1:5cc4)
+	call DrawCardPageSurroundingBox
+	lb de, 5, 1
+	ld hl, wLoadedCard1Name
+	call ProcessTextFromPointerToID_InitTextPrinting
+	ld a, [wCardPageType]
+	or a
+	jr z, .from_loaded_card
+	ld a, [wCurPlayAreaSlot]
+	call GetPlayAreaCardColor
+	jr .got_color
+.from_loaded_card
+	ld a, [wLoadedCard1Type]
+.got_color
+	lb bc, 18, 1
+	inc a
+	call JPWriteByteToBGMap0
+	call DrawCardPageSet2AndRarityIcons
+	ret
+; 0x5cec
+
+; draws the 20x18 surrounding box and also colorizes the card image
+DrawCardPageSurroundingBox: ; 5cec (1:5cec)
+	ld hl, wTextBoxFrameType
+	set 7, [hl] ; colorize textbox border also on SGB (with SGB1)
+	push hl
+	lb de, 0, 0
+	lb bc, 20, 18
+	call DrawRegularTextBox
+	pop hl
+	res 7, [hl]
+	lb de, 6, 4
+	call ApplyBGP6OrSGB3ToCardImage
+	ret
+; 0x5d05
+
+CardPageRetreatWRTextData: ; 5d05 (1:5d05)
+	textitem 1, 14, RetreatCostText
+	textitem 1, 15, WeaknessText
+	textitem 1, 16, ResistanceText
+	db $ff
+
+CardPageLvHPNoTextTileData: ; 5d12 (1:5d12)
+	db 11,  2, SYM_Lv, 0
+	db 15,  2, SYM_HP, 0
+;	continues to CardPageNoTextTileData
+
+CardPageNoTextTileData: ; 5d1a (1:5d1a)
+	db 15, 16, SYM_No, 0
+	db $ff
+
+DisplayCardPage_PokemonMove1Page1: ; 5d1f (1:5d1f)
+	ld hl, wLoadedCard1Move1Name
+	ld de, wLoadedCard1Move1Description
+	jr DisplayPokemonMoveCardPage
+
+DisplayCardPage_PokemonMove1Page2: ; 5d27 (1:5d27)
+	ld hl, wLoadedCard1Move1Name
+	ld de, wLoadedCard1Move1Description + 2
+	jr DisplayPokemonMoveCardPage
+
+DisplayCardPage_PokemonMove2Page1: ; 5d2f (1:5d2f)
+	ld hl, wLoadedCard1Move2Name
+	ld de, wLoadedCard1Move2Description
+	jr DisplayPokemonMoveCardPage
+
+DisplayCardPage_PokemonMove2Page2: ; 5d37 (1:5d37)
+	ld hl, wLoadedCard1Move2Name
+	ld de, wLoadedCard1Move2Description + 2
+;	fallthrough
+
+; input:
+   ; hl = address of the move's name (text id)
+   ; de = address of the move's description (either first or second text id)
+DisplayPokemonMoveCardPage: ; 5d3d (1:5d3d)
+	push de
+	push hl
+	; print surrounding box, card name at 5,1, type, set 2, and rarity
+	call PrintPokemonCardPageGenericInformation
+	; print name, damage, and energy cost of move or Pokemon power starting at line 2
+	ld e, 2
+	pop hl
+	call PrintMoveOrPkmnPowerInformation
+	pop hl
+;	fallthrough
+
+; print, if non-null, the description of the trainer card, energy card, move,
+; or Pokemon power, given as a pointer to text id in hl, starting from 1,11
+PrintMoveOrNonPokemonCardDescription: ; 5d49 (1:5d49)
+	ld a, [hli]
+	or [hl]
+	ret z
+	dec hl
+	lb de, 1, 11
+	call PrintMoveOrCardDescription
+	ret
+; 0x5d54
+
+DisplayCardPage_PokemonDescription: ; 5d54 (1:5d54)
+	; print surrounding box, card name at 5,1, type, set 2, and rarity
+	call PrintPokemonCardPageGenericInformation
+	call LoadDuelCardSymbolTiles2
+	; print "LENGTH", "WEIGHT", "Lv", and "HP" where it corresponds in the page
+	ld hl, CardPageLengthWeightTextData
+	call PlaceTextItems
+	ld hl, CardPageLvHPTextTileData
+	call WriteDataBlocksToBGMap0
+	; draw the card symbol associated to its TYPE_* at 3,2
+	lb de, 3, 2
+	call DrawCardSymbol
+	; print the Level and HP numbers at 12,2 and 16,2 respectively
+	lb bc, 12, 2
+	ld a, [wLoadedCard1Level]
+	call WriteTwoDigitNumberInTxSymbolFormat
+	lb bc, 16, 2
+	ld a, [wLoadedCard1HP]
+	call WriteTwoByteNumberInTxSymbolFormat
+	; print the Pokemon's category at 1,10 (just above the length and weight texts)
+	lb de, 1, 10
+	ld hl, wLoadedCard1Category
+	call ProcessTextFromPointerToID_InitTextPrinting
+	ld a, TX_KATAKANA
+	call ProcessSpecialTextCharacter
+	ldtx hl, PokemonText
+	call ProcessTextFromID
+	; print the length and weight values at 5,11 and 5,12 respectively
+	lb bc, 5, 11
+	ld hl, wLoadedCard1Length
+	ld a, [hli]
+	ld l, [hl]
+	ld h, a
+	call PrintPokemonCardLength
+	lb bc, 5, 12
+	ld hl, wLoadedCard1Weight
+	ld a, [hli]
+	ld h, [hl]
+	ld l, a
+	call PrintPokemonCardWeight
+	ldtx hl, LbsText
+	call InitTextPrinting_ProcessTextFromID
+	; print the card's description without line separation
+	call SetNoLineSeparation
+	ld hl, wLoadedCard1Description
+	ld a, [hli]
+	ld h, [hl]
+	ld l, a
+	call CountLinesOfTextFromID
+	lb de, 1, 13
+	cp 4
+	jr nc, .print_description
+	inc e ; move a line down, as the description is short enough to fit in three lines
+.print_description
+	ld a, 19 ; line length
+	call InitTextPrintingInTextbox
+	ld hl, wLoadedCard1Description
+	call ProcessTextFromPointerToID
+	call SetOneLineSeparation
+	ret
+; 0x5dd3
+
+; given a card rarity constant in a, and CardRarityTextIDs in hl,
+; print the text character associated to it at d,e
+PrintCardPageRarityIcon: ; 5dd3 (1:5dd3)
+	inc a
+	add a
+	ld c, a
+	ld b, $00
+	add hl, bc
+	call ProcessTextFromPointerToID_InitTextPrinting
+	ret
+; 0x5ddd
+
+; prints the card's set 2 icon and the full width text character of the card's rarity
+DrawCardPageSet2AndRarityIcons: ; 5ddd (1:5ddd)
+	ld a, [wLoadedCard1Set]
+	call LoadCardSet2Tiles
+	jr c, .icon_done
+	; draw the 2x2 set 2 icon of this card
+	ld a, $fc
+	lb hl, 1, 2
+	lb bc, 2, 2
+	lb de, 15, 8
+	call FillRectangle
+.icon_done
+	lb de, 18, 9
+	ld hl, CardRarityTextIDs
+	ld a, [wLoadedCard1Rarity]
+	cp PROMOSTAR
+	call nz, PrintCardPageRarityIcon
+	ret
+; 0x5e02
+
+CardPageLengthWeightTextData: ; 5e02 (1:5e02)
+	textitem 1, 11, LengthText
+	textitem 1, 12, WeightText
+	db $ff
+
+CardPageLvHPTextTileData: ; 5e0b (1:5e0b)
+	db 11, 2, SYM_Lv, 0
+	db 15, 2, SYM_HP, 0
+	db $ff
+
+CardRarityTextIDs: ; 5e14 (1:5e14)
+	tx PromostarRarityText ; PROMOSTAR (unused)
+	tx CircleRarityText    ; CIRCLE
+	tx DiamondRarityText   ; DIAMOND
+	tx StarRarityText      ; STAR
+; 0x5e1c
 
-Func_5c33: ; 5c33 (1:5c33
-	INCROM $5c33, $5e5f
+DisplayCardPage_TrainerPage1: ; 5e1c (1:5e1c)
+	xor a ; HEADER_TRAINER
+	ld hl, wLoadedCard1NonPokemonDescription
+	jr DisplayEnergyOrTrainerCardPage
 
-; display the card details of the card index in wLoadedCard1
+DisplayCardPage_TrainerPage2: ; 5e22 (1:5e22)
+	xor a ; HEADER_TRAINER
+	ld hl, wLoadedCard1NonPokemonDescription + 2
+	jr DisplayEnergyOrTrainerCardPage
+
+DisplayCardPage_Energy: ; 5e28 (1:5e28)
+	ld a, HEADER_ENERGY
+	ld hl, wLoadedCard1NonPokemonDescription
+;	fallthrough
+
+; input:
+   ; a = HEADER_ENERGY or HEADER_TRAINER
+   ; hl = address of the card's description (text id)
+DisplayEnergyOrTrainerCardPage: ; 5e2d (1:5e2d)
+	push hl
+	call LoadCardTypeHeaderTiles
+	; draw surrounding box
+	lb de, 0, 0
+	lb bc, 20, 18
+	call DrawRegularTextBox
+	; print the card's name at 4,3
+	lb de, 4, 3
+	ld hl, wLoadedCard1Name
+	call ProcessTextFromPointerToID_InitTextPrinting
+	; colorize the card image
+	lb de, 6, 4
+	call ApplyBGP6OrSGB3ToCardImage
+	; display the card type header
+	ld a, $e0
+	lb hl, 1, 8
+	lb de, 6, 1
+	lb bc, 8, 2
+	call FillRectangle
+	; print the set 2 icon and rarity symbol of the card
+	call DrawCardPageSet2AndRarityIcons
+	pop hl
+	call PrintMoveOrNonPokemonCardDescription
+	ret
+; 0x5e5f
+
+; display the card details of the card in wLoadedCard1
 ; print the text at hl
 _DisplayCardDetailScreen: ; 5e5f (1:5e5f)
 	push hl
@@ -3313,8 +4435,8 @@ DrawLargePictureOfCard: ; 5e75 (1:5e75)
 	call EmptyScreen
 	call LoadSymbolsFont
 	call SetDefaultPalettes
-	ld a, $08
-	ld [wcac2], a
+	ld a, LARGE_CARD_PICTURE
+	ld [wDuelDisplayedScreen], a
 	call LoadCardOrDuelMenuBorderTiles
 	ld e, HEADER_TRAINER
 	ld a, [wLoadedCard1Type]
@@ -3356,19 +4478,124 @@ LargeCardTileData: ; 5eb7 (1:5eb7)
 	db $ff
 ; 0x5f4a
 
-Func_5f4a: ; 5f4a (1:5f4a)
+; print lines of text with no separation between them
+SetNoLineSeparation: ; 5f4a (1:5f4a)
 	ld a, $01
-Func_5f4c: ; 5f4c (1:5f4c)
+;	fallthrough
+
+SetLineSeparation: ; 5f4c (1:5f4c)
 	ld [wLineSeparation], a
 	ret
 ; 0x5f50
 
-Func_5f50: ; 5f50 (1:5f50)
+; separate lines of text by an empty line
+SetOneLineSeparation: ; 5f50 (1:5f50)
 	xor a
-	jr Func_5f4c
+	jr SetLineSeparation
 ; 0x5f53
 
-	INCROM $5f53, $5fd9
+; given a number in hl, print it divided by 10 at b,c, with decimal part
+; separated by a dot (unless it's 0). used to print a Pokemon card's weight.
+PrintPokemonCardWeight: ; 5f53 (1:5f53)
+	push bc
+	ld de, -1
+	ld bc, -10
+.divide_by_10_loop
+	inc de
+	add hl, bc
+	jr c, .divide_by_10_loop
+	ld bc, 10
+	add hl, bc
+	pop bc
+	push hl
+	push bc
+	ld l, e
+	ld h, d
+	call TwoByteNumberToTxSymbol_TrimLeadingZeros_Bank1
+	pop bc
+	pop hl
+	ld a, l
+	ld hl, wStringBuffer + 5
+	or a
+	jr z, .decimal_done
+	ld [hl], SYM_DOT
+	inc hl
+	add SYM_0
+	ld [hli], a
+.decimal_done
+	ld [hl], 0
+	push bc
+	call BCCoordToBGMap0Address
+	ld hl, wStringBuffer
+.find_first_digit_loop
+	ld a, [hli]
+	or a
+	jr z, .find_first_digit_loop
+	dec hl
+	push hl
+	ld b, -1
+.get_number_length_loop
+	inc b
+	ld a, [hli]
+	or a
+	jr nz, .get_number_length_loop
+	pop hl
+	push bc
+	call SafeCopyDataHLtoDE
+	pop bc
+	pop de
+	ld a, b
+	add d
+	ld d, a
+	ret
+; 0x5f9a
+
+; given a number in h and another in l, print them formatted as <l>'<h>" at b,c.
+; used to print the length (feet and inches) of a Pokemon card.
+PrintPokemonCardLength: ; 5f9a (1:5f9a)
+	push hl
+	ld l, h
+	ld h, $00
+	ldtx de, FeetText ; '
+	call .print_feet_or_inches
+	pop hl
+	ld h, $00
+	ldtx de, InchesText ; "
+	call .print_feet_or_inches
+	ret
+
+.print_feet_or_inches
+; keep track how many digits each number consists of in wPokemonLengthPrintOffset,
+; in order to align the rest of the string. the text with id at de
+; is printed after the number.
+	push de
+	push bc
+	call TwoByteNumberToTxSymbol_TrimLeadingZeros_Bank1
+	ld a, b
+	inc a
+	ld [wPokemonLengthPrintOffset], a
+	pop bc
+	push bc
+	push hl
+	call BCCoordToBGMap0Address
+	ld a, [wPokemonLengthPrintOffset]
+	ld b, a
+	pop hl
+	call SafeCopyDataHLtoDE
+	pop bc
+	ld a, [wPokemonLengthPrintOffset]
+	add b
+	ld b, a
+	pop hl
+	push bc
+	ld e, c
+	ld d, b
+	call InitTextPrinting
+	call ProcessTextFromID
+	pop bc
+	inc b
+	ret
+; 0x5fd9
 
 ; return carry if the turn holder has any Pokemon with non-zero HP on the bench.
 ; return how many Pokemon with non-zero HP in b.
@@ -3381,6 +4608,8 @@ HasAlivePokemonOnBench: ; 5fd9 (1:5fd9)
 ; return how many Pokemon with non-zero HP in b.
 HasAlivePokemonInPlayArea: ; 5fdd (1:5fdd)
 	xor a
+;	fallthrough
+
 _HasAlivePokemonInPlayArea: ; 5fde (1:5fde)
 	ld [wExcludeArenaPokemon], a
 	ld b, a
@@ -3414,19 +4643,19 @@ _HasAlivePokemonInPlayArea: ; 5fde (1:5fde)
 
 OpenPlayAreaScreenForViewing: ; 6008 (1:6008)
 	ld a, START + A_BUTTON
-	jr _OpenPlayAreaScreen
+	jr DisplayPlayAreaScreen
 
 OpenPlayAreaScreenForSelection: ; 600c (1:600c)
 	ld a, START
 ;	fallthrough
 
-_OpenPlayAreaScreen: ; 600e (1:600e)
-	ld [wcbd6], a
+DisplayPlayAreaScreen: ; 600e (1:600e)
+	ld [wNoItemSelectionMenuKeys], a
 	ldh a, [hTempCardIndex_ff98]
 	push af
 	ld a, [wcbd3]
 	or a
-	jr nz, .asm_6034
+	jr nz, .skip_ahead
 	xor a
 	ld [wSelectedDuelSubMenuItem], a
 	inc a
@@ -3436,25 +4665,25 @@ _OpenPlayAreaScreen: ; 600e (1:600e)
 	call EmptyScreen
 	call LoadDuelCardSymbolTiles
 	call LoadDuelCheckPokemonScreenTiles
-	call $61c7
+	call PrintPlayAreaCardList
 	call EnableLCD
-.asm_6034
+.skip_ahead
 	ld hl, PlayAreaScreenMenuParameters_ActivePokemonIncluded
 	ld a, [wExcludeArenaPokemon]
 	or a
-	jr z, .asm_6040
+	jr z, .init_menu_params
 	ld hl, PlayAreaScreenMenuParameters_ActivePokemonExcluded
-.asm_6040
+.init_menu_params
 	ld a, [wSelectedDuelSubMenuItem]
 	call InitializeMenuParameters
-	ld a, [wcbc8]
+	ld a, [wNumPlayAreaItems]
 	ld [wNumMenuItems], a
 .asm_604c
 	call DoFrame
-	call $60dd
+	call Func_60dd
 	jr nc, .asm_6061
 	cp $02
-	jp z, $60ac
+	jp z, .asm_60ac
 	pop af
 	ldh [hTempCardIndex_ff98], a
 	ld a, [wcbd4] ; useless
@@ -3466,47 +4695,47 @@ _OpenPlayAreaScreen: ; 600e (1:600e)
 	ld [wSelectedDuelSubMenuItem], a
 	ld a, [wExcludeArenaPokemon]
 	add e
-	ld [wcbc9], a
-	ld a, [wcbd6]
+	ld [wCurPlayAreaSlot], a
+	ld a, [wNoItemSelectionMenuKeys]
 	ld b, a
-	ldh a, [hButtonsPressed]
+	ldh a, [hKeysPressed]
 	and b
 	jr z, .asm_6091
-	ld a, [wcbc9]
+	ld a, [wCurPlayAreaSlot]
 	add DUELVARS_ARENA_CARD
 	call GetTurnDuelistVariable
 	cp -1
 	jr z, .asm_6022
 	call GetCardIDFromDeckIndex
 	call LoadCardDataToBuffer1_FromCardID
-	call Func_576a
+	call OpenCardPage_FromCheckPlayArea
 	jr .asm_6022
 .asm_6091
 	ld a, [wExcludeArenaPokemon]
 	ld c, a
 	ldh a, [hCurMenuItem]
 	add c
-	ldh [hTempPlayAreaLocationOffset_ff9d], a
+	ldh [hTempPlayAreaLocation_ff9d], a
 	ldh a, [hCurMenuItem]
 	cp $ff
 	jr z, .asm_60b5
-	ldh a, [hTempPlayAreaLocationOffset_ff9d]
+	ldh a, [hTempPlayAreaLocation_ff9d]
 	add DUELVARS_ARENA_CARD_HP
 	call GetTurnDuelistVariable
 	or a
 	jr nz, .asm_60ac
-	jr .asm_6034
+	jr .skip_ahead
 .asm_60ac
 	pop af
 	ldh [hTempCardIndex_ff98], a
-	ldh a, [hTempPlayAreaLocationOffset_ff9d]
+	ldh a, [hTempPlayAreaLocation_ff9d]
 	ldh [hCurMenuItem], a
 	or a
 	ret
 .asm_60b5
 	pop af
 	ldh [hTempCardIndex_ff98], a
-	ldh a, [hTempPlayAreaLocationOffset_ff9d]
+	ldh a, [hTempPlayAreaLocation_ff9d]
 	ldh [hCurMenuItem], a
 	scf
 	ret
@@ -3529,7 +4758,7 @@ PlayAreaScreenMenuParameters_ActivePokemonExcluded: ; 60c6 (1:60c6)
 	dw PlayAreaScreenMenuFunction ; function pointer if non-0
 
 PlayAreaScreenMenuFunction: ; 60ce (1:60ce)
-	ldh a, [hButtonsPressed]
+	ldh a, [hKeysPressed]
 	and A_BUTTON | B_BUTTON | START
 	ret z
 	bit B_BUTTON_F, a
@@ -3541,29 +4770,259 @@ PlayAreaScreenMenuFunction: ; 60ce (1:60ce)
 	ret
 ; 0x60dd
 
-	INCROM $60dd, $622a
+Func_60dd: ; 60dd (1:60dd)
+	ld a, [wcbd4]
+	or a
+	ret z
+	ldh a, [hKeysPressed]
+	and SELECT
+	ret z
+	ld a, [wcbd4]
+	cp $02
+	jr z, .asm_6121
+	xor a
+	ld [wCurrentDuelMenuItem], a
+.asm_60f2
+	call DrawDuelMainScene
+	ldtx hl, SelectingBenchPokemonHandExamineBackText
+	call DrawWideTextBox_PrintTextNoDelay
+	call Func_615c
+.asm_60fe
+	call DoFrame
+	ldh a, [hKeysPressed]
+	and A_BUTTON
+	jr nz, .a_pressed
+	call Func_6137
+	call RefreshMenuCursor
+	xor a
+	call Func_6862
+	jr nc, .asm_60fe
+	ldh a, [hKeysPressed]
+	and SELECT
+	jr z, .asm_60f2
+.asm_6119
+	call HasAlivePokemonOnBench
+	ld a, $01
+	ld [wcbd4], a
+.asm_6121
+	scf
+	ret
+.a_pressed
+	ld a, [wCurrentDuelMenuItem]
+	cp 2
+	jr z, .asm_6119
+	or a
+	jr z, .asm_6132
+	call Func_3096
+	jr .asm_60f2
+.asm_6132
+	call Func_434e
+	jr .asm_60f2
+; 0x6137
+
+Func_6137: ; 6137 (1:6137)
+	ldh a, [hDPadHeld]
+	bit 1, a
+	ret nz
+	and D_RIGHT | D_LEFT
+	ret z
+	ld b, a
+	ld a, [wCurrentDuelMenuItem]
+	bit D_LEFT_F, b
+	jr z, .asm_6150
+	dec a
+	bit D_DOWN_F, a
+	jr z, .asm_6156
+	ld a, 2
+	jr .asm_6156
+.asm_6150
+	inc a
+	cp 3
+	jr c, .asm_6156
+	xor a
+.asm_6156
+	ld [wCurrentDuelMenuItem], a
+	call EraseCursor
+;	fallthrough
+
+Func_615c:
+	ld a, [wCurrentDuelMenuItem]
+	ld d, a
+	add a
+	add d
+	add a
+	add 2
+	ld d, a
+	ld e, 16
+	lb bc, SYM_CURSOR_R, SYM_SPACE
+	jp SetCursorParametersForTextBox
+; 0x616e
+
+Func_616e: ; 616e (1:616e)
+	ldh [hTempPlayAreaLocation_ff9d], a
+	call ZeroObjectPositionsAndToggleOAMCopy
+	call EmptyScreen
+	call LoadDuelCardSymbolTiles
+	call LoadDuelCheckPokemonScreenTiles
+	xor a
+	ld [wExcludeArenaPokemon], a
+	call PrintPlayAreaCardList
+	call EnableLCD
+;	fallthrough
+
+Func_6186:
+	ld hl, wCurPlayAreaSlot
+	ldh a, [hTempPlayAreaLocation_ff9d]
+	ld [hli], a
+	ld c, a
+	add a
+	add c
+	ld [hl], a
+	call PrintPlayAreaCardInformationAndLocation
+	ret
+; 0x6194
+
+Func_6194: ; 6194 (1:6194)
+	call Func_6186
+	ld a, [wCurPlayAreaY]
+	ld e, a
+	ld d, 0
+	call SetCursorParametersForTextBox_Default
+	ret
+; 0x61a1
+
+Func_61a1: ; 61a1 (1:61a1)
+	xor a
+	ld [wExcludeArenaPokemon], a
+	ld a, [wDuelDisplayedScreen]
+	cp PLAY_AREA_CARD_LIST
+	ret z
+	call ZeroObjectPositionsAndToggleOAMCopy
+	call EmptyScreen
+	call LoadDuelCardSymbolTiles
+	call LoadDuelCheckPokemonScreenTiles
+	ret
+; 0x61b8
+
+; for each turn holder's play area Pokemon card, print the name, level,
+; face down stage card, color symbol, status symbol (if any), pluspower/defender
+; symbols (if any), attached energies (if any), and HP bar.
+; also print the play area locations (ACT/BPx indicators) for each of the six slots.
+; return the value of wNumPlayAreaItems (as returned from PrintPlayAreaCardList) in a.
+PrintPlayAreaCardList_EnableLCD: ; 61b8 (1:61b8)
+	ld a, PLAY_AREA_CARD_LIST
+	ld [wDuelDisplayedScreen], a
+	call PrintPlayAreaCardList
+	call EnableLCD
+	ld a, [wNumPlayAreaItems]
+	ret
+; 0x61c7
+
+; for each turn holder's play area Pokemon card, print the name, level,
+; face down stage card, color symbol, status symbol (if any), pluspower/defender
+; symbols (if any), attached energies (if any), and HP bar.
+; also print the play area locations (ACT/BPx indicators) for each of the six slots.
+PrintPlayAreaCardList: ; 61c7 (1:61c7)
+	ld a, PLAY_AREA_CARD_LIST
+	ld [wDuelDisplayedScreen], a
+	ld de, wDuelTempList
+	call SetListPointer
+	ld a, DUELVARS_NUMBER_OF_POKEMON_IN_PLAY_AREA
+	call GetTurnDuelistVariable
+	ld c, a
+	ld b, $00
+.print_cards_info_loop
+	; for each Pokemon card in play area, print its information (and location)
+	push hl
+	push bc
+	ld a, b
+	ld [wCurPlayAreaSlot], a
+	ld a, b
+	add a
+	add b
+	ld [wCurPlayAreaY], a
+	ld a, b
+	add DUELVARS_ARENA_CARD
+	call GetTurnDuelistVariable
+	call SetNextElementOfList
+	call PrintPlayAreaCardInformationAndLocation
+	pop bc
+	pop hl
+	inc b
+	dec c
+	jr nz, .print_cards_info_loop
+	push bc
+.print_locations_loop
+	; print all play area location indicators (even if there's no Pokemon card on it)
+	ld a, b
+	cp MAX_PLAY_AREA_POKEMON
+	jr z, .locations_printed
+	ld [wCurPlayAreaSlot], a
+	add a
+	add b
+	ld [wCurPlayAreaY], a
+	push bc
+	call PrintPlayAreaCardLocation
+	pop bc
+	inc b
+	jr .print_locations_loop
+.locations_printed
+	pop bc
+	ld a, b
+	ld [wNumPlayAreaItems], a
+	ld a, [wExcludeArenaPokemon]
+	or a
+	ret z
+	; if wExcludeArenaPokemon is set, decrement [wNumPlayAreaItems] and shift back wDuelTempList
+	dec b
+	ld a, b
+	ld [wNumPlayAreaItems], a
+	ld hl, wDuelTempList + 1
+	ld de, wDuelTempList
+.shift_back_loop
+	ld a, [hli]
+	ld [de], a
+	inc de
+	dec b
+	jr nz, .shift_back_loop
+	ret
+; 0x622a
 
-Func_622a: ; 622a (1:622a)
-	ld a, [wcbc9]
+; print a turn holder's play area Pokemon card's name, level, face down stage card,
+; color symbol, status symbol (if any), pluspower/defender symbols (if any),
+; attached energies (if any), HP bar, and the play area location (ACT/BPx indicator)
+; input:
+   ; wCurPlayAreaSlot: PLAY_AREA_* of the card to display the information of
+   ; wCurPlayAreaY: Y coordinate of where to print the card's information
+; total space occupied is a rectangle of 20x3 tiles
+PrintPlayAreaCardInformationAndLocation: ; 622a (1:622a)
+	ld a, [wCurPlayAreaSlot]
 	add DUELVARS_ARENA_CARD
 	call GetTurnDuelistVariable
 	cp -1
 	ret z
-	call Func_627c
-	ld a, [wcbc9]
+	call PrintPlayAreaCardInformation
+;	fallthrough
+
+;  print a turn holder's play area Pokemon card's location (ACT/BPx indicator)
+PrintPlayAreaCardLocation: ; 6238 (1:6238)
+	; print the ACT/BPx indicator
+	ld a, [wCurPlayAreaSlot]
 	add a
 	add a
 	ld e, a
 	ld d, $00
-	ld hl, UnknownData_6264
+	ld hl, PlayAreaLocationTileNumbers
 	add hl, de
 	ldh a, [hWhoseTurn]
 	cp PLAYER_TURN
-	jr z, .asm_624c
+	jr z, .write_tiles
+	; move forward to the opponent's side tile numbers
+	; they have black letters and white background instead of the other way around
 	ld d, $0a
-.asm_624c
-	ld a, [wcbc9 + 1]
-	ld b, $01
+.write_tiles
+	ld a, [wCurPlayAreaY]
+	ld b, 1
 	ld c, a
 	ld a, [hli]
 	add d
@@ -3579,11 +5038,211 @@ Func_622a: ; 622a (1:622a)
 	ret
 ; 0x6264
 
-UnknownData_6264: ; 6264 (1:6264)
-	INCROM $6264, $627c
+PlayAreaLocationTileNumbers: ; 6264 (1:6264)
+	db $e0, $e1, $e2, $00 ; ACT
+	db $e3, $e4, $e5, $00 ; BP1
+	db $e3, $e4, $e6, $00 ; BP2
+	db $e3, $e4, $e7, $00 ; BP3
+	db $e3, $e4, $e8, $00 ; BP4
+	db $e3, $e4, $e9, $00 ; BP5
+
+; print a turn holder's play area Pokemon card's name, level, face down stage card,
+; color symbol, status symbol (if any), pluspower/defender symbols (if any),
+; attached energies (if any), and HP bar.
+; input:
+   ; wCurPlayAreaSlot: PLAY_AREA_* of the card to display the information of
+   ; wCurPlayAreaY: Y coordinate of where to print the card's information
+; total space occupied is a rectangle of 20x3 tiles
+PrintPlayAreaCardInformation: ; 627c (1:627c)
+	; print name, level, color, stage, status, pluspower/defender
+	call PrintPlayAreaCardHeader
+	; print the symbols of the attached energies
+	ld a, [wCurPlayAreaSlot]
+	ld e, a
+	ld a, [wCurPlayAreaY]
+	inc a
+	ld c, a
+	ld b, 7
+	call PrintPlayAreaCardAttachedEnergies
+	ld a, [wCurPlayAreaY]
+	inc a
+	ld c, a
+	ld b, 5
+	ld a, SYM_E
+	call WriteByteToBGMap0
+	; print the HP bar
+	inc c
+	ld a, SYM_HP
+	call WriteByteToBGMap0
+	ld a, [wCurPlayAreaSlot]
+	add DUELVARS_ARENA_CARD_HP
+	call GetTurnDuelistVariable
+	or a
+	jr z, .zero_hp
+	ld e, a
+	ld a, [wLoadedCard1HP]
+	ld d, a
+	call DrawHPBar
+	ld a, [wCurPlayAreaY]
+	inc a
+	inc a
+	ld c, a
+	ld b, 7
+	call BCCoordToBGMap0Address
+	ld hl, wDefaultText
+	ld b, 12
+	call SafeCopyDataHLtoDE
+	ret
+.zero_hp
+	; if fainted, print "Knock Out" in place of the HP bar
+	ld a, [wCurPlayAreaY]
+	inc a
+	inc a
+	ld e, a
+	ld d, 7
+	ldtx hl, KnockOutText
+	call InitTextPrinting_ProcessTextFromID
+	ret
+; 0x62d5
+
+; print a turn holder's play area Pokemon card's name, level, face down stage card,
+; color symbol, status symbol (if any), and pluspower/defender symbols (if any).
+; input:
+   ; wCurPlayAreaSlot: PLAY_AREA_* of the card to display the information of
+   ; wCurPlayAreaY: Y coordinate of where to print the card's information
+PrintPlayAreaCardHeader: ; 62d5 (1:62d5)
+	; start by printing the Pokemon's name
+	ld a, [wCurPlayAreaSlot]
+	add DUELVARS_ARENA_CARD
+	call GetTurnDuelistVariable
+	call LoadCardDataToBuffer1_FromDeckIndex
+	ld a, [wCurPlayAreaY]
+	ld e, a
+	ld d, 4
+	call InitTextPrinting
+	; copy the name to wDefaultText (max. 10 characters)
+	; then call ProcessText with hl = wDefaultText
+	ld hl, wLoadedCard1Name
+	ld a, [hli]
+	ld h, [hl]
+	ld l, a
+	ld de, wDefaultText
+	push de
+	ld a, 10 ; card name maximum length
+	call CopyTextData_FromTextID
+	pop hl
+	call ProcessText
+
+	; print the Pokemon's color and the level
+	ld a, [wCurPlayAreaY]
+	ld c, a
+	ld b, 18
+	ld a, [wCurPlayAreaSlot]
+	call GetPlayAreaCardColor
+	inc a
+	call JPWriteByteToBGMap0
+	ld b, 14
+	ld a, SYM_Lv
+	call WriteByteToBGMap0
+	ld a, [wCurPlayAreaY]
+	ld c, a
+	ld b, 15
+	ld a, [wLoadedCard1Level]
+	call WriteTwoDigitNumberInTxSymbolFormat
+
+	; print the 2x2 face down card image depending on the Pokemon's evolution stage
+	ld a, [wCurPlayAreaSlot]
+	add DUELVARS_ARENA_CARD_STAGE
+	call GetTurnDuelistVariable
+	add a
+	ld e, a
+	ld d, $00
+	ld hl, FaceDownCardTileNumbers
+	add hl, de
+	ld a, [hli] ; starting tile to fill the 2x2 rectangle with
+	push hl
+	push af
+	lb hl, 1, 2
+	lb bc, 2, 2
+	ld a, [wCurPlayAreaY]
+	ld e, a
+	ld d, 2
+	pop af
+	call FillRectangle
+	pop hl
+	ld a, [wConsole]
+	cp CONSOLE_CGB
+	jr nz, .not_cgb
+	; in cgb, we have to take care of coloring it too
+	ld a, [hl]
+	lb hl, 0, 0
+	lb bc, 2, 2
+	call BankswitchVRAM1
+	call FillRectangle
+	call BankswitchVRAM0
+
+.not_cgb
+	; print the status condition symbol if any (only for the arena Pokemon card)
+	ld hl, wCurPlayAreaSlot
+	ld a, [hli]
+	or a
+	jr nz, .skip_status
+	ld c, [hl]
+	inc c
+	inc c
+	ld b, 2
+	ld a, DUELVARS_ARENA_CARD_STATUS
+	call GetTurnDuelistVariable
+	call CheckPrintCnfSlpPrz
+	inc b
+	call CheckPrintPoisoned
+	inc b
+	call CheckPrintDoublePoisoned
+
+.skip_status
+	; finally check whether to print the Pluspower and/or Defender symbols
+	ld a, [wCurPlayAreaSlot]
+	add DUELVARS_ARENA_CARD_ATTACHED_PLUSPOWER
+	call GetTurnDuelistVariable
+	or a
+	jr z, .not_pluspower
+	ld a, [wCurPlayAreaY]
+	inc a
+	ld c, a
+	ld b, 15
+	ld a, SYM_PLUSPOWER
+	call WriteByteToBGMap0
+	inc b
+	ld a, [hl]
+	add SYM_0
+	call WriteByteToBGMap0
+.not_pluspower
+	ld a, [wCurPlayAreaSlot]
+	add DUELVARS_ARENA_CARD_ATTACHED_DEFENDER
+	call GetTurnDuelistVariable
+	or a
+	jr z, .not_defender
+	ld a, [wCurPlayAreaY]
+	inc a
+	ld c, a
+	ld b, 17
+	ld a, SYM_DEFENDER
+	call WriteByteToBGMap0
+	inc b
+	ld a, [hl]
+	add SYM_0
+	call WriteByteToBGMap0
+.not_defender
+	ret
+; 0x63b3
 
-Func_627c: ; 627c (1:627c)
-	INCROM $627c, $63bb
+FaceDownCardTileNumbers: ; 63b3 (1:63b3)
+; starting tile number, cgb palette (grey, yellow/red, green/blue, pink/orange)
+	db $d0, $02 ; basic
+	db $d4, $02 ; stage 1
+	db $d8, $01 ; stage 2
+	db $dc, $01 ; stage 2 special
+; 0x63bb
 
 ; given a card's status in a, print the Poison symbol at bc if it's poisoned
 CheckPrintPoisoned: ; 63bb (1:63bb)
@@ -3678,40 +5337,47 @@ PrintPlayAreaCardAttachedEnergies: ; 63e6 (1:63e6)
 
 	INCROM $6423, $6510
 
-Func_6510: ; 6510 (1:6510)
-	ldh a, [hTempPlayAreaLocationOffset_ff9d]
-	ld [wcbc9], a
+; display the screen that prompts the player to use the selected card's
+; Pokemon Power. Includes the card's information above, and the Pokemon Power's
+; description below.
+; input: hTempPlayAreaLocation_ff9d
+DisplayUsePokemonPowerScreen: ; 6510 (1:6510)
+	ldh a, [hTempPlayAreaLocation_ff9d]
+	ld [wCurPlayAreaSlot], a
 	xor a
-	ld [wcbc9 + 1], a
+	ld [wCurPlayAreaY], a
 	call ZeroObjectPositionsAndToggleOAMCopy
 	call EmptyScreen
 	call LoadDuelCardSymbolTiles
 	call LoadDuelCheckPokemonScreenTiles
-	call Func_622a
+	call PrintPlayAreaCardInformationAndLocation
 	lb de, 1, 4
 	call InitTextPrinting
 	ld hl, wLoadedCard1Move1Name
-	call Func_2c20
+	call ProcessTextFromPointerToID_InitTextPrinting
 	lb de, 1, 6
 	ld hl, wLoadedCard1Move1Description
-	call Func_653e
+	call PrintMoveOrCardDescription
 	ret
 ; 0x653e
 
-Func_653e: ; 653e (1:653e)
-	call Func_5f4a
+; print the description of a move, a Pokemon power, or a trainer or energy card
+; x,y coordinates of where to start printing the text are given at de
+; don't separate lines of text
+PrintMoveOrCardDescription: ; 653e (1:653e)
+	call SetNoLineSeparation
 	ld a, [hli]
 	ld h, [hl]
 	ld l, a
-	call Func_2c37
-	cp $07
-	jr c, .asm_654c
-	dec e
-.asm_654c
+	call CountLinesOfTextFromID
+	cp 7
+	jr c, .print
+	dec e ; move one line up to fit (assumes it will be enough)
+.print
 	ld a, 19
 	call InitTextPrintingInTextbox
-	call Func_2c29
-	call Func_5f50
+	call ProcessTextFromID
+	call SetOneLineSeparation
 	ret
 ; 0x6558
 
@@ -3760,7 +5426,7 @@ AttemptRetreat: ; 657a (1:657a)
 	scf
 	ret
 .success
-	ldh a, [hTempPlayAreaLocationOffset_ffa1]
+	ldh a, [hTempPlayAreaLocation_ffa1]
 	ld e, a
 	call SwapArenaWithBenchPokemon
 	xor a
@@ -3768,7 +5434,93 @@ AttemptRetreat: ; 657a (1:657a)
 	ret
 ; 0x659f
 
-	INCROM $659f, $6614
+; given a number between 0-255 in a, converts it to TX_SYMBOL format,
+; and writes it to wStringBuffer + 2 and to the BGMap0 address at bc.
+; leading zeros replaced with SYM_SPACE.
+WriteTwoByteNumberInTxSymbolFormat: ; 659f (1:659f)
+	push de
+	push bc
+	ld l, a
+	ld h, $00
+	call TwoByteNumberToTxSymbol_TrimLeadingZeros_Bank1
+	pop bc
+	push bc
+	call BCCoordToBGMap0Address
+	ld hl, wStringBuffer + 2
+	ld b, 3
+	call SafeCopyDataHLtoDE
+	pop bc
+	pop de
+	ret
+; 0x65b7
+
+; given a number between 0-99 in a, converts it to TX_SYMBOL format,
+; and writes it to wStringBuffer + 3 and to the BGMap0 address at bc.
+; if the number is between 0-9, the first digit is replaced with SYM_SPACE.
+WriteTwoDigitNumberInTxSymbolFormat: ; 65b7 (1:65b7)
+	push hl
+	push de
+	push bc
+	ld l, a
+	ld h, $00
+	call TwoByteNumberToTxSymbol_TrimLeadingZeros_Bank1
+	pop bc
+	push bc
+	call BCCoordToBGMap0Address
+	ld hl, wStringBuffer + 3
+	ld b, 2
+	call SafeCopyDataHLtoDE
+	pop bc
+	pop de
+	pop hl
+	ret
+; 0x65d1
+
+; convert the number at hl to TX_SYMBOL text format and write it to wStringBuffer
+; replace leading zeros with SYM_SPACE
+TwoByteNumberToTxSymbol_TrimLeadingZeros_Bank1: ; 65d1 (1:65d1)
+	ld de, wStringBuffer
+	ld bc, -10000
+	call .get_digit
+	ld bc, -1000
+	call .get_digit
+	ld bc, -100
+	call .get_digit
+	ld bc, -10
+	call .get_digit
+	ld bc, -1
+	call .get_digit
+	xor a ; TX_END
+	ld [de], a
+	ld hl, wStringBuffer
+	ld b, 4
+.digit_loop
+	ld a, [hl]
+	cp SYM_0
+	jr nz, .done ; jump if not zero
+	ld [hl], SYM_SPACE ; trim leading zero
+	inc hl
+	dec b
+	jr nz, .digit_loop
+.done
+	ret
+
+.get_digit
+	ld a, SYM_0 - 1
+.substract_loop
+	inc a
+	add hl, bc
+	jr c, .substract_loop
+	ld [de], a
+	inc de
+	ld a, l
+	sub c
+	ld l, a
+	ld a, h
+	sbc b
+	ld h, a
+	ret
+; 0x6614
 
 ; input d, e: max. HP, current HP
 DrawHPBar: ; 6614 (1:6614)
@@ -3814,44 +5566,239 @@ Func_6635: ; 6635 (1:6635)
 	jr z, .first_move
 	ld hl, wLoadedCard1Move2Name
 .first_move
-	ld e, $01
-	call Func_5c33
+	ld e, 1
+	call PrintMoveOrPkmnPowerInformation
 	lb de, 1, 4
 	ld hl, wLoadedMoveDescription
-	call Func_653e
+	call PrintMoveOrCardDescription
 	ret
 ; 0x666a
 
-Func_666a: ; 666a (1:666a)
+; display card detail when a trainer card is used, and print "Used xxx"
+; hTempCardIndex_ff9f contains the card's deck index
+DisplayUsedTrainerCardDetailScreen: ; 666a (1:666a)
 	ldh a, [hTempCardIndex_ff9f]
 	ldtx hl, UsedText
 	call DisplayCardDetailScreen
 	ret
 ; 0x6673
 
-Func_6673: ; 6673 (1:6673)
+; prints the name and description of a trainer card, along with the
+; "Used xxx" text in a text box. this function is used to show the player
+; the information of a trainer card being used by the opponent.
+PrintUsedTrainerCardDescription: ; 6673 (1:6673)
 	call EmptyScreen
-	call Func_5f4a
+	call SetNoLineSeparation
 	lb de, 1, 1
 	call InitTextPrinting
 	ld hl, wLoadedCard1Name
-	call Func_2c23
+	call ProcessTextFromPointerToID
 	ld a, 19
 	lb de, 1, 3
 	call InitTextPrintingInTextbox
 	ld hl, wLoadedCard1NonPokemonDescription
-	call Func_2c23
-	call Func_5f50
+	call ProcessTextFromPointerToID
+	call SetOneLineSeparation
 	ldtx hl, UsedText
 	call DrawWideTextBox_WaitForInput
 	ret
 ; 0x669d
 
-	INCROM $669d, $6785
+; save data of the current duel to sCurrentDuel
+; byte 0 is $01, bytes 1 and 2 are the checksum, byte 3 is [wDuelType]
+; next $33a bytes come from DuelDataToSave
+SaveDuelData: ; 669d (1:669d)
+	farcall CommentedOut_1a6cc
+	ld de, sCurrentDuel
+;	fallthrough
 
-Func_6785: ; 6785 (1:6785)
+; save data of the current duel to de (in SRAM)
+; byte 0 is $01, bytes 1 and 2 are the checksum, byte 3 is [wDuelType]
+; next $33a bytes come from DuelDataToSave
+SaveDuelDataToDE: ; 66a4 (1:66a4)
 	call EnableSRAM
-	ld hl, $bc00
+	push de
+	inc de
+	inc de
+	inc de
+	inc de
+	ld hl, DuelDataToSave
+	push de
+.save_duel_data_loop
+	; start copying data to de = sCurrentDuelData + $1
+	ld c, [hl]
+	inc hl
+	ld b, [hl]
+	inc hl
+	ld a, c
+	or b
+	jr z, .data_done
+	push hl
+	push bc
+	ld c, [hl]
+	inc hl
+	ld b, [hl]
+	inc hl
+	pop hl
+	call CopyDataHLtoDE
+	pop hl
+	inc hl
+	inc hl
+	jr .save_duel_data_loop
+.data_done
+	pop hl
+	; save a checksum to hl = sCurrentDuelData + $1
+	lb de, $23, $45
+	ld bc, $334 ; misses last 6 bytes to calculate checksum
+.checksum_loop
+	ld a, e
+	sub [hl]
+	ld e, a
+	ld a, [hli]
+	xor d
+	ld d, a
+	dec bc
+	ld a, c
+	or b
+	jr nz, .checksum_loop
+	pop hl
+	ld a, $01
+	ld [hli], a ; sCurrentDuel
+	ld [hl], e ; sCurrentDuelChecksum
+	inc hl
+	ld [hl], d ; sCurrentDuelChecksum
+	inc hl
+	ld a, [wDuelType]
+	ld [hl], a ; sCurrentDuelData
+	call DisableSRAM
+	ret
+; 0x66e9
+
+Func_66e9: ; 66e9 (1:66e9)
+	ld hl, sCurrentDuel
+	call ValidateSavedDuelData
+	ret c
+	ld de, sCurrentDuel
+	call LoadSavedDuelData
+	call Func_3a45
+	ret nc
+	call Func_3a40
+	or a
+	ret
+; 0x66ff
+
+; load the data saved in sCurrentDuelData to WRAM according to the distribution
+; of DuelDataToSave. assumes saved data exists and that the checksum is valid.
+LoadSavedDuelData: ; 66ff (1:66ff)
+	call EnableSRAM
+	inc de
+	inc de
+	inc de
+	inc de
+	ld hl, DuelDataToSave
+.next_block
+	ld c, [hl]
+	inc hl
+	ld b, [hl]
+	inc hl
+	ld a, c
+	or b
+	jr z, .done
+	push hl
+	push bc
+	ld c, [hl]
+	inc hl
+	ld b, [hl]
+	inc hl
+	pop hl
+.copy_loop
+	ld a, [de]
+	inc de
+	ld [hli], a
+	dec bc
+	ld a, c
+	or b
+	jr nz, .copy_loop
+	pop hl
+	inc hl
+	inc hl
+	jr .next_block
+.done
+	call DisableSRAM
+	ret
+; 0x6729
+
+DuelDataToSave: ; 6729 (1:6729)
+;	dw address, number_of_bytes_to_copy
+	dw wPlayerDuelVariables, wOpponentDuelVariables - wPlayerDuelVariables
+	dw wOpponentDuelVariables, wPlayerDeck - wOpponentDuelVariables
+	dw wPlayerDeck, wc500 + $10 - wPlayerDeck
+	dw wWhoseTurn, wDuelTheme + $1 - wWhoseTurn
+	dw hWhoseTurn, $1
+	dw wRNG1, wRNGCounter + $1 - wRNG1
+	dw wcda5, $0010
+	dw $0000
+; 0x6747
+
+; return carry if there is no data saved at sCurrentDuel or if the checksum isn't correct,
+; or if the value saved from wDuelType is DUELTYPE_LINK
+ValidateSavedNonLinkDuelData: ; 6747 (1:6747)
+	call EnableSRAM
+	ld hl, sCurrentDuel
+	ld a, [sCurrentDuelData]
+	call DisableSRAM
+	cp DUELTYPE_LINK
+	jr nz, ValidateSavedDuelData
+	; ignore any saved data of a link duel
+	scf
+	ret
+
+; return carry if there is no data saved at sCurrentDuel or if the checksum isn't correct
+; input: hl = sCurrentDuel
+ValidateSavedDuelData: ; 6759 (1:6759)
+	call EnableSRAM
+	push de
+	ld a, [hli]
+	or a
+	jr z, .no_saved_data
+	lb de, $23, $45
+	ld bc, $334
+	ld a, [hl]
+	sub e
+	ld e, a
+	inc hl
+	ld a, [hl]
+	xor d
+	ld d, a
+	inc hl
+	inc hl
+.loop
+	ld a, [hl]
+	add e
+	ld e, a
+	ld a, [hli]
+	xor d
+	ld d, a
+	dec bc
+	ld a, c
+	or b
+	jr nz, .loop
+	ld a, e
+	or d
+	jr z, .ok
+.no_saved_data
+	scf
+.ok
+	call DisableSRAM
+	pop de
+	ret
+; 0x6785
+
+; discard data of a duel that was saved by SaveDuelData, by setting the first byte
+; of sCurrentDuel to $00, and zeroing the checksum (next two bytes)
+DiscardSavedDuelData: ; 6785 (1:6785)
+	call EnableSRAM
+	ld hl, sCurrentDuel
 	xor a
 	ld [hli], a
 	ld [hli], a
@@ -3860,32 +5807,35 @@ Func_6785: ; 6785 (1:6785)
 	ret
 ; 0x6793
 
-; loads player deck from SRAM to wPlayerDeck
+; loads a player deck (sDeck*Cards) from SRAM to wPlayerDeck
+; s0b700 determines which sDeck*Cards source (0-3)
 LoadPlayerDeck: ; 6793 (1:6793)
 	call EnableSRAM
-	ld a, [$b700]
+	ld a, [s0b700]
 	ld l, a
-	ld h, $54
+	ld h, sDeck2Cards - sDeck1Cards
 	call HtimesL
 	ld de, sDeck1Cards
 	add hl, de
 	ld de, wPlayerDeck
 	ld c, DECK_SIZE
-.next_card_loop
+.copy_cards_loop
 	ld a, [hli]
 	ld [de], a
 	inc de
 	dec c
-	jr nz, .next_card_loop
+	jr nz, .copy_cards_loop
 	call DisableSRAM
 	ret
 ; 0x67b2
 
-Func_67b2: ; 67b2 (1:67b2)
-	ld a, [wccf2]
+; returns carry if wSkipDelayAllowed is non-0 and B is being held in order to branch
+; out of the caller's wait frames loop. probably only used for debugging.
+CheckSkipDelayAllowed: ; 67b2 (1:67b2)
+	ld a, [wSkipDelayAllowed]
 	or a
 	ret z
-	ldh a, [hButtonsHeld]
+	ldh a, [hKeysHeld]
 	and B_BUTTON
 	ret z
 	scf
@@ -3896,7 +5846,7 @@ Func_67b2: ; 67b2 (1:67b2)
 ; called multiple times during one ai turn
 AIMakeDecision: ; 67be (1:67be)
 	ldh [hAIActionTableIndex], a
-	ld hl, wcbf9
+	ld hl, wSkipDuelistIsThinkingDelay
 	ld a, [hl]
 	ld [hl], $0
 	or a
@@ -3904,7 +5854,7 @@ AIMakeDecision: ; 67be (1:67be)
 .delay_loop
 	call DoFrame
 	ld a, [wVBlankCounter]
-	cp $3c
+	cp 60
 	jr c, .delay_loop
 
 .skip_delay
@@ -3917,7 +5867,7 @@ AIMakeDecision: ; 67be (1:67be)
 	ld hl, wAITurnEnded
 	or [hl]
 	jr nz, .turn_ended
-	ld a, [wcbf9]
+	ld a, [wSkipDuelistIsThinkingDelay]
 	or a
 	ret nz
 	ld [wVBlankCounter], a
@@ -3931,13 +5881,215 @@ AIMakeDecision: ; 67be (1:67be)
 	ret
 ; 0x67fb
 
-	INCROM $67fb, $68e4
+Func_67fb: ; 67fb (1:67fb)
+	ld a, 10
+.delay_loop
+	call DoFrame
+	dec a
+	jr nz, .delay_loop
+	ld [wCurrentDuelMenuItem], a ; 0
+.asm_6806
+	ld a, PLAYER_TURN
+	ldh [hWhoseTurn], a
+	ldtx hl, WaitingHandExamineText
+	call DrawWideTextBox_PrintTextNoDelay
+	call Func_6850
+.asm_6813
+	call DoFrame
+	call Func_683e
+	call RefreshMenuCursor
+	ldh a, [hKeysPressed]
+	bit 0, a
+	jr nz, .asm_682e
+	ld a, $01
+	call Func_6862
+	jr nc, .asm_6813
+.asm_6829
+	call DrawDuelMainScene
+	jr .asm_6806
+.asm_682e
+	ld a, [wCurrentDuelMenuItem]
+	or a
+	jr z, .asm_6839
+	call Func_3096
+	jr .asm_6829
+.asm_6839
+	call Func_434e
+	jr .asm_6829
+; 0x683e
+
+Func_683e: ; 683e (1:683e)
+	ldh a, [hDPadHeld]
+	bit 1, a
+	ret nz
+	and D_LEFT | D_RIGHT
+	ret z
+	call EraseCursor
+	ld hl, wCurrentDuelMenuItem
+	ld a, [hl]
+	xor $01
+	ld [hl], a
+;	fallthrough
+
+Func_6850: ; 6850 (1:6850)
+	ld d, 2
+	ld a, [wCurrentDuelMenuItem]
+	or a
+	jr z, .set_cursor_params
+	ld d, 8
+.set_cursor_params
+	ld e, 16
+	lb bc, SYM_CURSOR_R, SYM_SPACE
+	jp SetCursorParametersForTextBox
+; 0x6862
+
+Func_6862: ; 6862 (1:6862)
+	ld [wcbff], a
+	ldh a, [hKeysPressed]
+	bit START_F, a
+	jr nz, .start_pressed
+	bit SELECT_F, a
+	jr nz, .select_pressed
+	ldh a, [hKeysHeld]
+	and B_BUTTON
+	ret z
+	ldh a, [hKeysPressed]
+	bit D_DOWN_F, a
+	jr nz, .down_pressed
+	bit D_LEFT_F, a
+	jr nz, .left_pressed
+	bit D_UP_F, a
+	jr nz, .up_pressed
+	bit D_RIGHT_F, a
+	jr nz, .right_pressed
+	or a
+	ret
+.start_pressed
+	ld a, DUELVARS_ARENA_CARD
+	call GetTurnDuelistVariable
+	cp -1
+	jr z, .return_carry
+	call GetCardIDFromDeckIndex
+	call LoadCardDataToBuffer1_FromCardID
+	ld hl, wCurPlayAreaSlot
+	xor a
+	ld [hli], a
+	ld [hl], a ; wCurPlayAreaY
+	call OpenCardPage_FromCheckPlayArea
+.return_carry
+	scf
+	ret
+.select_pressed
+	ld a, [wcbff]
+	or a
+	jr nz, .asm_68ad
+	call Func_30a6
+	jr .return_carry
+.asm_68ad
+	call Func_4597
+	jr .return_carry
+.down_pressed
+	call OpenPlayAreaScreen
+	jr .return_carry
+.left_pressed
+	call OpenPlayerDiscardPileScreen
+	jr .return_carry
+.up_pressed
+	call OpenOpponentPlayAreaScreen
+	jr .return_carry
+.right_pressed
+	call OpenOpponentDiscardPileScreen
+	jr .return_carry
+; 0x68c6
+
+Func_68c6: ; 68c6 (1:68c6)
+	call Func_3b31
+	ld hl, sp+$00
+	ld a, l
+	ld [wcbf7], a
+	ld a, h
+	ld [wcbf7 + 1], a
+	ld de, Func_0f1d
+	ld hl, wDoFrameFunction
+	ld [hl], e
+	inc hl
+	ld [hl], d
+	ret
+; 0x68dd
+
+ResetDoFrameFunction_Bank1: ; 68dd (1:68dd)
+	xor a
+	ld hl, wDoFrameFunction
+	ld [hli], a
+	ld [hl], a
+	ret
+; 0x68e4
+
+; print the AttachedEnergyToPokemonText, given the energy card to attach in hTempCardIndex_ff98,
+; and the PLAY_AREA_* of the turn holder's Pokemon to attach the energy to in hTempPlayAreaLocation_ff9d
+PrintAttachedEnergyToPokemon: ; 68e4 (1:68e4)
+	ldh a, [hTempPlayAreaLocation_ff9d]
+	add DUELVARS_ARENA_CARD
+	call GetTurnDuelistVariable
+	call LoadCardNameToTxRam2_b
+	ldh a, [hTempCardIndex_ff98]
+	call LoadCardNameToTxRam2
+	ldtx hl, AttachedEnergyToPokemonText
+	call DrawWideTextBox_WaitForInput
+	ret
+; 0x68fa
 
-Func_68e4: ; 68e4 (1:68e4)
-	INCROM $68e4, $68fa
+; print the PokemonEvolvedIntoPokemonText, given the Pokemon card to evolve in wccee,
+; and the evolved Pokemon card in hTempCardIndex_ff98. also play a sound effect.
+PrintPokemonEvolvedIntoPokemon: ; 68fa (1:68fa)
+	ld a, $5e
+	call PlaySFX
+	ld a, [wccee]
+	call LoadCardNameToTxRam2
+	ldh a, [hTempCardIndex_ff98]
+	call LoadCardNameToTxRam2_b
+	ldtx hl, PokemonEvolvedIntoPokemonText
+	call DrawWideTextBox_WaitForInput
+	ret
+; 0x6911
 
-Func_68fa: ; 68fa (1:68fa)
-	INCROM $68fa, $695e
+Func_6911: ; 6911 (1:6911)
+	xor a
+	ld [wAITurnEnded], a
+	xor a
+	ld [wSkipDuelistIsThinkingDelay], a
+.asm_6919
+	ld a, [wSkipDuelistIsThinkingDelay]
+	or a
+	jr nz, .asm_6932
+	call Func_68c6
+	call Func_67fb
+	ld a, [wDuelDisplayedScreen]
+	cp CHECK_PLAY_AREA
+	jr nz, .asm_6932
+	lb de, $38, $9f
+	call SetupText
+.asm_6932
+	call ResetDoFrameFunction_Bank1
+	call SerialRecvDuelData
+	ld a, OPPONENT_TURN
+	ldh [hWhoseTurn], a
+	ld a, [wSerialFlags]
+	or a
+	jp nz, DuelTransmissionError
+	xor a
+	ld [wSkipDuelistIsThinkingDelay], a
+	ldh a, [hAIActionTableIndex]
+	cp $17
+	jp nc, DuelTransmissionError
+	ld hl, AIActionTable
+	call JumpToFunctionInTable
+	ld hl, wAITurnEnded
+	ld a, [wDuelFinished]
+	or [hl]
+	jr z, .asm_6919
+	ret
+; 0x695e
 
 AIActionTable: ; 695e (1:695e)
 	dw DuelTransmissionError
@@ -3946,13 +6098,13 @@ AIActionTable: ; 695e (1:695e)
 	dw AIAction_UseEnergyCard
 	dw AIAction_TryRetreat
 	dw AIAction_FinishedTurnNoAttack
-	dw AIAction_PlayNonPokemonCard
+	dw AIAction_UseTrainerCard
 	dw AIAction_TryExecuteEffect
 	dw AIAction_Attack
 	dw AIAction_AttackEffect
 	dw AIAction_AttackDamage
 	dw AIAction_DrawCard
-	dw AIAction_PokemonPower
+	dw AIAction_UsePokemonPower
 	dw AIAction_6b07
 	dw AIAction_ForceOpponentSwitchActive
 	dw AIAction_NoAction
@@ -3972,7 +6124,7 @@ AIAction_DrawCard: ; 698c (1:698c)
 
 AIAction_FinishedTurnNoAttack: ; 6993 (1:6993)
 	call DrawDuelMainScene
-	call Func_717a
+	call ClearNonTurnTemporaryDuelvars
 	ldtx hl, FinishedTurnWithoutAttackingText
 	call DrawWideTextBox_WaitForInput
 	ld a, 1
@@ -3981,8 +6133,8 @@ AIAction_FinishedTurnNoAttack: ; 6993 (1:6993)
 ; 0x69a5
 
 AIAction_UseEnergyCard: ; 69a5 (1:69a5)
-	ldh a, [hTempPlayAreaLocationOffset_ffa1]
-	ldh [hTempPlayAreaLocationOffset_ff9d], a
+	ldh a, [hTempPlayAreaLocation_ffa1]
+	ldh [hTempPlayAreaLocation_ff9d], a
 	ld e, a
 	ldh a, [hTemp_ffa0]
 	ldh [hTempCardIndex_ff98], a
@@ -3990,7 +6142,7 @@ AIAction_UseEnergyCard: ; 69a5 (1:69a5)
 	ldh a, [hTemp_ffa0]
 	call LoadCardDataToBuffer1_FromDeckIndex
 	call DrawLargePictureOfCard
-	call Func_68e4
+	call PrintAttachedEnergyToPokemon
 	ld a, 1
 	ld [wAlreadyPlayedEnergy], a
 	call DrawDuelMainScene
@@ -3998,14 +6150,14 @@ AIAction_UseEnergyCard: ; 69a5 (1:69a5)
 ; 0x69c5
 
 AIAction_EvolvePokemon: ; 69c5 (1:69c5)
-	ldh a, [hTempPlayAreaLocationOffset_ffa1]
-	ldh [hTempPlayAreaLocationOffset_ff9d], a
+	ldh a, [hTempPlayAreaLocation_ffa1]
+	ldh [hTempPlayAreaLocation_ff9d], a
 	ldh a, [hTemp_ffa0]
 	ldh [hTempCardIndex_ff98], a
 	call LoadCardDataToBuffer1_FromDeckIndex
 	call DrawLargePictureOfCard
 	call EvolvePokemonCard
-	call Func_68fa
+	call PrintPokemonEvolvedIntoPokemon
 	call Func_161e
 	call DrawDuelMainScene
 	ret
@@ -4015,7 +6167,7 @@ AIAction_PlayBenchPokemon: ; 69e0 (1:69e0)
 	ldh a, [hTemp_ffa0]
 	ldh [hTempCardIndex_ff98], a
 	call PutHandPokemonCardInPlayArea
-	ldh [hTempPlayAreaLocationOffset_ff9d], a
+	ldh [hTempPlayAreaLocation_ff9d], a
 	add DUELVARS_ARENA_CARD_STAGE
 	call GetTurnDuelistVariable
 	ld [hl], 0
@@ -4035,7 +6187,7 @@ AIAction_TryRetreat: ; 69ff (1:69ff)
 	ldtx hl, RetreatWasUnsuccessfulText
 	jr c, .failed
 	xor a
-	ld [wcac2], a
+	ld [wDuelDisplayedScreen], a
 	ldtx hl, RetreatedToTheBenchText
 .failed
 	push hl
@@ -4043,19 +6195,19 @@ AIAction_TryRetreat: ; 69ff (1:69ff)
 	pop hl
 	pop af
 	push hl
-	call Func_6b7e
+	call LoadCardNameToTxRam2
 	pop hl
-	call Func_6b9e
+	call DrawWideTextBox_WaitForInput_Bank1
 	ret
 ; 0x6a23
 
-AIAction_PlayNonPokemonCard: ; 6a23 (1:6a23)
+AIAction_UseTrainerCard: ; 6a23 (1:6a23)
 	call LoadNonPokemonCardEffectCommands
-	call Func_666a
-	call Func_6673
-	call Func_0f58
+	call DisplayUsedTrainerCardDetailScreen
+	call PrintUsedTrainerCardDescription
+	call ExchangeRNG
 	ld a, $01
-	ld [wcbf9], a
+	ld [wSkipDuelistIsThinkingDelay], a
 	ret
 ; 0x6a35
 
@@ -4068,7 +6220,7 @@ AIAction_TryExecuteEffect: ; 6a35 (1:6a35)
 	call DrawDuelMainScene
 	ldh a, [hTempCardIndex_ff9f]
 	call MoveHandCardToDiscardPile
-	call Func_0f58
+	call ExchangeRNG
 	call DrawDuelMainScene
 	ret
 ; 0x6a4e
@@ -4084,7 +6236,7 @@ AIAction_Attack: ; 6a4e (1:6a4e)
 	call CopyMoveDataAndDamage_FromDeckIndex
 	call Func_16f6
 	ld a, $01
-	ld [wcbf9], a
+	ld [wSkipDuelistIsThinkingDelay], a
 	call CheckSandAttackOrSmokescreenSubstatus
 	jr c, .has_status_effect
 	ld a, DUELVARS_ARENA_CARD_STATUS
@@ -4092,16 +6244,16 @@ AIAction_Attack: ; 6a4e (1:6a4e)
 	and CNF_SLP_PRZ
 	cp CONFUSED
 	jr z, .has_status_effect
-	call Func_0f58
+	call ExchangeRNG
 	ret
 .has_status_effect
 	call DrawDuelMainScene
-	call Func_1b90
+	call PrintPokemonsAttackText
 	call WaitForWideTextBoxInput
-	call Func_0f58
+	call ExchangeRNG
 	call HandleSandAttackOrSmokescreenSubstatus
 	ret nc ; attack is successful
-	call Func_717a
+	call ClearNonTurnTemporaryDuelvars
 	; only end the turn if the attack fails
 	ld a, 1
 	ld [wAITurnEnded], a
@@ -4114,11 +6266,11 @@ AIAction_AttackEffect: ; 6a8c (1:6a8c)
 	call CheckSelfConfusionDamage
 	jr c, .confusion_damage
 	call Func_6635
-	call Func_1b90
+	call PrintPokemonsAttackText
 	call WaitForWideTextBoxInput
-	call Func_0f58
+	call ExchangeRNG
 	ld a, $01
-	ld [wcbf9], a
+	ld [wSkipDuelistIsThinkingDelay], a
 	ret
 .confusion_damage
 	call DealConfusionDamageToSelf
@@ -4146,31 +6298,31 @@ AIAction_ForceOpponentSwitchActive: ; 6aba (1:6aba)
 	call OpenPlayAreaScreenForSelection
 	jr c, .force_selection
 	call SwapTurn
-	ldh a, [hTempPlayAreaLocationOffset_ff9d]
-	call Func_0e0a
+	ldh a, [hTempPlayAreaLocation_ff9d]
+	call SerialSendByte
 	ret
 ; 0x6ad9
 
-AIAction_PokemonPower: ; 6ad9 (1:6ad9)
+AIAction_UsePokemonPower: ; 6ad9 (1:6ad9)
 	ldh a, [hTempCardIndex_ff9f]
 	ld d, a
 	ld e, $00
 	call CopyMoveDataAndDamage_FromDeckIndex
 	ldh a, [hTemp_ffa0]
-	ldh [hTempPlayAreaLocationOffset_ff9d], a
-	call Func_6510
+	ldh [hTempPlayAreaLocation_ff9d], a
+	call DisplayUsePokemonPowerScreen
 	ldh a, [hTempCardIndex_ff9f]
-	call Func_6b7e
+	call LoadCardNameToTxRam2
 	ld hl, wLoadedMoveName
 	ld a, [hli]
 	ld [wTxRam2_b], a
 	ld a, [hl]
 	ld [wTxRam2_b + 1], a
 	ldtx hl, WillUseThePokemonPowerText
-	call Func_6b9e
-	call Func_0f58
+	call DrawWideTextBox_WaitForInput_Bank1
+	call ExchangeRNG
 	ld a, $01
-	ld [wcbf9], a
+	ld [wSkipDuelistIsThinkingDelay], a
 	ret
 ; 0x6b07
 
@@ -4179,7 +6331,7 @@ AIAction_6b07: ; 6b07 (1:6b07)
 	ld a, $03
 	call TryExecuteEffectCommandFunction
 	ld a, $01
-	ld [wcbf9], a
+	ld [wSkipDuelistIsThinkingDelay], a
 	ret
 ; 0x6b15
 
@@ -4187,7 +6339,7 @@ AIAction_6b15: ; 6b15 (1:6b15)
 	ld a, $04
 	call TryExecuteEffectCommandFunction
 	ld a, $01
-	ld [wcbf9], a
+	ld [wSkipDuelistIsThinkingDelay], a
 	ret
 ; 0x6b20
 
@@ -4197,10 +6349,10 @@ AIAction_DrawDuelMainScene: ; 6b20 (1:6b20)
 ; 0x6b24
 
 AIAction_TossCoinATimes: ; 6b24 (1:6b24)
-	call Func_0fe9
+	call SerialRecv8Bytes
 	call TossCoinATimes
 	ld a, $01
-	ld [wcbf9], a
+	ld [wSkipDuelistIsThinkingDelay], a
 	ret
 ; 0x6b30
 
@@ -4222,22 +6374,22 @@ AIAction_6b3e: ; 6b3e (1:6b3e)
 	and CNF_SLP_PRZ
 	cp CONFUSED
 	jr z, .asm_6b56
-	call Func_1b90
+	call PrintPokemonsAttackText
 	call .asm_6b56
 	call WaitForWideTextBoxInput
 	ret
 .asm_6b56
-	call Func_0fe9
+	call SerialRecv8Bytes
 	push bc
 	call SwapTurn
 	call CopyMoveDataAndDamage_FromDeckIndex
 	call SwapTurn
 	ldh a, [hTempCardIndex_ff9f]
-	ld [wcc11], a
+	ld [wPlayerAttackingCardIndex], a
 	ld a, [wSelectedMoveIndex]
-	ld [wcc10], a
+	ld [wPlayerAttackingMoveIndex], a
 	ld a, [wTempCardID_ccc2]
-	ld [wcc12], a
+	ld [wPlayerAttackingCardID], a
 	call Func_16f6
 	pop bc
 	ld a, c
@@ -4249,7 +6401,9 @@ AIAction_NoAction: ; 6b7d (1:6b7d)
 	ret
 ; 0x6b7e
 
-Func_6b7e: ; 6b7e (1:6b7e)
+; load the text ID of the card name with deck index given in a to TxRam2
+; also loads the card to wLoadedCard1
+LoadCardNameToTxRam2: ; 6b7e (1:6b7e)
 	call LoadCardDataToBuffer1_FromDeckIndex
 	ld a, [wLoadedCard1Name]
 	ld [wTxRam2], a
@@ -4258,7 +6412,9 @@ Func_6b7e: ; 6b7e (1:6b7e)
 	ret
 ; 0x6b8e
 
-Func_6b8e: ; 6b8e (1:6b8e)
+; load the text ID of the card name with deck index given in a to TxRam2_b
+; also loads the card to wLoadedCard1
+LoadCardNameToTxRam2_b: ; 6b8e (1:6b8e)
 	call LoadCardDataToBuffer1_FromDeckIndex
 	ld a, [wLoadedCard1Name]
 	ld [wTxRam2_b], a
@@ -4267,12 +6423,253 @@ Func_6b8e: ; 6b8e (1:6b8e)
 	ret
 ; 0x6b9e
 
-Func_6b9e: ; 6b9e (1:6b9e)
+DrawWideTextBox_WaitForInput_Bank1: ; 6b9e (1:6b9e)
 	call DrawWideTextBox_WaitForInput
 	ret
 ; 0x6ba2
 
-	INCROM $6ba2, $6d84
+Func_6ba2: ; 6ba2 (1:6ba2)
+	call DrawWideTextBox_PrintText
+	ld a, [wDuelistType]
+	cp DUELIST_TYPE_LINK_OPP
+	ret z
+	call WaitForWideTextBoxInput
+	ret
+; 0x6baf
+
+; apply and/or refresh status conditions and other events that trigger between turns
+HandleBetweenTurnsEvents: ; 6baf (1:6baf)
+	call IsArenaPokemonAsleepOrDoublePoisoned
+	jr c, .something_to_handle
+	cp PARALYZED
+	jr z, .something_to_handle
+	call SwapTurn
+	call IsArenaPokemonAsleepOrDoublePoisoned
+	call SwapTurn
+	jr c, .something_to_handle
+	call DiscardAttachedPluspowers
+	call SwapTurn
+	call DiscardAttachedDefenders
+	call SwapTurn
+	ret
+.something_to_handle
+	; either:
+	; 1. turn holder's arena Pokemon is paralyzed, asleep or double poisoned
+	; 2. non-turn holder's arena Pokemon is asleep or double poisoned
+	call Func_3b21
+	call ZeroObjectPositionsAndToggleOAMCopy
+	call EmptyScreen
+	ld a, BOXMSG_BETWEEN_TURNS
+	call DrawDuelBoxMessage
+	ldtx hl, BetweenTurnsText
+	call DrawWideTextBox_WaitForInput
+	ld a, DUELVARS_ARENA_CARD
+	call GetTurnDuelistVariable
+	call GetCardIDFromDeckIndex
+	ld a, e
+	ld [wTempNonTurnDuelistCardID], a
+	ld l, DUELVARS_ARENA_CARD_STATUS
+	ld a, [hl]
+	or a
+	jr z, .asm_6c1a
+	call $6d3f
+	jr c, .asm_6c1a
+	call Func_6cfa
+	ld a, [hl]
+	and CNF_SLP_PRZ
+	cp PARALYZED
+	jr nz, .asm_6c1a
+	ld a, DOUBLE_POISONED
+	and [hl]
+	ld [hl], a
+	call Func_6c7e
+	ldtx hl, IsCuredOfParalysisText
+	call Func_6ce4
+	ld a, $3e
+	call Func_6cab
+	call WaitForWideTextBoxInput
+.asm_6c1a
+	call DiscardAttachedPluspowers
+	call SwapTurn
+	ld a, DUELVARS_ARENA_CARD
+	call GetTurnDuelistVariable
+	call GetCardIDFromDeckIndex
+	ld a, e
+	ld [wTempNonTurnDuelistCardID], a
+	ld l, DUELVARS_ARENA_CARD_STATUS
+	ld a, [hl]
+	or a
+	jr z, .asm_6c3a
+	call $6d3f
+	jr c, .asm_6c3a
+	call Func_6cfa
+.asm_6c3a
+	call DiscardAttachedDefenders
+	call SwapTurn
+	call $6e4c
+	ret
+; 0x6c44
+
+; discard any PLUSPOWER attached to the turn holder's arena and/or bench Pokemon
+DiscardAttachedPluspowers: ; 6c44 (1:6c44)
+	ld a, DUELVARS_ARENA_CARD_ATTACHED_PLUSPOWER
+	call GetTurnDuelistVariable
+	ld e, MAX_PLAY_AREA_POKEMON
+	xor a
+.unattach_pluspower_loop
+	ld [hli], a
+	dec e
+	jr nz, .unattach_pluspower_loop
+	ld de, PLUSPOWER
+	jp MoveCardToDiscardPileIfInArena
+; 0x6c56
+
+; discard any DEFENDER attached to the turn holder's arena and/or bench Pokemon
+DiscardAttachedDefenders: ; 6c56 (1:6c56)
+	ld a, DUELVARS_ARENA_CARD_ATTACHED_DEFENDER
+	call GetTurnDuelistVariable
+	ld e, MAX_PLAY_AREA_POKEMON
+	xor a
+.unattach_defender_loop
+	ld [hli], a
+	dec e
+	jr nz, .unattach_defender_loop
+	ld de, DEFENDER
+	jp MoveCardToDiscardPileIfInArena
+; 0x6c68
+
+; return carry if the turn holder's arena Pokemon card is double poisoned or asleep.
+; also, if confused, paralyzed, or asleep, return the status condition in a.
+IsArenaPokemonAsleepOrDoublePoisoned: ; 6c68 (1:6c68)
+	ld a, DUELVARS_ARENA_CARD_STATUS
+	call GetTurnDuelistVariable
+	or a
+	ret z
+	and DOUBLE_POISONED
+	jr nz, .set_carry
+	ld a, [hl]
+	and CNF_SLP_PRZ
+	cp ASLEEP
+	jr z, .set_carry
+	or a
+	ret
+.set_carry
+	scf
+	ret
+; 0x6c7e
+
+Func_6c7e: ; 6c7e (1:6c7e)
+	ld a, [wDuelDisplayedScreen]
+	cp DUEL_MAIN_SCENE
+	jr z, .asm_6c98
+	ld hl, wWhoseTurn
+	ldh a, [hWhoseTurn]
+	cp [hl]
+	jp z, DrawDuelMainScene
+	call SwapTurn
+	call DrawDuelMainScene
+	call SwapTurn
+	ret
+.asm_6c98
+	ld hl, wWhoseTurn
+	ldh a, [hWhoseTurn]
+	cp [hl]
+	jp z, DrawDuelHUDs
+	call SwapTurn
+	call DrawDuelHUDs
+	call SwapTurn
+	ret
+; 0x6cab
+
+Func_6cab: ; 6cab (1:6cab)
+	push af
+	ld a, [wDuelType]
+	or a
+	jr nz, .asm_6cc6
+	ld a, [wWhoseTurn]
+	cp PLAYER_TURN
+	jr z, .asm_6cc6
+	call SwapTurn
+	ldh a, [hWhoseTurn]
+	ld [wd4af], a
+	call SwapTurn
+	jr .asm_6ccb
+.asm_6cc6
+	ldh a, [hWhoseTurn]
+	ld [wd4af], a
+.asm_6ccb
+	xor a
+	ld [wd4b0], a
+	ld a, $00
+	ld [wd4ae], a
+	pop af
+	call Func_3b6a
+.asm_6cd8
+	call DoFrame
+	call Func_3b52
+	jr c, .asm_6cd8
+	call Func_6c7e.asm_6c98
+	ret
+; 0x6ce4
+
+; prints the name of the card at wTempNonTurnDuelistCardID in a text box
+Func_6ce4: ; 6ce4 (1:6ce4)
+	push hl
+	ld a, [wTempNonTurnDuelistCardID]
+	ld e, a
+	call LoadCardDataToBuffer1_FromCardID
+	ld hl, wLoadedCard1Name
+	ld a, [hli]
+	ld h, [hl]
+	ld l, a
+	call LoadTxRam2
+	pop hl
+	call DrawWideTextBox_PrintText
+	ret
+; 0x6cfa
+
+Func_6cfa: ; 6cfa (1:6cfa)
+	ld a, [hl]
+	and CNF_SLP_PRZ
+	cp ASLEEP
+	ret nz
+	push hl
+	ld a, [wTempNonTurnDuelistCardID]
+	ld e, a
+	call LoadCardDataToBuffer1_FromCardID
+	ld a, 18
+	call CopyCardNameAndLevel
+	ld [hl], TX_END
+	ld hl, wTxRam2
+	xor a
+	ld [hli], a
+	ld [hl], a
+	ldtx de, PokemonsSleepCheckText
+	call TossCoin
+	ld a, $03
+	ldtx hl, IsStillAsleepText
+	jr nc, .asm_6d2d
+	pop hl
+	push hl
+	ld a, DOUBLE_POISONED
+	and [hl]
+	ld [hl], a
+	ld a, $3e
+	ldtx hl, IsCuredOfSleepText
+.asm_6d2d
+	push af
+	push hl
+	call Func_6c7e
+	pop hl
+	call Func_6ce4
+	pop af
+	call Func_6cab
+	pop hl
+	call WaitForWideTextBoxInput
+	ret
+; 0x6d3f
+
+	INCROM $6d3f, $6d84
 
 ; given the deck index of a turn holder's card in register a,
 ; and a pointer in hl to the wLoadedCard* buffer where the card data is loaded,
@@ -4332,18 +6729,164 @@ ConvertSpecialTrainerCardToPokemon: ; 6d84 (1:6d84)
     db UNABLE_RETREAT     ; CARD_DATA_RETREAT_COST
     ds $0d                ; PKMN_CARD_DATA_LENGTH - (CARD_DATA_RETREAT_COST + 1)
 
-	INCROM $6df1, $70e6
+; this function applies status conditions to the defending Pokemon,
+; returned by the effect functions in wEffectFunctionsFeedback
+Func_6df1: ; 6df1 (1:6df1)
+	xor a
+	ld [wPlayerArenaCardLastTurnStatus], a
+	ld [wOpponentArenaCardLastTurnStatus], a
+	ld hl, wEffectFunctionsFeedbackIndex
+	ld a, [hl]
+	or a
+	ret z
+	ld e, [hl]
+	ld d, $00
+	ld hl, wEffectFunctionsFeedback
+	add hl, de
+	ld [hl], $00
+	call CheckNoDamageOrEffect
+	jr c, .no_damage_or_effect
+	ld hl, wEffectFunctionsFeedback
+.apply_status_loop
+	ld a, [hli]
+	or a
+	jr z, .done
+	ld d, a
+	call ApplyStatusConditionToArenaPokemon
+	jr .apply_status_loop
+.done
+	scf
+	ret
+.no_damage_or_effect
+	ld a, l
+	or h
+	call nz, DrawWideTextBox_PrintText
+	ld hl, wEffectFunctionsFeedback
+.asm_6e23
+	ld a, [hli]
+	or a
+	jr z, .asm_6e37
+	ld d, a
+	ld a, [wWhoseTurn]
+	cp d
+	jr z, .asm_6e32
+	inc hl
+	inc hl
+	jr .asm_6e23
+.asm_6e32
+	call ApplyStatusConditionToArenaPokemon
+	jr .asm_6e23
+.asm_6e37
+	ret
+; 0x6e38
+
+; apply the status condition at hl+1 to the arena Pokemon
+; discard the arena Pokemon's status conditions contained in the bitmask at hl
+ApplyStatusConditionToArenaPokemon: ; 6e38 (1:6e38)
+	ld e, DUELVARS_ARENA_CARD_STATUS
+	ld a, [de]
+	and [hl]
+	inc hl
+	or [hl]
+	ld [de], a
+	dec hl
+	ld e, DUELVARS_ARENA_CARD_LAST_TURN_STATUS
+	ld a, [de]
+	and [hl]
+	inc hl
+	or [hl]
+	inc hl
+	ld [de], a
+	ret
+; 0x6e49
+
+Func_6e49: ; 6e49 (1:6e49)
+	INCROM $6e49, $700a
+
+; print one of the "There was no effect from" texts depending
+; on the value at wccf1 ($00 or a status condition constant)
+PrintThereWasNoEffectFromStatusText: ; 700a (1:700a)
+	ld a, [wccf1]
+	or a
+	jr nz, .status
+	ld hl, wLoadedMoveName
+	ld a, [hli]
+	ld h, [hl]
+	ld l, a
+	call LoadTxRam2
+	ldtx hl, ThereWasNoEffectFromTxRam2Text
+	ret
+.status
+	ld c, a
+	ldtx hl, ThereWasNoEffectFromPoisonConfusionText
+	cp POISONED | CONFUSED
+	ret z
+	and PSN_DBLPSN
+	jr nz, .poison
+	ld a, c
+	and CNF_SLP_PRZ
+	ldtx hl, ThereWasNoEffectFromParalysisText
+	cp PARALYZED
+	ret z
+	ldtx hl, ThereWasNoEffectFromSleepText
+	cp ASLEEP
+	ret z
+	ldtx hl, ThereWasNoEffectFromConfusionText
+	ret
+.poison
+	ldtx hl, ThereWasNoEffectFromPoisonText
+	cp POISONED
+	ret z
+	ldtx hl, ThereWasNoEffectFromToxicText
+	ret
+; 0x7045
+
+	INCROM $7045, $70aa
+
+; initializes variables when a duel begins, such as zeroing wDuelFinished or wDuelTurns,
+; and setting wDuelType based on wPlayerDuelistType and wOpponentDuelistType
+InitVariablesToBeginDuel: ; 70aa (1:70aa)
+	xor a
+	ld [wDuelFinished], a
+	ld [wDuelTurns], a
+	ld [wcce7], a
+	ld a, $ff
+	ld [wcc0f], a
+	ld [wPlayerAttackingCardIndex], a
+	ld [wPlayerAttackingMoveIndex], a
+	call EnableSRAM
+	ld a, [s0a009]
+	ld [wSkipDelayAllowed], a
+	call DisableSRAM
+	ld a, [wPlayerDuelistType]
+	cp DUELIST_TYPE_LINK_OPP
+	jr z, .set_duel_type
+	bit 7, a ; DUELIST_TYPE_AI_OPP
+	jr nz, .set_duel_type
+	ld a, [wOpponentDuelistType]
+	cp DUELIST_TYPE_LINK_OPP
+	jr z, .set_duel_type
+	bit 7, a ; DUELIST_TYPE_AI_OPP
+	jr nz, .set_duel_type
+	xor a
+.set_duel_type
+	ld [wDuelType], a
+	ret
+; 0x70e6
 
-Func_70e6: ; 70e6 (1:70e6)
+; init variables that last a single player's turn
+InitVariablesToBeginTurn: ; 70e6 (1:70e6)
 	xor a
 	ld [wAlreadyPlayedEnergy], a
 	ld [wGotHeadsFromConfusionCheckDuringRetreat], a
 	ld [wGotHeadsFromSandAttackOrSmokescreenCheck], a
 	ldh a, [hWhoseTurn]
-	ld [wcc05], a
+	ld [wWhoseTurn], a
 	ret
 ; 0x70f6
 
+; make all Pokemon in the turn holder's play area able to evolve. called from the
+; player's second turn on, in order to allow evolution of all Pokemon already played.
 SetAllPlayAreaPokemonCanEvolve: ; 70f6 (1:70f6)
 	ld a, DUELVARS_NUMBER_OF_POKEMON_IN_PLAY_AREA
 	call GetTurnDuelistVariable
@@ -4394,16 +6937,73 @@ InitializeDuelVariables: ; 7107 (1:7107)
 	ld c, 1 + MAX_BENCH_POKEMON + 1
 .init_play_area
 ; initialize to $ff card in arena as well as cards in bench (plus a terminator)
-	ld [hl], $ff
+	ld [hl], -1
 	inc l
 	dec c
 	jr nz, .init_play_area
 	ret
 ; 0x7133
 
-	INCROM $7133, $717a
+; draw [wDuelInitialPrizes] cards from the turn holder's deck and place them as prizes:
+; write their deck indexes to DUELVARS_PRIZE_CARDS, set their location to
+; CARD_LOCATION_PRIZE, and set [wDuelInitialPrizes] bits of DUELVARS_PRIZES.
+InitTurnDuelistPrizes: ; 7133 (1:7133)
+	ldh a, [hWhoseTurn]
+	ld d, a
+	ld e, DUELVARS_PRIZE_CARDS
+	ld a, [wDuelInitialPrizes]
+	ld c, a
+	ld b, 0
+.draw_prizes_loop
+	call DrawCardFromDeck
+	ld [de], a
+	inc de
+	ld h, d
+	ld l, a
+	ld [hl], CARD_LOCATION_PRIZE
+	inc b
+	ld a, b
+	cp c
+	jr nz, .draw_prizes_loop
+	push hl
+	ld e, c
+	ld d, $00
+	ld hl, PrizeBitmasks
+	add hl, de
+	ld a, [hl]
+	pop hl
+	ld l, DUELVARS_PRIZES
+	ld [hl], a
+	ret
+; 0x715a
+
+PrizeBitmasks: ; 715a (1:715a)
+	db %0, %1, %11, %111, %1111, %11111, %111111
+; 0x7161
 
-Func_717a: ; 717a (1:717a)
+Func_7161: ; 7161 (1:7161)
+	or a
+	ret z
+	ld c, a
+	call CountPrizes
+	sub c
+	jr nc, .asm_716b
+	xor a
+.asm_716b
+	ld c, a
+	ld b, $00
+	ld hl, PrizeBitmasks
+	add hl, bc
+	ld b, [hl]
+	ld a, DUELVARS_PRIZES
+	call GetTurnDuelistVariable
+	ld [hl], b
+	ret
+; 0x717a
+
+; clear the non-turn holder's duelvars starting at DUELVARS_ARENA_CARD_DISABLED_MOVE_INDEX
+; these duelvars only last a two-player turn at most.
+ClearNonTurnTemporaryDuelvars: ; 717a (1:717a)
 	ld a, DUELVARS_ARENA_CARD_DISABLED_MOVE_INDEX
 	call GetNonTurnDuelistVariable
 	xor a
@@ -4418,12 +7018,38 @@ Func_717a: ; 717a (1:717a)
 	ret
 ; 0x7189
 
-	INCROM $7189, $71ad
+; same as ClearNonTurnTemporaryDuelvars, except the non-turn holder's arena
+; Pokemon status condition is copied to wccc5
+ClearNonTurnTemporaryDuelvars_CopyStatus: ; 7189 (1:7189)
+	ld a, DUELVARS_ARENA_CARD_STATUS
+	call GetNonTurnDuelistVariable
+	ld [wccc5], a
+	call ClearNonTurnTemporaryDuelvars
+	ret
+; 0x7195
+
+Func_7195: ; 7195 (1:7195)
+	ld a, DUELVARS_ARENA_CARD_LAST_TURN_DAMAGE
+	call GetNonTurnDuelistVariable
+	ld a, [wccef]
+	or a
+	jr nz, .asm_71a9
+	ld a, [wDealtDamage]
+	ld [hli], a
+	ld a, [wccc0]
+	ld [hl], a
+	ret
+.asm_71a9
+	xor a
+	ld [hli], a
+	ld [hl], a
+	ret
+; 0x71ad
 
 _TossCoin: ; 71ad (1:71ad)
 	ld [wcd9c], a
-	ld a, [wcac2]
-	cp $6
+	ld a, [wDuelDisplayedScreen]
+	cp COIN_TOSS
 	jr z, .asm_71c1
 	xor a
 	ld [wcd9f], a
@@ -4434,10 +7060,10 @@ _TossCoin: ; 71ad (1:71ad)
 	ld a, [wcd9f]
 	or a
 	jr nz, .asm_71ec
-	ld a, $6
-	ld [wcac2], a
-	ld de, $000c
-	ld bc, $1406
+	ld a, COIN_TOSS
+	ld [wDuelDisplayedScreen], a
+	lb de, 0, 12
+	lb bc, 20, 6
 	ld hl, $0000
 	call DrawLabeledTextBox
 	call EnableLCD
@@ -4459,24 +7085,24 @@ _TossCoin: ; 71ad (1:71ad)
 	ld a, DUELVARS_DUELIST_TYPE
 	call GetTurnDuelistVariable
 	ld [wcd9e], a
-	call Func_0f58
+	call ExchangeRNG
 	xor a
-	ld [wcd9d], a
+	ld [wCoinTossNumHeads], a
 
 .asm_7204
 	ld a, [wcd9c]
 	cp $2
 	jr c, .asm_7223
-	ld bc, $0f0b
+	lb bc, 15, 11
 	ld a, [wcd9f]
 	inc a
-	call $65b7
+	call WriteTwoDigitNumberInTxSymbolFormat
 	ld b, 17
-	ld a, $2e
+	ld a, SYM_SLASH
 	call WriteByteToBGMap0
 	inc b
 	ld a, [wcd9c]
-	call $65b7
+	call WriteTwoDigitNumberInTxSymbolFormat
 
 .asm_7223
 	call Func_3b21
@@ -4530,7 +7156,7 @@ _TossCoin: ; 71ad (1:71ad)
 	jr z, .asm_727c
 	ld b, $5b
 	ld c, $30
-	ld hl, wcd9d
+	ld hl, wCoinTossNumHeads
 	inc [hl]
 
 .asm_727c
@@ -4588,7 +7214,7 @@ _TossCoin: ; 71ad (1:71ad)
 	call z, WaitForWideTextBoxInput
 	call $7324
 	ld a, [wcd9c]
-	ld hl, wcd9d
+	ld hl, wCoinTossNumHeads
 	or [hl]
 	jr nz, .asm_72e2
 	call z, WaitForWideTextBoxInput
@@ -4604,10 +7230,10 @@ _TossCoin: ; 71ad (1:71ad)
 	ld hl, wcd9c
 	cp [hl]
 	jp c, .asm_7204
-	call Func_0f58
+	call ExchangeRNG
 	call Func_3b31
 	call Func_3b21
-	ld a, [wcd9d]
+	ld a, [wCoinTossNumHeads]
 	or a
 	ret z
 	scf
@@ -4627,7 +7253,132 @@ Func_7415: ; 7415 (1:7415)
 	ret
 ; 0x741a
 
-	INCROM $741a, $7571
+Func_741a: ; 741a (1:741a)
+	ld hl, wEffectFunctionsFeedbackIndex
+	ld a, [hl]
+	or a
+	ret z
+	ld e, a
+	ld d, $00
+	ld hl, wEffectFunctionsFeedback
+	add hl, de
+	ld [hl], $00
+	ld hl, wEffectFunctionsFeedback
+.loop
+	ld a, [hli]
+	or a
+	jr z, .done
+	ld d, a
+	inc hl
+	ld a, [hli]
+	ld e, $7e
+	cp ASLEEP
+	jr z, .got_anim
+	ld e, $7d
+	cp PARALYZED
+	jr z, .got_anim
+	ld e, $7b
+	cp POISONED
+	jr z, .got_anim
+	ld e, $7b
+	cp DOUBLE_POISONED
+	jr z, .got_anim
+	ld e, $7c
+	cp CONFUSED
+	jr nz, .loop
+	ldh a, [hWhoseTurn]
+	cp d
+	jr nz, .got_anim
+	ld e, $7f
+.got_anim
+	ld a, e
+	ld [wLoadedMoveAnimation], a
+	xor a
+	ld [wd4b0], a
+	push hl
+	farcall $6, $4f9c
+	pop hl
+	jr .loop
+.done
+	ret
+; 0x7469
+
+Func_7469: ; 7469 (1:7469)
+	push hl
+	push de
+	call Func_7494
+	call Func_7484
+	pop de
+	pop hl
+	call SubstractHP
+	ld a, [wDuelDisplayedScreen]
+	cp DUEL_MAIN_SCENE
+	ret nz
+	push hl
+	push de
+	call DrawDuelHUDs
+	pop de
+	pop hl
+	ret
+; 0x7484
+
+Func_7484: ; 7484 (1:7484)
+	ld a, [wLoadedMoveAnimation]
+	or a
+	ret z
+	push de
+.asm_748a
+	call DoFrame
+	call Func_3b52
+	jr c, .asm_748a
+	pop de
+	ret
+; 0x7494
+
+Func_7494: ; 7494 (1:7494)
+	ldh a, [hWhoseTurn]
+	push af
+	push hl
+	push de
+	push bc
+	ld a, [wWhoseTurn]
+	ldh [hWhoseTurn], a
+	ld a, c
+	ld [wce81], a
+	ldh a, [hWhoseTurn]
+	cp h
+	jr z, .asm_74aa
+	set 7, b
+.asm_74aa
+	ld a, b
+	ld [wce82], a
+	ld a, [wWhoseTurn]
+	ld [wce83], a
+	ld a, [wTempNonTurnDuelistCardID]
+	ld [wce84], a
+	ld hl, wce7f
+	ld [hl], e
+	inc hl
+	ld [hl], d
+	ld a, [wLoadedMoveAnimation]
+	cp $01
+	jr nz, .asm_74d1
+	ld a, e
+	cp $46
+	jr c, .asm_74d1
+	ld a, $02
+	ld [wLoadedMoveAnimation], a
+.asm_74d1
+	farcall $6, $4f9c
+	pop bc
+	pop de
+	pop hl
+	pop af
+	ldh [hWhoseTurn], a
+	ret
+; 0x74dc
+
+	INCROM $74dc, $7571
 
 Func_7571: ; 7571 (1:7571)
 	INCROM $7571, $7576
@@ -4647,4 +7398,11 @@ Func_7594: ; 7594 (1:7594)
 	ret
 ; 0x7599
 
-	INCROM $7599, $8000
-\ No newline at end of file
+Func_7599: ; 7599 (1:7599)
+	farcall $6, $668d
+	ret
+; 0x759e
+
+rept $a62
+	db $ff
+endr
diff --git a/src/engine/bank02.asm b/src/engine/bank02.asm
index 4f88d0a..509a1e9 100644
--- a/src/engine/bank02.asm
+++ b/src/engine/bank02.asm
@@ -1,4 +1,23 @@
-	INCROM $8000, $8cd4
+Func_8000: ; 8000 (2:4000)
+	INCROM $8000, $8211
+
+Func_8211: ; 8211 (2:4211)
+	INCROM $8211, $833c
+
+Func_833c: ; 833c (2:433c)
+	INCROM $833c, $8764
+
+Func_8764: ; 8764 (2:4764)
+	INCROM $8764, $8932
+
+Func_8932: ; 8932 (2:4932)
+	INCROM $8932, $8aaa
+
+Func_8aaa: ; 8aaa (2:4aaa)
+	INCROM $8aaa, $8b85
+
+Func_8b85: ; 8b85 (2:4b85)
+	INCROM $8b85, $8cd4
 
 Func_8cd4: ; 8cd4 (2:4cd4)
 	push bc
@@ -50,8 +69,8 @@ Func_8d56: ; 8d56 (2:4d56)
 	call LoadDuelCardSymbolTiles
 	call Func_8d0b
 	bank1call SetDefaultPalettes
-	ld de, $3cbf
-	call Func_2275
+	lb de, $3c, $bf
+	call SetupText
 	ret
 ; 0x8d78
 
@@ -100,7 +119,7 @@ Unknown_8de2: ; 8de2 (2:4de2)
 	INCROM $8de2, $8dea
 
 Func_8dea: ; 8dea (2:4dea)
-	ldh a, [hButtonsPressed2]
+	ldh a, [hDPadHeld]
 	and START
 	ret z
 	ld a, [wCurMenuItem]
@@ -324,7 +343,7 @@ Func_8f8a: ; 8f8a (2:4f8a)
 
 Func_8f9d: ; 8f9d (2:4f9d)
 	call EnableSRAM
-	ld a, [$b700]
+	ld a, [s0b700]
 	call DisableSRAM
 	ld h, $3
 	ld l, a
@@ -338,7 +357,7 @@ Func_8f9d: ; 8f9d (2:4f9d)
 	call FillRectangle
 	ld a, [wceb1]
 	call EnableSRAM
-	ld [$b700], a
+	ld [s0b700], a
 	call DisableSRAM
 	call Func_9326
 	call GetPointerToDeckName
@@ -420,7 +439,7 @@ Func_9065: ; 9065 (2:5065)
 	ld d, a
 	ld a, [wceb0]
 	ld e, a
-	ldh a, [hButtonsPressed2]
+	ldh a, [hDPadHeld]
 	or a
 	jr z, .asm_90a6
 	bit D_LEFT_F, a
@@ -454,7 +473,7 @@ Func_9065: ; 9065 (2:5065)
 	xor a
 	ld [wcea3], a
 .asm_90a6
-	ldh a, [hButtonsPressed]
+	ldh a, [hKeysPressed]
 	and A_BUTTON | B_BUTTON
 	jr z, .asm_90c1
 	and A_BUTTON
@@ -637,7 +656,7 @@ Func_9168: ; 9168 (2:5168)
 	ld [wceb5], a
 .asm_9214
 	call EnableSRAM
-	ld a, [$b700]
+	ld a, [s0b700]
 	ld c, a
 	ld b, $0
 	ld d, $2
@@ -657,7 +676,7 @@ Func_9168: ; 9168 (2:5168)
 	jr .asm_921f
 .asm_9234
 	ld a, c
-	ld [$b700], a
+	ld [s0b700], a
 	call DisableSRAM
 	call Func_9326
 	call EnableLCD
@@ -706,7 +725,7 @@ Func_926e: ; 926e (2:526e)
 .asm_929c
 	call InitTextPrinting
 	ldtx hl, NewDeckText
-	call Func_2c29
+	call ProcessTextFromID
 	scf
 	ret
 
@@ -746,7 +765,7 @@ Func_9314: ; 9314 (2:5314)
 
 Func_9326: ; 9326 (2:5326)
 	call EnableSRAM
-	ld a, [$b700]
+	ld a, [s0b700]
 	call DisableSRAM
 	ld h, 3
 	ld l, a
@@ -927,12 +946,12 @@ Func_ba04: ; ba04 (2:7a04)
 	call DoFrame
 	call HandleMenuInput
 	jr c, .asm_baa3
-	ldh a, [hButtonsPressed2]
+	ldh a, [hDPadHeld]
 	and D_UP | D_DOWN
 	jr z, .asm_ba4e
 
 .asm_ba4e
-	ldh a, [hButtonsPressed2]
+	ldh a, [hDPadHeld]
 	and START
 	jr z, .asm_ba40
 	ld a, [wcea1]
diff --git a/src/engine/bank03.asm b/src/engine/bank03.asm
index 744a3ef..1c346d5 100644
--- a/src/engine/bank03.asm
+++ b/src/engine/bank03.asm
@@ -1,7 +1,7 @@
 LoadMap: ; c000 (3:4000)
 	call DisableLCD
 	call EnableSRAM
-	bank1call Func_6785
+	bank1call DiscardSavedDuelData
 	call DisableSRAM
 	ld a, GAME_EVENT_OVERWORLD
 	ld [wGameEvent], a
@@ -267,9 +267,9 @@ Func_c1f8: ; c1f8 (3:41f8)
 	ld [wd112], a
 	ld [wd3b8], a
 	call EnableSRAM
-	ld a, [sa007]
+	ld a, [s0a007]
 	ld [wd421], a
-	ld a, [sa006]
+	ld a, [s0a006]
 	ld [wTextSpeed], a
 	call DisableSRAM
 	farcall Func_10756
@@ -290,8 +290,8 @@ Func_c241: ; c241 (3:4241)
 	push hl
 	push bc
 	push de
-	ld de, $307f
-	call Func_2275
+	lb de, $30, $7f
+	call SetupText
 	call Func_c258
 	pop de
 	pop bc
@@ -326,7 +326,7 @@ Func_c268: ; c268 (3:4268)
 	ld l, a
 	or h
 	jr z, .asm_c27a
-	call Func_2c29
+	call ProcessTextFromID
 	pop hl
 	inc hl
 	inc hl
@@ -366,8 +366,8 @@ Func_c2a3: ; c2a3 (3:42a3)
 	farcall Func_10ab4
 	ld a, $80
 	call Func_c29b
-	ld de, $307f
-	call Func_2275
+	lb de, $30, $7f
+	call SetupText
 	farcall Func_12ba7
 	call Func_3ca0
 	call ZeroObjectPositions
@@ -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)
@@ -623,7 +623,7 @@ Func_c510: ; c510 (3:4510)
 	call nz, Func_c6dc
 	ret
 .asm_c535
-	ldh a, [hButtonsPressed]
+	ldh a, [hKeysPressed]
 	and START
 	call nz, Func_c74d
 	ret
@@ -695,7 +695,7 @@ Func_c58b: ; c58b (3:458b)
 	ret
 
 Func_c5ac: ; c5ac (3:45ac)
-	ldh a, [hButtonsHeld]
+	ldh a, [hKeysHeld]
 	and D_PAD
 	jr z, .asm_c5bf
 	call Func_c5cb
@@ -704,7 +704,7 @@ Func_c5ac: ; c5ac (3:45ac)
 	and $1
 	jr nz, .asm_c5ca
 .asm_c5bf
-	ldh a, [hButtonsPressed]
+	ldh a, [hKeysPressed]
 	and A_BUTTON
 	jr z, .asm_c5ca
 	call Func_c71e
@@ -824,7 +824,7 @@ Func_c66c: ; c66c (3:466c)
 	push hl
 	push bc
 	ld c, $1
-	ldh a, [hButtonsHeld]
+	ldh a, [hKeysHeld]
 	bit B_BUTTON_F, a
 	jr z, .asm_c67e
 	ld a, [wd338]
@@ -1063,7 +1063,7 @@ PC_c7ea: ; c7ea (3:47ea)
 	call $4915
 	call DoFrameIfLCDEnabled
 	ldtx hl, TurnedPCOnText
-	call Func_2c73
+	call PrintScrollableText_NoTextBoxLabel
 	call $484e
 .asm_c801
 	ld a, $1
@@ -1121,7 +1121,7 @@ Func_c891: ; c891 (3:4891)
 	call Func_c241
 	call $4915
 	call DoFrameIfLCDEnabled
-	call Func_2c73
+	call PrintScrollableText_NoTextBoxLabel
 	ret
 
 Func_c8ba: ; c8ba (3:48ba)
@@ -1716,7 +1716,7 @@ Func_ccdc: ; ccdc (3:4cdc)
 
 Func_cce4: ; cce4 (3:4ce4)
 	ld a, $1
-	ld [wcd9a], a
+	ld [wDefaultYesOrNo], a
 
 ; Asks the player a question then jumps if they answer yes
 OWScript_AskQuestionJump: ; cce9 (3:4ce9)
diff --git a/src/engine/bank04.asm b/src/engine/bank04.asm
index 28108fb..6d29486 100644
--- a/src/engine/bank04.asm
+++ b/src/engine/bank04.asm
@@ -3,14 +3,14 @@ Func_10000: ; 10000 (4:4000)
 	ld [wTileMapFill], a
 	call EmptyScreen
 	call LoadSymbolsFont
-	ld de, $307f
-	call Func_2275
+	lb de, $30, $7f
+	call SetupText
 	call Set_OBJ_8x8
 	xor a
 	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
@@ -91,7 +91,7 @@ Medal_1029e: ; 1029e (4:429e)
 	cp $e0
 	jr nz, .asm_102e2
 	ldtx hl, WonTheMedalText
-	call Func_2c73
+	call PrintScrollableText_NoTextBoxLabel
 	call Func_3c96
 	call ResumeSong
 	pop af
@@ -148,11 +148,11 @@ BoosterPack_1031b: ; 1031b (4:431b)
 	jr nz, .asm_10373
 	ldtx hl, AndAnotherBoosterPackText
 .asm_10373
-	call Func_2c73
+	call PrintScrollableText_NoTextBoxLabel
 	call Func_3c96
 	call ResumeSong
 	ldtx hl, CheckedCardsInBoosterPackText
-	call Func_2c73
+	call PrintScrollableText_NoTextBoxLabel
 	call DisableLCD
 	call Func_1288c
 	call ZeroObjectPositions
@@ -223,7 +223,7 @@ Duel_Init: ; 103d3 (4:43d3)
 	lb bc, $2f, $1d ; cursor tile, tile behind cursor
 	lb de, 18, 17 ; x, y
 	call SetCursorParametersForTextBox
-	call WaitForButtonAorB ; wait for the user to press a or b
+	call WaitForButtonAorB
 	call Func_3c96
 	call Func_10ab4 ; fade out
 	pop af
@@ -361,7 +361,7 @@ Func_10e55: ; 10e55 (4:4e55)
 	ret
 
 Func_10e71: ; 10e71 (4:4e71)
-	ldh a, [hButtonsPressed]
+	ldh a, [hKeysPressed]
 	and D_PAD
 	jr z, .asm_10e83
 	farcall Func_c5d5
@@ -369,7 +369,7 @@ Func_10e71: ; 10e71 (4:4e71)
 	call Func_10e97
 	jr .asm_10e96
 .asm_10e83
-	ldh a, [hButtonsPressed]
+	ldh a, [hKeysPressed]
 	and A_BUTTON
 	jr z, .asm_10e96
 	ld a, $2
@@ -445,7 +445,7 @@ Func_10f2e: ; 10f2e (4:4f2e)
 	ld a, [hli]
 	ld h, [hl]
 	ld l, a
-	call Func_2c29
+	call ProcessTextFromID
 	pop de
 	pop hl
 	ret
@@ -1113,9 +1113,9 @@ MainMenu_NewGame: ; 12704 (4:6704)
 	call Func_128a9
 	farcall Func_1996e
 	call EnableSRAM
-	ld a, [sa007]
+	ld a, [s0a007]
 	ld [wd421], a
-	ld a, [sa006]
+	ld a, [s0a006]
 	ld [wTextSpeed], a
 	call DisableSRAM
 	ld a, MUSIC_STOP
@@ -1511,7 +1511,7 @@ Func_1344d: ; 1344d (4:744d)
 	ld a, MUSIC_MEDAL
 	call PlaySong
 	ldtx hl, DefeatedFiveOpponentsText
-	call Func_2c73
+	call PrintScrollableText_NoTextBoxLabel
 	call Func_3c96
 	call ResumeSong
 	ret
@@ -1533,7 +1533,7 @@ Func_13485: ; 13485 (4:7485)
 	ld a, MUSIC_MEDAL
 	call PlaySong
 	ldtx hl, ConsecutiveWinRecordIncreasedText
-	call Func_2c73
+	call PrintScrollableText_NoTextBoxLabel
 	call Func_3c96
 	call ResumeSong
 	ret
diff --git a/src/engine/bank05.asm b/src/engine/bank05.asm
index 0fd6f82..464ce48 100644
--- a/src/engine/bank05.asm
+++ b/src/engine/bank05.asm
@@ -222,8 +222,8 @@ Func_1468b: ; 1468b (5:468b)
 	ret
 ; 0x14786
 
-
 	INCROM $14786, $15636
+
 Func_15636: ; 15636 (5:5636)
 	ld a, $10
 	ld hl, wcda5
@@ -243,12 +243,12 @@ Func_15649: ; 15649 (5:5649)
 	ld [wcddb], a
 	ld [wcddc], a
 	ld [wce03], a
-	ld a, [wcc10]
+	ld a, [wPlayerAttackingMoveIndex]
 	cp $ff
 	jr z, .asm_156b1
 	or a
 	jr z, .asm_156b1
-	ld a, [wcc11]
+	ld a, [wPlayerAttackingCardIndex]
 	cp $ff
 	jr z, .asm_156b1
 	call SwapTurn
diff --git a/src/engine/bank06.asm b/src/engine/bank06.asm
index fc5e5c4..9cda475 100644
--- a/src/engine/bank06.asm
+++ b/src/engine/bank06.asm
@@ -147,6 +147,7 @@ Func_18086: ; 18086 (6:4086)
 	ret
 ; 0x180d5
 
+Func_180d5: ; 180d5 (6:40d5)
 	INCROM $180d5, $186f7
 
 INCLUDE "data/effect_commands.asm"
@@ -167,13 +168,13 @@ Func_1996e: ; 1996e (6:596e)
 	or b
 	jr nz, .asm_1997b
 	ld a, $5
-	ld hl, sa350
+	ld hl, s0a350
 	call Func_199e0
 	ld a, $7
-	ld hl, sa3a4
+	ld hl, s0a3a4
 	call Func_199e0
 	ld a, $9
-	ld hl, sa3f8
+	ld hl, s0a3f8
 	call Func_199e0
 	call EnableSRAM
 	ld hl, sCardCollection
@@ -196,16 +197,16 @@ Func_1996e: ; 1996e (6:596e)
 	dec c
 	jr nz, .asm_199b2
 	ld a, $2
-	ld [sa003], a
+	ld [s0a003], a
 	ld a, $2
-	ld [sa006], a
+	ld [s0a006], a
 	ld [wTextSpeed], a
 	xor a
-	ld [sa007], a
-	ld [sa009], a
-	ld [sa004], a
-	ld [sa005], a
-	ld [sa00a], a
+	ld [s0a007], a
+	ld [s0a009], a
+	ld [s0a004], a
+	ld [s0a005], a
+	ld [s0a00a], a
 	farcall Func_8cf9
 	call DisableSRAM
 	ret
@@ -261,8 +262,8 @@ Func_19a12: ; 19a12 (6:5a12)
 
 Func_1a61f: ; 1a61f (6:661f)
 	push af
-	ld de, $389f
-	call Func_2275
+	lb de, $38, $9f
+	call SetupText
 	pop af
 	or a
 	jr nz, .asm_1a640
diff --git a/src/engine/bank07.asm b/src/engine/bank07.asm
index 1ebffa2..dfae95a 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
@@ -367,7 +367,53 @@ Func_1c83d: ; 1c83d (7:483d)
 	ret
 ; 0x1c858
 
-	INCROM $1c858, $1d078
+	INCROM $1c858, $1cb18
+
+Func_1cb18: ; 1cb18 (7:4b18)
+	push hl
+	push bc
+	push de
+	ld a, [wDoFrameFunction]
+	cp LOW(Func_3ba2)
+	jr nz, .asm_1cb5b
+	ld a, [wDoFrameFunction + 1]
+	cp HIGH(Func_3ba2)
+	jr nz, .asm_1cb5b
+	ld a, $ff
+	ld [wd4c0], a
+	ld a, [wd42a]
+	cp $ff
+	call nz, $4cd4
+	ld hl, wd423
+	ld c, $07
+.asm_1cb3b
+	push bc
+	ld a, [hl]
+	cp $ff
+	jr z, .asm_1cb4b
+	ld [wWhichSprite], a
+	farcall $4, $69fa
+	ld a, $ff
+	ld [hl], a
+.asm_1cb4b
+	pop bc
+	inc hl
+	dec c
+	jr nz, .asm_1cb3b
+	xor a
+	ld [wd4ac], a
+	ld [wd4ad], a
+.asm_1cb57
+	pop de
+	pop bc
+	pop hl
+	ret
+.asm_1cb5b
+	scf
+	jr .asm_1cb57
+; 0x1cb5e
+
+	INCROM $1cb5e, $1d078
 
 Func_1d078: ; 1d078 (7:5078)
 	ld a, [wd627]
@@ -402,7 +448,7 @@ Func_1d078: ; 1d078 (7:5078)
 	dec [hl]
 	jr .asm_1d095
 .asm_1d0b8
-	ldh a, [hButtonsPressed]
+	ldh a, [hKeysPressed]
 	and A_BUTTON | START
 	jr z, .asm_1d095
 	ld a, $2
@@ -443,8 +489,8 @@ Func_1d11c: ; 1d11c (7:511c)
 	call PlaySong
 	call DisableLCD
 	farcall $4, $4000
-	ld de, $308f
-	call Func_2275
+	lb de, $30, $8f
+	call SetupText
 	call Func_3ca0
 	xor a
 	ld [wLineSeparation], a
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/effect_functions.asm b/src/engine/effect_functions.asm
index 0f9bd72..b3c707b 100644
--- a/src/engine/effect_functions.asm
+++ b/src/engine/effect_functions.asm
@@ -4,17 +4,17 @@ Poison50PercentEffect: ; 2c000 (b:4000)
 	ret nc
 
 PoisonEffect: ; 2c007 (b:4007)
-	lb bc, $0f, POISONED
+	lb bc, CNF_SLP_PRZ, POISONED
 	jr ApplyStatusEffect
 
-	lb bc, $0f, DOUBLE_POISONED
+	lb bc, CNF_SLP_PRZ, DOUBLE_POISONED
 	jr ApplyStatusEffect
 
 Paralysis50PercentEffect: ; 2c011 (b:4011)
 	ldtx de, ParalysisCheckText
 	call TossCoin_BankB
 	ret nc
-	lb bc, $f0, PARALYZED
+	lb bc, PSN_DBLPSN, PARALYZED
 	jr ApplyStatusEffect
 
 Confusion50PercentEffect: ; 2c01d (b:401d)
@@ -23,7 +23,7 @@ Confusion50PercentEffect: ; 2c01d (b:401d)
 	ret nc
 
 ConfusionEffect: ; 2c024 (b:4024)
-	lb bc, $f0, CONFUSED
+	lb bc, PSN_DBLPSN, CONFUSED
 	jr ApplyStatusEffect
 
 	ldtx de, SleepCheckText
@@ -31,12 +31,12 @@ ConfusionEffect: ; 2c024 (b:4024)
 	ret nc
 
 SleepEffect: ; 2c030 (b:4030)
-	lb bc, $f0, ASLEEP
+	lb bc, PSN_DBLPSN, ASLEEP
 	jr ApplyStatusEffect
 
 ApplyStatusEffect:
 	ldh a, [hWhoseTurn]
-	ld hl, wcc05
+	ld hl, wWhoseTurn
 	cp [hl]
 	jr nz, .can_induce_status
 	ld a, [wTempNonTurnDuelistCardID]
@@ -57,25 +57,26 @@ ApplyStatusEffect:
 .cant_induce_status
 	ld a, c
 	ld [wccf1], a
-	call Func_2c09c
+	call SetNoEffectFromStatus
 	or a
 	ret
 
 .can_induce_status
-	ld hl, wcccd
+	ld hl, wEffectFunctionsFeedbackIndex
 	push hl
 	ld e, [hl]
 	ld d, $0
-	ld hl, wccce
+	ld hl, wEffectFunctionsFeedback
 	add hl, de
 	call SwapTurn
 	ldh a, [hWhoseTurn]
 	ld [hli], a
 	call SwapTurn
-	ld [hl], b
+	ld [hl], b ; mask of status conditions not to discard on the target
 	inc hl
-	ld [hl], c
+	ld [hl], c ; status condition to inflict to the target
 	pop hl
+	; advance wEffectFunctionsFeedbackIndex
 	inc [hl]
 	inc [hl]
 	inc [hl]
@@ -97,32 +98,32 @@ CommentedOut_2c086: ; 2c086 (b:4086)
 	ret
 ; 0x2c087
 
-PlaceTextItems7: ; 2c087 (b:4087)
+Func_2c087: ; 2c087 (b:4087)
 	xor a
-	jr PlaceTextItemsc
+	jr Func_2c08c
 
-PlaceTextItemsa: ; 2c08a (b:408a)
+Func_2c08a: ; 2c08a (b:408a)
 	ld a, $1
 
-PlaceTextItemsc:
+Func_2c08c:
 	push de
 	push af
 	ld a, $11
-	call SetDuelAIAction
+	call SetAIAction_SerialSendDuelData
 	pop af
 	pop de
-	call Func_0fac
+	call SerialSend8Bytes
 	call TossCoinATimes
 	ret
 ; 0x2c09c
 
-Func_2c09c: ; 2c09c (b:409c)
+SetNoEffectFromStatus: ; 2c09c (b:409c)
 	ld a, $1
 	ld [wcced], a
 	ret
 ; 0x2c0a2
 
-Func_2c0a2: ; 2c0a2 (b:40a2)
+SetWasUnsuccessful: ; 2c0a2 (b:40a2)
 	ld a, $2
 	ld [wcced], a
 	ret
@@ -232,7 +233,7 @@ SpitPoison_Poison50PercentEffect: ; 2c6f8 (b:46f8)
 	jp c, PoisonEffect
 	ld a, $8c
 	ld [wLoadedMoveAnimation], a
-	call Func_2c09c
+	call SetNoEffectFromStatus
 	ret
 ; 0x2c70a
 
@@ -279,7 +280,7 @@ FoulOdorEffect: ; 2c793 (b:4793)
 KakunaStiffenEffect: ; 2c7a0 (b:47a0)
 	ldtx de, IfHeadsNoDamageNextTurnText
 	call TossCoin_BankB
-	jp nc, Func_2c0a2
+	jp nc, SetWasUnsuccessful
 	ld a, $4f
 	ld [wLoadedMoveAnimation], a
 	ld a, SUBSTATUS1_NO_DAMAGE_STIFFEN
@@ -306,7 +307,7 @@ SwordsDanceEffect: ; 2c7d0 (b:47d0)
 
 ZubatSupersonicEffect: ; 2c7dc (b:47dc)
 	call Confusion50PercentEffect
-	call nc, Func_2c09c
+	call nc, SetNoEffectFromStatus
 	ret
 ; 0x2c7e3
 
@@ -316,7 +317,7 @@ ZubatSupersonicEffect: ; 2c7dc (b:47dc)
 MetapodStiffenEffect: ; 2c836 (b:4836)
 	ldtx de, IfHeadsNoDamageNextTurnText
 	call TossCoin_BankB
-	jp nc, Func_2c0a2
+	jp nc, SetWasUnsuccessful
 	ld a, $4f
 	ld [wLoadedMoveAnimation], a
 	ld a, SUBSTATUS1_NO_DAMAGE_STIFFEN
diff --git a/src/engine/home.asm b/src/engine/home.asm
index a922861..0046286 100644
--- a/src/engine/home.asm
+++ b/src/engine/home.asm
@@ -6,11 +6,11 @@ SECTION "rst08", ROM0
 SECTION "rst10", ROM0
 	ret
 SECTION "rst18", ROM0
-	jp RST18
+	jp Bank1Call
 SECTION "rst20", ROM0
 	jp RST20
 SECTION "rst28", ROM0
-	jp RST28
+	jp FarCall
 SECTION "rst30", ROM0
 	ret
 SECTION "rst38", ROM0
@@ -43,7 +43,7 @@ Start: ; 0150 (0:0150)
 	ld [rIE], a
 	call ZeroRAM
 	ld a, $1
-	call BankswitchHome
+	call BankswitchROM
 	xor a
 	call BankswitchSRAM
 	call BankswitchVRAM0
@@ -51,21 +51,22 @@ 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
 	call ResetSerial
 	call CopyDMAFunction
-	call SetupExtRAM
+	call ValidateSRAM
 	ld a, BANK(GameLoop)
-	call BankswitchHome
+	call BankswitchROM
 	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,20 +99,21 @@ 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
+	call BankswitchROM
 	pop hl
 	pop de
 	pop bc
 	pop af
 	reti
 
+; timer interrupt handler
 TimerHandler: ; 01e6 (0:01e6)
 	push af
 	push hl
@@ -129,19 +131,19 @@ 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)
-	call BankswitchHome
+	call BankswitchROM
 	call SoundTimerHandler
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	; 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
@@ -430,7 +439,7 @@ SetupVRAM: ; 03a1 (0:03a1)
 	jr nz, .loop
 	ret
 
-; fill VRAM0 BG maps with [wTileMapFill] and VRAM1 BG Maps with 0
+; fill VRAM0 BG map 0 with [wTileMapFill] and VRAM1 BG map 0 with $00
 FillTileMap: ; 03c0 (0:03c0)
 	call BankswitchVRAM0
 	ld hl, v0BGMap0
@@ -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,27 @@ 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
+;	fallthrough
 
-SetFlushPalette0:
-	ld a, FLUSH_ONE
+; Flush non-CGB palettes and the first CGB palette
+FlushPalette0:
+	ld a, FLUSH_ONE_PAL
+;	fallthrough
 
-SetFlushPalettes:
+FlushPalettes:
 	ld [wFlushPaletteFlags], a
 	ld a, [wLCDC]
 	rla
@@ -505,7 +517,7 @@ SetFlushPalettes:
 	push hl
 	push de
 	push bc
-	call FlushPalettes
+	call FlushPalettesIfRequested
 	pop bc
 	pop de
 	pop hl
@@ -514,19 +526,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 +559,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 +576,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 +601,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,37 +615,42 @@ 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
 
+; initialize the screen by emptying the tilemap. used during screen transitions
 EmptyScreen: ; 04a2 (0:04a2)
 	call DisableLCD
 	call FillTileMap
 	xor a
-	ld [wcac2], a
+	ld [wDuelDisplayedScreen], a
 	ld a, [wConsole]
 	cp CONSOLE_SGB
 	ret nz
 	call EnableLCD
-	ld hl, AttrBlkPacket_04bf
+	ld hl, AttrBlkPacket_EmptyScreen
 	call SendSGB
 	call DisableLCD
 	ret
 
-AttrBlkPacket_04bf: ; 04bf (0:04bf)
+AttrBlkPacket_EmptyScreen: ; 04bf (0:04bf)
 	sgb ATTR_BLK, 1 ; sgb_command, length
 	db 1 ; number of data sets
 	; Control Code,  Color Palette Designation, X1, Y1, X2, Y2
@@ -658,16 +675,18 @@ BCCoordToBGMap0Address: ; 04cf (0:04cf)
 	ld d, h
 	ret
 
+; read joypad data to refresh hKeysHeld, hKeysPressed, and hKeysReleased
+; the A + B + Start + Select combination resets the game
 ReadJoypad: ; 04de (0:04de)
-	ld a, $20
+	ld a, JOY_BTNS_SELECT
 	ld [rJOYP], a
 	ld a, [rJOYP]
 	ld a, [rJOYP]
 	cpl
-	and $f
+	and JOY_INPUT_MASK
 	swap a
-	ld b, a
-	ld a, $10
+	ld b, a ; buttons data
+	ld a, JOY_DPAD_SELECT
 	ld [rJOYP], a
 	ld a, [rJOYP]
 	ld a, [rJOYP]
@@ -676,24 +695,24 @@ ReadJoypad: ; 04de (0:04de)
 	ld a, [rJOYP]
 	ld a, [rJOYP]
 	cpl
-	and $f
+	and JOY_INPUT_MASK
 	or b
-	ld c, a ; joypad data
+	ld c, a ; dpad data
 	cpl
-	ld b, a
-	ldh a, [hButtonsHeld]
+	ld b, a ; buttons data
+	ldh a, [hKeysHeld]
 	xor c
 	and b
-	ldh [hButtonsReleased], a
-	ldh a, [hButtonsHeld]
+	ldh [hKeysReleased], a
+	ldh a, [hKeysHeld]
 	xor c
 	and c
 	ld b, a
-	ldh [hButtonsPressed], a
-	ldh a, [hButtonsHeld]
+	ldh [hKeysPressed], a
+	ldh a, [hKeysHeld]
 	and BUTTONS
 	cp BUTTONS
-	jr nz, ReadJoypad_SaveButtonsHeld
+	jr nz, SaveButtonsHeld
 	; A + B + Start + Select: reset game
 	call ResetSerial
 ;	fallthrough
@@ -703,10 +722,10 @@ Reset: ; 051b (0:051b)
 	di
 	jp Start
 
-ReadJoypad_SaveButtonsHeld:
+SaveButtonsHeld:
 	ld a, c
-	ldh [hButtonsHeld], a
-	ld a, $30
+	ldh [hKeysHeld], a
+	ld a, JOY_BTNS_SELECT | JOY_DPAD_SELECT
 	ld [rJOYP], a
 	ret
 
@@ -715,11 +734,11 @@ ClearJoypad: ; 052a (0:052a)
 	push hl
 	ld hl, hDPadRepeat
 	xor a
-	ld [hli], a
-	ld [hli], a
-	ld [hli], a
-	ld [hli], a
-	ld [hli], a
+	ld [hli], a ; hDPadRepeat
+	ld [hli], a ; hKeysReleased
+	ld [hli], a ; hDPadHeld
+	ld [hli], a ; hKeysHeld
+	ld [hli], a ; hKeysPressed
 	pop hl
 	ret
 
@@ -734,7 +753,7 @@ DoAFrames: ; 0536 (0:0536)
 	ret
 
 ; updates background, sprites and other game variables, halts until vblank, and reads user input
-; if wcad5 is not 0, the game can be paused (and resumed) by pressing the select button
+; if wcad5 is not 0, the game can be paused (and resumed) by pressing the SELECT button
 DoFrame: ; 053f (0:053f)
 	push af
 	push hl
@@ -748,14 +767,14 @@ DoFrame: ; 053f (0:053f)
 	ld a, [wcad5]
 	or a
 	jr z, .done
-	ldh a, [hButtonsPressed]
+	ldh a, [hKeysPressed]
 	and SELECT
 	jr z, .done
 .game_paused_loop
 	call WaitForVBlank
 	call ReadJoypad
 	call HandleDPadRepeat
-	ldh a, [hButtonsPressed]
+	ldh a, [hKeysPressed]
 	and SELECT
 	jr z, .game_paused_loop
 .done
@@ -765,29 +784,31 @@ DoFrame: ; 053f (0:053f)
 	pop af
 	ret
 
-; handle D-pad repeatcounter
+; handle D-pad repeat counter
+; used to quickly scroll through menus when a relevant D-pad key is held
 HandleDPadRepeat: ; 0572 (0:0572)
-	ldh a, [hButtonsHeld]
-	ldh [hButtonsPressed2], a
+	ldh a, [hKeysHeld]
+	ldh [hDPadHeld], a
 	and D_PAD
-	jr z, .asm_58c
+	jr z, .done
 	ld hl, hDPadRepeat
-	ldh a, [hButtonsPressed]
+	ldh a, [hKeysPressed]
 	and D_PAD
-	jr z, .asm_586
+	jr z, .dpad_key_held
 	ld [hl], 24
 	ret
-.asm_586
+.dpad_key_held
 	dec [hl]
-	jr nz, .asm_58c
+	jr nz, .done
 	ld [hl], 6
 	ret
-.asm_58c
-	ldh a, [hButtonsPressed]
+.done
+	ldh a, [hKeysPressed]
 	and BUTTONS
-	ldh [hButtonsPressed2], a
+	ldh [hDPadHeld], a
 	ret
 
+; copy DMA to hDMAFunction
 CopyDMAFunction: ; 0593 (0:0593)
 	ld c, LOW(hDMAFunction)
 	ld b, JumpToFunctionInTable - DMA
@@ -841,16 +862,16 @@ CallHL: ; 05c1 (0:05c1)
 	jp hl
 ; 0x5c2
 
-; converts two one-digit numbers provided in a to text (ascii) format,
-; writes them to [wTextBuf] and [wTextBuf + 1], and to the BGMap0 address at bc
-WriteTwoOneDigitNumbers: ; 05c2 (0:05c2)
+; converts the two-digit BCD number provided in a to text (ascii) format,
+; writes them to [wStringBuffer] and [wStringBuffer + 1], and to the BGMap0 address at bc
+WriteTwoDigitBCDNumber: ; 05c2 (0:05c2)
 	push hl
 	push bc
 	push de
-	ld hl, wTextBuf
+	ld hl, wStringBuffer
 	push hl
 	push bc
-	call WriteNumbersInTextFormat
+	call WriteBCDNumberInTextFormat
 	pop bc
 	call BCCoordToBGMap0Address
 	pop hl
@@ -862,16 +883,16 @@ WriteTwoOneDigitNumbers: ; 05c2 (0:05c2)
 	ret
 ; 0x5db
 
-; converts a one-digit number provided in the lower nybble of a to text
-; (ascii) format, and writes it to [wTextBuf] and to the BGMap0 address at bc
-WriteOneDigitNumber: ; 05db (0:05db)
+; converts the one-digit BCD number provided in the lower nybble of a to text
+; (ascii) format, and writes it to [wStringBuffer] and to the BGMap0 address at bc
+WriteOneDigitBCDNumber: ; 05db (0:05db)
 	push hl
 	push bc
 	push de
-	ld hl, wTextBuf
+	ld hl, wStringBuffer
 	push hl
 	push bc
-	call WriteNumberInTextFormat
+	call WriteBCDDigitInTextFormat
 	pop bc
 	call BCCoordToBGMap0Address
 	pop hl
@@ -883,21 +904,21 @@ WriteOneDigitNumber: ; 05db (0:05db)
 	ret
 ; 0x5f4
 
-; converts four one-digit numbers provided in h and l to text (ascii) format,
-; writes them to [wTextBuf] through [wTextBuf + 3], and to the BGMap0 address at bc
-WriteFourOneDigitNumbers: ; 05f4 (0:05f4)
+; converts the four-digit BCD number provided in h and l to text (ascii) format,
+; writes them to [wStringBuffer] through [wStringBuffer + 3], and to the BGMap0 address at bc
+WriteFourDigitBCDNumber: ; 05f4 (0:05f4)
 	push hl
 	push bc
 	push de
 	ld e, l
 	ld d, h
-	ld hl, wTextBuf
+	ld hl, wStringBuffer
 	push hl
 	push bc
 	ld a, d
-	call WriteNumbersInTextFormat
+	call WriteBCDNumberInTextFormat
 	ld a, e
-	call WriteNumbersInTextFormat
+	call WriteBCDNumberInTextFormat
 	pop bc
 	call BCCoordToBGMap0Address
 	pop hl
@@ -909,20 +930,19 @@ WriteFourOneDigitNumbers: ; 05f4 (0:05f4)
 	ret
 ; 0x614
 
-; given two one-digit numbers in the two nybbles of register a,
+; given two BCD digits in the two nybbles of register a,
 ; write them in text (ascii) format to hl (most significant nybble first).
 ; numbers above 9 end up converted to half-width font tiles.
-WriteNumbersInTextFormat: ; 0614 (0:0614)
+WriteBCDNumberInTextFormat: ; 0614 (0:0614)
 	push af
 	swap a
-	call WriteNumberInTextFormat
+	call WriteBCDDigitInTextFormat
 	pop af
 ;	fallthrough
 
-; given a one-digit number in the (lower nybble) of register a,
-; write it in text (ascii) format to hl.
-; numbers above 9 end up converted to half-width font tiles.
-WriteNumberInTextFormat:
+; given a BCD digit in the (lower nybble) of register a, write it in text (ascii)
+;  format to hl. numbers above 9 end up converted to half-width font tiles.
+WriteBCDDigitInTextFormat:
 	and $0f
 	add "0"
 	cp "9" + 1
@@ -934,13 +954,13 @@ WriteNumberInTextFormat:
 ; 0x627
 
 ; converts the one-byte number at a to text (ascii) format,
-; and writes it to [wTextBuf] and the BGMap0 address at bc
+; and writes it to [wStringBuffer] and the BGMap0 address at bc
 WriteOneByteNumber: ; 0627 (0:0627)
 	push bc
 	push hl
 	ld l, a
 	ld h, $00
-	ld de, wTextBuf
+	ld de, wStringBuffer
 	push de
 	push bc
 	ld bc, -100
@@ -960,10 +980,10 @@ WriteOneByteNumber: ; 0627 (0:0627)
 ; 0x650
 
 ; converts the two-byte number at hl to text (ascii) format,
-; and writes it to [wTextBuf] and the BGMap0 address at bc
+; and writes it to [wStringBuffer] and the BGMap0 address at bc
 WriteTwoByteNumber: ; 0650 (0:0650)
 	push bc
-	ld de, wTextBuf
+	ld de, wStringBuffer
 	push de
 	call TwoByteNumberToText
 	call BCCoordToBGMap0Address
@@ -1167,6 +1187,7 @@ CopyGfxData: ; 070c (0:070c)
 	jr nz, .next_tile
 	ret
 
+; copy bc bytes from hl to de. preserves all regsters except af
 CopyDataHLtoDE_SaveRegisters: ; 0732 (0:0732)
 	push hl
 	push de
@@ -1177,7 +1198,7 @@ CopyDataHLtoDE_SaveRegisters: ; 0732 (0:0732)
 	pop hl
 	ret
 
-; copies bc bytes from hl to de
+; copy bc bytes from hl to de
 CopyDataHLtoDE: ; 073c (0:073c)
 	ld a, [hli]
 	ld [de], a
@@ -1188,10 +1209,10 @@ CopyDataHLtoDE: ; 073c (0:073c)
 	jr nz, CopyDataHLtoDE
 	ret
 
-; switch to rombank (A + top2 of H shifted down),
-; set top2 of H to 01 (switchable ROM bank area),
+; switch to rombank (a + top2 of h shifted down),
+; set top2 of h to 01 (switchable ROM bank area),
 ; return old rombank id on top-of-stack
-BankpushHome: ; 0745 (0:0745)
+BankpushROM: ; 0745 (0:0745)
 	push hl
 	push bc
 	push af
@@ -1222,14 +1243,14 @@ BankpushHome: ; 0745 (0:0745)
 	pop de
 	pop af
 	add b
-	call BankswitchHome
+	call BankswitchROM
 	pop bc
 	ret
 ; 0x76f
 
-; switch to rombank A,
+; switch to rombank a,
 ; return old rombank id on top-of-stack
-BankpushHome2: ; 076f (0:076f)
+BankpushROM2: ; 076f (0:076f)
 	push hl
 	push bc
 	push af
@@ -1252,18 +1273,18 @@ BankpushHome2: ; 076f (0:076f)
 	ld h, d
 	pop de
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	pop bc
 	ret
 ; 0x78e
 
 ; restore rombank from top-of-stack
-BankpopHome: ; 078e (0:078e)
+BankpopROM: ; 078e (0:078e)
 	push hl
 	push de
 	ld hl, sp+$7
 	ld a, [hld]
-	call BankswitchHome
+	call BankswitchROM
 	dec hl
 	ld d, [hl]
 	dec hl
@@ -1278,13 +1299,13 @@ BankpopHome: ; 078e (0:078e)
 	pop af
 	ret
 
-; switch ROM bank
-BankswitchHome: ; 07a3 (0:07a3)
+; switch ROM bank to a
+BankswitchROM: ; 07a3 (0:07a3)
 	ldh [hBankROM], a
 	ld [MBC3RomBank], a
 	ret
 
-; switch SRAM bank
+; switch SRAM bank to a
 BankswitchSRAM: ; 07a9 (0:07a9)
 	push af
 	ldh [hBankSRAM], a
@@ -1294,7 +1315,7 @@ BankswitchSRAM: ; 07a9 (0:07a9)
 	pop af
 	ret
 
-; enable external RAM
+; enable external RAM (SRAM)
 EnableSRAM: ; 07b6 (0:07b6)
 	push af
 	ld a, SRAM_ENABLE
@@ -1302,7 +1323,7 @@ EnableSRAM: ; 07b6 (0:07b6)
 	pop af
 	ret
 
-; disable external RAM
+; disable external RAM (SRAM)
 DisableSRAM: ; 07be (0:07be)
 	push af
 	xor a ; SRAM_DISABLE
@@ -1328,14 +1349,14 @@ BankswitchVRAM1: ; 07cd (0:07cd)
 	pop af
 	ret
 
-; set current dest VRAM bank
-; a: value to write
+; set current dest VRAM bank to a
 BankswitchVRAM: ; 07d6 (0:07d6)
 	ldh [hBankVRAM], a
 	ld [rVBK], a
 	ret
 ; 0x7db
 
+; switch to CGB Normal Speed Mode if playing on CGB and current mode is Double Speed Mode
 SwitchToCGBNormalSpeed: ; 7db (0:7db)
 	call CheckForCGB
 	ret c
@@ -1344,6 +1365,7 @@ SwitchToCGBNormalSpeed: ; 7db (0:7db)
 	ret z
 	jr CGBSpeedSwitch
 
+; switch to CGB Double Speed Mode if playing on CGB and current mode is Normal Speed Mode
 SwitchToCGBDoubleSpeed: ; 07e7 (0:07e7)
 	call CheckForCGB
 	ret c
@@ -1352,6 +1374,7 @@ SwitchToCGBDoubleSpeed: ; 07e7 (0:07e7)
 	ret nz
 ;	fallthrough
 
+; switch between CGB Double Speed Mode and Normal Speed Mode
 CGBSpeedSwitch: ; 07f1 (0:07f1)
 	ld a, [rIE]
 	push af
@@ -1369,74 +1392,78 @@ CGBSpeedSwitch: ; 07f1 (0:07f1)
 	ld [rIE], a
 	ret
 
-SetupExtRAM: ; 080b (0:080b)
+; validate the saved data in SRAM
+; it must contain with the sequence $04, $21, $05 at s0a000
+ValidateSRAM: ; 080b (0:080b)
 	xor a
 	call BankswitchSRAM
-	ld hl, sa000
-	ld bc, $1000
-.asm_815
+	ld hl, $a000
+	ld bc, $2000 / 2
+.check_pattern_loop
 	ld a, [hli]
 	cp $41
-	jr nz, .asm_82f
+	jr nz, .check_sequence
 	ld a, [hli]
 	cp $93
-	jr nz, .asm_82f
+	jr nz, .check_sequence
 	dec bc
 	ld a, c
 	or b
-	jr nz, .asm_815
-	call Func_084d
+	jr nz, .check_pattern_loop
+	call RestartSRAM
 	scf
 	call Func_4050
 	call DisableSRAM
 	ret
-.asm_82f
-	ld hl, sa000
+.check_sequence
+	ld hl, s0a000
 	ld a, [hli]
-	cp $4
-	jr nz, .asm_842
+	cp $04
+	jr nz, .restart_sram
 	ld a, [hli]
 	cp $21
-	jr nz, .asm_842
+	jr nz, .restart_sram
 	ld a, [hl]
-	cp $5
-	jr nz, .asm_842
+	cp $05
+	jr nz, .restart_sram
 	ret
-.asm_842
-	call Func_084d
+.restart_sram
+	call RestartSRAM
 	or a
 	call Func_4050
 	call DisableSRAM
 	ret
 
-Func_084d: ; 084d (0:084d)
+; zero all SRAM banks and set s0a000 to $04, $21, $05
+RestartSRAM: ; 084d (0:084d)
 	ld a, 3
 .clear_loop
-	call ClearExtRAMBank
+	call ClearSRAMBank
 	dec a
 	cp -1
 	jr nz, .clear_loop
-	ld hl, sa000
-	ld [hl], $4
+	ld hl, s0a000
+	ld [hl], $04
 	inc hl
 	ld [hl], $21
 	inc hl
-	ld [hl], $5
+	ld [hl], $05
 	ret
 
-ClearExtRAMBank: ; 0863 (0:0863)
+; zero the loaded SRAM bank
+ClearSRAMBank: ; 0863 (0:0863)
 	push af
 	call BankswitchSRAM
 	call EnableSRAM
 	ld hl, $a000
 	ld bc, $2000
-.asm_870
+.loop
 	xor a
 	ld [hli], a
 	dec bc
 	ld a, c
 	or b
-	jr nz, .asm_870
+	jr nz, .loop
 	pop af
 	ret
 
@@ -1474,6 +1501,7 @@ Random: ; 088f (0:088f)
 	ret
 ; 0x89b
 
+; get the next random numbers of the wRNG1 and wRNG2 sequences
 UpdateRNGSources: ; 089b (0:089b)
 	push hl
 	push de
@@ -1718,10 +1746,10 @@ ZeroObjectPositions: ; 099c (0:099c)
 	jr nz, .loop
 	ret
 
-; this function affects the stack so that it returns
-; to the pointer following the rst call
-; similar to rst 28, except this always loads bank 1
-RST18: ; 09ae (0:09ae)
+; RST18
+; this function affects the stack so that it returns to the pointer following
+; the rst call. similar to rst 28, except this always loads bank 1
+Bank1Call: ; 09ae (0:09ae)
 	push hl
 	push hl
 	push hl
@@ -1749,8 +1777,9 @@ RST18: ; 09ae (0:09ae)
 	ld [hl], a
 	ld a, $1
 ;	fallthrough
-Func_09ce: ; 09ce (0:09ce)
-	call BankswitchHome
+
+Bank1Call_FarCall_Common: ; 09ce (0:09ce)
+	call BankswitchROM
 	ld hl, sp+$d
 	inc de
 	inc de
@@ -1763,12 +1792,13 @@ Func_09ce: ; 09ce (0:09ce)
 	ret
 ; 0x9dc
 
+; switch to the ROM bank at sp+4
 SwitchToBankAtSP: ; 9dc (0:9dc)
 	push af
 	push hl
 	ld hl, sp+$04
 	ld a, [hl]
-	call BankswitchHome
+	call BankswitchROM
 	pop hl
 	pop af
 	inc sp
@@ -1776,9 +1806,10 @@ SwitchToBankAtSP: ; 9dc (0:9dc)
 	ret
 ; 0x9e9
 
+; RST28
 ; this function affects the stack so that it returns
 ; to the three byte pointer following the rst call
-RST28: ; 09e9 (0:09e9)
+FarCall: ; 09e9 (0:09e9)
 	push hl
 	push hl
 	push hl
@@ -1808,65 +1839,81 @@ RST28: ; 09e9 (0:09e9)
 	dec de
 	ld a, [de]
 	inc de
-	jr Func_09ce
+	jr Bank1Call_FarCall_Common
 
 ; setup SNES memory $810-$867 and palette
 InitSGB: ; 0a0d (0:0a0d)
 	ld hl, MaskEnPacket_Freeze
 	call SendSGB
-	ld hl, DataSndPacket_0a50
+	ld hl, DataSndPacket1
 	call SendSGB
-	ld hl, DataSndPacket_0a60
+	ld hl, DataSndPacket2
 	call SendSGB
-	ld hl, DataSndPacket_0a70
+	ld hl, DataSndPacket3
 	call SendSGB
-	ld hl, DataSndPacket_0a80
+	ld hl, DataSndPacket4
 	call SendSGB
-	ld hl, DataSndPacket_0a90
+	ld hl, DataSndPacket5
 	call SendSGB
-	ld hl, DataSndPacket_0aa0
+	ld hl, DataSndPacket6
 	call SendSGB
-	ld hl, DataSndPacket_0ab0
+	ld hl, DataSndPacket7
 	call SendSGB
-	ld hl, DataSndPacket_0ac0
+	ld hl, DataSndPacket8
 	call SendSGB
-	ld hl, Pal01Packet
+	ld hl, Pal01Packet_InitSGB
 	call SendSGB
 	ld hl, MaskEnPacket_Cancel
 	call SendSGB
 	ret
 
-DataSndPacket_0a50: ; 0a50 (0:0a50)
+DataSndPacket1: ; 0a50 (0:0a50)
 	sgb DATA_SND, 1 ; sgb_command, length
-	db $5d,$08,$00,$0b,$8c,$d0,$f4,$60,$00,$00,$00,$00,$00,$00,$00
+	dwb $085d, $00 ; destination address, bank
+	db $0b ; number of bytes to write
+	db $8c, $d0, $f4, $60, $00, $00, $00, $00, $00, $00, $00 ; data bytes
 
-DataSndPacket_0a60: ; 0a60 (0:0a60)
+DataSndPacket2: ; 0a60 (0:0a60)
 	sgb DATA_SND, 1 ; sgb_command, length
-	db $52,$08,$00,$0b,$a9,$e7,$9f,$01,$c0,$7e,$e8,$e8,$e8,$e8,$e0
+	dwb $0852, $00 ; destination address, bank
+	db $0b ; number of bytes to write
+	db $a9, $e7, $9f, $01, $c0, $7e, $e8, $e8, $e8, $e8, $e0 ; data bytes
 
-DataSndPacket_0a70: ; 0a70 (0:0a70)
+DataSndPacket3: ; 0a70 (0:0a70)
 	sgb DATA_SND, 1 ; sgb_command, length
-	db $47,$08,$00,$0b,$c4,$d0,$16,$a5,$cb,$c9,$05,$d0,$10,$a2,$28
+	dwb $0847, $00 ; destination address, bank
+	db $0b ; number of bytes to write
+	db $c4, $d0, $16, $a5, $cb, $c9, $05, $d0, $10, $a2, $28 ; data bytes
 
-DataSndPacket_0a80: ; 0a80 (0:0a80)
+DataSndPacket4: ; 0a80 (0:0a80)
 	sgb DATA_SND, 1 ; sgb_command, length
-	db $3c,$08,$00,$0b,$f0,$12,$a5,$c9,$c9,$c8,$d0,$1c,$a5,$ca,$c9
+	dwb $083c, $00 ; destination address, bank
+	db $0b ; number of bytes to write
+	db $f0, $12, $a5, $c9, $c9, $c8, $d0, $1c, $a5, $ca, $c9 ; data bytes
 
-DataSndPacket_0a90: ; 0a90 (0:0a90)
+DataSndPacket5: ; 0a90 (0:0a90)
 	sgb DATA_SND, 1 ; sgb_command, length
-	db $31,$08,$00,$0b,$0c,$a5,$ca,$c9,$7e,$d0,$06,$a5,$cb,$c9,$7e
+	dwb $0831, $00 ; destination address, bank
+	db $0b ; number of bytes to write
+	db $0c, $a5, $ca, $c9, $7e, $d0, $06, $a5, $cb, $c9, $7e ; data bytes
 
-DataSndPacket_0aa0: ; 0aa0 (0:0aa0)
+DataSndPacket6: ; 0aa0 (0:0aa0)
 	sgb DATA_SND, 1 ; sgb_command, length
-	db $26,$08,$00,$0b,$39,$cd,$48,$0c,$d0,$34,$a5,$c9,$c9,$80,$d0
+	dwb $0826, $00 ; destination address, bank
+	db $0b ; number of bytes to write
+	db $39, $cd, $48, $0c, $d0, $34, $a5, $c9, $c9, $80, $d0 ; data bytes
 
-DataSndPacket_0ab0: ; 0ab0 (0:0ab0)
+DataSndPacket7: ; 0ab0 (0:0ab0)
 	sgb DATA_SND, 1 ; sgb_command, length
-	db $1b,$08,$00,$0b,$ea,$ea,$ea,$ea,$ea,$a9,$01,$cd,$4f,$0c,$d0
+	dwb $081b, $00 ; destination address, bank
+	db $0b ; number of bytes to write
+	db $ea, $ea, $ea, $ea, $ea, $a9, $01, $cd, $4f, $0c, $d0 ; data bytes
 
-DataSndPacket_0ac0: ; 0ac0 (0:0ac0)
+DataSndPacket8: ; 0ac0 (0:0ac0)
 	sgb DATA_SND, 1 ; sgb_command, length
-	db $10,$08,$00,$0b,$4c,$20,$08,$ea,$ea,$ea,$ea,$ea,$60,$ea,$ea
+	dwb $0810, $00 ; destination address, bank
+	db $0b ; number of bytes to write
+	db $4c, $20, $08, $ea, $ea, $ea, $ea, $ea, $60, $ea, $ea ; data bytes
 
 MaskEnPacket_Freeze: ; 0ad0 (0:0ad0)
 	sgb MASK_EN, 1 ; sgb_command, length
@@ -1878,7 +1925,7 @@ MaskEnPacket_Cancel: ; 0ae0 (0:0ae0)
 	db MASK_EN_CANCEL_MASK
 	ds $0e
 
-Pal01Packet: ; 0af0 (0:0af0)
+Pal01Packet_InitSGB: ; 0af0 (0:0af0)
 	sgb PAL01, 1 ; sgb_command, length
 	rgb 28, 28, 24
 	rgb 20, 20, 16
@@ -1889,7 +1936,7 @@ Pal01Packet: ; 0af0 (0:0af0)
 	rgb 7, 0, 0
 	db $00
 
-Pal23Packet: ; 0b00 (0:0b00)
+Pal23Packet_0b00: ; 0b00 (0:0b00)
 	sgb PAL23, 1 ; sgb_command, length
 	rgb 0, 31, 0
 	rgb 0, 15, 0
@@ -1908,65 +1955,67 @@ AttrBlkPacket_0b10: ; 0b10 (0:0b10)
 	ds 6 ; data set 2
 	ds 2 ; data set 3
 
-; send SGB command
+; send SGB packet at hl (or packets, if length > 1)
 SendSGB: ; 0b20 (0:0b20)
 	ld a, [hl]
 	and $7
-	ret z
-	ld b, a
-	ld c, $0
-.asm_b27
+	ret z ; return if packet length is 0
+	ld b, a ; length (1-7)
+	ld c, LOW(rJOYP)
+.send_packets_loop
 	push bc
 	ld a, $0
 	ld [$ff00+c], a
-	ld a, $30
+	ld a, P15 | P14
 	ld [$ff00+c], a
-	ld b, $10
-.asm_b30
+	ld b, SGB_PACKET_SIZE
+.send_packet_loop
 	ld e, $8
 	ld a, [hli]
 	ld d, a
-.asm_b34
+.read_byte_loop
 	bit 0, d
-	ld a, $10
-	jr nz, .asm_b3c
-	ld a, $20
-.asm_b3c
+	ld a, P14 ; '1' bit
+	jr nz, .transfer_bit
+	ld a, P15 ; '0' bit
+.transfer_bit
 	ld [$ff00+c], a
-	ld a, $30
+	ld a, P15 | P14
 	ld [$ff00+c], a
 	rr d
 	dec e
-	jr nz, .asm_b34
+	jr nz, .read_byte_loop
 	dec b
-	jr nz, .asm_b30
-	ld a, $20
+	jr nz, .send_packet_loop
+	ld a, P15 ; stop bit
 	ld [$ff00+c], a
-	ld a, $30
+	ld a, P15 | P14
 	ld [$ff00+c], a
 	pop bc
 	dec b
-	jr nz, .asm_b27
+	jr nz, .send_packets_loop
 	ld bc, 4
 	call Wait
 	ret
 
+; SGB hardware detection
+; return carry if SGB detected and disable multi-controller mode before returning
 DetectSGB: ; 0b59 (0:0b59)
 	ld bc, 60
 	call Wait
 	ld hl, MltReq2Packet
 	call SendSGB
 	ld a, [rJOYP]
-	and $3
-	cp $3
+	and %11
+	cp SNES_JOYPAD1
 	jr nz, .sgb
-	ld a, $20
+	ld a, P15
 	ld [rJOYP], a
 	ld a, [rJOYP]
 	ld a, [rJOYP]
-	ld a, $30
+	ld a, P15 | P14
 	ld [rJOYP], a
-	ld a, $10
+	ld a, P14
 	ld [rJOYP], a
 	ld a, [rJOYP]
 	ld a, [rJOYP]
@@ -1974,14 +2023,14 @@ DetectSGB: ; 0b59 (0:0b59)
 	ld a, [rJOYP]
 	ld a, [rJOYP]
 	ld a, [rJOYP]
-	ld a, $30
+	ld a, P15 | P14
 	ld [rJOYP], a
 	ld a, [rJOYP]
 	ld a, [rJOYP]
 	ld a, [rJOYP]
 	ld a, [rJOYP]
-	and $3
-	cp $3
+	and %11
+	cp SNES_JOYPAD1
 	jr nz, .sgb
 	ld hl, MltReq1Packet
 	call SendSGB
@@ -2003,6 +2052,9 @@ MltReq2Packet: ; 0bbb (0:0bbb)
 	db MLT_REQ_2_PLAYERS
 	ds $0e
 
+; fill v*Tiles1 and v*Tiles2 with data at hl
+; write $0d sequences of $80,$81,$82,...,$94 separated each by $0c bytes to v*BGMap0
+; send the SGB packet at de
 Func_0bcb: ; 0bcb (0:0bcb)
 	di
 	push de
@@ -2010,35 +2062,35 @@ 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
 	ld de, v0Tiles1
 	ld bc, v0BGMap0 - v0Tiles1
-.loop
+.tiles_loop
 	ld a, [hli]
 	ld [de], a
 	inc de
 	dec bc
 	ld a, b
 	or c
-	jr nz, .loop
+	jr nz, .tiles_loop
 	ld hl, v0BGMap0
 	ld de, $000c
 	ld a, $80
-	ld c, $d
-.asm_bf3
+	ld c, $0d
+.bgmap_outer_loop
 	ld b, $14
-.asm_bf5
+.bgmap_inner_loop
 	ld [hli], a
 	inc a
 	dec b
-	jr nz, .asm_bf5
+	jr nz, .bgmap_inner_loop
 	add hl, de
 	dec c
-	jr nz, .asm_bf3
-	ld a, $c3
+	jr nz, .bgmap_outer_loop
+	ld a, LCDC_BGON | LCDC_OBJON | LCDC_WIN9C00 | LCDC_ON
 	ld [rLCDC], a
 	pop hl
 	call SendSGB
@@ -2070,12 +2122,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 +2143,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
@@ -2109,7 +2161,7 @@ HblankCopyDataDEtoHL: ; 0c32 (0:0c32)
 ; 0xc4b
 
 ; returns a *= 10
-Func_0c4b: ; 0c4b (0:0c4b)
+ATimes10: ; 0c4b (0:0c4b)
 	push de
 	ld e, a
 	add a
@@ -2121,7 +2173,7 @@ Func_0c4b: ; 0c4b (0:0c4b)
 ; 0xc53
 
 ; returns hl *= 10
-Func_0c53: ; 0c53 (0:0c53)
+HLTimes10: ; 0c53 (0:0c53)
 	push de
 	ld l, a
 	ld e, a
@@ -2137,7 +2189,7 @@ Func_0c53: ; 0c53 (0:0c53)
 
 ; returns a /= 10
 ; returns carry if a % 10 >= 5
-Func_0c5f: ; 0c5f (0:0c5f)
+ADividedBy10: ; 0c5f (0:0c5f)
 	push de
 	ld e, -1
 .asm_c62
@@ -2209,9 +2261,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
@@ -2222,15 +2274,15 @@ SerialTimerHandler: ; 0c91 (0:0c91)
 	cp [hl]
 	ld [hl], a
 	ld hl, wSerialTimeoutCounter
-	jr nz, .clear_counter
+	jr nz, .clear_timeout_counter
 	inc [hl]
 	ld a, [hl]
-	cp $4
+	cp 4
 	ret c
 	ld hl, wSerialFlags
 	set 7, [hl]
 	ret
-.clear_counter
+.clear_timeout_counter
 	ld [hl], $0
 	ret
 ; 0xcc5
@@ -2253,9 +2305,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]
@@ -2308,7 +2360,7 @@ SerialHandler: ; 0d26 (0:0d26)
 .asm_d35
 	ld a, [wSerialOp]    ;
 	or a                 ;
-	jr z, .asm_d55       ; skip ahead if [wcb74] zero
+	jr z, .asm_d55       ; skip ahead if [wSerialOp] zero
 	; send/receive a byte
 	ld a, [rSB]
 	call SerialHandleRecv
@@ -2323,8 +2375,8 @@ SerialHandler: ; 0d26 (0:0d26)
 	ld [rSB], a          ; prepare sending byte (from Func_0dc8?)
 	ld a, [wSerialOp]
 	cp $29
-	jr z, .done          ; if [wcb74] != $29, use external clock
-	jr .asm_d6a          ; and prepare for next byte.  either way, return
+	jr z, .done          ; if [wSerialOp] != $29, use external clock
+	jr .asm_d6a          ; and prepare for next byte. either way, return
 .asm_d55
 	ld a, $1
 	ld [wSerialRecvCounter], a
@@ -2334,9 +2386,9 @@ SerialHandler: ; 0d26 (0:0d26)
 	ld [rSB], a
 	ld a, [wSerialRecvBuf]
 	cp $12               ; if [wSerialRecvBuf] != $12, use external clock
-	jr z, .done          ; and prepare for next byte.  either way, return
+	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
@@ -2460,8 +2512,8 @@ SerialHandleSend: ; 0dc8 (0:0dc8)
 	ld a, $ca
 	ret
 
-; store data in sendbuf for sending?
-Func_0e0a: ; 0e0a (0:0e0a)
+; store byte at a in wSerialSendBuf for sending
+SerialSendByte: ; 0e0a (0:0e0a)
 	push hl
 	push de
 	push bc
@@ -2498,7 +2550,8 @@ Func_0e32: ; 0e32 (0:0e32)
 	scf
 	ret
 
-Func_0e39: ; 0e39 (0:0e39)
+; receive byte in wSerialRecvBuf
+SerialRecvByte: ; 0e39 (0:0e39)
 	push hl
 	ld hl, wSerialRecvCounter
 	ld a, [hl]
@@ -2530,7 +2583,8 @@ Func_0e39: ; 0e39 (0:0e39)
 	or a
 	ret
 
-Func_0e63: ; 0e63 (0:0e63)
+; exchange c bytes. send bytes at hl and store received bytes in de
+SerialExchangeBytes: ; 0e63 (0:0e63)
 	ld b, c
 .asm_e64
 	ld a, b
@@ -2543,13 +2597,13 @@ Func_0e63: ; 0e63 (0:0e63)
 	dec c
 	jr z, .asm_e75
 	ld a, [hli]
-	call Func_0e0a
+	call SerialSendByte
 	dec c
 .asm_e75
 	inc b
 	dec b
 	jr z, .asm_e81
-	call Func_0e39
+	call SerialRecvByte
 	jr c, .asm_e81
 	ld [de], a
 	inc de
@@ -2571,27 +2625,30 @@ 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
 
+; disable serial interrupt, and clear rSB, rSC, and serial registers in WRAM
 ResetSerial: ; 0ea6 (0:0ea6)
 	ld a, [rIE]
-	and $f7
+	and ~(1 << INT_SERIAL)
 	ld [rIE], a
 	xor a
 	ld [rSB], a
 	ld [rSC], a
 ;	fallthrough
+
+; zero serial registers in WRAM
 ClearSerialData: ; 0eb1 (0:0eb1)
 	ld hl, wSerialOp
-	ld bc, $0051
+	ld bc, wSerialEnd - wSerialOp
 .loop
 	xor a
 	ld [hli], a
@@ -2601,48 +2658,50 @@ ClearSerialData: ; 0eb1 (0:0eb1)
 	jr nz, .loop
 	ret
 
-Func_0ebf: ; 0ebf (0:0ebf)
+; store bc bytes from hl in wSerialSendBuf for sending
+SerialSendBytes: ; 0ebf (0:0ebf)
 	push bc
-.asm_ec0
+.send_loop
 	ld a, [hli]
-	call Func_0e0a
+	call SerialSendByte
 	ld a, [wSerialFlags]
 	or a
-	jr nz, .asm_ed2
+	jr nz, .done
 	dec bc
 	ld a, c
 	or b
-	jr nz, .asm_ec0
+	jr nz, .send_loop
 	pop bc
 	or a
 	ret
-.asm_ed2
+.done
 	pop bc
 	scf
 	ret
 ; 0xed5
 
-Func_0ed5: ; 0ed5 (0:0ed5)
+; receive bc bytes in wSerialRecvBuf and save them to hl
+SerialRecvBytes: ; 0ed5 (0:0ed5)
 	push bc
-.asm_ed6
-	call Func_0e39
-	jr nc, .asm_edf
+.recv_loop
+	call SerialRecvByte
+	jr nc, .save_byte
 	halt
 	nop
-	jr .asm_ed6
-.asm_edf
+	jr .recv_loop
+.save_byte
 	ld [hli], a
 	ld a, [wSerialFlags]
 	or a
-	jr nz, .asm_eee
+	jr nz, .done
 	dec bc
 	ld a, c
 	or b
-	jr nz, .asm_ed6
+	jr nz, .recv_loop
 	pop bc
 	or a
 	ret
-.asm_eee
+.done
 	pop bc
 	scf
 	ret
@@ -2697,7 +2756,7 @@ Func_0f1d: ; 0f1d (0:0f1d)
 	ret nc
 .asm_f27
 	ld a, $01
-	call BankswitchHome
+	call BankswitchROM
 	ld hl, wcbf7
 	ld a, [hli]
 	ld h, [hl]
@@ -2707,6 +2766,8 @@ Func_0f1d: ; 0f1d (0:0f1d)
 	ret
 ; 0xf35
 
+; load the number at wSerialFlags (error code?) to TxRam3, print
+; TransmissionErrorText, exit the duel, and reset serial registers.
 DuelTransmissionError: ; 0f35 (0:0f35)
 	ld a, [wSerialFlags]
 	ld l, a
@@ -2726,31 +2787,35 @@ DuelTransmissionError: ; 0f35 (0:0f35)
 	call ResetSerial
 	ret
 
-Func_0f58: ; 0f58 (0:0f58)
+; exchange RNG during a link duel between both games
+ExchangeRNG: ; 0f58 (0:0f58)
 	ld a, [wDuelType]
 	cp DUELTYPE_LINK
-	jr z, .asm_f60
+	jr z, .link_duel
 	ret
-.asm_f60
+.link_duel
 	ld a, DUELVARS_DUELIST_TYPE
 	call GetTurnDuelistVariable
 	or a ; cp DUELIST_TYPE_PLAYER
-	jr z, .asm_f70
-	ld hl, wcbe2
+	jr z, .player_turn
+; link opponent's turn
+	ld hl, wOppRNG1
 	ld de, wRNG1
-	jr .asm_f76
-.asm_f70
+	jr .exchange
+.player_turn
 	ld hl, wRNG1
-	ld de, wcbe2
-.asm_f76
-	ld c, $3
-	call Func_0e63
+	ld de, wOppRNG1
+.exchange
+	ld c, 3 ; wRNG1, wRNG2, and wRNGCounter
+	call SerialExchangeBytes
 	jp c, DuelTransmissionError
 	ret
 
-; sets hAIActionTableIndex to an AI action specified in register a
-; also appears to handle sending data in a link duel
-SetDuelAIAction: ; 0f7f (0:0f7f)
+; sets hAIActionTableIndex to an AI action specified in register a.
+; send 10 bytes of data to the other game from hAIActionTableIndex, hTempCardIndex_ff9f,
+; hTemp_ffa0, and hTempPlayAreaLocation_ffa1, and hTempRetreatCostCards.
+; finally exchange RNG data.
+SetAIAction_SerialSendDuelData: ; 0f7f (0:0f7f)
 	push hl
 	push bc
 	ldh [hAIActionTableIndex], a
@@ -2759,28 +2824,33 @@ SetDuelAIAction: ; 0f7f (0:0f7f)
 	cp DUELIST_TYPE_LINK_OPP
 	jr nz, .not_link
 	ld hl, hAIActionTableIndex
-	ld bc, $000a
-	call Func_0ebf
-	call Func_0f58
+	ld bc, 10
+	call SerialSendBytes
+	call ExchangeRNG
 .not_link
 	pop bc
 	pop hl
 	ret
 ; 0xf9b
 
-Func_0f9b: ; 0f9b (0:0f9b)
+; receive 10 bytes of data from wSerialRecvBuf and store them into hAIActionTableIndex,
+; hTempCardIndex_ff9f, hTemp_ffa0, and hTempPlayAreaLocation_ffa1,
+; and hTempRetreatCostCards. also exchange RNG data.
+SerialRecvDuelData: ; 0f9b (0:0f9b)
 	push hl
 	push bc
 	ld hl, hAIActionTableIndex
-	ld bc, $000a
-	call Func_0ed5
-	call Func_0f58
+	ld bc, 10
+	call SerialRecvBytes
+	call ExchangeRNG
 	pop bc
 	pop hl
 	ret
 ; 0xfac
 
-Func_0fac: ; 0fac (0:0fac)
+; serial send 8 bytes at f, a, l, h, e, d, c, b
+; only during a duel against a link opponent
+SerialSend8Bytes: ; 0fac (0:0fac)
 	push hl
 	push af
 	ld a, DUELVARS_DUELIST_TYPE
@@ -2801,7 +2871,7 @@ Func_0fac: ; 0fac (0:0fac)
 	push de
 	push hl
 	push af
-	ld hl, wcbed
+	ld hl, wTempSerialBuf
 	pop de
 	ld [hl], e
 	inc hl
@@ -2820,9 +2890,9 @@ Func_0fac: ; 0fac (0:0fac)
 	ld [hl], c
 	inc hl
 	ld [hl], b
-	ld hl, wcbed
-	ld bc, $0008
-	call Func_0ebf
+	ld hl, wTempSerialBuf
+	ld bc, 8
+	call SerialSendBytes
 	jp c, DuelTransmissionError
 	pop bc
 	pop de
@@ -2831,11 +2901,12 @@ Func_0fac: ; 0fac (0:0fac)
 	ret
 ; 0xfe9
 
-Func_0fe9: ; 0fe9 (0:0fe9)
-	ld hl, wcbed
-	ld bc, $0008
+; serial recv 8 bytes to f, a, l, h, e, d, c, b
+SerialRecv8Bytes: ; 0fe9 (0:0fe9)
+	ld hl, wTempSerialBuf
+	ld bc, 8
 	push hl
-	call Func_0ed5
+	call SerialRecvBytes
 	jp c, DuelTransmissionError
 	pop hl
 	ld e, [hl]
@@ -2861,20 +2932,23 @@ Func_0fe9: ; 0fe9 (0:0fe9)
 ; 0x100b
 
 ; save duel state to SRAM
-; called between each two-player turn, just after player draws card
+; called between each two-player turn, just after player draws card (ROM bank 1 loaded)
 SaveDuelStateToSRAM: ; 100b (0:100b)
 	ld a, $2
 	call BankswitchSRAM
-	call $669d
+	; save duel data to sCurrentDuel
+	call SaveDuelData
 	xor a
 	call BankswitchSRAM
 	call EnableSRAM
-	ld hl, sa008
+	ld hl, s0a008
 	ld a, [hl]
 	inc [hl]
 	call DisableSRAM
+	; select hl = SRAM3:(a000 + $400 * [s0a008] & $3)
+	; save wDuelTurns, non-turn holder's arena card ID, turn holder's arena card ID
 	and $3
-	add $28
+	add HIGH($a000) / 4
 	ld l, $0
 	ld h, a
 	add hl, hl
@@ -2903,18 +2977,19 @@ SaveDuelStateToSRAM: ; 100b (0:100b)
 	ld [hli], a
 	ld a, [wTempTurnDuelistCardID]
 	ld [hli], a
+	; save duel data to SRAM3:(a000 + $400 * [s0a008] & $3) + $0010
 	pop hl
 	ld de, $0010
 	add hl, de
 	ld e, l
 	ld d, h
 	call DisableSRAM
-	bank1call $66a4
+	bank1call SaveDuelDataToDE
 	xor a
 	call BankswitchSRAM
 	ret
 
-; copies the deck pointed to by de to wPlayerDeck or wOpponentDeck
+; copies the deck pointed to by de to wPlayerDeck or wOpponentDeck (depending on whose turn it is)
 CopyDeckData: ; 1072 (0:1072)
 	ld hl, wPlayerDeck
 	ldh a, [hWhoseTurn]
@@ -2962,7 +3037,7 @@ CopyDeckData: ; 1072 (0:1072)
 	ret
 ; 0x10aa
 
-; return, in register a, the amount of unclaimed prizes that the turn holder has left
+; return, in register a, the amount of prizes that the turn holder has not yet drawn
 CountPrizes: ; 10aa (0:10aa)
 	push hl
 	ld a, DUELVARS_PRIZES
@@ -2980,7 +3055,7 @@ CountPrizes: ; 10aa (0:10aa)
 ; 0x10bc
 
 ; shuffles the turn holder's deck
-; if less than 60 cards remain in the deck, make sure the rest are ignored
+; if less than 60 cards remain in the deck, it makes sure that the rest are ignored
 ShuffleDeck: ; 10bc (0:10bc)
 	ldh a, [hWhoseTurn]
 	ld h, a
@@ -2996,8 +3071,9 @@ ShuffleDeck: ; 10bc (0:10bc)
 	call ShuffleCards
 	ret
 
-; draw a card from the turn holder's deck, saving its location as CARD_LOCATION_JUST_DRAWN
-; returns carry if deck is empty, nc if a card was succesfully drawn
+; draw a card from the turn holder's deck, saving its location as CARD_LOCATION_JUST_DRAWN.
+; returns carry if deck is empty, nc if a card was succesfully drawn.
+; AddCardToHand is meant to be called next (unless this function returned carry).
 DrawCardFromDeck: ; 10cf (0:10cf)
 	push hl
 	ld a, DUELVARS_NUMBER_OF_CARDS_NOT_IN_DECK
@@ -3042,7 +3118,7 @@ ReturnCardToDeck: ; 10e8 (0:10e8)
 
 ; 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
+; 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
@@ -3130,7 +3206,7 @@ RemoveCardFromHand: ; 1139 (0:1139)
 	pop hl
 	jr .done_card
 .no_match
-	ld [de], a ; keep card in hand
+	ld [de], a ; keep any card that doesn't match in the player's hand
 	inc de
 .done_card
 	dec b
@@ -3155,7 +3231,7 @@ MoveHandCardToDiscardPile: ; 1160 (0:1160)
 	call RemoveCardFromHand
 ;	fallthrough
 
-; puts the card with the deck index (0-59) given in a into the discard pile
+; puts the turn holder's card with the deck index (0-59) given in a into the discard pile
 PutCardInDiscardPile: ; 116a (0:116a)
 	push af
 	push hl
@@ -3231,7 +3307,7 @@ PowersOf2:
 	db $01, $02, $04, $08, $10, $20, $40, $80
 ; 0x11bf
 
-; fill wDuelTempList with the turn holder's discard pile cards (their 0-59 deck index)
+; fill wDuelTempList with the turn holder's discard pile cards (their 0-59 deck indexes)
 ; return carry if the turn holder has no cards in the discard pile
 CreateDiscardPileCardList: ; 11bf (0:11bf)
 	ldh a, [hWhoseTurn]
@@ -3261,7 +3337,7 @@ CreateDiscardPileCardList: ; 11bf (0:11bf)
 	ret
 ; 0x11df
 
-; fill wDuelTempList with the turn holder's remaining deck cards (their 0-59 deck index)
+; fill wDuelTempList with the turn holder's remaining deck cards (their 0-59 deck indexes)
 ; return carry if the turn holder has no cards left in the deck
 CreateDeckCardList: ; 11df (0:11df)
 	ld a, DUELVARS_NUMBER_OF_CARDS_NOT_IN_DECK
@@ -3298,7 +3374,7 @@ CreateDeckCardList: ; 11df (0:11df)
 ; 0x120a
 
 ; fill wDuelTempList with the turn holder's energy cards
-; in the arena or in a bench slot (their 0-59 deck index).
+; in the arena or in a bench slot (their 0-59 deck indexes).
 ; if a == 0: search in CARD_LOCATION_ARENA
 ; if a != 0: search in CARD_LOCATION_BENCH_[A]
 ; return carry if no energy cards were found
@@ -3338,7 +3414,7 @@ CreateArenaOrBenchEnergyCardList: ; 120a (0:120a)
 	ret
 ; 0x123b
 
-; fill wDuelTempList with the turn holder's hand cards (their 0-59 deck index)
+; fill wDuelTempList with the turn holder's hand cards (their 0-59 deck indexes)
 ; return carry if the turn holder has no cards in hand
 CreateHandCardList: ; 123b (0:123b)
 	call FindLastCardInHand
@@ -3408,8 +3484,8 @@ FindLastCardInHand: ; 1271 (0:1271)
 
 ; shuffles the deck by swapping the position of each card with the position of another random card
 ; input:
-; - a  = how many cards to shuffle
-; - hl = DUELVARS_DECK_CARDS + [DUELVARS_NUMBER_OF_CARDS_NOT_IN_DECK]
+   ; a  = how many cards to shuffle
+   ; hl = DUELVARS_DECK_CARDS + [DUELVARS_NUMBER_OF_CARDS_NOT_IN_DECK]
 ShuffleCards: ; 127f (0:127f)
 	or a
 	ret z ; return if deck is empty
@@ -3688,20 +3764,19 @@ LoadCardDataToBuffer2_FromDeckIndex: ; 138c (0:138c)
 	ret
 ; 0x13a2
 
-; evolve a turn holder's Pokemon card in the play area slot determined by hTempPlayAreaLocationOffset_ff9d
+; evolve a turn holder's Pokemon card in the play area slot determined by hTempPlayAreaLocation_ff9d
 ; into another turn holder's Pokemon card identifier by it's deck index (0-59) in hTempCardIndex_ff98.
 ; return nc if evolution was succesful.
 EvolvePokemonCard: ; 13a2 (0:13a2)
 	; first make sure the attempted evolution is viable
 	ldh a, [hTempCardIndex_ff98]
 	ld d, a
-	ldh a, [hTempPlayAreaLocationOffset_ff9d]
+	ldh a, [hTempPlayAreaLocation_ff9d]
 	ld e, a
 	call CheckIfCanEvolveInto
 	ret c ; return if it's not capable of evolving into the selected Pokemon
-
 	; place the evolved Pokemon card in the play area location of the pre-evolved Pokemon card
-	ldh a, [hTempPlayAreaLocationOffset_ff9d]
+	ldh a, [hTempPlayAreaLocation_ff9d]
 	ld e, a
 	add DUELVARS_ARENA_CARD
 	call GetTurnDuelistVariable
@@ -3712,9 +3787,8 @@ EvolvePokemonCard: ; 13a2 (0:13a2)
 	call LoadCardDataToBuffer1_FromDeckIndex
 	ldh a, [hTempCardIndex_ff98]
 	call PutHandCardInPlayArea
-
 	; update the Pokemon's HP with the difference
-	ldh a, [hTempPlayAreaLocationOffset_ff9d]
+	ldh a, [hTempPlayAreaLocation_ff9d]
 	ld a, e ; derp
 	add DUELVARS_ARENA_CARD_HP
 	call GetTurnDuelistVariable
@@ -3735,10 +3809,9 @@ EvolvePokemonCard: ; 13a2 (0:13a2)
 	ld [hl], $00
 	ld a, e
 	or a
-	call z, ResetStatusConditions
-
+	call z, ClearAllStatusConditions
 	; set the new evolution stage of the card
-	ldh a, [hTempPlayAreaLocationOffset_ff9d]
+	ldh a, [hTempPlayAreaLocation_ff9d]
 	add DUELVARS_ARENA_CARD_STAGE
 	call GetTurnDuelistVariable
 	ld a, [wLoadedCard1Stage]
@@ -3746,6 +3819,7 @@ EvolvePokemonCard: ; 13a2 (0:13a2)
 	or a
 	ret
 
+; never executed
 	scf
 	ret
 ; 0x13f7
@@ -3836,10 +3910,10 @@ CheckIfCanEvolveInto_BasicToStage2: ; 142b (0:142b)
 	ret
 ; 0x1461
 
-; init the status and all substatuses of the turn holder's arena Pokemon.
-; called when sending a new Pokemon into the arena.
+; clear the status, all substatuses, and temporary duelvars of the turn holder's
+; arena Pokemon. called when sending a new Pokemon into the arena.
 ; does not reset Headache, since it targets a player rather than a Pokemon.
-ResetStatusConditions: ; 1461 (0:1461)
+ClearAllStatusConditions: ; 1461 (0:1461)
 	push hl
 	ldh a, [hWhoseTurn]
 	ld h, a
@@ -3872,7 +3946,7 @@ ResetStatusConditions: ; 1461 (0:1461)
 ; Removes a Pokemon card from the hand and places it in the arena or first available bench slot.
 ; If the Pokemon is placed in the arena, the status conditions of the player's arena card are zeroed.
 ; input:
-; - a = deck index of the card
+   ; a = deck index of the card
 ; return carry if there is no room for more Pokemon
 PutHandPokemonCardInPlayArea: ; 1485 (0:1485)
 	push af
@@ -3919,7 +3993,7 @@ PutHandPokemonCardInPlayArea: ; 1485 (0:1485)
 	ld [hl], a ; set card's evolution stage
 	ld a, e
 	or a
-	call z, ResetStatusConditions ; only call if Pokemon is being place in the arena
+	call z, ClearAllStatusConditions ; only call if Pokemon is being placed in the arena
 	ld a, e
 	or a
 	ret
@@ -3933,10 +4007,10 @@ PutHandPokemonCardInPlayArea: ; 1485 (0:1485)
 ; Removes a card from the hand and changes its location to arena or bench. Given that
 ; DUELVARS_ARENA_CARD or DUELVARS_BENCH aren't affected, this function is meant for energy and trainer cards.
 ; input:
-; - a = deck index of the card
-; - e = play area location offset (PLAY_AREA_*)
-; returns
-; - a = CARD_LOCATION_PLAY_AREA + e
+   ; a = deck index of the card
+   ; e = play area location offset (PLAY_AREA_*)
+; returns:
+   ; a = CARD_LOCATION_PLAY_AREA + e
 PutHandCardInPlayArea: ; 14d2 (0:14d2)
 	call RemoveCardFromHand
 	call GetTurnDuelistVariable
@@ -4028,7 +4102,7 @@ ShiftTurnPokemonToFirstPlayAreaSlots: ; 152b (0:152b)
 ; reset the status and all substatuses of the arena Pokemon before swapping.
 ; e is the play area location offset of the bench Pokemon (PLAY_AREA_*).
 SwapArenaWithBenchPokemon: ; 1543 (0:1543)
-	call ResetStatusConditions
+	call ClearAllStatusConditions
 	ld d, PLAY_AREA_ARENA
 ;	fallthrough
 
@@ -4201,7 +4275,7 @@ CountCardIDInLocation: ; 15ef (0:15ef)
 	ret
 
 ; returns [[hWhoseTurn] << 8 + a] in a and in [hl]
-; i.e. variable a of the player whose turn it is
+; i.e. duelvar a of the player whose turn it is
 GetTurnDuelistVariable: ; 160b (0:160b)
 	ld l, a
 	ldh a, [hWhoseTurn]
@@ -4210,7 +4284,7 @@ GetTurnDuelistVariable: ; 160b (0:160b)
 	ret
 
 ; returns [([hWhoseTurn] ^ $1) << 8 + a] in a and in [hl]
-; i.e. variable a of the player whose turn it is not
+; i.e. duelvar a of the player whose turn it is not
 GetNonTurnDuelistVariable: ; 1611 (0:1611)
 	ld l, a
 	ldh a, [hWhoseTurn]
@@ -4223,6 +4297,9 @@ GetNonTurnDuelistVariable: ; 1611 (0:1611)
 	ret
 ; 0x161e
 
+; when playing a Pokemon card, initializes some variables according to the
+; card played, and checks if the played card has Pokemon Power to show it to
+; the player, and possibly to use it if it triggers when the card is played.
 Func_161e: ; 161e (0:161e)
 	ldh a, [hTempCardIndex_ff98]
 	call ClearChangedTypesIfMuk
@@ -4239,7 +4316,7 @@ Func_161e: ; 161e (0:161e)
 	ld a, [wLoadedMoveCategory]
 	cp POKEMON_POWER
 	ret nz
-	call $6510
+	call DisplayUsePokemonPowerScreen
 	ldh a, [hTempCardIndex_ff98]
 	call LoadCardDataToBuffer1_FromDeckIndex
 	ld hl, wLoadedCard1Name
@@ -4249,17 +4326,17 @@ Func_161e: ; 161e (0:161e)
 	call LoadTxRam2
 	ldtx hl, HavePokemonPowerText
 	call DrawWideTextBox_WaitForInput
-	call Func_0f58
+	call ExchangeRNG
 	ld a, [wLoadedCard1ID]
 	cp MUK
 	jr z, .use_pokemon_power
 	ld a, $01 ; check only Muk
 	call CheckCannotUseDueToStatus_OnlyToxicGasIfANon0
 	jr nc, .use_pokemon_power
-	call $6510
+	call DisplayUsePokemonPowerScreen
 	ldtx hl, UnableToUsePkmnPowerDueToToxicGasText
 	call DrawWideTextBox_WaitForInput
-	call Func_0f58
+	call ExchangeRNG
 	ret
 
 .use_pokemon_power
@@ -4288,8 +4365,8 @@ Func_161e: ; 161e (0:161e)
 	ld [hl], a
 	ldtx hl, WillUseThePokemonPowerText
 	call DrawWideTextBox_WaitForInput
-	call Func_0f58
-	call $7415
+	call ExchangeRNG
+	call Func_7415
 	ld a, $07
 	call TryExecuteEffectCommandFunction
 	ret
@@ -4299,6 +4376,7 @@ Func_161e: ; 161e (0:161e)
 ; - e into wSelectedMoveIndex and d into hTempCardIndex_ff9f
 ; - Move1 (if e == 0) or Move2 (if e == 1) data into wLoadedMove
 ; - Also from that move, its Damage field into wDamage
+; finally, clears wNoDamageOrEffect and wDealtDamage
 CopyMoveDataAndDamage_FromCardID: ; 16ad (0:16ad)
 	push de
 	push af
@@ -4317,6 +4395,7 @@ CopyMoveDataAndDamage_FromCardID: ; 16ad (0:16ad)
 ; - e into wSelectedMoveIndex and d into hTempCardIndex_ff9f
 ; - Move1 (if e == 0) or Move2 (if e == 1) data into wLoadedMove
 ; - Also from that move, its Damage field into wDamage
+; finally, clears wNoDamageOrEffect and wDealtDamage
 CopyMoveDataAndDamage_FromDeckIndex: ; 16c0 (0:16c0)
 	ld a, e
 	ld [wSelectedMoveIndex], a
@@ -4347,12 +4426,15 @@ CopyMoveDataAndDamage:
 	xor a
 	ld [hl], a
 	ld [wNoDamageOrEffect], a
-	ld hl, wTempDamage_ccbf
+	ld hl, wDealtDamage
 	ld [hli], a
 	ld [hl], a
 	ret
 
-; inits hTempCardIndex_ff9f, wTempTurnDuelistCardID, wTempNonTurnDuelistCardID, and other temp variables
+; inits hTempCardIndex_ff9f and wTempTurnDuelistCardID to the turn holder's arena card,
+; wTempNonTurnDuelistCardID to the non-turn holder's arena card, and zeroes other temp
+; variables that only last between each two-player turn.
+; this is called when a Pokemon card is played or when an attack is used
 Func_16f6: ; 16f6 (0:16f6)
 	ld a, DUELVARS_ARENA_CARD
 	call GetTurnDuelistVariable
@@ -4369,61 +4451,63 @@ Func_16f6: ; 16f6 (0:16f6)
 	call SwapTurn
 	xor a
 	ld [wccec], a
-	ld [wcccd], a
+	ld [wEffectFunctionsFeedbackIndex], a
 	ld [wcced], a
-	ld [wDamageToSelfMode], a
+	ld [wIsDamageToSelf], a
 	ld [wccef], a
 	ld [wccf0], a
 	ld [wccf1], a
-	bank1call $7189
+	bank1call ClearNonTurnTemporaryDuelvars_CopyStatus
 	ret
 
-Func_1730: ; 1730 (0:1730)
+; use attack or Pokemon Power
+UseAttackOrPokemonPower: ; 1730 (0:1730)
 	ld a, [wSelectedMoveIndex]
-	ld [wcc10], a
+	ld [wPlayerAttackingMoveIndex], a
 	ldh a, [hTempCardIndex_ff9f]
-	ld [wcc11], a
+	ld [wPlayerAttackingCardIndex], a
 	ld a, [wTempCardID_ccc2]
-	ld [wcc12], a
+	ld [wPlayerAttackingCardID], a
 	ld a, [wLoadedMoveCategory]
 	cp POKEMON_POWER
-	jp z, Func_184b
+	jp z, UsePokemonPower
 	call Func_16f6
 	ld a, $1
 	call TryExecuteEffectCommandFunction
-	jp c, Func_181e
+	jp c, DrawWideTextBox_WaitForInput_ReturnCarry
 	call CheckSandAttackOrSmokescreenSubstatus
 	jr c, .asm_1766
 	ld a, $2
 	call TryExecuteEffectCommandFunction
-	jp c, Func_1821
+	jp c, ReturnCarry
 	call Func_1874
 	jr .asm_1777
 .asm_1766
 	call Func_1874
 	call HandleSandAttackOrSmokescreenSubstatus
-	jp c, Func_1823
+	jp c, ClearNonTurnTemporaryDuelvars_ResetCarry
 	ld a, $2
 	call TryExecuteEffectCommandFunction
-	jp c, Func_1821
+	jp c, ReturnCarry
 .asm_1777
 	ld a, $9
-	call SetDuelAIAction
+	call SetAIAction_SerialSendDuelData
 	ld a, $6
 	call TryExecuteEffectCommandFunction
 	call CheckSelfConfusionDamage
 	jp c, DealConfusionDamageToSelf
-	call Func_1b8d
+	call DrawDuelMainScene_PrintPokemonsAttackText
 	call WaitForWideTextBoxInput
-	call Func_0f58
+	call ExchangeRNG
 	ld a, $5
 	call TryExecuteEffectCommandFunction
 	ld a, $a
-	call SetDuelAIAction
+	call SetAIAction_SerialSendDuelData
 ;	fallthrough
 
+; deal attack damage
 Func_179a: ; 179a (0:179a)
-	call $7415
+	call Func_7415
 	ld a, [wLoadedMoveCategory]
 	and RESIDUAL
 	jr nz, .asm_17ad
@@ -4432,12 +4516,12 @@ Func_179a: ; 179a (0:179a)
 	call SwapTurn
 .asm_17ad
 	xor a
-	ldh [hTempPlayAreaLocationOffset_ff9d], a
+	ldh [hTempPlayAreaLocation_ff9d], a
 	ld a, $3
 	call TryExecuteEffectCommandFunction
 	call ApplyDamageModifiers_DamageToTarget
 	call Func_189d
-	ld hl, wTempDamage_ccbf
+	ld hl, wDealtDamage
 	ld [hl], e
 	inc hl
 	ld [hl], d
@@ -4448,14 +4532,14 @@ Func_179a: ; 179a (0:179a)
 	call GetNonTurnDuelistVariable
 	push de
 	push hl
-	call $7494
-	call $741a
-	call $7484
+	call Func_7494
+	call Func_741a
+	call Func_7484
 	pop hl
 	pop de
 	call SubstractHP
-	ld a, [wcac2]
-	cp $1
+	ld a, [wDuelDisplayedScreen]
+	cp DUEL_MAIN_SCENE
 	jr nz, .skip_draw_huds
 	push hl
 	bank1call DrawDuelHUDs
@@ -4472,6 +4556,8 @@ Func_17ed: ; 17ed (0:17ed)
 	ld [hl], a
 	ld a, NO_DAMAGE_OR_EFFECT_AGILITY
 	ld [wNoDamageOrEffect], a
+;	fallthrough
+
 Func_17fb: ; 17fb (0:17fb)
 	ld a, [wTempNonTurnDuelistCardID]
 	push af
@@ -4480,34 +4566,34 @@ Func_17fb: ; 17fb (0:17fb)
 	pop af
 	ld [wTempNonTurnDuelistCardID], a
 	call HandleStrikesBack_AgainstResidualMove
-	bank1call $6df1
+	bank1call Func_6df1
 	call Func_1bb4
-	bank1call $7195
-	call $6e49
+	bank1call Func_7195
+	call Func_6e49
 	or a
 	ret
 
-Func_1819: ; 1819 (0:1819)
+DisplayUsePokemonPowerScreen_WaitForInput: ; 1819 (0:1819)
 	push hl
-	call $6510
+	call DisplayUsePokemonPowerScreen
 	pop hl
 
-Func_181e: ; 181e (0:181e)
+DrawWideTextBox_WaitForInput_ReturnCarry: ; 181e (0:181e)
 	call DrawWideTextBox_WaitForInput
 
-Func_1821: ; 1821 (0:1821)
+ReturnCarry: ; 1821 (0:1821)
 	scf
 	ret
 
-Func_1823: ; 1823 (0:1823)
-	bank1call $717a
+ClearNonTurnTemporaryDuelvars_ResetCarry: ; 1823 (0:1823)
+	bank1call ClearNonTurnTemporaryDuelvars
 	or a
 	ret
 
 DealConfusionDamageToSelf: ; 1828 (0:1828)
 	bank1call DrawDuelMainScene
 	ld a, 1
-	ld [wDamageToSelfMode], a
+	ld [wIsDamageToSelf], a
 	ldtx hl, DamageToSelfDueToConfusionText
 	call DrawWideTextBox_PrintText
 	ld a, $75
@@ -4515,28 +4601,29 @@ DealConfusionDamageToSelf: ; 1828 (0:1828)
 	ld a, 20 ; damage
 	call Func_195c
 	call Func_1bb4
-	call $6e49
-	bank1call $717a
+	call Func_6e49
+	bank1call ClearNonTurnTemporaryDuelvars
 	or a
 	ret
 
-Func_184b: ; 184b (0:184b)
-	call $7415
+; use Pokemon Power
+UsePokemonPower: ; 184b (0:184b)
+	call Func_7415
 	ld a, $2
 	call TryExecuteEffectCommandFunction
-	jr c, Func_1819
+	jr c, DisplayUsePokemonPowerScreen_WaitForInput
 	ld a, $5
 	call TryExecuteEffectCommandFunction
-	jr c, Func_1821
+	jr c, ReturnCarry
 	ld a, $c
-	call SetDuelAIAction
-	call Func_0f58
+	call SetAIAction_SerialSendDuelData
+	call ExchangeRNG
 	ld a, $d
-	call SetDuelAIAction
+	call SetAIAction_SerialSendDuelData
 	ld a, $3
 	call TryExecuteEffectCommandFunction
 	ld a, $16
-	call SetDuelAIAction
+	call SetAIAction_SerialSendDuelData
 	ret
 
 Func_1874: ; 1874 (0:1874)
@@ -4549,13 +4636,13 @@ Func_1874: ; 1874 (0:1874)
 	push af
 	ld a, $1
 	ld [wccec], a
-	ld a, [wcc11]
+	ld a, [wPlayerAttackingCardIndex]
 	ldh [hTempCardIndex_ff9f], a
-	ld a, [wcc10]
+	ld a, [wPlayerAttackingMoveIndex]
 	ldh [hTemp_ffa0], a
 	ld a, $8
-	call SetDuelAIAction
-	call Func_0f58
+	call SetAIAction_SerialSendDuelData
+	call ExchangeRNG
 	pop af
 	ldh [hTempCardIndex_ff9f], a
 	pop af
@@ -4576,14 +4663,14 @@ Func_189d: ; 189d (0:189d)
 	call GetNonTurnDuelistVariable
 	or a
 	jr nz, .asm_18b9
-	ld a, [wcccd]
+	ld a, [wEffectFunctionsFeedbackIndex]
 	or a
 	ret z
 .asm_18b9
 	push de
 	call SwapTurn
 	xor a
-	ld [wTempPlayAreaLocationOffset_cceb], a
+	ld [wTempPlayAreaLocation_cceb], a
 	call HandleTransparency
 	call SwapTurn
 	pop de
@@ -4642,27 +4729,27 @@ UseTrainerCard: ; 18f9 (0:18f9)
 	call TryExecuteEffectCommandFunction
 	jr c, .done
 	ld a, $06
-	call SetDuelAIAction
-	call $666a
-	call Func_0f58
+	call SetAIAction_SerialSendDuelData
+	call DisplayUsedTrainerCardDetailScreen
+	call ExchangeRNG
 	ld a, $06
 	call TryExecuteEffectCommandFunction
 	ld a, $05
 	call TryExecuteEffectCommandFunction
 	ld a, $07
-	call SetDuelAIAction
+	call SetAIAction_SerialSendDuelData
 	ld a, $03
 	call TryExecuteEffectCommandFunction
 	ldh a, [hTempCardIndex_ff9f]
 	call MoveHandCardToDiscardPile
-	call Func_0f58
+	call ExchangeRNG
 .done
 	or a
 	ret
 ; 0x1944
 
 ; loads the effect commands of a (trainer or energy) card with deck index (0-59) at hTempCardIndex_ff9f
-; into wLoadedMoveEffectCommands
+; into wLoadedMoveEffectCommands. in practice, only used for trainer cards
 LoadNonPokemonCardEffectCommands: ; 1944 (0:1944)
 	ldh a, [hTempCardIndex_ff9f]
 	call LoadCardDataToBuffer1_FromDeckIndex
@@ -4681,16 +4768,18 @@ Func_1955: ; 1955 (0:1955)
 	ld a, $7a
 	ld [wLoadedMoveAnimation], a
 	pop af
+;	fallthrough
+
 ; this function appears to handle dealing damage to self due to confusion
 Func_195c: ; 195c (0:195c)
 	ld hl, wDamage
 	ld [hli], a
-	ld [hl], $0
+	ld [hl], 0
 	ld a, [wNoDamageOrEffect]
 	push af
 	xor a
 	ld [wNoDamageOrEffect], a
-	bank1call $7415
+	bank1call Func_7415
 	ld a, [wTempNonTurnDuelistCardID]
 	push af
 	ld a, [wTempTurnDuelistCardID]
@@ -4701,7 +4790,7 @@ Func_195c: ; 195c (0:195c)
 	ld b, $0
 	ld a, DUELVARS_ARENA_CARD_HP
 	call GetTurnDuelistVariable
-	bank1call $7469
+	bank1call Func_7469
 	call PrintKnockedOutIfHLZero
 	pop af
 	ld [wTempNonTurnDuelistCardID], a
@@ -4725,7 +4814,7 @@ ApplyDamageModifiers_DamageToTarget: ; 1994 (0:1994)
 	ret
 .non_zero_damage
 	xor a ; PLAY_AREA_ARENA
-	ldh [hTempPlayAreaLocationOffset_ff9d], a
+	ldh [hTempPlayAreaLocation_ff9d], a
 	ld d, [hl]
 	dec hl
 	ld e, [hl]
@@ -4741,7 +4830,7 @@ ApplyDamageModifiers_DamageToTarget: ; 1994 (0:1994)
 	ld a, e
 	or d
 	ret z
-	ldh a, [hTempPlayAreaLocationOffset_ff9d]
+	ldh a, [hTempPlayAreaLocation_ff9d]
 	call GetPlayAreaCardColor
 	call TranslateColorToWR
 	ld b, a
@@ -4926,7 +5015,8 @@ PrintKnockedOutIfHLZero: ; 1ad0 (0:1ad0)
 	ret nz
 ;	fallthrough
 
-; print in a text box that the Pokemon card at wTempNonTurnDuelistCardID was knocked out and wait 40 frames
+; print in a text box that the Pokemon card at wTempNonTurnDuelistCardID
+; was knocked out and wait 40 frames
 PrintKnockedOut: ; 1ad3 (0:1ad3)
 	ld a, [wTempNonTurnDuelistCardID]
 	ld e, a
@@ -4947,12 +5037,15 @@ PrintKnockedOut: ; 1ad3 (0:1ad3)
 	ret
 ; 0x1af3
 
-; seems to be a function to deal damage to a card
+; seems to be a function to deal damage to a card, but can be used
+; to deal damage to a benched Pokemon.
+; shows the defending player's play area screen when dealing the damage
+; instead of the main duel interface, and has a fixed move animation
 Func_1af3: ; 1af3 (0:1af3)
 	ld a, $78
 	ld [wLoadedMoveAnimation], a
 	ld a, b
-	ld [wTempPlayAreaLocationOffset_cceb], a
+	ld [wTempPlayAreaLocation_cceb], a
 	or a ; cp PLAY_AREA_ARENA
 	jr nz, .skip_no_damage_or_effect_check
 	ld a, [wNoDamageOrEffect]
@@ -4965,17 +5058,17 @@ Func_1af3: ; 1af3 (0:1af3)
 	xor a
 	ld [wNoDamageOrEffect], a
 	push de
-	ld a, [wTempPlayAreaLocationOffset_cceb]
+	ld a, [wTempPlayAreaLocation_cceb]
 	add DUELVARS_ARENA_CARD
 	call GetTurnDuelistVariable
 	call GetCardIDFromDeckIndex
 	ld a, e
 	ld [wTempNonTurnDuelistCardID], a
 	pop de
-	ld a, [wTempPlayAreaLocationOffset_cceb]
+	ld a, [wTempPlayAreaLocation_cceb]
 	or a ; cp PLAY_AREA_ARENA
 	jr nz, .next
-	ld a, [wDamageToSelfMode]
+	ld a, [wIsDamageToSelf]
 	or a
 	jr z, .turn_swapped
 	ld b, CARD_LOCATION_ARENA
@@ -4990,12 +5083,12 @@ Func_1af3: ; 1af3 (0:1af3)
 	ld a, [wLoadedMoveCategory]
 	cp POKEMON_POWER
 	jr z, .skip_defender
-	ld a, [wTempPlayAreaLocationOffset_cceb]
+	ld a, [wTempPlayAreaLocation_cceb]
 	or CARD_LOCATION_PLAY_AREA
 	ld b, a
 	call ApplyAttachedDefender
 .skip_defender
-	ld a, [wTempPlayAreaLocationOffset_cceb]
+	ld a, [wTempPlayAreaLocation_cceb]
 	or a ; cp PLAY_AREA_ARENA
 	jr nz, .in_bench
 	push de
@@ -5008,12 +5101,12 @@ Func_1af3: ; 1af3 (0:1af3)
 	ld de, 0
 .no_underflow
 	call HandleDamageReductionOrNoDamageFromPkmnPowerEffects
-	ld a, [wTempPlayAreaLocationOffset_cceb]
+	ld a, [wTempPlayAreaLocation_cceb]
 	ld b, a
 	or a ; cp PLAY_AREA_ARENA
 	jr nz, .benched
-	; add damage at de to [wTempDamage_ccbf]
-	ld hl, wTempDamage_ccbf
+	; add damage at de to [wDealtDamage]
+	ld hl, wDealtDamage
 	ld a, e
 	add [hl]
 	ld [hli], a
@@ -5025,7 +5118,7 @@ Func_1af3: ; 1af3 (0:1af3)
 	add DUELVARS_ARENA_CARD_HP
 	call GetTurnDuelistVariable
 	push af
-	bank1call $7469
+	bank1call Func_7469
 	pop af
 	or a
 	jr z, .skip_knocked_out
@@ -5040,15 +5133,24 @@ Func_1af3: ; 1af3 (0:1af3)
 	ret
 ; 0x1b8d
 
-Func_1b8d: ; 1b8d (0:1b8d)
+; draw duel main scene, then print the "<Pokemon Lvxx>'s <attack>" text
+; The Pokemon's name is the turn holder's arena Pokemon, and the
+; attack's name is taken from wLoadedMoveName.
+DrawDuelMainScene_PrintPokemonsAttackText: ; 1b8d (0:1b8d)
 	bank1call DrawDuelMainScene
-Func_1b90: ; 1b90 (0:1b90)
+;	fallthrough
+
+; print the "<Pokemon Lvxx>'s <attack>" text
+; The Pokemon's name is the turn holder's arena Pokemon, and the
+; attack's name is taken from wLoadedMoveName.
+PrintPokemonsAttackText: ; 1b90 (0:1b90)
 	ld a, DUELVARS_ARENA_CARD
 	call GetTurnDuelistVariable
 	call LoadCardDataToBuffer1_FromDeckIndex
 	ld a, 18
 	call CopyCardNameAndLevel
-	ld [hl], $0
+	ld [hl], TX_END
+	; zero wTxRam2 so that the name & level text just loaded to wDefaultText is printed
 	ld hl, wTxRam2
 	xor a
 	ld [hli], a
@@ -5057,33 +5159,36 @@ Func_1b90: ; 1b90 (0:1b90)
 	ld [hli], a ; wTxRam2_b
 	ld a, [wLoadedMoveName + 1]
 	ld [hli], a
-	ldtx hl, PokemonsAttackText ; text when using an attack
+	ldtx hl, PokemonsAttackText
 	call DrawWideTextBox_PrintText
 	ret
 
 Func_1bb4: ; 1bb4 (0:1bb4)
 	call Func_3b31
 	bank1call DrawDuelMainScene
-	call $503a
+	call DrawDuelHUDs
 	xor a
-	ldh [hTempPlayAreaLocationOffset_ff9d], a
+	ldh [hTempPlayAreaLocation_ff9d], a
 	call Func_1bca
 	call WaitForWideTextBoxInput
-	call Func_0f58
+	call ExchangeRNG
 	ret
 
+; prints one of the ThereWasNoEffectFrom*Text if wcced contains $1,
+; and WasUnsuccessfulText if wcced contains $2
 Func_1bca: ; 1bca (0:1bca)
 	ld a, [wcced]
 	or a
 	ret z
 	cp $1
-	jr z, .asm_1bfd
-	ldh a, [hTempPlayAreaLocationOffset_ff9d]
+	jr z, .no_effect_from_status
+	ldh a, [hTempPlayAreaLocation_ff9d]
 	add DUELVARS_ARENA_CARD
 	call GetTurnDuelistVariable
 	call LoadCardDataToBuffer1_FromDeckIndex
 	ld a, 18
 	call CopyCardNameAndLevel
+	; zero wTxRam2 so that the name & level text just loaded to wDefaultText is printed
 	ld [hl], $0
 	ld hl, $0000
 	call LoadTxRam2
@@ -5098,17 +5203,17 @@ Func_1bca: ; 1bca (0:1bca)
 	call DrawWideTextBox_PrintText
 	scf
 	ret
-.asm_1bfd
-	call $700a
+.no_effect_from_status
+	call PrintThereWasNoEffectFromStatusText
 	call DrawWideTextBox_PrintText
 	scf
 	ret
 ; 0x1c05
 
 ; return in a the retreat cost of the turn holder's arena or benchx Pokemon
-; given the PLAY_AREA_* value in hTempPlayAreaLocationOffset_ff9d
+; given the PLAY_AREA_* value in hTempPlayAreaLocation_ff9d
 GetPlayAreaCardRetreatCost: ; 1c05 (0:1c05)
-	ldh a, [hTempPlayAreaLocationOffset_ff9d]
+	ldh a, [hTempPlayAreaLocation_ff9d]
 	add DUELVARS_ARENA_CARD
 	call GetTurnDuelistVariable
 	call LoadCardDataToBuffer1_FromDeckIndex
@@ -5170,9 +5275,9 @@ SubstractHPFromCard: ; 1c35 (0:1c35)
 
 ; check if a flag of wLoadedMove is set
 ; input:
-  ; a = %fffffbbb, where
-     ; fffff = flag address counting from wLoadedMoveFlag1
-     ; bbb = flag bit
+   ; a = %fffffbbb, where
+      ; fffff = flag address counting from wLoadedMoveFlag1
+      ; bbb = flag bit
 ; return carry if the flag is set
 CheckLoadedMoveFlag: ; 1c50 (0:1c50)
 	push hl
@@ -5218,7 +5323,7 @@ SwapTurn: ; 1c72 (0:1c72)
 	pop af
 	ret
 
-; copy the $00-terminated player's name from sPlayerName to de
+; copy the TX_END-terminated player's name from sPlayerName to de
 CopyPlayerName: ; 1c7d (0:1c7d)
 	call EnableSRAM
 	ld hl, sPlayerName
@@ -5226,13 +5331,16 @@ CopyPlayerName: ; 1c7d (0:1c7d)
 	ld a, [hli]
 	ld [de], a
 	inc de
-	or a
+	or a ; TX_END
 	jr nz, .loop
 	dec de
 	call DisableSRAM
 	ret
 
-; copy the opponent's name to de (usually via CopyText)
+; copy the opponent's name to de
+; if text ID at wOpponentName is non-0, copy it from there
+; else, if text at wc500 is non-0, copy if from there
+; else, copy Player2Text
 CopyOpponentName: ; 1c8e (0:1c8e)
 	ld hl, wOpponentName
 	ld a, [hli]
@@ -5268,7 +5376,6 @@ GetRawAmountOfCardsOwned: ; 1caa (0:1caa)
 	ld bc, DECK_SIZE
 	add hl, bc
 	ld c, a
-
 .skip_deck
 	ld a, sDeck2Cards - sDeck1Cards
 	add e
@@ -5278,7 +5385,6 @@ GetRawAmountOfCardsOwned: ; 1caa (0:1caa)
 	ld d, a ; de = sDeck*Cards[x]
 	dec c
 	jr nz, .next_deck
-
 	; hl = DECK_SIZE * (no. of non-empty decks)
 	ld de, sCardCollection
 .next_card
@@ -5288,7 +5394,6 @@ GetRawAmountOfCardsOwned: ; 1caa (0:1caa)
 	ld c, a ; card count in sCardCollection
 	ld b, $0
 	add hl, bc
-
 .skip_card
 	inc e
 	jr nz, .next_card ; assumes sCardCollection is $100 bytes long (CARD_COLLECTION_SIZE)
@@ -5320,12 +5425,10 @@ GetCardCountInCollectionAndDecks: ; 1ce1 (0:1ce1)
 	cp c
 	jr nz, .no_match
 	inc b ; this deck card matches card c
-
 .no_match
 	dec e
 	jr nz, .next_card
 	pop hl
-
 .deck_done
 	push de
 	ld de, sDeck2Cards - sDeck1Cards
@@ -5333,7 +5436,6 @@ GetCardCountInCollectionAndDecks: ; 1ce1 (0:1ce1)
 	pop de
 	dec d
 	jr nz, .next_deck
-
 	; all decks done
 	ld h, HIGH(sCardCollection)
 	ld l, c
@@ -5341,7 +5443,6 @@ GetCardCountInCollectionAndDecks: ; 1ce1 (0:1ce1)
 	bit CARD_NOT_OWNED_F, a
 	jr nz, .done
 	add b ; if card seen, add b to count
-
 .done
 	and CARD_COUNT_MASK
 	call DisableSRAM
@@ -5397,13 +5498,13 @@ AddDeckCardsToTempCardCollection: ; 1d59 (0:1d59)
 	ld d, h
 	ld h, HIGH(wTempCardCollection)
 	ld c, DECK_SIZE
-.next_card
+.next_card_loop
 	ld a, [de] ; count of current card being added
 	inc de ; move to next card for next iteration
 	ld l, a
 	inc [hl] ; increment count
 	dec c
-	jr nz, .next_card
+	jr nz, .next_card_loop
 	ret
 
 ; add card with id given in a to sCardCollection, provided that
@@ -5486,7 +5587,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]
@@ -5542,20 +5643,20 @@ AdjustCoordinatesForBGScroll: ; 1deb (0:1deb)
 DrawLabeledTextBox: ; 1e00 (0:1e00)
 	ld a, [wConsole]
 	cp CONSOLE_SGB
-	jr nz, .draw_top_border
+	jr nz, .draw_textbox
 	ld a, [wTextBoxFrameType]
 	or a
-	jr z, .draw_top_border
+	jr z, .draw_textbox
 ; Console is SGB and frame type is != 0.
-; The text box will be colorized so a SGB command needs to be sent
+; The text box will be colorized so a SGB command needs to be sent as well
 	push de
 	push bc
-	call .draw_top_border ; this falls through to drawing the whole box
+	call .draw_textbox
 	pop bc
 	pop de
 	jp ColorizeTextBoxSGB
 
-.draw_top_border
+.draw_textbox
 	push de
 	push bc
 	push hl
@@ -5649,6 +5750,8 @@ DrawRegularTextBoxDMG: ; 1e88 (0:1e88)
 	call CopyLine
 ;	fallthrough
 
+; continue drawing a labeled or regular textbox on DMG or SGB:
+; body and bottom line of either type of textbox
 ContinueDrawingTextBoxDMGorSGB:
 	dec c
 	dec c
@@ -5699,6 +5802,7 @@ CopyLine: ; 1ea5 (0:1ea5)
 	add sp, BG_MAP_WIDTH
 	ret
 
+; DrawRegularTextBox branches here on CGB console
 DrawRegularTextBoxCGB:
 	call DECoordToBGMap0Address
 	; top line (border) of the text box
@@ -5707,6 +5811,8 @@ DrawRegularTextBoxCGB:
 	call CopyCurrentLineTilesAndAttrCGB
 ;	fallthrough
 
+; continue drawing a labeled or regular textbox on CGB:
+; body and bottom line of either type of textbox
 ContinueDrawingTextBoxCGB:
 	dec c
 	dec c
@@ -5740,6 +5846,7 @@ CopyCurrentLineTilesAndAttrCGB: ; 1efb (0:1efb)
 	call CopyLine
 	pop hl
 ;	fallthrough
+
 CopyCurrentLineAttrCGB:
 	call BankswitchVRAM1
 	ld a, [wTextBoxFrameType] ; on CGB, wTextBoxFrameType determines the palette and the other attributes
@@ -5749,6 +5856,7 @@ CopyCurrentLineAttrCGB:
 	call BankswitchVRAM0
 	ret
 
+; DrawRegularTextBox branches here on SGB console
 DrawRegularTextBoxSGB: ; 1f0f (0:1f0f)
 	push bc
 	push de
@@ -5758,12 +5866,14 @@ DrawRegularTextBoxSGB: ; 1f0f (0:1f0f)
 	ld a, [wTextBoxFrameType]
 	or a
 	ret z
+;	fallthrough
+
 ColorizeTextBoxSGB:
 	push bc
 	push de
 	ld hl, wTempSGBPacket
-	ld de, AttrBlkPacket_1f4f
-	ld c, $10
+	ld de, AttrBlkPacket_TextBox
+	ld c, SGB_PACKET_SIZE
 .copy_sgb_command_loop
 	ld a, [de]
 	inc de
@@ -5773,10 +5883,12 @@ ColorizeTextBoxSGB:
 	pop de
 	pop bc
 	ld hl, wTempSGBPacket + 4
+	; set X1, Y1 to d, e
 	ld [hl], d
 	inc hl
 	ld [hl], e
 	inc hl
+	; set X2, Y2 to d+b-1, e+c-1
 	ld a, d
 	add b
 	dec a
@@ -5787,15 +5899,18 @@ ColorizeTextBoxSGB:
 	ld [hli], a
 	ld a, [wTextBoxFrameType]
 	and $80
-	jr z, .asm_1f48
-	ld a, $2
+	jr z, .send_packet
+	; reset ATTR_BLK_CTRL_INSIDE if bit 7 of wTextBoxFrameType is set.
+	; appears to be irrelevant, as the inside of a textbox uses the white color,
+	; which is the same in all four SGB palettes.
+	ld a, ATTR_BLK_CTRL_LINE
 	ld [wTempSGBPacket + 2], a
-.asm_1f48
+.send_packet
 	ld hl, wTempSGBPacket
 	call SendSGB
 	ret
 
-AttrBlkPacket_1f4f: ; 1f4f (0:1f4f)
+AttrBlkPacket_TextBox: ; 1f4f (0:1f4f)
 	sgb ATTR_BLK, 1 ; sgb_command, length
 	db 1 ; number of data sets
 	; Control Code,  Color Palette Designation, X1, Y1, X2, Y2
@@ -6085,7 +6200,8 @@ LoadDuelCardSymbolTiles: ; 20b0 (0:20b0)
 	ld b, $30
 	jr CopyFontsOrDuelGraphicsTiles
 
-; loads the symbols for Stage 1 Pkmn card, Stage 2 Pkmn card, and Trainer card
+; loads the symbols for Stage 1 Pkmn card, Stage 2 Pkmn card, and Trainer card.
+; unlike LoadDuelCardSymbolTiles excludes the symbols for Basic Pkmn and all energies.
 LoadDuelCardSymbolTiles2: ; 20c4 (0:20c4)
 	ld hl, DuelDmgSgbSymbolGraphics + $4 tiles - $4000
 	ld a, [wConsole]
@@ -6097,12 +6213,12 @@ LoadDuelCardSymbolTiles2: ; 20c4 (0:20c4)
 	ld b, $c
 	jr CopyFontsOrDuelGraphicsTiles
 
-; load the face down stage0 / stage1 / stage2 card images shown in the ckeck Pokemon screens
+; load the face down basic / stage1 / stage2 card images shown in the ckeck Pokemon screens
 LoadDuelFaceDownCardTiles: ; 20d8 (0:20d8)
 	ld b, $10
 	jr LoadDuelCheckPokemonScreenTiles.got_num_tiles
 
-; same as LoadDuelFaceDownCardTiles, plus also load the ACT / BP text tiles
+; same as LoadDuelFaceDownCardTiles, plus also load the ACT / BPx tiles
 LoadDuelCheckPokemonScreenTiles: ; 20dc (0:20dc)
 	ld b, $24
 .got_num_tiles
@@ -6140,6 +6256,7 @@ LoadDuelCoinTossResultTiles: ; 210f (0:210f)
 	ld b, $8
 	jr CopyFontsOrDuelGraphicsTiles
 
+; load the tiles of the text characters used with TX_SYMBOL
 LoadSymbolsFont: ; 2119 (0:2119)
 	ld hl, SymbolsFont - $4000
 	ld de, v0Tiles2 ; destination
@@ -6152,14 +6269,14 @@ LoadSymbolsFont: ; 2119 (0:2119)
 ;   copy b tiles from Gfx2:hl to de
 CopyFontsOrDuelGraphicsTiles: ; 2121 (0:2121)
 	ld a, BANK(Fonts); BANK(DuelGraphics)
-	call BankpushHome
+	call BankpushROM
 	ld c, TILE_SIZE
 	call CopyGfxData
-	call BankpopHome
+	call BankpopROM
 	ret
 ; 0x212f
 
-; this function appears to copy gfx data into sram
+; this function copies gfx data into sram
 Func_212f: ; 212f (0:212f)
 	ld hl, SymbolsFont - $4000
 	ld de, $a400
@@ -6213,7 +6330,7 @@ DrawDuelBoxMessage: ; 2167 (0:2167)
 LoadFullWidthFontTiles: ; 2189 (0:2189)
 	ld hl, FullWidthFonts + $3cc tiles_1bpp - $4000
 	ld a, BANK(Fonts); BANK(DuelGraphics)
-	call BankpushHome
+	call BankpushROM
 	push hl
 	ld e, l
 	ld d, h
@@ -6224,7 +6341,7 @@ LoadFullWidthFontTiles: ; 2189 (0:2189)
 	call Copy1bppTiles
 	ld hl, v0Tiles1
 	call Copy1bppTiles
-	call BankpopHome
+	call BankpopROM
 	ret
 ; 0x21ab
 
@@ -6246,9 +6363,9 @@ Copy1bppTiles: ; 21ab (0:21ab)
 ; 0x21ba
 
 ; similar to ProcessText except it calls InitTextPrinting first
-; with register de as an argument to set hTextBGMap0Address.
+; with the first two bytes of hl being used to set hTextBGMap0Address.
 ; (the caller to ProcessText usually calls InitTextPrinting first)
-ProcessText_InitTextPrinting: ; 21ba (0:21ba)
+InitTextPrinting_ProcessText: ; 21ba (0:21ba)
 	push de
 	push bc
 	ld d, [hl]
@@ -6258,8 +6375,8 @@ ProcessText_InitTextPrinting: ; 21ba (0:21ba)
 	call InitTextPrinting
 	jr ProcessText.next_char
 
-; reads the characters from the text at hl processes them. loops until TX_END
-; is found. ignores TX_RAM1, TX_RAM2, and TX_RAM3 characters.
+; reads the characters from the text at hl processes them. loops until
+; TX_END is found. ignores TX_RAM1, TX_RAM2, and TX_RAM3 characters.
 ProcessText: ; 21c5 (0:21c5)
 	push de
 	push bc
@@ -6380,7 +6497,10 @@ ProcessSpecialTextCharacter: ; 21f2 (0:21f2)
 	xor a
 	ret
 
-Func_2275: ; 2275 (0:2275)
+; calls InitTextFormat, selects tiles at $8800-$97FF for text, and clears the wc600.
+; selects the first and last tile to be reserved for constructing text tiles in VRAM
+; based on the values given in d and e respectively.
+SetupText: ; 2275 (0:2275)
 	ld a, d
 	dec a
 	ld [wcd04], a
@@ -6395,11 +6515,11 @@ Func_2275: ; 2275 (0:2275)
 	ld a, $80
 	ld [wTilePatternSelectorCorrection], a
 	ld hl, wc600
-.asm_2292
+.clear_loop
 	xor a
 	ld [hl], a
 	inc l
-	jr nz, .asm_2292
+	jr nz, .clear_loop
 	ret
 
 ; wFontWidth <- FULL_WIDTH
@@ -6447,6 +6567,11 @@ InitTextPrinting: ; 22ae (0:22ae)
 	pop hl
 	ret
 
+; requests a text tile to be generated and prints it in the screen
+; different modes depending on hffb0:
+   ; hffb0 == $0: generate and place text tile
+   ; hffb0 == $2 (bit 1 set): only generate text tile?
+   ; hffb0 == $1 (bit 0 set): not even generate it, but just update text buffers?
 Func_22ca: ; 22ca (0:22ca)
 	push hl
 	push de
@@ -6791,12 +6916,12 @@ CopyTextData: ; 23fd (0:23fd)
 	ret
 ; 0x245d
 
-; convert the number at hl to TX_SYMBOL text format and write it to wTextBuf
+; convert the number at hl to TX_SYMBOL text format and write it to wStringBuffer
 ; replace leading zeros with SYM_SPACE
 TwoByteNumberToTxSymbol_TrimLeadingZeros: ; 245d (0:245d)
 	push de
 	push bc
-	ld de, wTextBuf
+	ld de, wStringBuffer
 	push de
 	ld bc, -10000
 	call .get_digit
@@ -6808,7 +6933,7 @@ TwoByteNumberToTxSymbol_TrimLeadingZeros: ; 245d (0:245d)
 	call .get_digit
 	ld bc, -1
 	call .get_digit
-	xor a
+	xor a ; TX_END
 	ld [de], a
 	pop hl
 	ld e, 5
@@ -6883,7 +7008,7 @@ CreateHalfWidthFontTile: ; 24ca (0:24ca)
 	ldh a, [hBankROM]
 	push af
 	ld a, BANK(HalfWidthFont)
-	call BankswitchHome
+	call BankswitchROM
 	; write the right half of the tile (first character) to wTextTileBuffer + 2n
 	push de
 	ld a, e
@@ -6906,7 +7031,7 @@ CreateHalfWidthFontTile: ; 24ca (0:24ca)
 	ld [hli], a
 	dec b
 	jr nz, .loop
-	call BankpopHome
+	call BankpopROM
 	pop bc
 	ld de, wTextTileBuffer
 	ret
@@ -6968,7 +7093,7 @@ ConvertTileNumberToTileDataAddress: ; 2518 (0:2518)
 ; within the full-width font graphics (FullWidthFonts) in hl
 CreateFullWidthFontTile: ; 252e (0:252e)
 	ld a, BANK(Fonts); BANK(DuelGraphics)
-	call BankpushHome
+	call BankpushROM
 	ld de, wTextTileBuffer
 	push de
 	ld c, TILE_SIZE_1BPP
@@ -6981,7 +7106,7 @@ CreateFullWidthFontTile: ; 252e (0:252e)
 	dec c
 	jr nz, .loop
 	pop de
-	call BankpopHome
+	call BankpopROM
 	ret
 
 ; given two text characters at de, use the char at e (first one)
@@ -7050,6 +7175,7 @@ GetFullWidthFontTileOffset: ; 256d (0:256d)
 	ret
 ; 0x2589
 
+; pointers to VRAM?
 Unknown_2589: ; 2589 (0:2589)
 	db $18
 	dw $8140
@@ -7102,11 +7228,11 @@ Unknown_2589: ; 2589 (0:2589)
 	dw $ffff
 ; 0x25ea
 
-; initializes parameters for a card list (e.g. list of hand cards in a duel or booster pack cards)
+; 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
+   ; 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
@@ -7140,10 +7266,10 @@ InitializeCardListParameters: ; 25ea (0:25ea)
 	ret
 ; 0x2626
 
-; similar to HandleMenuInput, but conveniently returns parameters related
-; to the state of the list in a, d, and e if A or B were pressed.
-; also returns carry if A or B were pressed, nc otherwise.
-; used in the Hand card list and Discard Pile card list screens.
+; similar to HandleMenuInput, but conveniently returns parameters related to the
+; state of the list in a, d, and e if A or B were pressed. also returns carry
+; if A or B were pressed, nc otherwise. returns -1 in a if B was pressed.
+; used for example in the Hand card list and Discard Pile card list screens.
 HandleCardListInput: ; 2626 (0:2626)
 	call HandleMenuInput
 	ret nc
@@ -7157,15 +7283,15 @@ HandleCardListInput: ; 2626 (0:2626)
 ; 0x2636
 
 ; initializes parameters for a menu, given the 8 bytes starting at hl,
-; which represent the following:
-;   cursor x coord, cursor y coord, y displacement between items, number of items,
-;   cursor tile number, tile behind cursor, function pointer if non-0.
-; also sets the current menu item to the one specified in register a
+; which are loaded to the following addresses:
+;   wCursorXPosition, wCursorYPosition, wYDisplacementBetweenMenuItems, wNumMenuItems,
+;   wCursorTile, wTileBehindCursor, wMenuFunctionPointer.
+; also sets the current menu item (wCurMenuItem) to the one specified in register a.
 InitializeMenuParameters: ; 2636 (0:2636)
 	ld [wCurMenuItem], a
 	ldh [hCurMenuItem], a
 	ld de, wCursorXPosition
-	ld b, $8
+	ld b, wMenuFunctionPointer + $2 - wCursorXPosition
 .loop
 	ld a, [hli]
 	ld [de], a
@@ -7178,10 +7304,11 @@ InitializeMenuParameters: ; 2636 (0:2636)
 
 ; returns with the carry flag set if A or B were pressed
 ; returns a = 0 if A was pressed, a = -1 if B was pressed
+; note: return values still subject to those of the function at [wMenuFunctionPointer] if any
 HandleMenuInput: ; 264b (0:264b)
 	xor a
 	ld [wRefreshMenuCursorSFX], a
-	ldh a, [hButtonsPressed2]
+	ldh a, [hDPadHeld]
 	or a
 	jr z, .up_down_done
 	ld b, a
@@ -7235,12 +7362,12 @@ HandleMenuInput: ; 264b (0:264b)
 	scf
 	ret
 .check_A_or_B
-	ldh a, [hButtonsPressed]
+	ldh a, [hKeysPressed]
 	and A_BUTTON | B_BUTTON
 	jr z, RefreshMenuCursor_CheckPlaySFX
 	and A_BUTTON
-	jr nz, HandleMenuInput.A_pressed_draw_cursor
-	; b button pressed
+	jr nz, .A_pressed_draw_cursor
+	; B button pressed
 	ld a, [wCurMenuItem]
 	ld e, a
 	ld a, $ff
@@ -7274,6 +7401,7 @@ RefreshMenuCursor_CheckPlaySFX: ; 26d1 (0:26d1)
 	jr z, RefreshMenuCursor
 	call PlaySFX
 ;	fallthrough
+
 RefreshMenuCursor: ; 26da (0:26da)
 	ld hl, wCursorBlinkCounter
 	ld a, [hl]
@@ -7284,9 +7412,15 @@ RefreshMenuCursor: ; 26da (0:26da)
 	ld a, [wCursorTile]
 	bit 4, [hl]
 	jr z, DrawCursor
+;	fallthrough
+
+; set the tile at [wCursorXPosition],[wCursorYPosition] to [wTileBehindCursor]
 EraseCursor: ; 26e9 (0:26e9)
 	ld a, [wTileBehindCursor]
-DrawCursor:
+;	fallthrough
+
+; set the tile at [wCursorXPosition],[wCursorYPosition] to a
+DrawCursor: ; 26ec (0:26ec)
 	ld c, a
 	ld a, [wYDisplacementBetweenMenuItems]
 	ld l, a
@@ -7307,11 +7441,12 @@ DrawCursor:
 	or a
 	ret
 
-; unlike DrawCursor, read cursor tile from wCursorTile instead of register a
+; set the tile at [wCursorXPosition],[wCursorYPosition] to [wCursorTile]
 DrawCursor2: ; 270b (0:270b)
 	ld a, [wCursorTile]
 	jr DrawCursor
 
+; set wCurMenuItem, and hCurMenuItem to a, and zero wCursorBlinkCounter
 SetMenuItem: ; 2710 (0:2710)
 	ld [wCurMenuItem], a
 	ldh [hCurMenuItem], a
@@ -7322,9 +7457,9 @@ 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 PrintDuelMenu.handle_input
+; other input in handled by PrintDuelMenuAndHandleInput.handle_input
 HandleDuelMenuInput: ; 271a (0:271a)
-	ldh a, [hButtonsPressed2]
+	ldh a, [hDPadHeld]
 	or a
 	jr z, .blink_cursor
 	ld b, a
@@ -7365,7 +7500,7 @@ HandleDuelMenuInput: ; 271a (0:271a)
 	ld [wCursorBlinkCounter], a
 	jr .blink_cursor
 .dpad_not_pressed
-	ldh a, [hButtonsPressed2]
+	ldh a, [hDPadHeld]
 	and A_BUTTON
 	jp nz, HandleMenuInput.A_pressed
 .blink_cursor
@@ -7408,7 +7543,11 @@ DuelMenuCursorCoords: ; 278d (0:278d)
 	db 14, 16 ; Done
 
 ; print the items of a list of cards (hand cards in a duel, cards from a booster pack...)
-; and initialize the parameters of the list
+; and initialize the parameters of the list given:
+   ; wDuelTempList = card list source
+   ; a = list length
+   ; de = initial page scroll offset, initial item (in the visible page)
+   ; hl: 9 bytes with the rest of the parameters
 PrintCardListItems: ; 2799 (0:2799)
 	call InitializeCardListParameters
 	ld hl, wMenuFunctionPointer
@@ -7420,7 +7559,11 @@ PrintCardListItems: ; 2799 (0:2799)
 	ld [wYDisplacementBetweenMenuItems], a
 	ld a, 1
 	ld [wCardListIndicatorYPosition], a
-.reload
+;	fallthrough
+
+; like PrintCardListItems, except more parameters are already initialized
+; called instead of PrintCardListItems to reload the list after moving up or down
+ReloadCardListItems:
 	ld e, SYM_SPACE
 	ld a, [wListScrollOffset]
 	or a
@@ -7492,10 +7635,11 @@ PrintCardListItems: ; 2799 (0:2799)
 	ret
 ; 0x2827
 
+; reload a list of cards, except don't print their names
 Func_2827: ; 2827 (0:2827)
 	ld a, $01
 	ldh [hffb0], a
-	call PrintCardListItems.reload
+	call ReloadCardListItems
 	xor a
 	ldh [hffb0], a
 	ret
@@ -7511,7 +7655,7 @@ OneByteNumberToTxSymbol_TrimLeadingZerosAndAlign: ; 2832 (0:2832)
 	; shift number one tile to the left
 	ld a, [hld]
 	ld [hli], a
-	ld [hl], $00
+	ld [hl], SYM_SPACE
 .not_zero
 	ret
 ; 0x283f
@@ -7519,7 +7663,7 @@ OneByteNumberToTxSymbol_TrimLeadingZerosAndAlign: ; 2832 (0:2832)
 ; this function is always loaded to wMenuFunctionPointer by PrintCardListItems
 ; takes care of things like handling page scrolling and calling the function at wListFunctionPointer
 CardListMenuFunction: ; 283f (0:283f)
-	ldh a, [hButtonsPressed2]
+	ldh a, [hDPadHeld]
 	ld b, a
 	ld a, [wNumMenuItems]
 	dec a
@@ -7537,7 +7681,7 @@ CardListMenuFunction: ; 283f (0:283f)
 	or a ; can we scroll up?
 	jr z, .no_more_items
 	dec [hl] ; scroll page up
-	call PrintCardListItems.reload
+	call ReloadCardListItems
 	jp .continue
 .not_up
 	bit D_DOWN_F, b
@@ -7555,7 +7699,7 @@ CardListMenuFunction: ; 283f (0:283f)
 	jr z, .no_more_items
 	ld hl, wListScrollOffset
 	inc [hl] ; scroll page down
-	call PrintCardListItems.reload
+	call ReloadCardListItems
 	jp .continue
 .not_last_visible_item
 	; this appears to be a redundant check
@@ -7580,7 +7724,7 @@ CardListMenuFunction: ; 283f (0:283f)
 	sub [hl]
 	jr c, .top_of_page_reached
 	ld [wListScrollOffset], a
-	call PrintCardListItems.reload
+	call ReloadCardListItems
 	jr .continue
 .top_of_page_reached
 	call EraseCursor
@@ -7597,7 +7741,7 @@ CardListMenuFunction: ; 283f (0:283f)
 	xor a
 	ld [wListScrollOffset], a
 	ld [wRefreshMenuCursorSFX], a
-	call PrintCardListItems.reload
+	call ReloadCardListItems
 	jr .continue
 .not_left
 	bit D_RIGHT_F, b
@@ -7617,7 +7761,7 @@ CardListMenuFunction: ; 283f (0:283f)
 	jr nc, .asm_28f9
 	ld a, c
 	ld [wListScrollOffset], a
-	call PrintCardListItems.reload
+	call ReloadCardListItems
 	jr .continue
 .asm_28f9
 	call EraseCursor
@@ -7636,7 +7780,7 @@ CardListMenuFunction: ; 283f (0:283f)
 	add [hl]
 .asm_2914
 	ld [wCurMenuItem], a
-	call PrintCardListItems.reload
+	call ReloadCardListItems
 .continue
 	ld a, [wListScrollOffset]
 	ld hl, wCurMenuItem
@@ -7672,7 +7816,7 @@ CardListMenuFunction: ; 283f (0:283f)
 	ldh a, [hCurMenuItem]
 	jp hl ; execute the function at wListFunctionPointer
 .no_list_function
-	ldh a, [hButtonsPressed]
+	ldh a, [hKeysPressed]
 	and A_BUTTON | B_BUTTON
 	ret z
 	and B_BUTTON
@@ -7781,7 +7925,7 @@ DrawCardSymbol: ; 29ac (0:29ac)
 ; 0x29dd
 
 CardSymbolTable:
-; starting tile number, cgb palette (grey, red, blue, pink)
+; starting tile number, cgb palette (grey, yellow/red, green/blue, pink/orange)
 	db $e0, $01 ; TYPE_ENERGY_FIRE
 	db $e4, $02 ; TYPE_ENERGY_GRASS
 	db $e8, $01 ; TYPE_ENERGY_LIGHTNING
@@ -7790,7 +7934,7 @@ CardSymbolTable:
 	db $f4, $03 ; TYPE_ENERGY_FIGHTING
 	db $f8, $00 ; TYPE_ENERGY_DOUBLE_COLORLESS
 	db $fc, $02 ; TYPE_ENERGY_UNUSED
-	db $d0, $02 ; TYPE_PKMN_*, Stage 0
+	db $d0, $02 ; TYPE_PKMN_*, Basic
 	db $d4, $02 ; TYPE_PKMN_*, Stage 1
 	db $d8, $01 ; TYPE_PKMN_*, Stage 2
 	db $dc, $02 ; TYPE_TRAINER
@@ -7802,7 +7946,10 @@ CopyCardNameAndLevel: ; 29f5 (0:29f5)
 	ret
 ; 0x29fa
 
-Func_29fa: ; 29fa (0:29fa)
+; sets cursor parameters for navigating in a text box, but using
+; default values for the cursor tile (SYM_CURSOR_R) and the tile behind it (SYM_SPACE).
+; d,e: coordinates of the cursor
+SetCursorParametersForTextBox_Default: ; 29fa (0:29fa)
 	lb bc, SYM_CURSOR_R, SYM_SPACE ; cursor tile, tile behind cursor
 	call SetCursorParametersForTextBox
 ;	fallthrough
@@ -7812,7 +7959,7 @@ Func_29fa: ; 29fa (0:29fa)
 WaitForButtonAorB: ; 2a00 (0:2a00)
 	call DoFrame
 	call RefreshMenuCursor
-	ldh a, [hButtonsPressed]
+	ldh a, [hKeysPressed]
 	bit A_BUTTON_F, a
 	jr nz, .a_pressed
 	bit B_BUTTON_F, a
@@ -7825,6 +7972,9 @@ WaitForButtonAorB: ; 2a00 (0:2a00)
 	or a
 	ret
 
+; sets cursor parameters for navigating in a text box
+; d,e: coordinates of the cursor
+; b,c: tile numbers of the cursor and of the tile behind it
 SetCursorParametersForTextBox: ; 2a1a (0:2a1a)
 	xor a
 	ld hl, wCurMenuItem
@@ -7846,7 +7996,7 @@ SetCursorParametersForTextBox: ; 2a1a (0:2a1a)
 
 ; draw a 20x6 text box aligned to the bottom of the screen,
 ; print the text at hl without letter delay, and wait for A or B pressed
-Func_2a30: ; 2a30 (0:2a30)
+DrawWideTextBox_PrintTextNoDelay_Wait: ; 2a30 (0:2a30)
 	call DrawWideTextBox_PrintTextNoDelay
 	jp WaitForWideTextBoxInput
 ; 0x2a36
@@ -7857,7 +8007,7 @@ DrawWideTextBox_PrintTextNoDelay: ; 2a36 (0:2a36)
 	push hl
 	call DrawWideTextBox
 	ld a, 19
-	jr Func_2a44
+	jr DrawTextBox_PrintTextNoDelay
 
 ; draw a 12x6 text box aligned to the bottom left of the screen
 ; and print the text at hl without letter delay
@@ -7867,7 +8017,7 @@ DrawNarrowTextBox_PrintTextNoDelay: ; 2a3e (0:2a3e)
 	ld a, 11
 ;	fallthrough
 
-Func_2a44: ; 2a44 (0:2a44)
+DrawTextBox_PrintTextNoDelay: ; 2a44 (0:2a44)
 	lb de, 1, 14
 	call AdjustCoordinatesForBGScroll
 	call InitTextPrintingInTextbox
@@ -7910,7 +8060,7 @@ DrawNarrowTextBox_WaitForInput: ; 2a7c (0:2a7c)
 .wait_A_or_B_loop
 	call DoFrame
 	call RefreshMenuCursor
-	ldh a, [hButtonsPressed]
+	ldh a, [hKeysPressed]
 	and A_BUTTON | B_BUTTON
 	jr z, .wait_A_or_B_loop
 	ret
@@ -7936,6 +8086,8 @@ DrawWideTextBox: ; 2a9e (0:2a9e)
 DrawWideTextBox_WaitForInput: ; 2aab (0:2aab)
 	call DrawWideTextBox_PrintText
 ;	fallthrough
+
+; wait for A or B to be pressed on a wide (20x6) text box
 WaitForWideTextBoxInput: ; 2aae (0:2aae)
 	xor a
 	ld hl, WideTextBoxMenuParameters
@@ -7944,7 +8096,7 @@ WaitForWideTextBoxInput: ; 2aae (0:2aae)
 .wait_A_or_B_loop
 	call DoFrame
 	call RefreshMenuCursor
-	ldh a, [hButtonsPressed]
+	ldh a, [hKeysPressed]
 	and A_BUTTON | B_BUTTON
 	jr z, .wait_A_or_B_loop
 	call EraseCursor
@@ -7972,44 +8124,51 @@ TwoItemHorizontalMenu: ; 2ad0 (0:2ad0)
 	jp HandleYesOrNoMenu.refresh_menu
 ; 0x2aeb
 
-Func_2aeb: ; 2aeb (0:2aeb)
+YesOrNoMenuWithText_SetCursorToYes: ; 2aeb (0:2aeb)
 	ld a, $01
-	ld [wcd9a], a
+	ld [wDefaultYesOrNo], a
 ;	fallthrough
 
-; display a yes / no menu with custom text provided in hl and handle input
+; display a yes / no menu in a 20x8 textbox with custom text provided in hl and handle input
+; wDefaultYesOrNo determines whether the cursor initially points to YES or to NO
 ; returns carry if "no" selected
 YesOrNoMenuWithText: ; 2af0 (0:2af0)
 	call DrawWideTextBox_PrintText
 ;	fallthrough
+
+; prints the YES / NO menu items at coordinates x,y = 7,16 and handles input
+; input: wDefaultYesOrNo. returns carry if "no" selected
 YesOrNoMenu: ; 2af3 (0:2af3)
 	lb de, 7, 16 ; x, y
 	call PrintYesOrNoItems
 	lb de, 6, 16 ; x, y
 	jr HandleYesOrNoMenu
 
+; prints the YES / NO menu items at coordinates x,y = 3,16 and handles input
+; input: wDefaultYesOrNo. returns carry if "no" selected
 YesOrNoMenuWithText_LeftAligned: ; 2afe (0:2afe)
 	call DrawNarrowTextBox_PrintTextNoDelay
 	lb de, 3, 16 ; x, y
 	call PrintYesOrNoItems
 	lb de, 2, 16 ; x, y
 ;	fallthrough
+
 HandleYesOrNoMenu:
 	ld a, d
 	ld [wLeftmostItemCursorX], a
 	lb bc, SYM_CURSOR_R, SYM_SPACE ; cursor tile, tile behind cursor
 	call SetCursorParametersForTextBox
-	ld a, [wcd9a]
+	ld a, [wDefaultYesOrNo]
 	ld [wCurMenuItem], a
 	call EnableLCD
 	jr .refresh_menu
 .wait_button_loop
 	call DoFrame
 	call RefreshMenuCursor
-	ldh a, [hButtonsPressed]
+	ldh a, [hKeysPressed]
 	bit A_BUTTON_F, a
 	jr nz, .a_pressed
-	ldh a, [hButtonsPressed2]
+	ldh a, [hDPadHeld]
 	and D_RIGHT | D_LEFT
 	jr z, .wait_button_loop
 	; left or right pressed, so switch to the other menu item
@@ -8038,11 +8197,11 @@ HandleYesOrNoMenu:
 	or a
 	jr nz, .no
 ;.yes
-	ld [wcd9a], a ; 0
+	ld [wDefaultYesOrNo], a ; 0
 	ret
 .no
 	xor a
-	ld [wcd9a], a ; 0
+	ld [wDefaultYesOrNo], a ; 0
 	ld a, 1
 	ldh [hCurMenuItem], a
 	scf
@@ -8052,17 +8211,19 @@ HandleYesOrNoMenu:
 PrintYesOrNoItems: ; 2b66 (0:2b66)
 	call AdjustCoordinatesForBGScroll
 	ldtx hl, YesOrNoText
-	call Func_2c1b
+	call InitTextPrinting_ProcessTextFromID
 	ret
 ; 0x2b70
 
-Func_2b70: ; 2b70 (0:2b70)
-	ld a, BANK(ContinueDuel)
-	call BankswitchHome
-	jp ContinueDuel
+ContinueDuel: ; 2b70 (0:2b70)
+	ld a, BANK(_ContinueDuel)
+	call BankswitchROM
+	jp _ContinueDuel
 ; 0x2b78
 
-; loads opponent deck to wOpponentDeck
+; loads opponent deck at wOpponentDeckID to wOpponentDeck, and initializes wPlayerDuelistType.
+; on a duel against Sam, also loads PRACTICE_PLAYER_DECK to wPlayerDeck.
+; also, sets wRNG1, wRNG2, and wRNGCounter to $57.
 LoadOpponentDeck: ; 2b78 (0:2b78)
 	xor a
 	ld [wIsPracticeDuel], a
@@ -8071,13 +8232,11 @@ LoadOpponentDeck: ; 2b78 (0:2b78)
 	jr z, .normal_sam_duel
 	or a ; cp SAMS_PRACTICE_DECK_ID
 	jr nz, .not_practice_duel
-
 ; only practice duels will display help messages, but
 ; any duel with Sam will force the PRACTICE_PLAYER_DECK
 ;.practice_sam_duel
 	inc a
 	ld [wIsPracticeDuel], a
-
 .normal_sam_duel
 	xor a
 	ld [wOpponentDeckID], a
@@ -8091,7 +8250,6 @@ LoadOpponentDeck: ; 2b78 (0:2b78)
 	ld [hli], a
 	ld [hl], a
 	xor a
-
 .not_practice_duel
 	inc a
 	inc a ; convert from *_DECK_ID constant read from wOpponentDeckID to *_DECK constant
@@ -8101,7 +8259,6 @@ LoadOpponentDeck: ; 2b78 (0:2b78)
 	jr c, .valid_deck
 	ld a, PRACTICE_PLAYER_DECK_ID
 	ld [wOpponentDeckID], a
-
 .valid_deck
 ; set opponent as controlled by AI
 	ld a, DUELVARS_DUELIST_TYPE
@@ -8122,7 +8279,7 @@ Func_2bc3: ; 2bc3 (0:2bc3)
 Func_2bc7: ; 2bc7 (0:2bc7)
 	ld a, $3
 	call Func_2bdb
-	ldh [hTempPlayAreaLocationOffset_ff9d], a
+	ldh [hTempPlayAreaLocation_ff9d], a
 	ret
 
 Func_2bcf: ; 2bcf (0:2bcf)
@@ -8139,13 +8296,13 @@ Func_2bdb: ; 2bdb (0:2bdb)
 	ld c, a
 	ldh a, [hBankROM]
 	push af
-	ld a, $5
-	call BankswitchHome
+	ld a, BANK(PointerTable_14000)
+	call BankswitchROM
 	ld a, [wOpponentDeckID]
 	ld l, a
 	ld h, $0
 	add hl, hl
-	ld de, $4000
+	ld de, PointerTable_14000
 	add hl, de
 	ld a, [hli]
 	ld h, [hl]
@@ -8163,7 +8320,7 @@ Func_2bdb: ; 2bdb (0:2bdb)
 .asm_2c01
 	ld c, a
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ld a, c
 	ret
 
@@ -8179,36 +8336,49 @@ PlaceTextItems: ; 2c08 (0:2c08)
 	inc hl ; hl = text id
 	call InitTextPrinting
 	push hl
-	call Func_2c23
+	call ProcessTextFromPointerToID
 	pop hl
 	inc hl
 	inc hl
 	jr PlaceTextItems ; do next item
 
-Func_2c1b: ; 2c1b (0:2c1b)
+; like ProcessTextFromID, except it calls InitTextPrinting first
+InitTextPrinting_ProcessTextFromID: ; 2c1b (0:2c1b)
 	call InitTextPrinting
-	jr Func_2c29
+	jr ProcessTextFromID
 
-Func_2c20: ; 2c20 (0:2c20)
+; like ProcessTextFromPointerToID, except it calls InitTextPrinting first
+ProcessTextFromPointerToID_InitTextPrinting: ; 2c20 (0:2c20)
 	call InitTextPrinting
-Func_2c23: ; 2c23 (0:2c23)
+;	fallthrough
+
+; like ProcessTextFromID below, except a memory address containing a text ID is
+; provided in hl rather than the text ID directly.
+ProcessTextFromPointerToID: ; 2c23 (0:2c23)
 	ld a, [hli]
 	or [hl]
 	ret z
 	ld a, [hld]
 	ld l, [hl]
 	ld h, a
-Func_2c29: ; 2c29 (0:2c29)
+;	fallthrough
+
+; given the ID of a text in hl, reads the characters from it processes them.
+; loops until TX_END is found. ignores TX_RAM1, TX_RAM2, and TX_RAM3 characters.
+; restores original ROM bank before returning.
+ProcessTextFromID: ; 2c29 (0:2c29)
 	ldh a, [hBankROM]
 	push af
 	call GetTextOffsetFromTextID
 	call ProcessText
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 ; 0x2c37
 
-Func_2c37: ; 2c37 (0:2c37)
+; return, in a, the number of lines of the text given in hl as an ID
+; this is calculated by counting the amount of '\n' characters and adding 1 to the result
+CountLinesOfTextFromID: ; 2c37 (0:2c37)
 	push hl
 	push de
 	push bc
@@ -8233,7 +8403,7 @@ Func_2c37: ; 2c37 (0:2c37)
 	jr .char_loop
 .end
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ld a, c
 	inc a
 	pop bc
@@ -8242,10 +8412,13 @@ Func_2c37: ; 2c37 (0:2c37)
 	ret
 ; 0x2c62
 
-Func_2c62: ; 2c62 (0:2c62)
-	call .asm_2c67
+; call PrintScrollableText with text box label, then wait for the
+; player to press A or B to advance the printed text
+PrintScrollableText_WithTextBoxLabel: ; 2c62 (0:2c62)
+	call PrintScrollableText_WithTextBoxLabel_NoWait
 	jr WaitForPlayerToAdvanceText
-.asm_2c67
+
+PrintScrollableText_WithTextBoxLabel_NoWait: ; 2c67 (0:2c67)
 	push hl
 	ld hl, wTextBoxLabel
 	ld [hl], e
@@ -8255,12 +8428,15 @@ Func_2c62: ; 2c62 (0:2c62)
 	ld a, $01
 	jr PrintScrollableText
 
-Func_2c73: ; 2c73 (0:2c73)
+; call PrintScrollableText with no text box label, then wait for the
+; player to press A or B to advance the printed text
+PrintScrollableText_NoTextBoxLabel: ; 2c73 (0:2c73)
 	xor a
 	call PrintScrollableText
+;	fallthrough
 
-; when a text box is full, prompt the player to press A or B
-; in order to clear the text and print the next lines.
+; when a text box is full or the text is over, prompt the player to
+; press A or B in order to clear the text and print the next lines.
 WaitForPlayerToAdvanceText: ; 2c77 (0:2c77)
 	lb bc, SYM_CURSOR_D, SYM_BOX_BOTTOM ; cursor tile, tile behind cursor
 	lb de, 18, 17 ; x, y
@@ -8268,16 +8444,17 @@ WaitForPlayerToAdvanceText: ; 2c77 (0:2c77)
 	call WaitForButtonAorB
 	ret
 
-; prints text with id at hl, with letter delay, in a textbox area.
-; unlike PrintText, PrintScrollableText supports scrollable text, and prompts
-; the user to press A or B to advance the page or close the text.
-; used mostly for overworld NPC text.
+; draws a text box, and prints the text with id at hl, with letter delay. unlike PrintText,
+; PrintScrollableText also supports scrollable text, and prompts the user to press A or B
+; to advance the page or close the text. register a determines whether the textbox is
+; labeled or not. if labeled, the text id of the label is provided in wTextBoxLabel.
+; PrintScrollableText is used mostly for overworld NPC text.
 PrintScrollableText: ; 2c84 (0:2c84)
 	ld [wIsTextBoxLabeled], a
 	ldh a, [hBankROM]
 	push af
 	call GetTextOffsetFromTextID
-	call Func_2d15
+	call DrawTextReadyLabeledOrRegularTextBox
 	call ResetTxRam_WriteToTextHeader
 .print_char_loop
 	ld a, [wTextSpeed]
@@ -8289,7 +8466,7 @@ PrintScrollableText: ; 2c84 (0:2c84)
 	cp 2
 	jr nc, .apply_delay
 	; if text speed is 1, pressing b ignores it
-	ldh a, [hButtonsHeld]
+	ldh a, [hKeysHeld]
 	and B_BUTTON
 	jr nz, .skip_delay
 .apply_delay
@@ -8307,11 +8484,11 @@ PrintScrollableText: ; 2c84 (0:2c84)
 	jr c, .print_char_loop
 	; two lines of text already printed, so need to advance text
 	call WaitForPlayerToAdvanceText
-	call Func_2d15
+	call DrawTextReadyLabeledOrRegularTextBox
 	jr .print_char_loop
 .asm_2cc3
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 
 ; zero wWhichTextHeader, wWhichTxRam2 and wWhichTxRam3, and set hJapaneseSyllabary to TX_KATAKANA
@@ -8361,7 +8538,7 @@ ReadTextHeader: ; 2cf3 (0:2cf3)
 	ld a, [hli]
 	ld [wFontWidth], a
 	ld a, [hli]
-	call BankswitchHome
+	call BankswitchROM
 	ld a, [hli]
 	ld h, [hl]
 	ld l, a
@@ -8380,7 +8557,10 @@ GetPointerToTextHeader: ; 2d06 (0:2d06)
 	add hl, de
 	ret
 
-Func_2d15: ; 2d15 (0:2d15)
+; draws a wide text box with or without label depending on wIsTextBoxLabeled
+; if labeled, the label's text ID is provided in wTextBoxLabel
+; calls InitTextPrintingInTextbox after drawing the text box
+DrawTextReadyLabeledOrRegularTextBox: ; 2d15 (0:2d15)
 	push hl
 	lb de, 0, 12
 	lb bc, 20, 6
@@ -8483,7 +8663,7 @@ ProcessTextHeader: ; 2d43 (0:2d43)
 .tx_ram1
 	call WriteToTextHeader_MoveToNext
 	call CopyPlayerNameOrTurnDuelistName
-	ld a, [wTextBuf]
+	ld a, [wStringBuffer]
 	cp TX_HALFWIDTH
 	jr z, .tx_halfwidth
 	ld a, TX_HALF2FULL
@@ -8521,7 +8701,7 @@ GetTextOffsetFromTextID: ; 2ded (0:2ded)
 	add hl, de
 	set 6, h ; hl = (hl * 3) + $4000
 	ld a, BANK(TextOffsets)
-	call BankswitchHome
+	call BankswitchROM
 	ld e, [hl]
 	inc hl
 	ld d, [hl]
@@ -8533,7 +8713,7 @@ GetTextOffsetFromTextID: ; 2ded (0:2ded)
 	rl h
 	rla
 	add BANK(TextOffsets)
-	call BankswitchHome
+	call BankswitchROM
 	res 7, d
 	set 6, d ; $4000 ≤ de ≤ $7fff
 	ld l, e
@@ -8542,16 +8722,16 @@ GetTextOffsetFromTextID: ; 2ded (0:2ded)
 	ret
 
 ; if [wFontWidth] == HALF_WIDTH:
-;   convert the number at hl to text (ascii) format and write it to wTextBuf
+;   convert the number at hl to text (ascii) format and write it to wStringBuffer
 ;   return c = 4 - leading_zeros
 ; if [wFontWidth] == FULL_WIDTH:
-;   convert the number at hl to TX_SYMBOL text format and write it to wTextBuf
+;   convert the number at hl to TX_SYMBOL text format and write it to wStringBuffer
 ;   replace leading zeros with SYM_SPACE
 TwoByteNumberToText_CountLeadingZeros: ; 2e12 (0:2e12)
 	ld a, [wFontWidth]
 	or a ; FULL_WIDTH
 	jp z, TwoByteNumberToTxSymbol_TrimLeadingZeros
-	ld de, wTextBuf
+	ld de, wStringBuffer
 	push de
 	call TwoByteNumberToText
 	pop hl
@@ -8565,10 +8745,10 @@ TwoByteNumberToText_CountLeadingZeros: ; 2e12 (0:2e12)
 	jr nz, .digit_loop
 	ret
 
-; in the overworld: copy the player's name to wTextBuf
-; in a duel: copy the name of the duelist whose turn it is to wTextBuf
+; in the overworld: copy the player's name to wStringBuffer
+; in a duel: copy the name of the duelist whose turn it is to wStringBuffer
 CopyPlayerNameOrTurnDuelistName: ; 2e2c (0:2e2c)
-	ld de, wTextBuf
+	ld de, wStringBuffer
 	push de
 	ldh a, [hWhoseTurn]
 	cp OPPONENT_TURN
@@ -8592,14 +8772,14 @@ PrintText: ; 2e41 (0:2e41)
 	call GetTextOffsetFromTextID
 	call .print_text
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 .from_ram
 	ld hl, wDefaultText
 .print_text
 	call ResetTxRam_WriteToTextHeader
 .next_tile_loop
-	ldh a, [hButtonsHeld]
+	ldh a, [hKeysHeld]
 	ld b, a
 	ld a, [wTextSpeed]
 	inc a
@@ -8631,7 +8811,7 @@ PrintTextNoDelay: ; 2e76 (0:2e76)
 	call ProcessTextHeader
 	jr nc, .next_tile_loop
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 
 ; copies a text given its id at hl, to de
@@ -8650,7 +8830,7 @@ CopyText: ; 2e89 (0:2e89)
 	or a
 	jr nz, .next_tile_loop
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	dec de
 	ret
 .special
@@ -8660,7 +8840,11 @@ CopyText: ; 2e89 (0:2e89)
 	jp CopyPlayerName
 ; 0x2ea9
 
-Func_2ea9: ; 2ea9 (0:2ea9)
+; copy text of maximum length a (in tiles) from its ID at hl to de,
+; then terminate the text with TX_END if it doesn't contain it already.
+; fill any remaining bytes with spaces plus TX_END to match the length specified in a.
+; return the text's actual length in characters (i.e. before the first TX_END) in e.
+CopyTextData_FromTextID: ; 2ea9 (0:2ea9)
 	ldh [hff96], a
 	ldh a, [hBankROM]
 	push af
@@ -8668,7 +8852,7 @@ Func_2ea9: ; 2ea9 (0:2ea9)
 	ldh a, [hff96]
 	call CopyTextData
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 ; 0x2ebb
 
@@ -8693,7 +8877,7 @@ LoadTxRam3: ; 2ec4 (0:2ec4)
 LoadCardDataToBuffer1_FromName: ; 2ecd (0:2ecd)
 	ld hl, CardPointers + 2 ; skip first $0000 pointer
 	ld a, BANK(CardPointers)
-	call BankpushHome2
+	call BankpushROM2
 .find_card_loop
 	ld a, [hli]
 	or [hl]
@@ -8703,7 +8887,7 @@ LoadCardDataToBuffer1_FromName: ; 2ecd (0:2ecd)
 	ld l, [hl]
 	ld h, a
 	ld a, BANK(CardPointers)
-	call BankpushHome2
+	call BankpushROM2
 	ld bc, CARD_DATA_NAME
 	add hl, bc
 	ld a, [hli]
@@ -8721,7 +8905,7 @@ LoadCardDataToBuffer1_FromName: ; 2ecd (0:2ecd)
 	ld l, [hl]
 	ld h, a
 	ld a, BANK(CardPointers)
-	call BankpushHome2
+	call BankpushROM2
 	ld de, wLoadedCard1
 	ld b, PKMN_CARD_DATA_LENGTH
 .copy_card_loop
@@ -8732,7 +8916,7 @@ LoadCardDataToBuffer1_FromName: ; 2ecd (0:2ecd)
 	jr nz, .copy_card_loop
 	pop hl
 .done
-	call BankpopHome
+	call BankpopROM
 	ret
 ; 0x2f0a
 
@@ -8756,7 +8940,7 @@ LoadCardDataToHL_FromCardID: ; 2f14 (0:2f14)
 	pop de
 	jr c, .done
 	ld a, BANK(CardPointers)
-	call BankpushHome2
+	call BankpushROM2
 	ld b, PKMN_CARD_DATA_LENGTH
 .copy_card_data_loop
 	ld a, [hli]
@@ -8764,7 +8948,7 @@ LoadCardDataToHL_FromCardID: ; 2f14 (0:2f14)
 	inc de
 	dec b
 	jr nz, .copy_card_data_loop
-	call BankpopHome
+	call BankpopROM
 	or a
 .done
 	pop bc
@@ -8778,9 +8962,9 @@ GetCardType: ; 2f32 (0:2f32)
 	call GetCardPointer
 	jr c, .done
 	ld a, BANK(CardPointers)
-	call BankpushHome2
+	call BankpushROM2
 	ld l, [hl]
-	call BankpopHome
+	call BankpopROM
 	ld a, l
 	or a
 .done
@@ -8793,13 +8977,13 @@ GetCardName: ; 2f45 (0:2f45)
 	call GetCardPointer
 	jr c, .done
 	ld a, BANK(CardPointers)
-	call BankpushHome2
+	call BankpushROM2
 	ld de, CARD_DATA_NAME
 	add hl, de
 	ld e, [hl]
 	inc hl
 	ld d, [hl]
-	call BankpopHome
+	call BankpopROM
 	or a
 .done
 	pop hl
@@ -8814,14 +8998,14 @@ GetCardTypeRarityAndSet: ; 2f5d (0:2f5d)
 	call GetCardPointer
 	jr c, .done
 	ld a, BANK(CardPointers)
-	call BankpushHome2
+	call BankpushROM2
 	ld e, [hl] ; CARD_DATA_TYPE
 	ld bc, CARD_DATA_RARITY
 	add hl, bc
 	ld b, [hl] ; CARD_DATA_RARITY
 	inc hl
 	ld c, [hl] ; CARD_DATA_SET
-	call BankpopHome
+	call BankpopROM
 	ld a, e
 	or a
 .done
@@ -8848,11 +9032,11 @@ GetCardPointer: ; 2f7c (0:2f7c)
 	ccf
 	jr c, .out_of_bounds
 	ld a, BANK(CardPointers)
-	call BankpushHome2
+	call BankpushROM2
 	ld a, [hli]
 	ld h, [hl]
 	ld l, a
-	call BankpopHome
+	call BankpopROM
 	or a
 .out_of_bounds
 	pop bc
@@ -8860,9 +9044,9 @@ GetCardPointer: ; 2f7c (0:2f7c)
 	ret
 
 ; 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
+   ; 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)
@@ -8875,7 +9059,7 @@ LoadCardGfx: ; 2fa0 (0:2fa0)
 	srl h
 	ld a, BANK(CardGraphics)
 	add h
-	call BankswitchHome
+	call BankswitchROM
 	pop hl
 	; once we have the bank, get the pointer: multiply by 8 and discard the bank offset
 	add hl, hl
@@ -8893,26 +9077,26 @@ LoadCardGfx: ; 2fa0 (0:2fa0)
 	dec b
 	jr nz, .copy_card_palette
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 
 ; identical to CopyFontsOrDuelGraphicsTiles
 CopyFontsOrDuelGraphicsTiles2: ; 2fcb (0:2fcb)
 	ld a, BANK(Fonts); BANK(DuelGraphics)
-	call BankpushHome
+	call BankpushROM
 	ld c, TILE_SIZE
 	call CopyGfxData
-	call BankpopHome
+	call BankpopROM
 	ret
 
-; Checks if the command type at a is one of the commands of the move or card effect currently in use,
-; and executes its associated function if so.
+; Checks if the command type at a is one of the commands of the move or
+; card effect currently in use, and executes its associated function if so.
 ; input:
-; a = command type to check
-; [wLoadedMoveEffectCommands] = pointer to list of commands of current move or trainer card
+   ; a = command type to check
+   ; [wLoadedMoveEffectCommands] = pointer to list of commands of current move or trainer card
 TryExecuteEffectCommandFunction: ; 2fd9 (0:2fd9)
 	push af
-; grab pointer to command list from wLoadedMoveEffectCommands
+	; grab pointer to command list from wLoadedMoveEffectCommands
 	ld hl, wLoadedMoveEffectCommands
 	ld a, [hli]
 	ld h, [hl]
@@ -8920,37 +9104,37 @@ TryExecuteEffectCommandFunction: ; 2fd9 (0:2fd9)
 	pop af
 	call CheckMatchingCommand
 	jr nc, .execute_function
-; return if no matching command was found
+	; return if no matching command was found
 	or a
 	ret
 
 .execute_function
-; executes the function at [wce22]:hl
+	; execute the function at [wce22]:hl
 	ldh a, [hBankROM]
 	push af
 	ld a, [wce22]
-	call BankswitchHome
+	call BankswitchROM
 	or a
 	call CallHL
 	push af
-; restore original bank and return
+	; restore original bank and return
 	pop bc
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	push bc
 	pop af
 	ret
 
 ; input:
-  ; a = command type to check
-  ; hl = list of commands of current move or trainer card
+   ; a = command type to check
+   ; hl = list of commands of current move or trainer card
 ; 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 carry if pointer is $0000
+	; return carry if pointer is $0000
 	scf
 	ret
 
@@ -8958,8 +9142,8 @@ CheckMatchingCommand: ; 2ffe (0:2ffe)
 	ldh a, [hBankROM]
 	push af
 	ld a, BANK(EffectCommands)
-	call BankswitchHome
-; store the bank number of command functions ($b) in wce22
+	call BankswitchROM
+	; store the bank number of command functions ($b) in wce22
 	ld a, $b
 	ld [wce22], a
 .check_command_loop
@@ -8968,30 +9152,32 @@ CheckMatchingCommand: ; 2ffe (0:2ffe)
 	jr z, .no_more_commands
 	cp c
 	jr z, .matching_command_found
-; skip function pointer for this command and move to the next one
+	; skip function pointer for this command and move to the next one
 	inc hl
 	inc hl
 	jr .check_command_loop
 
 .matching_command_found
-; load function pointer for this command
+	; load function pointer for this command
 	ld a, [hli]
 	ld h, [hl]
 	ld l, a
-; restore bank and return nc
+	; restore bank and return nc
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	or a
 	ret
-; restore bank and return c
+
 .no_more_commands
+	; restore bank and return c
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	scf
 	ret
 
-; loads the deck id in a from DeckPointers
-; sets carry flag if an invalid deck id is used
+; loads the deck id in a from DeckPointers and copies it to wPlayerDeck or to
+; wOpponentDeck, depending on whose turn it is.
+; sets carry flag if an invalid deck id is used.
 LoadDeck: ; 302c (0:302c)
 	push hl
 	ld l, a
@@ -8999,7 +9185,7 @@ LoadDeck: ; 302c (0:302c)
 	ldh a, [hBankROM]
 	push af
 	ld a, BANK(DeckPointers)
-	call BankswitchHome
+	call BankswitchROM
 	add hl, hl
 	ld de, DeckPointers
 	add hl, de
@@ -9011,29 +9197,31 @@ LoadDeck: ; 302c (0:302c)
 	jr z, .null_pointer
 	call CopyDeckData
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	pop hl
 	or a
 	ret
 .null_pointer
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	pop hl
 	scf
 	ret
 
-Func_3055: ; 3055 (0:3055)
+; [wDamage] += a
+AddToDamage: ; 3055 (0:3055)
 	push hl
 	ld hl, wDamage
 	add [hl]
 	ld [hli], a
-	ld a, $0
+	ld a, 0
 	adc [hl]
 	ld [hl], a
 	pop hl
 	ret
 
-Func_3061: ; 3061 (0:3061)
+; [wDamage] -= a
+SubstractFromDamage: ; 3061 (0:3061)
 	push de
 	push hl
 	ld e, a
@@ -9042,7 +9230,7 @@ Func_3061: ; 3061 (0:3061)
 	sub e
 	ld [hli], a
 	ld a, [hl]
-	sbc $0
+	sbc 0
 	ld [hl], a
 	pop hl
 	pop de
@@ -9051,7 +9239,7 @@ Func_3061: ; 3061 (0:3061)
 ; function that executes one or more consecutive coin tosses during a duel (a = number of coin tosses),
 ; displaying each result ([O] or [X]) starting from the top left corner of the screen.
 ; text at de is printed in a text box during the coin toss.
-;   returns: the number of heads in a and in wcd9d, and carry if at least one heads
+; returns: the number of heads in a and in wCoinTossNumHeads, and carry if at least one heads
 TossCoinATimes: ; 3071 (0:3071)
 	push hl
 	ld hl, wCoinTossScreenTextID
@@ -9064,21 +9252,22 @@ TossCoinATimes: ; 3071 (0:3071)
 
 ; function that executes a single coin toss during a duel.
 ; text at de is printed in a text box during the coin toss.
-;   returns: - carry, and 1 in a and in wcd9d if heads
-;            - nc, and 0 in a and in wcd9d if tails
+; returns: - carry, and 1 in a and in wCoinTossNumHeads if heads
+;          - nc, and 0 in a and in wCoinTossNumHeads if tails
 TossCoin: ; 307d (0:307d)
 	push hl
 	ld hl, wCoinTossScreenTextID
 	ld [hl], e
 	inc hl
 	ld [hl], d
-	ld a, $1
+	ld a, 1
 	bank1call _TossCoin
-	ld hl, wcac2
-	ld [hl], $0
+	ld hl, wDuelDisplayedScreen
+	ld [hl], 0
 	pop hl
 	ret
 
+; cp de, bc
 CompareDEtoBC: ; 3090 (0:3090)
 	ld a, d
 	cp b
@@ -9090,24 +9279,24 @@ CompareDEtoBC: ; 3090 (0:3090)
 Func_3096: ; 3096 (0:3096)
 	ldh a, [hBankROM]
 	push af
-	ld a, $2
-	call BankswitchHome
-	call $4000
+	ld a, BANK(Func_8000)
+	call BankswitchROM
+	call Func_8000
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 
 Func_30a6: ; 30a6 (0:30a6)
 	ldh a, [hBankROM]
 	push af
-	ld a, $6
-	call BankswitchHome
+	ld a, BANK(Func_180d5)
+	call BankswitchROM
 	ld a, $1
 	ld [wce60], a
-	call $40d5
+	call Func_180d5
 	pop bc
 	ld a, b
-	call BankswitchHome
+	call BankswitchROM
 	ret
 
 Func_30bc: ; 30bc (0:30bc)
@@ -9117,33 +9306,33 @@ Func_30bc: ; 30bc (0:30bc)
 	ld [wce51], a
 	ldh a, [hBankROM]
 	push af
-	ld a, $2
-	call BankswitchHome
-	call $4211
+	ld a, BANK(Func_8211)
+	call BankswitchROM
+	call Func_8211
 	call DrawWideTextBox
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 
 Func_30d7: ; 30d7 (0:30d7)
 	ldh a, [hBankROM]
 	push af
-	ld a, $2
-	call BankswitchHome
-	call $433c
+	ld a, BANK(Func_833c)
+	call BankswitchROM
+	call Func_833c
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 
 Func_30e7: ; 30e7 (0:30e7)
 	ldh a, [hBankROM]
 	push af
-	ld a, $2
-	call BankswitchHome
-	call $4764
+	ld a, BANK(Func_8764)
+	call BankswitchROM
+	call Func_8764
 	ld b, a
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ld a, b
 	ret
 
@@ -9151,35 +9340,36 @@ Func_30f9: ; 30f9 (0:30f9)
 	ld b, a
 	ldh a, [hBankROM]
 	push af
-	ld a, $2
-	call BankswitchHome
-	call $4932
+	ld a, BANK(Func_8932)
+	call BankswitchROM
+	call Func_8932
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 
 Func_310a: ; 310a (0:310a)
 	ld [wce59], a
 	ldh a, [hBankROM]
 	push af
-	ld a, $2
-	call BankswitchHome
-	call $4aaa
+	ld a, BANK(Func_8aaa)
+	call BankswitchROM
+	call Func_8aaa
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 
 Func_311d: ; 311d (0:311d)
 	ldh a, [hBankROM]
 	push af
-	ld a, $2
-	call BankswitchHome
-	call $4b85
+	ld a, BANK(Func_8b85)
+	call BankswitchROM
+	call Func_8b85
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 
-Func_312d: ; 312d (0:312d)   ; serial transfer-related
+; serial transfer-related
+Func_312d: ; 312d (0:312d)
 	push hl
 	ld hl, wce64
 	ld a, $88
@@ -9344,44 +9534,45 @@ 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
 
-; doubles the damage at de if swords dance or focus energy was used in the last turn
+; doubles the damage at de if swords dance or focus energy was used
+; in the last turn by the turn holder's arena Pokemon
 HandleDoubleDamageSubstatus: ; 321d (0:321d)
 	ld a, DUELVARS_ARENA_CARD_SUBSTATUS3
 	call GetTurnDuelistVariable
 	bit SUBSTATUS3_THIS_TURN_DOUBLE_DAMAGE, [hl]
-	call nz, DoubleDamageAtDE
+	call nz, .double_damage_at_de
 	ld a, DUELVARS_ARENA_CARD_SUBSTATUS1
 	call GetTurnDuelistVariable
 	or a
-	call nz, CommentedOut_323a
+	call nz, .ret1
 	ld a, DUELVARS_ARENA_CARD_SUBSTATUS2
 	call GetTurnDuelistVariable
 	or a
-	call nz, CommentedOut_3243
+	call nz, .ret2
 	ret
-
-CommentedOut_323a: ; 323a (0:323a)
+.ret1
 	ret
-
-DoubleDamageAtDE: ; 323b (0:323b)
+.double_damage_at_de
 	ld a, e
 	or d
 	ret z
 	sla e
 	rl d
 	ret
-
-CommentedOut_3243: ; 3243 (0:3243)
+.ret2
 	ret
 
-; check if the attacked card has any substatus that reduces the damage this turn
-; damage is given in de as input and the possibly updated damage is also returned in de
+; check if the attacking card (non-turn holder's arena card) has any substatus that
+; reduces the damage dealt this turn (SUBSTATUS2).
+; check if the defending card (turn holder's arena card) has any substatus that
+; reduces the damage dealt to it this turn (SUBSTATUS1 or Pkmn Powers).
+; damage is given in de as input and the possibly updated damage is also returned in de.
 HandleDamageReduction: ; 3244 (0:3244)
 	call HandleDamageReductionExceptSubstatus2
 	ld a, DUELVARS_ARENA_CARD_SUBSTATUS2
@@ -9408,9 +9599,9 @@ HandleDamageReduction: ; 3244 (0:3244)
 	ld d, h
 	ret
 
-; check if the attacked card has any substatus that reduces the damage this turn
-; substatus 2 is not checked
-; damage is given in de as input and the possibly updated damage is also returned in de
+; check if the defending card (turn holder's arena card) has any substatus that
+; reduces the damage dealt to it this turn. (SUBSTATUS1 or Pkmn Powers)
+; damage is given in de as input and the possibly updated damage is also returned in de.
 HandleDamageReductionExceptSubstatus2: ; 3269 (0:3269)
 	ld a, [wNoDamageOrEffect]
 	or a
@@ -9509,7 +9700,7 @@ HandleDamageReductionOrNoDamageFromPkmnPowerEffects: ; 32f7 (0:32f7)
 	ld a, MUK
 	call CountPokemonIDInBothPlayAreas
 	ret c
-	ld a, [wTempPlayAreaLocationOffset_cceb]
+	ld a, [wTempPlayAreaLocation_cceb]
 	or a
 	call nz, HandleDamageReductionExceptSubstatus2.pkmn_power
 	push de ; push damage from call above, which handles Invisible Wall and Kabuto Armor
@@ -9522,26 +9713,27 @@ HandleDamageReductionOrNoDamageFromPkmnPowerEffects: ; 32f7 (0:32f7)
 	ret
 ; 0x3317
 
-; when Machamp is damaged, if its Strikes Back is active,
-; the attacking Pokemon takes 10 damage.
+; when MACHAMP is damaged, if its Strikes Back is active, the
+; attacking Pokemon (turn holder's arena Pokemon) takes 10 damage.
+; ignore if damage taken at de is 0.
 ; used to bounce back a damaging move.
 HandleStrikesBack_AgainstDamagingMove: ; 3317 (0:3317)
 	ld a, e
 	or d
 	ret z
-	ld a, [wDamageToSelfMode]
+	ld a, [wIsDamageToSelf]
 	or a
 	ret nz
-	ld a, [wTempNonTurnDuelistCardID]
+	ld a, [wTempNonTurnDuelistCardID] ; ID of defending Pokemon
 	cp MACHAMP
 	ret nz
 	ld a, MUK
 	call CountPokemonIDInBothPlayAreas
 	ret c
-	ld a, [wLoadedMoveCategory]
+	ld a, [wLoadedMoveCategory] ; category of attack used
 	cp POKEMON_POWER
 	ret z
-	ld a, [wTempPlayAreaLocationOffset_cceb]
+	ld a, [wTempPlayAreaLocation_cceb] ; defending Pokemon's PLAY_AREA_*
 	or a ; cp PLAY_AREA_ARENA
 	jr nz, .in_bench
 	call CheckCannotUseDueToStatus
@@ -9549,6 +9741,7 @@ HandleStrikesBack_AgainstDamagingMove: ; 3317 (0:3317)
 .in_bench
 	push hl
 	push de
+	; substract 10 HP from attacking Pokemon (turn holder's arena Pokemon)
 	call SwapTurn
 	ld a, DUELVARS_ARENA_CARD
 	call GetTurnDuelistVariable
@@ -9583,7 +9776,8 @@ HandleStrikesBack_AgainstDamagingMove: ; 3317 (0:3317)
 	ret
 ; 0x337f
 
-; return carry if NShield or Transparency activate, and print their corresponding text if so
+; return carry if NShield or Transparency activate (if MEW1 or HAUNTER1 is
+; the turn holder's arena Pokemon), and print their corresponding text if so
 HandleNShieldAndTransparency: ; 337f (0:337f)
 	push de
 	ld a, DUELVARS_ARENA_CARD
@@ -9614,7 +9808,7 @@ HandleNShieldAndTransparency: ; 337f (0:337f)
 	ret
 .transparency
 	xor a
-	ld [wcac2], a
+	ld [wDuelDisplayedScreen], a
 	ldtx de, TransparencyCheckText
 	call TossCoin
 	jr nc, .done
@@ -9624,8 +9818,8 @@ HandleNShieldAndTransparency: ; 337f (0:337f)
 	jr .print_text
 ; 0x33c1
 
-; return carry if card is under a condition that makes it unable to attack
-; also return in hl the text id to be displayed
+; return carry if the turn holder's arena Pokemon is under a condition that makes
+; it unable to attack. also return in hl the text id to be displayed
 HandleCantAttackSubstatus: ; 33c1 (0:33c1)
 	ld a, DUELVARS_ARENA_CARD_SUBSTATUS2
 	call GetTurnDuelistVariable
@@ -9646,7 +9840,8 @@ HandleCantAttackSubstatus: ; 33c1 (0:33c1)
 	scf
 	ret
 
-; return carry if card cannot use selected move due to amnesia
+; return carry if the turn holder's arena Pokemon cannot use
+; selected move at wSelectedMoveIndex due to amnesia
 HandleAmnesiaSubstatus: ; 33e1 (0:33e1)
 	ld a, DUELVARS_ARENA_CARD_SUBSTATUS2
 	call GetTurnDuelistVariable
@@ -9669,7 +9864,7 @@ HandleAmnesiaSubstatus: ; 33e1 (0:33e1)
 	scf
 	ret
 
-; return carry if the attack was unsuccessful due to sand attack or smokescreen effect
+; return carry if the turn holder's attack was unsuccessful due to sand attack or smokescreen effect
 HandleSandAttackOrSmokescreenSubstatus: ; 3400 (0:3400)
 	call CheckSandAttackOrSmokescreenSubstatus
 	ret nc
@@ -9682,7 +9877,7 @@ HandleSandAttackOrSmokescreenSubstatus: ; 3400 (0:3400)
 	scf
 	ret
 
-; return carry if card is under the effects of sand attack or smokescreen
+; return carry if the turn holder's arena card is under the effects of sand attack or smokescreen
 CheckSandAttackOrSmokescreenSubstatus: ; 3414 (0:3414)
 	ld a, DUELVARS_ARENA_CARD_SUBSTATUS2
 	call GetTurnDuelistVariable
@@ -9703,9 +9898,9 @@ CheckSandAttackOrSmokescreenSubstatus: ; 3414 (0:3414)
 	scf
 	ret
 
-; return carry if card being attacked is under a substatus that prevents
-; any damage or effect dealt to it for a turn.
-; also return the cause of the substatus at wNoDamageOrEffect
+; return carry if the defending card (turn holder's arena card) is under a substatus
+; that prevents any damage or effect dealt to it for a turn.
+; also return the cause of the substatus in wNoDamageOrEffect
 HandleNoDamageOrEffectSubstatus: ; 3432 (0:3432)
 	xor a
 	ld [wNoDamageOrEffect], a
@@ -9741,7 +9936,7 @@ HandleNoDamageOrEffectSubstatus: ; 3432 (0:3432)
 	scf
 	ret
 .neutralizing_shield
-	ld a, [wDamageToSelfMode]
+	ld a, [wIsDamageToSelf]
 	or a
 	ret nz
 	; prevent damage if attacked by a non-basic Pokemon
@@ -9756,7 +9951,7 @@ HandleNoDamageOrEffectSubstatus: ; 3432 (0:3432)
 	ldtx hl, NoDamageOrEffectDueToNShieldText
 	jr .no_damage_or_effect
 
-; if the Pokemon being attacked is Haunter1, and its Transparency is active,
+; if the Pokemon being attacked is HAUNTER1, and its Transparency is active,
 ; there is a 50% chance that any damage or effect is prevented
 ; return carry if damage is prevented
 HandleTransparency: ; 348a (0:348a)
@@ -9770,11 +9965,11 @@ HandleTransparency: ; 348a (0:348a)
 	ld a, [wLoadedMoveCategory]
 	cp POKEMON_POWER
 	jr z, .done ; Transparency has no effect against Pkmn Powers
-	ld a, [wTempPlayAreaLocationOffset_cceb]
+	ld a, [wTempPlayAreaLocation_cceb]
 	call CheckCannotUseDueToStatus_OnlyToxicGasIfANon0
 	jr c, .done
 	xor a
-	ld [wcac2], a
+	ld [wDuelDisplayedScreen], a
 	ldtx de, TransparencyCheckText
 	call TossCoin
 	ret nc
@@ -9787,6 +9982,7 @@ HandleTransparency: ; 348a (0:348a)
 
 ; 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
+; input: a = NO_DAMAGE_OR_EFFECT_*
 CheckNoDamageOrEffect: ; 34b7 (0:34b7)
 	ld a, [wNoDamageOrEffect]
 	or a
@@ -9831,8 +10027,8 @@ IsClairvoyanceActive: ; 34e2 (0:34e2)
 	call CountPokemonIDInPlayArea
 	ret
 
-; returns carry if paralyzed, asleep, confused, and/or toxic gas in play,
-; meaning that move and/or pkmn power cannot be used
+; returns carry if turn holder's arena card is paralyzed, asleep, confused,
+; and/or toxic gas in play, meaning that move and/or pkmn power cannot be used
 CheckCannotUseDueToStatus: ; 34ef (0:34ef)
 	xor a
 
@@ -9961,7 +10157,7 @@ GetLoadedCard1RetreatCost: ; 356a (0:356a)
 	ret
 ; 0x3597
 
-; return carry if the turn holder's active Pokemon is affected by Acid and can't retreat
+; return carry if the turn holder's arena Pokemon is affected by Acid and can't retreat
 CheckCantRetreatDueToAcid: ; 3597 (0:3597)
 	ld a, DUELVARS_ARENA_CARD_SUBSTATUS2
 	call GetTurnDuelistVariable
@@ -9977,7 +10173,7 @@ CheckCantRetreatDueToAcid: ; 3597 (0:3597)
 	ret
 ; 0x35a9
 
-; return carry if the turn holder's active Pokemon is affected by Headache and trainer cards can't be used
+; return carry if the turn holder is affected by Headache and trainer cards can't be used
 CheckCantUseTrainerDueToHeadache: ; 35a9 (0:35a9)
 	ld a, DUELVARS_ARENA_CARD_SUBSTATUS3
 	call GetTurnDuelistVariable
@@ -10001,7 +10197,7 @@ IsPrehistoricPowerActive: ; 35b7 (0:35b7)
 	ret
 ; 0x35c7
 
-; clears some substatus 2 conditions from the turn holder's active Pokemon
+; clears some SUBSTATUS2 conditions from the turn holder's active Pokemon
 Func_35c7: ; 35c7 (0:35c7)
 	ld a, DUELVARS_ARENA_CARD_SUBSTATUS2
 	call GetTurnDuelistVariable
@@ -10023,7 +10219,7 @@ Func_35c7: ; 35c7 (0:35c7)
 	ret
 ; 0x35e6
 
-; clears the substatus 1 and updates the double damage condition of the player about to start his turn
+; clears the SUBSTATUS1 and updates the double damage condition of the player about to start his turn
 UpdateSubstatusConditions_StartOfTurn: ; 35e6 (0:35e6)
 	ld a, DUELVARS_ARENA_CARD_SUBSTATUS1
 	call GetTurnDuelistVariable
@@ -10037,7 +10233,7 @@ UpdateSubstatusConditions_StartOfTurn: ; 35e6 (0:35e6)
 	set SUBSTATUS3_THIS_TURN_DOUBLE_DAMAGE, [hl]
 	ret
 
-; clears the substatus 2, Headache, and updates the double damage condition of the player ending his turn
+; clears the SUBSTATUS2, Headache, and updates the double damage condition of the player ending his turn
 UpdateSubstatusConditions_EndOfTurn: ; 35fa (0:35fa)
 	ld a, DUELVARS_ARENA_CARD_SUBSTATUS3
 	call GetTurnDuelistVariable
@@ -10068,14 +10264,14 @@ IsRainDanceActive: ; 3615 (0:3615)
 ; 0x3622
 
 ; return carry if card at [hTempCardIndex_ff98] is a water energy card AND
-; if card at [hTempPlayAreaLocationOffset_ff9d] is a water Pokemon card.
+; if card at [hTempPlayAreaLocation_ff9d] is a water Pokemon card.
 CheckRainDanceScenario: ; 3622 (0:3622)
 	ldh a, [hTempCardIndex_ff98]
 	call GetCardIDFromDeckIndex
 	call GetCardType
 	cp TYPE_ENERGY_WATER
 	jr nz, .done
-	ldh a, [hTempPlayAreaLocationOffset_ff9d]
+	ldh a, [hTempPlayAreaLocation_ff9d]
 	call GetPlayAreaCardColor
 	cp TYPE_PKMN_WATER
 	jr nz, .done
@@ -10086,8 +10282,8 @@ CheckRainDanceScenario: ; 3622 (0:3622)
 	ret
 ; 0x363b
 
-; if the target card's HP is 0 and the attacking card's HP is not,
-; the attacking card faints if it was affected by destiny bond
+; if the defending (non-turn) card's HP is 0 and the attacking (turn) card's HP
+;  is not, the attacking card faints if it was affected by destiny bond
 HandleDestinyBondSubstatus: ; 363b (0:363b)
 	ld a, DUELVARS_ARENA_CARD_SUBSTATUS1
 	call GetNonTurnDuelistVariable
@@ -10108,10 +10304,10 @@ HandleDestinyBondSubstatus: ; 363b (0:363b)
 	call GetTurnDuelistVariable
 	or a
 	ret z
-	ld [hl], $0
+	ld [hl], 0
 	push hl
-	call $4f9d
-	call $503a
+	call DrawDuelMainScene
+	call DrawDuelHUDs
 	pop hl
 	ld l, DUELVARS_ARENA_CARD
 	ld a, [hl]
@@ -10126,8 +10322,8 @@ HandleDestinyBondSubstatus: ; 363b (0:363b)
 	ret
 ; 0x367b
 
-; when Machamp is damaged, if its Strikes Back is active,
-; the attacking Pokemon takes 10 damage.
+; when MACHAMP is damaged, if its Strikes Back is active, the
+; attacking Pokemon (turn holder's arena Pokemon) takes 10 damage.
 ; used to bounce back a move of the RESIDUAL category
 HandleStrikesBack_AgainstResidualMove: ; 367b (0:367b)
 	ld a, [wTempNonTurnDuelistCardID]
@@ -10138,7 +10334,7 @@ HandleStrikesBack_AgainstResidualMove: ; 367b (0:367b)
 	ld a, [wLoadedMoveCategory]
 	and RESIDUAL
 	ret nz
-	ld a, [wTempDamage_ccbf]
+	ld a, [wDealtDamage]
 	or a
 	ret z
 	call SwapTurn
@@ -10177,12 +10373,12 @@ ApplyStrikesBack_AgainstResidualMove: ; 36a2 (0:36a2)
 	call WaitForWideTextBoxInput
 	xor a
 	call PrintPlayAreaCardKnockedOutIfNoHP
-	call $503a
+	call DrawDuelHUDs
 	scf
 	ret
 ; 0x36d9
 
-; if the id of the card provided in register a as a deck index is Muk,
+; if the id of the card provided in register a as a deck index is MUK,
 ; clear the changed type of all arena and bench Pokemon
 ClearChangedTypesIfMuk: ; 36d9 (0:36d9)
 	call GetCardIDFromDeckIndex
@@ -10297,8 +10493,8 @@ GetCardResistance:
 	ret
 ; 0x375d
 
-; this function checks if charizard's energy burn is active, and if so
-; turns all energies except double colorless energies into fire energies
+; this function checks if turn holder's CHARIZARD energy burn is active, and if so, turns
+; all energies at wAttachedEnergies except double colorless energies into fire energies
 HandleEnergyBurn: ; 375d (0:375d)
 	ld a, DUELVARS_ARENA_CARD
 	call GetTurnDuelistVariable
@@ -10365,7 +10561,7 @@ Func_37a5: ; 37a5 (0:37a5)
 	srl h
 	ld a, BANK(CardGraphics)
 	add h
-	call BankswitchHome
+	call BankswitchROM
 	pop hl
 	add hl, hl
 	add hl, hl
@@ -10374,7 +10570,7 @@ Func_37a5: ; 37a5 (0:37a5)
 	set 6, h ; $4000 ≤ hl ≤ $7fff
 	call Func_37c5
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 ; 0x37c5
 
@@ -10445,19 +10641,19 @@ Func_380e: ; 380e (0:380e)
 	ldh a, [hBankROM]
 	push af
 	ld a, BANK(SetScreenScrollWram)
-	call BankswitchHome
+	call BankswitchROM
 	call SetScreenScrollWram
 	call Func_c554
 	ld a, BANK(Func_1c610)
-	call BankswitchHome
+	call BankswitchROM
 	call Func_1c610
 	call Func_3cb4
 	ld a, BANK(Func_804d8)
-	call BankswitchHome
+	call BankswitchROM
 	call Func_804d8
 	call UpdateRNGSources
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 
 ; enable the play time counter and execute the game event at [wGameEvent].
@@ -10474,7 +10670,7 @@ ExecuteGameEvent: ; 383d (0:383d)
 	jr .loop
 .restart
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 
 ; execute a game event at [wGameEvent] from GameEventPointerTable
@@ -10518,7 +10714,7 @@ GameEvent_GiftCenter: ; 3876 (0:3876)
 	ld [wd10e], a
 	call ResumeSong
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	scf
 	ret
 
@@ -10529,7 +10725,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
@@ -10588,7 +10784,7 @@ Func_3917: ; 3917 (0:3917)
 	ld a, $22
 	farcall CheckIfEventFlagSet
 	call EnableSRAM
-	ld [sa00a], a
+	ld [s0a00a], a
 	call DisableSRAM
 	ret
 
@@ -10651,10 +10847,10 @@ Func_395a: ; 395a (0:395a)
 	ldh a, [hBankROM]
 	push af
 	ld a, [wd4c6]
-	call BankswitchHome
+	call BankswitchROM
 	call CopyGfxData
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 
 Unknown_396b: ; 396b (0:396b)
@@ -10687,10 +10883,10 @@ Func_3997: ; 3997 (0:3997)
 	ldh a, [hBankROM]
 	push af
 	ld a, BANK(Func_1c056)
-	call BankswitchHome
+	call BankswitchROM
 	call Func_1c056
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 
 Func_39a7: ; 39a7 (0:39a7)
@@ -10698,7 +10894,7 @@ Func_39a7: ; 39a7 (0:39a7)
 	call Func_39ad
 	ret
 
-; return hl = wd34a + a * $c + l, a < $8
+; return hl = wd34a + a * $c + l, with a < $8
 Func_39ad: ; 39ad (0:39ad)
 	push bc
 	cp $8
@@ -10755,11 +10951,11 @@ Func_39ea: ; 39ea (0:39ea)
 	ldh a, [hBankROM]
 	push af
 	ld a, $03
-	call BankswitchHome
+	call BankswitchROM
 	ld a, [bc]
 	ld c, a
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ld a, c
 	pop bc
 	ret
@@ -10847,10 +11043,10 @@ Func_3a5e: ; 3a5e (0:3a5e)
 	call Func_3abd
 	jr nc, .asm_3ab3
 	ld a, BANK(Func_c653)
-	call BankswitchHome
+	call BankswitchROM
 	call Func_c653
 	ld a, $4
-	call BankswitchHome
+	call BankswitchROM
 	ld a, [wd334]
 	ld d, a
 .asm_3a79
@@ -10882,7 +11078,7 @@ Func_3a5e: ; 3a5e (0:3a5e)
 	pop hl
 	pop bc
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	scf
 	ret
 .asm_3aab
@@ -10893,7 +11089,7 @@ Func_3a5e: ; 3a5e (0:3a5e)
 	jr .asm_3a79
 .asm_3ab3
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ld l, $6
 	call $49c2
 	ret
@@ -10916,12 +11112,12 @@ Func_3abd: ; 3abd (0:3abd)
 	ldh a, [hBankROM]
 	push af
 	ld a, BANK(MapScripts)
-	call BankswitchHome
+	call BankswitchROM
 	ld a, [hli]
 	ld h, [hl]
 	ld l, a
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ld a, l
 	or h
 	jr nz, .asm_3ae5
@@ -10956,12 +11152,12 @@ RunOverworldScript: ; 3aed (0:3aed)
 	ldh a, [hBankROM]
 	push af
 	ld a, BANK(OverworldScriptTable)
-	call BankswitchHome
+	call BankswitchROM
 	ld a, [hli]
 	ld h, [hl]
 	ld l, a
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	pop bc
 	jp hl
 ; 0x3b11
@@ -10970,39 +11166,39 @@ Func_3b11: ; 3b11 (0:3b11)
 	ldh a, [hBankROM]
 	push af
 	ld a, $04
-	call BankswitchHome
+	call BankswitchROM
 	call $66d1
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 ; 0x3b21
 
 Func_3b21: ; 3b21 (0:3b21)
 	ldh a, [hBankROM]
 	push af
-	ld a, $7
-	call BankswitchHome
+	ld a, $07
+	call BankswitchROM
 	call $48bc
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 
 Func_3b31: ; 3b31 (0:3b31)
 	ldh a, [hBankROM]
 	push af
-	ld a, $7
-	call BankswitchHome
-	call $4b18
+	ld a, BANK(Func_1cb18)
+	call BankswitchROM
+	call Func_1cb18
 	jr c, .asm_3b45
 	xor a
 	ld [wDoFrameFunction], a
-	ld [wcad4], a
+	ld [wDoFrameFunction + 1], a
 .asm_3b45
 	call ZeroObjectPositions
 	ld a, 1
 	ld [wVBlankOAMCopyToggle], a
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 
 Func_3b52: ; 3b52 (0:3b52)
@@ -11031,8 +11227,8 @@ Func_3b6a: ; 3b6a (0:3b6a)
 	push hl
 	push bc
 	push de
-	ld a, $7
-	call BankswitchHome
+	ld a, $07
+	call BankswitchROM
 	ld a, [wd422]
 	cp $61
 	jr nc, .asm_3b90
@@ -11053,7 +11249,7 @@ Func_3b6a: ; 3b6a (0:3b6a)
 	pop bc
 	pop hl
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 ; 0x3ba2
 
@@ -11061,11 +11257,11 @@ Func_3ba2: ; 3ba2 (0:3ba2)
 	ldh a, [hBankROM]
 	push af
 	ld a, $07
-	call BankswitchHome
+	call BankswitchROM
 	call $4ac5
 	call Func_3cb4
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 ; 0x3bb5
 
@@ -11075,11 +11271,11 @@ Func_3bb5: ; 3bb5 (0:3bb5)
 	ldh a, [hBankROM]
 	push af
 	ld a, [wd4be]
-	call BankswitchHome
+	call BankswitchROM
 	call Func_3cb4
 	call CallHL2
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ld a, $80
 	ld [wd4c0], a
 	ret
@@ -11105,10 +11301,10 @@ Func_3be4: ; 3be4 (0:3be4)
 	ldh a, [hBankROM]
 	push af
 	ld a, [wd4c6]
-	call BankswitchHome
+	call BankswitchROM
 	call Func_08de
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 ; 0x3bf5
 
@@ -11117,7 +11313,7 @@ Func_3bf5: ; 3bf5 (0:3bf5)
 	push af
 	push hl
 	ld a, [wd4c6]
-	call BankswitchHome
+	call BankswitchROM
 	ld a, [wd4c4]
 	ld l, a
 	ld a, [wd4c5]
@@ -11125,7 +11321,7 @@ Func_3bf5: ; 3bf5 (0:3bf5)
 	call CopyDataHLtoDE_SaveRegisters
 	pop hl
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 ; 0x3c10
 
@@ -11174,13 +11370,13 @@ Func_3c2d: ; 3c2d (0:3c2d)
 	push hl
 	ld hl, sp+$05
 	ld a, [hl]
-	call BankswitchHome
+	call BankswitchROM
 	pop hl
 	ld a, [hl]
 	ld hl, sp+$03
 	ld [hl], a
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	pop af
 	pop hl
 	ret
@@ -11198,7 +11394,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
@@ -11273,20 +11469,20 @@ Func_3ca4: ; 3ca4 (0:3ca4)
 	ldh a, [hBankROM]
 	push af
 	ld a, BANK(Func_1296e)
-	call BankswitchHome
+	call BankswitchROM
 	call Func_1296e
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 
 Func_3cb4: ; 3cb4 (0:3cb4)
 	ldh a, [hBankROM]
 	push af
 	ld a, BANK(Func_12a21)
-	call BankswitchHome
+	call BankswitchROM
 	call Func_12a21
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 ; 0x3cc4
 
@@ -11295,7 +11491,7 @@ Func_3cc4: ; 3cc4 (0:3cc4)
 	ldh a, [hBankROM]
 	push af
 	ld a, [wd5d6]
-	call BankswitchHome
+	call BankswitchROM
 	ld a, [wd5d1]
 	cp $f0
 	ld a, $00
@@ -11401,7 +11597,7 @@ Func_3cc4: ; 3cc4 (0:3cc4)
 	jr nz, .asm_3ced
 .done
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 ; 0x3d72
 
@@ -11422,7 +11618,7 @@ Func_3d72: ; 3d72 (0:3d72)
 	ld a, [wd4c5]
 	ld h, a
 	ld a, [wd4c6]
-	call BankswitchHome
+	call BankswitchROM
 	ld a, [hli]
 	push af
 	ld a, [wd4ca]
@@ -11441,7 +11637,7 @@ Func_3d72: ; 3d72 (0:3d72)
 	ld bc, $000b
 	add hl, bc
 	ld [hli], a
-	call BankswitchHome
+	call BankswitchROM
 	ld a, [de]
 	ld [hli], a
 	inc de
@@ -11449,7 +11645,7 @@ Func_3d72: ; 3d72 (0:3d72)
 	ld [hl], a
 	pop hl
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 
 Func_3db7: ; 3db7 (0:3db7)
@@ -11514,34 +11710,38 @@ Func_3df3: ; 3df3 (0:3df3)
 	push af
 	push hl
 	ld a, BANK(Func_12c7f)
-	call BankswitchHome
+	call BankswitchROM
 	ld hl, sp+$5
 	ld a, [hl]
 	call Func_12c7f
-	call SetFlushAllPalettes
+	call FlushAllPalettes
 	pop hl
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	pop af
 	ld a, [wd61b]
 	ret
 ; 0x3e10
 
+; draws player's portrait at b,c
 Func_3e10: ; 3e10 (0:3e10)
 	ld a, $1
 	ld [wd61e], a
 	ld a, $62
+;	fallthrough
+
 Func_3e17: ; 3e17 (0:3e17)
 	ld [wd131], a
 	ldh a, [hBankROM]
 	push af
 	ld a, $4
-	call BankswitchHome
+	call BankswitchROM
 	call $6fc6
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 
+; draws opponent's portrait given in a at b,c
 Func_3e2a: ; 3e2a (0:3e2a)
 	ld [wd61e], a
 	ld a, $63
@@ -11553,10 +11753,10 @@ Func_3e31: ; 3e31 (0:3e31)
 	push af
 	call Func_3cb4
 	ld a, $20
-	call BankswitchHome
+	call BankswitchROM
 	call $44d8
 	pop af
-	call BankswitchHome
+	call BankswitchROM
 	ret
 ; 0x3e44
 
@@ -11625,7 +11825,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 +11848,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 +11909,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/hram.asm b/src/hram.asm
index 13c4756..bfdf81a 100644
--- a/src/hram.asm
+++ b/src/hram.asm
@@ -12,19 +12,25 @@ hBankVRAM:: ; ff82
 hDMAFunction:: ; ff83
 	ds $a
 
+; D-pad repeat counter. see HandleDPadRepeat
 hDPadRepeat:: ; ff8d
 	ds $1
 
-hButtonsReleased:: ; ff8e
+; keys pressed in last frame but not in current frame
+hKeysReleased:: ; ff8e
 	ds $1
 
-hButtonsPressed2:: ; ff8f
+; used to quickly scroll through menus when a relevant D-pad key is held
+; see HandleDPadRepeat
+hDPadHeld:: ; ff8f
 	ds $1
 
-hButtonsHeld:: ; ff90
+; keys pressed in last frame and in current frame
+hKeysHeld:: ; ff90
 	ds $1
 
-hButtonsPressed:: ; ff91
+; keys pressed in current frame but not in last frame
+hKeysPressed:: ; ff91
 	ds $1
 
 hSCX:: ; ff92
@@ -60,9 +66,10 @@ hTempCardID_ff9b:: ; ff9b
 	ds $2
 
 ; a PLAY_AREA_* constant (0: arena card, 1-5: bench card)
-hTempPlayAreaLocationOffset_ff9d:: ; ff9d
+hTempPlayAreaLocation_ff9d:: ; ff9d
 	ds $1
 
+; index for AIActionTable
 hAIActionTableIndex:: ; ff9e
 	ds $1
 
@@ -70,19 +77,19 @@ hAIActionTableIndex:: ; ff9e
 hTempCardIndex_ff9f:: ; ff9f
 	ds $1
 
-; multipurpose temp storage
+; multipurpose temp storage (card's deck index, selected move index, status condition...)
 hTemp_ffa0:: ; ffa0
 	ds $1
 
 ; a PLAY_AREA_* constant (0: arena card, 1-5: bench card)
-hTempPlayAreaLocationOffset_ffa1:: ; ffa1
+hTempPlayAreaLocation_ffa1:: ; ffa1
 	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
 
-; hffa8 through hffb0 appear to be related to text processing
+; hffa8 through hffb0 belong to the text engine
 hffa8:: ; ffa8
 	ds $1
 
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/macros/wram.asm b/src/macros/wram.asm
index ad6075f..ca8a9d0 100644
--- a/src/macros/wram.asm
+++ b/src/macros/wram.asm
@@ -26,7 +26,7 @@ card_data_struct: MACRO
 ENDM
 
 move_data_struct: MACRO
-\1Energy::         ds NUM_TYPES / 2
+\1EnergyCost::     ds NUM_TYPES / 2
 \1Name::           ds 2
 \1Description::    ds 4
 \1Damage::         ds 1
diff --git a/src/sram.asm b/src/sram.asm
index e5bd99d..fa58d07 100644
--- a/src/sram.asm
+++ b/src/sram.asm
@@ -1,38 +1,82 @@
-SECTION "SRAM", SRAM
+SECTION "SRAM0", SRAM
 
-sa000:: ds $3 ; a000
+s0a000:: ; a000
+	ds $3
 
-sa003:: ds $1 ; a003
-sa004:: ds $1 ; a004
-sa005:: ds $1 ; a005
-sa006:: ds $1 ; a006
-sa007:: ds $1 ; a007
-sa008:: ds $1 ; a008
-sa009:: ds $1 ; a009
-sa00a:: ds $1 ; a00a
+s0a003:: ; a003
+	ds $1
+s0a004:: ; a004
+	ds $1
+s0a005:: ; a005
+	ds $1
+s0a006:: ; a006
+	ds $1
+s0a007:: ; a007
+	ds $1
+s0a008:: ; a008
+	ds $1
+s0a009:: ; a009
+	ds $1
+s0a00a:: ; a00a
+	ds $1
 
 	ds $5
 
-sPlayerName:: ds $10 ; a010
+sPlayerName:: ; a010
+	ds $10
 
 	ds $e0
 
 ; for each card, how many (0-127) the player owns
 ; CARD_NOT_OWNED ($80) indicates that the player has not yet seen the card
-sCardCollection:: ds $100 ; a100
+sCardCollection:: ; a100
+	ds $100
 
-sDeck1Name::  ds DECK_NAME_SIZE ; a200
-sDeck1Cards:: ds DECK_SIZE      ; a218
+sDeck1Name:: ; a200
+	ds DECK_NAME_SIZE
+sDeck1Cards:: ; a218
+	ds DECK_SIZE
 
-sDeck2Name::  ds DECK_NAME_SIZE ; a254
-sDeck2Cards:: ds DECK_SIZE      ; a26c
+sDeck2Name:: ; a254
+	ds DECK_NAME_SIZE
+sDeck2Cards:: ; a26c
+	ds DECK_SIZE
 
-sDeck3Name::  ds DECK_NAME_SIZE ; a2a8
-sDeck3Cards:: ds DECK_SIZE      ; a2c0
+sDeck3Name:: ; a2a8
+	ds DECK_NAME_SIZE
+sDeck3Cards:: ; a2c0
+	ds DECK_SIZE
 
-sDeck4Name::  ds DECK_NAME_SIZE ; a2fc
-sDeck4Cards:: ds DECK_SIZE      ; a314
+sDeck4Name:: ; a2fc
+	ds DECK_NAME_SIZE
+sDeck4Cards:: ; a314
+	ds DECK_SIZE
 
-sa350:: ds DECK_NAME_SIZE + DECK_SIZE ; a350
-sa3a4:: ds DECK_NAME_SIZE + DECK_SIZE ; a3a4
-sa3f8:: ds DECK_NAME_SIZE + DECK_SIZE ; a3f8
+s0a350:: ; a350
+	ds DECK_NAME_SIZE + DECK_SIZE
+s0a3a4:: ; a3a4
+	ds DECK_NAME_SIZE + DECK_SIZE
+s0a3f8:: ; a3f8
+	ds DECK_NAME_SIZE + DECK_SIZE
+
+	ds $12b4
+
+s0b700:: ; b700
+	ds $1
+
+SECTION "SRAM1", SRAM
+
+SECTION "SRAM2", SRAM
+
+	ds $1c00
+
+; saved data of the current duel, including a two-byte checksum
+; see SaveDuelDataToDE
+sCurrentDuel:: ; bc00
+	ds $1
+sCurrentDuelChecksum:: ; bc01
+	ds $2
+sCurrentDuelData:: ; bc04
+	ds $33b
+
+SECTION "SRAM3", SRAM
diff --git a/src/text/text1.asm b/src/text/text1.asm
index 0274dc2..19c999b 100644
--- a/src/text/text1.asm
+++ b/src/text/text1.asm
@@ -62,19 +62,19 @@ LbsText: ; 36385 (d:6385)
 	text "lbs."
 	done
 
-Text0011: ; 3638b (d:638b)
+PromostarRarityText: ; 3638b (d:638b)
 	textfw0 " "
 	done
 
-Text0012: ; 3638d (d:638d)
+CircleRarityText: ; 3638d (d:638d)
 	textfw3 "●"
 	done
 
-Text0013: ; 36390 (d:6390)
+DiamondRarityText: ; 36390 (d:6390)
 	textfw3 "◆"
 	done
 
-Text0014: ; 36393 (d:6393)
+StarRarityText: ; 36393 (d:6393)
 	textfw3 "★"
 	done
 
@@ -171,7 +171,7 @@ IsCuredOfParalysisText: ; 36539 (d:6539)
 	line "cured of Paralysis."
 	done
 
-Text002b: ; 36553 (d:6553)
+BetweenTurnsText: ; 36553 (d:6553)
 	text "Between Turns."
 	done
 
@@ -331,7 +331,7 @@ Text004d: ; 3685a (d:685a)
 	text "Bench"
 	done
 
-Text004e: ; 36861 (d:6861)
+KnockOutText: ; 36861 (d:6861)
 	text "Knock Out"
 	done
 
@@ -376,12 +376,12 @@ TransmitingDataText: ; 369a2 (d:69a2)
 	text "Transmitting data..."
 	done
 
-Text0058: ; 369b8 (d:69b8)
+WaitingHandExamineText: ; 369b8 (d:69b8)
 	text "Waiting..."
 	line "    Hand        Examine"
 	done
 
-Text0059: ; 369dc (d:69dc)
+SelectingBenchPokemonHandExamineBackText: ; 369dc (d:69dc)
 	text "Selecting Bench Pokémon..."
 	line "    Hand        Examine     Back"
 	done
@@ -406,16 +406,16 @@ FinishedTurnWithoutAttackingText: ; 36a74 (d:6a74)
 	line "without Attacking."
 	done
 
-Text005e: ; 36a9a (d:6a9a)
+DuelistsTurnText: ; 36a9a (d:6a9a)
 	text "<RAMNAME>'s Turn."
 	done
 
-Text005f: ; 36aa5 (d:6aa5)
+AttachedEnergyToPokemonText: ; 36aa5 (d:6aa5)
 	text "Attached <RAMTEXT>"
 	line "to <RAMTEXT>."
 	done
 
-Text0060: ; 36ab7 (d:6ab7)
+PokemonEvolvedIntoPokemonText: ; 36ab7 (d:6ab7)
 	text "<RAMTEXT> evolved"
 	line "into <RAMTEXT>."
 	done
@@ -462,7 +462,7 @@ ChooseBasicPkmnToPlaceInArenaText: ; 36bc2 (d:6bc2)
 	line "to place in the Arena."
 	done
 
-Text006a: ; 36bf1 (d:6bf1)
+ThereAreNoBasicPokemonInHand: ; 36bf1 (d:6bf1)
 	text "There are no Basic Pokémon"
 	line "in <RAMNAME>'s hand."
 	done
@@ -472,7 +472,7 @@ NeitherPlayerHasBasicPkmnText: ; 36c1a (d:6c1a)
 	line "Pokémon in his or her hand."
 	done
 
-Text006c: ; 36c54 (d:6c54)
+ReturnCardsToDeckAndDrawAgainText: ; 36c54 (d:6c54)
 	text "Return the cards to the Deck"
 	line "and draw again."
 	done
@@ -482,12 +482,12 @@ ChooseUpTo5BasicPkmnToPlaceOnBenchText: ; 36c82 (d:6c82)
 	line "to place on the Bench."
 	done
 
-Text006e: ; 36cbf (d:6cbf)
+PleaseChooseAnActivePokemonText: ; 36cbf (d:6cbf)
 	text "Please choose an"
 	line "Active Pokémon."
 	done
 
-Text006f: ; 36ce1 (d:6ce1)
+ChooseYourBenchPokemonText: ; 36ce1 (d:6ce1)
 	text "Choose your"
 	line "Bench Pokémon."
 	done
@@ -496,7 +496,7 @@ YouDrewText: ; 36cfd (d:6cfd)
 	text "You drew <RAMTEXT>."
 	done
 
-Text0071: ; 36d0a (d:6d0a)
+YouCannotSelectThisCardText: ; 36d0a (d:6d0a)
 	text "You cannot select this card."
 	done
 
@@ -509,13 +509,13 @@ PleasePlacePrizesText: ; 36d3f (d:6d3f)
 	line "<RAMNUM> Prizes."
 	done
 
-IfHeadPlayerPlaysFirstText: ; 36d57 (d:6d57)
+IfHeadsDuelistPlaysFirstText: ; 36d57 (d:6d57)
 	text "If heads,"
 	line ""
 	text "<RAMTEXT> plays first."
 	done
 
-CoinTossToDetermineWhoFirstText: ; 36d72 (d:6d72)
+CoinTossToDecideWhoPlaysFirstText: ; 36d72 (d:6d72)
 	text "A coin will be tossed"
 	line "to decide who plays first."
 	done
@@ -543,21 +543,21 @@ StartSuddenDeathMatchText: ; 36e05 (d:6e05)
 	line "Match for 1 Prize!"
 	done
 
-Text007b: ; 36e2e (d:6e2e)
+PrizesLeftActivePokemonCardsInDeckText: ; 36e2e (d:6e2e)
 	text "Prizes Left"
 	line "Active Pokémon"
 	line "Cards in Deck"
 	done
 
-Text007c: ; 36e58 (d:6e58)
+NoneText: ; 36e58 (d:6e58)
 	text "None"
 	done
 
-Text007d: ; 36e5e (d:6e5e)
+YesText: ; 36e5e (d:6e5e)
 	text "Yes"
 	done
 
-Text007e: ; 36e63 (d:6e63)
+CardsText: ; 36e63 (d:6e63)
 	text "Cards"
 	done
 
@@ -586,17 +586,17 @@ UnableToUsePkmnPowerDueToToxicGasText: ; 36ed5 (d:6ed5)
 	line "the effect of Toxic Gas."
 	done
 
-Text0084: ; 36f11 (d:6f11)
+PlayCheck1Text: ; 36f11 (d:6f11)
 	text "  Play"
 	line "  Check"
 	done
 
-Text0085: ; 36f21 (d:6f21)
+PlayCheck2Text: ; 36f21 (d:6f21)
 	text "  Play"
 	line "  Check"
 	done
 
-Text0086: ; 36f31 (d:6f31)
+SelectCheckText: ; 36f31 (d:6f31)
 	text "  Select"
 	line "  Check"
 	done
diff --git a/src/text/text2.asm b/src/text/text2.asm
index cd3aeed..934a2ec 100644
--- a/src/text/text2.asm
+++ b/src/text/text2.asm
@@ -18,7 +18,7 @@ ConfusionCheckRetreatText: ; 380ac (e:40ac)
 	line "If Tails, unable to Retreat."
 	done
 
-Text00f9: ; 380db (e:40db)
+PokemonsSleepCheckText: ; 380db (e:40db)
 	text "<RAMTEXT>'s Sleep check."
 	done
 
@@ -173,11 +173,11 @@ Text0117: ; 386f2 (e:46f2)
 	text "Draw 1 card from the Deck."
 	done
 
-DrawCardsFromTheDeck: ; 3870e (e:470e)
+DrawCardsFromTheDeckText: ; 3870e (e:470e)
 	text "Draw <RAMNUM> card(s) from the Deck."
 	done
 
-NoCardsInDeckCannotDraw: ; 3872d (e:472d)
+CannotDrawCardBecauseNoCardsInDeckText: ; 3872d (e:472d)
 	text "Cannot draw a card because"
 	line "there are no cards in the Deck."
 	done
@@ -478,7 +478,7 @@ WasUnsuccessfulText: ; 393e6 (e:53e6)
 	line "<RAMTEXT> was unsuccessful."
 	done
 
-Text014b: ; 393ff (e:53ff)
+ThereWasNoEffectFromTxRam2Text: ; 393ff (e:53ff)
 	text "There was no effect"
 	line "from <RAMTEXT>."
 	done
@@ -725,32 +725,32 @@ Text017d: ; 39b97 (e:5b97)
 	text "There was no effect!"
 	done
 
-Text017e: ; 39bad (e:5bad)
+ThereWasNoEffectFromToxicText: ; 39bad (e:5bad)
 	text "There was no effect"
 	line "from Toxic"
 	done
 
-Text017f: ; 39bcd (e:5bcd)
+ThereWasNoEffectFromPoisonText: ; 39bcd (e:5bcd)
 	text "There was no effect"
 	line "from Poison."
 	done
 
-Text0180: ; 39bef (e:5bef)
+ThereWasNoEffectFromSleepText: ; 39bef (e:5bef)
 	text "There was no effect"
 	line "from Sleep."
 	done
 
-Text0181: ; 39c10 (e:5c10)
+ThereWasNoEffectFromParalysisText: ; 39c10 (e:5c10)
 	text "There was no effect"
 	line "from Paralysis."
 	done
 
-Text0182: ; 39c35 (e:5c35)
+ThereWasNoEffectFromConfusionText: ; 39c35 (e:5c35)
 	text "There was no effect"
 	line "from Confusion."
 	done
 
-Text0183: ; 39c5a (e:5c5a)
+ThereWasNoEffectFromPoisonConfusionText: ; 39c5a (e:5c5a)
 	text "There was no effet"
 	line "from Poison, Confusion."
 	done
@@ -1479,7 +1479,7 @@ GrassAndPsychicDeckName: ; 3b75d (e:775d)
 	text "Grass & Psychic"
 	done
 
-Text0212: ; 3b76e (e:776e)
+RetreatCostText: ; 3b76e (e:776e)
 	text "Retreat Cost"
 	done
 
@@ -1491,11 +1491,11 @@ Text0214: ; 3b799 (e:7799)
 	textfw3 "S", "W", "I", "T", "C", "H", " ", "T", "O", " ", "L", "O", "W", "E", "R"
 	done
 
-Text0215: ; 3b7b6 (e:77b6)
+FeetText: ; 3b7b6 (e:77b6)
 	textfw3 "'"
 	done
 
-Text0216: ; 3b7b9 (e:77b9)
+InchesText: ; 3b7b9 (e:77b9)
 	textfw3 "”"
 	done
 
diff --git a/src/text/text_offsets.asm b/src/text/text_offsets.asm
index 7838e80..d09504f 100644
--- a/src/text/text_offsets.asm
+++ b/src/text/text_offsets.asm
@@ -18,10 +18,10 @@ TextOffsets:: ; 34000 (d:4000)
 	textpointer PokemonText                              ; 0x000e
 	textpointer Text000f                                 ; 0x000f
 	textpointer LbsText                                  ; 0x0010
-	textpointer Text0011                                 ; 0x0011
-	textpointer Text0012                                 ; 0x0012
-	textpointer Text0013                                 ; 0x0013
-	textpointer Text0014                                 ; 0x0014
+	textpointer PromostarRarityText                                 ; 0x0011
+	textpointer CircleRarityText                                 ; 0x0012
+	textpointer DiamondRarityText                                 ; 0x0013
+	textpointer StarRarityText                                 ; 0x0014
 	textpointer Text0015                                 ; 0x0015
 	textpointer Text0016                                 ; 0x0016
 	textpointer Text0017                                 ; 0x0017
@@ -44,7 +44,7 @@ TextOffsets:: ; 34000 (d:4000)
 	textpointer IsStillAsleepText                        ; 0x0028
 	textpointer IsCuredOfSleepText                       ; 0x0029
 	textpointer IsCuredOfParalysisText                   ; 0x002a
-	textpointer Text002b                                 ; 0x002b
+	textpointer BetweenTurnsText                         ; 0x002b
 	textpointer Text002c                                 ; 0x002c
 	textpointer Text002d                                 ; 0x002d
 	textpointer Text002e                                 ; 0x002e
@@ -79,9 +79,9 @@ TextOffsets:: ; 34000 (d:4000)
 	textpointer Text004b                                 ; 0x004b
 	textpointer Text004c                                 ; 0x004c
 	textpointer Text004d                                 ; 0x004d
-	textpointer Text004e                                 ; 0x004e
+	textpointer KnockOutText                             ; 0x004e
 	textpointer DamageToSelfDueToConfusionText           ; 0x004f
-	textpointer ChooseEnergyCardToDiscardText                                 ; 0x0050
+	textpointer ChooseEnergyCardToDiscardText            ; 0x0050
 	textpointer Text0051                                 ; 0x0051
 	textpointer Text0052                                 ; 0x0052
 	textpointer YouPlayFirstText                         ; 0x0053
@@ -89,15 +89,15 @@ TextOffsets:: ; 34000 (d:4000)
 	textpointer TransmissionErrorText                    ; 0x0055
 	textpointer ChooseTheCardYouWishToExamineText        ; 0x0056
 	textpointer TransmitingDataText                      ; 0x0057
-	textpointer Text0058                                 ; 0x0058
-	textpointer Text0059                                 ; 0x0059
+	textpointer WaitingHandExamineText                                 ; 0x0058
+	textpointer SelectingBenchPokemonHandExamineBackText                                 ; 0x0059
 	textpointer RetreatedToTheBenchText                  ; 0x005a
 	textpointer RetreatWasUnsuccessfulText               ; 0x005b
 	textpointer WillUseThePokemonPowerText               ; 0x005c
 	textpointer FinishedTurnWithoutAttackingText         ; 0x005d
-	textpointer Text005e                                 ; 0x005e
-	textpointer Text005f                                 ; 0x005f
-	textpointer Text0060                                 ; 0x0060
+	textpointer DuelistsTurnText                         ; 0x005e
+	textpointer AttachedEnergyToPokemonText                                 ; 0x005f
+	textpointer PokemonEvolvedIntoPokemonText                                 ; 0x0060
 	textpointer PlacedOnTheBenchText                     ; 0x0061
 	textpointer PlacedInTheArenaText                     ; 0x0062
 	textpointer ShufflesTheDeckText                      ; 0x0063
@@ -107,35 +107,35 @@ TextOffsets:: ; 34000 (d:4000)
 	textpointer Text0067                                 ; 0x0067
 	textpointer DeckHasXCardsText                        ; 0x0068
 	textpointer ChooseBasicPkmnToPlaceInArenaText        ; 0x0069
-	textpointer Text006a                                 ; 0x006a
+	textpointer ThereAreNoBasicPokemonInHand                                 ; 0x006a
 	textpointer NeitherPlayerHasBasicPkmnText            ; 0x006b
-	textpointer Text006c                                 ; 0x006c
+	textpointer ReturnCardsToDeckAndDrawAgainText                                 ; 0x006c
 	textpointer ChooseUpTo5BasicPkmnToPlaceOnBenchText   ; 0x006d
-	textpointer Text006e                                 ; 0x006e
-	textpointer Text006f                                 ; 0x006f
+	textpointer PleaseChooseAnActivePokemonText                                 ; 0x006e
+	textpointer ChooseYourBenchPokemonText                                 ; 0x006f
 	textpointer YouDrewText                              ; 0x0070
-	textpointer Text0071                                 ; 0x0071
+	textpointer YouCannotSelectThisCardText                                 ; 0x0071
 	textpointer PlacingThePrizesText                     ; 0x0072
 	textpointer PleasePlacePrizesText                    ; 0x0073
-	textpointer IfHeadPlayerPlaysFirstText               ; 0x0074
-	textpointer CoinTossToDetermineWhoFirstText          ; 0x0075
+	textpointer IfHeadsDuelistPlaysFirstText               ; 0x0074
+	textpointer CoinTossToDecideWhoPlaysFirstText          ; 0x0075
 	textpointer DecisionText                             ; 0x0076
 	textpointer DuelWasADrawText                         ; 0x0077
 	textpointer WonDuelText                              ; 0x0078
 	textpointer LostDuelText                             ; 0x0079
 	textpointer StartSuddenDeathMatchText                ; 0x007a
-	textpointer Text007b                                 ; 0x007b
-	textpointer Text007c                                 ; 0x007c
-	textpointer Text007d                                 ; 0x007d
-	textpointer Text007e                                 ; 0x007e
+	textpointer PrizesLeftActivePokemonCardsInDeckText                                 ; 0x007b
+	textpointer NoneText                                 ; 0x007c
+	textpointer YesText                                 ; 0x007d
+	textpointer CardsText                                 ; 0x007e
 	textpointer Text007f                                 ; 0x007f
 	textpointer Text0080                                 ; 0x0080
 	textpointer WasKnockedOutText                        ; 0x0081
 	textpointer HavePokemonPowerText                     ; 0x0082
 	textpointer UnableToUsePkmnPowerDueToToxicGasText    ; 0x0083
-	textpointer Text0084                                 ; 0x0084
-	textpointer Text0085                                 ; 0x0085
-	textpointer Text0086                                 ; 0x0086
+	textpointer PlayCheck1Text                                 ; 0x0084
+	textpointer PlayCheck2Text                                 ; 0x0085
+	textpointer SelectCheckText                                 ; 0x0086
 	textpointer Text0087                                 ; 0x0087
 	textpointer DuelistIsThinkingText                    ; 0x0088
 	textpointer Text0089                                 ; 0x0089
@@ -192,7 +192,7 @@ TextOffsets:: ; 34000 (d:4000)
 	textpointer Text00bc                                 ; 0x00bc
 	textpointer Text00bd                                 ; 0x00bd
 	textpointer Text00be                                 ; 0x00be
-	textpointer EnergyCardsRequiredToRetreatText                                 ; 0x00bf
+	textpointer EnergyCardsRequiredToRetreatText         ; 0x00bf
 	textpointer NotEnoughEnergyCardsText                 ; 0x00c0
 	textpointer Text00c1                                 ; 0x00c1
 	textpointer Text00c2                                 ; 0x00c2
@@ -250,7 +250,7 @@ TextOffsets:: ; 34000 (d:4000)
 	textpointer TransparencyCheckText                    ; 0x00f6
 	textpointer ConfusionCheckDamageText                 ; 0x00f7
 	textpointer ConfusionCheckRetreatText                ; 0x00f8
-	textpointer Text00f9                                 ; 0x00f9
+	textpointer PokemonsSleepCheckText                   ; 0x00f9
 	textpointer Text00fa                                 ; 0x00fa
 	textpointer Text00fb                                 ; 0x00fb
 	textpointer Text00fc                                 ; 0x00fc
@@ -281,8 +281,8 @@ TextOffsets:: ; 34000 (d:4000)
 	textpointer Text0115                                 ; 0x0115
 	textpointer Text0116                                 ; 0x0116
 	textpointer Text0117                                 ; 0x0117
-	textpointer DrawCardsFromTheDeck                     ; 0x0118
-	textpointer NoCardsInDeckCannotDraw                  ; 0x0119
+	textpointer DrawCardsFromTheDeckText                     ; 0x0118
+	textpointer CannotDrawCardBecauseNoCardsInDeckText                  ; 0x0119
 	textpointer Text011a                                 ; 0x011a
 	textpointer Text011b                                 ; 0x011b
 	textpointer Text011c                                 ; 0x011c
@@ -332,7 +332,7 @@ TextOffsets:: ; 34000 (d:4000)
 	textpointer Text0148                                 ; 0x0148
 	textpointer Text0149                                 ; 0x0149
 	textpointer WasUnsuccessfulText                      ; 0x014a
-	textpointer Text014b                                 ; 0x014b
+	textpointer ThereWasNoEffectFromTxRam2Text                                 ; 0x014b
 	textpointer Text014c                                 ; 0x014c
 	textpointer Text014d                                 ; 0x014d
 	textpointer Text014e                                 ; 0x014e
@@ -383,12 +383,12 @@ TextOffsets:: ; 34000 (d:4000)
 	textpointer Text017b                                 ; 0x017b
 	textpointer Text017c                                 ; 0x017c
 	textpointer Text017d                                 ; 0x017d
-	textpointer Text017e                                 ; 0x017e
-	textpointer Text017f                                 ; 0x017f
-	textpointer Text0180                                 ; 0x0180
-	textpointer Text0181                                 ; 0x0181
-	textpointer Text0182                                 ; 0x0182
-	textpointer Text0183                                 ; 0x0183
+	textpointer ThereWasNoEffectFromToxicText                                 ; 0x017e
+	textpointer ThereWasNoEffectFromPoisonText                                 ; 0x017f
+	textpointer ThereWasNoEffectFromSleepText                                 ; 0x0180
+	textpointer ThereWasNoEffectFromParalysisText                                 ; 0x0181
+	textpointer ThereWasNoEffectFromConfusionText                                 ; 0x0182
+	textpointer ThereWasNoEffectFromPoisonConfusionText                                 ; 0x0183
 	textpointer Text0184                                 ; 0x0184
 	textpointer Text0185                                 ; 0x0185
 	textpointer Text0186                                 ; 0x0186
@@ -531,11 +531,11 @@ TextOffsets:: ; 34000 (d:4000)
 	textpointer LightningAndFireDeckName                 ; 0x020f
 	textpointer WaterAndFightingDeckName                 ; 0x0210
 	textpointer GrassAndPsychicDeckName                  ; 0x0211
-	textpointer Text0212                                 ; 0x0212
+	textpointer RetreatCostText                                 ; 0x0212
 	textpointer Text0213                                 ; 0x0213
 	textpointer Text0214                                 ; 0x0214
-	textpointer Text0215                                 ; 0x0215
-	textpointer Text0216                                 ; 0x0216
+	textpointer FeetText                                 ; 0x0215
+	textpointer InchesText                                 ; 0x0216
 	textpointer YourDiscardPileText                      ; 0x0217
 	textpointer OpponentsDiscardPileText                 ; 0x0218
 	textpointer Text0219                                 ; 0x0219
diff --git a/src/wram.asm b/src/wram.asm
index e40d382..ca314b7 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,
@@ -43,9 +43,11 @@ wPlayerDuelVariables:: ; c200
 wPlayerCardLocations:: ; c200
 	ds DECK_SIZE
 
+; deck indexes of the up to 6 cards placed as prizes
+wPlayerPrizeCards:: ; c23c
 	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 +63,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
@@ -186,13 +188,24 @@ wPlayerDuelistType:: ; c2f1
 wPlayerArenaCardDisabledMoveIndex:: ; c2f2
 	ds $1
 
-	ds $d
+; damage taken the last time the opponent attacked (0 if no damage)
+wPlayerArenaCardLastTurnDamage:: ; c2f3
+	ds $1
+
+	ds $1
+
+; status condition received the last time the opponent attacked (0 if none)
+wPlayerArenaCardLastTurnStatus:: ; c2f5
+	ds $1
+
+	ds $a
 
 wOpponentDuelVariables:: ; c300
 
 wOpponentCardLocations:: ; c300
 	ds DECK_SIZE
 
+wOpponentPrizeCards:: ; c33c
 	ds $6
 
 wOpponentHand:: ; c342
@@ -319,10 +332,19 @@ wOpponentDuelistType:: ; c3f1
 wOpponentArenaCardDisabledMoveIndex:: ; c3f2
 	ds $1
 
-	ds $d
+wOpponentArenaCardLastTurnDamage:: ; c3f3
+	ds $1
+
+	ds $1
+
+wOpponentArenaCardLastTurnStatus:: ; c3f5
+	ds $1
+
+	ds $a
 
 UNION
 
+; temporary list of the cards drawn from a booster pack
 wBoosterCardsDrawn:: ; c400
 wBoosterTempNonEnergiesDrawn:: ; c400
 	ds $b
@@ -354,7 +376,7 @@ wDuelTempList:: ; c510
 wDefaultText:: ; c590
 	ds $70
 
-SECTION "WRAM Text Engine", WRAM0
+SECTION "WRAM0 Text Engine", WRAM0
 
 wc600:: ; c600
 	ds $100
@@ -368,12 +390,14 @@ wc800:: ; c800
 wc900:: ; c900
 	ds $100
 
-SECTION "WRAM Engine 1", WRAM0
+SECTION "WRAM0 1", WRAM0
 
 wOAM:: ; ca00
 	ds $a0
 
-wTextBuf:: ; caa0
+; 16-byte buffer to store text, usually a name or a number
+; used by TX_RAM1 but not exclusively
+wStringBuffer:: ; caa0
 	ds $10
 
 wcab0:: ; cab0
@@ -385,7 +409,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 +422,15 @@ 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,
+; or to delay a specific amount of frames
 wVBlankCounter:: ; cab8
 	ds $1
 
@@ -426,9 +453,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
 
@@ -436,7 +466,9 @@ wVBlankOAMCopyToggle:: ; cac0
 wTempByte:: ; cac1
 	ds $1
 
-wcac2:: ; cac2
+; which screen or interface is currently displayed in the screen during a duel
+; used to prevent loading graphics or drawing stuff more times than necessary
+wDuelDisplayedScreen:: ; cac2
 	ds $1
 
 ; used to increase the play time counter every four timer interrupts (60.24 Hz)
@@ -467,14 +499,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 +539,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 +554,7 @@ wObjectPalettesCGB:: ; cb30
 wListPointer:: ; cb72
 	ds $2
 
-SECTION "WRAM Serial Transfer", WRAM0
+SECTION "WRAM0 Serial Transfer", WRAM0
 
 wSerialOp:: ; cb74
 	ds $1
@@ -578,33 +610,54 @@ wSerialRecvIndex:: ; cba4
 wSerialRecvBuf:: ; cba5
 	ds $20
 
-	ds $1
+wSerialEnd:: ; cbc5
+
+SECTION "WRAM0 Duels 2", WRAM0
 
-SECTION "WRAM Duels 2", WRAM0
+	ds $1
 
 ; 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)
+; see CARDPAGE_* constants
 wCardPageNumber:: ; cbc7
 	ds $1
 
-wcbc8:: ; cbc8
+; how many selectable items are in a play area screen. used to set wNumMenuItems
+; in order to navigate through a play area screen. this becomes the number of bench
+; Pokemon cards if wExcludeArenaPokemon is 1, and that number plus 1 if it's 0.
+wNumPlayAreaItems:: ; cbc8
 	ds $1
 
-; 2-byte something
-wcbc9:: ; cbc9
-	ds $2
+; selects a PLAY_AREA_* slot in order to display information related to it. used by functions
+; such as PrintPlayAreaCardLocation, PrintPlayAreaCardInformation and PrintPlayAreaCardHeader
+wCurPlayAreaSlot:: ; cbc9
+
+; X position to display the attached energies, HP bar, and Pluspower/Defender icons
+; obviously different for player and opponent side. used by DrawDuelHUD.
+wHUDEnergyAndHPBarsX:: ; cbc9
+	ds $1
+
+; current Y coordinate where some play area information is being printed at. used by functions
+; such as PrintPlayAreaCardLocation, PrintPlayAreaCardInformation and PrintPlayAreaCardHeader
+wCurPlayAreaY:: ; cbca
+
+; Y position to display the attached energies, HP bar, and Pluspower/Defender icons
+; obviously different for player and opponent side. used by DrawDuelHUD.
+wHUDEnergyAndHPBarsY:: ; cbca
+	ds $1
 
 ; selected bench slot (1-5, that is, a PLAY_AREA_BENCH_* constant)
 wBenchSelectedPokemon:: ; cbcb
 	ds $1
 
+; used by CheckIfEnoughEnergiesToRetreat and DisplayRetreatScreen
 wEnergyCardsRequiredToRetreat:: ; cbcc
 	ds $1
 
@@ -615,7 +668,7 @@ wcbcd:: ; cbcd
 wAttachedEnergiesAccum:: ; cbce
 	ds $1
 
-; When you're in a duel submenu like the cards in your hand and you press A,
+; when you're in a duel submenu like the cards in your hand and you press A,
 ; the following two addresses keep track of which item was selected by the cursor
 wSelectedDuelSubMenuItem:: ; cbcf
 	ds $1
@@ -623,7 +676,9 @@ wSelectedDuelSubMenuItem:: ; cbcf
 wSelectedDuelSubMenuScrollOffset:: ; cbd0
 	ds $1
 
-wcbd1:: ; cbd1
+; CARDPAGETYPE_PLAY_AREA or CARDPAGETYPE_NOT_PLAY_AREA
+; some of the elements displayed in a card page change depending on which value
+wCardPageType:: ; cbd1
 	ds $1
 
 ; when processing or displaying the play area Pokemon cards of a duelist,
@@ -640,10 +695,14 @@ wcbd4:: ; cbd4
 wcbd5:: ; cbd5
 	ds $1
 
-wcbd6:: ; cbd6
+; in a card list, which keys (among START and A_BUTTON) do not open the item selection
+; menu when a card is selected, directly "submitting" the selected card instead.
+wNoItemSelectionMenuKeys:: ; cbd6
 	ds $1
 
-wcbd7:: ; cbd7
+; when viewing a card page, which keys (among B_BUTTON, D_UP, and D_DOWN) will exit the page,
+; either to go back to the previous menu orlist, or to load the card page of the card above/below it
+wCardPageExitKeys:: ; cbd7
 	ds $1
 
 wcbd8:: ; cbd8
@@ -660,7 +719,9 @@ wCardListInfoBoxText:: ; cbda
 wCardListHeaderText:: ; cbdc
 	ds $2
 
-wcbde:: ; cbde
+; when selecting an item of a list of cards which type of menu shows up.
+; PLAY_CHECK, SELECT_CHECK, or $00 for none.
+wCardListItemSelectionMenuType:: ; cbde
 	ds $1
 
 ; flag indicating whether a list of cards should be sorted by ID
@@ -673,8 +734,14 @@ wcbe0:: ; cbe0
 wAITurnEnded:: ; cbe1
 	ds $1
 
-wcbe2:: ; cbe2
-	ds $3
+wOppRNG1:: ; cbe2
+	ds $1
+
+wOppRNG2:: ; cbe3
+	ds $1
+
+wOppRNGCounter:: ; cbe4
+	ds $1
 
 ; sp is saved here when starting a duel, in order to save the return address
 ; however, it only seems to be read after a transmission error in a link duel
@@ -684,15 +751,19 @@ wDuelReturnAddress:: ; cbe5
 wcbe7:: ; cbe7
 	ds $1
 
-wcbe8:: ; cbe8
+wNumCardsTryingToDraw:: ; cbe8
 	ds $1
 
-wcbe9:: ; cbe9
+; number of cards being drawn in order to animate the number of cards in
+; the hand and in the deck in the draw card screen
+wNumCardsBeingDrawn:: ; cbe9
 	ds $1
 
 	ds $3
 
-wcbed:: ; cbed
+; temporarily stores 8 bytes for serial send/recv.
+; used by SerialSend8Bytes and SerialRecv8Bytes
+wTempSerialBuf:: ; cbed
 	ds $8
 
 	ds $2
@@ -700,7 +771,8 @@ wcbed:: ; cbed
 wcbf7:: ; cbf7
 	ds $2
 
-wcbf9:: ; cbf9
+; when non-0, AIMakeDecision doesn't wait 60 frames and print DuelistIsThinkingText
+wSkipDuelistIsThinkingDelay:: ; cbf9
 	ds $1
 
 wcbfa:: ; cbfa
@@ -709,7 +781,11 @@ wcbfa:: ; cbfa
 wcbfb:: ; cbfb
 	ds $1
 
-	ds $2
+wcbfc:: ; cbfc
+	ds $1
+
+wcbfd:: ; cbfd
+	ds $1
 
 ; during a practice duel, identifies an entry of PracticeDuelActionTable
 wPracticeDuelAction:: ; cbfe
@@ -721,12 +797,22 @@ wcbff:: ; cbff
 wcc00:: ; cc00
 	ds $1
 
-	ds $3
+	ds $2
 
-wcc04:: ; cc04
+; used to print a Pokemon card's length in feet and inches
+wPokemonLengthPrintOffset:: ; cc03
 	ds $1
 
-wcc05:: ; cc05
+; used when opening the card page of a move when attacking, serving as an index for MovePageDisplayPointerTable.
+; see MOVEPAGE_* constants
+wMovePageNumber:: ; cc04
+	ds $1
+
+; the value of hWhoseTurn gets loaded here at the beginning of each duelist's turn.
+; more reliable than hWhoseTurn, as hWhoseTurn may change temporarily in order to handle status
+; conditions or other events of the non-turn duelist. used mostly between turns (to check which
+; duelist's turn just finished), or to restore the value of hWhoseTurn at some point.
+wWhoseTurn:: ; cc05
 	ds $1
 
 ; number of turns taken by both players
@@ -745,7 +831,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,19 +851,25 @@ 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
 
+wcc0f:: ; cc0f
 	ds $1
 
-wcc10:: ; cc10
+; index (0-1) of the move or Pokemon Power being used by the player's arena card
+; set to $ff when the duel starts and at the end of the opponent's turn
+wPlayerAttackingMoveIndex:: ; cc10
 	ds $1
 
-wcc11:: ; cc11
+; deck index of the player's arena card that is attacking or using a Pokemon Power
+; set to $ff when the duel starts and at the end of the opponent's turn
+wPlayerAttackingCardIndex:: ; cc11
 	ds $1
 
-wcc12:: ; cc12
+; ID of the player's arena card that is attacking or using a Pokemon Power
+wPlayerAttackingCardID:: ; cc12
 	ds $1
 
 wIsPracticeDuel:: ; cc13
@@ -801,11 +893,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 +906,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
+; the damage field of an used move is loaded here
 wDamage:: ; ccb9
 	ds $2
 
@@ -836,9 +927,14 @@ wccbc:: ; ccbc
 
 	ds $2
 
-wTempDamage_ccbf:: ; ccbf
-	ds $2
+; damage dealt by an attack to a target
+wDealtDamage:: ; ccbf
+	ds $1
+
+wccc0:: ; ccc0
+	ds $1
 
+; WEAKNESS and RESISTANCE flags	for a damaging attack
 wDamageEffectiveness:: ; ccc1
 	ds $1
 
@@ -852,6 +948,8 @@ wTempTurnDuelistCardID:: ; ccc3
 wTempNonTurnDuelistCardID:: ; ccc4
 	ds $1
 
+; the status condition of the defending Pokemon is loaded here after an attack
+wccc5:: ; ccc5
 	ds $1
 
 ; may contain 0 or 1 depending on which move was selected
@@ -868,61 +966,77 @@ wGotHeadsFromConfusionCheck:: ; ccc9
 
 	ds $3
 
-wcccd:: ; cccd
+wEffectFunctionsFeedbackIndex:: ; cccd
 	ds $1
 
-; some array used in effect functions with wcccd as the index. unknown length
-wccce:: ; ccce
+; some array used in effect functions with wEffectFunctionsFeedbackIndex
+; as the index, used to return feedback. unknown length.
+wEffectFunctionsFeedback:: ; ccce
 	ds $18
 
 ; this is 1 (non-0) if dealing damage to self due to confusion
-wDamageToSelfMode:: ; cce6
+wIsDamageToSelf:: ; cce6
 	ds $1
 
-	ds $2
+wcce7:: ; cce7
+	ds $1
+
+	ds $1
 
 ; used in CopyDeckData
 wcce9:: ; cce9
 	ds $2
 
 ; a PLAY_AREA_* constant (0: arena card, 1-5: bench card)
-wTempPlayAreaLocationOffset_cceb:: ; cceb
+wTempPlayAreaLocation_cceb:: ; cceb
 	ds $1
 
 wccec:: ; ccec
 	ds $1
 
+; used by the effect functions to return the cause of an effect to fail
+; $01: was not affected by a status condition
+; $02: prints WasUnsuccessfulText
 wcced:: ; cced
 	ds $1
 
 wccee:: ; ccee
 	ds $1
 
+; when this is non-0, DUELVARS_ARENA_CARD_LAST_TURN_DAMAGE and the
+; next duelvar are always set to 0 after an attack
 wccef:: ; ccef
 	ds $1
 
 wccf0:: ; ccf0
 	ds $1
 
+; effect functions return a status condition constant here when it had no effect
+; on the target, in order to print one of the ThereWasNoEffectFrom* texts
 wccf1:: ; ccf1
 	ds $1
 
-wccf2:: ; ccf2
+; when non-0, allows the player to skip some delays during a duel by pressing B.
+; value read from s0a009. probably only used for debugging.
+wSkipDelayAllowed:: ; 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 CGB, attributes of the text box borders. (values 0-7 seem to be used, which only affect 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
 
@@ -1029,7 +1143,9 @@ wLeftmostItemCursorX:: ; cd98
 wRefreshMenuCursorSFX:: ; cd99
 	ds $1
 
-wcd9a:: ; cd9a
+; when printing a YES/NO menu, whether the cursor is
+; initialized to the YES ($01) or to the NO ($00) item
+wDefaultYesOrNo:: ; cd9a
 	ds $1
 
 ; used in _CopyCardNameAndLevel to keep track of the remaining space to copy the text
@@ -1040,7 +1156,7 @@ wcd9c:: ; cd9c
 	ds $1
 
 ; this stores the result from a coin toss (number of heads)
-wcd9d:: ; cd9d
+wCoinTossNumHeads:: ; cd9d
 	ds $1
 
 wcd9e:: ; cd9e
@@ -1098,6 +1214,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 +1272,7 @@ wWhichTxRam3:: ; ce4a
 wIsTextBoxLabeled:: ; ce4b
 	ds $1
 
+; text id of a text box's label
 wTextBoxLabel:: ; ce4c
 	ds $2
 
@@ -1240,7 +1358,22 @@ wTempPokemonID_ce7c:: ; ce7c
 wce7e:: ; ce7e
 	ds $1
 
-	ds $22
+wce7f:: ; ce7f
+	ds $2
+
+wce81:: ; ce81
+	ds $1
+
+wce82:: ; ce82
+	ds $1
+
+wce83:: ; ce83
+	ds $1
+
+wce84:: ; ce84
+	ds $1
+
+	ds $1c
 
 wcea1:: ; cea1
 	ds $1
@@ -1413,7 +1546,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 +1649,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
 
@@ -1786,7 +1920,16 @@ wd4ac:: ; d4ac
 wd4ad:: ; d4ad
 	ds $1
 
-	ds $10
+wd4ae:: ; d4ae
+	ds $1
+
+wd4af:: ; d4af
+	ds $1
+
+wd4b0:: ; d4b0
+	ds $1
+
+	ds $d
 
 wd4be:: ; d4be
 	ds $1
@@ -1965,7 +2108,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 +2116,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 +2141,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 +2174,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
author	xCrystal <rgr.crystal@gmail.com>	2018-08-13 14:54:31 +0200
committer	GitHub <noreply@github.com>	2018-08-13 14:54:31 +0200
commit	f5330d15daed2d77ff48360554a36162843fe199 (patch)
tree	f8142591ea01c720be6d6b979b2fadb84e3018f0 /src
parent	783f5fe610c69006742b4976ab4f183f39512d89 (diff)
parent	3581a4baed71f596eedb9c234b910f1d6a7736be (diff)