# CatDoku - Puzzle dei Gatti

![CatDoku](https://img.shields.io/badge/version-1.0.0-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Platform](https://img.shields.io/badge/platform-Web-orange)

## 📖 Descrizione

**CatDoku** è un puzzle game ispirato al classico Sudoku, ma con una meccanica unica basata sul posizionamento di gatti su una griglia colorata. Il gioco combina logica, strategia e divertimento in un'esperienza web moderna e responsive.

### 🎯 Obiettivo del Gioco

Posizionare un gatto in ogni riga, colonna e regione colorata della griglia, rispettando il vincolo che nessun gatto può essere adiacente (in qualsiasi direzione, incluse le diagonali) ad un altro gatto.

## ✨ Caratteristiche Principali

### 🎮 Gameplay
- **Griglie dinamiche**: Supporto per griglie da 6×6 fino a 12×12
- **Generazione procedurale**: Ogni partita genera un puzzle unico e sempre risolvibile
- **Regioni colorate contigue**: I colori formano aree connesse per una migliore esperienza visiva
- **Sistema di errori**: 3 tentativi massimi per livello con feedback visivo immediato
- **Suggerimenti**: 3 hint gratuiti per livello con sistema premium per suggerimenti aggiuntivi

###  Interfaccia
- **Design moderno**: UI pulita e intuitiva con animazioni fluide
- **Responsive**: Giocabile su desktop, tablet e mobile
- **Interazione touch**: Supporto completo per dispositivi touch
  - Click singolo: posiziona/rimuove X
  - Pressione prolungata (0.5s): posiziona/rimuove gatto
- **Feedback visivo**: Animazioni per errori, posizionamenti e vittorie

###  Sistema Player
- **Alias personalizzati**: Ogni giocatore può inserire il proprio nome/alias
- **Tracking tempo**: Timer per ogni livello con formato mm:ss
- **Salvataggio locale**: Progressi salvati in localStorage
- **Classifica**: Leaderboard completa con filtri e statistiche

### 🏆 Leaderboard
- **Statistiche globali**: Partite giocate, giocatori unici, miglior tempo, miglior punteggio
- **Filtri avanzati**: Per giocatore, livello e dimensione griglia
- **Medaglie**: Prime 3 posizioni con medaglie d'oro, argento e bronzo
- **Cronologia**: Data e ora di ogni partita completata

### 💎 Sistema Premium
- **Popup premium**: Attivato quando si esauriscono i suggerimenti
- **Countdown**: 5 secondi di attesa prima di poter ottenere un hint aggiuntivo
- **Design accattivante**: UI dorata con animazioni

## 🚀 Installazione e Avvio

### Requisiti
- Browser moderno con supporto JavaScript ES6+
- Nessun server richiesto (funziona con file:// protocol)

### Avvio Rapido

1. **Clona il repository**:
   ```bash
   git clone http://192.168.0.183:8085/truetype/catdoku.git
   cd catdoku
   ```

2. **Apri il gioco**:
   ```bash
   # Metodo 1: Apri direttamente nel browser
   open index.html
   
   # Metodo 2: Usa un server HTTP locale (opzionale)
   python3 -m http.server 8000
   # Poi visita http://localhost:8000
   ```

3. **Inizia a giocare**:
   - Inserisci il tuo nome/alias
   - Seleziona la dimensione della griglia (6×6 fino a 12×12)
   - Clicca "Nuova Partita"

## 🎮 Come Giocare

### Controlli

| Azione | Mouse | Touch |
|--------|-------|-------|
| Posiziona/Rimuovi X | Click singolo | Tap singolo |
| Posiziona/Rimuovi Gatto | Pressione 0.5s | Pressione 0.5s |
| Cancella tutte le X | Pulsante gomma | Pulsante gomma |
| Suggerimento | Pulsante lampadina | Pulsante lampadina |

### Regole del Gioco

1. **Un gatto per riga**: Ogni riga deve contenere esattamente un gatto
2. **Un gatto per colonna**: Ogni colonna deve contenere esattamente un gatto
3. **Un gatto per colore**: Ogni regione colorata deve contenere esattamente un gatto
4. **Nessuna adiacenza**: I gatti non possono essere adiacenti (incluse diagonali)

### Sistema di Punteggio

Il punteggio viene calcolato in base a:
- **Errori rimanenti**: 10 punti per ogni errore non commesso
- **Suggerimenti rimanenti**: 5 punti per ogni hint non utilizzato
- **Tempo**: Non influisce sul punteggio ma viene tracciato per la leaderboard

## 🛠️ Sviluppo

### Struttura del Progetto

```
catdoku/
├── index.html          # Pagina principale del gioco
├── style.css           # Stili e layout responsive
── game.js             # Logica di gioco e generatore di puzzle
├── leaderboard.html    # Pagina classifica
├── README.md           # Documentazione principale
└── docs/               # Documentazione tecnica
    ├── architecture.md # Architettura del sistema
    ├── game-rules.md   # Regole del gioco dettagliate
    ├── generator.md    # Algoritmo di generazione puzzle
    └── api.md          # API e struttura dati
```

### Tecnologie Utilizzate

- **HTML5**: Struttura semantica
- **CSS3**: Stili moderni con Grid, Flexbox, animazioni
- **JavaScript ES6+**: Logica di gioco, generatore procedurale
- **localStorage API**: Persistenza dati locale

### Architettura

Il progetto segue un'architettura **MVC semplificata**:

- **Model**: Stato del gioco (griglia, soluzione, punteggio, timer)
- **View**: Rendering DOM e gestione eventi UI
- **Controller**: Logica di gioco, validazione, generazione puzzle

### Generatore di Puzzle

Il generatore utilizza un algoritmo in 3 fasi:

1. **Backtracking randomizzato**: Posiziona N gatti validi sulla griglia
2. **Flood fill simultaneo**: Espande regioni colorate contigue da ogni gatto
3. **Validazione**: Garantisce puzzle sempre risolvibile con soluzione unica

## 📊 Roadmap Futura

- [ ] Livelli predefiniti con difficoltà crescente
- [ ] Sistema di achievement/badge
- [ ] Modalità sfida a tempo
- [ ] Condivisione punteggi sui social
- [ ] Tema scuro
- [ ] Suoni ed effetti audio
- [ ] Multiplayer locale (2 giocatori)
- [ ] Esportazione/importazione record

## 🤝 Contribuire

Le contribuzioni sono benvenute! Per contribuire:

1. Fork il progetto
2. Crea un branch per la tua feature (`git checkout -b feature/AmazingFeature`)
3. Commit le tue modifiche (`git commit -m 'Add some AmazingFeature'`)
4. Push sul branch (`git push origin feature/AmazingFeature`)
5. Apri una Pull Request

##  License

Questo progetto è distribuito sotto licenza MIT. Vedi il file `LICENSE` per maggiori informazioni.

## 👤 Autore

**truetype**

- Server Gitea: http://192.168.0.183:8085
- Repository: http://192.168.0.183:8085/truetype/catdoku

## 🙏 Ringraziamenti

- Ispirato al gioco "Clash of Critters"
- Icone e emoji standard Unicode
- Font di sistema per massima compatibilità

---

**Buon divertimento con CatDoku! 🐱**