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 past/current and current/future line strips with endpoint color gradients. Android DrawGameStageCharacter proves that the active forwardDrawDist value is a count of beats, not seconds. If beat_ms = 60000 / bpm, it computes:

beat_start  = floor(current_ms / beat_ms) * beat_ms
future_ms   = forwardDrawDist * beat_ms
first_ms    = max(0, beat_start - max(beat_ms, future_ms))
last_ms     = min(song_end, beat_start + future_ms)

The same active value drives both sides, but only the past side has a minimum one-beat span. Thus a dynamic value of zero removes the future route while retaining one past beat. The first backwardsDrawDist config float is retained while parsing but is not consumed by this normal Android rendering path.

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)
first range field: 10
active range:       7 beats

The rail brightness is also chart-clock driven. Over a two-beat triangle wave, pulse = triangle * 0.6 + 0.4; the past segment grades from 0.7*pulse to pulse alpha and the future segment from pulse to 0.5*pulse. Both are submitted with additive blending.

Track colors

The stage config stores two RGBA colors directly after the draw-range values. Android uses the first for the past/current call and the second for the current/future call. For 10pt8tion_hard they are (255,0,128) and (255,255,255) respectively; the older ahead/behind field names were inferred backwards.

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 rhythm_reactive_color

FUN_00642390 holds the active colors unless interpolate_to_next is set. The transition uses CalcCrossFadeColor's 25% overlap rather than a plain linear mix. rhythm_reactive_color multiplies HSV brightness by a 0.5..0.75 triangle wave derived from chart time and the active BPM in SetCommonParam; it is not sourced from an audio analyser. The Linux player implements both.

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 FlowItem, 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.

Android GameScene::ExecFlowItem scales both repeatMeasure and lifespanMeasure by the active beat duration. Recovered spawn layouts are: type 1, a random screen point; type 2, a screen/grid group using groupShapeSize; type 3, eight points at 45-degree intervals around a circle. The player follows those timing/layout rules, unprojects the points to route depth and applies the authored velocity, but substitutes colored billboards for original texture selectors 34/35.

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.