scenes: infraestructura de la capa scenes:: (scene, timeline, sprite mover, frame animator, palette fade, surface handle, registry)

source/scenes/frame_animator.hpp

@@ -0,0 +1,34 @@
+#pragma once
+
+namespace scenes {
+
+// Cicla per un conjunt de frames numerats (0..num_frames-1) avançant un
+// frame cada `frame_ms` mil·lisegons. No carrega ni dibuixa cap sprite —
+// només el caller sap quins frames dibuixar a partir de `frame()`.
+//
+// Usat per animacions periòdiques amb frames subsamplejats: palmeres,
+// camell, aigua, torxes, Sam caminant amb `(i/5) % fr` del codi original.
+class FrameAnimator {
+   public:
+    FrameAnimator() = default;
+    FrameAnimator(int num_frames, int frame_ms, bool loop = true);
+
+    void tick(int delta_ms);
+
+    int frame() const { return current_frame_; }
+    bool done() const { return !loop_ && finished_; }
+    int numFrames() const { return num_frames_; }
+
+    void reset();
+    void setFrameMs(int frame_ms) { frame_ms_ = frame_ms; }
+
+   private:
+    int num_frames_{1};
+    int frame_ms_{100};
+    bool loop_{true};
+    int current_frame_{0};
+    int elapsed_ms_{0};
+    bool finished_{false};
+};
+
+}  // namespace scenes