catdoku/README.md

CatDoku - Puzzle dei Gatti

📖 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:

   git clone http://192.168.0.183:8085/truetype/catdoku.git
   cd catdoku
   

2. Apri il gioco:

   # 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! 🐱