diff --git a/Directory.Build.props b/Directory.Build.props new file mode 100644 index 0000000..3219789 --- /dev/null +++ b/Directory.Build.props @@ -0,0 +1,14 @@ + + + + latest + enable + enable + + true + true + false + false + + diff --git a/README.md b/README.md index ff576d0..2fa8daf 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,68 @@ -# Restaurant (working codename: "Mise") +# Restaurant (working codename: **"Mise"**) -Pre-production. A single-player restaurant-management simulation; spiritual successor to -a 2003-era restaurant tycoon design, rebuilt on a deterministic, engine-agnostic core. +A single-player, desktop-first **restaurant-management simulation** — a spiritual successor to a 2003-era +restaurant tycoon, rebuilt on a deterministic, engine-agnostic core. **Pre-production; currently at +milestone M0.** This is not a finished game, and it will not ship under the "Restaurant Empire" name. -Active development happens on the branch **`foundation/m0-headless-service-lab`** and is -delivered to owners via pull request for review. That branch contains the full project -structure, the planning and architecture documents, and the **M0 Headless Service Lab**. +> **Core fantasy:** *I build one distinctive restaurant whose menu, people, layout, and service work as a +> coherent machine, and then turn that hard-won operating model into a culinary empire.* +> +> **Design spine:** **the menu is the strategy.** A menu determines demand, expectations, ingredient cost, +> kitchen-station load, prep complexity, chef needs, service speed, waste, pricing power, identity, and +> profitability. -See the open pull request (or that branch) for everything. This `main` branch holds only -the license and this pointer until the M0 gate is reviewed and merged by the owners. +## Status: M0 — Headless Service Lab +M0 answers one question, headless, before any graphics: + +> *Can menu, pricing, staffing, and capacity decisions create multiple understandable and viable restaurant +> strategies, with visible consequences that make players want to revise their plan and run another service?* + +Built: a deterministic simulation core, a playable CLI loop, an automated strategy/distribution/determinism +harness, 74 passing tests, and committed evidence. See [`docs/CURRENT-STATE.md`](docs/CURRENT-STATE.md). + +## Repository structure +``` +docs/ plans, design & architecture contracts, risks, commercial & playtest docs, archive +src/ RestaurantSim.Core (pure sim) · .Cli (player loop) · .Harness (evidence) +tests/ Core / Determinism / Scenario test projects (74 tests) +fixtures/ (reserved for external fixture data; M0 fixtures are code in Core/M0Content.cs) +reports/ generated evidence: balance/ determinism/ m0/ +tools/ (reserved) +``` + +## Build and run +Requires the **.NET 8 SDK** (pinned in `global.json`). + +```bash +dotnet build Restaurant.sln # build everything +dotnet test Restaurant.sln # run all 74 tests + +# play the M0 loop (interactive): inspect -> plan -> forecast -> commit -> autopsy -> revise -> run again +dotnet run --project src/RestaurantSim.Cli +# e.g. inside: preset "Balanced Competent" -> forecast -> log on -> run +# or run one strategy non-interactively: +dotnet run --project src/RestaurantSim.Cli -- strategy "Focused Value" lunch-rush 700042 + +# regenerate the evidence reports (distribution, determinism, example autopsy): +dotnet run -c Release --project src/RestaurantSim.Harness -- --seeds 200 --out reports +``` + +Generated reports appear under [`reports/`](reports/): `balance/distribution.md`, +`determinism/checksums.md`, `m0/example-forecast-vs-actual.txt`. + +## What is explicitly NOT being built yet +No graphics, engine, pathfinding, inventory/suppliers, recipe editor, competitors, campaign, managers, +multiple restaurants, save system, audio, or asset integration. These are on the M0 non-goals list and the +deferred backlog by decision, not oversight. See +[`docs/design/DEFERRED-FEATURES.md`](docs/design/DEFERRED-FEATURES.md). Only M0 is authorized. + +## Read next +- [`docs/MASTER-PLAN.md`](docs/MASTER-PLAN.md) — the active plan (and the change record over the archived v1). +- [`docs/CURRENT-STATE.md`](docs/CURRENT-STATE.md) — what's true right now. +- [`docs/NEXT-ACTION.md`](docs/NEXT-ACTION.md) — the single next authorized action (re-verify reality first). +- [`docs/design/M0-PROTOTYPE-CONTRACT.md`](docs/design/M0-PROTOTYPE-CONTRACT.md) — the M0 scope and gate. +- [`docs/architecture/DETERMINISM-CONTRACT.md`](docs/architecture/DETERMINISM-CONTRACT.md) — the numeric/RNG rules. + +## License +Proprietary; all rights reserved. Commercial game in pre-production. See [`LICENSE`](LICENSE). Third-party +asset packages are recorded in [`docs/assets/`](docs/assets/) and deliberately not committed here. diff --git a/Restaurant.sln b/Restaurant.sln new file mode 100644 index 0000000..fd9c4fa --- /dev/null +++ b/Restaurant.sln @@ -0,0 +1,64 @@ + +Microsoft Visual Studio Solution File, Format Version 12.00 +# Visual Studio Version 17 +VisualStudioVersion = 17.0.31903.59 +MinimumVisualStudioVersion = 10.0.40219.1 +Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{7A4E9898-B55F-4C7F-A8B5-E3F3AAF7D1FB}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "RestaurantSim.Core", "src\RestaurantSim.Core\RestaurantSim.Core.csproj", "{76FDF7CF-8D13-4276-BD40-F7C40FBEA33B}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "RestaurantSim.Cli", "src\RestaurantSim.Cli\RestaurantSim.Cli.csproj", "{16E8E8DE-EB36-4C07-AF78-4A981E83D700}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "RestaurantSim.Harness", "src\RestaurantSim.Harness\RestaurantSim.Harness.csproj", "{C3EC1423-7B14-4105-9F57-FAFD6DC29724}" +EndProject +Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{F5189331-BA8E-459C-AFE2-96DFBEF12582}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "RestaurantSim.Core.Tests", "tests\RestaurantSim.Core.Tests\RestaurantSim.Core.Tests.csproj", "{85D535DB-22A5-4739-9CFD-F39EA4449ED7}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "RestaurantSim.Determinism.Tests", "tests\RestaurantSim.Determinism.Tests\RestaurantSim.Determinism.Tests.csproj", "{286BD256-4FE4-4E75-B075-A9E5916827BF}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "RestaurantSim.Scenario.Tests", "tests\RestaurantSim.Scenario.Tests\RestaurantSim.Scenario.Tests.csproj", "{DD4ECF63-0452-420F-A364-B8355014B761}" +EndProject +Global + GlobalSection(SolutionConfigurationPlatforms) = preSolution + Debug|Any CPU = Debug|Any CPU + Release|Any CPU = Release|Any CPU + EndGlobalSection + GlobalSection(SolutionProperties) = preSolution + HideSolutionNode = FALSE + EndGlobalSection + GlobalSection(ProjectConfigurationPlatforms) = postSolution + {76FDF7CF-8D13-4276-BD40-F7C40FBEA33B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {76FDF7CF-8D13-4276-BD40-F7C40FBEA33B}.Debug|Any CPU.Build.0 = Debug|Any CPU + {76FDF7CF-8D13-4276-BD40-F7C40FBEA33B}.Release|Any CPU.ActiveCfg = Release|Any CPU + {76FDF7CF-8D13-4276-BD40-F7C40FBEA33B}.Release|Any CPU.Build.0 = Release|Any CPU + {16E8E8DE-EB36-4C07-AF78-4A981E83D700}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {16E8E8DE-EB36-4C07-AF78-4A981E83D700}.Debug|Any CPU.Build.0 = Debug|Any CPU + {16E8E8DE-EB36-4C07-AF78-4A981E83D700}.Release|Any CPU.ActiveCfg = Release|Any CPU + {16E8E8DE-EB36-4C07-AF78-4A981E83D700}.Release|Any CPU.Build.0 = Release|Any CPU + {C3EC1423-7B14-4105-9F57-FAFD6DC29724}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {C3EC1423-7B14-4105-9F57-FAFD6DC29724}.Debug|Any CPU.Build.0 = Debug|Any CPU + {C3EC1423-7B14-4105-9F57-FAFD6DC29724}.Release|Any CPU.ActiveCfg = Release|Any CPU + {C3EC1423-7B14-4105-9F57-FAFD6DC29724}.Release|Any CPU.Build.0 = Release|Any CPU + {85D535DB-22A5-4739-9CFD-F39EA4449ED7}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {85D535DB-22A5-4739-9CFD-F39EA4449ED7}.Debug|Any CPU.Build.0 = Debug|Any CPU + {85D535DB-22A5-4739-9CFD-F39EA4449ED7}.Release|Any CPU.ActiveCfg = Release|Any CPU + {85D535DB-22A5-4739-9CFD-F39EA4449ED7}.Release|Any CPU.Build.0 = Release|Any CPU + {286BD256-4FE4-4E75-B075-A9E5916827BF}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {286BD256-4FE4-4E75-B075-A9E5916827BF}.Debug|Any CPU.Build.0 = Debug|Any CPU + {286BD256-4FE4-4E75-B075-A9E5916827BF}.Release|Any CPU.ActiveCfg = Release|Any CPU + {286BD256-4FE4-4E75-B075-A9E5916827BF}.Release|Any CPU.Build.0 = Release|Any CPU + {DD4ECF63-0452-420F-A364-B8355014B761}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {DD4ECF63-0452-420F-A364-B8355014B761}.Debug|Any CPU.Build.0 = Debug|Any CPU + {DD4ECF63-0452-420F-A364-B8355014B761}.Release|Any CPU.ActiveCfg = Release|Any CPU + {DD4ECF63-0452-420F-A364-B8355014B761}.Release|Any CPU.Build.0 = Release|Any CPU + EndGlobalSection + GlobalSection(NestedProjects) = preSolution + {76FDF7CF-8D13-4276-BD40-F7C40FBEA33B} = {7A4E9898-B55F-4C7F-A8B5-E3F3AAF7D1FB} + {16E8E8DE-EB36-4C07-AF78-4A981E83D700} = {7A4E9898-B55F-4C7F-A8B5-E3F3AAF7D1FB} + {C3EC1423-7B14-4105-9F57-FAFD6DC29724} = {7A4E9898-B55F-4C7F-A8B5-E3F3AAF7D1FB} + {85D535DB-22A5-4739-9CFD-F39EA4449ED7} = {F5189331-BA8E-459C-AFE2-96DFBEF12582} + {286BD256-4FE4-4E75-B075-A9E5916827BF} = {F5189331-BA8E-459C-AFE2-96DFBEF12582} + {DD4ECF63-0452-420F-A364-B8355014B761} = {F5189331-BA8E-459C-AFE2-96DFBEF12582} + EndGlobalSection +EndGlobal diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md new file mode 100644 index 0000000..ec1a922 --- /dev/null +++ b/docs/CURRENT-STATE.md @@ -0,0 +1,48 @@ +# Current State + +**As of:** 2026-07-28 · **Branch:** `foundation/m0-headless-service-lab` (delivered as a PR into `main`) +**Milestone:** M0 — Headless Service Lab. **Most recent gate decision:** none yet (awaiting owner review). + +## What is complete +- Repository initialized; full structure; license; determinism/architecture/design/product/risk/commercial/ + playtest/asset docs; the original v1 charter preserved immutably in `docs/archive/2026-07-28/`. +- **M0 simulation core** (`src/RestaurantSim.Core`): deterministic, integer-only, seeded streams, no wall + clock — service simulator, demand/choice model, quality/satisfaction, economy, causal autopsy, forecast, + FNV-1a state checksum. Fixtures: 3 segments, 12 recipes, 8 employees, 3 market scenarios, 9 named strategies. +- **CLI** (`src/RestaurantSim.Cli`): inspect → plan → forecast → commit → autopsy → revise → run again. +- **Harness** (`src/RestaurantSim.Harness`): distribution/dominance/determinism analysis → `reports/`. +- **Tests:** 74 passing across 3 projects (invariants, determinism, golden scenarios, balance properties). +- **Evidence** (200 seeds/cell) committed under `reports/`. + +## Latest test status +`dotnet test` → **74 passed, 0 failed** (Core 36, Determinism 30, Scenario 8). Re-run to confirm. + +## Latest determinism status +Harness determinism check: **PASS** for the sampled matrix (same seed ⇒ identical checksum). Golden +checksums locked in `tests/RestaurantSim.Scenario.Tests`. Cross-OS CI comparison is an OPEN item. + +## Balance status +Distinct winning strategies across 3 markets: **2 of 3** → no single dominant strategy. Poor strategies all +post negative medians and are legibly diagnosed. See `reports/balance/distribution.md` and +`docs/design/M0-BALANCE-HYPOTHESES.md`. + +## What is partially complete / not started +- **Human playtests:** NOT gathered. The Builder cannot fabricate them. Plan/script/consent are ready in + `docs/playtests/`. This is the owners' step; the fun/comprehension/replay half of the M0 gate is pending. +- **Cross-OS determinism CI:** not wired (local double-run + golden checksums are active). +- Everything M1+ (spatial, persistence, identity, delegation, city, campaign, content, presentation): **not + started, not authorized.** + +## Known defects / caveats +- None blocking. Known limitation (by design, not a defect): in a single service with no repeat visits, + throughput dominates profit and quality has limited economic teeth — see DECISION-LOG D-012. This is a + finding for M1, not a bug. + +## Scope audit +Clean. No item from the M0 hard non-goals list was built (no graphics/engine/pathfinding/inventory/ +suppliers/recipe-editor/competitors/campaign/managers/save-system/assets). Asset packages remain quarantined +and uncommitted. + +## How to run +See `README.md`. `dotnet test` for tests; `dotnet run --project src/RestaurantSim.Harness` for evidence; +`dotnet run --project src/RestaurantSim.Cli` for the playable loop. diff --git a/docs/DECISION-LOG.md b/docs/DECISION-LOG.md new file mode 100644 index 0000000..330dd34 --- /dev/null +++ b/docs/DECISION-LOG.md @@ -0,0 +1,62 @@ +# Decision Log + +Every important decision: date, decision, status (provisional | locked), rationale, alternatives, +consequences, owner, and conditions to revisit. Newest first. + +--- + +### 2026-07-28 · D-012 · Balance signal: throughput dominates a single service (honest M0 finding) +- **Status:** locked (as a finding, not a change) +- **Decision:** Record that, in M0's single-service scope, covers-served is the dominant profit lever and + quality/satisfaction have limited economic teeth (only via comped failures). Do NOT fix this by building + repeat-visit/reputation systems (M1/M2 scope). +- **Rationale:** Faithful to M0 non-goals; the gap is itself a useful design signal for M1. +- **Owner:** Builder → owners. **Revisit:** at M1 design (repeat visits/reviews give quality teeth). + +### 2026-07-28 · D-011 · Failed dishes are comped (no revenue, ingredient still paid) +- **Status:** locked · **Owner:** Builder +- **Decision:** A botched dish earns no revenue but consumes ingredients, giving execution economic weight + in a single service. **Alternatives:** remake loops (unbounded), pay-in-full (no teeth). **Revisit:** if + M1 repeat-visit feedback makes this redundant. + +### 2026-07-28 · D-010 · Kitchen concurrency = 4 dishes per cook (`Tuning.SlotsPerCook`) +- **Status:** provisional · **Decision:** one cook oversees several covers at once (active-vs-passive cook + time abstraction) so throughput matches demand. **Revisit:** replace with an explicit active/passive + time model at M1 if needed. + +### 2026-07-28 · D-009 · M0 fixtures: 3 segments, 12 recipes, 8 employees, 3 market scenarios +- **Status:** locked for M0 · **Rationale:** smallest set that produces context-dependent, non-dominant + strategies (proven in `reports/balance/distribution.md`). **Revisit:** M0.5 calibration. + +### 2026-07-28 · D-008 · Numeric determinism: integer cents, basis points, milli, fixed-point; no float +- **Status:** locked · **Owner:** Builder · **Rationale:** floating point is the top threat to + cross-machine reproducibility (accepted review finding). Enforced by a reflection test. See ADR-002. + +### 2026-07-28 · D-007 · Seeded, named, per-entity RNG streams (SplitMix64); never System.Random +- **Status:** locked · See ADR-003. **Consequence:** adding a roll to one entity cannot perturb another. + +### 2026-07-28 · D-006 · Authoritative engine-agnostic C# core; presentation is a read model +- **Status:** locked · See ADR-001/ADR-004. **Consequence:** the renderer owns no truth; the sim runs + headless. **Revisit:** never for M0; the boundary is the whole point. + +### 2026-07-28 · D-005 · First-commercial cut = through M3 +- **Status:** provisional (planning boundary) · **Owner:** owners · See FIRST-COMMERCIAL-CUT. **Revisit:** + if M0–M3 evidence changes the viable scope. + +### 2026-07-28 · D-004 · Fantasy continuity: flagship stays hand-authored; chains are delegated +- **Status:** provisional (assumption with a deferred proof gate) · See FANTASY-CONTINUITY. + +### 2026-07-28 · D-003 · Launch model (premium vs Early Access) left OPEN pending platform answers +- **Status:** open · **Owner:** owners · **Rationale:** premium was locked before the platform question in + v1; de-locked here. See EARLY-ACCESS-DECISION. **Revisit:** before the store page goes up. + +### 2026-07-28 · D-002 · Owner-supplied asset packages quarantined; none in M0; none committed +- **Status:** locked · See ASSET-QUARANTINE / ASSET-PROVENANCE. Downtown MegaKit is CC0 (cleared for later); + the rest are unclear/legacy → do not use. + +### 2026-07-28 · D-001 · Ship on a branch as a PR the owners review/merge; never direct to main +- **Status:** locked · **Owner:** owners · **Rationale:** independent review before M1; the PR is the review + surface. The Builder does not declare M1 ready. + +### 2026-07-28 · D-000 · Design spine preserved: "the menu is the strategy"; core fantasy unchanged +- **Status:** locked · The v1 charter is archived immutably; the active plan is a change record over it. diff --git a/docs/MASTER-PLAN.md b/docs/MASTER-PLAN.md new file mode 100644 index 0000000..67b8cf6 --- /dev/null +++ b/docs/MASTER-PLAN.md @@ -0,0 +1,49 @@ +# Master Plan (active) + +**Status:** Living. This is the active plan. The original reviewed charter is preserved **immutably** at +[`archive/2026-07-28/restaurant-empire-successor-master-plan-v1.md`](archive/2026-07-28/restaurant-empire-successor-master-plan-v1.md) +and is not edited. This document keeps the design spine, records the accepted review findings and where each +is now addressed, and points to the detail docs. Codename **"Mise"** (working; not the final title). + +## The spine (unchanged) +- **Core fantasy:** *I build one distinctive restaurant whose menu, people, layout, and service work as a + coherent machine, and then turn that hard-won operating model into a culinary empire.* +- **Design spine:** **the menu is the strategy.** +- **M0 product question:** *Can menu, pricing, staffing, and capacity decisions create multiple + understandable and viable restaurant strategies, with visible consequences that make players want to + revise their plan and run another service?* +- Governance, pillars/anti-pillars, six-test standard, milestone gates, and system contracts all carry over + from the archived v1. See [`design/DESIGN-PRINCIPLES.md`](design/DESIGN-PRINCIPLES.md). + +## Accepted review findings and where each is now addressed +The v1 plan was excellent on systems and thin on commercial reality, team reality, and a few architecture +specifics. Each accepted finding is now a document: + +| Finding (from the accepted review) | Addressed in | +|---|---| +| No go-to-market / wishlist / launch funnel | [`product/GO-TO-MARKET.md`](product/GO-TO-MARKET.md) | +| "Premium" asserted, never sized (price, audience, break-even) | [`product/COMMERCIAL-HYPOTHESIS.md`](product/COMMERCIAL-HYPOTHESIS.md), [`commercial/PRICE-AND-BREAK-EVEN-HYPOTHESIS.md`](commercial/PRICE-AND-BREAK-EVEN-HYPOTHESIS.md), [`commercial/COMPARABLES.md`](commercial/COMPARABLES.md) | +| Premium-vs-Early-Access never weighed | [`commercial/EARLY-ACCESS-DECISION.md`](commercial/EARLY-ACCESS-DECISION.md) | +| No total effort estimate; no MVP cut line | [`product/EFFORT-AND-SCOPE.md`](product/EFFORT-AND-SCOPE.md), [`product/FIRST-COMMERCIAL-CUT.md`](product/FIRST-COMMERCIAL-CUT.md) | +| Risk register had zero team/human/commercial risk | [`risks/RISK-REGISTER.md`](risks/RISK-REGISTER.md), [`risks/HUMAN-RISK-PLAN.md`](risks/HUMAN-RISK-PLAN.md) | +| M0 tested comprehension/replay but not FUN | [`design/M0-PROTOTYPE-CONTRACT.md`](design/M0-PROTOTYPE-CONTRACT.md) §2/§9, [`playtests/M0-TEST-SCRIPT.md`](playtests/M0-TEST-SCRIPT.md) | +| The two fantasies compete; resolution asserted not gated | [`product/FANTASY-CONTINUITY.md`](product/FANTASY-CONTINUITY.md) | +| Determinism asserted but numeric strategy unspecified | [`architecture/DETERMINISM-CONTRACT.md`](architecture/DETERMINISM-CONTRACT.md), [`architecture/ADR-002-NUMERIC-DETERMINISM.md`](architecture/ADR-002-NUMERIC-DETERMINISM.md) | +| "Five uncoached players" never sourced | [`playtests/PLAYTEST-SOURCING.md`](playtests/PLAYTEST-SOURCING.md), [`playtests/CONSENT-AND-DATA.md`](playtests/CONSENT-AND-DATA.md) | +| Edge gaps: audio, controller/Deck, telemetry consent, accessibility | [`design/DEFERRED-FEATURES.md`](design/DEFERRED-FEATURES.md), risk register, consent doc | + +## Milestones (from v1 §14, unchanged in intent) +`M-1 Product Lock → M0 Headless Service Lab → M0.5 Calibration → M1 Spatial gray-box → M2 Persistent → +M3 Identity & progression → M4 Delegation & 2nd location → M5 Living city → M6 Campaign → M7 Production +content & presentation → M8 Release readiness.` +- **First-commercial cut = through M3.** M4+ are post-release/v1.x candidates (see FIRST-COMMERCIAL-CUT). +- **Only M0 is authorized to build now.** M0 status: built; see [`CURRENT-STATE.md`](CURRENT-STATE.md). + +## What is deliberately NOT built +The v1 non-goals and defer lists stand. See [`design/DEFERRED-FEATURES.md`](design/DEFERRED-FEATURES.md). +A deferred idea written down is a decision anyone can find; a silently-built one is a gap nobody can find. + +## Source of truth +This repository is the permanent source of truth. Decisions live in +[`DECISION-LOG.md`](DECISION-LOG.md); the current state and the single next action live in +[`CURRENT-STATE.md`](CURRENT-STATE.md) and [`NEXT-ACTION.md`](NEXT-ACTION.md). diff --git a/docs/NEXT-ACTION.md b/docs/NEXT-ACTION.md new file mode 100644 index 0000000..08719e6 --- /dev/null +++ b/docs/NEXT-ACTION.md @@ -0,0 +1,24 @@ +# Next Action + +> **FIRST: re-confirm the repository's actual current state before trusting this document.** +> Run `git status`, `git log --oneline -8`, `dotnet test`, and +> `dotnet run -c Release --project src/RestaurantSim.Harness -- --seeds 200 --out /tmp/verify`. +> Confirm 74 tests pass, determinism reports PASS, and distinct winners = 2/3. Any commit hash or number in +> a doc is a timestamp, not a contract — verify against reality first. + +## The single next authorized action +**Owner + independent reviewer close the M0 gate.** Specifically: + +1. **Independent reviewer** (not the Builder): clone fresh, run the tests and the harness with their own + tooling, try to break determinism, and confirm M0 stayed in scope (nothing from the non-goals list, no + asset files committed). Use `docs/AI-AGENT-WORKFLOW`-style separation: the builder does not grade its own + homework. +2. **Owners (Howard & Aaron)** run the **human playtest** using `docs/playtests/M0-TEST-SCRIPT.md` with at + least five uncoached testers sourced per `docs/playtests/PLAYTEST-SOURCING.md` (consent per + `docs/playtests/CONSENT-AND-DATA.md`). Record results in `docs/playtests/reports/`. +3. **Owners decide the gate verdict** (Fail / Conditional-Pass / Pass-with-notes / Pass) and the action + (Continue / Defer / Rewrite / Abandon), and record it in `docs/DECISION-LOG.md` and `CURRENT-STATE.md`. + +## Do NOT +- Do not begin M1, add a renderer/engine, integrate the asset packs, or expand the simulation while awaiting + the decision. The Builder is not authorized to declare the project ready for M1. diff --git a/docs/architecture/ADR-001-AUTHORITATIVE-SIMULATION.md b/docs/architecture/ADR-001-AUTHORITATIVE-SIMULATION.md new file mode 100644 index 0000000..ac62639 --- /dev/null +++ b/docs/architecture/ADR-001-AUTHORITATIVE-SIMULATION.md @@ -0,0 +1,46 @@ +# ADR-001: The simulation core is authoritative and engine-agnostic + +Purpose: record the decision that one pure simulation core owns all game truth, and that every presentation surface is a read model over its output. + +**Status:** Accepted. Embodied by `RestaurantSim.Core`, `ServiceResult`, and `TextReport` in the M0 build. + +--- + +## Context + +The master plan's anti-pillars explicitly reject "UI screens that independently recalculate engine truth," and its six-test standard requires that every mechanic have exactly one authoritative system that calculates the result (test 3, "Truth"). A management sim that shows the player a number, then lets a view recompute a slightly different number, has two truths and no way to say which is real. That defeats the whole premise — the player is supposed to reason about consequences, which is only possible if the consequences are stable and singular. + +M0's product question ("do menu/pricing/staffing/capacity decisions create understandable, viable strategies with visible consequences?") can only be answered honestly if the consequences the player reacts to are the consequences the simulation actually produced — not a re-derivation in a report or UI. + +The project also intends to add a rendering engine later (Godot is named in the determinism contract as an M1+ concern). If truth lived partly in the renderer, the headless harness and the future engine build could diverge, and cross-version determinism would be impossible. + +## Decision + +**The simulation core (`RestaurantSim.Core`) is the single owner of authoritative state, and it is engine-agnostic.** + +Concretely, as built: + +1. `ServiceSimulator.Run(world, scenario, plan, seed)` is a pure function. It produces one `ServiceResult` that contains every authoritative number for a service. Nothing outside the simulator computes a service outcome. +2. `ServiceResult` is an immutable record. Its doc comment states the rule directly: *"Every number here is derived from authoritative simulation state, not recomputed by a view."* +3. `RestaurantSim.Core` has **zero project references** — no renderer, no engine, no I/O framework. It cannot depend on presentation even by accident. The CLI and harness depend on Core, never the reverse. +4. Presentation is a read model. `TextReport` (whose doc comment reads *"This is a read-model view: it only reads ServiceResult / ForecastSnapshot and computes no new simulation truth"*) formats — it does not calculate. It renders the ledger, the funnel, the breakdowns, and the causal summary that the simulator already computed. See `ADR-004-PRESENTATION-BOUNDARY.md` for the presentation boundary in detail. + +The `M0-SYSTEM-CONTRACTS.md` invariant for `ServiceResult` states the same rule from the object's side: *"every reported number is derived from authoritative state, not recomputed by a separate formula in the view."* + +## Consequences + +**Positive** + +- One truth. The player, the CLI autopsy, the harness distribution report, and any future UI all read the same `ServiceResult`. There is no "which number is right?" ambiguity. +- Testability. Because the core is pure and self-contained, the entire determinism and balance evidence set (checksums, golden scenarios, distribution matrix) runs headless with no engine present. +- Portability. The same engine runs in the CLI REPL, in the batch harness, and — later — under a rendering engine, producing byte-identical results. This is the precondition for the save/replay and cross-OS determinism goals. +- Clean scope boundary. The repository boundary in `M0-PROTOTYPE-CONTRACT.md` §11 ("The core has zero dependency on any renderer") is enforceable and enforced by the project graph. + +**Negative / costs** + +- The core cannot take shortcuts through a UI. Anything the player needs to see must be a real field on `ServiceResult` (e.g. `BottleneckCause`, `MostProfitableRecipeId`), computed inside the sim. This is more work up front than letting a view "just compute it," and it is deliberate. +- Views are strictly downstream. A report can only show what the simulator chose to expose; adding a new reported quantity means adding it to the authoritative result, not to the formatter. + +**Neutral** + +- This ADR is about ownership of truth, not about numeric representation (see `ADR-002`), randomness (`ADR-003`), or the read-only presentation contract (`ADR-004`), which together make the authoritative core actually deterministic and actually isolated. diff --git a/docs/architecture/ADR-002-NUMERIC-DETERMINISM.md b/docs/architecture/ADR-002-NUMERIC-DETERMINISM.md new file mode 100644 index 0000000..945825f --- /dev/null +++ b/docs/architecture/ADR-002-NUMERIC-DETERMINISM.md @@ -0,0 +1,51 @@ +# ADR-002: Integer / fixed-point numerics only — no float, double, or decimal in authoritative state + +Purpose: record the decision to represent all authoritative quantities as integers (money as minor units, rates as basis points, bounded quantities on a 0..1000 "milli" scale, fractions via fixed-point) and to ban binary/`decimal` floating point from the simulation core. + +**Status:** Accepted. Enforced by a reflection test in `RestaurantSim.Determinism.Tests` and implemented in `Numerics.cs`. + +--- + +## Context + +`DETERMINISM-CONTRACT.md` opens by naming the single biggest threat to cross-machine, cross-version determinism: **binary floating point.** `float`/`double` results can differ across CPUs, compilers, and optimization settings (fused multiply-add, x87 vs SSE, reordering), so a sim that decides outcomes with them cannot promise "same seed reproduces the same state." `decimal` is deterministic but slow and, worse, silently invites fractional money and accidental rounding drift. + +M0 promises exactly that reproducibility — checksums must match on any machine — so the authoritative core must avoid all three. The contract's §1.5 lists the fields this applies to: money, ingredient amounts, preparation progress, satisfaction, quality, skill, demand probability, time, inventory, utilization, productivity, "or any value that feeds a comparison, a branch, or an RNG draw." + +## Decision + +**All authoritative quantities are integers, with documented, explicit rounding. No `float`, `double`, or `decimal` may appear in any authoritative field of `RestaurantSim.Core`.** + +The representations, as built in `Numerics.cs` and used throughout the core: + +1. **Money = integer minor units.** The `Money` struct wraps a single `long Cents`. Arithmetic (`+ - *`) and comparisons operate directly on cents; `ToString()` formats to dollars for display only. There is no floating money anywhere. `Money.ApplyBp(int bp)` applies a basis-point rate with explicit integer rounding. +2. **Rates / percentages = basis points (`int`).** `FixedMath.Bp = 10000` (100% = 10,000 bp). Conversion, price-fit, utilization, confidence bands, complexity load, and every ratio in the sim are basis-point integers. +3. **Bounded quality-like quantities = "milli" scale 0..1000 (`int`).** `FixedMath.Scale = 1000`. Quality, satisfaction, appeal, skill, station fit, novelty, and expectations all live on 0..1000. `FixedMath.Milli(int)` clamps into that range. +4. **Fixed-point where a fraction is unavoidable.** `FixedMath.MulDivRound(long value, long num, long den)` computes `value * num / den` with **round-half-away-from-zero** and a **128-bit (`Int128`) intermediate** so the product cannot overflow before the divide. Every scaled multiply in the core goes through this one function, so rounding is defined in exactly one place. (The RNG's Lemire bound uses `UInt128` for the same overflow-safe reason.) + +Floats are permitted **only** in a future presentation/rendering layer (animation, camera, particles) where they can never determine a simulation outcome — see `DETERMINISM-CONTRACT.md` §1.5 and `ADR-004`. + +## Enforcement + +This is not a convention that relies on discipline; it is a build gate: + +- **Reflection test** (`NumericStrategyTests.No_authoritative_field_in_Core_uses_float_double_or_decimal`): loads the `RestaurantSim.Core` assembly, walks every field of every type, and fails if any field's type is `System.Single`, `System.Double`, or `System.Decimal`. +- **Rounding tests** (`NumericsTests`): assert `ApplyBp` rounds half away from zero (`75.25%` of `1000` → `753`, and the negative case `−1000 → −500`) and that `MulDivRound` handles values beyond `int` range without overflow (`9,000,000,000 × 5000 / 10000 = 4,500,000,000`) via the 128-bit intermediate. +- **Economy reconciliation tests** confirm the integer ledger closes exactly: `contribution == revenue − ingredient − labor − overhead` and per-dish revenue/ingredient sum to the authoritative totals, in cents, with no residual. + +## Consequences + +**Positive** + +- Cross-machine determinism is achievable and checkable. With no binary floats deciding outcomes, the FNV-1a checksum is stable across CPUs and OSes. +- Money is exact. There is no fractional-cent drift, ever; the ledger reconciles to the cent. +- Rounding is centralized and documented. `MulDivRound` is the single rounding authority, so behaviour cannot silently vary between call sites. + +**Negative / costs** + +- Every fractional relationship must be re-expressed as a scaled integer with a chosen denominator (bp or milli), which is more verbose than writing `0.75`. Author intent has to be explicit about scale. +- The author must think about rounding and overflow at each scaled multiply. The mitigation is that they don't have to think hard — they call `MulDivRound`, which already handles both. + +**Neutral** + +- This decision constrains *representation*; it does not by itself make the sim deterministic. It works together with the seeded, named RNG streams (`ADR-003`) and the fixed integer timestep and system order (see `ARCHITECTURE-OVERVIEW.md` §4). diff --git a/docs/architecture/ADR-003-RNG-STREAMS.md b/docs/architecture/ADR-003-RNG-STREAMS.md new file mode 100644 index 0000000..daeb2ed --- /dev/null +++ b/docs/architecture/ADR-003-RNG-STREAMS.md @@ -0,0 +1,57 @@ +# ADR-003: SplitMix64 with named, per-entity RNG streams + +Purpose: record the decision to derive all randomness from a single deterministic PRNG (SplitMix64) organized into named, per-entity streams, so that adding a random roll to one entity cannot perturb any other entity or stream, and `System.Random` is never used. + +**Status:** Accepted. Implemented in `Rng.cs` and enforced by unit tests in `RestaurantSim.Core.Tests` and a source-scan test in `RestaurantSim.Determinism.Tests`. + +--- + +## Context + +`DETERMINISM-CONTRACT.md` §3 states two requirements that ordinary RNG usage violates: + +1. **No platform RNG.** `System.Random` is not guaranteed stable across .NET versions or platforms, so it cannot back a "same seed reproduces the same state" promise. +2. **Position-independence across entities.** If randomness is one shared sequence, the *number of draws* an earlier entity happens to take shifts every later entity's rolls. Then adding a new random roll anywhere — a design change during development — silently changes unrelated outcomes and breaks every locked checksum for reasons that have nothing to do with the change. The contract's exact requirement: *"adding a new random roll must not silently change unrelated RNG sequences."* + +A management sim under active development needs to add and remove rolls freely (a new mistake check, a new jitter) without invalidating the determinism guarantees for parts of the sim it didn't touch. + +## Decision + +**Use one deterministic PRNG — SplitMix64 — and organize all randomness into named streams, each of which derives an independent sub-generator per entity key. Never use `System.Random`.** + +As built in `Rng.cs`: + +1. **The PRNG is `SplitMix64`** — a portable, integer-only, well-known generator. It exposes `NextU64`, `NextInt(boundExclusive)` (Lemire multiply-high with a `UInt128` intermediate, so it is unbiased and overflow-safe), `NextRange(lo, hi)`, `Chance(num, den)`, and `Jitter(range)`. All integer, all deterministic. +2. **Streams are named.** `enum RngStream { Arrivals, Party, Choice, Execution, Incident }` — the five M0 domains. (The contract reserves `Reviews`, `MarketEvents`, `Competitors` for later; they are deliberately not present yet.) Each stream name is hashed once at type-init with FNV-1a-64 into a per-stream salt. +3. **Randomness is per-entity, not a shared sequence.** `RngStreams.For(RngStream stream, long entityKey)` returns a fresh `SplitMix64` seeded by mixing the root seed, the stream salt, and the entity key: + + ``` + For(stream, key) = SplitMix64( Mix( Mix(rootSeed, streamSalt[stream]), key ) ) + ``` + + The entity key is the party id, the dish id, or the minute — whatever makes the roll attributable. Because each `(stream, key)` gets its own generator, the number of draws taken for one key cannot influence any other key. Every random decision is traceable to `(rootSeed, streamName, entityKey, drawIndex)`. + +The M0 usage (see `ARCHITECTURE-OVERVIEW.md` §5): `Arrivals` keyed by minute (arrival counts, door acceptance); `Party` keyed by party id (segment, size, budget/patience jitter); `Choice` keyed by party id (per-cover dish selection); `Execution` keyed by dish id (quality jitter); `Incident` keyed by dish id (mistake/failure). + +## Enforcement + +- **Stream-isolation unit test** (`RngIsolationTests.Entity_streams_are_independent_...`): captures party 1's first three `NextU64` values, then consumes 50 draws from party 2 and 50 from the `Arrivals` stream, then re-derives party 1 and asserts its sequence is **identical**. This is the direct proof that adding rolls to one entity cannot shift another. +- **Distinctness unit test** (`Different_streams_and_keys_produce_different_sequences`): asserts different streams and different keys produce different first draws (the streams really are separated, not accidentally aliased). +- **Source-scan test** (`CoreSourceScanTests.Core_does_not_read_the_wall_clock_or_use_system_random`): scans all `RestaurantSim.Core` `.cs` files (with comments and string literals stripped so documentation mentioning the banned APIs doesn't trip it) and fails if `System.Random` / `new Random` appears in executable code. + +## Consequences + +**Positive** + +- Rolls can be added or removed during development without perturbing unrelated entities — the property that lets the golden checksums stay meaningful as the sim evolves. +- Every random outcome is attributable to a named stream and a specific entity, which supports the "causal, legible" reporting goal (a failure is traceable, not a black box). +- Fully portable determinism: the generator and all mixing are integer-only, so seeds reproduce across machines. + +**Negative / costs** + +- Deriving a sub-generator per `(stream, key)` is slightly more work than pulling from one shared sequence, and the author must pick a stable, meaningful entity key for each roll. Choosing a bad key (e.g. a loop index that isn't stable) would undermine attribution — so the key choice is a real design decision, not an afterthought. +- Correlations that a single shared stream would give "for free" must be modelled explicitly if wanted. + +**Neutral** + +- This ADR governs randomness. It relies on the integer numerics of `ADR-002` (the mixing and bounding are integer/`UInt128`) and supports the authoritative-core decision of `ADR-001`. diff --git a/docs/architecture/ADR-004-PRESENTATION-BOUNDARY.md b/docs/architecture/ADR-004-PRESENTATION-BOUNDARY.md new file mode 100644 index 0000000..0ded21c --- /dev/null +++ b/docs/architecture/ADR-004-PRESENTATION-BOUNDARY.md @@ -0,0 +1,46 @@ +# ADR-004: Presentation reads immutable results only and computes no simulation truth + +Purpose: record the decision that every presentation surface (the CLI text today, a rendering engine later) reads only immutable `ServiceResult` / `ForecastSnapshot` values and derives no simulation outcome of its own, and that forecasts are immutable snapshots never recomputed with post-service information. + +**Status:** Accepted. Embodied by `TextReport`, `ForecastSnapshot`, and `Forecaster` in the M0 build. + +--- + +## Context + +`ADR-001` establishes that the simulation core owns all truth. This ADR fixes the other side of that boundary: what presentation is *allowed to do*. Two failure modes must be ruled out. + +1. **A view that recalculates.** The master plan's anti-pillars reject "UI screens that independently recalculate engine truth." If a report re-derives contribution, or a UI recomputes a satisfaction score from raw dish data, the displayed number can drift from the authoritative one — two truths again. `M0-SYSTEM-CONTRACTS.md` makes this an invariant of `ServiceResult`: *"every reported number is derived from authoritative state, not recomputed by a separate formula in the view."* + +2. **A forecast contaminated by hindsight.** A forecast is only meaningful as a *prediction* if it is locked before the service and never touched afterward. If it were recomputed with post-service knowledge (or with today's formulas after the formulas changed), the "forecast vs actual" gap — which is the whole point, it teaches the player where their plan was wrong — would be fake. `M0-SYSTEM-CONTRACTS.md` gives the Forecast object the invariant: *"once results exist, the stored forecast is byte-identical to what was shown at commit time."* + +## Decision + +**Presentation reads immutable authoritative values and computes no simulation truth. The forecast is an immutable pre-commit snapshot that is never recomputed with post-service information.** + +As built: + +1. **`TextReport` is a pure formatter.** Its doc comment: *"This is a read-model view: it only reads ServiceResult / ForecastSnapshot and computes no new simulation truth."* Its three methods — `PlanSummary`, `Forecast`, `Autopsy` — take already-computed records and render them. The autopsy prints fields the simulator produced (the funnel, the integer-cents ledger, per-dish/segment/station breakdowns, the `BottleneckCause`, most/least-useful dishes, the checksum). It does no arithmetic that produces a simulation outcome; the only computation it does is display formatting (e.g. `Pct(bp)` divides basis points by 100 for the label, and it subtracts two already-authoritative contribution figures to show the forecast-vs-actual *diff*). The CLI (`RestaurantSim.Cli`) routes **all** player-facing output through `TextReport`; it never formats a result itself. + +2. **`ServiceResult` and `ForecastSnapshot` are immutable records.** They are C# `record` types passed by reference to views; a view cannot mutate them, and there is nothing to mutate — they are the finished truth. + +3. **The forecast is computed once, before commit, from pre-commit information only.** `Forecaster.Compute(world, scenario, plan)` uses only the world fixtures, the market scenario, and the committed plan — no service results, no RNG outcomes. Its doc comment states it is *"computed from pre-commit information only ... it is NEVER recomputed with post-service knowledge"* and that it is *"an analytic approximation, so forecast-vs-actual gaps are expected and informative."* The live simulator and the forecaster share the same `DemandModel` and `Tuning` constants precisely so the forecast is built from the same assumptions the service will use — the gap is due to queue nonlinearity and luck, not two unrelated formulas. + +4. **The forecast does not move when the service runs.** The immutability test (`ForecastTests.Forecast_is_computed_from_pre_service_info_and_is_stable_across_a_run`) computes the forecast, runs the service, computes the forecast again, and asserts the expected covers / contribution / revenue are unchanged — running the service cannot change what the forecast says. + +## Consequences + +**Positive** + +- No divergent truths. The player, the autopsy, and any future UI show exactly the simulator's numbers. +- Honest forecasting. The forecast-vs-actual comparison in the autopsy is a real prediction error, which is what makes it instructive ("you expected 90 covers, the kitchen delivered 61 — here's the bottleneck"). +- The presentation layer is swappable. Because a view only reads immutable results, replacing the CLI with a rendering engine changes nothing about the truth; it just renders it differently. This is the presentation half of the portability that `ADR-001` set up. + +**Negative / costs** + +- Anything the player needs to see must already be a field of `ServiceResult` or `ForecastSnapshot`. A view cannot "just compute" a missing quantity; the quantity has to be added to the authoritative result first. (This is the intended constraint, not a bug.) +- The forecaster duplicates some capacity/complexity logic that the simulator also does. That duplication is deliberate and bounded — the shared pieces live in `DemandModel` and `Tuning` — but the analytic forecast and the discrete-event sim are, and must remain, two different computations, so some drift between them is inherent (and is exactly the signal the player learns from). + +**Neutral** + +- This ADR governs the read side of the boundary; `ADR-001` governs the write side. Together they make the core authoritative and the presentation strictly downstream. diff --git a/docs/architecture/ARCHITECTURE-OVERVIEW.md b/docs/architecture/ARCHITECTURE-OVERVIEW.md new file mode 100644 index 0000000..03cf8a0 --- /dev/null +++ b/docs/architecture/ARCHITECTURE-OVERVIEW.md @@ -0,0 +1,113 @@ +# Architecture Overview — M0 Headless Service Lab + +Purpose: describe the authoritative-state pipeline of the M0 build as it actually exists in code — how a committed plan plus a seed becomes a single authoritative `ServiceResult`, and how everything else (text report, harness) is a pure read of that result. + +**Status:** Describes the built and tested M0 code in `src/RestaurantSim.Core`, `src/RestaurantSim.Cli`, `src/RestaurantSim.Harness`, and the three test projects. This document is descriptive, not aspirational: it names real types and methods. + +--- + +## 1. The pipeline + +M0 has exactly one source of truth per service: the `ServiceResult` produced by the simulator. The flow is one-directional. + +``` +world fixtures (M0World) ┐ +committed plan (ServicePlan) ├──► ServiceSimulator.Run(...) ──► ServiceResult ──► TextReport / Harness +seed (ulong) ┘ (authoritative sim) (read model) (views only) + │ +Forecaster.Compute(...) ──► ForecastSnapshot ─────────────────────────┘ + (pre-commit only) (immutable) shown alongside, never fed back in +``` + +- **Inputs are the whole truth.** `ServiceSimulator.Run(M0World world, MarketScenario scenario, ServicePlan plan, ulong seed, SimOptions? options)` is a pure function of `(world, scenario, plan, seed)`. It reads no wall clock, no `System.Random`, no ambient state, and performs no I/O. +- **The simulator owns all outcomes.** Every number a player sees is a field of `ServiceResult`, computed inside the sim from authoritative state. +- **Renderer owns no truth.** `TextReport` and the harness only *read* an already-computed `ServiceResult` (and `ForecastSnapshot`). They compute no simulation outcome. See `ADR-001-AUTHORITATIVE-SIMULATION.md` and `ADR-004-PRESENTATION-BOUNDARY.md`. + +--- + +## 2. The projects + +| Project | Role | Depends on | +|---|---|---| +| **`RestaurantSim.Core`** | The pure simulation core. No I/O, no `Console`, no renderer, no engine. Contains the numeric primitives, RNG, model, demand/forecast, the simulator, tuning, fixtures (`M0Content`), named strategies (`M0Strategies`), and the read-model formatter (`TextReport`). | nothing (net8.0, zero `ProjectReference`) | +| **`RestaurantSim.Cli`** | The player loop. Interactive REPL (`inspect → plan → forecast → commit → autopsy → revise → run again`) plus a non-interactive `list` / `strategy` mode. All output goes through `TextReport`. | Core | +| **`RestaurantSim.Harness`** | Distribution / balance / determinism evidence generator. Runs every named strategy across every scenario over many seeds, writes Markdown/txt reports under `reports/`, and asserts the balance and determinism properties. | Core | +| **`RestaurantSim.Core.Tests`** | Invariant unit tests: money arithmetic, `MulDivRound` 128-bit path, RNG stream isolation, economy reconciliation, forecast immutability. | Core, xUnit | +| **`RestaurantSim.Determinism.Tests`** | Same-seed checksum reproduction across the full strategy × scenario matrix; the reflection test banning `float`/`double`/`decimal` in Core; the source-scan test banning wall-clock and `System.Random` in Core. | Core, xUnit | +| **`RestaurantSim.Scenario.Tests`** | Golden-checksum scenarios (locked expected checksums) and the balance property tests (no dominant strategy; deliberately-bad strategies never win; premium is not always best). | Core, xUnit | + +The one architectural fact these dependencies encode: **Core references nothing.** That is what lets the same engine run headless in the CLI, batch in the harness, and (later) under a rendering engine, all producing byte-identical results. + +--- + +## 3. Authoritative types + +- **`M0World`** (`Model.cs`) — the immutable fixture set: `SegmentDef[]`, `RecipeDef[]`, `EmployeeDef[]`, `StartingCash`, `FixedOverheadPerService`. Populated by `M0Content.World()`. +- **`MarketScenario`** — a daypart/market context: service length, expected attempted arrivals, arrival-peak position, per-segment mix (bp), mean party size. +- **`ServicePlan`** — the committed command that drives a service: chosen `MenuItem[]` (recipe + price), `Assignments` (employeeId → `Assignment`), `Seats`, and `WalkInAcceptanceBp`. This is the "player's decision" the sim consumes. +- **`ServiceResult`** (`Result.cs`) — the authoritative read model: the demand funnel, the integer-cents ledger, service-quality aggregates, per-dish / per-segment / per-station / per-employee breakdowns, the causal summary (bottleneck cause, most-profitable dish, least-useful dish, highest-pressure station), the covers-weighted `OverallSatisfaction`, a `Checksum`, and an optional sampled `ServiceLog`. +- **`ForecastSnapshot`** (`Result.cs`) — the immutable pre-service forecast (expected covers, expected revenue/contribution, a confidence band, key assumptions). Computed by `Forecaster.Compute` from pre-commit information only; never recomputed with post-service knowledge. + +--- + +## 4. The fixed-timestep service tick + +`ServiceSimulator.Run` advances the world in **fixed one-minute integer steps** — no wall clock, no variable dt, no sub-minute state. It runs for `scenario.ServiceMinutes + TailMinutes` (`TailMinutes = 90`), where the tail lets already-seated parties finish after arrivals stop. The loop terminates early once arrivals have ended and no party is waiting or active. + +Within each minute `t`, the simulator applies its systems in **one documented order**. Iteration over collections that affect authoritative results is done in a stable order (parties in arrival order; assignments ordered by `employeeId` via `OrderBy(kv => kv.Key)`), never in hash/dictionary enumeration order. + +### Exact per-minute system order (as coded in `Run`) + +1. **Arrivals** — only while `t < scenario.ServiceMinutes`. The per-minute arrival intensity comes from `DemandModel.ArrivalCurve` (a triangular curve in milli-parties, scaled by the demand `conversionBp`). The whole part is emitted directly; the fractional part becomes one extra party with probability `frac/1000` via the **`Arrivals`** stream keyed by the minute `t`. Each candidate party is then subjected to the plan's `WalkInAcceptanceBp` door posture (same `Arrivals` sub-generator). Accepted parties are built by `MakeParty` and added to `waiting`. +2. **Seating** — walk the `waiting` list in arrival order. A party whose seat wait exceeds its `PatienceSeat` becomes `WalkedSeat` (lost to capacity). Otherwise, if `seatsFree >= party.Size`, it is seated: seats are decremented, state becomes `Browsing`, and its `BrowseReady` minute is set (`BrowseMin` plus a front-of-house-driven order delay). +3. **Advance active parties** — walk `active` and step each party's state machine: `Browsing → Cooking → Eating → Paid`, with `NoOrder` and `WalkedFood` exits. On `Browsing→` completion, `OrderDishes` runs (weighted dish choice per cover) and enqueues dish tickets to stations; a party that can order nothing becomes `NoOrder`. In `Cooking`, a per-minute service-quality sample is taken, a food-patience walkout (`WalkedFood`) is possible, and delivery happens once all dishes are `Done` (plus an FOH delivery delay), which stamps ticket time and applies holding loss. In `Eating`, once `EatUntil` is reached the party pays for delivered non-failed dishes (revenue accrues) and becomes `Paid`. +4. **Station production** — for each of the 4 stations with crew, map `Slots` (= `crew.Count × Tuning.SlotsPerCook`) round-robin to cooks, pull tickets off the station queue into free slots, and advance each in-progress dish by the cook's effective speed (`SpeedBp × StationFit / 1000`) measured in bp-minutes. When a dish reaches `WorkNeeded`, `FinishDish` computes its quality (skill-vs-difficulty), rolls jitter on the **`Execution`** stream and a mistake on the **`Incident`** stream (unreliability + complexity/2 + station overload), accrues ingredient cost, and frees the slot. Station busy-minutes, slot-minutes, peak queue, and produced count are tracked here for utilization. +5. **FOH sampling** — front-of-house is modelled as a capacity ratio, not a queue. `fohCapacity` is computed once from assigned FOH staff and their `FohSkill`; each minute a `fohRatioBp` (`fohCapacity / active parties`) drives order delay, delivery delay, and the per-minute `ServiceScore` samples accumulated onto each cooking/eating party. (This is the "FOH tasks / service quality" step; there is no separate ticket queue for it.) +6. **Snapshot** — if `SimOptions.CaptureLog` is on, a sampled one-line snapshot (`SnapshotLine`) is appended every 15 minutes and at end-of-service. This is diagnostic output only; it reads state, it does not change it. + +After the loop, any still-unfinished active party at the tail is counted as `WalkedFood`, then `Finalize` derives all aggregates, the causal report (`DiagnoseBottleneck`), the covers-weighted satisfaction, and the checksum. + +> Relationship to `DETERMINISM-CONTRACT.md` §4: that section lists an idealized 9-step tick. The built code collapses several of those into the six phases above — e.g. "release dish tickets" happens inside step 3 (`OrderDishes`), "FOH tasks" and "update satisfaction/walkaways" are folded into steps 3 and 5, and "post minute metrics" is the optional snapshot in step 6. The *ordering guarantees* (arrivals before seating before production, stable id-ordered iteration, integer-only, single-threaded) hold exactly as the contract requires. + +--- + +## 5. Named RNG streams + +Randomness is organized into named, per-entity streams so that adding a roll to one entity can never perturb another. `RngStreams` (`Rng.cs`) is constructed from the root `seed` and derives an independent `SplitMix64` per `(stream, entityKey)`: + +``` +RngStreams.For(RngStream stream, long entityKey) + = SplitMix64( mix64( mix64(rootSeed, streamSalt[stream]), entityKey ) ) +``` + +where `streamSalt` is an FNV-1a-64 hash of the stream name. The five M0 streams and their entity keys: + +| Stream | Keyed by | Used for | +|---|---|---| +| `Arrivals` | minute `t` | arrival count fractional roll; door acceptance | +| `Party` | party id | segment pick, party size, budget/patience jitter | +| `Choice` | party id | per-cover weighted dish selection, starter/dessert rolls | +| `Execution` | dish id | quality jitter | +| `Incident` | dish id | mistake/failure roll | + +Because each generator is re-derived from `(root, stream, key)`, the number of draws taken by one party or dish does not shift any other party or dish. This is proven by the isolation test in `RestaurantSim.Core.Tests` (party 1's sequence is unchanged after party 2 and the arrivals stream consume 50 draws each). See `ADR-003-RNG-STREAMS.md`. + +--- + +## 6. The checksum + +`Finalize` calls `ComputeChecksum`, a 64-bit FNV-1a hash folded over all authoritative integer fields in a canonical, id-ordered serialization: the ledger (`revenue`, `ingredient`, `labor`, `overhead`, `contribution` in cents), the funnel counts, service failures, ticket time, satisfaction, then each dish / segment / station / employee outcome in ascending id order. The checksum is a field of `ServiceResult`. + +Its job is to make determinism cheaply testable: the same `(world, scenario, plan, seed)` must yield the same checksum on any machine. This is asserted three ways: + +- **Same-seed reproduction** across the full strategy × scenario matrix (`RestaurantSim.Determinism.Tests`), running each cell twice and comparing checksums. +- **Golden checksums** — three `(strategy, scenario, seed)` triples with hard-coded expected checksum values (`RestaurantSim.Scenario.Tests`), which lock the numeric behaviour against silent drift. +- **The harness** re-runs a sampled matrix twice and writes `reports/determinism/checksums.md`, returning a non-zero exit code on any mismatch. + +Because the core uses only integer/`Int128`/`UInt128` math, a portable PRNG, and no platform RNG or wall clock, these checksums are expected to be identical cross-OS (cross-OS CI is an open item in the determinism contract; the local double-run check is active). + +--- + +## 7. Why this shape + +The pipeline is deliberately one-way: `(inputs) → sim → result → view`. Nothing downstream of the simulator can invent or recompute an outcome. That is the property that lets M0 answer its product question honestly (the numbers the player reacts to are the numbers the sim actually produced), and it is the property a future save/replay system and a future rendering engine will both depend on. See `SAVE-AND-HISTORY-CONTRACT.md` and `ADR-004-PRESENTATION-BOUNDARY.md`. diff --git a/docs/architecture/DETERMINISM-CONTRACT.md b/docs/architecture/DETERMINISM-CONTRACT.md new file mode 100644 index 0000000..e22fe12 --- /dev/null +++ b/docs/architecture/DETERMINISM-CONTRACT.md @@ -0,0 +1,165 @@ +# Determinism Contract + +**Status:** Locked for M0. Enforced by tests in `tests/RestaurantSim.Determinism.Tests`. +**Owner:** Builder / Technical Lead. Changing this contract requires a DECISION-LOG entry. + +This contract closes the accepted review finding that the plan asserted "same seed reproduces +the same state" 20+ times but never named the mechanisms that make cross-machine, cross-version +determinism actually hard. The single biggest threat is binary floating-point. This contract +removes it from the authoritative core. + +> **Rule:** The authoritative simulation is a pure function of `(initial state, seed, commands)`. +> Given the same three, it produces byte-identical end state on any machine, any OS, any run. + +--- + +## 1. Numeric representation + +### 1.1 Money — integer minor units +All authoritative money is `long` **cents**. Never `float`/`double`/`decimal` for authoritative money. + +``` +$12.34 == 1234 cents +``` + +`decimal` is banned in the core too: it is deterministic but slow and invites accidental +fractional money. Rounding is explicit and integer-only, at documented points. + +### 1.2 Percentages, rates, probabilities — integer basis points / per-million +- Rates and percentages: **basis points** (`int`), 10,000 bp = 100%. +- Probabilities that need finer resolution: **per-million** (`int`), 1,000,000 = certainty. + +``` +75.25% == 7525 bp +appeal 0.812 == 812000 per-million (or 812 on the 0..1000 "milli" scale, see 1.3) +``` + +### 1.3 Bounded quality-like quantities — integer "milli" scale (0..1000) +Quality, satisfaction, appeal, skill, freshness-like 0..1 quantities are integers on a +**0..1000** scale ("milli"). 1000 = maximum. This keeps them legible and exact. + +### 1.4 Fixed-point where a fraction is unavoidable +Where a genuine fractional quantity is needed (e.g. fractional portions), use a documented +fixed-point integer at **scale 1000**: + +``` +1.125 portions == 1125 fixed units at scale 1000 +``` + +Multiplication of two scaled integers divides by the scale with explicit integer rounding +(round half up, documented in `FixedMath`). + +### 1.5 Forbidden in authoritative fields +No `float` or `double` (and no `decimal`) may appear in any authoritative model field: +money, ingredient amounts, preparation progress, satisfaction, quality, skill, demand +probability, time, inventory, waste, pricing elasticity, station utilization, employee +productivity, or any value that feeds a comparison, a branch, or an RNG draw. + +Floats are permitted **only** in a future presentation/rendering layer (animation +interpolation, camera, cosmetic transforms, particles). They may never determine a +simulation outcome. This is enforced by a reflection test that scans all `RestaurantSim.Core` +model types for `System.Single`/`System.Double`/`System.Decimal` fields and fails the build. + +--- + +## 2. Time + +- The simulation advances in **fixed integer steps** ("operational minutes"). M0 ticks one + simulated minute at a time over a fixed-length service. +- No authoritative system may read the wall clock: `DateTime.Now`, `DateTime.UtcNow`, + `DateTimeOffset.Now`, `Environment.TickCount`, `Stopwatch`, or any ambient time source is + banned in `RestaurantSim.Core`. Enforced by a source-scan test. +- Simulation speed (1x/2x/…) is a **presentation** concern only. It never changes results. + +--- + +## 3. Randomness — named, seeded, attributable streams + +- The core uses one deterministic PRNG (SplitMix64) and **never** `System.Random`. Enforced by + a source-scan test. +- Randomness is organized into **named streams** so that adding a new roll in one stream cannot + perturb an unrelated stream. M0 streams: `Arrivals`, `Party`, `Choice`, `Execution`, + `Incident`. (Reserved for later: `Reviews`, `MarketEvents`, `Competitors`.) +- Every draw is **attributable** and **position-independent across entities**. A stream is not a + single shared sequence; a per-entity sub-generator is derived by mixing: + +``` +seed(stream, entityKey) = mix64(rootSeed, fnv1a64(streamName), entityKey) +``` + + So the 4th party's rolls do not shift the 5th party's rolls, and adding a roll to party A + never changes party B. This satisfies the contract requirement: "adding a new random roll must + not silently change unrelated RNG sequences." +- Each random decision is traceable to `(rootSeed, streamName, entityKey, drawIndex)`. + +--- + +## 4. Deterministic system order + +The service tick applies systems in a single documented order; there is no reliance on +collection-iteration order for authoritative results. Where a system iterates a collection, the +collection is ordered by a stable integer key (entity id), never by hash-set/dictionary +enumeration order. Parallelism is not used in the M0 core. If ever introduced, it is permitted +only where reduction order is fixed and cannot change results. + +M0 tick order as implemented in `ServiceSimulator.Run` (see `ARCHITECTURE-OVERVIEW.md` for detail). +The committed plan and menu-complexity load are applied once before the loop. Then, each minute: +1. Generate arrivals for the minute (`Arrivals` stream, keyed by minute), apply door acceptance. +2. Seat or queue waiting parties in arrival order; expire seat-queue walk-aways. +3. Advance seated parties through the state machine — Browsing (dish tickets are released here via + `OrderDishes`, `Choice` stream) → Cooking (walkout check, delivery when all dishes done) → Eating → + Paid. Front-of-house is a per-minute capacity **ratio** (`fohRatioBp`) that gates order/delivery + delays and samples a service-quality score; it is not a separate task queue in M0. +4. Station production: each station advances its occupied slots (`Execution`/`Incident` streams for + quality and mistakes) under capacity, pulling from its queue. +5. Optional sampled service-log snapshot. +Final (once, in `Finalize`): compute each party's satisfaction, settle the economy, build the causal +report, and compute the state checksum. + +Collections are iterated in stable id order (stations 0..3, menu by recipe id, segments by id, +employees by id). No authoritative result depends on hash-set/dictionary enumeration order. + +--- + +## 5. State checksum + +- `ServiceResult` and the authoritative end state expose a **64-bit FNV-1a checksum** computed + over all authoritative integer fields in a canonical, id-ordered serialization. +- **CI runs the same fixture at least twice and compares checksums.** A mismatch is a blocking + failure. +- Where practical, the determinism fixture is run on at least two OS environments (e.g. macOS and + Linux in CI) and the end-state checksum compared. Because the core uses only integer math, no + RNG from the platform, and no wall clock, these must match exactly. (Cross-OS CI is an + [OPEN ITEM] until a CI provider is wired up; the local double-run check is active now.) + +--- + +## 6. Save / replay determinism (forward reference) + +M0 has no production save system (a non-goal). But the contract already guarantees the property +a save system will later depend on: persisting `(initial state, seed, command log, RNG stream +positions)` and replaying yields an identical checksum. See `SAVE-AND-HISTORY-CONTRACT.md`. + +--- + +## 7. Future pathfinding / engine boundary (forward reference, not built in M0) + +When spatial movement arrives (M1+), Godot's `NavigationServer`/`PhysicsServer` or any engine +navigation may **propose or display** movement, but may never become the sole owner of an +authoritative restaurant outcome. Authoritative movement/timing must run in the C# core on a +deterministic grid with integer coordinates and deterministic tie-breaking. Engine navigation is +cosmetic/interpolated only. This is on the hard do-not list for M1 agents. + +--- + +## 8. What the tests enforce (summary) + +| Guarantee | Test | +|---|---| +| No float/double/decimal in authoritative fields | reflection scan of Core model types | +| No wall-clock use in Core | source-scan for banned time APIs | +| No `System.Random` in Core | source-scan | +| Same seed+commands ⇒ same checksum | run fixture twice, compare | +| Adding a roll to one entity doesn't shift another | stream-isolation unit test | +| Money reconciles exactly | economy invariant test | +| Historical forecast immutable after results | forecast-immutability test | diff --git a/docs/architecture/SAVE-AND-HISTORY-CONTRACT.md b/docs/architecture/SAVE-AND-HISTORY-CONTRACT.md new file mode 100644 index 0000000..161403c --- /dev/null +++ b/docs/architecture/SAVE-AND-HISTORY-CONTRACT.md @@ -0,0 +1,48 @@ +# Save & History Contract + +Purpose: state the one determinism property M0 already guarantees that a future save/replay system will depend on, and enumerate — clearly marked as *not built in M0* — the forward requirements such a system must meet. + +**Status:** Forward-looking. **M0 has no production save system; that is an explicit non-goal** (`M0-PROTOTYPE-CONTRACT.md` §4, "a full production save system"; §7 "no production assets ... Everything on the non-goals list is absent, not stubbed"). This document records the guarantee M0 *does* provide and the requirements a later save system *will* have. Nothing here is implemented in M0, except where it says "M0 already guarantees." + +--- + +## 1. What M0 already guarantees + +M0 does not save anything. But it establishes the single property that makes save/replay tractable later: + +> **The simulation is a pure function of `(world, seed, committed plan)`.** +> `ServiceSimulator.Run(world, scenario, plan, seed)` reads no wall clock, no `System.Random`, no ambient state, and performs no I/O. Given the same inputs it produces byte-identical authoritative state, summarized by the same 64-bit checksum. + +The consequence a future save system inherits for free: + +> **Persisting the inputs — `(world/fixtures, scenario, committed plan, seed, and RNG stream positions)` — and replaying them reproduces the identical `ServiceResult` and identical `Checksum`.** + +There is no need to serialize the entire mid-service object graph to reproduce a service: the inputs *are* the save. This is exactly the property `DETERMINISM-CONTRACT.md` §6 forward-references — *"persisting `(initial state, seed, command log, RNG stream positions)` and replaying yields an identical checksum"* — and it is proven today by: + +- the same-seed checksum reproduction across the full strategy × scenario matrix (`RestaurantSim.Determinism.Tests`), +- the three locked **golden checksums** (`RestaurantSim.Scenario.Tests`), which are effectively a hand-maintained "replay expectation" for three fixed runs, and +- the harness double-run determinism report. + +Because the RNG is a set of named, per-entity streams derived deterministically from the root seed (`ADR-003`), "RNG stream positions" for M0 reduce to the root seed plus the command inputs — there is no hidden global RNG cursor to capture. (A future system with long-lived, incrementally-advanced streams would need to persist their positions explicitly; M0's re-derivation model does not.) + +## 2. Forward requirements (NOT built in M0) + +The following are requirements a real save/replay/history system will have to meet. **None of these exist in M0.** They are recorded here so the eventual builder implements them deliberately, not so anything is scaffolded now. (Sources: the master plan's save-system requirements, §12.7/§12.8; `M0-PROTOTYPE-CONTRACT.md` non-goals.) + +1. **Schema version on every save.** A save file carries an explicit format/schema version so a future engine can recognize and migrate old saves rather than misread them. + +2. **Content manifest versions.** Fixtures (segments, recipes, employees, scenarios) must be identified by stable, namespaced IDs and schema versions, so a replay is validated against the content it was recorded with. A missing or changed content item must be diagnosed, not silently substituted (the master plan's "missing-mod diagnostics"). + +3. **Immutable historical records.** Anything recorded as history — the pre-service `ForecastSnapshot` above all — is written once and never rewritten. This extends the M0 forecast-immutability invariant (`ADR-004`) into persistence: a stored forecast must remain byte-identical to what was shown at commit time, so a "forecast vs actual" review is honest across a save/load boundary. + +4. **Atomic write-then-replace.** Saves are written to a temporary file and atomically renamed over the target, with validation before the overwrite, so a crash mid-write cannot corrupt an existing save. Rotating autosaves and a recovery save sit alongside manual saves. + +5. **Migrations.** Loading an older save runs forward migrations to the current schema. Migrations are first-class, tested, and long-lived. + +6. **No silent data loss.** Loading must never quietly drop state it doesn't understand; unknown or unmigratable data is surfaced as a diagnostic, never discarded without warning. Backward-compatibility and mid-service save/load are covered by their own regression tests. + +## 3. The aspiration: save compatibility as a product feature + +The master plan names **OpenTTD** as the model to learn from: *"OpenTTD's long-running commitment to loading old save revisions is the aspirational model: save compatibility is a product feature, not housekeeping"* (§12.7), and among the OpenTTD lessons, *"save compatibility can become a durable product promise"* (§ Study of comparable projects). The intent for the eventual game is that a player's saved restaurants keep loading across versions — a promise, not an afterthought. + +M0's contribution to that promise is upstream and structural: by making the sim a pure, integer-only, seed-driven function with a stable checksum **now**, it guarantees that whatever save format is chosen later can be validated by replay ("does loading this save and re-running produce the recorded checksum?"). The hard part of save compatibility — a deterministic core whose replays are trustworthy — is the part M0 has already locked. The file format, migrations, and versioning listed in §2 remain entirely future work. diff --git a/docs/archive/2026-07-28/method-how-to-build-your-next-game-faster.md b/docs/archive/2026-07-28/method-how-to-build-your-next-game-faster.md new file mode 100644 index 0000000..e557ad4 --- /dev/null +++ b/docs/archive/2026-07-28/method-how-to-build-your-next-game-faster.md @@ -0,0 +1,966 @@ +# How to Build Your Next Game Faster + +### A field guide to proving a game is worth building — before you build it + +*For the solo creator or the two-person team, leaning hard on AI coding agents, in any genre.* + +--- + +**Who this is for.** You have a game idea. You are not a career engineer. You will do a lot of the work by directing AI coding agents, and you may be building something completely different from whatever the person next to you is building — an action game, a management sim, a card game, a puzzle box, a racing game. You want to move fast without wasting weeks on the wrong thing. + +**This is a method, not a promise.** No book makes a game good. What a method can do is help you *learn sooner* — find out whether your idea is worth building while it is still cheap to find out, and stop pouring time into an idea that a five-hour test would have told you to change. "Faster" here never means "skip the hard parts." It means you waste less, you learn earlier, and when something is wrong you find out on day one instead of month three. + +Read it in order the first time. After that, jump to the section you need. Every major section ends with a one-line **test** you can actually run and a short **watch out for** list of the ways people trip. + +--- + +## Table of contents + +1. [The central rule](#1-the-central-rule) +2. [Turn the idea into one product question](#2-turn-the-idea-into-one-product-question) +3. [Choose the cheapest valid prototype](#3-choose-the-cheapest-valid-prototype) +4. [Define the prototype contract before building](#4-define-the-prototype-contract-before-building) +5. [Build a complete gray-box loop](#5-build-a-complete-gray-box-loop) +6. [Prove player value before art](#6-prove-player-value-before-art) +7. [Lock scale, camera, input, and interaction early](#7-lock-scale-camera-input-and-interaction-early) +8. [Keep game rules separate from presentation](#8-keep-game-rules-separate-from-presentation) +9. [One source of truth for world data (and make it reproducible)](#9-one-source-of-truth-for-world-data-and-make-it-reproducible) +10. [Measure speed on the device you'll ship on](#10-measure-speed-on-the-device-youll-ship-on) +11. [Borrow the background, build the identity](#11-borrow-the-background-build-the-identity) +12. [Review gates, and knowing when to stop](#12-review-gates-and-knowing-when-to-stop) +13. [Directing AI coding agents](#13-directing-ai-coding-agents) +14. [Adapting this to your genre](#14-adapting-this-to-your-genre) +15. [Common ways this goes wrong (and how to catch it early)](#15-common-ways-this-goes-wrong-and-how-to-catch-it-early) +16. [A realistic timeline, and what "faster" means](#16-a-realistic-timeline-and-what-faster-means) +17. [Putting it all together](#17-putting-it-all-together) + +Appendices: [A — The prototype brief](#appendix-a--the-prototype-brief-blank-copy-ready) · [B — The first player test](#appendix-b--the-first-player-test-script) · [C — Day-one standards](#appendix-c--day-one-standards-one-screen-checklist) · [D — The other two documents](#appendix-d--the-other-two-documents) + +--- + +## 1. The central rule + +Here it is, the whole handbook compressed into one sentence. Everything after this is just unpacking it. + +> **Build the cheapest complete experience that can disprove your idea, let a real person use it, correct only what prevents an honest verdict, and integrate it only after the main game is ready to consume it.** + +Read it twice. Now let's take it apart clause by clause, because every word is load-bearing. + +**"the cheapest complete experience"** — *cheapest*, so you spend the least time and money that still answers the question. *Complete*, so it is a whole loop, not a pretty fragment. A gorgeous menu that leads nowhere teaches you nothing. An ugly, complete thing you can actually play teaches you everything. Cheap and complete pull against each other, and the art of this whole method is finding the point where they meet: the smallest thing that is still *whole*. + +**"that can disprove your idea"** — this is the part people skip, and it's the most important. Your prototype has to be able to *fail*. If there is no possible outcome where you look at the result and say "no, this doesn't work," then you haven't built a test, you've built a demo that will always tell you what you wanted to hear. A test that can only pass is theater. Before you start, you must be able to name the result that would make you stop. + +**"let a real person use it"** — not you. You already love it; you made it. You know what the buttons do and what you *meant*. A real person, ideally one who has never seen it, is the only instrument that measures whether the thing is understandable and fun. You watch them; you don't rescue them. + +**"correct only what prevents an honest verdict"** — when the test surfaces problems, fix *only* the ones that stop you from getting a clean answer. If a player literally can't tell what to do, fix that — you can't get a verdict through the confusion. If a shadow flickers but the game is clearly fun anyway, leave it. One bounded fix pass, then stop. Do not slide into polishing. + +**"and integrate it only after the main game is ready to consume it"** — your prototype lives somewhere it cannot hurt your real project. You fold it into the main game *last*, deliberately, once the real game actually has a place to plug it in — not the moment it looks nice. Early integration is how a throwaway experiment quietly becomes load-bearing and then you can't change it. + +### The ladder of proof + +Not all "does it work?" questions are the same size. There are five rungs, and each one is a genuinely harder claim than the one below it. Name the rung you're testing, and don't claim a higher one than you've earned. + +1. **It runs.** Compiles, launches, doesn't crash. The *machine* can tell you this. It proves almost nothing about the game. +2. **It's understandable.** A fresh person, with no coaching, forms the *correct* idea of what to do. Only a first-time player can tell you this. +3. **It's fun.** Someone calls it fun with no "well, if you imagine..." qualifiers attached. A player, on the real device, tells you this. +4. **It scales.** Still readable and still fast when you have real content volume — forty roster spots, not three; a whole city, not one block. +5. **It's production-ready.** You have an *honest* number for what building the whole thing costs. + +Rung 1 is nearly free and proves the least. Most prototypes should be aiming at rung 2 or 3. Here's the trap that catches everyone: "the tests pass" is rung 1, and it gets mistaken for a verdict on rungs 2 through 4 constantly. On one real prototype, *every single* problem that mattered — the character that was the wrong size, a surface that flickered when the camera moved, a scene that didn't read the way it was supposed to — was invisible to the automated checks and got caught only by a human looking at the actual screen. A green build is not evidence your game is understandable, fun, or scalable. Those are different rungs with different judges. + +### What this handbook helps you avoid + +Some pain in game development is *normal*. When you first put real art into a scene, things will flicker, things will vanish at odd camera angles, an imported model will look wrong. That is expected discovery cost — you fix it as you go, and it is not a sign you did anything wrong. + +This handbook is not about that. It's about the *preventable* waste — the kind that comes from process, not from the medium: + +- Building beautiful art before you knew the game was fun. +- Redoing work because two lists that were supposed to agree quietly drifted apart. +- Catching a basic scale error late, after everything was built around it. +- Guarding your real project against a prototype with a check so brittle it breaks itself. +- Over-documenting something you were going to throw away. +- Assuming a cheap placeholder was production-ready and building on it. + +Keep those two categories separate in your head. Flickering when you drop in new art is the cost of doing the work. Redoing a week because you skipped a five-minute check is the thing we're here to prevent. + +**The test:** you can state, in one sentence each, your one testable question, the result that would make you stop, and where your prototype lives so it can't hurt your real project. + +**Watch out for:** +- A "test" with no possible failing outcome — that's a demo wearing a lab coat. +- Reading "it compiles and runs" as "it's good." That's rung 1 pretending to be rung 3. +- Falling in love with the thing you built and losing the ability to judge it — which is exactly why a real person, not you, gives the verdict. + +--- + +## 2. Turn the idea into one product question + +An idea is a feeling. "A game where you run a football club." "A cozy game about tending a garden." Feelings are wonderful and you can't test a feeling. Before you build anything, you have to boil the idea down to *one question you're genuinely unsure of* — one that a small, cheap test could actually answer with a yes or a no. + +Not "can I build this?" You almost certainly can, given enough time. The question is whether the thing at the *center* of your idea — the part everything else hangs on — actually delivers the feeling you're chasing. That's what you don't know yet, and that's what's expensive to get wrong. + +### The worksheet + +Fill in every line before you write a line of code. If you can't answer one, that gap *is* the thing to investigate. + +- **The fantasy** — what does the player get to *feel* they are? (A cunning manager. A daring driver. A clever detective.) +- **The core action** — the one thing the player physically does, over and over. (Sign a player. Take a corner. Read a clue.) +- **The core decision** — the interesting choice underneath that action. (Who to sign, and at what cost. When to brake. Which clue to trust.) +- **The intended emotion** — what should the player feel in the moment the core decision lands? (Tension. Mastery. Doubt.) +- **The biggest uncertainty** — the one thing you genuinely don't know will work. +- **The expensive-to-reverse assumption** — the belief that, if it's wrong, forces a rewrite or a re-do of a lot of art. +- **The cheapest test** — the smallest thing that could show you whether that assumption holds. +- **The pass condition** — what a good result looks like, concretely. +- **The fail condition** — what result would honestly make you stop or change direction. + +If your pass and fail conditions are the same vague thing ("it feels good"), sharpen them until a stranger could tell them apart by watching someone play. + +### Weak vs strong + +The single biggest upgrade you can make is turning a weak question into a strong one. + +- **Weak:** *"Can I build a football-management game?"* This can't fail. Of course you can build one, eventually. There's no stop condition, nothing to measure, no moment where the answer is "no." It's unfalsifiable — meaning no result could ever prove it wrong. + +- **Strong:** *"Can a player make a meaningful roster decision in under two minutes while understanding both its short-term and long-term consequences?"* Now we're talking. You can watch someone try. You can time it. You can ask them what they thought the decision would do and check it against what it actually did. It has a clear pass and a clear fail. It can produce a "no." + +The difference: the strong question isolates the *one uncertain, expensive-to-reverse axis* — here, whether the core decision is both quick and legible — and makes it measurable. + +### Eight questions, across genres + +Yours should sound like these. Each one is falsifiable, cheap to test, and can produce a real "no." + +- **Action** — *Is the core movement and combat satisfying at a smooth frame rate?* Judged by a player feeling it, not by a passing test. +- **Simulation / Management** — *Can resource management stay understandable as the system grows more complex?* Judged by whether a fresh player still forms a correct plan when there's more going on. +- **Strategy** — *Does the core decision have a real counter — is it expressive, or is there one obvious best move?* Judged by whether a thoughtful player finds more than one viable line. +- **RPG** — *Does a build choice lead to a fight and a payoff that feel like they're the player's own?* Judged by whether the player takes ownership of how they progressed. +- **Racing** — *Is the handling fun right at the edge of control?* Judged by a player pushing the limit, on real hardware. +- **Narrative** — *Does a branching choice produce a consequence a fresh player actually notices and can name?* Judged by whether they can tell you what their choice changed. +- **Multiplayer** — *Is a contested moment fair and consistent for both players even with lag?* Judged by two people playing against each other, not by one person imagining the second. +- **Card / Deckbuilder** — *Is the deck-building loop expressive, or is it already solved?* Judged by whether a reviewer finds more than one strong way to play. + +Notice that not one of these is "build the game." Each isolates a single uncertain thing that would be painful to discover you got wrong. + +### Picking a question that can actually STOP + +The whole point is a clean decision, so bias toward the question whose failure would cost you the most later. If getting the camera and scale wrong means re-doing a month of art, prove the camera and scale. If the thing that could sink you is that your clever card mechanic is secretly solvable in one obvious line, prove *that* with a handful of cards before you design a hundred. + +Say the honesty rule out loud before you start: *a failed experiment is fine; a misleading success is not.* That one sentence is what keeps a prototype honest, because it makes "we proved it doesn't work" a win instead of a failure you're tempted to hide. + +**The test:** you can write your product question in one sentence, and next to it a fail condition that a stranger watching a playtest could recognize. + +**Watch out for:** +- The "can I build it?" question — always yes, never useful. Ask "is the core *good*?" instead. +- A pass condition you can't distinguish from the fail condition. If both are "it feels fun," you haven't defined either. +- Testing the safe part. If you prove the thing you were already confident about, you've spent time to learn nothing. + +--- + +## 3. Choose the cheapest valid prototype + +You have your question. Now: what's the *cheapest thing you can build that can honestly answer it?* Sometimes that's a spreadsheet. Sometimes it's a rough playable scene. The mistake is reaching for the biggest, most impressive form when a smaller one would answer the question just as well — and the opposite mistake, reaching for a form too flimsy to answer it at all. + +First, two words you'll see throughout, defined simply: + +- **gray-box** (also called a *blockout*) = the game built out of rough placeholder shapes — boxes, capsules, flat colors — instead of real art. It's the playable skeleton before the skin. +- **vertical slice** = one small but *complete* slice of the game: the whole loop working, just tiny and ugly. + +### The forms, cheapest to heaviest + +- **Paper** — cards, tokens, a hand-drawn grid. Best for turn-based rules, card games, tactics, social-deduction. You can test whether a decision is interesting before a single line of code. +- **Spreadsheet** — for economies and progression curves. Does the resource math create interesting choices, or does one strategy dominate? A spreadsheet answers that in an afternoon. +- **Text simulation** — a program with no graphics that just prints what happens each turn. Perfect for a management or strategy loop where the *numbers and decisions* are the game and the visuals are secondary. +- **Mocked UI** — clickable screens with fake data behind them. Tests whether the *interface* is understandable before you build the systems it controls. +- **Gray-box** — the playable blockout. Boxes and capsules moving around. This is your default for anything where *movement, space, camera, or feel* matter. +- **Engine sandbox** — a throwaway scene inside your game engine to test one mechanic (a grappling hook, a handling model) in isolation. +- **Network harness** — a minimal two-client setup with one authoritative host, for multiplayer. You need this early because "feels fine on my machine" tells you nothing about lag. + +Then there's the question of *where the code lives*, which matters as much as the form. From most separate to least: + +- **Standalone repo** = a completely separate copy of your code, with no link back to the real project. The prototype physically cannot touch the main game. Safest. +- **Branch** = a parallel line of development inside your real project's repository. Isolated in history, but it shares the project and can be merged in — so it's easier for prototype code to leak into the real thing. +- **Worktree** = a second working folder attached to the same repository, letting you have the main game and the prototype checked out side by side. Convenient; still one repository underneath. +- **In-main prototype** = you just build it right inside the real project. Fastest to start, most dangerous — there's nothing stopping the experiment from tangling into production code. + +### A decision table + +Match the pressures of your prototype to the form. Read down the left, and let the heaviest pressure win. + +| If this is high... | ...lean toward | +|---|---| +| **Visual dependence** (the answer depends on how it *looks*) | gray-box, then real art | +| **Input dependence** (the answer depends on how it *feels* to control) | engine sandbox on the real device | +| **Sim complexity** (the game is mostly numbers and rules) | spreadsheet or text sim | +| **Multiplayer** | network harness with a real authoritative host | +| **Save implications** (you'll test long-term progression) | pick a form that can persist state, and design the save shape early | +| **Existing codebase to protect** | standalone repo or branch, never in-main | +| **Integration risk** (prototype could tangle into production) | standalone repo — maximum isolation | +| **Expected lifespan** (you'll keep iterating on it for weeks) | worktree or branch, so it's maintainable | + +### A simple decision tree + +1. **Is the game mostly rules and numbers, with visuals secondary?** → Paper or spreadsheet or text sim. Stop; you don't need an engine yet. +2. **Does the answer depend on how it looks or feels to move?** → Gray-box in an engine. If control feel is the whole question, an engine sandbox on the real device. +3. **Is it multiplayer?** → Add a network harness with one authoritative host from the start; lag is not something you bolt on later. +4. **Do you already have a real project this could damage?** → Build it in a standalone repo by default. Drop to a branch or worktree only if you truly need to share code, and even then, keep a clean boundary. +5. **Otherwise** → gray-box in whatever engine you'll ship in. + +### When isolation is overkill + +If you have no real project yet — this *is* the beginning of your game — then a standalone repo just to "isolate" it from nothing is ceremony. Build in a plain project and move on. Isolation earns its keep specifically when there's an existing, working thing you could break. The rule isn't "always maximally separate"; it's "as separate as the thing you're protecting demands, and no more." + +**The test:** you can name your prototype's form and its home, and explain in one sentence why that's the *cheapest* form that can still answer your question. + +**Watch out for:** +- Reaching for a 3D engine when a spreadsheet would answer the question — impressive, and a week wasted. +- Building in your real project "just for now," then discovering the prototype has grown roots into production code. +- Under-building: a form so thin it can't actually produce the reaction you need to judge. A paper mockup won't tell you if the driving *feels* good. + +--- + +## 4. Define the prototype contract before building + +Before you or an AI agent writes anything, write the *contract* — a short, explicit brief that says what this prototype is, what it is emphatically *not*, and how you'll know it's done. This is the single highest-leverage half-hour in the whole process. It's what keeps a two-day experiment from becoming a two-week one. + +The brief matters double when you're directing AI agents, because an agent will happily build anything you leave a door open for. A vague brief doesn't produce a smaller result — it produces a *bigger* one, full of things you never asked for. + +### The prototype brief — 12 items + +1. **Product question** — the one sentence from Section 2. What are you actually trying to learn? +2. **Target player reaction** — the specific reaction from a real person that would count as success ("a first-timer plans two moves ahead unprompted"). +3. **Authorized scope** — exactly what's in bounds to build. A short list. +4. **Explicit non-goals** — what is *deliberately not* being built. (See below — this list is as important as the scope.) +5. **Timebox** — how long you're giving this. A real limit, in hours or days, not "until it's done." +6. **Required systems** — the minimum machinery the prototype genuinely needs to answer the question. +7. **Placeholder policy** — what is allowed to stay fake. Which parts are boxes-and-capsules, which are stub data, which don't exist at all. +8. **Evidence required** — what proof you'll produce. A recording of a playtest. A screenshot on the real device. A captured performance number. Name it now so you can't hand-wave it later. +9. **Pass criteria** — what result means "yes." +10. **Stop conditions** — what result means "stop" — either because you got a clear "no," or because you've hit the timebox, or because the question turned out to be unanswerable this way. +11. **Repository boundary** — where it lives and, concretely, how it *cannot* hurt the real project. +12. **Owner decision required** — the specific decision you (or whoever owns the project) will make when the prototype is done. Name it so the prototype has a purpose beyond existing. + +### Why non-goals matter as much as goals + +A goal tells the builder — human or AI — what to aim at. A non-goal tells them where to *stop*, and stopping is the harder discipline. Every hour spent on something outside the question is an hour that didn't go toward answering it. + +Non-goals also protect you from your own good ideas. Mid-build, you *will* think of a great feature. The non-goals list is where you already decided, calmly and in advance, that it waits. Write down what you're deferring — don't quietly build it, and don't pretend you never thought of it. A deferred idea on a list is a decision anyone can find later. A silently-built one is a gap nobody can find. + +A useful pattern when working with agents: give them a hard **do-not-build** list, verbatim, as part of the brief. Not "focus on X" — an explicit "do not build inventory, do not add save/load, do not touch the networking." Agents rationalize scope creep; a hard list is what they check themselves against. + +### Scope creep, by example + +Here's what creep actually looks like, so you can catch it early: + +- Building an **inventory system before movement is even fun.** If walking around isn't good yet, a backpack full of items won't save it. +- Wiring up **multiplayer progression before the netcode is stable.** You're decorating a house with no foundation. +- Designing **fifty cards before three cards create a real decision.** If three cards aren't interesting, fifty are just fifty flavors of not-interesting. +- Commissioning **final character art before you've proven you can even render close-up characters well.** Beautiful art on top of an unsolved pipeline is money set on fire. +- Simulating **a whole city before a single block communicates cause and effect.** If a player can't read why one block thrived, a hundred blocks are just noise. + +Each of these has the same shape: spending on breadth before proving the thing that breadth depends on. + +**The test:** every item on the 12-point brief is filled in, and the non-goals list has at least as much thought in it as the scope list. + +**Watch out for:** +- An empty or hand-wavy non-goals list — that's an open invitation for scope creep, especially from an AI agent. +- A missing timebox. "Until it's done" is not a timebox; it's how a two-day test becomes a month. +- Promising evidence in the brief ("we'll measure performance") and then never capturing it. If you promise a number, record it — or cut the promise. + +--- + +## 5. Build a complete gray-box loop + +Now you build — and the rule is: get the boring version playable *first*. + +Boxes and capsules. Flat colors. No art, no sound to speak of, no polish. If a boxes-and-capsules version of your game isn't a little bit fun — or at least clearly *pointing at* fun — prettier art will not save it. It will just cost you a month first, and then you'll have a beautiful thing that still isn't fun, and now you're too invested to change it. + +The magic word is **complete**. Not big — complete. + +### What "complete" means + +Complete means the *whole loop closes*. The player can start, do the core action, cause a change in the world, succeed or fail, see the result, and go again. A fragment — even a lovely one — that doesn't close the loop can't produce an honest reaction, because the player never reaches the point where the game is supposed to pay off. + +Tiny is fine. Ugly is fine. Incomplete is not. One small complete loop beats ten polished fragments. + +### Per-genre gray-box: the smallest loop that earns an honest reaction + +For each genre, this is the minimum complete loop — the least you can build and still get a real reaction to your actual question. + +- **Action** — a character you control, one threat, and input-to-feedback at a smooth frame rate. Question it answers: *does moving and fighting feel good?* +- **Simulation / Management** — one resource, one decision, one consequence you can read on screen. *Can a new player form a plan?* +- **Strategy** — one real decision that has a real counter. *Is it expressive, or is there one obvious best move?* +- **Sports / Roster** — evaluate, sign, field, result, with a tiny roster. *Does it stay clear as the roster grows?* +- **RPG** — one build choice, one fight, one payoff. *Does progressing feel like it's yours?* +- **Narrative** — one branch whose consequence a fresh player actually notices. *Does the choice create ownership?* +- **Racing** — one stretch of track and a handling model. *Is it fun near the limit of control?* +- **Multiplayer** — two players, one authoritative host, one contested moment. *Is it fair and consistent with lag?* +- **Mobile / Touch** — one core interaction sized for thumbs, on a real phone. *Is it readable and reachable one-handed?* +- **Roguelike** — one seeded run, a few rooms, death, and a little meta-progression. *Is run-to-run variety meaningful?* +- **Puzzle** — one rule set and three handmade puzzles. *Is the "aha" reachable and fair — no guessing?* +- **Card / Deckbuilder** — a small deck, a few turns. *Is the play expressive, not already solved?* +- **City-builder** — one build, simulate, feedback tick. *Can the player see cause and effect?* +- **Social-deduction** — one round of hidden roles. *Does the information create useful doubt?* +- **Tactics** — one small-grid skirmish. *Can players read the board and plan two moves ahead?* + +### What stays fake, simplified, or absent + +Be deliberate about this — it's the whole economy of a good gray-box. + +- **Stays fake (placeholder):** all art, all characters (boxes and capsules with a label), most sound, menus and framing. +- **Simplified:** the numbers can be round and hand-tuned; the content can be a handful of items instead of the full set. +- **Absent entirely:** anything on your non-goals list. Save/load if you're not testing progression. Settings, options, accessibility passes, tutorials — none of it exists yet. + +### The ingredient list + +A complete gray-box loop has these ingredients. If one's missing, the loop isn't complete: + +- **Input** — the player can act. +- **Feedback** — the game visibly responds to that action. +- **State change** — the action actually changes the world, not just the screen. +- **Failure** — there's a way to lose, or to do worse, so success means something. +- **Reset** — the player can start over cleanly and go again. +- **Navigation** — the player can get from where they are to where the action is. +- **Camera / viewport** — you can actually see what matters (more on this in Section 7). +- **Scale** — objects are the right size relative to each other and to the player (Section 7 again — this is where projects quietly go wrong). +- **Collision** — the player and the world can't pass through each other where they shouldn't. +- **Readability** — a person who isn't you can look at the screen and tell what's going on. +- **A deterministic fixture** — a fixed, repeatable starting setup so the same test produces the same situation every time. (*Deterministic* = same inputs always give the exact same result, with no hidden randomness and no dependence on the clock. More on why this matters in Section 9.) +- **A performance instrument** — a way to see your frame rate and memory *while it runs*, wired in from the very first build. Don't add it later; you'll want it the moment something feels slow. (Section 10.) + +That last two-item pair — a repeatable fixture and a performance meter, both present from day one — is what separates a gray-box you can actually *learn* from and one that just runs. + +**The test:** a person who has never seen your game can pick it up, complete the full loop once without you touching the keyboard, and start it again. + +**Watch out for:** +- A "vertical slice" that's actually just a nice-looking fragment — the loop never closes, so no honest reaction is possible. +- Skipping the deterministic fixture, so every test starts from a slightly different situation and you can never compare two runs. +- Adding art before the boxes-and-capsules version is even a little fun. The art won't fix "not fun"; it'll just make "not fun" more expensive to change. + +--- + +## 6. Prove player value before art + +You have a complete gray-box loop. Before you spend one hour on art, you put it in front of a real person and *watch them play*. This is the moment the whole method exists for. Everything before it was setup; everything after depends on what you learn here. + +The hard truth: **you loving your game is not evidence.** You made it. You know the controls, you know the intent, you know what that unlabeled box is supposed to be. You are the least reliable judge alive. A real person — ideally someone who's never seen it — is the only instrument that measures whether the thing is understandable and fun to anyone but you. + +### The first player test + +Sit someone down. Give them the minimum to start ("here's how you move") and then *stop talking*. Watch. Take notes. Do not rescue them, do not explain, do not defend. When they're confused, that confusion is your most valuable data — don't step on it. Every time you jump in to help, you erase a finding. + +Afterward, ask these eight questions. Ask them plainly; don't lead: + +1. **What did you think you were supposed to do?** +2. **What did you actually do?** +3. **What felt satisfying?** +4. **What felt confusing?** +5. **What did you expect to happen?** +6. **What surprised you?** +7. **Did you want to try again?** +8. **Was anything stopping you from giving an honest verdict?** + +The gap between question 1 and question 2 — what they *thought* they should do versus what they *did* — is often the single most useful thing you'll learn. It tells you whether the game communicates itself. + +### Observe, don't lead + +The failure mode here is coaching. You'll feel a powerful urge to explain, to smooth things over, to say "oh, you just need to..." Resist it completely. The player struggling *is the test working*. A test where you talked them through every rough spot tells you only that your game is playable with you sitting next to every customer, which you will not be. + +### Separate the layers of "did it work" + +When you review what you saw, sort it into distinct buckets — because these are genuinely different verdicts and it's easy to blur them: + +- **Technical success** — did it run without breaking? (The easy one, and the least meaningful.) +- **Usability** — could they operate the controls and interface? +- **Comprehension** — did they understand what was happening and why? +- **Fun** — did they enjoy it, without qualifiers? +- **Emotional value** — did it produce the feeling you were aiming for in Section 2? +- **Replay** — did they *want* to go again? + +A prototype can pass "technical success" and "usability" and completely fail "comprehension" and "fun." That's a common and important result: the machine works, the person doesn't get it. That's a design problem no amount of art will fix, and it's exactly the kind of thing this test catches before you've spent a dollar on art. + +If the gray-box earns a genuine reaction — someone who isn't you wants to play again — *then* art is worth funding. If it doesn't, art is the most expensive way possible to avoid fixing the real problem. + +**The test:** a first-time player completes the loop with no coaching from you, and can tell you afterward — in their own words — what they were doing and whether they'd play again. + +**Watch out for:** +- Coaching. The instant you explain the confusing part, you've deleted the finding you most needed. +- Counting "it ran fine" as success. Running is rung 1; you came here for rungs 2 and 3. +- Testing only on people who already know your game (including you). They can't be confused by it anymore, so they can't tell you what's confusing. + +--- + +## 7. Lock scale, camera, input, and interaction early + +This is the section that saves the most weeks, and it's the one non-experts most often skip. Scale, camera, input, and how it feels to interact are the *foundation everything else is built on*. Get them wrong and you don't find out until you've built a lot on top — and then fixing the foundation means tearing down everything above it. + +So you lock them *early*, on the *real device*, before you spend on detailed art. + +### The standards to pin down (2D and 3D) + +You don't need to memorize numbers — you need to *decide* yours, write them down, and check them: + +- **Object and animation scale** — how big things are relative to each other and to the player. A character next to a door, a car, a tree — do the sizes make sense together? +- **Camera** — distance, field of view (how wide the lens is), zoom range. How far back does the camera sit, and how much does it show? +- **Occlusion** — *occlusion* means something getting between the camera and what the player needs to see. Does a wall, a roof, a big foreground object ever block the thing the player has to look at? +- **Screen density** — how much stuff is on screen at once, and is it readable or cluttered? +- **Cursor and touch targets** — are clickable and tappable things big enough to hit reliably? (Especially on a phone — a thumb is not a mouse pointer.) +- **Controller feel** — does input map to action in a way that feels responsive, not laggy or floaty? +- **UI scale** — is text and interface legible at the real screen size, not just zoomed in on your dev monitor? +- **Movement speed, interaction range, hitboxes** — how fast things move, how close you have to be to interact, how big the "you hit it" zones are. + +### The mandatory scale-reference test + +Make this your *first* real task, before you compose any scene: put a known-size reference next to every new thing, and *look at it on the actual target device.* + +Here's why, from a real prototype: imported characters came in about 1.5x too tall, and nobody caught it — because a raw measurement of the model gave a misleading number, and the mistake only became obvious when someone looked at the character standing next to a door and a car *on real hardware*. It reads instantly to a human eye and it lied in the raw data. So the rule, learned the expensive way, is now this: **always put a known-size reference next to new art, and look at it on the real device.** Don't trust a number from a measurement tool alone; trust the rendered picture next to something whose size you know. + +And when the character is the wrong size, shrink the character — don't enlarge the whole world to match it. Fix scale at the source, once, driven by a named value, and prove it in an isolated little test scene before anything is built around it. + +### Prove the camera before the environment art + +Lock the camera *first*, then freeze it. On one real 3D prototype, the camera framing was proven and blessed at the gray-box stage, and then *never moved again* — which meant that when art came in later, it slotted into a framing that was already known-good, and none of the later work risked the "does this read right?" verdict that had already been earned. + +There's one thing to add when you first prove the camera: an **occlusion check**. From each camera position, is the line to the thing the player needs to see actually clear? On that same prototype, occlusion was the *one* thing the frozen camera didn't check for, and a big foreground object turned out to block a key view — caught late, precisely because there was no occlusion test at the moment the camera was proven. Add it early: for each camera view, confirm nothing blocks the subject. + +### Early acceptance tests + +Before detailed environment art, put these to the test — each is a quick, concrete check: + +- **Obstruction** — from every camera angle, is the important thing visible? +- **Readability** — can a stranger tell what's what at real screen size? +- **Predictable movement** — does the player go where you'd expect when they push a direction? +- **Motion comfort** — does moving the camera around make anyone queasy? (Real people, real device.) +- **Selection** — can the player reliably click/tap the thing they mean to? +- **Small screens** — if it might ship on a phone, is it reachable and readable one-handed, on an actual phone? +- **Controller/mouse parity** — does it feel right on every input method you plan to support, not just the one you develop on? + +Every one of these is cheap to check on a gray-box and painful to discover after art. + +**The test:** on the real target device, a known-size reference stands correctly next to every object class, and from every camera view the thing the player needs to see is unobstructed. + +**Watch out for:** +- Trusting a measurement number over the rendered picture. The number lied on a real project; the eye caught it. Look at it on real hardware. +- Enlarging the world to fix a too-small-looking character, instead of fixing the character. Now everything's wrong. +- Proving the camera and then never testing whether something blocks the view — occlusion is the defect that hides until late. + +--- + +## 8. Keep game rules separate from presentation + +Here's an architecture idea that sounds abstract and pays off constantly: **the part of your game that draws things should own no truth.** The rules, the money, the scores, the outcomes, the saved game — all of that lives in one place, and the renderer (the part that draws) and the UI just *display* it. They never decide anything. + +Why this matters so much for *you* specifically: it's what lets you change how the game *looks* without touching how the game *works*, and vice versa. Swap a 2D view for a 3D one, redo your whole interface, try a different art style — if the rules don't live inside the visuals, all of that is cheap. If they do, every visual change risks breaking the game itself. + +### The architecture, in plain language + +Think of it as a one-way loop. Truth flows out to the screen; player intentions flow back to the truth. Nothing in the middle owns anything. + +``` + +--------------------------------------+ + | AUTHORITATIVE GAME STATE | <-- the ONE source of truth + | (rules, cash, scores, outcomes, | nothing else owns this + | the saved game — all of it) | + +--------------------------------------+ + | + v + +---------------------------+ + | PRESENTATION ADAPTER | translates game truth into + | (game truth -> a plain, | a plain snapshot for drawing + | read-only snapshot) | + +---------------------------+ + | + v + +---------------------------+ + | IMMUTABLE PRESENTATION | a frozen, read-only picture + | STATE | of "what to show right now" + | (a snapshot; no logic) | + +---------------------------+ + | + v + +---------------------------+ + | RENDERER / UI / AUDIO | just draws the snapshot. + | (draws; owns NO truth) | decides nothing. + +---------------------------+ + | + v + +---------------------------+ + | PLAYER INTENT | the player clicks / presses; + | ("I want to do X") | this is a request, not a change + +---------------------------+ + | + v + +--------------------------------------+ + | AUTHORITATIVE GAME COMMAND | the game state decides what + | (the rules process the intent and | actually happens, then the + | update the ONE source of truth) | loop starts over at the top + +--------------------------------------+ +``` + +Read it as a circle. The game state is the only thing that's *true*. It hands a read-only snapshot down to the drawing layer. The player's clicks and button presses come back up as *intentions* — "I want to sign this player," "I want to move here" — and the game state, and only the game state, decides what actually happens. Then the loop runs again. + +### Why the renderer must own no truth + +If your drawing code is allowed to *decide* things — to hold the real score, to know the actual cash, to be the place a fact lives — then two bad things happen. First, you can't change the visuals without risking the rules. Second, you can end up with two copies of the truth that quietly disagree, and now you have a bug that only appears on screen and can't be reproduced in the logic. + +Keep it strict: the renderer receives a snapshot, draws it, and sends intentions back. It never *knows* anything the game state didn't tell it, and it never *changes* anything directly. + +### Reuse the pattern — but verify the actual data + +Here's an important, easy-to-get-wrong point. This snapshot-in, intent-out *pattern* is wonderfully reusable. You can use the same shape of boundary for a 2D view and a 3D view, for a phone UI and a desktop UI. + +But — and this is the trap — **reusing the shape of the boundary does not mean the two sides use a literally identical data contract.** On one real project, a 2D view and a 3D view shared the same *pattern*, and it was tempting to say "so one snapshot drives both." It didn't. The two snapshots had different fields and even different lists of objects — one carried things the other didn't. They looked interchangeable and were not. + +So the rule is: **reuse the shape of the boundary, but verify that the actual data each side expects really matches. Don't assume they're interchangeable just because they follow the same pattern.** When you build a second view, check field by field that it's asking for what the first one provides — or accept that it's a *related* contract you'll have to reconcile, not the same one. + +### Why this makes swapping look-and-feel cheap + +When the rules live in one place and the visuals only read from it, changing the look is a *local* change. You rewrite the renderer against the same snapshot; the game underneath doesn't move. On one real prototype, an entire art pass — swapping every placeholder shape for real art — went in *without moving the boundary at all*: the interface between rules and drawing was byte-for-byte identical before and after. That's the payoff. The art changed completely; the game didn't have to change even slightly to allow it. That's what "the renderer owns no truth" buys you. + +**The test:** you can point to the one place your game's truth lives, confirm the drawing layer only reads a snapshot of it, and — if you have two views — show they either share a verified-identical data contract or you've explicitly noted where they differ. + +**Watch out for:** +- The renderer holding a fact — a score, a cash value, the "real" state of something. The moment it does, you have two truths that will disagree. +- Assuming two views that share a *pattern* share an *identical data contract*. Check field by field; they drift apart quietly. +- Building the visuals and the rules so tangled that you can't change one without the other — which is the exact thing this architecture exists to prevent. + +Everything above depends on the game's truth being clean and reliable in that one place it lives. Which raises the next question: where, exactly, does your *world* data live — the positions, the obstacles, the spawn points, the rules — and can both the game and your checks read the same copy? + +--- + +## 9. One source of truth for world data (and make it reproducible) + +Section 8 kept your rules apart from your pictures. Now go one level deeper into the rules themselves: where the facts of your world actually live, and how to make those facts behave the same way every single time you run the game. + +Here is the trap, and almost everyone falls into it once. Your game has a tree in it. The renderer draws the tree at position (10, 4). Somewhere else — in your movement code, your pathfinding, your "can the player stand here" check — there's a *separate* list of things that block movement, and someone forgot to add the tree to it. So the tree looks solid but characters walk straight through it. Or the reverse: there's an invisible wall where a tree used to be, because the tree got deleted from the drawing list but not the blocking list. + +That is not a rendering bug. That is **two lists that were supposed to agree drifting apart** — and it is one of the most expensive, most preventable kinds of waste there is, because nothing crashes. Everything looks fine until a player walks somewhere they shouldn't and you spend an hour hunting a "ghost." + +The fix is a rule: **every placed thing in your world lives in exactly one place, and both the drawing code and the rules code read from that same place.** (*Source of truth* = the ONE place a piece of data lives, that everything else reads from.) A tree isn't "a thing the renderer draws" plus "a thing the collision list blocks." It's one tree, in one list, and *drawing it* and *blocking movement around it* are two things that both read the same tree. A prop cannot exist in the world without also being an obstacle, because there is no second list for it to be missing from. + +On one real 3D prototype this exact drift happened. Trees, hedges, and equipment got added to the scene as scenery — but the movement-check list never learned about them. So the automated "is this path clear?" check happily reported "all clear" while, on screen, a parked trailer was sitting right on top of a walking character. The check wasn't lying; it just couldn't see props that lived in a list it didn't read. The fix was to make one list — positions, sizes, obstacles, spawn points, camera framings, doorways — that *both* the renderer and the path-checker consume. After that, adding a prop automatically added an obstacle. You physically could not create the mismatch again. + +**What goes in the one place:** the static facts of your world. Where buildings, walls, and obstacles are. Where things spawn. Where the camera can sit. Which door is where. The rules and numbers that define what's legal. Keep these as plain data — a list, a table, a config — not buried inside drawing code. + +**What does NOT go there:** motion and choreography. If a character walks a path over time, that's a separate thing (a timeline, an animation) that *reads* the static data to know what it must avoid. Keep "where things are" (data) apart from "how things move" (motion). One checker can then validate any motion against the same obstacle data — because there's only one obstacle data. + +Now the second half: **reproducibility.** A bug you can't reproduce is a bug you can't fix. Two habits make your whole game reproducible. + +First, **seeded random** (randomness you can reproduce, because it starts from a number — a "seed" — you control) instead of raw randomness. If your game shuffles a deck, spawns enemies, or rolls damage, run all of it through a seeded generator. Then "run number 4271" always plays out identically. A tester reports a broken run; they give you the seed; you replay the exact same run and watch it break. Without seeding, they say "it happened once" and you're blind. Never reach for the language's built-in random — it's different every run and you can never get that run back. + +Second, **no dependence on the wall clock.** This is the other half of *deterministic* from Section 5: if your logic asks "what time is it right now?" or advances by however many milliseconds happened to pass, your game does something slightly different every run and on every machine. Instead, advance the simulation by fixed steps you control. Then you can run the whole thing offline, fast, headless, a thousand times, and it's identical each time. This is also what lets an automated check re-run your entire scene and *prove* nothing overlaps — because "the scene" is a pure function of its data, not of when you happened to press play. + +One more discipline that sounds obvious and isn't: **never move a placed object "by eye" without re-running your checks.** On that same prototype, someone nudged a trailer to make a shot look better — and quietly parked it on top of a path a character walked. It was only caught because a checker re-ran against the one obstacle list. If you move something, re-validate. A five-second nudge can silently break a path you validated an hour ago. + +**The test:** Delete one obstacle from your world data and run the game. Both the picture *and* the movement rules should change together — the thing should stop being drawn AND stop blocking. If only one changes, you have two lists, and they will drift. Separately: run the same seed twice and confirm you get a byte-for-byte identical result. + +**Watch out for:** +- **The second list nobody maintains** — a "collision list," "minimap list," or "AI targets list" that's a hand-kept copy of the real one. Copies drift. Derive them from the one source instead. +- **"It happened once"** — if a bug can't be reproduced, the real bug is that your game isn't deterministic yet. Fix the reproducibility before you chase the ghost. +- **Eyeballed moves** — repositioning a placed object without re-running the check that depends on it. The move takes five seconds; the silent break costs an afternoon. + +--- + +## 10. Measure speed on the device you'll ship on + +Every game has a speed budget. (*frame budget / fps* = how many times per second the game redraws; "fps" = frames per second; higher is smoother — 60 fps feels smooth, 30 is playable, below that starts to feel bad.) The whole point of this section is one uncomfortable truth: **a speed number from anywhere except the actual device you'll ship on is a floor, not a verdict.** + +Here's what that means in practice. On one real prototype, the automated test setup ran the game with software rendering — that's the graphics done by the main processor instead of the graphics chip, which every automated/headless environment falls back to. That setup reported about 11 fps. Alarming. Looked like the whole approach was too slow to ship. But when the owner opened the exact same scene on their actual computer with a real graphics chip, it ran at around 120 fps. That's more than a tenfold difference for *identical code*. + +If they'd trusted the 11, they'd have "failed" a design that was actually more than fast enough — and possibly thrown away weeks of good work, or bloated the schedule ripping out things that were never the problem. The slow number wasn't wrong, exactly. It was a real measurement of the real scene on the wrong hardware. Which makes it useful for one thing only: as a **floor** — a worst-case reading you can watch for regressions in your automated tests — and useless as the actual answer to "is my game fast enough?" + +So the rule is blunt: **the verdict about speed comes from the real target device, and only from there.** Shipping to phones? The number that matters comes from a mid-range phone in your hand, not a simulator on your beefy laptop. Shipping to a specific console or a five-year-old laptop? Measure there. Your dev machine is almost always faster than what most players own, so a number from your dev machine is *also* a floor, just a friendlier-looking one. + +Two practical habits make this cheap. + +**Instrument from day one.** (*instrument / profiling* = measuring speed and memory while the game runs.) Put a little fps counter on screen from the very first playable build — before art, before anything. It costs about fifteen lines. Then every version you look at comes with a number attached, and you'll notice the day something got slow, instead of discovering it a month later when the trail is cold. On that prototype the fps counter existed from the first build and never changed — so every review checkpoint had a real number, for free. + +**Capture the metrics you promise.** This is a discipline failure that's embarrassingly common: someone writes "we'll measure triangle counts, draw calls, and memory" in a plan, and then nobody ever does, and the empty checkbox sits there forever pretending it's covered. On the prototype above, a preflight doc listed exactly those numbers as required — and not one of them was ever actually recorded. The speed verdict ended up resting entirely on eyeballed fps with no geometry budget behind it. So: either capture the number, or delete the promise. Don't leave a "we'll measure performance later" checkbox unchecked and let it launder as done. If you say you'll measure draw calls, most engines hand you that number in one line — capture it, write it down, and now you have something to regress against. + +A subtler point that will save you real grief: **a single number is a coarse pass/fail, not a benchmark.** That ~120 fps figure was one rounded eyeball reading, almost certainly capped by the monitor's refresh rate, reused across every test scenario. It was completely trustworthy for answering "are we comfortably above the bar?" (yes, obviously) — and completely useless for answering "did this change make us 8% slower?" (can't tell; the number's capped and rounded). If you want to track small changes over time, measure with an uncapped, precise counter. If you just want to know whether you're in the safe zone, one clear reading on the real device is plenty. Know which question you're asking. + +Last thing, and it's a mindset: **protect your headroom, don't spend it.** When you find you have lots of speed to spare, the temptation is to fill it — more effects, more objects, more detail. Resist a little. On that prototype the single biggest cost by far was one high-resolution shadow-casting light, not the characters or the buildings — so the first lever if speed ever got tight was "turn down the shadow," not "cut content." Know your one biggest cost, keep a margin, and don't fund every shiny idea out of it. The margin is what absorbs the stuff you can't predict yet. + +**The test:** Point at a number and say out loud what device produced it. If that device isn't the one your players will use, you have a floor, not a verdict — and you owe yourself a real reading on real hardware before you make any decision that trades away work. + +**Watch out for:** +- **Reading a software-render or dev-machine number as the answer** — it can be off by 10x in either direction. Treat it as a floor, get the real reading before you decide. +- **The unchecked "we'll measure it" box** — if you promised triangles/draw calls/memory, capture them or cut the line. An unmeasured promise is a lie you told yourself. +- **Spending all your headroom the day you find it** — leave a margin for the things you haven't hit yet. + +--- + +## 11. Borrow the background, build the identity + +At some point you need things to look and sound like a real game, not gray boxes. This section is about spending that effort where it counts — and a hard truth about what you can and can't buy. + +Split your world into two layers. + +**The supporting layer** is the stuff that makes your world feel lived-in but that no player will remember: background props, generic crowds, ambient scenery, common sound effects, filler UI. You should *borrow* this. Grab one coherent family of ready-made assets — free or cheap, from a single source so they share a look — and use it wholesale. + +**The identity layer** is the handful of things that *make your game your game*: the thing on the box, the silhouette a player recognizes in a screenshot, the signature mechanic's feedback, the one landmark or character or sound that says "oh, that's *that* game." You have to **build** this yourself. It cannot be downloaded. + +That second sentence is the whole lesson, and it's worth proving. On one real prototype, the team took a big, coherent pack of decent generic assets and carefully arranged them into what should have been the game's signature location. It came out looking like a plausible, pleasant... generic place. Not the specific place it needed to be. An independent reviewer's honest verdict was that this expensive arrangement of bought assets was **no more recognizable than the original gray boxes had been.** Buying a *bigger* asset pack would not have fixed it. Identity comes from bespoke, made-for-this silhouettes and details — and the moment the team spent their effort authoring those custom landmarks instead of shopping for them, the place finally read as itself. + +So: borrow the dressing, build the identity. The generic family makes the world feel populated at near-zero cost. Only the custom pieces make it *yours*. + +Now, three rules that keep this from blowing up on you. + +**Check the license BEFORE you download — not before you ship.** (*provenance* = a written record of where an asset came from and what license lets you use it.) Decide up front which licenses you'll accept, and only download things that clearly qualify. For each asset you keep, write one line: where it came from, the license, the version, what you changed. Do this at download time, while you have the tab open — not in a panic the week before release when you're trying to reconstruct where forty files came from. On that prototype every asset's license was confirmed *twice* — the bundled license file and the live source page — before it ever entered the scene, and every asset got a row in a provenance file. Result: zero "wait, are we even allowed to use this?" panics, ever. + +**Keep reference art out of your shipped game.** Concept images, mood boards, screenshots of other games you looked at for inspiration, anything AI-generated you used to think with — those are reference. They inspire your work; they do not *become* your work. Never let a reference image sneak in as an actual texture, a traced shape, or a background. Build a firewall in your own head: reference stays in the reference folder and never crosses into shippable content. + +**Run a small "can we even get this?" survey before the big art push.** Before you commit weeks to production art, spend a little time proving you can actually obtain or make the make-or-break pieces. The prototype above did this and learned early that generic assets couldn't carry the identity — which redirected the whole art plan *before* the expensive push, not after. Cheap to check; brutal to discover late. + +Finally, the character-quality trap, stated honestly. Cheap placeholder characters — rigid, blocky, jointed figures that snap at the joints rather than bending smoothly — are genuinely fine for background and crowd. On that prototype, a family of blocky jointed figures worked well for distant crew and drivers, and one figure was shared and copied across a whole crowd for almost no cost. **But those same figures were explicitly ruled out for anything a player looks at up close.** A hero character in a close-up needs a genuinely different, higher-fidelity pipeline — a smoothly-deforming ("skinned") rig, real detail, per-character distinctiveness. That is a separate, later, bigger job. Do not let "the cheap crowd characters look fine" fool you into thinking your close-up hero problem is solved — it's a different problem, and you validate it separately, later. Be honest in your notes about which characters are placeholder-forever and which ones still need the real pipeline. Calling a blocky jointed figure a finished hero rig is exactly the kind of overclaim that ambushes you at the worst moment. + +**The test:** Show someone a screenshot with all the borrowed dressing but your identity pieces still gray-boxed. If they can't tell what game it is, your identity layer is the real work — and no asset store will do it for you. Separately: pick any asset in your build and produce, in ten seconds, the one line saying where it came from and that you're allowed to use it. + +**Watch out for:** +- **Trying to buy identity** — a bigger asset pack makes the background nicer, not the game more recognizable. Identity is bespoke. +- **License-checking after you're attached** — decide your allowed licenses and log provenance at download time, or you'll be ripping out a favorite asset at the worst possible moment. +- **Mistaking a cheap crowd rig for a finished hero** — background characters and close-up characters are two different pipelines; prove the hero one separately and later. + +--- + +## 12. Review gates, and knowing when to stop + +You've built a slice. Now: is it actually good, and are you done? This section is the checkpoint — the "gate" — that answers both, and the vocabulary for deciding what happens next. + +Use **two stages**, in order, and don't skip either. + +**Stage one: an outside pair of eyes, for correctness.** Someone who did *not* build the slice checks it — ideally using their own tools, not just reading your notes. Does the logic hold? Is the prototype actually isolated from your real project? Is anything leaking? Are the licenses clean? The key word is *independent*: a reviewer who just re-reads your own claims back to you is a rubber stamp, not a review. On one real prototype, the independent reviewer re-ran the isolation check from their own shell, re-parsed the asset files themselves, and scanned for problems the builder hadn't looked for — "not the builder's word for it" — and caught a genuine memory leak the builder had missed. That's what independence buys you. + +**Stage two: the owner — you — on the real device, for feel.** Some things no automated check and no outside code-reviewer can judge: does it *feel* good, does it *read* clearly, is it actually fast on the target hardware. On that same prototype, the outside reviewers — sharp as they were — *missed* that imported characters were about 1.5x too tall. It looked plausible enough on paper, and a bounding-box measurement had been waved away as a technical artifact. Only the owner, looking at the character next to a known-size reference on the real device, caught it. And only the owner produced the real frame rate (the 10x-higher-than-CI number from Section 10). Feel, scale, and true speed are human-on-real-hardware judgments. Keep that stage. + +When a gate finishes, give it a **clear verdict** — one of exactly four, so "can we keep going?" is never ambiguous: + +- **Fail** — a load-bearing claim turned out false, or a defect kills the whole point of this slice. This is an *allowed* outcome. A prototype that honestly fails has done its job: it saved you from building the wrong thing. Say it plainly and stop. +- **Conditional-Pass** — there's a real behavior or correctness bug you must fix *before* going further. Not cosmetic. You fix it, then continue. +- **Pass-with-notes** — only cosmetic or wording issues remain. Safe to proceed; clean them up whenever. +- **Pass** — the outside review is clean AND the owner confirmed it on the real device. Fully done with this gate. + +Why bother with four words instead of a thumbs-up? Because on that prototype, everything got labeled "pass with corrections" whether the correction was a real memory leak or a typo in a doc. A reader couldn't tell at a glance whether a gate had found something serious. Splitting "you must fix this first" (Conditional-Pass) from "just tidy the prose" (Pass-with-notes) makes the state of your project honest and scannable. + +Now the discipline that matters most: **one bounded fix pass, then stop.** When a gate turns up problems, fix *those* problems — and only those — in one focused pass. Then freeze what's proven and stop. Do not let "while I'm in here" turn one fix pass into a second unplanned build. Freeze the proven core and iterate *behind* it. On that prototype, once the camera framing was blessed, it was frozen and never touched again — every later change was evaluated against a framing that was already known-good. That freeze is why later work never accidentally broke the thing that already worked. + +And the hardest skill in this whole handbook: **knowing which of four things to do next.** + +- **Continue** — the slice passed and answered its question with a yes. Move to the next question. +- **Defer** — a real piece of work is needed, but not now. *Write it down as a backlog item* and move on. Deferring is only honest if it's written down. A deferral you keep in your head is just a thing you'll secretly start building. On that prototype, a whole class of camera problem was correctly identified, scoped, named, and written down as a future task — and deliberately *not* built on the spot. That's the model: name it, park it, don't sneak-build it. +- **Rewrite** — the idea is sound but this implementation is fighting you. Rewrites are cheapest when the thing is small and gray-boxed, which is exactly why you prototype small. +- **Abandon** — the question got answered with a no. This is a win, not a failure. You spent a little to avoid spending a lot. The whole method exists to make "abandon" cheap and early instead of expensive and late. + +One last distinction, because it decides whether you should feel bad. **Normal defects are not process waste.** When you integrate real art and a surface flickers, or something vanishes at a weird camera angle, or a new asset renders wrong — that's expected discovery cost. You find it, you fix it, you move on. That is *normal*, and it will keep happening no matter how good you get. **Preventable waste is different:** redoing work because two lists drifted apart, chasing a moving target with a brittle check, catching a scale error a month too late. The first kind you accept as the cost of making things. The second kind is exactly what the rest of this handbook helps you not do. Don't beat yourself up over the first. Don't excuse the second. + +**The test:** After a gate, you can state — in four words or fewer — the verdict (Fail / Conditional-Pass / Pass-with-notes / Pass) and the decision (Continue / Defer / Rewrite / Abandon). If you can't say both crisply, you haven't actually finished the gate. + +**Watch out for:** +- **The reviewer who just re-reads your claims** — that's a rubber stamp. Independence means they use their own tools and try to break it. +- **The fix pass that becomes a second build** — fix what the gate found, freeze, stop. "While I'm in here" is how a checkpoint eats a week. +- **The deferral you don't write down** — an unwritten "later" is a thing you'll secretly build. Park it in the backlog, visibly, or you didn't really defer it. + +--- + +## 13. Directing AI coding agents + +Most of this handbook works whether you write the code yourself or an AI agent writes it. This section is about the case where an agent does the building — because directing an agent well is a genuine skill, and doing it badly wastes more time than doing it yourself would have. + +Start with **three roles that must stay separate.** + +- **The Builder** — the agent doing the work. It writes the code, implements the mechanic, runs its own tests. It is also, structurally, the *worst* judge of whether the work is done, because it's invested in "done" and blind to the defects its own mental model can't see. +- **An independent Reviewer** — a *different* agent (or a person) who did not build the slice, checking correctness and isolation with their *own* tools. The builder cannot review itself for the same reason you can't proofread your own writing cold. +- **You, the owner, on the real device** — judging feel, clarity, and true speed. No agent, however good, can feel your game or produce a real frame rate on real hardware. That's yours. + +Keep these apart. When they collapse into one — when the builder grades its own homework — you get confident reports of success sitting on top of real defects. + +The heart of good direction is **a tight brief.** Give the Builder, up front, in roughly this order: + +1. **Context** — what this is and why it exists, in a couple of sentences. +2. **Verified starting state** — the actual current state of the code, re-checked at the start, never trusted from memory. (More on this below — it matters more than it sounds.) +3. **The one question** — the single thing this session is proving, with a real pass/fail. (Straight from Section 2.) +4. **Authorized scope** — exactly what it may build. If it's not listed, it's not authorized. +5. **A HARD do-not-build list** — enumerated, explicit, verbatim. This is the single most powerful line in the brief. A vague "keep it focused" can be rationalized around; an itemized "do not build: saving, networking, the economy, any integration into the real app" cannot. On one real prototype, when the agent's instinct was to wire the throwaway into the live application "to make the demo real," the do-not-build list had already forbidden exactly that — so the correct move was the *only* move available. List the temptations by name. +6. **Milestones** — the checkpoints, marked *provisional*, with the agent required to tell you the *actual* plan as it goes. On that prototype the real milestone map diverged from the written plan (a survey step got inserted mid-flight); a reader trusting the original plan would've been misled. +7. **How you'll judge it** and **how it'll be tested** — name the verification, and be brutally honest about what the tests do and don't cover. If "the tests" are a script you run by hand with no automated enforcement, say so. Otherwise "all tests pass" will read as far stronger than it is. +8. **What evidence to produce** — screenshots, a recording, a short playtest clip. Name the artifacts up front. +9. **When to stop** — an explicit halt, so a passing checkpoint isn't read as permission to keep going. + +Two rules sit on top of the brief and matter enormously. + +**Check for contamination structurally, not by memorizing a version number.** You'll want to make sure the prototype's code isn't leaking into your real project. The tempting-but-wrong way is to pin an exact version ("the real project is at commit X") and treat any change as an alarm. That breaks immediately: your real project keeps moving for legitimate reasons, so the check screams "drift!" constantly, you re-pin it over and over as pure busywork, and eventually you train yourself to ignore a guard that cried wolf. On one prototype this happened exactly this way — the pinned-version check went red every time the real project made unrelated progress, got manually re-pinned three times, and is *now stuck red* because nobody re-pinned it again. It never once caught real contamination; it only ever caught its own staleness. Do it structurally instead: check that *no prototype files or imports exist anywhere in the real project*, and that the prototype stays in its own isolated home. That check goes red only for *actual* leakage — never for your real project simply advancing. + +**Make the agent SHOW you it working.** "The tests pass" is not proof the game plays right. On that prototype, the load-bearing bugs — a scale error, invisible bodies from a material glitch, characters getting wrongly hidden up close — were *all* found by looking at captured screenshots, not by any test. Tests check the things you already thought to check. A screenshot or a recording or a two-minute playtest catches the thing you didn't. So require the visual evidence, look at it yourself, and after any "done," ask the plain question: *did that actually work?* — then re-run the check yourself. Treat every "done" as a claim to verify, not a fact to accept. + +For **bigger jobs, use a fan-out pattern** — it's how you get many agents working without producing a mess: + +1. **Several evidence agents, read-only, in parallel** — each gathers facts about part of the problem. They *only* gather; they make no decisions and change nothing. Because they can't collide (nobody's writing), they run at the same time safely. +2. **You lock the decisions** — take their findings and commit to one plan, one set of shared constants, one shape everyone will follow. This locked spine is the thing that keeps the parallel work from drifting. +3. **Several build/write agents in parallel** — each expands one slice of the locked plan. Because the spine is fixed and their slices don't overlap, they move fast and don't step on each other. +4. **One agent checks the whole thing for consistency** — a final adversarial pass over all the parallel work, looking for the seams where two slices disagree. + +The locked spine in step 2 is the trick. Many parallel writers cannot stay consistent by good intentions; they stay consistent because they're all reading the same locked decisions. (This is the same "one source of truth" idea from Section 9, applied to your *process* instead of your world data.) + +Finally, **handoff notes**, because agent sessions end and you'll lose your place. Keep two short living documents — one saying **CURRENT STATE** (what's true right now: where the code is, what's done, what's open) and one saying **NEXT ACTION** whose very first step is *"re-confirm reality matches this note before doing anything."* On that prototype, when a session was lost, recovery worked precisely because state lived in notes outside the code that re-verified the actual project state at the top before trusting anything. Write the note so a cold-start session re-checks reality first and trusts nothing from memory. Memory goes stale; a note that re-verifies doesn't lie to you. + +**The test:** Hand your brief to a fresh agent (or read it as if you were one). Can it tell, without asking you, what to build, what NOT to build, how it'll be judged, what to show you, and when to stop? And when it reports "done," do you have a screenshot or recording you looked at yourself — not just a green checkmark? + +**Watch out for:** +- **The builder grading its own homework** — keep an independent reviewer and your own real-device check separate from the agent that built it. +- **Pinning a version number as your contamination guard** — it goes stale, cries wolf, and trains you to ignore it. Check structurally for leaked files instead. +- **Accepting "the tests pass" as proof it plays right** — make it show you working footage, and re-ask "did that actually work?" yourself. + +--- + +## 14. Adapting this to your genre + +Everything so far has leaned on visual, spatial examples — cameras, scale, characters. If you're building a card game or a text sim, you might be wondering how much of this is even for you. Answer: the *method* is universal; the *emphasis* is genre-specific. Here's the split. + +**Universal — applies to every genre, no exceptions:** turn your idea into one testable question with a real stop condition (Section 2). Build the cheapest *complete* loop before art (Section 5). Put a real person on it before you spend on polish (Section 6). Keep your rules separate from your presentation (Section 8). Keep one source of truth for your world data and make it reproducible with seeded randomness (Section 9). Two-stage review, then stop (Section 12). Direct your agents with a tight brief and a hard do-not-build list (Section 13). Those are load-bearing everywhere. + +**Genre-specific — dial the depth up or down:** the heavy chapters on scale, camera, occlusion, character pipelines, and shipping-device speed (Sections 7, 10, 11) matter enormously for a 3D action or city game and *barely at all* for a pure text or card game. Don't perform ceremony that doesn't apply to you. A word game does not need a scale-reference test. Be honest about that and spend the saved time on what your genre actually risks. + +Here's what to prove first, per genre — the smallest thing that earns an honest reaction: + +- **Action** — a character you control, one threat, input-to-feedback at a smooth frame rate. Prove: does moving and fighting *feel* good? (This genre leans hard on Sections 7 and 10.) +- **Simulation / Management** — one resource, one decision, a consequence you can read. Prove: can a new player form a plan? (Leans on Section 8's clean rules and Section 9's readable state.) +- **Strategy** — one real decision with a real counter. Prove: is it expressive, or is there one obvious best move? +- **Sports / Roster** — evaluate, sign, field, result, with a *tiny* roster. Prove: does it stay clear as the roster grows? +- **RPG** — one build choice, one fight, one payoff. Prove: does progressing feel like it's *yours*? +- **Narrative** — one branch whose consequence a fresh player actually notices. Prove: does the choice create ownership? +- **Racing** — one stretch of track and a handling model. Prove: is it fun *near the limit* of control? (Leans on Sections 7 and 10.) +- **Multiplayer** — two players, one authoritative host, one contested moment. Prove: is it fair and consistent *with lag*? (This is your make-or-break; prove it before content.) +- **Mobile / Touch** — one core interaction sized for thumbs, on a *real* phone. Prove: readable and reachable one-handed? (Leans hard on Section 10 — measure on the actual phone.) +- **Roguelike** — one *seeded* run, a few rooms, death, a little meta. Prove: is run-to-run variety meaningful? (Leans hard on Section 9 — seeded runs are the whole thing.) +- **Puzzle** — one rule set and three handmade puzzles. Prove: is the "aha" reachable and fair, with no guessing? +- **Card / Deckbuilder** — a small deck, a few turns. Prove: is the play expressive, not already solved? +- **City-builder** — one build, simulate, feedback tick. Prove: can players *see* cause and effect? (Leans on Sections 8 and 9.) +- **Social-deduction** — one round of hidden roles. Prove: does the information create useful doubt? +- **Tactics** — one small-grid skirmish. Prove: can players read the board and plan two moves ahead? + +Notice the pattern: every genre's "prove first" targets *the one thing most likely to be un-fun or unfair* — the handling in racing, the netcode in multiplayer, the decision space in strategy, the run variety in a roguelike. That's not the flashiest part; it's the *riskiest* part. Point your cheapest complete loop straight at it. + +**The test:** For your specific genre, name the one thing that, if it isn't fun or fair, sinks the whole game — and confirm your first prototype points directly at *that*, not at the easy, always-works dressing around it. + +**Watch out for:** +- **Performing ceremony from another genre** — a text game doesn't need a scale test; a puzzle game doesn't need a camera pass. Skip what doesn't apply. +- **Prototyping the safe part** — building the part that always works (the menu, the dressing) instead of the risky part (the handling, the netcode, the decision space). +- **Assuming "universal" means "identical depth"** — the method is universal; how deep you go into each section depends on what your genre actually risks. + +--- + +## 15. Common ways this goes wrong (and how to catch it early) + +Every trap in this section is real and cost someone real time. For each: the trap, the early warning sign, and the guard. + +**Reading a fake-renderer or dev-machine speed as real.** You measure speed in an automated environment or on your fast dev box, see a number, and make a decision on it. *Early warning:* you can't say, out loud, which device produced the number. *Guard:* a number from anywhere but the real target is a floor, not a verdict — get the real reading before you decide (Section 10). On one prototype, a software-render reading of ~11 fps sat next to a real-hardware reading of ~120 for identical code. Trusting the 11 would've killed a design that was more than fast enough. + +**Chasing a moving target with a brittle check.** You guard your project by pinning "the other thing is at version X" and alarming on any change. *Early warning:* you're re-pinning the same check by hand, again, for the third time, and it's never actually caught anything. *Guard:* check *structurally* — is any prototype code leaking into the real project? — not by memorizing a version that goes stale the instant the other work advances (Section 13). This is *preventable waste*, not normal cost. + +**Letting the "what's drawn" list and the "what blocks movement" list drift apart.** Two separate lists that are supposed to agree, maintained by hand. *Early warning:* you can see something but walk through it, or you're blocked by nothing. *Guard:* one source of truth that both drawing and rules read from; adding a thing to the world adds it to both by construction (Section 9). Also preventable waste. + +**Moving something "by eye" and breaking a path.** You nudge a placed object to make a shot look nicer and silently park it on top of a route. *Early warning:* you moved something and *didn't* re-run your checks. *Guard:* never reposition a placed object without re-validating against the same data your checks read (Section 9). + +**Catching a scale error late.** Imported art is the wrong size, and nobody notices until it's fully dressed and viewed on the real device. *Early warning:* you've placed new art but never stood it next to a known-size reference on real hardware. *Guard:* always put a known-size reference next to new art and look at it on the actual target device, early (Section 7). On one prototype, characters came in about 1.5x too tall, a bounding-box reading was waved off as a "measurement artifact," and only the owner-on-hardware caught it — after the scene was already dressed. That rework was preventable waste. + +**Polishing art before the loop is fun.** You start making things pretty before a boxes-and-capsules version is even a little bit fun. *Early warning:* you're picking colors and you haven't run a single player test. *Guard:* prove player value on the gray-box first; prettier art won't save an un-fun loop, it'll just cost you a month first (Sections 5 and 6). + +**Over-documenting a throwaway.** You write pages of docs for a prototype you'll discard, and restate the same fact in five places. *Early warning:* you've written the same number into five different files. *Guard:* single-source each fact, cite where it lives, and keep throwaway docs light (Section 12's freeze-and-move-on spirit). On one prototype, a single speed number was restated across five documents — five places to update, five chances to drift. + +**Assuming a cheap character rig is production-ready.** The blocky background crew looks fine, so you assume your close-up hero is handled. *Early warning:* you're describing a rigid, jointed placeholder as if it were a finished, smoothly-deforming hero rig. *Guard:* background characters and hero close-ups are two different pipelines; the cheap one is fine for crowds and a separate, later, higher-fidelity job for heroes — validate it on its own (Section 11). On one prototype a blocky jointed figure was explicitly *good enough* for distant crew and explicitly *not approved* for anything up close; conflating the two would've promised a hero quality that didn't exist. + +Here is the distinction that ties the whole section together, because it decides how you should feel when something breaks. + +**Normal defects are the expected cost of making things.** Surfaces that flicker where they overlap, an object that vanishes at a weird camera angle, a new asset that renders wrong the first time you integrate it — these show up the moment real art meets a moving camera, and they'll keep showing up no matter how experienced you get. You find them, you apply a standard fix, you move on. Budget for them. Don't feel bad about them. + +**Preventable waste is the stuff this handbook exists to stop.** Redoing work because two lists drifted. Re-pinning a brittle check that never caught anything. Discovering a scale error a month late. Restating one fact in five files. These aren't the cost of making things — they're the cost of *not* front-loading a few cheap disciplines. When you hit one, don't shrug it off as "just game dev." Name it, fix the *process* that let it happen, and it won't happen twice. + +The skill is telling the two apart in the moment. A flickering surface after art integration? Normal — fix it, move on. A path that broke because you moved a prop by eye? Preventable — and now you know to re-validate every move. + +**The test:** When something breaks, you can immediately say whether it's a normal defect (accept it, fix it, move on) or preventable waste (fix the process, not just the symptom). If you're treating preventable waste as "just how game dev goes," you're paying a tax you don't have to. + +**Watch out for:** +- **Blaming yourself for normal defects** — flickering surfaces and first-integration art bugs are expected discovery cost, not failure. +- **Excusing preventable waste as "normal"** — drifted lists, brittle checks, and late scale errors are exactly what a little up-front discipline removes. +- **Ignoring the early warning signs** — every trap here announces itself (an unowned second list, a re-pinned check, un-referenced new art). The signs are cheap to notice if you're looking. + +--- + +## 16. A realistic timeline, and what "faster" means + +Let's put a real number on "faster," because vague promises help no one. + +Here is the evidence. A focused, well-scoped visual proof — an entire vertical slice of a real-time 3D game: camera, a complete moving scene, characters, borrowed dressing, custom identity pieces, and three adversarial review checkpoints — was executed in **one continuous session of a little under five hours.** Not five days. Not five weeks. One sitting. The milestone structure *reads* like a multi-week project, but the record says the "milestones" were review checkpoints inside a single afternoon. + +Sit with that, because it reframes the whole handbook. All the gating discipline, the two-stage reviews, the freeze-the-proven-core habit — none of it is heavyweight process that slows you down. It all fit inside one session and is *why* the session produced a trustworthy answer instead of a pile of hopeful code. Heavy discipline and going fast are not opposites. The discipline is what *makes* you fast, by stopping you from building the wrong thing. + +So what does "faster" actually mean? It means **learning sooner and wasting less** — not skipping steps. You reach the honest yes-or-no on your idea in hours instead of weeks. You find out on a gray box, for almost nothing, whether the loop is fun. "Faster" is about the *earliness of the verdict*, not about cutting corners to ship sooner. + +**What compresses the timeline** — front-load these and you save real time: + +- **Front-load your scale, camera, and input standards.** The single most repeated waste on that prototype was fixing scale *late*. Pulled forward to the very start, it removes an entire rework pass and the follow-on bugs that came with it. +- **Front-load your world-data model.** Decide on the one source of truth for positions and obstacles up front, with the checker reading the same data, and you never suffer the drifted-lists rework at all. +- **Use a light structural isolation guard, not a brittle version pin.** Set up the "no prototype files leaked into the real project" check once and it just works; the brittle alternative cost three rounds of pure busywork on that prototype and still ended up broken. + +**What you must NOT skip** — these are load-bearing, and cutting them doesn't make you faster, it makes you wrong: + +- **The complete gray-box loop.** The whole method rests on proving the loop before art. Skip it and you're back to spending a month on pretty before you know if it's fun. +- **A real-player test on the real device.** The developer loving it isn't evidence. And the owner-on-real-hardware catch (scale, feel, true speed) is exactly the class of problem no shortcut and no automated check will find for you. +- **The make-or-break content survey.** Before the big art push, prove you can actually get or make the pieces that carry your game's identity. On that prototype this survey is what revealed — early and cheaply — that generic assets couldn't carry the identity. Skip it and you learn the same thing expensively, after the push. + +With the compressions above folded in, a proof like that plausibly runs in a bit more than *half* the time — the front-loaded invariants remove the reworks that ate the difference. That's the honest shape of "faster": same steps, fewer do-overs. + +And the honest **uncertainties**, stated plainly so you don't mistake a fast proof for a finished game. That five-hour session proved the *slice* — it did not build the game. Two costs specifically remain separate and larger: the **hero-character pipeline** (the smoothly-deforming, close-up-quality characters from Section 11) was explicitly *not* validated and could be a big job on its own; and **real integration into the finished game** is its own separate effort, not something a throwaway prototype delivers. A fast, trustworthy *proof* is a genuine, valuable thing. It is not the same as a shipped game, and pretending otherwise is exactly the "misleading success" this whole method is built to prevent. + +**The test:** You can point at the parts of your process you *front-loaded* to go faster (scale, world-data, isolation) and the parts you *refused to skip* (the gray-box loop, the real-device player test, the content survey) — and you're honest that a fast proof is a proof, not a finished game. + +**Watch out for:** +- **Reading "faster" as "skip the loop or the player test"** — those are the load-bearing steps; cutting them makes you wrong sooner, not done sooner. +- **Mistaking a proven slice for a shipped game** — hero content and real integration are separate, larger costs you haven't paid yet. +- **Skipping the make-or-break survey to "save time"** — you'll learn the same lesson later, at many times the cost. + +--- + +## 17. Putting it all together + +Here is the whole method, in order. Nothing new — just the sequence, so you can see the shape of it start to finish. + +1. Turn your idea into **one testable question** with a real stop condition. +2. Choose the **cheapest valid prototype form** that can answer it. +3. Write the **prototype brief** — including the hard do-not-build list — before you build anything. +4. Build the **complete gray-box loop**: the whole loop, tiny and ugly, in placeholder shapes. +5. Lock **scale, camera, input, interaction** early, and check them on the real device. +6. Keep your **rules separate from your presentation**, with one source of truth for world data, made reproducible with seeded randomness. +7. Put a **real person on it** — the eight-question player test — before you spend on art. +8. **Borrow the background, build the identity** — check licenses first, survey the make-or-break content before the big push. +9. Run the **two-stage gate** (outside eyes for correctness, you on the real device for feel), give a **clear verdict**, do **one bounded fix pass**, and **stop** — Continue, Defer, Rewrite, or Abandon. +10. If agents are building, **direct them with a tight brief**, check contamination structurally, and make them show you it working. + +Now watch it run in two very different genres. + +**A small management game.** *Question:* "Can a new player make a meaningful resource decision in under two minutes and read its consequence?" *Prototype form:* a mocked-up screen or even a spreadsheet — no art, no engine, this genre barely touches scale or camera. *Gray-box loop:* one resource, one decision that spends it, one consequence you can plainly read, and a reset. Rules kept separate from the display; the world state in one place; the same numbers driving the screen and the logic. *Player test:* hand it to someone; watch — don't coach. Ask what they thought they were supposed to do, what they actually did, whether the consequence was clear. If they can't form a plan, the decision space is too murky. *Gate:* you (owner) judge whether it *reads*; there's no real device speed issue here, so Stage two is mostly "is it understandable." *Verdict and decision:* if a fresh player forms a plan and reads the consequence — Pass, Continue to a second decision. If the consequence is invisible — Conditional-Pass, fix the readability, re-test. If nobody can ever form a plan even after fixes — that's an honest Abandon, and you've spent an afternoon instead of a season. + +**A small action game.** *Question:* "Does moving and hitting things feel good with one character, one threat, and responsive controls?" *Prototype form:* an engine sandbox with boxes and capsules — this genre leans *hard* on scale, camera, input, and real-device speed. *Gray-box loop:* one capsule you control, one threat that can hurt you, input-to-feedback at a smooth frame rate, a failure state, and a reset. Lock the scale (a known-size reference next to your capsule, checked on the real device), the camera distance, and the control response *first* — before any environment art. Put the fps counter on screen from frame one. *Player test:* watch someone play; the question isn't "did they win," it's "did moving feel good, did hitting feel satisfying, did they want to try again." *Gate:* outside eyes confirm the code's clean and isolated; then you, on the *actual target device*, judge feel and true speed — because a smooth number on your dev box is only a floor. *Verdict and decision:* feels good and runs smooth on target — Pass, Continue. Feels floaty — Conditional-Pass, tune the input, re-test. Fundamentally not fun even with tuning — Abandon, cheaply, on a capsule, before you ever paid for art. + +Notice how the *same ten steps* produced two completely different-looking processes — a spreadsheet in one case, an engine sandbox in the other; a "does it read?" gate in one, a "does it feel good on the real phone?" gate in the other. That's the method working as intended: universal spine, genre-specific depth. + +A closing word, and I'll be honest with you. This method will not make a mediocre idea good. What it will do is tell you — fast, cheaply, and honestly — *which* of your ideas are worth your real time, and get the boring, load-bearing version of a good one playable before you spend a season making it beautiful. Most of the discipline here exists to protect you from the most expensive mistake in game development: falling in love with something that was never going to be fun, and finding out a year and a pile of art too late. + +You do not need a big team or years of experience to work this way. You need one honest question at a time, the willingness to let a real person tell you the truth, and the discipline to stop when you've got your answer. Build the cheapest complete thing that can prove you wrong. Let someone play it. Fix only what blocks an honest verdict. That's the whole game. Now go build the ugly version — and find out. + +--- + +## Appendix A — The prototype brief (blank, copy-ready) + +Fill this in *before* you build. If you can't fill a line, that's a gap to resolve first. + +``` +1 PRODUCT QUESTION + The single falsifiable question this prototype answers. + (Has a clear pass AND a clear fail. If it can't fail, rewrite it.) + +2 TARGET PLAYER REACTION + The specific reaction a real player must have for this to be a "yes." + +3 AUTHORIZED SCOPE + Exactly what this prototype may build. Nothing implied. + +4 EXPLICIT NON-GOALS (the hard DO-NOT-BUILD list) + Enumerated, by name. List the temptations you must NOT build. + +5 TIMEBOX + How long this gets before you stop and judge it. + +6 REQUIRED SYSTEMS + The minimum systems needed for the loop to be complete. + +7 PLACEHOLDER POLICY + What stays fake / simplified / absent, and stays that way. + +8 EVIDENCE REQUIRED + What artifact proves it (screenshot / recording / playtest notes). + +9 PASS CRITERIA + What result counts as "yes, continue." + +10 STOP CONDITIONS + Where you halt — including "it passed, now await a decision." + +11 REPOSITORY BOUNDARY + Where the prototype lives and how it structurally CANNOT hurt the + real project (isolated home; no prototype files leak into the real one). + +12 OWNER DECISION REQUIRED + The specific decision you (owner) must make at the end. +``` + +--- + +## Appendix B — The first player test (script) + +Hand the person the build. Do NOT explain it. Do NOT coach. Watch what they do, and only ask afterward. Your job is to stay quiet and take notes. + +``` +Before: say only "play this and think out loud." Nothing more. + +Watch silently. Note where they hesitate, where they smile, where +they get stuck, and where they do something you didn't expect. + +After they play, ask — in order — and just listen: + +1 What did you think you were supposed to do? +2 What did you actually do? +3 What felt satisfying? +4 What felt confusing? +5 What did you expect to happen (that maybe didn't)? +6 What surprised you? +7 Did you want to try again? +8 Was anything stopping you from giving an honest verdict? + +Sort what you heard into: + technical success (did it run?) + usability (could they operate it?) + comprehension (did they understand it?) + fun (did they enjoy it?) + emotional value (did they feel ownership / want more?) + replay (did they want another go?) + +Remember: YOU loving it is not evidence. Their honest reaction is. +``` + +--- + +## Appendix C — Day-one standards (one-screen checklist) + +Stand these up at the *start*, not as later patches. Skip the lines that genuinely don't apply to your genre. + +``` +[ ] One testable question written down, with a real pass AND fail. +[ ] The cheapest prototype form chosen (paper / sheet / sandbox / ...). +[ ] Prototype lives in its own isolated home; can't touch the real project. +[ ] Structural contamination check (no prototype files in the real project) — + NOT a version-number pin. +[ ] Rules separate from presentation; the renderer/UI owns no truth. +[ ] ONE source of truth for world data; drawing and rules both read it. +[ ] Seeded random only. No raw randomness. No dependence on the wall clock. +[ ] Scale reference (known-size object next to new art) — checked on the + REAL target device. (skip for pure text/card games) +[ ] Camera distance + input response locked before environment art. + (skip where not applicable) +[ ] fps counter on screen from the first build. (skip for turn-based/text) +[ ] The complete gray-box loop: input, feedback, state change, failure, + reset, readability. +[ ] Licenses decided up front; provenance logged at download time. +[ ] Hard do-not-build list written, enumerated, by name. +[ ] A CURRENT-STATE note and a NEXT-ACTION note that re-verify reality first. +[ ] Stop condition named: where you halt and await a decision. +``` + +--- + +## Appendix D — The other two documents + +This handbook has two companions. All three agree and each stands alone. + +- **START-HERE** (about one page) — what each of the three documents is and the order to read them: START-HERE first, then the QUICK-START-GUIDE if you want to move *today*, then this full Handbook for the *why* and the depth. It also gives a three-or-four-sentence summary of the whole method. + +- **QUICK-START-GUIDE** (a compressed, do-this-then-that version of this exact method) — the same steps as action items, with the prototype brief (Appendix A), the player-test script (Appendix B), and the day-one checklist (Appendix C) inline, so you can run the whole loop from that one document without flipping back here. + +If you only have five minutes: read START-HERE. If you have an afternoon and want to build: follow the QUICK-START-GUIDE. If you want to understand *why* each step earns its place — and what it costs to skip it — you're already in the right document. diff --git a/docs/archive/2026-07-28/method-quick-start-guide.md b/docs/archive/2026-07-28/method-quick-start-guide.md new file mode 100644 index 0000000..55f6f09 --- /dev/null +++ b/docs/archive/2026-07-28/method-quick-start-guide.md @@ -0,0 +1,321 @@ +# Quick-Start Guide + +## Build Your Next Game Faster — the method, compressed into do-this-then-that + +This is the whole method as a checklist. If you've read the full handbook, this is your +field card. If you haven't, this still stands on its own — but read the one callout below, +because everything here is just that sentence, unpacked into steps. + +> **The central rule:** Build the cheapest complete experience that can disprove your idea, +> let a real person use it, correct only what prevents an honest verdict, and integrate it +> only after the main game is ready to consume it. + +A few words you'll see, defined once: +- **gray-box / blockout** = the game built from rough placeholder shapes (boxes, capsules, + flat colors) instead of art. +- **deterministic** = same inputs always produce the same result (no hidden randomness, no + reliance on the clock); **seeded random** = randomness you can reproduce because it starts + from a number (a "seed") you control. +- **source of truth** = the ONE place a piece of data lives that everything else reads from. +- **fps** = frames per second — how many times a second the game redraws; higher is smoother. + +Work top to bottom. Don't skip a step because it "looks obvious" — the obvious steps are the +ones people skip and pay for later. + +--- + +## Step 0 — Write your one product question (15 minutes) + +Turn the idea into a single testable question with a clear pass and a clear fail. + +- **Weak** (unfalsifiable, no stop): "Can I build a football-management game?" +- **Strong** (testable, has a pass/fail): "Can a player make a meaningful roster decision + in under two minutes while understanding its short- and long-term consequences?" + +Fill this in before you write any code: + +``` +FANTASY (what the player gets to feel they are): ________________ +CORE ACTION (the verb they do most): ________________ +CORE DECISION (the interesting choice): ________________ +INTENDED EMOTION: ________________ +BIGGEST UNCERTAINTY (what you're unsure works): ________________ +MOST EXPENSIVE-TO-REVERSE ASSUMPTION: ________________ +CHEAPEST TEST THAT COULD DISPROVE IT: ________________ +PASS CONDITION (a real person does/feels ___): ________________ +FAIL CONDITION (an honest "no" looks like ___): ________________ +``` + +If you can't write a fail condition, you don't have a question yet. A failed experiment is +fine. A misleading success is the expensive one. + +--- + +## Step 1 — Pick the cheapest valid prototype form (10 minutes) + +Choose the *least* machinery that can still answer the question. In rough order of cost: +paper → spreadsheet → text sim → mocked UI → gray-box in an engine → network harness. + +Then choose *where the code lives* by how much it could hurt your real project: +- **No real project yet, or zero integration risk** → just a new folder/repo. Isolation is + overkill; don't over-engineer. +- **You have a real game and this could contaminate it** → a **standalone repo** (a fully + separate copy with no link back). This is the safest, and it's what a risky visual or + systems spike wants. +- **In between** → a **branch** (a parallel copy inside the same repo) or a **worktree** (a + second working folder off the same repo). Cheaper isolation, but you must not let + prototype code leak into the real project. + +Rule of thumb: the more a prototype could poison the real game, the more separate it lives. + +--- + +## Step 2 — Write the prototype brief BEFORE building (20 minutes) + +Copy this, fill every line. The non-goals matter as much as the goals — they're what stop a +one-day probe from becoming a one-month project. + +``` +THE PROTOTYPE BRIEF + 1 PRODUCT QUESTION — the one falsifiable question from Step 0. + 2 TARGET PLAYER REACTION — the specific reaction that means "yes." + 3 AUTHORIZED SCOPE — the smallest set of things you WILL build. + 4 EXPLICIT NON-GOALS — what you will NOT build (list it, out loud). + 5 TIMEBOX — hours/days; when you stop regardless. + 6 REQUIRED SYSTEMS — the minimum systems the loop needs to exist. + 7 PLACEHOLDER POLICY — what stays fake (art, audio, data, AI). + 8 EVIDENCE REQUIRED — what you must SHOW (recording, screenshot, playtest). + 9 PASS CRITERIA — the observation that = proceed. +10 STOP CONDITIONS — the observations that = stop / defer / rewrite. +11 REPOSITORY BOUNDARY — where it lives; how it structurally can't hurt the real game. +12 OWNER DECISION REQUIRED — the one call you (the owner) will make at the end. +``` + +Scope-creep to refuse in item 4: inventory before movement is fun; multiplayer progression +before the netcode is stable; fifty cards before three cards make a real decision; final +character art before close-up characters are proven; a whole city before one block shows +cause and effect. + +--- + +## Step 3 — Build a COMPLETE gray-box loop (the main work) + +"Complete" means the whole loop runs end to end — ugly, but nothing missing. Boxes and +capsules only. Get the boring version playable before you draw a single nice-looking thing. If +a boxes-and-capsules version isn't a *little* bit fun, prettier art won't save it — it will +just cost you a month first. + +Find your genre's smallest complete loop and build exactly that: + +- **Action:** a character + one threat + input→feedback at a smooth frame rate. +- **Simulation/Management:** one resource → decision → a consequence you can read. +- **Strategy:** one real decision with a real counter (not one obvious best move). +- **Sports/Roster:** evaluate → sign → field → result, with a tiny roster. +- **RPG:** one build choice → one fight → one payoff. +- **Narrative:** one branch a fresh player actually notices the consequence of. +- **Racing:** one stretch of track + a handling model. +- **Multiplayer:** two players + one authoritative host + one contested moment. +- **Mobile/Touch:** one core interaction sized for thumbs on a real phone. +- **Roguelike:** one seeded run → a few rooms → death + a little meta. +- **Puzzle:** one rule set + three handmade puzzles. +- **Card/Deckbuilder:** a small deck + a few turns. +- **City-builder:** one build → simulate → feedback tick. +- **Social-deduction:** one round of hidden roles. +- **Tactics:** one small-grid skirmish you can read and plan two moves ahead in. + +The gray-box ingredient checklist — every box ticked, or the loop isn't complete: + +``` +[ ] Input — the player can act. +[ ] Feedback — the game visibly responds. +[ ] State change — something in the world actually changes. +[ ] Failure — you can lose / be wrong / hit a wall. +[ ] Reset — you can start over cleanly. +[ ] Navigation — you can get from one part to another. +[ ] Camera / viewport — the player can see what they need to. +[ ] Scale — objects are the right size relative to each other. +[ ] Collision — things block or don't, on purpose, and it's checked. +[ ] Readability — a stranger can tell what's happening. +[ ] Deterministic fixture — a fixed, reproducible test scene (seeded, no clock). +[ ] Performance instrument — a way to measure speed/memory while it runs. +``` + +Keep the game rules separate from how it looks. The renderer/UI owns no truth: game state +decides what's real, presentation just draws it. That makes swapping the look-and-feel cheap +later, and lets you reuse the *shape* of that boundary in another project — but verify the +actual data each side expects really matches; don't assume two renderers are interchangeable +just because they share a pattern. + +--- + +## Step 4 — Lock scale, camera, input, interaction — and check on the real device + +Do this early, in gray-box, not after art. These are the settings that are miserable to +change once art depends on them. + +**The mandatory scale-reference test:** put a known-size reference (a human-height marker) +next to every new object class — character, vehicle, building, prop — and look at it on the +actual target hardware, not just your dev machine. On one real 3D prototype, imported +characters rendered about 1.5x too tall and nobody caught it until it was viewed on the real +device. A bounding-box *number* can under-report an oversized rigged mesh; trust the rendered +figure on hardware, not the number. + +Prove the camera and input first, then **freeze the camera** and stop touching it. Add these +acceptance checks now, not after art: + +``` +[ ] Nothing important is hidden behind something else (no occlusion of what matters). +[ ] Text and key objects are readable at real screen density / real phone size. +[ ] Movement is predictable; no motion sickness on a 3D camera. +[ ] Selecting / targeting works; touch targets are reachable one-handed on a phone. +[ ] Controller and mouse both feel right (parity), if you support both. +[ ] Scale is within tolerance for every object class — verified on device. +``` + +--- + +## Step 5 — One source of truth for world data (+ make it reproducible) + +Put positions, obstacles, spawns, and rules in ONE place that BOTH the game and your checks +read from. Add each thing to that source *the moment it exists* — the day you render a tree, +the tree also exists in the list your movement/routing checker reads. + +The classic, preventable waste: the "what's drawn" list and the "what blocks movement" list +drift apart, so props are visible but invisible to your path checks. Link them from the start. +And never move a placed object "by eye" — re-run your check after any move, or you'll silently +break a path. + +Use **seeded random** and avoid clock-dependence, so every bug reproduces and you can test +offline. Same seed, same run, every time. + +--- + +## Step 6 — Measure speed on the device you'll actually ship on + +A speed number from a fake/software renderer or a beefy dev box is a **floor, not the +verdict.** On one real case the software floor read about 11 fps while the real hardware ran +about 120 fps — more than a 10x gap. If you'd trusted the floor you'd have "fixed" a +problem that didn't exist; if you'd trusted a fast dev box you'd have shipped a slow game. + +Instrument from day one, and actually *capture* the numbers you promised — fps, and where it +matters, triangles / draw calls / memory. Don't leave a "we'll measure performance" checkbox +unchecked. Record it or cut the promise. Then protect your headroom instead of spending it all +on the prototype. + +--- + +## Step 7 — Run the first player test on the real device (do NOT coach) + +Get one real person who isn't you. Hand them the gray-box on the target device. Watch. Don't +explain, don't rescue, don't lead. The developer loving it is not evidence. + +``` +THE FIRST PLAYER TEST — 8 questions, asked AFTER they play +1 What did you think you were supposed to do? +2 What did you actually do? +3 What felt satisfying? +4 What felt confusing? +5 What did you expect to happen? +6 What surprised you? +7 Did you want to try again? +8 Was anything stopping you from giving an honest verdict? +``` + +Separate the layers in your head: technical success (it ran) ≠ usability (they could operate +it) ≠ comprehension (they understood it) ≠ fun ≠ emotional value ≠ replay (they wanted another +go). You need the later ones, not just "it ran." + +--- + +## Step 8 — Two-stage review gate, then STOP + +Two different kinds of eyes: +1. **An outside reviewer** (someone who did NOT build it) checks correctness, isolation, and + determinism. Scale the depth to the risk. +2. **You (the owner), or a real player, on the real device** check feel, readability, and + speed. A green outside review alone does not close the gate; the on-device verdict does. + +Use a clean verdict vocabulary: + +``` +FAIL — the question answered "no," or it's broken. +CONDITIONAL-PASS — promising, but a behavior fix is required before continuing. +PASS-WITH-NOTES — good; only cosmetic/doc notes remain. +PASS — proceed. +``` + +Then: **one bounded fix pass, and stop.** Freeze what's proven and iterate behind it. Write +deferrals into a backlog — do NOT quietly start building them; a silently filled gap is a gap +nobody can find later. Know the three exits: **defer** (park it, written down), **rewrite** (the +approach was wrong, redo it small), **abandon** (the question answered "no" — a win; you learned +it cheap). + +Tell the two cost types apart. **Normal defects** — flickering overlapping surfaces, something +vanishing at a bad camera angle, an art-integration bug — are expected discovery cost; fix them +as you go. **Preventable waste** — redoing work because two lists drifted, chasing a moving +target with a brittle check, catching a scale error too late — is what this method exists to +stop. Don't lump them together. + +--- + +## Step 9 — Integrate only when the main game is ready to consume it + +The last clause of the central rule. A proven prototype is proof, not a shipped feature. Wire +it into the real game only when the real game actually has a place for it — not the moment the +prototype turns green. + +If you guard the real project against contamination, do it **structurally** — check that no +prototype paths or imports have leaked into the real game's files — not by memorizing an exact +commit number of a repo that keeps moving. A moving target makes a pinned number stale +instantly and gives you false alarms. + +--- + +## If you're using AI coding agents (you probably are) + +Three roles: the **Builder** agent, an **independent Reviewer** agent, and **you** as owner on +the real device. Give the Builder the same 12-item brief above plus a hard **do-not-build** +list, and make it *show you it working* — a recording, a screenshot, a playtest. "The tests +pass" is not proof it plays right; after any "done," ask "did that actually work?" and re-check +the claim yourself. + +For bigger jobs, fan out: several agents gather evidence → you lock the decisions → several +agents build in parallel → one agent checks it all for consistency. Keep a short handoff note +(a CURRENT-STATE + NEXT-ACTION file) so a fresh session re-checks reality first — any commit +hash written in a doc is a timestamp, not a contract. + +--- + +## What "faster" actually means + +Faster is **learning sooner and wasting less** — not skipping steps. A focused, well-scoped +visual proof was once done in about one continuous ~5-hour session: proof a tight question can +be answered fast. What made it fast was front-loading scale and the world-data model plus a +light structural isolation guard. What you must NOT skip: the complete gray-box loop, a +real-player test on the real device, and a quick "can we even get the make-or-break content?" +check before any big art push. Be honest that hero close-up art and real integration are +separate, larger costs — a cheap blocky placeholder character is fine for background and crowds, +but a hero close-up needs a genuinely higher-fidelity pipeline you prove later, on its own. + +--- + +## The one-screen day-one standards checklist + +Pin this where you can see it: + +``` +DAY-ONE STANDARDS +[ ] One falsifiable product question, with a written FAIL condition. +[ ] Prototype form = the cheapest that can answer it. +[ ] Repository boundary chosen; isolation matched to real risk. +[ ] The 12-item brief written, non-goals included, BEFORE any code. +[ ] Gray-box loop is COMPLETE (all ingredients ticked) before any art. +[ ] Game rules separated from presentation; renderer owns no truth. +[ ] Scale reference beside every object class — checked ON THE DEVICE. +[ ] Camera + input proven, then camera FROZEN. +[ ] ONE source of truth for world data; drawn == blocking; seeded RNG; no clock. +[ ] Performance instrumented from day one; numbers CAPTURED on the real device. +[ ] First player test done on the real device; you watched, didn't coach. +[ ] Two-stage gate; ONE bounded fix pass; deferrals written down, not built. +[ ] Integrate only when the main game is ready to consume it. +``` diff --git a/docs/archive/2026-07-28/method-start-here.md b/docs/archive/2026-07-28/method-start-here.md new file mode 100644 index 0000000..d579100 --- /dev/null +++ b/docs/archive/2026-07-28/method-start-here.md @@ -0,0 +1,53 @@ +# Start Here + +Welcome. This is a small kit — three files — for a non-expert game creator working solo or +with one partner, leaning heavily on AI coding agents, in whatever genre you like. Read this +page first. It's short on purpose. + +## What's in this kit + +**1. START-HERE.md** — this page. What each file is, the order to read them, and the whole +method in four sentences. Read it now. + +**2. QUICK-START-GUIDE.md** — the method compressed into a do-this-then-that checklist you can +work straight through today. It has the three copy-ready blocks inline: the 12-item prototype +brief, the 8-question first player test, and a one-screen day-one standards checklist. Use this +when you want to *move*. + +**3. HOW-TO-BUILD-YOUR-NEXT-GAME-FASTER.md** — the full handbook: the same method with the +*why* behind every step, per-genre guidance, worked examples, the architecture, how to direct +AI agents, and honest notes on tradeoffs and when to stop, defer, rewrite, or abandon. Read +this when a step in the Quick-Start raises a "but why?" or "what about my genre?" + +## Reading order + +1. **START-HERE** (now) — get the shape of it. +2. **QUICK-START-GUIDE** (to move today) — follow it step by step on your actual idea. +3. **The Handbook** (for the why and the depth) — dip in wherever the Quick-Start leaves you + wanting the reasoning or a genre-specific answer. + +All three stand alone and agree with each other. You don't need any other document, tool, or +project to use them. + +## The whole method, in four sentences + +Turn your idea into one testable question with a real fail condition, then build the cheapest +*complete* version of the loop — rough boxes and capsules, no nice art — that could honestly +disprove it. Put a real person on it, on the real device, and watch without coaching; fix only +what's blocking an honest verdict, measure speed on the hardware you'll actually ship on, and +keep the game's rules separate from how it looks so the look is cheap to change. Prove it's fun +in gray-box *before* you spend on art, keep your world data in one reproducible source of truth, +and stop after one focused fix pass — freezing what's proven and writing down (not secretly +building) anything you defer. Integrate the proven piece into your real game only when the real +game is actually ready to consume it. + +## This is a method, not a promise + +Following this won't guarantee your game is good — nothing can. What it *does* guarantee is that +you'll find out whether your idea works **sooner and cheaper**, and waste far less time on the +avoidable, self-inflicted kind of mistake (two lists drifting apart, a scale error caught too +late, a month of art on a loop that was never fun). "Faster" here means learning sooner and +wasting less, not skipping steps. Be encouraged: a tight, well-scoped question really can be +answered fast — but the speed comes from good scoping, not from cutting the loop short. + +Now open the **QUICK-START-GUIDE** and run it on your idea. diff --git a/docs/archive/2026-07-28/restaurant-empire-successor-master-plan-v1.md b/docs/archive/2026-07-28/restaurant-empire-successor-master-plan-v1.md new file mode 100644 index 0000000..f8ebabc --- /dev/null +++ b/docs/archive/2026-07-28/restaurant-empire-successor-master-plan-v1.md @@ -0,0 +1,4122 @@ +# Restaurant Empire Successor +## Master Pre-Production, Systems Design, and Technical Architecture Plan + +**Document status:** Pre-production charter +**Purpose:** Define what must be proven, designed, and locked before production implementation begins. +**Default team assumption:** One or two creators directing AI coding agents. +**Default launch assumption:** Premium, single-player, desktop-first management simulation. +**Working rule:** No assumption in this document is permanent merely because it is detailed. Every high-cost assumption has a named proof gate. + +--- + +# 0. Executive Decision + +## The proposed definitive fantasy + +> **I build one distinctive restaurant whose menu, people, layout, and service work as a coherent machine—and then turn that hard-won operating model into a culinary empire.** + +This is the project's locked design spine unless player research disproves it. + +It unifies three fantasies that would otherwise compete: + +1. **Chef-owner:** I create dishes, develop chefs, and establish a culinary identity. +2. **Restaurant operator:** I solve the live operational puzzle of turning demand into excellent service and profit. +3. **Empire builder:** I standardize, delegate, diversify, and expand without losing what made the original restaurant special. + +These are not three separate games played simultaneously. They are stages of one career: + +```text +Founder-Chef +→ Hands-on Operator +→ Restaurateur +→ Multi-unit Leader +→ Restaurant Group Architect +``` + +The player should feel increasing leverage as the organization grows. Early play is about direct decisions. Later play is about policies, people, systems, and capital allocation. + +## The central product question + +> **Can menu, pricing, staffing, and capacity decisions create multiple understandable and viable restaurant strategies, with visible consequences that make players want to revise their plan and run another service?** + +This question must be answered before detailed art, multiple cities, a campaign, hundreds of recipes, or a restaurant empire are built. + +## The first non-negotiable proof + +Build a headless service laboratory in which the player can: + +1. Inspect a restaurant and local demand. +2. Choose a menu. +3. Set prices. +4. Assign staff and kitchen capacity. +5. Run a service. +6. See what happened and why. +7. Change the plan. +8. Run again. + +If that loop is not interesting without graphics, no amount of furniture, animation, recipe content, or story will rescue the project. + +## The project's core promise + +The successor will preserve the original game's best insight: + +> **The menu is not a cosmetic list. It is the restaurant's product strategy, production schedule, labor plan, ingredient portfolio, price architecture, and identity.** + +The game will modernize everything required to make that insight legible and scalable: + +- honest cooking and throughput information; +- server sections and kitchen stations; +- shift scheduling; +- inventory, waste, and supplier tradeoffs; +- causal diagnostics; +- reusable templates; +- actual day-by-day economics; +- manager delegation; +- multiple viable restaurant concepts; +- durable save and simulation architecture. + +## What this game is not + +It is not: + +- a cooking-action game with a thin tycoon layer; +- a furniture-placement game where décor scores overpower operations; +- an accounting spreadsheet with animated customers; +- a life simulator for every employee; +- a city-scale logistics simulator on day one; +- a recipe editor disconnected from customer demand and kitchen execution; +- a faithful copy of every inconvenience in a 2003 game; +- a click-tax game in which scale merely means repeating the same setup. + +--- + +# 1. Planning Method and Governance + +The project follows one rule: + +> Build the cheapest complete experience that can disprove the idea, let a real player use it, correct only what blocks an honest verdict, and integrate it only when the production game is ready to consume it. + +Every milestone must have: + +1. Product question. +2. Target player reaction. +3. Authorized scope. +4. Explicit non-goals. +5. Effort cap. +6. Required systems. +7. Placeholder policy. +8. Evidence required. +9. Pass criteria. +10. Stop conditions. +11. Repository boundary. +12. Owner decision. + +Every gate ends with one verdict and one action: + +```text +Verdict: Fail | Conditional Pass | Pass with Notes | Pass +Action: Continue | Defer | Rewrite | Abandon +``` + +Only one bounded correction pass is allowed after a gate. New ideas found during the gate go into a visible backlog rather than being secretly added. + +## Roles when using AI agents + +Keep three roles separate: + +- **Builder:** Implements the bounded slice and runs its own technical tests. +- **Independent reviewer:** Uses separate tools and assumptions to try to break the builder's claim. +- **Owner/player tester:** Judges comprehension, feel, temptation, and performance on the real target device. + +The builder never grades its own homework. + +## Required living documents + +Maintain these from the first repository commit: + +- `VISION.md` +- `DESIGN_CONTRACT.md` +- `GLOSSARY.md` +- `CURRENT_STATE.md` +- `NEXT_ACTION.md` +- `DECISIONS.md` +- `DEFERRED_BACKLOG.md` +- `CONTENT_PROVENANCE.md` +- `SAVE_SCHEMA.md` +- `BALANCE_TARGETS.md` +- `TEST_SCENARIOS.md` + +`NEXT_ACTION.md` must begin with: **Re-confirm that the repository still matches CURRENT_STATE before changing anything.** + +--- + +# 2. Design Philosophy + +## Pillar 1 — The menu is the strategy + +A menu determines: + +- what customers consider ordering; +- which customer segments the restaurant attracts; +- ingredient purchasing and spoilage exposure; +- kitchen-station demand; +- preparation and holding times; +- chef-development priorities; +- average check and contribution margin; +- perceived identity; +- repeat visitation; +- review language; +- the restaurant's ability to absorb peak demand. + +A recipe exists only if it creates decisions in several of these areas. + +## Pillar 2 — Service is a readable flow problem + +The restaurant is a flow network: + +```text +Demand +→ Arrival +→ Seating +→ Ordering +→ Ticket release +→ Preparation +→ Course coordination +→ Pass +→ Delivery +→ Eating +→ Payment +→ Review and return behavior +``` + +The game must show where flow failed. “Service was bad” is not acceptable feedback. The player should see the actual causal chain. + +## Pillar 3 — People are both capacity and characters + +Employees are not interchangeable production multipliers. They have: + +- skills; +- specialties; +- reliability; +- stamina; +- goals; +- wage expectations; +- learning rates; +- leadership; +- limited availability. + +However, the game will not simulate private lives in detail unless that creates restaurant decisions. Character systems exist to make staffing, development, retention, and delegation meaningful. + +## Pillar 4 — Growth means leverage, not more clicking + +A larger organization should create new decisions: + +- standardize or localize; +- promote or externally hire; +- centralize or decentralize; +- expand or protect cash; +- preserve a flagship or replicate it; +- build one brand or a portfolio; +- own supply capabilities or stay flexible. + +Growth must remove routine work through managers, templates, policies, central purchasing, and reporting. + +## Pillar 5 — Thin margins create pressure; the game creates recovery + +Real restaurants can operate on extremely narrow margins. The game should preserve the pressure without copying real-world misery exactly. + +Players need: + +- enough margin for decisions to be legible; +- enough downside for capital choices to matter; +- multiple recovery paths; +- a difference between an operational problem and terminal failure. + +The economy should punish repeated bad judgment, not one unlucky dinner rush. + +## Pillar 6 — Awareness and satisfaction are different truths + +Marketing, location, reputation, novelty, and publicity create visits. + +Food, service, value, atmosphere, and expectation fit determine satisfaction and return behavior. + +A restaurant can be: + +- unknown but excellent; +- famous and disappointing; +- busy but unprofitable; +- profitable but creatively stagnant; +- prestigious but fragile; +- operationally excellent but poorly positioned. + +The game must allow all of these stories. + +## Pillar 7 — Upgrades unlock capabilities + +An upgrade should change what the player can do or how work flows. + +Good: + +- a combi oven supports several techniques and reduces station contention; +- a walk-in refrigerator permits larger, less frequent deliveries; +- a reservation desk enables deposits and controlled pacing; +- a training kitchen permits practice without disrupting service; +- a commissary centralizes prep across locations; +- a bar adds a new service flow and high-margin product category. + +Weak: + +- “Premium stove: +5% food quality.” +- “Gold wallpaper: +8 customer happiness.” + +## Pillar 8 — The simulation creates stories + +The best stories should come from systems: + +- the pastry chef who became indispensable after a surprise review; +- a viral promotion that overwhelmed an unready kitchen; +- a supplier failure that forced a successful seasonal special; +- a loyal server promoted into management who saves a second location; +- a flagship whose prestige hides poor economics; +- a cheap neighborhood dish that becomes the group's signature item. + +Events should expose or redirect existing pressures rather than act as unrelated random punishment. + +## Anti-pillars + +The project rejects: + +- hidden production times; +- unexplained global ratings; +- mandatory twitch minigames; +- repetitive per-recipe updates across every location; +- pathfinding failures treated as player mistakes; +- false choices where one option always dominates; +- random events with no preparation or recovery; +- expansion that duplicates setup work; +- hundreds of recipes before a dozen create meaningful strategies; +- simulation detail that the player cannot perceive or influence; +- AI agents with magical knowledge; +- UI screens that independently recalculate engine truth. + +## Six-test standard for every mechanic + +A mechanic is not complete until it passes: + +1. **Fantasy:** Does it reinforce the player's role? +2. **Choice:** Are at least two options rational in different contexts? +3. **Truth:** Does one authoritative system calculate the result? +4. **Clarity:** Can a fresh player explain the consequence? +5. **Risk:** Can poor judgment produce a meaningful cost? +6. **Recovery:** Can the player respond without simply restarting? + +--- + +# 3. Competitive Analysis + +## 3.1 Restaurant Empire + +### Core loop + +Build and furnish a restaurant, hire staff, assemble a menu, price dishes, run service, improve ratings, meet campaign goals, acquire recipes and chefs, and eventually operate multiple restaurants. + +### Strongest mechanics + +- Recipes connect ingredient cost, price, equipment, preparation, quality, and chef mastery. +- Chefs develop knowledge in cuisine/course categories and individual recipes. +- Campaign objectives teach revenue, profitability, service, ratings, chef prestige, and expansion. +- Special customers, suppliers, and competitions make recipe acquisition feel connected to the world. +- The restaurant is both a spatial build and an operating business. + +### Why those mechanics work + +They create ownership. The player does not merely buy “better food”; the player chooses which dishes the restaurant will become good at making and which chefs will learn them. The same choice affects identity, operations, and finances. + +### Weakest mechanics + +- Cooking-time indicators can be misleading. +- Pathfinding and staff autonomy make failures hard to diagnose. +- The player lacks enough direct assignment tools. +- Later restaurants require repetitive room and setup work. +- Rating components are too compressed. +- Some recipes are plainly superior, weakening menu diversity. +- The campaign can teach through forced tutorial friction rather than discovery. + +### What to preserve + +- Recipe-level economics and mastery. +- Chef identity and development. +- Story campaign plus sandbox. +- Cooking competitions and special opportunities. +- Multi-restaurant progression. +- Playful tone. + +### What not to copy + +- Opaque clocks and hidden formulas. +- One universal restaurant-quality score. +- Repetitive bathroom, kitchen, menu, and supplier setup. +- Random recipe sellers as the primary progression system. +- Staff AI that cannot be directed but still punishes the player. +- Monthly results extrapolated unrealistically from one service. + +## 3.2 Restaurant Empire II + +### Strongest additions + +- More cities, cuisines, recipes, objects, and campaign breadth. +- Coffee and dessert concepts. +- More entertainment and themed-building options. +- Stronger fantasy of a broad hospitality empire. + +### Why it underperformed as a model for scale + +Breadth arrived without enough leverage. Updating supplier quality or pricing dish-by-dish and restaurant-by-restaurant turns expansion into clerical repetition. Content growth multiplied the weaknesses of the interaction model. + +### Lesson + +Do not add a second cuisine, concept, or city until the first can be managed through: + +- shared templates; +- batch actions; +- policies; +- exception reporting; +- managers; +- reusable menu architectures. + +## 3.3 Pizza Connection + +### Valuable ideas + +- Product creation gives the player authorship. +- City context and competition make the restaurant feel embedded in a market. +- A distinctive, slightly absurd tone creates memorable identity. +- Different business tactics allow more than one route to growth. + +### Failure patterns seen in later entries + +- Simplifying the city and character systems can remove the series' identity. +- Unclear pizza ratings and pricing make experimentation feel arbitrary. +- Weak AI and balance make product creation cosmetic. +- Delivery, staffing, restaurant size, and inventory can fail to form one coherent economy. + +### Lesson + +A recipe editor matters only when the simulation can answer: + +- Who wants this? +- What does it cost? +- What does it do to production? +- What other items does it cannibalize? +- Why did it succeed or fail? + +## 3.4 Chef: A Restaurant Tycoon Game + +### Strongest mechanic + +The recipe editor gives strong creative ownership through ingredient selection, composition, and menu creation. + +### Main weakness + +Operational management is too shallow to sustain the fantasy. Without strong schedules, service structure, sections, goals, and long-horizon business pressure, the restaurant can become “set it and watch it.” + +### Lesson + +Recipe authorship should be retained, but it must feed: + +- ingredient cross-utilization; +- station load; +- customer-segment appeal; +- chef capability; +- pricing; +- menu coherence; +- reviews; +- waste. + +The editor should create strategic consequences, not merely novelty. + +## 3.5 Big Ambitions + +### Strongest mechanics + +- Granular business ownership. +- Scheduling and staffing. +- Warehouses, purchasing, and delivery. +- Dashboards and automation that eventually reduce routine work. +- The feeling of physically starting small and gaining leverage. + +### Weaknesses + +- Errands and travel can become friction rather than strategy. +- Late play can devolve into time-skipping while money accumulates. +- Repetition appears when the next meaningful decision is too far away. + +### Lesson + +Use its transition from manual work to management, but do not force the player to perform routine logistics after the decision is solved. The player may choose delivery frequency and supplier strategy; they should not manually drive every box forever. + +## 3.6 Two Point Hospital and Two Point Campus + +### Strongest mechanics + +- Readable humor and strong visual communication. +- Scenario-specific constraints that change strategy. +- Room templates and approachable building. +- Staff traits and training that create stories. +- A clear escalation from simple operation to interconnected systems. + +### Weaknesses + +- Rebuilding the same basic rooms in every scenario becomes busywork. +- Some objectives become waiting games. +- Repetition appears when the scenario changes targets but not decisions. + +### Lesson + +Campaign maps need rule changes, not merely larger targets. Templates, unlock carryover, and scenario-specific markets should prevent the first twenty minutes of every location from feeling identical. + +## 3.7 Dave the Diver + +### Strongest design lesson + +Two distinct loops—resource acquisition and restaurant service—feed each other in a clear rhythm. The changing activity prevents fatigue, and recurring characters create emotional investment. + +### What not to copy automatically + +An action-adventure gathering loop would fundamentally change this project's fantasy and scope. It should not be added merely because variety is good. + +### Adaptable lesson + +Use cadence variety inside management: + +- planning; +- service observation; +- post-service diagnosis; +- staff conversations; +- supplier decisions; +- competitions; +- expansion. + +The player needs changes in cognitive mode without leaving the restaurant-management fantasy. + +## 3.8 Cook, Serve, Delicious + +### Strongest mechanics + +- Menu choice changes the physical difficulty and rhythm of service. +- Fast feedback creates mastery. +- Throughput is tactile and legible. +- Harder dishes feel materially different to execute. + +### Weaknesses for this project + +- Repetition and difficulty can overwhelm players. +- Mistake feedback can feel punitive when causes are unclear. +- Manual execution would compete with the strategic management layer. + +### Lesson + +A voluntary “chef challenge” or competition mode may later use tactile execution. Normal restaurant success must never depend on the owner personally completing action minigames. + +## 3.9 Project Highrise + +### Strongest mechanics + +- Spatial relationships and service dependencies matter. +- Different tenants create an ecosystem rather than independent rooms. +- Expansion is constrained by utilities, access, and demand. + +### Weaknesses + +- Delayed satisfaction can be hard to understand. +- Timing exploits can undermine long-horizon management. +- Difficulty can fail to scale with player mastery. + +### Lesson + +Use adjacency, space, access, and infrastructure, but make delayed effects forecastable and preserve the original decision snapshot. + +## 3.10 RimWorld + +### Strongest lesson + +Agents and incidents are designed to produce stories, not merely to model reality. Character traits matter because they interact with pressure. + +### What not to copy + +Do not simulate every need, relationship, possession, and emotional state. Restaurant employees need enough personality to affect staffing decisions and stories—not a complete colony-sim psychology model. + +### Adaptable lesson + +Events should be selected from current state: + +- an exhausted team is more vulnerable to a mistake; +- a dissatisfied chef may entertain an offer; +- a strong regular-customer base may rally after a bad review; +- a risky supplier arrangement may fail during a holiday rush. + +## 3.11 Factorio + +### Strongest mechanics + +- Bottlenecks are visible. +- Systems interact predictably. +- Scaling creates new design problems. +- Blueprints preserve solved work. +- Automation converts routine labor into higher-level decisions. + +### What not to copy + +A restaurant cannot become a pure throughput factory. Hospitality, expectations, atmosphere, identity, and human inconsistency must remain. + +### Adaptable lesson + +Restaurant service should provide Factorio-like causal readability without turning guests into identical ore: + +- station utilization; +- queue length; +- travel distance; +- handoff delays; +- holding loss; +- course synchronization; +- table-turn constraints. + +--- + +# 4. Original Feature-Parity Charter + +## Preserve + +- Full restaurant construction. +- Recipe-level data. +- Ingredient quality choices. +- Chef cuisine/course/recipe mastery. +- Staff training. +- Menu pricing. +- Restaurant ratings with visible components. +- Campaign and sandbox. +- Special customers and suppliers. +- Cooking contests. +- Multi-location growth. +- Light, characterful narrative tone. + +## Modernize + +- Staff scheduling. +- Server sections. +- Kitchen stations. +- Host and table-assignment policies. +- Menu editing. +- Supplier updates. +- Camera and selection. +- Pathfinding. +- Save/autosave. +- Tutorials. +- Reports. +- Reusable layouts. +- Restaurant-to-restaurant comparison. + +## Deepen + +- Customer segments and occasions. +- Restaurant concept and positioning. +- Menu complexity and ingredient cross-utilization. +- Prep, inventory, spoilage, and waste. +- Table mix and reservation pacing. +- Course firing and expediting. +- Staff careers and management bench. +- Reviews, expectations, and repeat visits. +- Competitors and neighborhood change. +- Unit economics and expansion readiness. +- Brand architecture and portfolio strategy. +- Recovery from operational decline. + +## Replace + +- Misleading cooking clocks. +- A single global quality score. +- Random acquisition as the main recipe system. +- Per-item repetitive supplier edits. +- Manual recreation of standard rooms. +- Twitch contests as the primary competition determinant. +- Artificial “one day equals one month” accounting. +- Staff behavior that is both uncontrollable and unexplained. + +## Defer + +- Delivery platforms. +- Food trucks. +- Catering. +- Hotels. +- Farming. +- Vertical integration. +- Franchising. +- International regulation. +- Celebrity-media systems. +- Cooperative multiplayer. +- Code mods. +- User-shared building marketplaces. + +## Remove + +- Unskippable tutorials. +- Content whose only function is numerical inflation. +- Mandatory decorative clutter. +- Objectives that merely require waiting. +- Equipment tiers that provide only generic percentage bonuses. +- Any system that repeats solved work at every new restaurant. + +--- + +# 5. Restaurant Industry Model: Reality Versus Gameplay + +## 5.1 Financial reality to preserve + +Real full-service restaurants often face food and labor costs near one-third of sales each, leaving narrow margins after occupancy and other operating expenses. The simulation should therefore make these ratios important: + +- food cost percentage; +- labor cost percentage; +- prime cost; +- occupancy cost; +- contribution margin; +- cash runway; +- store-level operating profit; +- capital payback. + +## 5.2 Financial reality to simplify + +A literal recreation of tax, payroll compliance, insurance forms, merchant statements, health-code paperwork, and accounting accruals would add work rather than decisions. + +The launch simulation should use: + +- cash basis for ordinary service transactions; +- an append-only financial ledger; +- clear daily and weekly reports; +- simplified permits and taxes; +- summarized fixed expenses; +- optional advanced accounting later. + +## 5.3 Menu engineering + +Traditional menu engineering compares item popularity and contribution margin. The game should include that view but extend it with operational load. + +Every dish needs: + +- sales volume; +- selling price; +- ingredient cost; +- contribution per sale; +- preparation labor; +- station minutes; +- contribution per constrained station minute; +- ingredient cross-utilization; +- waste exposure; +- customer-segment appeal; +- review association; +- chef mastery; +- holding tolerance. + +A “high margin” dish can still be strategically weak if it monopolizes the grill during peak demand. + +## 5.4 Revenue management + +A restaurant sells time and space as well as food. + +Important variables: + +- party-size distribution; +- table-size mix; +- average dining duration; +- average check; +- reservation pacing; +- no-show risk; +- walk-in demand; +- daypart; +- table-turn time; +- revenue per available seat-hour; +- value per square-foot-hour. + +The game should make a two-top-heavy dining room perform differently from a room dominated by four-tops. + +## 5.5 Kitchen workflow + +A believable kitchen requires: + +```text +Receiving +→ Storage +→ Prep +→ Station mise en place +→ Order release +→ Station production +→ Course synchronization +→ Expediter/pass +→ Food runner/server +→ Table +→ Dish return +→ Washing +``` + +The simulation does not need to animate every knife cut. It does need to model the constraints that create decisions: + +- station capacity; +- batch prep; +- active versus passive cook time; +- sequencing; +- dependencies; +- holding; +- shared equipment; +- skill; +- travel; +- handoffs. + +## 5.6 Staffing + +Real scheduling balances demand, availability, wages, legal constraints, training, fatigue, and retention. The game should preserve: + +- daypart staffing; +- role coverage; +- availability; +- breaks; +- overtime; +- skill mix; +- section size; +- station assignment; +- manager quality; +- workload; +- morale; +- turnover. + +It should simplify jurisdiction-specific labor law into configurable policy rules rather than reproduce every statute. + +## 5.7 Purchasing and suppliers + +Supplier decisions should involve: + +- price; +- quality; +- consistency; +- delivery days; +- lead time; +- minimum order; +- credit terms; +- exclusivity; +- seasonality; +- sustainability/prestige; +- substitution risk. + +The player chooses policies and exceptions. They should not click through every recipe at every restaurant to update a supplier. + +## 5.8 Customer psychology + +Customers compare the experience with expectations. + +Expectation is influenced by: + +- price; +- brand; +- prior visits; +- reviews; +- marketing; +- chef reputation; +- décor; +- occasion; +- stated wait time. + +Satisfaction is influenced by: + +- food; +- service; +- time; +- accuracy; +- comfort; +- value; +- fit for occasion; +- recovery after a failure. + +A modest neighborhood restaurant can delight by exceeding modest expectations. A prestigious flagship can disappoint despite objectively good food. + +## 5.9 Reviews and loyalty + +Reviews should be memory snapshots, not generic dice rolls. + +A customer remembers a small set of salient moments: + +- the longest delay; +- the strongest dish; +- a service recovery; +- value; +- atmosphere; +- an unusual event. + +Repeat behavior should depend more on fit, consistency, and remembered value than on one universal score. + +## 5.10 Expansion + +Expansion should test whether the player has created a transferable operating model. + +Readiness depends on: + +- unit economics; +- cash and debt capacity; +- manager bench; +- chef bench; +- documented menu and prep standards; +- supplier capacity; +- brand strength; +- local market fit; +- owner attention. + +Scale amplifies good and bad economics. A second weak unit is not progress. + +--- + +# 6. Player Fantasy and Career Structure + +## Stage 1 — Founder-Chef + +Player emphasis: + +- choose initial concept; +- restore or build a small restaurant; +- author a focused menu; +- hire a tiny team; +- learn service flow; +- survive cash pressure; +- establish one signature. + +The player may personally occupy the chef-owner role, but direct action minigames are not required. + +## Stage 2 — Operator + +Player emphasis: + +- schedule shifts; +- assign sections and stations; +- improve prep; +- diagnose queues; +- refine price and menu architecture; +- train staff; +- manage suppliers; +- build repeat demand. + +The restaurant becomes a coherent system. + +## Stage 3 — Restaurateur + +Player emphasis: + +- develop leaders; +- create policies; +- renovate; +- use events and marketing; +- balance creative identity and profitability; +- build a second concept or location; +- manage capital. + +## Stage 4 — Group Leader + +Player emphasis: + +- portfolio strategy; +- central services; +- manager accountability; +- talent pipeline; +- brand architecture; +- acquisitions; +- expansion sequencing; +- market competition. + +## Stage 5 — Legacy Architect + +Player emphasis: + +- flagship preservation; +- franchising or ownership strategy; +- succession; +- international or cross-format growth; +- awards and institutional reputation; +- resilience through changing markets. + +This final stage is an expansion target, not required for the first commercial release. + +--- + +# 7. Core Gameplay Loops + +## 7.1 Service loop + +```text +Forecast demand +→ Plan menu, prep, staffing, sections, and reservations +→ Open service +→ Observe flow and intervene selectively +→ Close service +→ Review causal report +→ Adapt +``` + +### Allowed live interventions + +- pause or change simulation speed; +- reassign a server section; +- move a cook between stations; +- call an on-call employee; +- stop accepting walk-ins; +- extend quoted wait; +- eighty-six a dish; +- release or delay reservations; +- comp an item/table; +- prioritize a ticket; +- adjust course firing; +- close a station or shorten the menu. + +These interventions have costs. The game should not become whack-a-mole. + +## 7.2 Daily loop + +- review bookings and forecast; +- check deliveries and stock risks; +- confirm staffing; +- set prep priorities; +- run lunch and/or dinner; +- inspect daily cash, guest, and operations report; +- respond to urgent employee or supplier issues. + +## 7.3 Weekly loop + +- menu engineering; +- schedule creation; +- staff training; +- supplier ordering and negotiation; +- maintenance; +- marketing; +- review analysis; +- competitor scan; +- cash and debt management; +- strategic specials. + +## 7.4 Seasonal loop + +- seasonal menu; +- demand shifts; +- wage and ingredient changes; +- staff reviews and promotions; +- awards and critics; +- renovations; +- financing; +- major events; +- expansion decision. + +## 7.5 Empire loop + +```text +Evaluate markets +→ Choose concept and investment thesis +→ Allocate leader, chef, capital, and operating model +→ Launch location +→ Stabilize +→ Delegate +→ Compare portfolio performance +→ Standardize, localize, sell, close, or expand +``` + +--- + +# 8. Decision Inventory and Tradeoff Map + +## Concept + +- broad appeal vs distinctive identity; +- value vs premium; +- consistency vs experimentation; +- local familiarity vs novelty; +- destination dining vs neighborhood frequency. + +## Menu + +- breadth vs mastery; +- choice vs speed; +- ingredient quality vs price accessibility; +- high margin per plate vs contribution per station minute; +- signature specialization vs resilience; +- seasonal freshness vs supply consistency; +- shared ingredients vs menu variety; +- scratch preparation vs purchased convenience. + +## Staff + +- experienced hire vs trainable prospect; +- labor buffer vs tight scheduling; +- specialists vs flexible generalists; +- high wages vs turnover risk; +- promote internally vs hire externally; +- owner control vs manager autonomy. + +## Capacity and layout + +- seats vs comfort; +- large tables vs flexible two-tops; +- compact kitchen vs station separation; +- premium bar space vs dining capacity; +- storage vs revenue-generating floor; +- short travel paths vs aesthetics; +- redundant equipment vs capital efficiency. + +## Demand + +- marketing now vs operational readiness; +- reservations vs walk-ins; +- volume promotion vs brand positioning; +- discounts vs perceived value; +- critic pursuit vs regular-customer loyalty. + +## Finance + +- renovate vs maintain cash; +- lease vs buy equipment; +- debt vs equity; +- second location vs first-location resilience; +- central kitchen vs local flexibility; +- growth vs management bench. + +## Empire + +- shared menu vs local menu; +- chain brand vs portfolio; +- central purchasing vs supplier diversity; +- strict standards vs manager creativity; +- own-and-operate vs franchise; +- acquire vs build. + +No system is authorized unless it creates at least one of these tensions or materially clarifies their consequences. + +--- + +# 9. Simulation Map + +| Simulation | Purpose | Primary inputs | Primary outputs | Important interactions | Failure modes | Expansion path | +|---|---|---|---|---|---|---| +| Time and calendar | Establish cadence and causality | tick, speed, daypart, season | service windows, deadlines | demand, payroll, spoilage, events | wall-clock dependence, inconsistent speeds | eras, holidays, weather | +| Market and location | Create external demand context | district, traffic, segments, competition | demand forecast, rent, awareness ceiling | concept, pricing, marketing | one “best” location | city evolution, international markets | +| Restaurant concept | Define promise and operating model | cuisine, format, price tier, service style | expectations, segment fit, capability needs | menu, décor, staffing | cosmetic labels | multiple brands | +| Customer party | Convert market demand into experiences | segment, occasion, budget, patience | orders, satisfaction, reviews, loyalty | menu, queue, service | omniscient agents, noise | regulars, VIPs, groups | +| Reservations and queue | Pace arrivals and allocate capacity | booking rules, table mix, walk-ins | seated parties, waits, no-shows | demand, host, tables | arbitrary queues | deposits, events, waitlist channels | +| Menu | Express product strategy | recipes, prices, availability | choice set, expected demand, identity | kitchen, inventory, customers | dominant recipe, content bloat | tasting menus, dayparts | +| Recipe and variant | Define production and value | ingredients, technique, process graph | quality potential, cost, station load | chef, equipment, supplier | editor disconnected from game | user-created recipes | +| Inventory and ingredients | Create purchasing and waste decisions | lots, freshness, orders, storage | availability, cost, spoilage | recipes, suppliers, prep | item-count micromanagement | commissaries, transfers | +| Suppliers | Create external cost/quality/risk | catalog, price, reliability, terms | deliveries and disruptions | inventory, finance, reputation | random punishment | contracts, exclusivity | +| Kitchen production | Turn orders into dishes | tickets, staff, station capacity, prep | dish time, quality, errors | menu, equipment, FOH | deadlocks, hidden queues | advanced techniques | +| Front of house | Move information, food, and hospitality | sections, tasks, staff | order speed, delivery, service quality | kitchen, tables, customers | uncontrolled AI | sommelier, events | +| Employees | Create capacity, development, and stories | skill, traits, schedule, wage | performance, learning, morale | all operations | life-sim bloat | careers, unions, leadership | +| Layout and equipment | Make space operational | geometry, paths, equipment, furniture | travel, capacity, comfort, capabilities | staff, customer flow | décor stat stacking | multi-floor, outdoor | +| Economy and ledger | Make tradeoffs durable | transactions, loans, capital | cash, P&L, ratios, forecasts | every business system | arbitrary balance taxes | investors, acquisitions | +| Awareness and marketing | Generate consideration | channels, targeting, spend, story | visits, expectations | demand, reputation, capacity | marketing always optimal | PR, influencers, loyalty | +| Reputation and reviews | Create memory and long-term demand | experiences, critics, consistency | segment reputation, awards | marketing, pricing, staff | one global rating | prestige systems | +| Competitors | Make the market dynamic | concept, quality, price, capacity | market-share pressure, openings/closures | demand, hiring, suppliers | full-sim cost or cheating AI | acquisitions, rivalry | +| Events and narrative | Create state-based stories | current pressures, characters, calendar | opportunities and crises | all systems | unrelated randomness | campaign arcs | +| Management and delegation | Convert scale into leverage | policies, manager skill, reporting | automated decisions, exceptions | multi-unit operations | black-box automation | regional management | +| Progression and capabilities | Pace complexity | achievements, capital, knowledge | new actions and constraints | equipment, staff, cities | linear +5% tree | research, institutions | +| Save and history | Preserve player investment | authoritative state, schema version | recoverable career | forecasts, reports, mods | corruption, rewritten history | cloud, workshop | +| Analytics and explanation | Make decisions legible | event log, state snapshots | reports, heatmaps, causal chains | every simulation | data dump without meaning | advisor and replay | + +--- + +# 10. Detailed System Design + +## 10.1 Time and service cadence + +### Time scales + +- **Simulation tick:** deterministic internal unit. +- **Operational minute:** customer and task timing. +- **Service:** lunch, dinner, brunch, or special event. +- **Day:** deliveries, cash, reviews, spoilage. +- **Week:** schedules, payroll, menu review. +- **Season:** demand and strategic planning. + +### Rules + +- Pausing is always allowed in the standard mode. +- Multiple speeds are allowed. +- Outcomes cannot depend on the computer's wall clock. +- Speed changes cannot alter simulation results for the same seed and commands. +- High-speed simulation may abstract animation but not rules. +- A day is simulated as a day; it is not multiplied into an artificial month. + +## 10.2 Market, district, and location + +Each location has: + +- foot traffic by daypart; +- resident, worker, tourist, and nightlife mix; +- income distribution; +- cuisine familiarity; +- occasion demand; +- rent and lease terms; +- visibility; +- access; +- nearby attractions; +- competitor set; +- delivery access; +- alcohol restrictions; +- seasonality. + +### Market demand + +Demand should be generated in layers: + +```text +Addressable segment demand +× daypart and calendar +× location accessibility +× concept fit +× awareness +× price consideration +× competitive share +× reservation availability += attempted visits +``` + +Attempted visits are not guaranteed covers. Queue, table fit, no-shows, and walk-aways intervene. + +### Location information + +The player receives forecasts and confidence bands, not omniscience. Better research, experienced managers, and operating history narrow uncertainty. + +The forecast shown when signing a lease must be persisted as a historical snapshot. + +## 10.3 Restaurant concept and promise + +A concept is an authored set of commitments: + +- cuisine and culinary point of view; +- service style; +- price tier; +- target occasions; +- menu breadth; +- speed promise; +- atmosphere; +- reservation model; +- alcohol program; +- degree of experimentation; +- consistency versus seasonal change. + +The concept affects customer expectations and required capabilities. It does not directly grant quality. + +A “fine dining” label increases expectations, labor needs, pacing complexity, and acceptable prices. It does not add points. + +## 10.4 Customers and parties + +### Party over individual + +The party is the economic and seating unit. Individuals within a party modify preferences and order choices, but the game avoids simulating unnecessary private detail. + +### Party properties + +- size; +- segment; +- occasion; +- budget; +- patience; +- time budget; +- cuisine preferences; +- dietary requirements; +- alcohol propensity; +- quality expectation; +- service expectation; +- atmosphere preference; +- price sensitivity; +- novelty preference; +- review propensity; +- loyalty; +- prior memories. + +### State machine + +```text +Considering +→ Traveling +→ Arrived +→ Host queue +→ Waiting +→ Seated +→ Browsing +→ Ordering +→ Waiting for drinks +→ Waiting for courses +→ Eating +→ Additional order decision +→ Check +→ Payment +→ Exit +→ Memory/review/return update +``` + +### Knowledge rule + +Customers know only what they can observe or have been told: + +- quoted wait; +- visible crowding; +- menu; +- prices; +- prior reputation; +- elapsed time; +- delivered food and service. + +They do not know the hidden kitchen queue or staff skill values. + +### Choice model + +A dish's utility may consider: + +- preference fit; +- dietary eligibility; +- expected quality; +- price fit; +- novelty; +- signature status; +- description; +- pairing; +- wait expectation; +- availability; +- social influence within the party. + +The exact formula is calibration work, not a design truth. + +### Satisfaction dimensions + +Keep separate: + +- food; +- service warmth; +- service accuracy; +- waiting; +- atmosphere; +- comfort; +- value; +- occasion fit; +- recovery. + +The final memory emphasizes a few salient moments rather than averaging every second equally. + +## 10.5 Reservations, waiting, and tables + +### Reservation policies + +- walk-in only; +- mixed; +- reservation heavy; +- deposits; +- fixed seating waves; +- flexible pacing; +- overbooking tolerance; +- held-table duration; +- late-arrival policy. + +### Table assignment + +The host balances: + +- table capacity; +- merge/split rules; +- section workload; +- reservation protection; +- expected dining duration; +- party patience; +- accessibility; +- preference; +- revenue opportunity. + +### Table mix + +A table has: + +- seats; +- footprint; +- merge relationships; +- comfort; +- turn/reset time; +- location desirability. + +Large tables waste seats on small parties but handle groups. Two-tops improve flexibility but may hurt group business and atmosphere. + +## 10.6 Menu architecture + +A menu has: + +- daypart; +- course sections; +- recipe variants; +- prices; +- availability rules; +- limited quantities; +- pairings; +- descriptions; +- menu identity; +- change date; +- target segments. + +### Menu complexity + +Complexity grows with: + +- recipe count; +- unique ingredients; +- low-volume perishables; +- distinct techniques; +- station concentration; +- number of variants; +- number of chefs who require training; +- prep fragmentation; +- plating diversity. + +Consequences include: + +- prep hours; +- inventory; +- waste; +- mistakes; +- ticket time; +- diluted mastery; +- training burden. + +Do not impose an arbitrary hard cap unless testing shows it improves comprehension. Prefer visible complexity budgets and consequences. + +### Menu coherence + +Coherence measures whether the menu delivers a recognizable promise. It is not “authenticity policing.” A creative fusion menu can be coherent if its ingredients, techniques, prices, and descriptions form a deliberate identity. + +Coherence affects: + +- customer confidence; +- review language; +- cross-selling; +- training efficiency; +- brand memory. + +### Menu engineering views + +- popularity vs contribution; +- contribution per station minute; +- segment appeal; +- ingredient network; +- station-load heatmap; +- waste risk; +- mastery coverage; +- review sentiment; +- price elasticity; +- pairings. + +## 10.7 Recipes and recipe development + +### Recipe definition + +- stable ID; +- name and description; +- cuisines/tags; +- course/daypart; +- techniques; +- required and optional ingredients; +- quantities; +- process graph; +- active and passive time; +- station/equipment requirements; +- batchability; +- holding tolerance; +- plating steps; +- base difficulty; +- quality potential; +- portion; +- allergens/dietary tags; +- target-segment affinities; +- lineage and variants. + +### Preparation graph + +A recipe is a directed process: + +```text +Prep ingredients +→ component tasks +→ parallel cooking tasks +→ dependency joins +→ plating +→ pass +``` + +This permits believable throughput without animating every motion. + +### Quality model + +Conceptual model: + +```text +Delivered dish quality = +recipe potential ++ ingredient contribution ++ chef execution ++ equipment/process fit ++ plating +- mistakes +- holding loss +- coordination failure +``` + +Do not allow premium ingredients to erase poor execution or skill to erase spoiled ingredients. + +### Recipe mastery + +Mastery is per chef and recipe, influenced by: + +- cuisine familiarity; +- technique familiarity; +- recipe difficulty; +- actual repetitions; +- practice; +- mentorship; +- feedback; +- fatigue; +- learning trait. + +Diminishing returns prevent easy dishes from producing endless skill. + +### Recipe discovery + +Sources: + +- staff knowledge; +- mentor events; +- cookbooks/research; +- travel; +- supplier relationships; +- customer traditions; +- competitions; +- acquisitions; +- experimentation; +- seasonal ingredients. + +### Recipe development + +A new recipe begins as a hypothesis. The player chooses: + +- base structure; +- techniques; +- ingredients; +- portion; +- plating; +- target price; +- intended segment; +- intended station/load. + +Testing reveals uncertainty through: + +- staff tasting; +- limited special; +- soft launch; +- regular service; +- critic exposure. + +The game should not reveal exact market appeal before evidence exists. + +## 10.8 Ingredients and inventory + +### Inventory abstraction + +Use lots, not individual items. + +An ingredient lot has: + +- ingredient ID; +- quantity; +- unit; +- quality; +- freshness; +- received date; +- use-by date; +- supplier; +- unit cost; +- storage requirement; +- reserved quantity. + +### Inventory policies + +- par level; +- safety stock; +- reorder point; +- preferred supplier; +- approved substitutes; +- emergency purchase permission; +- first-expire-first-out; +- waste tolerance. + +### Prep inventory + +Track prepared components separately when important: + +- sauces; +- dough; +- stocks; +- portioned proteins; +- pastry components. + +Prep creates labor and may extend or shorten service throughput at the cost of freshness and waste risk. + +### Waste categories + +- spoilage; +- trim/yield; +- over-prep; +- mistakes; +- returns; +- comps; +- theft/variance, deferred. + +The player needs category explanations rather than one waste number. + +## 10.9 Suppliers + +A supplier has: + +- product catalog; +- quality range; +- pricing; +- delivery schedule; +- lead time; +- minimum order; +- reliability; +- substitution behavior; +- payment terms; +- capacity; +- relationship; +- prestige/sustainability tags. + +### Supplier tradeoffs + +- cheap and inconsistent; +- premium and reliable; +- local and seasonal; +- broadline convenience; +- specialist quality; +- exclusive but inflexible. + +Disruptions should be forecastable in risk terms and recoverable through substitutes, safety stock, menu changes, or emergency purchasing. + +## 10.10 Kitchen production + +### Core objects + +- order; +- course; +- dish ticket; +- task; +- station queue; +- equipment reservation; +- prepared component; +- pass batch. + +### Ticket lifecycle + +```text +Order confirmed +→ courses scheduled +→ ticket tasks released +→ stations accept tasks +→ components prepared +→ course synchronized +→ plated +→ quality check +→ pass +→ runner pickup +→ table delivery +``` + +### Station model + +Stations include: + +- grill; +- sauté; +- fry; +- oven; +- cold; +- pastry; +- beverage; +- pass. + +Each station has: + +- work surfaces; +- equipment capacity; +- assigned employees; +- queue discipline; +- prep availability; +- congestion; +- cleanliness; +- failure state. + +### Course coordination + +A table's dishes should arrive together within a tolerance. Starting everything immediately is not always optimal. + +The expediter or kitchen lead decides: + +- when to fire; +- whether to hold; +- whether to remake; +- which table has priority; +- whether to split delivery. + +### Bottleneck model + +A bottleneck may arise from: + +- station saturation; +- one high-load recipe; +- missing prep; +- skill mismatch; +- equipment failure; +- long travel; +- poor firing; +- dishwashing shortage; +- server congestion; +- excessive simultaneous seating. + +The game must identify the causal chain after service. + +## 10.11 Front of house + +### Roles + +- host; +- server; +- captain/lead server; +- bartender; +- food runner; +- busser; +- sommelier, later; +- manager; +- cleaner. + +### Server sections + +A section defines: + +- tables; +- expected covers; +- travel distance; +- support staff; +- maximum concurrent workload. + +The player can create a stable section plan and temporarily reassign during service. + +### FOH tasks + +- greet; +- seat; +- present menu; +- take order; +- enter/send order; +- deliver drinks; +- check table; +- coordinate courses; +- clear; +- reset; +- resolve complaint; +- present check; +- payment. + +### Service quality + +Service quality is not only speed. It includes: + +- warmth; +- accuracy; +- attentiveness; +- knowledge; +- pacing; +- recovery. + +## 10.12 Employees + +### Employee attributes + +- role qualifications; +- cuisine familiarity; +- technique skill; +- recipe mastery; +- speed; +- accuracy; +- hospitality; +- sales; +- stamina; +- stress tolerance; +- reliability; +- learning; +- teaching; +- leadership; +- creativity; +- schedule availability; +- wage; +- ambitions; +- traits; +- morale; +- fatigue; +- reputation. + +### Scope guard + +Traits must alter restaurant decisions. Do not add a trait merely because it is colorful. + +Good: + +- “Calm under pressure” reduces performance loss at overload. +- “Mentor” increases nearby learning but expects a leadership path. +- “Perfectionist” improves quality but slows tasks when rushed. + +Weak: + +- unrelated collectible personality text with no operational consequence. + +### Scheduling + +- weekly shift templates; +- daypart demand forecast; +- role minimums; +- availability; +- breaks; +- overtime; +- on-call; +- split shifts; +- cross-training; +- labor target. + +### Morale and retention + +Morale responds to: + +- workload; +- pay fairness; +- schedule predictability; +- leadership; +- training; +- restaurant performance; +- equipment; +- recognition; +- promotion; +- repeated failures. + +Turnover is signaled before resignation unless an extreme event occurs. + +### Careers + +Employees may: + +- improve; +- specialize; +- mentor; +- seek promotion; +- request compensation; +- leave; +- become managers; +- follow the player to a new concept; +- become competitors, later. + +## 10.13 Layout, furniture, and equipment + +### Functional zones + +- entrance and host; +- waiting; +- bar; +- dining; +- kitchen; +- prep; +- storage; +- receiving; +- dishwashing; +- restrooms; +- staff space; +- office; +- private dining; +- pickup, later. + +### Flow networks + +Track: + +- customer flow; +- clean food flow; +- dirty dish flow; +- ingredient flow; +- employee flow; +- information flow. + +### Décor + +Décor affects: + +- concept fit; +- expectations; +- comfort; +- acoustics; +- perceived privacy; +- dwell time; +- segment appeal. + +It should not apply one universal happiness bonus. + +### Equipment as capability + +Each equipment item has: + +- supported techniques; +- capacity; +- speed; +- footprint; +- utilities; +- maintenance; +- reliability; +- cleaning; +- skill requirements. + +### Templates + +Players can save: + +- room; +- kitchen line; +- table layout; +- section plan; +- shift plan; +- menu; +- supplier policy; +- full operating model. + +Templates preserve solved work but remain editable. + +## 10.14 Economy and accounting + +### Economic layers + +**Capital economy** + +- construction; +- equipment; +- deposits; +- renovations; +- licenses; +- central facilities. + +**Service/project economy** + +- ingredients; +- hourly labor; +- promotions; +- event-specific costs; +- refunds/comps; +- incremental revenue. + +**Operating economy** + +- rent; +- salaries; +- utilities; +- maintenance; +- insurance abstraction; +- subscriptions; +- debt service. + +**Corporate economy** + +- central staff; +- regional management; +- commissary; +- brand marketing; +- acquisitions; +- shared infrastructure. + +### Financial statements + +- daily service summary; +- weekly operating statement; +- cash flow; +- balance sheet, simplified; +- unit economics; +- menu contribution; +- labor report; +- inventory/waste report; +- expansion model. + +### Key metrics + +- covers; +- average check; +- sales; +- contribution margin; +- food cost %; +- labor %; +- prime cost; +- occupancy %; +- store operating profit; +- cash runway; +- table turns; +- revenue per available seat-hour; +- contribution per station minute; +- waste %; +- repeat rate; +- marketing acquisition cost; +- opening payback. + +### Balance philosophy + +Use real restaurant ratios as anchors, then exaggerate enough for game readability. + +A first successful restaurant may show stronger margins than a typical real restaurant so that upgrades and recovery are visible. The simulation should preserve the relationship among costs rather than worship literal percentages. + +### Forecasts + +Before a decision, save: + +- expected demand range; +- expected costs; +- expected profit range; +- confidence; +- assumptions; +- known risks. + +Afterward, compare the persisted forecast with actual results. Never rebuild the old forecast using current reputation, current formulas, or new information. + +## 10.15 Awareness, marketing, and reputation + +### Separate states + +- awareness; +- consideration; +- expectation; +- trial; +- satisfaction; +- memory; +- loyalty; +- advocacy. + +### Marketing channels + +- local print/media; +- outdoor; +- digital targeting; +- social content; +- influencer/critic outreach; +- partnerships; +- events; +- loyalty; +- direct reservations; +- public relations. + +Channels differ by: + +- segment reach; +- geography; +- cost; +- lead time; +- credibility; +- expectation inflation; +- duration. + +### Overmarketing + +Marketing can: + +- overwhelm capacity; +- attract the wrong segment; +- inflate expectations; +- generate one-time traffic without loyalty; +- dilute prestige through discounting. + +Therefore “maximum marketing” is never automatically correct. + +### Reputation + +Track reputation by dimension and segment: + +- food; +- service; +- value; +- speed; +- atmosphere; +- consistency; +- innovation; +- hospitality; +- suitability for occasions. + +## 10.16 Reviews, critics, and awards + +### Customer reviews + +A review is generated from an experience snapshot and reviewer propensity. + +It should mention specific causes: + +- a dish; +- a wait; +- a staff interaction; +- value; +- atmosphere; +- recovery. + +### Critics + +Critics have: + +- specialty; +- standards; +- preferences; +- influence; +- anonymity level; +- visit conditions. + +The player can pursue attention but cannot buy the score. + +### Awards + +Awards require sustained evidence, not one event. They may value different things: + +- consistency; +- innovation; +- value; +- service; +- sustainability; +- regional identity. + +Use fictional award systems unless licensed. + +## 10.17 Competitors and living market + +### Abstraction level + +Competitors do not require the same agent-level simulation as the player's active restaurant. + +Each competitor has: + +- concept; +- price tier; +- menu profile; +- capacity; +- quality dimensions; +- awareness; +- loyalty; +- financial health; +- staff reputation; +- strategic posture. + +They periodically make decisions based on the same broad pressures: + +- price; +- promotion; +- renovation; +- hiring; +- menu change; +- opening; +- closure; +- acquisition. + +### Fairness + +Competitors cannot see hidden player data. Their information is based on market-visible signals and difficulty settings. + +### Market stories + +- new competitor opening; +- neighborhood gentrification; +- office closure; +- event venue opening; +- ingredient trend; +- critic shift; +- labor shortage; +- competitor scandal; +- acquisition opportunity. + +## 10.18 Events and narrative + +### Event design rules + +An event must: + +1. Be connected to current state. +2. Expose a tradeoff. +3. Offer at least two rational responses. +4. Have a forecastable risk. +5. Produce a later consequence. +6. Avoid a single obviously correct answer. +7. Never permanently destroy a run without warning and recovery. + +### Event categories + +- staff; +- customer; +- supplier; +- critic; +- competitor; +- finance; +- landlord; +- neighborhood; +- regulation abstraction; +- equipment; +- opportunity; +- personal legacy. + +## 10.19 Cooking competitions + +Competitions are optional strategic projects. + +Preparation includes: + +- choose chef/team; +- choose dish; +- source ingredients; +- practice; +- study criteria; +- accept service disruption; +- decide creative risk. + +Event decisions may include: + +- simplify; +- substitute; +- assist another station; +- take a presentation risk; +- recover from failure. + +Outcome should be driven primarily by preparation, skill, and fit—not button speed. + +Rewards: + +- reputation; +- recipe knowledge; +- supplier access; +- staff development; +- cash; +- invitations. + +## 10.20 Growth and multiple restaurants + +### Expansion readiness + +A location is ready to support expansion when: + +- trailing unit economics are stable; +- cash reserve exceeds a policy threshold; +- a manager can operate the current unit; +- chef and service leaders exist; +- supplier capacity exists; +- operating standards are documented; +- brand awareness has room to transfer; +- target market fit is credible. + +The game may allow premature expansion, but it clearly forecasts the risk. + +### Expansion forms + +- larger site; +- second location of same brand; +- new concept; +- acquisition; +- pop-up, later; +- franchise, later. + +### Delegation + +Managers operate within policies: + +- menu authority; +- price authority; +- hiring authority; +- purchasing authority; +- labor target; +- quality target; +- marketing limit; +- maintenance limit; +- escalation rules. + +Manager performance is visible through forecast accuracy, exceptions, staff outcomes, and unit results. + +### Brand architecture + +**Chain** + +- shared menu; +- shared identity; +- purchasing scale; +- easier training; +- brand-wide risk. + +**Restaurant group** + +- distinct concepts; +- creative flexibility; +- more complex leadership; +- diversified reputation. + +**Hybrid** + +- shared back office and talent; +- local concepts; +- selected shared capabilities. + +## 10.21 Failure and recovery + +### Failure spirals + +- cash squeeze; +- turnover; +- quality collapse; +- bad reviews; +- overmarketing; +- supplier failure; +- overexpansion; +- debt burden; +- concept-market mismatch; +- owner attention overload. + +### Recovery tools + +- reduce hours; +- reduce menu complexity; +- close a daypart; +- temporary closure; +- retrain; +- replace leadership; +- renegotiate supplier; +- emergency financing; +- sell equipment; +- sell or close a location; +- reposition concept; +- loyalty recovery event; +- consultant/mentor; +- structured bankruptcy, later. + +A bad restaurant should create a recovery puzzle before a game-over screen. + +--- + +# 11. System Contracts + +## 11.1 Game Clock + +**Knows:** simulation time, calendar, speed, scheduled events. +**Can:** tick, pause, schedule, advance deterministic time. +**Cannot:** use wall-clock time to decide outcomes. +**Invariant:** Same starting state, seed, and commands produce the same state. + +## 11.2 Restaurant + +**Knows:** owned layout, equipment, menu, employees assigned, policies, local operational state. +**Can:** open, close, accept demand, generate orders, incur transactions. +**Cannot:** own the global market model or independently recalculate historical forecasts. +**Invariant:** Every active service has one location, one calendar state, and one authoritative ledger. + +## 11.3 Restaurant Concept + +**Knows:** promise, service format, price tier, target occasions, style tags. +**Can:** influence expectations, segment fit, capability requirements. +**Cannot:** directly grant quality or demand. +**Invariant:** Concept effects occur through expectations, fit, and constraints. + +## 11.4 Customer Party + +**Knows:** its own preferences, budget, patience, observed experience, prior memories. +**Can:** consider, arrive, wait, order, eat, complain, pay, review, return, leave. +**Cannot:** see hidden kitchen state, teleport, ignore capacity, revise memory retroactively. +**Invariant:** Every satisfaction effect traces to an observed or communicated event. + +## 11.5 Table + +**Knows:** capacity, location, state, merge relationships, reservation hold. +**Can:** be reserved, seated, occupied, cleared, reset. +**Cannot:** seat incompatible parties or exist in two states at once. +**Invariant:** A seat cannot serve two parties simultaneously. + +## 11.6 Order + +**Knows:** party, server, line items, courses, timestamps, modifications. +**Can:** be entered, confirmed, amended before lock, fired, completed, voided. +**Cannot:** silently change after confirmation. +**Invariant:** Financial and production quantities reconcile with line items and explicit voids. + +## 11.7 Dish Ticket + +**Knows:** recipe variant, quantity, table/course, required tasks, current stage, timestamps. +**Can:** queue, start, pause, complete, hold, fail, remake, deliver. +**Cannot:** skip dependencies or consume nonexistent ingredients. +**Invariant:** Every delivered dish has a traceable production history. + +## 11.8 Recipe + +**Knows:** static authored definition and process requirements. +**Can:** generate task requirements and expected inputs. +**Cannot:** store live inventory, chef state, or customer-specific outcomes. +**Invariant:** Runtime execution modifies a dish ticket, not the recipe definition. + +## 11.9 Recipe Variant + +**Knows:** parent recipe and explicit deltas. +**Can:** alter ingredients, process, portion, presentation, price eligibility. +**Cannot:** mutate its parent. +**Invariant:** Variant changes are inspectable and reproducible. + +## 11.10 Ingredient Lot + +**Knows:** quantity, quality, freshness, cost, supplier, dates, storage. +**Can:** be received, reserved, consumed, spoiled, transferred. +**Cannot:** become fresher or appear without a transaction. +**Invariant:** Quantity is conserved through explicit movements and waste. + +## 11.11 Supplier + +**Knows:** catalog, price, quality range, schedule, reliability, terms. +**Can:** quote, accept order, deliver, substitute, fail within modeled risk. +**Cannot:** alter player inventory directly without a delivery transaction. +**Invariant:** Every delivery has an order or documented emergency source. + +## 11.12 Employee + +**Knows:** own skills, traits, schedule, assigned role/task, observable local state. +**Can:** accept tasks, work, learn, tire, communicate, request, resign. +**Cannot:** teleport, perform an unqualified task without penalty/rule, know global hidden state. +**Invariant:** An employee performs at most one exclusive task at a time. + +## 11.13 Shift + +**Knows:** restaurant, employee, start/end, role, station/section, break. +**Can:** activate, pause for break, complete, incur labor. +**Cannot:** overlap illegally unless explicitly authorized. +**Invariant:** Labor cost derives from actual shift time and pay rules. + +## 11.14 Station + +**Knows:** equipment, capacity, assigned staff, queue, cleanliness, local prep. +**Can:** accept eligible tasks, reserve capacity, process, block. +**Cannot:** perform unsupported techniques. +**Invariant:** Capacity reservations cannot exceed usable capacity. + +## 11.15 Manager Policy + +**Knows:** allowed decisions, targets, thresholds, escalation rules. +**Can:** authorize routine AI decisions within bounds. +**Cannot:** override owner-reserved decisions. +**Invariant:** Every delegated decision records actor, policy, information, and reason. + +## 11.16 Market + +**Knows:** segments, demand, trends, competitor public state, calendar. +**Can:** generate attempted visits and opportunity forecasts. +**Cannot:** determine customer satisfaction after service. +**Invariant:** Demand creation and delivered satisfaction remain separate. + +## 11.17 Competitor + +**Knows:** its own abstract state and public market information. +**Can:** price, promote, hire, improve, expand, close. +**Cannot:** use player-only hidden data. +**Invariant:** Difficulty changes resources/decision quality, not omniscience. + +## 11.18 Review + +**Knows:** experience snapshot, reviewer traits, salient moments, publication time. +**Can:** affect awareness, expectations, and reputation. +**Cannot:** be recomputed when formulas or current restaurant state change. +**Invariant:** Historical review content is immutable. + +## 11.19 Financial Ledger + +**Knows:** append-only transactions and account mappings. +**Can:** post, reverse with linked entries, summarize. +**Cannot:** edit history silently. +**Invariant:** Cash and reports reconcile to transactions. + +## 11.20 Event + +**Knows:** trigger state, participants, options, delayed consequences. +**Can:** present choices and schedule effects. +**Cannot:** create arbitrary untraceable changes. +**Invariant:** Every effect records source event and chosen response. + +--- + +# 12. Authoritative Technical Architecture + +## 12.1 Architectural rule + +```text +Authoritative Game State +→ validated command +→ deterministic simulation systems +→ new authoritative state +→ read models / snapshots +→ UI, renderer, audio +→ player intent +→ validated command +``` + +The renderer owns no truth. + +The UI may format, filter, sort, and explain. It may not independently calculate the real cash, quality, demand, profit, or forecast. + +## 12.2 Recommended stack + +### Provisional recommendation + +- **Simulation language:** C#/.NET. +- **Presentation engine:** Godot 4.x stable production release at the time the project locks its engine. +- **Primary platform:** Windows desktop, mouse and keyboard. +- **Simulation packaging:** engine-agnostic class library with a command-line harness. +- **Testing:** standard .NET unit/property/integration test projects. +- **Content:** schema-validated external data imported into typed runtime definitions. + +### Why this is the default + +- C# is highly legible to a small team and AI agents. +- Mature test and serialization tools reduce custom infrastructure. +- Godot supports headless execution and can remain a presentation shell around a separate simulation. +- Open licensing reduces engine-business risk. +- A desktop-first UI suits information-dense management play. + +### Alternatives + +**Unity 6 LTS** + +Choose if: + +- the team already knows Unity; +- asset-store and console pipelines matter; +- a stronger commercial tooling ecosystem outweighs project complexity. + +Do not place business rules in MonoBehaviours or scenes. + +**Bevy/Rust** + +Choose only if: + +- the team has strong Rust experience; +- data-oriented performance is a primary need; +- API evolution and lower editor maturity are acceptable. + +Its headless, fixed-timestep, ECS, diagnostics, and stress-test patterns are valuable research references, but it is not the default recommendation for a non-expert two-person team. + +### Engine decision gate + +Before commitment, build the same tiny test in the two leading options: + +- 200 moving agents; +- selectable tables/stations; +- UI panel with live read model; +- pause and speed changes; +- headless simulation invocation; +- save/load sample; +- pathfinding update after furniture move. + +Judge: + +- iteration speed; +- UI productivity; +- agent coding reliability; +- profiling; +- build/export; +- maintainability; +- performance on target hardware. + +## 12.3 Hybrid domain architecture + +Do not force every concept into one architecture pattern. + +Use: + +- **domain aggregates** for restaurant, menu, ledger, schedule, supplier contracts; +- **data-oriented entities/components** for high-volume runtime agents, tasks, tickets, and paths; +- **immutable definitions** for recipes, ingredients, equipment, traits, and content; +- **events** for cross-system facts; +- **commands** for requested state changes; +- **read models** for UI. + +A full ECS is not automatically superior. It can make domain rules harder to understand if applied indiscriminately. + +## 12.4 Time and deterministic order + +Define a documented system order, for example: + +```text +1. Apply player/AI commands +2. Calendar and scheduled events +3. Demand and arrivals +4. Reservations and seating +5. FOH task allocation +6. Order and course release +7. Kitchen task allocation +8. Movement and path reservations +9. Task progress +10. Dish/pass/delivery transitions +11. Customer consumption and patience +12. Satisfaction and departure +13. Inventory and waste +14. Employee fatigue, learning, morale +15. Finance postings +16. Event generation +17. Metrics and read-model snapshot +``` + +Parallel execution is allowed only where ordering cannot change results or where reduction order is controlled. + +## 12.5 Randomness + +Use named, seeded streams: + +- market; +- arrivals; +- customer choice; +- execution variance; +- employee events; +- supplier events; +- competitor decisions; +- narrative events. + +Never call raw global randomness. + +Every test can: + +- set seed; +- replay commands; +- reproduce outcome; +- inspect random-stream usage. + +## 12.6 Event log and causal trace + +Log meaningful events: + +- party arrived; +- seated; +- order placed; +- task queued; +- ingredient unavailable; +- station blocked; +- dish completed; +- dish held; +- delivered; +- complaint; +- comp; +- review; +- transaction. + +The player-facing explanation system uses this event history to construct causal summaries. Avoid full event sourcing of every internal mutation unless testing proves it necessary. + +## 12.7 Persistence + +### Save package + +- schema version; +- content manifest versions; +- authoritative state snapshot; +- RNG stream states; +- scheduled events; +- immutable historical records; +- ledger; +- forecast snapshots; +- optional event tail; +- checksum; +- metadata preview. + +### Requirements + +- rotating autosaves; +- manual saves; +- atomic write then replace; +- validation before overwrite; +- recovery save; +- migrations; +- backward-compatibility tests; +- mid-service save/load tests; +- missing-mod diagnostics; +- no silent data deletion. + +OpenTTD's long-running commitment to loading old save revisions is the aspirational model: save compatibility is a product feature, not housekeeping. + +## 12.8 Content architecture + +Each definition has: + +- stable namespaced ID; +- schema version; +- localization key; +- source/provenance; +- tags; +- dependencies; +- validation rules. + +Content categories: + +- ingredients; +- recipes; +- techniques; +- equipment; +- furniture; +- traits; +- roles; +- segments; +- districts; +- events; +- objectives; +- awards; +- suppliers. + +Runtime code never relies on display names as identifiers. + +## 12.9 Mod strategy + +### Launch-capable foundation + +- data registries; +- stable IDs; +- load ordering; +- validation; +- dependency manifests; +- save manifest; +- conflict reporting. + +### Initial mod support + +- data-only recipes; +- ingredients; +- furniture; +- events; +- localization; +- scenarios. + +### Later + +- scripted systems; +- total conversions; +- workshop integration. + +Do not promise code mods until save, security, and API stability are mature. + +## 12.10 Pathfinding and movement + +### Architecture + +- high-level zone/room graph; +- local grid or navigation mesh; +- cached paths; +- dynamic obstacle updates; +- destination reservation; +- queue positions; +- congestion costs; +- stuck detection; +- deterministic tie-breaking. + +### Separation + +Task selection decides **what** an agent should do. Pathfinding decides **how** to reach it. Neither silently overrides the other. + +### Performance + +- do not repath every agent every tick; +- invalidate only affected routes; +- use local avoidance sparingly; +- abstract off-screen or inactive restaurants; +- maintain a reproducible crowd benchmark. + +## 12.11 AI task allocation + +Use explicit task objects with: + +- type; +- target; +- priority; +- deadline; +- required qualification; +- reservation state; +- estimated duration; +- source; +- cancellation rule. + +Employees score eligible tasks using: + +- role; +- assignment; +- distance; +- urgency; +- section/station; +- current task; +- workload; +- policy. + +The player can inspect why a task is waiting and why an employee selected another task. + +## 12.12 Testing layers + +### Unit + +- formulas; +- state transitions; +- eligibility; +- conservation; +- pricing; +- scheduling. + +### Invariant/property + +- no negative inventory without explicit debt/backorder; +- no duplicated seats; +- no employee performing two exclusive tasks; +- cash reconciles; +- delivered dishes have completed dependencies; +- save/reload produces same future outcome; +- speed does not alter result. + +### Golden scenarios + +- fixed restaurant; +- fixed seed; +- fixed commands; +- expected event trace and outcome. + +### Distribution harness + +Run thousands of services/careers across named strategies: + +- focused value; +- focused premium; +- broad neighborhood; +- understaffed aggressive; +- overstaffed quality; +- overmarketed unready; +- high-quality low-awareness; +- cheap low-skill; +- seasonal specialist; +- reckless expansion; +- conservative cash; +- manager-led chain. + +Measure: + +- median; +- p10/p90; +- failure probability; +- cash drawdown; +- recovery time; +- choice frequency; +- bottleneck distribution; +- segment satisfaction; +- strategy dominance. + +### Persistence + +- all supported save versions; +- corrupted save; +- interrupted write; +- mid-service; +- after content update; +- missing optional content. + +### Performance + +- active-agent crowd; +- peak ticket volume; +- path invalidation; +- 10x simulation; +- empire dashboard with abstract locations; +- long-run memory stability. + +## 12.13 Tooling + +Build tools before content volume: + +- recipe validator; +- ingredient-network viewer; +- station-load calculator; +- scenario editor; +- event validator; +- save inspector; +- deterministic replay viewer; +- performance overlay; +- pathfinding heatmap; +- task-queue inspector; +- economic harness; +- localization checker; +- content dependency graph. + +--- + +# 13. Information Architecture and UI + +## UI principle + +A management game is an information game. Every major decision view must communicate: + +1. Current state. +2. Available options. +3. Expected consequence. +4. Risk and uncertainty. +5. Commitment. +6. Actual result. +7. Why result differed. + +## Primary views + +### Restaurant overview + +- today/next service; +- demand; +- bookings; +- staffing gaps; +- stock risks; +- cash; +- urgent exceptions; +- recent reputation changes. + +### Live service + +- restaurant view; +- party patience; +- table states; +- server sections; +- station queues; +- ticket timeline; +- dishwashing; +- alerts; +- intervention controls. + +### Post-service autopsy + +- what was forecast; +- actual covers/check/profit; +- customer funnel; +- time distribution; +- station bottlenecks; +- top delayed tickets; +- complaints; +- lost sales; +- labor; +- waste; +- causal recommendations. + +### Menu lab + +- recipe list; +- menu architecture; +- price; +- popularity; +- contribution; +- station load; +- ingredients; +- mastery; +- segment fit; +- complexity; +- forecast comparison. + +### Workforce + +- schedule; +- coverage; +- sections/stations; +- wages; +- skill matrix; +- training; +- fatigue; +- morale; +- career risk. + +### Layout + +- build tools; +- valid placement; +- path and congestion heatmaps; +- table mix; +- seat-hour model; +- equipment utilization; +- saved blueprints. + +### Finance + +- cash; +- P&L; +- unit economics; +- prime cost; +- runway; +- loans; +- capital plan; +- forecast snapshots. + +### Empire + +- portfolio scorecard; +- exceptions; +- same-store sales; +- unit profit; +- leader status; +- brand; +- expansion pipeline; +- capital allocation. + +## Alert philosophy + +Alerts are: + +- actionable; +- prioritized; +- attributable; +- suppressible when a policy handles them. + +Bad alert: + +> Customers are unhappy. + +Good alert: + +> Four dinner parties waited more than 18 minutes for entrées because the sauté station received 63% of all main-course work between 7:10 and 7:40. Two menu changes or one station-capacity change are available. + +## Forecast display + +Use: + +- expected range; +- confidence; +- key assumptions; +- biggest downside; +- biggest opportunity; +- change from prior plan. + +Do not expose unexplained raw vectors. + +## Tutorial + +- contextual; +- skippable; +- scenario-driven; +- teaches one decision at a time; +- never locks the player into an extended dialogue chain; +- includes “why” and causal feedback; +- lets experienced players begin in sandbox. + +--- + +# 14. Milestone Roadmap and Proof Gates + +## M-1 — Product Lock + +### Question + +Can the owners state one fantasy, one target player, one launch platform, and one product question without contradiction? + +### Deliverables + +- vision; +- pillars/anti-pillars; +- feature-parity charter; +- glossary; +- target platform decision; +- legal naming plan; +- engine candidates; +- research archive; +- M0 contract. + +### Non-goals + +- code; +- final formulas; +- content production; +- art style production. + +### Pass + +Every proposed feature can be traced to the fantasy and one meaningful decision. Expensive-to-reverse assumptions are named. + +--- + +## M0 — Headless Service Lab + +### 1. Product question + +Can a player form, execute, diagnose, and revise a restaurant operating strategy using only menu, price, staffing, and capacity choices? + +### 2. Target reaction + +A fresh player says, without prompting: + +> “I know why that service went badly, and I want to change the plan and run it again.” + +### 3. Authorized scope + +- one abstract restaurant; +- one district; +- three customer segments; +- three occasions; +- 12 recipes; +- four kitchen stations; +- eight employees; +- lunch and dinner; +- menu selection; +- prices; +- staffing; +- station assignment; +- seat capacity/table mix abstraction; +- service simulation; +- causal report; +- deterministic seed; +- batch harness. + +### 4. Hard non-goals + +Do not build: + +- 2D/3D restaurant; +- movement/pathfinding; +- furniture; +- décor; +- inventory lots; +- suppliers; +- recipe editor; +- campaign; +- competitors; +- staff relationships; +- awards; +- multiplayer; +- mods; +- localization; +- final save system; +- final UI. + +### 5. Effort cap + +25–40 focused builder hours before mandatory review. + +### 6. Required systems + +- state; +- command processing; +- demand; +- customer choice; +- order generation; +- station queues; +- staff capacity; +- dish outcome; +- satisfaction; +- finance; +- report; +- seeded randomness; +- strategy harness. + +### 7. Placeholder policy + +- text/terminal or minimal browser/desktop form; +- hand-authored round numbers; +- no production assets; +- no animations; +- no simulated walking; +- no content polish. + +### 8. Evidence + +- five uncoached player sessions; +- command logs; +- post-service reports; +- distribution output for named strategies; +- recorded pass/fail notes; +- independent review. + +### 9. Pass criteria + +- at least four of five fresh testers correctly describe their intended strategy; +- at least four diagnose the primary bottleneck after service; +- at least three voluntarily run another service; +- at least three strategy families are viable in different market scenarios; +- no single menu/staffing option dominates all tested contexts; +- reports reconcile financially; +- same state/seed/commands reproduce the same result. + +### 10. Fail/stop conditions + +Stop and redesign if: + +- players optimize one obvious number rather than form a restaurant plan; +- outcomes feel arbitrary; +- one strategy dominates; +- players cannot connect result to decision; +- replay desire is weak; +- the effort cap is reached without an honest test. + +### 11. Repository boundary + +Standalone prototype repository or clearly isolated root package with no dependency from production presentation code. + +### 12. Owner decision + +Continue, rewrite the core model, narrow the fantasy, or abandon. + +--- + +## M0.5 — Calibration and Explanation + +### Question + +Can the model remain balanced across many seeds and can a player understand uncertainty? + +### Scope + +- named strategy library; +- scenario fixtures; +- distribution metrics; +- persisted pre-service forecasts; +- actual-vs-forecast autopsy; +- economic reconciliation. + +### Pass + +- failures occur for understandable reasons; +- expected value is sensible before variance is widened; +- uncertainty narrows with better information; +- reports preserve what was known at decision time. + +--- + +## M1 — Spatial Gray-Box Restaurant + +### Question + +Does physical layout create readable, interesting decisions beyond the headless capacity model? + +### Scope + +- one floor; +- entrance; +- host; +- dining; +- kitchen; +- pass; +- dishwashing; +- restroom; +- basic storage; +- placeholder tables/equipment; +- customer/staff movement; +- sections/stations; +- congestion; +- live service; +- heatmaps. + +### Non-goals + +- final art; +- multiple floors; +- multiple restaurants; +- décor catalog; +- advanced inventory; +- campaign; +- custom recipes; +- multiplayer. + +### Pass + +- first-time players can identify a visible bottleneck; +- layout changes produce expected effects; +- no routine deadlock; +- stuck agents self-report and recover; +- moving a table or equipment invalidates only required paths; +- camera, scale, selection, and occlusion are locked on target hardware; +- service remains deterministic at rule level across speed settings. + +--- + +## M2 — Persistent Restaurant + +### Question + +Do decisions remain meaningful over eight to twelve simulated weeks? + +### Scope + +- actual calendar; +- schedules; +- payroll; +- inventory lots; +- prep; +- suppliers; +- waste; +- maintenance; +- staff learning; +- morale; +- reviews; +- repeat customers; +- marketing; +- robust save/load. + +### Pass + +- focused and broad menus create different long-horizon pressures; +- labor decisions affect both service and retention; +- inventory policies create risk without clerical overload; +- save/load is reliable at all key states; +- no solved “always maximum” policy. + +--- + +## M3 — Identity and Progression + +### Question + +Does the restaurant develop an identity the player can describe and care about? + +### Scope + +- restaurant concept; +- recipe variants/development; +- signature dishes; +- chef careers; +- critics; +- awards; +- capability upgrades; +- special events; +- renovations; +- one complete progression arc. + +### Pass + +- testers describe their restaurant differently; +- restaurant identity emerges from decisions, not a selected label alone; +- progression unlocks capabilities rather than generic multipliers; +- signature dishes have both upside and operational cost. + +--- + +## M4 — Delegation and Second Location + +### Question + +Can expansion create higher-level decisions without doubling routine work? + +### Scope + +- second location; +- manager policies; +- staff transfers; +- templates; +- centralized reports; +- shared purchasing options; +- cannibalization; +- leader bench; +- expansion forecast. + +### Pass + +- the second location can operate without constant manual intervention; +- the player manages exceptions and policy; +- same-brand and new-concept expansion have different rational cases; +- overexpansion is dangerous but recoverable; +- opening does not require rebuilding every solved configuration manually. + +--- + +## M5 — Living City and Competition + +### Question + +Does the market force adaptation and create stories without feeling arbitrary? + +### Scope + +- several districts; +- abstract competitors; +- labor market; +- market trends; +- neighborhood events; +- supplier competition; +- openings/closures; +- acquisition opportunities. + +### Pass + +- competitors alter rational decisions; +- player can explain market changes; +- AI does not cheat; +- the city evolves without destabilizing every week; +- events connect to state and offer tradeoffs. + +--- + +## M6 — Campaign and Scenario System + +### Question + +Can scenarios teach and challenge through changed rules rather than repeated setup? + +### Scope + +- scenario scripting; +- objectives; +- story characters; +- rival group; +- carryover rules; +- skip-ready tutorials; +- six representative scenarios. + +### Pass + +- each scenario changes at least one strategic assumption; +- no scenario depends primarily on waiting; +- the player can use templates and prior knowledge; +- story supports rather than interrupts management. + +--- + +## M7 — Production Content and Presentation + +### Scope + +- final art direction; +- animation; +- audio; +- accessibility; +- full content; +- localization foundation; +- performance optimization; +- complete campaign; +- sandbox generation; +- onboarding. + +### Gate + +No production content volume begins before M3 has passed. + +--- + +## M8 — Release Readiness + +### Scope + +- stability; +- save compatibility; +- balance; +- platform QA; +- accessibility; +- tutorial; +- performance; +- crash recovery; +- content provenance; +- legal review; +- mod data foundation; +- telemetry review; +- economy exploit review. + +### Release condition + +The game is not “done” because features exist. It is ready when a fresh player can understand, enjoy, recover from failure, and sustain a career without one dominant strategy or intolerable micromanagement. + +--- + +# 15. Proposed Commercial Scope + +This is a ceiling to test, not an authorization to build immediately. + +## Launch focus + +- full-service restaurants; +- one city; +- four distinct districts; +- three cuisine families; +- one cross-cultural recipe-development system; +- approximately 60–90 well-differentiated base recipes; +- 30–45 ingredients with meaningful cross-utilization; +- 20–30 techniques/process components; +- one campaign of approximately 10–12 scenarios; +- sandbox; +- up to 4–6 owned locations in a normal career; +- staff careers and manager delegation; +- critics, fictional awards, and competitions; +- data-only mod foundation. + +## Deliberately outside launch + +- delivery marketplace; +- food trucks; +- hotels; +- farming; +- franchises; +- multiplayer; +- international cities; +- celebrity media career; +- full code mods; +- real-world Michelin branding; +- detailed alcohol production; +- organized crime/politics systems; +- mobile and console launch parity. + +A “definitive” simulation is created by strong system interaction, not by promising every hospitality format at version 1.0. + +--- + +# 16. Expansion Roadmap and Architectural Dependencies + +## Delivery and takeout + +Requires: + +- packaging; +- delivery timing; +- order-channel throttling; +- separate menu variants; +- kitchen queue priority; +- reputation by channel. + +Architectural requirement: orders already support source/channel and promised time. + +## Bars and nightlife + +Requires: + +- bar seating; +- beverage production; +- intoxication policy abstraction; +- late-night demand; +- entertainment; +- security, possibly. + +Architectural requirement: restaurant concept and station systems support non-kitchen production. + +## Cafés, bakeries, and dessert houses + +Requires: + +- batch production; +- display inventory; +- morning demand; +- counter service; +- takeaway; +- shelf life. + +Architectural requirement: service formats cannot assume table service. + +## Catering and events + +Requires: + +- project contracts; +- off-site production; +- capacity reservations; +- temporary staffing; +- logistics; +- reputation risk. + +Architectural requirement: a service can occur outside a permanent restaurant. + +## Food trucks and pop-ups + +Requires: + +- mobile locations; +- weather; +- permits abstraction; +- tiny capacity; +- event demand. + +Architectural requirement: location and restaurant are separate concepts. + +## Fine-dining prestige + +Requires: + +- tasting menus; +- reservation deposits; +- critic system; +- advanced course pacing; +- service rituals; +- chef reputation. + +Architectural requirement: orders support fixed menus and synchronized courses. + +## Franchising + +Requires: + +- standards; +- franchise contracts; +- royalties; +- audits; +- territory; +- franchisee quality; +- brand risk. + +Architectural requirement: ownership, brand, and operator are separate. + +## Acquisitions + +Requires: + +- valuation; +- due diligence; +- hidden liabilities; +- integration; +- leader retention; +- rebranding. + +Architectural requirement: restaurants can change ownership without losing history. + +## International expansion + +Requires: + +- currencies; +- labor/regulation profiles; +- cuisine familiarity; +- supplier networks; +- localization; +- regional management. + +Architectural requirement: money and rules cannot be hard-coded globally. + +## Multiplayer/co-op + +Requires early architectural restraint but not launch implementation: + +- authoritative host/server; +- commands; +- conflict resolution; +- deterministic or server-authoritative state; +- permissions; +- pause policy. + +Do not promise multiplayer until a contested management interaction is prototyped with real latency. + +--- + +# 17. Risk Register + +| Risk | Why it is dangerous | Early signal | Mitigation | Kill/rewrite trigger | +|---|---|---|---|---| +| Core loop becomes spreadsheet optimization | Operations lack emotion and temporality | Players stare at margin only | Service stories, spatial proof, causal events | Players do not want to rerun | +| Recipe editor is a toy | Creation has no downstream consequence | Recipes differ mostly by name | Process graph, segment fit, station load, tests | One formula produces best recipe | +| Pathfinding consumes project | Spatial simulation becomes engineering sink | Repeated stuck-agent bugs | Simple grid, reservations, benchmark, separate task AI | M1 cannot produce stable service | +| Staff AI feels unfair | Player punished by hidden choices | “Why is nobody doing this?” | inspectable tasks, assignments, reasons | Players blame AI more than strategy | +| Micromanagement explosion | More restaurants mean more clicks | routine alerts rise linearly | templates, policies, managers, batch actions | M4 doubles routine work | +| Over-simulation | Systems exist without decisions | invisible state dominates code | purpose/interaction test, abstraction | player cannot perceive system | +| One dominant strategy | Replay collapses | same menu/staffing always wins | scenario matrix, distributions | option dominates all contexts | +| Realistic margins feel unrewarding | Progress is numerically invisible | players ignore finances | readable scale, stronger early margins | cash feels irrelevant or hopeless | +| Marketing becomes free money | Demand has no downside | max spend always selected | expectations, capacity, diminishing returns | one spend level dominates | +| Content explosion | Team builds recipes instead of game | dozens before 12 are balanced | content gate and validators | new content masks core weakness | +| Expansion repeats setup | Empire fantasy becomes clerical | second location feels identical | blueprints, manager policy, transfer | players avoid expansion | +| Character system becomes RimWorld-lite | Scope and bugs explode | irrelevant needs/relationships | restaurant-decision rule | traits do not affect choices | +| Random events feel punitive | Story generator loses trust | no preparation or recovery | state-based event contracts | players reload to avoid events | +| Save corruption | Destroys emotional investment | autosave or migration failures | atomic saves, rotation, compatibility tests | any unrecoverable career loss | +| AI agent scope creep | Prototype becomes production tangle | unrequested systems appear | hard non-goals, separate reviewer | contaminated repository | +| Engine lock-in | rules tied to scenes/objects | headless harness needs engine | engine-agnostic core | cannot run sim without renderer | +| Performance at time acceleration | management games need fast-forward | speed alters behavior or stalls | fixed tick, abstraction, benchmarks | 4x cannot sustain target | +| UI hides balance | good math feels arbitrary | players miss controls/risks | hierarchy, forecast, explanation | comprehension tests fail | +| Campaign becomes tutorial prison | replay and experienced players suffer | unskippable sequence | sandbox, skip, contextual learning | players abandon onboarding | +| IP confusion | product appears official/derivative | reused names/art/story | original brand, assets, text, counsel | unresolved clearance before marketing | + +--- + +# 18. Legal and Brand Guardrail + +This is a spiritual successor, not a source-code recreation. + +Do not reuse: + +- “Restaurant Empire” as the product title without clearance and rights; +- character names; +- OmniFood; +- story dialogue; +- logos; +- user-interface art; +- recipe descriptions; +- music; +- textures; +- models; +- source code; +- campaign text; +- distinctive marketing presentation. + +Mechanics and methods of play are treated differently from creative expression under U.S. copyright principles, but names, branding, code, art, text, and audiovisual expression create separate risks. Conduct a professional trademark and IP review before public branding or commercial release. + +Create original: + +- title; +- fictional city/world; +- rival organization; +- characters; +- visual identity; +- narrative; +- recipe prose; +- UI; +- data; +- sound. + +Maintain `CONTENT_PROVENANCE.md` for every external asset and dataset. + +--- + +# 19. GitHub and Open-Source Research Lessons + +## OpenRCT2 + +Learn: + +- modernization can preserve an old game's identity while improving interface, limits, AI, tools, and platforms; +- scenario and sandbox can coexist; +- plugins and editing tools extend longevity; +- command-line/headless operation supports automation and testing. + +Do not copy GPL code into a proprietary project without understanding license obligations. + +## OpenTTD + +Learn: + +- save compatibility can become a durable product promise; +- regression suites deserve a first-class repository location; +- simulation games benefit from stable data formats and long-lived migrations; +- add-on content works best with explicit contracts. + +## CorsixTH + +Learn: + +- rooms, staff fatigue, qualifications, training, and facility dependencies create understandable operational loops; +- an open reimplementation can separate original assets from new engine work; +- room capabilities are more legible than abstract bonuses. + +## Godot demos + +Learn: + +- use official navigation, pathfinding, headless, save/load, and UI demonstrations as references; +- branch/version matching matters; +- platform behavior must be verified on target hardware. + +## Bevy examples + +Learn: + +- headless applications; +- fixed timesteps; +- custom schedules; +- diagnostics; +- stress tests; +- serialization; +- system-order nondeterminism detection. + +Caution: + +- active API evolution and Rust complexity may be expensive for this team. + +## Open-source code policy + +Use repositories to study: + +- folder boundaries; +- testing; +- tooling; +- save migration; +- command-line entry points; +- content registries; +- plugin APIs; +- pathfinding diagnostics. + +Do not copy code merely because it is visible. Record license and provenance before adopting any dependency or pattern requiring attribution. + +--- + +# 20. AI-Agent Implementation Workflow + +## Evidence fan-out + +Before a major system: + +1. Several read-only agents research separate questions. +2. The owner locks one design spine. +3. Builders implement non-overlapping slices. +4. One independent agent checks system seams. +5. The owner verifies on real hardware. + +## Builder brief template + +```text +CONTEXT +Why this slice exists. + +VERIFIED STARTING STATE +What is actually present now; re-check it. + +ONE PRODUCT QUESTION +A falsifiable pass/fail question. + +AUTHORIZED SCOPE +Exact systems/files allowed. + +HARD DO-NOT-BUILD LIST +Named temptations that are forbidden. + +DESIGN CONTRACT +Definitions, invariants, owners of truth. + +PROVISIONAL MILESTONES +Small checkpoints; report actual deviations. + +TESTS +What automated checks prove and do not prove. + +EVIDENCE +Logs, screenshots, recordings, benchmarks. + +STOP +The exact point at which the agent halts. + +HANDOFF +Update CURRENT_STATE, NEXT_ACTION, DECISIONS, and deferred work. +``` + +## Independent reviewer checklist + +- Reproduce from clean checkout. +- Confirm no unauthorized files or dependencies. +- Inspect design invariants. +- Run tests independently. +- Try invalid commands. +- Compare same-seed replay. +- Save/load mid-state. +- Inspect causal report. +- Challenge dominant strategies. +- Verify screenshots/video, not only green tests. +- State verdict and action. + +## No silent decisions + +An agent must not silently: + +- add a system; +- change a formula; +- introduce a dependency; +- alter save schema; +- rename stable IDs; +- add RNG; +- move engine truth into UI; +- change milestone scope; +- “improve” a locked invariant. + +It must stop and surface the decision. + +--- + +# 21. Areas Requiring Prototyping + +Ranked by expensive-to-reverse risk. + +## 1. Core service decision loop + +Will menu, price, staffing, and capacity produce compelling revision? + +## 2. Causal explanation + +Can the game explain a failure without exposing incomprehensible math? + +## 3. Spatial pathfinding and task AI + +Can a busy service remain stable and readable? + +## 4. Recipe development + +Can creativity coexist with balance, or will players discover one optimal construction formula? + +## 5. Menu complexity + +Does an emergent complexity cost work better than a hard menu cap? + +## 6. Customer segmentation + +How many segments create strategy without noise? + +## 7. Active service control + +How much intervention feels managerial rather than frantic? + +## 8. Thin-margin economy + +What degree of abstraction preserves pressure while keeping progress satisfying? + +## 9. Staff character depth + +What is the minimum personality model that creates attachment and staffing decisions? + +## 10. Delegation + +Can manager policies feel trustworthy and inspectable? + +## 11. Multi-location abstraction + +When should a restaurant continue full simulation, reduced simulation, or statistical simulation? + +## 12. Camera and presentation + +2D, 2.5D, or 3D must be proven with selection, occlusion, density, and target hardware. + +## 13. Campaign carryover + +How much progress should carry between scenarios without trivializing them? + +## 14. Competition format + +Can contests feel exciting without mandatory twitch play? + +## 15. Mod data boundary + +Which content types can be safely extended while preserving saves? + +--- + +# 22. Questions the Owners Still Need to Answer + +These are ordered by cost of reversing the answer. + +## Product and platform + +1. Is Windows desktop the first and only launch platform? +2. Is the game mouse-and-keyboard first? +3. Is the world 2D, 2.5D, or fully 3D? +4. Is the camera fixed-isometric, rotatable, or free? +5. Is single-player the only launch requirement? +6. Is commercial release the goal or a private project? + +## Fantasy and tone + +7. Is the player explicitly a chef-owner, an owner-operator, or an unnamed business founder? +8. Is the tone grounded, playful, satirical, or cartoonish? +9. Is food culture treated realistically, fictionally, or as an exaggerated world? +10. Is the emotional center the restaurant, the employees, the chef, or the empire? +11. Can the player become famous personally, or only build famous restaurants? + +## Service interaction + +12. Can the player pause? +13. How much can the player change during live service? +14. Are emergency interventions limited resources or ordinary controls? +15. Is direct cooking ever playable? +16. Is a service watched continuously or summarized when the player chooses? + +## Simulation depth + +17. Should inventory use recipe portions, standardized units, or detailed weights? +18. Are dietary restrictions central or supporting? +19. How realistic should alcohol service be? +20. Are taxes, leases, and labor law merely abstractions? +21. Should weather exist at launch? +22. Should restaurants close between services for explicit prep? + +## Content and authorship + +23. How free is recipe creation? +24. Can players name recipes and write descriptions? +25. Can recipes violate real culinary logic? +26. Is cuisine authenticity a mechanic, a tag, or not judged? +27. How many cuisine families are required for launch identity? +28. Are user-created recipes shareable? + +## Progression + +29. Campaign first or sandbox first? +30. Does campaign progress carry into sandbox? +31. Is bankruptcy a hard game over? +32. Can the player sell a restaurant and continue? +33. Is there an end state or only legacy goals? +34. Does time advance across years and generations? + +## Business growth + +35. Is launch scope one restaurant, several locations, or a true empire? +36. Are all restaurants fully simulated while viewed? +37. Does the player own brands, individual restaurants, or a holding company? +38. Are acquisitions required at launch? +39. Is franchising a core fantasy or expansion? + +## Art and identity + +40. What is the visual comparison target? +41. How stylized are people and food? +42. Must dishes be visually represented individually? +43. How much object customization matters? +44. Is there an original fictional city or real-world cities? +45. What title and brand can be legally cleared? + +## Production constraints + +46. What is the actual team skill profile? +47. Which engine does the builder already understand? +48. What hardware is the minimum target? +49. What budget exists for art, audio, legal, and QA? +50. How much original content can the team realistically produce? +51. Will outside modders or contributors be supported? +52. Who has final design authority when the brothers disagree? + +--- + +# 23. Locked Decisions Recommended Now + +Unless the owners reject them explicitly, lock these for M0: + +1. The fantasy sentence in Section 0. +2. Desktop-first single-player. +3. Pause and speed controls. +4. Menu as the central strategic system. +5. Demand and satisfaction remain separate. +6. One authoritative simulation truth. +7. Headless deterministic harness before a visual restaurant. +8. C# engine-agnostic simulation core. +9. No production art before M1 passes. +10. No multiple restaurants before persistent single-restaurant play passes. +11. No delivery, franchising, multiplayer, or code mods for launch proof. +12. Every new capability must create a tradeoff. +13. Every historical forecast/review/result remains immutable. +14. Every AI decision and task wait can be explained. +15. Expansion must reduce routine work through delegation and templates. +16. The original game's creative expression will not be reused. + +--- + +# 24. Immediate Next Planning Sequence + +No production coding begins yet. + +## Step 1 — Owner answer sheet + +Answer the expensive-to-reverse questions in Section 22, beginning with platform, camera, player role, tone, and service interaction. + +## Step 2 — Research lock + +Create a source-backed archaeology table for every original feature: + +```text +Feature +Verified original behavior +Why players valued it +Known failure +Preserve/Modernize/Deepen/Replace/Defer/Remove +Target successor behavior +Proof milestone +``` + +## Step 3 — M0 numeric design + +Author only: + +- three customer segments; +- three occasions; +- 12 recipes; +- four stations; +- eight employees; +- three market scenarios; +- 10 named strategies; +- initial economic targets. + +Do not add content outside that matrix. + +## Step 4 — M0 interface mock + +Create a clickable or paper mock for: + +- pre-service plan; +- commit; +- service result; +- causal autopsy; +- revise. + +Test comprehension before the simulation is complete. + +## Step 5 — Engine bake-off + +Run the small engine decision gate only after M0 proves the loop. + +## Step 6 — Builder contract + +Hand the chosen coding agent the exact M0 contract, hard non-goals, invariants, tests, evidence requirements, and stop condition. + +## Step 7 — Independent gate + +A separate reviewer verifies technical truth. Then five uncoached players test comprehension and replay desire. + +## Step 8 — Owner decision + +Continue, rewrite, narrow, or abandon. Do not begin M1 merely because M0 runs. + +--- + +# 25. Final Product Standard + +The definitive restaurant management simulation is not the game with the most recipes, cities, furniture, or accounting fields. + +It is the game in which a player can say: + +- “I built this kind of restaurant on purpose.” +- “I understand why tonight succeeded or failed.” +- “My menu changes how the kitchen works.” +- “My staff became a team.” +- “This location has an identity.” +- “Expansion forced me to become a different kind of leader.” +- “The disaster was my fault, but I know how to recover.” +- “My restaurant created a story I want to tell someone.” + +That is the standard against which every system, milestone, and line of code should be judged. + + +--- + +# Appendix A — Research Basis + +This plan synthesizes the following source families. These sources are evidence for design analysis, not specifications to copy. + +## Original game archaeology + +- [Let's Play Archive — Restaurant Empire, Part 1](https://lparchive.org/Restaurant-Empire/Update%2001/) +- [GameFAQs — Trevor Chan's Restaurant Empire Guide and Walkthrough](https://gamefaqs.gamespot.com/pc/561054-trevor-chans-restaurant-empire/faqs/47456) +- [Something Awful — Armand Leboeuf's Kitchen Nightmares: Let's Play Restaurant Empire](https://forums.somethingawful.com/showthread.php?threadid=3862045) +- [Restaurant Empire II — Steam](https://store.steampowered.com/app/32900/Restaurant_Empire_II/) + +## Comparable games and player-response evidence + +- [Chef: A Restaurant Tycoon Game — Steam](https://store.steampowered.com/app/886900/Chef_A_Restaurant_Tycoon_Game/) +- [Chef community reviews](https://steamcommunity.com/app/886900/reviews/?browsefilter=toprated) +- [Big Ambitions — Steam](https://store.steampowered.com/app/1331550/Big_Ambitions/) +- [Big Ambitions community reviews](https://steamcommunity.com/app/1331550/reviews/) +- [Two Point Hospital review — GameSpot](https://www.gamespot.com/reviews/two-point-hospital-review-laughter-is-the-best-med/1900-6416981/) +- [Two Point Campus — Steam](https://store.steampowered.com/app/1649080/Two_Point_Campus/) +- [Dave the Diver — Steam](https://store.steampowered.com/app/1868140/DAVE_THE_DIVER/) +- [Project Highrise — Steam](https://store.steampowered.com/app/423580/Project_Highrise/) +- [RimWorld overview](https://rimworldwiki.com/wiki/About_RimWorld) +- [Factorio systems overview](https://www.factorio.com/game/content) + +## Restaurant operations and economics + +- [Cornell/eCornell — Restaurant Revenue Management](https://ecornell.cornell.edu/certificates/hospitality-and-foodservice-management/restaurant-revenue-management/) +- [National Restaurant Association — Elevated costs and restaurant profitability](https://restaurant.org/research-and-media/research/restaurant-economic-insights/analysis-commentary/elevated-costs-continue-to-pressure-restaurant-profitability/) +- [National Restaurant Association — Restaurant labor costs](https://www.restaurant.org/research-and-media/research/restaurant-economic-insights/analysis-commentary/restaurant-labor-costs-are-well-above-historical-averages/) + +## Architecture and open-source patterns + +- [OpenRCT2](https://github.com/OpenRCT2/OpenRCT2) +- [OpenRCT2 command-line Docker images](https://github.com/OpenRCT2/openrct2-docker) +- [OpenTTD](https://github.com/OpenTTD/OpenTTD) +- [OpenTTD savegame interoperability](https://wiki.openttd.org/en/Manual/Interoperability) +- [CorsixTH](https://github.com/CorsixTH/CorsixTH) +- [Godot demo projects](https://github.com/godotengine/godot-demo-projects) +- [Godot headless/dedicated server documentation](https://docs.godotengine.org/en/stable/tutorials/export/exporting_for_dedicated_servers.html) +- [Bevy examples](https://github.com/bevyengine/bevy/blob/main/examples/README.md) + +## Legal guardrails + +- [U.S. Copyright Office — Games](https://www.copyright.gov/register/tx-games.html) +- [U.S. Copyright Act, Section 102](https://www.copyright.gov/title17/92chap1.html) +- [USPTO — Likelihood of confusion](https://www.uspto.gov/trademarks/search/likelihood-confusion) + +## Internal planning inputs + +- *How to Build Your Next Game Faster* — uploaded project-planning handbook. +- *Start Here* — uploaded quick orientation. +- Uploaded remake-methodology notes emphasizing decision structures, authoritative truth, deterministic harnesses, forecast snapshots, vertical proofs, and save durability. + +Research should continue during each milestone, but new findings do not automatically authorize new scope. diff --git a/docs/assets/ASSET-PROVENANCE.md b/docs/assets/ASSET-PROVENANCE.md new file mode 100644 index 0000000..aef8d40 --- /dev/null +++ b/docs/assets/ASSET-PROVENANCE.md @@ -0,0 +1,24 @@ +# Asset Provenance + +**Status:** M0 uses ZERO external art/audio/animation assets. This file records the asset packages the +owner supplied, their licenses, and their disposition. **None are integrated into M0**, and the binary +source files are deliberately NOT committed to this repository (see `ASSET-QUARANTINE.md` and `.gitignore`). + +The repository may document restricted assets without containing the restricted files themselves. + +## Recorded packages (supplied by the owner, held outside the repo) + +| Package | Source / author | License (as found in the package) | Redistribution | Disposition | +|---|---|---|---|---| +| `Downtown City MegaKit[Standard].zip` (224 MB) | Quaternius (quaternius.com) | **CC0 1.0 Universal** (public-domain dedication), confirmed in bundled `License_Standard.txt` | Permitted (CC0) | **Cleared for future use**, but not in M0 and not committed (repo hygiene: 224 MB of binaries; not needed until a presentation milestone). | +| `Universal Animation Library[Standard].zip` (15 MB) | Quaternius (same author family, "[Standard]" free pack) | `License.txt` present but **empty** in the package; `README.txt` present. Quaternius free packs are CC0 by the author's convention. | **Likely CC0 — CONFIRM at source before use** | Quarantined pending license confirmation at quaternius.com. Not in M0. | +| `FBX-20260727T232629Z-1-001.zip` (1.4 MB) | Unknown (loose FBX props, no bundled license file) | **None found** | **Unknown — do not use** | Quarantined. Provenance must be established before any use. | +| `wintersets.zip` (17 MB) | Unknown legacy installer package (German `Deinstallationsanleitung.txt`, `zapinfo` installer metadata; consistent with a legacy game's set assets) | **None (installer package)** | **Presumed proprietary — do not use** | Quarantined; treat as DO-NOT-USE legacy game content unless the owner produces a clear license. | + +## Rules + +- Confirm every asset's license **twice** before it ever enters a build: the bundled license file AND the + live source page. Record the result here with the date. +- CC0 clearance does not by itself mean "commit the binary to the public repo." Large binaries and + future art belong in a dedicated asset pipeline (e.g. Git LFS or an external store), decided later. +- Nothing here influences M0 architecture. M0 is headless and asset-free by contract. diff --git a/docs/assets/ASSET-QUARANTINE.md b/docs/assets/ASSET-QUARANTINE.md new file mode 100644 index 0000000..6b3082d --- /dev/null +++ b/docs/assets/ASSET-QUARANTINE.md @@ -0,0 +1,32 @@ +# Asset Quarantine + +**Status:** Active. All owner-supplied asset packages are quarantined. None are integrated into M0, none +are committed to this repository, and their availability must NOT influence M0 architecture. + +## Why quarantine +The owner supplied several asset packages (environment kit, animation library, loose FBX props, a legacy +set package). M0 is a headless simulation with graphics, animation, and asset integration on its explicit +non-goals list. Letting available art pull the design toward a renderer now would violate the M0 contract +("do not add a feature merely because the architecture could support it"). + +## Quarantine rules +1. Do not import any of these files into `src/` or any build. +2. Do not commit the binary files to GitHub (this repo is **public**; `.gitignore` blocks `*.zip`, + `*.fbx`, `*.glb`, `*.blend`, images, and audio as defense in depth). +3. Do not let asset availability shape M0 (e.g. do not add a scene format "so the kit could load later"). +4. Record every package in `ASSET-PROVENANCE.md`; record unresolved questions below. + +## Unresolved questions (must be answered before any use, at M1+ at the earliest) +- **Universal Animation Library[Standard]** — the bundled `License.txt` is empty. Confirm the CC0 status + on quaternius.com and record the confirmation (author + license URL + date) before any use. +- **FBX-20260727T232629Z-1-001.zip** — no license file and unknown origin. Establish where these props + came from and under what terms before touching them. +- **wintersets.zip** — a legacy installer package with no clear license; treat as proprietary + game content and **do not use** unless the owner produces explicit rights. +- **Downtown City MegaKit[Standard]** — CC0-confirmed and cleared for future use, but still not committed + here; decide the asset-delivery mechanism (Git LFS vs external store) when a presentation milestone + is actually authorized. + +## Disposition +Quarantined until (a) M1+ is authorized by the owners, and (b) each package's license question above is +resolved and recorded. See `LICENSE-POLICY.md`. diff --git a/docs/assets/LICENSE-POLICY.md b/docs/assets/LICENSE-POLICY.md new file mode 100644 index 0000000..02f4f17 --- /dev/null +++ b/docs/assets/LICENSE-POLICY.md @@ -0,0 +1,27 @@ +# Asset License Policy + +**Status:** Active. Applies to every external art, audio, animation, font, or data asset ever considered. + +## Accepted licenses (decide before you download) +1. **CC0 / public domain** — always acceptable; still record provenance. +2. **Permissive with attribution** (e.g. CC-BY) — acceptable *if* attribution is feasible and recorded. +3. **Paid asset-store "standard" licenses** — acceptable for use in the shipped game ONLY per the exact + terms; **ownership of a license is NOT permission to redistribute the source** in a public repo. + +## Rejected by default +- Anything with unclear or missing license. +- Anything ripped or extracted from another game (e.g. legacy game set files). +- AI-generated assets used as *shippable content* (fine as private reference only; see below). + +## Hard rules +- **Check the license before downloading, not before shipping.** Log it at download time. +- **Never commit paid or restricted source assets to this public repository.** Document them instead. +- **Reference art stays reference.** Concept images, mood boards, screenshots of other games, and + AI-generated thumbnails may inform work; they must never become shipped textures, meshes, or audio. +- Ownership of an asset-store license permits *use as allowed by that license*, which usually does NOT + include public redistribution of the source files. +- Every kept asset gets a row in `ASSET-PROVENANCE.md`: source, license, version, date, and what changed. + +## M0 note +M0 integrates no assets at all. This policy governs M1+ (spatial gray-box) and the later presentation +and production-content milestones. See `../design/DEFERRED-FEATURES.md`. diff --git a/docs/commercial/COMPARABLES.md b/docs/commercial/COMPARABLES.md new file mode 100644 index 0000000..e237c8e --- /dev/null +++ b/docs/commercial/COMPARABLES.md @@ -0,0 +1,52 @@ +# Comparables & Lineage — "Mise" (working codename) + +**Purpose:** Ground the commercial thesis in real, mostly-2020s comparable and lineage titles — what each proves about the audience and what to steal or avoid. + +**Status:** DRAFT / RESEARCH INPUT. Figures are **[VERIFIED]** where web-sourced (July 2026) and **[ASSUMPTION — confirm]** otherwise. Only **M0** is authorized for implementation; this is planning input. + +> "Mise" is a spiritual successor to Restaurant Empire (2003/2004). We never brand as "Restaurant Empire." Comparables are for positioning, not imitation. + +--- + +## The table + +Prices are Steam **list** prices in USD; sale prices are ignored. "Positioning" is our read of where each sits. + +| # | Title | Year | Rough positioning | Price tier | What it proves about the audience | Learn / avoid | +|---|---|---|---|---|---|---| +| 1 | **Restaurant Empire I / II** | 2003 / 2004 | Direct lineage — business-of-a-restaurant depth, campaign + freeplay | Legacy (n/a) | A dedicated fanbase for *deep restaurant business* sim exists with **no modern successor**. **[ASSUMPTION — confirm]** | **Learn:** the menu/finance depth is the fantasy. **Avoid:** dated UX, wall-of-menus opacity. | +| 2 | **Two Point Hospital** | 2018 | Charming, legible management sim; systemic humor | Full-price ~$34.99 list, deep-discounts common | Charming legible management sims sell big: **[VERIFIED]** SteamSpy 1–2M owners, 93% positive. | **Learn:** legibility + charm scale. **Avoid:** assuming its art budget is reachable by two people. | +| 3 | **Two Point Campus** | 2022 | Sequel-genre management; broader/softer | Full-price tier | Proves the formula extends but **[ASSUMPTION — confirm]** sequels can feel same-y; novelty matters. | **Learn:** consistent management grammar. **Avoid:** iteration without a new hook. | +| 4 | **Dave the Diver** | 2023 | Hybrid: dive/action + **restaurant management** loop; narrative | $19.99 | Restaurant-adjacent management with an emergent, charming loop can go **viral: 5M+ copies by late 2024**. **[VERIFIED]** | **Learn:** the "run the restaurant tonight" session is magnetic. **Avoid:** its action half is not our genre. | +| 5 | **PlateUp!** | 2022 | Roguelite co-op cooking + restaurant *automation/management* | $19.99 | Roguelite-management with **shareable runs** reaches ~1M owners, 94% positive. **[VERIFIED]** | **Learn:** runs that produce stories drive discovery. **Avoid:** co-op/execution focus — not our single-player depth pitch. | +| 6 | **Chef: A Restaurant Tycoon Game** | EA (ongoing) | **Direct competitor** — build/run restaurants, recipe editor, career | $19.99 | Direct demand is real but **under-satisfied**: **[VERIFIED]** 72% "Mostly Positive", ~1.4k reviews. | **Learn:** recipe/menu creation is wanted. **Avoid:** the quality/legibility gaps that cap it at "Mostly Positive" — this is our opening. | +| 7 | **Big Ambitions** | EA (2023) | Deep first-person business-empire sim (restaurants among many) | ~$24.99 | Deep business-sim **EA holds 92% positive across 5k+ reviews**. **[VERIFIED]** EA is viable for depth-forward business sims. | **Learn:** EA + depth can earn trust. **Avoid:** breadth-first empire sprawl (we go depth-first single restaurant). | +| 8 | **Recipe for Disaster** | EA (2021) | **Closest niche twin** — design/run a restaurant, staff, menus, ingredients | $16.99 | The exact niche is real but easy to leave **"Mixed" (69%)**. **[VERIFIED]** | **Learn:** the niche exists. **Avoid:** the legibility/polish shortfalls that produced "Mixed" — our whole thesis is legibility. | +| 9 | **Cook, Serve, Delicious! (2/3)** | 2017–2020 | Fast execution cooking; menu breadth as challenge | ~$12.99–$19.99 | Menu variety and mastery sell; **[ASSUMPTION — confirm]** but execution-first ≠ management-first. | **Learn:** menu as identity. **Avoid:** twitch execution as the core — we are decisions, not dexterity. | +| 10 | **PlateUp!-adjacent roguelite-management wave** | 2022– | Roguelite structure applied to management loops | $15–$25 typical | A **2022+ current**: roguelite framing makes management replayable and clip-able. **[ASSUMPTION — confirm]** | **Learn:** run-based replay + seeds. **Avoid:** forcing permadeath onto a build-my-restaurant fantasy. | +| 11 | **Cozy-management wave** (e.g. café/diner cozy sims) | 2023– | Low-stress, aesthetic-forward management | $10–$20 typical | A **2023+ current**: a large audience wants *approachable* management with vibe. **[ASSUMPTION — confirm]** | **Learn:** approachability + audio/visual warmth widen the top of funnel. **Avoid:** sanding off the depth that is our reason to exist. | +| 12 | **Startup Company / business-sim tail** | 2020– | Systems-heavy niche business sims | $15–$25 | Proves a durable niche audience for **spreadsheet-comes-alive** sims. **[ASSUMPTION — confirm]** | **Learn:** systems depth retains a loyal core. **Avoid:** UI opacity that gates the audience. | + +--- + +## What the field tells us (synthesis) + +1. **Demand exists at every price rung** from $16.99 (Recipe for Disaster) to $19.99 (PlateUp!, Chef, Dave the Diver) to full-price ($24.99+ Two Point / Big Ambitions). Price is a positioning choice, not a demand question. +2. **The niche twin (Recipe for Disaster) is only "Mixed."** That is our clearest opening: same niche, better legibility and polish. +3. **The direct competitor (Chef) is only "Mostly Positive."** Under-satisfied demand. +4. **Story-producing runs drive discovery** (PlateUp!, Dave the Diver). Design for shareable moments. +5. **Two 2020s currents to respect but not chase:** roguelite-management (replay/clips) and cozy-management (approachability). We borrow their *accessibility and shareability*, not their shallowness. + +--- + +## Explicit non-comparables + +We are **not** competing with co-op party cooking (Overcooked), pure execution (Cook Serve Delicious as a twitch game), or action hybrids (Dave the Diver's dive half). Positioning those as peers would mis-tag us and mis-set expectations. + +## Deferred lineage (post-M3, NOT now) + +Multi-restaurant empire, franchising, corporate layer, living-city competition, food trucks, delivery, celebrity-chef, multiplayer, UGC — these are **v1.x candidates, not committed**, and are out of scope for the first commercial cut (through M3). Comparables for *those* systems are intentionally not researched here. + +--- + +**Sources:** [PlateUp! SteamSpy](https://steamspy.com/app/1599600) · [PlateUp! on Steam](https://store.steampowered.com/app/1599600/PlateUp/) · [Dave the Diver 4M — Game World Observer](https://gameworldobserver.com/2024/06/27/dave-the-diver-4-million-copies-sold-anniversary) · [Dave the Diver 5M — DLCompare](https://www.dlcompare.com/gaming-news/dave-the-diver-tops-5-million-units-in-sales) · [Two Point Hospital SteamSpy](https://www.steamspy.com/app/535930) · [Chef: A Restaurant Tycoon on Steam](https://store.steampowered.com/app/886900/Chef_A_Restaurant_Tycoon_Game/) · [Big Ambitions on Steam](https://store.steampowered.com/app/1331550/Big_Ambitions/) · [Recipe for Disaster on Steam](https://store.steampowered.com/app/1492360/Recipe_for_Disaster/) · [Cook, Serve, Delicious! on Steam](https://store.steampowered.com/app/247020/) diff --git a/docs/commercial/EARLY-ACCESS-DECISION.md b/docs/commercial/EARLY-ACCESS-DECISION.md new file mode 100644 index 0000000..3bd8166 --- /dev/null +++ b/docs/commercial/EARLY-ACCESS-DECISION.md @@ -0,0 +1,90 @@ +# Early Access vs Premium 1.0 — Decision Brief — "Mise" (working codename) + +**Purpose:** A structured comparison of Premium-1.0 vs Early-Access as the launch model for the first commercial cut, with a provisional recommendation and a de-locked decision trigger. + +**Status:** DRAFT. **This is an [OWNER DECISION]** (Howard + Aaron), kept **de-locked pending platform answers**. Only **M0** is authorized for implementation; nothing here authorizes building the launch build. + +> Labeling: **[VERIFIED]** · **[ASSUMPTION]** · **[OPEN QUESTION]** · **[OWNER DECISION]**. +> First commercial cut = **everything through Milestone M3** (one deeply-simulated restaurant with identity, persistent staff/finances, progression, critics, robust saves, enough content for repeat play). M4+ is deferred / not committed. + +--- + +## 1. The two models in one line + +- **Premium 1.0:** ship the through-M3 build *finished* at full price; one clean review moment. +- **Early Access:** ship a smaller-but-complete deterministic slice into EA and grow it in public toward the through-M3 target. + +--- + +## 2. Structured comparison + +| Axis | Premium 1.0 | Early Access | +|---|---|---| +| **Cash flow** | No revenue until launch; longest runway required. | **Early revenue** during development — real for this genre (Chef, Big Ambitions, Recipe for Disaster all EA). **[VERIFIED]** genre-default. | +| **Community / review flywheel** | One review moment; sentiment set at 1.0 and hard to move. | **Community shapes design**; reviews compound — *if* cadence holds. Risk: premature **"Mixed"** (Recipe for Disaster 69%). **[VERIFIED]** | +| **Scope-forgiveness** | Low — must be "done" and polished on day one. | **High** — EA norms tolerate a growing slice, provided each release is coherent. | +| **Fit with a 1–2 person cadence** | Fits a team that would rather ship *done* once than run a public live cadence. | Demands a **sustained public update rhythm** (dev posts every 2–4 weeks). **Cadence risk is the top human risk** for two people. **[ASSUMPTION]** | +| **First-review risk** | One shot; a weak launch build is punishing. | Spread over time; early adopters are more forgiving, but the EA score still anchors. | +| **Discoverability** | Single spike; must maximize wishlists pre-launch. | Two moments (EA launch + 1.0), each a visibility event. | +| **Refund exposure** | Standard. | Standard, but EA expectations can raise refund risk if the slice feels thin. **[ASSUMPTION]** | + +--- + +## 3. Architecture fit — why EA is technically natural here + +The engine is a **C#/.NET engine-agnostic deterministic simulation core**, built as **modular systems** with a pure `(state, actions) => state` shape. That has a direct commercial consequence: + +- Systems can ship as **coherent, independently-testable modules** — a menu module, a staffing module, a critics module — each with reproducible behavior thanks to determinism and seeded RNG. +- A **staged EA rollout** maps cleanly onto that modularity: each EA update is "we turned on the next verified module," not "we destabilized the whole game." +- Deterministic saves make EA less scary: player saves and bug repros are reproducible across updates. + +**[ASSUMPTION]** This makes EA *lower-risk* for us than for a team with an entangled codebase — the architecture already thinks in stages. + +--- + +## 4. Provisional recommendation + +**Provisional lean: enter via Early Access at $19.99, staged by module, ONLY if the pre-launch gates are cleared — otherwise ship Premium 1.0.** + +Rationale: +- The genre's successful path is EA. **[VERIFIED]** +- Our architecture suits staged rollout. **[ASSUMPTION]** +- Early cash flow de-risks the *cash* cost categories (art/audio/legal) that dominate our budget. + +**But** this lean **flips to Premium 1.0** if either is true: +1. We cannot commit to a sustained public update cadence (honest two-person capacity check), **or** +2. The through-M3 build is close enough to done that EA adds cadence burden without adding runway. + +**This is not a decision. It is a lean pending the triggers below.** + +--- + +## 5. Decision trigger & timing (de-locked) + +The model choice is made at the **EA-vs-premium decision gate** in `docs/product/GO-TO-MARKET.md` (step 7) — **after** the public demo and Next Fest have produced real wishlist and sentiment data, and **after** platform answers are in. + +**Inputs required before the gate can be decided (all currently [OPEN QUESTION]):** + +| Input | Why it gates the decision | +|---|---| +| Post-demo / Next Fest wishlist level vs the `[PROVISIONAL — research]` target | Tells us if a Premium spike is even viable. | +| Playtest sentiment: did M0/demo clear the **fun** bar (not just comprehension)? | A weak slice must not enter EA (Recipe-for-Disaster failure mode). | +| Honest two-person **cadence commitment** | The single biggest EA risk. | +| Real cost budget → runway | If runway is short, EA cash flow may be necessary. | +| Steam Deck / controller answer | Affects launch readiness and which model can ship when. | + +**Timing:** do **not** lock the model until these are answered. Premature locking is exactly the kind of silently-filled gap the project rules forbid. + +**[OWNER DECISION]** Howard + Aaron own this gate. Kept de-locked. + +--- + +## 6. Failure modes to watch either way + +- **EA cadence collapse** → "Mixed" score → inverted flywheel. (Watch: can we truly post every 2–4 weeks?) +- **Premium under-delivery** → one bad review moment with no recovery. +- **Discoverability failure** (shared by both) → not enough wishlists for either model to matter; see the named failure condition in GO-TO-MARKET. + +--- + +**Sources:** [Chef: A Restaurant Tycoon on Steam](https://store.steampowered.com/app/886900/Chef_A_Restaurant_Tycoon_Game/) · [Big Ambitions on Steam](https://store.steampowered.com/app/1331550/Big_Ambitions/) · [Recipe for Disaster on Steam](https://store.steampowered.com/app/1492360/Recipe_for_Disaster/) · [PlateUp! on Steam](https://store.steampowered.com/app/1599600/PlateUp/) diff --git a/docs/commercial/PRICE-AND-BREAK-EVEN-HYPOTHESIS.md b/docs/commercial/PRICE-AND-BREAK-EVEN-HYPOTHESIS.md new file mode 100644 index 0000000..dd1836f --- /dev/null +++ b/docs/commercial/PRICE-AND-BREAK-EVEN-HYPOTHESIS.md @@ -0,0 +1,131 @@ +# Price & Break-Even Hypothesis — "Mise" (working codename) + +**Purpose:** A provisional price band with reasoning against comparables, and a **transparent** break-even model — formula plus a worked example with clearly-labeled placeholder inputs. No invented sales numbers. + +**Status:** DRAFT / HYPOTHESIS. Price is **[OWNER DECISION]**, not locked. Only **M0** is authorized for implementation. + +> Labeling: **[VERIFIED]** web-sourced/in-repo · **[ASSUMPTION]** / **[ASSUMPTION — confirm]** working belief · **[OPEN QUESTION]** unresolved · **[OWNER DECISION]** owners decide. + +--- + +## 1. Provisional price band + +**Target band: $19.99–$24.99 ([ASSUMPTION]).** + +Reasoning against **[VERIFIED]** comparable list prices: + +| Comparable | List price | Signal for us | +|---|---|---| +| Recipe for Disaster (EA, "Mixed") | $16.99 | Floor. The niche twin sits here; if we launch light or into EA we anchor near this. | +| PlateUp! (~1M owners, 94%) | $19.99 | The proven sweet spot for a well-liked management title. | +| Chef: A Restaurant Tycoon (EA, 72%) | $19.99 | Direct competitor's price — matching it is defensible. | +| Dave the Diver (5M+) | $19.99 | Shows $19.99 is not a ceiling on ambition. | +| Big Ambitions (EA, 92%) | ~$24.99 | Deep business sim can hold $24.99 in EA. | +| Two Point titles | full-price tier | Only reachable with clear content volume + polish. | + +**Read:** $19.99 is the *center of gravity* for a liked restaurant-management sim. We list at **$19.99–$24.99** and let the M3 content volume and the EA-vs-premium decision pick the exact number. + +- **Lean $19.99** if entering **Early Access** or if launch content is modest — matches Chef/PlateUp!, lowers the "maybe→yes" barrier after a good demo. **[ASSUMPTION]** +- **Lean $24.99** only if the **premium-1.0 through-M3** build has clearly more depth than the field. **[ASSUMPTION]** + +**[OWNER DECISION]** Exact price is not set here. + +--- + +## 2. Break-even model (transparent formula) + +**Net revenue per unit** (list price adjusted for the real ways money leaks): + +``` +net_per_unit = price + × (1 − store_cut) // Steam base 30% → 0.30 [VERIFIED base rate] + × (1 − refund_rate) // fraction of sales refunded + × (1 − discount_avg) // blended lifetime discount vs list +``` + +**Break-even units:** + +``` +break_even_units = total_cost / net_per_unit +``` + +Where `total_cost` = the sum of **cash** cost categories (art, audio, legal, QA, marketing, contractors, platform) — engineering is largely covered by owners + AI agents, so it is a *time* cost, not a cash line. See `docs/product/COMMERCIAL-HYPOTHESIS.md` §11. + +--- + +## 3. Worked example — ALL INPUTS ARE PLACEHOLDERS + +> These are **not** real figures. They exist to show the arithmetic. Replace every placeholder with a real quote before drawing any conclusion. + +| Input | Placeholder | Label | +|---|---|---| +| `price` | $20.00 | [ASSUMPTION — target band midpoint] | +| `store_cut` | 0.30 | [VERIFIED] Steam base rate | +| `refund_rate` | 0.08 | [ASSUMPTION — confirm] rule-of-thumb | +| `discount_avg` | 0.20 | [ASSUMPTION — confirm] blended lifetime | +| `total_cost` | $40,000 | **[OPEN QUESTION]** placeholder — no line is quoted yet | + +**Net per unit:** + +``` +net_per_unit = 20.00 × 0.70 × 0.92 × 0.80 + = 20.00 × 0.5152 + = $10.30 (placeholder-derived) +``` + +**Break-even units:** + +``` +break_even_units = 40,000 / 10.30 ≈ 3,884 units (ILLUSTRATIVE ONLY) +``` + +**Reading it honestly:** because engineering is owner+agent labor, `total_cost` is dominated by cash categories we have **not quoted**. A different placeholder `total_cost` moves break-even linearly: + +| Placeholder `total_cost` | Break-even units @ $10.30 net | +|---|---| +| $10,000 | ~971 | +| $25,000 | ~2,427 | +| $40,000 | ~3,884 | +| $75,000 | ~7,282 | + +**[OPEN QUESTION]** Real `total_cost` is unknown until the §11 categories are quoted. Break-even is a **framework**, not a figure, until then. + +--- + +## 4. Net-per-unit sensitivity to price + +Holding `store_cut=0.30`, `refund_rate=0.08`, `discount_avg=0.20` (all placeholders): + +| List price | net_per_unit (placeholder) | +|---|---| +| $16.99 | ~$8.75 | +| $19.99 | ~$10.30 | +| $24.99 | ~$12.87 | + +Higher list price raises net-per-unit and lowers break-even units **if** it does not depress conversion. It usually does depress conversion somewhat — which is the next section. + +--- + +## 5. Sensitivity: price × wishlist-conversion × review-score + +Break-even units is only half the picture; whether we *reach* it depends on the funnel. Qualitatively (we do **not** invent the numbers): + +- **Price ↑** → net-per-unit ↑ (fewer units to break even) but wishlist→sale conversion typically ↓, and refund risk may ↑ if perceived value lags. **[ASSUMPTION]** +- **Wishlist-conversion ↑** (driven by a good demo + Next Fest + a wishlist-CTA at demo end) → more units per wishlist. **[VERIFIED, directional]** demo-end CTA and Next Fest lift conversion. +- **Review-score ↑** (the "menu is the strategy" legibility payoff) → higher long-tail conversion, lower refund rate, better Steam visibility. The niche twin's "Mixed" (69%) and the competitor's 72% show how much headroom a *well-reviewed* entry has. **[VERIFIED]** + +**Interaction that matters most for a two-person team:** review-score is the multiplier that touches *every* other term (conversion up, refunds down, visibility up). **Getting to "Very Positive" is worth more than a few dollars of list price.** This is why the M0 bar must clear **fun**, not just comprehension. + +**[OPEN QUESTION]** Our actual wishlist→sale conversion and review distribution — measured via the GO-TO-MARKET gates, never assumed here. + +--- + +## 6. What would change these numbers + +- A real cost budget (§11 of the hypothesis) replaces the `total_cost` placeholder. +- The EA-vs-premium decision changes both `price` and the discount/refund profile. +- Steam revenue-share tiers (rate improves above revenue thresholds) would raise net-per-unit at scale — **[VERIFIED]** the tiered structure exists; we model the base 30% conservatively. + +--- + +**Sources:** [PlateUp! on Steam](https://store.steampowered.com/app/1599600/PlateUp/) · [Chef: A Restaurant Tycoon on Steam](https://store.steampowered.com/app/886900/Chef_A_Restaurant_Tycoon_Game/) · [Big Ambitions on Steam](https://store.steampowered.com/app/1331550/Big_Ambitions/) · [Recipe for Disaster on Steam](https://store.steampowered.com/app/1492360/Recipe_for_Disaster/) · [Wishlist-to-buyer conversion — alinea analytics](https://alineaanalytics.substack.com/p/wishlist-to-buyer-conversions-for) · [Next Fest data — Second Stage](https://secondstage.io/2026/04/steam-next-fest-the-data-behind-what-actually-drives-wishlists) diff --git a/docs/design/DEFERRED-FEATURES.md b/docs/design/DEFERRED-FEATURES.md new file mode 100644 index 0000000..b564052 --- /dev/null +++ b/docs/design/DEFERRED-FEATURES.md @@ -0,0 +1,89 @@ +# DEFERRED-FEATURES + +**Purpose:** The written backlog of everything we have **deliberately chosen not to build** in M0, and not to build for the first commercial cut (through M3). Each entry records the decision so it can be found later. + +**Status:** Planning artifact. **Only M0 is authorized for implementation.** Nothing in this document is a build order. This is the opposite of a build order — it is a list of things *not* to build now. + +--- + +## Why this document exists + +> **A deferred idea written down is a decision anyone can find. A silently-built one is a gap nobody can find.** + +The failure mode for a two-person team directing AI coding agents is *quiet scope creep*: an agent, trying to be helpful, scaffolds inventory, or stubs a supplier market, or leaves a TODO for franchising — and now the codebase carries weight nobody chose to carry. Six weeks later no one can find where the scope grew or why the build slipped. + +This document is the antidote. If you find yourself wanting a feature that is listed here, that is the **signal to stop** — the decision has already been made, and the place to reopen it is a milestone review, not a commit. If you want a feature that is *not* listed here, add it here first (feature, why deferred, earliest reconsideration, architectural seam), and only then discuss building it. + +**The architectural rule:** deferring a feature does **not** license us to actively foreclose it. Where a deferred feature has a natural seam in the core, we note the seam and require only that it **not be foreclosed** — no active work, no stubs, no abstractions built "for later." A seam left open is a door; a stub is furniture in the doorway. + +**Labeling key:** **[VERIFIED]** cited evidence · **[ASSUMPTION]** working belief, confirm · **[OPEN QUESTION]** unresolved · **[OWNER DECISION]** reserved for Howard and Aaron. + +--- + +## How to read the tables + +- **Earliest reconsideration** is the *soonest* milestone the feature could be *discussed*, not a commitment to build it then. Many entries are "post-M3 / v1.x candidate," meaning after the first commercial cut ships. +- **Architectural seam** names what the core must merely **not foreclose**. "None required" means the feature is purely additive and can be bolted on with no early accommodation. Building the seam early is itself scope creep unless it costs nothing. + +--- + +## Part A — M0 non-goals + +M0 is a **deterministic, headless service lab**. It has no presentation layer and no world systems. Everything below is out of M0 by definition. Most are also out of the first commercial cut; the "earliest reconsideration" column says when each could return. + +| Feature | Why deferred | Earliest reconsideration | Architectural seam (must NOT be foreclosed) | +| --- | --- | --- | --- | +| **Graphics / rendering** | M0 proves the sim spine headlessly; pixels can't validate the menu-as-strategy chain and would burn most of the effort. | M1 (first playable presentation) | Core is engine-agnostic and headless; sim state is fully observable via instrumentation so any renderer can read it. Keep core free of any rendering/DOM/engine reference. | +| **Pathfinding / floor navigation** | Spatial movement is a presentation and later-sim concern; M0 models service as flow/capacity, not walked paths. | M1–M2 | Represent layout as abstract capacity/adjacency, not hardcoded geometry, so a spatial layer can later resolve to real paths. Do not build a nav mesh now. | +| **Inventory / suppliers / spoilage** | A full supply system is a second game; M0 models ingredient cost and waste as menu-derived aggregates, not tracked stock. | M2 (economy depth) | Ingredient cost and waste already flow *from the menu* (see design spine). Keep those as computed aggregates with a clear boundary so a real stock model can later sit behind the same interface. | +| **Recipe / dish creation (custom recipes)** | Player-authored recipes are a huge content and balance surface; M0 uses a curated dish set to test menu *composition*, not dish invention. | M3 or v1.x | Dishes are data records with declared cost/station/complexity fields; a recipe editor would produce the same record type. Do not hardcode the dish list into logic. | +| **Reviews as a world system** | Critics/press modeled as living entities is an M3 feature; M0 needs outcome *legibility*, not a review ecosystem. | M3 (critics) | Service outcomes emit legible quality/satisfaction signals; a review system later consumes those signals. Keep outcome data structured, not just printed. | +| **Hiring / firing labor market** | A staffing *market* (candidates, offers, poaching) is Operator/Restaurateur-tier depth; M0 tests staffing as a capacity/skill decision with a fixed roster. | M2–M3 | Staff are records with skill/role/cost; a market later supplies those records. Do not couple sim logic to how staff were acquired. | +| **Managers / delegation** | Delegation is the Operator→Restaurateur hinge and only matters with more than one venue's worth of work; premature now. | M4+ (post-cut) | None required; delegation is an additive control layer over an already-observable sim. | +| **Competitors / rival restaurants** | Rivals modeled as agents are a living-city feature; they add balance and AI cost with no payoff to the M0 question. | M4+ (post-cut) | Demand is modeled as a market the restaurant draws from; a competitor could later subtract from the same market. Do not assume a single-restaurant-only demand model in a way that blocks this. | +| **City / district simulation** | Location, neighborhoods, foot traffic as a simulated world is post-cut scope. | M4+ (post-cut) | Location can be a parameter set on the restaurant (demand profile, rent); keep those as inputs, not constants baked into sim math. | +| **Narrative / campaign** | A structured campaign is M3+/post-cut content; M0 is a sandbox lab, not a story. | M3 or v1.x | Sim exposes events/milestones as data; a campaign layer later scripts against them. Do not embed story branching in the core. | +| **Tutorials / onboarding** | Onboarding teaches an interface that does not exist yet; wasted until there is UI to teach. | M1–M2 (with UI) | None required; onboarding sits entirely in the presentation layer. | +| **Localization / i18n** | Premature before content and copy stabilize; no strings worth translating in a headless lab. | Pre-release hardening (M3) | Keep user-facing strings out of the sim core (core deals in data/enums, not display text) so a later i18n layer has one place to work. | +| **Multiplayer / co-op** | Fundamentally reshapes state ownership and determinism; a different product. Single-player is locked. | v2+ only, if ever | **[OWNER DECISION]** Determinism and single-owner state are being preserved for *reproducibility*, not for netcode. Do not add multiplayer scaffolding. A deterministic core does not owe multiplayer anything. | +| **Mods / UGC platform** | A modding surface is a support and security commitment a two-person team cannot carry at launch. | v1.x+ | Data-driven content (dishes, staff as records) keeps a *future* mod path open at zero cost today. Do not build a mod API, loader, or sandbox now. | +| **Steam integration** | Storefront/SDK work belongs with the commercial cut, not the sim lab. | M3 (commercial cut) | Core has no platform dependencies; Steam SDK lives in the shell/presentation layer only. | +| **Achievements** | Depend on Steam integration and stable milestones; nothing to award in M0. | M3 (with Steam) | Sim already emits milestone/event data an achievement layer can read. No early work. | +| **Cloud saves** | A platform feature layered on the save format; premature before saves are robust. | M3 (robust saves) | Save format is versioned and self-contained; cloud sync is a transport concern layered on top. Keep saves serializable and versioned. | +| **Audio (incl. audio-as-legibility)** | No presentation layer to carry it in M0. **But flagged, not forgotten:** a prior review noted audio can be a *legibility* channel (a service going wrong should be *hearable*), so audio is a design concern for M1, not just polish. | M1 (presentation) | None required in core; the review-flagged "audio as legibility" idea is recorded here so it is not lost. **[OWNER DECISION]** how far to invest. | +| **Procedural / AI-generated content** | Generated dishes/venues/text add unpredictability, tone risk, and support cost with no help to the M0 question; determinism is a core value. | v1.x+, if ever | Data-driven content authoring keeps content curated and reproducible. **[OWNER DECISION]** — do not introduce any LLM/generative dependency into the core without an explicit owner decision. | + +--- + +## Part B — Post-M3 systems (the empire layer) + +These are the **M4+ / post-release / v1.x candidate** systems named in the LOCKED facts. They are the *promise* of the core fantasy's "…and then turn that hard-won operating model into a culinary empire," and the top rungs of the career arc (Restaurateur → Group Leader → Legacy Architect). **None is committed.** They are here so the first commercial cut can be built *without foreclosing* them — and without building any of them. + +| Feature | Why deferred | Earliest reconsideration | Architectural seam (must NOT be foreclosed) | +| --- | --- | --- | --- | +| **Multi-restaurant (portfolio)** | The whole design bet is *depth before breadth*: one deeply-simulated restaurant must be great before a second exists. Shipping the empire first skips the fantasy. | M4+ (post-cut) | A restaurant is a self-contained sim entity with its own state; the core should treat "the restaurant" as an instance, not a global singleton, so a portfolio can later hold several. Do NOT build portfolio management now — just avoid singletons that assume exactly one. | +| **Corporate layer** | Group-level finance, HR, and brand only have meaning across multiple venues; nothing to manage yet. | M4+ (post-cut) | Per-restaurant finances roll up cleanly; keep financial records attributable to a restaurant instance so a corporate aggregate is a sum, not a rewrite. | +| **Franchising** | Licensing your operating model to others is Legacy-Architect scope; requires the operating model to first be a *transferable object*, which the cut does not yet produce. | Post-release / v1.x | The "operating model" (menu + staffing template + layout) is data; if it stays data, it can later be packaged as a franchise template. No early franchise system. | +| **Acquisitions** | Buying existing venues presupposes competitors and a market of restaurants — both deferred. | Post-release / v1.x | Depends on the multi-restaurant and competitor seams above; nothing additional needed now. | +| **International expansion** | New regions imply new markets, cuisines, regulations, currencies, and localization — a large content and systems surface for post-release. | Post-release / v1.x | Location/market parameters (demand profile, cost basis) are already inputs on a restaurant; a region is just a parameter set. Do not hardcode a single locale's economics into sim math. | +| **Delivery** | Delivery reshapes demand, service, and kitchen load; a distinct mode better added once the dine-in machine is proven. | Post-release / v1.x | Demand and service are modeled as channels the kitchen serves; keep "the guest experience" abstract enough that a delivery channel could later draw on the same kitchen. No delivery code now. | +| **Food trucks** | A different venue archetype with different constraints (mobility, tiny footprint); additive content, not foundational. | Post-release / v1.x | A food truck is another restaurant-instance archetype with different capacity/layout parameters. The restaurant-as-instance seam covers it. No early work. | +| **Celebrity chef** | A late-fantasy fame/persona system (your name as brand, reputation across venues) belonging to Legacy-Architect scope. | Post-release / v1.x | Reputation/identity signals already emitted per restaurant; a personal-brand layer later aggregates them. Keep reputation data structured. | + +--- + +## The seam discipline, restated + +For every row above, "architectural seam (must NOT be foreclosed)" means exactly this and nothing more: + +- **Do** keep the core data-driven, instance-based, headless, and free of platform/engine/display coupling. That costs us nothing today and keeps every door open. +- **Do NOT** build the deferred feature, stub it, add a flag for it, abstract "for" it, or leave a TODO for it. Those are furniture in the doorway. They are the exact scope creep this document exists to stop. + +If honoring a seam would require real work *now*, it is no longer a free seam — stop and raise it as an **[OWNER DECISION]**, because you have found a place where a deferral and the architecture genuinely trade off, and that tradeoff is the owners' call, not an agent's. + +--- + +**Cross-references:** +- [PRODUCT-VISION.md](../product/PRODUCT-VISION.md) — the core fantasy, spine, career arc, and "what this is NOT" +- [MASTER-PLAN.md](../MASTER-PLAN.md) — milestone definitions M0–M3+ +- [FIRST-COMMERCIAL-CUT.md](../commercial/FIRST-COMMERCIAL-CUT.md) — the M3 release line these deferrals sit outside of diff --git a/docs/design/DESIGN-PRINCIPLES.md b/docs/design/DESIGN-PRINCIPLES.md new file mode 100644 index 0000000..6587c17 --- /dev/null +++ b/docs/design/DESIGN-PRINCIPLES.md @@ -0,0 +1,69 @@ +# Design Principles + +Purpose: distill the master plan's design philosophy (its pillars, anti-pillars, and six-test standard for every mechanic) into a working principles document, and show concretely how the built M0 "Headless Service Lab" embodies each — with references to real code. + +**Status:** Working principles for the project, derived from `docs/archive/2026-07-28/restaurant-empire-successor-master-plan-v1.md` §2. The "how M0 embodies this" notes describe code that exists and is tested; forward pillars are flagged where M0 deliberately does not implement them (they are on the non-goals list). + +--- + +## The pillars + +The master plan §2 states eight design pillars. M0's authorized scope covers the first two fully, touches the third partially, and defers the rest. They are all listed so the principle is complete; each says honestly what M0 does and does not do. + +### Pillar 1 — The menu is the strategy +A menu determines what customers consider, which segments the restaurant attracts, kitchen-station demand, prep/holding times, average check and margin, and the room's ability to absorb peaks. A recipe earns its place only if it creates decisions in several of these areas. + +**How M0 embodies it.** The menu is literally the primary command. `ServicePlan.Menu` (recipe + price) drives everything downstream: `DemandModel.ConversionBp` turns menu fit and pricing into how many attempted visits convert; each dish routes to a `StationId`, so menu composition *is* station load; `Tuning.ComplexityBp` taxes broad, prep-heavy menus with real ticket-work and mistake overhead; and dish choice per cover (`ServiceSimulator.OrderDishes` / `PickBest`) spreads diners across dishes by appeal × price-fit. The 12 fixtures in `M0Content` are deliberate archetypes (value burger vs. premium ribeye vs. craft risotto) with no single dominant dish — the recipe invariant in `M0-SYSTEM-CONTRACTS.md`. + +### Pillar 2 — Service is a readable flow problem +The restaurant is a flow network (demand → arrival → seating → ordering → ticket → preparation → coordination → delivery → eating → payment). The game must show *where flow failed*; "service was bad" is not acceptable feedback. + +**How M0 embodies it.** The simulator advances that exact flow as a per-minute party state machine (`Waiting → Browsing → Cooking → Eating → Paid`, with `WalkedSeat`, `WalkedFood`, `NoOrder` exits — see `ARCHITECTURE-OVERVIEW.md` §4). The `ServiceResult` exposes the funnel (`DemandGenerated`, `PartiesServed`, `LostToCapacity`, `LostToWait`, `LostToMenuFit`) and per-station utilization/peak-queue. And `DiagnoseBottleneck` names the single binding constraint in words — seating, service, a specific station, weak demand, or menu complexity — which the autopsy prints as `BottleneckCause`. The player is told *where* flow failed, not just that it did. + +### Pillar 3 — People are both capacity and characters +Employees are not interchangeable multipliers; they have skills, specialties, reliability, wages, and limited availability. Character depth exists only to make staffing/development/retention meaningful. + +**How M0 embodies it (partially, by design).** M0 models the *capacity* half: `EmployeeDef` has wage, speed, quality skill, reliability, per-station fit, and FOH skill, and assignment matters (`StationFit` multiplies effective skill and speed; low-skill cooks on hard dishes fail more via the `Incident` roll). M0 deliberately does **not** model the *character* half — goals, stamina, learning, relationships, hiring/firing/progression are all on the `M0-PROTOTYPE-CONTRACT.md` §4 non-goals list and are absent, not stubbed. + +### Pillars 4–8 (deferred in M0) +- **Pillar 4 — Growth means leverage, not more clicking.** Multiple restaurants, managers, delegation: non-goals in M0. +- **Pillar 5 — Thin margins create pressure; the game creates recovery.** M0 embodies the *pressure and recovery loop within a single service* (see Risk/Recovery below) but not the long-horizon capital economy. +- **Pillar 6 — Awareness and satisfaction are different truths.** M0 keeps satisfaction as a first-class, multi-dimensional truth (food/wait/service/value, never one global score) but does not model awareness/marketing/reputation — those are non-goals. +- **Pillar 7 — Upgrades unlock capabilities.** No upgrades in M0. +- **Pillar 8 — The simulation creates stories.** M0's causal autopsy is the seed of this (systemic outcomes explained by cause), but persistent world stories/events are out of scope. + +The forward pillars are recorded to keep the principle honest; **do not build them into M0** (see `CLAUDE.md` and the prototype contract). + +--- + +## The anti-pillars + +The master plan rejects, among others: hidden production times; unexplained global ratings; false choices where one option always dominates; random events with no preparation or recovery; simulation detail the player cannot perceive; AI agents with magical knowledge; and **UI screens that independently recalculate engine truth.** + +**How M0 respects them.** +- *No hidden production times / no unexplained ratings:* ticket time, station utilization, per-dish quality, and the bottleneck cause are all reported from authoritative state; there is no opaque "quality score." +- *No false choices:* the balance harness and `BalancePropertyTests` prove no single strategy wins every market and that deliberately-bad strategies never win — dominance is a tested failure condition, not an aspiration. +- *No unrecoverable randomness:* variance comes from seeded streams within a plan the player controls; a bad service is answered by revising the plan and running again, not by an unpreventable event. +- *No imperceptible detail:* the fixtures are hand-authored round numbers; every modelled quantity surfaces in the autopsy. +- *No recalculating views:* `TextReport` reads `ServiceResult`/`ForecastSnapshot` and computes no simulation truth — the anti-pillar this project cares most about, enforced by `ADR-001` and `ADR-004`. + +--- + +## The six-test standard + +The master plan §2 requires every mechanic to pass six tests. Below, each test is stated, then shown against the M0 build with a concrete, checkable referent. + +| # | Test | Question | How M0 satisfies it (concretely) | +|---|---|---|---| +| 1 | **Fantasy** | Does it reinforce the player's role? | The player plays the operator: choose the menu and prices, assign the crew to stations and front-of-house, set seats and door acceptance, forecast, commit, then read the autopsy and revise. The CLI loop (`RestaurantSim.Cli`) *is* the restaurateur's decision cycle, with no non-restaurant busywork. | +| 2 | **Choice** | Are ≥2 options rational in different contexts? | Proven, not asserted. `BalancePropertyTests.No_single_strategy_wins_every_market` and the harness's dominance check show different strategies win different markets; per-cover **weighted dish choice** (`PickBest`) means no single dish dominates, so menus have genuinely different, context-dependent payoffs. `Premium_is_not_always_best_it_loses_the_value_lunch` locks this in. | +| 3 | **Truth** | Does one authoritative system calculate the result? | Yes — `ServiceSimulator` produces one `ServiceResult`; every reported number is a field of it, not a view re-computation (`ADR-001`, `M0-SYSTEM-CONTRACTS.md` `ServiceResult` invariant). Determinism/reconciliation tests confirm the one truth is stable and closes to the cent. | +| 4 | **Clarity** | Can a fresh player explain the consequence? | The causal autopsy names the bottleneck in a sentence (`DiagnoseBottleneck` → `BottleneckCause`), reports the funnel and the forecast-vs-actual gap, and flags the most-profitable and least-useful dish. The intent is that a player can say *why* the service went the way it did — the explicit target reaction in `M0-PROTOTYPE-CONTRACT.md` §2. | +| 5 | **Risk** | Can poor judgment produce a meaningful cost? | Yes. Overpricing, understaffing, an over-broad menu, or a one-station menu produce walkouts, comped failures (a botched dish costs ingredients and earns nothing — `ServiceResult` / `EconomyReconciliationTests`), and real losses. `Deliberately_bad_strategies_lose_money_in_the_high_volume_lunch` asserts the downside is real. | +| 6 | **Recovery** | Can the player respond without restarting? | Yes — the loop *is* revise-and-run-again. After the autopsy the player edits the same draft plan (menu, prices, assignments, seats, acceptance) and runs another service against the same market; nothing forces a restart. This is the "voluntarily wants to run another service" behaviour M0 is trying to produce. | + +--- + +## Using this document + +These principles are the "why" behind the architecture decisions in `docs/architecture/` and the object contracts in `M0-SYSTEM-CONTRACTS.md`. When evaluating any proposed M0 change, run it through the six-test standard and check it against the anti-pillars — and remember the hard scope boundary: a feature is not justified merely because the architecture could support it (`M0-PROTOTYPE-CONTRACT.md` §4). diff --git a/docs/design/M0-BALANCE-HYPOTHESES.md b/docs/design/M0-BALANCE-HYPOTHESES.md new file mode 100644 index 0000000..08c5e27 --- /dev/null +++ b/docs/design/M0-BALANCE-HYPOTHESES.md @@ -0,0 +1,54 @@ +# M0 Balance Hypotheses (pre-registered) and Observed Results + +**Status:** Hypotheses locked before the distribution runs; results below are from the committed +`reports/balance/distribution.md` (200 seeds/cell). This is the design-truth check for the M0 question. + +## The bar M0 must clear +- More than one strategy is rational. +- **Context** changes which strategy is best (no single dominant strategy). +- Deliberately poor strategies fail understandably. +- Premium is not always best; max capacity is not always best; the biggest menu is not always best; + the highest prices are not automatically best; the cheapest labor is not automatically best. + +## Pre-registered hypotheses +| # | Hypothesis | +|---|---| +| H1 | The **value lunch rush** rewards a lean, fast, cheap operation (Focused Value), and punishes premium pricing (the value crowd balks). | +| H2 | The **enthusiast evening** rewards skilled premium execution (Premium Craft) and its high checks; a bare value menu leaves money on the table. | +| H3 | The **social dinner** is contested — a fast value operation, a broad menu, and a balanced mid operation are all in play; no runaway winner. | +| H4 | **Overcapacity** (accept more than the kitchen can serve) fails in high-volume markets via walkouts. | +| H5 | **Understaffed** and **Station Bottleneck** fail via kitchen queues and walkouts, legibly attributed by the autopsy. | +| H6 | **Broad Menu** pays a real complexity tax (slower tickets, more comped failures) and is never the best plan. | +| H7 | **Overpriced Weak Execution** craters on value and satisfaction (high price, low skill → comped failures). | +| H8 | No single strategy is the best across all three markets. | + +## Observed results (200 seeds/cell) +Winners by market: **lunch → Focused Value**, **social → Focused Value (median) / Premium Craft (most seeds won)**, **enthusiast → Premium Craft**. Distinct winning strategies across markets: **2 of 3** → *no single dominant strategy* (harness ✅). + +Median service contribution (winner **bold**): + +| Strategy | lunch | social | enthusiast | +|---|--:|--:|--:| +| Focused Value | **+$304** | **+$520** | +$247 | +| Premium Craft | −$52 | +$362 | **+$1032** | +| Broad Menu | −$394 | −$66 | +$557 | +| Balanced Competent | −$408 | +$42 | +$485 | +| Overcapacity / Understaffed / Overpriced / Station Bottleneck / Intentionally Bad | all negative | all negative | all negative | + +Hypothesis verdicts: **H1 ✅** (Focused Value wins lunch; Premium loses it, 21 covers). **H2 ✅** (Premium Craft +$1032 enthusiast vs Focused +$247). **H3 ✅** (social is contested: Focused, Premium, and Balanced all profitable/near-even; Premium wins the most individual seeds while Focused has the best median). **H4–H7 ✅** (all deliberately-bad strategies post negative medians in every market, and the autopsy names the cause — e.g. "Kitchen bottleneck at the Grill station: 91% utilized, peak queue 46"). **H6 ✅** (Broad Menu never wins; it loses the lunch rush outright). **H8 ✅**. + +These properties are also enforced as tests in `tests/RestaurantSim.Scenario.Tests` (`BalancePropertyTests`). + +## Honest finding for the owners (a real M0 design signal) +Within a **single service with no repeat visits** (M0's scope), the dominant profit lever is **throughput** +(covers served), and **quality/satisfaction have limited economic teeth** — they only bite through comped +failures. That is why a fast value menu is broadly strong and quality-led menus win only where checks are +high (enthusiast) or volume is capped. This is expected and correct for M0: satisfaction, reputation, and +**repeat visits** are what should give quality durable economic weight, and those are **M1/M2 systems**, not +M0. The M0 lab proves the decision loop is legible and non-degenerate; it deliberately does not yet reward +identity/quality over time. Flag this for the M1 design: repeat-visit and reputation feedback is the +mechanism that makes "the menu is the strategy" pay off beyond a single night. + +## Stop / rewrite triggers (from the contract) — none tripped +No strategy dominates all markets; poor strategies fail; the economy produces both real losses and real +profits; menu complexity creates real pressure; premium/price/capacity/menu-size are each not always best. diff --git a/docs/design/M0-PROTOTYPE-CONTRACT.md b/docs/design/M0-PROTOTYPE-CONTRACT.md new file mode 100644 index 0000000..185d89f --- /dev/null +++ b/docs/design/M0-PROTOTYPE-CONTRACT.md @@ -0,0 +1,89 @@ +# M0 Prototype Contract — Headless Service Lab + +**Status:** Locked. This is the authorization boundary for M0. Only M0 is authorized. +**Owner decision at the end:** whether the loop is fun enough (owner-run playtests) to continue. + +## 1. Product question +> Can menu, pricing, staffing, and capacity decisions create multiple understandable and viable +> restaurant strategies, with visible consequences that make players want to revise their plan and +> run another service? + +## 2. Target player reaction (fun is required, not just comprehension) +A successful M0 player: +- understands the menu changes how the kitchen operates, +- forms a plan before simulating, +- predicts at least one likely consequence, +- reacts to the service results, +- identifies at least one cause of success or failure, +- changes the next plan for a reason, +- **voluntarily wants to run another service**, and +- describes at least one decision as satisfying, tense, clever, or fun. + +Competence alone is not a pass. See `../playtests/M0-TEST-SCRIPT.md`. + +## 3. Authorized scope +One restaurant; one service period; 3 customer segments; 12 recipes; 3 courses; 4 kitchen +stations; 8 employees; fixed starting cash; menu selection; dish pricing; employee assignment; +station assignment; a capacity posture; a simplified but internally consistent service +simulation; revenue and direct costs; labor cost; customer satisfaction; ticket time; lost +demand; service failures; dish contribution; station utilization; a post-service causal report; +revise-and-run-again; deterministic seeds; an automated strategy harness; state checksums; and a +CLI (or similarly minimal) interface. + +## 4. Explicit non-goals (hard do-not-build) +2D/3D graphics; Godot integration; furniture/placement; character models; animation; +pathfinding; spatial walking; inventory purchasing; suppliers; spoilage; recipe creation; +recipe discovery; marketing campaigns; reviews/critics as persistent world systems; employee +relationships; hiring market; firing; career progression; multiple restaurants; managers; +delegation; competitors; city simulation; campaign story; tutorials; localization; multiplayer; +mod support; Steam integration; achievements; cloud saves; a full production save system; +asset-pack integration; final UI; final audio; procedural recipe generation; AI-generated +content pipelines. + +**Do not add a feature merely because the architecture could support it.** + +## 5. Timebox +25–40 focused builder hours (from the master plan's M0 expectation). If the honest estimate +exceeds it: reduce M0 content/complexity while preserving the *complete loop*, do not silently +extend, document the discrepancy, and stop for an owner decision if the question cannot be +answered within a reasonable extension. See `../product/EFFORT-AND-SCOPE.md` for the actual +build accounting. + +## 6. Required systems +Authoritative state; command processing; demand generation; customer choice; order generation; +station queues; staff capacity; dish outcome/quality; satisfaction; finance; causal report; +seeded randomness; strategy harness; deterministic checksum. + +## 7. Placeholder policy +CLI/terminal interface; hand-authored round-number fixtures; no production assets; no +animation; no simulated walking; no content polish. Everything on the non-goals list is absent, +not stubbed. + +## 8. Evidence required +Passing automated invariant tests; a determinism checksum reproduced across repeated runs; a +strategy-distribution report across seeds and market scenarios; an example seed + checksum; an +example forecast-vs-actual causal report; and a playtest plan/script ready for owner-run human +sessions. (Human playtest *results* are the owners' to gather; the Builder cannot fabricate +them.) + +## 9. Pass criteria (provisional thresholds) +See `M0-SYSTEM-CONTRACTS.md` §Gate and the master-plan gate. Technical criteria the Builder can +verify: no dominant strategy across reasonable fixtures; ≥2 strategies viable in different +contexts; intentionally poor strategies fail understandably; reports expose the main cause of +failure; identical checksums on repeated runs; money/state invariants pass; scope stayed clean. +Human criteria the owners must verify: ≥5 uncoached players complete the loop; ≥4 explain the +menu/staffing/station/result relationship; ≥3 voluntarily run again; ≥3 use positive-affect +language; owner judges the loop points toward a commercially interesting game. + +## 10. Stop / fail / rewrite conditions +See `../design/M0-BALANCE-HYPOTHESES.md` and the master plan §15. Failure is an acceptable +result and must not be disguised by adding features. + +## 11. Repository boundary +M0 lives in `src/RestaurantSim.Core` (pure), `src/RestaurantSim.Cli`, `src/RestaurantSim.Harness`, +with tests and fixtures. No presentation engine, no asset packs, no future systems. The core has +zero dependency on any renderer. + +## 12. Owner decision required at the gate +Continue, Defer, Rewrite, or Abandon — decided by Howard and Aaron after human playtests, not by +the Builder. diff --git a/docs/design/M0-SYSTEM-CONTRACTS.md b/docs/design/M0-SYSTEM-CONTRACTS.md new file mode 100644 index 0000000..fae3366 --- /dev/null +++ b/docs/design/M0-SYSTEM-CONTRACTS.md @@ -0,0 +1,104 @@ +# M0 System Contracts + +**Status:** Locked for M0. The code in `RestaurantSim.Core` implements these object contracts. +Each object states what it Knows, what it Can do, what it Cannot do, and its Invariant. + +These are the master plan's §11 contracts narrowed to the M0 scope. Anything not listed here is +out of M0 scope. + +--- + +## World / fixtures (immutable definitions) + +### Segment +- **Knows:** budget (cents), patience-for-seating (min), patience-for-food (min), quality + expectation (0..1000), price sensitivity (bp), atmosphere weight (0..1000), course tendency, + service-failure sensitivity (0..1000), novelty preference (0..1000). +- **Cannot:** change at runtime. Segments are fixtures. + +### Recipe (12 of them) +- **Knows:** course (Starter/Main/Dessert), primary station, optional secondary station, + ingredient cost (cents), quality ceiling (0..1000), base difficulty (0..1000), active + station-minutes per dish, prep-complexity weight, holding tolerance (min), per-segment appeal + (0..1000), suggested price (cents). +- **Cannot:** store runtime state. A recipe is a definition; execution modifies a dish ticket. +- **Invariant:** no single recipe strictly dominates all others across cost/quality/appeal/load. + +### Station (4: Cold/Prep, Sauté/Range, Grill/Oven, Pastry/Plating) +- **Knows:** which recipes it can produce, and its per-minute throughput derived from assigned + employees and their station fit. +- **Cannot:** produce more simultaneous dishes than its capacity without queueing or failing. +- **Invariant:** capacity reservations never exceed usable capacity; overflow becomes queue time + or an explicit failure, never silent. + +### Employee (8) +- **Knows:** wage (cents/service), speed (bp), quality skill (0..1000), reliability (bp), station + fit per station (0..1000). +- **Can:** be assigned to exactly one of {Cold, Sauté, Grill, Pastry, FrontOfHouse, Off}. +- **Cannot:** work two assignments at once; an `Off` employee incurs no wage and does no work. +- **Invariant:** labor cost derives only from employees actually working the service. + +--- + +## Runtime (authoritative, per service) + +### Restaurant +- **Knows:** its menu (chosen recipes + prices), staffing/station assignment, capacity posture + (seats + walk-in acceptance), starting cash. +- **Cannot:** recalculate the market or rewrite a persisted forecast. +- **Invariant:** one service = one authoritative ledger and one calendar of minutes. + +### Party (customer unit) +- **Knows:** its segment, size, budget, patience, the menu/prices it observed, its own elapsed + waits, and the dishes actually delivered to it. +- **Can:** consider → (queue or walk away) → seat → browse → order → wait → eat → pay → leave; + and form a satisfaction memory. +- **Cannot:** see hidden kitchen queue depth or employee skill numbers; be in two states at once; + revise its memory after leaving. +- **Invariant:** every satisfaction effect traces to an observed or experienced event (a wait it + felt, a dish it received, a service interaction), never to hidden global state. + +### Seat pool (abstracted tables) +- **Knows:** total seats (from capacity posture) and seats currently occupied. +- **Cannot:** seat more covers than capacity; seat one seat to two parties at once. +- **Invariant:** occupied seats ≤ capacity at every minute. + +### Order / Dish ticket +- **Knows:** its party, chosen dishes by course, timestamps, and current stage. +- **Can:** be placed, fired, produced, completed, delivered, or fail. +- **Cannot:** generate revenue unless the dish was completed and delivered and paid. +- **Invariant:** a failed/undelivered dish produces ingredient cost but **zero** revenue. + +### Forecast (immutable snapshot) +- **Knows:** the pre-service expected covers, expected contribution, and a confidence band, + computed only from information available before commit. +- **Cannot:** be recomputed using post-service results, current formulas, or new information. +- **Invariant:** once results exist, the stored forecast is byte-identical to what was shown at + commit time. + +### Ledger (append-only) +- **Knows:** revenue, ingredient cost, labor cost, fixed operating allocation, contribution. +- **Cannot:** edit history silently. +- **Invariant:** `contribution == revenue − ingredientCost − laborCost − fixedOverhead` exactly, + in integer cents. + +### ServiceResult / Causal report +- **Knows:** demand generated / served / lost-to-capacity / lost-to-wait; orders by dish; + revenue; ingredient cost; labor cost; contribution; average ticket time; satisfaction by + segment; quality by dish; station utilization; employee utilization; service failures; + complexity penalty; bottleneck cause; most-profitable dish; least-useful dish; highest-pressure + station; and a deterministic checksum. +- **Cannot:** collapse the outcome into a single universal "restaurant quality" score. +- **Invariant:** every reported number is derived from authoritative state, not recomputed by a + separate formula in the view. + +--- + +## Gate (what closes M0) + +Technical (Builder-verifiable): determinism reproduced; money/state invariants pass; no dominant +strategy across scenarios; ≥2 viable strategies by context; poor strategies fail legibly; reports +expose the bottleneck cause; scope clean. + +Human (owner-verifiable): comprehension, voluntary replay, and positive affect from ≥5 uncoached +players. See `M0-PROTOTYPE-CONTRACT.md` §9. diff --git a/docs/playtests/CONSENT-AND-DATA.md b/docs/playtests/CONSENT-AND-DATA.md new file mode 100644 index 0000000..5aeee5c --- /dev/null +++ b/docs/playtests/CONSENT-AND-DATA.md @@ -0,0 +1,79 @@ +# Consent & Data Policy (Playtests + Future Telemetry) + +**Purpose:** A lightweight, honest consent and data-handling policy for M0 playtests — and the standing rule for any telemetry we might ship in the game later. + +**Status:** DRAFT — policy/planning. Only **M0** is authorized for implementation. This policy governs how we treat *people's data* during M0 testing, and pre-commits the principles for any future shipped-game telemetry. It authorizes no data collection by itself; it constrains what we may collect *if and when* we collect at all. + +--- + +## 1. Principles (non-negotiable) + +These hold for M0 sessions today and for anything the shipped game might ever measure: + +1. **No telemetry or session recording without explicit consent.** No screen capture, no audio, no keystroke logging, no "quietly note what they did" — nothing recorded — until the person has said yes, out loud or in writing, to that specific thing. +2. **Documented purpose.** Before we collect anything we write down *why* we need it and *what question it answers.* If we can't state the purpose, we don't collect it. +3. **Minimum necessary.** We collect the least data that answers the question. We do **not** collect real names, contact details, precise location, device fingerprints, or anything about the person beyond what the M0 read requires. +4. **Defined retention.** Every kind of data has a stated shelf life and is deleted at the end of it. No indefinite hoarding. +5. **A way to decline — and to withdraw.** A person can refuse recording and still take part (moderator just takes written notes instead), and can ask us to delete their data afterward. Declining costs them nothing. + +--- + +## 2. What we collect at M0, why, and for how long + +| Data | Why (purpose) | Necessary? | Retention [ASSUMPTION — confirm] | +|---|---|---|---| +| Session **screen + audio recording** | Re-watch observed behavior vs. stated opinion (test script §3) | Only *with* consent; notes-only if declined | Delete raw recording **≤ 60 days** after the report is written | +| **Behavior notes / report** (`reports/`) | The actual M0 findings | Yes | Keep — but **pseudonymized** (tester-tag, not name) | +| **Tester tag** (e.g., `T-07`) | Link a report to a session without storing identity | Yes | Keep (non-identifying) | +| **Screener answers** (genre hours, desktop y/n) | Confirm fit to target player (sourcing §3) | Yes | Delete **≤ 30 days** after session | +| **Contact info** (email/Discord handle to schedule) | Scheduling only | Minimal | Delete **≤ 30 days** after session; never stored in the report | +| Real name, address, payment/PII | — | **No — do not collect** | n/a | + +**Rules that follow from the table:** + +- Reports in `docs/playtests/reports/` use a **tester-tag, never a real name.** Keep any tag→identity mapping *out* of the repo (repo is source of truth for findings, not for people's identities). +- Raw recordings live **outside the repo** and are deleted on the retention clock above. +- **[OWNER DECISION]** confirm the exact retention windows (30/60 days are our proposed defaults). + +--- + +## 3. Reusable consent blurb (say aloud or paste before a session) + +> **Before we start — quick consent.** +> This is a playtest of an early build. I'd like to **record the screen and our voices** so I can review how the game played afterward. I'm interested in *what the game does and doesn't communicate* — not in judging you; there's no right or wrong. +> +> **What I'll record:** the screen and our audio during this session. +> **Why:** so I can re-watch what happened and write up what worked and what confused people. +> **What I won't collect:** your real name, contact info beyond scheduling, or anything else about you. Notes are labeled with a code, not your name. +> **How long I keep it:** the recording is deleted within about 60 days once I've written my notes; scheduling contact info is deleted within about 30 days. +> **Your choice:** you can say **no to recording** and we'll do exactly the same session with me just taking notes. You can also change your mind partway through, and you can ask me to delete your data afterward — no reason needed. +> +> **Is it okay to record? (yes / no)** + +If the answer is **no**: proceed notes-only. Do not record. Do not treat declining as a problem. + +--- + +## 4. Standing rule for FUTURE shipped-game telemetry + +We are not building telemetry now — **only M0 is authorized**, and M0 has no shipped telemetry. But accepted review finding #6 named telemetry consent as a gap, so we pre-commit the rule so nobody "just adds analytics" later without thinking: + +- **Opt-in is the default posture we design toward.** [OWNER DECISION] whether launch telemetry is strictly opt-in or opt-out — but if opt-out, it must be **clearly disclosed on first run with a one-click off**, never buried. +- **Opt-out must always exist and always work** — a single, obvious toggle that fully stops collection. +- **Minimum-necessary and purpose-documented** apply exactly as in §1. Telemetry answers a *named product question* (e.g., "which strategies do players actually run?") or we don't collect it. +- **No PII in gameplay telemetry.** Aggregate/pseudonymous events only; no names, no precise location, no cross-product identifiers. +- **EU-data awareness.** [ASSUMPTION — confirm] a desktop game sold on Steam will reach EU players, which brings **GDPR**-style obligations (lawful basis, disclosure, deletion/access rights, data-minimization). We do not need to solve this now, but any telemetry design must be reviewed against it *before* it ships. Treat "we'll figure out GDPR later" as a blocker, not a footnote. +- **[OPEN QUESTION]** which platform/analytics tooling (if any) we would use, and whether it can honor deletion requests and EU residency — must be answered before a single telemetry event ships. + +--- + +## 5. Open questions & owner decisions (rollup) + +- **[OWNER DECISION]** Confirm retention windows (proposed: recordings ≤60d, screener/contact ≤30d). +- **[OWNER DECISION]** Future shipped telemetry: opt-in vs. clearly-disclosed opt-out. +- **[OPEN QUESTION]** Where do raw recordings and the tag→identity map live (outside the repo, access-controlled)? +- **[OPEN QUESTION]** GDPR/EU-data path for any future telemetry — tooling that supports disclosure, deletion, and residency. + +--- + +*This policy pairs with `M0-TEST-SCRIPT.md` (which requires consent before recording) and `PLAYTEST-SOURCING.md` (IP-exposure note §8 covers protecting the build; this file covers protecting the person).* diff --git a/docs/playtests/M0-TEST-SCRIPT.md b/docs/playtests/M0-TEST-SCRIPT.md new file mode 100644 index 0000000..d14469f --- /dev/null +++ b/docs/playtests/M0-TEST-SCRIPT.md @@ -0,0 +1,178 @@ +# M0 Moderator Test Script + +**Purpose:** The exact protocol a moderator follows for an M0 playtest session — how to introduce the build (without coaching), what to observe, what to ask afterward, and how to score whether M0 is actually *fun*. + +**Status:** DRAFT — planning/protocol only. Only **M0** is authorized for implementation. This script governs how we test M0; it does not authorize building anything beyond it. + +--- + +## 0. The one rule of this session: do not coach + +The M0 core product question is: + +> *Can menu, pricing, staffing, and capacity decisions create multiple understandable and viable restaurant strategies, with visible consequences that make players want to revise their plan and run another service?* + +You cannot answer that question if you tell the player the answer. **The design spine is "the menu is the strategy" — the player must discover that (or fail to), never be told it.** + +Therefore: + +- **Do NOT** explain the intended strategy, the intended build order, what the menu "should" do, or what a good outcome looks like. +- **Do NOT** rescue the player when they head toward a "wrong" decision. A player walking into a bottleneck is *data*, not a mistake to prevent. +- **Do NOT** answer "am I doing this right?" Deflect: *"There's no right — do what makes sense to you and keep talking."* +- **Only** answer questions about the *interface/mechanics of the terminal* ("how do I enter a number?") — never about *strategy*. + +If you catch yourself about to teach, stop. The session is contaminated the moment you coach. + +--- + +## 1. Session setup (moderator checklist) + +- [ ] Confirm the tester is **uncoached** (has not read design docs / heard the pitch). If unsure, they are not an M0 core-read tester. See `PLAYTEST-SOURCING.md` §2-3. +- [ ] Confirm **consent** for any recording/telemetry per `CONSENT-AND-DATA.md`. Read the consent blurb aloud; get an explicit yes. **No recording without it.** +- [ ] Build ready: moderated screen-share or hosted terminal (M0 is a CLI build — see sourcing §4). Verify it launches *before* the tester joins. +- [ ] Have the **report template** (§7) open and ready to fill live. +- [ ] Set expectations for time: **[ASSUMPTION]** ~45-60 minutes total. + +--- + +## 2. The only introduction you give + +Say this, and essentially nothing more: + +> **"Play this and think out loud."** + +You may add the minimum logistics only: + +> "It's a text/terminal program about running a restaurant. There's no right or wrong way. Say whatever's going through your head as you go — what you're looking at, what you're deciding, what you expected. I'll mostly stay quiet. If something breaks or you can't figure out how to type an answer, ask me — but for anything about *what to do*, just go with your gut." + +Then **be quiet and observe.** Prompt to keep them talking only when they go silent: *"What are you thinking right now?"* / *"What did you expect to happen there?"* Never *"why don't you try X?"* + +--- + +## 3. What to record WHILE they play — OBSERVED BEHAVIOR + +**Record OBSERVED BEHAVIOR separately from STATED OPINION.** This separation is mandatory. What a player *does* is stronger evidence than what a player *says*, and the two often disagree (accepted finding #4: comprehension is not fun; a player can succeed and still be bored). + +Log behavior with rough timestamps. Capture: + +- **First decisions** — what do they touch first (menu? pricing? staff? capacity?) and in what order, before any coaching could have happened. +- **Comprehension moments** — where they clearly understood a consequence ("oh, so if I price this high, fewer people order it"). +- **Confusion moments** — where they misread a number, couldn't find an action, or drew a wrong causal conclusion. +- **Bottleneck contact** — do they *notice* when their plan hits a wall (e.g., kitchen can't keep up, staffing too thin)? Do they *diagnose* it? +- **Revision** — after seeing results, do they *change their plan* and run another service? (This is the M0 question in behavioral form.) +- **Unprompted reactions** — leaning in, laughing, groaning, "ooh," "ugh," going quiet-and-focused vs. quiet-and-checked-out. + +--- + +## 4. Fun and affect observation rubric + +**This is the part of M0 the old plan missed (accepted finding #4).** M0's bar was comprehension + replay, but never *fun*. A build can be fully understandable and fully replayable and still be a **chore**. We are watching for genuine affect. Score each signal as **Present / Weak / Absent** from *observed behavior*, not from the exit survey. + +| Signal | What it looks like | Present / Weak / Absent | +|---|---|---| +| **Leaning in** | Body/voice engages; posture forward; faster, focused input | | +| **Unprompted reaction to results** | Spontaneous "ooh / ugh / yes / no" when a service resolves — not solicited | | +| **Satisfaction after diagnosing a bottleneck** | Visible "aha" + pleasure when they figure out *why* the plan stalled | | +| **Frustration aimed at their own plan, not the interface** | "*I* under-staffed," not "this UI is broken" — frustration at the *problem*, which is good; frustration at the *tool*, which is a defect | | +| **Desire to retry** | Wants to run another service / start over with a new plan *before* we ask | | +| **Experimentation** | Deliberately varies a lever to see what happens; tests a hypothesis | | +| **Ownership language** | "*my* menu," "*my* mistake," "I should try…," "next time *I'll*…" — they've adopted the restaurant as theirs | | + +**Interpretation:** + +- Multiple signals **Present**, and frustration aimed at *their own plan* → M0 is doing its job: the systems are legible enough to own and interesting enough to want to beat. +- Signals **Absent** or frustration aimed at the **interface** → the fun is not landing, or legibility is failing. + +**Hard rule — the M0 fail signal:** + +> **A player who completes the loop competently but calls it a chore is an M0 FAIL / REWRITE signal, not a pass.** + +Comprehension + replay-capability with *no fun* does **not** clear M0. If we see competent, joyless completion, we do not ship the systems as-is — we rewrite. Record this verdict explicitly in the report; do not soften it. + +--- + +## 5. The 12 post-play questions + +Ask these *after* play. Keep asking them open — do not lead. Capture answers as **STATED OPINION** (kept separate from the behavior log in §3). + +1. **In your own words, what is this game about?** (Did the core fantasy — building one distinctive restaurant as a coherent machine — come through, unprompted?) +2. **What were you trying to do?** (What did they perceive as the goal / win condition?) +3. **What decisions did you feel you were making?** (Do menu / pricing / staffing / capacity register as *decisions*?) +4. **Which of your decisions mattered most, and how could you tell?** (Are consequences *visible* and attributable to a lever?) +5. **When something went wrong or underperformed, did you understand *why*?** (Legibility of failure — the bottleneck read.) +6. **Did you feel like there was more than one viable way to play?** (The "multiple understandable and viable strategies" clause — directly.) +7. **What would you do differently if you ran it again?** (Do they have a *revised plan*? Do they even want a next run?) +8. **Was there a moment you wanted to stop, or a moment you didn't want to stop? When?** (Locates engagement and drop-off in time.) +9. **What was the most satisfying moment? The most frustrating?** (And — was the frustration at *their plan* or at the *tool*?) +10. **Was any number, screen, or result confusing or hard to trust?** (Comprehension defects; audio/legibility gaps.) +11. **Did it feel like *your* restaurant?** (Ownership — pairs with the §4 ownership-language signal.) +12. **Would you play another service right now if I let you? Would you play this again next week?** (Pull-to-replay — immediate *and* durable.) + +> **Never** ask leading questions ("Wasn't the menu the key?"). If a question above starts to teach, cut it. + +--- + +## 6. Wrap-up + +- Thank them. **Do not** debrief them on the "intended" strategy — they may test a later build, and you'd contaminate them. +- Confirm data handling per `CONSENT-AND-DATA.md` (what you recorded, how long you keep it, how they can withdraw). +- Fill in the report **immediately**, while behavior is fresh, into `docs/playtests/reports/`. + +--- + +## 7. Report template + +Copy this into a new file at **`docs/playtests/reports/YYYY-MM-DD-.md`** (one file per session; `` is a non-identifying code, not a name — see consent policy). + +```markdown +# M0 Playtest Report — + +- **Date:** YYYY-MM-DD +- **Moderator:** +- **Build / commit:** +- **Channel (source):** +- **Tester fit vs §3 profile:** +- **Uncoached confirmed:** +- **Consent given (recording/telemetry):** + +## A. OBSERVED BEHAVIOR (what they DID — timestamps) +- First things touched (order): +- Comprehension moments: +- Confusion moments: +- Bottleneck: noticed? diagnosed? +- Revised plan / ran another service? +- Unprompted reactions: + +## B. FUN & AFFECT RUBRIC (Present / Weak / Absent — from behavior) +| Signal | Score | Note | +|---|---|---| +| Leaning in | | | +| Unprompted reaction to results | | | +| Satisfaction after diagnosing a bottleneck | | | +| Frustration at own plan (not interface) | | | +| Desire to retry | | | +| Experimentation | | | +| Ownership language | | | + +## C. STATED OPINION (the 12 questions — kept separate from A) +1. What is this about: +2. Trying to do: +3. Decisions felt: +4. What mattered / how they could tell: +5. Understood why things went wrong: +6. More than one viable way: +7. Would do differently: +8. Wanted to stop / didn't want to stop: +9. Most satisfying / most frustrating (and at what): +10. Confusing / untrustworthy numbers: +11. Felt like *your* restaurant: +12. Play again now / next week: + +## D. VERDICT +- **Core question (multiple viable, legible strategies → want to revise & replay):** +- **FUN check:** +- **⚠️ Chore flag:** +- **Behavior vs. opinion disagreements:** +- **Top 3 findings:** +- **Recommended action:** +``` diff --git a/docs/playtests/PLAYTEST-SOURCING.md b/docs/playtests/PLAYTEST-SOURCING.md new file mode 100644 index 0000000..ea1365c --- /dev/null +++ b/docs/playtests/PLAYTEST-SOURCING.md @@ -0,0 +1,192 @@ +# Playtest Sourcing Plan (M0) + +**Purpose:** A realistic plan for a 1-2 person team to recruit at least five *uncoached* playtesters for the M0 build, treating testers as a scarce, non-free resource. + +**Status:** DRAFT — planning/hypotheses only. Only **M0** is authorized for implementation. This document does not authorize building anything; it plans how we will *find humans to test M0*. + +--- + +## 0. Labeling key + +Every non-obvious claim is tagged: + +- **[VERIFIED]** — grounded in a cited source (see Sources). +- **[ASSUMPTION]** / **[ASSUMPTION — confirm]** — our working guess; confirm before spending money. +- **[OPEN QUESTION]** — unresolved; needs an answer before we lean on it. +- **[OWNER DECISION]** — Howard/Aaron must choose. + +--- + +## 1. Why this document exists + +Accepted review finding #6 flagged **playtester sourcing** as an edge gap: the plan assumed testers would simply appear. They will not. For a two-person team (Howard and Aaron) directing AI agents, human attention is the single scarcest input we have — scarcer than compute, scarcer than code. Every tester we burn on a broken build or a confusing session is a tester we cannot re-use for a fresh-eyes read later. + +This plan therefore treats testers as **inventory**: finite, costly to acquire, and easy to spoil. + +--- + +## 2. What we are recruiting *for* + +The M0 core product question is: + +> *Can menu, pricing, staffing, and capacity decisions create multiple understandable and viable restaurant strategies, with visible consequences that make players want to revise their plan and run another service?* + +So an M0 tester is not a QA bug-hunter. We need people who will **make decisions, see consequences, and tell us whether they wanted to try again** — and, per accepted finding #4, whether it was actually **fun**, not merely comprehensible. See `M0-TEST-SCRIPT.md` for the moderator protocol and the fun/affect rubric. + +**"Uncoached" is the whole point.** A tester who has read the design docs, heard Howard explain "the menu is the strategy," or been told the intended build order is *contaminated* and cannot be used for the M0 comprehension/fun read. Guard this hard: the people closest to us are the easiest to accidentally coach. + +--- + +## 3. Target player profile (screener) + +We are building a **single-player, desktop-first, premium restaurant-management simulation** — a spiritual successor in the lineage of Restaurant Empire I/II, adjacent to Chef: A Restaurant Tycoon Game, Big Ambitions, Two Point Hospital, Recipe for Disaster, and PlateUp!. Codename **"Mise"** (not final; never brand it "Restaurant Empire"). + +**Screen IN — a representative M0 tester:** + +- Plays management / tycoon / colony / builder sims on **desktop** (mouse+keyboard), and has finished at least one. +- Is comfortable reading numbers and tables (this is a systems game, not a cozy clicker). +- Can articulate *why* they made a decision, even loosely (needed for think-aloud). +- Has **not** read our design docs and has **not** been briefed on strategy. + +**Screen OUT (for the core read):** + +- Anyone who worked on or was briefed on Mise. +- People who only play action/shooter/sports titles and dislike spreadsheets — they are a real future audience segment but not the M0 comprehension cohort. +- **[ASSUMPTION]** For M0 specifically, deprioritize pure-console/controller-only players: M0 is a **CLI/terminal build** with no controller support. Controller/Steam Deck matters commercially later ([VERIFIED] Deck verification and controller support materially affect management-sim sales — accepted finding #6 / market context), but it is out of scope for the M0 read. + +**One-line screener question (reusable):** +> "Roughly how many hours have you put into management or tycoon games like Two Point Hospital, Big Ambitions, RimWorld, or a restaurant/city builder in the last year, and did you play them on desktop?" + +Answers of "dozens+ on desktop" = strong fit. "Never / only on console" = weak fit for M0. + +--- + +## 4. The build we are handing them: an M0 CLI / headless problem + +**Critical constraint:** M0 is a **C#/.NET deterministic simulation core with a CLI/terminal front end.** There is no GUI, no installer, no store page. This shapes every distribution choice below. + +Implications, and how we deal with them: + +| Problem | Mitigation | +|---|---| +| A raw terminal binary looks like malware to a normal player. | Ship a **self-contained single-file build** (`dotnet publish` self-contained, per-OS) so there is **no .NET install step**. Zip it with a one-page `HOW-TO-RUN.txt` (double-click / right-click→Open on macOS Gatekeeper, `chmod +x` note for Linux). | +| CLI intimidates non-technical testers. | For remote/unmoderated testers, prefer a **hosted terminal session** (see below) over asking them to run a binary. For friends/local, do it **moderated over a screen-share** so we drive the terminal setup and they drive the decisions. | +| Gatekeeper / SmartScreen will block an unsigned binary. | **[ASSUMPTION — confirm]** We will not code-sign for M0 (cost + cert hassle). Instead, moderated sessions or hosted terminals sidestep the OS-trust prompt entirely. | +| We need to see *behavior*, not just hear opinions. | Prefer **moderated screen-share** for M0 so the moderator can log observed behavior live (finding: observed vs stated must be separated — see test script). | + +**Distribution options, cheapest-trust-first:** + +1. **Moderated screen-share (default for M0).** Tester joins a video call; **we** run the build on our machine or theirs via screen-control, they call the shots and think aloud. Zero install trust problem, maximal observation. Best signal, highest moderator cost (our time). +2. **Hosted terminal / web-shell.** Run the M0 binary on a small VM and expose it through a browser terminal (e.g., a `ttyd`/`gotty`-style shell or a container-per-session) behind a one-time link. **[ASSUMPTION — confirm]** feasibility and cost; good for unmoderated remote where we cannot ask a stranger to run an unsigned binary. **[OPEN QUESTION]** does exposing a shell to the internet create an abuse/security surface we must sandbox? (Yes — one-time link, disposable container, no host FS access.) +3. **Direct binary + `HOW-TO-RUN.txt`.** Zip via a private link (see IP note §8). Only for **technically comfortable** testers who pass a "are you OK running a terminal program?" pre-check. + +--- + +## 5. Channels + +Five channels below. For each: recruitment method, expected cost, scheduling, build distribution, and screening. **Costs are per accepted-finding discipline — no fabricated figures; ranges are labeled.** + +### Channel A — Friends who did *not* read the design docs + +- **Recruitment:** Direct ask from Howard/Aaron's own network. The catch: **you must find friends who are genuinely uncoached.** Keep an explicit "do-not-ask" list of anyone who has heard the pitch. +- **Expected cost:** **[ASSUMPTION]** ~$0 cash; cost is *social capital* + our moderator time (~45-60 min/session). Cheapest channel, but the **scarcest supply of truly uncoached people** and the highest coaching-contamination risk. +- **Scheduling:** Text/DM, pick a slot directly. Fastest to schedule. +- **Build distribution:** Moderated screen-share (option 1). We drive the terminal. +- **Screening:** Apply the §3 screener honestly. A friend who never plays sims is a weak-fit *and* likely to be polite rather than truthful — a double failure mode. **Guard against politeness bias**: friends over-praise. Weight their *observed behavior* far above their stated opinion. + +### Channel B — Tycoon / management-game Discords + +- **Recruitment:** Post in playtest/feedback channels of servs for adjacent games (management-sim communities, tycoon-game hubs). **Read each server's rules first** — many ban unsolicited recruitment; use only servers that permit it or ask a mod. **[OPEN QUESTION]** which specific servers allow paid/unpaid playtest recruitment — build a small allow-list before posting. +- **Expected cost:** **[ASSUMPTION]** $0-$25/tester if we offer a small thank-you (a few dollars gift code, or a future key). Cash-optional; goodwill-driven. +- **Scheduling:** Async signup form → we book moderated slots, or run unmoderated via hosted terminal. +- **Build distribution:** Hosted terminal (option 2) for reach, or screen-share for the best-fit volunteers. +- **Screening:** Naturally high fit — these people already play the genre — but skew toward *enthusiast/expert*, which can *underweight* first-timer confusion. Balance with at least one genre-lighter tester. + +### Channel C — Permitted subreddits + +- **Recruitment:** Post where the rules explicitly allow playtest recruitment (e.g., dedicated playtesting/gamedev-recruitment subs and any game-specific sub that permits it). **Do not spam general game subs** — most forbid self-promo and will remove/ban. +- **Expected cost:** **[ASSUMPTION]** $0 cash + our time to write a compliant post and vet respondents. Moderate scheduling overhead (strangers flake). +- **Scheduling:** Screener form linked in the post → book confirmed fits only. Expect **[ASSUMPTION]** a high no-show rate; over-recruit by ~2x. +- **Build distribution:** Hosted terminal (strangers, unsigned-binary trust problem); screen-share for the strongest fits who agree to a call. +- **Screening:** Screener form is mandatory here — Reddit surfaces a lot of off-target volunteers. Filter hard on the §3 desktop-sim question. + +### Channel D — Paid remote-playtest platforms (PlaytestCloud / UserTesting) + +- **Recruitment:** Their panels. You define an audience, they recruit; results come back as recordings + surveys. +- **Expected cost:** + - **PlaytestCloud:** priced in **Video Tokens** — most standard single-session playtests are **~1 token/player**, advanced targeting from ~1.5 tokens; token bundles come via subscription tiers (**Professional Basic ~$1,175/mo billed yearly / 120 tokens/yr** and up), with an **Indie Pass** for studios under $1M revenue. [VERIFIED — PlaytestCloud pricing page / G2, 2026] Effective per-tester cost depends entirely on the plan; **[ASSUMPTION — confirm]** the Indie Pass is the only tier that makes sense for us, and we should price it directly before committing. + - **UserTesting:** does **not** publish per-session pricing; sold as **annual contracts commonly $25k-$35k minimum** for a first contract, median north of ~$40k/yr. [VERIFIED — Vendr / UserIntuition, 2026] **This is almost certainly out of budget for a two-person team.** Generic panels also skew toward general consumers, not sim enthusiasts. + - Rule of thumb for *ad-hoc* paid testers elsewhere: **[ASSUMPTION]** ~$30-$80 per unmoderated session, more for a specialized audience. [VERIFIED — general user-testing cost ranges, Articos/UXtweak 2026] +- **Scheduling:** Platform-managed; results in **[ASSUMPTION]** days, not hours. +- **Build distribution:** **This is the hard part for a CLI build.** These platforms expect a URL or an installable app, not a terminal binary. → We must expose M0 through a **hosted terminal/web-shell** (option 2) and give the platform a plain link. **[OPEN QUESTION]** confirm the chosen platform can point participants at an arbitrary web URL and record their screen while they use it. +- **Screening:** Best *targeting* controls of any channel (age, genre, spend), but **[OWNER DECISION]** whether M0 is worth paid spend at all, given that a CLI build is a poor fit for these platforms and M0's real question is *fun/comprehension* best read by a live moderator. **Recommendation:** defer paid platforms to a later, GUI-having milestone; use them for M0 only if free channels cannot yield 5 fits. + +### Channel E — Local gamedev / university groups + +- **Recruitment:** Local IGDA-style meetups, university game-dev clubs, game-design courses (offer to be a "bring your build" night). In-person is high-signal and high-trust. +- **Expected cost:** **[ASSUMPTION]** ~$0 cash + travel/time; maybe pizza. Access depends on Howard/Aaron actually having a local group within reach. **[OPEN QUESTION]** do we have one? +- **Scheduling:** Tied to the group's meeting cadence — **least flexible**, plan weeks ahead. +- **Build distribution:** In-person, on **our laptop** (moderated) — completely sidesteps the install/trust problem. Ideal for a CLI build. +- **Screening:** Gamedev crowds are systems-literate (good) but can slip into *designer-critique* mode ("here's how I'd build it") instead of *player* mode. Redirect them to think-aloud *play*, not design feedback. + +--- + +## 6. Channel comparison at a glance + +| Channel | Cash cost [ASSUMPTION unless noted] | Uncoached supply | CLI-build fit | Signal quality | Scheduling speed | +|---|---|---|---|---|---| +| A. Uncoached friends | ~$0 | Low (contamination risk) | High (moderated) | Medium (politeness bias) | Fast | +| B. Tycoon Discords | $0-$25/tester | Medium-High | Medium (hosted term) | High (on-genre) | Medium | +| C. Permitted subreddits | ~$0 | High | Medium (hosted term) | Medium (flake risk) | Medium | +| D. Paid platforms | High (see §5D) [VERIFIED ranges] | High (targeted) | **Low** (no CLI support) | High but pricey | Slow | +| E. Local gamedev/uni | ~$0 | Medium | **High** (in-person) | High | Slow | + +**Recommended M0 mix:** lead with **A + B + E** (near-zero cash, good CLI fit); use **C** to top up to five; treat **D** as a deferred/last-resort. This keeps M0 testing effectively free-in-cash and spends our real scarce resource — moderator time — where it yields the most behavioral signal. + +--- + +## 7. Minimum-viable N (if five representative testers are unreachable) + +Five is the target. It is not sacred. Guidance: + +- **[VERIFIED — usability rule of thumb]** ~5 users surface the large majority of *usability* problems in a system; this is a well-known heuristic (Nielsen). M0 is partly a comprehension/usability read, so five is a defensible target. +- **Minimum viable N = 3** *if all three are genuinely representative and uncoached.* Three on-target testers who independently reach the same comprehension/fun verdict is a stronger signal than five where three are off-profile friends being polite. +- **Quality gate over quantity:** **[OWNER DECISION]** we would rather ship the M0 verdict on **3 good-fit uncoached** sessions than on 5 where fit is compromised. Document exactly who tested and their fit in each report. +- If we cannot reach even **3** good-fit testers, that is itself a finding: **stop and report** that M0 could not be validated for lack of representative testers, rather than validating on a non-representative sample. **[OWNER DECISION]** on whether to then pay for Channel D to reach N=3. + +--- + +## 8. IP-exposure note for a pre-release build + +We are handing a pre-release build of a **premium** product to strangers. Minimize exposure: + +- **No source, ever.** Ship compiled binaries only. The deterministic sim core and any tuning tables are competitive substance — never distribute source or config we would not want a competitor to see. +- **Prefer moderated / hosted-terminal delivery** (options 1-2) over handing out downloadable binaries. A binary that leaves our control can be redistributed, decompiled, or leaked. A hosted session leaves nothing on the tester's machine. +- **If we must ship a binary:** private, expiring links (not a public URL); a build watermarked with a per-tester tag so a leak is traceable; **[ASSUMPTION — confirm]** whether we ask for a lightweight click-through NDA/"please don't share or stream this build" agreement — heavy NDAs kill goodwill and are hard to enforce against strangers, so keep it a **plain-language request, not a legal cudgel** for M0. +- **No streaming/recording of the build without our OK for a pre-release milestone** — and no *tester*-side recording of the build's contents. (Separately, *our* recording of the *session* requires **their** consent — see `CONSENT-AND-DATA.md`.) +- **Assume any pre-release build may leak.** Do not put anything in the M0 build (unreleased brand, roadmap, real financials) that would hurt us if screenshotted. M0 is a CLI sim of one restaurant; keep it that way. +- **[OPEN QUESTION]** at which milestone (M1? M2?) does the exposure calculus justify code-signing + a real click-through agreement? Revisit before the first GUI build goes to strangers. + +--- + +## 9. Open questions & owner decisions (rollup) + +- **[OWNER DECISION]** Is any paid-platform spend authorized for M0, or is M0 strictly free-channel? (Recommendation: free-channel only.) +- **[OWNER DECISION]** Minimum viable N floor — is 3 acceptable, and what happens if we can't reach 3? +- **[OWNER DECISION]** Do we ask for a plain-language "don't share this build" agreement, and at which milestone does that harden? +- **[OPEN QUESTION]** Which Discords/subreddits actually permit playtest recruitment? (Build the allow-list before posting.) +- **[OPEN QUESTION]** Hosted-terminal feasibility, cost, and sandboxing for a headless build exposed to strangers. +- **[OPEN QUESTION]** Do Howard/Aaron have a reachable local gamedev/university group? + +--- + +## Sources + +- [PlaytestCloud — Pricing](https://www.playtestcloud.com/pricing) +- [PlaytestCloud Pricing Overview — G2](https://www.g2.com/products/playtestcloud/pricing) +- [UserTesting Software Pricing & Plans 2026 — Vendr](https://www.vendr.com/marketplace/usertesting) +- [UserTesting Pricing in 2026 — UserIntuition](https://www.userintuition.ai/reference-guides/usertesting-pricing/) +- [User Testing Cost: The Honest Breakdown (2026) — Articos](https://www.articos.com/blog/user-testing-cost) +- [UserTesting Pricing in 2026 — UXtweak](https://blog.uxtweak.com/usertesting-pricing/) + +*Nielsen "~5 users find most usability problems" is cited as a widely-known heuristic, not from a fresh fetch above — treat as a rule of thumb.* diff --git a/docs/product/COMMERCIAL-HYPOTHESIS.md b/docs/product/COMMERCIAL-HYPOTHESIS.md new file mode 100644 index 0000000..9db7f3b --- /dev/null +++ b/docs/product/COMMERCIAL-HYPOTHESIS.md @@ -0,0 +1,278 @@ +# Commercial Hypothesis — "Mise" (working codename) + +**Purpose:** A falsifiable commercial thesis for the Restaurant Empire spiritual successor — who buys it, why it is distinct, how it could reach break-even, and what would prove the thesis wrong. + +**Status:** DRAFT / HYPOTHESIS. This is a set of testable claims, not a promise or a commitment to build. Only **M0** is authorized for implementation. Everything here is planning input. + +> Labeling convention used throughout: **[VERIFIED]** = web-sourced or in-repo fact; **[ASSUMPTION]** = a working belief we should confirm; **[ASSUMPTION — confirm]** = a market/number we have not grounded; **[OPEN QUESTION]** = unresolved; **[OWNER DECISION]** = Howard/Aaron must decide. + +--- + +## 0. The team we are writing for + +This document is written for the **actual team**: one or two non-expert creators (Howard and Aaron) directing AI coding agents. It is **not** written for a funded studio. Every recommendation is filtered through: *can two people sustain this cadence, and does it avoid commitments we cannot keep?* This is a direct response to the accepted review finding that scope was unrealistic and that the plan carried **zero team/human/commercial risk** in its register. + +--- + +## 1. Target audience + +**Primary audience:** players of deep, systems-driven **management / tycoon / business simulations** who want *decisions with consequences*, not twitch execution. They read patch notes, they replan between runs, and they enjoy spreadsheets that come alive. + +**Concentric segments:** + +| Ring | Who | What they want from us | +|---|---|---| +| Core | Fans of Restaurant Empire I/II, Two Point Hospital, Big Ambitions, Chef: A Restaurant Tycoon | A *modern, deeply-simulated* restaurant where the menu is the strategy | +| Adjacent | Colony/economy-sim players (Rimworld-adjacent, tycoon-adjacent) who like emergent operating models | Legible systems that produce stories | +| Cozy-curious | Players who arrived via Dave the Diver / cozy-management who want more depth | An approachable-but-deep single restaurant | + +**[ASSUMPTION]** The under-served niche is *depth-forward single-restaurant simulation with a distinctive identity*, sitting between the light/cozy end (Dave the Diver) and the chaotic-execution end (PlateUp!, Cook Serve Delicious). + +**[OPEN QUESTION]** Real addressable size of the "management-sim purist" audience in 2026. We do not have a defensible number and must not invent one. The wishlist campaign (see GO-TO-MARKET) is the instrument that *measures* it. + +--- + +## 2. The core player problem / desire + +Players who love this genre have a recurring frustration: most restaurant games are either **execution games** (cook fast, don't drop the plate) or **shallow tycoons** (place tables, watch money go up). Few let you *design an operating model* — a coherent machine of menu, pricing, staffing, and layout — and then *watch it succeed or fail for legible reasons*. + +**Core fantasy (locked):** *"I build one distinctive restaurant whose menu, people, layout, and service work as a coherent machine, and then turn that hard-won operating model into a culinary empire."* + +**Design spine (locked):** **The menu is the strategy.** + +The desire we serve: *"Let me make consequential decisions, see why they worked or didn't, and want to revise my plan and run another service."* That is also the **M0 core product question**. + +--- + +## 3. Why this is distinct in the 2026 management-sim market + +| Distinctive claim | How it differs from the field | +|---|---| +| **Menu-as-strategy** | Competitors treat the menu as decoration or a recipe minigame. Here it is the primary strategic surface — the thing that determines viability. | +| **One deeply-simulated restaurant first** | Not a sprawling empire on day one. Depth over breadth. The empire is the *earned* payoff (post-M3, deferred). | +| **Multiple viable strategies** | The M0 bar is that menu/pricing/staffing/capacity produce *several understandable, viable strategies* — not one dominant build. | +| **Legibility as a feature** | Consequences are visible and explainable, so players learn and replan. Audio-as-legibility is a first-class concern, not an afterthought. | +| **Deterministic simulation core** | C#/.NET engine-agnostic deterministic core supports reproducible "stories," robust saves, and clean staged rollout. | + +**[ASSUMPTION]** Restaurant Empire fans are an active, under-served nostalgia base with no modern equal that nails the *business-of-a-restaurant* fantasy. We must **never** market under the "Restaurant Empire" brand — codename only. + +--- + +## 4. Likely Steam tags + +**[ASSUMPTION]** Provisional tag set (Steam tags are player-driven; we can seed but not dictate): + +- Management, Simulation, Economy, Tycoon, Building +- Singleplayer, Strategy, Resource Management +- Cooking, Restaurant (thematic discovery) +- Character Customization / Base Building (secondary) + +Deliberately **not** targeting: Co-op, Multiplayer, Action (these describe PlateUp!/Cook Serve Delicious, not us). + +--- + +## 5. Comparable titles — what each proves about demand + +Full table lives in `docs/commercial/COMPARABLES.md`. Summary of what the field proves: + +| Title | Proves about the audience | +|---|---| +| **Restaurant Empire I/II** (2003/2004) | A dedicated fanbase exists for *business-of-a-restaurant* depth with no modern successor. **[ASSUMPTION]** | +| **Two Point Hospital** (2018) | Charming, legible management sims sell 1–2M+. **[VERIFIED]** SteamSpy band 1–2M owners; 93% positive. | +| **Dave the Diver** (2023) | Restaurant-adjacent management + emergent loop can go massively viral: 5M+ copies by late 2024. **[VERIFIED]** | +| **PlateUp!** (2022) | Roguelite-management with *shareable runs* reaches ~1M owners at $19.99, 94% positive. **[VERIFIED]** | +| **Chef: A Restaurant Tycoon** (EA) | Direct-competitor demand exists but is under-satisfied: $19.99, "Mostly Positive" 72%. **[VERIFIED]** — a quality gap we can beat. | +| **Big Ambitions** (EA, 2023) | Deep business-sim EA can hold 92% positive across 5k+ reviews. **[VERIFIED]** — EA is viable for this genre. | +| **Recipe for Disaster** (EA) | The *exact* restaurant-management niche is real but easy to leave "Mixed" (69%) if legibility/polish slip. **[VERIFIED]** — a cautionary tale. | + +**Takeaway:** demand is proven up and down the price ladder; the open question is *execution quality and legibility*, which is exactly where the M0 bar is aimed. + +--- + +## 6. Provisional price bands + +Reasoning and the break-even model live in `docs/commercial/PRICE-AND-BREAK-EVEN-HYPOTHESIS.md`. Bands here are **[ASSUMPTION]** anchored to **[VERIFIED]** comparable prices: + +| Band | Range | Anchor comparables | When it fits | +|---|---|---|---| +| Value | $14.99–$16.99 | Recipe for Disaster ($16.99) | If content depth at launch is modest | +| **Standard (target)** | **$19.99–$24.99** | PlateUp! ($19.99), Chef ($19.99) | The likely premium-1.0 landing zone | +| Premium-depth | $24.99–$29.99 | Two Point titles' full-price tier | Only if M3 content clearly justifies it | + +**[OWNER DECISION]** Final price band is not locked and depends on the actual M3 content volume and the EA-vs-premium decision. + +--- + +## 7. The premium-launch (1.0) case + +- **What it is:** ship a finished, well-reviewed **first-commercial cut = everything through M3** at full price. +- **Pros:** one clean review moment; strong "1.0" launch spike; no promise-management burden; matches a small team that would rather ship *done* than run a live-service cadence. +- **Cons:** no early revenue; no community-shaped design; one shot at first-review sentiment; higher risk if the launch build under-delivers. + +## 8. The Early-Access case + +- **What it is:** ship a smaller-but-complete deterministic slice into EA and grow it in public. +- **Pros:** **EA is the genre-default successful path** (Chef, Big Ambitions, Recipe for Disaster all EA). Early cash flow; community-driven design; scope-forgiveness; the **modular deterministic architecture suits a staged rollout** (systems ship as coherent, testable modules). +- **Cons:** demands sustained public cadence (hard for two people); "Mixed" is a real failure mode (Recipe for Disaster); review score is set early and sticks. + +## 9. Risks of each model + +| Model | Primary risk | Mitigation | +|---|---|---| +| Premium 1.0 | One-shot review risk; no runway | Heavy pre-launch demo + Next Fest to de-risk sentiment before charging | +| Early Access | Cadence risk for a 2-person team; premature "Mixed" | Enter EA only with a *legible, fun* slice; stage by module; keep scope honest | +| **Both** | **Discoverability failure** (see §17) | Treat "we can be discovered" as an explicit proof gate, not an assumption | + +Full structured comparison and provisional recommendation: `docs/commercial/EARLY-ACCESS-DECISION.md`. **This is an [OWNER DECISION]**, kept de-locked pending platform answers. + +--- + +## 10. Units-to-break-even FRAMEWORK + +> No invented sales numbers. This is a **formula plus a worked example with clearly-labeled placeholder inputs.** Replace placeholders with real quotes/costs before trusting any output. + +**Net revenue per unit:** + +``` +net_per_unit = price + × (1 − store_cut) // Steam standard is 30% until revenue tiers; use 0.30 + × (1 − refund_rate) // fraction refunded + × (1 − discount_avg) // blended lifetime discount vs list price +``` + +**Break-even units:** + +``` +break_even_units = total_cost / net_per_unit +``` + +**Worked example (ALL INPUTS ARE PLACEHOLDERS — not real figures):** + +| Input | Placeholder value | Label | +|---|---|---| +| `price` | $20.00 | [ASSUMPTION — target band] | +| `store_cut` | 0.30 | [VERIFIED] Steam standard base rate | +| `refund_rate` | 0.08 | [ASSUMPTION — confirm] rule-of-thumb | +| `discount_avg` | 0.20 | [ASSUMPTION — confirm] blended lifetime | +| `total_cost` | $PLACEHOLDER | [OPEN QUESTION] must be summed from §11 | + +``` +net_per_unit = 20.00 × 0.70 × 0.92 × 0.80 = $10.30 (placeholder-derived) +break_even_units = total_cost / 10.30 +``` + +So if `total_cost` were a placeholder **$40,000** of out-of-pocket spend, `break_even_units ≈ 3,884`. **This number is illustrative only** — engineering labor is largely covered by owners+agents (see §11), so `total_cost` is dominated by *cash* categories (art, audio, legal, QA, marketing, contractors), which we have not yet quoted. + +**[OPEN QUESTION]** What is the real `total_cost`? Until §11 categories are quoted, break-even is a framework, not a figure. + +--- + +## 11. Cost categories + +| Category | Status for this team | +|---|---| +| **Engineering** | **Largely covered by owners + AI agents** — near-zero cash, real *time* cost | +| Art (2D/3D, UI) | **Cash / contractor** — likely the biggest out-of-pocket line | +| Audio (music, SFX, audio-as-legibility) | **Cash / contractor** — legibility makes this load-bearing, not cosmetic | +| Legal (entity, trademark clearance vs "Restaurant Empire", contracts, privacy/consent) | **Cash** — trademark clearance is mandatory given the codename constraint | +| QA / playtesting (sourcing testers, devices) | **Cash + time** — review flagged playtester sourcing as an edge gap | +| Marketing (capsule art, trailer, Next Fest, key distribution) | **Cash + time** | +| Contractors (specialists filling non-expert gaps) | **Cash, variable** | +| Platform / tooling (Steam $100 fee, build infra) | **Cash, minor** — [VERIFIED] Steam Direct fee is $100 per app | + +**[OPEN QUESTION]** No line here has a real quote yet. A costed budget is a prerequisite to trusting §10. + +--- + +## 12. Wishlist-funnel assumptions + +**[ASSUMPTION — confirm / PROVISIONAL — research]** Rules of thumb, not our numbers: + +- Wishlists are the primary pre-launch health metric; **launch-day conversion of wishlists to sales is commonly cited in the low tens of percent**, rising over the first year. We will **measure, not assume**, our own rate. +- **[VERIFIED, directional]** Next Fest is the single strongest organic wishlist-acceleration event for a pre-launch PC game; demos that end on a wishlist CTA convert materially better than those that don't. (Second Stage / StraySpark analyses.) +- **[ASSUMPTION]** For a two-person team, a *healthy* pre-launch wishlist target is a **research task**, not a guess in this doc. GO-TO-MARKET carries the provisional targets, all marked `[PROVISIONAL — research]`. + +--- + +## 13. Demo strategy + +- Ship a **short, immediately-engaging** demo built from the M0 slice once it is *legible and fun* (not just comprehensible — the review found M0 tested comprehension/replay but never fun). +- The demo must **exhibit the core loop fast** (menu → pricing → staffing → run a service → visible consequence → want to replan) with **no long tutorial**. +- The demo **ends on a wishlist CTA**, not a black screen. **[VERIFIED, directional]** this alone can move conversion meaningfully. +- Keep the demo scope inside authorized work: it is a *presentation* of the M0/M1 slice, not new features. + +## 14. Steam Next Fest strategy + +- Enter Next Fest **once**, with the demo already tested privately — you get the strongest wishlist bump only if the demo is good on arrival. **[VERIFIED, directional]** +- **Stream during the fest** — authenticity beats production value; multiple sessions correlate with higher conversion. **[VERIFIED, directional]** Fits a founder-led two-person team. +- Post dev updates every 2–4 weeks around the fest to re-engage wishlisters. **[VERIFIED, directional]** + +## 15. Creator / streamer discoverability + +- **[ASSUMPTION]** This genre is streamer-friendly when runs produce *stories and legible failure*. PlateUp! and Dave the Diver prove that a shareable moment drives discovery. +- We should design the demo so a streamer hits a **"look what my restaurant did"** moment within minutes. +- **[OPEN QUESTION]** Do we have any creator relationships? If zero, that is a named risk (see §17), not a plan. + +## 16. Session / replay characteristics that produce shareable stories + +- A **service** is a natural short, self-contained session with a clear outcome — good clip length. +- **Multiple viable strategies** (the M0 bar) means players compare builds — natural "here's my weird menu that somehow works" content. +- Deterministic core → **reproducible/seed-shareable** situations. **[ASSUMPTION]** seed-sharing could be a low-cost virality lever (design input, not a committed feature). + +## 16b. Steam Deck & controller relevance + +- **[VERIFIED, directional]** Steam Deck Verified status and controller support **materially affect sales** for management/tycoon/colony sims in 2026. +- **[ASSUMPTION]** A menu-and-tables management sim is *plausibly* Deck-friendly but is UI-dense; controller/Deck support is a real design cost, flagged by the review as an edge gap. +- **[OWNER DECISION]** Whether to target Deck Verified for the first commercial cut, or treat it as a fast-follow. Not committed. Note: **only M0 is authorized**; this is a downstream decision. + +--- + +## 17. Conditions that would INVALIDATE the commercial thesis + +The thesis is falsifiable. It is **refuted** if: + +1. **Fun fails.** M0/demo playtesters understand and can replay but *do not want to* — no pull to run another service. (Directly the review's accepted finding about the M0 bar.) +2. **No differentiation lands.** Playtesters cannot articulate why this beats Chef / Recipe for Disaster; "menu is the strategy" doesn't read in play. +3. **Discoverability fails.** The Coming-Soon + demo + Next Fest sequence does not clear the wishlist gate defined in GO-TO-MARKET (named failure condition there). **This is the single most likely killer for a two-person team.** +4. **One dominant strategy.** M0 shows a single optimal build, collapsing the "multiple viable strategies" premise. +5. **Cadence collapse.** If EA is chosen and the two-person team cannot sustain the public update cadence, the review flywheel inverts to "Mixed." +6. **Break-even is unreachable** once §11 is really costed against a realistic wishlist-derived sales range. + +Any one of these firing is a **stop-and-report** event, not something to paper over. + +--- + +## Verified / Assumptions / Open questions / Owner decisions + +### [VERIFIED] (web-sourced or in-repo) +- PlateUp! ~1M owners, $19.99, 94% positive. (SteamSpy / Steam) +- Dave the Diver 5M+ copies by late 2024. (Game World Observer / Steam) +- Two Point Hospital 1–2M owners, 93% positive. (SteamSpy) +- Chef: A Restaurant Tycoon $19.99, EA, 72% "Mostly Positive". (Steam) +- Big Ambitions 92% positive across 5k+ reviews, EA. (Steam) +- Recipe for Disaster $16.99, EA, 69% "Mixed". (Steam) +- Steam standard store cut base rate 30%; Steam Direct fee $100/app. +- Next Fest is the strongest single organic wishlist event; demo-end wishlist CTA lifts conversion; streaming during the fest correlates with higher conversion. (Second Stage, StraySpark, alinea analytics — directional.) +- EA is the genre-default successful path for restaurant/business sims. + +### [ASSUMPTION] (confirm before relying) +- Restaurant Empire fanbase is active and under-served. +- Target price band $19.99–$24.99. +- Our niche = depth-forward single-restaurant sim between cozy and chaotic-execution. +- Refund rate ~8%, blended lifetime discount ~20% (placeholders in the break-even model). +- This genre is streamer-friendly given legible failure. + +### [OPEN QUESTION] +- Real addressable audience size (measured by the wishlist campaign, not guessed). +- Real `total_cost` — no cost line is quoted yet. +- Our own wishlist→sale conversion rate. +- Do we have any creator/streamer relationships? (If none, that is a risk.) +- Deck-friendliness of a UI-dense management sim. + +### [OWNER DECISION] +- Final price band. +- Premium-1.0 vs Early-Access (de-locked pending platform answers — see EARLY-ACCESS-DECISION.md). +- Steam Deck Verified now vs fast-follow. +- Whether/when to authorize any work beyond M0. + +**Sources:** [PlateUp! SteamSpy](https://steamspy.com/app/1599600) · [PlateUp! on Steam](https://store.steampowered.com/app/1599600/PlateUp/) · [Dave the Diver 4M — Game World Observer](https://gameworldobserver.com/2024/06/27/dave-the-diver-4-million-copies-sold-anniversary) · [Two Point Hospital SteamSpy](https://www.steamspy.com/app/535930) · [Chef: A Restaurant Tycoon on Steam](https://store.steampowered.com/app/886900/Chef_A_Restaurant_Tycoon_Game/) · [Big Ambitions on Steam](https://store.steampowered.com/app/1331550/Big_Ambitions/) · [Recipe for Disaster on Steam](https://store.steampowered.com/app/1492360/Recipe_for_Disaster/) · [Next Fest data — Second Stage](https://secondstage.io/2026/04/steam-next-fest-the-data-behind-what-actually-drives-wishlists) · [Demo optimization — StraySpark](https://www.strayspark.studio/blog/steam-next-fest-demo-optimization-wishlists) diff --git a/docs/product/EFFORT-AND-SCOPE.md b/docs/product/EFFORT-AND-SCOPE.md new file mode 100644 index 0000000..897ae35 --- /dev/null +++ b/docs/product/EFFORT-AND-SCOPE.md @@ -0,0 +1,54 @@ +# Effort and Scope (honest estimate) + +**Status:** Planning. Only **M0 is authorized to build.** Everything below M0 is an estimate to inform an +owner go/no-go, not a commitment. Ranges, not false precision. + +Closes the accepted review finding that no total effort estimate existed between the M0 proof and the +"definitive" ceiling, and that most milestones lacked an effort band. + +## How to read this +"Builder hours" assume 1–2 non-expert owners **directing AI coding agents**. Agents accelerate **code** +far more than they accelerate **balanced original content, art, audio, and legal-clean assets** — those +are called out separately because they are the real schedule risk. Wall-clock assumes part-time effort. + +## M0 — Headless Service Lab (**authorized; built**) +- **Proof question:** Can menu/price/staffing/capacity decisions create multiple understandable, viable + strategies with visible consequences that make players want to revise and run again? +- **Scope / non-goals:** see `../design/M0-PROTOTYPE-CONTRACT.md`. +- **Effort band (contract):** 25–40 focused builder hours. **Actual (this build):** the deterministic + core, CLI, harness, 74 tests, fixtures, and evidence came in within that band; the largest time sink + was **balance tuning** (throughput, comps, complexity, per-strategy design), exactly as expected. +- **Exit criteria:** determinism reproduced; invariants pass; no dominant strategy; poor strategies fail + legibly; **plus owner-run human playtests** for comprehension/replay/fun (owners' to gather). +- **Stop condition:** cap reached without an honest verdict, or the loop is competent-but-a-chore. + +## M1–M8 estimate (NOT authorized) + +Bands are rough and widen with distance. "Content" = recipes/scenarios/prose/balance authoring. + +| Milestone | Engineering (agent-assisted) | Content/design/balance | Art | Audio | UI/UX | Testing | Commercial/community | Wall-clock (1–2 p/t) | Confidence | Largest unknown | +|---|--:|--:|--:|--:|--:|--:|--:|---|:--:|---| +| **M1** Spatial gray-box | 60–120 h | 10–20 h | 0 (gray-box) | 0 | 20–40 h | 20–40 h | 0 | 1–2 months | Med | pathfinding/task-AI staying deterministic and not becoming a sink | +| **M2** Persistent restaurant (calendar, payroll, inventory, saves) | 100–180 h | 30–60 h | 0 | 0 | 30–50 h | 40–70 h | 0 | 2–4 months | Med | save-migration discipline; inventory without clerical overload | +| **M3** Identity & progression (concept, variants, chefs, critics, upgrades) → **first-commercial cut** | 100–180 h | 60–120 h | **begins** (see gate) | small | 40–70 h | 40–70 h | store page + wishlist starts | 3–5 months | Low–Med | whether identity/quality gets economic teeth via repeat visits/reviews | +| **M4** Delegation & 2nd location | 120–200 h | 40–80 h | some | some | 40–70 h | 40–70 h | ongoing | 3–5 months | Low | leverage-not-clicking; fantasy-continuity gate | +| **M5** Living city & competition | 100–180 h | 40–80 h | some | some | 30–60 h | 40–70 h | ongoing | 2–4 months | Low | competitor AI that is fair and not a sink | +| **M6** Campaign & scenarios | 80–150 h | 80–160 h (heavy authoring) | some | some | 40–70 h | 40–60 h | ongoing | 2–4 months | Low | scenario authoring is content-bound, not code-bound | +| **M7** Production content & presentation | 100–200 h | 150–300 h | **large** | **large** | 100–200 h | 60–100 h | demo + Next Fest | 4–8 months | Very low | art/audio sourcing feasibility (see `../risks/RISK-REGISTER.md`) | +| **M8** Release readiness | 80–160 h | 40–80 h | polish | polish | 40–80 h | 100–160 h | launch | 2–4 months | Very low | platform QA, save compatibility, exploit review | + +## The honest totals +- **Through M3 (first-commercial cut):** roughly **8–16 part-time months** of concentrated work for a + 1–2 person team using agents, with the art push deliberately gated to start at M3. +- **Full ceiling (through M8):** a **multi-year** effort. This is the number the original plan never stated. + It is the reason M4+ is a separate, evidence-gated commitment, not an assumed continuation. + +## What agents do and do NOT accelerate +- **Accelerated:** simulation code, tests, tooling, harnesses, refactors, docs. +- **Not much accelerated:** balanced original recipe/scenario design, art direction, audio, legal-clean + asset sourcing, and human playtesting. Budget these as their own line items (they dominate M6–M8). + +## Discipline +If any milestone's honest estimate exceeds its appetite, **cut scope while preserving the complete loop**, +write the deferral into `../design/DEFERRED-FEATURES.md`, and stop for an owner decision. Do not silently +extend. Re-estimate at each gate against reality, not against this table. diff --git a/docs/product/FANTASY-CONTINUITY.md b/docs/product/FANTASY-CONTINUITY.md new file mode 100644 index 0000000..73b1b3f --- /dev/null +++ b/docs/product/FANTASY-CONTINUITY.md @@ -0,0 +1,38 @@ +# Fantasy Continuity + +**Status:** Provisional resolution locked; the proof gate below is deferred (NOT built in M0). + +Closes the accepted review finding that the two fantasies "author one distinctive restaurant" and +"delegate and scale an empire" compete on the core verb, and the plan asserted the resolution rather than +gating it. + +## The tension +1. **Author** a distinctive restaurant (menu authorship is the player's signature verb). +2. **Delegate and scale** a restaurant empire (standardize, delegate, replicate — which hands the verb to + managers). + +Left unmanaged, expansion *retires* the most enjoyable decision instead of extending it. + +## Provisional resolution +> **The flagship restaurant remains the founder's creative laboratory and may always be operated at full +> detail. Additional restaurants can be standardized and delegated.** + +Expansion must not erase the game's strongest verb. It makes the founder-chef verb **scarce and protected** +rather than obsolete: the flagship stays hand-authored while chains run on the operating model you proved. + +## Player decisions the later game must offer +At M4+ (not now) the player should decide, per restaurant and per recipe: +- which restaurant remains personally authored, +- which recipes become standardized, +- which practices are delegated, +- which quality standards are mandatory, +- where creative freedom is allowed, +- which chefs receive autonomy. + +## Future proof gate (deferred; do not implement in M0) +> Does empire growth make the founder-chef fantasy feel **more valuable and scarce**, or does it merely +> remove the player from the most enjoyable decisions? + +This gate is analogous to M0's dominant-strategy test: it must be answered with evidence (playtests at the +delegation milestone), not asserted. Until then, treat the resolution above as an **assumption with a named +proof gate**, per the master plan's working rule. diff --git a/docs/product/FIRST-COMMERCIAL-CUT.md b/docs/product/FIRST-COMMERCIAL-CUT.md new file mode 100644 index 0000000..3e06bf9 --- /dev/null +++ b/docs/product/FIRST-COMMERCIAL-CUT.md @@ -0,0 +1,37 @@ +# First-Commercial Cut + +**Status:** Planning boundary (not authorization to build). Only M0 is authorized for implementation. + +Designating **everything through milestone M3** as the first potential commercial product gives the project +a real floor between "M0 proof" and the full "definitive simulation" ceiling — closing the accepted review +finding that the plan had no MVP cut line. + +## The first-commercial product (through M3) +One deeply-simulated restaurant that a stranger can understand, enjoy, fail at, and recover from: +- One restaurant, deep **menu strategy** (the spine). +- A functional **kitchen and front-of-house** simulation (M0's core, made spatial and persistent). +- **Persistent employees** with skills that develop. +- **Restaurant progression** and capability upgrades that change how work flows. +- **Reviews and critics**, and a restaurant **identity** that emerges from decisions. +- **Robust saving and recovery.** +- Enough **content for repeatable play**, a complete **onboarding path**, and a satisfying **medium-term goal**. + +## Explicitly EXCLUDED from the first-commercial commitment +Multiple simultaneous restaurants · full corporate layer · international expansion · franchising · +acquisitions · multiplayer · user-generated-content platform · full narrative campaign · large living +city · delivery empire · food trucks · celebrity-chef system. + +These are **post-release / v1.x candidates**, reconsidered only after the first-commercial product proves +demand. See `../design/DEFERRED-FEATURES.md` and the master plan §15/§16 for the ceiling and architectural +seams to keep open (without building). + +## Why M3, specifically +M3 is the first milestone at which the restaurant has an **identity the player can describe and care about** +(concept, signature dishes, chef careers, critics, progression) on top of a persistent, save-safe single +restaurant (M2). That is the smallest configuration that is genuinely a *game someone would buy*, not a +systems demo. M4+ (delegation, second location, living city, campaign) turn it into an empire game — real +value, but a separate, evidence-gated commitment. + +## Gate +M4 and beyond are **contingent** on the through-M3 product proving commercially and technically viable +(retention, reviews, sales, and a stable save format), not an assumed continuation. diff --git a/docs/product/GO-TO-MARKET.md b/docs/product/GO-TO-MARKET.md new file mode 100644 index 0000000..1559500 --- /dev/null +++ b/docs/product/GO-TO-MARKET.md @@ -0,0 +1,96 @@ +# Go-To-Market Sequence — "Mise" (working codename) + +**Purpose:** The provisional, gated sequence that takes the game from private testing to launch and expansion — each step with a measurable gate, and "we can be discovered" treated as an explicit proof gate. + +**Status:** DRAFT / PROVISIONAL. This is a plan, not an authorization. **Only M0 is authorized for implementation.** All wishlist targets and conversion figures are **[PROVISIONAL — research]** — replace with real data before relying on them. + +> Labeling: **[VERIFIED]** · **[ASSUMPTION]** · **[PROVISIONAL — research]** · **[OPEN QUESTION]** · **[OWNER DECISION]**. +> First commercial cut = **everything through M3**. M4+ deferred / not committed. + +--- + +## How to read the gates + +Each step has a **gate**: a measurable condition that must be true to advance. A gate that fails is a **stop-and-report**, not a "push through." Gates protect a two-person team from over-committing. + +--- + +## Step 1 — Private M0 / M1 testing + +- **Do:** playtest the M0 slice (and M1 as it lands) with a **sourced** set of testers. Playtester sourcing was flagged as an edge gap — treat "who tests this" as a real task, not an assumption. +- **Gate (measurable):** + - **≥ [PROVISIONAL — research] testers** complete a full service loop, **and** + - The **M0 core question passes**: menu/pricing/staffing/capacity produce *multiple understandable, viable strategies* with visible consequences, **and** + - The **fun bar clears**: a majority report they *wanted* to run another service (not merely understood it). This directly answers the accepted review finding that M0 tested comprehension/replay but never fun. +- **Failure = stop.** If it is legible but not fun, do not proceed to public marketing. + +## Step 2 — First visually-coherent shareable build + +- **Do:** produce the first build that *looks* like a game — coherent enough that a screenshot or 20-second clip reads to an outsider. Include **audio-as-legibility** (service rhythm, cues) as flagged in the review. +- **Gate:** an outside viewer, shown a clip cold, can **say what the game is** and **name one interesting decision** — with **no explanation from us**. **[ASSUMPTION]** this is the "shareable" threshold. + +## Step 3 — Steam "Coming Soon" page (wishlist campaign opens) + +- **Do:** stand up the Steam Coming-Soon page: capsule art, short pitch built on **"the menu is the strategy,"** first screenshots/clip. Trademark-clear the final name (never "Restaurant Empire"). Steam Direct fee **[VERIFIED] $100/app**. +- **Gate:** page live; wishlist accrual **measurable and non-flat** within the first weeks. Set an initial wishlist checkpoint **[PROVISIONAL — research]** — do not guess it here. + +## Step 4 — Dev updates focused on emergent restaurant stories + +- **Do:** post updates every **2–4 weeks** built around *emergent stories* ("this weird menu somehow worked," "the Friday rush that broke my staffing"). Determinism enables **reproducible / seed-shareable** moments. **[VERIFIED, directional]** regular posts re-engage wishlisters. +- **Gate:** each post produces measurable wishlist bump and/or engagement; cadence is actually sustainable for two people (an honest capacity check — if not, that is a finding). + +## Step 5 — Public demo + +- **Do:** ship a **short, immediately-engaging** demo of the M0/M1 slice. Exhibit the core loop fast, **no long tutorial**, **end on a wishlist CTA**. **[VERIFIED, directional]** demo-end CTA lifts conversion. +- **Gate:** + - Median session reaches a **visible-consequence moment** (a completed service with a legible result), **and** + - **Demo → wishlist conversion ≥ [PROVISIONAL — research]**, **and** + - Qualitative: players articulate *why they'd replan*. + +## Step 6 — Steam Next Fest + +- **Do:** enter Next Fest **once**, with the demo already privately validated. **Stream multiple sessions** during the week (authenticity > production value). **[VERIFIED, directional]** Next Fest is the strongest single organic wishlist event; streaming correlates with higher conversion. +- **Gate:** Next Fest produces a **wishlist step-change to ≥ [PROVISIONAL — research] total wishlists**, the threshold below which neither launch model is viable. + +## Step 7 — EA-vs-Premium decision gate + +- **Do:** decide the launch model using the real post-demo/Next-Fest data. Full brief: `docs/commercial/EARLY-ACCESS-DECISION.md`. +- **Gate (inputs required, all currently [OPEN QUESTION]):** wishlist level vs target; fun-bar sentiment; **honest two-person cadence commitment**; real cost/runway; Steam Deck/controller answer. +- **[OWNER DECISION]** — kept **de-locked pending platform answers.** Do not lock early. + +## Step 8 — Launch (through-M3 first commercial cut) + +- **Do:** launch at the chosen price ($19.99–$24.99 band, **[OWNER DECISION]**) via the chosen model. Steam Deck/controller status decided by then. +- **Gate:** + - Launch build clears an internal **"Very Positive"-worthy quality bar** in final playtests (review-score is the multiplier that touches every funnel term — see PRICE-AND-BREAK-EVEN §5), **and** + - Wishlist base ≥ the Step-6 threshold, **and** + - Refund/first-week sentiment monitored against **[PROVISIONAL — research]** thresholds. + +## Step 9 — Expansion decisions from real retention / reviews / sales + +- **Do:** decide any M4+ work **only** from real post-launch retention, reviews, and sales. M4+ (multiple restaurants, delegation, corporate layer, living-city competition, narrative campaign, franchising, acquisitions, international, multiplayer, UGC, delivery, food trucks, celebrity-chef) are **deferred / not committed** — candidates, not commitments. +- **Gate:** an expansion is greenlit only if retention/review/sales data supports it **and** owners authorize it. No pre-building. **[OWNER DECISION]** + +--- + +## The discoverability proof gate (named failure condition) + +**Claim under test:** *"We can be discovered."* This is **not** an assumption to grant — it is a **proof gate** spanning Steps 3–6. + +- **Proof:** the Coming-Soon → dev-updates → demo → Next Fest sequence produces a wishlist trajectory reaching **≥ [PROVISIONAL — research]** total wishlists by end of Next Fest, on **sustainable** effort. +- **Named failure condition:** *If, after a live Coming-Soon page, sustained dev updates, a public demo, and Steam Next Fest, wishlists remain below the Step-6 threshold, the discoverability thesis is **REFUTED**.* That triggers a **stop-and-reassess** — rethink positioning/marketing or the go/no-go — **not** a march to launch on hope. + +This is the single most likely thesis-killer for a two-person team, so it gets its own gate rather than being buried in a launch checklist. + +--- + +## Cross-references + +- Audience, distinctiveness, risks, break-even framework: `docs/product/COMMERCIAL-HYPOTHESIS.md` +- Comparables and lineage: `docs/commercial/COMPARABLES.md` +- Price band & break-even math: `docs/commercial/PRICE-AND-BREAK-EVEN-HYPOTHESIS.md` +- Launch-model decision: `docs/commercial/EARLY-ACCESS-DECISION.md` + +--- + +**Sources:** [Next Fest data — Second Stage](https://secondstage.io/2026/04/steam-next-fest-the-data-behind-what-actually-drives-wishlists) · [Demo optimization — StraySpark](https://www.strayspark.studio/blog/steam-next-fest-demo-optimization-wishlists) · [Wishlist-to-buyer conversion — alinea analytics](https://alineaanalytics.substack.com/p/wishlist-to-buyer-conversions-for) · [PlateUp! on Steam](https://store.steampowered.com/app/1599600/PlateUp/) · [Dave the Diver 4M — Game World Observer](https://gameworldobserver.com/2024/06/27/dave-the-diver-4-million-copies-sold-anniversary) diff --git a/docs/product/PRODUCT-VISION.md b/docs/product/PRODUCT-VISION.md new file mode 100644 index 0000000..d0dcab8 --- /dev/null +++ b/docs/product/PRODUCT-VISION.md @@ -0,0 +1,151 @@ +# PRODUCT-VISION + +**Purpose:** The concise north-star for the Restaurant successor (working codename "Mise"). What the game *is*, what it is *not*, and the standard a finished build must meet. + +**Status:** Pre-production planning. This document is the product's north-star, not a build authorization. **Only M0 is authorized for implementation right now.** Everything past M0 in this document is hypothesis and direction. + +**Codename:** "Mise" — working only, NOT final. Never brand the product "Restaurant Empire"; that title names our *lineage*, not our product. + +Related source-of-truth docs (relative links): +- [MASTER-PLAN.md](../MASTER-PLAN.md) — milestones M0–M3+, scope, effort, sequencing +- [FIRST-COMMERCIAL-CUT.md](../commercial/FIRST-COMMERCIAL-CUT.md) — the M3 release definition and go-to-market +- [FANTASY-CONTINUITY.md](./FANTASY-CONTINUITY.md) — how the core fantasy survives from M0 to release +- [DEFERRED-FEATURES.md](../design/DEFERRED-FEATURES.md) — the written backlog of everything deliberately not in the cut + +--- + +## 1. The core fantasy (verbatim — LOCKED) + +> **"I build one distinctive restaurant whose menu, people, layout, and service work as a coherent machine, and then turn that hard-won operating model into a culinary empire."** + +Read that sentence carefully, because it encodes the whole product in order of priority: + +1. **One** restaurant first. Depth before breadth. The empire is *earned*, not handed out. +2. **Distinctive.** A place with an identity, not a generic node in a spreadsheet. +3. **A coherent machine.** Menu, people, layout, and service are *interlocking*, not separate menus. +4. **Hard-won operating model.** The player learns *how their restaurant works* by running it. +5. **Then** an empire — as the reward for having built something that actually works. + +The near-term product (M0 through the first commercial cut) is almost entirely sentence-clauses 1–4. The "empire" is the promise on the horizon, not the thing we build first. + +--- + +## 2. The design spine + +> **The menu is the strategy.** + +Every restaurant-management game has a menu screen. In most of them the menu is decoration — a list of dishes with a price and a profit number. In this game the menu is the **single highest-leverage decision the player makes**, and nearly every other system is downstream of it. + +When you change the menu, you change the restaurant. A menu is not a list of food. A menu *determines*: + +| A menu determines… | …because | +| --- | --- | +| **Demand** | which guests want to eat here, and how many | +| **Expectations** | what "good" means at this restaurant, and what disappoints | +| **Ingredient cost** | the raw inputs each dish consumes | +| **Station load** | how work distributes across grill, sauté, cold, pastry, pass | +| **Prep complexity** | how much mise en place a service requires before doors open | +| **Chef needs** | the skill mix the kitchen must have to execute it | +| **Service speed** | how fast tickets clear, and where they jam | +| **Waste** | what gets thrown away when demand and prep don't match | +| **Pricing power** | how much the guest will pay before value breaks | +| **Identity** | what this restaurant *is*, to a guest and to the owner | +| **Profitability** | whether all of the above nets out to a business that survives | + +A player who understands that list understands the game. A design change that breaks that chain of consequence is a design change that breaks the spine. + +--- + +## 3. The career arc + +The fantasy is a ladder. You start as the person in the kitchen and end as the person whose name is on the group. Five rungs: + +1. **Founder-Chef** — one restaurant, hands on the menu and the pass. You *are* the operation. +2. **Operator** — the restaurant runs as a machine you designed; you tune it rather than push every ticket. +3. **Restaurateur** — a second concept and a portfolio; the operating model becomes transferable. +4. **Group Leader** — multiple venues, delegated management, a corporate layer. +5. **Legacy Architect** — the empire runs itself; you shape identity, culture, and succession. + +**Near-term reality:** only **Founder-Chef** and **Operator** are in scope for M0 through the first commercial cut. Rungs 3–5 are the *direction* the design must not foreclose, but they are **not committed and not being built now** (see [DEFERRED-FEATURES.md](../design/DEFERRED-FEATURES.md)). We ship a great single restaurant before we ship an empire. + +--- + +## 4. The M0 product question + +Everything M0 does exists to answer one question: + +> **"Can menu, pricing, staffing, and capacity decisions create multiple understandable and viable restaurant strategies, with visible consequences that make players want to revise their plan and run another service?"** + +Note the four load-bearing words: +- **Multiple** — there is more than one right answer (a tight bistro *and* a high-volume diner can both work). +- **Understandable** — the player can *explain* why an outcome happened; it is not noise. +- **Viable** — the strategies actually survive as businesses; they are not traps. +- **Revise / run another** — the loop is *pullable*; a service ending makes you want to change one thing and go again. + +M0 is a **headless service lab**: a deterministic simulation core with no graphics, run and inspected through instrumentation and reports. It is not a demo. It exists to prove the spine is real before a single pixel is drawn. + +**[OWNER DECISION]** M0 must additionally demonstrate an early signal of *fun*, not only comprehension and replayability. A prior review found the M0 bar tested "can the player understand it?" and "will they run it again?" but never "is it enjoyable?" — the fun signal is now an explicit M0 acceptance concern. See [MASTER-PLAN.md](../MASTER-PLAN.md) for the current M0 exit bar. + +--- + +## 5. What this game is NOT + +Naming the boundary is a design decision, not an omission. This game is **not**: + +- **Not a clicker or an idle game.** Decisions have to be considered, and consequences have to be legible. Optimal play is not "buy the next upgrade." +- **Not a twitch/action cooking game.** It is not PlateUp!, Cook Serve Delicious, or the arcade half of Dave the Diver. The player is a *restaurateur*, not a line cook under a timer. (Those games are respected lineage, not the target.) +- **Not a city-builder or a logistics puzzle first.** Supply chains, pathfinding, and city simulation are secondary at most, and mostly deferred. +- **Not a story/character romance game.** Staff are a *team you build*, not a dating roster or a narrative-first cast. +- **Not a generic tycoon reskin.** "Same tycoon loop, but restaurants" is exactly the game we are not making. The menu-as-strategy spine is the differentiator. +- **Not a mobile / free-to-play / live-service product.** It is single-player, desktop-first, premium, and finished-at-release. No storefronts, no energy timers, no season pass. +- **Not an empire-management game *first*.** The empire is the late-game reward. A game that opens with spreadsheets of ten restaurants has skipped the entire fantasy. + +--- + +## 6. The final product standard + +We are done when the player, unprompted, can truthfully say each of these: + +- **"I built this restaurant on purpose."** The identity was chosen, not defaulted into. +- **"I understand why tonight succeeded or failed."** The outcome is explicable, not random. +- **"My menu changes how the kitchen works."** The spine is felt, not asserted. +- **"My staff became a team."** People have continuity and grow into a working unit. +- **"This place has an identity."** It is a *specific* restaurant, distinguishable from any other. +- **"The disaster was my fault — but I know how to recover."** Failure is fair, readable, and survivable. +- **"It created a story I want to tell."** The run generated a narrative the player carries out of the game. + +If a build passes its tests but a player cannot honestly say those things, the build is not done. That is the bar the whole project is measured against. + +--- + +## 7. Team and market reality (context for every decision) + +- **Team:** Howard and Aaron — **one or two non-expert creators directing AI coding agents.** Every scope, effort, and go-to-market decision must be sized for that team, not a funded studio. A feature we cannot realistically finish and support is a feature we do not start. +- **Positioning:** single-player, **desktop-first**, **premium** (paid, finished-at-release), spiritual successor to Restaurant Empire (2003/2004). +- **Tech:** a deterministic, engine-agnostic simulation core in **C#/.NET**; presentation engine (Godot is the candidate) chosen later. The core must run headless and reproducibly. [ASSUMPTION — confirm at engine-selection gate.] +- **Go-to-market lineage (grounded):** the genre-default successful path in 2026 is a Steam **"Coming Soon"** page + wishlist campaign → a public **demo** → **Steam Next Fest** → **Early Access**. Next Fest is the single largest free marketing beat most indie devs get, and store-page conversion (not demo play) drives the majority of wishlists — reported figures suggest the large majority of Next Fest wishlists come from browsers who never launch the demo. [VERIFIED — see sources.] Steam Deck verification and controller support materially affect sales for this genre. [ASSUMPTION — confirm.] +- **Pricing anchor:** comparable premium management sims cluster around the low-$20s to mid-$30s (e.g., Big Ambitions ~\$22.99; Two Point Hospital editions ~\$12–\$35). Treat our own price as **[OWNER DECISION]** to be set against the first-commercial-cut content, not fixed here. [VERIFIED comparables — see sources; our price is not set.] + +**[OPEN QUESTION]** Which Next Fest and which Early Access window do we target? This depends on when the first commercial cut is credibly demo-able and is owed a decision in [FIRST-COMMERCIAL-CUT.md](../commercial/FIRST-COMMERCIAL-CUT.md). + +--- + +## 8. Labeling key + +Throughout the docs cluster: +- **[VERIFIED]** — grounded in cited evidence. +- **[ASSUMPTION]** — a working belief we are proceeding on; confirm before it becomes load-bearing. +- **[OPEN QUESTION]** — unresolved; needs research or a decision. +- **[OWNER DECISION]** — reserved for Howard and Aaron; do not resolve unilaterally. + +Never fabricate a precise sales, wishlist, or revenue number. Rules of thumb are allowed *if labeled as such*. + +--- + +**Sources (market/go-to-market grounding):** +- [Steam Next Fest 2026 & beyond — GamesRadar+](https://www.gamesradar.com/games/steam-next-fest-guide/) +- [Steam Next Fest Complete Prep Guide — presskit.gg](https://presskit.gg/field-guides/steam-next-fest-guide) +- [Steam Early Access Strategy (2026) — Steam Page Analyzer](https://www.steampageanalyzer.com/blog/steam-early-access-strategy) +- [Big Ambitions on Steam](https://store.steampowered.com/app/1331550/Big_Ambitions/) +- [Two Point Hospital on Steam](https://store.steampowered.com/app/535930/Two_Point_Hospital/) +- [Deep dive: how Big Ambitions hit it big on Steam — GameDiscoverCo](https://newsletter.gamediscover.co/p/deep-dive-how-big-ambitions-hit-it) diff --git a/docs/risks/HUMAN-RISK-PLAN.md b/docs/risks/HUMAN-RISK-PLAN.md new file mode 100644 index 0000000..cc39b0d --- /dev/null +++ b/docs/risks/HUMAN-RISK-PLAN.md @@ -0,0 +1,161 @@ +# Human Risk Plan — Sustaining a 1–2 Person Multi-Year Build ("Mise") + +*Purpose: the operating discipline that keeps two non-expert creators (Howard and Aaron), directing AI coding agents, still building — and still willing to build — years from now. The most likely cause of death for this project is a person, not a subsystem. This plan defends the people.* + +**Status:** Living plan. Paired with the human/commercial rows in `RISK-REGISTER.md` (H1–H5, C1–C5). Reviewed at every quarterly gate. **Only M0 is authorized for implementation** — everything here about M1+ is a durability practice, not a build order. + +--- + +## Why this document exists + +An accepted review finding was blunt: the original plan had **zero team/human/commercial risks**, and its scope was **unrealistic for a two-person team** with no total effort estimate and no MVP cut line. A funded studio survives a burned-out founder by hiring around them. We cannot. If one of two people quits, loses interest, runs out of hours, or the two of us deadlock and stop talking, the project ends — no matter how clean the determinism harness is. + +So the discipline below treats **energy, agreement, time, and motivation as project resources** to be budgeted and protected as deliberately as we budget engineering effort. + +--- + +## 1. Milestone timeboxes with hard stops + +Every milestone gets a **timebox** — a calendar budget agreed before work starts — and a **hard stop** at the end of it. + +- The timebox is a decision, not a deadline to beat. Its job is to force a scope conversation, not to induce a crunch. +- At the hard stop we **cut scope, not the stop**. If M0 isn't done when its timebox ends, we ship less of M0 — we do not silently extend and burn a weekend to "just finish." +- Overruns are a *signal*, tracked against the coarse total-effort estimate (see §7). An overrun >30% is an early signal for funding/time exhaustion (Register H3). +- Sequence hard-frozen by the contract: **M0 → M1 → M2 → M3 = first commercial cut.** M4+ (multiple restaurants, delegation, corporate layer, living-city competition, campaign, franchising, acquisitions, international, multiplayer, UGC, delivery empire, food trucks, celebrity-chef) are **deferred, post-release/v1.x candidates only** and are not built now. **Only M0 is authorized today.** + +--- + +## 2. Scheduled breaks (protected, not optional) + +Breaks are on the calendar *before* the work is, and they are the first thing defended, not the first thing cut. + +- **A break follows every milestone gate.** Shipping a gate earns a real, work-free pause — not "a day off then straight into M1." +- **Breaks are protected.** Skipping a scheduled break, or cutting it short, is an explicit **burnout early signal** (Register H1) and gets raised at the next check-in. +- Between gates, a sustainable weekly cadence beats sprints. **Three consecutive project weekends by one owner** is a signal, not a badge. +- "I'll rest after launch" is a failure mode for a multi-year build — there is no after-launch for years. Rest is scheduled *through* the build. + +--- + +## 3. Shippable / playable at every gate + +Every gate must end with something that **runs and can be played or shown** — not a branch of half-wired infrastructure. + +- The definition of done for each gate includes a **playable/showable artifact**: a build a friendly outsider could sit down with, even if narrow. +- This does double duty: it de-risks the product (we always have a real thing) *and* protects motivation (effort visibly becomes a game, not a backlog). See §8. +- Infrastructure-only gates are allowed but **must be immediately followed by a visible-payoff gate** (see §8). We never stack two invisible gates. +- Saves, determinism, and the ability to *play the current build* are treated as always-green: a gate that leaves the build unplayable is not done. + +--- + +## 4. Visible scope cuts + +When we cut, we cut **out loud and in writing**. A silent cut is a gap nobody can find later (per `CLAUDE.md`). + +- Every de-scope is recorded: what was cut, why, and where it went (deferred to a named later milestone, or cancelled outright). +- Cutting is celebrated, not mourned. In a two-person build, **the ability to cut is the primary survival skill.** +- Cuts feed the register: content-explosion (P5), over-simulation (P4), and scope-creep (P9) mitigations all resolve through *visible* cuts. +- The deferred M4+ list is itself the largest standing scope cut. It stays cut until the first commercial cut has shipped and been reviewed. + +--- + +## 5. No guilt-driven scope expansion + +Scope grows only from a decision, never from guilt, comparison, or "it's cheap to add because the AI can do it." + +- **Guilt is not a spec.** "We should probably also…", "a real game would have…", "since we're already in there…" are banned as reasons to add scope. New scope requires an explicit decision against the contract and the cut line. +- Because AI agents make adding code *cheap*, this rule is load-bearing: cheap-to-add is not the same as cheap-to-own. Every added system must be one an owner can explain and review (Register P9). If neither owner can explain it, it doesn't ship. +- Comparison to bigger, funded games is not a scope input. We are building *one distinctive restaurant done deeply*, not feature-parity with a studio. + +--- + +## 6. Named product-owner-per-domain + founder-deadlock tiebreak + +Two founders with equal say and no tiebreak is a deadlock generator (Register H2). We resolve it structurally, and we resolve it *before* the first hard fight. + +**Domains** — each domain has **one named owner with final say in that domain.** The other founder advises, argues, and is heard, but does not hold a veto inside the other's domain. + +| Domain | Proposed owner | Notes | +|--------|----------------|-------| +| Design / core fantasy / "the menu is the strategy" / player-facing feel | `[OWNER DECISION]` (proposed: Howard) | Product-fun, legibility, content identity. | +| Engineering / determinism / saves / architecture / agent direction | `[OWNER DECISION]` (proposed: Aaron) | Technical soundness, build/release, scope-vs-effort reality. | +| Commercial / go-to-market / store page / pricing / wishlist | `[OWNER DECISION]` (proposed: Howard) | Steam page, Next Fest, EA plan, pricing (see `docs/commercial/`). | + +> The domain owners above are **proposed defaults, not locked.** The owners confirm or reassign them at the first governance review. + +**Tiebreak procedure for founder deadlock** — when the founders disagree and cannot converge: + +1. **Locate the domain.** The decision belongs to whichever domain it most affects. **That domain's named owner has final design authority for that decision.** The disagreement and the ruling are recorded out loud (per `CLAUDE.md`), so the choice is findable later. +2. **Cross-domain / genuinely ambiguous decisions** (it spans design *and* engineering *and* commercial) escalate to a single, pre-agreed **project tiebreaker**: + + > ### [OWNER DECISION] — Who has final design authority when the owners disagree? + > + > This must be answered *now, while calm*, not during the fight. Pick one and write the name in: + > + > - **Option A — Single project tiebreaker.** One named founder (e.g. Howard, as design/product lead for a game whose spine is "the menu is the strategy") holds the final call on any cross-domain deadlock. Fast, unambiguous; concentrates authority. + > - **Option B — Domain-owner-wins, always.** There is no project-level tiebreaker; every decision is forced into a domain and the domain owner rules. Requires that domains are drawn cleanly enough that nothing is truly cross-domain. + > - **Option C — Cool-off then coin.** 48-hour cool-off; if still deadlocked, the contested feature is **deferred/cut** rather than forced (deadlock defaults to *less* scope, which is usually the safe direction for a two-person team). + > + > **Chosen rule: ______________________ Decided by: Howard & Aaron on: __________** + +3. **Deadlock defaults to defer.** Until the rule above is chosen and written, any deadlock that blocks work for a full gate resolves by **deferring the contested feature** and shipping without it (Register H2 trigger). A shipped smaller thing beats a stalled bigger one. +4. **Chronic deadlock is a stop-level signal.** If deadlocks recur across multiple reviews despite the procedure, that is a governance failure — we pause and renegotiate roles rather than grind against each other. + +--- + +## 7. Total effort estimate & the MVP cut line + +The original plan had **no total effort estimate and no MVP cut line** — both are now required standing artifacts. + +- Maintain a **coarse total-effort estimate** for M0 → M3 (the first commercial cut), in owner-hours, updated each gate with actuals. It is allowed to be rough; it is not allowed to be absent. +- The estimate is checked against each owner's *actually available* weekly hours. If real life reduces those hours, we **re-plan the calendar, not the sleep schedule.** +- The **MVP cut line is fixed: everything through M3.** Anything past M3 is deferred by default. The cut line is what the effort estimate is measured against. +- Effort overrun >30% with no cut, or available hours dropping for a month with no re-plan, are the funding/time-exhaustion signals (Register H3). + +--- + +## 8. Motivation is protected by visible player-facing proofs + +**Motivation is defended with things you can play, not only with infrastructure that works.** This is a rule, not a nicety (Register H4). + +- Every gate must produce a **player-facing proof**: something an owner (or a friendly outsider) can *play for fun*, not just test. Two consecutive gates with no player-facing proof triggers a rewrite of the next gate's definition of done (Register H4 trigger). +- **Alternate the rhythm:** a hard-systems/infrastructure gate is always followed by a visible-payoff gate. We never let the project become months of plumbing with no game to look at. +- Owners should periodically **play their own build for the fun of it.** If neither owner has done so in a month, that's a motivation early signal. +- Show the build to a friendly outsider on a regular cadence. Watching someone enjoy (or not enjoy) it is worth more motivation than any green test suite. It also doubles as the fun/desire check the M0 bar was missing (Register C2). +- "We'll make it fun later" is a banned phrase in planning. Fun is proven continuously or it isn't real. + +--- + +## 9. Quarterly continue / rewrite / stop review + +Every quarter, the owners hold an explicit **continue / rewrite / stop** review. Three honest outcomes are all legitimate — including stop. + +**Agenda:** + +1. **Walk `RISK-REGISTER.md`.** For each row, mark the early signal *not observed / watch / triggered.* Any triggered row gets its pre-agreed action executed — no fresh debate. +2. **Human check first.** Burnout (H1), deadlock (H2), time/funding (H3), motivation (H4), bus-factor (H5). Ask out loud: *Are we still enjoying this? Are we still rested? Are we still agreeing? Do we still have the hours?* +3. **Effort reality (§7).** Actuals vs. estimate vs. available hours. Re-plan if reality moved. +4. **Player-facing proof (§8).** What can we actually play this quarter that we couldn't last quarter? If nothing — that's a finding. +5. **Verdict, written down:** + - **Continue** — signals green, keep the plan. + - **Rewrite** — a signal triggered; change scope, sequence, roles, or the plan. Cut visibly (§4). + - **Stop** — the honest answer is that the project should pause or end. **Choosing to stop a project that is hurting its makers is a success of this plan, not a failure.** A clean stop with the makers intact beats a death march. + +The review is short, honest, and outcome-first. Its output is a dated decision recorded alongside the register. + +--- + +## 10. The short version (pin this) + +- **Timebox every milestone; cut scope, never the hard stop.** +- **Breaks are scheduled and protected. Skipping one is a red flag.** +- **Every gate ships something playable. Two invisible gates in a row is not allowed.** +- **Cut out loud, in writing. Never expand scope out of guilt or because the AI made it cheap.** +- **Each domain has one owner with final say. The cross-domain tiebreak rule is [OWNER DECISION] — answer it while calm.** +- **Keep a rough total-effort estimate against a fixed MVP cut line (through M3).** +- **Protect motivation with things you can play, not just infrastructure that works.** +- **Review continue/rewrite/stop every quarter. Stopping intact is a win.** +- **Only M0 is authorized to build. Everything M4+ stays deferred until the first commercial cut ships.** + +--- + +*Related: `RISK-REGISTER.md` (rows H1–H5 human, C1–C5 commercial), `docs/commercial/` (go-to-market, wishlist, pricing), and the build contract as source of truth per `CLAUDE.md`.* diff --git a/docs/risks/RISK-REGISTER.md b/docs/risks/RISK-REGISTER.md new file mode 100644 index 0000000..9579e9a --- /dev/null +++ b/docs/risks/RISK-REGISTER.md @@ -0,0 +1,77 @@ +# Risk Register — Project "Mise" + +*Purpose: the single, ranked list of what can kill or derail this project — product, engineering, human, and commercial — each with a falsifiable early signal, an owner, a mitigation, and a pre-agreed trigger for rewrite/defer/cancel.* + +**Status:** Living document. Reviewed every quarterly continue/rewrite/stop gate (see `HUMAN-RISK-PLAN.md`). Only **M0 is authorized for implementation**; every mitigation below that references M1+ work is a *hypothesis to be scheduled later, not a license to build now.* + +--- + +## How to read this register + +- **Probability / Impact** are coarse (Low / Med / High) and deliberately not numeric. They rank attention, not actuarial truth. +- **Early signal** is written to be *falsifiable*: a specific observable that either is or is not happening. If you cannot check it, it is not a signal — rewrite it. +- **Owner** is a single named person accountable for watching the signal, not necessarily the one who fixes it. (Where an owner is unresolved it is flagged `[OWNER DECISION]`.) +- **Trigger** is the pre-committed condition under which we stop debating and act (rewrite the plan, defer the feature, or cancel it). Deciding the trigger *now*, while calm, is the entire point. + +Owners referenced: **Howard**, **Aaron**. Team reality: one or two non-expert creators directing AI coding agents. Every mitigation must be executable by that team, not a funded studio. + +Labels used below: `[VERIFIED]` grounded evidence · `[ASSUMPTION]` reasoned but unconfirmed · `[OPEN QUESTION]` unresolved · `[OWNER DECISION]` needs an owner to choose. + +--- + +## A. Product & design risks (the original plan tracked these) + +| # | Risk | Prob | Impact | Early signal (falsifiable) | Owner | Mitigation | Trigger for rewrite / defer / cancel | +|---|------|------|--------|----------------------------|-------|------------|--------------------------------------| +| P1 | **Core loop collapses into spreadsheet optimization** — "the menu is the strategy" degrades into solving one arithmetic problem; running a service adds nothing a calculator wouldn't. | Med | High | In M0 playtests, ≥50% of testers stop opening the live-service view and play entirely from the menu/pricing screen; or verbalize "I already know the answer, I'm just clicking next." | Howard | Ensure service outcomes carry information the planning screen cannot fully predict (variance, staff/customer behavior, capacity edge cases); make revising-after-a-service the fun. | If after two M0 iterations testers still optimize once and coast, **rewrite** the core-loop hypothesis before any M1 work. | +| P2 | **Dominant strategy** — one menu/pricing/staffing build wins in all conditions, flattening replay. | Med | High | In balance sweeps, a single build is top-quartile profit across ≥80% of seeded scenarios; or testers converge on the same build unprompted. | Aaron | Multiple viable archetypes as a design requirement; automated seeded balance sweeps flag runaway builds; tuning lives in `TUNING`, not scattered constants. | If ≥3 tuning passes cannot break a dominant build, **rewrite** the affected subsystem (e.g. pricing/demand curve). | +| P3 | **Pathfinding / agent-movement becomes a time sink** — floor navigation and service routing eat engineering months the design never asked for. | Med | Med | Cumulative time on movement/routing exceeds its M0 timebox by >50%; or a movement bug is the top blocker two gates running. | Aaron | Keep floor simulation at the *abstraction level the design needs* (capacity, throughput, seating pressure) rather than full physical pathfinding; treat literal pathfinding as deferred until a gate proves it's required. | If routing fidelity is consuming a gate with no design payoff, **defer** literal pathfinding and ship the abstract model. | +| P4 | **Over-simulation** — simulating detail (individual ingredients, per-dish physics, deep chemistry) that players never perceive as strategy. | High | Med | A simulated subsystem cannot be tied to a decision a tester actually makes; adding it does not change any playtest verdict. | Howard | Every simulated quantity must map to a player-legible decision (per `CLAUDE.md` non-goals and the build contract). Nothing gets simulated "for realism." | If a subsystem has no decision attached after one iteration, **cancel** it and record the cut. | +| P5 | **Content explosion** — the amount of dishes/ingredients/events/staff needed for "enough for repeat play" balloons past what two people + AI can author and balance. | High | High | Content-authoring backlog to reach the M3 "enough content" bar is estimated at >2× the timebox; or each new content item requires bespoke balancing. | Howard | Data-driven content with shared systems, not hand-tuned one-offs; define the *minimum* content set for the first commercial cut and hold the line; visible scope cuts (see `HUMAN-RISK-PLAN.md`). | If content needed for M3 exceeds 2× budget after de-scoping, **defer** breadth and ship a smaller, deeper content set. | +| P6 | **Save corruption / migration failure** — a premium single-player game that eats multi-hour saves is dead on arrival. | Med | High | Any test loses or corrupts a save across a version bump; round-trip save→load→save is not byte-stable in the determinism harness. | Aaron | Versioned save format with explicit migration tests; save round-trip is part of the determinism/regression suite from M0. | If a save-format change cannot be migrated safely, **defer** the change until a migration path exists; never ship a save-breaking build to players. | +| P7 | **Determinism failure** — the "same inputs → same outputs" guarantee breaks, invalidating tests, replays, and balance sweeps. | Med | High | The determinism harness reports a divergence; a seeded run is not reproducible across machines/runs. `Math.random`-equivalent nondeterminism appears in the core. | Aaron | Pure `(state, actions) => state` core, seeded RNG only, determinism regression in CI. (Numeric determinism strategy handled in the architecture docs.) | If nondeterminism cannot be isolated, **stop feature work** and fix the core before proceeding — a nondeterministic core cannot be balanced or tested. | +| P8 | **UI hides the balance** — the simulation is fair and legible but the presentation obscures cause and effect, so players can't see *why* a service went the way it did. | Med | High | In playtests, testers cannot correctly explain the cause of a good/bad service result after seeing the UI; ≥50% misattribute the outcome. | Howard | Design for *legibility first* (including audio-as-legibility and clear per-service feedback); presentation-layer changes are validated against comprehension, not aesthetics. Only M0 legibility is authorized now. | If two UI iterations fail the comprehension check, **rewrite** the feedback presentation before adding features. | +| P9 | **AI-agent scope creep** — because AI coding agents make it *cheap to add code*, the project accretes systems faster than two humans can understand, test, or maintain. | High | High | A subsystem exists that neither owner can explain or has personally reviewed; the diff volume per gate outpaces the owners' review capacity; "the agent added it" appears in any post-mortem. | Aaron | The build contract is the source of truth; agents implement it *as written* and stop-and-report gaps (per `CLAUDE.md`) rather than inventing scope. Human review is a hard gate on every merge. Owners must be able to explain every shipped system. | If shipped code exceeds owner comprehension/review capacity for a full gate, **stop new agent work** until the owners have re-read and pruned it. | + +--- + +## B. Human risks (the original plan omitted these — this is the whole point) + +> A one-or-two-person multi-year build is far more likely to end because a *person* ran out of energy, time, money, or agreement than because a subsystem was hard. These rows get first-class treatment and detailed, falsifiable signals. The narrative counterpart is `HUMAN-RISK-PLAN.md`. + +| # | Risk | Prob | Impact | Early signal (falsifiable) | Owner | Mitigation | Trigger for rewrite / defer / cancel | +|---|------|------|--------|----------------------------|-------|------------|--------------------------------------| +| H1 | **Creator burnout** — sustained overwork or joylessness pushes a founder from "tired" to "done," and a two-person team cannot absorb one person leaving. | High | High | **Falsifiable signals, watched at each gate:** (a) an owner works ≥3 consecutive weekends on the project; (b) a scheduled break is skipped or cut short two cycles running; (c) commit/activity cadence for an owner drops >50% for ≥2 weeks with no planned break; (d) an owner reports dread rather than anticipation before a work session in the quarterly check-in; (e) sleep/health explicitly traded for a deadline. | Howard | Milestone timeboxes with hard stops; **scheduled breaks that are protected, not optional**; "shippable/playable at every gate" so effort always produces something real; no guilt-driven scope expansion; the quarterly review explicitly asks "are you still enjoying this?" See `HUMAN-RISK-PLAN.md`. | If two consecutive gates show burnout signals for the same owner, **defer all non-essential scope**, take a hard break, and re-plan around a sustainable pace. If burnout persists after a full break, **stop** rather than grind. | +| H2 | **Founder disagreement / deadlock** — Howard and Aaron reach an unresolved design or direction split with no tiebreak, and the project stalls or fractures. | Med | High | (a) A design decision remains open across two gates because the owners disagree; (b) the same argument recurs in ≥2 reviews without resolution; (c) work stops or forks while the disagreement is live; (d) either owner privately builds in a direction the other rejected. | `[OWNER DECISION]` — **who has final design authority when the owners disagree?** See the named product-owner-per-domain + tiebreak procedure in `HUMAN-RISK-PLAN.md`. | A **named product owner per domain** with final say in that domain, a written tiebreak procedure, and disagreements recorded out loud (per `CLAUDE.md`). Decide the tiebreak rule *before* the first hard fight, not during it. | If a deadlock survives the tiebreak procedure and blocks work for a full gate, **defer** the contested feature entirely and ship without it; if deadlocks are chronic, treat it as a **stop**-level governance failure and renegotiate roles. | +| H3 | **Funding / time exhaustion** — the money and, more importantly, the *unpaid hours* run out before the first commercial cut ships; there is no total effort estimate to plan against. | High | High | (a) Actual hours-to-date exceed the running effort estimate for M0→M3 by >30% with no scope cut; (b) an owner's available weekly hours drop for ≥1 month (job/life change) with no re-plan; (c) any out-of-pocket spend (assets, tools, Steam fee) has no budget line; (d) the projected calendar to first commercial cut exceeds what the owners agreed they can sustain. | Aaron | Maintain a coarse **total effort estimate** and burn-down per gate; hold a hard MVP cut line (everything through M3); keep out-of-pocket spend minimal and listed; the quarterly review re-checks "can we still afford the time this will take?" | If the effort estimate to the first commercial cut exceeds the owners' sustainable time budget after de-scoping, **rewrite** the scope down to what fits; if it still doesn't fit, **defer** the release target or **stop**. | +| H4 | **Motivation loss** — not burnout (energy) but *interest*: the work drifts into infrastructure with no visible game, and the owners stop caring before players ever see it. | Med | High | (a) ≥2 consecutive gates ship only infrastructure/plumbing with **no new player-facing proof** anyone can look at and play; (b) neither owner has *played their own build for fun* (not testing) in a month; (c) enthusiasm language in check-ins turns to obligation language; (d) "we'll make it fun later" appears in planning. | Howard | **Motivation is protected by visible player-facing proofs, not only infrastructure work** — every gate must produce something playable/showable; alternate hard-systems gates with visible-payoff gates; demo the build to a friendly outsider periodically. See `HUMAN-RISK-PLAN.md`. | If two gates pass with no player-facing proof, **rewrite** the next gate's definition of done to require a playable/showable slice before any further infrastructure. | +| H5 | **Solo-bus-factor / life event** — one owner is unavailable (illness, job, family) and the other cannot carry the whole project. | Med | High | Any period where only one owner is active for >1 month; critical knowledge (build, deploy, save format) lives in exactly one head. | Aaron | Keep the build reproducible and documented so either owner can run/ship it; the contract + docs are the shared brain, not tribal knowledge; deliberately cross-share the "how to release" runbook. | If the project depends on knowledge only one unavailable owner has, **defer** dependent work until it's documented; if one owner exits, re-scope for a genuine solo build or **stop**. | + +--- + +## C. Commercial risks (also omitted originally — a finished game nobody buys is still a failure) + +> Accepted review finding: the original plan had **no go-to-market, wishlist, pricing, or audience-size plan**. These rows exist to make commercial reality a tracked risk, not a launch-day surprise. See `docs/commercial/` for the go-to-market work these reference. + +| # | Risk | Prob | Impact | Early signal (falsifiable) | Owner | Mitigation | Trigger for rewrite / defer / cancel | +|---|------|------|--------|----------------------------|-------|------------|--------------------------------------| +| C1 | **Commercial indifference — no audience / poor discoverability** — the game is competent but nobody finds it; wishlists never accumulate; the Steam algorithm never surfaces it. | High | High | (a) A Steam "Coming Soon" page is live but wishlist velocity is flat/near-zero over a sustained period `[ASSUMPTION — confirm target with a real page]`; (b) posts/devlogs get near-zero engagement across ≥3 attempts; (c) no content creator or community picks up the demo at Next Fest. | Howard | Stand up a Steam **Coming Soon page + wishlist campaign early**; ship a **public demo** and enter **Steam Next Fest**; treat **Early Access** as the genre-default path. `[VERIFIED]` Next Fest June 2026 ran 15–22 June; October 2026 runs Oct 19–26; demos released 2–4 weeks early and creator/press outreach starting ~8 weeks out are the documented playbook. | If wishlist velocity stays flat despite an active page and demo through one Next Fest cycle, **rewrite** the positioning/store page (capsule, pitch, tags) before committing to a launch date; if a second cycle also fails, **defer** launch and reassess whether there is an audience. | +| C2 | **Commercial indifference — players understand but do not care** — testers *get* the game, can explain it, replay it — and still feel no desire to buy or recommend. Comprehension ≠ desire. | Med | High | The M0 bar tests comprehension and replay but **never tested FUN** (accepted review finding); in playtests, testers correctly explain the loop yet, when asked, would not pay for it or tell a friend; Net-Promoter-style "would you recommend?" is low despite high comprehension. | Howard | **Add an explicit fun/desire check to the M0 bar**, separate from comprehension: does a tester *want* another service, *want* to tell someone, *would* pay? Track desire, not just understanding. | If testers reliably understand but do not want the game after two iterations, **rewrite** the core fantasy's expression (not just the tutorial) — this is a design-fun failure, not a communication failure — before any commercial commitment. | +| C3 | **Mispriced / wrong commercial model** — priced above what a debut two-person management sim can command, or structured wrong for the genre (full launch vs. Early Access). | Med | Med | Pricing is chosen with no comparable anchor; playtesters balk at the intended price; the plan assumes a full 1.0 launch against a genre where Early Access is the norm. | Aaron | Anchor price to real comparables and choose Early Access deliberately. `[VERIFIED]` Comparables (retrieved Jul 2026): Two Point Hospital base $29.99 (often discounted to ~$14.99); Big Ambitions $22.99 — a debut premium-but-indie management sim sits roughly in the **$20–30** band. `[ASSUMPTION — confirm]` exact price at launch. Steam Deck verification and controller support materially affect sales and should be scoped as commercial features, not afterthoughts. | If comparables and playtest willingness-to-pay don't support the intended price/model, **rewrite** the pricing/EA plan before the store page locks it in. | +| C4 | **Genre timing / crowded field** — the premium restaurant/management niche is saturated or moves on before the first commercial cut is ready. | Med | Med | Multiple close comparables launch into the same window; the distinctive hook ("the menu is the strategy," one deeply-simulated restaurant → empire) stops reading as distinctive against shipped competitors. | Howard | Lead with the differentiator relative to lineage (Restaurant Empire I/II, Chef, Big Ambitions, Two Point Hospital, Recipe for Disaster, PlateUp!, Dave the Diver); keep the first cut *deep and distinctive* rather than broad. Deferred M4+ features (multiple restaurants, corporate layer, franchising, etc.) are **not** the differentiator and are not built now. | If the distinctive hook no longer separates the game from shipped competitors, **rewrite** the positioning; if the niche is genuinely saturated, **defer** and re-time the launch. | +| C5 | **Edge-gap commercial features underscoped** — controller/Steam Deck support, telemetry/consent, audio-as-legibility, and playtester sourcing are treated as afterthoughts and become launch blockers. | Med | Med | Any of these appears for the first time as a *launch blocker* rather than a planned item; no lawful telemetry-consent story exists when telemetry is first added; no repeatable way to source playtesters exists when one is needed. | Aaron | Track each as a first-class line item from the appropriate gate: Steam Deck verification + controller support scoped as commercial requirements; telemetry only with explicit consent; audio treated as legibility (see P8); a named, repeatable playtester-sourcing channel. | If any edge-gap item surfaces as an unplanned launch blocker, **defer** the launch date rather than shipping it broken or non-compliant. | + +--- + +## Register hygiene + +- This register is reviewed at **every quarterly continue/rewrite/stop gate** (`HUMAN-RISK-PLAN.md`). Each row's early signal is checked against reality and marked *not observed / watch / triggered*. +- New risks are added the moment they are named, even before they're understood — a named risk with a rough signal beats an unlogged one. +- **Only M0 is authorized for implementation.** Mitigations that reference M1–M3 or post-release M4+ work are planning hypotheses, recorded here so they aren't forgotten — not instructions to start building. +- When the contract and instinct disagree, the contract wins, and the disagreement is recorded (per `CLAUDE.md`). + +--- + +*Sources for grounded market figures:* +- Steam Next Fest June 2026 dates and demo/outreach playbook — [Steamworks: Steam Next Fest June 2026](https://partner.steamgames.com/doc/marketing/upcoming_events/nextfest/2026june), [Steam Next Fest October 2026](https://partner.steamgames.com/doc/marketing/upcoming_events/nextfest/2026october), [Althera Games: Next Fest strategy](https://altheragames.com/en/blog/steam-next-fest-strategy), [Big Games Machine: Next Fest marketing](https://www.biggamesmachine.com/steam-next-fest-marketing-strategies/) +- Comparable pricing (retrieved Jul 2026) — [Two Point Hospital on Steam](https://store.steampowered.com/app/535930/), [Big Ambitions price tracker (Steambase)](https://steambase.io/games/big-ambitions/price) diff --git a/fixtures/README.md b/fixtures/README.md new file mode 100644 index 0000000..af3aa71 --- /dev/null +++ b/fixtures/README.md @@ -0,0 +1,9 @@ +# fixtures/ + +Reserved for external, data-driven fixture files (JSON/CSV) in later milestones. + +In **M0**, the fixtures (3 customer segments, 12 recipes, 8 employees, 3 market scenarios, 9 named +strategies) are authored as typed, immutable code in `src/RestaurantSim.Core/M0Content.cs` and +`src/RestaurantSim.Core/Strategies.cs` — hand-authored round numbers, per the M0 placeholder policy. When +content moves to external schema-validated data (M2+/content pipeline), it will live here with stable IDs +and provenance. diff --git a/global.json b/global.json new file mode 100644 index 0000000..b4c86c8 --- /dev/null +++ b/global.json @@ -0,0 +1,6 @@ +{ + "sdk": { + "version": "8.0.423", + "rollForward": "latestFeature" + } +} diff --git a/reports/balance/distribution.md b/reports/balance/distribution.md new file mode 100644 index 0000000..206c42a --- /dev/null +++ b/reports/balance/distribution.md @@ -0,0 +1,67 @@ +# M0 Balance / Distribution Report + +Generated by `RestaurantSim.Harness`. Seeds per cell: **200** (base seed 700000). +Contribution is per single service in integer cents rendered as dollars. "win%" = share of seeds +where this strategy had the highest contribution in that scenario (same seed compared across strategies). + +## Neighborhood Lunch Rush (`lunch-rush`) + +_Value-heavy, high-volume, price-sensitive, small parties, early peak. Rewards fast throughput and lean value menus._ + +| Strategy | median contrib | p10 | p90 | loss% | avg covers | avg sat | avg ticket | win% | +|---|--:|--:|--:|--:|--:|--:|--:|--:| +| Focused Value | $304.15 | $29.25 | $551.95 | 8% | 93 | 531 | 16m | 76% | +| Premium Craft | -$51.88 | -$387.76 | $325.66 | 56% | 21 | 767 | 15m | 16% | +| Broad Menu | -$393.50 | -$887.00 | $37.00 | 87% | 77 | 561 | 20m | 5% | +| Overcapacity | -$789.00 | -$929.00 | -$662.00 | 100% | 22 | 537 | 20m | 0% | +| Understaffed | -$528.00 | -$615.00 | -$448.50 | 100% | 12 | 506 | 22m | 0% | +| Balanced Competent | -$408.00 | -$726.00 | -$1.00 | 90% | 66 | 570 | 20m | 1% | +| Overpriced Weak Execution | -$302.80 | -$534.80 | $20.20 | 87% | 7 | 397 | 27m | 1% | +| Station Bottleneck | -$597.00 | -$707.50 | -$497.00 | 100% | 15 | 591 | 18m | 0% | +| Intentionally Bad | -$391.20 | -$441.00 | -$325.20 | 100% | 5 | 528 | 20m | 0% | + +**Winner:** Focused Value · **profitable strategies (median >= +$150):** 1 + +## Weekend Social Dinner (`social-dinner`) + +_Mid-budget social diners in groups, multi-course, moderate patience. Rewards a balanced, coherent menu and solid service._ + +| Strategy | median contrib | p10 | p90 | loss% | avg covers | avg sat | avg ticket | win% | +|---|--:|--:|--:|--:|--:|--:|--:|--:| +| Focused Value | $519.50 | $114.85 | $723.05 | 3% | 101 | 582 | 18m | 42% | +| Premium Craft | $361.90 | -$538.82 | $1334.24 | 31% | 58 | 639 | 24m | 43% | +| Broad Menu | -$66.00 | -$781.00 | $622.00 | 55% | 89 | 584 | 23m | 7% | +| Overcapacity | -$572.50 | -$843.50 | -$326.00 | 100% | 37 | 578 | 21m | 0% | +| Understaffed | -$480.00 | -$607.50 | -$354.50 | 100% | 17 | 514 | 25m | 0% | +| Balanced Competent | $42.00 | -$540.50 | $655.50 | 48% | 87 | 609 | 21m | 7% | +| Overpriced Weak Execution | -$899.10 | -$1077.60 | -$694.20 | 100% | 5 | 374 | 29m | 0% | +| Station Bottleneck | -$626.00 | -$807.50 | -$402.00 | 100% | 21 | 624 | 20m | 0% | +| Intentionally Bad | -$394.60 | -$488.80 | -$293.80 | 100% | 7 | 517 | 23m | 0% | + +**Winner:** Focused Value · **profitable strategies (median >= +$150):** 2 + +## Destination Enthusiast Evening (`enthusiast-evening`) + +_High-budget enthusiasts, lower volume, high quality expectations, patient. Rewards premium craft and skilled execution._ + +| Strategy | median contrib | p10 | p90 | loss% | avg covers | avg sat | avg ticket | win% | +|---|--:|--:|--:|--:|--:|--:|--:|--:| +| Focused Value | $246.95 | $80.95 | $411.30 | 2% | 63 | 633 | 13m | 0% | +| Premium Craft | $1031.68 | $161.14 | $1754.74 | 6% | 68 | 612 | 24m | 74% | +| Broad Menu | $556.50 | -$100.50 | $930.00 | 11% | 88 | 586 | 23m | 11% | +| Overcapacity | -$20.50 | -$424.00 | $486.50 | 52% | 51 | 561 | 22m | 0% | +| Understaffed | -$336.00 | -$498.50 | -$171.00 | 98% | 22 | 466 | 27m | 0% | +| Balanced Competent | $484.50 | $191.50 | $743.00 | 0% | 78 | 642 | 18m | 13% | +| Overpriced Weak Execution | -$851.80 | -$1053.60 | -$580.00 | 99% | 7 | 315 | 30m | 0% | +| Station Bottleneck | -$394.50 | -$666.00 | -$123.50 | 97% | 27 | 581 | 22m | 0% | +| Intentionally Bad | -$319.40 | -$442.40 | -$170.80 | 100% | 10 | 469 | 24m | 0% | + +**Winner:** Premium Craft · **profitable strategies (median >= +$150):** 4 + +## Dominance check + +- **lunch-rush** best strategy: `Focused Value` +- **social-dinner** best strategy: `Focused Value` +- **enthusiast-evening** best strategy: `Premium Craft` + +Distinct winning strategies across scenarios: **2** of 3. No single strategy wins across all markets: context changes the best plan. ✅ diff --git a/reports/determinism/checksums.md b/reports/determinism/checksums.md new file mode 100644 index 0000000..8dca289 --- /dev/null +++ b/reports/determinism/checksums.md @@ -0,0 +1,18 @@ +# M0 Determinism Report + +Each row runs the SAME (scenario, strategy, seed) twice and compares the authoritative state checksum. +A management sim that promises "same seed reproduces the same result" must pass this. See DETERMINISM-CONTRACT.md. + +| Scenario | Strategy | Seed | Checksum run 1 | Checksum run 2 | Match | +|---|---|--:|---|---|:--:| +| lunch-rush | Focused Value | 700042 | `F07AA46F729A0A8F` | `F07AA46F729A0A8F` | ✅ | +| lunch-rush | Premium Craft | 700042 | `A0D653B17FF192D8` | `A0D653B17FF192D8` | ✅ | +| lunch-rush | Broad Menu | 700042 | `E63EABF147F55033` | `E63EABF147F55033` | ✅ | +| social-dinner | Focused Value | 700042 | `54F356FF43370823` | `54F356FF43370823` | ✅ | +| social-dinner | Premium Craft | 700042 | `CC04BB7D20A81AEE` | `CC04BB7D20A81AEE` | ✅ | +| social-dinner | Broad Menu | 700042 | `A0054A9CE5021BBE` | `A0054A9CE5021BBE` | ✅ | +| enthusiast-evening | Focused Value | 700042 | `94FEB3F3011C1E36` | `94FEB3F3011C1E36` | ✅ | +| enthusiast-evening | Premium Craft | 700042 | `24EE4A83E7436797` | `24EE4A83E7436797` | ✅ | +| enthusiast-evening | Broad Menu | 700042 | `764B71FDC6B9E691` | `764B71FDC6B9E691` | ✅ | + +**All checksums matched: determinism holds for the sampled matrix.** diff --git a/reports/m0/M0-GATE-RECOMMENDATION.md b/reports/m0/M0-GATE-RECOMMENDATION.md new file mode 100644 index 0000000..ac9612a --- /dev/null +++ b/reports/m0/M0-GATE-RECOMMENDATION.md @@ -0,0 +1,68 @@ +# M0 Gate — Builder's Recommendation + +**Author:** Builder / Technical Lead. **Date:** 2026-07-28. The Builder recommends; **the owners decide.** +The Builder is NOT authorized to declare the project ready for M1. + +## Repository summary +- **Branch:** `foundation/m0-headless-service-lab`, delivered as a pull request into `main`. +- **Solution:** `Restaurant.sln` — `RestaurantSim.Core` (pure sim), `.Cli`, `.Harness`, and three test projects. +- **Major architecture decisions:** authoritative engine-agnostic core; renderer owns no truth; integer-only + numerics (cents / basis points / milli / fixed-point), no float in authoritative state; named seeded RNG + streams; FNV-1a state checksum; forecasts as immutable snapshots. See `docs/architecture/ADR-00{1..4}`. + +## M0 implementation +- **Exists:** demand/arrivals, weighted dish choice, seating/queue, a per-minute service tick, kitchen + station queues with per-cook concurrency, front-of-house capacity effects, quality/mistakes/comps, + holding loss, satisfaction (food/wait/service/value with salient-moment weighting), integer economy, + a pre-service forecast, a post-service causal autopsy, revise-and-run-again, deterministic seeds, a + strategy/distribution harness, and state checksums. A CLI plays the full loop. +- **Intentionally omitted (M0 non-goals):** graphics, engine, pathfinding/spatial movement, inventory/ + suppliers/spoilage, recipe editor, reviews/critics as world systems, hiring/firing, managers/delegation, + competitors, city, campaign, tutorials, localization, multiplayer, mods, save system, assets, audio. +- **How to run:** see `README.md` (`dotnet test`; `dotnet run --project src/RestaurantSim.Cli`; + `dotnet run -c Release --project src/RestaurantSim.Harness -- --seeds 200 --out reports`). + +## Evidence +- **Tests:** 74 passing (Core 36, Determinism 30, Scenario 8) — invariants, determinism, golden checksums, + balance properties. +- **Determinism:** same seed + commands ⇒ identical checksum across the sampled matrix (`reports/determinism/ + checksums.md`); enforced by tests including a reflection scan (no float/double/decimal in authoritative + fields) and a source scan (no wall-clock, no `System.Random`). Example: `Focused Value` / `lunch-rush` / + seed 700042 ⇒ checksum `F07AA46F729A0A8F` (golden-locked). +- **Distribution (200 seeds/cell, `reports/balance/distribution.md`):** winners are **lunch → Focused Value**, + **enthusiast → Premium Craft**, **social → contested**; **2 of 3 distinct winners → no single dominant + strategy**; every deliberately-poor strategy posts a negative median and is legibly diagnosed. +- **Forecast vs actual:** `reports/m0/example-forecast-vs-actual.txt` (Balanced Competent / social-dinner) + shows the immutable forecast, a sampled service log, and the causal autopsy side by side. +- **Playtest status:** plan, script, and consent are ready (`docs/playtests/`); **human sessions are NOT yet + run — they are the owners' to gather, and the Builder will not fabricate them.** + +## Findings +- **Promising:** the causal autopsy is genuinely legible (it names the binding constraint, e.g. "Kitchen + bottleneck at the Grill station: 91% utilized, peak queue 46"); menu/price/staffing/capacity choices + produce clearly different, context-dependent outcomes; the loop invites "change one thing and re-run." +- **Weak / honest limitation:** in a single service with no repeat visits, **throughput dominates profit and + quality has limited economic teeth** (only via comped failures). This is expected for M0 and is the key + signal for M1: repeat visits + reputation are what make identity/quality pay off over time. See + `docs/design/M0-BALANCE-HYPOTHESES.md` and DECISION-LOG D-012. +- **Dominance:** none. No strategy wins every market; premium/biggest-menu/max-capacity/highest-price/ + cheapest-labor are each *not* always best (enforced as tests). +- **Fun vs understandable:** the Builder can only attest that the loop is **understandable, legible, and + non-degenerate**, and that it *invites* revision. Whether it is **fun** is a human judgment that requires + the owner-run playtests. That half of the gate is deliberately left open. + +## Scope audit +**Clean.** No item from the M0 hard non-goals list was built. Asset packages remain quarantined and +uncommitted. No presentation/engine code exists. No unauthorized system was added. + +## Gate recommendation +- **Verdict: Conditional-Pass.** The *technical* M0 is proven — deterministic, reconciling, in-scope, with a + legible causal loop and no dominant strategy. It is "Conditional" only because the fun/comprehension/replay + half depends on human playtests that the Builder cannot run or fake, not because of any defect. +- **Action: Defer** the Continue / Rewrite / Abandon decision to the owners, pending (a) an independent + reviewer's verification and (b) the five-tester human playtest. **Do not begin M1.** + +## Required owner decision +Run the independent review and the five uncoached human playtests (comprehension, voluntary replay, and +**fun/affect** per the test script), then decide the M0 verdict and whether to authorize M1. Record it in +`docs/DECISION-LOG.md` and `docs/CURRENT-STATE.md`. diff --git a/reports/m0/example-forecast-vs-actual.txt b/reports/m0/example-forecast-vs-actual.txt new file mode 100644 index 0000000..360d575 --- /dev/null +++ b/reports/m0/example-forecast-vs-actual.txt @@ -0,0 +1,90 @@ +PLAN: Balanced Competent + Seats: 46 Walk-in acceptance: 100% + Menu: + [Starter] House Salad $8.00 (station Cold, 4m, cost $2.50) + [Main ] Classic Burger $15.00 (station Grill, 7m, cost $4.50) + [Main ] Roast Chicken $22.00 (station Grill, 12m, cost $5.50) + [Main ] Fish & Chips $18.00 (station Saute, 8m, cost $5.00) + [Dessert] Ice Cream $7.00 (station Pastry, 3m, cost $1.50) + [Dessert] Cheese Plate $16.00 (station Cold, 4m, cost $6.00) + Crew: + Nina -> Saute + Owen -> Grill + Priya -> Pastry + Diego -> Grill + Sam -> Cold + Lena -> FrontOfHouse + Tom -> FrontOfHouse + +FORECAST (committed before service; immutable): + Expected covers: 139 + Expected revenue: $3843.35 + Expected contribution: $1980.52 band [$1330.29 .. $2630.75] (confidence 76%) + Key assumptions: + - Conversion of attempted visits: 61% (menu fit & pricing vs this market). + - Expected attempted parties: 58 (~139 covers at mean size 2.4). + - Binding constraint at commit: attempted demand (market/pricing). + - Expected served covers: 139; expected check/cover: $27.65. + - Menu complexity load: +7% ticket work. + +SERVICE LOG (sampled): + t= 0 seated= 0 queue= 0 cooking= 0 tickets[Cold:0 Saute:0 Grill:0 Pastry:0] rev=$0.00 + t= 15 seated= 3 queue= 0 cooking= 2 tickets[Cold:1 Saute:0 Grill:0 Pastry:0] rev=$0.00 + t= 30 seated= 6 queue= 0 cooking= 4 tickets[Cold:0 Saute:0 Grill:0 Pastry:0] rev=$0.00 + t= 45 seated=11 queue= 0 cooking= 5 tickets[Cold:0 Saute:0 Grill:0 Pastry:0] rev=$81.00 + t= 60 seated=15 queue= 0 cooking=10 tickets[Cold:0 Saute:1 Grill:7 Pastry:0] rev=$339.00 + t= 75 seated=18 queue= 0 cooking=13 tickets[Cold:2 Saute:0 Grill:6 Pastry:0] rev=$533.00 + t= 90 seated=19 queue= 0 cooking=10 tickets[Cold:1 Saute:2 Grill:5 Pastry:0] rev=$761.00 + t=105 seated=17 queue= 2 cooking=10 tickets[Cold:4 Saute:2 Grill:8 Pastry:0] rev=$1085.00 + t=120 seated=18 queue= 5 cooking=12 tickets[Cold:8 Saute:0 Grill:10 Pastry:0] rev=$1260.00 + t=135 seated=20 queue= 4 cooking=14 tickets[Cold:8 Saute:0 Grill:11 Pastry:0] rev=$1511.00 + t=150 seated=20 queue= 2 cooking=15 tickets[Cold:8 Saute:0 Grill:14 Pastry:0] rev=$1734.00 + t=165 seated=17 queue= 0 cooking=13 tickets[Cold:1 Saute:0 Grill:9 Pastry:0] rev=$1940.00 + t=180 seated= 9 queue= 0 cooking= 7 tickets[Cold:1 Saute:0 Grill:4 Pastry:0] rev=$2193.00 + t=195 seated= 4 queue= 0 cooking= 2 tickets[Cold:0 Saute:0 Grill:0 Pastry:0] rev=$2247.00 + t=210 seated= 1 queue= 0 cooking= 0 tickets[Cold:0 Saute:0 Grill:0 Pastry:0] rev=$2427.00 + +====== POST-SERVICE AUTOPSY [social-dinner] Balanced Competent seed 700042 ====== +FORECAST vs ACTUAL: + Covers: forecast 139 actual 123 + Contribution: forecast $1980.52 actual $546.50 diff -$1434.02 + +DEMAND FUNNEL: + Attempted parties (after market/pricing): 69 + Served parties: 53 covers: 123 + Lost to seating/capacity: 1 walked out waiting: 15 no acceptable dish: 0 + +ECONOMY: + Revenue: $2524.00 + Ingredients: - $1222.50 + Labor: - $605.00 + Fixed overhead:- $150.00 + CONTRIBUTION: $546.50 (profit) + +SERVICE: avg ticket 23 min service failures 95 menu-complexity load +7% overall satisfaction 600/1000 + +BY DISH: + dish ord dlv fail qual revenue contrib + House Salad 78 62 26 377 $360.00 $165.00 + Classic Burger 46 33 16 399 $315.00 $108.00 + Roast Chicken 55 41 21 493 $550.00 $247.50 + Fish & Chips 55 49 3 595 $864.00 $589.00 + Ice Cream 30 24 5 518 $147.00 $102.00 + Cheese Plate 33 25 9 618 $288.00 $90.00 + +BY SEGMENT (satisfaction 0-1000; F=food W=wait S=service V=value): + Value Lunch parties 10 covers 18 sat 449 (F488 W380 S571 V627) + Social Dinner parties 48 covers 82 sat 512 (F456 W478 S636 V692) + Food Enthusiast parties 10 covers 23 sat 474 (F378 W609 S731 V655) + +BY STATION (utilization / peak queue / dishes / staff): + Cold util 64% peakQ 13 dishes 111 staff 1 + Saute util 64% peakQ 5 dishes 55 staff 1 + Grill util 76% peakQ 17 dishes 101 staff 2 + Pastry util 14% peakQ 1 dishes 30 staff 1 + +CAUSAL SUMMARY: + Service bottleneck: 15 parties walked out waiting for food. Front-of-house and/or kitchen throughput could not keep pace with seated demand. + Most profitable dish: Fish & Chips Least useful dish: Cheese Plate Highest-pressure station: Grill + checksum: 7C4703D4A5375AF5 + diff --git a/reports/m0/harness-console-summary.txt b/reports/m0/harness-console-summary.txt new file mode 100644 index 0000000..75fefbc --- /dev/null +++ b/reports/m0/harness-console-summary.txt @@ -0,0 +1,9 @@ +M0 harness: 9 strategies x 3 scenarios x 200 seeds = 5400 services + +=== SUMMARY === + lunch-rush winner: Focused Value viable strategies: 1 + social-dinner winner: Focused Value viable strategies: 2 + enthusiast-evening winner: Premium Craft viable strategies: 4 + distinct winners across scenarios: 2/3 no single dominant strategy + determinism: PASS example seed 700042 checksum 7C4703D4A5375AF5 + reports written under: reports/ diff --git a/src/RestaurantSim.Cli/Program.cs b/src/RestaurantSim.Cli/Program.cs new file mode 100644 index 0000000..22531b4 --- /dev/null +++ b/src/RestaurantSim.Cli/Program.cs @@ -0,0 +1,211 @@ +using RestaurantSim.Core; + +// M0 Headless Service Lab — CLI. Lets a player inspect, plan, forecast, commit, read the autopsy, +// revise, and run again. No graphics; the loop is the point. See docs/design/M0-PROTOTYPE-CONTRACT.md. + +var world = M0Content.World(); +var scenarios = M0Content.Scenarios(); + +if (args.Length > 0) +{ + return RunNonInteractive(args); +} + +RunInteractive(); +return 0; + +int RunNonInteractive(string[] a) +{ + switch (a[0].ToLowerInvariant()) + { + case "list": + PrintRecipes(); PrintStaff(); PrintScenarios(); + return 0; + case "strategy": + { + if (a.Length < 3) { Console.WriteLine("usage: strategy \"\" [seed]"); return 2; } + var plan = FindStrategy(a[1]); + if (plan == null) { Console.WriteLine($"unknown strategy '{a[1]}'"); return 2; } + var sc = scenarios.FirstOrDefault(s => s.Id == a[2]); + if (sc == null) { Console.WriteLine($"unknown scenario '{a[2]}'"); return 2; } + ulong seed = a.Length > 3 && ulong.TryParse(a[3], out var s) ? s : 20260728UL; + RunAndShow(plan, sc, seed, captureLog: true); + return 0; + } + default: + Console.WriteLine("commands: list | strategy \"\" [seed] | (no args) interactive"); + return 2; + } +} + +void RunInteractive() +{ + string scenarioId = scenarios[0].Id; + var menu = new List(); + var assign = new Dictionary(); + int seats = 40, acceptance = 10000; + bool captureLog = false; + + Console.WriteLine("=== M0 Headless Service Lab ==="); + Console.WriteLine("Type 'help' for commands, 'preset \"Balanced Competent\"' for a starting plan, then 'forecast' and 'run'."); + Console.WriteLine($"Market: {Scenario().Name}\n"); + + MarketScenario Scenario() => scenarios.First(s => s.Id == scenarioId); + ServicePlan Draft() => new("Custom", menu.ToList(), new Dictionary(assign), seats, acceptance); + + while (true) + { + Console.Write("> "); + var line = Console.ReadLine(); + if (line == null) break; + var t = line.Trim(); + if (t.Length == 0) continue; + var p = t.Split(' ', StringSplitOptions.RemoveEmptyEntries); + var cmd = p[0].ToLowerInvariant(); + try + { + switch (cmd) + { + case "help": PrintHelp(); break; + case "recipes": PrintRecipes(); break; + case "staff": PrintStaff(); break; + case "scenarios": PrintScenarios(); break; + case "quit": case "exit": return; + case "scenario": + if (scenarios.Any(s => s.Id == p[1])) { scenarioId = p[1]; Console.WriteLine($"Market: {Scenario().Name}"); } + else Console.WriteLine("unknown scenario id"); + break; + case "seats": seats = Math.Max(0, int.Parse(p[1])); Console.WriteLine($"seats = {seats}"); break; + case "accept": acceptance = Math.Clamp(int.Parse(p[1]) * 100, 0, 10000); Console.WriteLine($"acceptance = {acceptance / 100}%"); break; + case "menu": + HandleMenu(p, menu); + break; + case "assign": + { + int emp = int.Parse(p[1]); + var asg = ParseAssignment(p[2]); + if (asg == Assignment.Off) assign.Remove(emp); else assign[emp] = asg; + Console.WriteLine($"{world.Employee(emp).Name} -> {p[2]}"); + break; + } + case "preset": + { + var name = t.Substring(cmd.Length).Trim().Trim('"'); + var plan = FindStrategy(name); + if (plan == null) { Console.WriteLine("unknown preset; try: " + string.Join(", ", M0Strategies.All(world).Select(s => '"' + s.Name + '"'))); break; } + menu = plan.Menu.ToList(); assign = new Dictionary(plan.Assignments); seats = plan.Seats; acceptance = plan.WalkInAcceptanceBp; + Console.WriteLine($"loaded preset '{plan.Name}'. Type 'plan' to view, 'forecast', then 'run'."); + break; + } + case "plan": Console.Write(TextReport.PlanSummary(world, Draft())); break; + case "log": captureLog = p.Length > 1 && p[1] == "on"; Console.WriteLine($"service log {(captureLog ? "on" : "off")}"); break; + case "forecast": + if (menu.Count == 0) { Console.WriteLine("empty menu; add dishes or load a preset"); break; } + Console.Write(TextReport.Forecast(Forecaster.Compute(world, Scenario(), Draft()))); + break; + case "run": + { + if (menu.Count == 0) { Console.WriteLine("empty menu; add dishes or load a preset"); break; } + ulong seed = p.Length > 1 && ulong.TryParse(p[1], out var s) ? s : 20260728UL; + RunAndShow(Draft(), Scenario(), seed, captureLog); + break; + } + default: Console.WriteLine("unknown command; type 'help'"); break; + } + } + catch (Exception ex) { Console.WriteLine("input error: " + ex.Message); } + } +} + +void HandleMenu(string[] p, List menu) +{ + if (p.Length < 2) { Console.WriteLine("menu add|remove|price ..."); return; } + switch (p[1]) + { + case "add": + { + int id = int.Parse(p[2]); + long price = p.Length > 3 ? (long)(double.Parse(p[3]) * 100) : world.Recipe(id).SuggestedPriceCents; + menu.RemoveAll(m => m.RecipeId == id); + menu.Add(new MenuItem(id, price)); + Console.WriteLine($"added {world.Recipe(id).Name} @ {new Money(price)}"); + break; + } + case "remove": menu.RemoveAll(m => m.RecipeId == int.Parse(p[2])); Console.WriteLine("removed"); break; + case "price": + { + int id = int.Parse(p[2]); long price = (long)(double.Parse(p[3]) * 100); + menu.RemoveAll(m => m.RecipeId == id); menu.Add(new MenuItem(id, price)); + Console.WriteLine($"{world.Recipe(id).Name} price -> {new Money(price)}"); + break; + } + default: Console.WriteLine("menu add|remove|price ..."); break; + } +} + +Assignment ParseAssignment(string s) => s.ToLowerInvariant() switch +{ + "cold" => Assignment.Cold, "saute" => Assignment.Saute, "grill" => Assignment.Grill, + "pastry" => Assignment.Pastry, "foh" => Assignment.FrontOfHouse, _ => Assignment.Off +}; + +ServicePlan? FindStrategy(string name) + => M0Strategies.All(world).FirstOrDefault(s => s.Name.Equals(name, StringComparison.OrdinalIgnoreCase)) + ?? M0Strategies.All(world).FirstOrDefault(s => s.Name.Contains(name, StringComparison.OrdinalIgnoreCase)); + +void RunAndShow(ServicePlan plan, MarketScenario sc, ulong seed, bool captureLog) +{ + Console.WriteLine(); + Console.Write(TextReport.PlanSummary(world, plan)); + var forecast = Forecaster.Compute(world, sc, plan); + Console.WriteLine(); + Console.Write(TextReport.Forecast(forecast)); + var result = new ServiceSimulator().Run(world, sc, plan, seed, new SimOptions(captureLog)); + if (captureLog) + { + Console.WriteLine("\nSERVICE LOG (sampled):"); + foreach (var l in result.ServiceLog) Console.WriteLine(" " + l); + } + Console.WriteLine(); + Console.Write(TextReport.Autopsy(world, result, forecast)); + Console.WriteLine(); +} + +void PrintHelp() +{ + Console.WriteLine(@"commands: + recipes | staff | scenarios show fixtures + scenario choose market (lunch-rush | social-dinner | enthusiast-evening) + preset """" load a named strategy as your draft + menu add [price$] add a dish (default suggested price) + menu price change a price + menu remove remove a dish + assign assign an employee + seats | accept capacity posture + plan show your current draft + forecast show the pre-service forecast (immutable at commit) + log on|off capture a sampled minute-by-minute service log on run + run [seed] commit, simulate, and show the causal autopsy + quit"); +} + +void PrintRecipes() +{ + Console.WriteLine("RECIPES (id | course | station | cost | qCeil | difficulty | active-min | suggested price | appeal VL/SD/FE):"); + foreach (var r in world.Recipes) + Console.WriteLine($" {r.Id,2} {r.Name,-18} {r.Course,-7} {r.Station,-6} cost {new Money(r.IngredientCostCents),7} q{r.QualityCeiling} diff{r.Difficulty} {r.ActiveMinutes}m sug {new Money(r.SuggestedPriceCents),7} appeal {r.Appeal[0]}/{r.Appeal[1]}/{r.Appeal[2]}"); +} + +void PrintStaff() +{ + Console.WriteLine("STAFF (id | wage/service | speed | skill | reliability | fit Cold/Saute/Grill/Pastry | FOH):"); + foreach (var e in world.Employees) + Console.WriteLine($" {e.Id} {e.Name,-7} {new Money(e.WageCents),7} spd {e.SpeedBp / 100}% skill {e.QualitySkill} rel {e.ReliabilityBp / 100}% fit {e.StationFit[0]}/{e.StationFit[1]}/{e.StationFit[2]}/{e.StationFit[3]} foh {e.FohSkill}"); +} + +void PrintScenarios() +{ + Console.WriteLine("MARKET SCENARIOS:"); + foreach (var s in scenarios) + Console.WriteLine($" {s.Id,-18} {s.Name} — {s.Notes}"); +} diff --git a/src/RestaurantSim.Cli/RestaurantSim.Cli.csproj b/src/RestaurantSim.Cli/RestaurantSim.Cli.csproj new file mode 100644 index 0000000..0e5df78 --- /dev/null +++ b/src/RestaurantSim.Cli/RestaurantSim.Cli.csproj @@ -0,0 +1,14 @@ + + + + + + + + Exe + net8.0 + enable + enable + + + diff --git a/src/RestaurantSim.Core/Demand.cs b/src/RestaurantSim.Core/Demand.cs new file mode 100644 index 0000000..03991d4 --- /dev/null +++ b/src/RestaurantSim.Core/Demand.cs @@ -0,0 +1,52 @@ +namespace RestaurantSim.Core; + +/// +/// Pre-service demand model shared by the live simulator and the forecaster, so the forecast is +/// computed from the same assumptions the service will use (only pre-commit information). +/// +public static class DemandModel +{ + /// How attempted visits scale with menu fit and pricing for this market (basis points). + public static int ConversionBp(M0World world, MarketScenario sc, ServicePlan plan) + { + var menu = plan.Menu.ToDictionary(m => m.RecipeId, m => m.PriceCents); + var mains = plan.Menu.Select(m => world.Recipe(m.RecipeId)).Where(r => r.Course == Course.Main).ToList(); + if (mains.Count == 0) return 300; + long conv = 0; + for (int s = 0; s < sc.SegmentMixBp.Length; s++) + { + var seg = world.Segment((SegmentId)s); + int bestAppeal = mains.Max(r => r.Appeal[s]); + long budgetMain = seg.BudgetPerCoverCents * 6 / 10; + var top = mains.OrderByDescending(r => r.Appeal[s]).ThenBy(r => r.Id).First(); + long typicalMainPrice = menu[top.Id]; + int appealFactor = FixedMath.Clamp(bestAppeal * 10, 2000, 10000); + int overBp = (int)Math.Max(0, FixedMath.MulDivRound(typicalMainPrice, FixedMath.Bp, Math.Max(1, budgetMain)) - FixedMath.Bp); + int priceFactor = FixedMath.Clamp(FixedMath.Bp - overBp * seg.PriceSensitivityBp / FixedMath.Bp, 800, 10000); + int segConv = (int)FixedMath.MulDivRound(9000L * appealFactor / FixedMath.Bp * priceFactor, 1, FixedMath.Bp); + conv += (long)sc.SegmentMixBp[s] * segConv; + } + return FixedMath.Clamp((int)(conv / FixedMath.Bp), 300, 9800); + } + + /// Per-minute arrival intensity in milli-parties (expected parties x1000), triangular. + public static int[] ArrivalCurve(MarketScenario sc, int conversionBp) + { + int n = sc.ServiceMinutes; + var w = new int[n]; + int peak = FixedMath.Clamp(n * sc.PeakFractionBp / FixedMath.Bp, 1, n - 1); + long sum = 0; + for (int m = 0; m < n; m++) + { + int dist = m <= peak ? (m * 1000 / Math.Max(1, peak)) : (1000 - (m - peak) * 1000 / Math.Max(1, n - peak)); + w[m] = Math.Max(50, dist); sum += w[m]; + } + long totalMilli = (long)sc.ExpectedArrivals * 1000 * conversionBp / FixedMath.Bp; + var intensity = new int[n]; + for (int m = 0; m < n; m++) intensity[m] = (int)FixedMath.MulDivRound(totalMilli * w[m], 1, sum); + return intensity; + } + + public static int ExpectedAttemptedParties(M0World world, MarketScenario sc, ServicePlan plan) + => (int)FixedMath.MulDivRound(sc.ExpectedArrivals, ConversionBp(world, sc, plan), FixedMath.Bp); +} diff --git a/src/RestaurantSim.Core/Forecast.cs b/src/RestaurantSim.Core/Forecast.cs new file mode 100644 index 0000000..ec583e1 --- /dev/null +++ b/src/RestaurantSim.Core/Forecast.cs @@ -0,0 +1,105 @@ +namespace RestaurantSim.Core; + +/// +/// Computes the immutable pre-service forecast from pre-commit information only. The result is +/// stored and compared against the actual; it is NEVER recomputed with post-service knowledge. +/// It is an analytic approximation, so forecast-vs-actual gaps are expected and informative. +/// +public static class Forecaster +{ + public static ForecastSnapshot Compute(M0World world, MarketScenario sc, ServicePlan plan) + { + var menu = plan.Menu.ToDictionary(m => m.RecipeId, m => m.PriceCents); + var recipes = plan.Menu.Select(m => world.Recipe(m.RecipeId)).ToList(); + var mains = recipes.Where(r => r.Course == Course.Main).ToList(); + var starters = recipes.Where(r => r.Course == Course.Starter).ToList(); + var desserts = recipes.Where(r => r.Course == Course.Dessert).ToList(); + + int conversionBp = DemandModel.ConversionBp(world, sc, plan); + int attempts = DemandModel.ExpectedAttemptedParties(world, sc, plan); + int meanSizeX10 = sc.PartySizeMeanX10; + long attemptedCovers = (long)attempts * meanSizeX10 / 10; + + // expected dishes per cover from segment-mix-weighted course probabilities + long starterProb = 0, dessertProb = 0; + for (int s = 0; s < sc.SegmentMixBp.Length; s++) + { + var seg = world.Segment((SegmentId)s); + starterProb += (long)sc.SegmentMixBp[s] * seg.StarterProbBp; + dessertProb += (long)sc.SegmentMixBp[s] * seg.DessertProbBp; + } + starterProb /= FixedMath.Bp; dessertProb /= FixedMath.Bp; // now in bp + int dishesPerCoverBp = FixedMath.Bp + (starters.Count > 0 ? (int)starterProb : 0) + (desserts.Count > 0 ? (int)dessertProb : 0); + + // menu complexity (mirror simulator) + int menuSize = recipes.Count; + int avgPrep = menuSize == 0 ? 0 : (int)(recipes.Sum(r => (long)r.PrepComplexity) / menuSize); + int complexityBp = Tuning.ComplexityBp(menuSize, avgPrep); + + // kitchen cover capacity + long kitchenWorkCapacity = 0; // bp-minutes over the service + for (int i = 0; i < Stations.Count; i++) + { + foreach (var e in KitchenCrew(world, plan, (StationId)i)) + kitchenWorkCapacity += (long)sc.ServiceMinutes * e.SpeedBp * e.StationFit[i] / 1000 * Tuning.SlotsPerCook; + } + int avgActive = recipes.Count == 0 ? 10 : (int)(recipes.Sum(r => (long)r.ActiveMinutes) / recipes.Count); + long workPerDish = (long)avgActive * FixedMath.Bp * (FixedMath.Bp + complexityBp) / FixedMath.Bp; + long dishCapacity = workPerDish == 0 ? 0 : kitchenWorkCapacity / workPerDish; + long kitchenCoverCap = dishesPerCoverBp == 0 ? 0 : dishCapacity * FixedMath.Bp / dishesPerCoverBp; + + // seat cover capacity + int avgDwell = Tuning.ForecastAvgDwellMin; + long seatCoverCap = (long)plan.Seats * sc.ServiceMinutes / avgDwell; + + long expectedCovers = Math.Max(0, Math.Min(attemptedCovers, Math.Min(kitchenCoverCap, seatCoverCap))); + + // average check per cover + long AvgPrice(List list) => list.Count == 0 ? 0 : list.Sum(r => menu[r.Id]) / list.Count; + long AvgIng(List list) => list.Count == 0 ? 0 : list.Sum(r => r.IngredientCostCents) / list.Count; + long checkPerCover = AvgPrice(mains) + + (starters.Count > 0 ? AvgPrice(starters) * (int)starterProb / FixedMath.Bp : 0) + + (desserts.Count > 0 ? AvgPrice(desserts) * (int)dessertProb / FixedMath.Bp : 0); + long ingPerCover = AvgIng(mains) + + (starters.Count > 0 ? AvgIng(starters) * (int)starterProb / FixedMath.Bp : 0) + + (desserts.Count > 0 ? AvgIng(desserts) * (int)dessertProb / FixedMath.Bp : 0); + + var revenue = new Money(expectedCovers * checkPerCover); + var ingredient = new Money(expectedCovers * ingPerCover); + Money labor = Money.Zero; + foreach (var (empId, asg) in plan.Assignments) if (asg != Assignment.Off) labor += new Money(world.Employee(empId).WageCents); + var contribution = revenue - ingredient - labor - world.FixedOverheadPerService; + + // confidence band: wider if demand ~ capacity (queue nonlinearity) or if there is no FOH + bool capacityBound = expectedCovers < attemptedCovers; + int fohCount = plan.Assignments.Count(kv => kv.Value == Assignment.FrontOfHouse); + int bandBp = 2200 + (capacityBound ? 900 : 0) + (fohCount == 0 ? 1500 : 0) + complexityBp / 4; + bandBp = FixedMath.Clamp(bandBp, 1500, 6000); + + var revLow = revenue.ApplyBp(FixedMath.Bp - bandBp); + var revHigh = revenue.ApplyBp(FixedMath.Bp + bandBp); + var contribLow = revLow - ingredient.ApplyBp(FixedMath.Bp - bandBp) - labor - world.FixedOverheadPerService; + var contribHigh = revHigh - ingredient.ApplyBp(FixedMath.Bp + bandBp) - labor - world.FixedOverheadPerService; + + string binding = expectedCovers == attemptedCovers ? "attempted demand (market/pricing)" + : (kitchenCoverCap <= seatCoverCap ? "kitchen throughput" : "seating capacity"); + + var assumptions = new List + { + $"Conversion of attempted visits: {conversionBp / 100}% (menu fit & pricing vs this market).", + $"Expected attempted parties: {attempts} (~{attemptedCovers} covers at mean size {meanSizeX10 / 10}.{meanSizeX10 % 10}).", + $"Binding constraint at commit: {binding}.", + $"Expected served covers: {expectedCovers}; expected check/cover: {new Money(checkPerCover)}.", + $"Menu complexity load: +{complexityBp / 100}% ticket work.", + }; + + return new ForecastSnapshot((int)expectedCovers, revenue, contribution, contribLow, contribHigh, + FixedMath.Bp - bandBp, assumptions); + } + + private static IEnumerable KitchenCrew(M0World world, ServicePlan plan, StationId station) + { + foreach (var (empId, asg) in plan.Assignments) + if (Stations.ToStation(asg) == station) yield return world.Employee(empId); + } +} diff --git a/src/RestaurantSim.Core/M0Content.cs b/src/RestaurantSim.Core/M0Content.cs new file mode 100644 index 0000000..5d17c2d --- /dev/null +++ b/src/RestaurantSim.Core/M0Content.cs @@ -0,0 +1,71 @@ +namespace RestaurantSim.Core; + +/// +/// The hand-authored M0 fixtures. Round numbers on purpose. 3 segments, 12 recipes (deliberate +/// archetypes, no single dominant dish), 8 employees, 3 market scenarios. See M0-BALANCE-HYPOTHESES.md. +/// Appeal arrays are indexed by (int)SegmentId: [ValueLunch, SocialDinner, FoodEnthusiast]. +/// +public static class M0Content +{ + public static M0World World() => new() + { + Segments = Segments(), + Recipes = Recipes(), + Employees = Employees(), + StartingCash = Money.FromDollars(8000), + FixedOverheadPerService = Money.FromDollars(150), + }; + + public static IReadOnlyList Segments() => new[] + { + // budget seatPat foodPat qExp priceSens atmos startBp destBp failSens novelty WFood WWait WSvc WVal + new SegmentDef(SegmentId.ValueLunch, "Value Lunch", 2200, 12, 24, 520, 8000, 300, 1500, 1000, 500, 300, 25, 35, 15, 25), + new SegmentDef(SegmentId.SocialDinner, "Social Dinner", 5500, 20, 34, 640, 5000, 700, 5500, 5000, 700, 550, 28, 18, 30, 24), + new SegmentDef(SegmentId.FoodEnthusiast,"Food Enthusiast",8500, 25, 42, 820, 3500, 600, 6500, 5500, 850, 750, 45, 12, 18, 25), + }; + + public static IReadOnlyList Recipes() => new[] + { + // id name course station ing qCeil diff act prep hold price appeal[VL,SD,FE] + new RecipeDef(1, "House Salad", Course.Starter, StationId.Cold, 250, 620, 200, 4, 150, 15, 800, new[]{600,520,400}), + new RecipeDef(2, "Soup of the Day", Course.Starter, StationId.Cold, 200, 640, 260, 5, 200, 20, 900, new[]{520,560,480}), + new RecipeDef(3, "Seared Scallops", Course.Starter, StationId.Saute, 750, 900, 720, 9, 500, 6, 1800, new[]{200,620,880}), + new RecipeDef(4, "Classic Burger", Course.Main, StationId.Grill, 450, 680, 260, 7, 200, 12, 1500, new[]{820,600,360}), + new RecipeDef(5, "Roast Chicken", Course.Main, StationId.Grill, 550, 760, 420, 12, 300, 18, 2200, new[]{560,720,560}), + new RecipeDef(6, "Ribeye Steak", Course.Main, StationId.Grill, 1200, 900, 620, 11, 250, 10, 4200, new[]{240,760,820}), + new RecipeDef(7, "Mushroom Risotto", Course.Main, StationId.Saute, 400, 820, 640, 14, 650, 8, 2400, new[]{360,640,720}), + new RecipeDef(8, "Fish & Chips", Course.Main, StationId.Saute, 500, 700, 360, 8, 250, 10, 1800, new[]{700,560,420}), + new RecipeDef(9, "Veggie Bowl", Course.Main, StationId.Cold, 300, 640, 220, 5, 200, 20, 1400, new[]{480,460,360}), + new RecipeDef(10, "Ice Cream", Course.Dessert, StationId.Pastry, 150, 600, 150, 3, 100, 25, 700, new[]{520,520,360}), + new RecipeDef(11, "Chocolate Fondant", Course.Dessert, StationId.Pastry, 350, 900, 760, 10, 600, 6, 1400, new[]{300,640,820}), + new RecipeDef(12, "Cheese Plate", Course.Dessert, StationId.Cold, 600, 780, 200, 4, 300, 30, 1600, new[]{220,560,700}), + }; + + public static IReadOnlyList Employees() => new[] + { + // id name wage speed skill reliab fit[Cold,Saute,Grill,Pastry] foh + new EmployeeDef(1, "Marco", 18000, 12000, 880, 9600, new[]{700,900,850,600}, 300), + new EmployeeDef(2, "Nina", 13000, 11000, 760, 9400, new[]{750,800,780,650}, 350), + new EmployeeDef(3, "Owen", 9500, 11500, 700, 9200, new[]{500,600,900,400}, 250), + new EmployeeDef(4, "Priya", 10500, 10500, 820, 9500, new[]{650,500,450,950}, 300), + new EmployeeDef(5, "Diego", 7000, 10000, 520, 8600, new[]{700,650,650,600}, 400), + new EmployeeDef(6, "Sam", 6500, 10500, 560, 9000, new[]{900,600,500,600}, 450), + new EmployeeDef(7, "Lena", 8000, 9000, 400, 9000, new[]{400,400,400,400}, 900), + new EmployeeDef(8, "Tom", 6000, 9000, 380, 8800, new[]{400,400,400,400}, 780), + }; + + public static IReadOnlyList Scenarios() => new[] + { + new MarketScenario("lunch-rush", "Neighborhood Lunch Rush", 120, 120, 4000, + new[]{6500, 2500, 1000}, 18, + "Value-heavy, high-volume, price-sensitive, small parties, early peak. Rewards fast throughput and lean value menus."), + new MarketScenario("social-dinner", "Weekend Social Dinner", 180, 95, 5500, + new[]{1500, 6000, 2500}, 24, + "Mid-budget social diners in groups, multi-course, moderate patience. Rewards a balanced, coherent menu and solid service."), + new MarketScenario("enthusiast-evening", "Destination Enthusiast Evening", 180, 62, 6000, + new[]{500, 3000, 6500}, 22, + "High-budget enthusiasts, lower volume, high quality expectations, patient. Rewards premium craft and skilled execution."), + }; + + public static MarketScenario Scenario(string id) => Scenarios().First(s => s.Id == id); +} diff --git a/src/RestaurantSim.Core/Model.cs b/src/RestaurantSim.Core/Model.cs new file mode 100644 index 0000000..5e8df7c --- /dev/null +++ b/src/RestaurantSim.Core/Model.cs @@ -0,0 +1,100 @@ +namespace RestaurantSim.Core; + +public enum StationId { Cold = 0, Saute = 1, Grill = 2, Pastry = 3 } +public enum Course { Starter = 0, Main = 1, Dessert = 2 } +public enum SegmentId { ValueLunch = 0, SocialDinner = 1, FoodEnthusiast = 2 } + +/// Where an employee is assigned for the service. +public enum Assignment { Off = 0, Cold = 1, Saute = 2, Grill = 3, Pastry = 4, FrontOfHouse = 5 } + +public static class Stations +{ + public const int Count = 4; + public static StationId? ToStation(Assignment a) => a switch + { + Assignment.Cold => StationId.Cold, + Assignment.Saute => StationId.Saute, + Assignment.Grill => StationId.Grill, + Assignment.Pastry => StationId.Pastry, + _ => null + }; +} + +/// A customer segment (fixture). All fields integer. See M0-SYSTEM-CONTRACTS.md. +public sealed record SegmentDef( + SegmentId Id, + string Name, + long BudgetPerCoverCents, // typical total spend a cover is comfortable with + int PatienceSeatingMin, // minutes willing to wait for a seat before leaving + int PatienceFoodMin, // minutes willing to wait for food after ordering before walking out + int QualityExpectation, // 0..1000 + int PriceSensitivityBp, // higher = punishes over-budget prices harder + int AtmosphereWeight, // 0..1000 (folded into service dimension in M0) + int StarterProbBp, // chance a cover adds a starter + int DessertProbBp, // chance a cover adds a dessert + int ServiceFailureSensitivity, // 0..1000 + int NoveltyPreference, // 0..1000 + // satisfaction dimension weights (relative; need not sum to a constant) + int WFood, int WWait, int WService, int WValue); + +/// A recipe (fixture). Execution modifies a dish ticket, never this definition. +public sealed record RecipeDef( + int Id, + string Name, + Course Course, + StationId Station, + long IngredientCostCents, + int QualityCeiling, // 0..1000 best achievable + int Difficulty, // 0..1000 skill needed to reach the ceiling + int ActiveMinutes, // station-minutes per dish at speed 1.0 + int PrepComplexity, // 0..1000 contribution to menu complexity + int HoldingToleranceMin,// minutes it can sit plated before quality decays + long SuggestedPriceCents, + int[] Appeal); // per SegmentId (index by (int)SegmentId), 0..1000 + +/// An employee (fixture). +public sealed record EmployeeDef( + int Id, + string Name, + long WageCents, // wage for the whole service if working; Off costs nothing + int SpeedBp, // 10000 = 1.0 min of work per minute at a kitchen slot + int QualitySkill, // 0..1000 cooking skill + int ReliabilityBp, // chance per dish of NOT making a mistake + int[] StationFit, // per StationId 0..1000 (multiplies effective skill at that station) + int FohSkill); // 0..1000 front-of-house service skill + +/// A market context / daypart the service runs in (fixture). +public sealed record MarketScenario( + string Id, + string Name, + int ServiceMinutes, + int ExpectedArrivals, // target number of ATTEMPTED parties across the service, pre-conversion + int PeakFractionBp, // where the arrival peak sits in the service (e.g. 5000 = middle) + int[] SegmentMixBp, // per SegmentId, sums to 10000 + int PartySizeMeanX10, // e.g. 22 => mean party size 2.2 + string Notes); + +/// One menu line: a recipe offered at a price. +public sealed record MenuItem(int RecipeId, long PriceCents); + +/// The player's committed plan for a service. This is the command that drives the sim. +public sealed record ServicePlan( + string Name, + IReadOnlyList Menu, + IReadOnlyDictionary Assignments, // employeeId -> assignment + int Seats, // capacity posture: number of covers seatable at once + int WalkInAcceptanceBp); // 10000 = accept all attempted arrivals; lower = decline some at the door + +/// The immutable world of fixtures for an M0 run. +public sealed class M0World +{ + public required IReadOnlyList Segments { get; init; } + public required IReadOnlyList Recipes { get; init; } + public required IReadOnlyList Employees { get; init; } + public required Money StartingCash { get; init; } + public required Money FixedOverheadPerService { get; init; } + + public RecipeDef Recipe(int id) => Recipes.First(r => r.Id == id); + public SegmentDef Segment(SegmentId id) => Segments[(int)id]; + public EmployeeDef Employee(int id) => Employees.First(e => e.Id == id); +} diff --git a/src/RestaurantSim.Core/Numerics.cs b/src/RestaurantSim.Core/Numerics.cs new file mode 100644 index 0000000..2db44df --- /dev/null +++ b/src/RestaurantSim.Core/Numerics.cs @@ -0,0 +1,79 @@ +namespace RestaurantSim.Core; + +/// +/// Authoritative money as integer minor units (cents). No binary floating point, ever. +/// See docs/architecture/DETERMINISM-CONTRACT.md §1.1. +/// +public readonly struct Money : IEquatable, IComparable +{ + public readonly long Cents; + public Money(long cents) { Cents = cents; } + + public static readonly Money Zero = new(0); + public static Money FromDollars(long dollars) => new(dollars * 100); + + public static Money operator +(Money a, Money b) => new(a.Cents + b.Cents); + public static Money operator -(Money a, Money b) => new(a.Cents - b.Cents); + public static Money operator -(Money a) => new(-a.Cents); + public static Money operator *(Money a, long n) => new(a.Cents * n); + + public static bool operator >(Money a, Money b) => a.Cents > b.Cents; + public static bool operator <(Money a, Money b) => a.Cents < b.Cents; + public static bool operator >=(Money a, Money b) => a.Cents >= b.Cents; + public static bool operator <=(Money a, Money b) => a.Cents <= b.Cents; + public static bool operator ==(Money a, Money b) => a.Cents == b.Cents; + public static bool operator !=(Money a, Money b) => a.Cents != b.Cents; + + /// Apply basis points (10,000 = 100%) with explicit integer rounding. + public Money ApplyBp(int bp) => new(FixedMath.MulDivRound(Cents, bp, FixedMath.Bp)); + + public bool Equals(Money other) => Cents == other.Cents; + public override bool Equals(object? o) => o is Money m && Equals(m); + public override int GetHashCode() => Cents.GetHashCode(); + public int CompareTo(Money other) => Cents.CompareTo(other.Cents); + + public override string ToString() + { + long abs = Cents < 0 ? -Cents : Cents; + return (Cents < 0 ? "-$" : "$") + (abs / 100).ToString() + "." + (abs % 100).ToString("D2"); + } +} + +/// +/// Integer-only math helpers. All rounding is explicit and documented. +/// See docs/architecture/DETERMINISM-CONTRACT.md §1. +/// +public static class FixedMath +{ + public const int Scale = 1000; // "milli" scale for quality/appeal/satisfaction (0..1000) + public const int Bp = 10000; // basis-points denominator (100% = 10000) + + /// (value * num) / den, round half away from zero, 128-bit intermediate (no overflow). + public static long MulDivRound(long value, long num, long den) + { + if (den == 0) throw new DivideByZeroException(); + Int128 prod = (Int128)value * num; + Int128 d = den; + Int128 q = prod / d; + Int128 r = prod - q * d; + Int128 absR = r < 0 ? -r : r; + Int128 absD = d < 0 ? -d : d; + if (absR * 2 >= absD) q += (prod < 0) ? -1 : 1; + return (long)q; + } + + public static int ApplyBp(int value, int bp) => (int)MulDivRound(value, bp, Bp); + public static long ApplyBp(long value, int bp) => MulDivRound(value, bp, Bp); + + public static int Clamp(int v, int lo, int hi) => v < lo ? lo : (v > hi ? hi : v); + public static long Clamp(long v, long lo, long hi) => v < lo ? lo : (v > hi ? hi : v); + public static int Milli(int v) => Clamp(v, 0, Scale); + + /// Weighted average of values by weights (weights need not sum to a constant). Integer. + public static int WeightedAvg(ReadOnlySpan values, ReadOnlySpan weights) + { + long num = 0, den = 0; + for (int i = 0; i < values.Length; i++) { num += (long)values[i] * weights[i]; den += weights[i]; } + return den == 0 ? 0 : (int)MulDivRound(num, 1, den); + } +} diff --git a/src/RestaurantSim.Core/RestaurantSim.Core.csproj b/src/RestaurantSim.Core/RestaurantSim.Core.csproj new file mode 100644 index 0000000..bb23fb7 --- /dev/null +++ b/src/RestaurantSim.Core/RestaurantSim.Core.csproj @@ -0,0 +1,9 @@ + + + + net8.0 + enable + enable + + + diff --git a/src/RestaurantSim.Core/Result.cs b/src/RestaurantSim.Core/Result.cs new file mode 100644 index 0000000..7a75c3d --- /dev/null +++ b/src/RestaurantSim.Core/Result.cs @@ -0,0 +1,68 @@ +namespace RestaurantSim.Core; + +/// Immutable pre-service forecast. Computed only from pre-commit information; never recomputed. +public sealed record ForecastSnapshot( + int ExpectedCovers, + Money ExpectedRevenue, + Money ExpectedContribution, + Money ContributionLow, + Money ContributionHigh, + int ConfidenceBp, // 0..10000, higher = tighter band + IReadOnlyList KeyAssumptions); + +public sealed record DishOutcome( + int RecipeId, string Name, Course Course, + int Ordered, int Delivered, int Failed, + int AvgQuality, // 0..1000 over delivered dishes + Money Revenue, Money IngredientCost, Money Contribution); + +public sealed record SegmentOutcome( + SegmentId Id, string Name, + int Parties, int Covers, + int AvgSatisfaction, // 0..1000 + int AvgFood, int AvgWait, int AvgService, int AvgValue); + +public sealed record StationOutcome( + StationId Id, string Name, + int UtilizationBp, // 0..10000 fraction of slot-minutes used + int PeakQueue, int DishesProduced, int Staff); + +public sealed record EmployeeUtil(int EmployeeId, string Name, Assignment Assignment, int UtilizationBp); + +/// +/// The authoritative outcome of one service, including the causal report and a determinism checksum. +/// Every number here is derived from authoritative simulation state, not recomputed by a view. +/// +public sealed record ServiceResult( + string ScenarioId, + string PlanName, + ulong Seed, + // funnel + int DemandGenerated, // attempted arrivals after conversion + int PartiesServed, + int CoversServed, + int LostToCapacity, // walked from the seat queue (no seat in time) + int LostToWait, // seated then walked out waiting for food + int LostToMenuFit, // seated but nothing acceptable to order + // economy (integer cents) + Money Revenue, Money IngredientCost, Money LaborCost, Money FixedOverhead, Money Contribution, + // service quality + int AvgTicketTimeMin, + int ServiceFailures, + int ComplexityPenaltyBp, + // breakdowns + IReadOnlyList Dishes, + IReadOnlyList Segments, + IReadOnlyList StationsOut, + IReadOnlyList Employees, + // causal summary + string BottleneckCause, + int MostProfitableRecipeId, + int LeastUsefulRecipeId, + StationId HighestPressureStation, + int OverallSatisfaction, // covers-weighted, reported but NOT a single "quality score" + ulong Checksum, + IReadOnlyList ServiceLog) +{ + public bool Profitable => Contribution.Cents > 0; +} diff --git a/src/RestaurantSim.Core/Rng.cs b/src/RestaurantSim.Core/Rng.cs new file mode 100644 index 0000000..6108179 --- /dev/null +++ b/src/RestaurantSim.Core/Rng.cs @@ -0,0 +1,82 @@ +namespace RestaurantSim.Core; + +/// Deterministic PRNG (SplitMix64). Never System.Random. Portable, integer-only. +public struct SplitMix64 +{ + private ulong _state; + public SplitMix64(ulong seed) { _state = seed; } + + public ulong NextU64() + { + _state += 0x9E3779B97F4A7C15UL; + ulong z = _state; + z = (z ^ (z >> 30)) * 0xBF58476D1CE4E5B9UL; + z = (z ^ (z >> 27)) * 0x94D049BB133111EBUL; + return z ^ (z >> 31); + } + + /// Uniform int in [0, boundExclusive). Lemire multiply-high, deterministic. + public int NextInt(int boundExclusive) + { + if (boundExclusive <= 1) return 0; + ulong r = NextU64(); + UInt128 m = (UInt128)r * (ulong)boundExclusive; + return (int)(m >> 64); + } + + /// Uniform int in [lo, hi] inclusive. + public int NextRange(int lo, int hi) => hi <= lo ? lo : lo + NextInt(hi - lo + 1); + + /// True with probability num/den. + public bool Chance(int num, int den) + { + if (num <= 0) return false; + if (num >= den) return true; + return NextInt(den) < num; + } + + /// Small symmetric jitter in [-range, +range]. + public int Jitter(int range) => range <= 0 ? 0 : NextRange(-range, range); +} + +/// The five M0 RNG stream domains. Reserved-for-later streams are not present yet. +public enum RngStream { Arrivals = 0, Party = 1, Choice = 2, Execution = 3, Incident = 4 } + +/// +/// Named, seeded, attributable RNG. A per-(stream, entityKey) sub-generator is derived so that +/// adding a roll to one entity never perturbs an unrelated entity or stream. +/// See docs/architecture/DETERMINISM-CONTRACT.md §3. +/// +public sealed class RngStreams +{ + private readonly ulong _root; + private static readonly ulong[] StreamSalt; + + static RngStreams() + { + var vals = Enum.GetValues(); + StreamSalt = new ulong[vals.Length]; + foreach (var v in vals) StreamSalt[(int)v] = Fnv1a64("stream:" + v); + } + + public RngStreams(ulong rootSeed) { _root = rootSeed; } + + public static ulong Fnv1a64(string s) + { + ulong h = 1469598103934665603UL; + foreach (char c in s) { h ^= (byte)(c & 0xFF); h ^= (byte)(c >> 8); h *= 1099511628211UL; } + return h; + } + + private static ulong Mix(ulong a, ulong b) + { + ulong z = a ^ (b + 0x9E3779B97F4A7C15UL + (a << 6) + (a >> 2)); + z = (z ^ (z >> 30)) * 0xBF58476D1CE4E5B9UL; + z = (z ^ (z >> 27)) * 0x94D049BB133111EBUL; + return z ^ (z >> 31); + } + + /// An independent generator for a stream and entity key (party id, minute, dish id, ...). + public SplitMix64 For(RngStream stream, long entityKey) + => new SplitMix64(Mix(Mix(_root, StreamSalt[(int)stream]), unchecked((ulong)entityKey))); +} diff --git a/src/RestaurantSim.Core/Simulator.cs b/src/RestaurantSim.Core/Simulator.cs new file mode 100644 index 0000000..87083fe --- /dev/null +++ b/src/RestaurantSim.Core/Simulator.cs @@ -0,0 +1,567 @@ +namespace RestaurantSim.Core; + +public sealed record SimOptions(bool CaptureLog = false); + +/// +/// The authoritative M0 service simulator. Fixed one-minute timestep, integer-only, seeded streams, +/// no wall clock. A pure function of (world, scenario, plan, seed). See DETERMINISM-CONTRACT.md §4. +/// +public sealed class ServiceSimulator +{ + // Tuning constants (named; never inline magic numbers with meaning). + private const int BrowseMin = 4; + private const int EatMin = 12; + private const int DeliveryBaseMin = 1; + private const int FohPartiesPerStaff = 8; + private const int HoldingDecayPerMin = 18; // milli quality lost per minute held beyond tolerance + private const int MinOrderUtility = 110; // below this appeal-utility a course is not ordered + private const int TailMinutes = 90; // let seated parties finish after arrivals stop + + private enum PState { Waiting, Browsing, Cooking, Eating, Paid, WalkedSeat, WalkedFood, NoOrder } + + private sealed class Dish + { + public long Id; + public RecipeDef Recipe = null!; + public Party Party = null!; + public int WorkDone; // in bp-minutes + public int WorkNeeded; // in bp-minutes + public bool Started; + public bool Done; + public int DoneMin = -1; + public int Quality; // 0..1000, final (after holding loss) + public int RawQuality; // before holding loss + public bool Failed; + public int EmpId = -1; + } + + private sealed class Party + { + public long Id; + public SegmentId Seg; + public int Size; + public long BudgetPerCover; + public int PatienceSeat; + public int PatienceFood; + public int ArriveMin; + public int SeatMin = -1; + public int OrderMin = -1; + public int ReadyMin = -1; // all dishes cooked + public int DeliverMin = -1; + public int EatUntil = -1; + public int LeaveMin = -1; + public int BrowseReady = -1; + public PState State = PState.Waiting; + public List Dishes = new(); + public long ServiceScoreAccum; + public int ServiceScoreSamples; + // final satisfaction (0..1000) + public int SatFood, SatWait, SatService, SatValue, SatOverall; + public Money Paid = Money.Zero; + } + + private sealed class St + { + public StationId Id; + public List Crew = new(); + public Queue Queue = new(); + public Dish?[] Slots = Array.Empty(); + public long BusySlotMinutes; + public long SlotMinutesTotal; + public int PeakQueue; + public int Produced; + } + + public ServiceResult Run(M0World world, MarketScenario scenario, ServicePlan plan, ulong seed, SimOptions? options = null) + { + options ??= new SimOptions(); + var rng = new RngStreams(seed); + + // --- Menu / complexity analysis (once) --- + var menu = plan.Menu.ToDictionary(m => m.RecipeId, m => m.PriceCents); + var menuRecipes = plan.Menu.Select(m => world.Recipe(m.RecipeId)).ToList(); + int menuSize = menuRecipes.Count; + int avgPrep = menuSize == 0 ? 0 : (int)FixedMath.MulDivRound(menuRecipes.Sum(r => (long)r.PrepComplexity), 1, menuSize); + int complexityPenaltyBp = Tuning.ComplexityBp(menuSize, avgPrep); + + // --- Stations & crew --- + var stations = new St[Stations.Count]; + for (int i = 0; i < Stations.Count; i++) stations[i] = new St { Id = (StationId)i }; + var fohCrew = new List(); + var working = new List(); + foreach (var (empId, asg) in plan.Assignments.OrderBy(kv => kv.Key)) + { + if (asg == Assignment.Off) continue; + var emp = world.Employee(empId); + working.Add(emp); + if (asg == Assignment.FrontOfHouse) fohCrew.Add(emp); + else stations[(int)Stations.ToStation(asg)!.Value].Crew.Add(emp); + } + foreach (var st in stations) st.Slots = new Dish?[st.Crew.Count * Tuning.SlotsPerCook]; + + int fohCapacity = 0; + foreach (var f in fohCrew) fohCapacity += FohPartiesPerStaff * f.FohSkill / 1000; + + // --- Demand conversion (arrivals respond to the plan) --- + int conversionBp = DemandModel.ConversionBp(world, scenario, plan); + + // --- Arrival intensity curve (triangular; milli-parties per minute) --- + int[] intensity = DemandModel.ArrivalCurve(scenario, conversionBp); + + // --- Runtime state --- + int seatsFree = plan.Seats; + var waiting = new List(); + var active = new List(); + var allParties = new List(); + long nextPartyId = 1, nextDishId = 1; + int demandGenerated = 0; + + Money revenue = Money.Zero, ingredientCost = Money.Zero; + int serviceFailures = 0; + long ticketTimeSum = 0; int ticketTimeCount = 0; + var log = new List(); + + int totalMinutes = scenario.ServiceMinutes + TailMinutes; + for (int t = 0; t < totalMinutes; t++) + { + // 1) arrivals + if (t < scenario.ServiceMinutes) + { + var ar = rng.For(RngStream.Arrivals, t); + int whole = intensity[t] / 1000; + int frac = intensity[t] % 1000; + int count = whole + (ar.Chance(frac, 1000) ? 1 : 0); + for (int k = 0; k < count; k++) + { + // door acceptance posture + if (!ar.Chance(plan.WalkInAcceptanceBp, FixedMath.Bp)) continue; + long pid = nextPartyId++; + var p = MakeParty(world, scenario, pid, t, rng); + demandGenerated++; + waiting.Add(p); + allParties.Add(p); + } + } + + // 2) seating (arrival order); walk-aways from the seat queue + int fohRatioBp = fohCapacity <= 0 ? 0 : FixedMath.Clamp((int)FixedMath.MulDivRound(fohCapacity, FixedMath.Bp, Math.Max(1, active.Count)), 0, 20000); + for (int i = 0; i < waiting.Count; i++) + { + var p = waiting[i]; + if (t - p.ArriveMin > p.PatienceSeat) { p.State = PState.WalkedSeat; p.LeaveMin = t; continue; } + if (seatsFree >= p.Size) + { + seatsFree -= p.Size; + p.SeatMin = t; + p.State = PState.Browsing; + int orderDelay = fohRatioBp >= FixedMath.Bp ? 0 : FixedMath.Clamp((FixedMath.Bp - fohRatioBp) / 2500, 0, 6); + p.BrowseReady = t + BrowseMin + orderDelay; + active.Add(p); + } + } + waiting.RemoveAll(p => p.State == PState.WalkedSeat || p.State == PState.Browsing); + + // 3) advance active parties + for (int i = 0; i < active.Count; i++) + { + var p = active[i]; + switch (p.State) + { + case PState.Browsing: + if (t >= p.BrowseReady) + { + OrderDishes(world, plan, menu, p, ref nextDishId, rng, stations, complexityPenaltyBp); + if (p.Dishes.Count == 0) { p.State = PState.NoOrder; p.LeaveMin = t; seatsFree += p.Size; } + else { p.State = PState.Cooking; p.OrderMin = t; } + } + break; + case PState.Cooking: + // service sample + p.ServiceScoreAccum += ServiceScore(fohRatioBp); p.ServiceScoreSamples++; + // walkout if food too slow + if (t - p.OrderMin > p.PatienceFood) + { + p.State = PState.WalkedFood; p.LeaveMin = t; seatsFree += p.Size; serviceFailures++; + break; + } + // delivery when all dishes done + if (p.Dishes.All(d => d.Done)) + { + if (p.ReadyMin < 0) p.ReadyMin = t; + int deliveryDelay = DeliveryBaseMin + (fohRatioBp >= FixedMath.Bp ? 0 : FixedMath.Clamp((FixedMath.Bp - fohRatioBp) / 2000, 0, 6)); + if (t >= p.ReadyMin + deliveryDelay) + { + p.DeliverMin = t; p.EatUntil = t + EatMin; p.State = PState.Eating; + ApplyHoldingLoss(p); + ticketTimeSum += (p.DeliverMin - p.OrderMin); ticketTimeCount++; + } + } + break; + case PState.Eating: + p.ServiceScoreAccum += ServiceScore(fohRatioBp); p.ServiceScoreSamples++; + if (t >= p.EatUntil) + { + // pay for delivered dishes; a botched (failed) dish is comped -> no revenue, + // but its ingredients were still consumed. Execution has economic teeth. + foreach (var d in p.Dishes) if (!d.Failed) p.Paid += new Money(menu[d.Recipe.Id]); + revenue += p.Paid; + p.State = PState.Paid; p.LeaveMin = t; seatsFree += p.Size; + } + break; + } + } + active.RemoveAll(p => p.State is PState.Paid or PState.WalkedFood or PState.NoOrder); + + // 4) station production + foreach (var st in stations) + { + if (st.Crew.Count == 0) { if (st.Queue.Count > st.PeakQueue) st.PeakQueue = st.Queue.Count; continue; } + for (int s = 0; s < st.Slots.Length; s++) + { + var cook = st.Crew[s % st.Crew.Count]; // slots map round-robin to cooks + if (st.Slots[s] == null && st.Queue.Count > 0) + { + var d = st.Queue.Dequeue(); + d.Started = true; d.EmpId = cook.Id; + st.Slots[s] = d; + } + var dish = st.Slots[s]; + if (dish != null) + { + st.BusySlotMinutes++; + var emp = cook; + int fit = emp.StationFit[(int)st.Id]; + int effSpeed = emp.SpeedBp * fit / 1000; + dish.WorkDone += effSpeed; + if (dish.WorkDone >= dish.WorkNeeded) + { + FinishDish(world, dish, emp, st, complexityPenaltyBp, rng, ref serviceFailures); + dish.DoneMin = t; + ingredientCost += new Money(dish.Recipe.IngredientCostCents); + st.Produced++; + st.Slots[s] = null; + } + } + } + st.SlotMinutesTotal += st.Slots.Length; + if (st.Queue.Count > st.PeakQueue) st.PeakQueue = st.Queue.Count; + } + + if (options.CaptureLog && (t % 15 == 0 || t == scenario.ServiceMinutes)) + log.Add(SnapshotLine(t, active, waiting, stations, revenue)); + + // termination: after arrivals stop and nobody is active/waiting + if (t >= scenario.ServiceMinutes && active.Count == 0 && waiting.Count == 0) break; + } + + // any parties still unfinished at tail => lost to wait + foreach (var p in active) { if (p.State != PState.Paid) { p.State = PState.WalkedFood; serviceFailures++; } } + + return Finalize(world, scenario, plan, seed, allParties, stations, working, fohCrew, + revenue, ingredientCost, complexityPenaltyBp, serviceFailures, + ticketTimeCount == 0 ? 0 : (int)(ticketTimeSum / ticketTimeCount), + demandGenerated, menu, log); + } + + // ---- helpers ---- + + private static Party MakeParty(M0World world, MarketScenario sc, long pid, int t, RngStreams rng) + { + var r = rng.For(RngStream.Party, pid); + // segment by mix + int roll = r.NextInt(FixedMath.Bp); + int acc = 0; SegmentId seg = SegmentId.ValueLunch; + for (int s = 0; s < sc.SegmentMixBp.Length; s++) { acc += sc.SegmentMixBp[s]; if (roll < acc) { seg = (SegmentId)s; break; } } + var def = world.Segment(seg); + int size = PickSize(sc.PartySizeMeanX10, ref r); + long budget = def.BudgetPerCoverCents + r.Jitter((int)(def.BudgetPerCoverCents / 6)); + return new Party + { + Id = pid, Seg = seg, Size = size, BudgetPerCover = Math.Max(500, budget), + PatienceSeat = Math.Max(3, def.PatienceSeatingMin + r.Jitter(4)), + PatienceFood = Math.Max(6, def.PatienceFoodMin + r.Jitter(6)), + ArriveMin = t + }; + } + + private static int PickSize(int meanX10, ref SplitMix64 r) + { + int[] w = meanX10 <= 18 ? new[] { 35, 45, 12, 8 } + : meanX10 <= 24 ? new[] { 15, 50, 20, 15 } + : new[] { 8, 32, 25, 35 }; + int tot = w[0] + w[1] + w[2] + w[3]; + int d = r.NextInt(tot); + if (d < w[0]) return 1; d -= w[0]; + if (d < w[1]) return 2; d -= w[1]; + if (d < w[2]) return 3; return 4; + } + + private void OrderDishes(M0World world, ServicePlan plan, Dictionary menu, Party p, + ref long nextDishId, RngStreams rng, St[] stations, int complexityPenaltyBp) + { + var seg = world.Segment(p.Seg); + var choice = rng.For(RngStream.Choice, p.Id); + var byCourse = plan.Menu.Select(m => world.Recipe(m.RecipeId)).GroupBy(r => r.Course) + .ToDictionary(g => g.Key, g => g.ToList()); + for (int cover = 0; cover < p.Size; cover++) + { + // main (always attempted) + var main = PickBest(byCourse, Course.Main, seg, menu, 60, ref choice); + if (main == null) continue; // this cover finds no acceptable main + AddDish(world, p, main, menu, ref nextDishId, stations, complexityPenaltyBp); + // starter + if (choice.Chance(seg.StarterProbBp, FixedMath.Bp)) + { + var st = PickBest(byCourse, Course.Starter, seg, menu, 20, ref choice); + if (st != null) AddDish(world, p, st, menu, ref nextDishId, stations, complexityPenaltyBp); + } + // dessert + if (choice.Chance(seg.DessertProbBp, FixedMath.Bp)) + { + var de = PickBest(byCourse, Course.Dessert, seg, menu, 20, ref choice); + if (de != null) AddDish(world, p, de, menu, ref nextDishId, stations, complexityPenaltyBp); + } + } + } + + // Weighted-probabilistic choice: diners spread across acceptable dishes by utility (appeal x price + // fit), rather than everyone ordering the single best dish. This spreads station load realistically + // and is why a one-standout menu concentrates pressure while a coherent menu balances it. + private static RecipeDef? PickBest(Dictionary> byCourse, Course course, + SegmentDef seg, Dictionary menu, int budgetSharePct, ref SplitMix64 choice) + { + if (!byCourse.TryGetValue(course, out var list) || list.Count == 0) return null; + long shareBudget = seg.BudgetPerCoverCents * budgetSharePct / 100; + var weights = new long[list.Count]; + long total = 0; + for (int i = 0; i < list.Count; i++) + { + var r = list[i]; + int appeal = r.Appeal[(int)seg.Id]; + long price = menu[r.Id]; + int overBp = (int)Math.Max(0, FixedMath.MulDivRound(price, FixedMath.Bp, Math.Max(1, shareBudget)) - FixedMath.Bp); + int priceFit = FixedMath.Clamp(FixedMath.Bp - overBp * seg.PriceSensitivityBp / FixedMath.Bp, 300, 10000); + int novelty = 1000 - Math.Abs(seg.NoveltyPreference - r.PrepComplexity); + int u = (int)FixedMath.MulDivRound((long)appeal * priceFit, 1, FixedMath.Bp) + novelty / 40; + long w = u < MinOrderUtility ? 0 : (long)u * u; // square sharpens preference but still spreads + weights[i] = w; total += w; + } + if (total <= 0) return null; + long pick = choice.NextInt((int)Math.Min(total, int.MaxValue - 1)); + long acc = 0; + for (int i = 0; i < list.Count; i++) { acc += weights[i]; if (pick < acc) return list[i]; } + return list[^1]; + } + + private void AddDish(M0World world, Party p, RecipeDef r, Dictionary menu, + ref long nextDishId, St[] stations, int complexityPenaltyBp) + { + int workNeeded = (int)FixedMath.MulDivRound((long)r.ActiveMinutes * FixedMath.Bp, + FixedMath.Bp + complexityPenaltyBp, FixedMath.Bp); + var d = new Dish { Id = nextDishId++, Recipe = r, Party = p, WorkNeeded = workNeeded }; + p.Dishes.Add(d); + stations[(int)r.Station].Queue.Enqueue(d); + } + + private void FinishDish(M0World world, Dish d, EmployeeDef emp, St st, int complexityPenaltyBp, + RngStreams rng, ref int serviceFailures) + { + int fit = emp.StationFit[(int)st.Id]; + int effSkill = emp.QualitySkill * fit / 1000; + int skillRatioBp = (int)FixedMath.MulDivRound(effSkill, FixedMath.Bp, Math.Max(1, d.Recipe.Difficulty)); + int q = (int)FixedMath.MulDivRound(d.Recipe.QualityCeiling, FixedMath.Clamp(skillRatioBp, 0, FixedMath.Bp), FixedMath.Bp); + var ex = rng.For(RngStream.Execution, d.Id); + q += ex.Jitter(40); + // mistake: unreliability + complexity + station overload + int overloadBp = FixedMath.Clamp(st.Queue.Count * 300, 0, 3000); + var inc = rng.For(RngStream.Incident, d.Id); + int mistakeBp = (FixedMath.Bp - emp.ReliabilityBp) + complexityPenaltyBp / 2 + overloadBp; + if (inc.Chance(mistakeBp, FixedMath.Bp)) { q = q * 3 / 10; d.Failed = true; serviceFailures++; } + d.RawQuality = FixedMath.Milli(q); + d.Quality = d.RawQuality; + d.Done = true; // DoneMin is stamped by the station loop with the current minute + } + + private static void ApplyHoldingLoss(Party p) + { + // A dish that finished well before the whole party's meal was delivered has been "held": + // decay its quality by the time held beyond its holding tolerance. + foreach (var d in p.Dishes) + { + // conservative: if the party waited notably longer than this dish's tolerance, apply a modest loss + int held = Math.Max(0, (p.DeliverMin - p.OrderMin) - d.Recipe.HoldingToleranceMin - d.Recipe.ActiveMinutes); + if (held > 0) d.Quality = FixedMath.Milli(d.Quality - Math.Min(400, held * HoldingDecayPerMin)); + } + } + + private static int ServiceScore(int fohRatioBp) + { + // ratio >= 100% => strong service; understaffed => low; no FOH => near zero. + if (fohRatioBp <= 0) return 60; + return FixedMath.Clamp(200 + fohRatioBp / 14, 0, 1000); + } + + private static string SnapshotLine(int t, List active, List waiting, St[] st, Money rev) + { + int cooking = active.Count(p => p.State == PState.Cooking); + string q = string.Join(" ", st.Select(s => $"{s.Id}:{s.Queue.Count}")); + return $"t={t,3} seated={active.Count,2} queue={waiting.Count,2} cooking={cooking,2} tickets[{q}] rev={rev}"; + } + + private ServiceResult Finalize(M0World world, MarketScenario sc, ServicePlan plan, ulong seed, + List parties, St[] stations, List working, List fohCrew, + Money revenue, Money ingredientCost, int complexityPenaltyBp, int serviceFailures, + int avgTicketTime, int demandGenerated, Dictionary menu, List log) + { + // satisfaction per party + foreach (var p in parties) ComputeSatisfaction(world, p); + + int served = parties.Count(p => p.State == PState.Paid); + int covers = parties.Where(p => p.State == PState.Paid).Sum(p => p.Size); + int lostCap = parties.Count(p => p.State == PState.WalkedSeat); + int lostWait = parties.Count(p => p.State == PState.WalkedFood); + int lostMenu = parties.Count(p => p.State == PState.NoOrder); + + Money labor = Money.Zero; + foreach (var e in working) labor += new Money(e.WageCents); + Money overhead = world.FixedOverheadPerService; + Money contribution = revenue - ingredientCost - labor - overhead; + + // dish outcomes + var dishOut = new List(); + foreach (var item in plan.Menu.OrderBy(m => m.RecipeId)) + { + var r = world.Recipe(item.RecipeId); + var dishes = parties.SelectMany(p => p.Dishes).Where(d => d.Recipe.Id == r.Id).ToList(); + int ordered = dishes.Count; + int produced = dishes.Count(d => d.Done); // dishes that actually consumed ingredients + var deliveredDishes = parties.Where(p => p.State == PState.Paid).SelectMany(p => p.Dishes).Where(d => d.Recipe.Id == r.Id).ToList(); + int delivered = deliveredDishes.Count; + int deliveredPaid = deliveredDishes.Count(d => !d.Failed); // comped failures earn nothing + int failed = dishes.Count(d => d.Failed); + int avgQ = deliveredDishes.Count == 0 ? 0 : (int)(deliveredDishes.Sum(d => (long)d.Quality) / deliveredDishes.Count); + Money rev = new Money(menu[r.Id]) * deliveredPaid; + Money ing = new Money(r.IngredientCostCents) * produced; // ingredient cost reconciles to the accumulator + dishOut.Add(new DishOutcome(r.Id, r.Name, r.Course, ordered, delivered, failed, avgQ, rev, ing, rev - ing)); + } + + // segment outcomes + var segOut = new List(); + foreach (var seg in world.Segments) + { + var ps = parties.Where(p => p.Seg == seg.Id && (p.State == PState.Paid || p.State == PState.WalkedFood)).ToList(); + var paid = ps.Where(p => p.State == PState.Paid).ToList(); + int cov = paid.Sum(p => p.Size); + int Avg(Func f) => ps.Count == 0 ? 0 : (int)(ps.Sum(p => (long)f(p)) / ps.Count); + segOut.Add(new SegmentOutcome(seg.Id, seg.Name, ps.Count, cov, + Avg(p => p.SatOverall), Avg(p => p.SatFood), Avg(p => p.SatWait), Avg(p => p.SatService), Avg(p => p.SatValue))); + } + + // station outcomes + var stOut = new List(); + foreach (var st in stations) + { + int util = st.SlotMinutesTotal == 0 ? 0 : (int)FixedMath.MulDivRound(st.BusySlotMinutes, FixedMath.Bp, st.SlotMinutesTotal); + stOut.Add(new StationOutcome(st.Id, st.Id.ToString(), util, st.PeakQueue, st.Produced, st.Crew.Count)); + } + + // employee utilization (kitchen: share of dishes; foh: load proxy). Simplified: working=busy proportional. + var empUtil = new List(); + foreach (var (empId, asg) in plan.Assignments.OrderBy(kv => kv.Key)) + { + if (asg == Assignment.Off) continue; + var e = world.Employee(empId); + int util; + if (asg == Assignment.FrontOfHouse) + util = FixedMath.Clamp((int)FixedMath.MulDivRound(parties.Count(p => p.OrderMin >= 0), FixedMath.Bp, Math.Max(1, fohCrew.Count * 30)), 0, FixedMath.Bp); + else + { + var st = stations[(int)Stations.ToStation(asg)!.Value]; + util = st.SlotMinutesTotal == 0 ? 0 : (int)FixedMath.MulDivRound(st.BusySlotMinutes, FixedMath.Bp, st.SlotMinutesTotal); + } + empUtil.Add(new EmployeeUtil(empId, e.Name, asg, util)); + } + + // causal summary + var (bottleneck, pressureStation) = DiagnoseBottleneck(sc, plan, demandGenerated, served, lostCap, lostWait, stOut, complexityPenaltyBp); + int mostProfit = dishOut.Count == 0 ? -1 : dishOut.OrderByDescending(d => d.Contribution.Cents).ThenBy(d => d.RecipeId).First().RecipeId; + int leastUseful = dishOut.Count == 0 ? -1 : dishOut.OrderBy(d => d.Delivered == 0 ? long.MinValue : d.Contribution.Cents).ThenBy(d => d.RecipeId).First().RecipeId; + int overallSat = covers == 0 ? 0 : (int)(parties.Where(p => p.State == PState.Paid).Sum(p => (long)p.SatOverall * p.Size) / covers); + + ulong checksum = ComputeChecksum(revenue, ingredientCost, labor, overhead, contribution, + served, covers, lostCap, lostWait, lostMenu, serviceFailures, avgTicketTime, overallSat, dishOut, segOut, stOut, empUtil); + + return new ServiceResult(sc.Id, plan.Name, seed, + demandGenerated, served, covers, lostCap, lostWait, lostMenu, + revenue, ingredientCost, labor, overhead, contribution, + avgTicketTime, serviceFailures, complexityPenaltyBp, + dishOut, segOut, stOut, empUtil, + bottleneck, mostProfit, leastUseful, pressureStation, overallSat, checksum, log); + } + + private static void ComputeSatisfaction(M0World world, Party p) + { + if (p.State == PState.WalkedFood) { p.SatFood = p.SatWait = p.SatService = p.SatValue = 120; p.SatOverall = 120; return; } + if (p.State != PState.Paid) return; + var seg = world.Segment(p.Seg); + int avgQ = p.Dishes.Count == 0 ? 0 : (int)(p.Dishes.Sum(d => (long)d.Quality) / p.Dishes.Count); + p.SatFood = Meet(avgQ, seg.QualityExpectation); + int waitExp = (p.SeatMin - p.ArriveMin) + (p.DeliverMin - p.OrderMin); + int waitBudget = Math.Max(1, p.PatienceSeat + p.PatienceFood); + p.SatWait = FixedMath.Clamp(1050 - waitExp * 1000 / waitBudget, 50, 1000); + p.SatService = p.ServiceScoreSamples == 0 ? 500 : (int)(p.ServiceScoreAccum / p.ServiceScoreSamples); + long pricePerCover = p.Size == 0 ? 0 : p.Paid.Cents / p.Size; + int ratioBp = (int)FixedMath.Clamp(FixedMath.MulDivRound(seg.BudgetPerCoverCents, FixedMath.Bp, Math.Max(1, pricePerCover)), 3000, 20000); + int valueQuality = (int)FixedMath.MulDivRound(avgQ, ratioBp, FixedMath.Bp); + p.SatValue = Meet(valueQuality, seg.QualityExpectation); + // salient-moment weighting: pull the weighted average toward the worst dimension + Span dims = stackalloc int[] { p.SatFood, p.SatWait, p.SatService, p.SatValue }; + Span wts = stackalloc int[] { seg.WFood, seg.WWait, seg.WService, seg.WValue }; + int wavg = FixedMath.WeightedAvg(dims, wts); + int min = Math.Min(Math.Min(p.SatFood, p.SatWait), Math.Min(p.SatService, p.SatValue)); + p.SatOverall = (wavg * 6 + min * 4) / 10; + } + + private static int Meet(int actual, int expected) + => FixedMath.Clamp(650 + (actual - expected) * 700 / 1000, 40, 1000); + + private static (string, StationId) DiagnoseBottleneck(MarketScenario sc, ServicePlan plan, + int demand, int served, int lostCap, int lostWait, List st, int complexityBp) + { + var peak = st.OrderByDescending(s => s.UtilizationBp).ThenBy(s => (int)s.Id).First(); + // pressure scores + int seatPressure = lostCap * 100; + int servicePressure = lostWait * 120; + int stationPressure = peak.UtilizationBp >= 8800 ? (peak.UtilizationBp - 6000) + peak.PeakQueue * 100 : 0; + int demandShort = demand < served + lostCap + lostWait + 1 ? 0 : 0; + int weakDemand = (served + lostCap + lostWait) * 100 < sc.ExpectedArrivals * 45 ? (sc.ExpectedArrivals * 45 - (served + lostCap + lostWait) * 100) : 0; + int complexityPressure = complexityBp >= 2500 ? complexityBp : 0; + + int max = Math.Max(Math.Max(seatPressure, servicePressure), Math.Max(stationPressure, Math.Max(weakDemand, complexityPressure))); + if (max == 0) return ("Balanced service: no single dominating constraint. Demand met within capacity.", peak.Id); + if (max == stationPressure) + return ($"Kitchen bottleneck at the {peak.Id} station: {peak.UtilizationBp / 100}% utilized with a peak queue of {peak.PeakQueue} tickets. Add capacity there or move that station's dishes off the menu.", peak.Id); + if (max == servicePressure) + return ($"Service bottleneck: {lostWait} parties walked out waiting for food. Front-of-house and/or kitchen throughput could not keep pace with seated demand.", peak.Id); + if (max == seatPressure) + return ($"Seating/capacity bottleneck: {lostCap} parties left the door for lack of a seat in time. Seats or table turns limited covers.", peak.Id); + if (max == weakDemand) + return ("Weak demand: the dining room was not the limit. Menu fit and/or pricing kept attempted visits low for this market. Reconsider prices or the menu's appeal to this district.", peak.Id); + return ($"Menu-complexity pressure: a broad, prep-heavy menu added {complexityBp / 100}% to ticket work and mistakes. A tighter menu would run faster and cleaner.", peak.Id); + } + + private static ulong ComputeChecksum(Money rev, Money ing, Money lab, Money oh, Money contr, + int served, int covers, int lostCap, int lostWait, int lostMenu, int fails, int ticket, int sat, + List dishes, List segs, List stations, List emps) + { + ulong h = 1469598103934665603UL; + void M(long v) { unchecked { for (int i = 0; i < 8; i++) { h ^= (byte)(v >> (i * 8)); h *= 1099511628211UL; } } } + M(rev.Cents); M(ing.Cents); M(lab.Cents); M(oh.Cents); M(contr.Cents); + M(served); M(covers); M(lostCap); M(lostWait); M(lostMenu); M(fails); M(ticket); M(sat); + foreach (var d in dishes.OrderBy(x => x.RecipeId)) { M(d.RecipeId); M(d.Ordered); M(d.Delivered); M(d.Failed); M(d.AvgQuality); M(d.Revenue.Cents); } + foreach (var s in segs.OrderBy(x => (int)x.Id)) { M((int)s.Id); M(s.Parties); M(s.Covers); M(s.AvgSatisfaction); } + foreach (var s in stations.OrderBy(x => (int)x.Id)) { M((int)s.Id); M(s.UtilizationBp); M(s.DishesProduced); M(s.PeakQueue); } + foreach (var e in emps.OrderBy(x => x.EmployeeId)) { M(e.EmployeeId); M(e.UtilizationBp); } + return h; + } +} diff --git a/src/RestaurantSim.Core/Strategies.cs b/src/RestaurantSim.Core/Strategies.cs new file mode 100644 index 0000000..2c1cb8d --- /dev/null +++ b/src/RestaurantSim.Core/Strategies.cs @@ -0,0 +1,81 @@ +namespace RestaurantSim.Core; + +/// +/// The named M0 strategies. Each is an intentional operating plan, named for what it actually does. +/// The harness runs all of these across all scenarios and seeds to check that no single strategy +/// dominates and that poor strategies fail understandably. See M0-BALANCE-HYPOTHESES.md. +/// +public static class M0Strategies +{ + private static MenuItem Item(M0World w, int recipeId, int priceBp = 10000) + => new(recipeId, w.Recipe(recipeId).SuggestedPriceCents * priceBp / 10000); + + private static ServicePlan Plan(string name, IReadOnlyList menu, + (int emp, Assignment asg)[] staff, int seats, int acceptanceBp = 10000) + => new(name, menu, staff.ToDictionary(s => s.emp, s => s.asg), seats, acceptanceBp); + + public static IReadOnlyList All(M0World w) => new[] + { + FocusedValue(w), PremiumCraft(w), BroadMenu(w), Overcapacity(w), Understaffed(w), + BalancedCompetent(w), OverpricedWeakExecution(w), StationBottleneck(w), IntentionallyBad(w), + }; + + // Small fast value menu, lean cheap staff, high throughput, low prices. + public static ServicePlan FocusedValue(M0World w) => Plan("Focused Value", + new[] { Item(w, 1, 9500), Item(w, 4, 9500), Item(w, 8, 9500), Item(w, 9, 9500) }, + new[] { (3, Assignment.Grill), (5, Assignment.Saute), (6, Assignment.Cold), (8, Assignment.FrontOfHouse) }, + seats: 40); + + // Small premium menu, high-skill crew, higher prices, balanced station load, patient service. + // Sauté carries two dishes (scallops + risotto) so it is double-staffed on purpose. + public static ServicePlan PremiumCraft(M0World w) => Plan("Premium Craft", + new[] { Item(w, 3, 10800), Item(w, 6, 10800), Item(w, 7, 10800), Item(w, 11, 10800) }, + new[] { (1, Assignment.Saute), (2, Assignment.Saute), (3, Assignment.Grill), (4, Assignment.Pastry), (7, Assignment.FrontOfHouse), (8, Assignment.FrontOfHouse) }, + seats: 34); + + // Everything on the menu: tests the menu-complexity cost. Full crew. + public static ServicePlan BroadMenu(M0World w) => Plan("Broad Menu", + Enumerable.Range(1, 12).Select(id => Item(w, id)).ToArray(), + new[] { (1, Assignment.Saute), (2, Assignment.Saute), (3, Assignment.Grill), (5, Assignment.Grill), + (4, Assignment.Pastry), (6, Assignment.Cold), (7, Assignment.FrontOfHouse), (8, Assignment.FrontOfHouse) }, + seats: 48); + + // Accept far more demand than the kitchen can serve: walkouts. + public static ServicePlan Overcapacity(M0World w) => Plan("Overcapacity", + new[] { Item(w, 1), Item(w, 4), Item(w, 5), Item(w, 8), Item(w, 10) }, + new[] { (3, Assignment.Grill), (5, Assignment.Saute), (6, Assignment.Cold), (4, Assignment.Pastry), (8, Assignment.FrontOfHouse) }, + seats: 80); + + // Too few cooks for the seats and menu: kitchen falls behind. + public static ServicePlan Understaffed(M0World w) => Plan("Understaffed", + new[] { Item(w, 4), Item(w, 5), Item(w, 7), Item(w, 8) }, + new[] { (5, Assignment.Grill), (6, Assignment.Saute), (8, Assignment.FrontOfHouse) }, + seats: 50); + + // A mid-scale full-service dinner operation: a broader, coherent menu with a social-favourite + // main (roast chicken) and desserts, a double-staffed grill so two grill mains don't choke, and + // full front-of-house. Heavier labour than Focused Value, so it needs dinner check sizes to pay off. + public static ServicePlan BalancedCompetent(M0World w) => Plan("Balanced Competent", + new[] { Item(w, 1), Item(w, 4), Item(w, 5), Item(w, 8), Item(w, 10), Item(w, 12) }, + new[] { (3, Assignment.Grill), (5, Assignment.Grill), (2, Assignment.Saute), (4, Assignment.Pastry), + (6, Assignment.Cold), (7, Assignment.FrontOfHouse), (8, Assignment.FrontOfHouse) }, + seats: 46); + + // Premium prices the execution cannot back up: cheap low-skill crew on hard dishes. + public static ServicePlan OverpricedWeakExecution(M0World w) => Plan("Overpriced Weak Execution", + new[] { Item(w, 3, 12000), Item(w, 6, 12000), Item(w, 7, 12000), Item(w, 11, 12000) }, + new[] { (5, Assignment.Grill), (6, Assignment.Saute), (8, Assignment.Pastry), (7, Assignment.FrontOfHouse) }, + seats: 30); + + // Menu concentrated on one station: that station saturates while others idle. + public static ServicePlan StationBottleneck(M0World w) => Plan("Station Bottleneck", + new[] { Item(w, 4), Item(w, 5), Item(w, 6), Item(w, 1) }, + new[] { (3, Assignment.Grill), (6, Assignment.Cold), (7, Assignment.FrontOfHouse) }, + seats: 50); + + // Poor menu fit, poor assignments, overpriced: confirms failure is possible and legible. + public static ServicePlan IntentionallyBad(M0World w) => Plan("Intentionally Bad", + new[] { Item(w, 9, 14000), Item(w, 12, 14000) }, + new[] { (5, Assignment.Pastry), (8, Assignment.Cold), (7, Assignment.FrontOfHouse) }, + seats: 60); +} diff --git a/src/RestaurantSim.Core/TextReport.cs b/src/RestaurantSim.Core/TextReport.cs new file mode 100644 index 0000000..9c6803e --- /dev/null +++ b/src/RestaurantSim.Core/TextReport.cs @@ -0,0 +1,89 @@ +using System.Text; + +namespace RestaurantSim.Core; + +/// +/// Formats authoritative results into human-readable text. This is a read-model view: it only +/// reads ServiceResult / ForecastSnapshot and computes no new simulation truth. +/// +public static class TextReport +{ + private static string Pct(int bp) => (bp / 100) + "%"; + + public static string PlanSummary(M0World w, ServicePlan plan) + { + var sb = new StringBuilder(); + sb.AppendLine($"PLAN: {plan.Name}"); + sb.AppendLine($" Seats: {plan.Seats} Walk-in acceptance: {Pct(plan.WalkInAcceptanceBp)}"); + sb.AppendLine(" Menu:"); + foreach (var m in plan.Menu.OrderBy(m => w.Recipe(m.RecipeId).Course).ThenBy(m => m.RecipeId)) + { + var r = w.Recipe(m.RecipeId); + sb.AppendLine($" [{r.Course,-7}] {r.Name,-18} {new Money(m.PriceCents),8} (station {r.Station}, {r.ActiveMinutes}m, cost {new Money(r.IngredientCostCents)})"); + } + sb.AppendLine(" Crew:"); + foreach (var kv in plan.Assignments.OrderBy(k => k.Key)) + sb.AppendLine($" {w.Employee(kv.Key).Name,-7} -> {kv.Value}"); + return sb.ToString(); + } + + public static string Forecast(ForecastSnapshot f) + { + var sb = new StringBuilder(); + sb.AppendLine("FORECAST (committed before service; immutable):"); + sb.AppendLine($" Expected covers: {f.ExpectedCovers}"); + sb.AppendLine($" Expected revenue: {f.ExpectedRevenue}"); + sb.AppendLine($" Expected contribution: {f.ExpectedContribution} band [{f.ContributionLow} .. {f.ContributionHigh}] (confidence {Pct(f.ConfidenceBp)})"); + sb.AppendLine(" Key assumptions:"); + foreach (var a in f.KeyAssumptions) sb.AppendLine($" - {a}"); + return sb.ToString(); + } + + public static string Autopsy(M0World w, ServiceResult r, ForecastSnapshot? forecast = null) + { + var sb = new StringBuilder(); + sb.AppendLine($"====== POST-SERVICE AUTOPSY [{r.ScenarioId}] {r.PlanName} seed {r.Seed} ======"); + if (forecast != null) + { + long dc = r.Contribution.Cents - forecast.ExpectedContribution.Cents; + sb.AppendLine($"FORECAST vs ACTUAL:"); + sb.AppendLine($" Covers: forecast {forecast.ExpectedCovers,5} actual {r.CoversServed,5}"); + sb.AppendLine($" Contribution: forecast {forecast.ExpectedContribution,9} actual {r.Contribution,9} diff {new Money(dc)}"); + sb.AppendLine(); + } + sb.AppendLine("DEMAND FUNNEL:"); + sb.AppendLine($" Attempted parties (after market/pricing): {r.DemandGenerated}"); + sb.AppendLine($" Served parties: {r.PartiesServed} covers: {r.CoversServed}"); + sb.AppendLine($" Lost to seating/capacity: {r.LostToCapacity} walked out waiting: {r.LostToWait} no acceptable dish: {r.LostToMenuFit}"); + sb.AppendLine(); + sb.AppendLine("ECONOMY:"); + sb.AppendLine($" Revenue: {r.Revenue,9}"); + sb.AppendLine($" Ingredients: -{r.IngredientCost,9}"); + sb.AppendLine($" Labor: -{r.LaborCost,9}"); + sb.AppendLine($" Fixed overhead:-{r.FixedOverhead,9}"); + sb.AppendLine($" CONTRIBUTION: {r.Contribution,9} {(r.Profitable ? "(profit)" : "(LOSS)")}"); + sb.AppendLine(); + sb.AppendLine($"SERVICE: avg ticket {r.AvgTicketTimeMin} min service failures {r.ServiceFailures} menu-complexity load +{Pct(r.ComplexityPenaltyBp)} overall satisfaction {r.OverallSatisfaction}/1000"); + sb.AppendLine(); + sb.AppendLine("BY DISH:"); + sb.AppendLine($" {"dish",-18} {"ord",4} {"dlv",4} {"fail",4} {"qual",5} {"revenue",9} {"contrib",9}"); + foreach (var d in r.Dishes) + sb.AppendLine($" {d.Name,-18} {d.Ordered,4} {d.Delivered,4} {d.Failed,4} {d.AvgQuality,5} {d.Revenue,9} {d.Contribution,9}"); + sb.AppendLine(); + sb.AppendLine("BY SEGMENT (satisfaction 0-1000; F=food W=wait S=service V=value):"); + foreach (var s in r.Segments) + sb.AppendLine($" {s.Name,-16} parties {s.Parties,3} covers {s.Covers,3} sat {s.AvgSatisfaction,4} (F{s.AvgFood} W{s.AvgWait} S{s.AvgService} V{s.AvgValue})"); + sb.AppendLine(); + sb.AppendLine("BY STATION (utilization / peak queue / dishes / staff):"); + foreach (var s in r.StationsOut) + sb.AppendLine($" {s.Name,-8} util {Pct(s.UtilizationBp),5} peakQ {s.PeakQueue,3} dishes {s.DishesProduced,4} staff {s.Staff}"); + sb.AppendLine(); + sb.AppendLine("CAUSAL SUMMARY:"); + sb.AppendLine($" {r.BottleneckCause}"); + var most = r.MostProfitableRecipeId > 0 ? w.Recipe(r.MostProfitableRecipeId).Name : "n/a"; + var least = r.LeastUsefulRecipeId > 0 ? w.Recipe(r.LeastUsefulRecipeId).Name : "n/a"; + sb.AppendLine($" Most profitable dish: {most} Least useful dish: {least} Highest-pressure station: {r.HighestPressureStation}"); + sb.AppendLine($" checksum: {r.Checksum:X16}"); + return sb.ToString(); + } +} diff --git a/src/RestaurantSim.Core/Tuning.cs b/src/RestaurantSim.Core/Tuning.cs new file mode 100644 index 0000000..a097101 --- /dev/null +++ b/src/RestaurantSim.Core/Tuning.cs @@ -0,0 +1,26 @@ +namespace RestaurantSim.Core; + +/// +/// Shared M0 tuning constants used by BOTH the live simulator and the forecaster, so the two +/// agree on capacity assumptions. Named on purpose; never inline a number that has a meaning. +/// +public static class Tuning +{ + /// + /// Concurrent dishes a single cook oversees at a station. A cook is not hands-on every second of + /// a dish's cook time (searing, roasting, resting are largely passive), so one cook advances + /// several covers at once. This is the M0 abstraction of active-vs-passive cook time. + /// + public const int SlotsPerCook = 4; + + /// Approximate minutes a party occupies its seats, used only by the forecaster's turn estimate. + public const int ForecastAvgDwellMin = 34; + + /// + /// Menu-complexity load (basis points added to ticket work and mistake chance) as a function of + /// menu breadth and average prep complexity. Shared so the simulator and forecaster never drift. + /// A tight menu (<=4 items) is free; a broad, prep-heavy menu pays a real throughput tax. + /// + public static int ComplexityBp(int menuSize, int avgPrep) + => FixedMath.Clamp(Math.Max(0, menuSize - 4) * 300 + avgPrep * 5 / 10, 0, 6500); +} diff --git a/src/RestaurantSim.Harness/Program.cs b/src/RestaurantSim.Harness/Program.cs new file mode 100644 index 0000000..16bd2bc --- /dev/null +++ b/src/RestaurantSim.Harness/Program.cs @@ -0,0 +1,165 @@ +using System.Text; +using RestaurantSim.Core; + +// M0 distribution / balance / determinism harness. Runs every named strategy across every market +// scenario over many seeds, and writes evidence to reports/. See docs/design/M0-BALANCE-HYPOTHESES.md. + +int seeds = 200; +string outDir = "reports"; +ulong baseSeed = 700_000UL; +for (int i = 0; i < args.Length; i++) +{ + if (args[i] == "--seeds" && i + 1 < args.Length) seeds = int.Parse(args[++i]); + else if (args[i] == "--out" && i + 1 < args.Length) outDir = args[++i]; + else if (args[i] == "--base" && i + 1 < args.Length) baseSeed = ulong.Parse(args[++i]); +} + +var world = M0Content.World(); +var scenarios = M0Content.Scenarios(); +var strategies = M0Strategies.All(world); +var sim = new ServiceSimulator(); + +Directory.CreateDirectory(Path.Combine(outDir, "balance")); +Directory.CreateDirectory(Path.Combine(outDir, "determinism")); +Directory.CreateDirectory(Path.Combine(outDir, "m0")); + +Console.WriteLine($"M0 harness: {strategies.Count} strategies x {scenarios.Count} scenarios x {seeds} seeds = {strategies.Count * scenarios.Count * seeds} services"); + +// results[scenarioId][strategyName] = per-seed metrics +var cells = new Dictionary<(string sc, string st), List>(); +foreach (var sc in scenarios) + foreach (var st in strategies) + { + var list = new List(seeds); + for (int i = 0; i < seeds; i++) list.Add(sim.Run(world, sc, st, baseSeed + (ulong)i)); + cells[(sc.Id, st.Name)] = list; + } + +// ---------- distribution report ---------- +var md = new StringBuilder(); +md.AppendLine("# M0 Balance / Distribution Report"); +md.AppendLine(); +md.AppendLine($"Generated by `RestaurantSim.Harness`. Seeds per cell: **{seeds}** (base seed {baseSeed}). "); +md.AppendLine("Contribution is per single service in integer cents rendered as dollars. \"win%\" = share of seeds "); +md.AppendLine("where this strategy had the highest contribution in that scenario (same seed compared across strategies)."); +md.AppendLine(); + +var winnerByScenario = new Dictionary(); +var viableByScenario = new Dictionary(); + +foreach (var sc in scenarios) +{ + // per-seed winner among strategies + var winCount = strategies.ToDictionary(s => s.Name, _ => 0); + for (int i = 0; i < seeds; i++) + { + string best = ""; long bestC = long.MinValue; + foreach (var st in strategies) + { + long c = cells[(sc.Id, st.Name)][i].Contribution.Cents; + if (c > bestC) { bestC = c; best = st.Name; } + } + winCount[best]++; + } + + md.AppendLine($"## {sc.Name} (`{sc.Id}`)"); + md.AppendLine(); + md.AppendLine($"_{sc.Notes}_"); + md.AppendLine(); + md.AppendLine("| Strategy | median contrib | p10 | p90 | loss% | avg covers | avg sat | avg ticket | win% |"); + md.AppendLine("|---|--:|--:|--:|--:|--:|--:|--:|--:|"); + + var rows = new List<(string name, long median, long contribAvg, int sat)>(); + foreach (var st in strategies) + { + var rs = cells[(sc.Id, st.Name)]; + var contribs = rs.Select(r => r.Contribution.Cents).OrderBy(x => x).ToList(); + long median = Percentile(contribs, 50), p10 = Percentile(contribs, 10), p90 = Percentile(contribs, 90); + int lossPct = (int)(rs.Count(r => r.Contribution.Cents < 0) * 100.0 / rs.Count); + int avgCov = (int)rs.Average(r => r.CoversServed); + int avgSat = (int)rs.Average(r => r.OverallSatisfaction); + int avgTicket = (int)rs.Average(r => r.AvgTicketTimeMin); + int winPct = (int)(winCount[st.Name] * 100.0 / seeds); + rows.Add((st.Name, median, median, avgSat)); + md.AppendLine($"| {st.Name} | {new Money(median)} | {new Money(p10)} | {new Money(p90)} | {lossPct}% | {avgCov} | {avgSat} | {avgTicket}m | {winPct}% |"); + } + + var ordered = rows.OrderByDescending(r => r.median).ToList(); + winnerByScenario[sc.Id] = ordered[0].name; + // "viable" = a strategy that runs a clearly profitable service (median contribution >= +$150) + const long viableThreshold = 15000; + int viable = ordered.Count(r => r.median >= viableThreshold); + viableByScenario[sc.Id] = viable; + md.AppendLine(); + md.AppendLine($"**Winner:** {ordered[0].name} · **profitable strategies (median >= +$150):** {viable}"); + md.AppendLine(); +} + +// dominance verdict +var distinctWinners = winnerByScenario.Values.Distinct().Count(); +md.AppendLine("## Dominance check"); +md.AppendLine(); +foreach (var kv in winnerByScenario) md.AppendLine($"- **{kv.Key}** best strategy: `{kv.Value}`"); +md.AppendLine(); +bool oneDominates = distinctWinners == 1; +md.AppendLine($"Distinct winning strategies across scenarios: **{distinctWinners}** of {scenarios.Count}. " + + (oneDominates + ? "⚠️ One strategy wins everywhere — a possible dominance problem to investigate." + : "No single strategy wins across all markets: context changes the best plan. ✅")); +File.WriteAllText(Path.Combine(outDir, "balance", "distribution.md"), md.ToString()); + +// ---------- determinism report ---------- +var det = new StringBuilder(); +det.AppendLine("# M0 Determinism Report"); +det.AppendLine(); +det.AppendLine("Each row runs the SAME (scenario, strategy, seed) twice and compares the authoritative state checksum."); +det.AppendLine("A management sim that promises \"same seed reproduces the same result\" must pass this. See DETERMINISM-CONTRACT.md."); +det.AppendLine(); +det.AppendLine("| Scenario | Strategy | Seed | Checksum run 1 | Checksum run 2 | Match |"); +det.AppendLine("|---|---|--:|---|---|:--:|"); +bool allMatch = true; +ulong exampleSeed = baseSeed + 42; +foreach (var sc in scenarios) + foreach (var st in strategies.Take(3)) + { + var a = sim.Run(world, sc, st, exampleSeed); + var b = sim.Run(world, sc, st, exampleSeed); + bool m = a.Checksum == b.Checksum; + allMatch &= m; + det.AppendLine($"| {sc.Id} | {st.Name} | {exampleSeed} | `{a.Checksum:X16}` | `{b.Checksum:X16}` | {(m ? "✅" : "❌")} |"); + } +det.AppendLine(); +det.AppendLine(allMatch ? "**All checksums matched: determinism holds for the sampled matrix.**" + : "**MISMATCH DETECTED: determinism is broken. This is a blocking failure.**"); +File.WriteAllText(Path.Combine(outDir, "determinism", "checksums.md"), det.ToString()); + +// ---------- example forecast-vs-actual ---------- +var exScenario = scenarios.First(s => s.Id == "social-dinner"); +var exPlan = strategies.First(s => s.Name == "Balanced Competent"); +var exForecast = Forecaster.Compute(world, exScenario, exPlan); +var exResult = sim.Run(world, exScenario, exPlan, exampleSeed, new SimOptions(true)); +var ex = new StringBuilder(); +ex.AppendLine(TextReport.PlanSummary(world, exPlan)); +ex.AppendLine(TextReport.Forecast(exForecast)); +ex.AppendLine("SERVICE LOG (sampled):"); +foreach (var l in exResult.ServiceLog) ex.AppendLine(" " + l); +ex.AppendLine(); +ex.AppendLine(TextReport.Autopsy(world, exResult, exForecast)); +File.WriteAllText(Path.Combine(outDir, "m0", "example-forecast-vs-actual.txt"), ex.ToString()); + +// ---------- console summary ---------- +Console.WriteLine(); +Console.WriteLine("=== SUMMARY ==="); +foreach (var kv in winnerByScenario) + Console.WriteLine($" {kv.Key,-20} winner: {kv.Value,-24} viable strategies: {viableByScenario[kv.Key]}"); +Console.WriteLine($" distinct winners across scenarios: {distinctWinners}/{scenarios.Count} {(oneDominates ? "DOMINANCE RISK" : "no single dominant strategy")}"); +Console.WriteLine($" determinism: {(allMatch ? "PASS" : "FAIL")} example seed {exampleSeed} checksum {exResult.Checksum:X16}"); +Console.WriteLine($" reports written under: {outDir}/"); +return allMatch ? 0 : 1; + +static long Percentile(List sortedAsc, int pct) +{ + if (sortedAsc.Count == 0) return 0; + int idx = (int)Math.Clamp((long)pct * (sortedAsc.Count - 1) / 100, 0, sortedAsc.Count - 1); + return sortedAsc[idx]; +} diff --git a/src/RestaurantSim.Harness/RestaurantSim.Harness.csproj b/src/RestaurantSim.Harness/RestaurantSim.Harness.csproj new file mode 100644 index 0000000..0e5df78 --- /dev/null +++ b/src/RestaurantSim.Harness/RestaurantSim.Harness.csproj @@ -0,0 +1,14 @@ + + + + + + + + Exe + net8.0 + enable + enable + + + diff --git a/tests/RestaurantSim.Core.Tests/InvariantTests.cs b/tests/RestaurantSim.Core.Tests/InvariantTests.cs new file mode 100644 index 0000000..693fa17 --- /dev/null +++ b/tests/RestaurantSim.Core.Tests/InvariantTests.cs @@ -0,0 +1,132 @@ +using RestaurantSim.Core; +using Xunit; + +namespace RestaurantSim.Core.Tests; + +public class NumericsTests +{ + [Fact] + public void Money_arithmetic_is_exact_integer_cents() + { + Assert.Equal(1234, Money.FromDollars(12).Cents + 34); + Assert.Equal(new Money(1500), new Money(1000) + new Money(500)); + Assert.Equal(new Money(500), new Money(1000) - new Money(500)); + Assert.Equal(new Money(3000), new Money(1000) * 3); + } + + [Theory] + [InlineData(1000, 7525, 753)] // 75.25% of 1000 = 752.5 -> 753 (round half away from zero) + [InlineData(1000, 5000, 500)] + [InlineData(-1000, 5000, -500)] + public void ApplyBp_rounds_half_away_from_zero(long cents, int bp, long expected) + => Assert.Equal(expected, new Money(cents).ApplyBp(bp).Cents); + + [Fact] + public void MulDivRound_uses_128bit_intermediate_without_overflow() + { + long big = 9_000_000_000L; // > int range + Assert.Equal(4_500_000_000L, FixedMath.MulDivRound(big, 5000, 10000)); + } +} + +public class RngIsolationTests +{ + [Fact] + public void Entity_streams_are_independent_adding_draws_to_one_does_not_shift_another() + { + var rng = new RngStreams(0xABCDEF); + // party 1's sequence captured directly + var p1 = rng.For(RngStream.Party, 1); + var seq1 = new[] { p1.NextU64(), p1.NextU64(), p1.NextU64() }; + + // consume a bunch of draws from party 2 and other streams in between + var p2 = rng.For(RngStream.Party, 2); + for (int i = 0; i < 50; i++) p2.NextU64(); + var arr = rng.For(RngStream.Arrivals, 1); + for (int i = 0; i < 50; i++) arr.NextU64(); + + // party 1's sequence must be identical when re-derived + var p1b = rng.For(RngStream.Party, 1); + var seq2 = new[] { p1b.NextU64(), p1b.NextU64(), p1b.NextU64() }; + Assert.Equal(seq1, seq2); + } + + [Fact] + public void Different_streams_and_keys_produce_different_sequences() + { + var rng = new RngStreams(42); + Assert.NotEqual(rng.For(RngStream.Party, 1).NextU64(), rng.For(RngStream.Arrivals, 1).NextU64()); + Assert.NotEqual(rng.For(RngStream.Party, 1).NextU64(), rng.For(RngStream.Party, 2).NextU64()); + } +} + +public class EconomyReconciliationTests +{ + public static IEnumerable AllCombos() + { + var w = M0Content.World(); + foreach (var sc in M0Content.Scenarios()) + foreach (var st in M0Strategies.All(w)) + yield return new object[] { st.Name, sc.Id }; + } + + [Theory] + [MemberData(nameof(AllCombos))] + public void Contribution_and_dish_totals_reconcile_exactly(string strategyName, string scenarioId) + { + var w = M0Content.World(); + var sc = M0Content.Scenario(scenarioId); + var plan = M0Strategies.All(w).First(s => s.Name == strategyName); + var r = new ServiceSimulator().Run(w, sc, plan, 700042); + + // contribution reconciles to the ledger + Assert.Equal( + r.Revenue.Cents - r.IngredientCost.Cents - r.LaborCost.Cents - r.FixedOverhead.Cents, + r.Contribution.Cents); + + // per-dish revenue and ingredient sum to the authoritative totals (comps already excluded) + Assert.Equal(r.Revenue.Cents, r.Dishes.Sum(d => d.Revenue.Cents)); + Assert.Equal(r.IngredientCost.Cents, r.Dishes.Sum(d => d.IngredientCost.Cents)); + + // no negative or impossible values in the funnel + Assert.True(r.PartiesServed >= 0 && r.CoversServed >= 0); + Assert.True(r.LostToCapacity >= 0 && r.LostToWait >= 0 && r.LostToMenuFit >= 0); + Assert.InRange(r.OverallSatisfaction, 0, 1000); + foreach (var s in r.StationsOut) Assert.InRange(s.UtilizationBp, 0, 10000); + foreach (var s in r.Segments) Assert.InRange(s.AvgSatisfaction, 0, 1000); + } + + [Fact] + public void A_botched_dish_is_comped_no_revenue_but_ingredient_is_paid() + { + // Overpriced Weak Execution puts low-skill cooks on hard dishes -> failures -> comps. + var w = M0Content.World(); + var sc = M0Content.Scenario("enthusiast-evening"); + var plan = M0Strategies.OverpricedWeakExecution(w); + var r = new ServiceSimulator().Run(w, sc, plan, 700042); + Assert.True(r.ServiceFailures > 0, "expected some failures from weak execution"); + // failed dishes consumed ingredients but earned no revenue: total ingredient exceeds a naive + // revenue/price expectation. We assert the ledger still reconciles (already covered) and that + // dishes with failures have delivered>=... revenue reflects only non-failed. + foreach (var d in r.Dishes) + Assert.True(d.Revenue.Cents >= 0); + } +} + +public class ForecastTests +{ + [Fact] + public void Forecast_is_computed_from_pre_service_info_and_is_stable_across_a_run() + { + var w = M0Content.World(); + var sc = M0Content.Scenario("social-dinner"); + var plan = M0Strategies.BalancedCompetent(w); + var f1 = Forecaster.Compute(w, sc, plan); + _ = new ServiceSimulator().Run(w, sc, plan, 700042); + var f2 = Forecaster.Compute(w, sc, plan); + // running the service must not change what the forecast computes (no post-hoc recompute) + Assert.Equal(f1.ExpectedCovers, f2.ExpectedCovers); + Assert.Equal(f1.ExpectedContribution.Cents, f2.ExpectedContribution.Cents); + Assert.Equal(f1.ExpectedRevenue.Cents, f2.ExpectedRevenue.Cents); + } +} diff --git a/tests/RestaurantSim.Core.Tests/RestaurantSim.Core.Tests.csproj b/tests/RestaurantSim.Core.Tests/RestaurantSim.Core.Tests.csproj new file mode 100644 index 0000000..20847b0 --- /dev/null +++ b/tests/RestaurantSim.Core.Tests/RestaurantSim.Core.Tests.csproj @@ -0,0 +1,27 @@ + + + + net8.0 + enable + enable + + false + true + + + + + + + + + + + + + + + + + + diff --git a/tests/RestaurantSim.Determinism.Tests/DeterminismTests.cs b/tests/RestaurantSim.Determinism.Tests/DeterminismTests.cs new file mode 100644 index 0000000..aadb65b --- /dev/null +++ b/tests/RestaurantSim.Determinism.Tests/DeterminismTests.cs @@ -0,0 +1,105 @@ +using System.Reflection; +using System.Text.RegularExpressions; +using RestaurantSim.Core; +using Xunit; + +namespace RestaurantSim.Determinism.Tests; + +public class ChecksumDeterminismTests +{ + public static IEnumerable Matrix() + { + var w = M0Content.World(); + foreach (var sc in M0Content.Scenarios()) + foreach (var st in M0Strategies.All(w)) + yield return new object[] { st.Name, sc.Id }; + } + + [Theory] + [MemberData(nameof(Matrix))] + public void Same_seed_and_commands_reproduce_the_same_checksum(string strategyName, string scenarioId) + { + var w = M0Content.World(); + var sc = M0Content.Scenario(scenarioId); + var plan = M0Strategies.All(w).First(s => s.Name == strategyName); + var sim = new ServiceSimulator(); + var a = sim.Run(w, sc, plan, 700_042); + var b = sim.Run(w, sc, plan, 700_042); + Assert.Equal(a.Checksum, b.Checksum); + // and the full record equals itself value-wise on the headline numbers + Assert.Equal(a.Contribution.Cents, b.Contribution.Cents); + Assert.Equal(a.CoversServed, b.CoversServed); + } + + [Fact] + public void Different_seeds_generally_produce_different_outcomes() + { + var w = M0Content.World(); + var sc = M0Content.Scenario("social-dinner"); + var plan = M0Strategies.BalancedCompetent(w); + var sim = new ServiceSimulator(); + var checksums = Enumerable.Range(0, 20).Select(i => sim.Run(w, sc, plan, 700_000UL + (ulong)i).Checksum).ToHashSet(); + Assert.True(checksums.Count > 1, "seeds should produce a distribution, not a single fixed outcome"); + } +} + +public class NumericStrategyTests +{ + /// The determinism contract bans binary floating point from authoritative state. + [Fact] + public void No_authoritative_field_in_Core_uses_float_double_or_decimal() + { + var asm = typeof(ServiceSimulator).Assembly; + var banned = new[] { typeof(float), typeof(double), typeof(decimal) }; + var offenders = new List(); + foreach (var type in asm.GetTypes()) + { + foreach (var f in type.GetFields(BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Instance)) + if (banned.Contains(f.FieldType)) + offenders.Add($"{type.FullName}.{f.Name} : {f.FieldType.Name}"); + } + Assert.True(offenders.Count == 0, "float/double/decimal in authoritative Core fields:\n" + string.Join("\n", offenders)); + } +} + +public class CoreSourceScanTests +{ + private static string CoreSourceDir() + { + var di = new DirectoryInfo(AppContext.BaseDirectory); + while (di != null && !Directory.Exists(Path.Combine(di.FullName, "src", "RestaurantSim.Core"))) + di = di.Parent; + Assert.NotNull(di); + return Path.Combine(di!.FullName, "src", "RestaurantSim.Core"); + } + + [Fact] + public void Core_does_not_read_the_wall_clock_or_use_system_random() + { + var banned = new[] + { + "DateTime.Now", "DateTime.UtcNow", "DateTimeOffset.Now", "DateTimeOffset.UtcNow", + "Environment.TickCount", "Stopwatch", "System.Random", "new Random" + }; + var offenders = new List(); + foreach (var file in Directory.GetFiles(CoreSourceDir(), "*.cs", SearchOption.AllDirectories)) + { + var code = StripCommentsAndStrings(File.ReadAllText(file)); + foreach (var b in banned) + if (code.Contains(b)) + offenders.Add($"{Path.GetFileName(file)} contains '{b}'"); + } + Assert.True(offenders.Count == 0, "banned non-deterministic API in Core:\n" + string.Join("\n", offenders)); + } + + // The scan is about executable code, not documentation. Strip block/line comments and string + // literals so a comment like "never use System.Random" does not trip the guard. + private static string StripCommentsAndStrings(string s) + { + s = Regex.Replace(s, @"/\*.*?\*/", " ", RegexOptions.Singleline); + s = Regex.Replace(s, @"//[^\n]*", " "); + s = Regex.Replace(s, "@\"(?:[^\"]|\"\")*\"", " "); // verbatim strings + s = Regex.Replace(s, "\"(?:\\\\.|[^\"\\\\])*\"", " "); // regular strings + return s; + } +} diff --git a/tests/RestaurantSim.Determinism.Tests/RestaurantSim.Determinism.Tests.csproj b/tests/RestaurantSim.Determinism.Tests/RestaurantSim.Determinism.Tests.csproj new file mode 100644 index 0000000..20847b0 --- /dev/null +++ b/tests/RestaurantSim.Determinism.Tests/RestaurantSim.Determinism.Tests.csproj @@ -0,0 +1,27 @@ + + + + net8.0 + enable + enable + + false + true + + + + + + + + + + + + + + + + + + diff --git a/tests/RestaurantSim.Scenario.Tests/RestaurantSim.Scenario.Tests.csproj b/tests/RestaurantSim.Scenario.Tests/RestaurantSim.Scenario.Tests.csproj new file mode 100644 index 0000000..20847b0 --- /dev/null +++ b/tests/RestaurantSim.Scenario.Tests/RestaurantSim.Scenario.Tests.csproj @@ -0,0 +1,27 @@ + + + + net8.0 + enable + enable + + false + true + + + + + + + + + + + + + + + + + + diff --git a/tests/RestaurantSim.Scenario.Tests/ScenarioTests.cs b/tests/RestaurantSim.Scenario.Tests/ScenarioTests.cs new file mode 100644 index 0000000..c7a92b2 --- /dev/null +++ b/tests/RestaurantSim.Scenario.Tests/ScenarioTests.cs @@ -0,0 +1,93 @@ +using RestaurantSim.Core; +using Xunit; + +namespace RestaurantSim.Scenario.Tests; + +/// Golden scenarios: fixed restaurant, fixed seed, fixed commands, locked expected checksum. +public class GoldenScenarioTests +{ + [Theory] + [InlineData("Focused Value", "lunch-rush", 0xF07AA46F729A0A8FUL)] + [InlineData("Premium Craft", "enthusiast-evening", 0x24EE4A83E7436797UL)] + [InlineData("Balanced Competent", "social-dinner", 0x7C4703D4A5375AF5UL)] + public void Golden_checksums_are_stable(string strategyName, string scenarioId, ulong expected) + { + var w = M0Content.World(); + var sc = M0Content.Scenario(scenarioId); + var plan = M0Strategies.All(w).First(s => s.Name == strategyName); + var r = new ServiceSimulator().Run(w, sc, plan, 700_042); + Assert.Equal(expected, r.Checksum); + } +} + +/// +/// Encodes the M0 balance bar as tests: no single strategy dominates every market, deliberately-bad +/// strategies never win, and premium is not always best. See docs/design/M0-BALANCE-HYPOTHESES.md. +/// +public class BalancePropertyTests +{ + private const int Seeds = 40; + private static readonly string[] Reasonable = + { "Focused Value", "Premium Craft", "Balanced Competent", "Broad Menu" }; + private static readonly string[] DeliberatelyBad = + { "Understaffed", "Intentionally Bad", "Overpriced Weak Execution", "Overcapacity", "Station Bottleneck" }; + + private static Dictionary MedianContribByStrategy(string scenarioId) + { + var w = M0Content.World(); + var sc = M0Content.Scenario(scenarioId); + var sim = new ServiceSimulator(); + var result = new Dictionary(); + foreach (var st in M0Strategies.All(w)) + { + var contribs = Enumerable.Range(0, Seeds) + .Select(i => sim.Run(w, sc, st, 700_000UL + (ulong)i).Contribution.Cents) + .OrderBy(x => x).ToList(); + result[st.Name] = contribs[contribs.Count / 2]; + } + return result; + } + + private static string Winner(string scenarioId) + => MedianContribByStrategy(scenarioId).OrderByDescending(kv => kv.Value).First().Key; + + [Fact] + public void No_single_strategy_wins_every_market() + { + var winners = M0Content.Scenarios().Select(s => Winner(s.Id)).Distinct().ToList(); + Assert.True(winners.Count >= 2, "one strategy dominates every scenario: " + string.Join(",", winners)); + } + + [Fact] + public void Winners_are_always_reasonable_strategies_never_the_deliberately_bad_ones() + { + foreach (var sc in M0Content.Scenarios()) + { + var winner = Winner(sc.Id); + Assert.Contains(winner, Reasonable); + Assert.DoesNotContain(winner, DeliberatelyBad); + } + } + + [Fact] + public void Premium_is_not_always_best_it_loses_the_value_lunch() + { + Assert.NotEqual("Premium Craft", Winner("lunch-rush")); + } + + [Fact] + public void Deliberately_bad_strategies_lose_money_in_the_high_volume_lunch() + { + var med = MedianContribByStrategy("lunch-rush"); + foreach (var bad in new[] { "Understaffed", "Intentionally Bad", "Overpriced Weak Execution" }) + Assert.True(med[bad] < 0, $"{bad} should lose money at the lunch rush but median was {med[bad]}"); + } + + [Fact] + public void At_least_one_market_supports_multiple_profitable_strategies() + { + bool any = M0Content.Scenarios() + .Any(sc => MedianContribByStrategy(sc.Id).Values.Count(v => v >= 15000) >= 2); + Assert.True(any, "expected at least one scenario with >=2 clearly profitable strategies"); + } +} diff --git a/tools/README.md b/tools/README.md new file mode 100644 index 0000000..551b79f --- /dev/null +++ b/tools/README.md @@ -0,0 +1,6 @@ +# tools/ + +Reserved for developer tooling in later milestones (recipe validator, ingredient-network viewer, +station-load calculator, scenario editor, save inspector, deterministic replay viewer, etc. — master plan +§12.13). **Not built in M0.** In M0, the `RestaurantSim.Harness` project is the only tool, and it lives +under `src/` because it shares the simulation core directly.