102 lines
5.4 KiB
Markdown
102 lines
5.4 KiB
Markdown
# Architettura tecnica
|
||
|
||
Questo documento descrive la struttura del repository dopo il refactoring che ha separato shell dell'applicazione, menu, domini di gioco e componenti condivisi.
|
||
|
||
## Avvio e composizione
|
||
|
||
`project.godot` avvia `res://app/scenes/app_shell.tscn` e registra `Settings` come autoload da `res://shared/settings/settings.gd`.
|
||
|
||
`AppShell` (`app/scripts/app_shell.gd`) è il punto di composizione dell'applicazione:
|
||
|
||
1. istanzia il menu principale e il dialog di selezione modalità;
|
||
2. mostra la schermata Home, oppure una destinazione di debug richiesta dalla riga di comando;
|
||
3. quando l'utente conferma una modalità, nasconde il menu e istanzia JuggleBoard;
|
||
4. mantiene un solo gioco attivo alla volta.
|
||
|
||
## Menu
|
||
|
||
`menus/scenes/main_menu.tscn` usa `MainMenuController`, che sostituisce dinamicamente la schermata corrente e gestisce transizioni e feedback audio.
|
||
|
||
| Schermata | Scena | Script | Stato |
|
||
| --- | --- | --- | --- |
|
||
| Home | `menus/scenes/p1_home.tscn` | `menus/scripts/screens/p1_home_screen.gd` | Disponibile |
|
||
| Menu JuggleBoard | `menus/scenes/p2a_juggle_menu.tscn` | `menus/scripts/screens/p2a_juggle_menu_screen.gd` | Disponibile |
|
||
| Palestra di giocoleria | `menus/scenes/p3a_gym_menu.tscn` | `menus/scripts/screens/p3a_gym_menu_screen.gd` | Disponibile: avvia il prototipo P3B |
|
||
| Selettore modalità | `menus/scenes/mode_select_dialog.tscn` | `menus/scripts/mode_select_dialog.gd` e `mode_select_view.gd` | Disponibile |
|
||
|
||
I componenti `menus/scripts/components/menu_ui.gd` e `menu_audio.gd` raccolgono rispettivamente costruzione visuale e feedback sonori. Le immagini e lo shader del menu risiedono in `menus/assets/`.
|
||
|
||
## Dominio JuggleBoard
|
||
|
||
La scena `games/juggleboard/scenes/juggleboard.tscn` usa `JuggleBoardGame` in `games/juggleboard/scripts/game_controller.gd`.
|
||
|
||
Il controller crea plancia, biglie, HUD, audio e overlay, poi applica le regole di gioco:
|
||
|
||
- seleziona una biglia bersaglio tra quelle ferme;
|
||
- assegna punti in base alla combo;
|
||
- riduce il tempo di risposta in funzione del punteggio;
|
||
- applica il decadimento della combo e la penalità degli errori;
|
||
- gestisce Target, Zen e Survival;
|
||
- mostra vittoria al raggiungimento del punteggio obiettivo oppure game over dopo l'esaurimento delle vite in Survival.
|
||
|
||
### Componenti del dominio
|
||
|
||
| Area | Percorso | Responsabilità |
|
||
| --- | --- | --- |
|
||
| Configurazione di layout | `scripts/juggleboard_config.gd` | Costanti di viewport, corsie, colori e frequenze musicali. |
|
||
| Plancia e biglie | `scripts/components/board.gd`, `ball.gd` | Disegno della plancia e delle biglie, rilevamento di prossimità e animazione Tween del rotolamento. |
|
||
| Bersaglio | `scripts/components/target_dot.gd` | Rappresentazione della biglia richiesta nell'HUD. |
|
||
| HUD | `scripts/ui/game_hud.gd`, `hearts_display.gd`, `hud_cartouche.gd` | Punteggio, combo, timer, vite e cartiglio. |
|
||
| Opzioni | `scripts/ui/options_menu.gd`, `options_schema.gd`, `option_slider_row.gd` | Configurazione dei parametri di gioco. |
|
||
| Protezione adulto | `scripts/ui/lock_menu.gd` e relativi componenti | Sblocco delle opzioni tramite sequenza colori. |
|
||
| Fine partita | `scripts/ui/victory_overlay.gd` | Overlay per vittoria e game over, con reset. |
|
||
| Audio | `scripts/audio/game_audio.gd`, `circus_music.gd` | BGM e suoni di gioco; il BGM OGG è in `assets/audio/`. |
|
||
|
||
Le scene accessorie sono `options_menu.tscn`, `lock_menu.tscn` e `victory_overlay.tscn` nella stessa directory `games/juggleboard/scenes/`.
|
||
|
||
## Risorse condivise
|
||
|
||
- `shared/settings/settings.gd`: persiste i parametri in `user://settings.cfg`. Incrementare `VERSION` quando cambiano i valori predefiniti.
|
||
- `shared/audio/audio_factory.gd`: genera e riproduce feedback sonori morbidi.
|
||
- `menus/assets/audio/upendi_sign_drop.wav` e `upendi_sign_bounce.wav`: effetti CC0 OpenGameArt dell’insegna, convertiti in WAV PCM sedici bit e riprodotti da `MenuAudio`.
|
||
- `shared/ui/`: definisce tema, finiture e cornici circensi riusabili.
|
||
- `shared/assets/`: contiene font e texture comuni.
|
||
- `shared/branding/`: contiene logo UPENDI e risorse del boot splash.
|
||
|
||
## Dominio Palestra di giocoleria
|
||
|
||
`games/juggling_gym/scenes/juggling_gym.tscn` usa `JugglingGymGame` per il prototipo P3B. Il mockup completo resta lo sfondo della scena; `GymTool` crea aree di trascinamento trasparenti sopra la barra inferiore e `GymDropZone` gestisce i tre bersagli sui giocolieri.
|
||
|
||
Nel primo prototipo sono attivi tre attrezzi, con associazione univoca:
|
||
|
||
- palline → giocoliere sinistro;
|
||
- piatti cinesi → giocoliere destro;
|
||
- sfera → giocoliere centrale.
|
||
|
||
Rola bola e clave sono visibili nel mockup ma non ancora disponibili. Un rilascio corretto incrementa il progresso, disabilita l’attrezzo già posizionato e mostra il feedback; un rilascio errato lascia l’attrezzo riprovabile.
|
||
|
||
## Verifica visuale
|
||
|
||
`AppShell` e `MainMenuController` supportano la cattura del viewport per verificare i menu senza screenshot desktop:
|
||
|
||
```bash
|
||
godot --path . -- --capture-menus
|
||
godot --path . -- --capture-menus --capture-p2a
|
||
godot --path . -- --capture-menus --capture-p3a
|
||
godot --path . -- --capture-menus --capture-mode-dialog
|
||
```
|
||
|
||
Le immagini risultanti sono salvate in `/tmp/autgame_menu_*.png`. Per una cattura diretta della palestra usare:
|
||
|
||
```bash
|
||
godot --path . -- --start-gym --capture-menus
|
||
```
|
||
|
||
La cattura viene salvata in `/tmp/autgame_juggling_gym.png`. Per una cattura diretta di JuggleBoard usare:
|
||
|
||
```bash
|
||
godot --path . -- --start-juggleboard --capture-menus
|
||
```
|
||
|
||
che salva `/tmp/autgame_juggleboard.png`.
|