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, then → lobby
    lobby.scene               main menu; hosts the match UI
  prefabs/
    card.prefab               one playing card, face or back
    ...
  art/
    cards/                    36 faces + back, packed into cards.pac (2048²)
    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/
      lobby/                  lobby screen controller
      game/                   match screen: hand, table, deck, animations
      common/                 reusable widgets, safe-area root
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.

## 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/art/cards/ATTRIBUTION.md`](../assets/art/cards/ATTRIBUTION.md), which
also explains what would have to change to drop the dependency.

### Builds

Web: `web-mobile` template. Mobile: ASTC textures per [ART.md](ART.md), PNG for
web.