M0: план разработки, техническая структура, каркас проекта
- docs/PLAN.md — план по этапам, обновляется по мере работы - docs/TECHNICAL.md — слои, карта папок, контракты, рабочие процессы - docs/DECISIONS.md — журнал решений, принятых самостоятельно - разрешение 1080x1920, fit-width (портрет, 4:3..21:9) - каркас assets/scripts (core / modules / app / ui) - headless-тесты на vitest + strict typecheck + защита чистоты core - Rng: детерминированный генератор и перемешивание Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
@@ -100,3 +100,23 @@ cd extensions/cocos-code-mode && npm install --no-save --os=win32 --cpu=x64 --in
|
||||
|
||||
(`extensions/cocos-code-mode/node_modules` is gitignored, so that install does not
|
||||
survive a clean checkout either.)
|
||||
|
||||
## Known issue: the setter tools take arrays, not a single path
|
||||
|
||||
[CODE_MODE_TOOLS.md](CODE_MODE_TOOLS.md) is generated from the manual the
|
||||
extension serves, and for `inspectorSetInstanceProperties` /
|
||||
`inspectorSetSettingsProperties` that manual advertises a singular
|
||||
`propertyPath` + `value` pair. The implementation actually loaded
|
||||
([set-properties-tool.js](../extensions/cocos-code-mode/dist/utcp/tools/set-properties-tool.js))
|
||||
expects parallel arrays, and the singular form fails with the unhelpful
|
||||
`Cannot read properties of undefined (reading 'length')`.
|
||||
|
||||
Use:
|
||||
|
||||
```js
|
||||
CocosEditor.inspectorSetSettingsProperties({
|
||||
settingsType: 'ProjectSettings',
|
||||
propertyPaths: ['general.designResolution.width', 'general.fitWidth'],
|
||||
values: [1080, true],
|
||||
});
|
||||
```
|
||||
|
||||
@@ -0,0 +1,99 @@
|
||||
# Decision log
|
||||
|
||||
Choices made while implementing the specs, recorded so they can be challenged
|
||||
later. Each entry states what the specs left open, what was chosen and why.
|
||||
|
||||
Format: `YYYY-MM-DD` · area · decision.
|
||||
|
||||
---
|
||||
|
||||
## 2026-09-13 · Rules · Turn passes *past* a defender who took
|
||||
|
||||
GAMEPLAY.md says "after drawing cards move is passed to next player in clockwise
|
||||
order", but does not say what happens when the defender took the cards.
|
||||
|
||||
**Decision.** The defender who took is skipped: the next attacker is the player
|
||||
after the defender. In 1v1 this means the same player attacks again — the
|
||||
standard rule, and the one that makes taking a real cost.
|
||||
|
||||
## 2026-09-13 · Rules · Interpretation of the add-card limits
|
||||
|
||||
GAMEPLAY.md gives three limits on attacking cards. The second one ("there should
|
||||
not be more attacking cards than card amount in defending player's hand") is
|
||||
ambiguous about *when* it is measured.
|
||||
|
||||
**Decision.** A card may be added only if all three hold at the moment of adding:
|
||||
|
||||
1. `table.length < 6` (`< 5` on the very first turn of the game);
|
||||
2. `unbeatenCount < defenderHandSize` — where `unbeatenCount` counts attack cards
|
||||
with no defence on them, and `defenderHandSize` is the defender's hand *at that
|
||||
moment*. Once the defender has declared a take, their hand no longer shrinks,
|
||||
so this freezes naturally;
|
||||
3. its rank matches the rank of some card already on the table, attack or
|
||||
defence alike.
|
||||
|
||||
The first attacking card of a turn is exempt from (3) — there is nothing on the
|
||||
table to match.
|
||||
|
||||
## 2026-09-13 · Rules · Attack order is serialised
|
||||
|
||||
In a real game attackers may throw cards in at any moment, concurrently with the
|
||||
defender thinking. Modelling genuine concurrency buys nothing for 1v1 against a
|
||||
bot and makes the state machine much harder to test.
|
||||
|
||||
**Decision.** The core is a strict turn-based state machine with an explicit
|
||||
"who may act now" set. Attackers are polled for additions only when there are no
|
||||
unbeaten cards on the table, or after a take has been declared. This is
|
||||
behaviourally identical for 1v1 and extends cleanly to N players.
|
||||
|
||||
## 2026-09-13 · Architecture · Rules core is engine-independent
|
||||
|
||||
**Decision.** Everything under `assets/scripts/core/` is plain TypeScript with no
|
||||
`cc` import, no `Component`, no scene access, and no wall-clock time. The state
|
||||
machine is a pure reducer `apply(state, action) -> { state, events }` over a
|
||||
seeded RNG.
|
||||
|
||||
**Why.** It makes the entire rule set verifiable with `npm test` in a second, on
|
||||
any machine, with no editor running — which is the only practical way to build
|
||||
this unattended. It also leaves the door open for server-authoritative
|
||||
multiplayer later without a rewrite.
|
||||
|
||||
## 2026-09-13 · Architecture · Bots consume a restricted `PlayerView`
|
||||
|
||||
**Decision.** A bot never receives `GameState`. It receives a `PlayerView`: its
|
||||
own hand, the table, the trump card, counts (deck size, each opponent's hand
|
||||
size) and the discard count.
|
||||
|
||||
**Why.** It makes cheating structurally impossible rather than a matter of
|
||||
discipline, and a `PlayerView` is exactly the payload a future network protocol
|
||||
would send to a client.
|
||||
|
||||
## 2026-09-13 · Architecture · Savegame sections are self-registering
|
||||
|
||||
ARCHITECTURE.md asks for a save composed of independent classes, keyed by class
|
||||
name.
|
||||
|
||||
**Decision.** Sections implement `ISaveSection { readonly key; save(); load(data) }`
|
||||
and register with `SaveManager`. The key is an explicit string constant, *not*
|
||||
`constructor.name`, because minification in release builds renames classes and
|
||||
would silently orphan every existing save.
|
||||
|
||||
## 2026-09-13 · Presentation · 1080×1920 design resolution, fit-width
|
||||
|
||||
UI.md requires portrait, 4:3 to 21:9. ART.md fixes the art budget at 1080 px wide.
|
||||
|
||||
**Decision.** Design resolution 1080×1920 with `fitWidth = true`,
|
||||
`fitHeight = false`, so the width is always exactly 1080 design units and taller
|
||||
screens simply reveal more vertical space. Layout is anchored with widgets to
|
||||
top/bottom, the play area centred, and the safe-area inset respected on the top
|
||||
and bottom bars.
|
||||
|
||||
## 2026-09-13 · Art · Vector deck from `local/`, licence recorded
|
||||
|
||||
`local/Playing Cards` holds the Chris Aguilar "Vector Playing Cards" set
|
||||
(also mirrored on Wikimedia Commons), which is **LGPL-3.0**.
|
||||
|
||||
**Decision.** Use the 36 faces needed for a durak deck, rendered from the SVG
|
||||
sources so the downscale to the 1080-wide budget stays sharp. Attribution and
|
||||
licence text are recorded in `assets/art/cards/ATTRIBUTION.md`. The card back,
|
||||
table surface and UI chrome are not in that set and are authored for this project.
|
||||
@@ -0,0 +1,97 @@
|
||||
# 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](GAMEPLAY.md),
|
||||
[ARCHITECTURE.md](ARCHITECTURE.md), [LOBBY.md](LOBBY.md), [UI.md](UI.md),
|
||||
[ART.md](ART.md). Autonomous choices are logged in [DECISIONS.md](DECISIONS.md);
|
||||
the resulting structure is described in [TECHNICAL.md](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]`
|
||||
- [x] Read specs, confirm open questions with the user
|
||||
- [x] `docs/PLAN.md`, `docs/TECHNICAL.md`, `docs/DECISIONS.md`
|
||||
- [x] Asset folder skeleton under `assets/`
|
||||
- [x] Project settings: design resolution 1080×1920, fit-width
|
||||
- [x] 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 `[ ]`
|
||||
- [ ] `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 `[ ]`
|
||||
- [ ] `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 `[ ]`
|
||||
- [ ] 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 `[ ]`
|
||||
- [ ] `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 `[ ]`
|
||||
- [ ] `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 `[ ]`
|
||||
- [ ] Result overlay (win / lose), stats written through the savegame module
|
||||
- [ ] Return to lobby; start another match without a scene leak
|
||||
- [ ] Optional: surrender / leave match
|
||||
|
||||
### M8 — Responsive and touch pass `[ ]`
|
||||
- [ ] Verify layout from 4:3 to 21:9, portrait
|
||||
- [ ] All interactive elements meet a minimum tap size
|
||||
- [ ] Editor preview screenshots at the extreme aspect ratios
|
||||
|
||||
### M9 — Build verification and hand-off `[ ]`
|
||||
- [ ] Web-mobile build runs end to end
|
||||
- [ ] Android/iOS build settings documented (ASTC per ART.md)
|
||||
- [ ] README / TECHNICAL.md final pass
|
||||
|
||||
## 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.
|
||||
@@ -0,0 +1,132 @@
|
||||
# Technical structure
|
||||
|
||||
How this project is laid out, what each layer is allowed to do, and how to work
|
||||
on it. Companion to [ARCHITECTURE.md](ARCHITECTURE.md), which states the *intent*;
|
||||
this file states the *implementation*.
|
||||
|
||||
- Engine: **Cocos Creator 3.8.8**, TypeScript.
|
||||
- Targets: Web (mobile browser), Android, iOS. Portrait only.
|
||||
- Editor automation: the `cocos-code-mode` extension — see
|
||||
[CODE_MODE_SETUP.md](CODE_MODE_SETUP.md).
|
||||
|
||||
## Layering
|
||||
|
||||
Four layers, with dependencies pointing strictly downward. A layer may import
|
||||
from the layers below it and never from the ones above.
|
||||
|
||||
```
|
||||
ui/ Cocos components: scenes, prefabs, views, input, animation
|
||||
↓
|
||||
app/ bootstrap, service locator, scene transitions
|
||||
↓
|
||||
modules/ engine-aware services: savegame, (later) audio, analytics
|
||||
↓
|
||||
core/ pure rules and bots — no `cc` import anywhere
|
||||
```
|
||||
|
||||
The rule enforced by review and by the test harness: **nothing under
|
||||
`assets/scripts/core/` may import from `cc`.** It is plain TypeScript, runnable
|
||||
under Node, and that is what makes the rules testable without the engine.
|
||||
|
||||
## Folder map
|
||||
|
||||
```
|
||||
assets/
|
||||
scenes/
|
||||
loader.scene module init, then → lobby
|
||||
lobby.scene main menu; hosts the match UI
|
||||
prefabs/
|
||||
card.prefab one playing card, face or back
|
||||
...
|
||||
art/
|
||||
cards/ 36 faces + back, atlased
|
||||
ui/ panels, buttons, table surface
|
||||
scripts/
|
||||
core/ PURE TS — no engine imports
|
||||
cards/ Suit, Rank, Card, Deck
|
||||
rules/ GameState, actions, events, the reducer
|
||||
bot/ PlayerView projection, BasicBot
|
||||
util/ seeded RNG, shuffle, assertions
|
||||
modules/
|
||||
save/ SaveManager, ISaveSection, StatsSection, storage
|
||||
app/ Bootstrap, ServiceLocator, SceneRouter
|
||||
ui/
|
||||
lobby/ lobby screen controller
|
||||
game/ match screen: hand, table, deck, animations
|
||||
common/ reusable widgets, safe-area root
|
||||
tests/ vitest specs against assets/scripts/core
|
||||
docs/ specs, this file, plan, decisions
|
||||
local/ scratch art storage; contents get consumed
|
||||
extensions/cocos-code-mode/ editor tool server
|
||||
```
|
||||
|
||||
## The rules core
|
||||
|
||||
A deterministic state machine. The only entry point is a pure reducer:
|
||||
|
||||
```ts
|
||||
apply(state: GameState, action: Action): { state: GameState; events: GameEvent[] }
|
||||
```
|
||||
|
||||
- `GameState` is plain data: hands, deck, trump card, table slots, discard,
|
||||
phase, whose turn it is, and the RNG state. It is serialisable, which makes
|
||||
every test a fixture and every bug reproducible from a seed.
|
||||
- `Action` is what a participant *wants* to do — `Attack`, `Defend`, `Take`,
|
||||
`Pass`. Legality is decided by the core, never by the caller; `legalActions()`
|
||||
exists so the UI can grey out impossible taps, not as the source of truth.
|
||||
- `GameEvent` is what *happened* — `CardDealt`, `CardPlayed`, `CardBeaten`,
|
||||
`TableTaken`, `TableDiscarded`, `TurnPassed`, `PlayerOut`, `GameOver`. The view
|
||||
layer animates the event stream; it never inspects `GameState` directly for
|
||||
anything it is not allowed to see.
|
||||
- Randomness comes from a seeded PRNG carried inside the state. Same seed plus
|
||||
same action sequence always reproduces the same match.
|
||||
|
||||
## Bots
|
||||
|
||||
A bot is a function `(view: PlayerView) => Action`. `PlayerView` is a projection
|
||||
of `GameState` containing only legitimately visible information. `BasicBot`
|
||||
implements the policy in [GAMEPLAY.md](GAMEPLAY.md) verbatim.
|
||||
|
||||
## Savegame
|
||||
|
||||
Per [ARCHITECTURE.md](ARCHITECTURE.md): `SaveManager` keeps a registry of
|
||||
`ISaveSection` implementations. `save()` enumerates them and builds
|
||||
`{ [section.key]: section.save() }`; `load()` parses and dispatches each payload
|
||||
back to the matching section. A missing or unparsable section is skipped with a
|
||||
warning rather than failing the whole load, so a bad release cannot brick a save.
|
||||
|
||||
Keys are explicit string constants, not class names — release builds minify.
|
||||
|
||||
## Conventions
|
||||
|
||||
- TypeScript, 4-space indent, `PascalCase` for types, `camelCase` for members,
|
||||
`_private` for backing fields (matching Cocos's own style).
|
||||
- One exported class per file, file named after it.
|
||||
- Cocos components live only in `ui/`; they are thin and hold no rules logic.
|
||||
- No `any` in `core/`. `strict` is off in the Cocos tsconfig for engine-side
|
||||
convenience, but the test harness type-checks `core/` in strict mode.
|
||||
|
||||
## Workflows
|
||||
|
||||
### Tests
|
||||
|
||||
```bash
|
||||
npm test
|
||||
```
|
||||
|
||||
Runs vitest over `tests/` against `assets/scripts/core`. No editor required.
|
||||
|
||||
### Driving the editor
|
||||
|
||||
Cocos Creator must be running with this project open. See
|
||||
[CODE_MODE_SETUP.md](CODE_MODE_SETUP.md); the port changes on every editor
|
||||
restart, so always read `~/.utcp_config.json`.
|
||||
|
||||
Scripts and other text assets are written to disk directly and picked up by the
|
||||
editor's asset watcher. Scenes and prefabs are authored through the tools —
|
||||
never by hand-editing the `.scene`/`.prefab` JSON.
|
||||
|
||||
### Builds
|
||||
|
||||
Web: `web-mobile` template. Mobile: ASTC textures per [ART.md](ART.md), PNG for
|
||||
web.
|
||||
Reference in New Issue
Block a user