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

[HSpector1]

V0 — 3D Restaurant Readability Sandbox

Isolated visual-development track. Presentation-only. Owns no gameplay truth. Not integrated with the M0 RestaurantSim.Core.

Do not merge yet. This PR is open for Art PM review (Howard & Aaron). V0 recommends; it does not approve the visual direction, authorize M1, integrate the simulation, or self-merge.

The question V0 answers

Can a first-time viewer look at one small 3D restaurant during service and quickly understand where customers are, what staff are doing, where congestion is forming, and which area needs attention — without narration?

What's here

• Engine: Godot 4.7.1-stable, Forward+ (Metal), GDScript only. Binary lives outside the repo; not committed.
• Scale lab (1 u = 1 m locked) + three camera candidates (isometric / orbit / hybrid) + wall modes (solid / auto-hide / cutaway / transparent).
• Gray-box restaurant: 10 tables / 32 seats, host + waiting, compact 4-station kitchen + pass + dish, restrooms via a deliberate ~0.85 m pinch, staff door.
• Pure, seekable Mock/Scripted service with four scenarios whose peaks are visually distinct: healthy, kitchen bottleneck, front-of-house bottleneck, host/seating bottleneck.
• Readability language: role = colour + a second signal; table state via tinted top + disc; vertical station gauges; overlays OFF/MINIMAL/FULL; a HUD with a persistent "MOCK / SCRIPTED — not a simulation" tag.
• Evidence: 24 screenshots + 3 recordings + a performance CSV, all reproducible via tools/v0/capture.sh.

The critical read (§31.5): kitchen vs front-of-house bottleneck are unmistakably different

Kitchen bottleneck	Front-of-house bottleneck
Tall red grill gauge + orange waiting-for-food tables + servers massed idle at the pass	Calm green/idle kitchen + yellow/cyan/brown tables + a red overloaded-server ring

Scale reference and CC0 asset-assisted comparison (imports ~1:1 at 1.83 m, 43 animations):

Scale reference	Asset-assisted (CC0 Universal Animation Library)

Performance (M3 Max, 1920×1080, vsync off)

Typical frame ~3 ms (~330 FPS); worst single frame 13.9 ms (72 FPS); <850 draw calls; ~335 MB VRAM — large headroom over the 60 FPS target. Numbers are gray-box on one machine; not a production guarantee. Full table in reports/visual/v0/performance/performance.csv and the report §H.

Isolation & scope (verified)

• Branched from origin/main (06f0a7e, base only) into worktree ../Restaurant-VisualSandbox. The three M0 backend branches are untouched; nothing is merged.
• V0 touches only visual/, docs/art/, reports/, tools/, .gitignore. Zero .cs/src/tests.
• No restricted asset binaries committed — only text provenance (docs/art/ASSET-EVALUATION.md). Owner-supplied packages stay quarantined; the two Quaternius packs are CC0 (confirmed), the loose-FBX and wintersets packages are do-not-use.
• All §13 non-goals confirmed absent.

Gate recommendation

Verdict: Pass-with-notes
Action: Continue

Continue = recommend an Art PM review + a limited visual refinement pass. It does not authorize M1, backend integration, or final art.

Notes: the human visual test (§30) is prepared but not yet run (owners' to conduct); performance is validated on one machine with gray-box only.

The single Art PM decision (see report §K)

Adopt the V0 defaults — Hybrid-C camera + 1 u = 1 m scale + treatment-A readability baseline — and authorize a limited V0 refinement pass. Do not begin M1.

How to review

GODOT=~/.local/opt/godot/Godot.app/Contents/MacOS/Godot
"$GODOT" --path visual/RestaurantVisualSandbox            # run interactively (1/2/3 cameras, F1-F4 scenarios, Space pause, Tab overlays, H walls)
tools/v0/capture.sh                                       # regenerate all evidence

Full detail: reports/visual/v0/V0-REPORT.md (sections A–K, all 12 §31 pass criteria mapped to evidence).

🤖 Generated with Claude Code

[HSpector1]

Independent V0 Visual Sandbox Audit — Review

A. Review identity

Repository	HSpector1/Restaurant
Pull request	#4 — prototype/v0-3d-restaurant-sandbox → main
Exact commit reviewed	a9a4230622959987a3458300936d5ab96f987439 (matches origin PR head)
Date	2026-07-29
Method	Fresh clone at /tmp/v0-audit, read-only; project run from the clean clone; evidence regenerated and diffed; images inspected; licenses re-verified at source
Environment	Godot 4.7.1-stable (a13da4feb), Forward+/Metal, Apple M3 Max, macOS 26.5.1, 1920×1080
Sub-agents	Lead + 5 read-only reviewers: A Repo/Isolation, B Camera, C Readability, D Scale/Assets, E Performance/Reproducibility

B. Executive verdict

• Technical verdict: Pass-with-notes
• Action: Continue → authorize the uncoached human V0 visual test.
• Human-test authorization: YES (with the configuration in §L and the small pre-test items in §M).
• Merge recommendation: DO NOT merge PR #4 before the human gate.
• M1: not authorized. Backend integration: not authorized. Refinement pass: not authorized by this gate.

No Blocker and no High findings across any dimension. Every one of the five dimensions returned PASS or PASS-with-notes. The build runs cleanly from a fresh clone, its committed screenshots are byte-identical deterministic outputs of the committed code (regenerated and diffed — only performance.csv drifts, as expected), isolation from the M0 backend is total, and asset licenses are verified at source. Most importantly, an independent reviewer's uncoached first-reads of all four scenarios were correct and distinct — the core V0 readability question looks answerable.

C. Claims table

Builder claim	Verdict	Evidence
Branched from minimal main	Confirmed	merge-base(HEAD, origin/main) = 06f0a7e (the base-only tip)
Backend branches / M0 PRs untouched	Confirmed	M0 branch tips intact on origin; PRs #1–3 still OPEN; diff has 0 .cs/src/tests
Godot 4.7.1 Forward+/Metal	Confirmed	Ran the project; 4.7.1.stable.official.a13da4feb, Metal 4.0/Forward+
Three camera candidates	Confirmed	camera_rig.gd ISO/ORBIT/HYBRID; screenshots 01–04
Hybrid-C recommended	Confirmed	Reviewer B concurs (Hybrid = Orbit + focus/return)
1 unit = 1 meter	Confirmed (lock-with-notes)	v0_config.gd drives all geometry + labels; scenes 50/51 read coherently
Gray-box + scripted scenarios	Confirmed	4 scenarios; pure seekable MockService.snapshot(scenario,t)
Distinct kitchen / FOH / host / healthy	Confirmed	Distinct with HUD hidden; kitchen-vs-FOH survives greyscale at the top level
Treatment A as readability baseline	Confirmed (baseline, not final style)	40/41
Quaternius assets CC0	Confirmed at source	quaternius.com: MegaKit CC0 + Animation Library CC0 (independently fetched)
Restricted/unclear assets excluded	Confirmed	loose-FBX (no license) + wintersets (legacy) documented do-not-use; no binaries committed
~330 FPS typical / 72 FPS worst	Refined	Structural cost reproduces exactly; FPS is run-variable (fresh worst 103–420); "72" was a one-off
24 screenshots, 3 recordings	Confirmed	23 shot-list PNGs byte-identical on regen + 1 asset-assisted; 3 MP4s
No authoritative gameplay logic	Confirmed	snapshot() proven pure; renderer reads one-way; no money/served/satisfaction computed
Persistent mock/scripted disclosure	Confirmed (see D-note)	"MOCK / SCRIPTED — not a simulation" HUD tag, unconditional in _build_hud()
All V0 non-goals absent	Confirmed	Non-goal grep = documentation-only; no navmesh/save/economy/AI

D. Repository & isolation — PASS

Fresh-clone git diff 06f0a7e..a9a4230 touches only .gitignore, docs/art/*, local-assets/README.md, reports/visual/v0/*, tools/v0/capture.sh, visual/RestaurantVisualSandbox/* — zero .cs/.sln/.csproj, zero src//backend tests/ (only a 0-byte tests/.gitkeep). No tracked engine caches or asset binaries; git check-ignore confirms .godot/, placeholders/_assetlab/, local-assets/* (README kept), and asset-cache/ are ignored while the intended evidence is kept. Visual-authority boundary holds: snapshot() is a pure function of authored beats; ServiceView.apply() only reads the snapshot to choose colours/positions/overlay visibility and never writes back. All FileAccess.WRITE is evidence-capture I/O in diagnostic tooling. Every non-goal keyword hit is documentation-only.

• A6 (Low): .gitignore ignores the .import/ directory and _assetlab/, but not *.import sidecar files generally. Latent only (zero .import files exist today). Optional hardening: add *.import.

E. Camera & controls — PASS-with-notes

Clean single-node three-candidate rig; bounds match the docs (pitch 14–80, dist 6–48, ortho 7–44); the faces_camera dot-product wall-hide test is provably correct for the shown camera positions. Verdict: advance Hybrid-C as the primary management camera (Hybrid is Orbit + a focus/return convenience — do not retire Orbit).

• CAM-01 (Medium): focus_on()/return_to_overview() restore the frame()-time overview pose, not necessarily the exact pre-focus orientation if the user orbited first. Fix before Hybrid-C ships as the shipping camera; does not gate the test.
• CAM-02 (Medium): the focused view (pitch 28, dist 9) drops the room frame with no compass/return-hint. For the human test, add a "Focused — press G to return" hint and brief the operator.
• CAM-03 (Medium): rig WASD-pan poll isn't gated on the same focus condition as key handling. Harmless to the committed evidence (capture sets interactive=false); tidy later.

F. Scale — LOCK-with-notes

1 u = 1 m is coherent and structurally enforced: v0_config.gd defines every dimension metrically, and both the reference scene and the mesh builders size all proxies from those same constants (labels print the same constants, so geometry and labels cannot silently diverge). Screenshots 50/51 show correct relative ordering (adult ≈ 1.8× the 1 m cube; walk-through door; human-scale furniture). No scale hacks. Classify: ready to lock for V0 (notes are minor).

G. Readability — PASS-with-notes (the core question)

An independent, uncoached reviewer's first-reads of all four scenarios were correct and distinct: healthy = calm/no-red; kitchen = tall RED grill gauge pulling the eye to the back wall + orange tables; FOH = short cool kitchen gauges but cyan/red pass + mixed dining; host = entrance queue + idle kitchen. The lead independently confirmed the kitchen-vs-FOH distinction holds with the HUD headline hidden and survives desaturation at the top level (station-gauge height + queue-count text are non-colour cues). This is the §31.5 pass criterion, and it is met.

• C2 (Medium): per-table state is colour-only — in greyscale, table discs/tabletops collapse to near-identical grey (an orange "waiting-food" table is indistinguishable from a green "available" one). The area-level read is safe (gauge height); the per-table vocabulary is not colour-blind-safe. Document this before an uncoached test, or add a non-colour per-table signal (shape/fill/icon).
• C5 (Medium): at 960 px the on-world labels overprint capsules ("KITC.." truncates, "queue 3" overlaps the bar). Run the human test at ≥1920×1080 (where labels are legible) and fix label occlusion.
• Roles are distinguishable by colour + prop (toque/tray/clipboard/bin) — good, not colour-only.

H. Treatment — advance A as readability baseline (not final style)

Treatment A (clean/brighter) is the more readable at management distance; B (grounded/moody) is darker and better for marketing stills. Recommend A as the readability baseline / art-direction foundation, explicitly not the final shipped style.

I. Assets & licenses — PASS

Both used/evaluated packs are CC0, verified at source (not just filenames): Downtown City MegaKit and Universal Animation Library, both stated CC0 on quaternius.com. docs/art/ASSET-EVALUATION.md correctly handles the Animation Library's empty bundled License.txt by confirming CC0 at the source page. Loose-FBX (no license) and wintersets (legacy game mod) are correctly excluded / do-not-use. No asset source binary is committed. Animation compatibility (1.83 m, scale factor 0.984, 43 animations) is credible and reproduces the scale lock — but it is builder-attested: the CC0 GLB is git-ignored, so screenshot 60 is not regenerable from the clone alone (correct license hygiene; note the asymmetry).

J. Performance & reproducibility — ADEQUATE (scoped to the M3 Max)

The load-independent structural columns (draw calls 671–848, primitives 137k–475k, VRAM ~335 MB, mesh/actor counts) are stable and reproduce exactly. These are the defensible signal and they indicate real gray-box headroom.

• PERF-1 (Medium): the FPS columns are run-variable (committed worst 72–330 vs fresh worst 103–420) and read as more precise than the data supports. Reframe: lead with frame-time (~3 ms typical) + draw calls + VRAM; present worst-frame as a range or drop it. "Far exceeds 60 FPS" is fair only as "no red flags on one high-end machine, gray-box, uncapped vsync."
• PERF-4 (Medium): no documented step tells a fresh reviewer how to obtain Godot 4.7.1-stable (the version is pinned; the download is not). One line in the README/capture.sh closes it.
• Media = 27 files / ~7.7 MB, no LFS — proportionate for V0; recommend recordings move to release artifacts at future milestones.

K. Evidence — authentic and reproducible

All 23 shot-list screenshots regenerated byte-identical from the clean clone (deterministic; not hand-picked). Images are 1920×1080 and match their labels; the earlier duplicate (22 == 11) is fixed (the triptych is now a controlled HUD-off off/minimal/full set). The report's §H table matches the committed CSV exactly. The only non-reproducible artifact is screenshot 60 (git-ignored CC0 source, disclosed).

L. Human-test configuration (recommended, single-variable)

Setting	Value
Camera	Hybrid-C, default overview; focus-dive available; brief operator "press G to return"
Resolution	≥1920×1080 on a real display (not 960 px)
Walls	AUTO_HIDE default (context + interior visibility)
Treatment	A
Overlays	MINIMAL→FULL (station gauges + queue-count labels ON); HUD headline OFF during the blind comprehension phase so the answer is not given away
Mock disclosure	Facilitator verbally states "mock/scripted visualization" during the blind phase (the HUD tag is hidden with the headline); reveal the HUD after each answer
Scenario order	Healthy first (baseline), then the three bottlenecks in a non-obvious order; titles hidden until the viewer answers
Reset	R resets the active scenario; F1–F4 select scenario

Do not vary camera and treatment and overlay simultaneously — hold them fixed and vary only the scenario.

M. Required corrections before an honest human test

(test-protocol / doc items only — none require a code refinement pass, and none are code blockers)

1. Run at ≥1920×1080 and confirm on-world labels are legible (C5).
2. Brief the operator on focus→G-return and keep a return hint visible (CAM-02).
3. Disclose the colour-only limitation of per-table state to note-takers (C2) — do not let a colour-blind pilot's confusion be misread as a design failure.
4. Nice-to-have: one-line Godot-download note (PERF-4); reframe FPS wording (PERF-1). Not required to run the test.

N. Final gate

Verdict: Pass-with-notes
Action: Continue

Continue authorizes the uncoached human V0 visual test only. It does not authorize the limited refinement pass, merging PR #4, backend integration, or M1.

O. Required Art PM decision

Authorize the uncoached human visual test of V0 (PR #4) using the §L configuration — Hybrid-C overview, Treatment A, MINIMAL/FULL overlays with the HUD headline hidden during the blind phase, at ≥1920×1080 — and keep PR #4 unmerged until that test is run. Everything else (refinement pass, merge, integration, M1) stays deferred pending the test's outcome.

---

Independent review complete. Read-only. PR #4 not modified, not merged. M0 backend untouched. No refinement, integration, or M1 begun.