# Convencions del repo

## Missatges de commit

- En **valencià**, frases curtes i compactes.
- **Sense firma**: res de `Co-Authored-By:`, `Generated with Claude Code`, ni cap altra firma automàtica.
- Un commit per unitat lògica. Si el canvi afecta àrees separades (feature + docs + test), separar en commits diferents.
- Prefix opcional estil convencional (`feat:`, `fix:`, `refactor:`, `docs:`, `test:`) quan ajude a la llegibilitat.

Exemple correcte:

```
feat(scenes): afegir placeholders LogoScene/TitleScene/IntroScene

Tres escenes de 5 s cadascuna que precedeixen GameScene. Cada classe
té el seu fitxer perquè divergiran quan es desenvolupe el contingut
real (logo animat, menú de títol, cutscene).
```

## `debug.yaml` (ajust de dev, no versionat)

Fitxer personal de desenvolupament, **fora del repo**. Viu a la mateixa carpeta
de sistema que `config.yaml`:

- Linux (XDG): `$XDG_CONFIG_HOME/jailgames/aee_arcade/debug.yaml`
  - Per defecte: `~/.config/jailgames/aee_arcade/debug.yaml`

### Comportament segons build

Convenció alineada amb `../aee` i `../projecte_2026`:

- **Release** (`make` — binari d'ús normal): `debug.yaml` s'ignora completament.
  El joc arranca sempre a `LOGO` i recorre el flux sencer
  `LOGO → TITLE → INTRO → GAME`, tal com ho veurà el jugador final.
- **Debug** (`make debug`): es llig `debug.yaml`. Si no existeix, es crea
  automàticament amb `start_scene: GAME` perquè el dia a dia de gameplay no
  arrossegui els 15 s de placeholders. Editant-lo a mà, es pot triar el punt
  d'entrada.
- `make release` fa el Release + empaquetat per a distribució (zip/dmg/tar.gz);
  l'empaquetat concret està pendent d'implementar.

### Format

```yaml
start_scene: GAME   # valors vàlids: LOGO, TITLE, INTRO, GAME
```

- `start_scene: LOGO` → arranca a `LogoScene` i recorre `LOGO → TITLE → INTRO → GAME`.
- `start_scene: TITLE` → arranca a `TitleScene` i recorre `TITLE → INTRO → GAME`.
- `start_scene: INTRO` → arranca a `IntroScene` i recorre `INTRO → GAME`.
- `start_scene: GAME` → arranca directament a `GameScene` (valor que s'escriu
  per defecte en la creació automàtica).

### Comportament davant d'errors (build debug)

- Fitxer buit, valor desconegut o YAML invàlid → `GAME` amb warning a stderr.
  El fitxer no es reescriu automàticament: es respecta l'edició manual per si
  l'usuari ha teclejat alguna cosa intencionadament.

### Durada dels placeholders

Cada escena placeholder (LOGO, TITLE, INTRO) mostra el seu nom i un compte
regressiu de 5 segons al centre de la pantalla. Es pot saltar amb qualsevol
tecla excepte les registrades a `data/input/keys.yaml` (F1–F12 i Escape),
que mantenen el seu comportament de hotkey global.