docs(player): neteja comentaris dels YAMLs (sense documentar el motor)

data/player/sam.yaml

@@ -1,42 +1,20 @@
-# player animation
 sprite:
   path: sam.gif
   size: [16, 32]
 
-# Geometria de col·lisió del jugador (independent de l'animació):
-#   size      → costat del quadrat de col·lisió (16×16)
-#   base_size → costat del quadrat visual inferior del sprite (els "peus");
-#               s'usa per centrar la caixa de col·lisió sobre ell.
+# Geometria de col·lisió. `size` és la caixa contra murs/sarcs;
+# `hit_size`, la caixa contra altres actors (més petita); `height`,
+# l'alçada que un salt ha de superar per passar per damunt.
 collision:
   size: 16
   base_size: 16
-  # Caixa de contacte actor-actor (jugador↔jugador, jugador↔momia/trampa).
-  # Més petita que `size` perquè els contactes d'acció siguin precisos;
-  # `size` es reserva per a la col·lisió amb murs/sarcòfags i per enfilar
-  # els passadissos. Centrada en el mateix punt que la caixa base.
   hit_size: 8
-  # Alçada del cos en píxels. Funció DOBLE segons amb què col·lisione:
-  #   · Contra entitats (mummy, rolling_rock, sarc): si `jump_z > height`
-  #     d'aquella entitat, no hi ha col·lisió. Igual que als YAMLs
-  #     d'entitats.
-  #   · Contra altres jugadors: la col·lisió és binària per estat aeri.
-  #     Si un està en l'aire i l'altre no → cap col·lisió. Si tots dos
-  #     estan en l'aire, llavors `body_height` decideix si els rangs
-  #     verticals solapen i s'aplica el rebot mid-aire. `0` = sense cos
-  #     (ni rebot quan tots dos volen).
   height: 12
 
-# Animacions en mapa (clau = nom). Camps per animació:
-#   frames    → llista d'índexs dins de l'spritesheet.
-#   frame_ms  → durada de cada frame en ms. Escalar = uniforme; llista =
-#               per-frame (mateixa mida que `frames`).
-#   loop      → true per defecte. `loop: false` = un sol tret (es queda al
-#               darrer frame i `animationIsCompleted()` passa a true).
-#   loop_from → rebota a aquest índex en passar del final (implica loop).
 animations:
-  stand_down: { frames: [1] }
-  stand_up:   { frames: [5] }
-  stand:      { frames: [9] }
+  stand_down: { frames: [0] }
+  stand_up:   { frames: [4] }
+  stand:      { frames: [8] }
   jump_down:  { frames: [12] }
   jump_up:    { frames: [13] }
   jump:       { frames: [14] }
@@ -68,12 +46,8 @@ animations:
     frames: [8, 9, 10, 11]
     frame_ms: 100
 
-  # Animacions del braç llançant el látigo. Placeholder: reaprofiten els
-  # frames de `walk_*` perquè els sprites reals encara no existeixen
-  # (TODO: dibuixar-ne d'específics quan arribe l'art). El sprite del
-  # látigo viu al `WhipAttack` i es renderitza superposat per z-order.
   attack_down:
-    frames: [28, 29, 30, 31]
+    frames: [20, 21, 22, 23]
     frame_ms: 50
 
   attack_up:
@@ -81,63 +55,37 @@ animations:
     frame_ms: 50
 
   attack:
-    frames: [20, 21, 22, 23]
+    frames: [28, 29, 30, 31]
     frame_ms: 50
 
-  # Animacions de cooldown post-swing (recovery): mentre dura
-  # `whip_cooldown_ms` el jugador continua bloquejat però l'animació ja
-  # no és la d'atac. Placeholder: reaprofiten els frames de `stand_*`
-  # (la silueta no canvia respecte d'ells); quan arriben els frames
-  # reals només cal canviar els índexs ací, sense tocar el codi.
   recover_down:
-    frames: [1]
+    frames: [23]
 
   recover_up:
-    frames: [5]
+    frames: [27]
 
   recover:
-    frames: [9]
+    frames: [31]
 
-# Inèrcia només de frenada. L'acceleració és sempre instantània (soltar
-# el teclat + prémer una direcció = velocitat plena); en canvi, quan es
-# solta la direcció el jugador decau linealment a 0 en `brake_time_ms`.
-# El `threshold_ms` filtra els tocs curts: si el temps acumulat de
-# moviment continu no ha arribat al llindar, la parada és instantània
-# (permet "passets" d'un tile sense rellisquera). L'acumulador es
-# reseteja només quan no hi ha ni input ni velocitat residual, així
-# els canvis de direcció enmig del coast no rearmen el llindar.
-# `brake_time_ms: 0` o absència del bloc = inèrcia desactivada.
+# Inèrcia de frenada en soltar la direcció. `threshold_ms` filtra
+# tocs curts (passets d'un tile sense rellisquera).
 inertia:
   brake_time_ms: 150
   threshold_ms: 300
 
-# Gir de 180°: mentre dura, el facing queda fixat a la direcció
-# intermèdia (efecte purament visual; el moviment continua sense
-# alterar-se). Els girs de 90° no passen per cap intermedi.
+# Gir de 180°: durant `duration_ms` el facing es fixa a la direcció
+# intermèdia indicada (purament visual).
 turn:
   duration_ms: 80
-  # Direcció intermèdia per a cada gir de 180° (sentit horari).
   transitions:
-    west_to_east: down     # passa per baix  (stand_down)
-    east_to_west: up       # passa per dalt  (stand_up)
-    north_to_south: east   # passa per la dreta  (stand, sense flip)
-    south_to_north: west   # passa per l'esquerra (stand, amb flip)
+    west_to_east: down
+    east_to_west: up
+    north_to_south: east
+    south_to_north: west
 
-# Salt vertical (px verticals "visuals", no afecta la posició al món).
-#   impulse           → velocitat vertical inicial (px/s) en deixar el sòl.
-#   gravity           → acceleració descendent constant (px/s²).
-#   landing_stun_ms   → temps en què el jugador queda paralitzat en aterrar
-#                       (no es pot moure ni tornar a saltar).
-#   shadow_y_offset   → desplaçament vertical de la sombra (px, positiu =
-#                       puja). Compensa la franja transparent que els
-#                       sprites del jugador tenen sota els peus reals
-#                       perquè camine "pel mig del passadís" (3 px aquí).
-#   sound             → fitxer .wav reproduït al despegue (relatiu a
-#                       data/sounds/). Buit o absent = sense so.
-#   land_sound        → fitxer .wav reproduït en aterrar.
-# L'alçada del cos viu al bloc `collision:` (`height`), igual que la resta
-# d'entitats: és una propietat de col·lisió, no de la física del salt.
-# Amb impulse=240 i gravity=600: pic ≈ 48 px, temps total en l'aire ≈ 0.8 s.
+# Salt vertical (px de z, no toca la posició al món).
+# `shadow_y_offset`: puja la sombra per compensar la franja
+# transparent sota els peus del sprite.
 jump:
   impulse: 200
   gravity: 600
@@ -146,26 +94,16 @@ jump:
   sound: jump.wav
   land_sound: land.wav
 
-# Estat HURT: el jugador queda projectat sense control per un impacte
-# (algú que cau al damunt; en el futur també fuetada de l'altre jugador).
-# `enterHurt` tria automàticament la direcció amb més recorregut lliure
-# entre els 4 cardinals, posa la velocitat inicial a `speed` i la fa
-# decaure linealment fins a 0 en `brake_time_ms`. Si pel camí xoca amb
-# un mur, para en sec. En tornar a velocitat 0, recupera l'estat
-# GROUNDED i el control. Mentre dura, no col·lisiona amb altres jugadors.
-# Amb speed=120 i brake_time=500ms ⇒ recorregut ≈ 30 px (≈2 tiles).
+# Projecció post-impacte: surt cap a la direcció amb més recorregut
+# lliure i frena fins a 0 en `brake_time_ms`.
 hurt:
   speed: 120
   brake_time_ms: 500
   sound: hurt.wav
 
-# Configuració del látigo. `range_tiles` és la longitud de la hitbox
-# abans de retallar contra murs/sarcs (3 tiles ≈ 48 px). `swing_ms` és
-# la durada de l'animació de l'atac, durant la qual la hitbox del whip
-# està viva. `cooldown_ms` allarga ATTACKING amb una recuperació en què
-# el jugador segueix bloquejat però la hitbox ja ha desaparegut: castiga
-# l'ús abusiu del látigo. `damage` queda llegit per a futur (els
-# objectius reben `enterHurt` directament; cap entitat té HP encara).
+# Atac amb làtigo. `range_tiles` és la longitud abans de retallar
+# contra murs/sarcs; `cooldown_ms` allarga ATTACKING amb una
+# recuperació en què la hitbox ja no fa dany.
 whip:
   range_tiles: 3
   swing_ms: 200