scopone/docs/ARCHITECTURE.md

Architecture

Last Updated: 2026-03-31T00:00:00.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

Project Structure

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

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

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 (singleton, factory, observer, DI) detected.

Key Components

types.ts — Domain Types

• 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

engine.ts — Game Logic

• 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

ai.ts — Heuristic AI

• 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

GameScene.ts — Main Scene (~1340 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

Dependencies

Production

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

Development

Package	Version	Purpose
typescript	^5.0.0	TypeScript compiler
vite	^5.0.0	Dev server and bundler

Module Organisation

main.ts ──→ BootScene ──→ MenuScene ──→ GameScene
                                           │
                                           ├── game/engine (createInitialState, applyMove, findCaptures, ...)
                                           ├── game/ai     (chooseMove)
                                           └── game/types  (Card, GameState, ...)

game/ modules are pure logic with no framework coupling. scenes/ imports from game/ but never vice versa.

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

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)