Skip to main content

0009: Make The Engine-Native Visual Almanac Primary

Status: Historical; the primary-Almanac decision is superseded by ADR 0027; detached-export consequences were superseded by ADR 0025

ADR 0027 retains direct engine-native review but removes the Almanac as a required or primary STAGE surface. The observations below remain historical evidence.

Context​

STAGE's first Visual Rehearsal implementation began with capture plans, image indexes, videos, contact sheets, reviews, baselines, and receipts. The tooling could prove that files were generated consistently, but the resulting review experience was less useful than the game engine's own scenario and preview tools. Broad contact sheets also encouraged placeholder subjects and unrelated captures that satisfied an evidence matrix without answering a visual question.

The Circussy One already had deterministic Visual Test Lab scenarios, authored content bindings, camera controls, timeline seeking, and presentation presets. Those capabilities were routed toward export before they were composed into a good daily inspection surface.

Decision​

  • Define the Visual Almanac as the primary engine-native inspection surface.
  • Define Visual Rehearsal as the human-and-agent review activity performed primarily through that surface.
  • Treat screenshot, video, manifest, contact-sheet, baseline, comparison, and receipt generation as an optional Evidence Export.
  • Reuse the engine's real content resolution, rendering, animation, scene, lighting, UI, and runtime paths instead of reproducing them in a generic external viewer.
  • Keep subject identity, named beats, camera, lighting, background, quality, and procedural coordinates human-editable in project-owned configuration.
  • Require missing content or unsupported presentation to fail visibly rather than silently substitute placeholder primitives.
  • Keep exported evidence human-authoritative and provenance-bound when a project chooses to create it.

Consequences​

  • Daily visual iteration stays inside the engine and becomes faster to tune, replay, and understand.
  • A development Almanac can evolve into a useful player-facing gallery or codex, although that is not required.
  • Projects can adopt Visual Rehearsal before implementing an export adapter.
  • Existing capture schemas and tools remain useful for remote review, regression comparison, CI integrity checks, and durable milestones.
  • Contact sheets are explicitly secondary and should not drive subject design.
  • Engine integrations require more project-native work than a generic HTML page, but that work exercises the real visual pipeline and has higher product value.

ADR 0018 later narrowed the default-surface language: existing engine previews and direct game routes remain sufficient for one-off review. A project-owned Almanac is the primary surface only for recurring Scenarios that justify it.

Last updated on