Cutscene internals

At a glance

Movie overlay

PROT 0970 at 0x801CE818; play loop 1236 bytes; ring = 32 sectors at asset buffer +0x10000

Frame decoder

Iki: 10-byte header, LZSS qscale/DC table, AC VLC stream; port psx_mdec::MdecDecoder

Opening timeline

Partition-2 named records in each scene MAN, run by the field VM FUN_801DE840 as a spawned context

Camera

Op 0x45: 10 params into globals; mover actor FUN_801DD310; port engine-camera::camera_mover

Roller

Handler FUN_80037174; geometry at _DAT_801C6EA4 + 0x4C..0x52; port CutsceneNarration

Grade

Palette law (L, (L·247)>>8, L>>1) on the two graded CLUT rects; port Renderer::set_palette_grade

Confidence

Confirmed; the gold-grade CLUT rewrite is the prologue effect scripts' CLUT-cell cyclers

Movie overlay: ring, demux and MDEC feed

The five MDEC register/DMA helpers (feed, reset, two sync waiters, timeout dump) are the port boundary: they describe the chip, so the port has no counterpart for them. Everything above them - loop, ring, pump, slice callback, output control word - is a decision about the bitstream and has a crates/mdec counterpart.

Decoding one Iki frame

Implementation crates/mdec/src/lib.rs (MdecDecoder, AC_CODES, iki_lzss_decompress, IDCT_C, Q_MAT); a decoded-frame fingerprint is pinned against the disc. XA decode is bit-exact against a lossless reference of a real track; sector layout and filter coefficients are on XA audio.

The opening timeline

A timeline is a partition-2 named record in the scene MAN, executed by the ordinary field VM. Two things spawn one: op 0x44 in the scene's entry script (operand = a global record index re-based into partition 2), or a walk-on tile trigger (kind-1 record [tile_x][tile_z][p2_record][gate] in the scene .MAP's trigger block; the entry seat lands on the tile and fires the same tick). Both end in FUN_8003BDE0, which tests the record's story-flag gates against the bitmap at DAT_80085758 and spawns a VM context.

The scene's entry script runs first. The MAN loader FUN_8003AEB0 runs the script's install slice itself (FUN_8003AB2C, which calls the dispatcher directly), before any actor-list pass, so on the arrival frame the entry script's ops land before an arrival record's. In town01 that decides the visible tile window: the entry script sets the walking window (-10, -6, 8, 14) and the opening record then sets (-17, -13, 10, 31), which keeps the whole village in the establishing pan. The engine opens its first tick with that slice, ahead of a record installed at scene entry, and then runs the frame's own system pass, the script's second, as retail's first frame does.

System flag 7 is raised by the MAN loader FUN_8003AEB0 on every scene load (ori 0x1 into 0x80085758 at 0x8003AEF4), and no shipped script clears it. A record whose C1 list names it never spawns: over a hundred developer leftovers carry one, among them town01's two サウンド外 / サウンド内 walk-on records south of the Genesis Tree, whose whole body is a Greetings. box.

Nearly every op in the record carries the cross-context target 0xF8, which resolves to the player / camera-anchor actor - so the timeline drives the camera and the lead actor rather than itself. On-disc records have no end opcode: they park in a Nop+JmpRel-to-self loop or loop back to their top as a resident driver, and retail leaves them spinning invisibly.

Camera Configure (op 0x45)

A big-endian 10-bit mask selects which of ten signed-16 parameters follow; each is written to a camera struct at 0x801C6EA8 and committed by FUN_801DE084, which either snaps (apply == 0, killing any glide in flight) or hands a mover actor ten (start, end) pairs plus one shared progress, duration and curve.

The view builder composes screen = H · (R · (v − focus) + tr_eye) / Ze, with a constant 6× world scale folded into R. The mover advances t by the frame-skip factor each frame, so apply is a duration in display frames; every axis uses the same curve, angles included, with no shortest-arc handling.

Port: legaia_engine_camera::camera_mover, and both play hosts draw a scripted shot from the camera globals it writes (frame_step::scripted_view). Because retail scales the world 6× and the engine renders at 1×, tr_eye is divided by 6 - the perspective divide makes both project identically. Reference frame: focus (8640, 0, 10304), pitch 180, yaw −2967, H 792, tr_eye (260, 1293, 17145) projects the party to (172, 180), matching the capture.

The narration roller

Spawn op CC F8 80 N allocates a child actor from template DAT_801F28A0 with handler FUN_80037174, points its script pointer at the page-count byte, and the parent measures the pages to skip past the block. Config op CC F8 E8 w0 w1 w2 w3 (four signed-16 words) is mode-selected by w3:

Geometry and speed come from the scene: the roller reads its config block through *0x801C6EA4, the scene reset FUN_8003A024 stores 0x40 / 8 / 4 / 0, and a seed op overwrites the first three. A 4C E8 release count is block state too, so it dies with the scene. Every crawl block on the disc runs on a seed op placed immediately before it, or on the one an earlier block of the same scene left:

The line pitch is a fixed 16 (retail addiu s3,s3,0x10). The clock is the adaptive frame step DAT_1F800393: the accumulator gains it each frame and a pixel of climb happens when it reaches the divisor, the remainder dropped. With opdeene's frame-step floor of 3 (written by its own prescript), divisor 4 climbs a pixel every two frames.

Lines draw centred, all glyphs at once, scrolling upward in a clipped window. The single-line balloon (4C E1, centred at Y = 180, 120-frame timer) is a different op and never carries the crawl. Port engine-field::cutscene_narration (CutsceneNarration + RollerSeed::config_op_before).

Per-actor channels

Retail spawns one script context per partition-1 placement at scene entry (FUN_8003A1E4); its script id is partition-0 count + placement index, the id space cross-context ops resolve through. The timeline halt-acquires channels 0x05..0x0F (a sweep of 4C 85), pokes each beat (4C 45 param, 4B animate, 23/A3 move), resumes with B2 <id> 0A, and waits at B3 <id> <bit> until the channel's own script raises its completion flag. Even a halted channel keeps animating, because the per-actor anim tick runs independently of the parked script PC.

Port legaia_engine_field::field_channels: one FieldChannel per placement, stepped a slice per tick; pokes run against the resolved context; a failing cross-context flag test parks the timeline (bounded by CHANNEL_WAIT_PARK_TIMEOUT, falling back to a step-past). The player channel 0xF8 is modelled directly: ExecMove arms a countdown and the halt-acquire parks until it drains, so door records flow on to their scene change. Idle clips come from the scene's ANM bundle, whose descriptor-count seed is not uniform - the prologue scenes resolve only at count ≥ 5, so the render searches [3, 5, 6, 7].

Engine execution rules

• Only cutscene-class records (the opening chain, gated walk-on beats) install as the modal timeline with camera seize and locomotion lock; an ordinary mid-play op-0x44 spawn becomes a concurrent helper context that leaves the camera alone but still refuses the pad until it ends - retail's script runner raises the player's engaged bit for every context it steps.
• Narration blocks are data, so the stepper installs the pages and advances the PC past the block; it holds only for a scene's last crawl (so the scene change waits) and when a roller is still scrolling.
• Camera beats merge into a persistent parameter set - one opdeene beat sets only H - cleared on scene entry.
• Completion is the choreography wrap: a backward jump onto an already-executed PC. Real waits (0x4A, flag handshakes, the 0x49 name-entry suspend) halt at their own PC.
• A byte & 0x7F < 0x20 at the PC is a dialog transition, not an opcode; an 0x80-bit op whose target matches no spawned channel is skipped by width; resolved-channel busy-waits fall through because engine pokes complete synchronously.
• One engine tick is one vsync, and record contexts are stepped on every one; the frame delta they see is the game frame's length on a game-frame vsync and zero between (pacing).

Pacing: every wait is a count of display frames

Two clocks pace a record, and both count through the same factor. Op 0x4A (wait frames) adds the adaptive frame-skip byte DAT_1F800393 to a per-context sum on each visit and passes on the first visit whose sum reaches the operand; the camera mover adds the same byte to its progress. That byte is the number of display frames one logic tick spans, so every authored duration is a duration in 60 Hz frames, to within one game frame.

That last game frame is measurable. The op credits the frame that reaches it as well, so a wait of N at step s holds its record for s × (ceil(N / s) − 1) vsyncs:

• Measured. Every row is read off a per-vsync capture of the zero-input opening; all 59 waits the chain holds at one step from end to end fit the formula.
• The step is the adaptive one. opdeene runs at 3 because its prescript raises the floor; opstati and opurud sit on a floor of 2 and step by 2, 3 or 4 as their frames cost. No field scene steps by 1 - that floor belongs to name entry, the menus and battle.
• Why crediting one per vsync is wrong. It holds a wait for N − 1 ticks, up to two vsyncs long per wait at step 3, which over the opening record's waits puts it some thirty vsyncs behind retail by its last vignette.
• End-latch spins are on the grid too. The anim tick runs once a game frame and multiplies each clip's step by the frame step, so the engine advances every placed-prop, NPC and cross-context clip cursor on game frames only. The actor ticks after the record, so the record sees a clip's end latch on the next game frame and every spin ends on one.
• The residual is one-sided. A retail leg, measured scene label to scene label, includes the load and mode-transition window before the record's first tick; the engine's scene loads are instant, so it lands short by that window. Running long is the regression signal.

Fades, effect colour and the gold grade

Every scene's entry script arms 4C 12 00 00 00 00 00 then 4C 12 80 80 80 44 00 - instant black, 68-frame ramp to neutral. New Game sets system flag 0x52F to arm that handshake, and the engine pre-runs the entry script's load-frame slice so black is on screen before the first render. Port: fade::SceneTintRamp in World::presentation.tint; the effect beat is a pool colour tween read back as World::screen_tint_pushes, which is the one model - a live capture of a retail beat reads a three-argument push per frame, the push's shape exactly, while the global multiply tint stays neutral throughout. The three arguments are an ordering-table bucket, a semi-transparency equation and a GP0 colour word (red in the low byte); both hosts draw the frame's pushes through one shared emitter.

The gold grade on opdeene / opstati / opurud is a palette-space law applied to the loaded assets: the CLUT rects (0, 473, 320, 2) and (0, 476, 320, 34) are rewritten entry for entry from the disc value to (L, (L·247) >> 8, L >> 1) with L = max(r, g, b), STP bit preserved. The writer is four mode-3 CLUT-cell cyclers, records 10..13 of each prologue scene's effect-script bundle: two capture the rects and re-upload them grey (op 0x2B saturation -0x400), two capture the grey and re-upload it at hue +0x38 / saturation +0x80, every frame through FUN_80019D50. Packet colours split by source - the ground kernel's runtime neutral 0x80 stays neutral and draws gold purely through its collapsed CLUT, while each resident TMD's authored colour words are rewritten by the scripts' own two 4C E6 HSV ops (saturation -0x100, then hue +0x38 / saturation +0x90 / value -0x1E) to (V, V·246 >> 8, V·112 >> 8) with V = min(max(r,g,b), 0xF8) − 30 - a retail opdeene state holds every resident word on that curve. No depth cue runs: IR0 is 0 on every render node throughout the opening.

The port applies the same laws in its mesh shaders (palette_law_word / prologue_sepia_word, CPU mirrors in lockstep tests) because a 4/8bpp texel is a palette entry; exact-neutral words stay neutral, and the screen tint rides the same uniform. The ground matches the capture at G/R 0.890, B/R 0.46..0.48. The far spires are the exception that is not a palette law: they are light-source rows, which the 4C E6 rewrite never touches, and retail shades them through opdeene's dim scene back colour 0x202020 (B/R ≈ 0.15 in the capture).

Battle intro and script helpers

The full per-style emitter decode is in docs/subsystems/cutscene.md.

How we know

The movie path

The opening and its helpers

See also