![UPENDI](/branding/upendi_logo.png)

# 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 1280x720 landscape, GL Compatibility, ETC2/ASTC
export_presets.cfg     # preset Web e Android
assets/
  wood_board.png       # texture legno betulla (generata con Antigravity)
  wood_board_rounded.png  # variante con angoli arrotondati (board)
  circus_arena_bg.png  # sfondo arena circo (generato)
  fonts/NotoSerifDisplay-CondensedExtraBold.ttf   # font display circense
audio/circus.ogg       # BGM circense (generata con API Lyria, loop in import)
branding/              # logo UPENDI (boot splash, avatar, README)
docs/                  # mockup visuali
scenes/main.tscn
scripts/
  settings.gd          # AUTOLOAD Settings: parametri configurabili, user://settings.cfg
  main.gd              # logica gioco, HUD, difficoltà, vittoria/game over
  board.gd             # plancia legno: corsie a larghezza variabile, alloggiamenti, circo
  ball.gd              # biglia: glossy, venature casuali per colore, rotazione (asse Y)
  target_dot.gd        # biglia bersaglio nell'HUD
  hearts_display.gd    # cuori (survival)
  lock_menu.gd         # lock sequenza colori (protegge Opzioni)
  options_menu.gd      # menù impostazioni (persistente, riavvio)
  mode_select.gd       # dialog scelta modalità all'avvio
  victory_overlay.gd   # overlay VITTORIA / GAME OVER (show_end)
  hud_cartouche.gd     # HUD a cartiglio circense
```

## Impostazioni (`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**: `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>"}`.

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