Merge branch 'feat/paint-layer'

Fase 6: pintat de tiles amb PaintLayer com a font única del pintat.
Cadena on_tile_entered → tile_painted → sarcs. Feedback visual per
jugador via player{1,2}_paint_tile al YAML del mapa.

CMakeLists.txt

@@ -93,6 +93,7 @@ set(APP_SOURCES
     source/game/map/map.cpp
     source/game/map/tilemap.cpp
     source/game/map/tilemap_writer.cpp
+    source/game/map/paint_layer.cpp
     # Mòdul editor (només activa contingut en Debug via `#ifdef _DEBUG`).
     # En Release el fitxer compila a un object buit i l'enllaçador no
     # arrossega cap símbol del joc final.

data/maps/pyramid.yaml

@@ -13,6 +13,14 @@ tileset: data/tilesets/tomb.gif
 tile_size: 16
 origin: [-8, 0]
 
+# Índex de tile amb què cada jugador deixa rastre en trepitjar un sòl
+# pintable. Un índex per jugador perquè a multijugador local el recorregut
+# es distingeix a simple vista. Provisional fins que l'art del pintat
+# estigui definit; canviar aquí l'índex és tot el que cal. Omet el camp
+# per desactivar el pintat per a aquest jugador.
+player1_paint_tile: 2
+player2_paint_tile: 2
+
 # Geometria lògica de la piràmide (separada del render visual del tileset).
 # La graella de sarcòfags, el pitch entre ells i les amplades dels murs
 # decideixen els límits del jugador i les seues caixes de col·lisió. Abans

docs/entities-system.md

@@ -276,10 +276,74 @@ Canvi a [CMakeLists.txt](../CMakeLists.txt): la còpia de `data/` al build era u
 
 - `Mummy::step` partit: `snapToPlayfieldEdge`, `collectDirectionPools`, `applyChoice` — per mantenir la complexitat cognitiva sota el llindar de clang-tidy (< 25).
 
-## 8. Estat global
+## 8. Fase 6 — Pintat de tiles (DONE)
 
-- **Andamiatge, integració, render animat, falsa perspectiva, moviment, animació direccional de momia**: DONE. El `pyramid.yaml` actual (4 torches, 20 sarcs, 1 door, 2 mummies) es carrega, anima, col·loca amb l'anchor correcte, col·lisiona segons caixa lògica, el z-order interleava per peus, i la momia gira visualment a cada intersecció.
-- **Pendents majors**: ENT-HAZ-01 (sistema de vides), ENT-DOOR-01 (transició d'escena), ENT-IA-02 (bias IA), PER-01 (perímetre amb blocked_predicate quan els sarcs siguin veïns).
+Introdueix la mecànica central: el jugador deixa rastre al terra en trepitjar-lo, i els sarcòfags compten tiles **pintats** (no tiles *trepitjats*). Font única de veritat del pintat: una nova capa `PaintLayer` escolta el moviment del Player, filtra pintabilitat i re-publica `tile_painted`, que és el que ara observen els sarcs.
+
+### Cadena d'events resultant
+
+```
+Player canvi de tile
+  → bus: on_tile_entered { col, row, paint_tile_index }
+  → PaintLayer: filtra Map::isPaintable + "primer pinta guanya"
+              → buffer ARGB + bus: tile_painted { col, row }
+  → EntityManager fan-out → Sarcophagus::notifyTilePainted
+  → perímetre complet → OPENING → OPEN → sarcophagus_opened
+  → tots oberts → Door::open
+```
+
+Dos events encadenats perquè el *pintat* no és la *presència*: es filtra per pintabilitat i per "ja pintat", i el re-publish garanteix que els sarcs no vegin falsos positius (p. ex. el jugador lliscant contra un mur, o un tile ja marcat per l'altre jugador).
+
+### Canvis per fitxer
+
+| Path | Canvi |
+|---|---|
+| [event_bus.hpp](../source/game/entities/event_bus.hpp) | Nou `struct PaintedTile { col, row, tile_index }` al `Payload` variant + overload `publish`. |
+| [map.hpp](../source/game/map/map.hpp) / [.cpp](../source/game/map/map.cpp) | `Map::isPaintable(col, row)` → `true` si el tile cau dins del playfield i no s'encavalca cap sarc. |
+| [map/paint_layer.hpp](../source/game/map/paint_layer.hpp) / [.cpp](../source/game/map/paint_layer.cpp) | Classe nova. Subscriu `on_tile_entered`, marca `painted_[row][col]`, blita el tile al buffer ARGB propi, publica `tile_painted`. `render()` anàleg a `Tilemap::render`. |
+| [player.hpp](../source/game/entities/player.hpp) / [.cpp](../source/game/entities/player.cpp) | Camp `paint_tile_index_` al ctor (default -1). El Player publica `PaintedTile` amb el seu índex en lloc de `TilePos`. |
+| [entity.hpp](../source/game/entities/entity.hpp) / [.cpp](../source/game/entities/entity.cpp) | Rename `notifyTileEntered` → `notifyTilePainted`. |
+| [concrete/sarcophagus.hpp](../source/game/entities/concrete/sarcophagus.hpp) / [.cpp](../source/game/entities/concrete/sarcophagus.cpp) | Mateix rename. La lògica del `visited_` és idèntica — només canvia qui li truca el hook. |
+| [entity_manager.hpp](../source/game/entities/entity_manager.hpp) / [.cpp](../source/game/entities/entity_manager.cpp) | La subscripció canvia d'`on_tile_entered` → `tile_painted`. Fan-out renombrat a `notifyPlayerTilePainted`. |
+| [game_scene.hpp](../source/game/scenes/game_scene.hpp) / [.cpp](../source/game/scenes/game_scene.cpp) | Membre `std::unique_ptr<PaintLayer> paint_layer_` (declarat després d'`entity_manager_` per garantir ordre invers de destrucció). Helper local `readOptionalInt` llegeix `player1_paint_tile` del YAML del mapa i el passa al Player. `render()` crida `paint_layer_->render()` entre `tilemap_.render()` i els actors; s'amaga al mode editor. |
+| [data/maps/pyramid.yaml](../data/maps/pyramid.yaml) | Camps nous `player1_paint_tile: 2` i `player2_paint_tile: 2` (índex provisional, canviable sense recompilar). |
+| [tests/test_entities_smoke.cpp](../tests/test_entities_smoke.cpp) | T9 adaptat: publica `tile_painted` directament al bus per aïllar el fan-out d'EntityManager de la resta de la cadena. |
+
+### Decisions de disseny
+
+- **Centralitzat vs per-sarc**: l'estat "pintat" viu al `PaintLayer`, no dins cada sarc. Els sarcs només apunten els tiles del seu perímetre que han estat notificats pintats. Aquesta separació deixa preparat per a items-en-sarc (obrir quan `N` items trobats, no quan tots oberts) i per a altres productors de pintat futurs (enemics, trampes).
+- **"Primer pinta guanya"**: `PaintLayer::tryPaint` retorna false si el tile ja està pintat. No se sobreescriu amb l'índex d'un altre jugador. Reduïm fonts de decisió inconsistent; el rastre visual és estable.
+- **Paint tile per jugador**: l'índex l'aporta el YAML del mapa (`player1_paint_tile`, `player2_paint_tile`), no el YAML del jugador. Raó: depèn del tileset del mapa — cada nivell pot oferir rastres diferents; canviar de mapa canvia l'índex vàlid.
+- **Render al mode editor**: desactivat. L'editor edita el tilemap base; la capa de pintat és d'estat de joc, no de dades del nivell. Quan `editor_.active()`, `SKIP_ACTORS=true` i el `paint_layer_->render()` se salta amb la resta d'actors.
+- **Resolució**: 16×16 reutilitzant `Map::tile_size` i l'origen del tilemap. El `PaintLayer` emmagatzema `tile_size_` com a camp propi per facilitar una eventual migració a 8×8 (graella 2× més fina) sense tocar la interfície.
+- **Persistència**: runtime only. No hi ha camp `painted:` al YAML. Entrar al `GameScene` reseteja el pintat.
+- **No cal `is_blocked` al `sarc->place(...)`** per a aquest nivell: l'`outer_corridor` del `pyramid.yaml` és exactament 1 tile, cosa que garanteix que el perímetre de qualsevol sarc (fins i tot els de cantonades) cau íntegrament dins del playfield i és pintable. Quedaria rellevant si el disseny futur posa sarcs sense passadís al voltant — cobert per PER-01.
+
+### Verificació
+
+- `make debug` net, sense warnings ni de clang-tidy ni de cppcheck als fitxers nous.
+- `./build/test_entities_smoke`: **ALL OK** (14/14). T9 adaptat (publica `tile_painted` en lloc d'`on_tile_entered`); la resta de tests del sistema d'entitats passen sense tocar.
+- `timeout 5 xvfb-run ./build/aee_2026`: arrenca, log `PaintLayer: 21x15 tiles (336x240 px), tileset data/tilesets/tomb.gif` després de `EntityManager: 27 entitats carregades`, surt amb `Bye!` sense crash.
+
+### Pendent derivat
+
+| ID | Descripció | Estat |
+|---|---|---|
+| PAINT-01 | **Tile de pintat definitiu** quan l'art estigui madur. Ara `2` provisional al `pyramid.yaml`. Canviar l'índex no demana recompilar. | DEFERRED |
+| PAINT-02 | **Resolució 8×8** si es vol més granularitat. El `PaintLayer` porta el seu propi `tile_size_`; cal propagar-lo al ctor per a no lligar-lo a `Tilemap::getTileSize()`. També cal decidir com es mapen els perímetres dels sarcs a sub-caselles. | DEFERRED |
+| PAINT-03 | **Smoke unit del `PaintLayer`**: "primer pinta guanya", filtre d'`isPaintable`, publicació de `tile_painted`. Ara la cadena està coberta end-to-end via T9 (fan-out del bus) i via l'smoke d'arrencada, però el filtre i la deduplicació no tenen test directe. | DEFERRED |
+| PAINT-04 | **Player 2 cablejat al `GameScene`**: la lectura del YAML i el ctor ja suporten un segon jugador amb `paint_tile_index_` propi; només cal instanciar-lo amb Controls distints (p. ex. WASD) i afegir-lo al vector. | DEFERRED |
+
+### Memòria durable afectada
+
+INF-02 queda parcialment cobert: el `PaintedTile` ja porta `tile_index` (per jugador), que és una forma d'identificar qui pinta sense haver de propagar un `player_id` explícit. Si en el futur cal saber *qui* (p. ex. per puntuació individual), caldrà afegir el camp; el canvi és local al struct.
+
+---
+
+## 9. Estat global
+
+- **Andamiatge, integració, render animat, falsa perspectiva, moviment, animació direccional de momia, pintat de tiles**: DONE. El `pyramid.yaml` actual (4 torches, 20 sarcs, 1 door, 2 mummies) es carrega, anima, col·loca amb l'anchor correcte, col·lisiona segons caixa lògica, el z-order interleava per peus, la momia gira visualment a cada intersecció, i el jugador deixa rastre al terra.
+- **Pendents majors**: ENT-HAZ-01 (sistema de vides), ENT-DOOR-01 (transició d'escena), ENT-IA-02 (bias IA), PER-01 (perímetre amb blocked_predicate quan els sarcs siguin veïns), PAINT-03 (test unit del PaintLayer), PAINT-04 (Player 2 cablejat).
 - **Smoke tests**: 14/14 passant; regla durable de cobrir amb smoke tota lògica no trivial respectada a totes les fases.
 
 El document és viu: cada tasca nova hauria d'afegir-s'hi (entrada amb ID, descripció, estat) al fer-la o ajornar-la.

source/game/entities/concrete/sarcophagus.cpp

@@ -112,7 +112,7 @@ void Sarcophagus::update(float delta_time) {
     }
 }
 
-void Sarcophagus::notifyTileEntered(int col, int row) {
+void Sarcophagus::notifyTilePainted(int col, int row) {
     if (state_ != State::CLOSED) { return; }
     const TileKey KEY{.col = col, .row = row};
     if (perimeter_tiles_.find(KEY) == perimeter_tiles_.end()) { return; }

source/game/entities/concrete/sarcophagus.hpp

@@ -42,7 +42,7 @@ class Sarcophagus : public Interactable {
     void place(int anchor_col, int anchor_row, const BlockedPredicate& is_blocked);
 
     void update(float delta_time) override;
-    void notifyTileEntered(int col, int row) override;
+    void notifyTilePainted(int col, int row) override;
 
     [[nodiscard]] auto getState() const -> State { return state_; }
     [[nodiscard]] auto getPerimeterSize() const -> std::size_t { return perimeter_tiles_.size(); }

source/game/entities/entity.cpp

@@ -23,7 +23,7 @@ void Entity::onPlayerContact(Player* /*player*/) {
     // No-op per defecte.
 }
 
-void Entity::notifyTileEntered(int /*col*/, int /*row*/) {
+void Entity::notifyTilePainted(int /*col*/, int /*row*/) {
     // No-op per defecte; només `Sarcophagus` l'usa.
 }
 

source/game/entities/entity.hpp

@@ -77,9 +77,10 @@ class Entity {
     virtual void onPlayerContact(Player* player);
 
     // Hook que el `EntityManager` invoca per a cada entitat cada vegada
-    // que el jugador entra en un tile nou. Només `Sarcophagus` ho consumeix
-    // (per marcar perímetre visitat); per defecte no-op.
-    virtual void notifyTileEntered(int col, int row);
+    // que un tile es pinta (via PaintLayer, com a conseqüència d'un
+    // jugador trepitjant un sòl pintable). Només `Sarcophagus` ho consumeix
+    // (per marcar perímetre); per defecte no-op.
+    virtual void notifyTilePainted(int col, int row);
 
     [[nodiscard]] auto getName() const -> const std::string& { return name_; }
     [[nodiscard]] auto getTilePos() const -> TilePos { return tile_; }

source/game/entities/entity_manager.cpp

@@ -24,12 +24,13 @@ EntityManager::EntityManager() {
         }
     });
 
-    // Subscripció al moviment del jugador: quan publica `on_tile_entered`
-    // amb payload `TilePos`, fem fan-out a totes les entitats perquè els
-    // sarcòfags puguin actualitzar el seu `visited_`.
-    tile_sub_id_ = bus_.subscribe("on_tile_entered", [this](const Event& ev) {
+    // Subscripció al pintat: el PaintLayer publica `tile_painted` amb
+    // payload `TilePos` un cop ha filtrat pintabilitat i aplicat la regla
+    // "primer que pinta guanya". Fem fan-out a totes les entitats perquè
+    // els sarcòfags puguin actualitzar el seu `visited_`.
+    tile_sub_id_ = bus_.subscribe("tile_painted", [this](const Event& ev) {
         const auto* tile = std::get_if<TilePos>(&ev.payload);
-        if (tile != nullptr) { notifyPlayerEnteredTile(tile->col, tile->row); }
+        if (tile != nullptr) { notifyPlayerTilePainted(tile->col, tile->row); }
     });
 }
 
@@ -66,8 +67,8 @@ void EntityManager::update(float delta_time) {
     for (auto& e : entities_) { e->update(delta_time); }
 }
 
-void EntityManager::notifyPlayerEnteredTile(int col, int row) {
-    for (auto& e : entities_) { e->notifyTileEntered(col, row); }
+void EntityManager::notifyPlayerTilePainted(int col, int row) {
+    for (auto& e : entities_) { e->notifyTilePainted(col, row); }
 }
 
 auto EntityManager::getEntities() const -> std::vector<Entity*> {

source/game/entities/entity_manager.hpp

@@ -17,9 +17,9 @@ class Player;
 //   2. `update(dt)` propaga el tick a totes.
 //   3. Comptador de sarcòfags oberts — quan iguala el total registrat,
 //      crida `door_->open()` automàticament.
-//   4. `notifyPlayerEnteredTile(col, row)` — fan-out del hook per a tots
+//   4. `notifyPlayerTilePainted(col, row)` — fan-out del hook per a tots
 //      els sarcòfags (i qualsevol entitat futura que s'hi subscrigui via
-//      `notifyTileEntered`).
+//      `notifyTilePainted`).
 //
 // NO és un singleton: es crea una instància per nivell. De moment no
 // s'usa encara al GameScene (andamiatge pur).
@@ -74,10 +74,11 @@ class EntityManager {
     // reflecteixi l'estat del frame actual.
     void checkPlayerCollisions(const std::vector<Player*>& players);
 
-    // Fan-out del hook de moviment de jugador: per a cada sarcòfag,
-    // cridar notifyTileEntered. Les entitats no-sarcòfag ho ignoren per
-    // defecte (veure Entity::notifyTileEntered).
-    void notifyPlayerEnteredTile(int col, int row);
+    // Fan-out del hook de pintat: per a cada sarcòfag, cridar
+    // notifyTilePainted. Les entitats no-sarcòfag ho ignoren per defecte
+    // (veure Entity::notifyTilePainted). Invocat com a reacció a
+    // `tile_painted` al bus (re-publicat pel PaintLayer un cop filtrat).
+    void notifyPlayerTilePainted(int col, int row);
 
     // Carrega els spawns d'un YAML de nivell i els afegeix al manager:
     //   1. Llegeix el bloc `entities:` via EntityLoader.

source/game/entities/event_bus.hpp

@@ -23,16 +23,27 @@ class Entity;
 // consumir events tipats amb `std::get_if`. Si apareixen més tipus de
 // payload, s'amplia aquí sense tocar cridants existents.
 
-// Tile (col, row) — payload de `on_tile_entered`. No és un `pair<int,int>`
-// per evitar alias ambigus al variant (dos ints sense nom).
+// Tile (col, row) — payload de `tile_painted` (i altres events de tile sense
+// metadada extra). No és un `pair<int,int>` per evitar alias ambigus al
+// variant (dos ints sense nom).
 struct TilePos {
     int col{0};
     int row{0};
 };
 
+// Tile pintat pel jugador — payload de `on_tile_entered`. Porta l'índex
+// de tile amb què el jugador pinta (cada Player pot pintar amb un tile
+// diferent, llegit del YAML del mapa). El PaintLayer filtra pintabilitat,
+// marca i re-publica `tile_painted` amb només la posició.
+struct PaintedTile {
+    int col{0};
+    int row{0};
+    int tile_index{-1};
+};
+
 struct Event {
     std::string name;
-    using Payload = std::variant<std::monostate, int, std::string, Entity*, TilePos>;
+    using Payload = std::variant<std::monostate, int, std::string, Entity*, TilePos, PaintedTile>;
     Payload payload;
 };
 
@@ -71,6 +82,9 @@ class EventBus {
     void publish(const std::string& name, TilePos tile) {
         publish(Event{.name = name, .payload = tile});
     }
+    void publish(const std::string& name, PaintedTile painted) {
+        publish(Event{.name = name, .payload = painted});
+    }
 
    private:
     struct Subscription {

source/game/entities/player.cpp

@@ -73,10 +73,11 @@ void Player::loadFrom(const std::string& yaml_path) {
     collision_y_offset = (sprite_h - base_size) - collision_padding;
 }
 
-Player::Player(const std::string& anim_key, float x, float y, const Controls& controls, const Map::Info& map_info)
+Player::Player(const std::string& anim_key, float x, float y, const Controls& controls, const Map::Info& map_info, int paint_tile_index)
     : AnimatedSprite(Resource::Cache::get().getAnimationData(anim_key)),
       controls_(controls),
-      map_(map_info) {
+      map_(map_info),
+      paint_tile_index_(paint_tile_index) {
     setPos(x, y);
     setCurrentAnimation("stand");
 }
@@ -161,15 +162,16 @@ void Player::update(float delta_time) {
 
     // Detecció de canvi de tile. Es calcula *després* del clamp i de les
     // col·lisions perquè la posició aquí ja és la definitiva del frame;
-    // així els sarcòfags no reben falsos positius mentre el Player rellisca
+    // així el PaintLayer no rep falsos positius mentre el Player rellisca
     // contra una paret. Si el tile ha canviat, publiquem `on_tile_entered`
-    // al bus; l'EntityManager farà fan-out a notifyTileEntered.
+    // al bus amb l'índex de pintat d'aquest jugador; el PaintLayer filtra
+    // pintabilitat i re-publica `tile_painted` als sarcòfags.
     if (bus_ != nullptr) {
         const auto [COL, ROW] = getCurrentTile();
         if (COL != last_tile_col_ || ROW != last_tile_row_) {
             last_tile_col_ = COL;
             last_tile_row_ = ROW;
-            bus_->publish("on_tile_entered", TilePos{.col = COL, .row = ROW});
+            bus_->publish("on_tile_entered", PaintedTile{.col = COL, .row = ROW, .tile_index = paint_tile_index_});
         }
     }
 }

source/game/entities/player.hpp

@@ -41,7 +41,7 @@ class Player : public AnimatedSprite {
     // Ha de cridar-se abans d'instanciar Player; GameScene ho fa al ctor.
     static void loadFrom(const std::string& yaml_path);
 
-    Player(const std::string& anim_key, float x, float y, const Controls& controls, const Map::Info& map_info);
+    Player(const std::string& anim_key, float x, float y, const Controls& controls, const Map::Info& map_info, int paint_tile_index = -1);
 
     void update(float delta_time) override;
 
@@ -54,7 +54,9 @@ class Player : public AnimatedSprite {
 
     // Injecta el bus del nivell. El Player publica `on_tile_entered` cada
     // vegada que el centre de la seua caixa de col·lisió entra en una
-    // cel·la nova del tilemap. Si el bus no s'injecta, no emet res.
+    // cel·la nova del tilemap, amb payload `PaintedTile{col,row,paint_tile_index_}`.
+    // El PaintLayer filtra pintabilitat i re-publica `tile_painted` a qui
+    // correspongui (sarcòfags). Si el bus no s'injecta, no emet res.
     void setEventBus(EventBus* bus) { bus_ = bus; }
 
     // Tile actual del jugador (centre de `baseBox()` convertit a
@@ -127,4 +129,10 @@ class Player : public AnimatedSprite {
     // el primer frame en què el bus estigui connectat ja emeti un event.
     int last_tile_col_{-9999};
     int last_tile_row_{-9999};
+
+    // Índex de tile del tileset amb què aquest jugador pinta. Llegit del
+    // YAML del mapa (`player1_paint_tile` / `player2_paint_tile`) i passat
+    // al ctor per GameScene. -1 desactiva el pintat (p.ex. al test
+    // d'arrencada o en un escenari que no vulgui feedback visual).
+    int paint_tile_index_{-1};
 };

source/game/map/map.cpp

@@ -106,6 +106,23 @@ namespace Map {
         return box.x >= static_cast<float>(playfield_x) && box.y >= static_cast<float>(playfield_y) && box.x + box.w <= static_cast<float>(playfield_x + playfield_w) && box.y + box.h <= static_cast<float>(playfield_y + playfield_h);
     }
 
+    auto isPaintable(int col, int row) -> bool {
+        // Construïm la caixa píxel del tile a partir de l'origen del tilemap.
+        // El grid és 16-alineat respecte a `tilemap_origin_*`; per a un tile
+        // (col,row) la cantonada superior-esquerra cau a:
+        //     x = tilemap_origin_x + col * tile_size
+        //     y = tilemap_origin_y + row * tile_size
+        const SDL_FRect BOX{
+            .x = static_cast<float>(tilemap_origin_x + (col * tile_size)),
+            .y = static_cast<float>(tilemap_origin_y + (row * tile_size)),
+            .w = static_cast<float>(tile_size),
+            .h = static_cast<float>(tile_size),
+        };
+        if (!insidePlayfield(BOX)) { return false; }
+        if (collides(BOX)) { return false; }
+        return true;
+    }
+
     auto makeInfo() -> Info {
         return {
             .playfield_x = playfield_x,

source/game/map/map.hpp

@@ -81,6 +81,12 @@ namespace Map {
     // entitats dinàmiques per validar posicions candidates del seu step.
     [[nodiscard]] auto insidePlayfield(const SDL_FRect& box) -> bool;
 
+    // true si el tile (col, row) — coordenades del tilemap, amb origen
+    // `tilemap_origin_*` — és "sòl transitable" i per tant pintable: cau
+    // completament dins del playfield i no s'encavalca cap sarcòfag. Ho
+    // usa el `PaintLayer` per filtrar quines cel·les accepten pintat.
+    [[nodiscard]] auto isPaintable(int col, int row) -> bool;
+
     // Snapshot plà de la geometria del mapa + punters a `collides` /
     // `insidePlayfield`. Pensat per ser passat per valor (POD petit,
     // trivialment copiable). Un cop construïda, llegeix els valors

source/game/map/paint_layer.cpp

@@ -0,0 +1,134 @@
+#include "game/map/paint_layer.hpp"
+
+#include <algorithm>
+#include <cstddef>
+#include <cstdint>
+#include <iostream>
+#include <variant>
+
+#include "core/rendering/screen.hpp"
+#include "core/rendering/surface.hpp"
+#include "core/resources/resource_cache.hpp"
+#include "game/map/map.hpp"
+#include "game/map/tilemap.hpp"
+
+namespace {
+
+    // Blit d'un tile del tileset sobre un buffer ARGB de destí, respectant
+    // l'índex transparent del GIF. Mateixa convenció que la versió a
+    // `tilemap.cpp`: el tileset guarda índexs + paleta, i la destinació
+    // és un buffer ARGB32 lineal. Duplicat intencionat per no acoblar
+    // Tilemap i PaintLayer; si en el futur un tercer consumidor el vol
+    // reutilitzar, es promou a un helper compartit.
+    void blitTile(const Surface& tileset, int tile_size, int src_col, int src_row, std::vector<std::uint32_t>& dest, int dest_w, int dest_x, int dest_y) {
+        const int SRC_X0 = src_col * tile_size;
+        const int SRC_Y0 = src_row * tile_size;
+        const auto TRANSPARENT = tileset.getTransparentColor();
+        for (int y = 0; y < tile_size; ++y) {
+            for (int x = 0; x < tile_size; ++x) {
+                const auto IDX = tileset.getPixel(SRC_X0 + x, SRC_Y0 + y);
+                if (IDX == TRANSPARENT) { continue; }
+                const auto ARGB = tileset.getPaletteColor(IDX);
+                const auto DST_OFFSET =
+                    (static_cast<std::size_t>(dest_y + y) * static_cast<std::size_t>(dest_w)) + static_cast<std::size_t>(dest_x + x);
+                dest[DST_OFFSET] = ARGB;
+            }
+        }
+    }
+
+}  // namespace
+
+PaintLayer::PaintLayer(const Tilemap& tilemap, EventBus* bus)
+    : bus_(bus),
+      cols_(tilemap.getCols()),
+      rows_(tilemap.getRows()),
+      tile_size_(tilemap.getTileSize()),
+      origin_x_(tilemap.getOriginX()),
+      origin_y_(tilemap.getOriginY()),
+      width_px_(tilemap.getWidth()),
+      height_px_(tilemap.getHeight()),
+      tileset_cols_(tilemap.getTilesetCols()),
+      tileset_path_(tilemap.getTilesetPath()) {
+    painted_.assign(static_cast<std::size_t>(rows_), std::vector<int>(static_cast<std::size_t>(cols_), -1));
+    pixels_.assign(
+        static_cast<std::size_t>(width_px_) * static_cast<std::size_t>(height_px_),
+        0U);
+
+    if (bus_ != nullptr) {
+        // Subscripció a `on_tile_entered`: el Player publica aquest event
+        // amb `PaintedTile{col, row, tile_index}`. Filtrem pintabilitat
+        // (sòl transitable) via `Map::isPaintable` i, si aplica, marquem
+        // i re-publiquem `tile_painted` amb només la posició.
+        on_tile_sub_ = bus_->subscribe("on_tile_entered", [this](const Event& ev) {
+            const auto* paint = std::get_if<PaintedTile>(&ev.payload);
+            if (paint != nullptr) { tryPaint(paint->col, paint->row, paint->tile_index); }
+        });
+    }
+
+    std::cout << "PaintLayer: " << cols_ << "x" << rows_ << " tiles ("
+              << width_px_ << "x" << height_px_ << " px), tileset "
+              << tileset_path_ << '\n';
+}
+
+PaintLayer::~PaintLayer() {
+    if (bus_ != nullptr && on_tile_sub_ != 0) { bus_->unsubscribe(on_tile_sub_); }
+}
+
+auto PaintLayer::isPainted(int col, int row) const -> bool {
+    if (col < 0 || col >= cols_ || row < 0 || row >= rows_) { return false; }
+    return painted_[static_cast<std::size_t>(row)][static_cast<std::size_t>(col)] >= 0;
+}
+
+auto PaintLayer::tryPaint(int col, int row, int tile_index) -> bool {
+    if (col < 0 || col >= cols_ || row < 0 || row >= rows_) { return false; }
+    if (tile_index < 0) { return false; }
+    if (painted_[static_cast<std::size_t>(row)][static_cast<std::size_t>(col)] >= 0) {
+        // Primer que pinta guanya: no sobreescrivim.
+        return false;
+    }
+    if (!Map::isPaintable(col, row)) { return false; }
+
+    painted_[static_cast<std::size_t>(row)][static_cast<std::size_t>(col)] = tile_index;
+    blitPaintTile(col, row, tile_index);
+
+    if (bus_ != nullptr) {
+        bus_->publish("tile_painted", TilePos{.col = col, .row = row});
+    }
+    return true;
+}
+
+void PaintLayer::blitPaintTile(int col, int row, int tile_index) {
+    const auto TILESET = Resource::Cache::get().getSurface(tileset_path_);
+    if (TILESET == nullptr) { return; }
+    const int DX = col * tile_size_;
+    const int DY = row * tile_size_;
+    const int SRC_COL = tile_index % tileset_cols_;
+    const int SRC_ROW = tile_index / tileset_cols_;
+    blitTile(*TILESET, tile_size_, SRC_COL, SRC_ROW, pixels_, width_px_, DX, DY);
+}
+
+void PaintLayer::render() const {
+    // Còpia ARGB al canvas, anàloga a `Tilemap::render`. Píxels amb
+    // alpha=0 (tiles no pintats) es salten per deixar visible el tilemap
+    // base per sota.
+    auto& screen = Screen::get();
+    auto* canvas = screen.getCanvasArgb();
+    const int CANVAS_W = screen.getCanvasWidth();
+    const int CANVAS_H = screen.getCanvasHeight();
+
+    const int Y_START = std::max(0, -origin_y_);
+    const int Y_END = std::min(height_px_, CANVAS_H - origin_y_);
+    const int X_START = std::max(0, -origin_x_);
+    const int X_END = std::min(width_px_, CANVAS_W - origin_x_);
+
+    constexpr std::uint32_t ALPHA_MASK = 0xFF000000U;
+    for (int y = Y_START; y < Y_END; ++y) {
+        const auto* src_row = &pixels_[static_cast<std::size_t>(y) * static_cast<std::size_t>(width_px_)];
+        auto* dst_row =
+            &canvas[(static_cast<std::size_t>(origin_y_ + y) * static_cast<std::size_t>(CANVAS_W)) + static_cast<std::size_t>(origin_x_)];
+        for (int x = X_START; x < X_END; ++x) {
+            const auto PIXEL = src_row[x];
+            if ((PIXEL & ALPHA_MASK) != 0U) { dst_row[x] = PIXEL; }
+        }
+    }
+}

source/game/map/paint_layer.hpp

@@ -0,0 +1,72 @@
+#pragma once
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include "game/entities/event_bus.hpp"
+
+class Tilemap;
+
+// Capa visual de "pintat" sobre el tilemap base. Quan el jugador (o
+// qualsevol altre actor futur) publica `on_tile_entered` amb payload
+// `PaintedTile{col, row, tile_index}`, el PaintLayer filtra per
+// `Map::isPaintable`, marca el tile i re-publica `tile_painted` amb
+// només `TilePos` — abstracció del "el tile s'ha pintat" independent de
+// qui ho ha fet. Els sarcòfags escolten aquest segon event per comptar
+// el seu perímetre.
+//
+// Font única de veritat del pintat: evita duplicar l'estat dins de cada
+// sarcòfag i permet que el render mostri l'efecte al instant.
+//
+// Geometria: hereta `tile_size`, origen i dimensions del Tilemap
+// (mateixa graella). Reutilitza el tileset del Tilemap per blitejar els
+// tiles pintats a un buffer ARGB propi, anàleg a `Tilemap::pixels_`.
+//
+// Política de repintat: el primer que pinta un tile guanya. Intents
+// posteriors (amb el mateix índex o un altre) no tenen efecte —
+// garanteix coherència visual i evita notificar dos cops al mateix sarc.
+class PaintLayer {
+   public:
+    PaintLayer(const Tilemap& tilemap, EventBus* bus);
+    ~PaintLayer();
+
+    PaintLayer(const PaintLayer&) = delete;
+    PaintLayer(PaintLayer&&) = delete;
+    auto operator=(const PaintLayer&) -> PaintLayer& = delete;
+    auto operator=(PaintLayer&&) -> PaintLayer& = delete;
+
+    // Còpia del buffer ARGB sobre el canvas del Screen, respectant alpha
+    // (píxels no pintats queden al buffer amb alpha=0 i no s'escriuen).
+    // Pensat per cridar entre `Tilemap::render()` i el bloc d'actors.
+    void render() const;
+
+    // Intent de pintat directe (exposat per a tests i actors que pinten
+    // sense passar pel bus). Retorna true si el tile és pintable i no
+    // estava ja pintat; en aquest cas, publica `tile_painted`.
+    auto tryPaint(int col, int row, int tile_index) -> bool;
+
+    [[nodiscard]] auto isPainted(int col, int row) const -> bool;
+
+   private:
+    void blitPaintTile(int col, int row, int tile_index);
+
+    EventBus* bus_{nullptr};
+    EventBus::SubId on_tile_sub_{0};
+
+    int cols_{0};
+    int rows_{0};
+    int tile_size_{0};
+    int origin_x_{0};
+    int origin_y_{0};
+    int width_px_{0};
+    int height_px_{0};
+    int tileset_cols_{0};
+    std::string tileset_path_;
+
+    // `-1` = no pintat. Altres valors = índex de tile del tileset usat
+    // per pintar. No cal per al render (el buffer `pixels_` ja el conté),
+    // però facilita consultes ràpides d'estat i futures extensions.
+    std::vector<std::vector<int>> painted_;
+    std::vector<std::uint32_t> pixels_;
+};

source/game/scenes/game_scene.cpp

@@ -21,7 +21,9 @@
 #include "core/rendering/screen.hpp"
 #include "core/rendering/text.hpp"
 #include "core/resources/resource_cache.hpp"
+#include "core/resources/resource_helper.hpp"
 #include "core/system/event_buffer.hpp"
+#include "external/fkyaml_node.hpp"
 #include "game/entities/entity.hpp"
 #include "game/entities/event_bus.hpp"
 #include "game/entities/player.hpp"
@@ -42,6 +44,21 @@ namespace {
         return Tilemap(yaml_path);
     }
 
+    // Llegeix un camp sencer opcional del YAML del mapa. Si no hi és,
+    // retorna `fallback` (per defecte -1, que al Player indica "no pinta").
+    // S'usa per `player1_paint_tile` i `player2_paint_tile`: cada jugador
+    // pinta amb l'índex declarat al mapa, i un mapa sense aquests camps
+    // simplement no deixa rastre visual.
+    auto readOptionalInt(const std::string& yaml_path, const std::string& key, int fallback = -1) -> int {
+        auto bytes = Resource::Helper::loadFile(yaml_path);
+        if (bytes.empty()) { return fallback; }
+        const auto* begin = reinterpret_cast<const char*>(bytes.data());
+        const auto* end = begin + bytes.size();
+        auto yaml = fkyaml::node::deserialize(begin, end);
+        if (!yaml.contains(key)) { return fallback; }
+        return yaml[key].get_value<int>();
+    }
+
 }  // namespace
 
 auto GameScene::defaultConfig() -> Config {
@@ -103,10 +120,23 @@ GameScene::GameScene(Config config)
         static_cast<float>(Map::playfield_y) + (static_cast<float>(Map::outer_corridor) / 2.0F);
     const auto SPAWN_X = CORRIDOR_CENTER_X - (static_cast<float>(Player::sprite_w) / 2.0F);
     const auto SPAWN_Y = CORRIDOR_CENTER_Y - static_cast<float>(Player::collision_y_offset) - (static_cast<float>(Player::collision_size) / 2.0F);
-    players_.emplace_back(std::make_unique<Player>(ANIM_KEY, SPAWN_X, SPAWN_Y, CONTROLS_P1, Map::makeInfo()));
+    // Índex de tile amb què pinta cada jugador — llegit del YAML del mapa
+    // (camps opcionals `player1_paint_tile` / `player2_paint_tile`). Si no
+    // hi són, `paint_tile_index_ = -1` i el Player no deixa rastre.
+    const int P1_PAINT = readOptionalInt(config_.map_yaml, "player1_paint_tile", -1);
+    players_.emplace_back(std::make_unique<Player>(ANIM_KEY, SPAWN_X, SPAWN_Y, CONTROLS_P1, Map::makeInfo(), P1_PAINT));
 
-    // Connectem el Player al bus perquè emeti `on_tile_entered` i els
-    // sarcòfags rebin les notificacions de pas per tile.
+    // PaintLayer: font única del pintat del nivell. Es crea després de
+    // `loadFromLevel` perquè l'EntityManager ja ha de tenir els sarcòfags
+    // registrats (tot i que el sarc escolta via fan-out, no directament
+    // al bus; l'ordre de subscripcions aquí és irrellevant per la
+    // correcció, però sí pel log d'arrencada). Connectat al bus del
+    // manager per subscriure's a `on_tile_entered` i publicar `tile_painted`.
+    paint_layer_ = std::make_unique<PaintLayer>(tilemap_, &entity_manager_.getBus());
+
+    // Connectem el Player al bus perquè emeti `on_tile_entered` i el
+    // PaintLayer (subscrit ja) processe el pintat; el fan-out cap als
+    // sarcòfags passa per `tile_painted`.
     players_.back()->setEventBus(&entity_manager_.getBus());
 
     // Música de fons en bucle infinit. El track ja està al Resource::Cache
@@ -228,6 +258,10 @@ void GameScene::render() {
 #else
     constexpr bool SKIP_ACTORS = false;
 #endif
+    // Capa de pintat: va entre el tilemap base i els actors, perquè els
+    // sarcòfags i el jugador la tapen. S'amaga al mode editor (decisió
+    // explícita: l'editor edita el tilemap, no la capa de pintat).
+    if (!SKIP_ACTORS && paint_layer_) { paint_layer_->render(); }
     if (!SKIP_ACTORS) {
         // Z-order interleaving entitats ↔ players per `getFeetY()` ascendent:
         // els actors amb els peus més amunt queden dibuixats primer (al fons),

source/game/scenes/game_scene.hpp

@@ -6,6 +6,7 @@
 
 #include "core/scene/scene.hpp"
 #include "game/entities/entity_manager.hpp"
+#include "game/map/paint_layer.hpp"
 #include "game/map/tilemap.hpp"
 
 #ifdef _DEBUG
@@ -53,6 +54,15 @@ class GameScene : public Scene {
     // té els seus propis Controls i entra al vector amb una crida extra.
     std::vector<std::unique_ptr<Player>> players_;
 
+    // Capa de "pintat" del terra. Escolta `on_tile_entered` al bus,
+    // filtra pintabilitat (sòl transitable) i re-publica `tile_painted`
+    // per als sarcòfags. `unique_ptr` per controlar l'ordre de
+    // construcció/destrucció: es crea al ctor un cop `entity_manager_` i
+    // `tilemap_` estan llestos, i es destrueix abans que `entity_manager_`
+    // (on viu el bus al qual està subscrit). Declarat després d'aquests
+    // dos membres per garantir l'ordre invers a la destrucció.
+    std::unique_ptr<PaintLayer> paint_layer_;
+
     // Pausa de gameplay. Quan `paused_` és true, l'update de jugadors i
     // entitats es salta (el món es congela); l'input d'UI (GlobalInputs,
     // Notifier, RenderInfo) continua per no perdre hotkeys ni l'overlay de

tests/test_entities_smoke.cpp

@@ -4,7 +4,7 @@
 //   T1 factory — tots els tipus es registren i es creen.
 //   T2 loader  — llegeix `data/maps/test_entities.yaml` i retorna els spawns.
 //   T3 event bus — subscribe + publish + payload (entity*, int).
-//   T4 sarcòfag — perímetre computat correctament; notifyTileEntered
+//   T4 sarcòfag — perímetre computat correctament; notifyTilePainted
 //                 passa a OPENING quan es visiten tots els tiles.
 //   T5 manager — 2 sarcs + 1 door: forçant l'obertura dels sarcs, la porta
 //                s'obri sola; contactar la porta OPEN emet `level_complete`.
@@ -138,14 +138,14 @@ namespace {
         REQUIRE(sarc->getState() == Sarcophagus::State::CLOSED);
 
         // Visitem un tile que NO és al perímetre: res canvia.
-        sarc->notifyTileEntered(5, 5);
+        sarc->notifyTilePainted(5, 5);
         REQUIRE(sarc->getVisitedCount() == 0);
 
         // Visitem tots els del perímetre.
         const std::vector<std::pair<int, int>> PERIM = {
             {1, 0}, {2, 0}, {3, 0}, {1, 2}, {2, 2}, {3, 2}, {0, 1}, {4, 1},
         };
-        for (const auto& [c, r] : PERIM) { sarc->notifyTileEntered(c, r); }
+        for (const auto& [c, r] : PERIM) { sarc->notifyTilePainted(c, r); }
         REQUIRE(sarc->getVisitedCount() == 8);
         REQUIRE(sarc->getState() == Sarcophagus::State::OPENING);
 
@@ -186,12 +186,12 @@ namespace {
             const int W = s->getTileWidth();
             const int H = s->getTileHeight();
             for (int dc = 0; dc < W; ++dc) {
-                s->notifyTileEntered(COL0 + dc, ROW0 - 1);
-                s->notifyTileEntered(COL0 + dc, ROW0 + H);
+                s->notifyTilePainted(COL0 + dc, ROW0 - 1);
+                s->notifyTilePainted(COL0 + dc, ROW0 + H);
             }
             for (int dr = 0; dr < H; ++dr) {
-                s->notifyTileEntered(COL0 - 1, ROW0 + dr);
-                s->notifyTileEntered(COL0 + W, ROW0 + dr);
+                s->notifyTilePainted(COL0 - 1, ROW0 + dr);
+                s->notifyTilePainted(COL0 + W, ROW0 + dr);
             }
         };
         forceOpen(s1);
@@ -310,7 +310,9 @@ namespace {
         REQUIRE(ANCHOR_ROW == 4);
 
         // 4) Fan-out del bus: un sarcòfag ancorat a (3,4) mida 3×1 rep via
-        //    on_tile_entered una visita sobre el seu perímetre → state canvia.
+        //    tile_painted una notificació sobre cada tile del seu perímetre
+        //    → state canvia. Publiquem directament `tile_painted` (sense
+        //    passar pel PaintLayer) per aïllar el fan-out de l'EntityManager.
         EntityManager manager;
         auto sarc = std::make_unique<Sarcophagus>(EntityLoader::loadTemplate("sarcophagus"));
         sarc->place(3, 4, {});
@@ -323,7 +325,7 @@ namespace {
             {2, 4}, {6, 4},
         };
         for (const auto& [c, r] : PERIM) {
-            manager.getBus().publish("on_tile_entered", TilePos{.col = c, .row = r});
+            manager.getBus().publish("tile_painted", TilePos{.col = c, .row = r});
         }
         REQUIRE(sarc_raw->getState() == Sarcophagus::State::OPENING);
     }