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`.

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

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

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

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]

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
 

wram.asm

@@ -3049,7 +3049,7 @@ wNumActiveBattleAnims:: 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