18-LAB / Documentation

State schema

This reference uses JSON names from the published Rust model, including serde renames. integer is a JSON number whose model type is integral; ordinary number is floating-point. Objects marked omitted are absent when unavailable, not necessarily null. Nullable fields explicitly retain null. Large score/ID numbers follow JavaScript-number representation; do not assume arbitrary-precision integers.

The fields vary with client, ruleset, map readiness, and available process data. A stream can return an error document instead of this tree; HTTP readiness is 500 {"error":"osu is not ready/running"}.

Regular v2

GET /json/v2 and /websocket/v2 publish this document. /websocket/v2/subscribe selects pointers into it. The table recursively expands reused Rust types so each JSON path is explicit; [] denotes array elements.

Precise v2

GET /json/v2/precise and /websocket/v2/precise publish this smaller, independently sampled document. It is not a complete regular v2 state object.

Timing and input semantics

• beatmap.stats.hitWindow contains optional judgement members miss, meh, ok, good, great, and perfect: maximum absolute timing errors in milliseconds after the active clock rate is applied. Unsupported members are omitted. Missing/unparsed maps use {}. Catch publishes zeros for all six and omits stars.hitWindow; spatial catcher width is not a timing window. The judgement object is distinct from the scalar stars.hitWindow.
• hitErrorArray (regular v2) and hitErrors (precise v2) retain the original ordered timing-event history. pressHitErrors and releaseHitErrors vosu only split note presses and osu!mania hold-note releases; together they hold every value of the original array exactly once, in order. osu!lazer classifies from its judgement results. osu!stable classifies native mania maps, including with the Mirror mod, by matching each error to the map's judgement times and the replay's key transitions, so classification can lag the original array while that evidence arrives. An error that matches no transition (for example under the Random mod) is published as a press once the replay has moved 250 ms past it or one second has passed, so it never holds back later errors. Stable converted maps and maps without metadata stay press-only; osu!, taiko, and catch have no release judgements.
• Pause/results retain the current attempt’s history. Exiting the attempt clears it; a genuine quick retry begins fresh history. Polling before the first object and temporarily shrinking native lists do not clear history.
• keys.all vosu only uses logical B1-onwards names, not physical key names. Added in vosu 1.1.0: stable replay-frame parity and lazer's full 20-action mania range. Stable counts retained frame down-edges, including complete taps between polls, and timestamps exact replay-frame transitions up to the current play clock (including preloaded replays/spectating). Lazer timestamps sampled edges only; count jumps do not fabricate timestamps. The legacy four buttons keep their existing stable in-game-overlay source.
• The whole regular-v2 keys object vosu only is additional relative to upstream tosu; tosu exposes its four-button object only in precise v2.
• rankedPlay.stage: 0 WaitForJoin, 1 RoundWarmup, 2 CardDiscard, 3 FinishCardDiscard, 4 CardPlay, 5 FinishCardPlay, 6 GameplayWarmup, 7 Gameplay, 8 Results, 9 Ended.

Logical action order

vosu only Added in vosu 1.1.0: stable keys.all uses the same names/order as lazer.

Lazer enumerates distinct default-binding triggers, not available-action enums. Single-stage 4K–10K yields B1–B4 through B1–B10; dual-stage N+N yields B1–B(2N), stage one then stage two, up to 20. ENABLE_KEY_OVERLAY still gates updates after the opening 150 ms. Stable all follows replay frames independently of in-game overlay visibility; live osu!stable b20260924.1 confirmed the button byte in all four rulesets and counting with the in-game key overlay hidden.

Stable retry/rewind resets the attempt; rolling-window eviction preserves accumulated counts. Missing more than 8192 frames takes the first available state as a baseline without inventing a press. Lost edges and history evicted before a mid-play attachment cannot be recovered. Catch left/right and unrecoverable history remain parity differences, not physical-input measurements.

Spatial and per-key extensions

vosu only Added in vosu 1.1.0: hitOffsets, keyHitErrors, and catcher. The regular document nests them under play; precise v2 exposes them at the top level in the same order after releaseHitErrors. They are not added to v1 or streamCompanion. Precise tourney[] retains only its existing keys and aggregate error arrays.

Enable ENABLE_HIT_OFFSETS = true (Game data → Standard hit offsets in the dashboard) to expose hitOffsets. The default is false: the field is omitted entirely from both regular v2 play and precise v2 while disabled, not sent as an empty array. Enabling mid-attempt records subsequent hits only, without backfilling history; keys.all and catcher are independent of this setting.

hitOffsets contains cursor-minus-stacked-center X/Y in displayed 512×384 playfield pixels and the original matching timing error in ms. Missing spatial evidence omits a triple, not a zero position. keyHitErrors indexes displayed mania lanes including Mirror; untouched lanes before the highest observed lane are empty, and outside mania attempts both outer arrays are empty. Its history follows the existing reset/retention rules; enabling mid-attempt starts with subsequent classifications only.

catcher is omitted in menus, results and other rulesets. On lazer, hitOffsets, keyHitErrors and catcher use offsets measured for lazer 2026.921.0 (2026.1005.0 has the same layout) or generated at runtime for other versions. See extension semantics and remaining stable/lazer limitations.

v1 and streamCompanion

The v1 family (/json, /ws) exposes the gosuMemory-compatible grouped snapshot; streamCompanion (/json/sc, /tokens) exposes the compatibility token object. Use the upstream tosu wiki for those full compatibility references rather than a second duplicated schema.

vosu retains v1 hitErrorArray and streamCompanion hitErrors and adds sibling pressHitErrors / releaseHitErrors vosu only. Their split-history semantics are the same as above. Treat these additions as optional on other servers. Do not infer that the added v2 keys tree exists in the older schemas.

Sources

• Regular/precise DTOs and settings DTOs
• Mods, ranked-play types
• Upstream tosu types and builder

Edit this page on GitHub