fool-cardgame/docs/DECISIONS.md

# 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/resources/cards/ATTRIBUTION.md`. The card back,
table surface and UI chrome are not in that set and are authored for this project.

## 2026-09-13 · Presentation · The screen renders state, it does not replay events

The rules emit an event stream, which invites an animation queue that replays it.

**Decision.** `GameScreen.render(state)` lays the whole table out from the current
state and tweens every card node to its new place. A card node stays bound to its
`Card` for as long as that card is visible.

**Why.** "The six of clubs moved from my hand to the table" then needs no special
case — it is the same node arriving at a new position. An event-driven queue has
to choreograph every transition by hand and desynchronises the moment one case is
missed. The event stream is still there for sound and for one-off flourishes.

## 2026-09-13 · Presentation · Card art lives in the `resources` bundle

The first attempt gave `CardLibrary` a `SpriteAtlas` reference to the auto-atlas
(`cards.pac`) and asked it for frames by name. The build came out with no card
textures at all.

**Decision.** The 36 faces and the back live in `assets/resources/cards` and are
loaded with `resources.loadDir`. `Bootstrap` preloads the folder in the loader
scene, so the lobby never waits.

**Why.** A `.pac` is a build-time packing instruction, not a runtime asset: it
packs whatever sprite frames the build already pulled in, and it cannot be loaded
and queried by name. Nothing referenced the individual frames, so nothing was
packed. The `.pac` still earns its keep — all 37 sprites end up in one 2048²
texture, so the whole table costs one draw call.

## 2026-09-13 · Presentation · Button clicks are wired in code

**Decision.** Buttons are exposed as `@property(Button)` and subscribed to in
`onLoad` rather than through the scene's `clickEvents` list.

**Why.** The wiring stays visible in the source, and renaming a handler becomes a
compile error instead of a button that silently stops working. (The editor tool
server also cannot write array-typed properties, which is how `clickEvents` is
stored — so this was the only option available to automation anyway.)

## 2026-09-13 · Presentation · Interface text is English, collected in one file

**Decision.** Every player-visible string is in
`assets/scripts/ui/common/Strings.ts`, in English.

**Why.** The specs, the code and the docs are all in English, and localisation is
out of scope for iteration 1. Keeping the strings together means switching
language — or adding one — is a change to that one file rather than a hunt
through scenes and components. Worth revisiting before release, given the game
is *durak*.

## 2026-09-13 · Presentation · One tap is the whole interaction

**Decision.** Tapping a card plays it. When defending, the attack being answered
is worked out from the card rather than selected separately. The logic lives in
`core/rules/intent.ts`, not in the component.

**Why.** Select-then-target doubles the taps for no gain, because the serialised
rules leave only one unanswered attack at a time. Putting it in the core means
the one piece of interface logic that can silently reject a legal move is covered
by headless tests, including a property test that it never proposes an action the
rules would refuse.

## 2026-09-13 · Presentation · The loader reports every step it takes

**Decision.** `Bootstrap` writes each stage to the on-screen label and to the
console, and falls through to the lobby after ten seconds even if the art
preload never calls back.

**Why.** The first build ran but showed nothing but a green screen, because
every node authored through the editor tools had been left on the DEFAULT layer
while the camera only renders UI_2D (see CODE_MODE_SETUP.md). A blank screen
carries no information about which step failed, and a loader that can hang
forever on an asset the lobby does not even need is a dead end for no reason.

## 2026-09-13 · Presentation · The vertical layout follows the screen edges

**Decision.** `Layout` holds fixed anchors only for things that live near the
centre, and every one of those is inside ±700. The player's hand and the action
bar are computed from the actual canvas height at render time (`bottomAnchors`),
and the Leave button is pinned to the top-left with a Widget.

**Why.** `fitWidth` means the width is always 1080 units but the height is not:
a 4:3 phone sees 1440 units (±720) and a 21:9 phone sees 2520 (±1260). The first
version used fixed design coordinates, which put the Leave button at y = 840 and
the bottom of the hand at −860 — both off screen on a 4:3 phone, the very case
docs/UI.md asks for. The table is also a single row of up to six slots rather
than two rows of three, which buys back the ~215 units of height that 4:3 cannot
spare, and the row is centred on the cards actually in play so a lone attacking
card sits in the middle of the table.

## 2026-09-13 · Build · Never array-spread anything that is not an array

The build transpiles `[...a, ...b]` to `[].concat(a, b)`. That is right for
arrays, but `Array.prototype.concat` does not expand an arbitrary iterable — it
appends it as a single element. `[...this._views.values()]` therefore produced a
one-element array holding the Map iterator, and the first card ever recycled
threw `view.cancelAnimations is not a function`.

**Decision.** Use `Array.from(...)` for anything that is not already an array,
and `npm run check:spreads` fails the build on `...x.values()`, `...x.keys()`,
`...x.entries()` and spreads of things named like a Map or Set.

**Why.** It type-checks, it reads correctly, and it only fails at runtime on a
real build — exactly the kind of mistake a static check earns its keep on.