# Boss Alien Grunt — ondate dedicate e simulazione nativa

Pubblicato su https://enne2.net/pub/zombie-fps/ nella release **`86c32ea9f5a4470e`**.
Boss e asset sono inclusi nella versione Web; la simulazione diretta resta nativa.

## Regole delle ondate

- **10, 20, 30, ...**: un solo Alien Grunt sostituisce l'intera ondata ordinaria.
  Nessuno zombie aggiuntivo, nessuna seconda fase o sotto-ondata.
- Dopo la morte del boss, attesa standard di 3 secondi e ripresa degli zombie
  nell'ondata successiva (11, 21, ...).
- Il boss conta come vivo fin dall'apertura del portale: il preavviso non viene
  scambiato per un'ondata vuota. Morte, premio e transizione sono emessi una sola volta.
- Il teletrasporto cerca una posizione libera dagli arredi e collegata alla
  navigazione, distante almeno 5 metri dal giocatore. Il preavviso dura **1,5 s**:
  anelli, particelle CPU, luce verde/ciano e suoni originali di teletrasporto.
  Durante il preavviso il boss è invisibile e non colpibile.
- Barra della vita dedicata, grado e indicatore ARRIVO nell'HUD. Leggero bagliore
  Xen senza ombre per rendere il boss leggibile dopo lo spegnimento del portale.

## Progressione e combattimento

Il grado è `ondata / 10`; salute e danni aumentano senza cambiare la geometria del boss.
Velocità e cadenza hanno limiti per lasciare spazio alla schivata.

| Ondata | Grado | Vita | Danno pugno | Danno/proiettile | Velocità m/s | Intervallo attacchi | Premio |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 10 | 1 | 800 | 28 | 8 | 2,00 | 2,80 s | 1000 |
| 20 | 2 | 1200 | 34 | 10 | 2,12 | 2,62 s | 2000 |
| 30 | 3 | 1600 | 40 | 12 | 2,24 | 2,44 s | 3000 |

Formule (grado `g`):

- HP: `800 + 400 × (g − 1)`.
- Pugno: `28 + 6 × (g − 1)`; proiettile: `8 + 2 × (g − 1)`.
- Velocità: `min(3.4, 2 + 0.12 × (g − 1))`.
- Intervallo: `max(1.3, 2.8 − 0.18 × (g − 1))` secondi.
- Premio: `1000 × g`, indipendente dal colpo finale alla testa.

Il boss insegue usando la stessa mappa A* degli zombie, con capsula raggio 0,45 m e
altezza 2,4 m. Pugno ravvicinato ritardato di 0,45 s e controllato per distanza e
occlusione. A distanza: animazione di preavviso, poi tre hornet originali separati da
0,18 s. Velocità 8 m/s, traiettoria rettilinea **schivabile**, non hitscan e non a ricerca.
Un raggio continuo fra le posizioni fisiche intercetta giocatore e pareti: i proiettili
non attraversano gli oggetti. Vita massima 3 s; morte del boss annulla i colpi pendenti
ed elimina i suoi proiettili ancora in volo.

Fucile e granata usano la normale hitbox/gruppo `live_zombies`. Colpo alla testa sopra
1,95 m: moltiplicatore **1,5** (non quello dello zombie ordinario). Durante il
teletrasporto i danni sono ignorati. Alla morte il corpo resta, senza collisioni né
conteggio fra i nemici vivi.

## Prova nativa immediata

Dalla radice del progetto, senza attendere nove ondate:

```bash
# Primo boss, salute del giocatore normale
tools/run_boss_simulation.sh 10

# Primo boss, giocatore invulnerabile (modalità usata per la prova interattiva)
tools/run_boss_simulation.sh 10 --boss-god

# Boss successivi, già potenziati
tools/run_boss_simulation.sh 20
tools/run_boss_simulation.sh 30 --boss-god
```

Il launcher usa Godot 4.7.1 installato e il renderer Compatibility. Un'altra posizione
si può indicare con `GODOT_BIN=/percorso/Godot`. Equivalente diretto:

```bash
"$HOME/.local/opt/godot-4.7.1/Godot_v4.7.1-stable_linux.x86_64" \
  --path . --rendering-method gl_compatibility -- --boss-wave=10 --boss-god
```

**Gli argomenti di gioco vanno dopo `--`.** Il numero deve essere un multiplo positivo
di dieci; valori non validi terminano con codice 2. Questi argomenti sono ignorati
sul Web: la simulazione è esclusivamente nativa.

Controlli invariati: WASD, mouse, sinistro fucile, destro granata, R ricarica,
Spazio salto, Esc cursore. In modalità invulnerabile munizioni e ricariche restano
reali, semplicemente non si perdono HP.

- Parte direttamente il teletrasporto, senza menu o nome.
- La simulazione **non legge né scrive il profilo**, non aggiorna il miglior punteggio
  e disattiva la classifica anche se viene passato `--api=`.
- Dopo la vittoria resta nella **singola ondata** di prova; R oppure RIPROVA riavviano
  lo stesso grado. Dopo la morte valgono R/RICOMINCIA già presenti nel gioco.
- Per una prova senza invulnerabilità, avviare il comando senza `--boss-god`.
- La proprietà `player.invulnerable` è falsa nel gioco normale; `--boss-god` da solo,
  senza una simulazione, non la abilita.

## Asset originali e compatibilità

`tools/extract_boss_assets.py` legge l'installazione locale di Half-Life senza modificarla:

- `agrunt.mdl` + le 28 texture del companion `agruntt.mdl` incorporato.
- `hornet.mdl`, con texture già presenti.
- Voci `sound/agrunt/ag_{alert,attack,fire,idle,pain,die}1.wav`.
- `sound/ambience/port_suckin1.wav` e `port_suckout1.wav`.

Gli MDL derivati sono in `assets/boss/`, con SHA256 sorgenti/derivati e lista delle
animazioni in `source_manifest.json`. Sono conservate **25 sequenze autonome del
sequence-group zero** del grunt, incluse idle/walk/run, melee, hornetattack e morti.
Le 7 sequenze del gruppo esterno `agrunt01.mdl` (cinematiche e doppioni attack3) sono
escluse esplicitamente, non importate come clip vuote.

`tools/export_boss_assets.gd` genera `agrunt_textured.scn` e `hornet_textured.scn`,
verificando texture e animazioni. In alternativa il normale
`tools/export_web_assets.gd` ora include anche i due modelli. Runtime nativo/Web usa
solo **SCN, WAV e primitive Godot**, nessuna dipendenza dal plugin MDL nativo.
Nessun effetto richiede Forward+ o particelle GPU. La pipeline Web include i due
modelli; i 50 controlli sono passati anche nel progetto di staging senza GDExtension.
Il menu della release pubblicata è stato verificato nel browser senza avviare
partite di prova sulla classifica pubblica.

```bash
python3 tools/extract_boss_assets.py
"$HOME/.local/opt/godot-4.7.1/Godot_v4.7.1-stable_linux.x86_64" --headless --path . --import
"$HOME/.local/opt/godot-4.7.1/Godot_v4.7.1-stable_linux.x86_64" --headless --path . \
  --script res://tools/export_boss_assets.gd
```

## Verifiche

```bash
G="$HOME/.local/opt/godot-4.7.1/Godot_v4.7.1-stable_linux.x86_64"
"$G" --headless --path . --script res://tools/test_boss.gd
DISPLAY=:0 "$G" --path . --display-driver x11 --rendering-method gl_compatibility \
  --script res://tools/test_boss.gd
DISPLAY=:0 "$G" --path . --display-driver x11 --rendering-method gl_compatibility \
  --script res://tools/shot_boss.gd
```

**50 controlli**: selezione delle ondate, progressione e limiti, sedici estrazioni del
portale, completamento reale dell'ondata 9 con 22 zombie e transizione 9→10→11,
boss unico, teletrasporto/invulnerabilità iniziale, texture/animazioni, proiettili e
ostacoli, corpo a corpo, navigazione fisica attorno a entrambe le scrivanie/sedie/bidone,
fucile/granata, barra HP frazionaria, morte/premio singoli, annullamento raffiche,
simulazione di grado 2 con vittoria/morte e profilo persistente byte-identico.

Passate inoltre le 15 suite Godot preesistenti e i 42 controlli dell'API locale.
Le prove GUI `test_start_screen` richiedono il display reale **senza `--touch`**;
`test_touch_controls` viene eseguito separatamente con `--touch`.
Restano gli avvisi di risorse non liberate alla chiusura già presenti nelle prove
con gli asset GoldSrc; nessun errore di script durante il combattimento.

Screenshot: `/tmp/zombie-boss-{portal,arrival,combat}.png`.

Riferimento originale: https://github.com/ValveSoftware/halflife/blob/master/dlls/agrunt.cpp
(il boss potenziato e le regole di ondata sono specifici di questo progetto).