ref: 3540b2a2d646c1a9768a37a235b20adaa651c07a
dir: /docs/battle_anim_commands.md/
# Battle Animation Commands Defined in [macros/scripts/battle_anims.asm](/macros/scripts/battle_anims.asm) and [engine/battle_anims/anim_commands.asm:BattleAnimCommands](/engine/battle_anims/anim_commands.asm). ## `$00`−`$CF`: <code>anim_wait <i>length</i></code> - *length*: duration in frames ## `$D0`: <code>anim_obj <i>object</i>, <i>x</i>, <i>y</i>, <i>param</i></code> ***Alternate*: <code>anim_obj <i>object</i>, <i>x_tile</i>, <i>x</i>, <i>y_tile</i>, <i>y</i>, <i>param</i></code>** Spawns an *object* at coordinate (*x*, *y*). - *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. 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* ## `$D1`: <code>anim_1gfx <i>gfx</i></code> ## `$D2`: <code>anim_2gfx <i>gfx1</i>, <i>gfx2</i></code> ## `$D3`: <code>anim_3gfx <i>gfx1</i>, <i>gfx2</i>, <i>gfx3</i></code> ## `$D4`: <code>anim_4gfx <i>gfx1</i>, <i>gfx2</i>, <i>gfx3</i>, <i>gfx4</i></code> ## `$D5`: <code>anim_5gfx <i>gfx1</i>, <i>gfx2</i>, <i>gfx3</i>, <i>gfx4</i>, <i>gfx5</i></code> Loads 1-5 sets of graphics. Will overwrite any previously loaded sets. - *gfx*: `ANIM_GFX` constants (see [constants/battle_anim_constants.asm](/constants/battle_anim_constants.asm)) ## `$D6`: <code>anim_incobj <i>object_id</i></code> 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`: <code>anim_setobj <i>object_id</i>, <i>state</i></code> 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`: <code>anim_incbgeffect <i>bg_effect</i></code> 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`. ## `$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 `BattleAnimVar` to the result of [GetPokeBallWobble](/engine/battle_anims/pokeball_wobble.asm). ## `$DC`: `anim_transform` ## `$DD`: `anim_raisesub` ## `$DE`: `anim_dropsub` ## `$DF`: `anim_resetobp0` Resets rOBP0 to the default (`q0123` or `%00011011`). ## `$E0`: <code>anim_sound <i>duration</i>, <i>tracks</i>, <i>sound_id</i></code> Plays a sound. ## `$E1`: <code>anim_cry <i>pitch</i></code> 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`: <code>anim_if_param_and <i>value</i>, <i>address</i></code> ## `$EF`: <code>anim_jumpuntil <i>address</i></code> Jumps to another script and decrements `param` until it reaches 0. Similar to `anim_loop`. ## `$F0`: <code>anim_bgeffect <i>bg_effect</i>, <i>unknown1</i>, <i>unknown2</i>, <i>unknown3</i></code> - *bg_effect*: `ANIM_BG` constants (see [constants/battle_anim_constants.asm](/constants/battle_anim_constants.asm)) ## `$F1`: <code>anim_bgp <i>colors</i></code> Sets `rBGP` to *colors*. ## `$F2`: <code>anim_obp0 <i>colors</i></code> Sets `rOBP0` to *colors*. ## `$F3`: <code>anim_obp1 <i>colors</i></code> 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`: <code>anim_if_param_equal <i>value</i>, <i>address</i></code> Jumps to another script if `wBattleAnimParam` (aka `wKickCounter` or `wPresentPower`) is equal to *value*. ## `$F9`: <code>anim_setvar <i>value</i></code> Sets `BattleAnimVar` to *value*. ## `$FA`: `anim_incvar` Increments `BattleAnimVar` by 1. ## `$FB`: <code>anim_if_var_equal <i>value</i>, <i>address</i></code> Jumps to another script if `BattleAnimVar` is equal to *value*. ## `$FC`: <code>anim_jump <i>address</i></code> Jumps to another script. ## `$FD`: <code>anim_loop <i>count</i>, <i>address</i></code> Jumps to another script up to *count* times. Then does nothing, allowing execution to continue. ## `$FE`: <code>anim_call <i>address</i></code> 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.