Merge pull request #451 from yenatch/document-battle-anim-macros

Fix and document some battle animation macros

docs/battle_anim_commands.md

@@ -3,28 +3,30 @@
 Defined in [macros/scripts/battle_anims.asm](/macros/scripts/battle_anims.asm) and [data/moves/animations.asm:BattleAnimations](/data/moves/animations.asm).
 
 
-## `$00`−`$EF`: `anim_wait` *length*
+## `$00`−`$CF`: `anim_wait` *length*
 
-## `$D0`: `anim_obj` *object*, *x1*, *x2*, *y1*, *y2*, *param*
+- *length*: duration in frames
 
-The *x1*/*x2* and *y1*/*y2* pairs specify the position on screen of the animation object.
-*x1*/*y1* specify a tile position, and *x2*/*y2* specify a pixel offset from that tile. 
 
-Values for *x2*/*y2* are in the 0-7 range, since 8 pixels make a tile.
+## `$D0`: `anim_obj` *object*, *x*, *y*, *param*
+*Alternate*: `anim_obj` *object*, *x_tile*, *x*, *y_tile*, *y*, *param*
 
-Values for *x1* are between -16 to 31. In practice *x1* starts between 0 to 15, then between -16 to -10. Negative values are relative to the opponent, while positive values are relative to the player. Useful values are between 14 to -10 (for the opponent) and between 0 to 13 (for the player).
+Spawns an *object* at coordinate (*x*, *y*).
 
-Some sample values are:
+- *object*: `ANIM_OBJ` constants (see [constants/battle_anim_constants.asm](/constants/battle_anim_constants.asm))
+- *x*: the x position in pixels
+- *y*: the y position in pixels
+- *x_tile*: an added x position in tiles (8 pixels)
+- *y_tile*: an added y position in tiles (8 pixels)
+- *param*: modifies the behavior of *object*. The meaning differs for each object.
 
-- 0: player left border
-- 6: player center
-- -15: enemy center
-- -10: enemy right border
+The y position also depends on the y offset defined by the object.
+
+- *TODO: what happens for x/y values greater than 160/144 respectively? Is it 1:1 with screen coordinates?*
+- *TODO: how are the x/y values mirrored when the opponent is attacking?*
+- *TODO: useful positions*
+- *TODO: document each object*
 
-Values for *y1* are also between -16 to 31; the useful range is between 2 to 14.
-Values between 2 to 8 will be in the opponent's area (2 being the top border and 8 being the
-bottom border), and values between 8 to 14 will be in the player's area (again, 8 being the top border and 14 being the bottom border).
-The center of the body is often 2 to 4 tiles away from the border (i.e., 5-6 for the opponent or 10-11 for the player).
 
 ## `$D1`: `anim_1gfx` *gfx*
 
@@ -36,86 +38,186 @@ The center of the body is often 2 to 4 tiles away from the border (i.e., 5-6 for
 
 ## `$D5`: `anim_5gfx` *gfx1*, *gfx2*, *gfx3*, *gfx4*, *gfx5*
 
-## `$D6`: `anim_incobj` *id*
+Loads 1-5 sets of graphics. Will overwrite any previously loaded sets.
 
-## `$D7`: `anim_setobj` *id*, *object*
+- *gfx*: `ANIM_GFX` constants (see [constants/battle_anim_constants.asm](/constants/battle_anim_constants.asm))
+
+
+## `$D6`: `anim_incobj` *object_id*
+
+Increments an object's state.
+
+- *object_id*: the nth object in order of creation
+
+Objects are state machines. `anim_incobj` progresses the state of an object.
+
+## `$D7`: `anim_setobj` *object_id*, *state*
+
+Sets an object's state to a specific value.
+
+- *object_id*: the nth object in order of creation
+- *state*: the state index
+
+Objects are state machines. `anim_setobj` changes the state of an object.
+
+## `$D8`: `anim_incbgeffect` *bg_effect*
+
+Increments a bg effect's state.
+
+- *bg_effect*: `ANIM_BG` constants (see [constants/battle_anim_constants.asm](/constants/battle_anim_constants.asm))
+
+Since there can't be two of the same bg effect, the effect type is used. This is distinct from `anim_incobj`.
 
-## `$D8`: `anim_incbgeffect` *effect*
 
 ## `$D9`: `anim_enemyfeetobj`
 
+Temporarily creates sprites from the bottom row of the enemy frontpic, so that the player backpic can be moved around without corrupting the enemy frontpic.
+
 ## `$DA`: `anim_playerheadobj`
 
+Temporarily creates sprites from the top row of the player backpic, so that the enemy frontpic can be moved around without corrupting the player backpic.
+
+
 ## `$DB`: `anim_checkpokeball`
 
+Sets `var` to the result of [GetPokeBallWobble](/engine/battle_anims/getpokeballwobble.asm).
+
+
 ## `$DC`: `anim_transform`
 
 ## `$DD`: `anim_raisesub`
 
 ## `$DE`: `anim_dropsub`
 
+
 ## `$DF`: `anim_resetobp0`
 
-## `$E0`: `anim_sound` *duration*, *tracks*, *id*
+Resets rOBP0 to the default (`q0123` or `%00011011`).
+
+
+## `$E0`: `anim_sound` *duration*, *tracks*, *sound_id*
+
+Plays a sound.
 
 ## `$E1`: `anim_cry` *pitch*
 
+Plays the user's cry.
+
+
 ## `$E2`: `anim_minimizeopp`
 
+
 ## `$E3`: `anim_oamon`
 
 ## `$E4`: `anim_oamoff`
 
+
 ## `$E5`: `anim_clearobjs`
 
+Removes all active objects.
+
+
 ## `$E6`: `anim_beatup`
 
+
 ## `$E7`: `anim_0xe7`
 
+Does nothing. Unused.
+
+
 ## `$E8`: `anim_updateactorpic`
 
 ## `$E9`: `anim_minimize`
 
+
 ## `$EA`: `anim_0xea`
 
+Does nothing. Unused.
+
 ## `$EB`: `anim_0xeb`
 
+Does nothing. Unused.
+
 ## `$EC`: `anim_0xec`
 
+Does nothing. Unused.
+
 ## `$ED`: `anim_0xed`
 
+Does nothing. Unused.
+
+
 ## `$EE`: `anim_if_param_and` *value*, *address*
 
 ## `$EF`: `anim_jumpuntil` *address*
 
-## `$F0`: `anim_bgeffect` *effect*, *unknown1*, *unknown2*, *unknown3*
+Jumps to another script and decrements `param` until it reaches 0. Similar to `anim_loop`.
+
+
+## `$F0`: `anim_bgeffect` *bg_effect*, *unknown1*, *unknown2*, *unknown3*
+
+- *bg_effect*: `ANIM_BG` constants (see [constants/battle_anim_constants.asm](/constants/battle_anim_constants.asm))
+
 
 ## `$F1`: `anim_bgp` *colors*
 
+Sets `rBGP` to *colors*.
+
 ## `$F2`: `anim_obp0` *colors*
 
+Sets `rOBP0` to *colors*.
+
 ## `$F3`: `anim_obp1` *colors*
 
+Sets `rOBP1` to *colors*.
+
+
 ## `$F4`: `anim_clearsprites`
 
+
 ## `$F5`: `anim_0xf5`
 
+Does nothing. Unused.
+
 ## `$F6`: `anim_0xf6`
 
+Does nothing. Unused.
+
 ## `$F7`: `anim_0xf7`
 
+Does nothing. Unused.
+
+
 ## `$F8`: `anim_if_param_equal` *value*, *address*
 
+Jumps to another script if `wKickCounter` is equal to *value*.
+
 ## `$F9`: `anim_setvar` *value*
 
+Sets `var` to *value*.
+
 ## `$FA`: `anim_incvar`
 
+Increments `var` by 1.
+
 ## `$FB`: `anim_if_var_equal` *value*, *address*
 
+Jumps to another script if `var` is equal to *value*.
+
 ## `$FC`: `anim_jump` *address*
 
+Jumps to another script.
+
 ## `$FD`: `anim_loop` *count*, *address*
 
+Jumps to another script up to *count* times. Then does nothing, allowing execution to continue.
+
 ## `$FE`: `anim_call` *address*
 
+Calls a script.
+
+There is no call stack. The return address is overwritten, so the maximum call depth is 1.
+
 ## `$FF`: `anim_ret`
+
+Ends the script and returns to where it was called from. If there was no caller, the animation ends.

engine/sprites.asm

@@ -683,7 +683,7 @@ AnimateEndOfExpBar: ; 8e79d
 
 	ld a, $0
 	ld [hli], a
-	ld a, $6 ; OBJ 6
+	ld a, PAL_BATTLE_OB_BLUE
 	ld [hli], a
 	jr .anim_loop
 ; 8e7f4
@@ -701,7 +701,7 @@ ClearSpriteAnims2: ; 8e814
 	ld hl, wSpriteAnimDict
 	ld bc, wSpriteAnimsEnd - wSpriteAnimDict
 .loop
-	ld [hl], $0
+	ld [hl], 0
 	inc hl
 	dec bc
 	ld a, c

macros/scripts/battle_anims.asm

@@ -11,10 +11,17 @@ ENDM
 	enum anim_obj_command ; $d0
 anim_obj: MACRO
 	db anim_obj_command
-	db \1 ; obj
-	db (\2 << 3) + \3 ; x
-	db (\4 << 3) + \5 ; y
+if _NARG <= 4
+	db \1 ; object
+	db \2 ; x
+	db \3 ; y
+	db \4 ; param
+else
+	db \1 ; object
+	db (\2) * 8 + (\3) ; x_tile, x
+	db (\4) * 8 + (\5) ; y_tile, y
 	db \6 ; param
+endc
 ENDM
 
 	enum anim_1gfx_command ; $d1
@@ -60,14 +67,14 @@ ENDM
 	enum anim_incobj_command ; $d6
 anim_incobj: MACRO
 	db anim_incobj_command
-	db \1 ; id
+	db \1 ; object_id
 ENDM
 
 	enum anim_setobj_command ; $d7
 anim_setobj: MACRO
 	db anim_setobj_command
-	db \1 ; id
-	db \2 ; obj
+	db \1 ; object_id
+	db \2 ; value
 ENDM
 
 	enum anim_incbgeffect_command ; $d8
@@ -115,7 +122,7 @@ ENDM
 anim_sound: MACRO
 	db anim_sound_command
 	db (\1 << 2) | \2 ; duration, tracks
-	db \3 ; id
+	db \3 ; sound_id
 ENDM
 
 	enum anim_cry_command ; $e1