# Spec: Bevy visual floor ``` Type: spec Status: IMPLEMENTED Status note: implemented 2026-07-07 as a frontend-only visual floor: the B1 Bevy frame uses an amber attention reticle instead of a humanoid sprite, clinical fog/tile hierarchy, deliberate sensor-dark substrate, flat schematic default tiles, amber device nodes and reach/topology traces, a material-preview toggle for authored/generated art, and a right rail rebuilt as a Bevy-native command surface with pinned status/nudge/footer, priority cards, a graphical fleet aggregate bar, graphical detection rows, and scrollable secondary detail. Further polish belongs in interface/bevy-digital-real-canvas.md or narrower follow-up specs. Stage: Process / B1 frontend Design: - wiki/art/visual-identity.md#visual-identity-clinical-gore - wiki/interface/terminal-first.md#the-terminal-is-a-first-class-frontend - wiki/interface/presence.md#two-views-of-one-world-same-frame-digital-and-real-representations - wiki/vision/simulation-laws.md#justification-and-legibility Depends on: - wiki/interface/bevy.md#the-bevy-frontend - wiki/interface/flat-materials.md#spec-flat-materials-the-world-without-textures - wiki/mechanics/cursor.md#spec-the-cursor-and-the-senses - wiki/mechanics/reach.md#spec-digital-reach - wiki/interface/views.md#spec-views-same-frame-digital-and-real-representations ``` ## Dependency notes The structured references above identify the contracts to re-verify. Relationship context: interface/bevy.md (current Bevy parity), interface/flat-materials.md (world art is flat palette materials), mechanics/cursor.md (cursor is attention, not a body), mechanics/reach.md (digital-machine presence), interface/views.md (future split; this pass must not fight it) ## Why this spec exists The Bevy frontend reached mechanical parity before it reached the visual floor. The current default frame can read like a debug viewport: a small island of known tiles floating in a sea of unstyled black, a terminal-style text dump in the sidebar, and a purple humanoid process sprite at the center. That violates the clinical-gore identity and the cursor fiction even when the mechanics are correct. This spec is the narrow, implementable visual contract for the next pass: make one screenshot at game start look intentional, readable, and native to Misaligned, without waiting on new generated art and without hiding unearned facts. ## Scope In scope: - Bevy-only presentation, camera framing, tile tinting, lightweight overlays, UI layout, sidebar chrome, panels, and placeholder treatment. - Reusing, tinting, masking, or replacing current runtime assets with simple procedural shapes when an existing asset contradicts the fiction. - Updating the placeholder ledger when a placeholder is deliberately changed. Out of scope: - New sim mechanics, save fields, or knowledge state. - The full `views.md` implementation (digital graph default + physical flip). This spec must stage toward it, not replace it. - New art generation pipelines. World art is flat materials ([flat-materials.md](flat-materials.md)); ROADMAP #13 is retired. ## Visual contract ### Composition: no postage-stamp map The map pane is the hero surface, not empty letterboxing. At a new-game default window the known/remembered/blueprint content should occupy a deliberate frame: large enough to read tile silhouettes and object identity, with the camera centered on the relevant known cluster and not on an ocean of empty renderer black. The default presentation should read as an **AI sensorium**: a learned model, telemetry overlay, or device topology projected over the physical space, not a tiny character standing in a dungeon room. Unknown space may remain dark, but it must look like **sensor darkness**, not a missing scene. Use a near-black substrate, vignette, subtle grid/noise, or edge falloff that carries no factual tile information. The player should understand: "I am blind here," not "the game forgot to draw here." (Amended 2026-07-09: this fit-to-known-content default composition now governs the **flat sensorium** camera. The material render's default frame is the attention close-up owned by [material-dark-frame.md](material-dark-frame.md); the deliberate-frame and sensor-darkness requirements above still bind it in spirit.) ### Cursor: attention, not avatar The always-visible marker is the frontend cursor from cursor.md. It must read as an amber reticle/signal/selection focus, not as a body, character, pawn, or creature. Until a purpose-built process marker exists, the purple/teal humanoid sprite is forbidden in the B1 Bevy frame. The cursor can glow, pulse, bracket, or outline the selected tile; it cannot imply the AI is physically standing in the room. ### Fog and tile hierarchy Fog states are visually distinct while obeying the legibility law: - **Unknown:** near-black sensor darkness; no room edges, people, hardware, or tile facts. - **Blueprint / remembered:** schematic gunmetal/chrome silhouettes; enough geometry to orient, explicitly not live. - **Audio:** no tile grade or coverage diagram. A recent semantic capture may pulse briefly at the subscribed device in cold signal; it earns no room edge, person position, hardware, or floor fact (cursor.md). - **Seen / telemetry:** Seen is the richest *legible* treatment the current assets support; telemetry is panel proprioception and does not paint a material chassis before Seen (material-dark-frame.md). In the default sensorium this means quiet flat clinical blocks plus overlays, not noisy generated swatches. The pixel-art/material textures are allowed in the F3 material preview or future cohesive art passes, but they are not the default if they compete with fog, devices, and cursor semantics. Within earned visibility, hierarchy is fixed: 1. Cursor/selection and active machine presence (amber) read first. 2. The core and powered hardware read second, with restrained amber glow or rim-light. 3. Walls/doors/furniture establish the physical layout. 4. Floor texture is lowest contrast and never competes with objects. ### Sidebar: graphical command surface, not terminal dump The right sidebar may keep monospaced text for precision, but it must be a Bevy UI surface, not copied terminal output. Scrollability is only an overflow escape hatch; if the first screen is still a chronological text dump, the spec has failed. The rail has an explicit read order: 1. **Status header:** title, day/tick, run state, current representation, and the render toggle. This is pinned. 2. **Priority nudge:** one actionable sentence answering "what should I look at next?" This is pinned with the header. 3. **Focus:** cursor coordinate, fog state, and a small set of provenance-tagged facts for the selected tile. 4. **Live systems:** cycles, cover process, observer model, self host, and network/money as cards, ordered by what most often changes the next action. 5. **History and controls:** recent trace is secondary; the command vocabulary lives in a quiet pinned footer instead of consuming the live telemetry area. Required treatment: - A distinct dark rail with padding and visually separated cards. - No terminal chrome as primary structure: no `-- SECTION --` headers and no ASCII fleet bars when Bevy rectangles can carry the shape. - Fleet aggregate rendered as a real horizontal bar with adjacent labels, percentages, and effects. - Detection rendered as boxed rows or cells with observer labels and band names; color is never the only carrier of risk. - The clock, run state, current representation, priority nudge, and essential controls remain visible even when secondary cards are scrolled. - Key hints are visually quieter than live telemetry and pinned to the lower area. - Log lines retain tick prefixes and have their own bounded card. ASCII strings can remain inside cards when they are data. The Bevy sidebar is a command surface: it should answer "where am I looking, what is starving, what can catch me, and what key opens the next panel?" before it dumps exhaustive state. ### Panels and overlays Modal panel-open keys are gone (Actions live on the thing): status lives on the rail cards, local verbs on the focused spatial anchor, and strategic verbs on exact semantic objects in the Operations workspace. Overlays that remain (title, game-over, context-menu card, Operations) use the same amber/bone/crimson vocabulary as the main frame — dark translucent background, light border, padding, selected-row highlight, footer hints. ### Color and typography The terminal palette's meanings bind here too: bone/chrome/gunmetal for data and structure, sterile amber for machine presence, selection, active nodes, and AI telemetry traces; crimson for detection/danger only. Purple/teal from the deleted lair theme is stale and must not appear as a B1 default color. The default Bevy font is acceptable for now, but text hierarchy must come from size, weight, spacing, cards, and alignment. Labels are quieter than values; values are quieter than alerts. ## Acceptance criteria 1. At the default Bevy window size, a fresh run's first playing frame reads as an intentional AI sensorium: the known map cluster is framed prominently, unknown space has deliberate sensor-dark treatment, earned devices read as amber nodes/topology, and the sidebar is a designed panel rather than a text dump on black. 2. The cursor/process marker is non-humanoid and amber-coded; no purple/teal humanoid process sprite appears in the B1 default frame. 3. Unknown, blueprint/remembered, and seen/telemetry states are visually distinguishable and do not reveal facts the sim has not earned; audio events remain distinguishable device-bound evidence rather than a fog state. 4. Core and powered hardware have visible amber machine-presence treatment; floors, walls, doors, and objects have a readable contrast hierarchy. 5. The sidebar uses Bevy UI chrome: grouped cards, pinned status/nudge/footer, a readable first-screen priority order, and at least the fleet aggregate and detection meters represented as graphical bars/rows with adjacent labels/numbers. 6. Title, game-over, and context-menu overlays remain fully playable and use Bevy-native card chrome (background, border, selected-row treatment, footer hints) without losing terminal-parity action reachability. 7. The implementation touches only frontend/art/documentation surfaces. `Sim`, save/load, and tests of game rules remain unchanged unless a pre-existing bug is found and separately defended. 8. Verification includes `cargo fmt` and `./tools/check.sh --frontend` (tests plus `cargo clippy -p misaligned-bevy -p misaligned-assets --all-targets`), and an observed Bevy launch or screenshot noted in the devlog.