⚔️ Unconditional Surrender: Western Campaign - Digital Edition

Versione digitale interattiva del wargame storico Unconditional Surrender Western Campaign con intelligenza artificiale tattica (Minimax).

🎯 Visione del Progetto

Trasformare il classico wargame da tavolo Unconditional Surrender Western Campaign in una versione digitale completamente funzionale con:

• ✅ Mappa interattiva con hex grid
• ✅ Sistema di gioco completo (movimento, ZOC, combattimento, supply)
• ✅ Calcolo automatico di tiri, modificatori, casualità
• ✅ IA tattica con Minimax + Alpha-Beta Pruning
• ✅ Gioco solitario (umano vs IA)
• ✅ Umano vs Umano (via web)

---

🏗️ Architettura del Progetto

unconditional-surrender-digital/
├── packages/
│   ├── shared/              # Tipi, regole, configurazione (TypeScript)
│   ├── backend/             # Game engine + API (Node.js/Express)
│   ├── frontend/            # UI interattiva (React)
│   └── ai-engine/           # Minimax IA (Python)
├── package.json             # Root monorepo (Yarn workspaces)
└── README.md                # Questo file

Stack Tecnologico

Layer	Tecnologie
Frontend	React 18 + TypeScript + Vite + Zustand
Backend	Node.js + Express + TypeScript
Shared	TypeScript (tipi e regole comuni)
AI	Python 3.10+ (Minimax, NumPy)
Build	Turbo (monorepo orchestration)

---

📋 Regole Implementate (MVP)

Movimento

• Punti Movimento: 10 MP per turno (configurabile)
• Costi Terreno: Piano=1, Foresta=2, Montagna=3, Fiume=4
• ZOC: Esce da ZOC costa +2 MP aggiuntivi

Combattimento

• Rapporto Forze: Minimo 1.5:1 per vittoria garantita
• Tiri: d6 con modificatori (terreno, morale, leadership)
• Casualità: % base 30% normalizzato per rapporto forze
• Morale: Scala 0-10, impatta accettazione combattimento

Supply (Rifornimenti)

• Consumo: 1 livello supply per turno
• Range: 5 hex da depot/città
• Penalità Isolamento: Raddoppia consumo se isolata

ZOC (Zone of Control)

• Range: 1 hex intorno all'unità
• Effetti: Impedisce movimento nemico, aumenta costi, forza combattimento

---

🚀 Installazione & Setup

Prerequisiti

• Node.js >= 18.0.0
• Yarn 1.22+
• Python 3.10+

Setup Locale

# Clone o apri il progetto
cd "Desktop/Unconditional Surrender"

# Installa dipendenze (tutti i workspace)
yarn install

# Build tutti i pacchetti
yarn build

# Avvia dev servers
yarn dev

Questo lancerà:

• Frontend: http://localhost:5173
• Backend: http://localhost:3001
• AI: Pronto per integrazione

---

🎮 Uso

Gioco da Browser

1. Apri http://localhost:5173
2. New Game → Crea una partita
3. Seleziona unità e hex per muovere
4. IA calcola la mossa in ~3 secondi
5. Log di gioco mostra tutti gli eventi

API Backend

# Crea una nuova partita
curl -X POST http://localhost:3001/api/games

# Carica stato partita
curl http://localhost:3001/api/games/{gameId}

# Lista partite
curl http://localhost:3001/api/games

---

🧠 Intelligenza Artificiale (Minimax)

Algoritmo

Minimax(depth, side, alpha, beta)
  if depth == 0 or terminal state:
    return evaluate(position)
  
  if maximizing (ALLIED):
    for each move:
      score = Minimax(depth-1, AXIS, α, β, minimize)
      α = max(α, score)
      if β ≤ α: break  [Alpha-Beta Pruning]
    return α
  else (AXIS):
    for each move:
      score = Minimax(depth-1, ALLIED, α, β, maximize)
      β = min(β, score)
      if β ≤ α: break  [Alpha-Beta Pruning]
    return β

Caratteristiche

• ✅ Profondità Adattiva: Iterative deepening fino a timeout
• ✅ Transposition Table: Cache stati per evitare ricerca ripetuta
• ✅ Alpha-Beta Pruning: Riduce nodi esplorati del 90%
• ✅ Time Management: Timeout configurabile (default 3000ms)
• ✅ Valutazione Multifactor:
  • Controllo territoriale (30%)
  • Forza unità (25%)
  • Linee rifornimento (20%)
  • Morale (15%)
  • Rapporto perdite (10%)

---

📊 Fasi di Sviluppo

✅ FASE 1: SETUP (Completata)

• Monorepo structure
• TypeScript setup
• Schema dati comuni
• Backend Express base
• Frontend React base
• AI Minimax engine skeleton

📌 FASE 2: GAME ENGINE (Prossima)

• Parser mappa hex
• Sistema movimento con validazione
• Calcolo ZOC
• Risoluzione combattimento
• Sistema supply
• State management (turni, fasi)

📌 FASE 3: FRONTEND INTERATTIVO

• Rendering hex grid
• Visualizzazione unità
• Selezione e movimento UI
• Animation mosse
• Combat resolution display
• Game log/history

📌 FASE 4: BACKEND API

• REST endpoints per azioni
• WebSocket real-time
• Persistenza (DB)
• Autenticazione
• Matchmaking

📌 FASE 5: AI INTEGRATION

• Implementare generate_moves()
• Implementare apply_move()
• Implementare evaluation details
• Testing AI vs AI
• Tuning profondità/difficulty

📌 FASE 6: POLISH & TESTING

• Bug fixes
• Performance optimization
• UI/UX improvements
• Documentazione
• Deployment

---

This is the beginning of the README. Read the rest at the original. Read the full README ↗