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

@@ -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

data/moves/animations.asm

@@ -398,7 +398,7 @@ BattleAnim_ThrowPokeBall:
 	anim_jump .Loop
 
 .Click:
-	anim_clearsprites
+	anim_keepsprites
 	anim_ret
 
 .BreakFree:

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`

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:

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