aee-arcade/docs/convencions.md

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

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.