Merge pull request #101 from YamaArashi/master

Misc changes

constants/misc_constants.asm

@@ -8,7 +8,7 @@ NUM_BOXES    EQU 12
 
 HOF_MON       EQU $10
 HOF_TEAM      EQU PARTY_LENGTH * HOF_MON
-NUM_HOF_TEAMS EQU 50
+HOF_TEAM_CAPACITY EQU 50
 
 
 A_BUTTON EQU %00000001
@@ -109,6 +109,14 @@ NAME_PLAYER_SCREEN EQU 0
 NAME_RIVAL_SCREEN  EQU 1
 NAME_MON_SCREEN    EQU 2
 
+; mon data locations
+; Note that some values are not supported by all functions that use these values.
+PLAYER_PARTY_DATA EQU 0
+ENEMY_PARTY_DATA  EQU 1
+BOX_DATA          EQU 2
+DAYCARE_DATA      EQU 3
+BATTLE_MON_DATA   EQU 4
+
 ; serial
 
 ESTABLISH_CONNECTION_WITH_INTERNAL_CLOCK EQU $01

engine/HoF_room_pc.asm

@@ -6,10 +6,10 @@ HallOfFamePC: ; 7405c (1d:405c)
 	call DisableLCD
 	ld hl, vFont
 	ld bc, $800 / 2
-	call Func_74171
+	call ZeroMemory
 	ld hl, vChars2 + $600
 	ld bc, $200 / 2
-	call Func_74171
+	call ZeroMemory
 	ld hl, vChars2 + $7e0
 	ld bc, $10
 	ld a, $ff
@@ -30,12 +30,12 @@ HallOfFamePC: ; 7405c (1d:405c)
 	call DelayFrames
 	xor a
 	ld [wWhichTrade], a
-	ld [wTrainerEngageDistance], a
+	ld [wNumCreditsMonsDisplayed], a
 	jp Credits
 
-Func_740ba: ; 740ba (1d:40ba)
+FadeInCreditsText: ; 740ba (1d:40ba)
 	ld hl, HoFGBPalettes
-	ld b, $4
+	ld b, 4
 .asm_740bf
 	ld a, [hli]
 	ld [rBGP], a
@@ -52,7 +52,7 @@ DisplayCreditsMon: ; 740cb (1d:40cb)
 	call FillMiddleOfScreenWithWhite
 
 	; display the next monster from CreditsMons
-	ld hl,wTrainerEngageDistance
+	ld hl,wNumCreditsMonsDisplayed
 	ld c,[hl] ; how many monsters have we displayed so far?
 	inc [hl]
 	ld b,0
@@ -65,62 +65,69 @@ DisplayCreditsMon: ; 740cb (1d:40cb)
 	call GetMonHeader
 	call LoadFrontSpriteByMonIndex
 	ld hl,vBGMap0 + $c
-	call Func_74164
+	call CopyTileMapToVRAM
 	xor a
 	ld [H_AUTOBGTRANSFERENABLED],a
 	call LoadScreenTilesFromBuffer1
 	ld hl,vBGMap0
-	call Func_74164
+	call CopyTileMapToVRAM
 	ld a,$A7
-	ld [$FF4B],a
+	ld [rWX],a
 	ld hl,vBGMap1
-	call Func_74164
+	call CopyTileMapToVRAM
 	call FillMiddleOfScreenWithWhite
-	ld a,$FC
+	ld a,%11111100 ; make the mon a black silhouette 
 	ld [rBGP],a
+
+; scroll the mon left by one tile 7 times
 	ld bc,7
-.next
+.scrollLoop1
-	call Func_74140
+	call ScrollCreditsMonLeft
 	dec c
-	jr nz,.next
+	jr nz,.scrollLoop1
-	ld c,$14
+
-.next2
+; scroll the mon left by one tile 20 times
-	call Func_74140
+; This time, we have to move the window left too in order to hide the text that
-	ld a,[$FF4B]
+; is wrapping around to the right side of the screen. 
+	ld c,20
+.scrollLoop2
+	call ScrollCreditsMonLeft
+	ld a,[rWX]
 	sub 8
-	ld [$FF4B],a
+	ld [rWX],a
 	dec c
-	jr nz,.next2
+	jr nz,.scrollLoop2
+
 	xor a
 	ld [hWY],a
-	ld a,$C0
+	ld a,%11000000
 	ld [rBGP],a
 	ret
 
 INCLUDE "data/credit_mons.asm"
 
-Func_74140: ; 74140 (1d:4140)
+ScrollCreditsMonLeft: ; 74140 (1d:4140)
 	ld h, b
 	ld l, $20
-	call Func_74152
+	call ScrollCreditsMonLeft_SetSCX
 	ld h, $0
 	ld l, $70
-	call Func_74152
+	call ScrollCreditsMonLeft_SetSCX
 	ld a, b
 	add $8
 	ld b, a
 	ret
 
-Func_74152: ; 74152 (1d:4152)
+ScrollCreditsMonLeft_SetSCX: ; 74152 (1d:4152)
-	ld a, [$ff44]
+	ld a, [rLY]
 	cp l
-	jr nz, Func_74152
+	jr nz, ScrollCreditsMonLeft_SetSCX
 	ld a, h
 	ld [rSCX], a
-.asm_7415a
+.loop
-	ld a, [$ff44]
+	ld a, [rLY]
 	cp h
-	jr z, .asm_7415a
+	jr z, .loop
 	ret
 
 HoFGBPalettes: ; 74160 (1d:4160)
@@ -129,7 +136,7 @@ HoFGBPalettes: ; 74160 (1d:4160)
 	db %11100000
 	db %11110000
 
-Func_74164: ; 74164 (1d:4164)
+CopyTileMapToVRAM: ; 74164 (1d:4164)
 	ld a, l
 	ld [H_AUTOBGTRANSFERDEST], a
 	ld a, h
@@ -138,14 +145,15 @@ Func_74164: ; 74164 (1d:4164)
 	ld [H_AUTOBGTRANSFERENABLED], a
 	jp Delay3
 
-Func_74171: ; 74171 (1d:4171)
+ZeroMemory: ; 74171 (1d:4171)
-	ld [hl], $0
+; zero bc bytes at hl
+	ld [hl], 0
 	inc hl
 	inc hl
 	dec bc
 	ld a, b
 	or c
-	jr nz, Func_74171
+	jr nz, ZeroMemory
 	ret
 
 FillFourRowsWithBlack: ; 7417b (1d:417b)
@@ -162,26 +170,26 @@ FillMiddleOfScreenWithWhite: ; 74183 (1d:4183)
 Credits: ; 7418e (1d:418e)
 	ld de, CreditsOrder
 	push de
-.asm_74192
+.nextCreditsScreen
 	pop de
 	hlCoord 9, 6
 	push hl
 	call FillMiddleOfScreenWithWhite
 	pop hl
-.asm_7419b
+.nextCreditsCommand
 	ld a, [de]
 	inc de
 	push de
 	cp $ff
-	jr z, .asm_741d5
+	jr z, .fadeInTextAndShowMon
 	cp $fe
-	jr z, .asm_741dc
+	jr z, .showTextAndShowMon
 	cp $fd
-	jr z, .asm_741e6
+	jr z, .fadeInText
 	cp $fc
-	jr z, .asm_741ed
+	jr z, .showText
 	cp $fb
-	jr z, .asm_741f4
+	jr z, .showCopyrightText
 	cp $fa
 	jr z, .showTheEnd
 	push hl
@@ -189,7 +197,7 @@ Credits: ; 7418e (1d:418e)
 	ld hl, CreditsTextPointers
 	add a
 	ld c, a
-	ld b, $0
+	ld b, 0
 	add hl, bc
 	ld e, [hl]
 	inc hl
@@ -205,32 +213,32 @@ Credits: ; 7418e (1d:418e)
 	ld bc, SCREEN_WIDTH * 2
 	add hl, bc
 	pop de
-	jr .asm_7419b
+	jr .nextCreditsCommand
-.asm_741d5
+.fadeInTextAndShowMon
-	call Func_740ba
+	call FadeInCreditsText
 	ld c, 90
-	jr .asm_741de
+	jr .next1
-.asm_741dc
+.showTextAndShowMon
 	ld c, 110
-.asm_741de
+.next1
 	call DelayFrames
 	call DisplayCreditsMon
-	jr .asm_74192
+	jr .nextCreditsScreen
-.asm_741e6
+.fadeInText
-	call Func_740ba
+	call FadeInCreditsText
 	ld c, 120
-	jr .asm_741ef
+	jr .next2
-.asm_741ed
+.showText
 	ld c, 140
-.asm_741ef
+.next2
 	call DelayFrames
-	jr .asm_74192
+	jr .nextCreditsScreen
-.asm_741f4
+.showCopyrightText
 	push de
 	callba LoadCopyrightTiles
 	pop de
 	pop de
-	jr .asm_7419b
+	jr .nextCreditsCommand
 .showTheEnd
 	ld c, 16
 	call DelayFrames
@@ -246,7 +254,7 @@ Credits: ; 7418e (1d:418e)
 	hlCoord 4, 9
 	inc de
 	call PlaceString
-	jp Func_740ba
+	jp FadeInCreditsText
 
 TheEndTextString: ; 74229 (1d:4229)
 ; "T H E  E N D"

engine/battle/animations.asm

@@ -1973,7 +1973,7 @@ AnimationWavyScreen: ; 79666 (1e:5666)
 	push hl
 .asm_79680
 	call Func_796ae
-	ld a, [$ff44]
+	ld a, [rLY]
 	cp e
 	jr nz, .asm_79680
 	pop hl
@@ -2500,27 +2500,29 @@ CopyPicTiles: ; 79aae (1e:5aae)
 	ld a, [H_WHOSETURN]
 	and a
 	ld a, $31 ; base tile ID of player mon sprite
-	jr z, .asm_79ab6
+	jr z, .next
 ; enemy turn
 	xor a ; base tile ID of enemy mon sprite
-.asm_79ab6
+.next
 	ld [hBaseTileID], a
-	jr asm_79acb
+	jr CopyTileIDs_NoBGTransfer
 
-; copy the tiles used when a mon is being sent out
+; copy the tiles used when a mon is being sent out of or into a pokeball
-; and "growing" out of the pokeball
+CopyDownscaledMonTiles: ; 79aba (1e:5aba)
-CopyGrowingMonTiles: ; 79aba (1e:5aba)
 	call GetPredefRegisters
-	ld a, [wcd6c]
+	ld a, [wDownscaledMonSize]
 	and a
-	jr nz, .asm_79ac8
+	jr nz, .smallerSize
-	ld de, Unknown_79b02 ; 5x5
+	ld de, DownscaledMonTiles_5x5
-	jr asm_79acb
+	jr CopyTileIDs_NoBGTransfer
-.asm_79ac8
+.smallerSize
-	ld de, Unknown_79b1b ; 3x3
+	ld de, DownscaledMonTiles_3x3
-asm_79acb: ; 79acb (1e:5acb)
+; fall through
+
+CopyTileIDs_NoBGTransfer: ; 79acb (1e:5acb)
 	xor a
 	ld [H_AUTOBGTRANSFERENABLED], a
+; fall through
 
 ; b = number of rows
 ; c = number of columns
@@ -2567,14 +2569,14 @@ TileIDListPointerTable: ; 79aea (1e:5aea)
 	dw Unknown_79c50
 	db $3C
 
-Unknown_79b02: ; 79b02 (1e:5b02)
+DownscaledMonTiles_5x5: ; 79b02 (1e:5b02)
 	db $31,$38,$46,$54,$5B
 	db $32,$39,$47,$55,$5C
 	db $34,$3B,$49,$57,$5E
 	db $36,$3D,$4B,$59,$60
 	db $37,$3E,$4C,$5A,$61
 
-Unknown_79b1b: ; 79b1b (1e:5b1b)
+DownscaledMonTiles_3x3: ; 79b1b (1e:5b1b)
 	db $31,$46,$5B
 	db $34,$49,$5E
 	db $37,$4C,$61

engine/battle/bank_e_misc.asm

@@ -24,7 +24,7 @@ FormatMovesString: ; 39b87 (e:5b87)
 	jr .copyNameLoop
 .doneCopyingName
 	ld a, b
-	ld [wcd6c], a
+	ld [wNumMovesMinusOne], a
 	inc b
 	ld a, $4e ; line break
 	ld [de], a
@@ -70,7 +70,7 @@ InitList: ; 39bd5 (e:5bd5)
 .notPlayer
 	cp INIT_MON_LIST
 	jr nz, .notMonster
-	ld hl, wStringBuffer2 + 11
+	ld hl, wItemList
 	ld de, MonsterNames
 	ld a, MONSTER_NAME
 	jr .done
@@ -82,15 +82,15 @@ InitList: ; 39bd5 (e:5bd5)
 	ld a, ITEM_NAME
 	jr .done
 .notBag
-	ld hl, wStringBuffer2 + 11
+	ld hl, wItemList
 	ld de, ItemNames
 	ld a, ITEM_NAME
 .done
 	ld [wNameListType], a
 	ld a, l
-	ld [wList], a
+	ld [wListPointer], a
 	ld a, h
-	ld [wList + 1], a
+	ld [wListPointer + 1], a
 	ld a, e
 	ld [wcf8d], a
 	ld a, d
@@ -102,10 +102,10 @@ InitList: ; 39bd5 (e:5bd5)
 	ld [wItemPrices + 1], a
 	ret
 
-; get species of mon e in list [wcc49] for LoadMonData
+; get species of mon e in list [wMonDataLocation] for LoadMonData
 GetMonSpecies: ; 39c37 (e:5c37)
 	ld hl, wPartySpecies
-	ld a, [wcc49]
+	ld a, [wMonDataLocation]
 	and a
 	jr z, .getSpecies
 	dec a

engine/battle/battle_transitions.asm

@@ -104,12 +104,12 @@ GetBattleTransitionID_CompareLevels: ; 709ef (1c:49ef)
 	jr nc, .highLevelEnemy
 	res 1, c
 	ld a, $1
-	ld [wcd47], a
+	ld [wBattleTransitionSpiralDirection], a
 	ret
 .highLevelEnemy
 	set 1, c
 	xor a
-	ld [wcd47], a
+	ld [wBattleTransitionSpiralDirection], a
 	ret
 
 ; fails to recognize VICTORY_ROAD_2, VICTORY_ROAD_3, all ROCKET_HIDEOUT maps,
@@ -196,7 +196,7 @@ BattleTransition_BlackScreen: ; 70a69 (1c:4a69)
 ; outward spiral if enemy is at least 3 levels
 ; higher than player and does an inward spiral otherwise
 BattleTransition_Spiral: ; 70a72 (1c:4a72)
-	ld a, [wcd47]
+	ld a, [wBattleTransitionSpiralDirection]
 	and a
 	jr z, .outwardSpiral
 	call BattleTransition_InwardSpiral

engine/battle/core.asm

@@ -225,7 +225,7 @@ StartBattle: ; 3c11e (f:411e)
 	xor a
 	ld [wPartyGainExpFlags], a
 	ld [wPartyFoughtCurrentEnemyFlags], a
-	ld [wcd6a], a
+	ld [wActionResultOrTookBattleTurn], a
 	inc a
 	ld [wd11d], a
 	ld hl, wEnemyMon1HP
@@ -260,7 +260,7 @@ StartBattle: ; 3c11e (f:411e)
 .displaySafariZoneBattleMenu
 	call DisplayBattleMenu
 	ret c ; return if the player ran from battle
-	ld a, [wcd6a]
+	ld a, [wActionResultOrTookBattleTurn]
 	and a ; was the item used successfully?
 	jr z, .displaySafariZoneBattleMenu ; if not, display the menu again; XXX does this ever jump?
 	ld a, [W_NUMSAFARIBALLS]
@@ -415,8 +415,8 @@ MainInBattleLoop: ; 3c233 (f:4233)
 	ld [wPlayerSelectedMove], a
 	jr .selectEnemyMove
 .selectPlayerMove
-	ld a, [wcd6a]
+	ld a, [wActionResultOrTookBattleTurn]
-	and a
+	and a ; has the player already used the turn (e.g. by using an item, trying to run or switching pokemon)
 	jr nz, .selectEnemyMove
 	ld [wMoveMenuType], a
 	inc a
@@ -816,11 +816,11 @@ HandleEnemyMonFainted: ; 3c525 (f:4525)
 	call ChooseNextMon
 .skipReplacingBattleMon
 	ld a, $1
-	ld [wcd6a], a
+	ld [wActionResultOrTookBattleTurn], a
 	call ReplaceFaintedEnemyMon
 	jp z, EnemyRan
 	xor a
-	ld [wcd6a], a
+	ld [wActionResultOrTookBattleTurn], a
 	jp MainInBattleLoop
 
 FaintEnemyPokemon: ; 0x3c567
@@ -990,7 +990,7 @@ ReplaceFaintedEnemyMon: ; 3c664 (f:4664)
 	call EnemySendOut
 	xor a
 	ld [W_ENEMYMOVENUM], a
-	ld [wcd6a], a
+	ld [wActionResultOrTookBattleTurn], a
 	ld [wAILayer2Encouragement], a
 	inc a ; reset Z flag
 	ret
@@ -1075,11 +1075,11 @@ HandlePlayerMonFainted: ; 3c700 (f:4700)
 	jp nz, MainInBattleLoop ; if the enemy mon has more than 0 HP, go back to battle loop
 ; the enemy mon has 0 HP
 	ld a, $1
-	ld [wcd6a], a
+	ld [wActionResultOrTookBattleTurn], a
 	call ReplaceFaintedEnemyMon
 	jp z, EnemyRan ; if enemy ran from battle rather than sending out another mon, jump
 	xor a
-	ld [wcd6a], a
+	ld [wActionResultOrTookBattleTurn], a
 	jp MainInBattleLoop
 
 ; resets flags, slides mon's pic down, plays cry, and prints fainted message
@@ -1177,11 +1177,11 @@ ChooseNextMon: ; 3c7d8 (f:47d8)
 	cp LINK_STATE_BATTLING
 	jr nz, .notLinkBattle
 	inc a
-	ld [wcd6a], a
+	ld [wActionResultOrTookBattleTurn], a
 	call LinkBattleExchangeData
 .notLinkBattle
 	xor a
-	ld [wcd6a], a
+	ld [wActionResultOrTookBattleTurn], a
 	call ClearSprites
 	ld a, [wWhichPokemon]
 	ld [wPlayerMonNumber], a
@@ -1646,7 +1646,7 @@ TryRunningFromBattle: ; 3cab9 (f:4ab9)
 	                  ; plus 30 times the number of attempts, the player can escape
 ; can't escape
 	ld a, $1
-	ld [wcd6a], a
+	ld [wActionResultOrTookBattleTurn], a ; you lose your turn when you can't escape
 	ld hl, CantEscapeText
 	jr .printCantEscapeOrNoRunningText
 .trainerBattle
@@ -1666,7 +1666,7 @@ TryRunningFromBattle: ; 3cab9 (f:4ab9)
 ; link battle
 	call SaveScreenTilesToBuffer1
 	xor a
-	ld [wcd6a], a
+	ld [wActionResultOrTookBattleTurn], a
 	ld a, $f
 	ld [wPlayerMoveListIndex], a
 	call LinkBattleExchangeData
@@ -1809,7 +1809,7 @@ SendOutMon: ; 3cc91 (f:4c91)
 	predef LoadMonBackPic
 	xor a
 	ld [$ffe1], a
-	ld hl, wcc2d
+	ld hl, wBattleAndStartSavedMenuItem
 	ld [hli], a
 	ld [hl], a
 	ld [wBoostExpByExpAll], a
@@ -1842,7 +1842,7 @@ SendOutMon: ; 3cc91 (f:4c91)
 	call PrintEmptyString
 	jp SaveScreenTilesToBuffer1
 
-; show 2 stages of the player getting smaller before disappearing
+; show 2 stages of the player mon getting smaller before disappearing
 AnimateRetreatingPlayerMon: ; 3ccfa (f:4cfa)
 	hlCoord 1, 5
 	ld bc, $707
@@ -1850,19 +1850,19 @@ AnimateRetreatingPlayerMon: ; 3ccfa (f:4cfa)
 	hlCoord 3, 7
 	ld bc, $505
 	xor a
-	ld [wcd6c], a
+	ld [wDownscaledMonSize], a
 	ld [H_DOWNARROWBLINKCNT1], a
-	predef CopyGrowingMonTiles
+	predef CopyDownscaledMonTiles
 	ld c, 4
 	call DelayFrames
 	call .clearScreenArea
 	hlCoord 4, 9
 	ld bc, $303
 	ld a, $1
-	ld [wcd6c], a
+	ld [wDownscaledMonSize], a
 	xor a
 	ld [H_DOWNARROWBLINKCNT1], a
-	predef CopyGrowingMonTiles
+	predef CopyDownscaledMonTiles
 	call Delay3
 	call .clearScreenArea
 	ld a, $4c
@@ -2123,7 +2123,7 @@ DisplayBattleMenu: ; 3ceb3 (f:4eb3)
 .oldManName
 	db "OLD MAN@"
 .handleBattleMenuInput
-	ld a, [wcc2d]
+	ld a, [wBattleAndStartSavedMenuItem]
 	ld [wCurrentMenuItem], a
 	ld [wLastMenuItem], a
 	sub 2 ; check if the cursor is in the left column
@@ -2206,7 +2206,7 @@ DisplayBattleMenu: ; 3ceb3 (f:4eb3)
 	ld a, [W_BATTLETYPE]
 	cp $2 ; is it a Safari battle?
 	ld a, [wCurrentMenuItem]
-	ld [wcc2d], a
+	ld [wBattleAndStartSavedMenuItem], a
 	jr z, .handleMenuSelection
 ; not Safari battle
 ; swap the IDs of the item menu and party menu (this is probably because they swapped the positions
@@ -2276,9 +2276,9 @@ BagWasSelected:
 	jr nz, DisplayPlayerBag ; no, it is a normal battle
 	ld hl, OldManItemList
 	ld a, l
-	ld [wList], a
+	ld [wListPointer], a
 	ld a, h
-	ld [wList + 1], a
+	ld [wListPointer + 1], a
 	jr DisplayBagMenu
 
 OldManItemList:
@@ -2290,20 +2290,20 @@ DisplayPlayerBag:
 	; get the pointer to player's bag when in a normal battle
 	ld hl, wNumBagItems
 	ld a, l
-	ld [wList], a
+	ld [wListPointer], a
 	ld a, h
-	ld [wList + 1], a
+	ld [wListPointer + 1], a
 
 DisplayBagMenu:
 	xor a
 	ld [wPrintItemPrices], a
 	ld a, ITEMLISTMENU
 	ld [wListMenuID], a
-	ld a, [wcc2c]
+	ld a, [wBagSavedMenuItem]
 	ld [wCurrentMenuItem], a
 	call DisplayListMenuID
 	ld a, [wCurrentMenuItem]
-	ld [wcc2c], a
+	ld [wBagSavedMenuItem], a
 	ld a, $0
 	ld [wMenuWatchMovingOutOfBounds], a
 	ld [wMenuItemToSwap], a
@@ -2326,7 +2326,7 @@ UseBagItem:
 	cp $2 ; is it a safari battle?
 	jr z, .checkIfMonCaptured
 
-	ld a, [wcd6a]
+	ld a, [wActionResultOrTookBattleTurn]
 	and a ; was the item used successfully?
 	jp z, BagWasSelected ; if not, go back to the bag menu
 
@@ -2435,8 +2435,8 @@ PartyMenuOrRockOrRun:
 	and a ; was Switch selected?
 	jr z, .switchMon ; if so, jump
 ; Stats was selected
-	xor a
+	xor a ; PLAYER_PARTY_DATA
-	ld [wcc49], a
+	ld [wMonDataLocation], a
 	ld hl, wPartyMon1
 	call ClearSprites
 ; display the two status screens
@@ -2479,7 +2479,7 @@ PartyMenuOrRockOrRun:
 	call HasMonFainted
 	jp z, .partyMonDeselected ; can't switch to fainted mon
 	ld a, $1
-	ld [wcd6a], a
+	ld [wActionResultOrTookBattleTurn], a
 	call GBPalWhiteOut
 	call ClearSprites
 	call LoadHudTilePatterns
@@ -2525,9 +2525,9 @@ BattleMenu_RunWasSelected: ; 3d1fa (f:51fa)
 	ld a, $0
 	ld [wd11f], a
 	ret c
-	ld a, [wcd6a]
+	ld a, [wActionResultOrTookBattleTurn]
 	and a
-	ret nz
+	ret nz ; return if the player couldn't escape
 	jp DisplayBattleMenu
 
 MoveSelectionMenu: ; 3d219 (f:5219)
@@ -2604,9 +2604,9 @@ MoveSelectionMenu: ; 3d219 (f:5219)
 	ld a, $7
 .menuset
 	ld hl, wTopMenuItemY
-	ld [hli], a
+	ld [hli], a ; wTopMenuItemY
 	ld a, b
-	ld [hli], a
+	ld [hli], a ; wTopMenuItemX
 	ld a, [wMoveMenuType]
 	cp $1
 	jr z, .selectedmoveknown
@@ -2615,30 +2615,30 @@ MoveSelectionMenu: ; 3d219 (f:5219)
 	ld a, [wPlayerMoveListIndex]
 	inc a
 .selectedmoveknown
-	ld [hli], a
+	ld [hli], a ; wCurrentMenuItem
 	inc hl ; wTileBehindCursor untouched
-	ld a, [wcd6c]
+	ld a, [wNumMovesMinusOne]
 	inc a
 	inc a
-	ld [hli], a
+	ld [hli], a ; wMaxMenuItem
 	ld a, [wMoveMenuType]
 	dec a
-	ld b, $c1 ; can't use B
+	ld b, D_UP | D_DOWN | A_BUTTON
 	jr z, .matchedkeyspicked
 	dec a
-	ld b, $c3
+	ld b, D_UP | D_DOWN | A_BUTTON | B_BUTTON
 	jr z, .matchedkeyspicked
 	ld a, [wLinkState]
 	cp LINK_STATE_BATTLING
 	jr z, .matchedkeyspicked
 	ld a, [W_FLAGS_D733]
 	bit 0, a
-	ld b, $c7
+	ld b, D_UP | D_DOWN | A_BUTTON | B_BUTTON | SELECT
 	jr z, .matchedkeyspicked
 	ld b, $ff
 .matchedkeyspicked
 	ld a, b
-	ld [hli], a
+	ld [hli], a ; wMenuWatchedKeys
 	ld a, [wMoveMenuType]
 	cp $1
 	jr z, .movelistindex1
@@ -2759,7 +2759,7 @@ CursorUp: ; 3d3c9 (f:53c9)
 	and a
 	jp nz, SelectMenuItem
 	call EraseMenuCursor
-	ld a, [wcd6c]
+	ld a, [wNumMovesMinusOne]
 	inc a
 	ld [wCurrentMenuItem], a
 	jp SelectMenuItem
@@ -2767,7 +2767,7 @@ CursorUp: ; 3d3c9 (f:53c9)
 CursorDown: ; 3d3dd (f:53dd)
 	ld a, [wCurrentMenuItem]
 	ld b, a
-	ld a, [wcd6c]
+	ld a, [wNumMovesMinusOne]
 	inc a
 	inc a
 	cp b
@@ -2935,8 +2935,8 @@ PrintMenuItem: ; 3d4b6 (f:54b6)
 	                            ; isn't actually selected (just pointed to by the cursor)
 	ld a, [wPlayerMonNumber]
 	ld [wWhichPokemon], a
-	ld a, $4
+	ld a, BATTLE_MON_DATA
-	ld [wcc49], a
+	ld [wMonDataLocation], a
 	callab GetMaxPP
 	ld hl, wCurrentMenuItem
 	ld c, [hl]
@@ -2983,7 +2983,7 @@ TypeText: ; 3d55f (f:555f)
 
 SelectEnemyMove: ; 3d564 (f:5564)
 	ld a, [wLinkState]
-	sub $4
+	sub LINK_STATE_BATTLING
 	jr nz, .noLinkBattle
 ; link battle
 	call SaveScreenTilesToBuffer1
@@ -3079,46 +3079,47 @@ LinkBattleExchangeData: ; 3d605 (f:5605)
 	ld [wSerialExchangeNybbleReceiveData], a
 	ld a, [wPlayerMoveListIndex]
 	cp $f ; is the player running from battle?
-	jr z, .asm_3d630
+	jr z, .doExchange
-	ld a, [wcd6a]
+	ld a, [wActionResultOrTookBattleTurn]
-	and a
+	and a ; is the player switching in another mon?
-	jr nz, .asm_3d629
+	jr nz, .switching
+; the player used a move
 	ld a, [wPlayerSelectedMove]
 	cp STRUGGLE
 	ld b, $e
-	jr z, .asm_3d62f
+	jr z, .next
 	dec b
 	inc a
-	jr z, .asm_3d62f
+	jr z, .next
 	ld a, [wPlayerMoveListIndex]
-	jr .asm_3d630
+	jr .doExchange
-.asm_3d629
+.switching
 	ld a, [wWhichPokemon]
-	add $4
+	add 4
 	ld b, a
-.asm_3d62f
+.next
 	ld a, b
-.asm_3d630
+.doExchange
 	ld [wSerialExchangeNybbleSendData], a
 	callab PrintWaitingText
-.asm_3d63b
+.syncLoop1
 	call Serial_ExchangeNybble
 	call DelayFrame
 	ld a, [wSerialExchangeNybbleReceiveData]
 	inc a
-	jr z, .asm_3d63b
+	jr z, .syncLoop1
-	ld b, $a
+	ld b, 10
-.asm_3d649
+.syncLoop2
 	call DelayFrame
 	call Serial_ExchangeNybble
 	dec b
-	jr nz, .asm_3d649
+	jr nz, .syncLoop2
-	ld b, $a
+	ld b, 10
-.asm_3d654
+.syncLoop3
 	call DelayFrame
 	call Serial_SendZeroByte
 	dec b
-	jr nz, .asm_3d654
+	jr nz, .syncLoop3
 	ret
 
 ExecutePlayerMove: ; 3d65e (f:565e)
@@ -3133,8 +3134,8 @@ ExecutePlayerMove: ; 3d65e (f:565e)
 	ld [wMoveDidntMiss], a
 	ld a, $a
 	ld [wDamageMultipliers], a
-	ld a, [wcd6a]
+	ld a, [wActionResultOrTookBattleTurn]
-	and a
+	and a ; has the player already used the turn (e.g. by using an item, trying to run or switching pokemon)
 	jp nz, ExecutePlayerMoveDone
 	call PrintGhostText
 	jp z, ExecutePlayerMoveDone
@@ -3324,7 +3325,7 @@ MultiHitText: ; 3d805 (f:5805)
 
 ExecutePlayerMoveDone: ; 3d80a (f:580a)
 	xor a
-	ld [wcd6a],a
+	ld [wActionResultOrTookBattleTurn],a
 	ld b,1
 	ret
 
@@ -6856,7 +6857,7 @@ DetermineWildOpponent: ; 3ef23 (f:6f23)
 InitBattleCommon: ; 3ef3d (f:6f3d)
 	ld a, [wMapPalOffset]
 	push af
-	ld hl, wd358
+	ld hl, wLetterPrintingDelayFlags
 	ld a, [hl]
 	push af
 	res 1, [hl]
@@ -6963,7 +6964,7 @@ InitBattle_Common: ; 3efeb (f:6feb)
 	call StartBattle
 	callab EndOfBattle
 	pop af
-	ld [wd358], a
+	ld [wLetterPrintingDelayFlags], a
 	pop af
 	ld [wMapPalOffset], a
 	ld a, [wd0d4]
@@ -6998,7 +6999,7 @@ ResetCryModifiers: ; 3f069 (f:7069)
 	ld [wc0f2], a
 	jp PlaySound
 
-; animtes the mon "growing" out of the pokeball
+; animates the mon "growing" out of the pokeball
 AnimateSendingOutMon: ; 3f073 (f:7073)
 	ld a, [wPredefRegisters]
 	ld h, a
@@ -7016,17 +7017,17 @@ AnimateSendingOutMon: ; 3f073 (f:7073)
 	ld bc, -41
 	add hl, bc
 	ld a, $1
-	ld [wcd6c], a
+	ld [wDownscaledMonSize], a
 	ld bc, $303
-	predef CopyGrowingMonTiles
+	predef CopyDownscaledMonTiles
 	ld c, 4
 	call DelayFrames
 	ld bc, -41
 	add hl, bc
 	xor a
-	ld [wcd6c], a
+	ld [wDownscaledMonSize], a
 	ld bc, $505
-	predef CopyGrowingMonTiles
+	predef CopyDownscaledMonTiles
 	ld c, 5
 	call DelayFrames
 	ld bc, -41
@@ -8242,14 +8243,14 @@ ChargeEffect: ; 3f88c (f:788c)
 	ld a, b
 	call PlayBattleAnimation
 	ld a, [de]
-	ld [wWhichTrade], a
+	ld [wChargeMoveNum], a
 	ld hl, ChargeMoveEffectText
 	jp PrintText
 
 ChargeMoveEffectText: ; 3f8c8 (f:78c8)
 	TX_FAR _ChargeMoveEffectText
 	TX_ASM
-	ld a, [wWhichTrade]
+	ld a, [wChargeMoveNum]
 	cp RAZOR_WIND
 	ld hl, MadeWhirlwindText
 	jr z, .asm_3f8f8

engine/battle/end_of_battle.asm

@@ -54,7 +54,7 @@ EndOfBattle: ; 137aa (4:77aa)
 	ld [wd11f], a
 	ld [wNumRunAttempts], a
 	ld [wEscapedFromBattle], a
-	ld hl, wcc2b
+	ld hl, wPartyAndBillsPCSavedMenuItem
 	ld [hli], a
 	ld [hli], a
 	ld [hli], a

engine/battle/experience.asm

@@ -148,8 +148,8 @@ GainExperience: ; 5524f (15:524f)
 	call GetPartyMonName
 	ld hl, GainedText
 	call PrintText
-	xor a ; party mon data
+	xor a ; PLAYER_PARTY_DATA
-	ld [wcc49], a
+	ld [wMonDataLocation], a
 	call LoadMonData
 	pop hl
 	ld bc, wPartyMon1Level - wPartyMon1Exp
@@ -242,15 +242,15 @@ GainExperience: ; 5524f (15:524f)
 .printGrewLevelText
 	ld hl, GrewLevelText
 	call PrintText
-	xor a ; party mon data
+	xor a ; PLAYER_PARTY_DATA
-	ld [wcc49], a
+	ld [wMonDataLocation], a
 	call LoadMonData
 	ld d, $1
 	callab PrintStatsBox
 	call WaitForTextScrollButtonPress
 	call LoadScreenTilesFromBuffer1
-	xor a
+	xor a ; PLAYER_PARTY_DATA
-	ld [wcc49], a
+	ld [wMonDataLocation], a
 	ld a, [wd0b5]
 	ld [wd11e], a
 	predef LearnMoveFromLevelUp

engine/battle/init_battle_variables.asm

@@ -2,9 +2,9 @@ InitBattleVariables: ; 525af (14:65af)
 	ld a, [hTilesetType]
 	ld [wd0d4], a
 	xor a
-	ld [wcd6a], a
+	ld [wActionResultOrTookBattleTurn], a
 	ld [wBattleResult], a
-	ld hl, wcc2b
+	ld hl, wPartyAndBillsPCSavedMenuItem
 	ld [hli], a
 	ld [hli], a
 	ld [hli], a

engine/battle/read_trainer_party.asm

@@ -55,8 +55,8 @@ ReadTrainer: ; 39c53 (e:5c53)
 	and a ; have we reached the end of the trainer data?
 	jr z,.FinishUp
 	ld [wcf91],a ; write species somewhere (XXX why?)
-	ld a,1
+	ld a,ENEMY_PARTY_DATA
-	ld [wcc49],a
+	ld [wMonDataLocation],a
 	push hl
 	call AddPartyMon
 	pop hl
@@ -72,8 +72,8 @@ ReadTrainer: ; 39c53 (e:5c53)
 	ld [W_CURENEMYLVL],a
 	ld a,[hli]
 	ld [wcf91],a
-	ld a,1
+	ld a,ENEMY_PARTY_DATA
-	ld [wcc49],a
+	ld [wMonDataLocation],a
 	push hl
 	call AddPartyMon
 	pop hl

engine/battle/trainer_ai.asm

@@ -559,7 +559,7 @@ AIPlayRestoringSFX: ; 3a69b (e:669b)
 AIUseFullRestore: ; 3a6a0 (e:66a0)
 	call AICureStatus
 	ld a,FULL_RESTORE
-	ld [wcf05],a
+	ld [wAIItem],a
 	ld de,wHPBarOldHP
 	ld hl,wEnemyMonHP + 1
 	ld a,[hld]
@@ -600,7 +600,7 @@ AIUseHyperPotion: ; 3a6d6 (e:66d6)
 
 AIRecoverHP: ; 3a6da (e:66da)
 ; heal b HP and print "trainer used $(a) on pokemon!"
-	ld [wcf05],a
+	ld [wAIItem],a
 	ld hl,wEnemyMonHP + 1
 	ld a,[hl]
 	ld [wHPBarOldHP],a
@@ -797,7 +797,7 @@ AIUseXSpecial: ; 3a804 (e:6804)
 	; fallthrough
 
 AIIncreaseStat: ; 3a808 (e:6808)
-	ld [wcf05],a
+	ld [wAIItem],a
 	push bc
 	call AIPrintItemUse_
 	pop bc
@@ -819,13 +819,13 @@ AIIncreaseStat: ; 3a808 (e:6808)
 	jp DecrementAICount
 
 AIPrintItemUse: ; 3a82c (e:682c)
-	ld [wcf05],a
+	ld [wAIItem],a
 	call AIPrintItemUse_
 	jp DecrementAICount
 
 AIPrintItemUse_: ; 3a835 (e:6835)
-; print "x used [wcf05] on z!"
+; print "x used [wAIItem] on z!"
-	ld a,[wcf05]
+	ld a,[wAIItem]
 	ld [wd11e],a
 	call GetItemName
 	ld hl, AIBattleUseItemText

engine/evos_moves.asm

@@ -55,8 +55,8 @@ Evolution_PartyMonLoop: ; loop over party mons
 	push hl
 	ld a, [wcf91]
 	push af
-	xor a
+	xor a ; PLAYER_PARTY_DATA
-	ld [wcc49], a
+	ld [wMonDataLocation], a
 	call LoadMonData
 	pop af
 	ld [wcf91], a
@@ -206,7 +206,7 @@ Evolution_PartyMonLoop: ; loop over party mons
 	ld a, [wd0b5]
 	ld [wd11e], a
 	xor a
-	ld [wcc49], a
+	ld [wMonDataLocation], a
 	call LearnMoveFromLevelUp
 	pop hl
 	predef SetPartyMonTypes
@@ -345,12 +345,13 @@ LearnMoveFromLevelUp: ; 3af5b (e:6f5b)
 	ld a, [hli] ; move ID
 	jr nz, .learnSetLoop
 	ld d, a ; ID of move to learn
-	ld a, [wcc49]
+	ld a, [wMonDataLocation]
 	and a
 	jr nz, .next
-; if [wcc49] is 0, get the address of the mon's current moves
+; If [wMonDataLocation] is 0 (PLAYER_PARTY_DATA), get the address of the mon's
-; there is no reason to make this conditional because the code wouldn't work properly without doing this
+; current moves in party data. Every call to this function sets
-; every call to this function sets [wcc49] to 0
+; [wMonDataLocation] to 0 because other data locations are not supported.
+; If it is not 0, this function will not work properly.
 	ld hl, wPartyMon1Moves
 	ld a, [wWhichPokemon]
 	ld bc, wPartyMon2 - wPartyMon1

engine/give_pokemon.asm

@@ -16,7 +16,7 @@ _GivePokemon: ; 4fda5 (13:7da5)
 	call SetPokedexOwnedFlag
 	callab SendNewMonToBox
 	ld hl, wcf4b
-	ld a, [wd5a0]
+	ld a, [wCurrentBoxNum]
 	and $7f
 	cp 9
 	jr c, .asm_4fdec

engine/hall_of_fame.asm

@@ -1,5 +1,5 @@
 AnimateHallOfFame: ; 701a0 (1c:41a0)
-	call Func_70423
+	call HoFFadeOutScreenAndMusic
 	call ClearScreen
 	ld c, 100
 	call DelayFrames
@@ -21,16 +21,16 @@ AnimateHallOfFame: ; 701a0 (1c:41a0)
 	ld [wUpdateSpritesEnabled], a
 	ld [hTilesetType], a
 	ld [W_SPRITEFLIPPED], a
-	ld [wd358], a
+	ld [wLetterPrintingDelayFlags], a ; no delay
-	ld [wTrainerScreenY], a
+	ld [wHoFMonOrPlayer], a ; mon
 	inc a
 	ld [H_AUTOBGTRANSFERENABLED], a
-	ld hl, wd5a2
+	ld hl, wNumHoFTeams
 	ld a, [hl]
 	inc a
-	jr z, .asm_701eb
+	jr z, .skipInc ; don't wrap around to 0
 	inc [hl]
-.asm_701eb
+.skipInc
 	ld a, $90
 	ld [hWY], a
 	ld c, BANK(Music_HallOfFame)
@@ -38,23 +38,23 @@ AnimateHallOfFame: ; 701a0 (1c:41a0)
 	call PlayMusic
 	ld hl, wPartySpecies
 	ld c, $ff
-.asm_701fb
+.partyMonLoop
 	ld a, [hli]
 	cp $ff
-	jr z, .asm_70241
+	jr z, .doneShowingParty
 	inc c
 	push hl
 	push bc
-	ld [wWhichTrade], a
+	ld [wHoFMonSpecies], a
 	ld a, c
-	ld [wTrainerEngageDistance], a
+	ld [wHoFPartyMonIndex], a
 	ld hl, wPartyMon1Level
 	ld bc, wPartyMon2 - wPartyMon1
 	call AddNTimes
 	ld a, [hl]
-	ld [wTrainerFacingDirection], a
+	ld [wHoFMonLevel], a
-	call Func_70278
+	call HoFShowMonOrPlayer
-	call Func_702e1
+	call HoFDisplayAndRecordMonInfo
 	ld c, 80
 	call DelayFrames
 	hlCoord 2, 13
@@ -69,8 +69,8 @@ AnimateHallOfFame: ; 701a0 (1c:41a0)
 	call GBFadeOutToWhite
 	pop bc
 	pop hl
-	jr .asm_701fb
+	jr .partyMonLoop
-.asm_70241
+.doneShowingParty
 	ld a, c
 	inc a
 	ld hl, wHallOfFame
@@ -79,12 +79,12 @@ AnimateHallOfFame: ; 701a0 (1c:41a0)
 	ld [hl], $ff
 	call SaveHallOfFameTeams
 	xor a
-	ld [wWhichTrade], a
+	ld [wHoFMonSpecies], a
 	inc a
-	ld [wTrainerScreenY], a
+	ld [wHoFMonOrPlayer], a ; player
-	call Func_70278
+	call HoFShowMonOrPlayer
 	call HoFDisplayPlayerStats
-	call Func_70423
+	call HoFFadeOutScreenAndMusic
 	xor a
 	ld [hWY], a
 	ld hl, rLCDC
@@ -94,69 +94,72 @@ AnimateHallOfFame: ; 701a0 (1c:41a0)
 HallOfFameText: ; 7026b (1c:426b)
 	db "HALL OF FAME@"
 
-Func_70278: ; 70278 (1c:4278)
+HoFShowMonOrPlayer: ; 70278 (1c:4278)
 	call ClearScreen
 	ld a, $d0
 	ld [hSCY], a
 	ld a, $c0
 	ld [hSCX], a
-	ld a, [wWhichTrade]
+	ld a, [wHoFMonSpecies]
 	ld [wcf91], a
 	ld [wd0b5], a
 	ld [wBattleMonSpecies2], a
 	ld [wcf1d], a
-	ld a, [wTrainerScreenY]
+	ld a, [wHoFMonOrPlayer]
 	and a
-	jr z, .asm_7029d
+	jr z, .showMon
+; show player
 	call HoFLoadPlayerPics
-	jr .asm_702ab
+	jr .next1
-.asm_7029d
+.showMon
 	hlCoord 12, 5
 	call GetMonHeader
 	call LoadFrontSpriteByMonIndex
 	predef LoadMonBackPic
-.asm_702ab
+.next1
 	ld b, $b
 	ld c, $0
 	call GoPAL_SET
-	ld a, $e4
+	ld a, %11100100
 	ld [rBGP], a
-	ld c, $31
+	ld c, $31 ; back pic
-	call Func_7036d
+	call HoFLoadMonPlayerPicTileIDs
 	ld d, $a0
-	ld e, $4
+	ld e, 4
 	ld a, [wOnSGB]
 	and a
-	jr z, .asm_702c7
+	jr z, .next2
-	sla e
+	sla e ; scroll more slowly on SGB
-.asm_702c7
+.next2
-	call .asm_702d5
+	call .ScrollPic ; scroll back pic left
 	xor a
 	ld [hSCY], a
-	ld c, a
+	ld c, a ; front pic
-	call Func_7036d
+	call HoFLoadMonPlayerPicTileIDs
-	ld d, $0
+	ld d, 0
-	ld e, $fc
+	ld e, -4
-.asm_702d5
+; scroll front pic right
+
+.ScrollPic
 	call DelayFrame
 	ld a, [hSCX]
 	add e
 	ld [hSCX], a
 	cp d
-	jr nz, .asm_702d5
+	jr nz, .ScrollPic
 	ret
 
-Func_702e1: ; 702e1 (1c:42e1)
+HoFDisplayAndRecordMonInfo: ; 702e1 (1c:42e1)
-	ld a, [wTrainerEngageDistance]
+	ld a, [wHoFPartyMonIndex]
 	ld hl, wPartyMonNicks
 	call GetPartyMonName
-	call Func_702f0
+	call HoFDisplayMonInfo
-	jp Func_70404
+	jp HoFRecordMonInfo
 
-Func_702f0: ; 702f0 (1c:42f0)
+HoFDisplayMonInfo: ; 702f0 (1c:42f0)
 	hlCoord 0, 2
-	ld b, $9
+	ld b, 9
-	ld c, $a
+	ld c, 10
 	call TextBoxBorder
 	hlCoord 2, 6
 	ld de, HoFMonInfoText
@@ -164,14 +167,14 @@ Func_702f0: ; 702f0 (1c:42f0)
 	hlCoord 1, 4
 	ld de, wcd6d
 	call PlaceString
-	ld a, [wTrainerFacingDirection]
+	ld a, [wHoFMonLevel]
 	hlCoord 8, 7
 	call PrintLevelCommon
-	ld a, [wWhichTrade]
+	ld a, [wHoFMonSpecies]
 	ld [wd0b5], a
 	hlCoord 3, 9
 	predef PrintMonType
-	ld a, [wWhichTrade]
+	ld a, [wHoFMonSpecies]
 	jp PlayCry
 
 HoFMonInfoText: ; 70329 (1c:4329)
@@ -197,8 +200,9 @@ HoFLoadPlayerPics: ; 7033e (1c:433e)
 	call InterlaceMergeSpriteBuffers
 	ld c, $1
 
-Func_7036d: ; 7036d (1c:436d)
+HoFLoadMonPlayerPicTileIDs: ; 7036d (1c:436d)
-	ld b, $0
+; c = base tile ID
+	ld b, 0
 	hlCoord 12, 5
 	predef_jump CopyTileIDsFromList
 
@@ -261,14 +265,14 @@ DexRatingText: ; 703ff (1c:43ff)
 	TX_FAR _DexRatingText
 	db "@"
 
-Func_70404: ; 70404 (1c:4404)
+HoFRecordMonInfo: ; 70404 (1c:4404)
 	ld hl, wHallOfFame
 	ld bc, HOF_MON
-	ld a, [wTrainerEngageDistance]
+	ld a, [wHoFPartyMonIndex]
 	call AddNTimes
-	ld a, [wWhichTrade]
+	ld a, [wHoFMonSpecies]
 	ld [hli], a
-	ld a, [wTrainerFacingDirection]
+	ld a, [wHoFMonLevel]
 	ld [hli], a
 	ld e, l
 	ld d, h
@@ -276,7 +280,7 @@ Func_70404: ; 70404 (1c:4404)
 	ld bc, $b
 	jp CopyData
 
-Func_70423: ; 70423 (1c:4423)
+HoFFadeOutScreenAndMusic: ; 70423 (1c:4423)
 	ld a, $a
 	ld [wcfc8], a
 	ld [wcfc9], a

engine/in_game_trades.asm

@@ -130,11 +130,11 @@ InGameTrade_DoTrade: ; 71c07 (1c:5c07)
 	ld a,[wInGameTradeReceiveMonSpecies]
 	ld [wcf91],a
 	xor a
-	ld [wcc49],a
+	ld [wMonDataLocation],a ; not used
 	ld [wRemoveMonFromBox],a
 	call RemovePokemon
-	ld a,$80
+	ld a,$80 ; prevent the player from naming the mon
-	ld [wcc49],a
+	ld [wMonDataLocation],a
 	call AddPartyMon
 	call InGameTrade_CopyDataToReceivedMon
 	callab EvolveTradeMon
@@ -177,9 +177,9 @@ InGameTrade_PrepareTradeData: ; 71cc1 (1c:5cc1)
 	ld bc, $b
 	call InGameTrade_CopyData
 	ld hl, InGameTrade_TrainerString
-	ld de, wcd4e
+	ld de, wTradedEnemyMonOT
 	call InGameTrade_CopyData
-	ld de, W_GRASSRATE
+	ld de, wLinkEnemyTrainerName
 	call InGameTrade_CopyData
 	ld hl, wPartyMon1OTID
 	ld bc, wPartyMon2 - wPartyMon1

engine/items/items.asm

@@ -1,6 +1,6 @@
 UseItem_: ; d5c7 (3:55c7)
 	ld a,1
-	ld [wcd6a],a
+	ld [wActionResultOrTookBattleTurn],a ; initialise to success value
 	ld a,[wcf91]	;contains item_ID
 	cp a,HM_01
 	jp nc,ItemUseTMHM
@@ -423,8 +423,8 @@ ItemUseBall: ; d687 (3:5687)
 	ld a,[wPartyCount]
 	cp a,PARTY_LENGTH		;is party full?
 	jr z,.sendToBox
-	xor a
+	xor a ; PLAYER_PARTY_DATA
-	ld [wcc49],a
+	ld [wMonDataLocation],a
 	call ClearSprites
 	call AddPartyMon	;add mon to Party
 	jr .End
@@ -661,7 +661,7 @@ ItemUseEvoStone: ; da5b (3:5a5b)
 	call ItemUseNoEffect
 .canceledItemUse
 	xor a
-	ld [wcd6a],a
+	ld [wActionResultOrTookBattleTurn],a ; item not used
 	pop af
 	ret
 
@@ -691,7 +691,7 @@ ItemUseMedicine: ; dabb (3:5abb)
 .emptyParty
 	ld hl,.emptyPartyText
 	xor a
-	ld [wcd6a],a ; item use failed
+	ld [wActionResultOrTookBattleTurn],a ; item use failed
 	jp PrintText
 .emptyPartyText
 	text "You don't have"
@@ -706,7 +706,7 @@ ItemUseMedicine: ; dabb (3:5abb)
 	ld a,[wWhichPokemon]
 	call AddNTimes
 	ld a,[wWhichPokemon]
-	ld [wcf06],a
+	ld [wUsedItemOnWhichPokemon],a
 	ld d,a
 	ld a,[wcf91]
 	ld e,a
@@ -803,7 +803,7 @@ ItemUseMedicine: ; dabb (3:5abb)
 	push hl
 	push de
 	push bc
-	ld a,[wcf06]
+	ld a,[wUsedItemOnWhichPokemon]
 	ld c,a
 	ld hl,wPartyFoughtCurrentEnemyFlags
 	ld b,$02
@@ -811,7 +811,7 @@ ItemUseMedicine: ; dabb (3:5abb)
 	ld a,c
 	and a
 	jr z,.next
-	ld a,[wcf06]
+	ld a,[wUsedItemOnWhichPokemon]
 	ld c,a
 	ld hl,wPartyGainExpFlags
 	ld b,$01
@@ -1106,7 +1106,7 @@ ItemUseMedicine: ; dabb (3:5abb)
 	jr .done
 .canceledItemUse
 	xor a
-	ld [wcd6a],a ; item use failed
+	ld [wActionResultOrTookBattleTurn],a ; item use failed
 	pop af
 	pop af
 .done
@@ -1265,14 +1265,14 @@ ItemUseMedicine: ; dabb (3:5abb)
 	ld [wWhichPokemon],a
 	ld a,e
 	ld [wd11e],a
-	xor a
+	xor a ; PLAYER_PARTY_DATA
-	ld [wcc49],a ; load from player's party
+	ld [wMonDataLocation],a
 	call LoadMonData
 	ld d,$01
 	callab PrintStatsBox ; display new stats text box
 	call WaitForTextScrollButtonPress ; wait for button press
-	xor a
+	xor a ; PLAYER_PARTY_DATA
-	ld [wcc49],a
+	ld [wMonDataLocation],a
 	predef LearnMoveFromLevelUp ; learn level up move, if any
 	xor a
 	ld [wForceEvolution],a
@@ -1384,7 +1384,7 @@ ItemUseEscapeRope: ; dfaf (3:5faf)
 	ld [W_SAFARIZONEENTRANCECURSCRIPT],a
 	inc a
 	ld [wEscapedFromBattle],a
-	ld [wcd6a],a ; item used
+	ld [wActionResultOrTookBattleTurn],a ; item used
 	ld a,[wd152]
 	and a ; using Dig?
 	ret nz ; if so, return
@@ -1550,7 +1550,7 @@ ItemUseXStat: ; e104 (3:6104)
 	jr nz,.inBattle
 	call ItemUseNotTime
 	ld a,2
-	ld [wcd6a],a ; item not used
+	ld [wActionResultOrTookBattleTurn],a ; item not used
 	ret
 .inBattle
 	ld hl,W_PLAYERMOVENUM
@@ -1783,7 +1783,7 @@ SuperRodCode: ; e283 (3:6283)
 	call ReadSuperRodData
 	ld a, e
 RodResponse: ; e28d (3:628d)
-	ld [wWhichTrade], a
+	ld [wRodResponse], a
 
 	dec a ; is there a bite?
 	jr nz, .next
@@ -1801,7 +1801,7 @@ RodResponse: ; e28d (3:628d)
 	push af
 	push hl
 	ld [hl], 0
-	callba Func_707b6
+	callba FishingAnim
 	pop hl
 	pop af
 	ld [hl], a
@@ -1963,8 +1963,8 @@ ItemUsePPRestore: ; e31e (3:631e)
 ; unsets zero flag if PP was restored, sets zero flag if not
 ; however, this is bugged for Max Ethers and Max Elixirs (see below)
 .restorePP
-	xor a
+	xor a ; PLAYER_PARTY_DATA
-	ld [wcc49],a ; party pokemon
+	ld [wMonDataLocation],a
 	call GetMaxPP
 	ld hl,wPartyMon1Moves
 	ld bc,44
@@ -2043,7 +2043,7 @@ ItemUsePPRestore: ; e31e (3:631e)
 	call GoPAL_SET_CF1C
 	pop af
 	xor a
-	ld [wcd6a],a ; item use failed
+	ld [wActionResultOrTookBattleTurn],a ; item use failed
 	ret
 
 RaisePPWhichTechniqueText: ; e45d (3:645d)
@@ -2104,7 +2104,7 @@ ItemUseTMHM: ; e479 (3:6479)
 	and a
 	jr z,.useMachine
 	ld a,2
-	ld [wcd6a],a ; item not used
+	ld [wActionResultOrTookBattleTurn],a ; item not used
 	ret
 .useMachine
 	ld a,[wWhichPokemon]
@@ -2234,7 +2234,7 @@ SurfingAttemptFailed: ; e5b6 (3:65b6)
 
 ItemUseFailed: ; e5b9 (3:65b9)
 	xor a
-	ld [wcd6a],a ; item use failed
+	ld [wActionResultOrTookBattleTurn],a ; item use failed
 	jp PrintText
 
 ItemUseNotTimeText: ; e5c0 (3:65c0)
@@ -2301,13 +2301,13 @@ RestoreBonusPP: ; e606 (3:6606)
 	ld a,[wWhichPokemon]
 	call AddNTimes
 	push hl
-	ld de,wcd78 - 1
+	ld de,wNormalMaxPPList - 1
-	predef LoadMovePPs ; loads the normal max PP of each of the pokemon's moves to wcd78
+	predef LoadMovePPs ; loads the normal max PP of each of the pokemon's moves to wNormalMaxPPList
 	pop hl
 	ld c,21
 	ld b,0
 	add hl,bc ; hl now points to move 1 PP
-	ld de,wcd78
+	ld de,wNormalMaxPPList
 	ld b,0 ; initialize move counter to zero
 ; loop through the pokemon's moves
 .loop
@@ -2379,7 +2379,7 @@ AddBonusPP: ; e642 (3:6642)
 ; gets max PP of a pokemon's move (including PP from PP Ups)
 ; INPUT:
 ; [wWhichPokemon] = index of pokemon within party/box
-; [wcc49] = pokemon source
+; [wMonDataLocation] = pokemon source
 ; 00: player's party
 ; 01: enemy's party
 ; 02: current box
@@ -2389,7 +2389,7 @@ AddBonusPP: ; e642 (3:6642)
 ; OUTPUT:
 ; [wd11e] = max PP
 GetMaxPP: ; e677 (3:6677)
-	ld a,[wcc49]
+	ld a,[wMonDataLocation]
 	and a
 	ld hl,wPartyMon1Moves
 	ld bc,wPartyMon2 - wPartyMon1
@@ -2420,13 +2420,13 @@ GetMaxPP: ; e677 (3:6677)
 	ld de,wcd6d
 	ld a,BANK(Moves)
 	call FarCopyData
-	ld de,wcd72
+	ld de,wcd6d + 5 ; PP is byte 5 of move data
 	ld a,[de]
 	ld b,a ; b = normal max PP
 	pop hl
 	push bc
 	ld bc,21 ; PP offset if not player's in-battle pokemon data
-	ld a,[wcc49]
+	ld a,[wMonDataLocation]
 	cp a,4 ; player's in-battle pokemon?
 	jr nz,.addPPOffset
 	ld bc,17 ; PP offset if player's in-battle pokemon data

engine/learn_move.asm

@@ -134,18 +134,18 @@ TryingToLearn: ; 6f07 (1:6f07)
 	res 2, a
 	ld [hFlags_0xFFF6], a
 	ld hl, wTopMenuItemY
-	ld a, $8
+	ld a, 8
-	ld [hli], a
+	ld [hli], a ; wTopMenuItemY
-	ld a, $5
+	ld a, 5
-	ld [hli], a
+	ld [hli], a ; wTopMenuItemX
 	xor a
-	ld [hli], a
+	ld [hli], a ; wCurrentMenuItem
 	inc hl
-	ld a, [wcd6c]
+	ld a, [wNumMovesMinusOne]
-	ld [hli], a
+	ld [hli], a ; wMaxMenuItem
-	ld a, $3
+	ld a, A_BUTTON | B_BUTTON
-	ld [hli], a
+	ld [hli], a ; wMenuWatchedKeys
-	ld [hl], $0
+	ld [hl], 0 ; wLastMenuItem
 	ld hl, hFlags_0xFFF6
 	set 1, [hl]
 	call HandleMenuInput

engine/menu/bills_pc.asm

@@ -1,44 +1,44 @@
-Func_213c8:: ; 213c8 (8:53c8)
+DisplayPCMainMenu:: ; 213c8 (8:53c8)
 	xor a
 	ld [H_AUTOBGTRANSFERENABLED], a
 	call SaveScreenTilesToBuffer2
-	ld a, [wd5a2]
+	ld a, [wNumHoFTeams]
 	and a
-	jr nz, .asm_213f3
+	jr nz, .leaguePCAvailable
 	ld a, [wd74b]
-	bit 5, a
+	bit 5, a ; received pokedex?
-	jr z, .asm_213ea
+	jr z, .noOaksPC
-	ld a, [wd5a2]
+	ld a, [wNumHoFTeams]
 	and a
-	jr nz, .asm_213f3
+	jr nz, .leaguePCAvailable
 	hlCoord 0, 0
-	ld b, $8
+	ld b, 8
-	ld c, $e
+	ld c, 14
-	jr .asm_213fa
+	jr .next
-.asm_213ea
+.noOaksPC
 	hlCoord 0, 0
-	ld b, $6
+	ld b, 6
-	ld c, $e
+	ld c, 14
-	jr .asm_213fa
+	jr .next
-.asm_213f3
+.leaguePCAvailable
 	hlCoord 0, 0
-	ld b, $a
+	ld b, 10
-	ld c, $e
+	ld c, 14
-.asm_213fa
+.next
 	call TextBoxBorder
 	call UpdateSprites
-	ld a, $3
+	ld a, 3
 	ld [wMaxMenuItem], a
 	ld a, [wd7f1]
 	bit 0, a
-	jr nz, .asm_21414
+	jr nz, .metBill
 	hlCoord 2, 2
 	ld de, SomeonesPCText
-	jr .asm_2141a
+	jr .next2
-.asm_21414
+.metBill
 	hlCoord 2, 2
 	ld de, BillsPCText
-.asm_2141a
+.next2
 	call PlaceString
 	hlCoord 2, 4
 	ld de, wPlayerName
@@ -48,43 +48,43 @@ Func_213c8:: ; 213c8 (8:53c8)
 	ld de, PlayersPCText
 	call PlaceString
 	ld a, [wd74b]
-	bit 5, a
+	bit 5, a ; received pokedex?
-	jr z, .asm_21462
+	jr z, .noOaksPC2
 	hlCoord 2, 6
 	ld de, OaksPCText
 	call PlaceString
-	ld a, [wd5a2]
+	ld a, [wNumHoFTeams]
 	and a
-	jr z, .asm_2145a
+	jr z, .noLeaguePC
-	ld a, $4
+	ld a, 4
 	ld [wMaxMenuItem], a
 	hlCoord 2, 8
 	ld de, PKMNLeaguePCText
 	call PlaceString
 	hlCoord 2, 10
 	ld de, LogOffPCText
-	jr .asm_2146d
+	jr .next3
-.asm_2145a
+.noLeaguePC
 	hlCoord 2, 8
 	ld de, LogOffPCText
-	jr .asm_2146d
+	jr .next3
-.asm_21462
+.noOaksPC2
 	ld a, $2
 	ld [wMaxMenuItem], a
 	hlCoord 2, 6
 	ld de, LogOffPCText
-.asm_2146d
+.next3
 	call PlaceString
-	ld a, $3
+	ld a, A_BUTTON | B_BUTTON
 	ld [wMenuWatchedKeys], a
-	ld a, $2
+	ld a, 2
 	ld [wTopMenuItemY], a
-	ld a, $1
+	ld a, 1
 	ld [wTopMenuItemX], a
 	xor a
 	ld [wCurrentMenuItem], a
 	ld [wLastMenuItem], a
-	ld a, $1
+	ld a, 1
 	ld [H_AUTOBGTRANSFERENABLED], a
 	ret
 
@@ -99,23 +99,23 @@ BillsPC_:: ; 0x214c2
 	ld hl, wd730
 	set 6, [hl]
 	xor a
-	ld [wccd3], a
+	ld [wParentMenuItem], a
 	inc a               ; MONSTER_NAME
 	ld [wNameListType], a
 	call LoadHpBarAndStatusTilePatterns
 	ld a, [wListScrollOffset]
 	push af
 	ld a, [wFlags_0xcd60]
-	bit 3, a
+	bit 3, a ; accessing Bill's PC through another PC?
 	jr nz, BillsPCMenu
+; accessing it directly
 	ld a, $99
 	call PlaySound
 	ld hl, SwitchOnText
 	call PrintText
 
-Func_214e8: ; 214e8 (8:54e8)
+BillsPCMenu: ; 214e8 (8:54e8)
-BillsPCMenu:
+	ld a, [wParentMenuItem]
-	ld a, [wccd3]
 	ld [wCurrentMenuItem], a
 	ld hl, vChars2 + $780
 	ld de, PokeballTileGraphics
@@ -123,79 +123,81 @@ BillsPCMenu:
 	call CopyVideoData
 	call LoadScreenTilesFromBuffer2DisableBGTransfer
 	hlCoord 0, 0
-	ld b, $a
+	ld b, 10
-	ld c, $c
+	ld c, 12
 	call TextBoxBorder
 	hlCoord 2, 2
 	ld de, BillsPCMenuText
 	call PlaceString
 	ld hl, wTopMenuItemY
-	ld a, $2
+	ld a, 2
-	ld [hli], a
+	ld [hli], a ; wTopMenuItemY
 	dec a
-	ld [hli], a
+	ld [hli], a ; wTopMenuItemX
 	inc hl
 	inc hl
-	ld a, $4
+	ld a, 4
-	ld [hli], a
+	ld [hli], a ; wMaxMenuItem
-	ld a, $3
+	ld a, A_BUTTON | B_BUTTON
-	ld [hli], a
+	ld [hli], a ; wMenuWatchedKeys
 	xor a
-	ld [hli], a
+	ld [hli], a ; wLastMenuItem
-	ld [hli], a
+	ld [hli], a ; wPartyAndBillsPCSavedMenuItem
 	ld hl, wListScrollOffset
-	ld [hli], a
+	ld [hli], a ; wListScrollOffset
-	ld [hl], a
+	ld [hl], a ; wMenuWatchMovingOutOfBounds
 	ld [wPlayerMonNumber], a
 	ld hl, WhatText
 	call PrintText
 	hlCoord 9, 14
-	ld b, $2
+	ld b, 2
-	ld c, $9
+	ld c, 9
 	call TextBoxBorder
-	ld a, [wd5a0]
+	ld a, [wCurrentBoxNum]
 	and $7f
 	cp 9
-	jr c, .asm_2154f
+	jr c, .singleDigitBoxNum
+; two digit box num
 	sub 9
 	hlCoord 17, 16
 	ld [hl], "1"
 	add "0"
-	jr .asm_21551
+	jr .next
-.asm_2154f
+.singleDigitBoxNum
 	add "1"
-.asm_21551
+.next
 	Coorda 18, 16
 	hlCoord 10, 16
 	ld de, BoxNoPCText
 	call PlaceString
-	ld a, $1
+	ld a, 1
 	ld [H_AUTOBGTRANSFERENABLED], a
 	call Delay3
 	call HandleMenuInput
 	bit 1, a
-	jp nz, Func_21588 ; b button
+	jp nz, ExitBillsPC ; b button
 	call PlaceUnfilledArrowMenuCursor
 	ld a, [wCurrentMenuItem]
-	ld [wccd3], a
+	ld [wParentMenuItem], a
 	and a
-	jp z, Func_21618 ; withdraw
+	jp z, BillsPCWithdraw ; withdraw
 	cp $1
-	jp z, Func_215ac ; deposit
+	jp z, BillsPCDeposit ; deposit
 	cp $2
-	jp z, Func_21673 ; release
+	jp z, BillsPCRelease ; release
 	cp $3
-	jp z, Func_216b3 ; change box
+	jp z, BillsPCChangeBox ; change box
 
-Func_21588: ; 21588 (8:5588)
+ExitBillsPC: ; 21588 (8:5588)
 	ld a, [wFlags_0xcd60]
-	bit 3, a
+	bit 3, a ; accessing Bill's PC through another PC?
-	jr nz, .asm_2159a
+	jr nz, .next
+; accessing it directly
 	call LoadTextBoxTilePatterns
 	ld a, $9a
 	call PlaySound
 	call WaitForSoundToFinish
-.asm_2159a
+.next
 	ld hl, wFlags_0xcd60
 	res 5, [hl]
 	call LoadScreenTilesFromBuffer2
@@ -205,26 +207,25 @@ Func_21588: ; 21588 (8:5588)
 	res 6, [hl]
 	ret
 
-Func_215ac: ; 215ac (8:55ac)
+BillsPCDeposit: ; 215ac (8:55ac)
-BillsPCDeposit:
 	ld a, [wPartyCount]
 	dec a
-	jr nz, .asm_215bb
+	jr nz, .partyLargeEnough
 	ld hl, CantDepositLastMonText
 	call PrintText
 	jp BillsPCMenu
-.asm_215bb
+.partyLargeEnough
 	ld a, [W_NUMINBOX]
 	cp MONS_PER_BOX
-	jr nz, .asm_215cb
+	jr nz, .boxNotFull
 	ld hl, BoxFullText
 	call PrintText
 	jp BillsPCMenu
-.asm_215cb
+.boxNotFull
 	ld hl, wPartyCount
-	call Func_216be
+	call DisplayMonListMenu
 	jp c, BillsPCMenu
-	call Func_2174b
+	call DisplayDepositWithdrawMenu
 	jp nc, BillsPCMenu
 	ld a, [wcf91]
 	call GetCryData
@@ -236,45 +237,45 @@ BillsPCDeposit:
 	ld [wRemoveMonFromBox], a
 	call RemovePokemon
 	call WaitForSoundToFinish
-	ld hl, wWhichTrade
+	ld hl, wBoxNumString
-	ld a, [wd5a0]
+	ld a, [wCurrentBoxNum]
 	and $7f
 	cp 9
-	jr c, .asm_2160a
+	jr c, .singleDigitBoxNum
 	sub 9
 	ld [hl], "1"
 	inc hl
 	add "0"
-	jr .asm_2160c
+	jr .next
-.asm_2160a
+.singleDigitBoxNum
 	add "1"
-.asm_2160c
+.next
 	ld [hli], a
 	ld [hl], $50
 	ld hl, MonWasStoredText
 	call PrintText
 	jp BillsPCMenu
 
-Func_21618: ; 21618 (8:5618)
+BillsPCWithdraw: ; 21618 (8:5618)
 	ld a, [W_NUMINBOX]
 	and a
-	jr nz, .asm_21627
+	jr nz, .boxNotEmpty
 	ld hl, NoMonText
 	call PrintText
-	jp Func_214e8
+	jp BillsPCMenu
-.asm_21627
+.boxNotEmpty
 	ld a, [wPartyCount]
 	cp PARTY_LENGTH
-	jr nz, .asm_21637
+	jr nz, .partyNotFull
 	ld hl, CantTakeMonText
 	call PrintText
-	jp Func_214e8
+	jp BillsPCMenu
-.asm_21637
+.partyNotFull
 	ld hl, W_NUMINBOX
-	call Func_216be
+	call DisplayMonListMenu
-	jp c, Func_214e8
+	jp c, BillsPCMenu
-	call Func_2174b
+	call DisplayDepositWithdrawMenu
-	jp nc, Func_214e8
+	jp nc, BillsPCMenu
 	ld a, [wWhichPokemon]
 	ld hl, wBoxMonNicks
 	call GetPartyMonName
@@ -290,25 +291,25 @@ Func_21618: ; 21618 (8:5618)
 	call WaitForSoundToFinish
 	ld hl, MonIsTakenOutText
 	call PrintText
-	jp Func_214e8
+	jp BillsPCMenu
 
-Func_21673: ; 21673 (8:5673)
+BillsPCRelease: ; 21673 (8:5673)
 	ld a, [W_NUMINBOX]
 	and a
-	jr nz, .asm_21682
+	jr nz, .loop
 	ld hl, NoMonText
 	call PrintText
-	jp Func_214e8
+	jp BillsPCMenu
-.asm_21682
+.loop
 	ld hl, W_NUMINBOX
-	call Func_216be
+	call DisplayMonListMenu
-	jp c, Func_214e8
+	jp c, BillsPCMenu
 	ld hl, OnceReleasedText
 	call PrintText
 	call YesNoChoice
 	ld a, [wCurrentMenuItem]
 	and a
-	jr nz, .asm_21682
+	jr nz, .loop
 	inc a
 	ld [wRemoveMonFromBox], a
 	call RemovePokemon
@@ -317,27 +318,27 @@ Func_21673: ; 21673 (8:5673)
 	call PlayCry
 	ld hl, MonWasReleasedText
 	call PrintText
-	jp Func_214e8
+	jp BillsPCMenu
 
-Func_216b3: ; 216b3 (8:56b3)
+BillsPCChangeBox: ; 216b3 (8:56b3)
 	callba ChangeBox
-	jp Func_214e8
+	jp BillsPCMenu
 
-Func_216be: ; 216be (8:56be)
+DisplayMonListMenu: ; 216be (8:56be)
 	ld a, l
-	ld [wList], a
+	ld [wListPointer], a
 	ld a, h
-	ld [wList + 1], a
+	ld [wListPointer + 1], a
 	xor a
 	ld [wPrintItemPrices], a
 	ld [wListMenuID], a
 	inc a                ; MONSTER_NAME
 	ld [wNameListType], a
-	ld a, [wcc2b]
+	ld a, [wPartyAndBillsPCSavedMenuItem]
 	ld [wCurrentMenuItem], a
 	call DisplayListMenuID
 	ld a, [wCurrentMenuItem]
-	ld [wcc2b], a
+	ld [wPartyAndBillsPCSavedMenuItem], a
 	ret
 
 BillsPCMenuText: ; 216e1 (8:56e1)
@@ -354,17 +355,19 @@ ENDC
 BoxNoPCText: ; 21713 (8:5713)
 	db "BOX No.@"
 
-Func_2171b:: ; 2171b (8:571b)
+KnowsHMMove:: ; 2171b (8:571b)
+; returns whether mon with party index [wWhichPokemon] knows an HM move
 	ld hl, wPartyMon1Moves
 	ld bc, wPartyMon2 - wPartyMon1
-	jr .asm_21729
+	jr .next
+; unreachable
 	ld hl, wBoxMon1Moves
 	ld bc, wBoxMon2 - wBoxMon1
-.asm_21729
+.next
 	ld a, [wWhichPokemon]
 	call AddNTimes
 	ld b, NUM_MOVES
-.asm_21731
+.loop
 	ld a, [hli]
 	push hl
 	push bc
@@ -375,7 +378,7 @@ Func_2171b:: ; 2171b (8:571b)
 	pop hl
 	ret c
 	dec b
-	jr nz, .asm_21731
+	jr nz, .loop
 	and a
 	ret
 
@@ -387,72 +390,72 @@ HMMoveArray: ; 21745 (8:5745)
 	db FLASH
 	db -1
 
-Func_2174b: ; 2174b (8:574b)
+DisplayDepositWithdrawMenu: ; 2174b (8:574b)
 	hlCoord 9, 10
-	ld b, $6
+	ld b, 6
-	ld c, $9
+	ld c, 9
 	call TextBoxBorder
-	ld a, [wccd3]
+	ld a, [wParentMenuItem]
-	and a
+	and a ; was the Deposit or Withdraw item selected in the parent menu?
 	ld de, DepositPCText
-	jr nz, .asm_21761
+	jr nz, .next
 	ld de, WithdrawPCText
-.asm_21761
+.next
 	hlCoord 11, 12
 	call PlaceString
 	hlCoord 11, 14
 	ld de, StatsCancelPCText
 	call PlaceString
 	ld hl, wTopMenuItemY
-	ld a, $c
+	ld a, 12
-	ld [hli], a
+	ld [hli], a ; wTopMenuItemY
-	ld a, $a
+	ld a, 10
-	ld [hli], a
+	ld [hli], a ; wTopMenuItemX
 	xor a
-	ld [hli], a
+	ld [hli], a ; wCurrentMenuItem
 	inc hl
-	ld a, $2
+	ld a, 2
-	ld [hli], a
+	ld [hli], a ; wMaxMenuItem
-	ld a, $3
+	ld a, A_BUTTON | B_BUTTON
-	ld [hli], a
+	ld [hli], a ; wMenuWatchedKeys
 	xor a
-	ld [hl], a
+	ld [hl], a ; wLastMenuItem
 	ld hl, wListScrollOffset
-	ld [hli], a
+	ld [hli], a ; wListScrollOffset
-	ld [hl], a
+	ld [hl], a ; wMenuWatchMovingOutOfBounds
 	ld [wPlayerMonNumber], a
-	ld [wcc2b], a
+	ld [wPartyAndBillsPCSavedMenuItem], a
-.asm_2178f
+.loop
 	call HandleMenuInput
-	bit 1, a
+	bit 1, a ; pressed B?
-	jr nz, .asm_2179f
+	jr nz, .exit
 	ld a, [wCurrentMenuItem]
 	and a
-	jr z, .asm_217a1
+	jr z, .choseDepositWithdraw
 	dec a
-	jr z, .asm_217a3
+	jr z, .viewStats
-.asm_2179f
+.exit
 	and a
 	ret
-.asm_217a1
+.choseDepositWithdraw
 	scf
 	ret
-.asm_217a3
+.viewStats
 	call SaveScreenTilesToBuffer1
-	ld a, [wccd3]
+	ld a, [wParentMenuItem]
 	and a
-	ld a, $0
+	ld a, PLAYER_PARTY_DATA
-	jr nz, .asm_217b0
+	jr nz, .next2
-	ld a, $2
+	ld a, BOX_DATA
-.asm_217b0
+.next2
-	ld [wcc49], a
+	ld [wMonDataLocation], a
 	predef StatusScreen
 	predef StatusScreen2
 	call LoadScreenTilesFromBuffer1
 	call ReloadTilesetTilePatterns
 	call GoPAL_SET_CF1C
 	call LoadGBPal
-	jr .asm_2178f
+	jr .loop
 
 DepositPCText:  db "DEPOSIT@"
 WithdrawPCText: db "WITHDRAW@"
@@ -518,9 +521,9 @@ CableClubLeftGameboy:: ; 5824 (8:5825)
 	ld a, [W_CURMAP]
 	cp BATTLE_CENTER
 	ld a, LINK_STATE_START_TRADE
-	jr z, .asm_2183a
+	jr z, .next
 	inc a ; LINK_STATE_START_BATTLE
-.asm_2183a
+.next
 	ld [wLinkState], a
 	call EnableAutoTextBoxDrawing
 	tx_pre_jump JustAMomentText
@@ -535,9 +538,9 @@ CableClubRightGameboy:: ; 5845 (8:5845)
 	ld a, [W_CURMAP]
 	cp BATTLE_CENTER
 	ld a, LINK_STATE_START_TRADE
-	jr z, .asm_2185a
+	jr z, .next
 	inc a ; LINK_STATE_START_BATTLE
-.asm_2185a
+.next
 	ld [wLinkState], a
 	call EnableAutoTextBoxDrawing
 	tx_pre_jump JustAMomentText

engine/menu/league_pc.asm

@@ -13,30 +13,32 @@ PKMNLeaguePC: ; 0x7657e
 	ld [W_SPRITEFLIPPED], a
 	ld [wUpdateSpritesEnabled], a
 	ld [wTrainerScreenX], a
-	ld [wcd42], a
+	ld [wHoFTeamNo], a
-	ld a, [wd5a2]
+	ld a, [wNumHoFTeams]
 	ld b, a
-	cp NUM_HOF_TEAMS + 1
+	cp HOF_TEAM_CAPACITY + 1
-	jr c, .first
+	jr c, .loop
-	ld b, NUM_HOF_TEAMS
+; If the total number of hall of fame teams is greater than the storage
+; capacity, then calculate the number of the first team that is still recorded.
+	ld b, HOF_TEAM_CAPACITY
 	sub b
-	ld [wcd42], a
+	ld [wHoFTeamNo], a
-.first
+.loop
-	ld hl, wcd42
+	ld hl, wHoFTeamNo
 	inc [hl]
 	push bc
 	ld a, [wTrainerScreenX]
-	ld [wWhichTrade], a
+	ld [wHoFMonSpecies], a
 	callba LoadHallOfFameTeams
-	call Func_765e5
+	call LeaguePCShowTeam
 	pop bc
-	jr c, .second
+	jr c, .doneShowingTeams
 	ld hl, wTrainerScreenX
 	inc [hl]
 	ld a, [hl]
 	cp b
-	jr nz, .first
+	jr nz, .loop
-.second
+.doneShowingTeams
 	pop af
 	ld [hTilesetType], a
 	pop af
@@ -48,11 +50,11 @@ PKMNLeaguePC: ; 0x7657e
 	call GoPAL_SET_CF1C
 	jp GBPalNormal
 
-Func_765e5: ; 765e5 (1d:65e5)
+LeaguePCShowTeam: ; 765e5 (1d:65e5)
 	ld c, PARTY_LENGTH
 .loop
 	push bc
-	call Func_76610
+	call LeaguePCShowMon
 	call WaitForTextScrollButtonPress
 	ld a, [hJoyHeld]
 	bit 1, a
@@ -75,18 +77,18 @@ Func_765e5: ; 765e5 (1d:65e5)
 	scf
 	ret
 
-Func_76610: ; 76610 (1d:6610)
+LeaguePCShowMon: ; 76610 (1d:6610)
 	call GBPalWhiteOutWithDelay3
 	call ClearScreen
 	ld hl, wHallOfFame
 	ld a, [hli]
-	ld [wWhichTrade], a
+	ld [wHoFMonSpecies], a
 	ld [wcf91], a
 	ld [wd0b5], a
 	ld [wBattleMonSpecies2], a
 	ld [wcf1d], a
 	ld a, [hli]
-	ld [wTrainerFacingDirection], a
+	ld [wHoFMonLevel], a
 	ld de, wcd6d
 	ld bc, $000B
 	call CopyData
@@ -105,11 +107,11 @@ Func_76610: ; 76610 (1d:6610)
 	ld de, HallOfFameNoText
 	call PlaceString
 	hlCoord 16, 15
-	ld de, wcd42
+	ld de, wHoFTeamNo
 	ld bc, $0103
 	call PrintNumber
-	ld b, BANK(Func_702f0)
+	ld b, BANK(HoFDisplayMonInfo)
-	ld hl, Func_702f0
+	ld hl, HoFDisplayMonInfo
 	jp Bankswitch
 
 HallOfFameNoText: ; 76670 (1d:6670)

engine/menu/main_menu.asm

@@ -16,7 +16,7 @@ MainMenu: ; 5af2 (1:5af2)
 	call DelayFrames
 	xor a ; LINK_STATE_NONE
 	ld [wLinkState],a
-	ld hl,wcc2b
+	ld hl,wPartyAndBillsPCSavedMenuItem
 	ld [hli],a
 	ld [hli],a
 	ld [hli],a
@@ -109,7 +109,7 @@ MainMenu: ; 5af2 (1:5af2)
 	ld [wd52a],a
 	ld c,10
 	call DelayFrames
-	ld a,[wd5a2]
+	ld a,[wNumHoFTeams]
 	and a
 	jp z,SpecialEnterMap
 	ld a,[W_CURMAP] ; map ID
@@ -124,14 +124,14 @@ MainMenu: ; 5af2 (1:5af2)
 
 Func_5bff: ; 5bff (1:5bff)
 	ld a,1
-	ld [wd358],a
+	ld [wLetterPrintingDelayFlags],a
 	ld a,3
 	ld [W_OPTIONS],a
 	ret
 
 LinkMenu: ; 5c0a (1:5c0a)
 	xor a
-	ld [wd358], a
+	ld [wLetterPrintingDelayFlags], a
 	ld hl, wd72e
 	set 6, [hl]
 	ld hl, TextTerminator_6b20
@@ -452,12 +452,12 @@ DisplayOptionMenu: ; 5e8a (1:5e8a)
 	ld [wCurrentMenuItem],a
 	ld [wLastMenuItem],a
 	inc a
-	ld [wd358],a
+	ld [wLetterPrintingDelayFlags],a
 	ld [wTrainerScreenY],a
 	ld a,3 ; text speed cursor Y coordinate
 	ld [wTopMenuItemY],a
 	call SetCursorPositionsFromOptions
-	ld a,[wWhichTrade] ; text speed cursor X coordinate
+	ld a,[wOptionsTextSpeedCursorX] ; text speed cursor X coordinate
 	ld [wTopMenuItemX],a
 	ld a,$01
 	ld [H_AUTOBGTRANSFERENABLED],a ; enable auto background transfer
@@ -507,7 +507,7 @@ DisplayOptionMenu: ; 5e8a (1:5e8a)
 .downPressed
 	cp a,16
 	ld b,-13
-	ld hl,wWhichTrade
+	ld hl,wOptionsTextSpeedCursorX
 	jr z,.updateMenuVariables
 	ld b,5
 	cp a,3
@@ -522,7 +522,7 @@ DisplayOptionMenu: ; 5e8a (1:5e8a)
 .upPressed
 	cp a,8
 	ld b,-5
-	ld hl,wWhichTrade
+	ld hl,wOptionsTextSpeedCursorX
 	jr z,.updateMenuVariables
 	cp a,13
 	inc hl
@@ -541,17 +541,17 @@ DisplayOptionMenu: ; 5e8a (1:5e8a)
 	call PlaceUnfilledArrowMenuCursor
 	jp .loop
 .cursorInBattleAnimation
-	ld a,[wTrainerEngageDistance] ; battle animation cursor X coordinate
+	ld a,[wOptionsBattleAnimCursorX] ; battle animation cursor X coordinate
 	xor a,$0b ; toggle between 1 and 10
-	ld [wTrainerEngageDistance],a
+	ld [wOptionsBattleAnimCursorX],a
 	jp .eraseOldMenuCursor
 .cursorInBattleStyle
-	ld a,[wTrainerFacingDirection] ; battle style cursor X coordinate
+	ld a,[wOptionsBattleStyleCursorX] ; battle style cursor X coordinate
 	xor a,$0b ; toggle between 1 and 10
-	ld [wTrainerFacingDirection],a
+	ld [wOptionsBattleStyleCursorX],a
 	jp .eraseOldMenuCursor
 .pressedLeftInTextSpeed
-	ld a,[wWhichTrade] ; text speed cursor X coordinate
+	ld a,[wOptionsTextSpeedCursorX] ; text speed cursor X coordinate
 	cp a,1
 	jr z,.updateTextSpeedXCoord
 	cp a,7
@@ -562,7 +562,7 @@ DisplayOptionMenu: ; 5e8a (1:5e8a)
 	sub a,7
 	jr .updateTextSpeedXCoord
 .pressedRightInTextSpeed
-	ld a,[wWhichTrade] ; text speed cursor X coordinate
+	ld a,[wOptionsTextSpeedCursorX] ; text speed cursor X coordinate
 	cp a,14
 	jr z,.updateTextSpeedXCoord
 	cp a,7
@@ -572,7 +572,7 @@ DisplayOptionMenu: ; 5e8a (1:5e8a)
 .fromFastToMedium
 	add a,6
 .updateTextSpeedXCoord
-	ld [wWhichTrade],a ; text speed cursor X coordinate
+	ld [wOptionsTextSpeedCursorX],a ; text speed cursor X coordinate
 	jp .eraseOldMenuCursor
 
 TextSpeedOptionText: ; 5fc0 (1:5fc0)
@@ -593,7 +593,7 @@ OptionMenuCancelText: ; 6018 (1:6018)
 ; sets the options variable according to the current placement of the menu cursors in the options menu
 SetOptionsFromCursorPositions: ; 601f (1:601f)
 	ld hl,TextSpeedOptionData
-	ld a,[wWhichTrade] ; text speed cursor X coordinate
+	ld a,[wOptionsTextSpeedCursorX] ; text speed cursor X coordinate
 	ld c,a
 .loop
 	ld a,[hli]
@@ -604,7 +604,7 @@ SetOptionsFromCursorPositions: ; 601f (1:601f)
 .textSpeedMatchFound
 	ld a,[hl]
 	ld d,a
-	ld a,[wTrainerEngageDistance] ; battle animation cursor X coordinate
+	ld a,[wOptionsBattleAnimCursorX] ; battle animation cursor X coordinate
 	dec a
 	jr z,.battleAnimationOn
 .battleAnimationOff
@@ -613,7 +613,7 @@ SetOptionsFromCursorPositions: ; 601f (1:601f)
 .battleAnimationOn
 	res 7,d
 .checkBattleStyle
-	ld a,[wTrainerFacingDirection] ; battle style cursor X coordinate
+	ld a,[wOptionsBattleStyleCursorX] ; battle style cursor X coordinate
 	dec a
 	jr z,.battleStyleShift
 .battleStyleSet
@@ -638,7 +638,7 @@ SetCursorPositionsFromOptions: ; 604c (1:604c)
 	pop bc
 	dec hl
 	ld a,[hl]
-	ld [wWhichTrade],a ; text speed cursor X coordinate
+	ld [wOptionsTextSpeedCursorX],a ; text speed cursor X coordinate
 	hlCoord 0, 3
 	call .placeUnfilledRightArrow
 	sla c
@@ -646,7 +646,7 @@ SetCursorPositionsFromOptions: ; 604c (1:604c)
 	jr nc,.storeBattleAnimationCursorX
 	ld a,10 ; Off
 .storeBattleAnimationCursorX
-	ld [wTrainerEngageDistance],a ; battle animation cursor X coordinate
+	ld [wOptionsBattleAnimCursorX],a ; battle animation cursor X coordinate
 	hlCoord 0, 8
 	call .placeUnfilledRightArrow
 	sla c
@@ -654,7 +654,7 @@ SetCursorPositionsFromOptions: ; 604c (1:604c)
 	jr nc,.storeBattleStyleCursorX
 	ld a,10
 .storeBattleStyleCursorX
-	ld [wTrainerFacingDirection],a ; battle style cursor X coordinate
+	ld [wOptionsBattleStyleCursorX],a ; battle style cursor X coordinate
 	hlCoord 0, 13
 	call .placeUnfilledRightArrow
 ; cursor in front of Cancel

engine/menu/party_menu.asm

@@ -227,7 +227,7 @@ RedrawPartyMenu_: ; 12ce3 (4:6ce3)
 	ld h,[hl]
 	ld l,a
 	push hl
-	ld a,[wcf06]
+	ld a,[wUsedItemOnWhichPokemon]
 	ld hl,wPartyMonNicks
 	call GetPartyMonName
 	pop hl

engine/menu/pc.asm

@@ -10,7 +10,7 @@ ActivatePC: ; 17e2c (5:7e2c)
 	call LoadScreenTilesFromBuffer2
 	call Delay3
 PCMainMenu: ; 17e48 (5:7e48)
-	callba Func_213c8
+	callba DisplayPCMainMenu
 	ld hl, wFlags_0xcd60
 	set 5, [hl]
 	call HandleMenuInput

engine/menu/players_pc.asm

@@ -5,18 +5,19 @@ PlayerPC: ; 78e6 (1:78e6)
 	ld [wNameListType], a
 	call SaveScreenTilesToBuffer1
 	xor a
-	ld [wcc2c], a
+	ld [wBagSavedMenuItem], a
-	ld [wccd3], a
+	ld [wParentMenuItem], a
 	ld a, [wFlags_0xcd60]
-	bit 3, a
+	bit 3, a ; accessing player's PC through another PC?
-	jr nz, Func_790c
+	jr nz, PlayerPCMenu
+; accessing it directly
 	ld a, (SFX_02_45 - SFX_Headers_02) / 3
 	call PlaySound
 	ld hl, TurnedOnPC2Text
 	call PrintText
 
-Func_790c: ; 790c (1:790c)
+PlayerPCMenu: ; 790c (1:790c)
-	ld a, [wccd3]
+	ld a, [wParentMenuItem]
 	ld [wCurrentMenuItem], a
 	ld hl, wFlags_0xcd60
 	set 5, [hl]
@@ -30,101 +31,102 @@ Func_790c: ; 790c (1:790c)
 	ld de, PlayersPCMenuEntries
 	call PlaceString
 	ld hl, wTopMenuItemY
-	ld a, $2
+	ld a, 2
-	ld [hli], a
+	ld [hli], a ; wTopMenuItemY
 	dec a
-	ld [hli], a
+	ld [hli], a ; wTopMenuItemX
 	inc hl
 	inc hl
-	ld a, $3
+	ld a, 3
-	ld [hli], a
+	ld [hli], a ; wMaxMenuItem
-	ld a, $3
+	ld a, A_BUTTON | B_BUTTON
-	ld [hli], a
+	ld [hli], a ; wMenuWatchedKeys
 	xor a
 	ld [hl], a
 	ld hl, wListScrollOffset
-	ld [hli], a
+	ld [hli], a ; wListScrollOffset
-	ld [hl], a
+	ld [hl], a ; wMenuWatchMovingOutOfBounds
 	ld [wPlayerMonNumber], a
 	ld hl, WhatDoYouWantText
 	call PrintText
 	call HandleMenuInput
 	bit 1, a
-	jp nz, Func_796d
+	jp nz, ExitPlayerPC
 	call PlaceUnfilledArrowMenuCursor
 	ld a, [wCurrentMenuItem]
-	ld [wccd3], a
+	ld [wParentMenuItem], a
 	and a
-	jp z, Func_7a12
+	jp z, PlayerPCWithdraw
 	dec a
-	jp z, Func_7995
+	jp z, PlayerPCDeposit
 	dec a
-	jp z, Func_7a8f
+	jp z, PlayerPCToss
 
-Func_796d: ; 796d (1:796d)
+ExitPlayerPC: ; 796d (1:796d)
 	ld a, [wFlags_0xcd60]
-	bit 3, a
+	bit 3, a ; accessing player's PC through another PC?
-	jr nz, .asm_797c
+	jr nz, .next
+; accessing it directly
 	ld a, (SFX_02_46 - SFX_Headers_02) / 3
 	call PlaySound
 	call WaitForSoundToFinish
-.asm_797c
+.next
 	ld hl, wFlags_0xcd60
 	res 5, [hl]
 	call LoadScreenTilesFromBuffer2
 	xor a
 	ld [wListScrollOffset], a
-	ld [wcc2c], a
+	ld [wBagSavedMenuItem], a
 	ld hl, wd730
 	res 6, [hl]
 	xor a
 	ld [wDoNotWaitForButtonPressAfterDisplayingText], a
 	ret
 
-Func_7995: ; 7995 (1:7995)
+PlayerPCDeposit: ; 7995 (1:7995)
 	xor a
 	ld [wCurrentMenuItem], a
 	ld [wListScrollOffset], a
 	ld a, [wNumBagItems]
 	and a
-	jr nz, Func_79ab
+	jr nz, .loop
 	ld hl, NothingToDepositText
 	call PrintText
-	jp Func_790c
+	jp PlayerPCMenu
-
+.loop
-Func_79ab: ; 79ab (1:79ab)
 	ld hl, WhatToDepositText
 	call PrintText
 	ld hl, wNumBagItems
 	ld a, l
-	ld [wList], a
+	ld [wListPointer], a
 	ld a, h
-	ld [wList + 1], a
+	ld [wListPointer + 1], a
 	xor a
 	ld [wPrintItemPrices], a
-	ld a, $3
+	ld a, ITEMLISTMENU
 	ld [wListMenuID], a
 	call DisplayListMenuID
-	jp c, Func_790c
+	jp c, PlayerPCMenu
 	call IsKeyItem
-	ld a, $1
+	ld a, 1
 	ld [wItemQuantity], a
 	ld a, [wIsKeyItem]
 	and a
-	jr nz, .asm_79e7
+	jr nz, .next
+; if it's not a key item, there can be more than one of the item
 	ld hl, DepositHowManyText
 	call PrintText
 	call DisplayChooseQuantityMenu
 	cp $ff
-	jp z, Func_79ab
+	jp z, .loop
-.asm_79e7
+.next
 	ld hl, wNumBoxItems
 	call AddItemToInventory
-	jr c, .asm_79f8
+	jr c, .roomAvailable
 	ld hl, NoRoomToStoreText
 	call PrintText
-	jp Func_79ab
+	jp .loop
-.asm_79f8
+.roomAvailable
 	ld hl, wNumBagItems
 	call RemoveItemFromInventory
 	call WaitForSoundToFinish
@@ -133,52 +135,52 @@ Func_79ab: ; 79ab (1:79ab)
 	call WaitForSoundToFinish
 	ld hl, ItemWasStoredText
 	call PrintText
-	jp Func_79ab
+	jp .loop
 
-Func_7a12: ; 7a12 (1:7a12)
+PlayerPCWithdraw: ; 7a12 (1:7a12)
 	xor a
 	ld [wCurrentMenuItem], a
 	ld [wListScrollOffset], a
 	ld a, [wNumBoxItems]
 	and a
-	jr nz, Func_7a28
+	jr nz, .loop
 	ld hl, NothingStoredText
 	call PrintText
-	jp Func_790c
+	jp PlayerPCMenu
-
+.loop
-Func_7a28: ; 7a28 (1:7a28)
 	ld hl, WhatToWithdrawText
 	call PrintText
 	ld hl, wNumBoxItems
 	ld a, l
-	ld [wList], a
+	ld [wListPointer], a
 	ld a, h
-	ld [wList + 1], a
+	ld [wListPointer + 1], a
 	xor a
 	ld [wPrintItemPrices], a
-	ld a, $3
+	ld a, ITEMLISTMENU
 	ld [wListMenuID], a
 	call DisplayListMenuID
-	jp c, Func_790c
+	jp c, PlayerPCMenu
 	call IsKeyItem
-	ld a, $1
+	ld a, 1
 	ld [wItemQuantity], a
 	ld a, [wIsKeyItem]
 	and a
-	jr nz, .asm_7a64
+	jr nz, .next
+; if it's not a key item, there can be more than one of the item
 	ld hl, WithdrawHowManyText
 	call PrintText
 	call DisplayChooseQuantityMenu
 	cp $ff
-	jp z, Func_7a28
+	jp z, .loop
-.asm_7a64
+.next
 	ld hl, wNumBagItems
 	call AddItemToInventory
-	jr c, .asm_7a75
+	jr c, .roomAvailable
 	ld hl, CantCarryMoreText
 	call PrintText
-	jp Func_7a28
+	jp .loop
-.asm_7a75
+.roomAvailable
 	ld hl, wNumBoxItems
 	call RemoveItemFromInventory
 	call WaitForSoundToFinish
@@ -187,56 +189,56 @@ Func_7a28: ; 7a28 (1:7a28)
 	call WaitForSoundToFinish
 	ld hl, WithdrewItemText
 	call PrintText
-	jp Func_7a28
+	jp .loop
 
-Func_7a8f: ; 7a8f (1:7a8f)
+PlayerPCToss: ; 7a8f (1:7a8f)
 	xor a
 	ld [wCurrentMenuItem], a
 	ld [wListScrollOffset], a
 	ld a, [wNumBoxItems]
 	and a
-	jr nz, Func_7aa5
+	jr nz, .loop
 	ld hl, NothingStoredText
 	call PrintText
-	jp Func_790c
+	jp PlayerPCMenu
-
+.loop
-Func_7aa5: ; 7aa5 (1:7aa5)
 	ld hl, WhatToTossText
 	call PrintText
 	ld hl, wNumBoxItems
 	ld a, l
-	ld [wList], a
+	ld [wListPointer], a
 	ld a, h
-	ld [wList + 1], a
+	ld [wListPointer + 1], a
 	xor a
 	ld [wPrintItemPrices], a
-	ld a, $3
+	ld a, ITEMLISTMENU
 	ld [wListMenuID], a
 	push hl
 	call DisplayListMenuID
 	pop hl
-	jp c, Func_790c
+	jp c, PlayerPCMenu
 	push hl
 	call IsKeyItem
 	pop hl
-	ld a, $1
+	ld a, 1
 	ld [wItemQuantity], a
 	ld a, [wIsKeyItem]
 	and a
-	jr nz, .asm_7aef
+	jr nz, .next
 	ld a, [wcf91]
 	call IsItemHM
-	jr c, .asm_7aef
+	jr c, .next
+; if it's not a key item, there can be more than one of the item
 	push hl
 	ld hl, TossHowManyText
 	call PrintText
 	call DisplayChooseQuantityMenu
 	pop hl
 	cp $ff
-	jp z, Func_7aa5
+	jp z, .loop
-.asm_7aef
+.next
-	call TossItem
+	call TossItem ; disallows tossing key items
-	jp Func_7aa5
+	jp .loop
 
 PlayersPCMenuEntries: ; 7af5 (1:7af5)
 	db   "WITHDRAW ITEM"

engine/menu/start_menu.asm

@@ -54,7 +54,7 @@ RedisplayStartMenu:: ; 2adf (0:2adf)
 .buttonPressed ; A, B, or Start button pressed
 	call PlaceUnfilledArrowMenuCursor
 	ld a,[wCurrentMenuItem]
-	ld [wcc2d],a ; save current menu item ID
+	ld [wBattleAndStartSavedMenuItem],a ; save current menu selection
 	ld a,b
 	and a,%00001010 ; was the Start button or B button pressed?
 	jp nz,CloseStartMenu

engine/menu/start_sub_menus.asm

@@ -33,14 +33,14 @@ StartMenu_Pokemon: ; 130a9 (4:70a9)
 	ld a,FIELD_MOVE_MON_MENU
 	ld [wTextBoxID],a
 	call DisplayTextBoxID ; display pokemon menu options
-	ld hl,wWhichTrade
+	ld hl,wFieldMoves
 	ld bc,$020c ; max menu item ID, top menu item Y
 	ld e,5
 .adjustMenuVariablesLoop
 	dec e
 	jr z,.storeMenuVariables
 	ld a,[hli]
-	and a
+	and a ; end of field moves?
 	jr z,.storeMenuVariables
 	inc b
 	dec c
@@ -50,7 +50,7 @@ StartMenu_Pokemon: ; 130a9 (4:70a9)
 	ld hl,wTopMenuItemY
 	ld a,c
 	ld [hli],a ; top menu item Y
-	ld a,[$fff7]
+	ld a,[hFieldMoveMonMenuTopMenuItemX]
 	ld [hli],a ; top menu item X
 	xor a
 	ld [hli],a ; current menu item ID
@@ -81,22 +81,22 @@ StartMenu_Pokemon: ; 130a9 (4:70a9)
 	jp z,.choseStats
 	ld c,a
 	ld b,0
-	ld hl,wWhichTrade
+	ld hl,wFieldMoves
 	add hl,bc
 	jp .choseOutOfBattleMove
 .choseSwitch
 	ld a,[wPartyCount]
 	cp a,2 ; is there more than one pokemon in the party?
 	jp c,StartMenu_Pokemon ; if not, no switching
-	call SwitchPartyMon_Stats
+	call SwitchPartyMon_InitVarOrSwapData ; init [wMenuItemToSwap]
 	ld a,SWAP_MONS_PARTY_MENU
 	ld [wPartyMenuTypeOrMessageID],a
 	call GoBackToPartyMenu
 	jp .checkIfPokemonChosen
 .choseStats
 	call ClearSprites
-	xor a
+	xor a ; PLAYER_PARTY_DATA
-	ld [wcc49],a
+	ld [wMonDataLocation],a
 	predef StatusScreen
 	predef StatusScreen2
 	call ReloadMapData
@@ -153,7 +153,7 @@ StartMenu_Pokemon: ; 130a9 (4:70a9)
 	bit 1,a ; does the player have the Cascade Badge?
 	jp z,.newBadgeRequired
 	predef UsedCut
-	ld a,[wcd6a]
+	ld a,[wActionResultOrTookBattleTurn]
 	and a
 	jp z,.loop
 	jp CloseTextDisplay
@@ -169,7 +169,7 @@ StartMenu_Pokemon: ; 130a9 (4:70a9)
 	ld [wcf91],a
 	ld [wd152],a
 	call UseItem
-	ld a,[wcd6a]
+	ld a,[wActionResultOrTookBattleTurn]
 	and a
 	jp z,.loop
 	call GBPalWhiteOutWithDelay3
@@ -197,7 +197,7 @@ StartMenu_Pokemon: ; 130a9 (4:70a9)
 	ld [wcf91],a
 	ld [wd152],a
 	call UseItem
-	ld a,[wcd6a]
+	ld a,[wActionResultOrTookBattleTurn]
 	and a
 	jp z,.loop
 	call GBPalWhiteOutWithDelay3
@@ -256,14 +256,14 @@ StartMenu_Pokemon: ; 130a9 (4:70a9)
 	ld a,[H_QUOTIENT + 2]
 	sbc b
 	jp nc,.notHealthyEnough
-	ld a,[wcc2b]
+	ld a,[wPartyAndBillsPCSavedMenuItem]
 	push af
 	ld a,POTION
 	ld [wcf91],a
 	ld [wd152],a
 	call UseItem
 	pop af
-	ld [wcc2b],a
+	ld [wPartyAndBillsPCSavedMenuItem],a
 	jp .loop
 .notHealthyEnough ; if current HP is less than 1/5 of max HP
 	ld hl,.notHealthyEnoughText
@@ -308,19 +308,19 @@ StartMenu_Item: ; 13302 (4:7302)
 	jr .exitMenu
 .notInCableClubRoom
 	ld bc,wNumBagItems
-	ld hl,wList
+	ld hl,wListPointer
 	ld a,c
 	ld [hli],a
-	ld [hl],b ; store item bag pointer at wList (for DisplayListMenuID)
+	ld [hl],b ; store item bag pointer in wListPointer (for DisplayListMenuID)
 	xor a
 	ld [wPrintItemPrices],a
 	ld a,ITEMLISTMENU
 	ld [wListMenuID],a
-	ld a,[wcc2c]
+	ld a,[wBagSavedMenuItem]
 	ld [wCurrentMenuItem],a
 	call DisplayListMenuID
 	ld a,[wCurrentMenuItem]
-	ld [wcc2c],a
+	ld [wBagSavedMenuItem],a
 	jr nc,.choseItem
 .exitMenu
 	call LoadScreenTilesFromBuffer2 ; restore saved screen
@@ -401,7 +401,7 @@ StartMenu_Item: ; 13302 (4:7302)
 	xor a
 	ld [wd152],a
 	call UseItem
-	ld a,[wcd6a]
+	ld a,[wActionResultOrTookBattleTurn]
 	and a
 	jp z,ItemMenuLoop
 	jp CloseStartMenu
@@ -409,7 +409,7 @@ StartMenu_Item: ; 13302 (4:7302)
 	ld a,[wUpdateSpritesEnabled]
 	push af
 	call UseItem
-	ld a,[wcd6a]
+	ld a,[wActionResultOrTookBattleTurn]
 	cp a,$02
 	jp z,.partyMenuNotDisplayed
 	call GBPalWhiteOutWithDelay3
@@ -566,7 +566,7 @@ DrawTrainerInfo: ; 1349a (4:749a)
 	ld de,vChars1 + $570
 	call TrainerInfo_FarCopyData
 	call EnableLCD
-	ld hl,wWhichTrade
+	ld hl,wTrainerInfoTextBoxWidthPlus1
 	ld a,18 + 1
 	ld [hli],a
 	dec a
@@ -574,7 +574,7 @@ DrawTrainerInfo: ; 1349a (4:749a)
 	ld [hl],1
 	hlCoord 0, 0
 	call TrainerInfo_DrawTextBox
-	ld hl,wWhichTrade
+	ld hl,wTrainerInfoTextBoxWidthPlus1
 	ld a,16 + 1
 	ld [hli],a
 	dec a
@@ -627,15 +627,15 @@ TrainerInfo_BadgesText: ; 13597 (4:7597)
 ; height is always 6
 ; INPUT:
 ; hl = destination address
-; [wWhichTrade] = width + 1
+; [wTrainerInfoTextBoxWidthPlus1] = width
-; [wTrainerEngageDistance] = width
+; [wTrainerInfoTextBoxWidth] = width - 1
-; [wTrainerFacingDirection] = distance from the end of a text box row to the start of the next
+; [wTrainerInfoTextBoxNextRowOffset] = distance from the end of a text box row to the start of the next
 TrainerInfo_DrawTextBox: ; 135a0 (4:75a0)
 	ld a,$79 ; upper left corner tile ID
 	ld de,$7a7b ; top edge and upper right corner tile ID's
 	call TrainerInfo_DrawHorizontalEdge ; draw top edge
 	call TrainerInfo_NextTextBoxRow
-	ld a,[wWhichTrade] ; width of the text box plus one
+	ld a,[wTrainerInfoTextBoxWidthPlus1]
 	ld e,a
 	ld d,0
 	ld c,6 ; height of the text box
@@ -651,7 +651,7 @@ TrainerInfo_DrawTextBox: ; 135a0 (4:75a0)
 
 TrainerInfo_DrawHorizontalEdge: ; 135c3 (4:75c3)
 	ld [hli],a ; place left corner tile
-	ld a,[wTrainerEngageDistance] ; width of the text box
+	ld a,[wTrainerInfoTextBoxWidth]
 	ld c,a
 	ld a,d
 .loop
@@ -663,7 +663,7 @@ TrainerInfo_DrawHorizontalEdge: ; 135c3 (4:75c3)
 	ret
 
 TrainerInfo_NextTextBoxRow: ; 135d0 (4:75d0)
-	ld a,[wTrainerFacingDirection] ; distance to the start of the next row
+	ld a,[wTrainerInfoTextBoxNextRowOffset] ; distance to the start of the next row
 .loop
 	inc hl
 	dec a
@@ -704,62 +704,65 @@ StartMenu_Option: ; 135f6 (4:75f6)
 	jp RedisplayStartMenu
 
 SwitchPartyMon: ; 13613 (4:7613)
-	call SwitchPartyMon_Stats
+	call SwitchPartyMon_InitVarOrSwapData ; swap data
-	ld a, [wWhichTrade]
+	ld a, [wSwappedMenuItem]
-	call SwitchPartyMon_OAM
+	call SwitchPartyMon_ClearGfx
 	ld a, [wCurrentMenuItem]
-	call SwitchPartyMon_OAM
+	call SwitchPartyMon_ClearGfx
 	jp RedrawPartyMenu_
 
-SwitchPartyMon_OAM: ; 13625 (4:7625)
+SwitchPartyMon_ClearGfx: ; 13625 (4:7625)
 	push af
 	hlCoord 0, 0
 	ld bc, SCREEN_WIDTH * 2
 	call AddNTimes
 	ld c, SCREEN_WIDTH * 2
 	ld a, " "
-.asm_13633
+.clearMonBGLoop ; clear the mon's row in the party menu
 	ld [hli], a
 	dec c
-	jr nz, .asm_13633
+	jr nz, .clearMonBGLoop
 	pop af
 	ld hl, wOAMBuffer
 	ld bc, $10
 	call AddNTimes
 	ld de, $4
 	ld c, e
-.asm_13645
+.clearMonOAMLoop
 	ld [hl], $a0
 	add hl, de
 	dec c
-	jr nz, .asm_13645
+	jr nz, .clearMonOAMLoop
 	call WaitForSoundToFinish
 	ld a, (SFX_02_58 - SFX_Headers_02) / 3
 	jp PlaySound
 
-SwitchPartyMon_Stats: ; 13653 (4:7653)
+SwitchPartyMon_InitVarOrSwapData: ; 13653 (4:7653)
+; This is used to initialise [wMenuItemToSwap] and to actually swap the data.
 	ld a, [wMenuItemToSwap]
-	and a
+	and a ; has [wMenuItemToSwap] been initialised yet?
-	jr nz, .asm_13661
+	jr nz, .pickedMonsToSwap
+; If not, initialise [wMenuItemToSwap] so that it matches the current mon.
 	ld a, [wWhichPokemon]
-	inc a
+	inc a ; [wMenuItemToSwap] counts from 1
 	ld [wMenuItemToSwap], a
 	ret
-.asm_13661
+.pickedMonsToSwap
 	xor a
 	ld [wPartyMenuTypeOrMessageID], a
 	ld a, [wMenuItemToSwap]
 	dec a
 	ld b, a
 	ld a, [wCurrentMenuItem]
-	ld [wWhichTrade], a
+	ld [wSwappedMenuItem], a
-	cp b
+	cp b ; swapping a mon with itself?
-	jr nz, .asm_1367b
+	jr nz, .swappingDifferentMons
+; can't swap a mon with itself
 	xor a
 	ld [wMenuItemToSwap], a
 	ld [wPartyMenuTypeOrMessageID], a
 	ret
-.asm_1367b
+.swappingDifferentMons
 	ld a, b
 	ld [wMenuItemToSwap], a
 	push hl
@@ -770,20 +773,20 @@ SwitchPartyMon_Stats: ; 13653 (4:7653)
 	ld a, [wCurrentMenuItem]
 	add l
 	ld l, a
-	jr nc, .asm_1368e
+	jr nc, .noCarry
 	inc h
-.asm_1368e
+.noCarry
 	ld a, [wMenuItemToSwap]
 	add e
 	ld e, a
-	jr nc, .asm_13696
+	jr nc, .noCarry2
 	inc d
-.asm_13696
+.noCarry2
 	ld a, [hl]
-	ld [H_DIVIDEND], a ; (aliases: H_PRODUCT, H_PASTLEADINGZEROES, H_QUOTIENT)
+	ld [hSwapTemp], a
 	ld a, [de]
 	ld [hl], a
-	ld a, [H_DIVIDEND] ; (aliases: H_PRODUCT, H_PASTLEADINGZEROES, H_QUOTIENT)
+	ld a, [hSwapTemp]
 	ld [de], a
 	ld hl, wPartyMons
 	ld bc, wPartyMon2 - wPartyMon1
@@ -791,19 +794,19 @@ SwitchPartyMon_Stats: ; 13653 (4:7653)
 	call AddNTimes
 	push hl
 	ld de, wSwitchPartyMonTempBuffer
-	ld bc, $2c
+	ld bc, wPartyMon2 - wPartyMon1
 	call CopyData
 	ld hl, wPartyMons
-	ld bc, $2c
+	ld bc, wPartyMon2 - wPartyMon1
 	ld a, [wMenuItemToSwap]
 	call AddNTimes
 	pop de
 	push hl
-	ld bc, $2c
+	ld bc, wPartyMon2 - wPartyMon1
 	call CopyData
 	pop de
 	ld hl, wSwitchPartyMonTempBuffer
-	ld bc, $2c
+	ld bc, wPartyMon2 - wPartyMon1
 	call CopyData
 	ld hl, wPartyMonOT
 	ld a, [wCurrentMenuItem]
@@ -842,7 +845,7 @@ SwitchPartyMon_Stats: ; 13653 (4:7653)
 	ld bc, $b
 	call CopyData
 	ld a, [wMenuItemToSwap]
-	ld [wWhichTrade], a
+	ld [wSwappedMenuItem], a
 	xor a
 	ld [wMenuItemToSwap], a
 	ld [wPartyMenuTypeOrMessageID], a

engine/menu/status_screen.asm

@@ -65,9 +65,10 @@ DrawHP_: ; 128fb (4:68fb)
 ; Predef 0x37
 StatusScreen: ; 12953 (4:6953)
 	call LoadMonData
-	ld a, [wcc49]
+	ld a, [wMonDataLocation]
-	cp $2 ; 2 means we're in a PC box
+	cp BOX_DATA
 	jr c, .DontRecalculate
+; mon is in a box or daycare
 	ld a, [wLoadedMonBoxLevel]
 	ld [wLoadedMonLevel], a
 	ld [W_CURENEMYLVL], a
@@ -148,13 +149,13 @@ StatusScreen: ; 12953 (4:6953)
 	hlCoord 11, 10
 	predef PrintMonType
 	ld hl, NamePointers2
-	call .asm_12a7e
+	call .GetStringPointer
 	ld d, h
 	ld e, l
 	hlCoord 9, 1
 	call PlaceString ; Pokémon name
 	ld hl, OTPointers
-	call .asm_12a7e
+	call .GetStringPointer
 	ld d, h
 	ld e, l
 	hlCoord 12, 16
@@ -175,17 +176,18 @@ StatusScreen: ; 12953 (4:6953)
 	pop af
 	ld [hTilesetType], a
 	ret
-.asm_12a7e ;  I don't know what this does, iterates over pointers?
+
-	ld a, [wcc49]
+.GetStringPointer
+	ld a, [wMonDataLocation]
 	add a
 	ld c, a
-	ld b, $0
+	ld b, 0
 	add hl, bc
 	ld a, [hli]
 	ld h, [hl]
 	ld l, a
-	ld a, [wcc49]
+	ld a, [wMonDataLocation]
-	cp $3
+	cp DAYCARE_DATA
 	ret z
 	ld a, [wWhichPokemon]
 	jp SkipFixedLengthTextEntries
@@ -316,7 +318,7 @@ StatusScreen2: ; 12b57 (4:6b57)
 	hlCoord 2, 9
 	ld de, wMovesString
 	call PlaceString ; Print moves
-	ld a, [wcd6c]
+	ld a, [wNumMovesMinusOne]
 	inc a
 	ld c, a
 	ld a, $4
@@ -335,7 +337,7 @@ StatusScreen2: ; 12b57 (4:6b57)
 .InitPP ; 12bbb
 	ld hl, wLoadedMonMoves
 	deCoord 14, 10
-	ld b, $0
+	ld b, 0
 .PrintPP ; 12bc3
 	ld a, [hli]
 	and a
@@ -356,15 +358,15 @@ StatusScreen2: ; 12b57 (4:6b57)
 	pop de
 	pop hl
 	push hl
-	ld bc, $0014
+	ld bc, wPartyMon1PP - wPartyMon1Moves - 1
 	add hl, bc
 	ld a, [hl]
 	and $3f
-	ld [wcd71], a
+	ld [wStatusScreenCurrentPP], a
 	ld h, d
 	ld l, e
 	push hl
-	ld de, wcd71
+	ld de, wStatusScreenCurrentPP
 	ld bc, $0102
 	call PrintNumber
 	ld a, "/"

engine/oak_speech.asm

@@ -1,5 +1,5 @@
 SetDefaultNames: ; 60ca (1:60ca)
-	ld a, [wd358]
+	ld a, [wLetterPrintingDelayFlags]
 	push af
 	ld a, [W_OPTIONS]
 	push af
@@ -18,7 +18,7 @@ SetDefaultNames: ; 60ca (1:60ca)
 	pop af
 	ld [W_OPTIONS], a
 	pop af
-	ld [wd358], a
+	ld [wLetterPrintingDelayFlags], a
 	ld a, [wd08a]
 	and a
 	call z, Func_5bff
@@ -193,18 +193,18 @@ IntroFadePalettes: ; 6282 (1:6282)
 
 MovePicLeft: ; 6288 (1:6288)
 	ld a,119
-	ld [$FF4B],a
+	ld [rWX],a
 	call DelayFrame
 
 	ld a,$E4
 	ld [rBGP],a
 .next
 	call DelayFrame
-	ld a,[$FF4B]
+	ld a,[rWX]
 	sub 8
 	cp $FF
 	ret z
-	ld [$FF4B],a
+	ld [rWX],a
 	jr .next
 
 Predef3B: ; 62a1 (1:62a1)

engine/overworld/cut.asm

@@ -1,6 +1,6 @@
 UsedCut: ; ef54 (3:6f54)
 	xor a
-	ld [wcd6a], a
+	ld [wActionResultOrTookBattleTurn], a ; initialise to failure value
 	ld a, [W_CURMAPTILESET]
 	and a ; OVERWORLD
 	jr z, .asm_ef6b
@@ -26,9 +26,9 @@ UsedCut: ; ef54 (3:6f54)
 	db "@"
 
 .asm_ef82
-	ld [wcd4d], a
+	ld [wCutTile], a
 	ld a, $1
-	ld [wcd6a], a
+	ld [wActionResultOrTookBattleTurn], a ; used cut
 	ld a, [wWhichPokemon]
 	ld hl, wPartyMonNicks
 	call GetPartyMonName
@@ -73,10 +73,10 @@ UsedCutText: ; eff2 (3:6ff2)
 
 AnimateCutTree: ; eff7 (3:6ff7)
 	xor a
-	ld [wcd50], a
+	ld [wWhichAnimationOffsets], a
 	ld a, $e4
 	ld [rOBP1], a
-	ld a, [wcd4d]
+	ld a, [wCutTile]
 	cp $52
 	jr z, .asm_f020
 	ld de, Overworld_GFX + $2d0 ; cuttable tree sprite top row
@@ -138,7 +138,7 @@ GetCutTreeBoulderDustAnimationOffsets: ; f068 (3:7068)
 	srl a
 	ld e, a
 	ld d, $0 ; de holds direction (00: down, 02: up, 04: left, 06: right)
-	ld a, [wcd50]
+	ld a, [wWhichAnimationOffsets]
 	and a
 	ld hl, CutTreeAnimationOffsets
 	jr z, .asm_f084

engine/overworld/cut2.asm

@@ -1,5 +1,5 @@
 Func_79e96: ; 79e96 (1e:5e96)
-	ld a, [wcd4d]
+	ld a, [wCutTile]
 	cp $52
 	jr z, .asm_79ec8
 	ld c, $8

engine/overworld/emotion_bubbles.asm

@@ -1,7 +1,7 @@
 EmotionBubble: ; 17c47 (5:7c47)
-	ld a, [wcd50]
+	ld a, [wWhichEmotionBubble]
 	ld c, a
-	ld b, $0
+	ld b, 0
 	ld hl, EmotionBubblesPointerTable
 	add hl, bc
 	add hl, bc
@@ -16,15 +16,18 @@ EmotionBubble: ; 17c47 (5:7c47)
 	ld a, $ff
 	ld [wUpdateSpritesEnabled], a
 	ld a, [wd736]
-	bit 6, a
+	bit 6, a ; are the last 4 OAM entries reserved for a shadow or fishing rod?
 	ld hl, wOAMBuffer + $8f
 	ld de, wOAMBuffer + $9f
-	jr z, .asm_17c7a
+	jr z, .next
 	ld hl, wOAMBuffer + $7f
 	ld de, wOAMBuffer + $8f
-.asm_17c7a
+
+; Copy OAM data 16 bytes forward to make room for emotion bubble OAM data at the
+; start of the OAM buffer.
+.next
 	ld bc, $90
-.asm_17c7d
+.loop
 	ld a, [hl]
 	ld [de], a
 	dec hl
@@ -32,12 +35,14 @@ EmotionBubble: ; 17c47 (5:7c47)
 	dec bc
 	ld a, c
 	or b
-	jr nz, .asm_17c7d
+	jr nz, .loop
+
+; get the screen coordinates of the sprite the bubble is to be displayed above
 	ld hl, wSpriteStateData1 + 4
-	ld a, [wcd4f]
+	ld a, [wEmotionBubbleSpriteIndex]
 	swap a
 	ld c, a
-	ld b, $0
+	ld b, 0
 	add hl, bc
 	ld a, [hli]
 	ld b, a
@@ -45,6 +50,7 @@ EmotionBubble: ; 17c47 (5:7c47)
 	ld a, [hl]
 	add $8
 	ld c, a
+
 	ld de, EmotionBubblesOAM
 	xor a
 	call WriteOAMBlock

engine/overworld/movement.asm

@@ -12,7 +12,7 @@ UpdatePlayerSprite: ; 4e31 (1:4e31)
 ; the maximum number for map tiles
 .checkIfTextBoxInFrontOfSprite
 	aCoord 8, 9
-	ld [$ff93], a
+	ld [hTilePlayerStandingOn], a
 	cp $60
 	jr c, .lowerLeftTileIsMapTile
 .disableSprite
@@ -21,52 +21,54 @@ UpdatePlayerSprite: ; 4e31 (1:4e31)
 	ret
 .lowerLeftTileIsMapTile
 	call DetectCollisionBetweenSprites
-	ld h, $c1
+	ld h, wSpriteStateData1 / $100
 	ld a, [wWalkCounter]
 	and a
-	jr nz, .asm_4e90
+	jr nz, .moving
 	ld a, [wd528]
+; check if down
 	bit 2, a
-	jr z, .notDown
+	jr z, .checkIfUp
 	xor a ; ld a, SPRITE_FACING_DOWN
-	jr .done
+	jr .next
-.notDown
+.checkIfUp
 	bit 3, a
-	jr z, .notUp
+	jr z, .checkIfLeft
 	ld a, SPRITE_FACING_UP
-	jr .done
+	jr .next
-.notUp
+.checkIfLeft
 	bit 1, a
-	jr z, .notLeft
+	jr z, .checkIfRight
 	ld a, SPRITE_FACING_LEFT
-	jr .done
+	jr .next
-.notLeft
+.checkIfRight
 	bit 0, a
-	jr z, .notRight
+	jr z, .notMoving
 	ld a, SPRITE_FACING_RIGHT
-	jr .done
+	jr .next
-.notRight
+.notMoving
+; zero the animation counters
 	xor a
 	ld [wSpriteStateData1 + 7], a
 	ld [wSpriteStateData1 + 8], a
-	jr .asm_4eab
+	jr .calcImageIndex
-.done
+.next
-	ld [wSpriteStateData1 + 9], a
+	ld [wSpriteStateData1 + 9], a ; facing direction
 	ld a, [wFontLoaded]
 	bit 0, a
-	jr nz, .notRight
+	jr nz, .notMoving
-.asm_4e90
+.moving
 	ld a, [wd736]
-	bit 7, a
+	bit 7, a ; is the player sprite spinning due to a spin tile?
-	jr nz, .asm_4eb6
+	jr nz, .skipSpriteAnim
 	ld a, [H_CURRENTSPRITEOFFSET]
 	add $7
 	ld l, a
 	ld a, [hl]
 	inc a
 	ld [hl], a
-	cp $4
+	cp 4
-	jr nz, .asm_4eab
+	jr nz, .calcImageIndex
 	xor a
 	ld [hl], a
 	inc hl
@@ -74,28 +76,32 @@ UpdatePlayerSprite: ; 4e31 (1:4e31)
 	inc a
 	and $3
 	ld [hl], a
-.asm_4eab
+.calcImageIndex
 	ld a, [wSpriteStateData1 + 8]
 	ld b, a
 	ld a, [wSpriteStateData1 + 9]
 	add b
 	ld [wSpriteStateData1 + 2], a
-.asm_4eb6
+.skipSpriteAnim
-	ld a, [$ff93]
+; If the player is standing on a grass tile, make the player's sprite have
+; lower priority than the background so that it's partially obscured by the
+; grass. Only the lower half of the sprite is permitted to have the priority
+; bit set by later logic.
+	ld a, [hTilePlayerStandingOn]
 	ld c, a
 	ld a, [W_GRASSTILE]
 	cp c
 	ld a, $0
-	jr nz, .asm_4ec3
+	jr nz, .next2
 	ld a, $80
-.asm_4ec3
+.next2
 	ld [wSpriteStateData2 + $07], a
 	ret
 
-Func_4ec7: ; 4ec7 (1:4ec7)
+UnusedReadSpriteDataFunction: ; 4ec7 (1:4ec7)
 	push bc
 	push af
-	ld a, [$ffda]
+	ld a, [H_CURRENTSPRITEOFFSET]
 	ld c, a
 	pop af
 	add c
@@ -103,7 +109,7 @@ Func_4ec7: ; 4ec7 (1:4ec7)
 	pop bc
 	ret
 
-Func_4ed1: ; 4ed1 (1:4ed1)
+UpdateNPCSprite: ; 4ed1 (1:4ed1)
 	ld a, [H_CURRENTSPRITEOFFSET]
 	swap a
 	dec a
@@ -148,40 +154,43 @@ Func_4ed1: ; 4ed1 (1:4ed1)
 	ld l, a
 	ld a, [hl]       ; c2x6: movement byte 1
 	inc a
-	jr z, .asm_4f59  ; value $FF
+	jr z, .randomMovement  ; value $FF
 	inc a
-	jr z, .asm_4f59  ; value $FE
+	jr z, .randomMovement  ; value $FE
+; scripted movement
 	dec a
-	ld [hl], a       ; (temporarily) increment movement byte 1
+	ld [hl], a       ; increment movement byte 1 (movement data index)
 	dec a
 	push hl
 	ld hl, wcf0f
 	dec [hl]         ; decrement wcf0f
 	pop hl
-	ld de, wcc5b
+	ld de, wNPCMovementDirections
-	call LoadDEPlusA ; a = [wcc5b + movement byte 1]
+	call LoadDEPlusA ; a = [wNPCMovementDirections + movement byte 1]
 	cp $e0
 	jp z, ChangeFacingDirection
 	cp $ff
-	jr nz, .asm_4f4b
+	jr nz, .next
-	ld [hl], a       ; reset movement byte 1 to initial value
+; reached end of wNPCMovementDirections list
+	ld [hl], a ; store $ff in movement byte 1, disabling scripted movement
 	ld hl, wd730
 	res 0, [hl]
 	xor a
 	ld [wSimulatedJoypadStatesIndex], a
 	ld [wWastedByteCD3A], a
 	ret
-.asm_4f4b
+.next
 	cp $fe
-	jr nz, .asm_4f5f
+	jr nz, .determineDirection
+; current NPC movement data is $fe. this seems buggy
 	ld [hl], $1     ; set movement byte 1 to $1
-	ld de, wcc5b
+	ld de, wNPCMovementDirections
-	call LoadDEPlusA ; a = [wcc5b + $fe] (?)
+	call LoadDEPlusA ; a = [wNPCMovementDirections + $fe] (?)
-	jr .asm_4f5f
+	jr .determineDirection
-.asm_4f59
+.randomMovement
-	call getTileSpriteStandsOn
+	call GetTileSpriteStandsOn
 	call Random
-.asm_4f5f
+.determineDirection
 	ld b, a
 	ld a, [wCurSpriteMovement2]
 	cp $d0
@@ -199,7 +208,7 @@ Func_4ed1: ; 4ed1 (1:4ed1)
 	cp $2
 	jr z, .moveLeft    ; movement byte 2 = $2 only allows left or right
 .moveDown
-	ld de, 2*20
+	ld de, 2*SCREEN_WIDTH
 	add hl, de         ; move tile pointer two rows down
 	ld de, $100
 
@@ -212,7 +221,7 @@ Func_4ed1: ; 4ed1 (1:4ed1)
 	cp $2
 	jr z, .moveRight   ; movement byte 2 = $2 only allows left or right
 .moveUp
-	ld de, -2*20
+	ld de, -2*SCREEN_WIDTH
 	add hl, de         ; move tile pointer two rows up
 	ld de, $ff00
 	ld bc, $804
@@ -249,7 +258,7 @@ ChangeFacingDirection: ; 4fc8 (1:4fc8)
 ; c: new facing direction (0,4,8 or $c)
 ; d: Y movement delta (-1, 0 or 1)
 ; e: X movement delta (-1, 0 or 1)
-; hl: pointer to tile the sprite would wlak onto
+; hl: pointer to tile the sprite would walk onto
 ; set carry on failure, clears carry on success
 TryWalking: ; 4fcb (1:4fcb)
 	push hl
@@ -470,7 +479,7 @@ CheckSpriteAvailability: ; 50dc (1:50dc)
 	ld l, a
 	ld a, [hl]      ; c2x6: movement byte 1
 	cp $fe
-	jr c, .skipXVisibilityTest ; movement byte 1 < $fe
+	jr c, .skipXVisibilityTest ; movement byte 1 < $fe (i.e. the sprite's movement is scripted)
 	ld a, [H_CURRENTSPRITEOFFSET]
 	add $4
 	ld l, a
@@ -495,7 +504,7 @@ CheckSpriteAvailability: ; 50dc (1:50dc)
 .skipXVisibilityTest
 ; make the sprite invisible if a text box is in front of it
 ; $5F is the maximum number for map tiles
-	call getTileSpriteStandsOn
+	call GetTileSpriteStandsOn
 	ld d, $60
 	ld a, [hli]
 	cp d
@@ -572,10 +581,11 @@ CanWalkOntoTile: ; 516e (1:516e)
 	ld l, a
 	ld a, [hl]         ; c2x6 (movement byte 1)
 	cp $fe
-	jr nc, .canMove    ; values $fe and $ff
+	jr nc, .notScripted    ; values $fe and $ff
+; always allow walking if the movement is scripted
 	and a
 	ret
-.canMove
+.notScripted
 	ld a, [W_TILESETCOLLISIONPTR]
 	ld l, a
 	ld a, [W_TILESETCOLLISIONPTR+1]
@@ -675,7 +685,7 @@ CanWalkOntoTile: ; 516e (1:516e)
 ; calculates the tile pointer pointing to the tile the current sprite stancs on
 ; this is always the lower left tile of the 2x2 tile blocks all sprites are snapped to
 ; hl: output pointer
-getTileSpriteStandsOn: ; 5207 (1:5207)
+GetTileSpriteStandsOn: ; 5207 (1:5207)
 	ld h, $c1
 	ld a, [H_CURRENTSPRITEOFFSET]
 	add $4
@@ -713,53 +723,58 @@ LoadDEPlusA: ; 522f (1:522f)
 	ld a, [de]
 	ret
 
-Func_5236: ; 5236 (1:5236)
+DoScriptedNPCMovement: ; 5236 (1:5236)
+; This is an alternative method of scripting an NPC's movement and is only used
+; a few times in the game. It is used when the NPC and player must walk together
+; in sync, such as when the player is following the NPC somewhere. An NPC can't
+; be moved in sync with the player using the other method.
 	ld a, [wd730]
 	bit 7, a
 	ret z
 	ld hl, wd72e
 	bit 7, [hl]
 	set 7, [hl]
-	jp z, Func_52a6
+	jp z, InitScriptedNPCMovement
 	ld hl, wNPCMovementDirections2
 	ld a, [wNPCMovementDirections2Index]
 	add l
 	ld l, a
-	jr nc, .asm_5251
+	jr nc, .noCarry
 	inc h
-.asm_5251
+.noCarry
 	ld a, [hl]
-	cp $40
+; check if moving up
-	jr nz, .asm_525f
+	cp NPC_MOVEMENT_UP
-	call Func_52b2
+	jr nz, .checkIfMovingDown
-	ld c, $4
+	call GetSpriteScreenYPointer
-	ld a, $fe
+	ld c, SPRITE_FACING_UP
-	jr .asm_5289
+	ld a, -2
-.asm_525f
+	jr .move
-	cp $0
+.checkIfMovingDown
-	jr nz, .asm_526c
+	cp NPC_MOVEMENT_DOWN
-	call Func_52b2
+	jr nz, .checkIfMovingLeft
-	ld c, $0
+	call GetSpriteScreenYPointer
-	ld a, $2
+	ld c, SPRITE_FACING_DOWN
-	jr .asm_5289
+	ld a, 2
-.asm_526c
+	jr .move
-	cp $80
+.checkIfMovingLeft
-	jr nz, .asm_5279
+	cp NPC_MOVEMENT_LEFT
-	call Func_52b7
+	jr nz, .checkIfMovingRight
-	ld c, $8
+	call GetSpriteScreenXPointer
-	ld a, $fe
+	ld c, SPRITE_FACING_LEFT
-	jr .asm_5289
+	ld a, -2
-.asm_5279
+	jr .move
-	cp $c0
+.checkIfMovingRight
-	jr nz, .asm_5286
+	cp NPC_MOVEMENT_RIGHT
-	call Func_52b7
+	jr nz, .noMatch
-	ld c, $c
+	call GetSpriteScreenXPointer
-	ld a, $2
+	ld c, SPRITE_FACING_RIGHT
-	jr .asm_5289
+	ld a, 2
-.asm_5286
+	jr .move
+.noMatch
 	cp $ff
 	ret
-.asm_5289
+.move
 	ld b, a
 	ld a, [hl]
 	add b
@@ -768,33 +783,34 @@ Func_5236: ; 5236 (1:5236)
 	add $9
 	ld l, a
 	ld a, c
-	ld [hl], a
+	ld [hl], a ; facing direction
-	call Func_52c3
+	call AnimScriptedNPCMovement
-	ld hl, wcf18
+	ld hl, wScriptedNPCWalkCounter
 	dec [hl]
 	ret nz
-	ld a, $8
+	ld a, 8
-	ld [wcf18], a
+	ld [wScriptedNPCWalkCounter], a
 	ld hl, wNPCMovementDirections2Index
 	inc [hl]
 	ret
 
-Func_52a6: ; 52a6 (1:52a6)
+InitScriptedNPCMovement: ; 52a6 (1:52a6)
 	xor a
 	ld [wNPCMovementDirections2Index], a
-	ld a, $8
+	ld a, 8
-	ld [wcf18], a
+	ld [wScriptedNPCWalkCounter], a
-	jp Func_52c3
+	jp AnimScriptedNPCMovement
 
-Func_52b2: ; 52b2 (1:52b2)
+GetSpriteScreenYPointer: ; 52b2 (1:52b2)
 	ld a, $4
 	ld b, a
-	jr asm_52ba
+	jr GetSpriteScreenXYPointerCommon
 
-Func_52b7: ; 52b7 (1:52b7)
+GetSpriteScreenXPointer: ; 52b7 (1:52b7)
 	ld a, $6
 	ld b, a
-asm_52ba: ; 52ba (1:52ba)
+
+GetSpriteScreenXYPointerCommon: ; 52ba (1:52ba)
 	ld hl, wSpriteStateData1
 	ld a, [H_CURRENTSPRITEOFFSET]
 	add l
@@ -802,12 +818,12 @@ asm_52ba: ; 52ba (1:52ba)
 	ld l, a
 	ret
 
-Func_52c3: ; 52c3 (1:52c3)
+AnimScriptedNPCMovement: ; 52c3 (1:52c3)
 	ld hl, wSpriteStateData2
 	ld a, [H_CURRENTSPRITEOFFSET]
 	add $e
 	ld l, a
-	ld a, [hl]
+	ld a, [hl] ; VRAM slot
 	dec a
 	swap a
 	ld b, a
@@ -815,47 +831,47 @@ Func_52c3: ; 52c3 (1:52c3)
 	ld a, [H_CURRENTSPRITEOFFSET]
 	add $9
 	ld l, a
-	ld a, [hl]
+	ld a, [hl] ; facing direction
-	cp $0
+	cp SPRITE_FACING_DOWN
-	jr z, .asm_52ea
+	jr z, .anim
-	cp $4
+	cp SPRITE_FACING_UP
-	jr z, .asm_52ea
+	jr z, .anim
-	cp $8
+	cp SPRITE_FACING_LEFT
-	jr z, .asm_52ea
+	jr z, .anim
-	cp $c
+	cp SPRITE_FACING_RIGHT
-	jr z, .asm_52ea
+	jr z, .anim
 	ret
-.asm_52ea
+.anim
 	add b
 	ld b, a
-	ld [$ffe9], a
+	ld [hSpriteVRAMSlotAndFacing], a
-	call Func_5301
+	call AdvanceScriptedNPCAnimFrameCounter
 	ld hl, wSpriteStateData1
 	ld a, [H_CURRENTSPRITEOFFSET]
 	add $2
 	ld l, a
-	ld a, [$ffe9]
+	ld a, [hSpriteVRAMSlotAndFacing]
 	ld b, a
-	ld a, [$ffea]
+	ld a, [hSpriteAnimFrameCounter]
 	add b
 	ld [hl], a
 	ret
 
-Func_5301: ; 5301 (1:5301)
+AdvanceScriptedNPCAnimFrameCounter: ; 5301 (1:5301)
 	ld a, [H_CURRENTSPRITEOFFSET]
 	add $7
 	ld l, a
-	ld a, [hl]
+	ld a, [hl] ; intra-animation frame counter
 	inc a
 	ld [hl], a
-	cp $4
+	cp 4
 	ret nz
 	xor a
-	ld [hl], a
+	ld [hl], a ; reset intra-animation frame counter
 	inc l
-	ld a, [hl]
+	ld a, [hl] ; animation frame counter
 	inc a
 	and $3
 	ld [hl], a
-	ld [$ffea], a
+	ld [hSpriteAnimFrameCounter], a
 	ret

engine/overworld/npc_movement.asm

@@ -44,60 +44,66 @@ _EndNPCMovementScript: ; 1a41d (6:641d)
 	ld [wSimulatedJoypadStatesEnd], a
 	ret
 
-ProfOakMovementScriptPointerTable: ; 1a442 (6:6442)
+PalletMovementScriptPointerTable: ; 1a442 (6:6442)
-	dw Func_1a44c
+	dw PalletMovementScript_OakMoveLeft
-	dw Func_1a485
+	dw PalletMovementScript_PlayerMoveLeft
-	dw Func_1a4a1
+	dw PalletMovementScript_WaitAndWalkToLab
-	dw Func_1a4a6
+	dw PalletMovementScript_WalkToLab
-	dw Func_1a4f4
+	dw PalletMovementScript_Done
 
-Func_1a44c: ; 1a44c (6:644c)
+PalletMovementScript_OakMoveLeft: ; 1a44c (6:644c)
 	ld a, [W_XCOORD]
 	sub $a
-	ld [wcca1], a
+	ld [wNumStepsToTake], a
-	jr z, .asm_1a475
+	jr z, .playerOnLeftTile
-	ld b, $0
+; The player is on the right tile of the northern path out of Pallet Town and
+; Prof. Oak is below.
+; Make Prof. Oak step to the left.
+	ld b, 0
 	ld c, a
 	ld hl, wNPCMovementDirections2
-	ld a, $80
+	ld a, NPC_MOVEMENT_LEFT
 	call FillMemory
 	ld [hl], $ff
 	ld a, [wSpriteIndex]
-	ld [H_DOWNARROWBLINKCNT2], a
+	ld [H_SPRITEINDEX], a
 	ld de, wNPCMovementDirections2
 	call MoveSprite
 	ld a, $1
 	ld [wNPCMovementScriptFunctionNum], a
-	jr .asm_1a47a
+	jr .done
-.asm_1a475
+; The player is on the left tile of the northern path out of Pallet Town and
+; Prof. Oak is below.
+; Prof. Oak is already on the right tile.
+.playerOnLeftTile
 	ld a, $3
 	ld [wNPCMovementScriptFunctionNum], a
-.asm_1a47a
+.done
 	ld hl, W_FLAGS_D733
 	set 1, [hl]
 	ld a, $fc
 	ld [wJoyIgnore], a
 	ret
 
-Func_1a485: ; 1a485 (6:6485)
+PalletMovementScript_PlayerMoveLeft: ; 1a485 (6:6485)
 	ld a, [wd730]
-	bit 0, a
+	bit 0, a ; is an NPC being moved by a script?
-	ret nz
+	ret nz ; return if Oak is still moving
-	ld a, [wcca1]
+	ld a, [wNumStepsToTake]
 	ld [wSimulatedJoypadStatesIndex], a
-	ld [$ff95], a
+	ld [hNPCMovementDirections2Index], a
 	predef ConvertNPCMovementDirectionsToJoypadMasks
 	call StartSimulatingJoypadStates
 	ld a, $2
 	ld [wNPCMovementScriptFunctionNum], a
 	ret
 
-Func_1a4a1: ; 1a4a1 (6:64a1)
+PalletMovementScript_WaitAndWalkToLab: ; 1a4a1 (6:64a1)
 	ld a, [wSimulatedJoypadStatesIndex]
-	and a
+	and a ; is the player done moving left yet?
 	ret nz
 
-Func_1a4a6: ; 1a4a6 (6:64a6)
+PalletMovementScript_WalkToLab: ; 1a4a6 (6:64a6)
 	xor a
 	ld [wOverrideSimulatedJoypadStatesMask], a
 	ld a, [wSpriteIndex]
@@ -122,12 +128,12 @@ Func_1a4a6: ; 1a4a6 (6:64a6)
 	ret
 
 RLEList_ProfOakWalkToLab: ; 1a4dc (6:64dc)
-	db $00, $05
+	db NPC_MOVEMENT_DOWN, $05
-	db $80, $01
+	db NPC_MOVEMENT_LEFT, $01
-	db $00, $05
+	db NPC_MOVEMENT_DOWN, $05
-	db $C0, $03
+	db NPC_MOVEMENT_RIGHT, $03
-	db $40, $01
+	db NPC_MOVEMENT_UP, $01
-	db $E0, $01
+	db $E0, $01 ; stand still
 	db $FF
 
 RLEList_PlayerWalkToLab: ; 1a4e9 (6:64e9)
@@ -138,7 +144,7 @@ RLEList_PlayerWalkToLab: ; 1a4e9 (6:64e9)
 	db D_DOWN, $06
 	db $FF
 
-Func_1a4f4: ; 1a4f4 (6:64f4)
+PalletMovementScript_Done: ; 1a4f4 (6:64f4)
 	ld a, [wSimulatedJoypadStatesIndex]
 	and a
 	ret nz
@@ -152,10 +158,10 @@ Func_1a4f4: ; 1a4f4 (6:64f4)
 	jp EndNPCMovementScript
 
 PewterMuseumGuyMovementScriptPointerTable: ; 1a510 (6:6510)
-	dw Func_1a514
+	dw PewterMovementScript_WalkToMuseum
-	dw PewterMovementScriptDone
+	dw PewterMovementScript_Done
 
-Func_1a514: ; 1a514 (6:6514)
+PewterMovementScript_WalkToMuseum: ; 1a514 (6:6514)
 	ld a, BANK(Music_MuseumGuy)
 	ld [wc0ef], a
 	ld [wc0f0], a
@@ -191,13 +197,13 @@ RLEList_PewterMuseumPlayer: ; 1a559 (6:6559)
 	db $FF
 
 RLEList_PewterMuseumGuy: ; 1a562 (6:6562)
-	db $40, $06
+	db NPC_MOVEMENT_UP, $06
-	db $80, $0D
+	db NPC_MOVEMENT_LEFT, $0D
-	db $40, $03
+	db NPC_MOVEMENT_UP, $03
-	db $80, $01
+	db NPC_MOVEMENT_LEFT, $01
 	db $FF
 
-PewterMovementScriptDone: ; 1a56b (6:656b)
+PewterMovementScript_Done: ; 1a56b (6:656b)
 	ld a, [wSimulatedJoypadStatesIndex]
 	and a
 	ret nz
@@ -208,10 +214,10 @@ PewterMovementScriptDone: ; 1a56b (6:656b)
 	jp EndNPCMovementScript
 
 PewterGymGuyMovementScriptPointerTable: ; 1a57d (6:657d)
-	dw Func_1a581
+	dw PewterMovementScript_WalkToGym
-	dw PewterMovementScriptDone
+	dw PewterMovementScript_Done
 
-Func_1a581: ; 1a581 (6:6581)
+PewterMovementScript_WalkToGym: ; 1a581 (6:6581)
 	ld a, BANK(Music_MuseumGuy)
 	ld [wc0ef], a
 	ld [wc0f0], a
@@ -252,12 +258,12 @@ RLEList_PewterGymPlayer: ; 1a5cd (6:65cd)
 	db $FF
 
 RLEList_PewterGymGuy: ; 1a5da (6:65da)
-	db $00, $02
+	db NPC_MOVEMENT_DOWN, $02
-	db $80, $0F
+	db NPC_MOVEMENT_LEFT, $0F
-	db $40, $05
+	db NPC_MOVEMENT_UP, $05
-	db $80, $0B
+	db NPC_MOVEMENT_LEFT, $0B
-	db $00, $05
+	db NPC_MOVEMENT_DOWN, $05
-	db $C0, $03
+	db NPC_MOVEMENT_RIGHT, $03
 	db $FF
 
 FreezeEnemyTrainerSprite: ; 1a5e7 (6:65e7)

engine/overworld/oam.asm

@@ -4,25 +4,26 @@ PrepareOAMData:
 
 	ld a, [wUpdateSpritesEnabled]
 	dec a
-	jr z, .asm_4b1e
+	jr z, .updateEnabled
 
 	cp 0 - 1
 	ret nz
 	ld [wUpdateSpritesEnabled], a
 	jp HideSprites
 
-.asm_4b1e
+.updateEnabled
 	xor a
-	ld [$ff90], a
+	ld [hOAMBufferOffset], a
-.asm_4b21
+
-	ld [$ff8f], a
+.spriteLoop
+	ld [hSpriteOffset2], a
 
 	ld d, wSpriteStateData1 / $100
-	ld a, [$ff8f]
+	ld a, [hSpriteOffset2]
 	ld e, a
 	ld a, [de] ; c1x0
 	and a
-	jp z, .asm_4bad
+	jp z, .nextSprite
 
 	inc e
 	inc e
@@ -31,21 +32,25 @@ PrepareOAMData:
 	cp $ff ; off-screen (don't draw)
 	jr nz, .visible
 
-	call Func_4bd1
+	call GetSpriteScreenXY
-	jr .asm_4bad
+	jr .nextSprite
 
 .visible
-	cp $a0
+	cp $a0 ; is the sprite unchanging like an item ball or boulder?
 	jr c, .usefacing
+
+; unchanging
 	and $f
-	add $10
+	add $10 ; skip to the second half of the table which doesn't account for facing direction
-	jr .asm_4b48
+	jr .next
 
 .usefacing
 	and $f
-.asm_4b48
+
+.next
 	ld l, a
 
+; get sprite priority
 	push de
 	inc d
 	ld a, e
@@ -53,15 +58,15 @@ PrepareOAMData:
 	ld e, a
 	ld a, [de] ; c2x7
 	and $80
-	ld [$ff94], a ; temp store sprite priority
+	ld [hSpritePriority], a ; temp store sprite priority
 	pop de
 
+; read the entry from the table
 	ld h, 0
 	ld bc, SpriteFacingAndAnimationTable
 	add hl, hl
 	add hl, hl
 	add hl, bc
-
 	ld a, [hli]
 	ld c, a
 	ld a, [hli]
@@ -70,24 +75,25 @@ PrepareOAMData:
 	ld h, [hl]
 	ld l, a
 
-	call Func_4bd1
+	call GetSpriteScreenXY
 
-	ld a, [$ff90]
+	ld a, [hOAMBufferOffset]
 	ld e, a
 	ld d, wOAMBuffer / $100
-.tile
+
-	ld a, [$ff92]            ; temp for sprite Y position
+.tileLoop
+	ld a, [hSpriteScreenY]   ; temp for sprite Y position
 	add $10                  ; Y=16 is top of screen (Y=0 is invisible)
 	add [hl]                 ; add Y offset from table
 	ld [de], a               ; write new sprite OAM Y position
 	inc hl
-	ld a, [$ff91]            ; temp for sprite X position
+	ld a, [hSpriteScreenX]   ; temp for sprite X position
 	add $8                   ; X=8 is left of screen (X=0 is invisible)
 	add [hl]                 ; add X offset from table
 	inc e
 	ld [de], a               ; write new sprite OAM X position
 	inc e
-	ld a, [bc]               ; read pattern number offset (accomodates orientation (offset 0,4 or 8) and animation (offset 0 or $80))
+	ld a, [bc]               ; read pattern number offset (accommodates orientation (offset 0,4 or 8) and animation (offset 0 or $80))
 	inc bc
 	push bc
 	ld b, a
@@ -99,55 +105,60 @@ PrepareOAMData:
 	; Sprites $a and $b have one face (and therefore 4 tiles instead of 12).
 	; As a result, sprite $b's tile offset is less than normal.
 	cp $b
-	jr nz, .offset
+	jr nz, .notFourTileSprite
 	ld a, $a * 12 + 4
-	jr .gotoffset
+	jr .next2
 
-.offset
+.notFourTileSprite
 	; a *= 12
 	sla a
 	sla a
 	ld c, a
 	sla a
 	add c
-.gotoffset
+
-	add b ; which frame
+.next2
+	add b ; add the tile offset from the table (based on frame and facing direction)
 	pop bc
 	ld [de], a ; tile id
 	inc hl
 	inc e
 	ld a, [hl]
-	bit 1, a ; sprite priority
+	bit 1, a ; is the tile allowed to set the sprite priority bit?
-	jr z, .fg
+	jr z, .skipPriority
-	ld a, [$ff94] ; facing priority
+	ld a, [hSpritePriority]
 	or [hl]
-.fg
+.skipPriority
 	inc hl
 	ld [de], a
 	inc e
 	bit 0, a ; OAMFLAG_ENDOFDATA
-	jr z, .tile
+	jr z, .tileLoop
 
 	ld a, e
-	ld [$ff90], a
+	ld [hOAMBufferOffset], a
 
-.asm_4bad
+.nextSprite
-	ld a, [$ff8f]
+	ld a, [hSpriteOffset2]
 	add $10
 	cp $100 % $100
-	jp nz, .asm_4b21
+	jp nz, .spriteLoop
 
 	; Clear unused OAM.
-	ld a, [$ff90]
+	ld a, [hOAMBufferOffset]
 	ld l, a
 	ld h, wOAMBuffer / $100
 	ld de, $4
 	ld b, $a0
 	ld a, [wd736]
-	bit 6, a
+	bit 6, a ; jumping down ledge or fishing animation?
 	ld a, $a0
 	jr z, .clear
+
+; Don't clear the last 4 entries because they are used for the shadow in the
+; jumping down ledge animation and the rod in the fishing animation.
 	ld a, $90
+
 .clear
 	cp l
 	ret z
@@ -155,24 +166,24 @@ PrepareOAMData:
 	add hl, de
 	jr .clear
 
-Func_4bd1: ; 4bd1 (1:4bd1)
+GetSpriteScreenXY: ; 4bd1 (1:4bd1)
 	inc e
 	inc e
 	ld a, [de] ; c1x4
-	ld [$ff92], a
+	ld [hSpriteScreenY], a
 	inc e
 	inc e
 	ld a, [de] ; c1x6
-	ld [$ff91], a
+	ld [hSpriteScreenX], a
-	ld a, $4
+	ld a, 4
 	add e
 	ld e, a
-	ld a, [$ff92]
+	ld a, [hSpriteScreenY]
-	add $4
+	add 4
 	and $f0
 	ld [de], a ; c1xa (y)
 	inc e
-	ld a, [$ff91]
+	ld a, [hSpriteScreenX]
 	and $f0
 	ld [de], a  ; c1xb (x)
 	ret

engine/overworld/player_animations.asm

@@ -1,5 +1,5 @@
 EnterMapAnim: ; 70510 (1c:4510)
-	call InitFacingDirectionBuffer
+	call InitFacingDirectionList
 	ld a, $ec
 	ld [wSpriteStateData1 + 4], a ; player's sprite Y screen position
 	call Delay3
@@ -32,7 +32,7 @@ EnterMapAnim: ; 70510 (1c:4510)
 	ld a, $8
 	ld [hli], a ; wPlayerSpinInPlaceAnimFrameDelayEndValue
 	ld [hl], $ff ; wPlayerSpinInPlaceAnimSoundID
-	ld hl, wcd48
+	ld hl, wFacingDirectionList
 	call PlayerSpinInPlace
 .restoreDefaultMusic
 	call PlayDefaultMusic
@@ -91,7 +91,7 @@ PlayerSpinWhileMovingDown: ; 705aa (1c:45aa)
 	jp PlayerSpinWhileMovingUpOrDown
 
 _LeaveMapAnim: ; 705ba (1c:45ba)
-	call InitFacingDirectionBuffer
+	call InitFacingDirectionList
 	call IsPlayerStandingOnWarpPadOrHole
 	ld a, b
 	and a
@@ -134,7 +134,7 @@ _LeaveMapAnim: ; 705ba (1c:45ba)
 	xor a
 	ld [hli], a ; wPlayerSpinInPlaceAnimFrameDelayEndValue
 	ld [hl], (SFX_02_4d - SFX_Headers_02) / 3 ; wPlayerSpinInPlaceAnimSoundID
-	ld hl, wcd48
+	ld hl, wFacingDirectionList
 	call PlayerSpinInPlace
 	jr .spinWhileMovingUp
 .flyAnimation
@@ -214,7 +214,7 @@ LeaveMapThroughHoleAnim: ; 7067d (1c:467d)
 	ld [wOAMBuffer + 1 * 4], a
 	ld c, 2
 	call DelayFrames
-	; hide lower half of player's sprite
+	; hide upper half of player's sprite
 	ld a, $a0
 	ld [wOAMBuffer + 2 * 4], a
 	ld [wOAMBuffer + 3 * 4], a
@@ -231,7 +231,7 @@ DoFlyAnimation: ; 706ae (1c:46ae)
 	call Delay3
 	ld a, [wFlyAnimUsingCoordList]
 	cp $ff
-	jr z, .asm_706cd
+	jr z, .skipCopyingCoords ; if the bird is flapping its wings in place
 	ld hl, wSpriteStateData1 + 4
 	ld a, [de]
 	inc de
@@ -240,7 +240,7 @@ DoFlyAnimation: ; 706ae (1c:46ae)
 	ld a, [de]
 	inc de
 	ld [hl], a
-.asm_706cd
+.skipCopyingCoords
 	ld a, [wFlyAnimCounter]
 	dec a
 	ld [wFlyAnimCounter], a
@@ -252,22 +252,23 @@ LoadBirdSpriteGraphics: ; 706d7 (1c:46d7)
 	ld hl, vNPCSprites
 	ld bc, (BANK(BirdSprite) << 8) + $0c
 	call CopyVideoData
-	ld de, BirdSprite + $c0 ; moving amination sprite
+	ld de, BirdSprite + $c0 ; moving animation sprite
 	ld hl, vNPCSprites2
 	ld bc, (BANK(BirdSprite) << 8) + $0c
 	jp CopyVideoData
 
-InitFacingDirectionBuffer: ; 706ef (1c:46ef)
+InitFacingDirectionList: ; 706ef (1c:46ef)
 	ld a, [wSpriteStateData1 + 2] ; player's sprite facing direction (image index is locked to standing images)
-	ld [wcd50], a
+	ld [wSavedPlayerFacingDirection], a
 	ld a, [wSpriteStateData1 + 4] ; player's sprite Y screen position
-	ld [wcd4f], a
+	ld [wSavedPlayerScreenY], a
 	ld hl, PlayerSpinningFacingOrder
-	ld de, wcd48
+	ld de, wFacingDirectionList
-	ld bc, $4
+	ld bc, 4
 	call CopyData
 	ld a, [wSpriteStateData1 + 2] ; player's sprite facing direction (image index is locked to standing images)
-	ld hl, wcd48
+	ld hl, wFacingDirectionList
+; find the place in the list that matches the current facing direction
 .loop
 	cp [hl]
 	inc hl
@@ -281,15 +282,16 @@ PlayerSpinningFacingOrder: ; 70713 (1c:4713)
 	db SPRITE_FACING_DOWN, SPRITE_FACING_LEFT, SPRITE_FACING_UP, SPRITE_FACING_RIGHT
 
 SpinPlayerSprite: ; 70717 (1c:4717)
+; copy the current value from the list into the sprite data and rotate the list
 	ld a, [hl]
 	ld [wSpriteStateData1 + 2], a ; player's sprite facing direction (image index is locked to standing images)
 	push hl
-	ld hl, wcd48
+	ld hl, wFacingDirectionList
-	ld de, wcd47
+	ld de, wFacingDirectionList - 1
-	ld bc, $4
+	ld bc, 4
 	call CopyData
-	ld a, [wcd47]
+	ld a, [wFacingDirectionList - 1]
-	ld [wcd4b], a
+	ld [wFacingDirectionList + 3], a
 	pop hl
 	ret
 
@@ -298,11 +300,12 @@ PlayerSpinInPlace: ; 70730 (1c:4730)
 	ld a, [wPlayerSpinInPlaceAnimFrameDelay]
 	ld c, a
 	and $3
-	jr nz, .asm_70743
+	jr nz, .skipPlayingSound
+; when the last delay was a multiple of 4, play a sound if there is one
 	ld a, [wPlayerSpinInPlaceAnimSoundID]
 	cp $ff
 	call nz, PlaySound
-.asm_70743
+.skipPlayingSound
 	ld a, [wPlayerSpinInPlaceAnimFrameDelayDelta]
 	add c
 	ld [wPlayerSpinInPlaceAnimFrameDelay], a
@@ -330,9 +333,9 @@ PlayerSpinWhileMovingUpOrDown: ; 70755 (1c:4755)
 	jr PlayerSpinWhileMovingUpOrDown
 
 RestoreFacingDirectionAndYScreenPos: ; 70772 (1c:4772)
-	ld a, [wcd4f]
+	ld a, [wSavedPlayerScreenY]
 	ld [wSpriteStateData1 + 4], a
-	ld a, [wcd50]
+	ld a, [wSavedPlayerFacingDirection]
 	ld [wSpriteStateData1 + 2], a
 	ret
 
@@ -378,11 +381,11 @@ IsPlayerStandingOnWarpPadOrHole: ; 70787 (1c:4787)
 	db INTERIOR, $55, 1 ; warp pad
 	db $FF
 
-Func_707b6: ; 707b6 (1c:47b6)
+FishingAnim: ; 707b6 (1c:47b6)
 	ld c, 10
 	call DelayFrames
 	ld hl, wd736
-	set 6, [hl]
+	set 6, [hl] ; reserve the last 4 OAM entries
 	ld de, RedSprite
 	ld hl, vNPCSprites
 	ld bc, (BANK(RedSprite) << 8) + $0c
@@ -393,55 +396,67 @@ Func_707b6: ; 707b6 (1c:47b6)
 	ld a, [wSpriteStateData1 + 2]
 	ld c, a
 	ld b, $0
-	ld hl, FishingRodGfxProperties
+	ld hl, FishingRodOAM
 	add hl, bc
 	ld de, wOAMBuffer + $9c
 	ld bc, $4
 	call CopyData
 	ld c, 100
 	call DelayFrames
-	ld a, [wWhichTrade]
+	ld a, [wRodResponse]
 	and a
 	ld hl, NoNibbleText
-	jr z, .asm_70836
+	jr z, .done
 	cp $2
 	ld hl, NothingHereText
-	jr z, .asm_70836
+	jr z, .done
-	ld b, $a
+
-.asm_707fe
+; there was a bite
-	ld hl, wSpriteStateData1 + 4
+
-	call Func_70842
+; shake the player's sprite vertically
+	ld b, 10
+.loop
+	ld hl, wSpriteStateData1 + 4 ; player's sprite Y screen position
+	call .ShakePlayerSprite
 	ld hl, wOAMBuffer + $9c
-	call Func_70842
+	call .ShakePlayerSprite
 	call Delay3
 	dec b
-	jr nz, .asm_707fe
+	jr nz, .loop
-	ld a, [wSpriteStateData1 + 2]
+
-	cp $4
+; If the player is facing up, hide the fishing rod so it doesn't overlap with
-	jr nz, .asm_7081c
+; the exclamation bubble that will be shown next.
+	ld a, [wSpriteStateData1 + 2] ; player's sprite facing direction
+	cp SPRITE_FACING_UP
+	jr nz, .skipHidingFishingRod
 	ld a, $a0
 	ld [wOAMBuffer + $9c], a
-.asm_7081c
+
-	ld hl, wcd4f
+.skipHidingFishingRod
+	ld hl, wEmotionBubbleSpriteIndex
 	xor a
-	ld [hli], a
+	ld [hli], a ; player's sprite
-	ld [hl], a
+	ld [hl], a ; EXCLAMATION_BUBBLE
 	predef EmotionBubble
-	ld a, [wSpriteStateData1 + 2]
+
-	cp $4
+; If the player is facing up, unhide the fishing rod.
-	jr nz, .asm_70833
+	ld a, [wSpriteStateData1 + 2] ; player's sprite facing direction
+	cp SPRITE_FACING_UP
+	jr nz, .skipUnhidingFishingRod
 	ld a, $44
 	ld [wOAMBuffer + $9c], a
-.asm_70833
+
+.skipUnhidingFishingRod
 	ld hl, ItsABiteText
-.asm_70836
+
+.done
 	call PrintText
 	ld hl, wd736
-	res 6, [hl]
+	res 6, [hl] ; unreserve the last 4 OAM entries
 	call LoadFontTilePatterns
 	ret
 
-Func_70842: ; 70842 (1c:4842)
+.ShakePlayerSprite
 	ld a, [hl]
 	xor $1
 	ld [hl], a
@@ -459,7 +474,7 @@ ItsABiteText: ; 70851 (1c:4851)
 	TX_FAR _ItsABiteText
 	db "@"
 
-FishingRodGfxProperties: ; 70856 (1c:4856)
+FishingRodOAM: ; 70856 (1c:4856)
 ; specifies how the fishing rod should be drawn on the screen
 ; first byte = screen y coordinate
 ; second byte = screen x coordinate

engine/overworld/pokemart.asm

@@ -57,9 +57,9 @@ DisplayPokemartDialogue_: ; 6c20 (1:6c20)
 	call DisplayTextBoxID ; draw money text box
 	ld hl,wNumBagItems
 	ld a,l
-	ld [wList],a
+	ld [wListPointer],a
 	ld a,h
-	ld [wList + 1],a
+	ld [wListPointer + 1],a
 	xor a
 	ld [wPrintItemPrices],a
 	ld [wCurrentMenuItem],a
@@ -136,11 +136,11 @@ DisplayPokemartDialogue_: ; 6c20 (1:6c20)
 	ld a,MONEY_BOX
 	ld [wTextBoxID],a
 	call DisplayTextBoxID
-	ld hl,wStringBuffer2 + 11
+	ld hl,wItemList
 	ld a,l
-	ld [wList],a
+	ld [wListPointer],a
 	ld a,h
-	ld [wList + 1],a
+	ld [wListPointer + 1],a
 	xor a
 	ld [wCurrentMenuItem],a
 	inc a

engine/overworld/ssanne.asm

@@ -1,6 +1,6 @@
 AnimateBoulderDust: ; 79f54 (1e:5f54)
 	ld a, $1
-	ld [wcd50], a ; select the boulder dust offsets
+	ld [wWhichAnimationOffsets], a ; select the boulder dust offsets
 	ld a, [wUpdateSpritesEnabled]
 	push af
 	ld a, $ff

engine/predefs.asm

@@ -57,7 +57,7 @@ PredefPointers:: ; 4fe79 (13:7e79)
 	add_predef AnimateSendingOutMon
 	add_predef ScaleSpriteByTwo
 	add_predef LoadMonBackPic
-	add_predef CopyGrowingMonTiles
+	add_predef CopyDownscaledMonTiles
 	add_predef LoadMissableObjects
 	add_predef HealParty
 	add_predef MoveAnimation; 08 play move animation

engine/predefs7.asm

@@ -1,11 +1,11 @@
 Func_1c9c6: ; 1c9c6 (7:49c6)
 	ld hl, WhichFloorText
 	call PrintText
-	ld hl, wStringBuffer2 + 11
+	ld hl, wItemList
 	ld a, l
-	ld [wList], a
+	ld [wListPointer], a
 	ld a, h
-	ld [wList + 1], a
+	ld [wListPointer + 1], a
 	ld a, [wListScrollOffset]
 	push af
 	xor a

engine/save.asm

@@ -309,7 +309,7 @@ Func_73863: ; 73863 (1c:7863)
 
 Func_7387b: ; 7387b (1c:787b)
 	ld hl, PointerTable_73895
-	ld a, [wd5a0]
+	ld a, [wCurrentBoxNum]
 	and $7f
 	cp NUM_BOXES / 2
 	ld b, $2
@@ -341,7 +341,7 @@ ChangeBox:: ; 738a1 (1c:78a1)
 	ld a, [wCurrentMenuItem]
 	and a
 	ret nz ; return if No was chosen
-	ld hl, wd5a0
+	ld hl, wCurrentBoxNum
 	bit 7, [hl]
 	call z, Func_73a29
 	call Func_7393f
@@ -360,7 +360,7 @@ ChangeBox:: ; 738a1 (1c:78a1)
 	call Func_7390e
 	ld a, [wCurrentMenuItem]
 	set 7, a
-	ld [wd5a0], a
+	ld [wCurrentBoxNum], a
 	call Func_7387b
 	ld de, W_NUMINBOX
 	call Func_7390e
@@ -422,7 +422,7 @@ Func_7393f: ; 7393f (1c:793f)
 	ld [wTopMenuItemX], a
 	xor a
 	ld [wMenuWatchMovingOutOfBounds], a
-	ld a, [wd5a0]
+	ld a, [wCurrentBoxNum]
 	and $7f
 	ld [wCurrentMenuItem], a
 	ld [wLastMenuItem], a
@@ -443,7 +443,7 @@ Func_7393f: ; 7393f (1c:793f)
 	call PlaceString
 	ld hl, hFlags_0xFFF6
 	res 2, [hl]
-	ld a, [wd5a0]
+	ld a, [wCurrentBoxNum]
 	and $7f
 	cp 9
 	jr c, .asm_739a6
@@ -561,7 +561,7 @@ Func_73a84: ; 73a84 (1c:7a84)
 	ld [MBC1SRamBankingMode], a
 	ld [MBC1SRamEnable], a
 	pop hl
-	ld a, [wd5a0]
+	ld a, [wCurrentBoxNum]
 	and $7f
 	ld c, a
 	ld b, $0
@@ -620,9 +620,9 @@ SAVCheckRandomID: ; 73ad1 (1c:7ad1)
 	ret
 
 SaveHallOfFameTeams: ; 73b0d (1c:7b0d)
-	ld a, [wd5a2]
+	ld a, [wNumHoFTeams]
 	dec a
-	cp NUM_HOF_TEAMS
+	cp HOF_TEAM_CAPACITY
 	jr nc, .asm_73b28
 	ld hl, sHallOfFame
 	ld bc, HOF_TEAM
@@ -636,10 +636,10 @@ SaveHallOfFameTeams: ; 73b0d (1c:7b0d)
 .asm_73b28
 	ld hl, sHallOfFame + HOF_TEAM
 	ld de, sHallOfFame
-	ld bc, HOF_TEAM * (NUM_HOF_TEAMS - 1)
+	ld bc, HOF_TEAM * (HOF_TEAM_CAPACITY - 1)
 	call HallOfFame_Copy
 	ld hl, wcc5b
-	ld de, sHallOfFame + HOF_TEAM * (NUM_HOF_TEAMS - 1)
+	ld de, sHallOfFame + HOF_TEAM * (HOF_TEAM_CAPACITY - 1)
 	ld bc, HOF_TEAM
 	jr HallOfFame_Copy
 

engine/titlescreen.asm

@@ -12,7 +12,7 @@ SetDefaultNamesBeforeTitlescreen: ; 42b7 (1:42b7)
 	call CopyFixedLengthText
 	xor a
 	ld [hWY], a
-	ld [wd358], a
+	ld [wLetterPrintingDelayFlags], a
 	ld hl, wd732
 	ld [hli], a
 	ld [hli], a
@@ -284,7 +284,7 @@ Func_44c1: ; 44c1 (1:44c1)
 
 Func_44cf: ; 44cf (1:44cf)
 .wait
-	ld a, [$ff44] ; rLY
+	ld a, [rLY]
 	cp l
 	jr nz, .wait
 
@@ -292,7 +292,7 @@ Func_44cf: ; 44cf (1:44cf)
 	ld [rSCX], a
 
 .wait2
-	ld a, [$ff44] ; rLY
+	ld a, [rLY]
 	cp h
 	jr z, .wait2
 	ret

engine/titlescreen2.asm

@@ -69,7 +69,7 @@ _TitleScroll: ; 3726a (d:726a)
 
 .ScrollBetween ; 37292 (d:7292)
 .wait
-	ld a, [$ff44] ; rLY
+	ld a, [rLY] ; rLY
 	cp l
 	jr nz, .wait
 
@@ -77,7 +77,7 @@ _TitleScroll: ; 3726a (d:726a)
 	ld [rSCX], a
 
 .wait2
-	ld a, [$ff44] ; rLY
+	ld a, [rLY] ; rLY
 	cp h
 	jr z, .wait2
 	ret

home.asm

@@ -243,7 +243,7 @@ DrawHPBar:: ; 1336 (0:1336)
 ; loads base stats to W_MONHDEXNUM
 ; INPUT:
 ; [wWhichPokemon] = index of pokemon within party/box
-; [wcc49] = source
+; [wMonDataLocation] = source
 ; 00: player's party
 ; 01: enemy's party
 ; 02: current box
@@ -376,15 +376,15 @@ PartyMenuInit:: ; 1420 (0:1420)
 	call LoadHpBarAndStatusTilePatterns
 	ld hl, wd730
 	set 6, [hl] ; turn off letter printing delay
-	xor a
+	xor a ; PLAYER_PARTY_DATA
-	ld [wcc49], a
+	ld [wMonDataLocation], a
 	ld [wMenuWatchMovingOutOfBounds], a
 	ld hl, wTopMenuItemY
 	inc a
 	ld [hli], a ; top menu item Y
 	xor a
 	ld [hli], a ; top menu item X
-	ld a, [wcc2b]
+	ld a, [wPartyAndBillsPCSavedMenuItem]
 	push af
 	ld [hli], a ; current menu item ID
 	inc hl
@@ -420,7 +420,7 @@ HandlePartyMenuInput:: ; 145a (0:145a)
 	xor a
 	ld [wd09b],a
 	ld a,[wCurrentMenuItem]
-	ld [wcc2b],a
+	ld [wPartyAndBillsPCSavedMenuItem],a
 	ld hl,wd730
 	res 6,[hl] ; turn on letter printing delay
 	ld a,[wMenuItemToSwap]
@@ -1055,7 +1055,7 @@ DisplayTextID:: ; 2920 (0:2920)
 	ld a,[H_LOADEDROMBANK]
 	push af
 	callba DisplayTextIDInit ; initialization
-	ld hl,wcf11
+	ld hl,wTextPredefFlag
 	bit 0,[hl]
 	res 0,[hl]
 	jr nz,.skipSwitchToMapBank
@@ -1225,7 +1225,7 @@ LoadItemList:: ; 2a5a (0:2a5a)
 	ld [wItemListPointer],a
 	ld a,l
 	ld [wItemListPointer + 1],a
-	ld de,wStringBuffer2 + 11
+	ld de,wItemList
 .loop
 	ld a,[hli]
 	ld [de],a
@@ -1372,7 +1372,7 @@ AddItemToInventory:: ; 2bcf (0:2bcf)
 
 ; INPUT:
 ; [wListMenuID] = list menu ID
-; [wList] = address of the list (2 bytes)
+; [wListPointer] = address of the list (2 bytes)
 DisplayListMenuID:: ; 2be6 (0:2be6)
 	xor a
 	ld [H_AUTOBGTRANSFERENABLED],a ; disable auto-transfer
@@ -1392,9 +1392,9 @@ DisplayListMenuID:: ; 2be6 (0:2be6)
 	xor a
 	ld [wMenuItemToSwap],a ; 0 means no item is currently being swapped
 	ld [wListCount],a
-	ld a,[wList]
+	ld a,[wListPointer]
 	ld l,a
-	ld a,[wList + 1]
+	ld a,[wListPointer + 1]
 	ld h,a ; hl = address of the list
 	ld a,[hl] ; the first byte is the number of entries in the list
 	ld [wListCount],a
@@ -1488,9 +1488,9 @@ DisplayListMenuIDLoop:: ; 2c53 (0:2c53)
 ; if it's an item menu
 	sla c ; item entries are 2 bytes long, so multiply by 2
 .skipMultiplying
-	ld a,[wList]
+	ld a,[wListPointer]
 	ld l,a
-	ld a,[wList + 1]
+	ld a,[wListPointer + 1]
 	ld h,a
 	inc hl ; hl = beginning of list entries
 	ld b,0
@@ -1519,7 +1519,7 @@ DisplayListMenuIDLoop:: ; 2c53 (0:2c53)
 	jr .storeChosenEntry
 .pokemonList
 	ld hl,wPartyCount
-	ld a,[wList]
+	ld a,[wListPointer]
 	cp l ; is it a list of party pokemon or box pokemon?
 	ld hl,wPartyMonNicks
 	jr z,.getPokemonName
@@ -1710,9 +1710,9 @@ PrintListMenuEntries:: ; 2e5a (0:2e5a)
 	ld b,$09
 	ld c,$0e
 	call ClearScreenArea
-	ld a,[wList]
+	ld a,[wListPointer]
 	ld e,a
-	ld a,[wList + 1]
+	ld a,[wListPointer + 1]
 	ld d,a
 	inc de ; de = beginning of list entries
 	ld a,[wListScrollOffset]
@@ -1756,7 +1756,7 @@ PrintListMenuEntries:: ; 2e5a (0:2e5a)
 .pokemonPCMenu
 	push hl
 	ld hl,wPartyCount
-	ld a,[wList]
+	ld a,[wListPointer]
 	cp l ; is it a list of party pokemon or box pokemon?
 	ld hl,wPartyMonNicks
 	jr z,.getPokemonName
@@ -1801,13 +1801,13 @@ PrintListMenuEntries:: ; 2e5a (0:2e5a)
 	push af
 	push hl
 	ld hl,wPartyCount
-	ld a,[wList]
+	ld a,[wListPointer]
 	cp l ; is it a list of party pokemon or box pokemon?
-	ld a,$00
+	ld a,PLAYER_PARTY_DATA
 	jr z,.next
-	ld a,$02
+	ld a,BOX_DATA
 .next
-	ld [wcc49],a
+	ld [wMonDataLocation],a
 	ld hl,wWhichPokemon
 	ld a,[hl]
 	ld b,a
@@ -1818,7 +1818,7 @@ PrintListMenuEntries:: ; 2e5a (0:2e5a)
 	add b
 	ld [hl],a
 	call LoadMonData ; load pokemon info
-	ld a,[wcc49]
+	ld a,[wMonDataLocation]
 	and a ; is it a list of party pokemon or box pokemon?
 	jr z,.skipCopyingLevel
 .copyLevel
@@ -1914,7 +1914,7 @@ GetMonName:: ; 2f9e (0:2f9e)
 	push de
 	ld bc,10
 	call CopyData
-	ld hl,wcd77
+	ld hl,wcd6d + 10
 	ld [hl], "@"
 	pop de
 	pop af
@@ -2090,7 +2090,7 @@ DisableWaitingAfterTextDisplay:: ; 30b6 (0:30b6)
 ; INPUT:
 ; [wcf91] = item ID
 ; OUTPUT:
-; [wcd6a] = success
+; [wActionResultOrTookBattleTurn] = success
 ; 00: unsucessful
 ; 01: successful
 ; 02: not able to be used right now, no extra menu displayed (only certain items use this)
@@ -2195,7 +2195,7 @@ RunNPCMovementScript:: ; 310e (0:310e)
 	ld [MBC1RomBank], a
 	ret
 .NPCMovementScriptPointerTables
-	dw ProfOakMovementScriptPointerTable
+	dw PalletMovementScriptPointerTable
 	dw PewterMuseumGuyMovementScriptPointerTable
 	dw PewterGymGuyMovementScriptPointerTable
 .playerStepOutFromDoor
@@ -2350,9 +2350,9 @@ CheckFightingMapTrainers:: ; 3219 (0:3219)
 .trainerEngaging
 	ld hl, W_FLAGS_D733
 	set 3, [hl]
-	ld [wcd4f], a
+	ld [wEmotionBubbleSpriteIndex], a
-	xor a
+	xor a ; EXCLAMATION_BUBBLE
-	ld [wcd50], a
+	ld [wWhichEmotionBubble], a
 	predef EmotionBubble
 	ld a, D_RIGHT | D_LEFT | D_UP | D_DOWN
 	ld [wJoyIgnore], a
@@ -2751,7 +2751,7 @@ SetSpriteImageIndexAfterSettingFacingDirection:: ; 34b9 (0:34b9)
 ; INPUT:
 ; hl = address of array
 ; OUTPUT:
-; [wWhichTrade] = if there is match, the matching array index
+; [wCoordIndex] = if there is match, the matching array index
 ; sets carry if the coordinates are in the array, clears carry if not
 ArePlayerCoordsInArray:: ; 34bf (0:34bf)
 	ld a,[W_YCOORD]
@@ -2762,13 +2762,13 @@ ArePlayerCoordsInArray:: ; 34bf (0:34bf)
 
 CheckCoords:: ; 34c7 (0:34c7)
 	xor a
-	ld [wWhichTrade],a
+	ld [wCoordIndex],a
 .loop
 	ld a,[hli]
 	cp a,$ff ; reached terminator?
 	jr z,.notInArray
 	push hl
-	ld hl,wWhichTrade
+	ld hl,wCoordIndex
 	inc [hl]
 	pop hl
 .compareYCoord
@@ -2792,7 +2792,7 @@ CheckCoords:: ; 34c7 (0:34c7)
 ; hl = address of array
 ; [H_SPRITEINDEX] = index of boulder sprite
 ; OUTPUT:
-; [wWhichTrade] = if there is match, the matching array index
+; [wCoordIndex] = if there is match, the matching array index
 ; sets carry if the coordinates are in the array, clears carry if not
 CheckBoulderCoords:: ; 34e4 (0:34e4)
 	push hl
@@ -2960,17 +2960,17 @@ HasEnoughCoins::
 BankswitchHome:: ; 35bc (0:35bc)
 ; switches to bank # in a
 ; Only use this when in the home bank!
-	ld [wcf09],a
+	ld [wBankswitchHomeTemp],a
 	ld a,[H_LOADEDROMBANK]
-	ld [wcf08],a
+	ld [wBankswitchHomeSavedROMBank],a
-	ld a,[wcf09]
+	ld a,[wBankswitchHomeTemp]
 	ld [H_LOADEDROMBANK],a
 	ld [MBC1RomBank],a
 	ret
 
 BankswitchBack:: ; 35cd (0:35cd)
 ; returns from BankswitchHome
-	ld a,[wcf08]
+	ld a,[wBankswitchHomeSavedROMBank]
 	ld [H_LOADEDROMBANK],a
 	ld [MBC1RomBank],a
 	ret
@@ -3043,8 +3043,8 @@ CalcDifference:: ; 3633 (0:3633)
 	ret
 
 MoveSprite:: ; 363a (0:363a)
-; move the sprite [$FF8C] with the movement pointed to by de
+; move the sprite [H_SPRITEINDEX] with the movement pointed to by de
-; actually only copies the movement data to wcc5b for later
+; actually only copies the movement data to wNPCMovementDirections for later
 	call SetSpriteMovementBytesToFF
 MoveSprite_:: ; 363d (0:363d)
 	push hl
@@ -3052,7 +3052,7 @@ MoveSprite_:: ; 363d (0:363d)
 	call GetSpriteMovementByte1Pointer
 	xor a
 	ld [hl],a
-	ld hl,wcc5b
+	ld hl,wNPCMovementDirections
 	ld c,0
 
 .loop
@@ -3078,7 +3078,7 @@ MoveSprite_:: ; 363d (0:363d)
 	ld [wWastedByteCD3A],a
 	ret
 
-; divides [$ffe5] by [$ffe6] and stores the quotient in [$ffe7]
+; divides [hDividend2] by [hDivisor2] and stores the quotient in [hQuotient2]
 DivideBytes:: ; 366b (0:366b)
 	push hl
 	ld hl, $ffe7
@@ -3538,18 +3538,18 @@ Divide:: ; 38b9 (0:38b9)
 
 ; This function is used to wait a short period after printing a letter to the
 ; screen unless the player presses the A/B button or the delay is turned off
-; through the [wd730] or [wd358] flags.
+; through the [wd730] or [wLetterPrintingDelayFlags] flags.
 PrintLetterDelay:: ; 38d3 (0:38d3)
 	ld a,[wd730]
 	bit 6,a
 	ret nz
-	ld a,[wd358]
+	ld a,[wLetterPrintingDelayFlags]
 	bit 1,a
 	ret z
 	push hl
 	push de
 	push bc
-	ld a,[wd358]
+	ld a,[wLetterPrintingDelayFlags]
 	bit 0,a
 	jr z,.waitOneFrame
 	ld a,[W_OPTIONS]
@@ -4586,8 +4586,8 @@ GivePokemon::
 	ld [wcf91], a
 	ld a, c
 	ld [W_CURENEMYLVL], a
-	xor a
+	xor a ; PLAYER_PARTY_DATA
-	ld [wcc49], a
+	ld [wMonDataLocation], a
 	ld b, BANK(_GivePokemon)
 	ld hl, _GivePokemon
 	jp Bankswitch
@@ -4656,7 +4656,7 @@ PrintPredefTextID:: ; 3ef5 (0:3ef5)
 	ld [H_DOWNARROWBLINKCNT2], a
 	ld hl, TextPredefs
 	call SetMapTextPointer
-	ld hl, wcf11
+	ld hl, wTextPredefFlag
 	set 0, [hl]
 	call DisplayTextID
 

home/init.asm

@@ -27,7 +27,7 @@ rLCDC_DEFAULT EQU %11100011
 	ld [$ff42], a
 	ld [rSB], a
 	ld [rSC], a
-	ld [$ff4b], a
+	ld [rWX], a
 	ld [$ff4a], a
 	ld [$ff06], a
 	ld [$ff07], a

home/overworld.asm

@@ -106,7 +106,7 @@ OverworldLoopLessDelay::
 	bit 0,a
 	jr nz,.checkForOpponent
 	aCoord 8, 9
-	ld [wcf0e],a
+	ld [wTilePlayerStandingOn],a ; unused?
 	call DisplayTextID ; display either the start menu or the NPC/sign text
 	ld a,[wcc47]
 	and a
@@ -1280,7 +1280,7 @@ CheckForJumpingAndTilePairCollisions:: ; 0c2a (0:0c2a)
 
 CheckForTilePairCollisions2:: ; 0c44 (0:0c44)
 	aCoord 8, 9 ; tile the player is on
-	ld [wcf0e],a
+	ld [wTilePlayerStandingOn],a
 
 CheckForTilePairCollisions:: ; 0c4a (0:0c4a)
 	ld a,[wTileInFrontOfPlayer]
@@ -1298,7 +1298,7 @@ CheckForTilePairCollisions:: ; 0c4a (0:0c4a)
 	inc hl
 	jr .tilePairCollisionLoop
 .tilesetMatches
-	ld a,[wcf0e] ; tile the player is on
+	ld a,[wTilePlayerStandingOn] ; tile the player is on
 	ld b,a
 	ld a,[hl]
 	cp b

home/text.asm

@@ -368,13 +368,13 @@ ProtectedDelay3:: ; 1b3a (0:1b3a)
 	ret
 
 TextCommandProcessor:: ; 1b40 (0:1b40)
-	ld a,[wd358]
+	ld a,[wLetterPrintingDelayFlags]
 	push af
 	set 1,a
 	ld e,a
 	ld a,[$fff4]
 	xor e
-	ld [wd358],a
+	ld [wLetterPrintingDelayFlags],a
 	ld a,c
 	ld [wcc3a],a
 	ld a,b
@@ -385,7 +385,7 @@ NextTextCommand:: ; 1b55 (0:1b55)
 	cp a, "@" ; terminator
 	jr nz,.doTextCommand
 	pop af
-	ld [wd358],a
+	ld [wLetterPrintingDelayFlags],a
 	ret
 .doTextCommand
 	push hl

hram.asm

@@ -28,6 +28,25 @@ hPartyMonIndex EQU $FF8C
 
 hHalveItemPrices EQU $FF8E
 
+hSpriteOffset2 EQU $FF8F
+
+hOAMBufferOffset EQU $FF90
+
+hSpriteScreenX EQU $FF91
+hSpriteScreenY EQU $FF92
+
+hTilePlayerStandingOn EQU $FF93
+
+hSpritePriority EQU $FF94
+
+hNPCMovementDirections2Index EQU $FF95
+
+; CalcPositionOfPlayerRelativeToNPC
+hNPCSpriteOffset EQU $FF95
+
+; temp value used when swapping bytes
+hSwapTemp EQU $FF95
+
 ; Multiplcation and division variables are meant
 ; to overlap for back-to-back usage. Big endian.
 
@@ -46,6 +65,33 @@ H_NUMTOPRINT        EQU $FF96 ; 3 bytes
 H_POWEROFTEN        EQU $FF99 ; 3 bytes
 H_SAVEDNUMTOPRINT   EQU $FF9C ; 3 bytes
 
+; distance in steps between NPC and player
+hNPCPlayerYDistance EQU $FF95
+hNPCPlayerXDistance EQU $FF96
+
+hFindPathNumSteps EQU $FF97
+
+; bit 0: set when the end of the path's Y coordinate matches the target's
+; bit 1: set when the end of the path's X coordinate matches the target's
+; When both bits are set, the end of the path is at the target's position
+; (i.e. the path has been found).
+hFindPathFlags EQU $FF98
+
+hFindPathYProgress EQU $FF99
+hFindPathXProgress EQU $FF9A
+
+; 0 = from player to NPC
+; 1 = from NPC to player
+hNPCPlayerRelativePosPerspective EQU $FF9B
+
+; bit 0:
+; 0 = target is to the south or aligned
+; 1 = target is to the north
+; bit 1:
+; 0 = target is to the east or aligned
+; 1 = target is to the west
+hNPCPlayerRelativePosFlags EQU $FF9D
+
 hSerialReceivedNewData EQU $FFA9
 
 ; $01 = using external clock
@@ -155,11 +201,23 @@ hTilesetType EQU $FFD7
 
 H_CURRENTSPRITEOFFSET EQU $FFDA ; multiple of $10
 
+hNewPartyLength EQU $FFE4
+
+hDividend2 EQU $FFE5
+hDivisor2  EQU $FFE6
+hQuotient2 EQU $FFE7
+
+hSpriteVRAMSlotAndFacing EQU $FFE9
+
+hSpriteAnimFrameCounter EQU $FFEA
+
 H_WHOSETURN EQU $FFF3 ; 0 on player’s turn, 1 on enemy’s turn
 
 ; bit 0: draw HP fraction to the right of bar instead of below (for party menu)
 ; bit 1: menu is double spaced
 hFlags_0xFFF6 EQU $FFF6
 
+hFieldMoveMonMenuTopMenuItemX EQU $FFF7
+
 hJoyInput EQU $FFF8
 

main.asm

@@ -80,7 +80,7 @@ SonyText:   db "SONY@"
 
 
 LoadMonData_:
-; Load monster [wWhichPokemon] from list [wcc49]:
+; Load monster [wWhichPokemon] from list [wMonDataLocation]:
 ;  0: partymon
 ;  1: enemymon
 ;  2: boxmon
@@ -90,8 +90,8 @@ LoadMonData_:
 
 	ld a, [wDayCareMonSpecies]
 	ld [wcf91], a
-	ld a, [wcc49]
+	ld a, [wMonDataLocation]
-	cp 3
+	cp DAYCARE_DATA
 	jr z, .GetMonHeader
 
 	ld a, [wWhichPokemon]
@@ -105,8 +105,8 @@ LoadMonData_:
 
 	ld hl, wPartyMons
 	ld bc, wPartyMon2 - wPartyMon1
-	ld a, [wcc49]
+	ld a, [wMonDataLocation]
-	cp 1
+	cp ENEMY_PARTY_DATA
 	jr c, .getMonEntry
 
 	ld hl, wEnemyMons
@@ -218,9 +218,9 @@ UpdateNonPlayerSprite:
 	ld a, [H_CURRENTSPRITEOFFSET]
 	cp b
 	jr nz, .unequal
-	jp Func_5236
+	jp DoScriptedNPCMovement
 .unequal
-	jp Func_4ed1
+	jp UpdateNPCSprite
 
 ; This detects if the current sprite (whose offset is at H_CURRENTSPRITEOFFSET)
 ; is going to collide with another sprite by looping over the other sprites.
@@ -564,7 +564,7 @@ TestBattle:
 	ld a, 20
 	ld [W_CURENEMYLVL], a
 	xor a
-	ld [wcc49], a
+	ld [wMonDataLocation], a
 	ld [W_CURMAP], a
 	call AddPartyMon
 
@@ -808,7 +808,7 @@ HandleItemListSwapping: ; 6b44 (1:6b44)
 	cp a,ITEMLISTMENU
 	jp nz,DisplayListMenuIDLoop ; only rearrange item list menus
 	push hl
-	ld hl,wList
+	ld hl,wListPointer
 	ld a,[hli]
 	ld h,[hl]
 	ld l,a
@@ -854,7 +854,7 @@ HandleItemListSwapping: ; 6b44 (1:6b44)
 	call DelayFrames
 	push hl
 	push de
-	ld hl,wList
+	ld hl,wListPointer
 	ld a,[hli]
 	ld h,[hl]
 	ld l,a
@@ -916,7 +916,7 @@ HandleItemListSwapping: ; 6b44 (1:6b44)
 	jr .done
 .combineItemSlots
 	ld [hl],a ; put the sum in the second item slot
-	ld hl,wList
+	ld hl,wListPointer
 	ld a,[hli]
 	ld h,[hl]
 	ld l,a
@@ -1090,7 +1090,7 @@ DrawStartMenu: ; 710b (1:710b)
 	ld [wTopMenuItemY],a ; Y position of first menu choice
 	ld a,$0b
 	ld [wTopMenuItemX],a ; X position of first menu choice
-	ld a,[wcc2d] ; remembered menu selection from last time
+	ld a,[wBattleAndStartSavedMenuItem] ; remembered menu selection from last time
 	ld [wCurrentMenuItem],a
 	ld [wLastMenuItem],a
 	xor a
@@ -1719,86 +1719,101 @@ TwoOptionMenuStrings: ; 7671 (1:7671)
 .HealCancelMenu ; 76d5 (1:36d5)
 	db "HEAL",$4E,"CANCEL@"
 
-DisplayFieldMoveMonMenu: ; 76e1 (1:36e1)
+DisplayFieldMoveMonMenu: ; 76e1 (1:76e1)
 	xor a
-	ld hl, wWhichTrade
+	ld hl, wFieldMoves
-	ld [hli], a
+	ld [hli], a ; wFieldMoves
-	ld [hli], a
+	ld [hli], a ; wFieldMoves + 1
-	ld [hli], a
+	ld [hli], a ; wFieldMoves + 2
-	ld [hli], a
+	ld [hli], a ; wFieldMoves + 3
-	ld [hli], a
+	ld [hli], a ; wNumFieldMoves
-	ld [hl], $c
+	ld [hl], 12 ; wFieldMovesLeftmostXCoord
 	call GetMonFieldMoves
-	ld a, [wTrainerScreenX]
+	ld a, [wNumFieldMoves]
 	and a
-	jr nz, .asm_770f
+	jr nz, .fieldMovesExist
+
+; no field moves
 	hlCoord 11, 11
-	ld b, $5
+	ld b, 5
-	ld c, $7
+	ld c, 7
 	call TextBoxBorder
 	call UpdateSprites
-	ld a, $c
+	ld a, 12
-	ld [$fff7], a
+	ld [hFieldMoveMonMenuTopMenuItemX], a
 	hlCoord 13, 12
 	ld de, PokemonMenuEntries
 	jp PlaceString
-.asm_770f
+
+.fieldMovesExist
 	push af
+
+; Calculate the text box position and dimensions based on the leftmost X coord
+; of the field move names before adjusting for the number of field moves.
 	hlCoord 0, 11
-	ld a, [wcd42]
+	ld a, [wFieldMovesLeftmostXCoord]
 	dec a
 	ld e, a
-	ld d, $0
+	ld d, 0
 	add hl, de
-	ld b, $5
+	ld b, 5
-	ld a, $12
+	ld a, 18
 	sub e
 	ld c, a
 	pop af
+
+; For each field move, move the top of the text box up 2 rows while the leaving
+; the bottom of the text box at the bottom of the screen.
 	ld de, -SCREEN_WIDTH * 2
-.asm_7725
+.textBoxHeightLoop
 	add hl, de
 	inc b
 	inc b
 	dec a
-	jr nz, .asm_7725
+	jr nz, .textBoxHeightLoop
+
+; Make space for an extra blank row above the top field move.
 	ld de, -SCREEN_WIDTH
 	add hl, de
 	inc b
+
 	call TextBoxBorder
 	call UpdateSprites
+
+; Calculate the position of the first field move name to print.
 	hlCoord 0, 12
-	ld a, [wcd42]
+	ld a, [wFieldMovesLeftmostXCoord]
 	inc a
 	ld e, a
-	ld d, $0
+	ld d, 0
 	add hl, de
 	ld de, -SCREEN_WIDTH * 2
-	ld a, [wTrainerScreenX]
+	ld a, [wNumFieldMoves]
-.asm_7747
+.calcFirstFieldMoveYLoop
 	add hl, de
 	dec a
-	jr nz, .asm_7747
+	jr nz, .calcFirstFieldMoveYLoop
+
 	xor a
-	ld [wTrainerScreenX], a
+	ld [wNumFieldMoves], a
-	ld de, wWhichTrade
+	ld de, wFieldMoves
-.asm_7752
+.printNamesLoop
 	push hl
 	ld hl, FieldMoveNames
 	ld a, [de]
 	and a
-	jr z, .asm_7776
+	jr z, .donePrintingNames
 	inc de
-	ld b, a
+	ld b, a ; index of name
-.asm_775c
+.skipNamesLoop ; skip past names before the name we want
 	dec b
-	jr z, .asm_7766
+	jr z, .reachedName
-.asm_775f
+.skipNameLoop ; skip past current name
 	ld a, [hli]
-	cp $50
+	cp "@"
-	jr nz, .asm_775f
+	jr nz, .skipNameLoop
-	jr .asm_775c
+	jr .skipNamesLoop
-.asm_7766
+.reachedName
 	ld b, h
 	ld c, l
 	pop hl
@@ -1809,16 +1824,17 @@ DisplayFieldMoveMonMenu: ; 76e1 (1:36e1)
 	ld bc, SCREEN_WIDTH * 2
 	add hl, bc
 	pop de
-	jr .asm_7752
+	jr .printNamesLoop
-.asm_7776
+
+.donePrintingNames
 	pop hl
-	ld a, [wcd42]
+	ld a, [wFieldMovesLeftmostXCoord]
-	ld [$fff7], a
+	ld [hFieldMoveMonMenuTopMenuItemX], a
 	hlCoord 0, 12
-	ld a, [wcd42]
+	ld a, [wFieldMovesLeftmostXCoord]
 	inc a
 	ld e, a
-	ld d, $0
+	ld d, 0
 	add hl, de
 	ld de, PokemonMenuEntries
 	jp PlaceString
@@ -1842,59 +1858,58 @@ PokemonMenuEntries: ; 77c2 (1:77c2)
 GetMonFieldMoves: ; 77d6 (1:77d6)
 	ld a, [wWhichPokemon]
 	ld hl, wPartyMon1Moves
-	ld bc, $2c
+	ld bc, wPartyMon2 - wPartyMon1
 	call AddNTimes
 	ld d, h
 	ld e, l
-	ld c, $5
+	ld c, NUM_MOVES + 1
-	ld hl, wWhichTrade
+	ld hl, wFieldMoves
-.asm_77e9
+.loop
 	push hl
-.asm_77ea
+.nextMove
 	dec c
-	jr z, .asm_7821
+	jr z, .done
-	ld a, [de] ; de is RAM address of move
+	ld a, [de] ; move ID
 	and a
-	jr z, .asm_7821
+	jr z, .done
 	ld b, a
-	inc de ; go to next move
+	inc de
 	ld hl, FieldMoveDisplayData
-.asm_77f6
+.fieldMoveLoop
 	ld a, [hli]
 	cp $ff
-	jr z, .asm_77ea
+	jr z, .nextMove ; if the move is not a field move
 	cp b
-	jr z, .asm_7802
+	jr z, .foundFieldMove
 	inc hl
 	inc hl
-	jr .asm_77f6
+	jr .fieldMoveLoop
-.asm_7802
+.foundFieldMove
 	ld a, b
-	ld [wcd43], a
+	ld [wLastFieldMoveID], a
-	ld a, [hli]
+	ld a, [hli] ; field move name index
-	ld b, [hl]
+	ld b, [hl] ; field move leftmost X coordinate
 	pop hl
-	ld [hli], a
+	ld [hli], a ; store name index in wFieldMoves
-	ld a, [wTrainerScreenX]
+	ld a, [wNumFieldMoves]
 	inc a
-	ld [wTrainerScreenX], a
+	ld [wNumFieldMoves], a
-	ld a, [wcd42]
+	ld a, [wFieldMovesLeftmostXCoord]
 	cp b
-	jr c, .asm_781b
+	jr c, .skipUpdatingLeftmostXCoord
 	ld a, b
-	ld [wcd42], a
+	ld [wFieldMovesLeftmostXCoord], a
-.asm_781b
+.skipUpdatingLeftmostXCoord
-	ld a, [wcd43]
+	ld a, [wLastFieldMoveID]
 	ld b, a
-	jr .asm_77e9
+	jr .loop
-.asm_7821
+.done
 	pop hl
 	ret
 
-; Format: [Move id], [list priority], [leftmost tile]
+; Format: [Move id], [name index], [leftmost tile]
 ; Move id = id of move
-; List priority = lower number means higher priority when field moves are displayed
+; Name index = index of name in FieldMoveNames
-;                 these priorities must be unique
 ; Leftmost tile = -1 + tile column in which the first letter of the move's name should be displayed
 ;                 "SOFTBOILED" is $08 because it has 4 more letters than "SURF", for example, whose value is $0C
 FieldMoveDisplayData: ; 7823 (1:7823)
@@ -2050,7 +2065,7 @@ ClearVariablesAfterLoadingMapData: ; c335 (3:4335)
 	ld [hJoyPressed], a
 	ld [hJoyReleased], a
 	ld [hJoyHeld], a
-	ld [wcd6a], a
+	ld [wActionResultOrTookBattleTurn], a
 	ld [wd5a3], a
 	ld hl, wCardKeyDoorY
 	ld [hli], a
@@ -2911,7 +2926,7 @@ RemoveItemFromInventory_: ; ce74 (3:4e74)
 	xor a
 	ld [wListScrollOffset],a
 	ld [wCurrentMenuItem],a
-	ld [wcc2c],a
+	ld [wBagSavedMenuItem],a
 	ld [wSavedListScrollOffset],a
 	pop hl
 	ld a,[hl] ; a = number of items in inventory
@@ -2973,20 +2988,20 @@ DrawBadges: ; ea03 (3:6a03)
 ; Instead of removing relevant code, the name graphics were erased.
 
 ; Tile ids for face/badge graphics.
-	ld de, wTrainerFacingDirection
+	ld de, wBadgeOrFaceTiles
 	ld hl, .FaceBadgeTiles
 	ld bc, 8
 	call CopyData
 
 ; Booleans for each badge.
-	ld hl, wcd49
+	ld hl, wTempObtainedBadgesBooleans
 	ld bc, 8
 	xor a
 	call FillMemory
 
 ; Alter these based on owned badges.
-	ld de, wcd49
+	ld de, wTempObtainedBadgesBooleans
-	ld hl, wTrainerFacingDirection
+	ld hl, wBadgeOrFaceTiles
 	ld a, [W_OBTAINEDBADGES]
 	ld b, a
 	ld c, 8
@@ -3005,17 +3020,17 @@ DrawBadges: ; ea03 (3:6a03)
 	jr nz, .CheckBadge
 
 ; Draw two rows of badges.
-	ld hl, wWhichTrade
+	ld hl, wBadgeNumberTile
 	ld a, $d8 ; [1]
 	ld [hli], a
 	ld [hl], $60 ; First name
 
 	hlCoord 2, 11
-	ld de, wcd49
+	ld de, wTempObtainedBadgesBooleans
 	call .DrawBadgeRow
 
 	hlCoord 2, 14
-	ld de, wcd49 + 4
+	ld de, wTempObtainedBadgesBooleans + 4
 ;	call .DrawBadgeRow
 ;	ret
 
@@ -3028,15 +3043,15 @@ DrawBadges: ; ea03 (3:6a03)
 	push hl
 
 ; Badge no.
-	ld a, [wWhichTrade]
+	ld a, [wBadgeNumberTile]
 	ld [hli], a
 	inc a
-	ld [wWhichTrade], a
+	ld [wBadgeNumberTile], a
 
 ; Names aren't printed if the badge is owned.
 	ld a, [de]
 	and a
-	ld a, [wTrainerEngageDistance]
+	ld a, [wBadgeNameTile]
 	jr nz, .SkipName
 	call .PlaceTiles
 	jr .PlaceBadge
@@ -3047,18 +3062,18 @@ DrawBadges: ; ea03 (3:6a03)
 	inc hl
 
 .PlaceBadge
-	ld [wTrainerEngageDistance], a
+	ld [wBadgeNameTile], a
-	ld de, 20 - 1
+	ld de, SCREEN_WIDTH - 1
 	add hl, de
-	ld a, [wTrainerFacingDirection]
+	ld a, [wBadgeOrFaceTiles]
 	call .PlaceTiles
 	add hl, de
 	call .PlaceTiles
 
 ; Shift badge array back one byte.
 	push bc
-	ld hl, wTrainerFacingDirection + 1
+	ld hl, wBadgeOrFaceTiles + 1
-	ld de, wTrainerFacingDirection
+	ld de, wBadgeOrFaceTiles
 	ld bc, 8
 	call CopyData
 	pop bc
@@ -3538,36 +3553,40 @@ ResetBoulderPushFlags: ; f2dd (3:72dd)
 	ret
 
 _AddPartyMon: ; f2e5 (3:72e5)
+; Adds a new mon to the player's or enemy's party.
+; [wMonDataLocation] is used in an unusual way in this function.
+; If the lower nybble is 0, the mon is added to the player's party, else the enemy's.
+; If the entire value is 0, then the player is allowed to name the mon.
 	ld de, wPartyCount
-	ld a, [wcc49]
+	ld a, [wMonDataLocation]
 	and $f
-	jr z, .asm_f2f2
+	jr z, .next
 	ld de, wEnemyPartyCount
-.asm_f2f2
+.next
 	ld a, [de]
 	inc a
 	cp PARTY_LENGTH + 1
-	ret nc
+	ret nc ; return if the party is already full
 	ld [de], a
 	ld a, [de]
-	ld [$ffe4], a
+	ld [hNewPartyLength], a
 	add e
 	ld e, a
-	jr nc, .asm_f300
+	jr nc, .noCarry
 	inc d
-.asm_f300
+.noCarry
 	ld a, [wcf91]
-	ld [de], a
+	ld [de], a ; write species of new mon in party list
 	inc de
-	ld a, $ff
+	ld a, $ff ; terminator
 	ld [de], a
 	ld hl, wPartyMonOT
-	ld a, [wcc49]
+	ld a, [wMonDataLocation]
 	and $f
-	jr z, .asm_f315
+	jr z, .next2
 	ld hl, wEnemyMonOT
-.asm_f315
+.next2
-	ld a, [$ffe4]
+	ld a, [hNewPartyLength]
 	dec a
 	call SkipFixedLengthTextEntries
 	ld d, h
@@ -3575,24 +3594,24 @@ _AddPartyMon: ; f2e5 (3:72e5)
 	ld hl, wPlayerName
 	ld bc, $b
 	call CopyData
-	ld a, [wcc49]
+	ld a, [wMonDataLocation]
 	and a
-	jr nz, .asm_f33f
+	jr nz, .skipNaming
 	ld hl, wPartyMonNicks
-	ld a, [$ffe4]
+	ld a, [hNewPartyLength]
 	dec a
 	call SkipFixedLengthTextEntries
 	ld a, NAME_MON_SCREEN
 	ld [wNamingScreenType], a
 	predef AskName
-.asm_f33f
+.skipNaming
 	ld hl, wPartyMons
-	ld a, [wcc49]
+	ld a, [wMonDataLocation]
 	and $f
-	jr z, .asm_f34c
+	jr z, .next3
 	ld hl, wEnemyMons
-.asm_f34c
+.next3
-	ld a, [$ffe4]
+	ld a, [hNewPartyLength]
 	dec a
 	ld bc, wPartyMon2 - wPartyMon1
 	call AddNTimes
@@ -3604,15 +3623,17 @@ _AddPartyMon: ; f2e5 (3:72e5)
 	call GetMonHeader
 	ld hl, W_MONHEADER
 	ld a, [hli]
-	ld [de], a
+	ld [de], a ; species
 	inc de
 	pop hl
 	push hl
-	ld a, [wcc49]
+	ld a, [wMonDataLocation]
 	and $f
 	ld a, $98     ; set enemy trainer mon IVs to fixed average values
 	ld b, $88
-	jr nz, .writeFreshMonData
+	jr nz, .next4
+
+; If the mon is being added to the player's party, update the pokedex.
 	ld a, [wcf91]
 	ld [wd11e], a
 	push de
@@ -3635,24 +3656,29 @@ _AddPartyMon: ; f2e5 (3:72e5)
 	pop bc
 	ld hl, wPokedexSeen
 	call FlagAction
+
 	pop hl
 	push hl
+
 	ld a, [W_ISINBATTLE]
-	and a
+	and a ; is this a wild mon caught in battle?
 	jr nz, .copyEnemyMonData
+
+; Not wild.
 	call Random ; generate random IVs
 	ld b, a
 	call Random
-.writeFreshMonData ; f3b3
+
+.next4
 	push bc
-	ld bc, $1b
+	ld bc, wPartyMon1DVs - wPartyMon1
 	add hl, bc
 	pop bc
 	ld [hli], a
 	ld [hl], b         ; write IVs
-	ld bc, $fff4
+	ld bc, (wPartyMon1HPExp - 1) - (wPartyMon1DVs + 1)
 	add hl, bc
-	ld a, $1
+	ld a, 1
 	ld c, a
 	xor a
 	ld b, a
@@ -3664,13 +3690,13 @@ _AddPartyMon: ; f2e5 (3:72e5)
 	ld [de], a
 	inc de
 	xor a
-	ld [de], a         ; level (?)
+	ld [de], a         ; box level
 	inc de
 	ld [de], a         ; status ailments
 	inc de
 	jr .copyMonTypesAndMoves
 .copyEnemyMonData
-	ld bc, $1b
+	ld bc, wPartyMon1DVs - wPartyMon1
 	add hl, bc
 	ld a, [wEnemyMonDVs] ; copy IVs from cur enemy mon
 	ld [hli], a
@@ -3683,7 +3709,7 @@ _AddPartyMon: ; f2e5 (3:72e5)
 	ld [de], a
 	inc de
 	xor a
-	ld [de], a                 ; level (?)
+	ld [de], a                ; box level
 	inc de
 	ld a, [wEnemyMonStatus]   ; copy status ailments from cur enemy mon
 	ld [de], a
@@ -3696,7 +3722,7 @@ _AddPartyMon: ; f2e5 (3:72e5)
 	ld a, [hli]       ; type 2
 	ld [de], a
 	inc de
-	ld a, [hli]       ; unused (?)
+	ld a, [hli]       ; catch rate (held item in gen 2)
 	ld [de], a
 	ld hl, W_MONHMOVES
 	ld a, [hli]
@@ -3795,7 +3821,7 @@ AddPartyMon_WriteMovePP: ; f476 (3:7476)
 	pop bc
 	pop de
 	pop hl
-	ld a, [wcd72] ; sixth move byte = pp
+	ld a, [wcd6d + 5] ; PP is byte 5 of move data
 .empty
 	inc de
 	ld [de], a
@@ -4020,7 +4046,7 @@ _MoveMon: ; f51e (3:751e)
 	push hl
 	srl a
 	add $2
-	ld [wcc49], a
+	ld [wMonDataLocation], a
 	call LoadMonData
 	callba CalcLevelFromExperience
 	ld a, d
@@ -4152,12 +4178,12 @@ HealParty:
 	push bc
 
 	ld hl, Moves
-	ld bc, $0006
+	ld bc, 6
 	call AddNTimes
 	ld de, wcd6d
 	ld a, BANK(Moves)
 	call FarCopyData
-	ld a, [wcd72] ; default pp
+	ld a, [wcd6d + 5] ; PP is byte 5 of move data
 
 	pop bc
 	pop de
@@ -4462,7 +4488,7 @@ START_MONEY EQU $3000
 	inc hl
 	ld [hl], a
 
-	ld [wcc49], a
+	ld [wMonDataLocation], a
 
 	ld hl, W_OBTAINEDBADGES
 	ld [hli], a
@@ -4506,72 +4532,75 @@ IsItemInBag_: ; f8a5 (3:78a5)
 
 FindPathToPlayer: ; f8ba (3:78ba)
 	xor a
-	ld hl, $ff97
+	ld hl, hFindPathNumSteps
-	ld [hli], a
+	ld [hli], a ; hFindPathNumSteps
-	ld [hli], a
+	ld [hli], a ; hFindPathFlags
-	ld [hli], a
+	ld [hli], a ; hFindPathYProgress
-	ld [hl], a
+	ld [hl], a  ; hFindPathXProgress
 	ld hl, wNPCMovementDirections2
 	ld de, $0
 .loop
-	ld a, [$ff99]
+	ld a, [hFindPathYProgress]
 	ld b, a
-	ld a, [$ff95] ; Y distance in steps
+	ld a, [hNPCPlayerYDistance] ; Y distance in steps
 	call CalcDifference
 	ld d, a
 	and a
 	jr nz, .asm_f8da
-	ld a, [$ff98]
+	ld a, [hFindPathFlags]
-	set 0, a
+	set 0, a ; current end of path matches the player's Y coordinate
-	ld [$ff98], a
+	ld [hFindPathFlags], a
 .asm_f8da
-	ld a, [$ff9a]
+	ld a, [hFindPathXProgress]
 	ld b, a
-	ld a, [$ff96] ; X distance in steps
+	ld a, [hNPCPlayerXDistance] ; X distance in steps
 	call CalcDifference
 	ld e, a
 	and a
 	jr nz, .asm_f8ec
-	ld a, [$ff98]
+	ld a, [hFindPathFlags]
-	set 1, a
+	set 1, a ; current end of path matches the player's X coordinate
-	ld [$ff98], a
+	ld [hFindPathFlags], a
 .asm_f8ec
-	ld a, [$ff98]
+	ld a, [hFindPathFlags]
-	cp $3
+	cp $3 ; has the end of the path reached the player's position?
 	jr z, .done
+; Compare whether the X distance between the player and the current of the path
+; is greater or if the Y distance is. Then, try to reduce whichever is greater.
 	ld a, e
 	cp d
-	jr c, .asm_f90a
+	jr c, .yDistanceGreater
-	ld a, [$ff9d]
+; x distance is greater
+	ld a, [hNPCPlayerRelativePosFlags]
 	bit 1, a
-	jr nz, .asm_f900
+	jr nz, .playerIsLeftOfNPC
 	ld d, NPC_MOVEMENT_RIGHT
-	jr .asm_f902
+	jr .next1
-.asm_f900
+.playerIsLeftOfNPC
 	ld d, NPC_MOVEMENT_LEFT
-.asm_f902
+.next1
-	ld a, [$ff9a]
+	ld a, [hFindPathXProgress]
-	add $1
+	add 1
-	ld [$ff9a], a
+	ld [hFindPathXProgress], a
-	jr .asm_f91c
+	jr .storeDirection
-.asm_f90a
+.yDistanceGreater
-	ld a, [$ff9d]
+	ld a, [hNPCPlayerRelativePosFlags]
 	bit 0, a
-	jr nz, .asm_f914
+	jr nz, .playerIsAboveNPC
 	ld d, NPC_MOVEMENT_DOWN
-	jr .asm_f916
+	jr .next2
-.asm_f914
+.playerIsAboveNPC
 	ld d, NPC_MOVEMENT_UP
-.asm_f916
+.next2
-	ld a, [$ff99]
+	ld a, [hFindPathYProgress]
-	add $1
+	add 1
-	ld [$ff99], a
+	ld [hFindPathYProgress], a
-.asm_f91c
+.storeDirection
 	ld a, d
 	ld [hli], a
-	ld a, [$ff97]
+	ld a, [hFindPathNumSteps]
 	inc a
-	ld [$ff97], a
+	ld [hFindPathNumSteps], a
 	jp .loop
 .done
 	ld [hl], $ff
@@ -4579,13 +4608,13 @@ FindPathToPlayer: ; f8ba (3:78ba)
 
 CalcPositionOfPlayerRelativeToNPC: ; f929 (3:7929)
 	xor a
-	ld [$ff9d], a
+	ld [hNPCPlayerRelativePosFlags], a
 	ld a, [wSpriteStateData1 + 4] ; player's sprite screen Y position in pixels
 	ld d, a
 	ld a, [wSpriteStateData1 + 6] ; player's sprite screen X position in pixels
 	ld e, a
 	ld hl, wSpriteStateData1
-	ld a, [$ff95] ; sprite offset
+	ld a, [hNPCSpriteOffset]
 	add l
 	add $4
 	ld l, a
@@ -4599,26 +4628,26 @@ CalcPositionOfPlayerRelativeToNPC: ; f929 (3:7929)
 	jr nc, .NPCSouthOfOrAlignedWithPlayer
 .NPCNorthOfPlayer
 	push hl
-	ld hl, $ff9d
+	ld hl, hNPCPlayerRelativePosFlags
 	bit 0, [hl]
 	set 0, [hl]
 	pop hl
 	jr .divideYDistance
 .NPCSouthOfOrAlignedWithPlayer
 	push hl
-	ld hl, $ff9d
+	ld hl, hNPCPlayerRelativePosFlags
 	bit 0, [hl]
 	res 0, [hl]
 	pop hl
 .divideYDistance
 	push hl
-	ld hl, $ffe5
+	ld hl, hDividend2
 	ld [hli], a
 	ld a, 16
 	ld [hli], a
 	call DivideBytes ; divide Y absolute distance by 16
 	ld a, [hl] ; quotient
-	ld [$ff95], a
+	ld [hNPCPlayerYDistance], a
 	pop hl
 	inc hl
 	ld b, e
@@ -4627,35 +4656,35 @@ CalcPositionOfPlayerRelativeToNPC: ; f929 (3:7929)
 	jr nc, .NPCEastOfOrAlignedWithPlayer
 .NPCWestOfPlayer
 	push hl
-	ld hl, $ff9d
+	ld hl, hNPCPlayerRelativePosFlags
 	bit 1, [hl]
 	set 1, [hl]
 	pop hl
 	jr .divideXDistance
 .NPCEastOfOrAlignedWithPlayer
 	push hl
-	ld hl, $ff9d
+	ld hl, hNPCPlayerRelativePosFlags
 	bit 1, [hl]
 	res 1, [hl]
 	pop hl
 .divideXDistance
-	ld [$ffe5], a
+	ld [hDividend2], a
 	ld a, 16
-	ld [$ffe6], a
+	ld [hDivisor2], a
 	call DivideBytes ; divide X absolute distance by 16
-	ld a, [$ffe7] ; quotient
+	ld a, [hQuotient2]
-	ld [$ff96], a
+	ld [hNPCPlayerXDistance], a
-	ld a, [$ff9b]
+	ld a, [hNPCPlayerRelativePosPerspective]
 	and a
 	ret z
-	ld a, [$ff9d]
+	ld a, [hNPCPlayerRelativePosFlags]
 	cpl
 	and $3
-	ld [$ff9d], a
+	ld [hNPCPlayerRelativePosFlags], a
 	ret
 
 ConvertNPCMovementDirectionsToJoypadMasks: ; f9a0 (3:79a0)
-	ld a, [$ff95]
+	ld a, [hNPCMovementDirections2Index]
 	ld [wNPCMovementDirections2Index], a
 	dec a
 	ld de, wSimulatedJoypadStatesEnd
@@ -4669,9 +4698,9 @@ ConvertNPCMovementDirectionsToJoypadMasks: ; f9a0 (3:79a0)
 	call ConvertNPCMovementDirectionToJoypadMask
 	ld [de], a
 	inc de
-	ld a, [$ff95]
+	ld a, [hNPCMovementDirections2Index]
 	dec a
-	ld [$ff95], a
+	ld [hNPCMovementDirections2Index], a
 	jr nz, .loop
 	ret
 

scripts/ceruleanhouse2.asm

@@ -20,11 +20,11 @@ CeruleanHouse2Text1: ; 74e15 (1d:4e15)
 	call PrintText
 	ld hl, BadgeItemList
 	call LoadItemList
-	ld hl, wStringBuffer2 + 11
+	ld hl, wItemList
 	ld a, l
-	ld [wList], a
+	ld [wListPointer], a
 	ld a, h
-	ld [wList + 1], a
+	ld [wListPointer + 1], a
 	xor a
 	ld [wPrintItemPrices], a
 	ld [wMenuItemToSwap], a

scripts/daycarem.asm

@@ -35,11 +35,11 @@ DayCareMText1: ; 56254 (15:6254)
 	pop af
 	ld hl, DayCareMText_56437
 	jp c, DayCareMScript_56409
-	callab Func_2171b
+	callab KnowsHMMove
 	ld hl, DayCareMText_5644a
 	jp c, DayCareMScript_56409
 	xor a
-	ld [wcc2b], a
+	ld [wPartyAndBillsPCSavedMenuItem], a
 	ld a, [wWhichPokemon]
 	ld hl, wPartyMonNicks
 	call GetPartyMonName
@@ -62,8 +62,8 @@ DayCareMScript_562e1: ; 562e1 (15:62e1)
 	xor a
 	ld hl, W_DAYCAREMONNAME
 	call GetPartyMonName
-	ld a, $3
+	ld a, DAYCARE_DATA
-	ld [wcc49], a
+	ld [wMonDataLocation], a
 	call LoadMonData
 	callab CalcLevelFromExperience
 	ld a, d

scripts/halloffameroom.asm

@@ -21,13 +21,13 @@ HallofFameRoomScript3: ; 5a4ba (16:64ba)
 
 HallofFameRoomScript2: ; 5a4bb (16:64bb)
 	call Delay3
-	ld a, [wd358]
+	ld a, [wLetterPrintingDelayFlags]
 	push af
 	xor a
 	ld [wJoyIgnore], a
 	predef HallOfFamePC
 	pop af
-	ld [wd358], a
+	ld [wLetterPrintingDelayFlags], a
 	ld hl, W_FLAGS_D733
 	res 1, [hl]
 	inc hl

scripts/oakslab.asm

@@ -333,14 +333,14 @@ OaksLabScript10: ; 1cd6d (7:4d6d)
 	ld [$ff8c], a
 	call DisplayTextID
 	ld a, $1
-	ld [$ff9b], a
+	ld [hNPCPlayerRelativePosPerspective], a
 	ld a, $1
 	swap a
-	ld [$ff95], a
+	ld [hNPCSpriteOffset], a
 	predef CalcPositionOfPlayerRelativeToNPC
-	ld a, [$ff95]
+	ld a, [hNPCPlayerYDistance]
 	dec a
-	ld [$ff95], a
+	ld [hNPCPlayerYDistance], a
 	predef FindPathToPlayer
 	ld de, wNPCMovementDirections2
 	ld a, $1
@@ -898,9 +898,9 @@ OaksLabMonChoiceMenu: ; 1d1b3 (7:51b3)
 	call PrintText
 	ld hl, OaksLabReceivedMonText
 	call PrintText
-	xor a
+	xor a ; PLAYER_PARTY_DATA
-	ld [wcc49], a
+	ld [wMonDataLocation], a
-	ld a, $5
+	ld a, 5
 	ld [W_CURENEMYLVL], a
 	ld a, [wcf91]
 	ld [wd11e], a

scripts/pallettown.asm

@@ -33,7 +33,7 @@ PalletTownScript0: ; 18e81 (6:4e81)
 	ld a,$FF
 	call PlaySound ; stop music
 	ld a, BANK(Music_MeetProfOak)
-	ld c,a ; song bank
+	ld c,a
 	ld a, MUSIC_MEET_PROF_OAK ; “oak appears” music
 	call PlayMusic
 	ld a,$FC
@@ -50,7 +50,7 @@ PalletTownScript1: ; 18eb2 (6:4eb2)
 	xor a
 	ld [wcf0d],a
 	ld a,1
-	ld [$FF8C],a
+	ld [hSpriteIndexOrTextID],a
 	call DisplayTextID
 	ld a,$FF
 	ld [wJoyIgnore],a
@@ -65,25 +65,25 @@ PalletTownScript1: ; 18eb2 (6:4eb2)
 
 PalletTownScript2: ; 18ed2 (6:4ed2)
 	ld a,1
-	ld [$FF8C],a
+	ld [H_SPRITEINDEX],a
-	ld a,4
+	ld a,SPRITE_FACING_UP
 	ld [$FF8D],a
 	call SetSpriteFacingDirectionAndDelay
 	call Delay3
 	ld a,1
 	ld [W_YCOORD],a
 	ld a,1
-	ld [$FF9B],a
+	ld [hNPCPlayerRelativePosPerspective],a
 	ld a,1
 	swap a
-	ld [$FF95],a
+	ld [hNPCSpriteOffset],a
 	predef CalcPositionOfPlayerRelativeToNPC
-	ld hl,$FF95
+	ld hl,hNPCPlayerYDistance
 	dec [hl]
 	predef FindPathToPlayer ; load Oak’s movement into wNPCMovementDirections2
 	ld de,wNPCMovementDirections2
 	ld a,1 ; oak
-	ld [$FF8C],a
+	ld [H_SPRITEINDEX],a
 	call MoveSprite
 	ld a,$FF
 	ld [wJoyIgnore],a
@@ -104,8 +104,9 @@ PalletTownScript3: ; 18f12 (6:4f12)
 	ld a,$FC
 	ld [wJoyIgnore],a
 	ld a,1
-	ld [$FF8C],a
+	ld [hSpriteIndexOrTextID],a
 	call DisplayTextID
+; set up movement script that causes the player to follow Oak to his lab
 	ld a,$FF
 	ld [wJoyIgnore],a
 	ld a,1
@@ -124,7 +125,7 @@ PalletTownScript3: ; 18f12 (6:4f12)
 
 PalletTownScript4: ; 18f4b (6:4f4b)
 	ld a,[wNPCMovementScriptPointerTableNum]
-	and a
+	and a ; is the movement script over?
 	ret nz
 
 	; trigger the next script
@@ -186,9 +187,9 @@ OakAppearsText: ; 18fb0 (6:4fb0)
 	ld c,10
 	call DelayFrames
 	xor a
-	ld [wcd4f],a
+	ld [wEmotionBubbleSpriteIndex],a ; player's sprite
-	ld [wcd50],a
+	ld [wWhichEmotionBubble],a ; EXCLAMATION_BUBBLE
-	predef EmotionBubble ; display ! over head
+	predef EmotionBubble
 	ld a,4
 	ld [wd528],a
 	jp TextScriptEnd

scripts/route22.asm

@@ -79,9 +79,9 @@ Route22Script0: ; 50f00 (14:4f00)
 
 .firstRivalBattle
 	ld a, $1
-	ld [wcd4f], a
+	ld [wEmotionBubbleSpriteIndex], a
-	xor a
+	xor a ; EXCLAMATION_BUBBLE
-	ld [wcd50], a
+	ld [wWhichEmotionBubble], a
 	predef EmotionBubble
 	ld a, [wWalkBikeSurfState]
 	and a
@@ -218,9 +218,9 @@ Route22Script3: ; 5102a (14:502a)
 
 Route22Script_5104e: ; 5104e (14:504e)
 	ld a, $2
-	ld [wcd4f], a
+	ld [wEmotionBubbleSpriteIndex], a
-	xor a
+	xor a ; EXCLAMATION_BUBBLE
-	ld [wcd50], a
+	ld [wWhichEmotionBubble], a
 	predef EmotionBubble
 	ld a, [wWalkBikeSurfState]
 	and a

scripts/vermiliondock.asm

@@ -167,13 +167,13 @@ VermilionDock_1dc7c: ; 1dc7c (7:5c7c)
 	ld h, $0
 	ld l, $80
 .asm_1dc86
-	ld a, [$ff44]
+	ld a, [rLY]
 	cp l
 	jr nz, .asm_1dc86
 	ld a, h
 	ld [$ff43], a
 .asm_1dc8e
-	ld a, [$ff44]
+	ld a, [rLY]
 	cp h
 	jr z, .asm_1dc8e
 	ret

sram.asm

@@ -6,7 +6,7 @@ S_SPRITEBUFFER2:: ds SPRITEBUFFERSIZE ; a310
 
 	ds $100
 
-sHallOfFame:: ds HOF_TEAM * NUM_HOF_TEAMS ; a598
+sHallOfFame:: ds HOF_TEAM * HOF_TEAM_CAPACITY ; a598
 
 
 SECTION "Save Data", SRAM, BANK[1]

text.asm

@@ -1816,7 +1816,7 @@ _MonWasStoredText:: ; 0x8a159
 	TX_RAM wcf4b
 	text " was"
 	line "stored in Box @"
-	TX_RAM wWhichTrade
+	TX_RAM wBoxNumString
 	text "."
 	prompt
 

wram.asm

@@ -236,15 +236,32 @@ wLastMenuItem:: ; cc2a
 ; id of previously selected menu item
 	ds 1
 
-; group these 3 addresses together because of an ld a,[hli]
+wPartyAndBillsPCSavedMenuItem:: ; cc2b
-wcc2b:: ds 1 ; used in party menu
+; It is mainly used by the party menu to remember the cursor position while the
-wcc2c:: ds 1 ; used in item related menus (inventory, pc)
+; menu isn't active.
-wcc2d:: ds 1 ; also used in inventory, supposed to save an item id
+; It is also used to remember the cursor position of mon lists (for the
+; withdraw/deposit/release actions) in Bill's PC so that it doesn't get lost
+; when you choose a mon from the list and a sub-menu is shown. It's reset when
+; you return to the main Bill's PC menu.
+	ds 1
+
+wBagSavedMenuItem:: ; cc2c
+; It is used by the bag list to remember the cursor position while the menu
+; isn't active.
+	ds 1
+
+wBattleAndStartSavedMenuItem:: ; cc2d
+; It is used by the start menu to remember the cursor position while the menu
+; isn't active.
+; The battle menu uses it so that the cursor position doesn't get lost when
+; a sub-menu is shown. It's reset at the start of each battle.
+	ds 1
 
 wPlayerMoveListIndex:: ; cc2e
 	ds 1
 
 wPlayerMonNumber:: ; cc2f
+; index in party of currently battling mon
 	ds 1
 
 wMenuCursorLocation:: ; cc30
@@ -326,7 +343,17 @@ wWhichTradeMonSelectionMenu:: ; cc49
 ; $00 = player mons
 ; $01 = enemy mons
 
-wcc49:: ds 1 ; used in some pokemon related stuff (some kind of species storage byte)
+wMonDataLocation:: ; cc49
+; 0 = player's party
+; 1 = enemy party
+; 2 = current box
+; 3 = daycare
+; 4 = in-battle mon
+;
+; AddPartyMon uses it slightly differently.
+; If the lower nybble is 0, the mon is added to the player's party, else the enemy's.
+; If the entire value is 0, then the player is allowed to name the mon.
+	ds 1
 
 wMenuWrappingEnabled:: ; cc4a
 ; set to 1 if you can go from the bottom to the top or top to bottom of a menu
@@ -369,6 +396,8 @@ wBoostExpByExpAll:: ; cc5b
 wAnimationType:: ; cc5b
 ; values between 0-6. Shake screen horizontally, shake screen vertically, blink Pokemon...
 
+wNPCMovementDirections:: ; cc5b
+
 wcc5b:: ds 1 ; these upcoming values below are miscellaneous storage values
 wcc5c:: ds 1 ; used in pokedex evaluation as well
 wcc5d:: ds 1 ; used in pokedex evaluation
@@ -388,7 +417,9 @@ wSwitchPartyMonTempBuffer:: ; cc97
 ; temporary buffer when swapping party mon data
 	ds 10
 
-wcca1:: ds 49 ; used in overworld npc movement
+wNumStepsToTake:: ; cca1
+; used in Pallet Town scripted movement
+	ds 49
 
 wRLEByteCount:: ; ccd2
 	ds 1
@@ -398,6 +429,8 @@ wSimulatedJoypadStatesEnd:: ; ccd3
 ; the list starts above this address and extends downwards in memory until here
 ; overloaded with below labels
 
+wParentMenuItem:: ; ccd3
+
 wccd3:: ds 1 ; used in battle, pokemon, PC and game corner stuff
 wForceEvolution::
 wccd4:: ds 1 ; has a direct reference for simulated joypad stuff in vermillion and seafoam
@@ -601,6 +634,32 @@ wOverrideSimulatedJoypadStatesMask:: ; cd3b
 
 	ds 1
 
+wChargeMoveNum:: ; cd3d
+
+wCoordIndex:: ; cd3d
+
+wOptionsTextSpeedCursorX:: ; cd3d
+
+wBoxNumString:: ; cd3d
+
+wTrainerInfoTextBoxWidthPlus1:: ; cd3d
+
+wSwappedMenuItem:: ; cd3d
+
+wHoFMonSpecies:: ; cd3d
+
+wFieldMoves:: ; cd3d
+; 4 bytes
+; the current mon's field moves
+
+wBadgeNumberTile:: ; cd3d
+; tile ID of the badge number being drawn
+
+wRodResponse:: ; cd3d
+; 0 = no bite
+; 1 = bite
+; 2 = no fish on map
+
 wWhichTownMapLocation:: ; cd3d
 
 wStoppingWhichSlotMachineWheel:: ; cd3d
@@ -630,6 +689,18 @@ wWhichTrade:: ; cd3d
 wTrainerSpriteOffset:: ; cd3d
 	ds 1
 
+wOptionsBattleAnimCursorX:: ; cd3e
+
+wTrainerInfoTextBoxWidth:: ; cd3e
+
+wHoFPartyMonIndex:: ; cd3e
+
+wNumCreditsMonsDisplayed:: ; cd3e
+; the number of credits mons that have been displayed so far
+
+wBadgeNameTile:: ; cd3e
+; first tile ID of the name being drawn
+
 wFlyLocationsList:: ; cd3e
 ; 11 bytes plus $ff sentinel values at each end
 
@@ -650,6 +721,17 @@ wHiddenObjectFunctionRomBank:: ; cd3e
 wTrainerEngageDistance:: ; cd3e
 	ds 1
 
+wOptionsBattleStyleCursorX:: ; cd3f
+
+wTrainerInfoTextBoxNextRowOffset:: ; cd3f
+
+wHoFMonLevel:: ; cd3f
+
+wBadgeOrFaceTiles:: ; cd3f
+; 8 bytes
+; a list of the first tile IDs of each badge or face (depending on whether the
+; badge is owned) to be drawn on the trainer screen
+
 wSlotMachineWheel2Offset:: ; cd3f
 
 wNameOfPlayerMonToBeTraded:: ; cd3f
@@ -666,6 +748,11 @@ wTrainerFacingDirection:: ; cd3f
 wcd3f:: ; used with daycare text for money amount
 	ds 1
 
+wHoFMonOrPlayer:: ; cd40
+; show mon or show player?
+; 0 = mon
+; 1 = player
+
 wSlotMachineWheel3Offset:: ; cd40
 
 wPlayerSpinInPlaceAnimSoundID:: ; cd40
@@ -679,22 +766,30 @@ wTradedPlayerMonOT:: ; cd41
 
 wHiddenObjectX:: ; cd41
 
-wSlotMachineWinningSymbol:: ; cd42
+wSlotMachineWinningSymbol:: ; cd41
 ; the OAM tile number of the upper left corner of the winning symbol minus 2
 
+wNumFieldMoves:: ; cd41
+
 wSlotMachineWheel1BottomTile:: ; cd41
 
 wTrainerScreenX:: ; cd41
 	ds 1
 ; a lot of the uses for these values use more than the said address
 
+wHoFTeamNo:: ; cd42
+
 wSlotMachineWheel1MiddleTile:: ; cd42
 
+wFieldMovesLeftmostXCoord:: ; cd42
+
 wcd42:: ds 1 ; used in pewter center script, printing field mon moves, slot machines and HoF PC
 
-wSlotMachineWheel1TopTile:: ; cd43
+wLastFieldMoveID:: ; cd43
+; unused
 
-wcd43:: ds 1 ; slot machine stuff and GetMonFieldMoves
+wSlotMachineWheel1TopTile:: ; cd43
+	ds 1
 
 wSlotMachineWheel2BottomTile:: ; cd44
 	ds 1
@@ -709,17 +804,27 @@ wTempCoins1:: ; cd46
 wSlotMachineWheel2TopTile:: ; cd46
 	ds 1
 
-wSlotMachineWheel3BottomTile:: ; cd47
+wBattleTransitionSpiralDirection:: ; cd47
+; 0 = outward, 1 = inward
 
-wcd47:: ds 1 ; used in slot machine and spinning player sprite
+wSlotMachineWheel3BottomTile:: ; cd47
+	ds 1
 
 wSlotMachineWheel3MiddleTile:: ; cd48
 
-wcd48:: ds 1 ; same as above
+wFacingDirectionList:: ; cd48
+; 4 bytes (also, the byte before the start of the list (cd47) is used a temp
+;          variable when the list is rotated)
+; used when spinning the player's sprite
+	ds 1
 
 wSlotMachineWheel3TopTile:: ; cd49
 
-wcd49:: ds 1 ; used in slot machine, displaying the gym leaders/badges on the trainer card, and displaying the town map
+wTempObtainedBadgesBooleans::
+; 8 bytes
+; temporary list created when displaying the badges on the trainer screen
+; one byte for each badge; 0 = not obtained, 1 = obtained
+	ds 1
 
 wTempCoins2:: ; cd4a
 ; 2 bytes
@@ -727,11 +832,7 @@ wTempCoins2:: ; cd4a
 
 wPayoutCoins:: ; cd4a
 ; 2 bytes
-	ds 1
+	ds 2
-
-wcd4b:: ; cd4b
-; used in player animations
-	ds 1
 
 wTradedPlayerMonOTID:: ; cd4c
 
@@ -744,25 +845,37 @@ wSlotMachineFlags:: ; cd4c
 wSlotMachineWheel1SlipCounter:: ; cd4d
 ; wheel 1 can "slip" while this is non-zero
 
-wcd4d:: ds 1 ; used with cut and slot machine
+wCutTile:: ; cd4d
+; $3d = tree tile
+; $52 = grass tile
+	ds 1
 
 wSlotMachineWheel2SlipCounter:: ; cd4e
 ; wheel 2 can "slip" while this is non-zero
 
 wTradedEnemyMonOT:: ; cd4e
+	ds 1
 
-wcd4e:: ds 1 ; used with in-game trades and slot machine
+wSavedPlayerScreenY:: ; cd4f
 
 wSlotMachineRerollCounter:: ; cd4f
 ; The remaining number of times wheel 3 will roll down a symbol until a match is
 ; found, when winning is enabled. It's initialized to 4 each bet.
 
-wcd4f:: ds 1 ; used with in-game trades, emotion bubbles, and player animations
+wEmotionBubbleSpriteIndex:: ; cd4f
+; the index of the sprite the emotion bubble is to be displayed above
+	ds 1
+
+wWhichEmotionBubble:: ; cd50
 
 wSlotMachineBet:: ; cd50
 ; how many coins the player bet on the slot machine (1 to 3)
 
-wcd50:: ds 9 ; used with in-game trades, emotion bubbles, and player and miscellaneous sprite animations
+wSavedPlayerFacingDirection:: ; cd50
+
+wWhichAnimationOffsets:: ; cd50
+; 0 = cut animation, 1 = boulder dust animation
+	ds 9
 
 wTradedEnemyMonOTID:: ; cd59
 	ds 2
@@ -786,25 +899,49 @@ wRightGBMonSpecies:: ; cd5f
 wFlags_0xcd60:: ; cd60
 ; bit 0: is player engaged by trainer (to avoid being engaged by multiple trainers simultaneously)
 ; bit 1: boulder dust animation (from using Strength) pending
+; bit 3: using generic PC
 ; bit 5: don't play sound when A or B is pressed in menu
 ; bit 6: tried pushing against boulder once (you need to push twice before it will move)
 	ds 1
 
 	ds 9
 
-wcd6a:: ds 1 ; used as the output of the outcome of an item (successful, unsuccessful, can't be used now, etc.)
+wActionResultOrTookBattleTurn:: ; cd6a
+; This has overlapping related uses.
+; When the player tries to use an item or use certain field moves, 0 is stored
+; when the attempt fails and 1 is stored when the attempt succeeds.
+; In addition, some items store 2 for certain types of failures, but this
+; cannot happen in battle.
+; In battle, a non-zero value indicates the player has taken their turn using
+; something other than a move (e.g. using an item or switching pokemon).
+; So, when an item is successfully used in battle, this value becomes non-zero
+; and the player is not allowed to make a move and the two uses are compatible.
+	ds 1
 
 wJoyIgnore:: ; cd6b
 ; Set buttons are ignored.
 	ds 1
 
-; as well as the said function, these values are used as a buffer for PlaceString
+wDownscaledMonSize:: ; cd6c
-wcd6c:: ds 1 ; used in pokemon status screen and battle stuff
+; size of downscaled mon pic used in pokeball entering/exiting animation
-wcd6d:: ds 4 ; used solely for PlaceString
+; $00 = 5×5
-wcd71:: ds 1 ; used with pokemon status screen
+; $01 = 3×3
-wcd72:: ds 5 ; used with restoring PP
+
-wcd77:: ds 1 ; used as an end terminator for GetMonName: (@ is written to this location)
+wNumMovesMinusOne:: ; cd6c
-wcd78:: ds 9 ; also used with restoring PP
+; FormatMovesString stores the number of moves minus one here
+	ds 1
+
+wcd6d:: ds 4 ; buffer for various data
+
+wStatusScreenCurrentPP:: ; cd71
+; temp variable used to print a move's current PP on the status screen
+	ds 1
+
+	ds 6
+
+wNormalMaxPPList:: ; cd78
+; list of normal max PP (without PP up) values
+	ds 9
 
 wSerialOtherGameboyRandomNumberListBlock:: ; cd81
 ; buffer for transferring the random number list generated by the other gameboy
@@ -835,15 +972,24 @@ wHPBarHPDifference:: ; cefd
 	ds 1
 	ds 7
 
-wcf05:: ds 1 ; used with enemy using healing moves
+wAIItem:: ; cf05
-wcf06:: ds 1 ; used with healing items as a storage value to store wWhichPokemon
+; the item that the AI used
+	ds 1
+
+wUsedItemOnWhichPokemon:: ; cf05
+	ds 1
 
 wAnimSoundID:: ; cf07
 ; sound ID during battle animations
 	ds 1
 
-wcf08:: ds 1 ; used as a storage value for the bank to return to after a BankswitchHome (bankswitch in homebank)
+wBankswitchHomeSavedROMBank:: ; cf08
-wcf09:: ds 1 ; used as a temp storage value for the bank to switch to
+; used as a storage value for the bank to return to after a BankswitchHome (bankswitch in homebank)
+	ds 1
+
+wBankswitchHomeTemp:: ; cf09
+; used as a temp storage value for the bank to switch to
+	ds 1
 
 wBoughtOrSoldItemInMart:: ; cf0a
 ; 0 = nothing bought or sold in pokemart
@@ -862,7 +1008,11 @@ wAutoTextBoxDrawingControl:: ; cf0c
 	ds 1
 
 wcf0d:: ds 1 ; used with some overworld scripts (not exactly sure what it's used for)
-wcf0e:: ds 1 ; used with some overworld collison check
+
+wTilePlayerStandingOn:: ; cf0e
+; used in CheckForTilePairCollisions2 to store the tile the player is on
+	ds 1
+
 wcf0f:: ds 1 ; used with moving overworld sprites
 
 wNPCMovementScriptFunctionNum:: ; cf10
@@ -870,7 +1020,10 @@ wNPCMovementScriptFunctionNum:: ; cf10
 ; wNPCMovementScriptPointerTableNum
 	ds 1
 
-wcf11:: ds 1 ; used as a flag if the game needs to switch to the bank which the map is in when displaying a text id (flag is set during predefs)
+wTextPredefFlag:: ; cf11
+; bit 0: set when printing a text predef so that DisplayTextID doesn't switch
+;        to the current map's bank
+	ds 1
 
 wPredefParentBank:: ; cf12
 	ds 1
@@ -887,7 +1040,10 @@ wNPCMovementScriptSpriteOffset:: ; cf17
 ; sprite offset of sprite being controlled by NPC movement script
 	ds 1
 
-wcf18:: ds 2 ; used with overworld movement
+wScriptedNPCWalkCounter:: ; cf18
+	ds 1
+
+	ds 1
 
 wGBC:: ; cf1a
 	ds 1
@@ -912,15 +1068,15 @@ wGainBoostedExp:: ; cf4d
 	ds 17
 
 wGymCityName:: ; cf5f
-wStringBuffer1:: ; cf5f
+	ds 17
-	ds 16 + 1
-wGymLeaderName:: ; cf70
-wStringBuffer2:: ; cf70
-	ds 16 + 1
-wStringBuffer3:: ; cf81
-	ds 9 + 1
 
-wList:: ; cf8b
+wGymLeaderName:: ; cf70
+	ds 11
+
+wItemList:: ; cf7b
+	ds 16
+
+wListPointer:: ; cf8b
 	ds 2
 
 wcf8d:: ds 1 ; used in GetMonName
@@ -993,7 +1149,10 @@ wcfc9:: ds 1 ; also used with audio
 wcfca:: ds 1 ; also used with audio too
 
 wUpdateSpritesEnabled:: ; cfcb
-; $01 enables UpdateSprites; anything else disables it
+; $00 = causes sprites to be hidden and the value to change to $ff
+; $01 = enabled
+; $ff = disabled
+; other values aren't used
 	ds 1
 
 W_ENEMYMOVENUM:: ; cfcc
@@ -1654,7 +1813,12 @@ W_OBTAINEDBADGES:: ; d356
 
 	ds 1
 
-wd358:: ds 1 ; bit 0 set = no delay when printing text (W_OPTIONS is still checked though)
+wLetterPrintingDelayFlags:: ; d358
+; bit 0: If 0, limit the delay to 1 frame. Note that this has no effect if
+;        the delay has been disabled entirely through bit 1 of this variable
+;        or bit 6 of wd730.
+; bit 1: If 0, no delay.
+	ds 1
 
 wPlayerID:: ; d359
 	ds 2
@@ -1862,8 +2026,13 @@ wBoxItems:: ; d53b
 	ds 50 * 2
 	ds 1 ; end
 
-wd5a0:: ds 2 ; current box number
+wCurrentBoxNum:: ; d5a0
-wd5a2:: ds 1 ; number of HOF teams
+	ds 2
+
+wNumHoFTeams:: ; d5a2
+; number of HOF teams
+	ds 1
+
 wd5a3:: ds 1 ; unused? (written to when loading map data)
 
 wPlayerCoins:: ; d5a4
@@ -2183,13 +2352,16 @@ wd72c:: ; d72c
 
 wd72d:: ds 1 ; misc temp flags? (in some scripts, bit 6 and 7 set after a special battle (e.g. gym leaders) has been won)
              ; also used as a start menu flag
-wd72e:: ds 2 ; more temp misc flags, used with npc movement, main menu and other stuff
+
+wd72e::
+; bit 7: set if scripted NPC movement has been initialised
+	ds 2 ; more temp misc flags, used with npc movement, main menu and other stuff
 
 wd730::
 ; bit 0: NPC sprite being moved by script
 ; bit 5: ignore joypad input
 ; bit 6: print text with no delay between each letter
-; bit 7: set if joypad states are being simulated in the overworld
+; bit 7: set if joypad states are being simulated in the overworld or an NPC's movement is being scripted
 	ds 1
 
 	ds 1
@@ -2219,7 +2391,8 @@ wd736:: ; d736
 ; bit 0: check if the player is standing on a door and make him walk down a step if so
 ; bit 1: the player is currently stepping down from a door
 ; bit 2: standing on a warp
-; bit 6: jumping down a ledge
+; bit 6: jumping down a ledge / fishing animation
+; bit 7: player sprite spinning due to spin tiles (Rocket hidehout / Viridian Gym)
 	ds 1
 
 wCompletedInGameTradeFlags:: ; d737