feat(effects): polvet transitori al despegue i a l'aterratge

source/game/entities/concrete/dust.cpp

@@ -0,0 +1,57 @@
+#include "game/entities/concrete/dust.hpp"
+
+#include <string>
+#include <vector>
+
+#include "game/entities/entity_factory.hpp"
+
+namespace {
+
+    // Llig una animació opcional del bloc `animations` del YAML, amb
+    // valors per defecte segurs (1 frame, fps=1, sense loop). Si la
+    // clau no existeix, retornem una animació "ja completada" — així,
+    // un Dust spawnejat amb una variant inexistent al YAML mor al
+    // pròxim frame sense petar.
+    auto buildAnim(const fkyaml::node& yaml, const std::string& key) -> AnimationComponent {
+        std::vector<int> frames = {0};
+        float fps = 1.0F;
+        bool loop = false;
+        if (yaml.contains("animations") && yaml["animations"].contains(key)) {
+            const auto& anim = yaml["animations"][key];
+            if (anim.contains("frames")) {
+                frames.clear();
+                for (const auto& f : anim["frames"]) {
+                    // cppcheck-suppress useStlAlgorithm
+                    frames.push_back(f.get_value<int>());
+                }
+                if (frames.empty()) { frames.push_back(0); }
+            }
+            if (anim.contains("fps")) { fps = anim["fps"].get_value<float>(); }
+            if (anim.contains("loop")) { loop = anim["loop"].get_value<bool>(); }
+        }
+        return {frames, fps, loop};
+    }
+
+}  // namespace
+
+Dust::Dust(const fkyaml::node& yaml)
+    : anim_jump_(buildAnim(yaml, "jump")),
+      anim_land_(buildAnim(yaml, "land")) {
+    name_ = yaml.contains("name") ? yaml["name"].get_value<std::string>() : std::string("dust");
+    collides_ = false;
+    interactable_ = false;
+    // Per defecte JUMP; el spawner pot canviar-la abans del primer tick.
+    anim_ = anim_jump_;
+}
+
+void Dust::setVariant(Variant v) {
+    anim_ = (v == Variant::JUMP) ? anim_jump_ : anim_land_;
+    if (anim_.has_value()) { anim_->reset(); }
+}
+
+void Dust::update(float delta_time) {
+    Entity::update(delta_time);
+    if (anim_.has_value() && anim_->completed()) { markDead(); }
+}
+
+REGISTER_ENTITY("dust", Dust)

source/game/entities/concrete/dust.hpp

@@ -0,0 +1,36 @@
+#pragma once
+
+#include <cstdint>
+
+#include "external/fkyaml_node.hpp"
+#include "game/entities/animation_component.hpp"
+#include "game/entities/entity.hpp"
+
+// Polvet transitori: efecte purament visual que viu una animació i
+// s'autoelimina (`markDead`) quan acaba. Spawneja el `GameScene` com a
+// reacció a events `player_jumped` i `player_landed` del bus. Les dues
+// variants (despegue / aterratge) viuen al mateix YAML amb dues
+// animacions distintes (`jump` i `land`); l'instància tria una via
+// `setVariant` just després de construir-se.
+class Dust : public Entity {
+   public:
+    enum class Variant : std::uint8_t {
+        JUMP,
+        LAND,
+    };
+
+    explicit Dust(const fkyaml::node& yaml);
+
+    // Tria quina animació es reproduirà. Cal cridar-lo abans del primer
+    // `update`; per defecte la variant és JUMP.
+    void setVariant(Variant v);
+
+    // Tickeja l'animació activa. Quan arriba a `completed()`, marquem
+    // l'entitat morta perquè l'`EntityManager` la purgue al final del
+    // frame.
+    void update(float delta_time) override;
+
+   private:
+    AnimationComponent anim_jump_;
+    AnimationComponent anim_land_;
+};

source/game/entities/entity.hpp

@@ -88,6 +88,14 @@ class Entity {
     [[nodiscard]] auto collides() const -> bool { return collides_; }
     [[nodiscard]] auto interactable() const -> bool { return interactable_; }
 
+    // Marca per a entitats transitòries: efectes (polvet, espurnes,
+    // explosions...) que viuen una sola animació i s'autoeliminen quan
+    // acaba. L'`EntityManager` purga totes les entitats amb `dead_=true`
+    // al final de cada `update`. Les entitats persistents (sarcs, momies,
+    // portes, jugadors) mai no la posen i hi viuen sempre.
+    [[nodiscard]] auto isDead() const -> bool { return dead_; }
+    void markDead() { dead_ = true; }
+
     // Associar el bus una sola vegada (propietat externa, p.ex.
     // `EntityManager`). Entitats que no publiquen events (Torch, trampes
     // estàtiques de moment) el poden ignorar.
@@ -162,6 +170,7 @@ class Entity {
     bool collides_{false};
     bool interactable_{false};
     int height_{0};
+    bool dead_{false};
     SDL_FlipMode flip_{SDL_FLIP_NONE};
     EventBus* bus_{nullptr};
 };

source/game/entities/entity_manager.cpp

@@ -64,7 +64,16 @@ auto EntityManager::addSarcophagus(std::unique_ptr<Sarcophagus> sarc) -> Sarcoph
 }
 
 void EntityManager::update(float delta_time) {
+    // ATENCIÓ: si en el futur una entitat publica al bus events que
+    // resulten en `entity_manager_.add()` (push_back a `entities_`), açò
+    // invalidaria l'iterador de la ranged-for. Avui no passa: els spawns
+    // runtime venen de fora del cicle d'`update` (p.ex. el polvet del
+    // saltador es spawneja durant `Player::tick`, abans d'aquest mètode).
     for (auto& e : entities_) { e->update(delta_time); }
+    // Purga d'entitats marcades mortes aquest frame (efectes acabats,
+    // p.ex. polvet d'aterratge). Les persistents (sarcs, momies, etc.)
+    // mai no es marquen.
+    std::erase_if(entities_, [](const auto& e) { return e->isDead(); });
 }
 
 void EntityManager::notifyPlayerTilePainted(int col, int row) {

source/game/entities/event_bus.hpp

@@ -41,9 +41,17 @@ struct PaintedTile {
     int tile_index{-1};
 };
 
+// Coordenades en píxels al canvas. Payload genèric per a events que
+// volen indicar "una cosa ha passat aquí" — actualment `player_jumped`
+// i `player_landed`, que el GameScene escolta per spawnejar polvet.
+struct WorldPos {
+    float x{0.0F};
+    float y{0.0F};
+};
+
 struct Event {
     std::string name;
-    using Payload = std::variant<std::monostate, int, std::string, Entity*, TilePos, PaintedTile>;
+    using Payload = std::variant<std::monostate, int, std::string, Entity*, TilePos, PaintedTile, WorldPos>;
     Payload payload;
     // Jugador que ha originat (o provocat) l'event. -1 = sense jugador
     // associat (events del món, com `sarcophagus_opened` des de la pròpia
@@ -90,6 +98,9 @@ class EventBus {
     void publish(const std::string& name, PaintedTile painted) {
         publish(Event{.name = name, .payload = painted});
     }
+    void publish(const std::string& name, WorldPos pos) {
+        publish(Event{.name = name, .payload = pos});
+    }
 
    private:
     struct Subscription {

source/game/entities/player.cpp

@@ -579,6 +579,15 @@ void Player::startJump() {
     if (!jump_config.sound_key.empty() && Audio::get() != nullptr) {
         Audio::get()->playSound(jump_config.sound_key, Audio::Group::GAME);
     }
+    // Avisem al bus perquè el GameScene puga spawnejar el polvet de
+    // despegue al peu del jugador.
+    if (bus_ != nullptr) {
+        bus_->publish(Event{
+            .name = "player_jumped",
+            .payload = WorldPos{.x = getPosX() + (static_cast<float>(sprite_w) * 0.5F), .y = getGroundFeetY()},
+            .player_id = id_,
+        });
+    }
     // Prou: la velocitat horitzontal del salt és la `intended_v*` actual
     // (input del frame). El facing també queda com està. Ja no es
     // tocaran fins a aterrar.
@@ -676,6 +685,13 @@ auto Player::integrateJump(float delta_time) -> bool {
         if (!jump_config.land_sound_key.empty() && Audio::get() != nullptr) {
             Audio::get()->playSound(jump_config.land_sound_key, Audio::Group::GAME);
         }
+        if (bus_ != nullptr) {
+            bus_->publish(Event{
+                .name = "player_landed",
+                .payload = WorldPos{.x = getPosX() + (static_cast<float>(sprite_w) * 0.5F), .y = getGroundFeetY()},
+                .player_id = id_,
+            });
+        }
         return true;
     }
     return false;