187 lines
9.4 KiB
Markdown
187 lines
9.4 KiB
Markdown
|
||
|
||
# JuggleBoard Game
|
||
|
||
Gioco arcade **reaction & chaining** per dispositivi mobili (orizzontale), realizzato in **Godot 4.7** (GDScript), ispirato al prodotto riabilitativo **"Juggle Board" by Craig Quat / Play Juggling**.
|
||
|
||
**Prodotto per la [Cooperativa Sociale UPENDI](https://www.upendi.it/)** (Gravina in Puglia) — Pedagogia del Circo e Circo Sociale. Target: bambini, anche neurodivergenti (autismo, ADHD, iperreattività sensoriale): suoni morbidi (sine, niente onde quadre/sega), palette tenue, modalità Zen e errori gentili.
|
||
|
||
---
|
||
|
||
## Gameplay
|
||
|
||
- **5 corsie orizzontali in legno** (plancia a tutta larghezza), ognuna con una **pallina colorata** glossy (corallo, blu, verde, giallo, viola) a riposo sull'alloggiamento destro.
|
||
- Un **bersaglio in alto** (HUD a cartiglio) indica quale pallina toccare; la pallina rotola a sinistra e torna (con **rotazione realistica** attorno all'asse perpendicolare al moto).
|
||
- Devi concatenare i lanci prima che scada il timeout. **Difficoltà crescente legata SOLO al punteggio** (`score_ramp = 8000` → velocità massima).
|
||
- Punteggio per lancio = **combo × valore punto** (`points_per_combo`, default 1; combo max 5).
|
||
- **Suoni generati proceduralmente** in 8-bit (sine morbide); BGM circense AI (Lyria) in OGG.
|
||
|
||
### Modalità di gioco (dialog all'avvio)
|
||
| Modalità | Descrizione |
|
||
|----------|-------------|
|
||
| **Target (Classica)** | Raggiungi il punteggio `target_score` (default 1000) → VITTORIA |
|
||
| **Target (Zen)** | Come Target ma **senza countdown né decay** combo |
|
||
| **Infinita (Survival)** | **A vite**: 4 cuori; errore o timeout = −1 cuore; 0 cuori → **GAME OVER** (ignora il target) |
|
||
|
||
Le modalità sono **mutuamente esclusive**; lo Zen è disponibile **solo** per la modalità Target.
|
||
|
||
### Protezione adulti (lock)
|
||
Il menù **Opzioni** è protetto: va sbloccato premendo la sequenza **giallo → verde → blu → rosso** tra le 5 biglie (pallini che mostrano i colori premuti; reset dopo feedback rosso 2s se la sequenza di 4 è errata).
|
||
|
||
---
|
||
|
||
## Requisiti
|
||
|
||
- **Godot 4.7.x** (testato con 4.7.1), renderer **GL Compatibility**.
|
||
- Per l'APK Android: JDK 17, Android SDK (vedi sotto), template Android.
|
||
|
||
## Eseguire
|
||
|
||
```bash
|
||
godot --path . # gioco
|
||
godot -e . # editor
|
||
godot --headless --path . --quit-after 120 # smoke test (errori)
|
||
```
|
||
|
||
## Struttura
|
||
|
||
```
|
||
project.godot # viewport 1280×720 orizzontale, GL Compatibility, ETC2/ASTC
|
||
export_presets.cfg # preset Web e Android
|
||
app/
|
||
scenes/app_shell.tscn # scena iniziale configurata in project.godot
|
||
scripts/app_shell.gd # coordina menu, selettore modalità e gioco attivo
|
||
menus/
|
||
scenes/ # shell menu e schermate P1, P2a, P3a
|
||
scripts/main_menu_controller.gd # navigazione e transizioni tra le schermate
|
||
scripts/screens/ # costruzione delle schermate Home, Juggle e Palestra
|
||
scripts/components/ # UI e audio condivisi dei menu
|
||
assets/ # fondali, tendoni, pulsanti e shader dei menu
|
||
games/
|
||
juggleboard/
|
||
scenes/ # scena di gioco, opzioni, lock adulto e fine partita
|
||
scripts/game_controller.gd # regole, punteggio, combo, timer e modalità
|
||
scripts/components/ # plancia, biglie e bersaglio
|
||
scripts/ui/ # HUD, cuori, opzioni e overlay
|
||
scripts/audio/ # BGM e feedback sonori
|
||
assets/ # texture e BGM di JuggleBoard
|
||
juggling_gym/ # asset provvisori della futura Palestra di giocoleria
|
||
shared/
|
||
settings/settings.gd # AUTOLOAD Settings: parametri e user://settings.cfg
|
||
audio/ # fabbrica dei suoni procedurali
|
||
ui/ # tema, cornici e decorazioni circensi riusabili
|
||
assets/ # font e texture condivise
|
||
branding/ # logo UPENDI e boot splash
|
||
docs/ # mockup, materiali di design e ARCHITECTURE.md
|
||
build/ # directory ignorata per gli export Web e Android
|
||
```
|
||
|
||
Il flusso e le responsabilità dei componenti sono descritti in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
|
||
|
||
## Impostazioni (`shared/settings/settings.gd` → `user://settings.cfg`)
|
||
|
||
Parametri modificabili dal menù Opzioni: tempi (start/min), `score_ramp`, `points_per_combo`, `target_score`, `max_combo`, decay combo (threshold/rate), `difficulty_decay_rate`, `gentle_errors`, `game_mode` (0 Classica, 1 Zen, 2 Survival).
|
||
|
||
> **CRITICO**: `shared/settings/settings.gd` ha `const VERSION`. Quando si cambiano i **default**, incrementare `VERSION`: i file `settings.cfg` salvati con versione più vecchia vengono **resettati ai nuovi default** (altrimenti i vecchi valori salvati sovrascrivono i nuovi default).
|
||
|
||
---
|
||
|
||
## Build Web
|
||
|
||
```bash
|
||
godot --headless --path . --export-release "Web" build/web/index.html
|
||
```
|
||
|
||
## Pubblicare il Web (enne2.net)
|
||
|
||
```bash
|
||
cd build/web
|
||
scp -r . debian@enne2.net:/home/debian/public_html/autgame/
|
||
```
|
||
→ URL: **https://enne2.net/pub/autgame/** (Nginx: `location /pub/` alias `/home/debian/public_html/`, autoindex on).
|
||
Nota: troppe connessioni SSH rapide attivano fail2ban → raggruppa i comandi.
|
||
|
||
## Build APK Android
|
||
|
||
Setup una tantum (macchina di sviluppo, senza sudo):
|
||
|
||
```bash
|
||
# 1) JDK portatile (Temurin 17)
|
||
# ~/.local/opt/jdk-17.0.20+8 (scarica da api.adoptium.net)
|
||
# 2) Android SDK in ~/Android/Sdk:
|
||
# cmdline-tools/latest/bin/sdkmanager (scaricare commandlinetools)
|
||
# sdkmanager "platform-tools" "platforms;android-35" "platforms;android-36" \
|
||
# "build-tools;35.0.0" "build-tools;36.0.0" (con JAVA_HOME esportato)
|
||
# 3) Impostazioni editor Godot (~/.config/godot/editor_settings-4.7.tres):
|
||
# export/android/android_sdk_path = "~/Android/Sdk"
|
||
# export/android/java_sdk_path = "~/.local/opt/jdk-17.0.20+8"
|
||
# 4) Debug keystore (alias androiddebugkey, pass android):
|
||
# ~/.local/share/godot/keystores/debug.keystore
|
||
# (usato anche come release keystore nel preset export_presets.cfg)
|
||
# 5) project.godot deve avere rendering/textures/vram_compression/import_etc2_astc=true
|
||
```
|
||
|
||
Build + firma:
|
||
|
||
```bash
|
||
export JAVA_HOME=~/.local/opt/jdk-17.0.20+8
|
||
export ANDROID_HOME=~/Android/Sdk
|
||
export PATH="$JAVA_HOME/bin:$ANDROID_HOME/build-tools/36.0.0:$PATH"
|
||
godot --headless --path . --export-release "Android" build/android/autgame.apk
|
||
# output: APK firmato v2/v3 (apksigner) in build/android/autgame.apk
|
||
```
|
||
|
||
Il preset usa l'**export classico** (`gradle_build/use_gradle_build=false`), che richiede i template Android in `~/.local/share/godot/export_templates/4.7.1.stable/` (da Godot_v4.7.1-stable_export_templates.tpz: `android_release.apk`, `android_debug.apk`, `android_source.zip`).
|
||
|
||
## Pubblicare la release su git.enne2.net (API)
|
||
|
||
```bash
|
||
TOKEN=$(python3 -c "import yaml;d=yaml.safe_load(open('$HOME/.config/tea/config.yml'));print([l['token'] for l in d['logins'] if l['name']=='enne2'][0])")
|
||
# nuova release (o riusa l'id esistente, es. 15 per v0.1):
|
||
curl -s -X POST https://git.enne2.net/api/v1/repos/enne2/autgame/releases \
|
||
-H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
|
||
-d '{"tag_name":"v0.2","name":"0.2","body":"..."}' # -> id RELEASE_ID
|
||
# sostituire l'asset APK:
|
||
AID=$(curl -s https://git.enne2.net/api/v1/repos/enne2/autgame/releases/$RELEASE_ID \
|
||
-H "Authorization: token $TOKEN" | python3 -c "import sys,json;print(json.load(sys.stdin)['assets'][0]['id'])")
|
||
curl -s -X DELETE .../releases/$RELEASE_ID/assets/$AID -H "Authorization: token $TOKEN"
|
||
curl -s -X POST .../releases/$RELEASE_ID/assets?name=autgame.apk -H "Authorization: token $TOKEN" \
|
||
-F "attachment=@build/android/autgame.apk"
|
||
```
|
||
|
||
Note: il CLI `tea repos create` ha un bug ("GetOrgByName") con owner utente → creare repo via `POST /api/v1/user/repos`. Avatar repo: `POST /api/v1/repos/{owner}/{repo}/avatar` con body JSON `{"image": "<base64 puro>"}`.
|
||
|
||
## Cattura screenshot interna Godot
|
||
|
||
Per il debugging grafico usare il Viewport Capture interno, non KDE/Spectacle come metodo primario. Il controller menu include flag di verifica:
|
||
|
||
```bash
|
||
# P1 (default), P2a, P3a o dialog modalità:
|
||
godot --path . -- --capture-menus
|
||
godot --path . -- --capture-menus --capture-p2a
|
||
godot --path . -- --capture-menus --capture-p3a
|
||
godot --path . -- --capture-menus --capture-mode-dialog
|
||
```
|
||
|
||
Gli screenshot vengono salvati in `/tmp/autgame_menu_*.png` dopo `await RenderingServer.frame_post_draw`, quindi includono il Viewport completo senza bordi della finestra.
|
||
|
||
## Workflow sviluppo (pi/Codex)
|
||
|
||
- La **logica** va implementata e verificata direttamente in Godot (test headless + screenshot).
|
||
- Per il **polish visivo** (tema legno/ottone/circo), mandare gli **screenshot** dello stato attuale a Codex CLI con prompt chiaro:
|
||
```bash
|
||
codex exec -C /home/enne2/Dev/autgame --dangerously-bypass-approvals-and-sandbox \
|
||
-i shot1.png -i shot2.png < prompt.txt
|
||
```
|
||
- **Chiudere sempre il processo godot dopo gli screenshot** (altrimenti interferisce).
|
||
|
||
## Asset generati con AI
|
||
|
||
- Texture legno e sfondo circo: modello immagini Antigravity.
|
||
- BGM circense: **API Gemini Lyria** (`lyria-3-pro-preview`), convertita in **OGG Vorbis** (Godot non importa .opus) con loop attivo nell'import.
|
||
- Logo UPENDI (boot splash, avatar repo, README): Gemini image / immagine da upendi.it.
|
||
|
||
---
|
||
|
||
© Cooperativa Sociale UPENDI — Gravina in Puglia
|