Skip to content

Move animations

When a creature uses a move, the battle says “X used Y!” and then plays the move’s animation; the battle waits for it to end. The animation is a short script in the project, not code. That has three reasons:

  • Every move shows something. A move without its own script plays its type’s and category’s fallback, so a game with a hundred invented moves needs only a handful of scripts to look finished.
  • The same on both platforms. Every value is a whole number and nothing is random, so a script plays frame for frame alike on desktop and DS (plan 10 keeps presentation apart from the battle’s state; an animation never changes it).
  • Imports and creators share one format. The importer writes the same file a creator writes by hand.

A game without the file shows the engine’s own: a lunge for moves that do damage and two small hops for the others. ploom build makes the file into the pack’s moveanims.pfv.

Creatures also move when they appear in battle and when their summary opens. Those motions are a separate file, graphics/creatures/motions.toml, with the same channels and shapes (Creatures and data).

graphics/battle/anims.txt holds one thing a line; # starts a comment (a word #rrggbb is a colour, not a comment). There are four kinds of entry:

gfx NAME FILE SIZE [frames=N] [period=N]
script NAME
...commands...
end
move ID [ID ...]
...commands...
end
fallback TYPE CATEGORY NAME
  • gfx names an effect picture: a PNG under graphics/battle/ of at most 15 colours plus clear, cut into frames of SIZE. The size must be a DS sprite’s, such as 16x16, 32x32 or 64x32, because each frame is drawn as one hardware sprite. period is how many frames each picture frame shows (4 if not said).
  • script is a shared piece other scripts call: a hit, a burst, an opening.
  • move is the script of one or more moves, by the identifiers of your data, compared without case or punctuation.
  • fallback is the script for a move of a type (any for every type) and a category (physical, special, status or any) with no script of its own. A move looks for its own script, then its type’s fallback, then the any type’s.

The sample’s graphics/battle/anims.txt has a fallback for each of its eight types and a few moves of their own. Its shared hit, used by almost everything:

gfx impact anims/impact.png 32x32 frames=2 period=4
# A hit: the burst on the target, which shakes and flashes.
script hit
sound bump at=target
sprite impact from=target frames=8 once
battler target x square 2 frames=12 cycles=3 env=fade
tint target #ffffff hold 10 frames=4
wait 6
end

A special move of the Ember type throws two embers in arcs, then hits and tints the target orange:

gfx ember anims/ember.png 16x16 frames=2 period=3
script ember_shot
sound click
sprite ember from=user to=target path=arc arc=12 frames=16
wait 4
sprite ember from=user to=target:0,-6 path=arc arc=18 frames=16
wait 12
call hit
tint target #f05020 sine 8 frames=16 cycles=1
sync
end

The fallbacks tie scripts to types and categories. The first three cover every move; the rest give each type its own special attack:

fallback any physical strike
fallback any status boost
fallback any special plain_shot
fallback EMBER special ember_shot
fallback TIDE special tide_shot

And one move with a script of its own, Nightfall, darkens the scene, circles the target with shadows and brings the light back:

move NIGHTFALL
background #100818
flash ramp 0 -6 frames=10
wait 10
flash hold -6 frames=24
sprite shade from=target path=orbit arc=18 turns=1 frames=24
sprite shade from=target path=orbit arc=18 turns=1 phase=85 frames=24
sprite shade from=target path=orbit arc=18 turns=1 phase=170 frames=24
tint target #8040c0 sine 10 frames=24 cycles=2
wait 24
flash ramp -6 0 frames=8
wait 8
background restore
sync
end

The sample’s pictures are drawn by tools/pl-samplekit, so the file says not to edit it by hand; a project of your own edits its file freely and rebuilds.

A sprite starts and ends at a place: user, target, middle, user_feet, target_feet or screen, with an optional offset in pixels, target:0,-6 (right and down are positive).

Scripts are written for a move by the player’s creature at the foe: bottom left to top right. When the foe uses the move, every sideways offset is mirrored, so one script works both ways. A sprite marked fixed is not mirrored; one marked flip is also drawn mirrored.

Battlers are named by who they are to the move: user, target, both, all (every creature, and the background for tints), partner (the user’s partner in doubles) and others.

Command What it does
wait N waits N frames (60 a second)
sync waits until every sprite and motion started so far has ended
call NAME [times=N] plays a script, N times in a row
sprite GFX from=PLACE [to=PLACE] [path=P] frames=N ... shows an effect picture moving along a path
battler WHO CHANNEL SHAPE A [B] frames=N ... moves, sizes or turns a battler
tint WHO #rrggbb SHAPE A [B] frames=N blends a battler’s colours, or the background’s, towards a colour (0 none, 16 all the way)
flash SHAPE A [B] frames=N the whole scene towards white (up to 16) or black (down to -16)
shake WHO x|y AMOUNT frames=N shakes a battler or the screen, dying away
background #rrggbb / background restore a plain colour behind everything instead of the place’s picture, and back
sound NAME [at=PLACE] a sound effect of audio/audio.txt, heard from that side
hide WHO / show WHO hides or shows a battler (for Fly or Dig); all are shown again when the script ends

Paths of a sprite: still (the default), line, arc (a throw raised by arc pixels), wave (swaying by arc pixels, turns waves) and orbit (round from at a radius of arc, turns times; phase 0 to 255 starts it further round). Words after the options: flip, fixed, translucent, behind (behind the battlers) and once (the picture’s frames play once and hold).

Channels of battler: x and y in pixels (x is always forwards, towards the other side), size, wide and tall in percent, and turn in degrees.

Shapes give a value over the command’s frames: hold A (steady), ramp A B (straight from A to B), sine A (a sine wave, cycles of them), hop A (the top halves of a sine) and square A (A, then -A: a shake). env= shapes it further: flat, fade, swell or arch. Every motion, tint and flash ends by itself, so a script never has to put anything back.

One move’s animation, with the scripts it calls, may use at most: 256 commands, 8 scripts (calls 3 deep), 4 pictures of 64 sprite tiles together (a 16 × 16 frame is 4 tiles, a 32 × 32 frame 16), 16 sprites and 16 motions at once, and 20 seconds. The build names the script that is over a limit, with its line.

The limits come from the DS. On DS the pictures are loaded into sprite memory when the move begins and the scripts sit in a 4 KB buffer made when the battle starts; nothing else is held. The battle’s sprite memory is shared with the battlers and the interface, so effects get 64 tiles of their own; when those are not free they borrow the player figure’s, which is read in again before it is next shown (Memory).

The engine plays one kind of script; the look is in the pictures and in how the scripts are written.

  • A GBA look: small, flat pictures with few colours (16 × 16 and 32 × 32), quick motions, many tints of battlers and background (the GBA games blend palettes a lot), shakes, and background colours for dark moves.
  • A DS look: the generation-4 games draw effects as 3D particles in many colours. Here, use larger pictures with more frames, translucent sprites, orbit and wave paths, flash for light, and longer, smoother ramps and sines on the battlers. Such a game usually gives its creatures motions as well.

ploom import of Emerald’s decompilation converts each move’s animation script from the user’s own tree at import time, with its effect pictures, into the import. The import report says how each command was converted: the same command, a guess, not needed, or left out. Sound effects keep Emerald’s names, so they are silent until the project’s audio.txt has sounds of those names; the build reports which are missing.

Platinum, HeartGold and Black are not converted. Their moves play the fallbacks the project writes. Platinum’s effects are 3D particle emitters, which would need a reader that bakes them into sprite frames; HeartGold’s and Black’s scripts are binary data in the ROM. None of this is scheduled.