named animation functions/variables

4 files changed, 107 insertions, 102 deletions

diff --git a/engine/overworld/card_key.asm b/engine/overworld/card_key.asm
index 0bb2e1b4..cc9fe3a7 100755
--- a/engine/overworld/card_key.asm
+++ b/engine/overworld/card_key.asm
@@ -47,7 +47,7 @@ PrintCardKeyText: ; 52673 (14:6673)
 .notSilphCo11F
 	ld a, $e
 .replaceCardKeyDoorTileBlock
-	ld [wd09f], a
+	ld [wNewTileBlockID], a
 	predef ReplaceTileBlock
 	ld hl, wd126
 	set 5, [hl]
diff --git a/engine/overworld/cut.asm b/engine/overworld/cut.asm
index 293daee7..2056bbb0 100755
--- a/engine/overworld/cut.asm
+++ b/engine/overworld/cut.asm
@@ -3,21 +3,21 @@ UsedCut: ; ef54 (3:6f54)
 	ld [wActionResultOrTookBattleTurn], a ; initialise to failure value
 	ld a, [W_CURMAPTILESET]
 	and a ; OVERWORLD
-	jr z, .asm_ef6b
+	jr z, .overworld
 	cp GYM
-	jr nz, .asm_ef77
+	jr nz, .nothingToCut
 	ld a, [wTileInFrontOfPlayer]
 	cp $50 ; gym cut tree
-	jr nz, .asm_ef77
-	jr .asm_ef82
-.asm_ef6b
+	jr nz, .nothingToCut
+	jr .canCut
+.overworld
 	dec a
 	ld a, [wTileInFrontOfPlayer]
 	cp $3d ; cut tree
-	jr z, .asm_ef82
+	jr z, .canCut
 	cp $52 ; grass
-	jr z, .asm_ef82
-.asm_ef77
+	jr z, .canCut
+.nothingToCut
 	ld hl, .NothingToCutText
 	jp PrintText
 
@@ -25,9 +25,9 @@ UsedCut: ; ef54 (3:6f54)
 	TX_FAR _NothingToCutText
 	db "@"
 
-.asm_ef82
+.canCut
 	ld [wCutTile], a
-	ld a, $1
+	ld a, 1
 	ld [wActionResultOrTookBattleTurn], a ; used cut
 	ld a, [wWhichPokemon]
 	ld hl, wPartyMonNicks
@@ -37,7 +37,7 @@ UsedCut: ; ef54 (3:6f54)
 	call GBPalWhiteOutWithDelay3
 	call ClearSprites
 	call RestoreScreenTilesAndReloadTilePatterns
-	ld a, $90
+	ld a, SCREEN_HEIGHT_PIXELS
 	ld [hWY], a
 	call Delay3
 	call LoadGBPal
@@ -53,11 +53,11 @@ UsedCut: ; ef54 (3:6f54)
 	res 6, [hl]
 	ld a, $ff
 	ld [wUpdateSpritesEnabled], a
-	call AnimateCutTree
+	call InitCutAnimOAM
 	ld de, CutTreeBlockSwaps
-	call Func_f09f
+	call ReplaceTreeTileBlock
 	call RedrawMapView
-	callba Func_79e96
+	callba AnimCut
 	ld a, $1
 	ld [wUpdateSpritesEnabled], a
 	ld a, SFX_CUT
@@ -71,14 +71,15 @@ UsedCutText: ; eff2 (3:6ff2)
 	TX_FAR _UsedCutText
 	db "@"
 
-AnimateCutTree: ; eff7 (3:6ff7)
+InitCutAnimOAM: ; eff7 (3:6ff7)
 	xor a
 	ld [wWhichAnimationOffsets], a
 	ld a, $e4
 	ld [rOBP1], a
 	ld a, [wCutTile]
 	cp $52
-	jr z, .asm_f020
+	jr z, .grass
+; tree
 	ld de, Overworld_GFX + $2d0 ; cuttable tree sprite top row
 	ld hl, vChars1 + $7c0
 	ld bc, (BANK(Overworld_GFX) << 8) + $02
@@ -87,45 +88,45 @@ AnimateCutTree: ; eff7 (3:6ff7)
 	ld hl, vChars1 + $7e0
 	ld bc, (BANK(Overworld_GFX) << 8) + $02
 	call CopyVideoData
-	jr WriteCutTreeBoulderDustAnimationOAMBlock
-.asm_f020
+	jr WriteCutOrBoulderDustAnimationOAMBlock
+.grass
 	ld hl, vChars1 + $7c0
-	call LoadCutTreeAnimationTilePattern
+	call LoadCutGrassAnimationTilePattern
 	ld hl, vChars1 + $7d0
-	call LoadCutTreeAnimationTilePattern
+	call LoadCutGrassAnimationTilePattern
 	ld hl, vChars1 + $7e0
-	call LoadCutTreeAnimationTilePattern
+	call LoadCutGrassAnimationTilePattern
 	ld hl, vChars1 + $7f0
-	call LoadCutTreeAnimationTilePattern
-	call WriteCutTreeBoulderDustAnimationOAMBlock
+	call LoadCutGrassAnimationTilePattern
+	call WriteCutOrBoulderDustAnimationOAMBlock
 	ld hl, wOAMBuffer + $93
-	ld de, $4
+	ld de, 4
 	ld a, $30
 	ld c, e
-.asm_f044
+.loop
 	ld [hl], a
 	add hl, de
 	xor $60
 	dec c
-	jr nz, .asm_f044
+	jr nz, .loop
 	ret
 
-LoadCutTreeAnimationTilePattern: ; f04c (3:704c)
+LoadCutGrassAnimationTilePattern: ; f04c (3:704c)
 	ld de, AnimationTileset2 + $60 ; tile depicting a leaf
 	ld bc, (BANK(AnimationTileset2) << 8) + $01
 	jp CopyVideoData
 
-WriteCutTreeBoulderDustAnimationOAMBlock: ; f055 (3:7055)
-	call GetCutTreeBoulderDustAnimationOffsets
+WriteCutOrBoulderDustAnimationOAMBlock: ; f055 (3:7055)
+	call GetCutOrBoulderDustAnimationOffsets
 	ld a, $9
-	ld de, CutTreeBoulderDustAnimationTilesAndAttributes
+	ld de, CutOrBoulderDustAnimationTilesAndAttributes
 	jp WriteOAMBlock
 
-CutTreeBoulderDustAnimationTilesAndAttributes: ; f060 (3:7060)
+CutOrBoulderDustAnimationTilesAndAttributes: ; f060 (3:7060)
 	db $FC,$10,$FD,$10
 	db $FE,$10,$FF,$10
 
-GetCutTreeBoulderDustAnimationOffsets: ; f068 (3:7068)
+GetCutOrBoulderDustAnimationOffsets: ; f068 (3:7068)
 	ld hl, wSpriteStateData1 + 4
 	ld a, [hli] ; player's sprite screen Y position
 	ld b, a
@@ -140,10 +141,10 @@ GetCutTreeBoulderDustAnimationOffsets: ; f068 (3:7068)
 	ld d, $0 ; de holds direction (00: down, 02: up, 04: left, 06: right)
 	ld a, [wWhichAnimationOffsets]
 	and a
-	ld hl, CutTreeAnimationOffsets
-	jr z, .asm_f084
+	ld hl, CutAnimationOffsets
+	jr z, .next
 	ld hl, BoulderDustAnimationOffsets
-.asm_f084
+.next
 	add hl, de
 	ld e, [hl]
 	inc hl
@@ -156,7 +157,7 @@ GetCutTreeBoulderDustAnimationOffsets: ; f068 (3:7068)
 	ld c, a
 	ret
 
-CutTreeAnimationOffsets: ; f08f (3:708f)
+CutAnimationOffsets: ; f08f (3:708f)
 ; Each pair represents the x and y pixels offsets from the player of where the cut tree animation should be drawn
 	db  8, 36 ; player is facing down
 	db  8,  4 ; player is facing up
@@ -171,75 +172,79 @@ BoulderDustAnimationOffsets: ; f097 (3:7097)
 	db -24, 20 ; player is facing left
 	db 40,  20 ; player is facing right
 
-Func_f09f: ; f09f (3:709f)
+ReplaceTreeTileBlock: ; f09f (3:709f)
+; Determine the address of the tile block that contains the tile in front of the
+; player (i.e. where the tree is) and replace it with the corresponding tile
+; block that doesn't have the tree.
 	push de
 	ld a, [W_CURMAPWIDTH]
-	add $6
+	add 6
 	ld c, a
-	ld b, $0
-	ld d, $0
+	ld b, 0
+	ld d, 0
 	ld hl, wCurrentTileBlockMapViewPointer
 	ld a, [hli]
 	ld h, [hl]
 	ld l, a
 	add hl, bc
-	ld a, [wSpriteStateData1 + 9]
+	ld a, [wSpriteStateData1 + 9] ; player sprite's facing direction
 	and a
 	jr z, .down
 	cp SPRITE_FACING_UP
 	jr z, .up
 	cp SPRITE_FACING_LEFT
 	jr z, .left
+; right
 	ld a, [W_XBLOCKCOORD]
 	and a
-	jr z, .asm_f0e0
-	jr .asm_f0ec
+	jr z, .centerTileBlock
+	jr .rightOfCenter
 .down
 	ld a, [W_YBLOCKCOORD]
 	and a
-	jr z, .asm_f0e0
-	jr .asm_f0df
+	jr z, .centerTileBlock
+	jr .belowCenter
 .up
 	ld a, [W_YBLOCKCOORD]
 	and a
-	jr z, .asm_f0e1
-	jr .asm_f0e0
+	jr z, .aboveCenter
+	jr .centerTileBlock
 .left
 	ld a, [W_XBLOCKCOORD]
 	and a
-	jr z, .asm_f0e6
-	jr .asm_f0e0
-.asm_f0df
+	jr z, .leftOfCenter
+	jr .centerTileBlock
+.belowCenter
 	add hl, bc
-.asm_f0e0
+.centerTileBlock
 	add hl, bc
-.asm_f0e1
+.aboveCenter
 	ld e, $2
 	add hl, de
-	jr .asm_f0f0
-.asm_f0e6
+	jr .next
+.leftOfCenter
 	ld e, $1
 	add hl, bc
 	add hl, de
-	jr .asm_f0f0
-.asm_f0ec
+	jr .next
+.rightOfCenter
 	ld e, $3
 	add hl, bc
 	add hl, de
-.asm_f0f0
+.next
 	pop de
 	ld a, [hl]
 	ld c, a
-.asm_f0f3
+.loop ; find the matching tile block in the array
 	ld a, [de]
 	inc de
 	inc de
 	cp $ff
 	ret z
 	cp c
-	jr nz, .asm_f0f3
+	jr nz, .loop
 	dec de
-	ld a, [de]
+	ld a, [de] ; replacement tile block from matching array entry
 	ld [hl], a
 	ret
 
diff --git a/engine/overworld/cut2.asm b/engine/overworld/cut2.asm
index 3194b39b..1cf832b5 100755
--- a/engine/overworld/cut2.asm
+++ b/engine/overworld/cut2.asm
@@ -1,19 +1,19 @@
-Func_79e96: ; 79e96 (1e:5e96)
+AnimCut: ; 79e96 (1e:5e96)
 	ld a, [wCutTile]
 	cp $52
-	jr z, .asm_79ec8
+	jr z, .grass
 	ld c, $8
-.asm_79e9f
+.cutTreeLoop
 	push bc
 	ld hl, wOAMBuffer + $91
-	ld a, $1
-	ld [wd08a], a
-	ld c, $2
+	ld a, 1
+	ld [wCoordAdjustmentAmount], a
+	ld c, 2
 	call AdjustOAMBlockXPos2
 	ld hl, wOAMBuffer + $99
-	ld a, $ff
-	ld [wd08a], a
-	ld c, $2
+	ld a, -1
+	ld [wCoordAdjustmentAmount], a
+	ld c, 2
 	call AdjustOAMBlockXPos2
 	ld a, [rOBP1]
 	xor $64
@@ -21,49 +21,49 @@ Func_79e96: ; 79e96 (1e:5e96)
 	call DelayFrame
 	pop bc
 	dec c
-	jr nz, .asm_79e9f
+	jr nz, .cutTreeLoop
 	ret
-.asm_79ec8
-	ld c, $2
-.asm_79eca
+.grass
+	ld c, 2
+.cutGrassLoop
 	push bc
 	ld c, $8
-	call Func_79eed
-	call Func_79f30
+	call AnimCutGrass_UpdateOAMEntries
+	call AnimCutGrass_SwapOAMEntries
 	ld c, $8
-	call Func_79eed
-	call Func_79f30
+	call AnimCutGrass_UpdateOAMEntries
+	call AnimCutGrass_SwapOAMEntries
 	ld hl, wOAMBuffer + $90
-	ld a, $2
-	ld [wd08a], a
-	ld c, $4
+	ld a, 2
+	ld [wCoordAdjustmentAmount], a
+	ld c, 4
 	call AdjustOAMBlockYPos2
 	pop bc
 	dec c
-	jr nz, .asm_79eca
+	jr nz, .cutGrassLoop
 	ret
 
-Func_79eed: ; 79eed (1e:5eed)
+AnimCutGrass_UpdateOAMEntries: ; 79eed (1e:5eed)
 	push bc
 	ld hl, wOAMBuffer + $91
-	ld a, $1
-	ld [wd08a], a
-	ld c, $1
+	ld a, 1
+	ld [wCoordAdjustmentAmount], a
+	ld c, 1
 	call AdjustOAMBlockXPos2
 	ld hl, wOAMBuffer + $95
-	ld a, $2
-	ld [wd08a], a
-	ld c, $1
+	ld a, 2
+	ld [wCoordAdjustmentAmount], a
+	ld c, 1
 	call AdjustOAMBlockXPos2
 	ld hl, wOAMBuffer + $99
-	ld a, $fe
-	ld [wd08a], a
-	ld c, $1
+	ld a, -2
+	ld [wCoordAdjustmentAmount], a
+	ld c, 1
 	call AdjustOAMBlockXPos2
 	ld hl, wOAMBuffer + $9d
-	ld a, $ff
-	ld [wd08a], a
-	ld c, $1
+	ld a, -1
+	ld [wCoordAdjustmentAmount], a
+	ld c, 1
 	call AdjustOAMBlockXPos2
 	ld a, [rOBP1]
 	xor $64
@@ -71,19 +71,19 @@ Func_79eed: ; 79eed (1e:5eed)
 	call DelayFrame
 	pop bc
 	dec c
-	jr nz, Func_79eed
+	jr nz, AnimCutGrass_UpdateOAMEntries
 	ret
 
-Func_79f30: ; 79f30 (1e:5f30)
+AnimCutGrass_SwapOAMEntries: ; 79f30 (1e:5f30)
 	ld hl, wOAMBuffer + $90
-	ld de, wHPBarMaxHP
+	ld de, wBuffer
 	ld bc, $8
 	call CopyData
 	ld hl, wOAMBuffer + $98
 	ld de, wOAMBuffer + $90
 	ld bc, $8
 	call CopyData
-	ld hl, wHPBarMaxHP
+	ld hl, wBuffer
 	ld de, wOAMBuffer + $98
 	ld bc, $8
 	jp CopyData
diff --git a/engine/overworld/ssanne.asm b/engine/overworld/ssanne.asm
index a59ae794..8c5485e2 100755
--- a/engine/overworld/ssanne.asm
+++ b/engine/overworld/ssanne.asm
@@ -8,14 +8,14 @@ AnimateBoulderDust: ; 79f54 (1e:5f54)
 	ld a, %11100100
 	ld [rOBP1], a
 	call LoadSmokeTileFourTimes
-	callba WriteCutTreeBoulderDustAnimationOAMBlock
+	callba WriteCutOrBoulderDustAnimationOAMBlock
 	ld c, 8 ; number of steps in animation
 .loop
 	push bc
 	call GetMoveBoulderDustFunctionPointer
 	ld bc, .returnAddress
 	push bc
-	ld c, $4
+	ld c, 4
 	jp [hl]
 .returnAddress
 	ld a, [rOBP1]
@@ -36,7 +36,7 @@ GetMoveBoulderDustFunctionPointer: ; 79f92 (1e:5f92)
 	ld b, $0
 	add hl, bc
 	ld a, [hli]
-	ld [wd08a], a
+	ld [wCoordAdjustmentAmount], a
 	ld a, [hli]
 	ld e, a
 	ld a, [hli]