fool-cardgame/docs/PLAN.md

Development plan

Living document. Updated as work progresses — each milestone is committed to master together with the update to this file.

Legend: [ ] not started · [~] in progress · [x] done

Source specs this plan implements: GAMEPLAY.md, ARCHITECTURE.md, LOBBY.md, UI.md, ART.md. Autonomous choices are logged in DECISIONS.md; the resulting structure is described in TECHNICAL.md.

Iteration 1 scope

Single-player match of podkidnoy durak against a bot, 1v1, no transferring (perevod). Lobby → match → result → lobby. Savegame framework in place with a statistics section only (no currency, no levels yet). Portrait mobile UI, targets: Web, Android, iOS.

Guiding principle

The rules live in a pure TypeScript core with no cc imports, driven as a deterministic state machine. That makes the whole game logic testable headlessly with npm test — no editor, no device — which is what allows unattended progress. The Cocos layer only renders state and turns taps into actions.

Milestones

M0 — Foundation [x]

• Read specs, confirm open questions with the user
• docs/PLAN.md, docs/TECHNICAL.md, docs/DECISIONS.md
• Asset folder skeleton under assets/
• Project settings: design resolution 1080×1920, fit-width
• Headless test harness (vitest) wired to assets/scripts/core, plus a core purity guard and a strict typecheck

M1 — Rules core [x]

• Seeded RNG and shuffle
• Suit, Rank, Card, 36-card deck
• GameState: hands, deck, trump, table slots, discard, phase, turn order
• First-attacker selection per GAMEPLAY.md (lowest trump → lowest card → random)
• Legal action generation: Attack, Defend, Take, Pass
• Turn resolution: beat-all / take, discard, draw order, player elimination
• End conditions and loser ("fool") determination
• Unit tests covering every rule clause, including the add-card limits

M2 — Bot and headless match runner [x]

• PlayerView projection — a bot sees only what a player legitimately sees
• BasicBot exactly per GAMEPLAY.md "Basic bot"
• MatchRunner driving a full headless match
• Soak test: thousands of seeded self-play matches finish with no illegal state

M3 — Savegame module [x]

• ISaveSection contract, SaveManager registry, JSON keyed by section name
• Storage backend over sys.localStorage (works on web and native)
• StatsSection: games played / won / lost, current and best win streak
• Versioning + tolerant load (unknown or missing sections do not break a load)
• Tests for save/load round-trip and corrupted-payload recovery

M4 — Art pipeline [x]

• Pick the 36 needed faces from local/, downscale to the 1080-wide budget
• Author the missing pieces: card back, table background, UI panels/buttons
• Import into assets/art/, configure sprite frames and atlasing
• Remove consumed source art from local/, record attribution/licence

M5 — Scenes and bootstrap [x]

• loader scene: module initialisation, then transition to lobby
• lobby scene: New Game button, statistics readout
• Canvas / resolution policy and a reusable safe-area-aware layout root

M6 — Game screen [x]

• Card prefab, face/back flipping, sizing
• Hand layout (fan), table layout (attack/defence pairs), deck and trump display
• Deal, attack, defend, take and discard animations driven by core events
• Tap/drag input producing core actions; illegal moves visibly rejected
• Bot acts with human-readable pacing

M7 — Match flow [x]

• Result overlay (win / lose), stats written through the savegame module
• Return to lobby; start another match without a scene leak
• Leave-match button, which ends the match as a loss

M8 — Responsive and touch pass [~]

• Fit-width canvas, safe-area root, widget-stretched background
• Every interactive element authored at or above the 120-unit minimum (buttons 330×140 and 560×150; hand cards expose ~128 units each)
• Vertical positions kept inside the 4:3 crop
• Blocked: seen at the extreme aspect ratios. Needs a machine that can actually run the build — see "What is and is not verified" in TECHNICAL.md

M9 — Build verification and hand-off [~]

• web-mobile build completes clean; command recorded in TECHNICAL.md
• Card art reaches the build and packs into a single 2048² atlas
• Every component reference in the scene verified populated
• Blocked: the build seen running. The browser in this environment falls back to a software renderer that cannot start the engine's main loop
• Android/iOS texture settings written up in TECHNICAL.md (they have to be applied once in the Inspector; they live in the .meta files)
• README

Known follow-ups

• The default skybox cubemap (~1.1 MB) still reaches the build. skybox.enabled is off in both scenes, but the scene keeps its _envmapHDR reference and the builder follows it. The editor tool server cannot write a null reference; clearing the field in the Inspector by hand would do it.
• Nothing verifies the presentation layer automatically. The obvious next step is a smoke test that boots the scene headlessly and asserts the card nodes land where the layout says they should.

Deliberately out of scope for iteration 1

Multiplayer or networking, more than two players at the table (the core is written for N players, but only 1v1 is exercised), transferring (perevod), smarter bots, currency, levels, shop, sound design, localisation.