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
|
||||
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": {
|
||||
"@utcp/code-mode": "^1.2.13",
|
||||
"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