Effect VM - battle sprite effects

At a glance

Where

Battle overlay (PROT 0898). Spawn API 0x801DFDF0, per-frame walker 0x801E0080 (called once per battle frame by the draw tick), pool at _DAT_8007BD30, 5008 bytes

Input

efect.dat (extraction 0873) - a 2-pack of 14 sprite-animation records and 33 effect scripts; see effect format

Capacity

32 effects (master slots, 28 B each) × 128 sprites (child slots, 32 B each)

Textures

Effect atlas etim.dat (0870, battle-only) and the field-resident character texture band (0874 §2)

In the port

engine-vm::effect_vm (Pool::tick_retail, Pool::child_billboards), driven by World::tick_effects - the engine's only per-frame effect path; the render-mode-4 emitters are engine-effects (effect_ribbon, effect_sprite_arm, effect_default_arm)

Confidence

Confirmed - walker and spawn traced instruction-for-instruction

Used by

The animation effect arm, the per-action effect-script walk, the move-power effect lists and the per-move effect-list spawner (spawn sources)

How it works

Cast a spell and three things happen on screen: the caster poses, a stream of sprites flies to the target, and a hit flash plays. Internally that is one effect script: a list of spawn records, each saying “start sprite animation K at this offset, then wait N frames”. A master slot walks the record list; each record it reaches claims a child slot, which walks its own animation frames and drifts along a velocity until its last frame retires it.

What the slots read

The "state" bytes are wait counters. Every wait in the system is 5.3 fixed-point: a frame count stored << 3 and decremented by 8 per frame. The only data consumed are two record kinds.

Spawn record (effect script, 14 bytes each)

The script's header is [child_count][flags][spread:i16]. The two planar legs (offsets and velocities) are rotated into world space by the master's spawn angle, so one script aims wherever the caster faces. With flag bit 0 set, the spawn API rewrites every record's two offsets in place with a random value in ±spread - the resident efect.dat buffer mutates on every randomised spawn.

Animation frame (6 bytes each)

• Bursts. Zero-delay records spawn as one burst and zero-delay frames advance as one burst: both loops repeat while the freshly loaded wait is zero.
• Graceful exhaustion. On a full pool the record is still consumed with no child - effects degrade rather than stall.
• Delays wrap. The wait is stored in a byte after the << 3, so a delay of 32 frames or more wraps modulo 32.
• Motion. Each step is pos += vel × frame.speed with the retail pool scale; each child also gets two random UV-mirror bits for variety.
• Idle early-out. A sweep that finds no active master and no active child skips the remaining catch-up iterations.
• Retirement overrun. Retiring a child zeroes its active flag and its wait, but the frame-advance loop tests only the wait, so retail keeps reading 6-byte strides past the batch end on the already-dead slot until it meets a non-zero delay byte. Only the dead slot is touched (the next seed rewrites it), so the port stops at retirement instead.
• Summon side call. Spawn ids 4 and 0x13 first call the move-VM part spawner 0x80050ED4, then take the ordinary spawn path.

How a child is drawn

• Brightness envelope. With n = frame_count >> 3, the colour ramps in over the first eighth of the animation and back out over the rest, clamped at 0x80 (neutral) and written as r = g = b.
• Size. Atlas w/h × sprite_scale >> 8 (retail scale 0xA00, ten times the texel size) is the half-extent, applied in view space after the centre is transformed - so the battle camera's 4× world scale never touches it. The scale is pool state, not per-effect: Viguro’s and Theeder’s Seru modules lower it for their casts (0x600, 0x400, 0x800 on Theeder’s hits) and their closing arms restore 0xA00, so the sparks those creatures shed draw smaller than a melee hit’s. The port applies the same stores to the pool head, and the battle teardown re-inits the pool as the battle load does.
• UVs. From the 8-byte atlas entry, corner order swapped by the child's mirror bits; CLUT from atlas +4, texture page from atlas +6.
• Battle centres are Y-flipped. The pool integrates in raw PSX units, Y down. The battle view-projection both hosts share carries a trailing scale(1, -1, 1) that cancels the per-model Y-flip every mesh draw carries; a billboard has no model matrix, so the port flips its centre before building corners (effect_billboard::battle_billboard_centre). Without it a spark rising past an actor's head draws as far below its feet.
• Blend. The packet's prim code 0x2E is a semi-transparent textured quad, so every effect child blends, and the page's own ABR bits pick how: pages (320,0) / (448,0) are additive (B + F), page (384,0) is B + 0.25F - why walk dust reads as almost nothing over a bright floor. Every effect the Rim Elm spar fires resolves to the (384,0) page under a dark warm-grey CLUT row, so it is faint by data, not by a bug; the bright additive pages belong to effect ids that fight never requests. The atlas stores its page in one byte, so the blend enable has nowhere to come from except the code byte; a port that copies the page alone draws the flames as opaque tan blobs.

Each host also carries a tinted billboard outline builder - a flat rectangle around each quad, faded by age. Retail draws no such rectangle; it is a diagnostic, off by default on both hosts (LEGAIA_DIAG_FX=1 on the native window, set_battle_fx_outline(true) on the play page).

The other effect primitives: render mode 4

The pool's quads are not the only way an effect actor draws. The per-actor render dispatcher's mode 4 picks one of three emitters off a selector halfword at actor+0x9E, and the move VM writes both the mode and the selector:

All three arms carry shipped content. An earlier census concluded the default arm was the only reachable one; it swept for the stores in the wrong form and missed the move VM's own. Both hosts draw every live kind-4 node of the summon, move-FX, effect-script and field ambient parts through World::active_effect_kind4_draws, composed like a mesh part.

None of the three emitters draws anything itself. Each writes a small Legaia TMD object into a scratch buffer, and the render dispatcher then draws it as the actor's own model through the ordinary TMD path.

The ribbon

Per step the ribbon writes six vertices and six packets joining them to the next step: a core strip stored twice in the core colour, two inner flares fading core to flare colour, and two outer fringes fading flare to black. Every packet samples one fixed 2×2 texel patch, so the colour words carry the look. In play the ribbon is Gilium's summon; the other carriers are not staged as scenes by the engine.

The sprite arm

The sprite arm builds one textured quad and falls into the ordinary model draw: scaled by the part's render scale +0x72 / 0x1000, turned by the rotation banks, and handed to the prim dispatcher with the colour word +0x74 and level +0x78. The scale is seated by the spawn call, not the record. Nearly every seater passes 0x1000, and the engine seats a staged part at that value unless a cast module reports the call with its own scale - PROT 0911’s group-extent calls, PROT 0913’s depth-scaled ones and the stager arms that forward a parent’s scale (SummonScene::push_parts_scaled). Its builder is main-executable code, so unlike the ribbon it draws in every mode; Baka Fighter's impact flash uses the same quad kernel.

A colour word with mode bit 0x20 sends a gouraud quad through the prim dispatcher’s third handler bank, which draws it as sixteen small triangles. Slippery’s storm clouds are such quads: huge sheets close to the eye, whose two halves the GPU would drop for their size where the sixteen pieces survive. Drawn whole, Deadly Rain’s sky read a third as bright as retail’s. The pieces are gouraud triangles with one colour on every corner, and the emulator dithers them like any gouraud draw: cut to five bits without the dither, eight stacked additive sheets lost a third of their light and broke into flat bands.

The default arm

The default builder takes a packed count / phase argument and a parameter block (inner / outer colours, a UV rectangle, page and CLUT, inner / outer radius and height, two in-plane scales). Besides move-VM op 0x13 it is called directly by the battle ground shadow, the field battle-intro ring and Baka Fighter's floor disc. Its mode word splits three ways:

The captured battle states use shapes 0..3 and none of 4..7. The port's effect_default_arm transliterates the builder onto a byte buffer and is held byte-for-byte to the scratch blocks retail captures left behind, including every ground-shadow build.

Draws that take the game’s random stream

Several effect builders draw rand() words while they build, from the game’s one random stream, so how many they take decides every later draw - an enemy’s pick, the next deal. The port meets each the same way: on the pass retail draws, it keeps the stream’s word as the part’s seed and steps the stream past its draws, and the draw replays the build from that seed.

• The jittered rings (default-arm shapes 4 and 5) draw three words a column every time the render pass reaches the node; a watch of the seed word through Ozma’s closing arms counts thousands an arm.
• The streak ribbon FUN_801E1D98, a separate routine from the move-VM ribbon above, is called by a cast module’s arm inside its own tick. It draws seven words for its bottom segment and four for each chained one - unless its top-edge test drops the ribbon. The test reads corners projected at a fixed half-width, so an anchor too near the eye (or behind it, where the divide saturates) draws nothing and leaves the stream alone. A frame’s count therefore climbs as the camera pulls back. The port projects each call through the battle frame’s own integer GTE view so the same calls drop.
• A homing flight’s bolts are the same ribbon calls from the flight’s slot loop, in flight and once landed, dealt the same way. Drawn off a private per-frame seed instead, a bolt pass took a tenth of retail’s draws.

Battle effect parts morph through vdf.dat

The effect-script table form stages move-VM parts like any other scene graph, and a part with op 0x0A lanes draws morphed: the lanes index the battle VDF pack vdf.dat (PROT 0872), whose sub-entry table battle init rebuilds from index 0. The Spirit charge is the visible case - two small rest meshes that VDF entry 12 grows into the aura cone.

• Waits drain at retail's per-frame rate. The part tick subtracts the frame factor times the rate byte from the wait each frame, so a wait of v holds v frames.
• Lanes grow from the frame after the spawn. The ramp envelope runs from the part tick's tail, which the spawn's own first VM step does not reach. Captures read the lane at exactly 0x66 per elapsed frame, so the cone takes 0x28 frames to open.
• The model draw applies the part's scale and colour word. The aura's op 0x0C writes an additive colour word at full level; op 0x0D's level rate takes the level to 0 over 0x20 frames and back to full over the last 0x0B.

Battle effects die with the battle

Retail never tears effects down one by one. The mode initialiser calls the per-stage init FUN_8001E1B4 on every mode switch, which re-seeds the 143-slot actor free stack and re-pops the seven actor-list sentinels, unlinking every effect actor still on a list with no walk. The efect.dat pool needs no reset on the way out: its walker is battle-overlay code behind the pool-ready byte, and the battle loader re-initialises it on the way in.

The port's World outlives every mode switch and both hosts draw effect state with no mode test, so it drops the same state by name: World::teardown_battle_effects runs at battle entry, at battle exit and at every scene load, resetting the pool and every battle-scoped cast, move-FX and effect-script scene graph. A staged cast module's scene is retired earlier, when the action state machine opens the next action, because the engine runs its records as data and nothing else would halt their infinite loops.

Textures and models

Effect sprites sample two texture pools. The flame atlas etim.dat is uploaded at battle entry only (its VRAM columns hold town textures on the field), while the character texture band stays resident from the field through battle - the Gimard summon flame samples the latter. A separate 30-entry model library, etmd.dat, gives 3D effects their meshes, and effect parts morph through vdf.dat.

The player summon (Gimard’s Burning Attack, and friends) is not an effect-pool child at all: a live trace shows it posed like an enemy body, the battle per-actor draw FUN_80048A08 running in lockstep with the rigid-keyframe decoder FUN_8004998C, one call per live actor per frame. Its flame animation is geometric, not palette cycling. The summon stager images in slot B hold real move-VM part records, run by the executable’s stager, and the engine drives them as a scene graph beside the body. The enemy Gimard’s Tail Fire is a different move again: a single move-VM part actor from the move-FX module PROT 0900. The floating damage numeral is not a pool child either; it samples the third etim TIM through its own sub-palette. Read from retail's own display list, the digit run keeps its horizontal centre while each cell grows toward its 1:1 24-pixel size and the run rises to a fixed screen row; the quads are unmodulated, so the numeral never fades. Placing it is a host job - the seat is the struck actor's projected screen position - and both hosts emit the cells through one builder, battle_numerals.

Pool layout

The head holds the motion scale (0x1000) and the sprite scale (0xA00) the init writes. A child slot mirrors the master's shape: frame count (doubling as the active flag), mirror bits, frame cursor, wait, i16 velocity, 16.8 position and an animation cursor.

Side-band streaming: summon.dat and readef.DAT

A separate loader case streams one of two runtime-only files into 0x10800-byte slots: per-special-attack CLUT rows and 4bpp texture pages, summon-creature actor records, and the player art-animation archives. The loader consumes a raw TOC index rather than the path string, which is why the names map to extraction entries 893 / 894. Full format: summon-readef.

Spawn sources

The effect catalog (efect.dat) loads at scene entry and stays resident across field / battle transitions. Four producers feed the spawn API:

• A spawn is seated at an actor, never the world origin: the caller copies the actor's world position, offsets it by the effect's planar legs rotated through its facing, and passes the facing as the spawn angle.
• The effect-script walk has two record forms. Its 0x80-flagged records route into this pool; its table-form records stage a small move-VM scene graph instead (see vdf.dat morphs).
• The last two producers share the bit-7 multiplex (effect format).
• HUD screen-element raises do not spawn here: the HUD spawner calls no effect routine.

Naming an effect id

Effect ids are anonymous - no string table says “fireball”. To name an id, trace the call sites of the spawn API: each caller passes a literal byte, which correlates with the action that triggered it (a Tactical Art, an item use, a spell cast).

In the port

World::tick_effects runs one walker sweep per retail logic frame, and World::active_effect_sprites maps pass 2 one-for-one into billboards, which both hosts draw as camera-facing textured quads sampling the scene VRAM. It is the engine’s only per-frame effect path.

A script spawn is walked on the frame it fires

Retail spawns and walks in one frame, in that order: the per-actor anim tick steps the action effect script, whose direct arm calls the spawn API, and the walker runs afterwards from the draw tick. The engine walks the pool inside its tick and routes queued script and homing spawns in the frame tail, after the walk - so each direct spawn is caught up by the sweeps that frame’s walker gave everything else (Pool::catch_up_master: that master and the children it seeds, nothing more). Without it an effect’s first batch landed one sweep late.

• In battle the walker sweeps from the draw preamble, as retail’s draw tick does: behind the frame driver’s discarded rand() word and the state machines’ and module’s draws, ahead of the burning bodies’ puffs. Swept at the head of the tick, its mirror draws came off the stream ahead of the pass; a watch of the seed word on Viguro’s film reads driver, ribbons, the walker’s mirrors, then the puffs.
• Two port-side deltas, both invisible to retail behaviour: the retirement overrun is cut at retirement, and a dead master lane is reused as an age counter for render fades.
• Debug spawns (the E key in play-window) live outside the pool, so the walker never sees them.
• A faint effect is usually faint by data (see how a child is drawn). Differencing two frames with the billboard draw suppressed (LEGAIA_DIAG_NOFX=1) shows the sprites really are drawn; LEGAIA_DIAG_FX=1 logs each live sprite’s position, size, page, CLUT and VRAM residency.

How we know

Full write-up: docs/subsystems/effect-vm.md.

See also