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
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"ver": "1.2.0",
|
||||||
|
"importer": "directory",
|
||||||
|
"imported": true,
|
||||||
|
"uuid": "c56646a3-5861-441d-b174-0b9712e86765",
|
||||||
|
"files": [],
|
||||||
|
"subMetas": {},
|
||||||
|
"userData": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"ver": "1.2.0",
|
||||||
|
"importer": "directory",
|
||||||
|
"imported": true,
|
||||||
|
"uuid": "b130857b-d0fd-47d0-b6a7-72a6d2faafd6",
|
||||||
|
"files": [],
|
||||||
|
"subMetas": {},
|
||||||
|
"userData": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"ver": "1.2.0",
|
||||||
|
"importer": "directory",
|
||||||
|
"imported": true,
|
||||||
|
"uuid": "f005faf0-2224-4396-89d7-763a71c16ab9",
|
||||||
|
"files": [],
|
||||||
|
"subMetas": {},
|
||||||
|
"userData": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"ver": "1.2.0",
|
||||||
|
"importer": "directory",
|
||||||
|
"imported": true,
|
||||||
|
"uuid": "47d05b64-ed47-445a-9fce-33a0253484c1",
|
||||||
|
"files": [],
|
||||||
|
"subMetas": {},
|
||||||
|
"userData": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"ver": "1.2.0",
|
||||||
|
"importer": "directory",
|
||||||
|
"imported": true,
|
||||||
|
"uuid": "008f0d07-3e06-4f0f-b557-a30fa1447a2a",
|
||||||
|
"files": [],
|
||||||
|
"subMetas": {},
|
||||||
|
"userData": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"ver": "1.2.0",
|
||||||
|
"importer": "directory",
|
||||||
|
"imported": true,
|
||||||
|
"uuid": "998dfbeb-890a-4444-b01a-b8f5c92223ef",
|
||||||
|
"files": [],
|
||||||
|
"subMetas": {},
|
||||||
|
"userData": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"ver": "1.2.0",
|
||||||
|
"importer": "directory",
|
||||||
|
"imported": true,
|
||||||
|
"uuid": "0c2ba096-89cd-4e81-bb73-8a02831db975",
|
||||||
|
"files": [],
|
||||||
|
"subMetas": {},
|
||||||
|
"userData": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"ver": "1.2.0",
|
||||||
|
"importer": "directory",
|
||||||
|
"imported": true,
|
||||||
|
"uuid": "84ea36f8-e700-4315-8516-373d82c81cd6",
|
||||||
|
"files": [],
|
||||||
|
"subMetas": {},
|
||||||
|
"userData": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"ver": "1.2.0",
|
||||||
|
"importer": "directory",
|
||||||
|
"imported": true,
|
||||||
|
"uuid": "d6eb348d-52cc-40e0-9de8-e3018ec92af2",
|
||||||
|
"files": [],
|
||||||
|
"subMetas": {},
|
||||||
|
"userData": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"ver": "1.2.0",
|
||||||
|
"importer": "directory",
|
||||||
|
"imported": true,
|
||||||
|
"uuid": "2690e23c-9deb-4acd-818d-bec476786aad",
|
||||||
|
"files": [],
|
||||||
|
"subMetas": {},
|
||||||
|
"userData": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"ver": "1.2.0",
|
||||||
|
"importer": "directory",
|
||||||
|
"imported": true,
|
||||||
|
"uuid": "649ca5c0-9d88-48ee-8cb4-269768037b5d",
|
||||||
|
"files": [],
|
||||||
|
"subMetas": {},
|
||||||
|
"userData": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"ver": "1.2.0",
|
||||||
|
"importer": "directory",
|
||||||
|
"imported": true,
|
||||||
|
"uuid": "3bc478de-2530-4d7a-ac17-861f3347644e",
|
||||||
|
"files": [],
|
||||||
|
"subMetas": {},
|
||||||
|
"userData": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1,65 @@
|
|||||||
|
/**
|
||||||
|
* Deterministic pseudo-random generator.
|
||||||
|
*
|
||||||
|
* The whole rules core is reproducible from a seed: given the same seed and the
|
||||||
|
* same sequence of actions, a match replays identically. That is what lets a bug
|
||||||
|
* report be a single integer, and what keeps the soak tests meaningful.
|
||||||
|
*
|
||||||
|
* Algorithm is mulberry32 — small, fast, and good enough for shuffling cards.
|
||||||
|
* Its entire state is one 32-bit integer, so it serialises into the save/state
|
||||||
|
* without ceremony.
|
||||||
|
*/
|
||||||
|
export class Rng {
|
||||||
|
private _state: number;
|
||||||
|
|
||||||
|
constructor(seed: number) {
|
||||||
|
// Force to uint32 so a negative or fractional seed still behaves.
|
||||||
|
this._state = seed >>> 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Current internal state, for serialising a game in progress. */
|
||||||
|
get state(): number {
|
||||||
|
return this._state;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Restores a generator to a previously captured state. */
|
||||||
|
static fromState(state: number): Rng {
|
||||||
|
return new Rng(state);
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Uniform float in [0, 1). */
|
||||||
|
next(): number {
|
||||||
|
this._state = (this._state + 0x6d2b79f5) >>> 0;
|
||||||
|
let t = this._state;
|
||||||
|
t = Math.imul(t ^ (t >>> 15), t | 1);
|
||||||
|
t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
|
||||||
|
return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Uniform integer in [0, bound). `bound` must be positive. */
|
||||||
|
nextInt(bound: number): number {
|
||||||
|
if (bound <= 0) {
|
||||||
|
throw new RangeError(`Rng.nextInt bound must be positive, got ${bound}`);
|
||||||
|
}
|
||||||
|
return Math.floor(this.next() * bound);
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Uniformly picks one element. Throws on an empty array. */
|
||||||
|
pick<T>(items: readonly T[]): T {
|
||||||
|
if (items.length === 0) {
|
||||||
|
throw new RangeError('Rng.pick called on an empty array');
|
||||||
|
}
|
||||||
|
return items[this.nextInt(items.length)];
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Fisher-Yates, in place. Returns the same array for convenience. */
|
||||||
|
shuffle<T>(items: T[]): T[] {
|
||||||
|
for (let i = items.length - 1; i > 0; i--) {
|
||||||
|
const j = this.nextInt(i + 1);
|
||||||
|
const tmp = items[i];
|
||||||
|
items[i] = items[j];
|
||||||
|
items[j] = tmp;
|
||||||
|
}
|
||||||
|
return items;
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"ver": "4.0.24",
|
||||||
|
"importer": "typescript",
|
||||||
|
"imported": true,
|
||||||
|
"uuid": "e9145215-b0c0-46a4-83b9-caf393a20cc1",
|
||||||
|
"files": [],
|
||||||
|
"subMetas": {},
|
||||||
|
"userData": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"ver": "1.2.0",
|
||||||
|
"importer": "directory",
|
||||||
|
"imported": true,
|
||||||
|
"uuid": "ce55fda9-c26d-4c2b-9baa-d7e8e5e1f49b",
|
||||||
|
"files": [],
|
||||||
|
"subMetas": {},
|
||||||
|
"userData": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"ver": "1.2.0",
|
||||||
|
"importer": "directory",
|
||||||
|
"imported": true,
|
||||||
|
"uuid": "b0733617-74e3-450d-9dfd-97cf9ef75e93",
|
||||||
|
"files": [],
|
||||||
|
"subMetas": {},
|
||||||
|
"userData": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"ver": "1.2.0",
|
||||||
|
"importer": "directory",
|
||||||
|
"imported": true,
|
||||||
|
"uuid": "d6076a47-71fc-41a3-82a7-a5a59d79a52e",
|
||||||
|
"files": [],
|
||||||
|
"subMetas": {},
|
||||||
|
"userData": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"ver": "1.2.0",
|
||||||
|
"importer": "directory",
|
||||||
|
"imported": true,
|
||||||
|
"uuid": "6c370e15-1daf-4bea-99fa-29acbaa3e03c",
|
||||||
|
"files": [],
|
||||||
|
"subMetas": {},
|
||||||
|
"userData": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"ver": "1.2.0",
|
||||||
|
"importer": "directory",
|
||||||
|
"imported": true,
|
||||||
|
"uuid": "bc778720-1b57-4cc0-b7d1-3c4f8dcdc51d",
|
||||||
|
"files": [],
|
||||||
|
"subMetas": {},
|
||||||
|
"userData": {}
|
||||||
|
}
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"ver": "1.2.0",
|
||||||
|
"importer": "directory",
|
||||||
|
"imported": true,
|
||||||
|
"uuid": "f2b25917-c1a9-486b-b671-760782f37bcd",
|
||||||
|
"files": [],
|
||||||
|
"subMetas": {},
|
||||||
|
"userData": {}
|
||||||
|
}
|
||||||
@@ -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
|
(`extensions/cocos-code-mode/node_modules` is gitignored, so that install does not
|
||||||
survive a clean checkout either.)
|
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.
|
||||||
Generated
+1606
File diff suppressed because it is too large
Load Diff
@@ -7,5 +7,15 @@
|
|||||||
"dependencies": {
|
"dependencies": {
|
||||||
"@utcp/code-mode": "^1.2.13",
|
"@utcp/code-mode": "^1.2.13",
|
||||||
"sharp": "^0.35.4"
|
"sharp": "^0.35.4"
|
||||||
|
},
|
||||||
|
"devDependencies": {
|
||||||
|
"typescript": "~5.6",
|
||||||
|
"vitest": "^3.2.7"
|
||||||
|
},
|
||||||
|
"scripts": {
|
||||||
|
"test": "vitest run",
|
||||||
|
"test:watch": "vitest",
|
||||||
|
"typecheck": "tsc -p tsconfig.test.json",
|
||||||
|
"check:core-purity": "node scripts/check-core-purity.mjs"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -0,0 +1,28 @@
|
|||||||
|
// Guards the one architectural rule that the type system cannot express:
|
||||||
|
// assets/scripts/core must never import the Cocos engine. See docs/TECHNICAL.md.
|
||||||
|
import { readdirSync, readFileSync, statSync } from 'node:fs';
|
||||||
|
import { join } from 'node:path';
|
||||||
|
|
||||||
|
const ROOT = 'assets/scripts/core';
|
||||||
|
const FORBIDDEN = /from\s+['"](cc|cc\/env|db:\/\/)/;
|
||||||
|
const offenders = [];
|
||||||
|
|
||||||
|
function walk(dir) {
|
||||||
|
for (const entry of readdirSync(dir)) {
|
||||||
|
const p = join(dir, entry);
|
||||||
|
if (statSync(p).isDirectory()) walk(p);
|
||||||
|
else if (p.endsWith('.ts')) {
|
||||||
|
const src = readFileSync(p, 'utf8');
|
||||||
|
src.split('\n').forEach((line, i) => {
|
||||||
|
if (FORBIDDEN.test(line)) offenders.push(`${p}:${i + 1} ${line.trim()}`);
|
||||||
|
});
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
walk(ROOT);
|
||||||
|
if (offenders.length) {
|
||||||
|
console.error('core/ must not import the engine:\n' + offenders.join('\n'));
|
||||||
|
process.exit(1);
|
||||||
|
}
|
||||||
|
console.log('core purity OK');
|
||||||
@@ -1,3 +1,14 @@
|
|||||||
{
|
{
|
||||||
"__version__": "1.0.6"
|
"__version__": "1.0.6",
|
||||||
|
"general": {
|
||||||
|
"designResolution": {
|
||||||
|
"width": 1080,
|
||||||
|
"height": 1920,
|
||||||
|
"fitWidth": true,
|
||||||
|
"fitHeight": false
|
||||||
|
},
|
||||||
|
"renderPipeline": "fd8ec536-a354-4a17-9c74-4f3883c378c8",
|
||||||
|
"highQuality": false,
|
||||||
|
"downloadMaxConcurrency": 15
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -0,0 +1,62 @@
|
|||||||
|
import { describe, expect, it } from 'vitest';
|
||||||
|
import { Rng } from '@core/util/Rng';
|
||||||
|
|
||||||
|
describe('Rng', () => {
|
||||||
|
it('is deterministic for a given seed', () => {
|
||||||
|
const a = Array.from({ length: 20 }, () => new Rng(42).next());
|
||||||
|
expect(new Set(a).size).toBe(1);
|
||||||
|
|
||||||
|
const first = new Rng(7);
|
||||||
|
const second = new Rng(7);
|
||||||
|
for (let i = 0; i < 100; i++) {
|
||||||
|
expect(first.next()).toBe(second.next());
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('produces different streams for different seeds', () => {
|
||||||
|
const a = new Rng(1);
|
||||||
|
const b = new Rng(2);
|
||||||
|
const differs = Array.from({ length: 10 }, () => a.next() !== b.next());
|
||||||
|
expect(differs.some(Boolean)).toBe(true);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('resumes from a captured state', () => {
|
||||||
|
const source = new Rng(123);
|
||||||
|
for (let i = 0; i < 5; i++) source.next();
|
||||||
|
|
||||||
|
const resumed = Rng.fromState(source.state);
|
||||||
|
for (let i = 0; i < 20; i++) {
|
||||||
|
expect(resumed.next()).toBe(source.next());
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('keeps nextInt inside its bound', () => {
|
||||||
|
const rng = new Rng(99);
|
||||||
|
for (let i = 0; i < 10000; i++) {
|
||||||
|
const v = rng.nextInt(36);
|
||||||
|
expect(v).toBeGreaterThanOrEqual(0);
|
||||||
|
expect(v).toBeLessThan(36);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('rejects a non-positive bound and an empty pick', () => {
|
||||||
|
const rng = new Rng(1);
|
||||||
|
expect(() => rng.nextInt(0)).toThrow(RangeError);
|
||||||
|
expect(() => rng.pick([])).toThrow(RangeError);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('shuffles as a permutation, not a resample', () => {
|
||||||
|
const rng = new Rng(2024);
|
||||||
|
const original = Array.from({ length: 36 }, (_, i) => i);
|
||||||
|
const shuffled = rng.shuffle([...original]);
|
||||||
|
|
||||||
|
expect(shuffled).toHaveLength(36);
|
||||||
|
expect([...shuffled].sort((x, y) => x - y)).toEqual(original);
|
||||||
|
expect(shuffled).not.toEqual(original);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('shuffles reproducibly', () => {
|
||||||
|
const deck = () => Array.from({ length: 36 }, (_, i) => i);
|
||||||
|
expect(new Rng(5).shuffle(deck())).toEqual(new Rng(5).shuffle(deck()));
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,17 @@
|
|||||||
|
{
|
||||||
|
/* Strict type-check for the engine-independent layers. Not used by Cocos. */
|
||||||
|
"compilerOptions": {
|
||||||
|
"target": "ES2020",
|
||||||
|
"module": "ESNext",
|
||||||
|
"moduleResolution": "bundler",
|
||||||
|
"strict": true,
|
||||||
|
"noEmit": true,
|
||||||
|
"skipLibCheck": true,
|
||||||
|
"types": ["vitest/globals"],
|
||||||
|
"baseUrl": ".",
|
||||||
|
"paths": {
|
||||||
|
"@core/*": ["assets/scripts/core/*"]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"include": ["assets/scripts/core/**/*.ts", "tests/**/*.ts"]
|
||||||
|
}
|
||||||
@@ -0,0 +1,14 @@
|
|||||||
|
import { defineConfig } from 'vitest/config';
|
||||||
|
import { resolve } from 'node:path';
|
||||||
|
|
||||||
|
export default defineConfig({
|
||||||
|
resolve: {
|
||||||
|
alias: {
|
||||||
|
'@core': resolve(__dirname, 'assets/scripts/core'),
|
||||||
|
},
|
||||||
|
},
|
||||||
|
test: {
|
||||||
|
include: ['tests/**/*.spec.ts'],
|
||||||
|
environment: 'node',
|
||||||
|
},
|
||||||
|
});
|
||||||
Reference in New Issue
Block a user