openroller/docs/re_gc_track.md

GC Track and Background Reverse Notes

Status: linear track evaluation and the base background color table are implemented in the Vectorail player. Camera mode bytes, fade modes and stage objects still need deeper mapping.

Track wire data

The main stage file stores track keys as big-endian records:

u32 count
repeat count times:
    u32 time_ms
    f32 x
    f32 y
    f32 z

The stage constructor FUN_005ed4c0 loads these into 16-byte runtime entries. The fourth float is not read from disk: the constructor computes the physical length to the next point and stores it there. It also accumulates the complete track length at stage-object offset +0xb0.

Confirmed evaluation

FUN_005e9690 evaluates a track position at an integer timestamp. It finds the adjacent time_ms keys and computes:

u = (time_ms - key[i].time_ms) / (key[i+1].time_ms - key[i].time_ms)
position = key[i] + (key[i+1] - key[i]) * u

There is no Catmull-Rom or other spline interpolation in this path.

The Android symbol GameScene::DrawWay (0x001b3b68) establishes how the visible route itself is rendered. It clips the authored point list to the requested first and last timestamps, inserts linearly interpolated points at both exact boundaries, interpolates an RGBA color over that time interval, and submits the result as primitive mode 3: a line strip. It does not generate a camera-facing ribbon, resample by physical distance, or cull triangles.

FUN_005e9990 is a separate physical-distance sampler used while constructing duration-note paths. It carries leftover distance between segments so those generated samples remain uniform over corners; it is not the normal route renderer.

The player now mirrors DrawWay: it uploads the original authored points plus the two exact timestamp intersections and draws separate behind/current and current/ahead line strips with endpoint color gradients. The stage values backwardsDrawDist and forwardDrawDist behave as seconds and are converted to milliseconds before comparison with track and note timestamps.

Dynamic TrackDrawDist records are step changes, not interpolation keys. The StageConfig forward distance remains active until the timestamp of the first matching record, then each record replaces it. This matters for Knight Rider: its only record is 128400 ms: 0, which hides the route at the end of the song; using the first record before its timestamp incorrectly hid the entire future route from the beginning.

For ac_10pt8tion_hard.dat:

first track key:  0 ms,    (0, 0, 0)
second track key: 6486 ms, (0, 0, 199.985)
draw behind:      10 s
draw ahead:       7 s

Treating 7/10 as world units collapses the visible rail to a tiny fraction of the first segment; timestamp clipping produces the expected visible range.

Track colors

The stage config stores two RGBA colors directly after the draw-range values. They are used for the forward and already-travelled portions of the rail. For 10pt8tion_hard they are (255,0,128) ahead and (255,255,255) behind.

Base background

The main .dat contains a ColorTable section. Each 22-byte record is:

u32 time_ms
rgba top_right
rgba top_left
rgba bottom_right
rgba bottom_left
u8 interpolate_to_next
u8 audio_reactive_color

FUN_00642390 holds the active colors unless interpolate_to_next is set; in that case it linearly interpolates all four RGBA values to the following key. audio_reactive_color applies FUN_005d9650 to each active color using the runtime analyser value. The Linux player now implements the exact hold versus interpolate selection and keeps the second mode at its neutral color factor until the analyser feeding stage renderer +0x24 is ported.

data/stage/2d/<song>_menu.dds is not the gameplay background. It is a 512x256 UI atlas whose top-left 197x197 cell is the song jacket. The player has a small uncompressed DDS loader, but the jacket is disabled by default and is only an explicit debug comparison layer (B). The inherited procedural blue/black square grid has also been removed: the base layer is now only the stage-authored color table before particles, visualizers and objects are drawn.

The remaining original scene is produced by the stage particles, visualizer, and objects sections (plus .tumo models), not by a single background bitmap. These sections are now decoded completely by StagePattern: particle records are 44 bytes, visualizer records are 12 bytes, and every variable-length object record is consumed through its visibility, movement, scaling, rotation and color-key arrays. Oshama contains 5 particle keys, 19 visualizer keys, 46 model names and 316 object instances; 10pt8tion contains 2, 28, 37 and 352 respectively. The Vectorail level data retains this decoded scene for the model-rendering pass.

The PSP package now retains all three timelines. The particle constructor at FUN_005f0940 creates a 64-instance pool for every configured particle key. FUN_005f0130 scales both repeatMeasure and lifespanMeasure by the active beat duration. Recovered spawn layouts are: type 1, a deterministic/random point; type 2, a screen/grid group using groupShapeSize; type 3, six points at 60-degree intervals around a circle. The PSP implementation follows these timing and layout rules, but substitutes geometry for the original particle texture resource until that resource binding is mapped.

The common .tumo container is also big-endian. Its outer count is followed, for each mesh, by resource names, an XYZ vertex table, eight bound floats, render parts, and polygon lists. A polygon corner is u32 vertexIndex, f32 u, f32 v; a separate block contains explicit line-index pairs. The player now triangulates polygon fans, retains line primitives, and renders stage objects with the original five animation channels: visibility, movement, scaling, linearly interpolated Euler rotation, and RGBA color. The final rotation uses the recovered (-Y, X, Z) quaternion-builder convention. Base and animated transform components are composed as separate matrices, matching FUN_00643b20; visibility fades use the original fixed 250 ms window. All 46 unique Oshama models and all 37 unique 10pt8tion models decode. O toggles this object layer for comparison.

For stage format versions newer than 0x29ce, the supplemental table beginning at the header's ColorTable2 offset has a relative pointer at base + 8. Its stream is u32 objectCount followed by one signed big-endian int16 parentIndex per object (-1 means no parent). FUN_006445b0 evaluates one parent level and renders parentTransform * childTransform; parent and child RGBA are multiplied component-wise. Oshama uses this on 80 of 316 objects and 10pt8tion on 87 of 352, so omitting it visibly loses grouped scale, placement, and opacity.

The object's wireframe byte also selects mutually exclusive model paths: FUN_005dd8e0 draws polygon parts, while FUN_005dd7f0 draws the explicit TUMO edge buffer. The player previously drew both. Polygon/edge selection now matches the flag. FUN_00648c30 enables D3DRS_ZENABLE and D3DRS_ZWRITEENABLE for the complete authored object loop, then disables both before the rail and markers are submitted. Objects therefore depth-test one another in file order, but never hide gameplay geometry drawn afterwards.

Per-frame object clipping

The stage loader also opens data/stage/<chart>_clip.dat. FUN_005ed4c0 decodes it as:

u32be object_count
u32be frame_count
u8 visible[object_count][frame_count]

The payload is object-major. FUN_006445b0 selects frame round(time_ms / (1000 / 60)) and skips the object when the byte is zero; when the table is absent or the requested frame is past its end, it falls back to the normal authored-visibility path. Knight Rider has 178 objects and 7909 clip frames. Ignoring this table submits many objects which the original never draws in that camera frame and turns its background into overlapping full-screen geometry. The Linux player now applies the same test before object animation and submission.

FUN_005dd8e0 itself supports two TUMO part types. Type 0 is a triangle list; type 1 is a line list. Type-1 source polygons contain exactly two corners. Oshama's models contain ten such parts, including one with 1498 line vertices; treating them as polygon fans silently discarded all of them. The player now keeps solid line parts separate from both triangle parts and the wireframe edge buffer. All Oshama and 10pt8tion models end with a zero node count, so an internal model hierarchy is not responsible for their transforms.