DX: config.lua com a unica font de configuracio (sense defaults amagats)

config.lua

@@ -1,12 +1,17 @@
--- Configuracio del Pepe Runner DX
+-- Configuracio del Pepe Runner DX.
--- Aquest fitxer es carrega amb dofile() al iniciar el joc.
+--
--- Si no existeix o te errors, s'usen els valors per defecte.
+-- Aquest fitxer es LA UNICA FUENT DE VERDAT per als valors editables del
--- Comenta una linia (--) per a deixar el seu valor per defecte.
+-- joc (skin, tecles, textos, temps de les animacions, vides, audio).
+-- El motor del joc (pepe_runner_dx.lua) llig aquestes globals al iniciar
+-- via dofile("config.lua"); no hi ha defaults amagats al codi.
+--
+-- Si vols recuperar un valor "original", consulta la rama de git o este
+-- mateix fitxer en versions anteriors. Si elimines una clau, el joc petara
+-- al usar-la — millor que prendre un valor obscur per defecte.
 
 -- ====================================================================
 -- ASPECTE GRAFIC
 -- ====================================================================
-
 -- Skin: nom del fitxer (sense extensio) dins de la carpeta skins/ que
 -- aporta els bitmaps i colors del joc. Skins inclosos:
 --
@@ -15,26 +20,41 @@
 --   "pintor" — Look revisat amb sprites propis (Pepe i 3 enemics diferents,
 --              escala de ma, pedra que decreix d'altura al cavar...).
 --
--- Cada skin defineix la seva propia paleta i bitmaps. Per a personalitzar
+-- Cada skin defineix la seua propia paleta i bitmaps. Per a personalitzar
 -- colors o sprites, edita el fitxer corresponent a skins/<nom>.lua.
 -- (En tots els casos el char 0 es reescriu a zeros, perque el ROM d'ascii
 --  hi te una caixa hueca que taparia tot el mapa.)
 skin = "pintor"
 
+-- ====================================================================
+-- JUGABILITAT
+-- ====================================================================
+-- Vides inicials. Convencio arcade (com Pac-Man): el numero es de
+-- "reserves", no de vides totals. 2 reserves = 3 vides totals (la actual +
+-- les 2 que es veuen al HUD). 0 = una sola oportunitat.
+VIDES_INI = 2
+
+-- Fase per la qual arranca una partida nova (1..10).
+-- Util per a depurar un mapa concret sense haver de jugar des de la 1.
+LEVEL_INI = 1
+
 -- ====================================================================
 -- TECLES
 -- ====================================================================
 -- Mapeig per defecte: cursors per a moure's, Z/X per a fer forats.
 -- Pots usar qualsevol constant KEY_* del intérpret (KEY_A..KEY_Z,
 -- KEY_UP/DOWN/LEFT/RIGHT, KEY_SPACE, KEY_RETURN, ...).
-
+-- Nota: KEY_ESCAPE no es pot usar — l'intérpret la captura per a la seua
--- keys.up        = KEY_UP
+-- consola de debug abans que Lua la veja.
--- keys.down      = KEY_DOWN
+keys = {
--- keys.left      = KEY_LEFT
+    up        = KEY_UP,
--- keys.right     = KEY_RIGHT
+    down      = KEY_DOWN,
--- keys.dig_left  = KEY_Z
+    left      = KEY_LEFT,
--- keys.dig_right = KEY_X
+    right     = KEY_RIGHT,
--- keys.quit      = KEY_Q       -- abandona la partida → game over
+    dig_left  = KEY_Z,
+    dig_right = KEY_X,
+    quit      = KEY_Q,    -- abandona la partida → game over
+}
 
 -- ====================================================================
 -- TEXTOS DEL JOC
@@ -42,52 +62,55 @@ skin = "pintor"
 -- Tots els missatges que veu el jugador. Pots editar per a corregir
 -- ortografia o traduir a una altra variant sense haver de tocar el .lua.
 -- (Convencio: Inicial Majuscula, resta minuscula.)
-
+textos = {
--- textos.title_press_play = "Prem l'espai per a jugar"
+    title_press_play = "Prem l'espai per a jugar",
--- textos.game_over        = "FI DE JOC"
+    game_over        = "FI DE JOC",
--- textos.new_record       = "Nou record !"
+    new_record       = "Nou record !",
--- textos.score_label      = "Punts"
+    score_label      = "Punts",
--- textos.level_label      = "Nivell"
+    level_label      = "Nivell",
--- textos.lives_label      = "Vides"
+    lives_label      = "Vides",
--- textos.record_label     = "Record"
+    record_label     = "Record",
--- textos.name_label       = "Nom:"
+    name_label       = "Nom:",
--- textos.name_help        = "(A-Z)"
+    name_help        = "(A-Z)",
+}
 
 -- ====================================================================
 -- TEMPS I DURACIONS
 -- ====================================================================
 -- Tots els valors van en *frames* (a 60 fps, 60 frames = 1 segon).
 -- Pots ajustar la sensacio del joc sense tocar el .lua.
-
+temps = {
--- temps.score_step           = 3    -- frames per cada +1 del comptador
+    score_step          = 3,    -- frames per cada +1 del comptador animat
---                                   -- animat del HUD. 3 = ~20 punts/segon.
+                                -- del HUD. 3 = ~20 punts/segon.
--- temps.fade_frames          = 18   -- duracio del fade out (i del fade in)
+    fade_frames         = 18,   -- duracio de cada fase del fade (out i in
---                                   -- entre pantalles. 18 = 0.3 s per fase.
+                                -- son simetrics). 18 = 0.3 s per fase.
--- temps.mort_anim_frames     = 30   -- duracio de l'animacio visual de mort
+    mort_anim_frames    = 30,   -- duracio de l'animacio visual de mort
---                                   -- (Pepe parpadejant + careta trista).
+                                -- (Pepe visible parpadejant + careta trista).
--- temps.respawn_delay_frames = 120  -- temps que Pepe queda invisible abans
+    respawn_delay_frames = 120, -- temps que Pepe queda invisible abans
---                                   -- del respawn (els malos segueixen).
+                                -- del respawn (els malos segueixen).
--- temps.invuln_frames        = 180  -- temps que Pepe es invulnerable al
+    invuln_frames       = 180,  -- temps que Pepe es invulnerable al
---                                   -- respawn, parpadejant blanc/groc.
+                                -- respawn, parpadejant blanc/groc.
--- temps.escala_step_frames   = 6    -- frames entre cada cel·la nova de
+    escala_step_frames  = 6,    -- frames entre cada cel·la nova de
---                                   -- l'escala lateral quan creix.
+                                -- l'escala lateral quan creix.
--- temps.gameover_delay_frames    = 80   -- espera abans del typewriter de
+    gameover_delay_frames   = 15,  -- espera abans del typewriter de
---                                       -- "FI DE JOC" (per a que no es
+                                   -- "FI DE JOC" (perque no es solape
---                                       -- solape amb sfx_gameover).
+                                   -- amb sfx_gameover).
--- temps.typewriter_step_frames   = 6    -- frames per cada lletra del
+    typewriter_step_frames  = 8,   -- frames per cada lletra del
---                                       -- typewriter al game over.
+                                   -- typewriter al game over.
--- temps.gameover_show_frames     = 60   -- temps que el text final es queda
+    gameover_show_frames    = 120, -- temps que el text final es queda
---                                       -- visible abans de la transicio.
+                                   -- visible abans de la transicio.
+}
 
 -- ====================================================================
--- JINGLES
+-- AUDIO (jingles dels estats no-jugables)
 -- ====================================================================
--- Es reproduixen una sola vegada quan entres al estat (title i enter name)
+-- L'engine d'ascii nomes te 1 canal d'audio: per aixo no hi ha musica
--- perque el motor d'ascii te 1 sol canal d'audio: les SFX tallarien la
+-- in-game (les SFX la tallarien). Es reprodueixen una sola vegada per
--- musica si la posarem in-game.
+-- entrada al estat (no en bucle).
+music_on = true   -- false desactiva tots els jingles. Les SFX continuen.
 
--- music_on = false              -- desactiva els jingles. Per defecte true.
+-- Melodies en MML estandard (vore ASCII_API.md §4).
-
+musica = {
--- Pots reescriure les melodies amb MML estandard (vore ASCII_API.md §4):
+    title     = "l4o4cegfedcceg",
--- musica.title     = "l4o4cegfedcceg"
+    entername = "l2o5cegcegced",
--- musica.entername = "l2o5cegcegced"
+}

pepe_runner_dx.lua

@@ -1,10 +1,22 @@
 -- Pepe Runner DX — versio millorada del port amb QoL i extres.
--- Carrega config.lua si existeix per a sobreescriure els valors per defecte.
+-- Tots els valors editables del joc viuen a `config.lua` (skin, tecles,
+-- textos, temps, vides, audio). Aquest fitxer nomes declara les globals
+-- buides; `carregar_config()` les ompli al iniciar.
 
 -- ====================================================================
--- VALORS PER DEFECTE DE CONFIGURACIO (sobreescriuibles per config.lua)
+-- GLOBALS DE CONFIGURACIO (els ompli config.lua via carregar_config())
 -- ====================================================================
-skin = "custom"   -- "custom" | "native" (vore config.lua per descripcio)
+-- Declarats aci nomes per a documentar que existeixen. El valor real
+-- arriba sempre de config.lua. Si config.lua no defineix algun, el joc
+-- petara al usar-lo — millor que un default amagat darrere.
+skin       = nil
+keys       = nil
+textos     = nil
+temps      = nil
+musica     = nil
+music_on   = nil
+VIDES_INI  = nil
+LEVEL_INI  = nil
 
 -- Codis CP437 dels sprites del joc original (de TIPOS.PAS).
 -- Els usem com a IDs logics de tipus de cel·la (i coincideixen amb el
@@ -53,33 +65,6 @@ skin_data = nil
 glif      = {}
 colors    = {}
 
--- Tecles del joc — sobreescriuibles per config.lua.
--- Nota: KEY_ESCAPE no es pot usar perque el interpret ascii la captura
--- per a la seva consola de debug abans que Lua la veja.
-keys = {
-    up        = KEY_UP,
-    down      = KEY_DOWN,
-    left      = KEY_LEFT,
-    right     = KEY_RIGHT,
-    dig_left  = KEY_Z,
-    dig_right = KEY_X,
-    quit      = KEY_Q,    -- abandona la partida → game over
-}
-
--- Textos del joc — sobreescriuibles per config.lua (taula `textos`).
--- Tots en sentence case (Inicial Majuscula, resta minuscula).
-textos = {
-    title_press_play = "Prem l'espai per a jugar",
-    game_over        = "FI DE JOC",
-    new_record       = "Nou record !",
-    score_label      = "Punts",   -- HUD i pantalla de nou record
-    level_label      = "Nivell",
-    lives_label      = "Vides",
-    record_label     = "Record",
-    name_label       = "Nom:",
-    name_help        = "(A-Z)",
-}
-
 -- Estats (de TIPOS.PAS — son bitflags per a SelectEstat dels enemics)
 NORMAL   = 0
 PUJAR    = 0x01
@@ -97,27 +82,6 @@ NUM_MALOS  = 3
 TEMPS_IA   = 30   -- iteracions del malo entre canvis de direccio
 MALO_RATIO = 4    -- els malos van 1/4 del ritme del Pepe (com en RUNNER.PAS)
 NUM_FASES  = 10   -- mapes 1..10 (el 0 esta reservat per al titol)
--- VIDES_INI = nombre de reserves (convencio arcade: el HUD mostra reserves,
--- no compta la vida actual). 2 reserves = 3 vides totals (1 actual + 2).
--- L'original arrancava amb 0 (= 1 vida total).
-VIDES_INI  = 2
--- LEVEL_INI = fase per la que arranca la partida nova (1..NUM_FASES).
--- Util per a depuracio i per a saltar al mapa que vols provar.
-LEVEL_INI  = 1
-
--- Tots els temps i durations de les animacions del DX. Sobreescriuibles
--- per config.lua (en frames a 60 fps; 60 = 1 segon).
-temps = {
-    score_step          = 3,    -- frames per cada +1 del comptador animat (60/3 = 20 pts/s)
-    fade_frames         = 18,   -- duracio de cada fase del fade (out i in son simetrics)
-    mort_anim_frames    = 30,   -- duracio de l'animacio de mort (Pepe visible, 0.5 s)
-    respawn_delay_frames = 120, -- temps que Pepe queda invisible abans del respawn (2 s)
-    invuln_frames       = 180,  -- temps invulnerable despres del respawn (3 s)
-    escala_step_frames  = 6,    -- frames entre cada cel·la nova de l'escala lateral (0.1 s)
-    gameover_delay_frames    = 15,  -- espera al entrar a game over abans d'engegar el typewriter
-    typewriter_step_frames   = 8,   -- frames per cada lletra del typewriter de "FI DE JOC"
-    gameover_show_frames     = 120, -- frames que el text final queda visible abans de la transicio
-}
 
 -- Estats del joc (maquina d'estats global)
 ESTAT_TITLE     = "title"
@@ -128,7 +92,10 @@ ESTAT_ENTERNAME = "entername"
 -- Estat global
 mapa  = {}   -- mapa[x][y] = { tipo=, color=, temps= }
 level = 1
-pepe  = { x=19, y=23, dibuix=PEPE_C, vides=VIDES_INI, estat=NORMAL,
+-- pepe: la inicialitzacio real (vides=VIDES_INI, posicio inicial...) la
+-- fa inicialitzacio() despres de carregar config.lua. Aci nomes declarem
+-- el shape per a que existeixca durant title/gameover (no es pinta).
+pepe  = { x=19, y=23, dibuix=PEPE_C, vides=0, estat=NORMAL,
           mort_t=0, invuln_t=0 }
 malos = {}
 score = 0
@@ -142,15 +109,9 @@ estat_inici = 0
 enter_name_idx = 1
 fade = nil   -- nil = sense transicio; o { phase="out"|"in", t=0, on_mid=... }
 
--- Jingles per als estats no-jugables: una sola reproduccio per entrada al
+-- Id del jingle reproduit actualment (nil = silenci). Les melodies
--- estat (no es repeteixen en bucle). El motor d'ascii nomes te un canal
+-- (musica.title, musica.entername) i music_on viuen a config.lua.
--- d'audio, per aixo no posem musica in-game (les SFX la tallarien).
+music_actual = nil
-music_on = true   -- false desactiva tots els jingles (les SFX continuen)
-musica = {
-    title     = "l4o4cegfedcceg",
-    entername = "l2o5cegcegced",
-}
-music_actual = nil   -- id del jingle reproduit actualment (nil = silenci)
 
 -- Estat de l'animacio de l'escala lateral (apareix quan no queden diners).
 -- "idle"    → encara no s'ha disparat per a este mapa
@@ -1162,26 +1123,12 @@ function pintar_hud()
     print(r, flr((40 - strlen(r)) / 2), 28)
 end
 
--- Carrega config.lua si existeix. Si falta o te errors, queden els defaults.
+-- config.lua es l'unica fuent de verdat per a tot lo configurable
--- Despres del dofile, si l'usuari ha fet "colors = {bg=X}" en lloc d'assignar
+-- (skin, keys, textos, temps, vides, audio). El carreguem amb dofile
--- camp a camp, hi haura claus que falten. Fem un merge amb les defaults
+-- directe — si peta o falta una clau, millor un error visible ara que
--- guardades per a que no quede res a nil.
+-- un valor sorpresa enmig d'una partida.
 function carregar_config()
-    -- Accedim per nom (_G) per a que aço seguisca funcionant fins i tot si
+    dofile("config.lua")
-    -- l'usuari reasigna tota la taula en config.lua (ex: `colors = {bg=...}`
-    -- en lloc de mutar camps individuals).
-    local noms = { "keys", "textos", "temps" }
-    local saved = {}
-    for _, nom in ipairs(noms) do
-        saved[nom] = {}
-        for k, v in pairs(_G[nom]) do saved[nom][k] = v end
-    end
-    pcall(dofile, "config.lua")
-    for _, nom in ipairs(noms) do
-        for k, v in pairs(saved[nom]) do
-            if _G[nom][k] == nil then _G[nom][k] = v end
-        end
-    end
 end
 
 function init()