Battle action state machine

At a glance

Where

Battle overlay (PROT 0898, resident at slot A during fights); driver FUN_801E295C, the overlay’s largest function

State

One byte, ctx[7] in the battle context at 0x800EB654, dispatched through a 256-entry jump table with no default arm

Band key

The actor’s category byte +0x1DE, read once at the seed state 0x0C

Damage

Not in the state bodies - one power byte per animation hit event, through the battle formulas

Turn end

Done band 0x50..0x52, then the end gate 0x5A, which also detects a party or monster wipe

Port

engine-vm::battle_action (ActionState, step, BattleActionHost); composed by engine-core::World

Confidence

Confirmed - every state body read from the disassembly; queue, summon loads and trigger tables capture-validated

Used by

battle loader, Arts browser, ROM patcher battle tuning

How it works

The driver runs every frame from the battle main dispatcher. It resolves the active combatant through the 8-slot actor pointer table and pumps the action through three keys:

• Not a bytecode VM. No opcode table, no program counter. Each state body waits on a per-actor condition - animation matched, timer expired, range check passed - and writes the next state when ready.
• Run band. 0x65 branches on the roll: a failed run returns to 0x50 (turn consumed, battle continues); a success enters 0x66, which stages a 64-frame black-to-white fade, sets the battle-end signal DAT_8007BD71 = 0xFE and parks in 0x67. Engine: ActionState::RunEscape → BattleEndCause::Escaped.
• Wipe arm. The 0x5A victory arm stages the win pose off the acting actor’s party slot, re-picking a living member only when the actor is dead. Retail is safe because the wipe scan and the scheduler share one liveness predicate; the randomizer’s enemy-ally charm widens that mask and breaks it (charm softlock).
• Effects are indirect. The machine calls the UI-element spawner with an element id (0x07, 0x0F, 0x34, …) and the effect VM resolves it to sprite spawns. That path draws the 2D layer; the 3D summon is a separate mechanism below.
• Two known parks. The 0x51 HP-bar settle gate and the 0x19 attack-approach range poll can wait forever under the wrong seeding; both are dissected in the full doc and the Gaza write-up.

Seru-magic summons

When a character casts a Seru spell, the creature that appears is not in the battle overlay: the cast state pages a small per-summon code overlay off the disc into slot B (0x801F69D8, above the resident battle overlay) while the cast band waits. That is why every summon has its own PROT entry and why a mid-cast save state holds an extra chunk of code.

The loader resolves its argument in the raw TOC (+ 0x381), which is extraction entry + 0x37F (PROT). The player and enemy arms of the same spell ship separate stagers. What a stager contains:

• No mesh geometry. The meshes are the separately loaded 30-entry model library etmd.dat (extraction 0871) that the battle loader registers at battle init; the flame atlas etim.dat is 0870 (effect cluster).
• Part records - [i16 model_sel][u16 reserved][move-VM bytecode] - handed to the executable’s part-stager, which spawns a part-actor per record: model_sel ≥ 0 seats a library mesh, -1 is a transform node, 0x4000 / 0x4001 are special render modes. Parser legaia_asset::summon_overlay.
• Motion is geometric. Gimard’s flame is eight RNG-seeded part-actors moving; the palette is byte-identical across animation-distinct frames.
• The player summon draws as an ordinary battle actor through the TRS-keyframe pipeline; the engine renders it that way (monster_archive::battle_render_mesh + MonsterAnimPlayer) and keeps the part records as the on-disc stager model.

The action queue and Tactical Arts triggers

What the player types on the D-pad becomes a flat list of action bytes before the machine sees it: the per-actor byte stream at actor[+0x1DF..+0x1F2]. Miracle Arts and Super Arts are pattern matches on that list, which is why the right arrows in the right order “upgrade” a chain into a named combo. The queue builder runs both passes, in this order, when the seed state commits the turn:

1. Miracle Art match. Two conditions, both required. The slot’s Miracle marker ctx[+0x25F + slot] has to be set — it is raised once per battle, when the party actor is seated, from the acting character’s Ra-Seru equipment byte, not by anything the player types. And the command string has to equal the character’s Miracle string (Vahn’s Craze: R D L U L U R D L). Then the whole queue becomes the replacement string: four directions, the SpecialStarter byte, then the arts.
2. Super Art tail replace. For each chained art the builder walks the character’s five Super find patterns; a match on the queue tail is replaced by the replace tail ending in the finisher. The match needs the find’s last art to be the queue’s last action, and every participating art to have paid AP.

Every string is capture-validated byte for byte against legaia_art’s tables, and a Vahn Tri-Somersault capture’s queue tail 19 27 0F 19 1F 0E 1A 2B 2B 2B equals its modelled replace. Ports: MiracleMatcher / SuperMatcher in legaia_art supply the tables; the live path runs the byte-exact appliers in battle_action::queue_applier. The Super pass applies once and takes the first matching row in resident-table order — not to a fixpoint, and not the longest match.

In the live Arts submenu (engine-core::battle_arts) an art is a saved directional chain. A Miracle is recognised by exact string match; a Super by tokenising the chain into named arts and tail-matching the art ordering, because the connector direction after each art is per-combo data (Vahn’s 0x27 is followed by 0F in Tri-Somersault but 0E in Power Slash) that a saved chain does not carry. Both flag the menu row with the combo name and resolve the strike profile from the replacement queue.

Strikes. In the attack chain (state 0x1A) the host receives apply_art_strike(ArtStrikeInfo) - per-strike power byte, damage timing, hit cue, status effect - alongside apply_damage. engine-core::art_strike folds it into an HP delta, a status flag and scheduled SFX cues; World::fold_battle_event applies HP / status and queues the cues, which the host plays through the scene VAB at the cue’s frame delay.

Spirit and Run in the live command menu

The engine’s command menu carries all six commands. Spirit charges the caster’s AP gauge (+5) and raises a guard stance - the engine model of the pending-action byte +0x1DE == 4 that the damage finisher’s guard-halve reads - until that actor’s next turn. Run arms the run band; success tears the battle down as Escaped (no loot, downed members floored at 1 HP), failure consumes the turn.

Ported as battle_formulas::escape_roll, rolled by World::roll_battle_escape.

Engine port

The port keeps one enum value per retail state byte, so a transition trace from the engine lines up against a retail capture line by line.

How we know

The full per-state table - every case body, what it runs and where it goes next - is in docs/subsystems/battle-action.md, along with the turn cursor ctx[+0x1A], the two park analyses, the Magic arm’s class discriminator and the battle voice cues.

See also