fool-cardgame/docs/TECHNICAL.md

# 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: { <key>: <payload> } }`. 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 `<rank>_of_<suit>`,
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=<loader.scene uuid>"
```

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`.