V0 — 3D Restaurant Readability Sandbox (visual track — do not merge, Art PM review)

.gitignore

@@ -47,3 +47,33 @@ Icon?
 /scratch/
 /tmp/
 *.log
+
+# ============================================================
+# V0 — 3D Restaurant Readability Sandbox (visual track)
+# ============================================================
+
+# --- Godot 4 engine cache / machine-local state (regenerated on open) ---
+.godot/
+visual/**/.godot/
+.import/
+export_presets.cfg
+exports/
+*.tmp
+
+# --- Local CC0 asset-lab extracts (source + Godot .import sidecars stay local) ---
+visual/RestaurantVisualSandbox/placeholders/_assetlab/
+
+# --- Local asset quarantine (§10) ---
+# Restricted / paid / unclear-license extracts live here and NEVER get committed
+# to this public repo. Provenance is tracked as text in docs/art/ASSET-EVALUATION.md.
+# Ignore all contents but keep the explanatory README committed as documentation.
+/local-assets/*
+!/local-assets/README.md
+asset-cache/
+
+# --- OS metadata ---
+Thumbs.db
+
+# NOTE: evidence intentionally committed under reports/visual/v0/ is NOT ignored.
+# (*.png screenshots, *.mp4 / *.gif recordings, *.csv / *.md performance & reports)
+# The audio/binary-art ignores above (*.wav/*.mp3/*.ogg/*.fbx/*.glb/...) do not match them.

docs/art/ART-DIRECTION-HYPOTHESES.md

@@ -0,0 +1,131 @@
+# Art Direction Hypotheses — V0 Readability Sandbox
+
+**Track:** V0 — 3D Restaurant Readability Sandbox
+**Scope:** the two visual-style treatments tested on the same gray-box (§27)
+**Status:** hypothesis for the Art PM — **not** a locked visual direction
+
+> V0 is a presentation-only gray-box experiment. It owns no gameplay truth, is not
+> integrated with `RestaurantSim.Core` (M0), and cannot approve visual direction,
+> authorize M1, or merge its own PR. Everything below is a **recommendation** for
+> Howard & Aaron and the Art PM to weigh; nothing here is a decision. See
+> `docs/art/V0-PROTOTYPE-CONTRACT.md` §9.
+
+---
+
+## 1. What was tested
+
+Two lighting/tone treatments were applied to the **identical** gray-box scene
+(`scripts/stage.gd`) — same geometry, same scale lock (§4), same camera, same
+scripted service, same overlays. Only the render mood changed. This isolates
+"treatment" from every other variable, so any difference in readability or appeal
+is attributable to the treatment alone.
+
+| | Treatment A | Treatment B |
+|---|---|---|
+| Label (§27) | "clean stylized management sim" | "grounded but readable" |
+| Ambient | 0.75 (bright) | 0.22 (low) |
+| Key light | soft light | stronger sun + shadows |
+| Tonemap | ACES | ACES |
+| SSAO | light | stronger |
+| Palette | brighter, higher-key | muted, darker |
+| Evidence | `reports/visual/v0/screenshots/40-treatment-A-clean.png` | `reports/visual/v0/screenshots/41-treatment-B-grounded.png` |
+
+Both images show the same restaurant floor from the same angle. In `40` the floor,
+walls, and role/state colours read as separated, high-contrast blocks. In `41` the
+same scene sits in deeper shadow: the mood reads richer, but darker regions
+(back-left kitchen, near-wall interiors) lose colour separation and the state
+signals sit closer together in value.
+
+---
+
+## 2. Comparison
+
+Scored on the criteria that matter for a management sim seen at management distance.
+"Management distance" here means the default readable overview the game will actually
+be played from — the ISO / hybrid-overview framings (§ cameras;
+`reports/visual/v0/screenshots/01-camera-A-isometric.png`,
+`03-camera-C-hybrid-overview.png`), not a close-up marketing crop.
+
+| Criterion | Treatment A (clean) | Treatment B (grounded) | Edge |
+|---|---|---|---|
+| **Readability at management distance** | High. Brighter ambient (0.75) keeps role colours (§21) and table-state tints (§22) separated in value across the whole floor. | Lower. Low ambient (0.22) + strong shadow compress darker zones; state tints crowd together where the sun doesn't reach. | **A** |
+| **Distinctiveness** | Clean, "management sim" look; risk of reading generic if under-detailed. | Moodier, more cinematic; feels more like a "place." | **B** |
+| **Asset compatibility** | Both treatments run on the same gray-box; the cleared CC0 Downtown MegaKit and the 1:1 Universal Animation Library import (see `ASSET-EVALUATION.md`) are neutral to lighting choice. A's soft light is more forgiving of flat/placeholder albedo. | Same assets; stronger shadow rewards higher-detail meshes and better materials — a heavier art bar to look intentional rather than just dark. | **A** (lower asset bar) |
+| **Production feasibility** | Fewer lighting variables to tune; soft light + light SSAO is cheap to author and stable across scenes. | More to balance (sun angle, shadow bias, SSAO strength, exposure) so darkness stays *readable* and not just dim. | **A** |
+| **Animation / lighting burden** | Lighter. Soft, mostly-ambient light hides interpolation seams and idle-motion imperfections. | Higher. Hard shadows and contrast expose animation pops, foot-slide, and popping, and demand tighter shadow tuning per camera angle. | **A** |
+| **Screenshot / marketing appeal** | Clear and legible but flatter; less dramatic as a hero still. | More atmospheric; better contrast and depth for a marketing still or trailer frame. | **B** |
+| **Risk of looking generic** | Real risk: bright + clean can read as "any Unity/Godot management asset flip" if not backed by strong shape language. | Lower risk of generic; mood gives identity — but higher risk of reading as "murky" or hard to parse. | split |
+
+Performance is **not** a differentiator: both treatments render the same gray-box and
+the sandbox far exceeds target on the documented machine — typical frame ~3 ms
+(~330 FPS), worst single frame 13.9 ms (72 FPS, a one-off hitch), ~335 MB VRAM,
+< 850 draw calls, against a 60 FPS target / 30 FPS floor (§28;
+`reports/visual/v0/performance/performance.csv`). SSAO/shadow cost was not isolated
+per treatment; treatment-level GPU deltas were **not measured in V0**.
+
+---
+
+## 3. Finding
+
+**A is more readable at management distance. B is moodier but darker, and the
+darkness costs readability.**
+
+The single question V0 exists to answer (§1) is whether a first-time viewer can read
+where customers are, what staff are doing, and where congestion is forming, without
+narration. Readability is the primary axis; mood is secondary. On the primary axis,
+A wins: at 0.75 ambient the role/state colour language (§21–23) stays separated in
+value across the entire floor, including the back-left kitchen and near-wall seating
+that B pushes into shadow. B's atmosphere is genuinely more attractive as a still,
+but it compresses exactly the value separation the readability language depends on —
+most visibly in the darker kitchen zone where the vertical station gauges (§22) and
+table discs need to pop.
+
+This finding is drawn from the two-image A/B comparison
+(`40-treatment-A-clean.png` vs `41-treatment-B-grounded.png`) under identical
+geometry and camera. The **human visual test (§30) is prepared but was not run** —
+that is Howard & Aaron's to conduct — so this is a builder-side read of the evidence,
+not a validated user finding.
+
+---
+
+## 4. Recommendation (hypothesis, not a decision)
+
+1. **Adopt A ("clean stylized") as the readability baseline** — the default look the
+   game is designed and tuned against, and the tone under which the readability
+   language (§21–23) is validated.
+
+2. **Reserve B ("grounded") for marketing stills and non-gameplay presentation** —
+   hero shots, trailer frames, key art — where a fixed, art-directed camera and
+   crop can compensate for the lost floor-wide legibility, and where mood earns its
+   keep.
+
+3. **Treat this as a hypothesis for the Art PM, not a locked direction.** The right
+   next step is the §30 human visual test on both treatments before anything is
+   committed. A viable outcome is a *tuned middle*: A's ambient floor with a
+   controlled amount of B's shadow/SSAO for depth — kept only as far as it does not
+   compress the state palette. V0 recommends; it does not approve (§9).
+
+### Open questions for the Art PM
+
+- Does A hold up once real (non-placeholder) materials replace flat gray-box albedo,
+  or does its "generic" risk grow? (Not testable in V0 — placeholder-first, §7.)
+- How dark can B go before state colours stop being distinguishable in the §30 test?
+  The crossover point was not measured here.
+- Is there a single tuned treatment that keeps A's floor-wide readability while
+  borrowing enough of B's depth to lower the "generic" risk?
+- Per-treatment GPU cost of the heavier shadow/SSAO in B — not isolated in V0.
+
+---
+
+## 5. Evidence index
+
+| File | Shows |
+|---|---|
+| `reports/visual/v0/screenshots/40-treatment-A-clean.png` | Treatment A, clean stylized (ambient 0.75) |
+| `reports/visual/v0/screenshots/41-treatment-B-grounded.png` | Treatment B, grounded (ambient 0.22) |
+| `reports/visual/v0/screenshots/01-camera-A-isometric.png` | ISO framing — a management-distance read |
+| `reports/visual/v0/screenshots/03-camera-C-hybrid-overview.png` | Hybrid overview — the default play framing |
+| `reports/visual/v0/screenshots/20-overlay-off.png` … `22-overlay-full.png` | Readability overlays that both treatments must carry |
+| `reports/visual/v0/performance/performance.csv` | Perf headroom (not a treatment differentiator) |
+| `docs/art/ASSET-EVALUATION.md` | Asset licensing/scale that both treatments inherit |
+| `docs/art/V0-PROTOTYPE-CONTRACT.md` | The shared visual contract (§ references above) |

docs/art/ASSET-EVALUATION.md

@@ -0,0 +1,65 @@
+# V0 — Asset Evaluation & Provenance (§10)
+
+**Verified:** 2026-07-29 · **Method:** each archive inspected read-only from the owner's
+Desktop (`~/Desktop/Restaurant Empire/`); only text/license files were read; **no binary
+was extracted into the repo**. Licenses confirmed **twice** where possible: the bundled
+license file **and** the live source page.
+
+> **Hard rule (§10).** Ownership of an asset-store package is **not** permission to upload
+> its source files to a public GitHub repo. No supplied package's source is committed here.
+> Archives stay on the owner's disk; any local extract lives only in the git-ignored
+> `local-assets/`.
+
+## Disposition table
+
+| Package | Source / author | Version | License | Commercial use | Public redistribution | Import result | V0 status |
+|---|---|---|---|---|---|---|---|
+| `Downtown City MegaKit[Standard].zip` (235 MB) | **Quaternius** (quaternius.com) | Standard / FREE (partial model set) | **CC0 1.0 Universal** — stated in bundled `License_Standard.txt` **and** at source | **Yes** | Permitted (CC0), **but not done** — repo hygiene (large binary; not needed for gray-box) | *Pending local import test (Phase C, asset-assisted comparison)* | **Approved for local evaluation** |
+| `Universal Animation Library[Standard].zip` (16 MB) | **Quaternius** | Standard / FREE | **CC0 1.0** — bundled `License.txt` is **empty (0 bytes)**; **confirmed CC0 at quaternius.com 2026-07-29** ("Free to use in personal, educational and commercial projects. CC0 License") | **Yes** | Permitted (CC0), **not done** (hygiene) | *Ships Godot-ready GLB + `Godot_Setup.png`; retarget test pending (Phase C)* | **Approved for local evaluation** |
+| `FBX-20260727T232629Z-1-001.zip` (1.5 MB) | **Unknown** (loose FBX props: `Table_RoundLarge`, `Houseplant_*`, `Bathroom_Mirror2`, `Light_*`) | Unknown | **None found** — no license file in the archive; publisher unidentifiable | **Unknown** | **No** | Not attempted | **Rejected — do not use** (no provenance) |
+| `wintersets.zip` (17 MB) | **Unknown legacy game mod** ("Zapsters-Wintersets modded by Zapster"; `zapinfo` installer, German `Deinstallationsanleitung.txt`, backdrops/lightmaps/camera-swing terminology) | Unknown | **None** (installer package; presumed proprietary legacy game content) | **No** | **No** | Not attempted | **Rejected — do not use** |
+
+## Per-package detail
+
+### Downtown City MegaKit [Standard] — CC0, cleared
+`License_Standard.txt` (verbatim): *"License: CC0 1.0 Universal (CC0 1.0) Public Domain
+Dedication … Models by @Quaternius."* This is the **free** version (a portion of the models);
+a paid SOURCE version exists with Godot projects/shaders. Contains `Exports/FBX (Unity)/…`
+(e.g. `Brick_*.fbx`) and `Textures/`. It is a **downtown/city exterior** kit — buildings,
+brick columns, trims — so its relevance to a restaurant *interior* is limited; useful mainly
+for an **exterior/street context** block and as a scale-compatibility check. **FBX import**
+in Godot 4.7 works via the built-in `ufbx` importer (no external converter needed) but FBX
+retains Unity axis/scale conventions — expect a 0.01 scale factor and axis fix on import.
+
+### Universal Animation Library [Standard] — CC0, cleared (source-confirmed)
+Bundled `License.txt` and `README.txt` are **empty**, which is a packaging omission, not a
+license grant — so per policy it was treated as *unresolved* until the **source page confirmed
+CC0** (quaternius.com, 2026-07-29). Ships `Unreal-Godot/UAL1_Standard.glb` (+`_RM.glb`
+root-motion) and a `Godot_Setup.png` guide — i.e. **explicitly Godot-ready animations in glTF**,
+which import natively in Godot 4 with their `AnimationPlayer`. This is the single most
+relevant supplied pack for eventual character motion. **V0 does not build the animation state
+machine** (§26); at most a Phase-C retarget/scale spot-check is warranted.
+
+### FBX-…zip — no license, do not use
+Ironically the most *restaurant-relevant* props (round tables, houseplants, a bathroom mirror,
+ceiling/stand lights), but the archive carries **no license file and no identifiable publisher**.
+Under `LICENSE-POLICY` ("anything with unclear or missing license is rejected by default"),
+it is **do-not-use** until the owner establishes where it came from and under what terms.
+
+### wintersets.zip — legacy game content, do not use
+Structure (`zapinfo` installer, `Data/meshes/*.txt`, "Sets/backdrops/thumbs/camera-swing"
+vocabulary, German uninstall guide) is unmistakably a **legacy game's set-mod package**. No
+license; presumed proprietary. **Do not use** unless the owner produces explicit rights.
+
+## Import compatibility (summary)
+- **glTF/GLB** (Universal Animation Library) → native Godot 4 import, animations intact. Best path.
+- **FBX** (MegaKit) → Godot 4.7 built-in importer; watch Unity-scale (×0.01) and axis conversion; compare against the scale-reference scene before trusting.
+- **No package is imported into V0 by default** (placeholder-first, §11). Any Phase-C
+  asset-assisted screenshot uses only CC0 packs, extracted to `local-assets/` (git-ignored),
+  and is documented as a *comparison*, never as the sandbox's identity.
+
+## Recommended future use (M1+, not V0)
+- **Characters/animation:** Universal Animation Library (CC0, Godot-ready) is the prime candidate — pending a proper retarget evaluation.
+- **Exterior/street dressing:** Downtown City MegaKit (CC0) for context blocks only.
+- **Interior props:** source a **licensed** restaurant-interior kit; the loose FBX pack is not usable as-is.
+- **Delivery:** even for CC0, decide Git-LFS-vs-external-store before committing any large binary; do not push source packs into this public repo.