185 lines
6.4 KiB
Markdown
185 lines
6.4 KiB
Markdown
# 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**:
|
||
```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 "Meowdoku" su Android
|
||
- Icone e emoji standard Unicode
|
||
- Font di sistema per massima compatibilità
|
||
|
||
---
|
||
|
||
**Buon divertimento con CatDoku! 🐱**
|