@esengine/pathfinding 12.0.0 → 12.1.2

package/dist/ecs.js

@@ -0,0 +1,1033 @@
+import {
+  CatmullRomSmoother,
+  CombinedSmoother,
+  GridMap,
+  IncrementalAStarPathfinder,
+  LineOfSightSmoother,
+  PathValidator
+} from "./chunk-TPT7Q3E3.js";
+import {
+  PathfindingState,
+  __name,
+  __publicField
+} from "./chunk-GTFFYRZM.js";
+
+// src/ecs/PathfindingAgentComponent.ts
+import { Component, ECSComponent, Serializable, Serialize, Property } from "@esengine/ecs-framework";
+function _ts_decorate(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate, "_ts_decorate");
+function _ts_metadata(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata, "_ts_metadata");
+var _PathfindingAgentComponent = class _PathfindingAgentComponent extends Component {
+  constructor() {
+    super(...arguments);
+    // =========================================================================
+    // 位置属性 | Position Properties
+    // =========================================================================
+    /**
+     * @zh 当前位置 X 坐标
+     * @en Current position X coordinate
+     */
+    __publicField(this, "x", 0);
+    /**
+     * @zh 当前位置 Y 坐标
+     * @en Current position Y coordinate
+     */
+    __publicField(this, "y", 0);
+    // =========================================================================
+    // 目标属性 | Target Properties
+    // =========================================================================
+    /**
+     * @zh 目标位置 X 坐标
+     * @en Target position X coordinate
+     */
+    __publicField(this, "targetX", 0);
+    /**
+     * @zh 目标位置 Y 坐标
+     * @en Target position Y coordinate
+     */
+    __publicField(this, "targetY", 0);
+    /**
+     * @zh 是否有新的寻路请求待处理
+     * @en Whether there is a new path request pending
+     */
+    __publicField(this, "hasRequest", false);
+    // =========================================================================
+    // 配置属性 | Configuration Properties
+    // =========================================================================
+    /**
+     * @zh 寻路优先级（数值越小优先级越高）
+     * @en Pathfinding priority (lower number = higher priority)
+     */
+    __publicField(this, "priority", 50);
+    /**
+     * @zh 每帧最大迭代次数
+     * @en Maximum iterations per frame
+     */
+    __publicField(this, "maxIterationsPerFrame", 100);
+    /**
+     * @zh 是否启用动态重规划
+     * @en Whether dynamic replanning is enabled
+     */
+    __publicField(this, "enableDynamicReplan", true);
+    /**
+     * @zh 向前探测距离（用于障碍物检测）
+     * @en Lookahead distance for obstacle detection
+     */
+    __publicField(this, "lookaheadDistance", 5);
+    /**
+     * @zh 路径验证间隔（帧数）
+     * @en Path validation interval (in frames)
+     */
+    __publicField(this, "validationInterval", 10);
+    // =========================================================================
+    // 运行时状态（不序列化）| Runtime State (not serialized)
+    // =========================================================================
+    /**
+     * @zh 当前寻路状态
+     * @en Current pathfinding state
+     */
+    __publicField(this, "state", PathfindingState.Idle);
+    /**
+     * @zh 当前请求 ID
+     * @en Current request ID
+     */
+    __publicField(this, "currentRequestId", -1);
+    /**
+     * @zh 当前路径点列表
+     * @en Current path waypoints
+     */
+    __publicField(this, "path", []);
+    /**
+     * @zh 当前路径索引
+     * @en Current path index
+     */
+    __publicField(this, "pathIndex", 0);
+    /**
+     * @zh 路径总代价
+     * @en Total path cost
+     */
+    __publicField(this, "pathCost", 0);
+    /**
+     * @zh 寻路进度 (0-1)
+     * @en Pathfinding progress (0-1)
+     */
+    __publicField(this, "progress", 0);
+    /**
+     * @zh 上次验证的帧号
+     * @en Last validation frame number
+     */
+    __publicField(this, "lastValidationFrame", 0);
+    /**
+     * @zh 寻路完成回调
+     * @en Pathfinding complete callback
+     */
+    __publicField(this, "onPathComplete");
+    /**
+     * @zh 寻路进度回调
+     * @en Pathfinding progress callback
+     */
+    __publicField(this, "onPathProgress");
+  }
+  // =========================================================================
+  // 公共方法 | Public Methods
+  // =========================================================================
+  /**
+   * @zh 请求寻路到目标位置
+   * @en Request path to target position
+   *
+   * @param targetX - @zh 目标 X 坐标 @en Target X coordinate
+   * @param targetY - @zh 目标 Y 坐标 @en Target Y coordinate
+   */
+  requestPathTo(targetX, targetY) {
+    this.targetX = targetX;
+    this.targetY = targetY;
+    this.hasRequest = true;
+    this.state = PathfindingState.Idle;
+    this.progress = 0;
+  }
+  /**
+   * @zh 取消当前寻路
+   * @en Cancel current pathfinding
+   */
+  cancelPath() {
+    this.hasRequest = false;
+    this.state = PathfindingState.Cancelled;
+    this.path = [];
+    this.pathIndex = 0;
+    this.progress = 0;
+    this.currentRequestId = -1;
+  }
+  /**
+   * @zh 获取下一个路径点
+   * @en Get next waypoint
+   *
+   * @returns @zh 下一个路径点或 null @en Next waypoint or null
+   */
+  getNextWaypoint() {
+    if (this.pathIndex < this.path.length) {
+      return this.path[this.pathIndex];
+    }
+    return null;
+  }
+  /**
+   * @zh 前进到下一个路径点
+   * @en Advance to next waypoint
+   */
+  advanceWaypoint() {
+    if (this.pathIndex < this.path.length) {
+      this.pathIndex++;
+    }
+  }
+  /**
+   * @zh 检查是否到达路径终点
+   * @en Check if reached path end
+   *
+   * @returns @zh 是否到达终点 @en Whether reached end
+   */
+  isPathComplete() {
+    return this.pathIndex >= this.path.length;
+  }
+  /**
+   * @zh 检查是否正在寻路
+   * @en Check if pathfinding is in progress
+   *
+   * @returns @zh 是否正在寻路 @en Whether pathfinding is in progress
+   */
+  isSearching() {
+    return this.state === PathfindingState.InProgress;
+  }
+  /**
+   * @zh 检查是否有有效路径
+   * @en Check if has valid path
+   *
+   * @returns @zh 是否有有效路径 @en Whether has valid path
+   */
+  hasValidPath() {
+    return this.state === PathfindingState.Completed && this.path.length > 0;
+  }
+  /**
+   * @zh 获取剩余路径点数量
+   * @en Get remaining waypoint count
+   *
+   * @returns @zh 剩余路径点数量 @en Remaining waypoint count
+   */
+  getRemainingWaypointCount() {
+    return Math.max(0, this.path.length - this.pathIndex);
+  }
+  /**
+   * @zh 获取当前路径的总长度
+   * @en Get total path length
+   *
+   * @returns @zh 路径总长度 @en Total path length
+   */
+  getPathLength() {
+    return this.path.length;
+  }
+  /**
+   * @zh 重置组件状态
+   * @en Reset component state
+   */
+  reset() {
+    this.state = PathfindingState.Idle;
+    this.currentRequestId = -1;
+    this.path = [];
+    this.pathIndex = 0;
+    this.pathCost = 0;
+    this.progress = 0;
+    this.hasRequest = false;
+    this.lastValidationFrame = 0;
+  }
+  /**
+   * @zh 组件从实体移除时调用
+   * @en Called when component is removed from entity
+   */
+  onRemovedFromEntity() {
+    this.reset();
+    this.onPathComplete = void 0;
+    this.onPathProgress = void 0;
+  }
+};
+__name(_PathfindingAgentComponent, "PathfindingAgentComponent");
+var PathfindingAgentComponent = _PathfindingAgentComponent;
+_ts_decorate([
+  Serialize(),
+  Property({
+    type: "number",
+    label: "Position X"
+  }),
+  _ts_metadata("design:type", Number)
+], PathfindingAgentComponent.prototype, "x", void 0);
+_ts_decorate([
+  Serialize(),
+  Property({
+    type: "number",
+    label: "Position Y"
+  }),
+  _ts_metadata("design:type", Number)
+], PathfindingAgentComponent.prototype, "y", void 0);
+_ts_decorate([
+  Serialize(),
+  Property({
+    type: "number",
+    label: "Target X"
+  }),
+  _ts_metadata("design:type", Number)
+], PathfindingAgentComponent.prototype, "targetX", void 0);
+_ts_decorate([
+  Serialize(),
+  Property({
+    type: "number",
+    label: "Target Y"
+  }),
+  _ts_metadata("design:type", Number)
+], PathfindingAgentComponent.prototype, "targetY", void 0);
+_ts_decorate([
+  Serialize(),
+  Property({
+    type: "number",
+    label: "Priority",
+    min: 0,
+    max: 100
+  }),
+  _ts_metadata("design:type", Number)
+], PathfindingAgentComponent.prototype, "priority", void 0);
+_ts_decorate([
+  Serialize(),
+  Property({
+    type: "number",
+    label: "Max Iterations/Frame",
+    min: 10,
+    max: 1e3
+  }),
+  _ts_metadata("design:type", Number)
+], PathfindingAgentComponent.prototype, "maxIterationsPerFrame", void 0);
+_ts_decorate([
+  Serialize(),
+  Property({
+    type: "boolean",
+    label: "Dynamic Replan"
+  }),
+  _ts_metadata("design:type", Boolean)
+], PathfindingAgentComponent.prototype, "enableDynamicReplan", void 0);
+_ts_decorate([
+  Serialize(),
+  Property({
+    type: "number",
+    label: "Lookahead Distance",
+    min: 1,
+    max: 20
+  }),
+  _ts_metadata("design:type", Number)
+], PathfindingAgentComponent.prototype, "lookaheadDistance", void 0);
+_ts_decorate([
+  Serialize(),
+  Property({
+    type: "number",
+    label: "Validation Interval",
+    min: 1,
+    max: 60
+  }),
+  _ts_metadata("design:type", Number)
+], PathfindingAgentComponent.prototype, "validationInterval", void 0);
+PathfindingAgentComponent = _ts_decorate([
+  ECSComponent("PathfindingAgent"),
+  Serializable({
+    version: 1,
+    typeId: "PathfindingAgent"
+  })
+], PathfindingAgentComponent);
+
+// src/ecs/PathfindingMapComponent.ts
+import { Component as Component2, ECSComponent as ECSComponent2, Serializable as Serializable2, Serialize as Serialize2, Property as Property2 } from "@esengine/ecs-framework";
+function _ts_decorate2(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate2, "_ts_decorate");
+function _ts_metadata2(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata2, "_ts_metadata");
+var _PathfindingMapComponent = class _PathfindingMapComponent extends Component2 {
+  constructor() {
+    super(...arguments);
+    // =========================================================================
+    // 地图配置 | Map Configuration
+    // =========================================================================
+    /**
+     * @zh 地图类型
+     * @en Map type
+     */
+    __publicField(this, "mapType", "grid");
+    /**
+     * @zh 网格宽度（仅 grid 类型）
+     * @en Grid width (grid type only)
+     */
+    __publicField(this, "width", 100);
+    /**
+     * @zh 网格高度（仅 grid 类型）
+     * @en Grid height (grid type only)
+     */
+    __publicField(this, "height", 100);
+    /**
+     * @zh 是否允许对角移动
+     * @en Whether diagonal movement is allowed
+     */
+    __publicField(this, "allowDiagonal", true);
+    /**
+     * @zh 是否避免穿角
+     * @en Whether to avoid corner cutting
+     */
+    __publicField(this, "avoidCorners", true);
+    // =========================================================================
+    // 系统配置 | System Configuration
+    // =========================================================================
+    /**
+     * @zh 每帧处理的最大代理数
+     * @en Maximum agents processed per frame
+     */
+    __publicField(this, "maxAgentsPerFrame", 10);
+    /**
+     * @zh 每帧总迭代次数预算
+     * @en Total iterations budget per frame
+     */
+    __publicField(this, "iterationsBudget", 1e3);
+    /**
+     * @zh 是否启用路径平滑
+     * @en Whether path smoothing is enabled
+     */
+    __publicField(this, "enableSmoothing", true);
+    /**
+     * @zh 路径平滑类型
+     * @en Path smoothing type
+     */
+    __publicField(this, "smoothingType", "los");
+    // =========================================================================
+    // 缓存配置 | Cache Configuration
+    // =========================================================================
+    /**
+     * @zh 是否启用路径缓存
+     * @en Whether path caching is enabled
+     */
+    __publicField(this, "enableCache", true);
+    /**
+     * @zh 缓存最大条目数
+     * @en Maximum cache entries
+     */
+    __publicField(this, "cacheMaxEntries", 1e3);
+    /**
+     * @zh 缓存过期时间（毫秒），0 表示不过期
+     * @en Cache TTL in milliseconds, 0 means no expiration
+     */
+    __publicField(this, "cacheTtlMs", 5e3);
+    // =========================================================================
+    // 调试配置 | Debug Configuration
+    // =========================================================================
+    /**
+     * @zh 是否显示调试信息
+     * @en Whether to show debug info
+     */
+    __publicField(this, "debugMode", false);
+    /**
+     * @zh 是否显示网格
+     * @en Whether to show grid
+     */
+    __publicField(this, "showGrid", false);
+    /**
+     * @zh 是否显示路径
+     * @en Whether to show paths
+     */
+    __publicField(this, "showPaths", false);
+    // =========================================================================
+    // 运行时实例（不序列化）| Runtime Instances (not serialized)
+    // =========================================================================
+    /**
+     * @zh 地图实例
+     * @en Map instance
+     */
+    __publicField(this, "map", null);
+    /**
+     * @zh 增量寻路器实例
+     * @en Incremental pathfinder instance
+     */
+    __publicField(this, "pathfinder", null);
+    /**
+     * @zh 路径平滑器实例
+     * @en Path smoother instance
+     */
+    __publicField(this, "smoother", null);
+    /**
+     * @zh 是否已初始化
+     * @en Whether initialized
+     */
+    __publicField(this, "initialized", false);
+    // =========================================================================
+    // 统计信息 | Statistics
+    // =========================================================================
+    /**
+     * @zh 当前活跃请求数
+     * @en Current active request count
+     */
+    __publicField(this, "activeRequests", 0);
+    /**
+     * @zh 本帧使用的迭代次数
+     * @en Iterations used this frame
+     */
+    __publicField(this, "iterationsUsedThisFrame", 0);
+    /**
+     * @zh 本帧处理的代理数
+     * @en Agents processed this frame
+     */
+    __publicField(this, "agentsProcessedThisFrame", 0);
+    /**
+     * @zh 缓存命中次数
+     * @en Cache hit count
+     */
+    __publicField(this, "cacheHits", 0);
+    /**
+     * @zh 缓存未命中次数
+     * @en Cache miss count
+     */
+    __publicField(this, "cacheMisses", 0);
+  }
+  // =========================================================================
+  // 公共方法 | Public Methods
+  // =========================================================================
+  /**
+   * @zh 设置网格单元格是否可通行
+   * @en Set grid cell walkability
+   *
+   * @param x - @zh X 坐标 @en X coordinate
+   * @param y - @zh Y 坐标 @en Y coordinate
+   * @param walkable - @zh 是否可通行 @en Is walkable
+   */
+  setWalkable(x, y, walkable) {
+    if (this.map && "setWalkable" in this.map) {
+      this.map.setWalkable(x, y, walkable);
+      if (this.pathfinder) {
+        this.pathfinder.notifyObstacleChange(x - 1, y - 1, x + 1, y + 1);
+      }
+    }
+  }
+  /**
+   * @zh 设置矩形区域是否可通行
+   * @en Set rectangular area walkability
+   *
+   * @param x - @zh 起始 X @en Start X
+   * @param y - @zh 起始 Y @en Start Y
+   * @param width - @zh 宽度 @en Width
+   * @param height - @zh 高度 @en Height
+   * @param walkable - @zh 是否可通行 @en Is walkable
+   */
+  setRectWalkable(x, y, rectWidth, rectHeight, walkable) {
+    if (this.map && "setRectWalkable" in this.map) {
+      this.map.setRectWalkable(x, y, rectWidth, rectHeight, walkable);
+      if (this.pathfinder) {
+        this.pathfinder.notifyObstacleChange(x - 1, y - 1, x + rectWidth + 1, y + rectHeight + 1);
+      }
+    }
+  }
+  /**
+   * @zh 检查位置是否可通行
+   * @en Check if position is walkable
+   *
+   * @param x - @zh X 坐标 @en X coordinate
+   * @param y - @zh Y 坐标 @en Y coordinate
+   * @returns @zh 是否可通行 @en Is walkable
+   */
+  isWalkable(x, y) {
+    return this.map?.isWalkable(x, y) ?? false;
+  }
+  /**
+   * @zh 重置统计信息
+   * @en Reset statistics
+   */
+  resetStats() {
+    this.iterationsUsedThisFrame = 0;
+    this.agentsProcessedThisFrame = 0;
+  }
+  /**
+   * @zh 获取剩余迭代预算
+   * @en Get remaining iteration budget
+   *
+   * @returns @zh 剩余预算 @en Remaining budget
+   */
+  getRemainingBudget() {
+    return Math.max(0, this.iterationsBudget - this.iterationsUsedThisFrame);
+  }
+  /**
+   * @zh 获取缓存统计信息
+   * @en Get cache statistics
+   *
+   * @returns @zh 缓存统计 @en Cache statistics
+   */
+  getCacheStats() {
+    const pathfinderWithCache = this.pathfinder;
+    if (pathfinderWithCache?.getCacheStats) {
+      const stats = pathfinderWithCache.getCacheStats();
+      this.cacheHits = stats.hits;
+      this.cacheMisses = stats.misses;
+      return {
+        enabled: this.enableCache,
+        hits: stats.hits,
+        misses: stats.misses,
+        hitRate: stats.hitRate
+      };
+    }
+    return {
+      enabled: this.enableCache,
+      hits: this.cacheHits,
+      misses: this.cacheMisses,
+      hitRate: this.cacheHits + this.cacheMisses > 0 ? this.cacheHits / (this.cacheHits + this.cacheMisses) : 0
+    };
+  }
+  /**
+   * @zh 组件从实体移除时调用
+   * @en Called when component is removed from entity
+   */
+  onRemovedFromEntity() {
+    if (this.pathfinder) {
+      this.pathfinder.clear();
+    }
+    this.map = null;
+    this.pathfinder = null;
+    this.smoother = null;
+    this.initialized = false;
+  }
+};
+__name(_PathfindingMapComponent, "PathfindingMapComponent");
+var PathfindingMapComponent = _PathfindingMapComponent;
+_ts_decorate2([
+  Serialize2(),
+  Property2({
+    type: "enum",
+    label: "Map Type",
+    options: [
+      {
+        value: "grid",
+        label: "Grid"
+      },
+      {
+        value: "navmesh",
+        label: "NavMesh"
+      }
+    ]
+  }),
+  _ts_metadata2("design:type", typeof PathfindingMapType === "undefined" ? Object : PathfindingMapType)
+], PathfindingMapComponent.prototype, "mapType", void 0);
+_ts_decorate2([
+  Serialize2(),
+  Property2({
+    type: "number",
+    label: "Map Width",
+    min: 1,
+    max: 1e4
+  }),
+  _ts_metadata2("design:type", Number)
+], PathfindingMapComponent.prototype, "width", void 0);
+_ts_decorate2([
+  Serialize2(),
+  Property2({
+    type: "number",
+    label: "Map Height",
+    min: 1,
+    max: 1e4
+  }),
+  _ts_metadata2("design:type", Number)
+], PathfindingMapComponent.prototype, "height", void 0);
+_ts_decorate2([
+  Serialize2(),
+  Property2({
+    type: "boolean",
+    label: "Allow Diagonal"
+  }),
+  _ts_metadata2("design:type", Boolean)
+], PathfindingMapComponent.prototype, "allowDiagonal", void 0);
+_ts_decorate2([
+  Serialize2(),
+  Property2({
+    type: "boolean",
+    label: "Avoid Corners"
+  }),
+  _ts_metadata2("design:type", Boolean)
+], PathfindingMapComponent.prototype, "avoidCorners", void 0);
+_ts_decorate2([
+  Serialize2(),
+  Property2({
+    type: "number",
+    label: "Max Agents/Frame",
+    min: 1,
+    max: 100
+  }),
+  _ts_metadata2("design:type", Number)
+], PathfindingMapComponent.prototype, "maxAgentsPerFrame", void 0);
+_ts_decorate2([
+  Serialize2(),
+  Property2({
+    type: "number",
+    label: "Iterations Budget",
+    min: 100,
+    max: 1e4
+  }),
+  _ts_metadata2("design:type", Number)
+], PathfindingMapComponent.prototype, "iterationsBudget", void 0);
+_ts_decorate2([
+  Serialize2(),
+  Property2({
+    type: "boolean",
+    label: "Enable Smoothing"
+  }),
+  _ts_metadata2("design:type", Boolean)
+], PathfindingMapComponent.prototype, "enableSmoothing", void 0);
+_ts_decorate2([
+  Serialize2(),
+  Property2({
+    type: "enum",
+    label: "Smoothing Type",
+    options: [
+      {
+        value: "los",
+        label: "Line of Sight"
+      },
+      {
+        value: "catmullrom",
+        label: "Catmull-Rom"
+      },
+      {
+        value: "combined",
+        label: "Combined"
+      }
+    ]
+  }),
+  _ts_metadata2("design:type", String)
+], PathfindingMapComponent.prototype, "smoothingType", void 0);
+_ts_decorate2([
+  Serialize2(),
+  Property2({
+    type: "boolean",
+    label: "Enable Cache"
+  }),
+  _ts_metadata2("design:type", Boolean)
+], PathfindingMapComponent.prototype, "enableCache", void 0);
+_ts_decorate2([
+  Serialize2(),
+  Property2({
+    type: "number",
+    label: "Cache Size",
+    min: 100,
+    max: 1e4
+  }),
+  _ts_metadata2("design:type", Number)
+], PathfindingMapComponent.prototype, "cacheMaxEntries", void 0);
+_ts_decorate2([
+  Serialize2(),
+  Property2({
+    type: "number",
+    label: "Cache TTL (ms)",
+    min: 0,
+    max: 6e4
+  }),
+  _ts_metadata2("design:type", Number)
+], PathfindingMapComponent.prototype, "cacheTtlMs", void 0);
+_ts_decorate2([
+  Serialize2(),
+  Property2({
+    type: "boolean",
+    label: "Debug Mode"
+  }),
+  _ts_metadata2("design:type", Boolean)
+], PathfindingMapComponent.prototype, "debugMode", void 0);
+_ts_decorate2([
+  Serialize2(),
+  Property2({
+    type: "boolean",
+    label: "Show Grid"
+  }),
+  _ts_metadata2("design:type", Boolean)
+], PathfindingMapComponent.prototype, "showGrid", void 0);
+_ts_decorate2([
+  Serialize2(),
+  Property2({
+    type: "boolean",
+    label: "Show Paths"
+  }),
+  _ts_metadata2("design:type", Boolean)
+], PathfindingMapComponent.prototype, "showPaths", void 0);
+PathfindingMapComponent = _ts_decorate2([
+  ECSComponent2("PathfindingMap"),
+  Serializable2({
+    version: 1,
+    typeId: "PathfindingMap"
+  })
+], PathfindingMapComponent);
+
+// src/ecs/PathfindingSystem.ts
+import { EntitySystem, Matcher, ECSSystem } from "@esengine/ecs-framework";
+function _ts_decorate3(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate3, "_ts_decorate");
+function _ts_metadata3(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata3, "_ts_metadata");
+var _PathfindingSystem = class _PathfindingSystem extends EntitySystem {
+  constructor() {
+    super(Matcher.all(PathfindingAgentComponent));
+    __publicField(this, "mapEntity", null);
+    __publicField(this, "mapComponent", null);
+    __publicField(this, "pathValidator");
+    __publicField(this, "agentQueue", []);
+    __publicField(this, "frameCounter", 0);
+    this.pathValidator = new PathValidator();
+  }
+  /**
+   * @zh 系统初始化
+   * @en System initialization
+   */
+  onInitialize() {
+    this.findMapEntity();
+    this.initializeMap();
+  }
+  /**
+   * @zh 系统激活时调用
+   * @en Called when system is enabled
+   */
+  onEnable() {
+    this.findMapEntity();
+  }
+  /**
+   * @zh 处理实体
+   * @en Process entities
+   */
+  process(entities) {
+    if (!this.mapComponent?.pathfinder) {
+      this.findMapEntity();
+      if (!this.mapComponent?.pathfinder) {
+        return;
+      }
+    }
+    this.frameCounter++;
+    this.mapComponent.resetStats();
+    this.buildAgentQueue(entities);
+    this.processAgentsWithBudget();
+    this.validatePaths(entities);
+  }
+  // =========================================================================
+  // 私有方法 | Private Methods
+  // =========================================================================
+  /**
+   * @zh 查找地图实体
+   * @en Find map entity
+   */
+  findMapEntity() {
+    if (!this.scene) return;
+    const entities = this.scene.entities.findEntitiesWithComponent(PathfindingMapComponent);
+    if (entities.length > 0) {
+      const entity = entities[0];
+      const mapComp = entity.getComponent(PathfindingMapComponent);
+      if (mapComp) {
+        this.mapEntity = entity;
+        this.mapComponent = mapComp;
+        if (!mapComp.initialized) {
+          this.initializeMap();
+        }
+      }
+    }
+  }
+  /**
+   * @zh 初始化地图
+   * @en Initialize map
+   */
+  initializeMap() {
+    if (!this.mapComponent) return;
+    if (this.mapComponent.initialized) return;
+    if (!this.mapComponent.map) {
+      if (this.mapComponent.mapType === "grid") {
+        this.mapComponent.map = new GridMap(this.mapComponent.width, this.mapComponent.height, {
+          allowDiagonal: this.mapComponent.allowDiagonal,
+          avoidCorners: this.mapComponent.avoidCorners
+        });
+      }
+    }
+    if (!this.mapComponent.pathfinder && this.mapComponent.map) {
+      this.mapComponent.pathfinder = new IncrementalAStarPathfinder(this.mapComponent.map, {
+        enableCache: this.mapComponent.enableCache,
+        cacheConfig: {
+          maxEntries: this.mapComponent.cacheMaxEntries,
+          ttlMs: this.mapComponent.cacheTtlMs
+        }
+      });
+    }
+    if (!this.mapComponent.smoother && this.mapComponent.enableSmoothing) {
+      switch (this.mapComponent.smoothingType) {
+        case "catmullrom":
+          this.mapComponent.smoother = new CatmullRomSmoother();
+          break;
+        case "combined":
+          this.mapComponent.smoother = new CombinedSmoother();
+          break;
+        case "los":
+        default:
+          this.mapComponent.smoother = new LineOfSightSmoother();
+          break;
+      }
+    }
+    this.mapComponent.initialized = true;
+  }
+  /**
+   * @zh 构建代理优先级队列
+   * @en Build agent priority queue
+   */
+  buildAgentQueue(entities) {
+    this.agentQueue.length = 0;
+    for (const entity of entities) {
+      const agent = entity.getComponent(PathfindingAgentComponent);
+      if (!agent) continue;
+      if (!agent.hasRequest && (agent.state === PathfindingState.Idle || agent.state === PathfindingState.Completed || agent.state === PathfindingState.Cancelled)) {
+        continue;
+      }
+      this.agentQueue.push({
+        entity,
+        component: agent
+      });
+    }
+    this.agentQueue.sort((a, b) => a.component.priority - b.component.priority);
+  }
+  /**
+   * @zh 使用预算处理代理
+   * @en Process agents with budget
+   */
+  processAgentsWithBudget() {
+    const pathfinder = this.mapComponent.pathfinder;
+    const maxAgents = this.mapComponent.maxAgentsPerFrame;
+    let remainingBudget = this.mapComponent.iterationsBudget;
+    let agentsProcessed = 0;
+    for (const { component: agent } of this.agentQueue) {
+      if (agentsProcessed >= maxAgents || remainingBudget <= 0) {
+        break;
+      }
+      if (agent.hasRequest && agent.state === PathfindingState.Idle) {
+        this.startNewRequest(agent, pathfinder);
+      }
+      if (agent.state === PathfindingState.InProgress) {
+        const iterations = Math.min(agent.maxIterationsPerFrame, remainingBudget);
+        const progress = pathfinder.step(agent.currentRequestId, iterations);
+        this.updateAgentFromProgress(agent, progress, pathfinder);
+        remainingBudget -= progress.nodesSearched;
+        this.mapComponent.iterationsUsedThisFrame += progress.nodesSearched;
+      }
+      agentsProcessed++;
+    }
+    this.mapComponent.agentsProcessedThisFrame = agentsProcessed;
+  }
+  /**
+   * @zh 启动新的寻路请求
+   * @en Start new pathfinding request
+   */
+  startNewRequest(agent, pathfinder) {
+    if (agent.currentRequestId >= 0) {
+      pathfinder.cancel(agent.currentRequestId);
+      pathfinder.cleanup(agent.currentRequestId);
+    }
+    const request = pathfinder.requestPath(agent.x, agent.y, agent.targetX, agent.targetY, {
+      priority: agent.priority
+    });
+    agent.currentRequestId = request.id;
+    agent.state = PathfindingState.InProgress;
+    agent.hasRequest = false;
+    agent.progress = 0;
+    agent.path = [];
+    agent.pathIndex = 0;
+    this.mapComponent.activeRequests++;
+  }
+  /**
+   * @zh 从进度更新代理状态
+   * @en Update agent state from progress
+   */
+  updateAgentFromProgress(agent, progress, pathfinder) {
+    agent.state = progress.state;
+    agent.progress = progress.estimatedProgress;
+    agent.onPathProgress?.(progress.estimatedProgress);
+    if (progress.state === PathfindingState.Completed) {
+      const result = pathfinder.getResult(agent.currentRequestId);
+      if (result && result.found) {
+        const smoother = this.mapComponent?.smoother;
+        const map = this.mapComponent?.map;
+        if (smoother && map && this.mapComponent?.enableSmoothing) {
+          agent.path = smoother.smooth(result.path, map);
+        } else {
+          agent.path = [
+            ...result.path
+          ];
+        }
+        agent.pathIndex = 0;
+        agent.pathCost = result.cost;
+        agent.onPathComplete?.(true, agent.path);
+      } else {
+        agent.path = [];
+        agent.state = PathfindingState.Failed;
+        agent.onPathComplete?.(false, []);
+      }
+      pathfinder.cleanup(agent.currentRequestId);
+      this.mapComponent.activeRequests--;
+    } else if (progress.state === PathfindingState.Failed) {
+      agent.path = [];
+      agent.onPathComplete?.(false, []);
+      pathfinder.cleanup(agent.currentRequestId);
+      this.mapComponent.activeRequests--;
+    }
+  }
+  /**
+   * @zh 周期性验证路径有效性
+   * @en Periodically validate path validity
+   */
+  validatePaths(entities) {
+    const map = this.mapComponent?.map;
+    if (!map) return;
+    for (const entity of entities) {
+      const agent = entity.getComponent(PathfindingAgentComponent);
+      if (!agent || !agent.enableDynamicReplan) continue;
+      if (agent.path.length === 0 || agent.isPathComplete()) continue;
+      if (this.frameCounter - agent.lastValidationFrame < agent.validationInterval) {
+        continue;
+      }
+      agent.lastValidationFrame = this.frameCounter;
+      const checkEnd = Math.min(agent.pathIndex + agent.lookaheadDistance, agent.path.length);
+      const result = this.pathValidator.validatePath(agent.path, agent.pathIndex, checkEnd, map);
+      if (!result.valid) {
+        agent.x = agent.path[agent.pathIndex]?.x ?? agent.x;
+        agent.y = agent.path[agent.pathIndex]?.y ?? agent.y;
+        agent.requestPathTo(agent.targetX, agent.targetY);
+      }
+    }
+  }
+};
+__name(_PathfindingSystem, "PathfindingSystem");
+var PathfindingSystem = _PathfindingSystem;
+PathfindingSystem = _ts_decorate3([
+  ECSSystem("Pathfinding", {
+    updateOrder: 0
+  }),
+  _ts_metadata3("design:type", Function),
+  _ts_metadata3("design:paramtypes", [])
+], PathfindingSystem);
+export {
+  PathfindingAgentComponent,
+  PathfindingMapComponent,
+  PathfindingSystem
+};
+//# sourceMappingURL=ecs.js.map