See what a document makes: previews in the Studio

Designed 2026-10-06, after driving the published 0.1.0 Studio. Part of M11 ("Documents and assets: models, sprites and sounds previewed as they build", ROADMAP.md) and of step 4's "before-and-after previews" (design/m11-studio.md).

Why

Every model, sprite, sound and score in a game is a recipe (a builder and its params, Tier 1, ADR-0011) that the player bakes when the game loads. In the Studio a person sees those recipes as fields and JSON only: Tideline's "Look and sound" holds 38 documents nobody can see or hear until they build the game and walk to where the thing is. A person changing a crow's colours, a sound's pitch or a score's tempo works blind, and the Director's look proposals ("bleach the driftwood so it catches the moon") can be judged only by playing. A game studio has to show the art.

What

A preview above a document's fields, for the kinds that are media recipes:

• Model: the built mesh in a small 3D view, lit as the game's Style lights it, turning slowly; drag to turn it, a reset button; its triangle count against its budget. A Model with poses (a body plan's gaits) plays them, one chosen from a list.
• Sprite: its frames baked into the atlas the player uses, each clip playing at its rate, a clip chosen from a list, drawn at whole-pixel zoom on the game's backdrop colour.
• Sound: Play for each variant, the waveform drawn, its length and level; a loop loops until stopped. It plays on the Studio's own bus, never the game's.
• Score: its sections, each playable as the game mixes it, with its layers listed and each one turned on and off; it stops when the person leaves the document.
• Style and Theme: their palettes as swatches with names, and the Style's light on a reference model (a lit sphere and a cube).

Each preview is built by the engine's own builders, the ones the player bakes with (GwMeshBuilders, GwSpriteBaker, GwSoundBank, GwScoreBaker), from the game's current documents. So what the preview shows is what the game shows: a test pins it (below). Nothing is drawn by a second path.

It follows the document. An edit (field or JSON, or undo) rebuilds the preview. A pending proposal that changes the document shows Now and Proposed side by side, built from the document before and after the change set, with Approve and Reject beside them, so a look proposal is judged by looking. A document that does not build says why in plain words where the preview would be.

It never stalls the Studio. Building runs on a worker thread or in steps a frame can afford (as the player's bake budget does: GwBakeBudget); no frame of the Studio's UI takes more than 33 ms while one builds. Built previews are cached by the recipe's hash, as the player caches its bakes, so going back to a document is instant. A preview builds only while its document is shown.

Plain words and the kit. Labels are the kit's (GwStudioUi, GwStudioWords): "Turn it", "Play", "Clip: gallop", "Now" and "Proposed"; ids only in tooltips. The preview area folds and its height is remembered, like every panel (S4).

Not now

Placing things in a level, a map view of a Level or Worldgen, and Screens drawn as the game draws them come later: they need the game's world, not one document. Image, sound and music files a person brings (M7) will preview through the same panel when they exist.

Proof

• Same as the game. For one Model, one Sprite, one Sound and one Score of each sample that has them, the preview's bake equals the player's: the mesh's vertex hash, the atlas's bytes, the sound buffer's hash, a section's rendered stem hash. gdUnit4, run red first by feeding the preview a changed param.
• It follows edits and proposals. A scenario (like tools/studio/edit-scenario.sh) opens Tideline's Driftwood model, shoots the preview, edits a palette slot, shoots it again, then a proposal made over MCP that changes the same document shows Now and Proposed; frames Read.
• It never stalls. The scenario records the longest UI frame while a score section and a sprite atlas build, and fails above 33 ms.
• Plain words (GwStudioScreen.not_words) and the layout report at 1280×720 and 1920×1080 hold with a preview open.