documented flags and misc. fixes

12 files changed, 98 insertions, 56 deletions

diff --git a/engine/hidden_object_functions17.asm b/engine/hidden_object_functions17.asm
index 77f3eeb9..65a4669e 100755
--- a/engine/hidden_object_functions17.asm
+++ b/engine/hidden_object_functions17.asm
@@ -95,23 +95,23 @@ LinkCableHelp: ; 5dc29 (17:5c29)
 	ld hl, LinkCableHelpText1
 	call PrintText
 	xor a
-	ld [W_ANIMATIONID], a
+	ld [wMenuItemOffset], a ; not used
 	ld [wCurrentMenuItem], a
 	ld [wLastMenuItem], a
 	ld a, A_BUTTON | B_BUTTON
 	ld [wMenuWatchedKeys], a
-	ld a, $3
+	ld a, 3
 	ld [wMaxMenuItem], a
-	ld a, $2
+	ld a, 2
 	ld [wTopMenuItemY], a
-	ld a, $1
+	ld a, 1
 	ld [wTopMenuItemX], a
 .linkHelpLoop
 	ld hl, wd730
 	set 6, [hl]
 	coord hl, 0, 0
-	ld b, $8
-	ld c, $d
+	ld b, 8
+	ld c, 13
 	call TextBoxBorder
 	coord hl, 2, 2
 	ld de, HowToLinkText
@@ -122,13 +122,13 @@ LinkCableHelp: ; 5dc29 (17:5c29)
 	bit 1, a ; pressed b
 	jr nz, .exit
 	ld a, [wCurrentMenuItem]
-	cp $3 ; pressed a on "STOP READING"
+	cp 3 ; pressed a on "STOP READING"
 	jr z, .exit
 	ld hl, wd730
 	res 6, [hl]
 	ld hl, LinkCableInfoTexts
 	add a
-	ld d, $0
+	ld d, 0
 	ld e, a
 	add hl, de
 	ld a, [hli]
@@ -179,16 +179,16 @@ ViridianSchoolBlackboard: ; 5dced (17:5ced)
 	ld hl, ViridianSchoolBlackboardText1
 	call PrintText
 	xor a
-	ld [W_ANIMATIONID], a
+	ld [wMenuItemOffset], a
 	ld [wCurrentMenuItem], a
 	ld [wLastMenuItem], a
 	ld a, D_LEFT | D_RIGHT | A_BUTTON | B_BUTTON
 	ld [wMenuWatchedKeys], a
-	ld a, $2
+	ld a, 2
 	ld [wMaxMenuItem], a
-	ld a, $2
+	ld a, 2
 	ld [wTopMenuItemY], a
-	ld a, $1
+	ld a, 1
 	ld [wTopMenuItemX], a
 .blackboardLoop
 	ld hl, wd730
@@ -210,34 +210,34 @@ ViridianSchoolBlackboard: ; 5dced (17:5ced)
 	bit 4, a ; pressed right
 	jr z, .didNotPressRight
 	; move cursor to right column
-	ld a, $2
+	ld a, 2
 	ld [wMaxMenuItem], a
-	ld a, $2
+	ld a, 2
 	ld [wTopMenuItemY], a
-	ld a, $6
+	ld a, 6
 	ld [wTopMenuItemX], a
-	ld a, $3
-	ld [W_ANIMATIONID], a
+	ld a, 3 ; in the the right column, use an offset to prevent overlap
+	ld [wMenuItemOffset], a
 	jr .blackboardLoop
 .didNotPressRight
 	bit 5, a ; pressed left
 	jr z, .didNotPressLeftOrRight
 	; move cursor to left column
-	ld a, $2
+	ld a, 2
 	ld [wMaxMenuItem], a
-	ld a, $2
+	ld a, 2
 	ld [wTopMenuItemY], a
-	ld a, $1
+	ld a, 1
 	ld [wTopMenuItemX], a
 	xor a
-	ld [W_ANIMATIONID], a
+	ld [wMenuItemOffset], a
 	jr .blackboardLoop
 .didNotPressLeftOrRight
 	ld a, [wCurrentMenuItem]
 	ld b, a
-	ld a, [W_ANIMATIONID]
+	ld a, [wMenuItemOffset]
 	add b
-	cp $5 ; cursor is pointing to "QUIT"
+	cp 5 ; cursor is pointing to "QUIT"
 	jr z, .exitBlackboard
 	; we must have pressed a on a status condition
 	; so print the text
@@ -245,7 +245,7 @@ ViridianSchoolBlackboard: ; 5dced (17:5ced)
 	res 6, [hl]
 	ld hl, ViridianBlackboardStatusPointers
 	add a
-	ld d, $0
+	ld d, 0
 	ld e, a
 	add hl, de
 	ld a, [hli]
diff --git a/engine/hidden_object_functions7.asm b/engine/hidden_object_functions7.asm
index 02d3928a..0c1e2be2 100755
--- a/engine/hidden_object_functions7.asm
+++ b/engine/hidden_object_functions7.asm
@@ -147,7 +147,7 @@ CinnabarGymQuiz: ; 1ea25 (7:6a25)
 	ld h, [hl]
 	ld l, a
 	call PrintText
-	ld a, $1
+	ld a, 1
 	ld [wDoNotWaitForButtonPressAfterDisplayingText], a
 	call CinnabarGymQuiz_1ea92
 	jp TextScriptEnd
@@ -391,23 +391,23 @@ BillsHousePokemonList: ; 1ec05 (7:6c05)
 	ld hl, BillsHousePokemonListText1
 	call PrintText
 	xor a
-	ld [W_ANIMATIONID], a
+	ld [wMenuItemOffset], a ; not used
 	ld [wCurrentMenuItem], a
 	ld [wLastMenuItem], a
 	ld a, A_BUTTON | B_BUTTON
 	ld [wMenuWatchedKeys], a
-	ld a, $4
+	ld a, 4
 	ld [wMaxMenuItem], a
-	ld a, $2
+	ld a, 2
 	ld [wTopMenuItemY], a
-	ld a, $1
+	ld a, 1
 	ld [wTopMenuItemX], a
 .billsPokemonLoop
 	ld hl, wd730
 	set 6, [hl]
 	coord hl, 0, 0
-	ld b, $a
-	ld c, $9
+	ld b, 10
+	ld c, 9
 	call TextBoxBorder
 	coord hl, 2, 2
 	ld de, BillsMonListText
diff --git a/engine/items/items.asm b/engine/items/items.asm
index f0666587..e8fe55f4 100755
--- a/engine/items/items.asm
+++ b/engine/items/items.asm
@@ -1421,7 +1421,7 @@ ItemUseCardKey: ; e022 (3:6022)
 	xor a
 	ld [wUnusedD71F],a
 	call GetTileAndCoordsInFrontOfPlayer
-	ld a,[GetTileAndCoordsInFrontOfPlayer] ; $4586
+	ld a,[GetTileAndCoordsInFrontOfPlayer]
 	cp a,$18
 	jr nz,.next0
 	ld hl,CardKeyTable1
diff --git a/engine/menu/main_menu.asm b/engine/menu/main_menu.asm
index 6c109cec..78830093 100755
--- a/engine/menu/main_menu.asm
+++ b/engine/menu/main_menu.asm
@@ -20,7 +20,7 @@ MainMenu: ; 5af2 (1:5af2)
 	ld [hli],a
 	ld [hli],a
 	ld [hl],a
-	ld [W_ANIMATIONID],a
+	ld [wDefaultMap],a
 	ld hl,wd72e
 	res 6,[hl]
 	call ClearScreen
@@ -269,7 +269,7 @@ LinkMenu: ; 5c0a (1:5c0a)
 	call DelayFrames
 	ld hl, wd732
 	res 1, [hl]
-	ld a, [W_ANIMATIONID]
+	ld a, [wDefaultMap]
 	ld [wDestinationMap], a
 	call SpecialWarpIn
 	ld c, 20
diff --git a/engine/menu/naming_screen.asm b/engine/menu/naming_screen.asm
index 978216c8..703d570a 100755
--- a/engine/menu/naming_screen.asm
+++ b/engine/menu/naming_screen.asm
@@ -166,7 +166,7 @@ DisplayNamingScreen: ; 6596 (1:6596)
 	call RunDefaultPaletteCommand
 	call GBPalNormal
 	xor a
-	ld [W_SUBANIMTRANSFORM], a
+	ld [wAnimCounter], a
 	ld hl, wd730
 	res 6, [hl]
 	ld a, [W_ISINBATTLE]
diff --git a/engine/menu/start_sub_menus.asm b/engine/menu/start_sub_menus.asm
index ab8c8756..678877ef 100755
--- a/engine/menu/start_sub_menus.asm
+++ b/engine/menu/start_sub_menus.asm
@@ -160,7 +160,7 @@ StartMenu_Pokemon: ; 130a9 (4:70a9)
 .surf
 	bit 4,a ; does the player have the Soul Badge?
 	jp z,.newBadgeRequired
-	callba CheckForForcedBikeSurf
+	callba IsSurfingAllowed
 	ld hl,wd728
 	bit 1,[hl]
 	res 1,[hl]
diff --git a/engine/oak_speech.asm b/engine/oak_speech.asm
index 0de7ffad..48e8da80 100755
--- a/engine/oak_speech.asm
+++ b/engine/oak_speech.asm
@@ -48,7 +48,7 @@ OakSpeech: ; 6115 (1:6115)
 	ld a,1
 	ld [wItemQuantity],a
 	call AddItemToInventory  ; give one potion
-	ld a,[W_ANIMATIONID]
+	ld a,[wDefaultMap]
 	ld [wDestinationMap],a
 	call SpecialWarpIn
 	xor a
diff --git a/engine/overworld/movement.asm b/engine/overworld/movement.asm
index be10fd69..2ed49838 100644
--- a/engine/overworld/movement.asm
+++ b/engine/overworld/movement.asm
@@ -133,8 +133,8 @@ UpdateNPCSprite: ; 4ed1 (1:4ed1)
 	ld l, a
 	inc l
 	ld a, [hl]        ; c1x1
-	bit 7, a
-	jp nz, InitializeSpriteFacingDirection  ; c1x1 >= $80
+	bit 7, a ; is the face player flag set?
+	jp nz, MakeNPCFacePlayer
 	ld b, a
 	ld a, [wFontLoaded]
 	bit 0, a
@@ -400,10 +400,15 @@ notYetMoving: ; 5073 (1:5073)
 	ld [hl], $0             ; c1x8 = 0 (walk animation frame)
 	jp UpdateSpriteImage
 
-InitializeSpriteFacingDirection: ; 507f (1:507f)
+MakeNPCFacePlayer: ; 507f (1:507f)
+; Make an NPC face the player if the player has spoken to him or her.
+
+; Check if the behaviour of the NPC facing the player when spoken to is
+; disabled. This is only done when rubbing the S.S. Anne captain's back.
 	ld a, [wd72d]
 	bit 5, a
 	jr nz, notYetMoving
+
 	res 7, [hl]
 	ld a, [wPlayerDirection]
 	bit PLAYER_DIR_BIT_UP, a
diff --git a/home/overworld.asm b/home/overworld.asm
index 051d055e..9eafba04 100644
--- a/home/overworld.asm
+++ b/home/overworld.asm
@@ -1190,8 +1190,8 @@ IsSpriteInFrontOfPlayer2:: ; 0b6d (0:0b6d)
 	ld a,l
 	and a,$f0
 	inc a
-	ld l,a
-	set 7,[hl]
+	ld l,a ; hl = $c1x1
+	set 7,[hl] ; set flag to make the sprite face the player
 	ld a,e
 	ld [hSpriteIndexOrTextID],a
 	ret
diff --git a/main.asm b/main.asm
index c87cd1f0..73f6de47 100755
--- a/main.asm
+++ b/main.asm
@@ -548,7 +548,7 @@ TestBattle:
 	ld [W_OBTAINEDBADGES], a
 
 	ld hl, W_FLAGS_D733
-	set 0, [hl]
+	set BIT_TEST_BATTLE, [hl]
 
 	; Reset the party.
 	ld hl, wPartyCount
@@ -668,7 +668,7 @@ LoadSpecialWarpData: ; 62ff (1:62ff)
 	xor a
 	jr .done
 .notFirstMap
-	ld a, [wLastMap]
+	ld a, [wLastMap] ; this value is overwritten before it's ever read
 	ld hl, wd732
 	bit 4, [hl] ; used dungeon warp (jumped down hole/waterfall)?
 	jr nz, .usedDunegonWarp
@@ -2751,7 +2751,10 @@ CanMoveBouldersText: ; cdbb (3:4dbb)
 	TX_FAR _CanMoveBouldersText
 	db "@"
 
-CheckForForcedBikeSurf: ; cdc0 (3:4dc0)
+IsSurfingAllowed: ; cdc0 (3:4dc0)
+; Returns whether surfing is allowed in bit of d728.
+; Surfing isn't allowed on the Cycling Road or in the lowest level of the
+; Seafoam Islands before the current has been slowed with boulders.
 	ld hl, wd728
 	set 1, [hl]
 	ld a, [wd732]
diff --git a/scripts/halloffameroom.asm b/scripts/halloffameroom.asm
index 1da6d3f5..de3cd779 100755
--- a/scripts/halloffameroom.asm
+++ b/scripts/halloffameroom.asm
@@ -47,11 +47,11 @@ HallofFameRoomScript2: ; 5a4bb (16:64bb)
 	ld [wLastBlackoutMap], a
 	callba SaveSAVtoSRAM
 	ld b, 5
-.asm_5a4ff
+.delayLoop
 	ld c, 600 / 5
 	call DelayFrames
 	dec b
-	jr nz, .asm_5a4ff
+	jr nz, .delayLoop
 	call WaitForTextScrollButtonPress
 	jp Init
 
diff --git a/wram.asm b/wram.asm
index cfa4cc51..9dd3fea3 100755
--- a/wram.asm
+++ b/wram.asm
@@ -1746,6 +1746,11 @@ wObjectToShow:: ; d07a
 
 	ds 1
 
+wDefaultMap:: ; d07c
+; the map you will start at when the debug bit is set
+
+wMenuItemOffset:: ; d07c
+
 W_ANIMATIONID:: ; d07c
 ; ID number of the current battle animation
 	ds 1
@@ -1789,7 +1794,7 @@ W_SUBANIMCOUNTER:: ; d087
 ; counts the number of subentries left in the current subanimation
 	ds 1
 
-wSaveFileStatus::
+wSaveFileStatus:: ; d088
 ; 1 = no save file or save file is corrupted
 ; 2 = save file exists and no corruption has been detected
 	ds 1
@@ -2921,8 +2926,14 @@ wUnusedD71F:: ; d71f
 
 	ds 8
 
-wd728::
+wd728:: ; d728
 ; bit 0: using Strength outside of battle
+; bit 1: set by IsSurfingAllowed when surfing's allowed, but the caller resets it after checking the result
+; bit 3: received Old Rod
+; bit 4: received Good Rod
+; bit 5: received Super Rod
+; bit 6: gave one of the Saffron guards a drink
+; bit 7: set by ItemUseCardKey, which is leftover code from a previous implementation of the Card Key
 	ds 1
 
 	ds 1
@@ -2936,16 +2947,36 @@ wBeatGymFlags:: ; d72a
 
 wd72c:: ; d72c
 ; bit 0: if not set, the 3 minimum steps between random battles have passed
+; bit 1: prevent audio fade out
+	ds 1
+
+wd72d:: ; d72d
+; This variable is used for temporary flags and as the destination map when
+; warping to the Trade Center or Colosseum.
+; bit 0: sprite facing directions have been initialised in the Trade Center
+; bit 3: do scripted warp (used to warp back to Lavender Town from the top of the pokemon tower)
+; bit 4: on a dungeon warp
+; bit 5: don't make NPCs face the player when spoken to
+; Bits 6 and 7 are set by scripts when starting major battles in the storyline,
+; but they do not appear to affect anything. Bit 6 is reset after all battles
+; and bit 7 is reset after trainer battles (but it's only set before trainer
+; battles anyway).
+	ds 1
+
+wd72e:: ; d72e
+; bit 0: the player has received Lapras in the Silph Co. building
+; bit 1: set in various places, but doesn't appear to have an effect
+; bit 2: the player has healed pokemon at a pokemon center at least once
+; bit 3: the player has a received a pokemon from Prof. Oak
+; bit 4: disable battles
+; bit 5: set when a battle ends and when the player blacks out in the overworld due to poison
+; bit 6: using the link feature
+; bit 7: set if scripted NPC movement has been initialised
 	ds 1
 
-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::
-; 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
+	ds 1
 
-wd730::
+wd730:: ; d730
 ; bit 0: NPC sprite being moved by script
 ; bit 5: ignore joypad input
 ; bit 6: print text with no delay between each letter
@@ -2970,6 +3001,9 @@ wd732:: ; d732
 
 W_FLAGS_D733:: ; d733
 ; bit 0: running a test battle
+; bit 1: prevent music from changing when entering new map
+; bit 2: skip the joypad check in CheckWarpsNoCollision (used for the forced warp down the waterfall in the Seafoam Islands)
+; bit 3: trainer wants to battle
 ; bit 4: use variable [W_CURMAPSCRIPT] instead of the provided index for next frame's map script (used to start battle when talking to trainers)
 ; bit 7: used fly out of battle
 	ds 1