Skip to main content

0024: Prefer Product-Native Visual Almanacs

Status: Superseded by ADR 0027

The decision to keep detached visual-export compatibility is superseded by ADR 0025. Product-native gallery implementation is now only an optional project recipe under ADR 0027. The separate capability-manifest decision is superseded by ADR 0026.

Date: 2026-07-21

Context​

STAGE's first visual system produced engine captures, motion files, an HTML contact sheet, analysis records, and review receipts outside the game. The pipeline was technically reproducible, but The Circussy One's project director rejected it as a development workflow. Most entries did not answer useful questions, detached presentation hid production context, and every adjustment required another export cycle. The one useful result, Enemy Arrival, worked because its actual setup, anticipation, reveal, and continuous motion formed a coherent in-engine event.

Moving the same idea into isolated test scenes corrected renderer ownership but did not fully correct product ownership. A parallel visual lab can still duplicate content resolution, lifecycle, lighting, camera, animation, and UI that the game already owns. It is maintenance work whose output disappears from ordinary play and is easy to fill with nominal coverage.

Games already have a more useful shape for recurring visual discovery: a gallery, codex, bestiary, model viewer, replay browser, world previewer, or debug inspect mode running inside the product shell. Such a surface can have independent player value while a gated developer mode exposes invalid content, diagnostic presentation, deterministic coordinates, and reset controls. One implementation can therefore improve the game and shorten visual iteration.

Decision​

  • For a one-off asset-local question, continue to use the engine's existing asset, animation, material, VFX, prefab, or scene preview.
  • For a one-off composed question, continue to use the real game or development route that contains the production consumer.
  • When recurring visual work earns a persistent Visual Almanac, prefer a product-native in-game gallery reached through the normal game shell or a gated development route. It should reuse production content resolution, rendering, animation, VFX, UI composition, input, and lifecycle wherever those systems are material to the review questions.
  • Prefer one runtime implementation with audience modes:
    • player mode owns unlocks, save state, localization, accessibility, performance, and product presentation;
    • developer mode owns unresolved-content visibility, diagnostic lighting and backgrounds, exact states or seeds, playback controls, reset, teardown, and state provenance.
  • Do not build a second renderer, subject catalog, or scene-per-asset review world when one generic product-native stage can resolve canonical content.
  • Use isolated editor or runtime stages only when the question is genuinely asset-local, destructive to ordinary product state, impossible to compose in the product shell, or cheaper enough to justify the narrower claim.
  • Store durable camera, distance, background, lighting, quality, playback, fixture, and procedural-seed choices in human-owned project authoring data. Automation may create a missing default but must not overwrite human edits.
  • Animation, VFX, lighting change, and other temporal questions must be inspectable as genuine engine motion. Stills and named beats remain useful navigation; encoded video is optional transport, not the native review surface.
  • Evidence Export may capture the already-active product-native coordinate for a named remote, regression, milestone, CI, or audit consumer. It must not reconstruct a parallel presentation or become the daily authoring loop.

Consequences​

  • Persistent visual infrastructure must earn both recurring review value and a truthful runtime home. It must pass a Product Utility Gate by serving a real player, author, or recurring developer job; artifact count is not progress.
  • Small games may gain a useful player feature from work that would otherwise be disposable development tooling.
  • Developer and player responsibilities remain distinct even when their resolver, stage, camera, playback, and presentation implementation is shared.
  • Shared player and developer modes derive explanation from canonical Subject identity rather than maintaining a second catalog for display copy.
  • The game shell becomes the default place to inspect final animation, lighting, background, post-processing, scale, interaction, and composition.
  • Controls are verified through the visible presentation they promise. A changed field or transform does not prove changed framing, lighting, motion, or readability.
  • Editor isolation remains valuable for diagnosis but carries only the claim its omitted runtime systems permit.
  • Detached Evidence Export schemas and scripts were later retired by ADR 0025; Git history preserves the failure evidence without an active compatibility burden.
  • The separate visual-almanac declaration was later retired by ADR 0026. Runtime entry points, audience, truth modes, presentation authority, and limitations belong in the ordinary project map and operating docs.

Rejected Alternative​

Improving the detached Circussy contact sheet with more assets, angles, backgrounds, lights, or videos would make the wrong product more elaborate. It would not fix duplicated composition, slow authoring feedback, missing gameplay context, or lack of player value. The historical export stays available to teach this failure rather than becoming a template to expand.

Last updated on