Main Street Scenario & Tutorial

[SorraTheOrc]

Main Street Scenario & Tutorial — Intake Draft

Problem statement

Create a playable, one-row "Main Street" scenario (1×10 street presented as responsive 2×5 grid) with a lightweight, non-interactive tutorial overlay and a deterministic smoke-test harness so new players can experience the core loop and contributors can run a reproducible demo.

Users

• New players who want a short, guided introduction to Main Street (user story: "As a new player I want an on-screen guided hint so I can learn where to buy cards and how to place them without reading external docs").
• Developers and CI maintainers who need a fast, deterministic smoke test (user story: "As a contributor I want a reproducible headless demo/test I can run locally or in CI to validate the core loop").
• Playtesters who need a consistent baseline scenario to validate balance and tutorial text.

Success criteria

• Playable one-row Main Street scenario that runs end-to-end in the game UI (desktop viewport) and is accessible via the Game Selector with a clear label "Scenario: Tutorial".
• Tutorial overlays implemented as non-interactive overlays/tooltips that highlight main UI regions (market, street slots, hand, action controls) and can be toggled on/off.
• Deterministic smoke test(s): (a) demo script (scripts/demo-main-street.ts) can run with a supplied seed (e.g. "smoke-1") and complete without errors; (b) a short headless integration test runs a fixed-seed session and asserts the run completes and the final run summary fields exist (and optionally match a golden value).
• UI and tutorial copy is discoverable in-game and included in docs; all strings are localizable (no hard-coded text embedded in unreachable code paths).
• All related documentation is updated to reflect the changes, including code comments, README, and any relevant wiki or docs site entries.
• Full project test suite passes with the new changes.

Constraints

• Must reuse Main Street engine pieces (example-games/main-street/*) and avoid adding new global-engine APIs unless absolutely necessary.
• Tutorial overlays must be implemented with the existing Overlay/HUD helpers (src/ui/Overlay.ts, MainStreetRenderer) and should not require a new renderer layer that breaks other games.
• Use only permissive or CC0 assets; do not add proprietary assets.
• Smoke tests must be deterministic given a seed and must not rely on network or external services.
• Keep scope limited to a single scenario and non-interactive overlays; interactive walkthroughs or branching tutorial flows should be captured as separate work items if desired.

Existing state

• Parent epic: "Main Street" (CG-0MM4R9UJF1DGI0ZF) contains full concept and PRDs.
• Code & artifacts already present: example-games/main-street/* (game state, engine, scenes, renderer, demo scripts), scripts/demo-main-street.ts, scripts/save-load-smoke.ts, scripts/playtest-scenarios.ts, tests/main-street/* (extensive unit and integration tests), docs/main-street/* (card catalog, dimensions, PRDs).
• Current work item: CG-0MM5ZGB8U02S0BFO titled "Main Street Scenario & Tutorial" (stage: idea).

Desired change

• Implement a self-contained scenario entry in the Game Selector labelled "Scenario: Tutorial" that launches Main Street in a simplified setup optimized for learning (fewer turns, reduced deck complexity).
• Add non-interactive tutorial overlays (tooltips + highlight boxes) covering: market, street slots, hand, action controls, end-turn flow, and scoring summary. Overlays must be dismissible and toggleable.
• Wire the demo script(s) to provide a canonical seed ("smoke-1") and document how to run the smoke test locally and in CI.
• Add a headless integration test that runs the scenario for a fixed seed and validates the run completes and emits expected summary fields.
• Update docs (docs/main-street/playtest-scenarios.md and README.md) and add a short developer note on how to add or update tutorial text.

Related work

Potentially related docs

• docs/main-street/playtest-scenarios.md — playtest runner & scenario guidance
• docs/main-street/card-catalog.md — card pool & balancing reference
• docs/main-street/card-dimensions.md — rendering/layout guidance

Potentially related code

• example-games/main-street/ — all Main Street game code (state, engine, scenes, renderer)
• scripts/demo-main-street.ts — deterministic demo runner (use as basis for smoke test)
• scripts/save-load-smoke.ts — save/load smoke harness
• scripts/playtest-scenarios.ts — scenario runner and examples
• src/ui/Overlay.ts — HUD/overlay helpers
• example-games/main-street/scenes/MainStreetRenderer.ts — UI renderer and layout helpers

Potentially related work items

• Main Street (CG-0MM4R9UJF1DGI0ZF) — parent epic: full Main Street program

Appendix: Clarifying questions & answers

• Q: "Win condition (choose one or give a custom answer)" — Answer (user): "A) Reach a target score"; Final: A. Source: interactive reply.
• Q: "Tutorial format (choose one or specify)" — Answer (user): "A) Non-interactive overlay hints (tooltips + highlight areas)"; Final: A. Source: interactive reply.
• Q: "Deterministic smoke test details (choose one or specify)" — Answer (user): "C) Both A and B" (use demo script with seed and add a headless integration test); Final: C. Source: interactive reply.

Notes and evidence

• The repository already contains scripts/demo-main-street.ts and multiple main-street tests (tests/main-street/*) that can be used as references for the smoke-test and headless test harness.

OPEN QUESTIONS

• Tutorial copy: who will author and review the tutorial text for clarity and tone? (OPEN QUESTION: directed to the Game Designer / Product Owner). Marked open because the user did not provide a copy or author.

-- End of intake draft --

Acceptance Criteria Addendum (2026-05-13)

To align delivery with the current PR scope and preserve traceability:

• The localization implementation requirement is split into child work item Main Street tutorial localization and i18n externalization (CG-0MP415DUV0032SKK), stage plan_complete.
• Parent criterion "UI and tutorial copy is discoverable in-game and included in docs; all strings are localizable" remains valid for discoverability/docs in this parent item, while i18n externalization implementation is tracked and completed in the child item above.

This addendum clarifies acceptance evaluation and does not remove any existing criteria.

[SorraTheOrc]

Map

Effort and risk estimate (agent): Effort: Small (2-4 developer-days). Big risks: 1) Tutorial copy ownership (missing author) may delay completion; 2) Overlay implementation may require small Renderer/Overlay adjustments if existing helpers don't expose needed anchors; 3) Deterministic tests may need small updates to RNG seeding or golden values. Mitigation: capture ownership as an OPEN QUESTION, reuse existing Overlay/HUD helpers, keep smoke test assertions permissive (existence of summary fields) when first landing.

[SorraTheOrc]

wl-delegate

Failed to assign @copilot to GitHub issue #114: GraphQL: Could not resolve to an issue or pull request with the number of 114. (repository.issue). Local state was not updated.

[SorraTheOrc]

Map

Cleared GitHub issue link: removed githubIssueNumber 114 because GitHub lookup for issue #114 could not be resolved. Imported updated work item to clear the mapping.

[SorraTheOrc]

wl-delegate

Failed to assign @copilot to GitHub issue #464: failed to update #464: '@copilot' not found
failed to update 1 issue. Local state was not updated.