Scopa

A Scopa web app built with Vite + React.

Play Online

Overview

This repository presents a web-based implementation of the traditional Italian card game Scopa. It features a polished interface, multiple CPU difficulty tiers, and a robust deterministic engine.

This project is built with OpenAI Codex as a hands-on experiment in AI-assisted software development. As a physicist, I am interested in how in using AI coding assistants can facilitate the development of applications, in this case a web game. Scopa is a fairly simple and fun card game, but it has a number of rules and exceptions, so it is a good candidate for testing AI-assisted web game development.

Features

• Standard Scopa Rules: Implements full rules including forced captures and the specific "scopa during last play" exception.
• Variety of CPU Opponents: Challenge three tiers of AI:
  • Random (Scimietta): Makes valid but arbitrary moves.
  • Greedy (Furbo): Prioritizes immediate captures and points.
  • Expert (Esperto): Uses advanced heuristics and Monte Carlo simulations to plan ahead.
• Interactive Gameplay:
  • Drag-and-drop card interactions.
  • Intuitive capture selection UI.
  • Round-by-round scoring breakdowns.
• Polished Aesthetics:
  • Choose between classic Napoletane and Siciliane deck skins, via high-quality raster card art.
  • Sound effects.
• Responsive Design: Playable on desktop and mobile devices.
• Local Stats: Tracks your performance against each CPU tier (stored locally).

Usage

1. Start a Game: Visit the live demo.
2. Choose Opponent: Select a CPU difficulty from the main menu.
3. Play Cards: Drag a card from your hand to the table.
   • If the card matches a table card's value, you capture it.
   • If it matches the sum of multiple cards, you can capture those.
   • If no match exists, the card remains on the table.
4. Scoring: Points are awarded for:
   • Scopa: Clearing the table (1 point).
   • Settebello: Capturing the 7 of Coins (1 point).
   • Primiera: Best combination of cards (1 point).
   • Coins: Most coins captured (1 point).
   • Cards: Most cards captured (1 point).
5. Winning: The first player to reach 11 points (or a configurable score) wins.

Technical Details

The application is a Single Page Application (SPA), a static site generator, and a web game.

Tech Stack

• Frontend: React + TypeScript
• Build Tool: Vite
• Styling: Tailwind CSS + PostCSS
• Animations: Framer Motion
• Testing: Vitest (Engine logic)

Project Structure

• src/engine/: Core game logic (rules, scoring, state management). Completely decoupled from UI.
• src/ai/: CPU opponent implementations and simulation workers.
• src/assets/: Static assets (images, audio).
• tests/engine/: Comprehensive unit tests ensuring rule compliance.

Getting Started

To run the project locally:

# Install dependencies
npm install

# Start development server
npm run dev

Open http://localhost:5173/ to play.

Scripts

• npm run dev: Start the Vite dev server with hot reload.
• npm run build: Create a production build in dist/.
• npm run preview: Serve the production build locally.
• npm run lint: Run ESLint.
• npm run format: Format code with Prettier.
• npm test: Run engine unit tests.

Possible future Improvements

• AI opponents (LLM).
• Multiplayer support.
• Additional deck skins.

Credits

• Audio: Sound effects adapted from Kenney Assets (see src/assets/audio/kenney-license.txt).
• Development: Built with the assistance of OpenAI Codex and Claude Code.
• Vibe Coding: Developed using the vibe-coding methodology described here.