From 6a927e176c01b28febbb8a4b6e33f9f0f4dfac7e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 23 May 2026 15:48:23 +0000 Subject: [PATCH] docs: sync repo docs with mechanika v1 Agent-Logs-Url: https://github.com/diwad-code/SpaceshipGame/sessions/9426ef6f-fab0-408a-9118-06525e306954 Co-authored-by: diwad-code <250159374+diwad-code@users.noreply.github.com> --- README.md | 24 +++++----- docs/ARCHITECTURE.md | 32 +++++++------- docs/COPILOT_WORKFLOW.md | 94 +++++++++++++++++++++------------------ docs/FABULA.md | 11 ++--- docs/GDD.md | 84 ++++++++++++++++++++++------------- docs/SCOPE.md | 96 ++++++++++++++++++++++------------------ 6 files changed, 195 insertions(+), 146 deletions(-) diff --git a/README.md b/README.md index 2681722..2e8c241 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Retro pixel-art game about managing a spaceship mission searching for life. The ## Current status -Pre-initialization / Sprint 0. No production code has been scaffolded yet. The `claude_tips/`, `dodatki/research/`, and `dodatki/skills/` folders are treated as reference material, not project source of truth. The `mechanika/` folder is reserved for the final gameplay mechanics specification and currently must not be invented around. +Sprint 0 / preproduction. No production code has been scaffolded yet, but `mechanika/` now contains gameplay specification v1.0 plus the remaining implementation blockers and open questions. The `claude_tips/`, `dodatki/research/`, and `dodatki/skills/` folders are still treated as reference material, not project source of truth. ## Approved stack @@ -24,7 +24,7 @@ Pre-initialization / Sprint 0. No production code has been scaffolded yet. The ` - `docs/CREATIVE_INPUTS.md` — how to use the new creative research pack and external skill library in `dodatki/`. - `docs/GAME_BRIEF.md` — durable product and mission brief before implementation expands. - `docs/FABULA.md` — story bible and narrative canon kept separate from gameplay rules. -- `docs/GDD.md` — structured design document linking brief, fabula, scope, and mechanika placeholders. +- `docs/GDD.md` — structured design document synchronized with the current brief, fabula, scope, and mechanika v1.0. - `docs/SCOPE.md` — what is and is not in the MVP. - `docs/IDEAS_LATER.md` — deferred ideas and scope-control list. - `docs/COPILOT_WORKFLOW.md` — natural-language guide for using `/game-dev`, `/game-brief`, `/fabula`, `/gdd`, and related prompts. @@ -36,13 +36,15 @@ Pre-initialization / Sprint 0. No production code has been scaffolded yet. The ` - `dodatki/skills/` — raw external skill library to review before adapting items into `.github/skills/incoming/`. - `.github/prompts/skills-adoption.prompt.md` — autonomous prompt for executing the skills/MCP adoption plan. - `.github/copilot-instructions.md` — always-on Copilot project rules. -- `mechanika/00-template-do-wypelnienia.md` — form to fill in with final gameplay mechanics. +- `mechanika/README.md` — guide to the mechanics folder and its intended use. +- `mechanika/00-overview.md` — one-file entry point to the current mechanics spec. +- `mechanika/99-open-questions.md` — implementation blockers and unresolved design decisions. ## Co dalej? Ta część ma być aktualizowana na bieżąco, tak aby kolejna osoba mogła przejąć projekt bez wcześniejszego kontekstu. -Aktualnie projekt jest w Sprint 0: porządkowana jest dokumentacja, workflow Copilota i materiały wejściowe. Nie ma jeszcze `package.json`, katalogu `src/` ani uruchamialnej wersji gry. Zestaw rekomendowanych skillów został już rozdzielony na aktywne lokalne skille i staged intake w `.github/skills/incoming/`, żeby przed dalszą pracą nad fabułą było jasne, co jest gotowe teraz, a co czeka na kolejne bramki. +Aktualnie projekt nadal jest w Sprint 0: nie ma jeszcze `package.json`, katalogu `src/` ani uruchamialnej wersji gry. Zmieniło się jednak to, że `mechanika/` jest już wypełniona i stała się głównym źródłem prawdy dla gameplayu. Najbliższa praca to synchronizacja dokumentów, zamknięcie krytycznych pytań z `mechanika/99-open-questions.md`, a potem scaffold projektu Vite + Phaser 4 zgodnie z `docs/ARCHITECTURE.md`. Najbliższe kroki: @@ -50,19 +52,21 @@ Najbliższe kroki: 2. Przeczytaj najpierw: - `docs/GAME_BRIEF.md` — czym ma być gra, - `docs/FABULA.md` — aktualny kanon fabularny, - - `docs/GDD.md` — uporządkowany projekt gry, + - `docs/GDD.md` — aktualny plan implementacyjny i stan designu, + - `mechanika/00-overview.md` — skrót całej mechaniki v1.0, + - `mechanika/99-open-questions.md` — pytania blokujące start implementacji, - `docs/ARCHITECTURE.md` — zasady techniczne i miejsca przyszłej integracji. 3. Używaj komend Copilota zgodnych z polem `name:` w plikach `.github/prompts/`: - `/game-dev` — sprawdzenie stanu repo i wybór kolejnych 1-3 kroków, - `/game-brief` — dopracowanie trwałego opisu projektu, - - `/fabula` — rozwijanie biblii fabularnej przed zamknięciem mechanik, - - `/gdd` — utrzymanie dokumentu projektowego w zgodzie z briefem i fabułą, + - `/fabula` — utrzymanie i dopracowanie biblii fabularnej, + - `/gdd` — utrzymanie dokumentu projektowego w zgodzie z briefem, fabułą i mechaniką, - `/skills-adoption` — wdrażanie zatwierdzonych skillów i MCP z dokumentacji, - `/investigate`, `/new-scene`, `/new-system`, `/new-event`, `/data-schema`, `/pwa-check`, `/mobile-ux`, `/code-review`. -4. W Sprint 0 trzymaj kolejność pracy: `/game-dev` → `/game-brief` → `/fabula` → `/gdd` → `/skills-adoption`. Skill packages wymagające aplikacji, CI albo pipeline'u art nadal zostają w `.github/skills/incoming/` do czasu odblokowania tych bramek. -5. Nie wymyślaj jeszcze szczegółowych mechanik walki, traitów, morale, progresji, frakcji ani łańcuchów questów. Te reguły mają trafić do `mechanika/`, gdy zostaną zatwierdzone. +4. W obecnym etapie trzymaj kolejność pracy: `/game-dev` → `/gdd` → rozstrzygnięcie B1/B7 z `mechanika/99-open-questions.md` → scaffold projektu → `/skills-adoption` dla kroków zależnych od aplikacji lub CI. +5. Nie dopisuj reguł sprzecznych z `mechanika/`. Jeśli jakaś część specyfikacji nadal jest otwarta, zapisz to w `mechanika/99-open-questions.md` albo w odpowiednim dokumencie, zamiast zgadywać. 6. Traktuj `dodatki/research/` i `dodatki/skills/` jako biblioteki wejściowe. Zatwierdzone wnioski przenoś do `docs/`, `mechanika/` albo `.github/skills/`. -7. Dopiero po ustabilizowaniu dokumentacji i assetów `.github/` scaffolduj projekt Vite + Phaser 4. +7. Przed scaffoldowaniem kodu dopnij synchronizację `README.md`, `docs/GDD.md`, `docs/SCOPE.md`, `docs/ARCHITECTURE.md` i workflow Copilota z gotową mechaniką. 8. Po każdej większej zmianie aktualizuj tę sekcję: wpisz aktualny stan, najbliższe kroki i blokery, które musi znać osoba kontynuująca pracę. ## If the slash commands do not appear diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 4f80e06..3dda453 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -25,7 +25,7 @@ Claude proposals rejected or modified: - **Rejected:** "Phaser 3 only / no Phaser 4". The approved architecture stays on Phaser 4. - **Rejected:** `idb-keyval` as the main save abstraction. Dexie.js remains approved because schema versioning and migrations matter for long-running save files. - **Modified:** "No Capacitor ever" becomes "no Capacitor for MVP; consider only for native APIs post-MVP." -- **Deferred:** Battle, traits, progression, combat beacon logic, quest logic, and morale formulas until `mechanika/` arrives. +- **Deferred after mechanika v1.0:** battle implementation, full trait-effect expansion, combat/quest beacon logic, faction systems, and any rules explicitly marked open or post-MVP in `mechanika/`. ## Target project structure @@ -116,13 +116,13 @@ When documents overlap, resolve conflicts in this order: | System | MVP responsibility | Notes | |---|---|---| -| `ShipSystem` | Ship hull/status/system health | No combat damage formula until `mechanika/`. | -| `CrewSystem` | Crew roster, assignments, health/morale clamps | Traits/progression are reserved fields only. | -| `MissionSystem` | Active mission state, mission steps, completion | Final mission mechanics wait for `mechanika/`. | -| `ResourceSystem` | Fuel, scrap, parts and resource deltas | Every resource needs an input and output. | -| `EventSystem` | Weighted random event selection and choice resolution | Effects must stay simple until mechanics spec arrives. | -| `LifeSearchSystem` | Search-for-life progress and discovery flags | Detailed discovery mechanics wait for `mechanika/`. | -| `SaveSystem` | Dexie save/load/autosave/schema versioning | `localStorage` is not allowed for primary saves. | +| `ShipSystem` | Ship hull/status/system health | Must cover the approved system list from `mechanika/05-ship-systems.md`; combat remains deferred. | +| `CrewSystem` | Crew roster, assignments, health/morale/fatigue/radiation clamps | Implements torpor rotation, relation flags, and approved trait hooks from `mechanika/04-crew.md`. | +| `MissionSystem` | Active mission state, mission steps, completion | Must support 14 approved missions, including multi-turn missions. | +| `ResourceSystem` | Oxygen, water, food, fuel, parts, and system-driven deltas | Every resource needs an input, output, and shortage consequence. | +| `EventSystem` | Weighted random event selection and choice resolution | Must support forced events, weighted events, blue options, and approved failure/death outcomes. | +| `LifeSearchSystem` | LifeData, discovery progress, and ending flags | MVP covers the approved discovery scale and mission/event dependencies only. | +| `SaveSystem` | Dexie save/load/autosave/schema versioning | Must preserve active run state plus logbook retention after permadeath. | ## Event model @@ -148,21 +148,21 @@ Events should be data-driven and compatible with FTL-like "blue options": } ``` -Combat-related requirements and death/permadeath effects are reserved until `mechanika/` defines the exact rules. +Combat remains reserved. Death, permadeath, and ending behavior should now follow `mechanika/09-failure-and-game-over.md`. ## Mechanics integration points -The following are allowed as **stubs or type placeholders only** until the user provides the `mechanika/` folder: +The following still require partial or deferred treatment even after `mechanika/` v1.0: | Integration point | Allowed now | Not allowed yet | |---|---|---| | `BattleScene` | Stub with TODO | Combat implementation | | `BattleSystem` | Stub with interface only | Damage formulas, enemy AI | -| `TraitSystem` | `traits: string[]` field | Trait effects | -| `ProgressionSystem` | `skills` fields | XP curves and level-up rules | +| `TraitSystem` | Serializable trait identifiers and only approved effects | Broad trait-effect design beyond approved spec | +| `ProgressionSystem` | Captain voices, crew micro-growth, discovery progression | Broad XP trees and level-up rules | | `BeaconType.combat` | Enum value as reserved | Combat encounters | | `BeaconType.quest` | Enum value as reserved | Quest chains | -| Morale | Numeric field and clamp | Detailed morale events/formulas | +| Morale | Numeric field, thresholds, and approved event hooks | Additional simulation outside `mechanika/` | ## Mermaid overview @@ -183,7 +183,7 @@ graph TB Systems --> Storage PWA --> App - subgraph Future["Pending mechanika/"] + subgraph Future["Deferred / post-MVP mechanics"] Battle["BattleSystem / BattleScene"] Traits["TraitSystem"] Progression["ProgressionSystem"] @@ -193,6 +193,6 @@ graph TB Systems -. integration points .-> Future ``` -## Narrative foundation before mechanics +## Narrative foundation with mechanics locked -Before detailed mechanics are finalized, the repository now keeps story canon in `docs/FABULA.md`, product intent in `docs/GAME_BRIEF.md`, and structured design state in `docs/GDD.md`. This keeps worldbuilding and content direction available to AI-assisted writing without forcing premature gameplay rules into `mechanika/`. Additional skill packages should be staged in `.github/skills/incoming/` before they become active local skills. +Now that `mechanika/` is filled, the repository uses it as the gameplay source of truth, while `docs/FABULA.md` remains the canon source for story and `docs/GAME_BRIEF.md` keeps the product frame concise. `docs/GDD.md` should track implementation order, blockers, and scope decisions instead of duplicating full mechanics tables. Additional skill packages should still be staged in `.github/skills/incoming/` before they become active local skills. diff --git a/docs/COPILOT_WORKFLOW.md b/docs/COPILOT_WORKFLOW.md index bb7d813..31b6522 100644 --- a/docs/COPILOT_WORKFLOW.md +++ b/docs/COPILOT_WORKFLOW.md @@ -1,6 +1,6 @@ # Instrukcja korzystania z promptów Copilota -English summary: the working custom slash commands are `/game-dev`, `/game-brief`, `/fabula`, `/gdd`, `/skills-adoption`, `/investigate`, `/new-scene`, `/new-system`, `/new-event`, `/data-schema`, `/pwa-check`, `/mobile-ux`, and `/code-review`. Start with `/game-dev`, then lock the brief and story before mechanics-heavy implementation. The detailed guide below is in Polish. +English summary: the working custom slash commands are `/game-dev`, `/game-brief`, `/fabula`, `/gdd`, `/skills-adoption`, `/investigate`, `/new-scene`, `/new-system`, `/new-event`, `/data-schema`, `/pwa-check`, `/mobile-ux`, and `/code-review`. Start with `/game-dev`, sync docs against `mechanika/`, then scaffold and implement in small steps. The detailed guide below is in Polish. Ten dokument jest prostą instrukcją pracy w VS Code z przygotowanymi promptami projektu SpaceshipGame. Traktuj go jak kolejność rozmowy z Copilotem. @@ -10,7 +10,7 @@ Najpierw używaj promptu **`/game-dev`**. To główny przełącznik projektu. On Nie zaczynaj od `/new-scene` albo `/new-system`, jeśli nie masz jeszcze gotowego projektu Vite/Phaser i podstawowych folderów. -W obecnym Sprint 0 przed mechaniką najpierw porządkuj: **brief → fabułę → GDD → adoption skills**. +W obecnym etapie po domknięciu `mechanika/` najpierw porządkuj: **game-dev → synchronizacja GDD/scope → decyzje blokujące → scaffold projektu**. ## Materiały kreatywne poza source of truth @@ -25,8 +25,8 @@ W obecnym Sprint 0 przed mechaniką najpierw porządkuj: **brief → fabułę |---|---|---| | `/game-dev` | Zawsze na początku sesji albo gdy nie wiesz, co dalej | Sprawdza projekt, dokumenty, braki i proponuje następne kroki | | `/game-brief` | Gdy chcesz ustabilizować wizję projektu | Tworzy lub aktualizuje `docs/GAME_BRIEF.md` bez wchodzenia w szczegółowe mechaniki | -| `/fabula` | Gdy tworzysz historię przed mechaniką | Buduje `docs/FABULA.md`: premisę, ton, świat i haki narracyjne | -| `/gdd` | Gdy chcesz utrzymać główny design doc | Aktualizuje `docs/GDD.md` i oznacza sekcje jako approved/reserved/open question | +| `/fabula` | Gdy zmienia się kanon albo trzeba dopisać brakującą warstwę narracyjną | Aktualizuje `docs/FABULA.md` bez przepisywania mechaniki | +| `/gdd` | Gdy chcesz utrzymać główny design doc i plan wdrożenia | Synchronizuje `docs/GDD.md` z briefem, fabułą, scope i `mechanika/` | | `/skills-adoption` | Gdy chcesz wdrożyć zatwierdzony zestaw skills/MCP | Czyta `SKILLS_RECOMMENDATIONS.txt` i `docs/skills-adoption/README.md`, wykonuje odblokowane kroki i raportuje blokery | | `/investigate` | Gdy najpierw trzeba coś sprawdzić | Robi ukierunkowany research repozytorium, konfliktów i blokerów | | `/new-scene` | Gdy potrzebujesz nowego ekranu/sceny gry | Tworzy lub planuje scenę Phaser 4, np. `BootScene`, `BridgeScene` | @@ -91,23 +91,23 @@ Wtedy najpierw użyj: ### Nie używaj `/new-system`, jeśli: -- system dotyczy walki, traits, progresji, morale albo questów, -- folder `mechanika/` nie zawiera jeszcze gotowej specyfikacji tych mechanik. +- system dotyczy walki, frakcji albo quest-chain poza MVP, +- chcesz dopisać reguły niezatwierdzone jeszcze w `mechanika/99-open-questions.md`. Wtedy poproś tylko o stub: ```text -/new-system Battle — tylko stub, mechanika będzie później w folderze mechanika +/new-system Battle — tylko stub, walka będzie doprecyzowana osobno ``` ### Nie używaj `/new-event`, jeśli: - event wymaga dokładnych reguł walki, -- event wymaga śmierci załogi, -- event wymaga XP/progresji, -- event wymaga frakcji albo quest-chain. +- event wymaga frakcji albo quest-chain, +- event opiera się na parametrze, który nadal jest otwartym pytaniem w `mechanika/99-open-questions.md`, +- chcesz dopisać nową klasę eventu zamiast zaimplementować zatwierdzone eventy z `mechanika/07-events.md`. -Do czasu dostarczenia `mechanika/` eventy mają być proste: zasoby, proste uszkodzenia, prosta zmiana zdrowia/morale, postęp misji. +Eventy implementuj zgodnie z `mechanika/07-events.md`. Jeśli brakuje decyzji albo parametr zależy od otwartego pytania, zatrzymaj się na danych/stubie zamiast wymyślać nową regułę. ## Harmonogram kolejnych promptów @@ -119,9 +119,9 @@ Do czasu dostarczenia `mechanika/` eventy mają być proste: zasoby, proste uszk Cel: Copilot ma przypomnieć sobie dokumentację i sprawdzić, czego brakuje. -### Etap 0.25 — brief i fabuła przed mechaniką +### Etap 0.25 — synchronizacja po mechanice -Zanim zaczniesz uszczegóławiać mechanikę, ustaw fundament narracyjny: +Zanim zaczniesz scaffoldować kod, zsynchronizuj dokumenty z gotową mechaniką: Jeśli potrzebujesz materiału wejściowego do tej fazy, najpierw przejrzyj: @@ -130,18 +130,24 @@ Jeśli potrzebujesz materiału wejściowego do tej fazy, najpierw przejrzyj: - `docs/CREATIVE_INPUTS.md` ```text -/game-brief uporządkuj krótki brief projektu i misji +/gdd zsynchronizuj brief, fabułę, scope i aktualną mechanikę ``` ```text -/fabula przygotuj bazę fabularną, ton i haki narracyjne do docs/FABULA.md +/investigate wypisz krytyczne blokery implementacji z mechanika/99-open-questions.md +``` + +Jeśli w trakcie wyjdzie rozjazd: + +```text +/game-brief uporządkuj brief zgodnie z aktualną mechaniką ``` ```text -/gdd zsynchronizuj brief, fabułę i aktualny scope +/fabula popraw tylko sekcje kanoniczne które rozjechały się z mechaniką ``` -Cel: repo ma mieć osobne miejsce na wizję produktu, fabułę i design doc zanim zacznie powstawać kod i finalna mechanika. +Cel: repo ma mieć spójny brief, fabułę, GDD i scope zanim zacznie powstawać kod. ### Etap 0.5 — research i wdrażanie skills/MCP @@ -183,6 +189,10 @@ Najpierw dane, potem logika: /data-schema ship-systems ``` +```text +/data-schema missions +``` + ```text /data-schema events ``` @@ -225,10 +235,10 @@ Twórz sceny w tej kolejności: /new-scene Crew ``` -Nie implementuj jeszcze `BattleScene`, chyba że jako stub: +Na starcie `BattleScene` zostaje stubem: ```text -/new-scene Battle — tylko stub z TODO pending mechanika +/new-scene Battle — tylko stub do czasu osobnej decyzji o walce ``` ### Etap 4 — systemy gry @@ -263,18 +273,18 @@ Twórz systemy w tej kolejności: /new-system LifeSearch ``` -Systemy zależne od przyszłej mechaniki tylko jako stub: +Systemy nadal odroczone albo częściowo ograniczone: ```text /new-system Battle — tylko stub, bez mechaniki walki ``` ```text -/new-system Trait — tylko stub, bez efektów traits +/new-system Trait — tylko approved hooks, bez pełnego systemu efektów ``` ```text -/new-system Progression — tylko stub, bez XP curves +/new-system Progression — tylko zatwierdzona progresja z mechanika, bez szerokich XP curves ``` ### Etap 5 — pierwsze eventy @@ -330,32 +340,32 @@ Jeśli Copilot znajdzie coś poważnego, napraw tylko to, a potem ponów: ## Proponowana kolejność pierwszych 20 promptów 1. `/game-dev sprawdź stan projektu i podaj następne kroki` -2. `/game-dev przygotuj projekt Vite + TypeScript + Phaser 4` -3. `/code-review sprawdź setup projektu` -4. `/data-schema resources` -5. `/data-schema crew` -6. `/data-schema ship-systems` -7. `/data-schema events` -8. `/new-scene Boot` -9. `/new-scene Preload` -10. `/new-scene MainMenu` -11. `/new-scene Bridge` -12. `/new-system Resource` -13. `/new-system Save` -14. `/new-system Event` -15. `/new-scene Map` -16. `/new-scene Event` -17. `/new-event drobna awaria napędu` -18. `/new-event opuszczona sonda badawcza` -19. `/pwa-check sprawdź gotowość PWA` -20. `/code-review sprawdź całość po pierwszym działającym loopie` +2. `/gdd zsynchronizuj docs z mechanika v1.0` +3. `/investigate wypisz blokery z mechanika/99-open-questions.md` +4. `/game-dev przygotuj projekt Vite + TypeScript + Phaser 4` +5. `/code-review sprawdź setup projektu` +6. `/data-schema resources` +7. `/data-schema crew` +8. `/data-schema ship-systems` +9. `/data-schema missions` +10. `/data-schema events` +11. `/new-scene Boot` +12. `/new-scene Preload` +13. `/new-scene MainMenu` +14. `/new-scene Bridge` +15. `/new-scene Systems` +16. `/new-scene Torpor` +17. `/new-system Resource` +18. `/new-system Save` +19. `/new-system Mission` +20. `/code-review sprawdź pierwszy działający szkielet loopa` ## Jak pracować, żeby nie zgubić projektu - Jedna rozmowa = jeden mały cel. - Jeśli Copilot proponuje dużą przebudowę, poproś: "podziel to na małe kroki". - Jeśli Copilot chce dodać bibliotekę, poproś: "najpierw ADR". -- Jeśli Copilot zaczyna wymyślać mechanikę walki/progresji, zatrzymaj go i przypomnij: "to czeka na folder mechanika". +- Jeśli Copilot zaczyna zmieniać zatwierdzoną mechanikę bez decyzji projektowej, zatrzymaj go i przypomnij: "trzymaj się mechanika/ albo dopisz open question". - Jeśli coś nie działa, użyj `/code-review` albo poproś `/game-dev` o diagnozę następnego kroku. ## Krótka ściąga diff --git a/docs/FABULA.md b/docs/FABULA.md index d2b6a51..f154105 100644 --- a/docs/FABULA.md +++ b/docs/FABULA.md @@ -656,8 +656,9 @@ Każde zakończenie ma tekst końcowy napisany w tonie logbooka kapitana. **Otwarte pytania:** - Patrz sekcja 11. -**Następne pliki do wypełnienia:** -- `mechanika/00-overview.md` — podsumowanie gry spójne z fabułą -- `mechanika/04-crew.md` — parametry postaci zgodne z profilemi -- `mechanika/07-events.md` — pierwsze 15 eventów MVP -- `docs/GDD.md` — synchronizacja z briefem i fabułą +**Pliki do utrzymywania w synchronizacji:** +- `mechanika/00-overview.md` — skrót gry spójny z fabułą +- `mechanika/04-crew.md` — profile postaci i ich parametry +- `mechanika/07-events.md` — eventy korzystające z motywów fabularnych +- `mechanika/09-failure-and-game-over.md` — zakończenia i konsekwencje śmierci +- `docs/GDD.md` — plan implementacyjny i bieżący stan designu diff --git a/docs/GDD.md b/docs/GDD.md index c020508..2854594 100644 --- a/docs/GDD.md +++ b/docs/GDD.md @@ -2,50 +2,74 @@ ## Status model -- **Approved now** — safe to use before the final mechanika pass. -- **Reserved** — known placeholder that must not be fully implemented yet. -- **Open question** — needs user decision or later spec work. +- **Approved** — already defined in `mechanika/` and safe to implement. +- **Deferred** — intentionally out of MVP or still limited to stubs. +- **Open question** — tracked blocker that needs a decision before or during implementation. -## Product frame +## Source stack -- Brief source: `docs/GAME_BRIEF.md` -- Narrative source: `docs/FABULA.md` -- Mechanics source: `mechanika/` +- Product brief: `docs/GAME_BRIEF.md` +- Narrative canon: `docs/FABULA.md` +- Mechanics source of truth: `mechanika/` +- MVP boundary: `docs/SCOPE.md` +- Technical structure: `docs/ARCHITECTURE.md` -## Core player loop +## Current design snapshot -- **Approved now:** manage ship state, review crew, travel, resolve events, track mission progress. -- **Reserved:** advanced combat, progression, and quest-chain loops. +### Core loop — Approved -## Content tracks +One turn is one rotation cycle: awakening, assignment, event, resolution, torpor. +The mission spans ~174 turns across 5 acts and keeps pressure on crew state, ship systems, resources, and discovery progress. -### Narrative and worldbuilding +### MVP content volume — Approved -- **Approved now:** create and maintain the story baseline in `docs/FABULA.md`. -- **Open question:** which story beats should be mandatory in MVP events. +- 14 gameplay scenes plus `BattleScene` as stub (`mechanika/02-screens-and-scenes.md`) +- 5 core resources + ECLSS/system-health layer (`mechanika/03-resources.md`, `mechanika/05-ship-systems.md`) +- 7 crew members + ARIA, torpor rotation, relations, inner voices (`mechanika/04-crew.md`, `mechanika/08-progression.md`) +- 14 mission types and LifeData discovery track (`mechanika/06-missions.md`) +- 15 MVP events: 6 forced, 9 weighted (`mechanika/07-events.md`) +- 5 hard game-over conditions and 6 narrative endings (`mechanika/09-failure-and-game-over.md`) -### Mechanics and balance +### Still deferred after mechanika v1.0 -- **Reserved:** final formulas and balance values until `mechanika/` is filled. +- Battle implementation beyond stub +- Full trait-effect system beyond approved trait hooks +- Quest/faction systems +- Post-MVP life-discovery levels 4–6 +- Broader XP trees, difficulty modes, and other ideas parked in `docs/IDEAS_LATER.md` -### UI and scene planning +## Implementation-readiness notes -- **Approved now:** document scene order, overlays, and mobile-first priorities. +### Approved implementation anchors -## Crew and content placeholders +- Systems should be data-driven and read gameplay values from `mechanika/`-derived data files. +- Mobile-first layouts, overlay structure, and scene order are already specified. +- Saves must preserve autosave, permadeath cleanup, and logbook retention. -- **Approved now:** crew roles, skills fields, morale fields, and event hooks may be described at a high level. -- **Reserved:** trait effects, XP curves, faction behaviors, and quest logic. +### Critical blockers before scaffolding logic -## Documentation workflow +- **B1 — Radiation baseline**: sync the final numeric decision across resources, crew, and balancing docs. +- **B7 — Captain torpor rule**: decide whether Jakub torpor is optional or mandatory. + +### Important near-term decisions + +- Language/i18n direction (`A3`, `D2`) +- Mission/event collision behavior (`B4`) +- Felix solo-path for M14 (`B6`) +- Third Quarter morale pressure tuning (`C2`) -1. Stabilize `docs/GAME_BRIEF.md`. -2. Build or revise `docs/FABULA.md`. -3. Keep `docs/GDD.md` aligned with the brief, fabula, and scope. -4. Move final gameplay rules into `mechanika/` as they are approved. +## Action plan -## Open questions +1. Keep repo docs aligned with `mechanika/` as the gameplay source of truth. +2. Resolve the critical blockers in `mechanika/99-open-questions.md` (`B1`, `B7`). +3. Scaffold the Vite + TypeScript + Phaser 4 project from the approved architecture. +4. Convert approved mechanics into data schemas first: resources, crew, ship systems, missions, events. +5. Implement the first playable loop in scene/system order from `mechanika/02-screens-and-scenes.md`. +6. Use early playtests to verify balance items listed in `mechanika/10-balancing-notes.md`. + +## Documentation workflow -- What is the first narrative revelation the player should encounter? -- Which event themes must exist before the first playable prototype? -- Which crew relationships are canon versus left systemic/open? +1. Update `docs/GAME_BRIEF.md` only when product framing changes. +2. Update `docs/FABULA.md` only when canon changes. +3. Update `docs/GDD.md` when implementation order, scope, or blockers change. +4. Update `mechanika/` when gameplay rules themselves change. diff --git a/docs/SCOPE.md b/docs/SCOPE.md index 75cd251..5a10be4 100644 --- a/docs/SCOPE.md +++ b/docs/SCOPE.md @@ -2,51 +2,56 @@ ## In the MVP -The MVP must prove the core management loop without waiting for final mechanics: +The MVP now targets the first playable implementation of the approved `mechanika/` v1.0: - Browser-first Phaser 4 app with TypeScript and Vite. - PWA installable on Android. -- Pixel-art presentation with placeholder assets. -- Bridge/main management screen. -- Basic sector/map screen with beacons. -- Event screen with weighted choices. -- Crew roster with role, skills, health, morale, and reserved traits. -- Resource management for: - - `fuel` - - `scrap` - - `parts` -- Save/load/autosave through IndexedDB + Dexie. -- At least 15 simple events. -- Basic "search for life" progress flag or track, without final discovery mechanics. +- Pixel-art presentation with placeholder art where needed. +- Scene flow covering: + - `BootScene` + - `PreloadScene` + - `MainMenuScene` + - `BridgeScene` + - `EventScene` + - `CrewScene` + - `SystemsScene` + - `TorporScene` + - `MapScene` + - `LogbookScene` + - `ApproachScene` + - `EndingScene` + - `GameOverScene` +- Crew roster for 7 characters plus ARIA context. +- Crew state: health, morale, fatigue, radiation, torpor rotation, and relations. +- Ship/system state for 13 systems including ECLSS dependencies. +- Resource model for `oxygen`, `water`, `food`, `fuel`, and `parts`. +- Mission model for 14 MVP missions and the LifeData track. +- Event model for 15 MVP events with forced/weighted structure and blue options. +- Save/load/autosave through IndexedDB + Dexie with logbook retention after permadeath. +- Narrative endings and hard game-over conditions defined in `mechanika/09-failure-and-game-over.md`. ## Not in the MVP -- Battle implementation. -- Turn-based combat. -- Trait effects. -- Crew XP/progression curves. -- Complex morale simulation. -- Quest chains. -- Factions. +- Battle implementation beyond stub. +- Faction systems. +- Quest chains / quest beacons. +- Full trait-effect simulation beyond approved hooks. +- Broad XP trees and post-MVP progression systems. +- Life-discovery levels 4–6. - Multiple starting ships. - iOS support. - Capacitor app shell. - Full Playwright E2E suite. - Final art polish. -## Reserved until `mechanika/` +## Open implementation blockers -Do not invent detailed rules for: +These are already identified and must be resolved or explicitly deferred before coding the affected systems: -- combat, -- injuries/death beyond simple health changes, -- morale formulas, -- skill progression, -- quest logic, -- faction logic, -- life discovery scoring. - -These must be integrated only after the user provides the `mechanika/` folder contents. +- Radiation baseline decision (`B1`) +- Captain torpor rule (`B7`) +- Language/i18n direction (`A3`, `D2`) +- Mission/event collision handling (`B4`) ## MVP scenes @@ -56,25 +61,30 @@ These must be integrated only after the user provides the `mechanika/` folder co | `PreloadScene` | Required | | `MainMenuScene` | Required | | `BridgeScene` | Required | -| `MapScene` | Required | | `EventScene` | Required | | `CrewScene` | Required | -| `BattleScene` | Stub only, pending `mechanika/` | +| `SystemsScene` | Required | +| `TorporScene` | Required | +| `MapScene` | Required | +| `LogbookScene` | Required | +| `ApproachScene` | Required in Act IV | +| `EndingScene` | Required | +| `GameOverScene` | Required | +| `BattleScene` | Stub only | -## MVP beacon types +## MVP beacon / content statuses | Type | Status | |---|---| -| `empty` | Required | | `event` | Required | -| `shop` | Optional | -| `distress` | Optional/simple event alias | -| `combat` | Reserved | -| `quest` | Reserved | +| mission travel / approach content | Required | +| `combat` | Stub/reserved | +| `quest` | Deferred | ## Scope-control rules -1. New ideas go to `docs/IDEAS_LATER.md`, not directly to code. -2. New dependencies require an ADR in `docs/ADRs/`. -3. The first playable version can be visually rough. -4. If a feature depends on missing mechanics, add a stub and TODO, then stop. +1. `mechanika/` is the gameplay source of truth; do not invent conflicting rules in code. +2. New ideas outside MVP go to `docs/IDEAS_LATER.md`, not directly to code. +3. New dependencies require an ADR in `docs/ADRs/`. +4. The first playable version can be visually rough. +5. If a feature depends on unresolved or deferred mechanics, keep it as a stub and stop there.