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:

istanzia il menu principale e il dialog di selezione modalità;
mostra la schermata Home, oppure una destinazione di debug richiesta dalla riga di comando;
quando l'utente conferma una modalità, nasconde il menu e istanzia JuggleBoard;
mantiene un solo gioco attivo alla volta.

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:

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:

godot --path . -- --start-gym --capture-menus

La cattura viene salvata in /tmp/autgame_juggling_gym.png. Per una cattura diretta di JuggleBoard usare:

godot --path . -- --start-juggleboard --capture-menus

che salva /tmp/autgame_juggleboard.png.

5.4 KiB Raw Blame History Unescape Escape