@nimbus2d/core 0.0.1

package/src/core/Camera/Camera.js

@@ -0,0 +1,534 @@
+// ============================================================================
+// Nimbus2D - Camera 高级视口相机
+// ----------------------------------------------------------------------------
+// 职责：
+//   1. 封装 PIXI.Container 作为视口容器，提供世界坐标系到屏幕坐标系的变换
+//   2. 提供跟随目标（lerp 插值 + 死区）能力
+//   3. 提供屏幕抖动（衰减 + 时间约束）能力
+//   4. 提供缩放、旋转、边界约束能力
+//   5. 通过 EventBus 广播相机事件（follow/shake/moved）
+//
+// 设计决策：
+//   - 不继承 PIXI 类：独立设计，内部持有 PIXI.Container 作为视口
+//     好处是 Camera 不污染 PIXI 命名空间，可独立测试和复用
+//   - lerp 插值帧率无关：使用 `1 - Math.pow(1 - lerp, delta * 60)` 公式
+//     确保不同帧率下行为一致（以 60fps 为基准）
+//   - 事件发射防重：每帧最多发射一次 camera:moved 事件（通过 _movedEmitted 标记）
+//     避免同一帧内 setter 与 update 重复发射事件
+//   - EventBus 注入：通过公开方法 setEventBus 注入（不放在构造函数）
+//     避免 Camera 构造时强制依赖 EventBus，符合依赖注入最佳实践
+//   - 销毁幂等：通过 _isDestroyed 标记避免重复销毁导致崩溃
+//   - zoom 最小值保护：Math.max(0.01, val) 防止零或负值导致渲染异常
+//   - follow 参数校验：避免传入无效目标导致后续 update 中 NaN 污染
+//
+// 四期新增（任务 1.4）：对标 Phaser 的 Camera 系统
+// ============================================================================
+
+import { Container } from 'pixi.js'
+import { CameraEventType, CameraError } from './CameraTypes.js'
+
+class Camera {
+  // --------------------------------------------------------------------------
+  // 构造函数
+  // --------------------------------------------------------------------------
+
+  /**
+   * 创建 Camera 实例
+   * @param {Object} [options={}] - 配置
+   * @param {number} [options.width=0] - 视口宽度（建议传入 PIXI 屏幕宽度）
+   * @param {number} [options.height=0] - 视口高度（建议传入 PIXI 屏幕高度）
+   * @param {number} [options.x=0] - 初始 X 位置（世界坐标）
+   * @param {number} [options.y=0] - 初始 Y 位置（世界坐标）
+   * @param {number} [options.zoom=1] - 初始缩放系数（>0，最小 0.01）
+   * @param {number} [options.rotation=0] - 初始旋转角度（弧度）
+   */
+  constructor(options = {}) {
+    /** @type {number} 相机在世界坐标系的 X 位置（左上角） */
+    this._x = options.x ?? 0
+    /** @type {number} 相机在世界坐标系的 Y 位置（左上角） */
+    this._y = options.y ?? 0
+    /** @type {number} 视口宽度（用于跟随计算居中点） */
+    this._width = options.width ?? 0
+    /** @type {number} 视口高度（用于跟随计算居中点） */
+    this._height = options.height ?? 0
+    /** @type {number} 缩放系数（>0） */
+    this._zoom = Math.max(0.01, options.zoom ?? 1)
+    /** @type {number} 旋转角度（弧度） */
+    this._rotation = options.rotation ?? 0
+
+    /**
+     * PIXI 视口容器
+     * 所有世界元素应添加到此容器的子级，相机的变换会自动应用到子级
+     * 通过 viewport.position/scale/rotation 实现世界坐标到屏幕坐标的变换
+     * @type {import('pixi.js').Container}
+     * @private
+     */
+    this._viewport = new Container()
+    this._viewport.label = 'nimbus_camera_viewport'
+
+    // === 跟随状态 ===
+    /**
+     * 跟随目标对象（需有 x/y 属性）
+     * @type {Object|null}
+     * @private
+     */
+    this._followTarget = null
+    /**
+     * 跟随插值系数（0=不跟随，1=立即跟随）
+     * @type {number}
+     * @private
+     */
+    this._followLerp = 1
+    /**
+     * 死区矩形 { x, y, width, height }
+     * 目标在死区内时相机不移动，超出死区时相机跟随
+     * @type {{x:number,y:number,width:number,height:number}|null}
+     * @private
+     */
+    this._deadzone = null
+
+    // === 抖动状态 ===
+    /** @type {number} 抖动强度（像素） */
+    this._shakeIntensity = 0
+    /** @type {number} 抖动持续时间（毫秒） */
+    this._shakeDuration = 0
+    /** @type {number} 抖动衰减系数（每帧乘以此值，0-1） */
+    this._shakeDecay = 0.95
+    /** @type {number} 抖动 X 偏移（像素，当前帧） */
+    this._shakeOffsetX = 0
+    /** @type {number} 抖动 Y 偏移（像素，当前帧） */
+    this._shakeOffsetY = 0
+    /** @type {number} 抖动已经过时间（毫秒） */
+    this._shakeElapsed = 0
+
+    // === 边界约束 ===
+    /**
+     * 相机活动边界 { x, y, width, height }
+     * 设置后相机位置会被约束在边界内
+     * @type {{x:number,y:number,width:number,height:number}|null}
+     * @private
+     */
+    this._bounds = null
+
+    // === 事件相关 ===
+    /**
+     * camera:moved 事件防重标记
+     * 每帧开始时重置为 false，发射后置 true，确保每帧最多发射一次
+     * @type {boolean}
+     * @private
+     */
+    this._movedEmitted = false
+    /**
+     * 事件总线（通过 setEventBus 注入）
+     * @type {import('../../core/EventBus/EventBus.js').EventBus|null}
+     * @private
+     */
+    this._eventBus = null
+
+    /** @type {boolean} 是否已销毁（用于幂等销毁） */
+    this._isDestroyed = false
+
+    // 构造完成后立即应用一次视口变换，确保初始状态正确
+    this._updateViewport()
+  }
+
+  // --------------------------------------------------------------------------
+  // 公共访问器：位置
+  // --------------------------------------------------------------------------
+
+  /** @type {number} 相机 X 位置（世界坐标） */
+  get x() { return this._x }
+  set x(val) {
+    // 销毁后保护：避免访问已销毁的 _viewport 导致崩溃
+    if (this._isDestroyed) return
+    this._x = val
+    this._updateViewport()
+  }
+
+  /** @type {number} 相机 Y 位置（世界坐标） */
+  get y() { return this._y }
+  set y(val) {
+    // 销毁后保护：避免访问已销毁的 _viewport 导致崩溃
+    if (this._isDestroyed) return
+    this._y = val
+    this._updateViewport()
+  }
+
+  // --------------------------------------------------------------------------
+  // 公共访问器：尺寸
+  // --------------------------------------------------------------------------
+
+  /** @type {number} 视口宽度 */
+  get width() { return this._width }
+
+  /** @type {number} 视口高度 */
+  get height() { return this._height }
+
+  /**
+   * 设置视口尺寸（用于窗口大小变化时同步更新）
+   * @param {number} width - 新宽度
+   * @param {number} height - 新高度
+   */
+  setSize(width, height) {
+    if (this._isDestroyed) return
+    this._width = width
+    this._height = height
+  }
+
+  // --------------------------------------------------------------------------
+  // 公共访问器：缩放与旋转
+  // --------------------------------------------------------------------------
+
+  /** @type {number} 缩放系数 */
+  get zoom() { return this._zoom }
+  set zoom(val) {
+    // 销毁后保护：避免访问已销毁的 _viewport 导致崩溃
+    if (this._isDestroyed) return
+    // 最小值保护，避免零或负值导致渲染异常
+    this._zoom = Math.max(0.01, val)
+    this._updateViewport()
+  }
+
+  /** @type {number} 旋转角度（弧度） */
+  get rotation() { return this._rotation }
+  set rotation(val) {
+    // 销毁后保护：避免访问已销毁的 _viewport 导致崩溃
+    if (this._isDestroyed) return
+    this._rotation = val
+    this._updateViewport()
+  }
+
+  // --------------------------------------------------------------------------
+  // 公共访问器：状态与视口
+  // --------------------------------------------------------------------------
+
+  /** @type {boolean} 是否正在抖动 */
+  get isShaking() { return this._shakeIntensity > 0 }
+
+  /** @type {boolean} 是否已销毁 */
+  get isDestroyed() { return this._isDestroyed }
+
+  /**
+   * PIXI 视口容器（用于添加到场景 stage）
+   * 用户应将此容器添加到 PIXI stage，并将世界元素添加到此容器的子级
+   * @type {import('pixi.js').Container}
+   */
+  get viewport() { return this._viewport }
+
+  // --------------------------------------------------------------------------
+  // 跟随
+  // --------------------------------------------------------------------------
+
+  /**
+   * 跟随目标对象
+   * @param {Object} target - 目标对象（需有数值类型的 x/y 属性）
+   * @param {Object} [options={}] - 跟随选项
+   * @param {number} [options.lerp=1] - 插值系数（0=不跟随，1=立即跟随）
+   * @param {{x:number,y:number,width:number,height:number}} [options.deadzone] - 死区矩形
+   * @throws {CameraError} target 为 null/undefined 或缺少数值类型的 x/y 属性
+   */
+  follow(target, options = {}) {
+    if (this._isDestroyed) return
+
+    // 参数校验：防止无效目标导致后续 update 中 NaN 污染
+    if (!target || typeof target.x !== 'number' || typeof target.y !== 'number') {
+      throw new CameraError('follow 目标必须包含数值类型的 x/y 属性')
+    }
+
+    this._followTarget = target
+
+    // 插值系数范围约束 [0, 1]
+    const lerp = options.lerp ?? 1
+    this._followLerp = Math.max(0, Math.min(1, lerp))
+
+    this._deadzone = options.deadzone ?? null
+
+    this._emitEvent(CameraEventType.FOLLOW_CHANGED, {
+      target,
+      lerp: this._followLerp,
+      deadzone: this._deadzone
+    })
+  }
+
+  /** 停止跟随 */
+  stopFollow() {
+    this._followTarget = null
+    this._deadzone = null
+  }
+
+  // --------------------------------------------------------------------------
+  // 抖动
+  // --------------------------------------------------------------------------
+
+  /**
+   * 触发抖动效果
+   * 若已有抖动进行中，新参数会覆盖旧参数（不发射 SHAKE_END，直接重新开始）
+   *
+   * @param {Object} [options={}] - 抖动选项
+   * @param {number} [options.intensity=10] - 抖动强度（像素）
+   * @param {number} [options.duration=500] - 持续时间（毫秒）
+   * @param {number} [options.decay=0.95] - 衰减系数（0-1，越小衰减越快）
+   */
+  shake(options = {}) {
+    if (this._isDestroyed) return
+
+    this._shakeIntensity = options.intensity ?? 10
+    this._shakeDuration = options.duration ?? 500
+    this._shakeDecay = options.decay ?? 0.95
+    this._shakeElapsed = 0
+    this._shakeOffsetX = 0
+    this._shakeOffsetY = 0
+
+    this._emitEvent(CameraEventType.SHAKE_START, {
+      intensity: this._shakeIntensity,
+      duration: this._shakeDuration
+    })
+  }
+
+  // --------------------------------------------------------------------------
+  // 边界约束
+  // --------------------------------------------------------------------------
+
+  /**
+   * 设置相机活动边界
+   * 设置后相机位置会被约束在 [bounds.x, bounds.x + bounds.width - width] 范围内
+   * @param {{x:number,y:number,width:number,height:number}} bounds - 边界矩形
+   */
+  setBounds(bounds) {
+    if (this._isDestroyed) return
+    this._bounds = bounds
+  }
+
+  /** 移除边界约束 */
+  removeBounds() {
+    this._bounds = null
+  }
+
+  // --------------------------------------------------------------------------
+  // 帧更新
+  // --------------------------------------------------------------------------
+
+  /**
+   * 每帧更新（由 Scene.update() 调用）
+   * @param {number} delta - 帧间隔（秒，建议使用 PixiJS ticker.deltaMS / 1000）
+   */
+  update(delta) {
+    if (this._isDestroyed) return
+
+    // 0. 每帧开始重置事件发射标记
+    this._movedEmitted = false
+
+    // 1. 跟随逻辑（更新 _x/_y）
+    this._updateFollow(delta)
+
+    // 2. 抖动逻辑（更新 _shakeOffsetX/_shakeOffsetY）
+    this._updateShake(delta)
+
+    // 3. 边界约束（约束 _x/_y 到 _bounds 范围内）
+    this._applyBounds()
+
+    // 4. 更新视口变换（同步到 PIXI 容器，并发射 camera:moved 事件）
+    this._updateViewport()
+  }
+
+  // --------------------------------------------------------------------------
+  // EventBus 注入
+  // --------------------------------------------------------------------------
+
+  /**
+   * 注入事件总线
+   * 由 Scene 或用户调用，注入后才能发射 camera:* 事件
+   *
+   * 注意：设计文档中此方法名为 _setEventBus（下划线前缀），
+   * 但根据任务 1.1 的经验，需要外部调用的方法应为公开方法，
+   * 故改为 setEventBus（与 SpriteGPULayer.setEventBus 保持一致）
+   *
+   * @param {import('../../core/EventBus/EventBus.js').EventBus} eventBus - 事件总线实例
+   */
+  setEventBus(eventBus) {
+    this._eventBus = eventBus
+  }
+
+  // --------------------------------------------------------------------------
+  // 私有方法：跟随更新
+  // --------------------------------------------------------------------------
+
+  /**
+   * 跟随更新（含 lerp 插值与死区处理）
+   * @param {number} delta - 帧间隔（秒）
+   * @private
+   */
+  _updateFollow(delta) {
+    if (!this._followTarget) return
+
+    // 计算目标位置（让目标居中显示在视口中央）
+    let targetX = this._followTarget.x - this._width / 2
+    let targetY = this._followTarget.y - this._height / 2
+
+    // 死区处理：目标在死区内时相机不移动
+    if (this._deadzone) {
+      const dz = this._deadzone
+      const dx = this._followTarget.x - this._x - this._width / 2
+      const dy = this._followTarget.y - this._y - this._height / 2
+
+      if (Math.abs(dx) > dz.width / 2) {
+        targetX = this._followTarget.x - (dz.width / 2 + dz.x) * Math.sign(dx)
+      } else {
+        targetX = this._x
+      }
+      if (Math.abs(dy) > dz.height / 2) {
+        targetY = this._followTarget.y - (dz.height / 2 + dz.y) * Math.sign(dy)
+      } else {
+        targetY = this._y
+      }
+    }
+
+    // lerp 插值（帧率无关公式）
+    // 假设 60fps 为基准：delta=1/60 时，lerpFactor = lerp
+    // 其他帧率下通过 Math.pow 调整，确保行为一致
+    const lerpFactor = 1 - Math.pow(1 - this._followLerp, delta * 60)
+    this._x += (targetX - this._x) * lerpFactor
+    this._y += (targetY - this._y) * lerpFactor
+  }
+
+  // --------------------------------------------------------------------------
+  // 私有方法：抖动更新
+  // --------------------------------------------------------------------------
+
+  /**
+   * 抖动更新
+   * @param {number} delta - 帧间隔（秒）
+   * @private
+   */
+  _updateShake(delta) {
+    if (this._shakeIntensity <= 0) return
+
+    // 累计已经过时间（毫秒）
+    this._shakeElapsed += delta * 1000
+
+    // 超过持续时间，结束抖动
+    if (this._shakeElapsed >= this._shakeDuration) {
+      this._shakeIntensity = 0
+      this._shakeOffsetX = 0
+      this._shakeOffsetY = 0
+      this._emitEvent(CameraEventType.SHAKE_END, {})
+      return
+    }
+
+    // 随机偏移（-1 到 1 乘以强度）
+    this._shakeOffsetX = (Math.random() * 2 - 1) * this._shakeIntensity
+    this._shakeOffsetY = (Math.random() * 2 - 1) * this._shakeIntensity
+
+    // 强度衰减（每帧乘以衰减系数）
+    this._shakeIntensity *= this._shakeDecay
+  }
+
+  // --------------------------------------------------------------------------
+  // 私有方法：边界约束
+  // --------------------------------------------------------------------------
+
+  /**
+   * 应用边界约束
+   * 将 _x/_y 约束在 _bounds 范围内
+   * @private
+   */
+  _applyBounds() {
+    if (!this._bounds) return
+
+    // 限制 X 范围：[bounds.x, bounds.x + bounds.width - width]
+    this._x = Math.max(
+      this._bounds.x,
+      Math.min(this._x, this._bounds.x + this._bounds.width - this._width)
+    )
+    // 限制 Y 范围：[bounds.y, bounds.y + bounds.height - height]
+    this._y = Math.max(
+      this._bounds.y,
+      Math.min(this._y, this._bounds.y + this._bounds.height - this._height)
+    )
+  }
+
+  // --------------------------------------------------------------------------
+  // 私有方法：视口变换更新
+  // --------------------------------------------------------------------------
+
+  /**
+   * 更新 PIXI 视口变换
+   * 注意：此方法在 update() 和 x/y/zoom/rotation setter 中均被调用，
+   * 为避免同一帧内多次发射 camera:moved 事件，使用 _movedEmitted 标记防重。
+   * @private
+   */
+  _updateViewport() {
+    // 同步位置（含抖动偏移）
+    this._viewport.position.set(
+      -this._x + this._shakeOffsetX,
+      -this._y + this._shakeOffsetY
+    )
+    // 同步缩放
+    this._viewport.scale.set(this._zoom, this._zoom)
+    // 同步旋转
+    this._viewport.rotation = this._rotation
+
+    // 发射 camera:moved 事件（每帧最多一次）
+    if (this._eventBus && !this._movedEmitted) {
+      this._emitEvent(CameraEventType.MOVED, { x: this._x, y: this._y })
+      this._movedEmitted = true
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // 私有方法：事件发射
+  // --------------------------------------------------------------------------
+
+  /**
+   * 发射事件（内部方法，安全包装，避免 emit 异常影响主流程）
+   * @param {string} eventType - 事件类型
+   * @param {Object} payload - 事件数据
+   * @private
+   */
+  _emitEvent(eventType, payload) {
+    if (this._eventBus) {
+      try {
+        this._eventBus.emit(eventType, payload)
+      } catch (e) {
+        // 事件发射异常不影响相机主流程
+      }
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // 销毁
+  // --------------------------------------------------------------------------
+
+  /**
+   * 销毁相机
+   * 清理所有内部引用和 PIXI 资源（幂等，可重复调用）
+   */
+  destroy() {
+    if (this._isDestroyed) return
+    this._isDestroyed = true
+
+    // 停止跟随
+    this.stopFollow()
+
+    // 清理抖动状态
+    this._shakeIntensity = 0
+    this._shakeOffsetX = 0
+    this._shakeOffsetY = 0
+    this._shakeDuration = 0
+    this._shakeElapsed = 0
+
+    // 清理边界
+    this._bounds = null
+
+    // 销毁视口容器（PIXI 资源）
+    if (this._viewport) {
+      this._viewport.destroy()
+      this._viewport = null
+    }
+
+    // 清理事件总线引用（避免内存泄漏）
+    this._eventBus = null
+  }
+}
+
+export { Camera }

package/src/core/Camera/CameraTypes.js

@@ -0,0 +1,59 @@
+// ============================================================================
+// Nimbus2D - Camera 类型定义
+// ----------------------------------------------------------------------------
+// 职责：
+//   1. 定义 Camera 相关的事件类型枚举（CameraEventType）
+//   2. 定义 Camera 错误类（CameraError）
+//
+// 设计决策：
+//   - 事件类型使用 Object.freeze 冻结，防止运行时被篡改
+//   - 错误类继承 NimbusError，附加 module='Camera' 字段，便于统一错误识别
+//   - 与 SpriteGPULayer/PoolManager 的类型定义风格保持一致
+//
+// 四期新增（任务 1.4）：Camera 系统的类型定义
+// ============================================================================
+
+import { NimbusError } from '../../errors/NimbusError.js'
+
+// ----------------------------------------------------------------------------
+// 事件类型枚举
+// ----------------------------------------------------------------------------
+
+/**
+ * Camera 事件类型
+ * @enum {string}
+ * @readonly
+ */
+const CameraEventType = Object.freeze({
+  /** 跟随目标改变时发射（follow/stopFollow） */
+  FOLLOW_CHANGED: 'camera:follow:changed',
+  /** 抖动开始时发射（shake 调用瞬间） */
+  SHAKE_START: 'camera:shake:start',
+  /** 抖动结束时发射（持续时间到或强度衰减完毕） */
+  SHAKE_END: 'camera:shake:end',
+  /** 相机位置变化时发射（每帧最多一次，防重） */
+  MOVED: 'camera:moved'
+})
+
+// ----------------------------------------------------------------------------
+// 错误类
+// ----------------------------------------------------------------------------
+
+/**
+ * Camera 错误基类
+ * 所有 Camera 错误构造函数设置 module='Camera'
+ * @extends NimbusError
+ */
+class CameraError extends NimbusError {
+  /**
+   * 构造函数
+   * @param {string} message - 错误消息
+   * @param {string} [code='CAMERA_ERROR'] - 错误码
+   * @param {Error|null} [cause=null] - 原始错误
+   */
+  constructor(message, code = 'CAMERA_ERROR', cause = null) {
+    super(message, code, 'Camera', cause)
+  }
+}
+
+export { CameraEventType, CameraError }

package/src/core/Camera/index.js

@@ -0,0 +1,13 @@
+// ============================================================================
+// Nimbus2D - Camera 模块入口
+// ----------------------------------------------------------------------------
+// 导出高级视口相机的所有公开 API
+//
+// 四期新增（任务 1.4）：Camera 系统模块入口
+// ============================================================================
+
+// Camera 主类
+export { Camera } from './Camera.js'
+
+// 类型定义（事件枚举 + 错误类）
+export { CameraEventType, CameraError } from './CameraTypes.js'