Commented/labelled misc functions

5 files changed, 102 insertions, 93 deletions

diff --git a/engine/overworld/card_key.asm b/engine/overworld/card_key.asm
index 885932d5..c4df0d51 100755
--- a/engine/overworld/card_key.asm
+++ b/engine/overworld/card_key.asm
@@ -2,18 +2,18 @@ PrintCardKeyText: ; 52673 (14:6673)
 	ld hl, SilphCoMapList
 	ld a, [W_CURMAP]
 	ld b, a
-.asm_5267a
+.silphCoMapListLoop
 	ld a, [hli]
 	cp $ff
 	ret z
 	cp b
-	jr nz, .asm_5267a
+	jr nz, .silphCoMapListLoop
 	predef GetTileAndCoordsInFrontOfPlayer
 	ld a, [wTileInFrontOfPlayer]
 	cp $18
-	jr z, .asm_5269c
+	jr z, .cardKeyDoorInFrontOfPlayer
 	cp $24
-	jr z, .asm_5269c
+	jr z, .cardKeyDoorInFrontOfPlayer
 	ld b, a
 	ld a, [W_CURMAP]
 	cp SILPH_CO_11F
@@ -21,41 +21,41 @@ PrintCardKeyText: ; 52673 (14:6673)
 	ld a, b
 	cp $5e
 	ret nz
-.asm_5269c
+.cardKeyDoorInFrontOfPlayer
 	ld b, CARD_KEY
 	call IsItemInBag
-	jr z, .asm_526dc
-	call Func_526fd
+	jr z, .noCardKey
+	call GetCoordsInFrontOfPlayer
 	push de
 	ld a, $1
-	ld [H_DOWNARROWBLINKCNT2], a ; $ff8c
+	ld [H_DOWNARROWBLINKCNT2], a
 	call PrintPredefTextID
 	pop de
 	srl d
 	ld a, d
 	ld b, a
-	ld [wd73f], a
+	ld [wCardKeyDoorY], a
 	srl e
 	ld a, e
 	ld c, a
-	ld [wd740], a
-	ld a, [W_CURMAP] ; W_CURMAP
+	ld [wCardKeyDoorX], a
+	ld a, [W_CURMAP]
 	cp SILPH_CO_11F
-	jr nz, .asm_526c8
+	jr nz, .notSilphCo11F
 	ld a, $3
-	jr .asm_526ca
-.asm_526c8
+	jr .replaceCardKeyDoorTileBlock
+.notSilphCo11F
 	ld a, $e
-.asm_526ca
+.replaceCardKeyDoorTileBlock
 	ld [wd09f], a
-	predef Func_ee9e
+	predef ReplaceTileBlock
 	ld hl, wd126
 	set 5, [hl]
 	ld a, (SFX_1f_57 - SFX_Headers_1f) / 3
 	jp PlaySound
-.asm_526dc
+.noCardKey
 	ld a, $2
-	ld [H_DOWNARROWBLINKCNT2], a ; $ff8c
+	ld [H_DOWNARROWBLINKCNT2], a
 	jp PrintPredefTextID
 
 SilphCoMapList: ; 526e3 (14:66e3)
@@ -81,26 +81,32 @@ CardKeyFailText: ; 526f8 (14:66f8)
 	TX_FAR _CardKeyFailText
 	db "@"
 
-Func_526fd: ; 526fd (14:66fd)
-	ld a, [W_YCOORD] ; wd361
+; d = Y
+; e = X
+GetCoordsInFrontOfPlayer: ; 526fd (14:66fd)
+	ld a, [W_YCOORD]
 	ld d, a
-	ld a, [W_XCOORD] ; wd362
+	ld a, [W_XCOORD]
 	ld e, a
-	ld a, [wSpriteStateData1 + 9]
+	ld a, [wSpriteStateData1 + 9] ; player's sprite facing direction
 	and a
-	jr nz, .asm_5270d
+	jr nz, .notFacingDown
+; facing down
 	inc d
 	ret
-.asm_5270d
-	cp $4
-	jr nz, .asm_52713
+.notFacingDown
+	cp SPRITE_FACING_UP
+	jr nz, .notFacingUp
+; facing up
 	dec d
 	ret
-.asm_52713
-	cp $8
-	jr nz, .asm_52719
+.notFacingUp
+	cp SPRITE_FACING_LEFT
+	jr nz, .notFacingLeft
+; facing left
 	dec e
 	ret
-.asm_52719
+.notFacingLeft
+; facing right
 	inc e
 	ret
diff --git a/engine/overworld/cut.asm b/engine/overworld/cut.asm
index 0cbc0214..f57b6465 100755
--- a/engine/overworld/cut.asm
+++ b/engine/overworld/cut.asm
@@ -56,7 +56,7 @@ asm_ef82: ; ef82 (3:6f82)
 	call AnimateCutTree
 	ld de, CutTreeBlockSwaps ; $7100
 	call Func_f09f
-	call Func_eedc
+	call RedrawMapView
 	callba Func_79e96
 	ld a, $1
 	ld [wUpdateSpritesEnabled], a
@@ -65,7 +65,7 @@ asm_ef82: ; ef82 (3:6f82)
 	ld a, $90
 	ld [hVBlankWY], a
 	call UpdateSprites
-	jp Func_eedc
+	jp RedrawMapView
 
 UsedCutText: ; eff2 (3:6ff2)
 	TX_FAR _UsedCutText
diff --git a/engine/overworld/elevator.asm b/engine/overworld/elevator.asm
index d1d7d82a..c2191b91 100755
--- a/engine/overworld/elevator.asm
+++ b/engine/overworld/elevator.asm
@@ -41,7 +41,7 @@ ShakeElevator: ; 7bf15 (1e:7f15)
 	jp PlayDefaultMusic
 
 Func_7bf64: ; 7bf64 (1e:7f64)
-	ld hl, wd527
+	ld hl, wMapViewVRAMPointer + 1
 	ld a, [hld]
 	push af
 	ld a, [hl]
diff --git a/engine/overworld/hidden_objects.asm b/engine/overworld/hidden_objects.asm
index 1be5170c..ae67aeed 100755
--- a/engine/overworld/hidden_objects.asm
+++ b/engine/overworld/hidden_objects.asm
@@ -6,7 +6,7 @@ Func_46981: ; 46981 (11:6981)
 	ret nz
 	call ArePlayerCoordsInArray
 	ret nc
-	ld a, [wWhichTrade] ; wWhichTrade
+	ld a, [wWhichTrade]
 	ld [wWhichDungeonWarp], a
 	ld hl, wd72d
 	set 4, [hl]
@@ -14,7 +14,8 @@ Func_46981: ; 46981 (11:6981)
 	set 4, [hl]
 	ret
 
-Func_469a0: ; 469a0 (11:69a0)
+; if a hidden object was found, stores $00 in [$ffee], else stores $ff
+CheckForHiddenObject: ; 469a0 (11:69a0)
 	ld hl, $ffeb
 	xor a
 	ld [hli], a
@@ -22,107 +23,110 @@ Func_469a0: ; 469a0 (11:69a0)
 	ld [hli], a
 	ld [hl], a
 	ld de, $0
-	ld hl, HiddenObjectMaps ; $6a40
-.asm_469ae
+	ld hl, HiddenObjectMaps
+.hiddenMapLoop
 	ld a, [hli]
 	ld b, a
 	cp $ff
-	jr z, .asm_469fc
-	ld a, [W_CURMAP] ; W_CURMAP
+	jr z, .noMatch
+	ld a, [W_CURMAP]
 	cp b
-	jr z, .asm_469be
+	jr z, .foundMatchingMap
 	inc de
 	inc de
-	jr .asm_469ae
-.asm_469be
-	ld hl, HiddenObjectPointers ; $6a96
+	jr .hiddenMapLoop
+.foundMatchingMap
+	ld hl, HiddenObjectPointers
 	add hl, de
 	ld a, [hli]
 	ld h, [hl]
 	ld l, a
 	push hl
-	ld hl, wWhichTrade ; wWhichTrade
+	ld hl, wHiddenObjectFunctionArgument
 	xor a
 	ld [hli], a
 	ld [hli], a
 	ld [hl], a
 	pop hl
-.asm_469ce
+.hiddenObjectLoop
 	ld a, [hli]
 	cp $ff
-	jr z, .asm_469fc
-	ld [wTrainerScreenY], a
+	jr z, .noMatch
+	ld [wHiddenObjectY], a
 	ld b, a
 	ld a, [hli]
-	ld [wTrainerScreenX], a
+	ld [wHiddenObjectX], a
 	ld c, a
-	call Func_46a01
+	call CheckIfCoordsInFrontOfPlayerMatch
 	ld a, [$ffea]
 	and a
-	jr z, .asm_469f0
+	jr z, .foundMatchingObject
 	inc hl
 	inc hl
 	inc hl
 	inc hl
 	push hl
-	ld hl, wTrainerFacingDirection
+	ld hl, wHiddenObjectIndex
 	inc [hl]
 	pop hl
-	jr .asm_469ce
-.asm_469f0
+	jr .hiddenObjectLoop
+.foundMatchingObject
 	ld a, [hli]
-	ld [wWhichTrade], a ; wWhichTrade
+	ld [wHiddenObjectFunctionArgument], a
 	ld a, [hli]
-	ld [wTrainerEngageDistance], a
+	ld [wHiddenObjectFunctionRomBank], a
 	ld a, [hli]
 	ld h, [hl]
 	ld l, a
 	ret
-.asm_469fc
+.noMatch
 	ld a, $ff
 	ld [$ffee], a
 	ret
 
-Func_46a01: ; 46a01 (11:6a01)
-	ld a, [wSpriteStateData1 + 9]
-	cp $4
-	jr z, .asm_46a16
-	cp $8
-	jr z, .asm_46a25
-	cp $c
-	jr z, .asm_46a2b
-	ld a, [W_YCOORD] ; wd361
+; checks if the coordinates in front of the player's sprite match Y in b and X in c
+; [$ffea] = $00 if they match, $ff if they don't match
+CheckIfCoordsInFrontOfPlayerMatch: ; 46a01 (11:6a01)
+	ld a, [wSpriteStateData1 + 9] ; player's sprite facing direction
+	cp SPRITE_FACING_UP
+	jr z, .facingUp
+	cp SPRITE_FACING_LEFT
+	jr z, .facingLeft
+	cp SPRITE_FACING_RIGHT
+	jr z, .facingRight
+; facing down
+	ld a, [W_YCOORD]
 	inc a
-	jr .asm_46a1a
-.asm_46a16
-	ld a, [W_YCOORD] ; wd361
+	jr .upDownCommon
+.facingUp
+	ld a, [W_YCOORD]
 	dec a
-.asm_46a1a
+.upDownCommon
 	cp b
-	jr nz, .asm_46a3b
-	ld a, [W_XCOORD] ; wd362
+	jr nz, .didNotMatch
+	ld a, [W_XCOORD]
 	cp c
-	jr nz, .asm_46a3b
-	jr .asm_46a38
-.asm_46a25
-	ld a, [W_XCOORD] ; wd362
+	jr nz, .didNotMatch
+	jr .matched
+.facingLeft
+	ld a, [W_XCOORD]
 	dec a
-	jr .asm_46a2f
-.asm_46a2b
-	ld a, [W_XCOORD] ; wd362
+	jr .leftRightCommon
+.facingRight
+	ld a, [W_XCOORD]
 	inc a
-.asm_46a2f
+.leftRightCommon
 	cp c
-	jr nz, .asm_46a3b
-	ld a, [W_YCOORD] ; wd361
+	jr nz, .didNotMatch
+	ld a, [W_YCOORD]
 	cp b
-	jr nz, .asm_46a3b
-.asm_46a38
+	jr nz, .didNotMatch
+.matched
 	xor a
-	jr .asm_46a3d
-.asm_46a3b
+	jr .done
+.didNotMatch
 	ld a, $ff
-.asm_46a3d
+.done
 	ld [$ffea], a
 	ret
 
diff --git a/engine/overworld/npc_movement.asm b/engine/overworld/npc_movement.asm
index 07a73be6..84e39853 100755
--- a/engine/overworld/npc_movement.asm
+++ b/engine/overworld/npc_movement.asm
@@ -260,12 +260,11 @@ RLEList_PewterGymGuy: ; 1a5da (6:65da)
 	db $C0, $03
 	db $FF
 
-; XXX why would this function want to return on POKEMONTOWER_7?
-Func_1a5e7: ; 1a5e7 (6:65e7)
-	ld a, [W_CURMAP] ; W_CURMAP
+FreezeEnemyTrainerSprite: ; 1a5e7 (6:65e7)
+	ld a, [W_CURMAP]
 	cp POKEMONTOWER_7
-	ret z
-	ld hl, RivalIDs ; $6605
+	ret z ; the Rockets on Pokemon Tower 7F leave after battling, so don't freeze them
+	ld hl, RivalIDs
 	ld a, [wEngagedTrainerClass]
 	ld b, a
 .loop
@@ -273,11 +272,11 @@ Func_1a5e7: ; 1a5e7 (6:65e7)
 	cp $ff
 	jr z, .notRival
 	cp b
-	ret z
+	ret z ; the rival leaves after battling, so don't freeze him
 	jr .loop
 .notRival
 	ld a, [wSpriteIndex]
-	ld [H_DOWNARROWBLINKCNT2], a ; $ff8c
+	ld [H_SPRITEINDEX], a
 	jp SetSpriteMovementBytesToFF
 
 RivalIDs: ; 1a605 (6:6605)