231 lines
9.3 KiB
Markdown
231 lines
9.3 KiB
Markdown
# Architecture
|
|
|
|
> Last Updated: 2026-04-08T19:48:08.000Z
|
|
|
|
## Overview
|
|
|
|
| Attribute | Value |
|
|
|-----------|-------|
|
|
| Primary language | TypeScript |
|
|
| Secondary language | Java |
|
|
| Project type | Phaser browser game packaged for Android with Capacitor |
|
|
| Framework | Phaser 3.87.0 |
|
|
| Tooling | Vite 5, TypeScript 5.x, Capacitor 8.3 |
|
|
| Runtime layout | 1280 x 720, `Phaser.Scale.FIT`, centered in `#game` |
|
|
| Build command | `npm run build` |
|
|
| Test command | `npx tsc --noEmit` |
|
|
|
|
The repository is a TypeScript-first implementation of Scopone Scientifico. Gameplay rules, scoring, inference, and AI live in framework-independent modules under `src/game/`. Phaser scenes under `src/scenes/` own rendering, input, UI, animation, and scene transitions. The `android/` tree is a Capacitor wrapper with a small custom `MainActivity` for immersive full-screen behavior.
|
|
|
|
## Project Structure
|
|
|
|
```text
|
|
scopone-phaser/
|
|
|- src/
|
|
| |- main.ts
|
|
| |- game/
|
|
| | |- types.ts
|
|
| | |- engine.ts
|
|
| | |- card-tracker.ts
|
|
| | |- ai.ts
|
|
| | |- ai-worker-protocol.ts
|
|
| | |- ai-worker-client.ts
|
|
| | `- ai.worker.ts
|
|
| `- scenes/
|
|
| |- BootScene.ts
|
|
| |- MenuScene.ts
|
|
| `- GameScene.ts
|
|
|- public/
|
|
|- android/
|
|
| |- app/
|
|
| `- variables.gradle
|
|
|- docs/
|
|
|- prompts/
|
|
|- package.json
|
|
|- tsconfig.json
|
|
|- vite.config.ts
|
|
`- capacitor.config.ts
|
|
```
|
|
|
|
## Key Directories
|
|
|
|
| Directory | Purpose |
|
|
|-----------|---------|
|
|
| `src/game/` | Rules engine, score calculation, imperfect-information tracking, AI heuristics, and master search |
|
|
| `src/scenes/` | Phaser scene lifecycle, menus, board rendering, interaction, HUD, audio, and FX |
|
|
| `public/` | Atlas metadata and other static assets loaded by Phaser |
|
|
| `android/` | Capacitor Android project, Gradle configuration, generated wrapper assets, and the native activity |
|
|
| `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.
|
|
|
|
Observed architectural patterns:
|
|
|
|
| Pattern | Where it appears |
|
|
|---------|------------------|
|
|
| Scene-based flow | `BootScene -> MenuScene -> GameScene` via Phaser scene registration |
|
|
| 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 |
|
|
| 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 error shapes |
|
|
| Imperfect-information search | `CardTracker` plus determinization sampling support the `master` AI tier |
|
|
|
|
## Key Components
|
|
|
|
### `src/main.ts`
|
|
|
|
- Creates the `Phaser.Game` instance.
|
|
- Registers `BootScene`, `MenuScene`, and `GameScene`.
|
|
- Installs a one-shot fullscreen request on first user input when supported.
|
|
|
|
### `src/game/types.ts`
|
|
|
|
- Defines the core game model: `Card`, `Capture`, `Player`, `GameState`, `TeamScore`, and `ScoreBreakdown`.
|
|
- Models constrained domains with unions such as `PlayerIndex` and `Difficulty`.
|
|
- Stores `PRIMIERA_VALUES` for end-of-round scoring.
|
|
|
|
### `src/game/engine.ts`
|
|
|
|
- Builds and shuffles the 40-card deck.
|
|
- Creates a round state for four players with dealer-relative opening order.
|
|
- Implements capture rules where direct value matches take priority over subset-sum captures.
|
|
- Applies moves immutably, awards scope, assigns leftover table cards, and computes round and match 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 value and suit residue helpers used by AI inference and probability estimates.
|
|
|
|
### `src/game/ai.ts`
|
|
|
|
- Exposes `chooseMove()` as the async AI entry point.
|
|
- Implements three difficulty tiers: `beginner`, `advanced`, and `master`.
|
|
- Uses table-driven search profiles, role-aware heuristics, tracker-based inference, and determinization plus alpha-beta search.
|
|
- Configures the current master profile with a 4600 ms budget, 10 samples, depth 6, and batch size 2.
|
|
|
|
### `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.
|
|
|
|
### `src/game/ai-worker-client.ts`
|
|
|
|
- Wraps worker lifecycle and pending-request tracking behind the same `chooseMove()` API that 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, messaging, or deserialization fails.
|
|
|
|
### `src/game/ai.worker.ts`
|
|
|
|
- Rehydrates `CardTracker` from a serialized snapshot.
|
|
- Delegates move selection to `chooseMove()`.
|
|
- Posts progress, result, or serialized error messages back to the main thread.
|
|
|
|
### `src/scenes/BootScene.ts`
|
|
|
|
- Loads the card atlas and card back.
|
|
- Displays a simple loading bar.
|
|
- Transitions into `MenuScene` after asset load.
|
|
|
|
### `src/scenes/MenuScene.ts`
|
|
|
|
- Renders the title, rules summary, and difficulty selection.
|
|
- Starts `GameScene` with the chosen difficulty.
|
|
|
|
### `src/scenes/GameScene.ts`
|
|
|
|
- Owns match flow, dealing, selection, capture resolution, AI turn orchestration, score HUD, status UI, think bar, particles, and procedural audio.
|
|
- Instantiates and disposes `AIWorkerClient` on scene lifecycle events.
|
|
- 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.
|
|
- Hides status and navigation bars with transient swipe behavior.
|
|
|
|
## Dependencies
|
|
|
|
### JavaScript production dependencies
|
|
|
|
| Package | Version | Purpose |
|
|
|---------|---------|---------|
|
|
| `phaser` | `^3.87.0` | Game engine runtime |
|
|
| `@capacitor/core` | `^8.3.0` | Capacitor runtime bridge |
|
|
| `@capacitor/cli` | `^8.3.0` | Capacitor project tooling |
|
|
| `@capacitor/android` | `^8.3.0` | Android platform integration |
|
|
|
|
### JavaScript development dependencies
|
|
|
|
| Package | Version | Purpose |
|
|
|---------|---------|---------|
|
|
| `typescript` | `^5.0.0` | Static type checking and TS compilation step |
|
|
| `vite` | `^5.0.0` | Dev server and production bundler |
|
|
|
|
### Android / Gradle dependencies
|
|
|
|
| Dependency | Version | Source | Purpose |
|
|
|------------|---------|--------|---------|
|
|
| `com.android.tools.build:gradle` | `8.13.0` | `android/build.gradle` | Android Gradle plugin |
|
|
| `com.google.gms:google-services` | `4.4.4` | `android/build.gradle` | Optional Google services integration |
|
|
| `androidx.appcompat:appcompat` | `1.7.1` | `android/variables.gradle` | Android app compatibility |
|
|
| `androidx.coordinatorlayout:coordinatorlayout` | `1.3.0` | `android/variables.gradle` | Layout coordination helpers |
|
|
| `androidx.core:core-splashscreen` | `1.2.0` | `android/variables.gradle` | Splash screen support |
|
|
| `junit:junit` | `4.13.2` | `android/variables.gradle` | JVM Android tests |
|
|
| `androidx.test.ext:junit` | `1.3.0` | `android/variables.gradle` | Instrumented test runner |
|
|
| `androidx.test.espresso:espresso-core` | `3.7.0` | `android/variables.gradle` | Instrumented UI testing |
|
|
|
|
### Platform configuration
|
|
|
|
- `compileSdkVersion`: 36
|
|
- `targetSdkVersion`: 36
|
|
- `minSdkVersion`: 24
|
|
|
|
## Module Organization
|
|
|
|
```text
|
|
main.ts
|
|
-> BootScene
|
|
-> MenuScene
|
|
-> GameScene
|
|
-> engine.ts
|
|
-> types.ts
|
|
-> card-tracker.ts
|
|
-> ai-worker-client.ts
|
|
-> ai-worker-protocol.ts
|
|
-> ai.worker.ts
|
|
-> ai.ts
|
|
```
|
|
|
|
Application-level dependency direction is one-way:
|
|
|
|
- `src/game/` imports only from sibling game modules.
|
|
- `src/scenes/` imports from `src/game/` and Phaser.
|
|
- `src/game/` never imports Phaser.
|
|
|
|
## Data Flow
|
|
|
|
1. `main.ts` creates the Phaser app and registers all scenes.
|
|
2. `BootScene` loads textures and starts `MenuScene`.
|
|
3. `MenuScene` passes the chosen difficulty to `GameScene`.
|
|
4. `GameScene.create()` creates a fresh `CardTracker`, constructs a new `GameState`, and starts the opening deal.
|
|
5. Human turns use pointer-driven card selection and `findCaptures()` output to choose legal captures.
|
|
6. AI turns call `AIWorkerClient.chooseMove(state, playerIdx, difficulty, tracker, onProgress)`.
|
|
7. `AIWorkerClient` posts a typed request to `ai.worker.ts`; if workers are unavailable, it reruns the same request in-thread.
|
|
8. `chooseMove()` returns a heuristic move for lower tiers or performs batched master search while emitting `AIDecisionProgress`.
|
|
9. `GameScene` updates the think bar from progress callbacks, executes the returned move, records tracker state, and advances turn order.
|
|
10. When every hand is empty, `engine.ts` finalizes scoring and `GameScene` presents the round or match outcome.
|
|
|
|
## Build System
|
|
|
|
| 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 preview` | `package.json` | Serves the built app with Vite preview |
|
|
| `npx tsc --noEmit` | user-provided test command | Type-checks the TypeScript codebase without emitting files |
|