mozempk/scopone
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 228 Activity

feat(SCOPONE-0010): vendor agent assets and clean docs

Browse Source
This commit is contained in:
Giancarmine Salucci
2026-04-10 22:35:01 +02:00
parent a4e2891c87
commit 5370876db3
32 changed files with 4046 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files

99
docs/ARCHITECTURE.md
View File

@@ -1,6 +1,6 @@
# Architecture
> Last Updated: 2026-04-09T20:59:51.000Z
> Last Updated: 2026-04-10T20:33:00.000Z
## Overview
@@ -8,15 +8,15 @@
|-----------|-------|
| Primary language | TypeScript |
| Secondary language | Java |
| Source counts | 15 TypeScript files under `src/`, 3 Java files under `android/` |
| Source counts | 17 TypeScript source files under `src/`, 3 Java files under `android/app/src/` |
| Project type | Phaser browser game packaged for Android with Capacitor |
| Framework | Phaser 3.87.0 |
| Tooling | Vite 5, TypeScript 5.x, Capacitor 8.3, tsx 4.19 |
| Tooling | Vite 5.x, TypeScript 5.x, Capacitor 8.3.x, tsx 4.19.x |
| Runtime layout | 1280 x 720, `Phaser.Scale.FIT`, centered in `#game` |
| Build command | `npm run build` |
| Test command | `npx tsc --noEmit` |
| Verification command | `npx tsc --noEmit` |
The repository is a TypeScript-first implementation of Scopone Scientifico. Pure game rules, scoring, imperfect-information tracking, AI heuristics, worker transport, and benchmark code live under `src/game/`. Phaser scenes under `src/scenes/` own rendering, input, animation, menu flow, status messaging, and procedural audio. The `android/` tree is a Capacitor wrapper with a small custom `MainActivity` that forces immersive full-screen behavior.
The repository is a TypeScript-first implementation of Scopone Scientifico. Pure rules, scoring, imperfect-information tracking, AI heuristics, worker transport, and benchmark code live under `src/game/`. Phaser scenes under `src/scenes/` own rendering, input, pacing, menus, and procedural audio. The `android/` tree is a Capacitor wrapper with Gradle configuration and a custom `MainActivity` for immersive full-screen behavior.
## Project Structure
@@ -25,24 +25,25 @@ scopone-phaser/
|- src/
| |- main.ts
| |- game/
| | |- types.ts
| | |- engine.ts
| | |- card-tracker.ts
| | |- preferences.ts
| | |- ai.ts
| | |- ai-worker-protocol.ts
| | |- ai-worker-client.ts
| | |- ai.worker.ts
| | |- ai-benchmark-fixtures.ts
| | |- ai-benchmark.ts
| | `- ai-benchmark-fixtures.ts
| | |- ai-worker-client.ts
| | |- ai-worker-protocol.ts
| | |- ai.ts
| | |- ai.worker.ts
| | |- card-tracker.ts
| | |- engine.ts
| | |- preferences.ts
| | `- types.ts
| `- scenes/
| |- BootScene.ts
| |- GameScene.ts
| |- MenuScene.ts
| |- SettingsScene.ts
| `- GameScene.ts
| `- SettingsScene.ts
|- public/
|- android/
| |- app/
| |- build.gradle
| `- variables.gradle
|- docs/
|- prompts/
@@ -56,16 +57,16 @@ scopone-phaser/
| Directory | Purpose |
|-----------|---------|
| `src/game/` | Rules engine, score calculation, imperfect-information tracking, audio preference persistence, AI heuristics, worker transport, and benchmark harnesses |
| `src/scenes/` | Phaser scene lifecycle, menus, settings UI, board rendering, interaction, HUD, audio, and FX |
| `public/` | Atlas metadata and static assets loaded by Phaser |
| `android/` | Capacitor Android project, Gradle configuration, generated wrapper assets, and the native activity |
| `src/game/` | Rules engine, state transitions, score calculation, hidden-information tracking, audio preference persistence, AI heuristics, worker protocol, and benchmark harnesses |
| `src/scenes/` | Phaser scene lifecycle, menu flow, settings UI, board rendering, HUD, interaction, particles, and audio playback |
| `public/` | Card atlas metadata and other static assets loaded by Phaser |
| `android/` | Capacitor Android project, Gradle configuration, generated wrapper assets, and native activity code |
| `docs/` | Architecture, code style, findings, and cache metadata |
| `prompts/` | JIRA workflow artifacts and iteration state |
## Design Patterns
No explicit GoF patterns were detected in the source or by semantic search.
No explicit design patterns were detected by semantic search.
Observed architectural patterns:
@@ -73,10 +74,10 @@ Observed architectural patterns:
|---------|------------------|
| Scene-based flow | `BootScene -> MenuScene -> GameScene`, with `SettingsScene` opened from the menu and returning to it |
| Functional core / imperative shell | `src/game/` avoids Phaser imports while `src/scenes/` owns runtime side effects |
| Immutable state transitions | `applyMove()` clones `GameState` before mutating round state |
| Immutable state transitions | `applyMove()` clones `GameState` before applying turn mutations |
| Worker offload with fallback | `AIWorkerClient` uses `ai.worker.ts` when available and falls back to direct `chooseMove()` otherwise |
| Typed message protocol | `ai-worker-protocol.ts` defines worker request, progress, result, and serialized error shapes |
| Persistence adapter | `preferences.ts` normalizes and stores audio settings through a storage boundary instead of scene-local flags |
| Persistence adapter | `preferences.ts` normalizes and stores audio settings through a storage boundary |
| Deterministic benchmark harness | `ai-benchmark.ts` uses fixtures, seeded self-play, and simulated timing sources to evaluate AI quality |
## Key Components
@@ -85,49 +86,49 @@ Observed architectural patterns:
- Creates the `Phaser.Game` instance.
- Installs a one-shot fullscreen request on first user input when supported.
- Registers `BootScene`, `MenuScene`, `GameScene`, and a local `SettingsScene` placeholder; `MenuScene` replaces that placeholder with the concrete `src/scenes/SettingsScene.ts` class before navigation.
- Registers `BootScene`, `MenuScene`, `GameScene`, and `SettingsScene` directly in the Phaser game config.
### `src/game/types.ts`
- Defines the core game model: `Card`, `Capture`, `Player`, `GameState`, `TeamScore`, and `ScoreBreakdown`.
- Models constrained domains with unions such as `PlayerIndex`, `Difficulty`, and `DealerRelativeRole`.
- Stores `PRIMIERA_VALUES` for end-of-round scoring.
- Stores `PRIMIERA_VALUES` for primiera scoring.
### `src/game/engine.ts`
- Builds and shuffles the 40-card deck.
- Creates a round state for four players with dealer-relative opening order and stable player labels.
- Creates a four-player round state with dealer-relative opening order and stable player labels.
- Implements Scopone capture rules where direct value matches take priority over subset-sum captures.
- Applies moves immutably, awards scopa only before the final play, assigns leftover table cards to the last capturing team, and computes round and match scoring.
- Applies moves immutably, awards scopa only before the final play, assigns leftover table cards to the last capturing team, and computes round scoring.
### `src/game/card-tracker.ts`
- Tracks cards visible through play and capture events without exposing hidden hands.
- Reconstructs unseen cards from `played + myHand + table`.
- Supplies suit counts, same-rank residue summaries, and hand-value probabilities used by the AI tiers.
- Reconstructs unseen cards from visible information.
- Supplies suit counts, same-rank residue summaries, and probability signals used by higher AI tiers.
### `src/game/preferences.ts`
- Defines the persisted audio preference model.
- Normalizes possibly invalid storage payloads back to safe defaults.
- Normalizes invalid storage payloads back to safe defaults.
- Loads and saves preferences through `localStorage` when available, with browser-safe fallbacks.
### `src/game/ai.ts`
- Exposes `chooseMove()` as the async AI entry point.
- Implements three difficulty tiers: `beginner`, `advanced`, and `master`.
- Uses role-aware heuristics, tracker-based inference, tactical priority scoring, determinization sampling, and alpha-beta search.
- Applies dynamic master search profiles based on total cards remaining, ranging from the base profile `4300 ms / 8 samples / depth 5 / batch 2` down to `3200 ms / 4 samples / exact endgame depth / batch 1` in the last four cards.
- Uses tracker-based inference, tactical scoring, determinization sampling, and alpha-beta search.
- Applies dynamic master search profiles, with a base profile of `4300 ms / 8 samples / depth 5 / batch 2` and tighter endgame branches down to `3200 ms / 4 samples / exact remaining depth / batch 1`.
### `src/game/ai-worker-protocol.ts`
- Defines a single `choose-move` worker request type.
- Defines typed progress, result, and serialized error responses.
- Keeps worker communication schema isolated from UI code.
- Keeps worker communication schema isolated from scene code.
### `src/game/ai-worker-client.ts`
- Wraps worker lifecycle and pending-request tracking behind the same `chooseMove()` API that scenes consume.
- Wraps worker lifecycle and pending-request tracking behind the same `chooseMove()` API scenes consume.
- Creates the worker as an ES module with `new Worker(new URL('./ai.worker.ts', import.meta.url), { type: 'module' })`.
- Fails over pending requests to in-thread AI execution if worker creation, posting, or deserialization fails.
@@ -139,21 +140,21 @@ Observed architectural patterns:
### `src/game/ai-benchmark.ts` and `src/game/ai-benchmark-fixtures.ts`
- Define the AI quality harness invoked by `npm run benchmark:ai-quality`.
- Combine fixed fixtures, critical-concept checks, seeded self-play, regression watchlists, and simulated timing sources.
- Encode the current iteration 5 benchmark contract: 13 fixed fixtures, 6 critical concepts, and 48 self-play matches.
- Define the AI quality harness exposed as `npm run benchmark:ai-quality`.
- Combine fixed fixtures, critical-concept checks, seeded self-play, and simulated timing sources.
- Enforce the current iteration 5 contract: 13 fixed fixtures, 6 critical concepts, and 48 self-play matches.
### `src/scenes/BootScene.ts`
- Loads the card atlas and card back.
- Displays a simple loading bar.
- Displays a loading bar.
- Transitions into `MenuScene` after asset load.
### `src/scenes/MenuScene.ts`
- Renders the title, compact rules summary, difficulty selection, and audio-settings entry point.
- Reads persisted audio preferences to describe current state before match start.
- Ensures the concrete `SettingsScene` class is registered before opening it.
- Renders the title, rules summary, difficulty selection, and audio-settings entry point.
- Reads persisted audio preferences before match start.
- Computes separate desktop and compact-viewport layouts for responsive menu composition.
### `src/scenes/SettingsScene.ts`
@@ -163,16 +164,16 @@ Observed architectural patterns:
### `src/scenes/GameScene.ts`
- Owns match flow, dealing, selection, capture resolution, AI turn orchestration, score HUD, status UI, think bar, particles, and procedural audio.
- Owns match flow, dealing, selection, capture resolution, AI orchestration, score HUD, status UI, think bar, particles, and procedural audio.
- Instantiates and disposes `AIWorkerClient` on scene lifecycle events.
- Enforces a minimum AI think display time and timer-based move outcome status messages.
- Enforces `AI_MIN_THINK_MS = 1000` and `MOVE_OUTCOME_STATUS_MS = 2000` through timer-backed scene logic.
- Reads normalized audio preferences from scene data or persisted storage.
- Updates `CardTracker` after play and capture events so AI inference remains derived from visible information.
### `android/app/src/main/java/com/phaser/scopa/MainActivity.java`
- Extends `BridgeActivity`.
- Applies immersive mode during `onCreate()` and whenever window focus returns.
- Applies immersive mode during `onCreate()` and when window focus returns.
- Hides status and navigation bars with transient swipe behavior.
## Dependencies
@@ -219,7 +220,7 @@ Observed architectural patterns:
main.ts
-> BootScene
-> MenuScene
-> SettingsScene (opened on demand after dynamic registration)
-> SettingsScene
-> GameScene
-> engine.ts
-> types.ts
@@ -248,7 +249,7 @@ Application-level dependency direction is one-way:
2. `BootScene` loads atlas assets and starts `MenuScene`.
3. `MenuScene` reads persisted audio preferences, lets the player choose difficulty, and can open `SettingsScene` for audio toggles.
4. `SettingsScene` writes audio preferences immediately and returns to `MenuScene`.
5. `GameScene.create()` normalizes incoming scene data, creates a fresh `CardTracker`, constructs a new `GameState`, and starts the opening deal.
5. `GameScene.create()` normalizes incoming scene data, creates a fresh `CardTracker`, creates a new `GameState`, and starts the opening deal.
6. Human turns use pointer-driven card selection and `findCaptures()` output to choose legal captures.
7. AI turns call `AIWorkerClient.chooseMove(state, playerIdx, difficulty, tracker, onProgress)`.
8. `AIWorkerClient` posts a typed request to `ai.worker.ts`; if workers are unavailable, it reruns the same request in-thread.
@@ -262,7 +263,9 @@ Application-level dependency direction is one-way:
| Command | Source | Purpose |
|---------|--------|---------|
| `npm run dev` | `package.json` | Starts the Vite dev server |
| `npm run build` | user-provided build command | Runs `tsc && vite build` and writes web output to `dist/` |
| `npm run build` | `package.json` | Runs `tsc && vite build` and writes web output to `dist/` |
| `npm run preview` | `package.json` | Serves the built app with Vite preview |
| `npm run benchmark:ai-quality` | `package.json` | Runs the AI benchmark harness through `tsx` |
| `npx tsc --noEmit` | user-provided test command | Type-checks the TypeScript codebase without emitting files |
| `npx tsc --noEmit` | inferred TypeScript verification | Type-checks the codebase without emitting build artifacts |
No top-level `tests/` directory was discovered in the repository.