Move animations
Overview
Section titled “Overview”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...endmove ID [ID ...] ...commands...endfallback TYPE CATEGORY NAMEgfxnames an effect picture: a PNG undergraphics/battle/of at most 15 colours plus clear, cut into frames ofSIZE. The size must be a DS sprite’s, such as16x16,32x32or64x32, because each frame is drawn as one hardware sprite.periodis how many frames each picture frame shows (4 if not said).scriptis a shared piece other scriptscall: a hit, a burst, an opening.moveis the script of one or more moves, by the identifiers of your data, compared without case or punctuation.fallbackis the script for a move of a type (anyfor every type) and a category (physical,special,statusorany) with no script of its own. A move looks for its own script, then its type’s fallback, then theanytype’s.
Example
Section titled “Example”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 6endA 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 syncendThe 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 strikefallback any status boostfallback any special plain_shotfallback EMBER special ember_shotfallback TIDE special tide_shotAnd 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 syncendThe 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.
Placement
Section titled “Placement”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.
Commands
Section titled “Commands”| 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.
Limits
Section titled “Limits”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).
Styles
Section titled “Styles”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, andbackgroundcolours 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,
translucentsprites,orbitandwavepaths,flashfor light, and longer, smootherramps andsines on the battlers. Such a game usually gives its creatures motions as well.
Imports
Section titled “Imports”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.