ascreamfromthedark-gb/doc/AScreamFromTheDark_report.md

# A Scream from the Dark — Report Tecnico Approfondito

> Survival-horror procedurale isometrico per Game Boy (DMG/CGB), scritto in C con **GBDK-2020** (SDCC).
> Repository: `gameboy-hello-iso` · ROM: `build/hello_iso.gb` (32 KB).
> ~6500 righe C/H + ~2000 righe Python (pipeline asset).

---

## 1. Identità del gioco

"A Scream from the Dark" è un survival-horror procedurale in prospettiva isometrica 2.5D. Sei imprigionato in un labirinto generato casualmente, illuminato solo da un ristretto quadrato di visibilità (Fog of War). Dei **fantasmi** si nascondono nel buio e ti braccano. L'unica via è una **botola** posta lontano dalla partenza: raggiungerla significa sprofondare più giù (*Going Deeper*) e affrontare un livello più grande, con più nemici e meno visibilità. Dopo **8 livelli** il gioco finisce con un **finale tragico**.

### Loop di gioco
1. **Title screen** — sfondo 2-bit + tema musicale tragico (112 note, 3 canali, ~56 sec in loop).
2. **Gameplay** — esplorazione a griglia con camminata, **corsa** (B+direzione), **salto evasivo** (A+direzione), stamina, AI greedy multi-nemico, hitbox pixel-perfect. Indicatore `L<n>` in alto a sinistra.
3. **Game Over (Sconfitta)** — 45 frame di fermo immagine → schermata `claimed.png` + metasprite "GAME OVER" + musica tragica (128 note). START → ricomincia dallo stesso livello.
4. **Going Deeper (Vittoria, livelli 1-7)** — schermata testuale "GOING DEEPER / LEVEL N" + melodia misteriosa (96 step). START → livello successivo (più grande, più difficile).
5. **Finale (Livello 8)** — `game_over = 3`: sfondo nero, messaggio tragico (spoiler-free) + musica dedicata (192 note, lamento discendente in Re minore, loop). START → titolo.

---

## 2. Architettura del codice

### 2.1 Moduli
| File | Ruolo |
|------|-------|
| `main.c` | Entry point, loop VBL, `app_state` (0=title, 1=game). |
| `engine.c` | Orchestrazione: `title_init/update`, `engine_init`, `engine_update`, game-over branches (1/2/3). |
| `globals.c/h` | Stato globale: mappa `[21][21]`, `map_size`, `fog_radius`, `level`, `num_enemies`, enemy arrays[8], stamina, ecc. |
| `maze.c` | DFS + loop + botola. Array statici in WRAM. |
| `player_logic.c` | DAS, camminata, corsa, salto, stamina, rilevamento botola (game_over 2/3). |
| `enemy_logic.c` | AI greedy multi-entity, cooldown scalabile, rendering, hitbox. |
| `render.c` | Iso, fog scalabile, auto-tiling multi-pass, flush dinamico 16-righe, HUD stamina + livello. |
| `sound.c` | Sequencer VBL: title (112), gameplay (96), gameover (128), finale (192 loop). |
| Asset `.c` | `tiles`, `player`, `enemy`, `gameover`, `stamina`, `level`, `claimed`, `title_bg` (png2asset). |

### 2.2 Pipeline asset
Script Python (`generate_assets.py`, `generate_enemy.py`, `generate_level.py`) → PNG → `png2asset` → `src/*.c` → `lcc` (SDCC) → ROM.

---

## 3. Funzionalità chiave

### 3.1 Proiezione isometrica
```
iso_x = (lx - ly) * 2 + 12    // tile 32x16
iso_y = (lx + ly) * 1 + 2     // altezza 8px
px = (lx - ly) * 16 + 96      // pixel fisici
py = (lx + ly) * 8  + 16
```
Camera: `scroll_x = px - 64`, `scroll_y = py - 72`.

### 3.2 Generazione labirinto (`maze.c`)
- **DFS iterativo** con stack in WRAM (statico, sized per `MAX_MAP_SIZE=21`). Celle dispari = stanze, pari = muri.
- **Loop**: riapertura 15% dei muri → percorsi alternativi.
- **Botola**: cella a Chebyshev ≥ `map_size/2` da (1,1), scelta casuale.
- **Dimensioni crescenti**: `map_size = 7 + 2*(level-1)`, capped 21 (livello 8). Sempre dispari.

### 3.3 Movimento & DAS (`player_logic.c`)
- **State machine**: durante `is_moving` (16 frame, 8 in corsa) input ignorato.
- **LERP** a punto fisso `>>4`. Corsa: `move_progress += 2`.
- **DAS**: delay 12, repeat 6 (walk) / 2 (run).
- **Salto**: A+dir → 2 tile, cella intermedia deve essere muro, stamina ≥ 60. Arco parabolico visivo.
- **Corsa**: B+dir, stamina ≥ 10, 8 frame/tile, 10 stamina/tile. Fallback a walk se stamina < 10.
- **Stamina**: ricarica 1 pt ogni `stamina_recharge_rate` (60..144 frame, scala col livello).

### 3.4 Fog of War (`render.c` + `enemy_logic.c`)
Chebyshev `max(|dx|,|dy|)` con raggio `fog_radius`:
- L1-6: `fog_radius = 2` (5×5).
- L7-8: `fog_radius = 1` (3×3).
Celle a `dist == fog_radius` → tile scuro (penombra). Il nemico si attiva solo se entro `fog_radius`.

### 3.5 Auto-tiling & multi-pass
Bitmasking 4-vicini (16 varianti × 2 stili). Pass 1: pavimenti. Pass 2: botola ( Painter's algorithm). Flush **dinamico 16 righe** centrato su `center_iso_y` con wrap (2 chiamate `set_bkg_tiles` se necessario). Necessario per labirinti grandi dove la finestra fog wrappa fuori dal range fisso 2-17.

### 3.6 AI Fantasmi (`enemy_logic.c`)
- **Multi-entity**: fino a 8 fantasmi (`num_enemies = level`). Stato in array. OAM `2+i*2`.
- **Greedy**: minimizza `dx²+dy²` tra le 4 celle adiacenti. No A* (troppo pesante su 4 MHz con 8 nemici).
- **Cooldown scalabile**: `enemy_step_cooldown = 60 - 7*(level-1)` (floor 10). Sfasamento iniziale `i*8`.
- **Hitbox pixel-perfect**: `|dx|<12 && |dy|<6`.
- **Culling**: renderizzato solo se entro `fog_radius` e on-screen.

### 3.7 Audio (`sound.c`)
Sequencer via VBL interrupt, 4 canali APU:
- **Title**: 112 note, 3 canali (CH1 melodia + CH2 basso indipendente + CH4 rintocchi), ~56 sec, loop. Progressione Dm-Bb-F-C-A7-Gm-A7 con C# (7ª armonica) e discesa cromatica. Envelope haunting.
- **Gameplay**: 96 note eerie pulse, 20 frame/nota.
- **Gameover**: 128 note polifoniche + noise (thud/crash), 10 frame/nota.
- **Finale**: 192 note (24 accordi), lamento discendente Dm→abisso (C2), 14 frame/nota, **loop infinito**. CH1 melodia sommessa + CH2 basso profondo + CH4 toll (mid/crash/deep).
- **Going Deeper**: 96 note misteriose, 15 frame/nota.
- **SFX**: salto (sweep up CH1), cattura (sweep down CH1).

### 3.8 HUD
- **Stamina** (alto dx): 5 sprite OAM 18-22. Base VRAM `tiles_TILE_COUNT` (≥128, workaround overlap).
- **Livello** (alto sx): 3 sprite OAM 23-25, asset `level.png` (glifi L, 0-9). Base VRAM allineata a indice **pari** (8x16 hardware ignora LSB). `-keep_duplicate_tiles` per ordine prevedibile. Nascosto durante game over.

### 3.9 Progressione livelli
- **8 livelli** con difficoltà crescente:
  - Maze: 7×7 → 21×21 (+2/livello).
  - Nemici: 1 → 8 (+1/livello).
  - Cooldown fantasma: 60 → 11 frame.
  - Ricarica stamina: 60 → 144 frame/pt.
  - Nebbia: 5×5 → 3×3 (dal L7).
- **Sconfitta**: ricomincia dallo stesso livello (non azzera).
- **Livello 8 superato**: `game_over = 3` (finale tragico) invece di 2.

### 3.10 Schermate
- **Title**: `title_bg.png` (160×144, 2-bit) + musica.
- **Death**: `claimed.png` (160×144, 2-bit) + metasprite "GAME OVER".
- **Going Deeper**: testo font IBM "GOING DEEPER / LEVEL N" (ex immagine, sostituita per risparmiare ROM).
- **Finale**: font IBM su sfondo nero (BGP 0x1B invertito), scritta diretta in `map_buffer` (tile = ASCII-32, no printf).

---

## 4. Workaround e fix storici (dalla git history)

| Commit | Problema | Workaround |
|--------|----------|------------|
| `93deb35` | VRAM overlap stamina/BG | Load stamina a `tiles_TILE_COUNT` (≥128). |
| `6d94992` | 2-frame lag DAS | Sync DAS con state machine passo. |
| `7d85aec` | Perfect maze intrappolava | Riapertura 15% muri → loop. |
| `b47455c` | Offset rendering nemico | Wrap `&255` + hitbox pixel-perfect 12×6. |
| `f14e264` | Scale bloccavano fantasma | Ridisegnate come botola (tile 2 calpestabile). |
| `cb19677` | Glitch next_level + scroll | Reset SCX/SCY + quantizzazione soglie fisse. |
| (livelli) | ROM >32KB con 3 immagini full-screen | Sostituito next_level image con testo font; claimed image.resize per fit. |
| (HUD livello) | Base VRAM dispari in 8x16 | Allineamento a pari `(raw+1) & 0xFE`. |
| (flush) | 32-row flush stallsava 5 frame | Flush dinamico 16-righe centrato + wrap. |
| (EVELYN) | Warning SDCC 110 | Easter-egg Frank Zappa, benigno. |

---

## 5. Debiti tecnici e osservazioni

1. **`test_movement.py`**: cerca `hello_iso.noi` nella cwd ma il Makefile genera solo `test_gameover.noi` in `build/`. Script stale.
2. **Warning 110 SDCC** ("EVELYN the modified DOG"): benigno, Easter-egg di Sandeep Dutta (omaggio a Frank Zappa, canzone "Evelyn, a Modified Dog"). Indica che l'ottimizzatore ha rielaborato il flusso di controllo.
3. **`victory.c/h` orfani**: rimossi (sostituiti da `next_level`/finale).
4. **Flush 16-righe**: ~2-3 frame di stall per `draw_map` (preesistente, accettabile). draw_map chiamato solo ai passi del movimento.
5. **Sprite budget**: ~27 sprite su 40. Per-scanline (10) rispettato (HUD alto, player centro, nemici sparsi nel fog).

---

## 6. Test & verifica

Pipeline headless (PyBoy + OpenCV):
- `test_pyboy.py` / `take_screenshot.py`: screenshot della ROM.
- `test_movement.py`: legge maze in WRAM e simula input (indirizzi stale).
- `opencv_analyze_tiles.py`: rileva disallineamenti isometrici.
- `test_gameover.gb`: ROM standalone per schermata game over.
- `test_finale.gb`: ROM standalone che va subito al finale (musica + testo) per test rapidi.

Verificato via PyBoy: dimensioni 7→21, nemici 1→8, cooldown 60→11, recharge 60→144, fog 2→1 (L7), hatch L1→game_over=2 / L8→game_over=3, finale renderizza + START→title→L1, death screen claimed.png, title music 3 canali attivi.

---

## 7. Conclusione

"A Scream from the Dark" è un survival-horror completo per Game Boy: 8 livelli di difficoltà crescente, multi-nemico, corsa e salto con stamina, fog of war scalabile, audio polifonico procedurale (4 tracce + SFX), finale tragico con musica dedicata — tutto in 32 KB di ROM e ~3 KB di WRAM. Il codice è modulare, commentato in italiano, e rappresenta un caso di studio su come tradurre feature "moderne" in matematica a punto fisso e gestione diretta dei registri hardware del Game Boy.