commented mon_party_sprites.asm

9 files changed, 88 insertions, 62 deletions

diff --git a/engine/menu/naming_screen.asm b/engine/menu/naming_screen.asm
index 7506c849..c5babaf2 100755
--- a/engine/menu/naming_screen.asm
+++ b/engine/menu/naming_screen.asm
@@ -92,7 +92,7 @@ DisplayNamingScreen: ; 6596 (1:6596)
 	call GoPAL_SET
 	call LoadHpBarAndStatusTilePatterns
 	call LoadEDTile
-	callba Func_7176c
+	callba LoadMonPartySpriteTilePatterns
 	hlCoord 0, 4
 	ld b, $9
 	ld c, $12
@@ -114,7 +114,7 @@ DisplayNamingScreen: ; 6596 (1:6596)
 	ld hl, wHPBarMaxHP + 1
 	ld [hli], a
 	ld [hli], a
-	ld [W_SUBANIMTRANSFORM], a
+	ld [wPartyMonAnimCounter], a
 .asm_65ed
 	call PrintAlphabet
 	call GBPalNormal
@@ -472,7 +472,7 @@ PrintNamingText: ; 68f8 (1:68f8)
 	ld a, [wcf91]
 	ld [wcd5d], a
 	push af
-	callba Func_71882
+	callba WriteMonPartySpriteOAMByMonID
 	pop af
 	ld [wd11e], a
 	call GetMonName
diff --git a/engine/menu/party_menu.asm b/engine/menu/party_menu.asm
index 97e520c2..7c163166 100755
--- a/engine/menu/party_menu.asm
+++ b/engine/menu/party_menu.asm
@@ -22,7 +22,7 @@ DrawPartyMenu_: ; 12cd2 (4:6cd2)
 	ld [H_AUTOBGTRANSFERENABLED],a
 	call ClearScreen
 	call UpdateSprites ; move sprites
-	callba Func_71791 ; load pokemon icon graphics
+	callba LoadMonPartySpriteTilePatternsWithLCDDisabled ; load pokemon icon graphics
 
 RedrawPartyMenu_: ; 12ce3 (4:6ce3)
 	ld a,[wd07d]
@@ -34,7 +34,7 @@ RedrawPartyMenu_: ; 12ce3 (4:6ce3)
 	ld de,wPartySpecies
 	xor a
 	ld c,a
-	ld [$FF8C],a ; loop counter
+	ld [hPartyMonIndex],a
 	ld [wcf2d],a
 .loop
 	ld a,[de]
@@ -49,11 +49,11 @@ RedrawPartyMenu_: ; 12ce3 (4:6ce3)
 	call GetPartyMonName
 	pop hl
 	call PlaceString ; print the pokemon's name
-	callba Func_71868 ; place the appropriate pokemon icon
-	ld a,[$FF8C] ; loop counter
+	callba WriteMonPartySpriteOAMByPartyIndex ; place the appropriate pokemon icon
+	ld a,[hPartyMonIndex]
 	ld [wWhichPokemon],a
 	inc a
-	ld [$FF8C],a
+	ld [hPartyMonIndex],a
 	call LoadMonData
 	pop hl
 	push hl
diff --git a/engine/mon_party_sprites.asm b/engine/mon_party_sprites.asm
index 52bd0fd4..37125bbb 100755
--- a/engine/mon_party_sprites.asm
+++ b/engine/mon_party_sprites.asm
@@ -1,6 +1,6 @@
 AnimatePartyMon_ForceSpeed1: ; 716f7 (1c:56f7)
 	xor a
-	ld [wCurrentMenuItem], a ; wCurrentMenuItem
+	ld [wCurrentMenuItem], a
 	ld b, a
 	inc a
 	jr GetAnimationSpeed
@@ -27,7 +27,7 @@ GetAnimationSpeed: ; 7170a (1c:570a)
 	ld c, a
 	add a
 	ld b, a
-	ld a, [W_SUBANIMTRANSFORM] ; W_SUBANIMTRANSFORM
+	ld a, [wPartyMonAnimCounter]
 	and a
 	jr z, .resetSprites
 	cp c
@@ -35,10 +35,10 @@ GetAnimationSpeed: ; 7170a (1c:570a)
 .incTimer
 	inc a
 	cp b
-	jr nz, .resetTimer
-	xor a
-.resetTimer
-	ld [W_SUBANIMTRANSFORM], a ; W_SUBANIMTRANSFORM
+	jr nz, .skipResetTimer
+	xor a ; reset timer
+.skipResetTimer
+	ld [wPartyMonAnimCounter], a
 	jp DelayFrame
 .resetSprites
 	push bc
@@ -81,16 +81,24 @@ GetAnimationSpeed: ; 7170a (1c:570a)
 	ld a, c
 	jr .incTimer
 
+; Party mon animations cycle between 2 frames.
+; The members of the PartyMonSpeeds array specify the number of V-blanks
+; that each frame lasts for green HP, yellow HP, and red HP in order.
+; On the naming screen, the yellow HP speed is always used.
 PartyMonSpeeds: ; 71769 (1c:5769)
 	db $05,$10,$20
 
-Func_7176c: ; 7176c (1c:576c)
-	ld hl, MonPartySpritePointers ; $57c0
+LoadMonPartySpriteTilePatterns: ; 7176c (1c:576c)
+; Load mon party sprite tile patterns into VRAM during V-blank.
+	ld hl, MonPartySpritePointers
 	ld a, $1c
 
-Func_71771: ; 71771 (1c:5771)
+LoadAnimSpriteTilePatterns: ; 71771 (1c:5771)
+; Load animated sprite tile patterns into VRAM during V-blank. hl is the address
+; of an array of structures that contain arguments for CopyVideoData and a is
+; the number of structures in the array.
 	ld bc, $0
-.asm_71774
+.loop
 	push af
 	push bc
 	push hl
@@ -114,12 +122,14 @@ Func_71771: ; 71771 (1c:5771)
 	ld c, a
 	pop af
 	dec a
-	jr nz, .asm_71774
+	jr nz, .loop
 	ret
 
-Func_71791: ; 71791 (1c:5791)
+LoadMonPartySpriteTilePatternsWithLCDDisabled: ; 71791 (1c:5791)
+; Load mon party sprite tile patterns into VRAM immediately by disabling the
+; LCD.
 	call DisableLCD
-	ld hl, MonPartySpritePointers ; $57c0
+	ld hl, MonPartySpritePointers
 	ld a, $1c
 	ld bc, $0
 .asm_7179c
@@ -293,51 +303,53 @@ MonPartySpritePointers: ; 717c0 (1c:57c0)
 	db BANK(MonPartySprites)
 	dw vSprites + $780
 
-Func_71868: ; 71868 (1c:5868)
+WriteMonPartySpriteOAMByPartyIndex: ; 71868 (1c:5868)
+; Write OAM blocks for the party mon in [hPartyMonIndex].
 	push hl
 	push de
 	push bc
-	ld a, [H_DOWNARROWBLINKCNT2] ; $ff8c
+	ld a, [hPartyMonIndex]
 	ld hl, wPartySpecies
 	ld e, a
-	ld d, $0
+	ld d, 0
 	add hl, de
 	ld a, [hl]
 	call GetPartyMonSpriteID
 	ld [wcd5b], a
-	call Func_718c3
+	call WriteMonPartySpriteOAM
 	pop bc
 	pop de
 	pop hl
 	ret
 
-Func_71882: ; 71882 (1c:5882)
+WriteMonPartySpriteOAMByMonID: ; 71882 (1c:5882)
+; Write OAM blocks for mon ID in [wcd5d].
 	xor a
-	ld [H_DOWNARROWBLINKCNT2], a ; $ff8c
+	ld [hPartyMonIndex], a
 	ld a, [wcd5d]
 	call GetPartyMonSpriteID
 	ld [wcd5b], a
-	jr Func_718c3
+	jr WriteMonPartySpriteOAM
 
-Func_71890: ; 71890 (1c:5890)
+UnusedPartyMonSpriteFunction: ; 71890 (1c:5890)
 	ld a, [wcf91]
 	call GetPartyMonSpriteID
 	push af
 	ld hl, vSprites
-	call Func_718ac
+	call .LoadTilePatterns
 	pop af
 	add $54
 	ld hl, vSprites + $40
-	call Func_718ac
+	call .LoadTilePatterns
 	xor a
 	ld [wcd5d], a
-	jr Func_71882
+	jr WriteMonPartySpriteOAMByMonID
 
-Func_718ac: ; 718ac (1c:58ac)
+.LoadTilePatterns ; 718ac (1c:58ac)
 	push hl
 	add a
 	ld c, a
-	ld b, $0
+	ld b, 0
 	ld hl, MonPartySpritePointers
 	add hl, bc
 	add hl, bc
@@ -353,23 +365,27 @@ Func_718ac: ; 718ac (1c:58ac)
 	pop hl
 	jp CopyVideoData
 
-Func_718c3: ; 718c3 (1c:58c3)
+WriteMonPartySpriteOAM: ; 718c3 (1c:58c3)
+; Write the OAM blocks for the first animation frame into the OAM buffer and
+; make a copy at wcc5b.
 	push af
 	ld c, $10
 	ld h, wOAMBuffer / $100
-	ld a, [H_DOWNARROWBLINKCNT2] ; $ff8c
+	ld a, [hPartyMonIndex]
 	swap a
 	ld l, a
 	add $10
 	ld b, a
 	pop af
-	cp $8
-	jr z, .asm_718da
-	call Func_712a6
-	jr .asm_718dd
-.asm_718da
-	call Func_71281
-.asm_718dd
+	cp SPRITE_HELIX << 2
+	jr z, .helix
+	call WriteSymmetricMonPartySpriteOAM
+	jr .makeCopy
+.helix
+	call WriteAsymmetricMonPartySpriteOAM
+; Make a copy of the OAM buffer with the first animation frame written so that
+; we can flip back to it from the second frame by copying it back.
+.makeCopy
 	ld hl, wOAMBuffer
 	ld de, wcc5b
 	ld bc, $60
@@ -384,13 +400,13 @@ GetPartyMonSpriteID: ; 718e9 (1c:58e9)
 	srl a
 	ld hl, MonPartyData
 	ld e, a
-	ld d, $0
+	ld d, 0
 	add hl, de
 	ld a, [hl]
 	bit 0, c
-	jr nz, .asm_71906
-	swap a
-.asm_71906
+	jr nz, .skipSwap
+	swap a ; use lower nybble if pokedex num is even
+.skipSwap
 	and $f0
 	srl a
 	srl a
diff --git a/engine/overworld/player_animations.asm b/engine/overworld/player_animations.asm
index be3d79e4..0ad31730 100755
--- a/engine/overworld/player_animations.asm
+++ b/engine/overworld/player_animations.asm
@@ -389,7 +389,7 @@ Func_707b6: ; 707b6 (1c:47b6)
 	call CopyVideoData
 	ld a, $4
 	ld hl, RedFishingTiles ; $4866
-	call Func_71771
+	call LoadAnimSpriteTilePatterns
 	ld a, [wSpriteStateData1 + 2]
 	ld c, a
 	ld b, $0
diff --git a/engine/town_map.asm b/engine/town_map.asm
index 7974cf1a..5a718519 100755
--- a/engine/town_map.asm
+++ b/engine/town_map.asm
@@ -444,12 +444,14 @@ Func_71279: ; 71279 (1c:5279)
 	ld c, l
 	pop hl
 
-Func_71281: ; 71281 (1c:5281)
+WriteAsymmetricMonPartySpriteOAM: ; 71281 (1c:5281)
+; Writes 4 OAM blocks for a helix mon party sprite, since is does not have
+; a vertical line of symmetry.
 	ld de, $202
-.asm_71284
+.loop
 	push de
 	push bc
-.asm_71286
+.innerLoop
 	ld a, b
 	ld [hli], a
 	ld a, c
@@ -465,24 +467,28 @@ Func_71281: ; 71281 (1c:5281)
 	add c
 	ld c, a
 	dec e
-	jr nz, .asm_71286
+	jr nz, .innerLoop
 	pop bc
 	pop de
 	ld a, $8
 	add b
 	ld b, a
 	dec d
-	jr nz, .asm_71284
+	jr nz, .loop
 	ret
 
-Func_712a6: ; 712a6 (1c:52a6)
+WriteSymmetricMonPartySpriteOAM: ; 712a6 (1c:52a6)
+; Writes 4 OAM blocks for a mon party sprite other than a helix. All the
+; sprites other than the helix one have a vertical line of symmetry which allows
+; the X-flip OAM bit to be used so that only 2 rather than 4 tile patterns are
+; needed.
 	xor a
 	ld [wcd5c], a
 	ld de, $202
-.asm_712ad
+.loop
 	push de
 	push bc
-.asm_712af
+.innerLoop
 	ld a, b
 	ld [hli], a
 	ld a, c
@@ -498,7 +504,7 @@ Func_712a6: ; 712a6 (1c:52a6)
 	add c
 	ld c, a
 	dec e
-	jr nz, .asm_712af
+	jr nz, .innerLoop
 	pop bc
 	pop de
 	push hl
@@ -510,7 +516,7 @@ Func_712a6: ; 712a6 (1c:52a6)
 	add b
 	ld b, a
 	dec d
-	jr nz, .asm_712ad
+	jr nz, .loop
 	ret
 
 Func_712d9: ; 712d9 (1c:52d9)
diff --git a/engine/trade.asm b/engine/trade.asm
index 5afca809..131b8493 100755
--- a/engine/trade.asm
+++ b/engine/trade.asm
@@ -146,8 +146,8 @@ LoadTradingGFXAndMonNames: ; 411a1 (10:51a1)
 Func_4120b: ; 4120b (10:520b)
 	ld a, %11010000
 	ld [rOBP1], a
-	ld b, BANK(Func_7176c)
-	ld hl, Func_7176c
+	ld b, BANK(LoadMonPartySpriteTilePatterns)
+	ld hl, LoadMonPartySpriteTilePatterns
 	jp Bankswitch
 
 Trade_SwapNames: ; 41217 (10:5217)
@@ -533,7 +533,7 @@ Func_414e8: ; 414e8 (10:54e8)
 	ret
 
 Func_41505: ; 41505 (10:5505)
-	callba Func_71882
+	callba WriteMonPartySpriteOAMByMonID
 	call Func_41558
 
 Func_41510: ; 41510 (10:5510)
diff --git a/home.asm b/home.asm
index c403642f..ed5f4db9 100644
--- a/home.asm
+++ b/home.asm
@@ -3923,7 +3923,7 @@ HandleMenuInputPokemonSelection:: ; 3ac2 (0:3ac2)
 	ld [H_DOWNARROWBLINKCNT2],a ; blinking down arrow timing value 2
 .loop1
 	xor a
-	ld [W_SUBANIMTRANSFORM],a ; counter for pokemon shaking animation
+	ld [wPartyMonAnimCounter],a ; counter for pokemon shaking animation
 	call PlaceMenuCursor
 	call Delay3
 .loop2
diff --git a/hram.asm b/hram.asm
index 1becd8c0..a6035b59 100644
--- a/hram.asm
+++ b/hram.asm
@@ -24,6 +24,8 @@ H_SPRITEINDEX      EQU $FF8C
 ; DisplayTextID's argument
 hSpriteIndexOrTextID EQU $FF8C
 
+hPartyMonIndex EQU $FF8C
+
 ; Multiplcation and division variables are meant
 ; to overlap for back-to-back usage. Big endian.
 
diff --git a/wram.asm b/wram.asm
index ee6cc20f..9ffbc8b8 100755
--- a/wram.asm
+++ b/wram.asm
@@ -1118,6 +1118,8 @@ wd08a:: ds 1
 
 wTownMapSpriteBlinkingCounter:: ; d08b
 
+wPartyMonAnimCounter:: ; d08b
+
 W_SUBANIMTRANSFORM:: ; d08b
 ; controls what transformations are applied to the subanimation
 ; 01: flip horizontally and vertically