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

feat(SCOPONE-0008): refresh project docs

Browse Source
This commit is contained in:
Giancarmine Salucci
2026-04-02 20:16:27 +02:00
parent 747da35190
commit 019c4380be
3 changed files with 333 additions and 321 deletions
Download Patch File Download Diff File Expand all files Collapse all files

260
docs/ARCHITECTURE.md
View File

@@ -1,147 +1,199 @@
# Architecture
> Last Updated: 2026-03-31T00:00:00.000Z
> Last Updated: 2026-04-02T18:12:18.000Z
## Overview
| Attribute | Value |
|-----------------|--------------------------------------------------------|
| **Language** | TypeScript (ES2020 target, strict mode) |
| **Type** | 2D card game — Scopone Scientifico |
| **Framework** | Phaser 3.87+ (scene-based game engine) |
| **Bundler** | Vite 5 |
| **Native** | Capacitor 8.3 (Android) |
| **Resolution** | 1280 × 720, FIT scaling with auto-center |
| Attribute | Value |
|-----------|-------|
| Primary language | TypeScript |
| Secondary language | Java (Capacitor Android shell) |
| Project type | Browser card game with Android packaging |
| 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 Scopone Scientifico implementation. The web client contains the real game logic and presentation. The Android tree is a Capacitor wrapper with a custom immersive `MainActivity`.
## Project Structure
```
```text
scopone-phaser/
├── src/
│ ├── main.ts # Phaser.Game bootstrap + config
│ ├── game/
│ │ ├── types.ts # Card, Suit, Player, GameState, TeamScore, ScoreBreakdown, PRIMIERA_VALUES
│ │ ├── engine.ts # Deck build, shuffle, capture logic, applyMove, scoring, primiera
│ │ └── ai.ts # Heuristic AI: chooseMove, scoreCapture, scoreDump
│ └── scenes/
│ ├── BootScene.ts # Asset loading (atlas, card back image)
│ ├── MenuScene.ts # Start menu with rules summary
│ └── GameScene.ts # Main game: rendering, turn management, effects, audio
├── index.html # Entry point, Italian locale, green felt background
├── public/ # Static assets (atlas.json, atlas.png, retro.png)
├── android/ # Capacitor Android native shell
├── package.json
├── tsconfig.json
├── vite.config.ts
└── capacitor.config.ts
|- src/
| |- main.ts
| |- game/
| | |- types.ts
| | |- engine.ts
| | |- card-tracker.ts
| | `- ai.ts
| `- scenes/
| |- BootScene.ts
| |- MenuScene.ts
| `- GameScene.ts
|- public/
|- android/
|- docs/
|- prompts/
|- package.json
|- tsconfig.json
|- vite.config.ts
`- capacitor.config.ts
```
## Key Directories
| Directory | Purpose |
|--------------------|----------------------------------------------------------------|
| `src/game/` | Domain logic — types, game engine, AI (no Phaser dependency) |
| `src/scenes/` | Phaser scenes — rendering, input, effects, audio |
| `public/` | Static assets served by Vite (card atlas, card back) |
| `android/` | Capacitor-generated Android project (Gradle, Java) |
| `prompts/` | JIRA agent pipeline artifacts |
| Directory | Purpose |
|-----------|---------|
| `src/game/` | Framework-independent rules, scoring, imperfect-information tracking, and AI search |
| `src/scenes/` | Phaser scene lifecycle, UI, animation, effects, and round orchestration |
| `public/` | Static web assets consumed by Phaser loaders |
| `android/` | Capacitor Android project, Gradle config, and immersive activity wrapper |
| `docs/` | Architecture, code style, findings, and cache metadata |
| `prompts/` | JIRA pipeline artifacts and iteration state |
## Design Patterns
| Pattern | Where |
|-----------------------------|--------------------------------------------------------------------|
| **Scene lifecycle** | BootScene → MenuScene → GameScene (Phaser scene graph) |
| **Immutable state updates** | `applyMove()` deep-clones `GameState` before mutation |
| **Heuristic scoring** | AI evaluates all legal moves with weighted feature scores |
| **Separation of concerns** | `game/` has no Phaser imports; `scenes/` bridges game ↔ rendering |
| **Procedural audio** | Web Audio API oscillators + delay reverb — no audio files |
No explicit GoF patterns were detected in the source or by semantic search.
No explicit GoF patterns (singleton, factory, observer, DI) detected.
Observed architectural patterns in the current codebase:
| Pattern | Where it appears |
|---------|------------------|
| Scene-based flow | `BootScene -> MenuScene -> GameScene` via Phaser scene registration |
| Functional core / imperative shell | `src/game/` stays free of Phaser imports, while `src/scenes/` owns rendering and input |
| Clone-before-mutate state transitions | `applyMove()` clones `GameState` before applying move effects |
| Determinization search | Master AI samples hidden hands before alpha-beta evaluation |
| Callback-driven progress reporting | `chooseMove()` reports `AIDecisionProgress` to `GameScene` for the think bar |
## Key Components
### `types.ts` — Domain Types
### `src/main.ts`
- `Card { suit, value, id }` — 40-card Napoletane deck (suits: bastoni, coppe, denara, spade; values 1-10)
- `GameState` — full round state: 4 players, table, current player, team scores, round tracking
- `TeamScore` — per-team stats: cards, scope, denari, settebello, primiera, round/total points
- `ScoreBreakdown` — which team won each scoring category
- `PRIMIERA_VALUES` — lookup table for primiera card values
- Bootstraps `Phaser.Game`.
- Registers `BootScene`, `MenuScene`, and `GameScene`.
- Installs a one-shot fullscreen request handler on first user interaction.
### `engine.ts` — Game Logic
### `src/game/types.ts`
- `buildDeck()` / `shuffle()` — Fisher-Yates 40-card deck
- `createInitialState()` — deals 10 cards per player, empty table (Scopone Scientifico rules)
- `findCaptures(played, table)` — direct value match (mandatory) or subset-sum combinations
- `applyMove(state, player, card, captureChoice)` — immutable state transition, scopa detection, end-of-round scoring
- `calculateScores()` / `scoreRound()` — carte, denari, settebello, primiera, scope points
- `calcPrimiera(pile)` — best card per suit using `PRIMIERA_VALUES`
- `teamOf(playerIdx)` — team assignment: 0+2 = Team A, 1+3 = Team B
- Defines the game model: `Card`, `Capture`, `Player`, `GameState`, `TeamScore`, `ScoreBreakdown`.
- Encodes difficulty tiers as `'beginner' | 'advanced' | 'master'`.
- Stores the `PRIMIERA_VALUES` lookup table.
### `ai.ts` — Heuristic AI
### `src/game/engine.ts` (371 lines)
- `chooseMove(state, playerIdx)` — evaluates all legal moves (captures + dumps)
- `scoreCapture()` — weighted: scopa (+500), settebello (+300), denari (+50 each), card count, primiera value, opponent threat
- `scoreDump()` — avoids giving opponents scopa (-400), prefers low-value non-denari, penalises dumping 7s and aces
- Builds and shuffles the 40-card deck.
- Creates the initial round state for four players.
- Implements capture selection rules: single direct matches take priority; subset sums are considered only when no direct match exists.
- Applies moves immutably, detects scopas, assigns leftover table cards, and computes round scores.
### `GameScene.ts` — Main Scene (~1340 lines)
### `src/game/card-tracker.ts` (89 lines)
- Four-player layout: South (human), West/East (AI, rotated ±90°), North (AI partner)
- Deal animation with staggered tweens
- Card selection with postFX glow pulse
- Capture highlighting with multiple-choice UI
- Particle effects: capture burst, scopa explosion, settebello flash, denari shimmer, primiera glow, card trails, victory confetti
- Camera shake + flash on scopa and settebello
- Live score bar with animated counter updates
- Think bar progress indicator during AI turns
- Procedural background music (oscillator drone + triangle melody + chord stabs)
- Round-end summary panel and game-over screen
- Tracks seen cards across a round without exposing hidden hands directly.
- Computes unseen cards from `played + myHand + table`.
- Supplies probability helpers used by the AI for value-based inference.
### `src/game/ai.ts` (1210 lines)
- Exposes `chooseMove()` as an async entry point.
- Implements three difficulty levels:
- `beginner`: noisy heuristic play.
- `advanced`: stronger heuristics with race awareness, partner setup, and card-tracker inference.
- `master`: determinization plus alpha-beta search with dynamic time budgets, batching, and progress callbacks.
- Uses `yieldToBrowser()` between master-search batches so Phaser can repaint the think bar.
### `src/scenes/BootScene.ts` (47 lines)
- Loads the card atlas and card-back texture.
- Shows a simple progress bar and transitions into the menu.
### `src/scenes/MenuScene.ts` (103 lines)
- Renders the title screen and rules summary.
- Lets the player choose `beginner`, `advanced`, or `master` difficulty.
- Starts `GameScene` with the selected difficulty in scene data.
### `src/scenes/GameScene.ts` (1446 lines)
- Owns the match loop, HUD, think bar, card interaction, animation, FX, audio, and round transitions.
- Uses `CardTracker` to record played and captured cards after each move.
- Bridges async AI progress into a visible top-of-screen think bar.
- Handles end-of-round overlays and full-match restart flow.
### `android/app/src/main/java/com/phaser/scopa/MainActivity.java`
- Extends `BridgeActivity`.
- Forces immersive mode by hiding status and navigation bars whenever the window gains focus.
## Dependencies
### Production
### JavaScript production dependencies
| Package | Version | Purpose |
|----------------------|----------|--------------------------------------|
| `phaser` | ^3.87.0 | 2D game engine |
| `@capacitor/core` | ^8.3.0 | Capacitor runtime |
| `@capacitor/cli` | ^8.3.0 | Capacitor CLI |
| `@capacitor/android` | ^8.3.0 | Android platform plugin |
| Package | Version | Purpose |
|---------|---------|---------|
| `phaser` | `^3.87.0` | Game engine |
| `@capacitor/core` | `^8.3.0` | Capacitor runtime |
| `@capacitor/cli` | `^8.3.0` | Capacitor tooling |
| `@capacitor/android` | `^8.3.0` | Android platform integration |
### Development
### JavaScript development dependencies
| Package | Version | Purpose |
|---------------|---------|--------------------------|
| `typescript` | ^5.0.0 | TypeScript compiler |
| `vite` | ^5.0.0 | Dev server and bundler |
| Package | Version | Purpose |
|---------|---------|---------|
| `typescript` | `^5.0.0` | Type-checking and TS compilation for builds |
| `vite` | `^5.0.0` | Dev server and bundling |
## Module Organisation
### Android / Gradle dependencies
```
main.ts ──→ BootScene ──→ MenuScene ──→ GameScene
│
├── game/engine (createInitialState, applyMove, findCaptures, ...)
├── game/ai (chooseMove)
└── game/types (Card, GameState, ...)
| Dependency | Source | Purpose |
|------------|--------|---------|
| `com.android.tools.build:gradle:8.13.0` | `android/build.gradle` | Android build plugin |
| `com.google.gms:google-services:4.4.4` | `android/build.gradle` | Optional Google services integration |
| `androidx.appcompat:appcompat` | `android/app/build.gradle` | Android UI compatibility |
| `androidx.coordinatorlayout:coordinatorlayout` | `android/app/build.gradle` | Android layout support |
| `androidx.core:core-splashscreen` | `android/app/build.gradle` | Splash screen support |
| `junit:junit` | `android/app/build.gradle` | JVM-side Android tests |
| `androidx.test.ext:junit` | `android/app/build.gradle` | Instrumented Android testing |
| `androidx.test.espresso:espresso-core` | `android/app/build.gradle` | Android UI testing |
## Module Organization
```text
main.ts
-> BootScene
-> MenuScene
-> GameScene
-> engine.ts
-> ai.ts
-> card-tracker.ts
-> types.ts
```
`game/` modules are pure logic with no framework coupling. `scenes/` imports from `game/` but never vice versa.
Dependencies are one-directional at the application level:
- `src/game/` imports only from sibling game modules.
- `src/scenes/` imports from `src/game/`.
- `src/game/` never imports Phaser.
## Data Flow
1. `createInitialState()` builds shuffled deck, deals 10 cards each, empty table
2. `GameScene.nextTurn()` detects current player: human → enable input; AI → delay + `chooseMove()`
3. `applyMove()` returns new `GameState` + capture result + scopa flag
4. `GameScene.executeMove()` animates: card flight → capture burst → pile collection
5. `updateScoreBar()` reflects live team stats with animated counter tweens
6. When all hands empty → `calculateScores()` → round-end overlay
7. First team to 11 points → game-over screen → optional restart
1. `main.ts` creates the Phaser app and registers all scenes.
2. `BootScene` loads assets, then starts `MenuScene`.
3. `MenuScene` passes the chosen difficulty into `GameScene`.
4. `GameScene.create()` initializes a new `CardTracker`, creates the initial `GameState`, and animates the opening deal.
5. On each turn:
- Human turns use click-driven selection and capture highlighting.
- AI turns call `chooseMove(state, playerIdx, difficulty, tracker, onProgress)`.
6. `chooseMove()` either returns immediately for heuristic tiers or performs batched master search while reporting `AIDecisionProgress`.
7. `GameScene.executeMove()` applies the move, updates the tracker, animates the result, refreshes the HUD, and advances the round.
8. When all hands are empty, `engine.ts` finalizes scoring and `GameScene` displays the round summary or final match screen.
## Build System
| Command | Action |
|--------------------|--------------------------------------------|
| `npm run dev` | `vite` — dev server on port 3000 |
| `npm run build` | `tsc && vite build` — compile + bundle to `dist/` |
| `npm run preview` | `vite preview` — preview production build |
| `tsc --noEmit` | Type-check only (no test framework) |
| Command | Source | Purpose |
|---------|--------|---------|
| `npm run dev` | `package.json` | Starts the Vite development server on port 3000 and opens the browser |
| `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 locally via Vite preview |
| `npx tsc --noEmit` | user-provided test command | Type-checks the TypeScript codebase without emitting files |