Engine reimplementation

At a glance

What it is

A Rust runtime - boot, field, battle, menus, cutscenes, minigames, audio - reading the original disc for every asset

What it is not

A recompile of SCUS_942.54, a re-authored asset set, or a build that loses the retail-faithful mode

Hosts

The native legaia-engine play-window (winit + wgpu), the browser play page (WASM, same engine) and the site’s minigames page

One session

engine-session::BootSession is the game loop both play hosts tick; hosts own only input, the draw target and audio output

Faithful vs enhanced

Shading defaults to retail, rasterisation to clean; every enhancement is bit-identical to retail when off

Proof

Save-hash scenarios, VRAM diff against save-state captures, mode / audio / sim traces, record-replay determinism, a retail comparison corpus

Legal posture

Zero Sony bytes in the repo or any binary; disc-dependent tests skip when no disc is supplied

Where it stands

The port plays the game. From a cold New Game it runs the opening, the towns and dungeons, random and boss battles, the pause menu, shops and inns, the five minigames, the movies and the save screen, on both the native window and the browser page, with sound. A segmented full-game ladder seeds the engine at each story milestone from a retail save and drives it to the next with pad input only, from the opening to the credits crawl; every segment of it clears.

What is still rough:

• It is not frame-identical to retail. The retail comparison corpus scores the engine against every catalogued save state and ranks the gaps worst first. Game state - scene, position, party, flags, bag, enemy roster - matches almost everywhere. The rendered frame is where the distance is: field, world-map and menu frames sit close to retail’s, and the frame in the middle of a battle is the furthest off.
• One New Game reaches the credits, on the hands measured. Every ladder segment starts with a retail player’s party and bag; the ladder’s continuous run plays a single New Game that is never re-seeded and reloads only its own saves, and it reaches the ending on each dealt hand of the rand stream it is measured on. Another deal meets other fights, so the figure on the landing page is a ratchet, not a promise.
• The ladder proves the route, not every room. It drives the critical path. Optional content, rare script branches and long unscripted play are covered by a seeded soak harness that hunts panics, softlocks and stalled scripts.
• Bugs happen. Expect the occasional visual or timing glitch outside the measured states. A report naming the scene and what you did to get there is the fastest way to a fix.
• NA disc first. The port targets the USA release; the Japanese and PAL builds differ in the executable and are not its target yet.

How the crates stack

The port is a stack of small crates with one rule running through it: the lower a crate sits, the fewer things it may link. Format parsers know nothing about engines; the VMs know nothing about GPUs or speakers; the simulation draws nothing; and only the hosts at the top touch a window, a browser or an audio device. That is what lets the browser run the same engine as the native window - it simply links a different top row.

The crate map draws the same stack interactively: every crate in its band, what it uses and what uses it, its scope and modules, and the path a scene takes from the disc to the screen. Its data is generated from the workspace's own manifests, so it cannot drift from them.

The edges among the World-free kernel crates are a committed table, scripts/ci/crate-layering.toml, and a gate fails any Cargo.toml that departs from it. Each crate’s rank is derived from its row: engine-system, engine-dialog and engine-vm at the bottom, then the shared camera engine-camera, engine-mode and the motion VMs, then the battle VM and render-kernels, then the cast modules engine-cast with the battle, effect and field kernels, then the draw-list kernels, fishing, the other minigames and the scene loader engine-scene, then the menus and the minigame scenes. A kernel crate never reaches engine-core or a host, and the edges a crate’s role alone does not explain are listed in the table with the items that hold them.

Runtime architecture

One session, one world. A host hands the session a pad word and the camera azimuth each frame; the session runs the mode seat and the scene host; the scene host ticks the world; the world drives every VM through the host trait engine-core implements for it. Rendering and audio hang off the side: they consume what the world reports and never reach back into it.

The frame model

One world tick is one retail vsync, and retail never catches up: a slow frame makes a slow game. The hosts render at the display’s refresh instead, so the engine owns the rule that turns display frames into ticks (engine-field::frame_step): whole 1/60 s ticks with the remainder carried, at most four per display frame, and a backlog past four dropped rather than carried. Both hosts call the same kernel. The pause menu, the name-entry prompt and a movie consume ticks without ticking the world - under the pause menu that is retail’s own shape, since its mode handler runs no frame driver.

Goal and non-goals

Goal: a playable port of the NA release on modern systems via Rust + wgpu, with a WASM target; JP / EU follow once NA is solid. “Playable port” is grounded in retail, not bound by it: the traced dumps and oracles pin what the original does, the faithful mode reproduces it provably, and that is a measuring stick rather than a ceiling.

• Not a decompilation. No byte-matching recompile is attempted and nothing is auto-translated from the MIPS; every line is fresh Rust written from format docs and the traced dumps, which stay reference material. Per-opcode tests use synthetic bytecode.
• Never lose retail. Departures live behind toggles; the oracles keep “faithful” a testable claim. A quirk is preserved in the faithful mode and fair game to improve outside it.
• No re-authored assets. Every texture, mesh, sample and sequence comes off your own disc at runtime.
• Deterministic simulation. Seeded RNG, fixed timestep - the precondition for record / replay.

Modding and translation are shipped tracks, not exceptions: the randomizer (in-browser via the ROM patcher) and the translation tools patch a user-supplied disc without touching the engine, and what they prove out against retail - softlock fixes, tuning sliders - is expected to graduate into engine toggles.

Fidelity and enhancements

In the faithful mode no toggle changes damage, drops, AP costs, encounter rates or story flags, and every parity measurement runs against that mode. Enhancements are explicit toggles, bit-identical to retail when off, so flipping one never touches replays or oracles. Defaults follow the better experience: a knob still defaulting to retail marks an enhanced side that is maturing, not a policy of restraint.

One switch pins all of it: play-window --retail turns every enhancement off and sets the persisted engine-only options to their retail values for the session, writing nothing back (OptionsState::pin_retail, WorldToggles::pin_retail). The retail-compare capture runs under it, so a new enhancement added there is off in the comparison without anyone remembering a --no-* flag. Both hosts also take it live: the play page’s Retail-faithful box and the window’s F12 Original game only row pin or release the options mid-game and re-apply the launch’s switch set with retail flipped. Released, the set gives back exactly what the pin lowered - the launch switches their launch values, and the two port guards no switch carries (the hop landing guard, the off-axis battle entry) the engine default.

The gameplay rows from Shiny Seru down to Battle tuning are disc-patcher features the engine runs itself, so a player of the port needs no patched disc. The patcher’s other features either cannot occur in the port (the approach softlock, the Conkram freeze), are still open as engine switches (enemy HP bars, Seru trading without a patched disc), or are disc-content randomizers and mods whose patched disc the engine plays as data.

• Shading defaults to retail. Retail’s textured and colour mesh paths draw the mesh’s baked colour word through the GTE depth cue with no light source, as texel × colour / 128; the exception is the light-source rows (TMD group flags 0x10..=0x17), which shade through the GTE light (shading). The engine draws exactly that; enhanced lighting is layered over it and is an identity when off (every parity capture turns it off).
• Rasterisation defaults to clean. The default image is sharper than a PlayStation’s; here faithfulness is opt-in.
• Affine texturing is not gated. The PS1 has no perspective-correct texturing and neither does the mesh path; the swimming textures are the faithful behaviour on both hosts.

The camera knobs stand down for an authored shot. The distance preset, orbit, tilt and wheel zoom shape the follow camera only; while a script that holds the player has an op-0x45 shot staged - a timeline, a helper record or an ordinary talk such as the Water Gate Controller’s - the view reads them at identity. They come back with the follow camera: retail latches no shot, so once the record lets the player go the shot stands until the first step, which eases off it, and the preset blends back in on that ease instead of jumping. The follow ease reads the player’s lock once before the walk, as retail’s field tick does, so brushing a door or stepping onto a stand-and-press tile does not stall the camera. The pause menu freezes the field camera, since retail swaps the field overlay out under it.

The ported VMs

Every interpreter is ported handler by handler: the opcode is read from the disassembly, rewritten in Rust and tested against captured traces. The target is behavioural fidelity per opcode, not byte-exact internals.

Gameplay systems

The loop closes end to end: title → save-select → field and encounters → battle → menus → save. BootSession drives all of it through engine-core::World; the rules themselves live in the kernel crates the table names.

The browser host

The WASM target runs the engine itself, not a second implementation of it: the play page holds a BootSession over its WebAudio output, built over a scene host it assembles in memory from the disc image. It reaches field and town scenes, live battles, the title and the opening chain, the pause menu and shops, the minigames and audio. Each screen is drawn from engine state through the shared engine-ui / engine-screens builders and the site’s WebGL renderer; per-feature parity between the two hosts is policed by the host-drift gates.

• Seating. The cold-boot spawn is authored for town01 only; every other scene expects a door warp. A host that drops the player straight into a scene gets a resolved seat: the retail one if it stands inside the scene’s largest walkable region, otherwise a door-arrival tile or the region’s centroid.
• Pass-through scenes. A scene can be a passage rather than a place: every arrival lands on a walk-on trigger that plays a beat and leaves the scene, and retail never hands the player control there. The scene host recognises that shape from the disc and seats a picked visit on the arrival itself, so the first tick plays the beat. Zora’s Floating Castle’s second form (taiku2) is the one such scene: its pack replaces every room the beat never frames with a three-vertex stub, so the castle to walk is taiku.
• Framing. Both hosts run the engine’s retail follow camera and neither adds a cull of its own - what drops out of a frame is what retail drops, the visible-tile crop and the actor cull at retail framing, which hold under a cutscene’s own shot as retail’s do; a wall between the lens and the player is handled by the see-through-walls fade.

How we know it matches

See also