# Spec: material render — HD-2D to default quality

```
Type: spec
Status: IMPLEMENTED
Status note: implemented 2026-07-08 — the material render is the Bevy
  default physical view; F3 flips to the flat sensorium. Debts paid:
  fog-gated south-face cutaway (chosen over a steeper pitch by
  screenshot comparison), dedicated darkened top caps on all extruded
  boxes, palette sweep of the b1 set (door/UPS/HVAC/switch hue-remapped
  off the stale purple/teal lair palette), fog contract asserted by a
  dev-harness audit (unknown=absent, model=unlit, seen=lit), zoom
  bounds tightened to hold the framing floor, and (tile, fog, part)
  material pooling with handle swaps (37 pooled handles for ~4600 tile
  entities in the audit run). People remain procedural silhouette
  billboards pending the cast sprite pass (debt 6, out of scope here).
  Prototype findings inventory: wiki/log/2026-07-07-hd2d-prototype.md;
  session log: wiki/log/2026-07-08-material-render-default.md.
  2026-07-08 flat-materials restyle (flat-materials.md): the texture
  language here (tile textures on sides, concrete caps) is superseded
  by solid palette color; the structural criteria (cutaway, caps,
  framing, fog contract, pooling, default view) were re-verified after
  the restyle — fog_audit_3d green, zoom-bound screenshots retaken.
  2026-07-09 dark-frame amendment (material-dark-frame.md): in the
  material render, blueprint/remembered mass is absent (not unlit) and
  the default framing is the attention close-up, not
  fit-to-known-content; that spec owns both clauses now. The flat
  sensorium keeps unlit blueprint; everything else here carries over.
  2026-07-10 perf pass: wall-clock timer lives off Game so restyle/UI
  do not rebuild every display frame; owned-tile caches; Heard noise
  walks the heard set (wiki/log/2026-07-10-bevy-perf-pass.md).
Stage: B1 — The Basement
Design:
  - wiki/interface/presence.md#two-views-of-one-world-same-frame-digital-and-real-representations
  - wiki/art/visual-identity.md#visual-identity-clinical-gore
  - wiki/vision/simulation-laws.md#justification-and-legibility
Depends on: views.md (same-frame contract), cursor.md (fog states),
  bevy-visual-floor.md (framing floor), the landed F3 toggle
```

## Behavior

The material render (Camera3d, extruded walls, billboarded sprites,
lit) becomes the default physical-view treatment in Bevy once its debts
are paid; the flat sensorium render remains the digital-layer treatment
and the terminal remains first-class. The prototype's fog contract is
law: unknown space is absent geometry, blueprint/remembered surfaces
render unlit, only camera-seen surfaces participate in lighting.
(Amended 2026-07-09: in the *material* render blueprint/remembered mass
no longer draws at all — [material-dark-frame.md](material-dark-frame.md)
owns that clause; unlit blueprint remains the flat sensorium's
treatment.)

## The debts (from the prototype findings)

1. **South-wall occlusion:** walls between the camera and room
   interiors hide them at the 40 degree pitch. Fix by cutaway (short or
   faded south faces) or steeper pitch; pick by screenshot comparison.
2. **Slab tops:** extruded boxes reuse wall textures on top faces and
   read as gray slabs. Top faces get a dedicated treatment (darkened
   variant or a top-face texture set).
3. **Stale palettes:** the door PNG reads purple under 3D light; sweep
   tiles for palette debts against the clinical-amber palette.
4. **Framing:** the visual-floor rules (fit-to-known-content, no
   postage stamp, no void-dominant frame) hold in material mode at all
   zoom levels.
5. **Perf:** materials pooled by (tile, fog, part) and handle-swapped;
   no per-tile unique material mutation (prototype finding 5). Wall-
   clock pacing must not dirty the Game resource every display frame —
   restyle_3d, map recolor, and the sidebar rebuild only on sim steps
   (or explicit dirty), not at 60 Hz from the tick timer alone.
6. **People:** the procedural silhouette billboards are placeholders;
   they read as presence, not identity, until the cast sprite pass —
   identity stays a panel/menu fact (legibility, not portraiture).

## Acceptance criteria

1. Room interiors are readable at default pitch: the chosen occlusion
   fix (cutaway or pitch) lands with before/after screenshots in the
   session log.
2. Top faces no longer read as untextured slabs (dedicated treatment).
3. No stale-palette tiles remain in the b1 set under 3D light (door
   fixed; sweep recorded).
4. The fog contract holds and is asserted: unknown = no geometry,
   blueprint/remembered = unlit, seen = lit (screenshot or debug-dump
   verification recorded in the log).
5. Framing floor holds in material mode (fit, zoom bounds, no void
   dominance) — checked at min/default/max zoom.
6. Material pooling implemented; tile-count-scaled material churn is
   gone (no per-tile unique materials in the frame loop). Full map
   restyle is not driven by the wall-clock timer alone — only by sim
   steps or an explicit dirty flag (2026-07-10).
7. Material render becomes the default physical view (F3 still flips
   to sensorium); README and bevy.md updated; terminal unaffected.