From 80ece33e3e847563188782b76107256fba53088d Mon Sep 17 00:00:00 2001
From: mid-kid <esteve.varela@gmail.com>
Date: Sat, 16 Feb 2019 12:55:15 +0100
Subject: [PATCH] Document wBattleAnimFlags

`anim_clearsprites` was misnamed, so I renamed it to `anim_keepsprites`,
and documented it in docs/battle_anim_commands.md
---
 constants/wram_constants.asm          |  7 ++++++
 data/moves/animations.asm             |  2 +-
 docs/battle_anim_commands.md          |  7 +++++-
 engine/battle_anims/anim_commands.asm | 31 ++++++++++++++-------------
 macros/scripts/battle_anims.asm       |  2 +-
 5 files changed, 31 insertions(+), 18 deletions(-)

diff --git a/constants/wram_constants.asm b/constants/wram_constants.asm
index 1c8ff5192..ab705bc12 100644
--- a/constants/wram_constants.asm
+++ b/constants/wram_constants.asm
@@ -123,6 +123,13 @@ DARKNESS EQU 1 << DARKNESS_F
 
 ANYTIME EQU MORN | DAY | NITE
 
+; wBattleAnimFlags:: ; d40f
+	const_def
+	const BATTLEANIM_STOP_F          ; 0
+	const BATTLEANIM_IN_SUBROUTINE_F ; 1
+	const BATTLEANIM_IN_LOOP_F       ; 2
+	const BATTLEANIM_KEEPSPRITES_F   ; 3
+
 ; wPlayerSpriteSetupFlags:: ; d45b
 PLAYERSPRITESETUP_FACING_MASK       EQU %11
 PLAYERSPRITESETUP_FEMALE_TO_MALE_F  EQU 2
diff --git a/data/moves/animations.asm b/data/moves/animations.asm
index 0902c143a..3b069efed 100644
--- a/data/moves/animations.asm
+++ b/data/moves/animations.asm
@@ -398,7 +398,7 @@ BattleAnim_ThrowPokeBall:
 	anim_jump .Loop
 
 .Click:
-	anim_clearsprites
+	anim_keepsprites
 	anim_ret
 
 .BreakFree:
diff --git a/docs/battle_anim_commands.md b/docs/battle_anim_commands.md
index 7c4d8313d..16b19bd35 100644
--- a/docs/battle_anim_commands.md
+++ b/docs/battle_anim_commands.md
@@ -91,6 +91,7 @@ Caveats:
 - Doesn't work with `anim_4gfx` and `anim_5gfx`.
 - This overwrites previously loaded animation graphics if you've loaded more than 53 tiles (2row) or 66 tiles (1row).
 
+
 ## `$DB`: `anim_checkpokeball`
 
 Sets `BattleAnimVar` to the result of [GetPokeBallWobble](/engine/battle_anims/pokeball_wobble.asm).
@@ -196,7 +197,11 @@ Sets `rOBP0` to *colors*.
 Sets `rOBP1` to *colors*.
 
 
-## `$F4`: `anim_clearsprites`
+## `$F4`: `anim_keepsprites`
+
+Causes only the palettes to be cleared from the OAM memory when the animation ends, instead of clearing all of the OAM memory. This causes all objects to start using palette 0 (monochrome) when the animation script ends, and whatever objects were on the screen before the last `anim_ret` will stay on the screen.
+
+This is only used for the Poke Ball animation.
 
 
 ## `$F5`: `anim_0xf5`
diff --git a/engine/battle_anims/anim_commands.asm b/engine/battle_anims/anim_commands.asm
index cdb8555bd..135ec31ea 100644
--- a/engine/battle_anims/anim_commands.asm
+++ b/engine/battle_anims/anim_commands.asm
@@ -128,10 +128,10 @@ RunBattleAnimScript:
 
 .done
 	ld a, [wBattleAnimFlags]
-	bit 0, a
+	bit BATTLEANIM_STOP_F, a
 	jr z, .playframe
 
-	call BattleAnim_ClearCGB_OAMFlags
+	call BattleAnim_ClearOAM
 	ret
 
 BattleAnimClearHud:
@@ -232,16 +232,17 @@ Unreferenced_Functioncc220:
 	call BattleAnimDelayFrame
 	ret
 
-BattleAnim_ClearCGB_OAMFlags:
+BattleAnim_ClearOAM:
 	ld a, [wBattleAnimFlags]
-	bit 3, a
+	bit BATTLEANIM_KEEPSPRITES_F, a
 	jr z, .delete
 
+	; Instead of deleting the sprites, make them all use palette 0 (monochrome)
 	ld hl, wVirtualOAMSprite00Attributes
 	ld c, NUM_SPRITE_OAM_STRUCTS
 .loop
 	ld a, [hl]
-	and $f0
+	and ~PALETTE_MASK & ~VRAM_BANK_1
 	ld [hli], a
 rept SPRITEOAMSTRUCT_LENGTH + -1
 	inc hl
@@ -289,10 +290,10 @@ RunBattleAnimCommand:
 
 ; Return from a subroutine.
 	ld hl, wBattleAnimFlags
-	bit 1, [hl]
+	bit BATTLEANIM_IN_SUBROUTINE_F, [hl]
 	jr nz, .do_anim
 
-	set 0, [hl]
+	set BATTLEANIM_STOP_F, [hl]
 	ret
 
 .not_done_with_anim
@@ -361,7 +362,7 @@ BattleAnimCommands::
 	dw BattleAnimCmd_BGP
 	dw BattleAnimCmd_OBP0
 	dw BattleAnimCmd_OBP1
-	dw BattleAnimCmd_ClearSprites
+	dw BattleAnimCmd_KeepSprites
 	dw BattleAnimCmd_F5
 	dw BattleAnimCmd_F6
 	dw BattleAnimCmd_F7
@@ -382,7 +383,7 @@ BattleAnimCmd_ED:
 
 BattleAnimCmd_Ret:
 	ld hl, wBattleAnimFlags
-	res 1, [hl]
+	res BATTLEANIM_IN_SUBROUTINE_F, [hl]
 	ld hl, wBattleAnimParent
 	ld e, [hl]
 	inc hl
@@ -413,7 +414,7 @@ BattleAnimCmd_Call:
 	inc hl
 	ld [hl], d
 	ld hl, wBattleAnimFlags
-	set 1, [hl]
+	set BATTLEANIM_IN_SUBROUTINE_F, [hl]
 	ret
 
 BattleAnimCmd_Jump:
@@ -430,12 +431,12 @@ BattleAnimCmd_Jump:
 BattleAnimCmd_Loop:
 	call GetBattleAnimByte
 	ld hl, wBattleAnimFlags
-	bit 2, [hl]
+	bit BATTLEANIM_IN_LOOP_F, [hl]
 	jr nz, .continue_loop
 	and a
 	jr z, .perpetual
 	dec a
-	set 2, [hl]
+	set BATTLEANIM_IN_LOOP_F, [hl]
 	ld [wBattleAnimLoops], a
 .continue_loop
 	ld hl, wBattleAnimLoops
@@ -456,7 +457,7 @@ BattleAnimCmd_Loop:
 
 .return_from_loop
 	ld hl, wBattleAnimFlags
-	res 2, [hl]
+	res BATTLEANIM_IN_LOOP_F, [hl]
 	ld hl, wBattleAnimAddress
 	ld e, [hl]
 	inc hl
@@ -1155,9 +1156,9 @@ BattleAnimCmd_OAMOff:
 	ldh [hOAMUpdate], a
 	ret
 
-BattleAnimCmd_ClearSprites:
+BattleAnimCmd_KeepSprites:
 	ld hl, wBattleAnimFlags
-	set 3, [hl]
+	set BATTLEANIM_KEEPSPRITES_F, [hl]
 	ret
 
 BattleAnimCmd_F5:
diff --git a/macros/scripts/battle_anims.asm b/macros/scripts/battle_anims.asm
index 01db12010..af447f1af 100644
--- a/macros/scripts/battle_anims.asm
+++ b/macros/scripts/battle_anims.asm
@@ -233,7 +233,7 @@ anim_obp1: MACRO
 ENDM
 
 	enum anim_clearsprites_command ; $f4
-anim_clearsprites: MACRO
+anim_keepsprites: MACRO
 	db anim_clearsprites_command
 ENDM