Labelled and commented mostly sprite-related things

25 files changed, 236 insertions, 227 deletions

diff --git a/engine/battle/4_2.asm b/engine/battle/4_2.asm
index bdbf70c5..79594bdd 100755
--- a/engine/battle/4_2.asm
+++ b/engine/battle/4_2.asm
@@ -88,7 +88,7 @@ PickUpPayDayMoneyText: ; 1386b (4:786b)
 	db "@"
 
 Func_13870: ; 13870 (4:7870)
-	ld a, [wcc57]
+	ld a, [wNPCMovementScriptPointerTableNum]
 	and a
 	ret nz
 	ld a, [wd736]
diff --git a/engine/battle/animations.asm b/engine/battle/animations.asm
index 6df682a0..a094b34c 100755
--- a/engine/battle/animations.asm
+++ b/engine/battle/animations.asm
@@ -1411,50 +1411,50 @@ Func_79329: ; 79329 (1e:5329)
 	ld [hli], a
 	ret
 
-Func_79337: ; 79337 (1e:5337)
+AdjustOAMBlockXPos: ; 79337 (1e:5337)
 	ld l, e
 	ld h, d
 
-Func_79339: ; 79339 (1e:5339)
+AdjustOAMBlockXPos2: ; 79339 (1e:5339)
 	ld de, $4
-.asm_7933c
+.loop
 	ld a, [wd08a]
 	ld b, a
 	ld a, [hl]
 	add b
 	cp $a8
-	jr c, .asm_7934a
+	jr c, .skipPuttingEntryOffScreen
 	dec hl
 	ld a, $a0
 	ld [hli], a
-.asm_7934a
+.skipPuttingEntryOffScreen
 	ld [hl], a
 	add hl, de
 	dec c
-	jr nz, .asm_7933c
+	jr nz, .loop
 	ret
 
-Func_79350: ; 79350 (1e:5350)
+AdjustOAMBlockYPos: ; 79350 (1e:5350)
 	ld l, e
 	ld h, d
 
-Func_79352: ; 79352 (1e:5352)
+AdjustOAMBlockYPos2: ; 79352 (1e:5352)
 	ld de, $4
-.asm_79355
+.loop
 	ld a, [wd08a]
 	ld b, a
 	ld a, [hl]
 	add b
 	cp $70
-	jr c, .asm_79363
+	jr c, .skipSettingPreviousEntrysAttribute
 	dec hl
-	ld a, $a0
+	ld a, $a0 ; bug, sets previous OAM entry's attribute
 	ld [hli], a
-.asm_79363
+.skipSettingPreviousEntrysAttribute
 	ld [hl], a
 	add hl, de
 	dec c
-	jr nz, .asm_79355
+	jr nz, .loop
 	ret
 
 AnimationBlinkEnemyMon: ; 79369 (1e:5369)
diff --git a/engine/evolve_trade.asm b/engine/evolve_trade.asm
index 97c261d0..7fbd4607 100755
--- a/engine/evolve_trade.asm
+++ b/engine/evolve_trade.asm
@@ -41,4 +41,4 @@ EvolveTradeMon: ; 17d7d (5:7d7d)
 	callab TryEvolvingMon
 	xor a
 	ld [W_ISLINKBATTLE], a ; W_ISLINKBATTLE
-	jp Func_2307
+	jp PlayDefaultMusic
diff --git a/engine/evos_moves.asm b/engine/evos_moves.asm
index 90f89bce..61ddb4e7 100755
--- a/engine/evos_moves.asm
+++ b/engine/evos_moves.asm
@@ -254,7 +254,7 @@ Evolution_PartyMonLoop: ; loop over party mons
 	ret nz
 	ld a, [wd121]
 	and a
-	call nz, Func_2307
+	call nz, PlayDefaultMusic
 	ret
 
 ; checks if the evolved mon's name is different from the standard name (i.e. it has a nickname)
diff --git a/engine/hidden_object_functions7.asm b/engine/hidden_object_functions7.asm
index 848f6f3d..07cf5651 100755
--- a/engine/hidden_object_functions7.asm
+++ b/engine/hidden_object_functions7.asm
@@ -357,7 +357,7 @@ BillsHousePC: ; 1eb6e (7:6b6e)
 	ld a, (SFX_02_3a - SFX_Headers_02) / 3
 	call PlaySound
 	call WaitForSoundToFinish
-	call Func_2307
+	call PlayDefaultMusic
 	ld hl, wd7f2
 	set 3, [hl]
 	ret
diff --git a/engine/in_game_trades.asm b/engine/in_game_trades.asm
index 7f0b21c1..ad9de8b1 100755
--- a/engine/in_game_trades.asm
+++ b/engine/in_game_trades.asm
@@ -150,7 +150,7 @@ Func_71c07: ; 71c07 (1c:5c07)
 
 Func_71ca2: ; 71ca2 (1c:5ca2)
 	call GBPalWhiteOutWithDelay3
-	call Func_3dbe
+	call RestoreScreenTilesAndReloadTilePatterns
 	call ReloadTilesetTilePatterns
 	call LoadScreenTilesFromBuffer2
 	call Delay3
diff --git a/engine/items/items.asm b/engine/items/items.asm
index b45c20da..860479e7 100755
--- a/engine/items/items.asm
+++ b/engine/items/items.asm
@@ -517,7 +517,7 @@ ItemUseBicycle: ; d977 (3:5977)
 	call ItemUseReloadOverworldData
 	xor a
 	ld [wd700],a ; change player state to walking
-	call Func_2307 ; play walking music
+	call PlayDefaultMusic ; play walking music
 	ld hl,GotOffBicycleText
 	jr .printText
 .tryToGetOnBike
@@ -529,7 +529,7 @@ ItemUseBicycle: ; d977 (3:5977)
 	inc a
 	ld [wd700],a ; change player state to bicycling
 	ld hl,GotOnBicycleText
-	call Func_2307 ; play bike riding music
+	call PlayDefaultMusic ; play bike riding music
 .printText
 	jp PrintText
 
@@ -551,7 +551,7 @@ ItemUseSurfboard: ; d9b4 (3:59b4)
 	set 7,[hl]
 	ld a,2
 	ld [wd700],a ; change player state to surfing
-	call Func_2307 ; play surfing music
+	call PlayDefaultMusic ; play surfing music
 	ld hl,SurfingGotOnText
 	jp PrintText
 .tryToStopSurfing
@@ -589,28 +589,28 @@ ItemUseSurfboard: ; d9b4 (3:59b4)
 	ld [wd700],a ; change player state to walking
 	dec a
 	ld [wJoyIgnore],a
-	call Func_2307 ; play walking music
+	call PlayDefaultMusic ; play walking music
 	jp LoadWalkingPlayerSpriteGraphics
 ; uses a simulated button press to make the player move forward
 .makePlayerMoveForward
 	ld a,[wd52a] ; direction the player is going
 	bit 3,a
-	ld b,%01000000 ; Up key
+	ld b,D_UP
 	jr nz,.storeSimulatedButtonPress
 	bit 2,a
-	ld b,%10000000 ; Down key
+	ld b,D_DOWN
 	jr nz,.storeSimulatedButtonPress
 	bit 1,a
-	ld b,%00100000 ; Left key
+	ld b,D_LEFT
 	jr nz,.storeSimulatedButtonPress
-	ld b,%00010000 ; Right key
+	ld b,D_RIGHT
 .storeSimulatedButtonPress
 	ld a,b
-	ld [wccd3],a ; base address of simulated button presses
+	ld [wSimulatedJoypadStatesEnd],a
 	xor a
-	ld [wcd39],a
+	ld [wWastedByteCD39],a
 	inc a
-	ld [wcd38],a ; index of current simulated button press
+	ld [wSimulatedJoypadStatesIndex],a
 	ret
 
 SurfingGotOnText: ; da4c (3:5a4c)
@@ -1727,7 +1727,7 @@ PlayedFluteHadEffectText: ; e215 (3:6215)
 	ld a,[wc028]
 	cp a,$b8
 	jr z,.musicWaitLoop
-	call Func_2307 ; start playing normal music again
+	call PlayDefaultMusic ; start playing normal music again
 .done
 	jp TextScriptEnd ; end text
 
diff --git a/engine/menu/diploma.asm b/engine/menu/diploma.asm
index 023c6177..adf4c396 100755
--- a/engine/menu/diploma.asm
+++ b/engine/menu/diploma.asm
@@ -61,7 +61,7 @@ DisplayDiploma: ; 566e2 (15:66e2)
 	ld hl, wd730
 	res 6, [hl]
 	call GBPalWhiteOutWithDelay3
-	call Func_3dbe
+	call RestoreScreenTilesAndReloadTilePatterns
 	call Delay3
 	jp GBPalNormal
 
diff --git a/engine/menu/naming_screen.asm b/engine/menu/naming_screen.asm
index 7a0e7691..f7fc883c 100755
--- a/engine/menu/naming_screen.asm
+++ b/engine/menu/naming_screen.asm
@@ -33,7 +33,7 @@ AskName: ; 64eb (1:64eb)
 	ld a, [W_ISINBATTLE] ; W_ISINBATTLE
 	and a
 	jr nz, .asm_653e
-	call Func_3e08
+	call ReloadMapSpriteTilePatterns
 .asm_653e
 	call LoadScreenTilesFromBuffer1
 	pop hl
@@ -61,7 +61,7 @@ Func_655c: ; 655c (1:655c)
 	ld [wd07d], a
 	call DisplayNamingScreen
 	call GBPalWhiteOutWithDelay3
-	call Func_3dbe
+	call RestoreScreenTilesAndReloadTilePatterns
 	call LoadGBPal
 	ld a, [wcf4b]
 	cp $50
diff --git a/engine/menu/pokedex.asm b/engine/menu/pokedex.asm
index 63e440f8..8f4bc508 100755
--- a/engine/menu/pokedex.asm
+++ b/engine/menu/pokedex.asm
@@ -36,8 +36,8 @@ ShowPokedexMenu: ; 40000 (10:4000)
 	ld [wCurrentMenuItem],a
 	ld [wLastMenuItem],a
 	ld [$ffb7],a
-	ld [wcd3a],a
-	ld [wcd3b],a
+	ld [wWastedByteCD3A],a
+	ld [wOverrideSimulatedJoypadStatesMask],a
 	pop af
 	ld [wListScrollOffset],a
 	call GBPalWhiteOutWithDelay3
diff --git a/engine/menu/start_sub_menus.asm b/engine/menu/start_sub_menus.asm
index 6a645675..e774565a 100755
--- a/engine/menu/start_sub_menus.asm
+++ b/engine/menu/start_sub_menus.asm
@@ -25,7 +25,7 @@ StartMenu_Pokemon: ; 130a9 (4:70a9)
 	jr nc,.chosePokemon
 .exitMenu
 	call GBPalWhiteOutWithDelay3
-	call Func_3dbe
+	call RestoreScreenTilesAndReloadTilePatterns
 	call LoadGBPal
 	jp RedisplayStartMenu
 .chosePokemon
@@ -273,7 +273,7 @@ StartMenu_Pokemon: ; 130a9 (4:70a9)
 	TX_FAR _NotHealthyEnoughText
 	db "@"
 .goBackToMap
-	call Func_3dbe
+	call RestoreScreenTilesAndReloadTilePatterns
 	jp CloseTextDisplay
 .newBadgeRequired
 	ld hl,.newBadgeRequiredText
@@ -413,7 +413,7 @@ StartMenu_Item: ; 13302 (4:7302)
 	cp a,$02
 	jp z,.partyMenuNotDisplayed
 	call GBPalWhiteOutWithDelay3
-	call Func_3dbe
+	call RestoreScreenTilesAndReloadTilePatterns
 	pop af
 	ld [wcfcb],a
 	jp StartMenu_Item
@@ -790,7 +790,7 @@ SwitchPartyMon_Stats: ; 13653 (4:7653)
 	ld a, [wCurrentMenuItem] ; wCurrentMenuItem
 	call AddNTimes
 	push hl
-	ld de, wcc97
+	ld de, wSwitchPartyMonTempBuffer
 	ld bc, $2c
 	call CopyData
 	ld hl, wPartyMons
@@ -802,14 +802,14 @@ SwitchPartyMon_Stats: ; 13653 (4:7653)
 	ld bc, $2c
 	call CopyData
 	pop de
-	ld hl, wcc97
+	ld hl, wSwitchPartyMonTempBuffer
 	ld bc, $2c
 	call CopyData
 	ld hl, wPartyMonOT ; wd273
 	ld a, [wCurrentMenuItem] ; wCurrentMenuItem
 	call SkipFixedLengthTextEntries
 	push hl
-	ld de, wcc97
+	ld de, wSwitchPartyMonTempBuffer
 	ld bc, $b
 	call CopyData
 	ld hl, wPartyMonOT ; wd273
@@ -820,14 +820,14 @@ SwitchPartyMon_Stats: ; 13653 (4:7653)
 	ld bc, $b
 	call CopyData
 	pop de
-	ld hl, wcc97
+	ld hl, wSwitchPartyMonTempBuffer
 	ld bc, $b
 	call CopyData
 	ld hl, wPartyMonNicks ; wPartyMonNicks
 	ld a, [wCurrentMenuItem] ; wCurrentMenuItem
 	call SkipFixedLengthTextEntries
 	push hl
-	ld de, wcc97
+	ld de, wSwitchPartyMonTempBuffer
 	ld bc, $b
 	call CopyData
 	ld hl, wPartyMonNicks ; wPartyMonNicks
@@ -838,7 +838,7 @@ SwitchPartyMon_Stats: ; 13653 (4:7653)
 	ld bc, $b
 	call CopyData
 	pop de
-	ld hl, wcc97
+	ld hl, wSwitchPartyMonTempBuffer
 	ld bc, $b
 	call CopyData
 	ld a, [wMenuItemToSwap]
diff --git a/engine/overworld/cut.asm b/engine/overworld/cut.asm
index d4d327e7..59abe791 100755
--- a/engine/overworld/cut.asm
+++ b/engine/overworld/cut.asm
@@ -36,7 +36,7 @@ asm_ef82: ; ef82 (3:6f82)
 	set 6, [hl]
 	call GBPalWhiteOutWithDelay3
 	call ClearSprites
-	call Func_3dbe
+	call RestoreScreenTilesAndReloadTilePatterns
 	ld a, $90
 	ld [hVBlankWY], a
 	call Delay3
@@ -87,17 +87,17 @@ AnimateCutTree: ; eff7 (3:6ff7)
 	ld hl, vChars1 + $7e0
 	ld bc, (BANK(Overworld_GFX) << 8) + $02
 	call CopyVideoData
-	jr asm_f055
+	jr WriteCutTreeBoulderDustAnimationOAMBlock
 .asm_f020
 	ld hl, vChars1 + $7c0
-	call LoadCutTreeOAM
+	call LoadCutTreeAnimationTilePattern
 	ld hl, vChars1 + $7d0
-	call LoadCutTreeOAM
+	call LoadCutTreeAnimationTilePattern
 	ld hl, vChars1 + $7e0
-	call LoadCutTreeOAM
+	call LoadCutTreeAnimationTilePattern
 	ld hl, vChars1 + $7f0
-	call LoadCutTreeOAM
-	call asm_f055
+	call LoadCutTreeAnimationTilePattern
+	call WriteCutTreeBoulderDustAnimationOAMBlock
 	ld hl, wOAMBuffer + $93
 	ld de, $4
 	ld a, $30
@@ -110,26 +110,27 @@ AnimateCutTree: ; eff7 (3:6ff7)
 	jr nz, .asm_f044
 	ret
 
-LoadCutTreeOAM: ; f04c (3:704c)
+LoadCutTreeAnimationTilePattern: ; f04c (3:704c)
 	ld de, AnimationTileset2 + $60 ; $474e ; tile depicting a leaf
 	ld bc, (BANK(AnimationTileset2) << 8) + $01
 	jp CopyVideoData
-asm_f055: ; f055 (3:7055)
-	call Func_f068
+
+WriteCutTreeBoulderDustAnimationOAMBlock: ; f055 (3:7055)
+	call GetCutTreeBoulderDustAnimationOffsets
 	ld a, $9
-	ld de, CutTreeOAM ; $7060
+	ld de, CutTreeBoulderDustAnimationTilesAndAttributes
 	jp WriteOAMBlock
 
-CutTreeOAM: ; f060 (3:7060)
+CutTreeBoulderDustAnimationTilesAndAttributes: ; f060 (3:7060)
 	db $FC,$10,$FD,$10
 	db $FE,$10,$FF,$10
 
-Func_f068: ; f068 (3:7068)
+GetCutTreeBoulderDustAnimationOffsets: ; f068 (3:7068)
 	ld hl, wSpriteStateData1 + 4
-	ld a, [hli]
+	ld a, [hli] ; player's sprite screen Y position
 	ld b, a
 	inc hl
-	ld a, [hli]
+	ld a, [hli] ; player's sprite screen X position
 	ld c, a ; bc holds ypos/xpos of player's sprite
 	inc hl
 	inc hl
@@ -139,9 +140,9 @@ Func_f068: ; f068 (3:7068)
 	ld d, $0 ; de holds direction (00: down, 02: up, 04: left, 06: right)
 	ld a, [wcd50]
 	and a
-	ld hl, CutTreeAnimationOffsets ; $708f
+	ld hl, CutTreeAnimationOffsets
 	jr z, .asm_f084
-	ld hl, CutTreeAnimationOffsets2 ; $7097
+	ld hl, BoulderDustAnimationOffsets
 .asm_f084
 	add hl, de
 	ld e, [hl]
@@ -162,8 +163,7 @@ CutTreeAnimationOffsets: ; f08f (3:708f)
 	db -8, 20 ; player is facing left
 	db 24, 20 ; player is facing right
 
-CutTreeAnimationOffsets2: ; f097 (3:7097)
-; Not sure if these ever get used. CutTreeAnimationOffsets only seems to be used.
+BoulderDustAnimationOffsets: ; f097 (3:7097)
 ; Each pair represents the x and y pixels offsets from the player of where the cut tree animation should be drawn
 ; These offsets represent 2 blocks away from the player
 	db  8,  52 ; player is facing down
diff --git a/engine/overworld/cut2.asm b/engine/overworld/cut2.asm
index 08f6d651..de2b9d55 100755
--- a/engine/overworld/cut2.asm
+++ b/engine/overworld/cut2.asm
@@ -9,12 +9,12 @@ Func_79e96: ; 79e96 (1e:5e96)
 	ld a, $1
 	ld [wd08a], a
 	ld c, $2
-	call Func_79339
+	call AdjustOAMBlockXPos2
 	ld hl, wOAMBuffer + $99
 	ld a, $ff
 	ld [wd08a], a
 	ld c, $2
-	call Func_79339
+	call AdjustOAMBlockXPos2
 	ld a, [rOBP1] ; $ff49
 	xor $64
 	ld [rOBP1], a ; $ff49
@@ -37,7 +37,7 @@ Func_79e96: ; 79e96 (1e:5e96)
 	ld a, $2
 	ld [wd08a], a
 	ld c, $4
-	call Func_79352
+	call AdjustOAMBlockYPos2
 	pop bc
 	dec c
 	jr nz, .asm_79eca
@@ -49,22 +49,22 @@ Func_79eed: ; 79eed (1e:5eed)
 	ld a, $1
 	ld [wd08a], a
 	ld c, $1
-	call Func_79339
+	call AdjustOAMBlockXPos2
 	ld hl, wOAMBuffer + $95
 	ld a, $2
 	ld [wd08a], a
 	ld c, $1
-	call Func_79339
+	call AdjustOAMBlockXPos2
 	ld hl, wOAMBuffer + $99
 	ld a, $fe
 	ld [wd08a], a
 	ld c, $1
-	call Func_79339
+	call AdjustOAMBlockXPos2
 	ld hl, wOAMBuffer + $9d
 	ld a, $ff
 	ld [wd08a], a
 	ld c, $1
-	call Func_79339
+	call AdjustOAMBlockXPos2
 	ld a, [rOBP1] ; $ff49
 	xor $64
 	ld [rOBP1], a ; $ff49
diff --git a/engine/overworld/doors.asm b/engine/overworld/doors.asm
index 42ebb174..85ff58b2 100755
--- a/engine/overworld/doors.asm
+++ b/engine/overworld/doors.asm
@@ -1,26 +1,27 @@
-HandleDoors: ; 1a609 (6:6609)
+; returns whether the player is standing on a door in carry
+IsPlayerStandingOnDoor: ; 1a609 (6:6609)
 	push de
 	ld hl, DoorTileIDPointers ; $662c
 	ld a, [W_CURMAPTILESET] ; W_CURMAPTILESET
 	ld de, $3
 	call IsInArray
 	pop de
-	jr nc, .asm_1a62a
+	jr nc, .notStandingOnDoor
 	inc hl
 	ld a, [hli]
 	ld h, [hl]
 	ld l, a
-	aCoord 8, 9
+	aCoord 8, 9 ; a = lower left background tile under player's sprite
 	ld b, a
-.asm_1a621
+.loop
 	ld a, [hli]
 	and a
-	jr z, .asm_1a62a
+	jr z, .notStandingOnDoor
 	cp b
-	jr nz, .asm_1a621
+	jr nz, .loop
 	scf
 	ret
-.asm_1a62a
+.notStandingOnDoor
 	and a
 	ret
 
diff --git a/engine/overworld/elevator.asm b/engine/overworld/elevator.asm
index 10b3b003..d1d7d82a 100755
--- a/engine/overworld/elevator.asm
+++ b/engine/overworld/elevator.asm
@@ -38,7 +38,7 @@ ShakeElevator: ; 7bf15 (1e:7f15)
 	cp $b9
 	jr z, .asm_7bf57
 	call UpdateSprites
-	jp Func_2307
+	jp PlayDefaultMusic
 
 Func_7bf64: ; 7bf64 (1e:7f64)
 	ld hl, wd527
diff --git a/engine/overworld/ledges.asm b/engine/overworld/ledges.asm
index 43df82e2..21e1b567 100755
--- a/engine/overworld/ledges.asm
+++ b/engine/overworld/ledges.asm
@@ -43,12 +43,12 @@ HandleLedges: ; 1a672 (6:6672)
 	ld [wJoyIgnore], a
 	ld hl, wd736
 	set 6, [hl]
-	call Func_3486
+	call StartSimulatingJoypadStates
 	ld a, e
-	ld [wccd3], a
-	ld [wccd4], a
+	ld [wSimulatedJoypadStatesEnd], a
+	ld [wSimulatedJoypadStatesEnd + 1], a
 	ld a, $2
-	ld [wcd38], a
+	ld [wSimulatedJoypadStatesIndex], a
 	call LoadHoppingShadowOAM
 	ld a, (SFX_02_4e - SFX_Headers_02) / 3
 	call PlaySound
diff --git a/engine/overworld/movement.asm b/engine/overworld/movement.asm
index d84079ad..3b9cac7d 100644
--- a/engine/overworld/movement.asm
+++ b/engine/overworld/movement.asm
@@ -168,8 +168,8 @@ Func_4ed1: ; 4ed1 (1:4ed1)
 	ld hl, wd730
 	res 0, [hl]
 	xor a
-	ld [wcd38], a
-	ld [wcd3a], a
+	ld [wSimulatedJoypadStatesIndex], a
+	ld [wWastedByteCD3A], a
 	ret
 .asm_4f4b
 	cp $fe
@@ -493,6 +493,8 @@ CheckSpriteAvailability: ; 50dc (1:50dc)
 	cp b
 	jr c, .spriteInvisible  ; right of screen region
 .skipXVisibilityTest
+; make the sprite invisible if a text box is in front of it
+; $5F is the maximum number for map tiles
 	call getTileSpriteStandsOn
 	ld d, $60
 	ld a, [hli]
@@ -719,8 +721,8 @@ Func_5236: ; 5236 (1:5236)
 	bit 7, [hl]
 	set 7, [hl]
 	jp z, Func_52a6
-	ld hl, wcc97
-	ld a, [wcd37]
+	ld hl, wNPCMovementDirections2
+	ld a, [wNPCMovementDirections2Index]
 	add l
 	ld l, a
 	jr nc, .asm_5251
@@ -773,13 +775,13 @@ Func_5236: ; 5236 (1:5236)
 	ret nz
 	ld a, $8
 	ld [wcf18], a
-	ld hl, wcd37
+	ld hl, wNPCMovementDirections2Index
 	inc [hl]
 	ret
 
 Func_52a6: ; 52a6 (1:52a6)
 	xor a
-	ld [wcd37], a
+	ld [wNPCMovementDirections2Index], a
 	ld a, $8
 	ld [wcf18], a
 	jp Func_52c3
diff --git a/engine/overworld/npc_movement.asm b/engine/overworld/npc_movement.asm
index 2cf6fea9..e49c6af1 100755
--- a/engine/overworld/npc_movement.asm
+++ b/engine/overworld/npc_movement.asm
@@ -1,25 +1,25 @@
-Func_1a3e0: ; 1a3e0 (6:63e0)
+PlayerStepOutFromDoor: ; 1a3e0 (6:63e0)
 	ld hl, wd730
 	res 1, [hl]
-	call HandleDoors
-	jr nc, .asm_1a406
+	call IsPlayerStandingOnDoor
+	jr nc, .notStandingOnDoor
 	ld a, $fc
 	ld [wJoyIgnore], a
 	ld hl, wd736
 	set 1, [hl]
 	ld a, $1
-	ld [wcd38], a
-	ld a, $80
-	ld [wccd3], a
+	ld [wSimulatedJoypadStatesIndex], a
+	ld a, D_DOWN
+	ld [wSimulatedJoypadStatesEnd], a
 	xor a
 	ld [wSpriteStateData1 + 2], a
-	call Func_3486
+	call StartSimulatingJoypadStates
 	ret
-.asm_1a406
+.notStandingOnDoor
 	xor a
-	ld [wcd3a], a
-	ld [wcd38], a
-	ld [wccd3], a
+	ld [wWastedByteCD3A], a
+	ld [wSimulatedJoypadStatesIndex], a
+	ld [wSimulatedJoypadStatesEnd], a
 	ld hl, wd736
 	res 0, [hl]
 	res 1, [hl]
@@ -27,7 +27,7 @@ Func_1a3e0: ; 1a3e0 (6:63e0)
 	res 7, [hl]
 	ret
 
-Func_1a41d: ; 1a41d (6:641d)
+_EndNPCMovementScript: ; 1a41d (6:641d)
 	ld hl, wd730
 	res 7, [hl]
 	ld hl, wd72e
@@ -36,15 +36,15 @@ Func_1a41d: ; 1a41d (6:641d)
 	res 0, [hl]
 	res 1, [hl]
 	xor a
-	ld [wcf17], a
-	ld [wcc57], a
-	ld [wcf10], a
-	ld [wcd3a], a
-	ld [wcd38], a
-	ld [wccd3], a
+	ld [wNPCMovementScriptSpriteOffset], a
+	ld [wNPCMovementScriptPointerTableNum], a
+	ld [wNPCMovementScriptFunctionNum], a
+	ld [wWastedByteCD3A], a
+	ld [wSimulatedJoypadStatesIndex], a
+	ld [wSimulatedJoypadStatesEnd], a
 	ret
 
-PointerTable_1a442: ; 1a442 (6:6442)
+ProfOakMovementScriptPointerTable: ; 1a442 (6:6442)
 	dw Func_1a44c
 	dw Func_1a485
 	dw Func_1a4a1
@@ -58,20 +58,20 @@ Func_1a44c: ; 1a44c (6:644c)
 	jr z, .asm_1a475
 	ld b, $0
 	ld c, a
-	ld hl, wcc97
+	ld hl, wNPCMovementDirections2
 	ld a, $80
 	call FillMemory
 	ld [hl], $ff
 	ld a, [wcf13]
 	ld [H_DOWNARROWBLINKCNT2], a ; $ff8c
-	ld de, wcc97
+	ld de, wNPCMovementDirections2
 	call MoveSprite
 	ld a, $1
-	ld [wcf10], a
+	ld [wNPCMovementScriptFunctionNum], a
 	jr .asm_1a47a
 .asm_1a475
 	ld a, $3
-	ld [wcf10], a
+	ld [wNPCMovementScriptFunctionNum], a
 .asm_1a47a
 	ld hl, W_FLAGS_D733
 	set 1, [hl]
@@ -84,33 +84,33 @@ Func_1a485: ; 1a485 (6:6485)
 	bit 0, a
 	ret nz
 	ld a, [wcca1]
-	ld [wcd38], a
+	ld [wSimulatedJoypadStatesIndex], a
 	ld [$ff95], a
-	predef Func_f9a0
-	call Func_3486
+	predef ConvertNPCMovementDirectionsToJoypadMasks
+	call StartSimulatingJoypadStates
 	ld a, $2
-	ld [wcf10], a
+	ld [wNPCMovementScriptFunctionNum], a
 	ret
 
 Func_1a4a1: ; 1a4a1 (6:64a1)
-	ld a, [wcd38]
+	ld a, [wSimulatedJoypadStatesIndex]
 	and a
 	ret nz
 
 Func_1a4a6: ; 1a4a6 (6:64a6)
 	xor a
-	ld [wcd3b], a
+	ld [wOverrideSimulatedJoypadStatesMask], a
 	ld a, [wcf13]
 	swap a
-	ld [wcf17], a
+	ld [wNPCMovementScriptSpriteOffset], a
 	xor a
 	ld [wSpriteStateData2 + $06], a
-	ld hl, wccd3
+	ld hl, wSimulatedJoypadStatesEnd
 	ld de, RLEList_1a4e9
 	call DecodeRLEList
 	dec a
-	ld [wcd38], a
-	ld hl, wcc97
+	ld [wSimulatedJoypadStatesIndex], a
+	ld hl, wNPCMovementDirections2
 	ld de, RLEList_1a4dc
 	call DecodeRLEList
 	ld hl, wd72e
@@ -118,7 +118,7 @@ Func_1a4a6: ; 1a4a6 (6:64a6)
 	ld hl, wd730
 	set 7, [hl]
 	ld a, $4
-	ld [wcf10], a
+	ld [wNPCMovementScriptFunctionNum], a
 	ret
 
 RLEList_1a4dc: ; 1a4dc (6:64dc)
@@ -131,15 +131,15 @@ RLEList_1a4dc: ; 1a4dc (6:64dc)
 	db $FF
 
 RLEList_1a4e9: ; 1a4e9 (6:64e9)
-	db $40, $02
-	db $10, $03
-	db $80, $05
-	db $20, $01
-	db $80, $06
+	db D_UP, $02
+	db D_RIGHT, $03
+	db D_DOWN, $05
+	db D_LEFT, $01
+	db D_DOWN, $06
 	db $FF
 
 Func_1a4f4: ; 1a4f4 (6:64f4)
-	ld a, [wcd38]
+	ld a, [wSimulatedJoypadStatesIndex]
 	and a
 	ret nz
 	ld a, $0
@@ -149,11 +149,11 @@ Func_1a4f4: ; 1a4f4 (6:64f4)
 	res 7, [hl]
 	ld hl, wd72e
 	res 7, [hl]
-	jp Func_314e
+	jp EndNPCMovementScript
 
-PointerTable_1a510: ; 1a510 (6:6510)
+PewterMuseumGuyMovementScriptPointerTable: ; 1a510 (6:6510)
 	dw Func_1a514
-	dw Func_1a56b
+	dw PewterMovementScriptDone
 
 Func_1a514: ; 1a514 (6:6514)
 	ld a, BANK(Music_MuseumGuy)
@@ -164,30 +164,30 @@ Func_1a514: ; 1a514 (6:6514)
 	call PlaySound
 	ld a, [wcf13]
 	swap a
-	ld [wcf17], a
-	call Func_3486
-	ld hl, wccd3
+	ld [wNPCMovementScriptSpriteOffset], a
+	call StartSimulatingJoypadStates
+	ld hl, wSimulatedJoypadStatesEnd
 	ld de, RLEList_PewterMuseumPlayer
 	call DecodeRLEList
 	dec a
-	ld [wcd38], a
+	ld [wSimulatedJoypadStatesIndex], a
 	xor a
 	ld [wd12f], a
 	predef PewterGuys
-	ld hl, wcc97
+	ld hl, wNPCMovementDirections2
 	ld de, RLEList_PewterMuseumGuy
 	call DecodeRLEList
 	ld hl, wd72e
 	res 7, [hl]
 	ld a, $1
-	ld [wcf10], a
+	ld [wNPCMovementScriptFunctionNum], a
 	ret
 
 RLEList_PewterMuseumPlayer: ; 1a559 (6:6559)
-	db $00, $01
-	db $40, $03
-	db $20, $0D
-	db $40, $06
+	db 0, $01
+	db D_UP, $03
+	db D_LEFT, $0D
+	db D_UP, $06
 	db $FF
 
 RLEList_PewterMuseumGuy: ; 1a562 (6:6562)
@@ -197,19 +197,19 @@ RLEList_PewterMuseumGuy: ; 1a562 (6:6562)
 	db $80, $01
 	db $FF
 
-Func_1a56b: ; 1a56b (6:656b)
-	ld a, [wcd38]
+PewterMovementScriptDone: ; 1a56b (6:656b)
+	ld a, [wSimulatedJoypadStatesIndex]
 	and a
 	ret nz
 	ld hl, wd730
 	res 7, [hl]
 	ld hl, wd72e
 	res 7, [hl]
-	jp Func_314e
+	jp EndNPCMovementScript
 
-PointerTable_1a57d: ; 1a57d (6:657d)
+PewterGymGuyMovementScriptPointerTable: ; 1a57d (6:657d)
 	dw Func_1a581
-	dw Func_1a56b
+	dw PewterMovementScriptDone
 
 Func_1a581: ; 1a581 (6:6581)
 	ld a, BANK(Music_MuseumGuy)
@@ -220,18 +220,18 @@ Func_1a581: ; 1a581 (6:6581)
 	call PlaySound
 	ld a, [wcf13]
 	swap a
-	ld [wcf17], a
+	ld [wNPCMovementScriptSpriteOffset], a
 	xor a
 	ld [wSpriteStateData2 + $06], a
-	ld hl, wccd3
+	ld hl, wSimulatedJoypadStatesEnd
 	ld de, RLEList_PewterGymPlayer
 	call DecodeRLEList
 	dec a
-	ld [wcd38], a
+	ld [wSimulatedJoypadStatesIndex], a
 	ld a, $1
 	ld [wd12f], a
 	predef PewterGuys
-	ld hl, wcc97
+	ld hl, wNPCMovementDirections2
 	ld de, RLEList_PewterGymGuy
 	call DecodeRLEList
 	ld hl, wd72e
@@ -239,16 +239,16 @@ Func_1a581: ; 1a581 (6:6581)
 	ld hl, wd730
 	set 7, [hl]
 	ld a, $1
-	ld [wcf10], a
+	ld [wNPCMovementScriptFunctionNum], a
 	ret
 
 RLEList_PewterGymPlayer: ; 1a5cd (6:65cd)
-	db $00, $01
-	db $10, $02
-	db $80, $05
-	db $20, $0B
-	db $40, $05
-	db $20, $0F
+	db 0, $01
+	db D_RIGHT, $02
+	db D_DOWN, $05
+	db D_LEFT, $0B
+	db D_UP, $05
+	db D_LEFT, $0F
 	db $FF
 
 RLEList_PewterGymGuy: ; 1a5da (6:65da)
diff --git a/engine/overworld/pewter_guys.asm b/engine/overworld/pewter_guys.asm
index 2f3001fb..eb6dd5ac 100755
--- a/engine/overworld/pewter_guys.asm
+++ b/engine/overworld/pewter_guys.asm
@@ -1,8 +1,8 @@
 PewterGuys: ; 37ca1 (d:7ca1)
-	ld hl, wccd3
-	ld a, [wcd38]
-	dec a
-	ld [wcd38], a
+	ld hl, wSimulatedJoypadStatesEnd
+	ld a, [wSimulatedJoypadStatesIndex]
+	dec a ; this decrement causes it to overwrite the last byte before $FF in the list
+	ld [wSimulatedJoypadStatesIndex], a
 	ld d, 0
 	ld e, a
 	add hl, de
@@ -37,9 +37,9 @@ PewterGuys: ; 37ca1 (d:7ca1)
 	ret z
 	ld [de], a
 	inc de
-	ld a, [wcd38]
+	ld a, [wSimulatedJoypadStatesIndex]
 	inc a
-	ld [wcd38], a
+	ld [wSimulatedJoypadStatesIndex], a
 	jr .asm_37cd2
 .asm_37ce1
 	inc hl
diff --git a/engine/overworld/player_animations.asm b/engine/overworld/player_animations.asm
index a0d8175f..f915a2b9 100755
--- a/engine/overworld/player_animations.asm
+++ b/engine/overworld/player_animations.asm
@@ -34,7 +34,7 @@ Func_70510: ; 70510 (1c:4510)
 	ld hl, wcd48
 	call Func_70730
 .asm_70558
-	call Func_2307
+	call PlayDefaultMusic
 .asm_7055b
 	jp Func_70772
 .asm_7055e
diff --git a/engine/overworld/ssanne.asm b/engine/overworld/ssanne.asm
index 8fd8f99a..bdbbd17e 100755
--- a/engine/overworld/ssanne.asm
+++ b/engine/overworld/ssanne.asm
@@ -1,37 +1,37 @@
-Func_79f54: ; 79f54 (1e:5f54)
+AnimateBoulderDust: ; 79f54 (1e:5f54)
 	ld a, $1
-	ld [wcd50], a
+	ld [wcd50], a ; select the boulder dust offsets
 	ld a, [wcfcb]
 	push af
 	ld a, $ff
 	ld [wcfcb], a
-	ld a, $e4
-	ld [rOBP1], a ; $ff49
+	ld a, %11100100
+	ld [rOBP1], a
 	call LoadSmokeTileFourTimes
-	callba asm_f055
-	ld c, $8
-.asm_79f73
+	callba WriteCutTreeBoulderDustAnimationOAMBlock
+	ld c, 8 ; number of steps in animation
+.loop
 	push bc
-	call Func_79f92
-	ld bc, .asm_79f7e
+	call GetMoveBoulderDustFunctionPointer
+	ld bc, .returnAddress
 	push bc
 	ld c, $4
 	jp [hl]
-.asm_79f7e
-	ld a, [rOBP1] ; $ff49
-	xor $64
-	ld [rOBP1], a ; $ff49
+.returnAddress
+	ld a, [rOBP1]
+	xor %01100100
+	ld [rOBP1], a
 	call Delay3
 	pop bc
 	dec c
-	jr nz, .asm_79f73
+	jr nz, .loop
 	pop af
 	ld [wcfcb], a
 	jp LoadPlayerSpriteGraphics
 
-Func_79f92: ; 79f92 (1e:5f92)
-	ld a, [wSpriteStateData1 + 9]
-	ld hl, PointerTable_79fb0 ; $5fb0
+GetMoveBoulderDustFunctionPointer: ; 79f92 (1e:5f92)
+	ld a, [wSpriteStateData1 + 9] ; player's sprite facing direction
+	ld hl, MoveBoulderDustFunctionPointerTable
 	ld c, a
 	ld b, $0
 	add hl, bc
@@ -51,18 +51,22 @@ Func_79f92: ; 79f92 (1e:5f92)
 	pop hl
 	ret
 
-PointerTable_79fb0: ; 79fb0 (1e:5fb0)
+MoveBoulderDustFunctionPointerTable: ; 79fb0 (1e:5fb0)
+; facing down
 	db $FF,$00
-	dw Func_79350
+	dw AdjustOAMBlockYPos
 
+; facing up
 	db $01,$00
-	dw Func_79350
+	dw AdjustOAMBlockYPos
 
+; facing left
 	db $01,$01
-	dw Func_79337
+	dw AdjustOAMBlockXPos
 
+; facing right
 	db $FF,$01
-	dw Func_79337
+	dw AdjustOAMBlockXPos
 
 LoadSmokeTileFourTimes: ; 79fc0 (1e:5fc0)
 	ld hl, vChars1 + $7c0
diff --git a/engine/overworld/trainers.asm b/engine/overworld/trainers.asm
index b05ddbf1..5237df0d 100755
--- a/engine/overworld/trainers.asm
+++ b/engine/overworld/trainers.asm
@@ -1,9 +1,9 @@
-Func_567f9: ; 567f9 (15:67f9)
+_GetSpritePosition1: ; 567f9 (15:67f9)
 	ld hl, wSpriteStateData1
 	ld de, $4
 	ld a, [wcf13]
-	ld [H_DOWNARROWBLINKCNT2], a ; $ff8c
-	call Func_56903
+	ld [H_SPRITEINDEX], a
+	call GetSpriteDataPointer
 	ld a, [hli]
 	ld [$ffeb], a
 	inc hl
@@ -17,50 +17,50 @@ Func_567f9: ; 567f9 (15:67f9)
 	ld [$ffee], a
 	ret
 
-Func_56819: ; 56819 (15:6819)
+_GetSpritePosition2: ; 56819 (15:6819)
 	ld hl, wSpriteStateData1
-	ld de, $0004
+	ld de, $4
 	ld a, [wcf13]
-	ld [H_DOWNARROWBLINKCNT2], a ; $ff8c
-	call Func_56903
-	ld a, [hli]
+	ld [H_SPRITEINDEX], a
+	call GetSpriteDataPointer
+	ld a, [hli] ; c1x4 (screen Y pos)
 	ld [wd130], a
 	inc hl
-	ld a, [hl]
+	ld a, [hl] ; c1x6 (screen X pos)
 	ld [wd131], a
-	ld de, $00fe
+	ld de, $104 - $6
 	add hl, de
-	ld a, [hli]
+	ld a, [hli] ; c2x4 (map Y pos)
 	ld [wd132], a
-	ld a, [hl]
+	ld a, [hl] ; c2x5 (map X pos)
 	ld [wd133], a
 	ret
 
-Func_5683d: ; 5683d (15:683d)
+_SetSpritePosition1: ; 5683d (15:683d)
 	ld hl, wSpriteStateData1
 	ld de, $4
 	ld a, [wcf13]
-	ld [H_DOWNARROWBLINKCNT2], a ; $ff8c
-	call Func_56903
-	ld a, [$ffeb]
+	ld [H_SPRITEINDEX], a
+	call GetSpriteDataPointer
+	ld a, [$ffeb] ; c1x4 (screen Y pos)
 	ld [hli], a
 	inc hl
-	ld a, [$ffec]
+	ld a, [$ffec] ; c1x6 (screen X pos)
 	ld [hl], a
-	ld de, $fe
+	ld de, $104 - $6
 	add hl, de
-	ld a, [$ffed]
+	ld a, [$ffed] ; c2x4 (map Y pos)
 	ld [hli], a
-	ld a, [$ffee]
+	ld a, [$ffee] ; c2x5 (map X pos)
 	ld [hl], a
 	ret
 
-Func_5685d: ; 5685d (15:685d)
+_SetSpritePosition2: ; 5685d (15:685d)
 	ld hl, wSpriteStateData1
 	ld de, $0004
 	ld a, [wcf13]
-	ld [H_DOWNARROWBLINKCNT2], a ; $ff8c
-	call Func_56903
+	ld [H_SPRITEINDEX], a
+	call GetSpriteDataPointer
 	ld a, [wd130]
 	ld [hli], a
 	inc hl
@@ -139,18 +139,20 @@ TrainerWalkUpToPlayer: ; 56881 (15:6881)
 	ld b, $0
 	ld a, $80           ; a = direction to go to
 .writeWalkScript
-	ld hl, wcc97
-	ld de, wcc97
+	ld hl, wNPCMovementDirections2
+	ld de, wNPCMovementDirections2
 	call FillMemory     ; write the necessary steps to reach player
 	ld [hl], $ff        ; write end of list sentinel
 	ld a, [wcf13]
-	ld [H_DOWNARROWBLINKCNT2], a ; $ff8c
+	ld [H_SPRITEINDEX], a
 	jp MoveSprite_
 
-Func_56903: ; 56903 (15:6903)
+; input: de = offset within sprite entry
+; output: de = pointer to sprite data
+GetSpriteDataPointer: ; 56903 (15:6903)
 	push de
 	add hl, de
-	ld a, [H_DOWNARROWBLINKCNT2] ; $ff8c
+	ld a, [H_SPRITEINDEX]
 	swap a
 	ld d, $0
 	ld e, a
diff --git a/engine/predefs.asm b/engine/predefs.asm
index 669d77f4..c492a206 100755
--- a/engine/predefs.asm
+++ b/engine/predefs.asm
@@ -84,10 +84,10 @@ PredefPointers:: ; 4fe79 (13:7e79)
 	dbw $03,Func_3eb5 ; for these two, the bank number is actually 0
 	dbw $03,GiveItem
 	add_predef Func_480eb
-	add_predef Func_f8ba
+	add_predef FindPathToPlayer
 	add_predef Func_480ff
-	add_predef Func_f929
-	add_predef Func_f9a0
+	add_predef CalcPositionOfPlayerRelativeToNPC
+	add_predef ConvertNPCMovementDirectionsToJoypadMasks
 	add_predef Func_48125
 	add_predef UpdateHPBar
 	add_predef HPBarLength
diff --git a/engine/slot_machine.asm b/engine/slot_machine.asm
index e43cc9ab..ed6f52fb 100755
--- a/engine/slot_machine.asm
+++ b/engine/slot_machine.asm
@@ -42,7 +42,7 @@ PromptUserToPlaySlots: ; 3730e (d:730e)
 	ld a, $1
 	ld [wcfcb], a
 	call GoPAL_SET_CF1C
-	call Func_3e08
+	call ReloadMapSpriteTilePatterns
 	call ReloadTilesetTilePatterns
 .skip
 	call LoadScreenTilesFromBuffer2
diff --git a/engine/turn_sprite.asm b/engine/turn_sprite.asm
index ecd8cf02..84037cfe 100755
--- a/engine/turn_sprite.asm
+++ b/engine/turn_sprite.asm
@@ -1,25 +1,25 @@
-Func_13074: ; 13074 (4:7074)
+UpdateSpriteFacingOffsetAndDelayMovement: ; 13074 (4:7074)
 	ld h, $c2
 	ld a, [H_CURRENTSPRITEOFFSET]
 	add $8
 	ld l, a
-	ld a, $7f
-	ld [hl], a
+	ld a, $7f ; maximum movement delay
+	ld [hl], a ; c2x8 (movement delay)
 	dec h
 	ld a, [H_CURRENTSPRITEOFFSET]
 	add $9
 	ld l, a
-	ld a, [hld]
+	ld a, [hld] ; c1x9 (facing direction)
 	ld b, a
 	xor a
 	ld [hld], a
-	ld [hl], a
+	ld [hl], a ; c1x8 (walk animation frame)
 	ld a, [H_CURRENTSPRITEOFFSET]
 	add $2
 	ld l, a
-	ld a, [hl]
-	or b
+	ld a, [hl] ; c1x2 (facing and animation table offset)
+	or b ; or in the facing direction
 	ld [hld], a
-	ld a, $2
-	ld [hl], a
+	ld a, $2 ; delayed movement status
+	ld [hl], a ; c1x1 (movement status)
 	ret