Anotate more of the battle anim subsystem

The X and Y flip flags can be applied through the stack consisting of:
- Object attributes
- Animation frame attributes
- OAM Data
Each of these negate eachother.

Confused yet? The same stack is traversed to obtain the final tile ID,
with an added layer on top for the base GFX offset and the offset for
the dynamically loaded GFX requested by the object!

wBattleAnimDelay is populated with the values passed to `anim_wait`.

3 files changed, 36 insertions, 23 deletions

diff --git a/engine/battle_anims/anim_commands.asm b/engine/battle_anims/anim_commands.asm
index f6c6b06a6..6c30ab51d 100644
--- a/engine/battle_anims/anim_commands.asm
+++ b/engine/battle_anims/anim_commands.asm
@@ -267,12 +267,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
 
@@ -296,10 +296,10 @@ RunBattleAnimCommand:
 	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 +310,7 @@ RunBattleAnimCommand:
 .DoCommand:
 ; Execute battle animation command in [wBattleAnimByte].
 	ld a, [wBattleAnimByte]
-	sub $d0
+	sub anim_obj_command
 
 	ld e, a
 	ld d, 0
diff --git a/engine/battle_anims/core.asm b/engine/battle_anims/core.asm
index 65e16c792..86863389c 100644
--- a/engine/battle_anims/core.asm
+++ b/engine/battle_anims/core.asm
@@ -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 $e0 ; Keep priority, x flip and y flip flags.
 	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
 	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
 	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..127fe5412 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 %00111111
 	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