Battle subsystem

At a glance

Where

Battle overlay = PROT entry 0898, loaded at 0x801CE818 (the slot the town overlay also uses, so the two never coexist); scene loader, seats and archive streamers are static SCUS_942.54 code.

Battle state

One context struct reached through the global pointer 0x8007BD24 (resolves to 0x800EB654); two byte cursors inside it drive the menu half (+0x06) and the action half (+0x07).

Roster

8-slot actor pointer table at 0x801C9370 - slots 0..2 party, 3..7 monsters.

Monster data

Monster archive, PROT entry 867: one LZS slot per species (stats, mesh, textures, spells, rewards).

Engine modules

engine-core (World battle tick, battle_input, battle_seats, monster_ai, battle_flow), engine-vm::battle_action + battle_formulas, engine-ui HUD.

Confidence

Loader, roster, seats, flow states, wipe path: Confirmed (disassembly + live captures). Some actor-struct fields and the Seru attachment table: Inferred.

Used by

Action state machine · Battle formulas · Arts gauge · Encounter record · Monster viewer

How a battle works

Three systems share the battle overlay. The scene loader pulls the stage, effect and monster assets off the disc. The menu state machine walks the player through Begin / Run, the command ring and the target cursor. The action state machine plays each committed command out over many frames - wind-up, strike, damage popup, recovery - and hands the turn on. The effect VM draws sparks and spell visuals but never decides anything; the move VM turns a Tactical Arts input into keyframes one layer below the action machine.

Getting into a fight

Three doors lead into the same loader:

• Walking. Every step onto a new 128-unit collision tile rolls against the region's rate; a hit picks a formation row from the scene's own table (see encounter record).
• World map. Each region rolls the same way against its own slice of rows (world map).
• Script. Boss rows sit outside every rollable slice and are reached only by the field-VM scripted-battle op 3E FF <row> (any op0 < 100 runs the same body). The row's non-zero header byte is what gives a scripted fight its particle intro and second audio cue.

Whichever door opens, the field scene is not unloaded: the scene-name table is identical before and after the switch, and the battle draws on top of the resident terrain. The formation ends up in one four-cell array of monster ids that every later stage reads (internals).

Loading the fight

Before the first prompt the loader ticks through an asynchronous ladder, one PROT.DAT entry per state. The stage overlay step is skipped for every retail fight except the Tetsu sparring tutorial and the Cort fight.

The befect_data rows below are numbered in the loader's own raw TOC space, the space its li constants live in; the extraction entry is two lower, so raw 872..875 are extraction 870..873 - etim / etmd / vdf / efect. Reading a raw index as an extraction one is what once fused the vdf pack with the character pack that carries extraction label 874.

When a stage overlay is paged in it takes the fight over. The evolved-Cort intro leaves the command-flow byte on a value the battle menu has no handler for, and the menu simply idles: the stage module runs its own camera move, its own banner and its own multi-frame countdown, then writes the flow byte back to a value the menu understands with the intro timer already zeroed - so the fight opens the moment the module is finished, and no button press hurries it. A live capture holding all ten pad buttons in turn moves the byte not at all.

• Party meshes are assembled, not loaded whole. The player battle files (data\battle\PLAYER1..4) carry per-equipment sections; the loader splices the equipped pieces into one mesh per member and relocates its textures into the seat's VRAM band. Details: battle data pack, character mesh.
• The heap is the real formation limit. Everything the loader places comes from one ~1.23 MB best-fit heap, and the monster streamer copies through the returned pointer unchecked. About 145 KB is left for distinct monster blocks; retail never authors more than two distinct species per formation and the randomizer enforces the same cap. Ledger on internals.
• Duplicates are free. Only the first occurrence of a species id streams; repeated seats share the record and mesh.

The arena: backdrop, camera and seats

There is no arena. The fight happens on the ground you were walking on; the camera swaps from the walk camera to a slow orbit around the midpoint between the rows, and the actors and HUD are layered on top. An overworld fight adds two layers so the horizon reads complete from every angle: a flat procedural grass grid under the actors and the map's sky dome, drawn twice (a half turn or an X mirror, chosen per stage by an authored table).

The orbit camera is pinned exactly: pitch 32 (of 4096), a fixed translation 7680 deep, a 4x world scale composed under each actor - the engine's retail_battle_mvp reproduces it to 0.0002 px against a savestate framebuffer. Constants on internals; the per-phase framing (far shot for the menu, close-up for arts input) is on battle action.

Seats are authored data. Two static tables of (x, y, z) entries, picked by combatant count, are stamped into every actor at setup. The party faces +Z, the monsters -Z.

An alternate monster family (used by the pincer and scripted seatings) is selected by the same flag bit that marks a fight no-escape. Engine mirror: engine-core::battle_seats.

Who is fighting

Every combatant is one actor struct reached through an 8-entry pointer table, and the slot number is identity for the rest of the fight: the action machine, the range check, the AI and the HUD all say "slot 4" rather than "the Gimard". Four records feed those structs:

The party side is read straight out of the character record and written back (HP / MP) when the fight ends. The monster side is decoded once per species: the loader keeps the record pointer in a side table so the spoils routine can read gold, EXP and the drop roll without copying them into the actor. Each monster's mesh is a Legaia TMD inside the same block, textured from a 15-palette pool that the loader relocates into the seat's own VRAM column - which is what the monster viewer and the engine's MonsterMesh both reproduce.

A round, turn by turn

The command UI is not one menu. The menu machine walks a byte cursor through three small D-pad surfaces - each a cluster of plate chips around a D-pad glyph - and every round opens on the same prompt:

The action machine then resolves the round. It keys on its own byte, walks a band of states per command category (Attack, Magic / Item, Summon, Spirit, Run / Capture, Done), and ends each action at a gate that counts who is still standing. When every living actor has acted it writes the menu machine back to turn setup and bumps the round counter - the two bytes hand the round back and forth. State bands and the validator are on battle action; the arithmetic is on battle formulas.

• Turn order is an initiative key per living actor, seeded from SPD plus a random spread and re-rolled each round; the highest key acts, ties break at random. Port: World::next_combatant_by_initiative.
• Monster AI is two routines: a picker that rolls between a physical strike and the record's castable spells (MP-gated, targeted by the spell's shape byte) and can be overridden by a per-monster-id script, and a target resolver that only runs for a charmed party member. Port: World::pick_monster_action, monster_ai::decide, World::resolve_monster_target.
• Status effects are bits in one halfword on the actor, set only by the battle overlay's two infliction legs. Poison ticks never kill (they bottom out at 1 HP); Stone counts as defeated. Per-status table on internals.
• AP is the arts budget for the turn; Spirit adds +5 once per turn and raises a guard stance that halves incoming damage. Costs and the weapon-specialty penalty are on arts command gauge; model engine-core::ap_gauge.
• Items come from the same 256-slot bag the field menu uses - there is no battle inventory. The bag and its "split bag" window are on inventory.
• Capture-class casts (Seru capture, the Amulet, the Delilas signature attacks) page a small dedicated module into the side overlay window and tick it every frame until it reports done. See internals and cast modules.

Ending the fight

Two things about the wipe catch people out. A scripted-loss battle (the Rim Elm ambush) raises a story-flag latch first, so its wipe returns to the field like a win; the same gate sets a second flag on the survived path, which is how a scene script can score a scripted battle. And the game-over artwork overlay that exists on the disc (mode 18/19) has no writer anywhere - it is a dev harness. Latches and stores on internals.

After every battle retail reloads the field scene and re-runs its entry script, which is what dispatches post-battle beat records (the rikuroa progression gate, for one). The port mirrors that reload on the Battle-to-Field edge.

The from-scratch port

The engine keeps the battle simulation renderer-free in engine-core and drives it from one per-frame World::tick, so walking, being ambushed, fighting and returning to the field all happen from a single call. Both hosts (native play-window and the browser play page) arm it through the same kernel, World::arm_live_loop.

Per frame the battle tick folds art-strike damage into HP, marks the dead, retires two animation gates retail's renderer would clear (advance-done at recovery, the caster's spell iterator at sustain), and re-arms the next attacker at the end-of-action gate. On completion it writes post-battle HP / MP into the character records before restoring the field snapshot - otherwise the fight's damage is thrown away. The loop flag gates only the encounter roll: once the world is in battle, however it got there, the tick always drives it to a result.

Player-driven battles are the default on both hosts; --no-live-loop turns the encounter roll off and --no-player-battle auto-attacks each party turn. Post-battle Seru learning banks capture points per Seru and party slot; the per-monster Seru attachment table is an engine-side approximation (SeruRegistry::vanilla), Inferred, not Confirmed.

How we know

Save-state diffs (overlay residency, actor-table window, stat-growth deltas) are on capture notes. Falsified readings are on do-not-re-walk.

Full reference

Source of record: docs/subsystems/battle.md. It also covers the sparring-tutorial prompt machine, the post-strike two-shot camera, the staged-anim channel, the packet-pinned HUD chrome and widget-class table, the weapon-trail builder, per-frame actor maintenance, the SFX scheduler and the field-to-battle intro curtain.

See also