scopone/docs/FINDINGS.md

Findings

Last Updated: 2026-04-08T19:48:08.000Z

Summary

Initializer refresh for SCOPONE-0009. The cached findings were stale relative to the live source tree, so the observations below reflect the current Phaser, worker, and AI implementation.

Codebase Observations

• Primary gameplay code currently lives in 10 TypeScript source files under src/; the Android wrapper adds 3 Java files.
• The project is structurally split between framework-free gameplay modules in src/game/ and Phaser scene code in src/scenes/.
• src/scenes/GameScene.ts and src/game/ai.ts remain the two largest concentrations of application logic.
• The AI transport layer is now a stable three-file path: ai-worker-protocol.ts, ai-worker-client.ts, and ai.worker.ts.
• The AI exposes three difficulty levels: beginner, advanced, and master.
• advanced and master both use CardTracker to reason about unseen cards without directly reading hidden hands.
• The current master search profile is timeBudgetMs: 4600, sampleCount: 10, maxDepth: 6, batchSize: 2.
• GameScene consumes AI progress callbacks to update an on-screen think bar while a worker request is running.
• AIWorkerClient fails over pending work to in-thread chooseMove() if worker creation, posting, or deserialization fails.
• The Android wrapper targets SDK 36 with minSdkVersion 24 and applies immersive mode from the native activity.
• Audio remains procedural via Web Audio; no dedicated audio asset pipeline is present in the source tree.
• No ESLint or Prettier configuration is present.
• The only repository-wide verification command supplied is npx tsc --noEmit.

Potential Improvement Areas

• GameScene.ts still centralizes layout, turn flow, HUD updates, effects, and audio in one scene class, which raises maintenance cost.
• ai.ts still combines heuristic tiers, inference helpers, determinization, and alpha-beta evaluation in one module.
• Worker transport is isolated cleanly, but progress rendering remains coupled to scene-level UI concerns.
• A 4600 ms master search budget may still be noticeable on slower mobile devices even with batch yielding.
• There is no dedicated automated rules or AI test suite beyond type-checking.
• Formatting and style are enforced socially rather than by automated linting or formatting tools.

Current Rule / Implementation Notes

Capture behavior in engine.ts

• Direct-match capture has priority over subset-sum capture.
• When multiple direct matches exist, findCaptures() returns one single-card option per matching card.
• Subset-sum captures are considered only when no direct match exists.
• applyMove() defaults to the first legal capture if no explicit capture choice is supplied.
• Scope is awarded only when a capture clears the table before the final play of the round.

AI implementation snapshot

• beginner uses a simpler heuristic with noise to remain beatable.
• advanced adds race awareness, anti-scopa logic, partner setup, anchor play, and tracker-based probability estimates.
• master orders legal moves with a quick evaluator, samples hidden hands, and scores them with alpha-beta search under the active deadline.
• Progress is reported through AIDecisionProgress so the scene can keep the think bar responsive.

Worker execution snapshot

• GameScene creates AIWorkerClient during create() and disposes it on both shutdown and destroy.
• AIWorkerClient serializes CardTracker state through toSnapshot() instead of attempting to transfer the class instance.
• ai.worker.ts rebuilds tracker state with CardTracker.fromSnapshot() before calling chooseMove().
• Progress, result, and serialized error payloads all travel through ai-worker-protocol.ts.
• If worker execution becomes unavailable, pending requests are rerun with the in-thread AI path rather than being dropped.

Scene / UI implementation snapshot

• BootScene loads atlas assets and presents a simple loading bar.
• MenuScene exposes difficulty selection before match start.
• GameScene tracks played and captured cards in CardTracker as the round evolves.
• The scene owns score HUD rendering, player labels, status text, think-bar rendering, and procedural particle effects.
• Round-end and match-end flows remain managed inside the scene instead of separate overlay components.

Research Performed

Web Research: Scopone Scientifico Rules (2026-03-31)

Sources: Wikipedia (Scopa article, Scopone section), Pagat.com (Scopone page by John McLeod)

Core Rules (Scopone Scientifico variant)

• 4 players, 2 fixed teams of 2 (sit opposite): Team A = players 0+2, Team B = players 1+3.
• 40-card Napoletane deck: 4 suits (bastoni, coppe, denara, spade), values 1-10.
• All 40 cards are dealt at the start of the round; the table begins empty.
• Turns advance in the implementation as 0 -> 1 -> 2 -> 3.

Capture Rules

1. If the played card matches one or more table cards by value, a direct match must be taken.
2. If multiple direct matches exist, one matching table card is chosen.
3. If no direct match exists, a subset of table cards may be captured when their values sum to the played value.
4. A direct match has priority over any possible sum capture.
5. Scopa awards a point only when the table is cleared before the final play of the round.

Scoring

Category	Rule
Carte	Majority of captured cards
Denari	Majority of denara suit cards
Settebello	Team that captures the 7 of denara
Primiera	Highest best-of-each-suit prime value
Scope	One point per scopa

Primiera values used in code

Card value	Primiera value
7	21
6	18
1	16
5	15
4	14
3	13
2	12
8, 9, 10	10

SCOPONE-0008: AI progress rendering notes (2026-04-02)

• The current implementation does not use Phaser TimerEvent progress helpers.
• Instead, chooseMove() emits its own normalized progress payload through AIDecisionProgress.
• GameScene.updateThinkBar() renders remaining time from that callback.
• The yielding behavior in the master search path is necessary so the browser can repaint while search batches continue.

SCOPONE-0009: Phaser scene lifecycle notes (2026-04-08)

• Source: Context7 /websites/phaser_io_api-documentation, query Phaser 3.87 Scene lifecycle create restart shutdown destroy event listeners scene restart preserving external state.
• Phaser dispatches shutdown when a scene stops being active but may be re-used later; resource cleanup that should also cover final teardown can additionally listen to destroy.
• The current GameScene pattern of registering one-shot shutdown and destroy handlers is aligned with Phaser guidance for worker disposal and UI cleanup.
• Dealer rotation and next-round state changes can stay inside the existing in-scene orchestration without requiring a different Phaser lifecycle primitive.