# 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 `npm run check:core-purity`: **nothing under `assets/scripts/core/` may import from `cc`**, and under `assets/scripts/modules/` only the adapters explicitly listed in that script may. Everything else is plain TypeScript, runnable under Node, which is what makes the rules and the save format testable without the engine. ## Folder map ``` assets/ scenes/ loader.scene module init and art preload, then → lobby lobby.scene Canvas > Background, Safe > LobbyRoot | GameRoot prefabs/ card.prefab one playing card, face or back resources/ cards/ 36 faces + back + cards.pac, loaded by path art/ ui/ table surface, nine-slice panels and buttons scripts/ core/ PURE TS — no engine imports cards/ Suit, Rank, Card, Deck rules/ GameState, actions, events, the reducer bot/ PlayerView projection, Bot contract, BasicBot match/ Match (stateful shell), runMatch (headless driver) util/ seeded RNG, shuffle modules/ save/ SaveManager, ISaveSection, StatsSection, IStorage + MemoryStorage, CocosStorage (engine) app/ Bootstrap, ServiceLocator, SceneRouter ui/ MainFlow.ts owns both screens and moves between them lobby/ LobbyScreen: statistics and the New Game button game/ GameScreen, CardView, CardLibrary common/ Theme (layout, palette, timings), Strings tests/ core/ vitest specs against assets/scripts/core support/ position fixtures and the state invariant checker tools/ measuring tools, not part of the suite art-src/cards/ vector sources for the card faces (LGPL, kept) docs/ specs, this file, plan, decisions local/ scratch art storage; contents get consumed scripts/ build and check tools run through npm 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 `decide(view: PlayerView) => Action`. `PlayerView` is a projection of `GameState` containing only legitimately visible information — own hand, table, trump, opponents' hand *sizes*, deck and discard counts — plus the list of legal actions. `BasicBot` implements the policy in [GAMEPLAY.md](GAMEPLAY.md). `Match` wraps the reducer with the current state and an event subscription; the game screen and the headless `runMatch` driver both hold one. As a reference point, 5000 `BasicBot` self-play matches split roughly 43/43/14 between the two seats and draws, with the opening attacker losing about 37% of the time — `npm run stats:bot` reprints these. ## 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. The document written is `{ version, sections: { : } }`. Storage sits behind `IStorage`, so all of the save logic is testable headlessly; `CocosStorage` is the only file in the module that imports the engine, and it falls back to an in-memory store when the device refuses to persist (private browsing, a full quota) rather than taking the game down. ## The lobby scene Both screens live in one scene, per ARCHITECTURE.md, so starting a match is a change of visible root rather than a scene load: ``` Canvas (1080×1920, Canvas + MainFlow) Camera orthographic, UI_2D only, clears to table green Background table_bg, widget-stretched Safe cc.SafeArea — everything tappable is inside it LobbyRoot LobbyScreen: title, statistics panel, New Game GameRoot GameScreen + CardLibrary (inactive until a match starts) Deck / OpponentLabel / Message / CardLayer / ActionBar / QuitButton ResultOverlay dimmer, result panel, Back ``` `GameScreen` renders from the current `GameState` rather than replaying the event stream — see docs/DECISIONS.md. Card nodes are pooled and stay bound to their `Card` while it is visible, so movement is a tween to a new position. Buttons are `@property(Button)` references subscribed in `onLoad`; the scene's `clickEvents` lists are deliberately empty. ## 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/core` against `assets/scripts/core`. No editor required. The soak specs play several thousand complete matches and re-check every state invariant after every single action, so a rule regression surfaces at the move that caused it. ```bash npm run typecheck # strict tsc over core/ and the tests npm run check:core-purity # fails if core/ ever imports the engine npm run stats:bot # BasicBot self-play distribution, not a test ``` ### 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. ### Art ```bash npm run build:art ``` Regenerates every sprite in `assets/art` from source. Card faces are rasterised from the vectors in `art-src/cards`; the card back, table and UI chrome are authored as SVG inside [`scripts/build-art.mjs`](../scripts/build-art.mjs) and rasterised from there, so a colour or radius is changed in one readable place rather than in a binary. Fixed numbers the layout depends on: | | | |---|---| | Card sprite | 220 × 320 px | | Nine-slice border | 40 px on 120 × 120 tiles | | Table background | 540 × 960, drawn at 2× | Card sprite frames have trimming switched off, because layout maths assumes every card rect is exactly 220 × 320. Card faces are named `_of_`, matching `Card.assetName` — that string is the only contract between the rules core and the art. Licence: the faces are LGPL-3.0 and attribution is mandatory. See [`assets/resources/cards/ATTRIBUTION.md`](../assets/resources/cards/ATTRIBUTION.md), which also explains what would have to change to drop the dependency. ### Builds A headless build, which is what CI would run: ```bash "C:/ProgramData/cocos/editors/Creator/3.8.8/CocosCreator.exe" --project "C:/Work/fool-cardgame" --build "platform=web-mobile;debug=true;startScene=" ``` It writes to `build/web-mobile` in about 40 seconds. Two caveats: it starts a second editor instance, so it competes with a running editor for `temp/logs/project.log` and can fail with a duplicate-class error — close the editor, or build from its Build panel. And `startScene` must be passed, or the build has no launch scene and stops on the splash. ### Per-platform texture settings [ART.md](ART.md) asks for ASTC on mobile and PNG on the web. Compression is set per image (or per folder) in the Inspector's texture-compress section, not in code, so it has to be applied once in the editor and is then stored in the `.meta` files: | Target | Setting | |---|---| | `web-mobile` | PNG, as now | | `android` | ASTC 6×6 for the card atlas, ASTC 4×4 for the UI sprites | | `ios` | the same ASTC settings; the format is supported on every device the game targets | The card atlas is the only texture where this matters — 2048×2048 uncompressed is 16 MB of video memory, and ASTC 6×6 brings that to roughly 1.2 MB. Do it before the first device build. ### Looking at it ```bash npm run serve ``` Serves `build/web-mobile` on http://localhost:8123, plus one route of its own: - `/_aspects` — the game in fixed-size iframes at 4:3, 16:9 and 21:9 portrait, side by side. The engine resizes itself to fill whatever window it is in, so an iframe is the only straightforward way to see the layout at a shape the desktop window is not. - `/_aspects?only=16:9&h=690` — one viewport, which boots much faster than three. The layout has been checked this way at all three ratios, and a full match played through in the browser: deal, attack, defend, take, discard, redraw, result overlay, and the statistics written and read back in the lobby. ### Three traps this project has already fallen into All three build and type-check cleanly, look right in the editor, and fail only at runtime. Each now has a guard; `npm run check` runs all of them. 1. **Node layers.** `nodeCreate` puts nodes on DEFAULT; a Canvas camera renders UI_2D only, so the build shows the camera's clear colour and nothing else. The scene view renders every layer, so the editor looks fine. 2. **The Canvas needs its own Widget.** Without one the Canvas keeps the size it was authored at and every widget-stretched child inherits it. `alignCanvasWithScreen` does not do this — it only adjusts the camera. 3. **Array spread of a non-array.** The build turns `[...x]` into `[].concat(x)`, which appends an iterator rather than expanding it. Use `Array.from`.