Merge pull request #601 from mid-kid/master

Exciting adventures down battle animation street!

17 files changed, 190 insertions, 145 deletions

diff --git a/constants/battle_anim_constants.asm b/constants/battle_anim_constants.asm
index c9eeac130..fcd512b97 100644
--- a/constants/battle_anim_constants.asm
+++ b/constants/battle_anim_constants.asm
@@ -25,6 +25,7 @@
 	const BATTLEANIMSTRUCT_16
 	const BATTLEANIMSTRUCT_17
 BATTLEANIMSTRUCT_LENGTH EQU const_value
+NUM_ANIM_OBJECTS EQU 10 ; see wActiveAnimObjects
 
 ; Start tile for battle animation graphics
 BATTLEANIM_BASE_TILE EQU 7 * 7  ; Maximum size of a pokemon picture
@@ -816,6 +817,8 @@ BATTLEANIM_BASE_TILE EQU 7 * 7  ; Maximum size of a pokemon picture
 	const BG_EFFECT_STRUCT_JT_INDEX
 	const BG_EFFECT_STRUCT_BATTLE_TURN
 	const BG_EFFECT_STRUCT_03
+BG_EFFECT_STRUCT_LENGTH EQU const_value
+NUM_BG_EFFECTS EQU 5 ; see wActiveBGEffects
 
 ; battle palettes
 	const_def
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/battle_anims/framesets.asm b/data/battle_anims/framesets.asm
index e0fe57007..a5641570c 100644
--- a/data/battle_anims/framesets.asm
+++ b/data/battle_anims/framesets.asm
@@ -230,11 +230,11 @@ BattleAnimFrameData:
 	frame BATTLEANIMOAMSET_4C,  2
 	frame BATTLEANIMOAMSET_4D,  4
 	frame BATTLEANIMOAMSET_4E,  2
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_4E,  2
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_4E,  2
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_4E,  2
 	delanim
 
@@ -243,11 +243,11 @@ BattleAnimFrameData:
 	frame BATTLEANIMOAMSET_4C,  2, OAM_X_FLIP
 	frame BATTLEANIMOAMSET_4D,  4, OAM_X_FLIP
 	frame BATTLEANIMOAMSET_4E,  2, OAM_X_FLIP
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_4E,  2, OAM_X_FLIP
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_4E,  2, OAM_X_FLIP
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_4E,  2, OAM_X_FLIP
 	delanim
 
@@ -256,11 +256,11 @@ BattleAnimFrameData:
 	frame BATTLEANIMOAMSET_4C,  2, OAM_X_FLIP, OAM_Y_FLIP
 	frame BATTLEANIMOAMSET_4D,  4, OAM_X_FLIP, OAM_Y_FLIP
 	frame BATTLEANIMOAMSET_4E,  2, OAM_X_FLIP, OAM_Y_FLIP
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_4E,  2, OAM_X_FLIP, OAM_Y_FLIP
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_4E,  2, OAM_X_FLIP, OAM_Y_FLIP
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_4E,  2, OAM_X_FLIP, OAM_Y_FLIP
 	delanim
 
@@ -272,11 +272,11 @@ BattleAnimFrameData:
 	frame BATTLEANIMOAMSET_50,  1
 	frame BATTLEANIMOAMSET_51,  1
 	frame BATTLEANIMOAMSET_52,  2
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_52,  2
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_52,  2
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_52,  2
 	delanim
 
@@ -288,11 +288,11 @@ BattleAnimFrameData:
 	frame BATTLEANIMOAMSET_50,  1, OAM_X_FLIP
 	frame BATTLEANIMOAMSET_51,  1, OAM_X_FLIP
 	frame BATTLEANIMOAMSET_52,  2, OAM_X_FLIP
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_52,  2, OAM_X_FLIP
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_52,  2, OAM_X_FLIP
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_52,  2, OAM_X_FLIP
 	delanim
 
@@ -368,13 +368,13 @@ BattleAnimFrameData:
 	frame BATTLEANIMOAMSET_10,  3
 	frame BATTLEANIMOAMSET_0F,  3
 	frame BATTLEANIMOAMSET_12,  1
-	dorepeat 1
+	dowait 1
 	frame BATTLEANIMOAMSET_12,  1
-	dorepeat 1
+	dowait 1
 	frame BATTLEANIMOAMSET_12,  1
-	dorepeat 1
+	dowait 1
 	frame BATTLEANIMOAMSET_12,  1
-	dorepeat 1
+	dowait 1
 	frame BATTLEANIMOAMSET_12,  3
 	delanim
 
@@ -535,13 +535,13 @@ BattleAnimFrameData:
 	frame BATTLEANIMOAMSET_34, 32
 	frame BATTLEANIMOAMSET_35, 32 ; fallthrough
 .Frameset_2f:
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_35,  4
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_35,  4
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_35,  4
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_35,  4
 	delanim
 
@@ -579,13 +579,13 @@ BattleAnimFrameData:
 
 .Frameset_35:
 	frame BATTLEANIMOAMSET_40,  2
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_40,  2
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_41,  2
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_41,  2
-	dorepeat 2
+	dowait 2
 	dorestart
 
 .Frameset_36:
@@ -597,7 +597,7 @@ BattleAnimFrameData:
 
 .Frameset_37:
 	frame BATTLEANIMOAMSET_19,  2
-	dorepeat 2
+	dowait 2
 	dorestart
 
 .Frameset_38:
@@ -607,7 +607,7 @@ BattleAnimFrameData:
 
 .Frameset_39:
 	frame BATTLEANIMOAMSET_18,  2
-	dorepeat 2
+	dowait 2
 	dorestart
 
 .Frameset_3a:
@@ -639,15 +639,15 @@ BattleAnimFrameData:
 	endanim
 
 .Frameset_44:
-	dorepeat 20
+	dowait 20
 	frame BATTLEANIMOAMSET_55, 40
 	frame BATTLEANIMOAMSET_54, 40
 	frame BATTLEANIMOAMSET_53, 20
-	dorepeat 4
+	dowait 4
 	frame BATTLEANIMOAMSET_53,  4
-	dorepeat 4
+	dowait 4
 	frame BATTLEANIMOAMSET_53,  4
-	dorepeat 4
+	dowait 4
 	frame BATTLEANIMOAMSET_53,  4
 	delanim
 
@@ -658,11 +658,11 @@ BattleAnimFrameData:
 	delanim
 
 .Frameset_45:
-	dorepeat 0
+	dowait 0
 	frame BATTLEANIMOAMSET_14,  0
 	frame BATTLEANIMOAMSET_15,  0
 	frame BATTLEANIMOAMSET_14,  0, OAM_X_FLIP
-	dorepeat 0
+	dowait 0
 	frame BATTLEANIMOAMSET_16,  0, OAM_X_FLIP
 	frame BATTLEANIMOAMSET_15,  0
 	frame BATTLEANIMOAMSET_16,  0
@@ -867,7 +867,7 @@ BattleAnimFrameData:
 	delanim
 
 .Frameset_68:
-	dorepeat 15
+	dowait 15
 	frame BATTLEANIMOAMSET_84, 15
 	frame BATTLEANIMOAMSET_85, 15
 	frame BATTLEANIMOAMSET_29, 15
@@ -970,11 +970,11 @@ BattleAnimFrameData:
 	frame BATTLEANIMOAMSET_9C,  2
 	frame BATTLEANIMOAMSET_9D,  2
 	frame BATTLEANIMOAMSET_9E,  8
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_9E,  2
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_9E,  2
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_9E,  2
 	delanim
 
@@ -1160,11 +1160,11 @@ BattleAnimFrameData:
 	frame BATTLEANIMOAMSET_50,  1
 	frame BATTLEANIMOAMSET_51,  1
 	frame BATTLEANIMOAMSET_52,  2
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_52,  2
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_52,  2
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_52,  2
 	delanim
 
@@ -1178,11 +1178,11 @@ BattleAnimFrameData:
 	frame BATTLEANIMOAMSET_50,  1, OAM_X_FLIP, OAM_Y_FLIP
 	frame BATTLEANIMOAMSET_51,  1, OAM_X_FLIP, OAM_Y_FLIP
 	frame BATTLEANIMOAMSET_52,  2, OAM_X_FLIP, OAM_Y_FLIP
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_52,  2, OAM_X_FLIP, OAM_Y_FLIP
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_52,  2, OAM_X_FLIP, OAM_Y_FLIP
-	dorepeat 2
+	dowait 2
 	frame BATTLEANIMOAMSET_52,  2, OAM_X_FLIP, OAM_Y_FLIP
 	delanim
 
diff --git a/data/battle_anims/oam.asm b/data/battle_anims/oam.asm
index 1beca2937..42c9c8295 100644
--- a/data/battle_anims/oam.asm
+++ b/data/battle_anims/oam.asm
@@ -1,6 +1,6 @@
 BattleAnimOAMData:
 ; entries correspond to BATTLEANIMOAMSET_* constants
-	; vtile offset, length, pointer
+	; vtile offset, data length, data pointer
 	dbbw $00, 16, .OAMData_00 ; BATTLEANIMOAMSET_00
 	dbbw $04,  9, .OAMData_01 ; BATTLEANIMOAMSET_01
 	dbbw $08,  4, .OAMData_02 ; BATTLEANIMOAMSET_02
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/data/sprite_anims/framesets.asm b/data/sprite_anims/framesets.asm
index 666f2b2e2..549b4b637 100644
--- a/data/sprite_anims/framesets.asm
+++ b/data/sprite_anims/framesets.asm
@@ -129,12 +129,12 @@ SpriteAnimFrameData:
 
 .Frameset_TextEntryCursor:
 	frame SPRITE_ANIM_OAMSET_TEXT_ENTRY_CURSOR,  1
-	dorepeat  1
+	dowait 1
 	dorestart
 
 .Frameset_TextEntryCursorBig:
 	frame SPRITE_ANIM_OAMSET_TEXT_ENTRY_CURSOR_BIG,  1
-	dorepeat  1
+	dowait 1
 	dorestart
 
 .Frameset_GameFreakLogo:
@@ -285,11 +285,11 @@ SpriteAnimFrameData:
 
 ; unused
 	frame SPRITE_ANIM_OAMSET_UNUSED_4E,  3
-	dorepeat  3
+	dowait 3
 	dorestart
 
 .Frameset_Unused1C:
-	dorepeat 32
+	dowait 32
 	endanim
 
 .Frameset_Leaf:
@@ -299,9 +299,9 @@ SpriteAnimFrameData:
 .Frameset_CutTree:
 	frame SPRITE_ANIM_OAMSET_TREE_1,      2
 	frame SPRITE_ANIM_OAMSET_CUT_TREE_2, 16
-	dorepeat  1
+	dowait 1
 	frame SPRITE_ANIM_OAMSET_CUT_TREE_3,  1
-	dorepeat  1
+	dowait 1
 	frame SPRITE_ANIM_OAMSET_CUT_TREE_4,  1
 	delanim
 
@@ -483,7 +483,7 @@ SpriteAnimFrameData:
 	endanim
 
 .Frameset_IntroUnownF:
-	dorepeat 0
+	dowait 0
 	endanim
 
 .Frameset_CelebiLeft:
diff --git a/data/sprite_anims/oam.asm b/data/sprite_anims/oam.asm
index 4fa153504..ece914e0c 100644
--- a/data/sprite_anims/oam.asm
+++ b/data/sprite_anims/oam.asm
@@ -1,6 +1,6 @@
 SpriteAnimOAMData:
 ; entries correspond to SPRITE_ANIM_OAMSET_* constants
-	; vtile offset, pointer
+	; vtile offset, data pointer
 	dbw $00, .OAMData_RedWalk                  ; SPRITE_ANIM_OAMSET_RED_WALK_1
 	dbw $04, .OAMData_RedWalk                  ; SPRITE_ANIM_OAMSET_RED_WALK_2
 	dbw $4c, .OAMData_1x1_Palette0             ; SPRITE_ANIM_OAMSET_GS_INTRO_BUBBLE_1
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 f6c6b06a6..135ec31ea 100644
--- a/engine/battle_anims/anim_commands.asm
+++ b/engine/battle_anims/anim_commands.asm
@@ -112,10 +112,10 @@ RunBattleAnimScript:
 	cp ROLLOUT
 	jr nz, .not_rollout
 
-	ld a, $2e
-	ld b, 5
-	ld de, 4
-	ld hl, wActiveBGEffects
+	ld a, ANIM_BG_2E
+	ld b, NUM_BG_EFFECTS
+	ld de, BG_EFFECT_STRUCT_LENGTH
+	ld hl, wBGEffect1Function
 .find
 	cp [hl]
 	jr z, .done
@@ -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
@@ -267,12 +268,12 @@ RunBattleAnimCommand:
 	ret
 
 .CheckTimer:
-	ld a, [wBattleAnimDuration]
+	ld a, [wBattleAnimDelay]
 	and a
 	jr z, .done
 
 	dec a
-	ld [wBattleAnimDuration], a
+	ld [wBattleAnimDelay], a
 	and a
 	ret
 
@@ -289,17 +290,17 @@ 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
-	cp $d0
+	cp anim_obj_command
 	jr nc, .do_anim
 
-	ld [wBattleAnimDuration], a
+	ld [wBattleAnimDelay], a
 	ret
 
 .do_anim
@@ -310,7 +311,7 @@ RunBattleAnimCommand:
 .DoCommand:
 ; Execute battle animation command in [wBattleAnimByte].
 	ld a, [wBattleAnimByte]
-	sub $d0
+	sub anim_obj_command
 
 	ld e, a
 	ld d, 0
@@ -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
@@ -643,10 +644,13 @@ BattleAnimCmd_ResetObp0:
 	ret
 
 BattleAnimCmd_ClearObjs:
+; BUG: This function only clears the first 6+(2/3) objects
+
 	ld hl, wActiveAnimObjects
 	ld a, $a0
+	; ld a, wActiveAnimObjectsEnd - wActiveAnimObjects
 .loop
-	ld [hl], $0
+	ld [hl], 0
 	inc hl
 	dec a
 	jr nz, .loop
@@ -693,7 +697,7 @@ endr
 
 BattleAnimCmd_IncObj:
 	call GetBattleAnimByte
-	ld e, 10
+	ld e, NUM_ANIM_OBJECTS
 	ld bc, wActiveAnimObjects
 .loop
 	ld hl, BATTLEANIMSTRUCT_INDEX
@@ -718,8 +722,8 @@ BattleAnimCmd_IncObj:
 
 BattleAnimCmd_IncBGEffect:
 	call GetBattleAnimByte
-	ld e, 5
-	ld bc, wActiveBGEffects
+	ld e, NUM_BG_EFFECTS
+	ld bc, wBGEffect1Function
 .loop
 	ld hl, $0
 	add hl, bc
@@ -743,7 +747,7 @@ BattleAnimCmd_IncBGEffect:
 
 BattleAnimCmd_SetObj:
 	call GetBattleAnimByte
-	ld e, 10
+	ld e, NUM_ANIM_OBJECTS
 	ld bc, wActiveAnimObjects
 .loop
 	ld hl, BATTLEANIMSTRUCT_INDEX
@@ -1152,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:
@@ -1430,10 +1434,10 @@ BattleAnim_SetOBPals:
 	ret
 
 BattleAnim_UpdateOAM_All:
-	ld a, $0
+	ld a, 0
 	ld [wBattleAnimOAMPointerLo], a
 	ld hl, wActiveAnimObjects
-	ld e, 10
+	ld e, NUM_ANIM_OBJECTS
 .loop
 	ld a, [hl]
 	and a
diff --git a/engine/battle_anims/bg_effects.asm b/engine/battle_anims/bg_effects.asm
index 0f2e716ca..00eb9a4ce 100644
--- a/engine/battle_anims/bg_effects.asm
+++ b/engine/battle_anims/bg_effects.asm
@@ -10,7 +10,7 @@
 
 ExecuteBGEffects:
 	ld hl, wActiveBGEffects
-	ld e, 5
+	ld e, NUM_BG_EFFECTS
 .loop
 	ld a, [hl]
 	and a
@@ -23,7 +23,7 @@ ExecuteBGEffects:
 	pop de
 	pop hl
 .next
-	ld bc, 4
+	ld bc, BG_EFFECT_STRUCT_LENGTH
 	add hl, bc
 	dec e
 	jr nz, .loop
@@ -31,12 +31,12 @@ ExecuteBGEffects:
 
 QueueBGEffect:
 	ld hl, wActiveBGEffects
-	ld e, 5
+	ld e, NUM_BG_EFFECTS
 .loop
 	ld a, [hl]
 	and a
 	jr z, .load
-	ld bc, 4
+	ld bc, BG_EFFECT_STRUCT_LENGTH
 	add hl, bc
 	dec e
 	jr nz, .loop
@@ -416,7 +416,7 @@ BattleBGEffect_BattlerObj_1Row:
 .zero
 	call BGEffect_CheckFlyDigStatus
 	jr z, .not_flying_digging
-	ld hl, wNumActiveBattleAnims
+	ld hl, wLastAnimObjectIndex
 	inc [hl]
 	call EndBattleBGEffect
 	ret
@@ -483,7 +483,7 @@ BattleBGEffect_BattlerObj_2Row:
 .zero
 	call BGEffect_CheckFlyDigStatus
 	jr z, .not_flying_digging
-	ld hl, wNumActiveBattleAnims
+	ld hl, wLastAnimObjectIndex
 	inc [hl]
 	call EndBattleBGEffect
 	ret
diff --git a/engine/battle_anims/core.asm b/engine/battle_anims/core.asm
index 65e16c792..171816f38 100644
--- a/engine/battle_anims/core.asm
+++ b/engine/battle_anims/core.asm
@@ -1,6 +1,6 @@
 QueueBattleAnimation:
 	ld hl, wActiveAnimObjects
-	ld e, 10
+	ld e, NUM_ANIM_OBJECTS
 .loop
 	ld a, [hl]
 	and a
@@ -15,7 +15,7 @@ QueueBattleAnimation:
 .done
 	ld c, l
 	ld b, h
-	ld hl, wNumActiveBattleAnims
+	ld hl, wLastAnimObjectIndex
 	inc [hl]
 	call InitBattleAnimation
 	ret
@@ -38,7 +38,7 @@ endr
 	ld d, h
 	ld hl, BATTLEANIMSTRUCT_INDEX
 	add hl, bc
-	ld a, [wNumActiveBattleAnims]
+	ld a, [wLastAnimObjectIndex]
 	ld [hli], a ; Index
 	ld a, [de]
 	inc de
@@ -80,32 +80,36 @@ endr
 BattleAnimOAMUpdate:
 	call InitBattleAnimBuffer
 	call GetBattleAnimFrame
-	cp -3
+	cp dowait_command
 	jp z, .done
-	cp -4
+	cp delanim_command
 	jp z, .delete
+
 	push af
 	ld hl, wBattleAnimTempOAMFlags
-	ld a, [wBattleAnimTempAddSubFlags]
+	ld a, [wBattleAnimTempFrameOAMFlags]
 	xor [hl]
-	and $e0
+	and PRIORITY | Y_FLIP | X_FLIP
 	ld [hl], a
 	pop af
+
 	push bc
 	call GetBattleAnimOAMPointer
 	ld a, [wBattleAnimTempTileID]
-	add [hl]
+	add [hl] ; tile offset
 	ld [wBattleAnimTempTileID], a
 	inc hl
-	ld a, [hli]
+	ld a, [hli] ; oam data length
 	ld c, a
-	ld a, [hli]
+	ld a, [hli] ; oam data pointer
 	ld h, [hl]
 	ld l, a
 	ld a, [wBattleAnimOAMPointerLo]
 	ld e, a
 	ld d, HIGH(wVirtualOAM)
+
 .loop
+	; Y Coord
 	ld a, [wBattleAnimTempYCoord]
 	ld b, a
 	ld a, [wBattleAnimTempYOffset]
@@ -114,16 +118,17 @@ BattleAnimOAMUpdate:
 	push hl
 	ld a, [hl]
 	ld hl, wBattleAnimTempOAMFlags
-	bit 6, [hl]
+	bit OAM_Y_FLIP, [hl]
 	jr z, .no_yflip
 	add $8
 	xor $ff
 	inc a
-
 .no_yflip
 	pop hl
 	add b
 	ld [de], a
+
+	; X Coord
 	inc hl
 	inc de
 	ld a, [wBattleAnimTempXCoord]
@@ -134,43 +139,47 @@ BattleAnimOAMUpdate:
 	push hl
 	ld a, [hl]
 	ld hl, wBattleAnimTempOAMFlags
-	bit 5, [hl]
+	bit OAM_X_FLIP, [hl]
 	jr z, .no_xflip
 	add $8
 	xor $ff
 	inc a
-
 .no_xflip
 	pop hl
 	add b
 	ld [de], a
+
+	; Tile ID
 	inc hl
 	inc de
 	ld a, [wBattleAnimTempTileID]
 	add BATTLEANIM_BASE_TILE
 	add [hl]
 	ld [de], a
+
+	; Attributes
 	inc hl
 	inc de
 	ld a, [wBattleAnimTempOAMFlags]
 	ld b, a
 	ld a, [hl]
 	xor b
-	and $e0
+	and PRIORITY | Y_FLIP | X_FLIP
 	ld b, a
 	ld a, [hl]
-	and $10
+	and OBP_NUM
 	or b
 	ld b, a
 	ld a, [wBattleAnimTempPalette]
-	and $f
+	and (PRIORITY | Y_FLIP | X_FLIP | OBP_NUM) ^ $ff
 	or b
 	ld [de], a
+
 	inc hl
 	inc de
 	ld a, e
 	ld [wBattleAnimOAMPointerLo], a
-	cp $a0
+	cp LOW(wVirtualOAMEnd)
 	jr nc, .exit_set_carry
 	dec c
 	jr nz, .loop
@@ -193,10 +202,11 @@ InitBattleAnimBuffer:
 	ld hl, BATTLEANIMSTRUCT_01
 	add hl, bc
 	ld a, [hl]
-	and %10000000
+
+	and PRIORITY
 	ld [wBattleAnimTempOAMFlags], a
 	xor a
-	ld [wBattleAnimTempAddSubFlags], a
+	ld [wBattleAnimTempFrameOAMFlags], a
 	ld hl, BATTLEANIMSTRUCT_PALETTE
 	add hl, bc
 	ld a, [hl]
@@ -217,15 +227,18 @@ InitBattleAnimBuffer:
 	ld [wBattleAnimTempXOffset], a
 	ld a, [hli]
 	ld [wBattleAnimTempYOffset], a
+
 	ldh a, [hBattleTurn]
 	and a
 	ret z
+
 	ld hl, BATTLEANIMSTRUCT_01
 	add hl, bc
 	ld a, [hl]
 	ld [wBattleAnimTempOAMFlags], a
 	bit 0, [hl]
 	ret z
+
 	ld hl, BATTLEANIMSTRUCT_XCOORD
 	add hl, bc
 	ld a, [hli]
diff --git a/engine/battle_anims/helpers.asm b/engine/battle_anims/helpers.asm
index 4a7f2950c..64d43f032 100644
--- a/engine/battle_anims/helpers.asm
+++ b/engine/battle_anims/helpers.asm
@@ -37,16 +37,16 @@ GetBattleAnimFrame:
 	push af
 	ld a, [hl]
 	push hl
-	and $3f
+	and (Y_FLIP << 1 | X_FLIP << 1) ^ $ff
 	ld hl, BATTLEANIMSTRUCT_DURATION
 	add hl, bc
 	ld [hl], a
 	pop hl
 .okay
 	ld a, [hl]
-	and $c0
+	and Y_FLIP << 1 | X_FLIP << 1 ; The << 1 is compensated in the "frame" macro
 	srl a
-	ld [wBattleAnimTempAddSubFlags], a
+	ld [wBattleAnimTempFrameOAMFlags], a
 	pop af
 	ret
 
@@ -55,6 +55,7 @@ GetBattleAnimFrame:
 	ld hl, BATTLEANIMSTRUCT_DURATION
 	add hl, bc
 	ld [hl], a
+
 	ld hl, BATTLEANIMSTRUCT_FRAME
 	add hl, bc
 	dec [hl]
diff --git a/engine/gfx/sprites.asm b/engine/gfx/sprites.asm
index 76519eb62..79cd71671 100644
--- a/engine/gfx/sprites.asm
+++ b/engine/gfx/sprites.asm
@@ -315,8 +315,8 @@ UpdateAnimFrame:
 AddOrSubtractY:
 	push hl
 	ld a, [hl]
-	ld hl, wCurSpriteAddSubFlags
-	bit 6, [hl]
+	ld hl, wCurSpriteOAMFlags
+	bit OAM_Y_FLIP, [hl]
 	jr z, .ok
 	; 8 - a
 	add $8
@@ -330,8 +330,8 @@ AddOrSubtractY:
 AddOrSubtractX:
 	push hl
 	ld a, [hl]
-	ld hl, wCurSpriteAddSubFlags
-	bit 5, [hl] ; x flip
+	ld hl, wCurSpriteOAMFlags
+	bit OAM_X_FLIP, [hl]
 	jr z, .ok
 	; 8 - a
 	add $8
@@ -343,20 +343,20 @@ AddOrSubtractX:
 	ret
 
 GetSpriteOAMAttr:
-	ld a, [wCurSpriteAddSubFlags]
+	ld a, [wCurSpriteOAMFlags]
 	ld b, a
 	ld a, [hl]
 	xor b
-	and $e0
+	and PRIORITY | Y_FLIP | X_FLIP
 	ld b, a
 	ld a, [hl]
-	and $1f
+	and (PRIORITY | Y_FLIP | X_FLIP) ^ $ff
 	or b
 	ret
 
 InitSpriteAnimBuffer:
 	xor a
-	ld [wCurSpriteAddSubFlags], a
+	ld [wCurSpriteOAMFlags], a
 	ld hl, SPRITEANIMSTRUCT_TILE_ID
 	add hl, bc
 	ld a, [hli]
@@ -436,7 +436,7 @@ GetSpriteAnimFrame:
 	push af
 	ld a, [hl]
 	push hl
-	and $3f
+	and (Y_FLIP << 1 | X_FLIP << 1) ^ $ff
 	ld hl, SPRITEANIMSTRUCT_DURATIONOFFSET
 	add hl, bc
 	add [hl]
@@ -446,9 +446,9 @@ GetSpriteAnimFrame:
 	pop hl
 .okay
 	ld a, [hl]
-	and $c0
+	and Y_FLIP << 1 | X_FLIP << 1 ; The << 1 is compensated in the "frame" macro
 	srl a
-	ld [wCurSpriteAddSubFlags], a
+	ld [wCurSpriteOAMFlags], a
 	pop af
 	ret
 
diff --git a/macros/legacy.asm b/macros/legacy.asm
index 8be6b3798..0aa4d5e4d 100644
--- a/macros/legacy.asm
+++ b/macros/legacy.asm
@@ -174,3 +174,6 @@ limited_interpret_data EQUS "text_dots"
 link_wait_button       EQUS "text_linkwaitbutton"
 current_day            EQUS "text_today"
 text_jump              EQUS "text_far"
+
+; macros/scripts/battle_anims.asm
+anim_clearsprites EQUS "anim_keepsprites"
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
 
diff --git a/macros/scripts/gfx_anims.asm b/macros/scripts/gfx_anims.asm
index 8f33512ec..3756481dd 100644
--- a/macros/scripts/gfx_anims.asm
+++ b/macros/scripts/gfx_anims.asm
@@ -15,20 +15,20 @@ ENDM
 	enum_start $fc
 
 	enum delanim_command ; $fc
-delanim: MACRO ; used for oam
+delanim: MACRO
+; Removes the object from the screen, as opposed to `endanim` which just stops all motion
 	db delanim_command
 ENDM
 
-	enum dorepeat_command ; $fd
-dorepeat: MACRO
-	db dorepeat_command
-	db \1 ; #
+	enum dowait_command ; $fd
+dowait: MACRO
+	db dowait_command
+	db \1 ; frames
 ENDM
 
-	enum setrepeat_command ; $fe
-setrepeat: MACRO
-	db setrepeat_command
-	db \1 ; #
+	enum dorestart_command ; $fe
+dorestart: MACRO
+	db dorestart_command
 ENDM
 
 	enum endanim_command ; $ff
@@ -36,9 +36,18 @@ endanim: MACRO
 	db endanim_command
 ENDM
 
-__enum__ = $fe
 
-	enum dorestart_command ; $fe
-dorestart: MACRO ; used for oam
-	db dorestart_command
+; Used for pic animations
+__enum__ = $fd
+
+	enum dorepeat_command ; $fd
+dorepeat: MACRO
+	db dorepeat_command
+	db \1 ; command offset to jump to
+ENDM
+
+	enum setrepeat_command ; $fe
+setrepeat: MACRO
+	db setrepeat_command
+	db \1 ; amount of times to repeat
 ENDM
diff --git a/wram.asm b/wram.asm
index f15e9f296..7fa8363d7 100644
--- a/wram.asm
+++ b/wram.asm
@@ -263,7 +263,7 @@ wCurIcon:: db ; c3b6
 wCurIconTile:: db
 wSpriteAnimAddrBackup::
 wSpriteAnimIDBuffer::
-wCurSpriteAddSubFlags::
+wCurSpriteOAMFlags::
 	dw
 wCurAnimVTile:: db
 wCurAnimXCoord:: db
@@ -3045,11 +3045,11 @@ wBGEffect4:: battle_bg_effect wBGEffect4
 wBGEffect5:: battle_bg_effect wBGEffect5
 wActiveBGEffectsEnd::
 
-wNumActiveBattleAnims:: db ; d40e
+wLastAnimObjectIndex:: db ; d40e
 
 wBattleAnimFlags:: db ; d40f
 wBattleAnimAddress:: dw ; d410
-wBattleAnimDuration:: db ; d412
+wBattleAnimDelay:: db ; d412
 wBattleAnimParent:: dw ; d413
 wBattleAnimLoops:: db ; d415
 wBattleAnimVar:: db ; d416
@@ -3077,7 +3077,7 @@ wBattleAnimTempXCoord:: db
 wBattleAnimTempYCoord:: db
 wBattleAnimTempXOffset:: db
 wBattleAnimTempYOffset:: db
-wBattleAnimTempAddSubFlags:: db
+wBattleAnimTempFrameOAMFlags:: db
 wBattleAnimTempPalette:: db
 ENDU ; d422