Extra2D/include/utils/timer_module.h

#pragma once

#include <functional>
#include <memory>
#include <module/module.h>
#include <module/module_registry.h>
#include <types/base/types.h>
#include <unordered_map>
#include <vector>

namespace extra2d {

/**
 * @brief 定时器句柄
 */
using TimerId = uint32;
constexpr TimerId INVALID_TIMER_ID = 0;

/**
 * @brief 定时器回调类型
 */
using TimerCallback = std::function<void()>;
using TimerUpdateCallback = std::function<void(float)>;

/**
 * @brief 定时器信息
 */
struct TimerInfo {
  TimerId id = INVALID_TIMER_ID;
  float interval = 0.0f;              // 间隔时间（秒）
  float elapsed = 0.0f;               // 已过去的时间
  uint32 repeat = 0;                  // 重复次数（0表示无限）
  uint32 executed = 0;                // 已执行次数
  bool paused = false;                // 是否暂停
  bool cancelled = false;             // 是否取消
  TimerCallback callback;             // 回调函数
  TimerUpdateCallback updateCallback; // 带dt的回调
};

/**
 * @brief 定时器模块
 *
 * 提供定时任务管理功能，作为引擎核心模块运行
 * 通过事件总线接收更新事件，无需直接依赖
 */
class TimerModule : public Module {
  // 优先级为 6，在 SceneModule (优先级 5) 之后初始化
  E2D_REGISTER_MODULE(TimerModule, "Timer", 6)

public:
  TimerModule();
  ~TimerModule() override;

  // 禁止拷贝和移动
  TimerModule(const TimerModule &) = delete;
  TimerModule &operator=(const TimerModule &) = delete;
  TimerModule(TimerModule &&) = delete;
  TimerModule &operator=(TimerModule &&) = delete;

  // Module 接口实现
  bool init() override;
  void shutdown() override;
  void update(float dt) override;

  /**
   * @brief 调度一次性任务
   * @param delay 延迟时间（秒）
   * @param callback 回调函数
   * @return 定时器ID
   */
  TimerId scheduleOnce(float delay, TimerCallback callback);

  /**
   * @brief 调度重复任务
   * @param interval 间隔时间（秒）
   * @param repeat 重复次数（0表示无限）
   * @param callback 回调函数
   * @return 定时器ID
   */
  TimerId scheduleRepeat(float interval, uint32 repeat, TimerCallback callback);

  /**
   * @brief 调度每帧更新任务
   * @param callback 回调函数（接收dt）
   * @return 定时器ID
   */
  TimerId scheduleUpdate(TimerUpdateCallback callback);

  /**
   * @brief 取消定时器
   * @param id 定时器ID
   */
  void cancel(TimerId id);

  /**
   * @brief 暂停定时器
   * @param id 定时器ID
   */
  void pause(TimerId id);

  /**
   * @brief 恢复定时器
   * @param id 定时器ID
   */
  void resume(TimerId id);

  /**
   * @brief 设置时间缩放
   * @param scale 时间缩放比例（1.0为正常）
   */
  void setTimeScale(float scale) { timeScale_ = scale; }

  /**
   * @brief 获取时间缩放
   */
  float getTimeScale() const { return timeScale_; }

  /**
   * @brief 取消所有定时器
   */
  void cancelAll();

  /**
   * @brief 获取活动定时器数量
   */
  size_t getActiveCount() const;

private:
  /**
   * @brief 生成唯一ID
   */
  TimerId generateId();

  std::unordered_map<TimerId, std::unique_ptr<TimerInfo>> timers_;
  std::vector<TimerId> pendingRemove_;
  TimerId nextId_ = 1;
  float timeScale_ = 1.0f;
  bool inUpdate_ = false;
};

} // namespace extra2d