From dade05eeac57ab4dcc828577d915689072ec0ab7 Mon Sep 17 00:00:00 2001
From: Matteo Benedetto <me@enne2.net>
Date: Wed, 1 Jul 2026 10:21:52 +0000
Subject: [PATCH] init: Build-&-Run

---
 Build-%26-Run.-.md | 100 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 Build-%26-Run.-.md

diff --git a/Build-%26-Run.-.md b/Build-%26-Run.-.md
new file mode 100644
index 0000000..440e1b3
--- /dev/null
+++ b/Build-%26-Run.-.md
@@ -0,0 +1,100 @@
+# Build & Run
+
+Come compilare il ROM a partire dal sorgente.
+
+## Prerequisiti
+
+1. **GBDK-2020** installato (testato con 4.2.0+)
+   - Path di default nel Makefile: `~/local/gbdk` (modifica `GBDK_HOME` se necessario)
+   - Variabili richieste: `lcc`, `png2asset`
+2. **Python 3** con:
+   ```bash
+   pip install --user Pillow pyboy opencv-python numpy
+   ```
+3. **make** e **bash**
+4. (Opzionale) un emulatore per testare il ROM:
+   - **BGB** (https://bgb.bircd.org/) — debugger consigliato
+   - **SameBoy** (https://github.com/LIJI32/SameBoy) — accurato
+   - **mGBA** (https://mgba.io/) — multipiattaforma
+   - **PyBoy** — Python, headless-friendly
+
+## Compilazione
+
+Da Windows / Linux / macOS con bash:
+
+```bash
+# Pulizia completa (rigenera anche gli asset da PNG)
+make clean
+
+# Build standard: produce hello_iso.gb + test_gameover.gb
+make
+
+# Build "release": copia anche con il nome canonico AScreamFromTheDark.gb
+make release
+```
+
+Output:
+
+| File | Descrizione |
+|---|---|
+| `build/hello_iso.gb` | ROM principale (32 KB) |
+| `build/AScreamFromTheDark.gb` | copia "release" (identica) |
+| `build/test_gameover.gb` | ROM di test game-over (più piccola) |
+| `build/*.map`, `build/*.noi` | simboli per debug |
+
+## Struttura del Makefile
+
+I target principali sono:
+
+| Target | Effetto |
+|---|---|
+| `make` | genera asset e compila i 2 ROM |
+| `make release` | `make` + copia `AScreamFromTheDark.gb` |
+| `make clean` | rimuove `build/` e tutti i `.c/.h` generati |
+| `make generate_images` | rigenera i PNG da Python |
+| `make generate_c_assets` | rigenera i `.c/.h` da PNG via `png2asset` |
+
+## Esecuzione
+
+### Su emulatore desktop
+
+```bash
+# mGBA
+mgba build/AScreamFromTheDark.gb
+
+# SameBoy
+sameboy build/AScreamFromTheDark.gb
+
+# BGB
+bgb build/AScreamFromTheDark.gb
+```
+
+### Su hardware reale
+
+Il ROM è 32 KB flat, compatibile con qualsiasi flashcart DMG/CGB:
+- **EverDrive GB X7 / Mini**
+- **BennVenn JoeyJr**
+- **FPGA cores** (Analogue Pocket)
+- **GB Operator**
+
+Copia `AScreamFromTheDark.gb` sulla SD del flashcart, accendi la console, seleziona il gioco.
+
+### Nel browser (WebAssembly)
+
+Vedi [Play in Browser](Play-in-Browser) per come eseguire il ROM in un emulatore WASM.
+
+## Variabili del Makefile
+
+```make
+GBDK_HOME = /home/enne2/.local/gbdk   # path di GBDK-2020
+SRC_DIR   = src                        # sorgenti C
+ASSETS_DIR = assets                    # PNG sorgenti
+BUILD_DIR = build                      # output
+```
+
+## Troubleshooting
+
+- **`png2asset: warning 64: 64 palettes found, truncating to 8`**: warning benigno, ignorabile.
+- **`conditional flow changed by optimizer`**: warning SDCC, non blocca la compilazione.
+- **ROM troppo grande (> 32 KB)**: errore di link. Controlla che i `.c/.h` generati non si siano accumulati dopo un `make` parziale. Esegui `make clean` e ricompila.
+- **font IBM non visibile**: controlla che `font_ibm` sia disponibile in GBDK (`$(GBDK_HOME)/include/gb/font_ibm.h`).