@esengine/pathfinding 12.0.0 → 12.1.2

package/dist/ecs.d.ts

@@ -0,0 +1,503 @@
+import { Component, EntitySystem, Entity } from '@esengine/ecs-framework';
+import { P as PathfindingState, e as IPoint, a as IPathfindingMap, f as IIncrementalPathfinder, m as IPathSmoother } from './IIncrementalPathfinding-3qs7e_pO.js';
+
+/**
+ * @zh 寻路代理组件
+ * @en Pathfinding Agent Component
+ */
+
+/**
+ * @zh 寻路代理组件
+ * @en Pathfinding Agent Component
+ *
+ * @zh 附加到需要寻路的实体上，管理寻路请求和结果
+ * @en Attach to entities that need pathfinding, manages path requests and results
+ *
+ * @example
+ * ```typescript
+ * const entity = scene.createEntity('Agent');
+ * const agent = entity.addComponent(new PathfindingAgentComponent());
+ *
+ * // Set initial position
+ * agent.x = 10;
+ * agent.y = 10;
+ *
+ * // Request path to target
+ * agent.requestPathTo(50, 50);
+ *
+ * // In movement system, follow the path
+ * const waypoint = agent.getNextWaypoint();
+ * if (waypoint) {
+ *     // Move towards waypoint
+ *     // When reached, call agent.advanceWaypoint()
+ * }
+ * ```
+ */
+declare class PathfindingAgentComponent extends Component {
+    /**
+     * @zh 当前位置 X 坐标
+     * @en Current position X coordinate
+     */
+    x: number;
+    /**
+     * @zh 当前位置 Y 坐标
+     * @en Current position Y coordinate
+     */
+    y: number;
+    /**
+     * @zh 目标位置 X 坐标
+     * @en Target position X coordinate
+     */
+    targetX: number;
+    /**
+     * @zh 目标位置 Y 坐标
+     * @en Target position Y coordinate
+     */
+    targetY: number;
+    /**
+     * @zh 是否有新的寻路请求待处理
+     * @en Whether there is a new path request pending
+     */
+    hasRequest: boolean;
+    /**
+     * @zh 寻路优先级（数值越小优先级越高）
+     * @en Pathfinding priority (lower number = higher priority)
+     */
+    priority: number;
+    /**
+     * @zh 每帧最大迭代次数
+     * @en Maximum iterations per frame
+     */
+    maxIterationsPerFrame: number;
+    /**
+     * @zh 是否启用动态重规划
+     * @en Whether dynamic replanning is enabled
+     */
+    enableDynamicReplan: boolean;
+    /**
+     * @zh 向前探测距离（用于障碍物检测）
+     * @en Lookahead distance for obstacle detection
+     */
+    lookaheadDistance: number;
+    /**
+     * @zh 路径验证间隔（帧数）
+     * @en Path validation interval (in frames)
+     */
+    validationInterval: number;
+    /**
+     * @zh 当前寻路状态
+     * @en Current pathfinding state
+     */
+    state: PathfindingState;
+    /**
+     * @zh 当前请求 ID
+     * @en Current request ID
+     */
+    currentRequestId: number;
+    /**
+     * @zh 当前路径点列表
+     * @en Current path waypoints
+     */
+    path: IPoint[];
+    /**
+     * @zh 当前路径索引
+     * @en Current path index
+     */
+    pathIndex: number;
+    /**
+     * @zh 路径总代价
+     * @en Total path cost
+     */
+    pathCost: number;
+    /**
+     * @zh 寻路进度 (0-1)
+     * @en Pathfinding progress (0-1)
+     */
+    progress: number;
+    /**
+     * @zh 上次验证的帧号
+     * @en Last validation frame number
+     */
+    lastValidationFrame: number;
+    /**
+     * @zh 寻路完成回调
+     * @en Pathfinding complete callback
+     */
+    onPathComplete?: (found: boolean, path: readonly IPoint[]) => void;
+    /**
+     * @zh 寻路进度回调
+     * @en Pathfinding progress callback
+     */
+    onPathProgress?: (progress: number) => void;
+    /**
+     * @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: number, targetY: number): void;
+    /**
+     * @zh 取消当前寻路
+     * @en Cancel current pathfinding
+     */
+    cancelPath(): void;
+    /**
+     * @zh 获取下一个路径点
+     * @en Get next waypoint
+     *
+     * @returns @zh 下一个路径点或 null @en Next waypoint or null
+     */
+    getNextWaypoint(): IPoint | null;
+    /**
+     * @zh 前进到下一个路径点
+     * @en Advance to next waypoint
+     */
+    advanceWaypoint(): void;
+    /**
+     * @zh 检查是否到达路径终点
+     * @en Check if reached path end
+     *
+     * @returns @zh 是否到达终点 @en Whether reached end
+     */
+    isPathComplete(): boolean;
+    /**
+     * @zh 检查是否正在寻路
+     * @en Check if pathfinding is in progress
+     *
+     * @returns @zh 是否正在寻路 @en Whether pathfinding is in progress
+     */
+    isSearching(): boolean;
+    /**
+     * @zh 检查是否有有效路径
+     * @en Check if has valid path
+     *
+     * @returns @zh 是否有有效路径 @en Whether has valid path
+     */
+    hasValidPath(): boolean;
+    /**
+     * @zh 获取剩余路径点数量
+     * @en Get remaining waypoint count
+     *
+     * @returns @zh 剩余路径点数量 @en Remaining waypoint count
+     */
+    getRemainingWaypointCount(): number;
+    /**
+     * @zh 获取当前路径的总长度
+     * @en Get total path length
+     *
+     * @returns @zh 路径总长度 @en Total path length
+     */
+    getPathLength(): number;
+    /**
+     * @zh 重置组件状态
+     * @en Reset component state
+     */
+    reset(): void;
+    /**
+     * @zh 组件从实体移除时调用
+     * @en Called when component is removed from entity
+     */
+    onRemovedFromEntity(): void;
+}
+
+/**
+ * @zh 寻路地图组件
+ * @en Pathfinding Map Component
+ */
+
+/**
+ * @zh 地图类型
+ * @en Map type
+ */
+type PathfindingMapType = 'grid' | 'navmesh';
+/**
+ * @zh 寻路地图组件
+ * @en Pathfinding Map Component
+ *
+ * @zh 挂载在场景实体上，持有地图实例和增量寻路器
+ * @en Attached to scene entity, holds map instance and incremental pathfinder
+ *
+ * @example
+ * ```typescript
+ * const mapEntity = scene.createEntity('PathfindingMap');
+ * const mapComp = mapEntity.addComponent(new PathfindingMapComponent());
+ *
+ * // Configure map
+ * mapComp.width = 100;
+ * mapComp.height = 100;
+ * mapComp.iterationsBudget = 2000;
+ *
+ * // Map and pathfinder will be initialized by PathfindingSystem
+ * ```
+ */
+declare class PathfindingMapComponent extends Component {
+    /**
+     * @zh 地图类型
+     * @en Map type
+     */
+    mapType: PathfindingMapType;
+    /**
+     * @zh 网格宽度（仅 grid 类型）
+     * @en Grid width (grid type only)
+     */
+    width: number;
+    /**
+     * @zh 网格高度（仅 grid 类型）
+     * @en Grid height (grid type only)
+     */
+    height: number;
+    /**
+     * @zh 是否允许对角移动
+     * @en Whether diagonal movement is allowed
+     */
+    allowDiagonal: boolean;
+    /**
+     * @zh 是否避免穿角
+     * @en Whether to avoid corner cutting
+     */
+    avoidCorners: boolean;
+    /**
+     * @zh 每帧处理的最大代理数
+     * @en Maximum agents processed per frame
+     */
+    maxAgentsPerFrame: number;
+    /**
+     * @zh 每帧总迭代次数预算
+     * @en Total iterations budget per frame
+     */
+    iterationsBudget: number;
+    /**
+     * @zh 是否启用路径平滑
+     * @en Whether path smoothing is enabled
+     */
+    enableSmoothing: boolean;
+    /**
+     * @zh 路径平滑类型
+     * @en Path smoothing type
+     */
+    smoothingType: 'los' | 'catmullrom' | 'combined';
+    /**
+     * @zh 是否启用路径缓存
+     * @en Whether path caching is enabled
+     */
+    enableCache: boolean;
+    /**
+     * @zh 缓存最大条目数
+     * @en Maximum cache entries
+     */
+    cacheMaxEntries: number;
+    /**
+     * @zh 缓存过期时间（毫秒），0 表示不过期
+     * @en Cache TTL in milliseconds, 0 means no expiration
+     */
+    cacheTtlMs: number;
+    /**
+     * @zh 是否显示调试信息
+     * @en Whether to show debug info
+     */
+    debugMode: boolean;
+    /**
+     * @zh 是否显示网格
+     * @en Whether to show grid
+     */
+    showGrid: boolean;
+    /**
+     * @zh 是否显示路径
+     * @en Whether to show paths
+     */
+    showPaths: boolean;
+    /**
+     * @zh 地图实例
+     * @en Map instance
+     */
+    map: IPathfindingMap | null;
+    /**
+     * @zh 增量寻路器实例
+     * @en Incremental pathfinder instance
+     */
+    pathfinder: IIncrementalPathfinder | null;
+    /**
+     * @zh 路径平滑器实例
+     * @en Path smoother instance
+     */
+    smoother: IPathSmoother | null;
+    /**
+     * @zh 是否已初始化
+     * @en Whether initialized
+     */
+    initialized: boolean;
+    /**
+     * @zh 当前活跃请求数
+     * @en Current active request count
+     */
+    activeRequests: number;
+    /**
+     * @zh 本帧使用的迭代次数
+     * @en Iterations used this frame
+     */
+    iterationsUsedThisFrame: number;
+    /**
+     * @zh 本帧处理的代理数
+     * @en Agents processed this frame
+     */
+    agentsProcessedThisFrame: number;
+    /**
+     * @zh 缓存命中次数
+     * @en Cache hit count
+     */
+    cacheHits: number;
+    /**
+     * @zh 缓存未命中次数
+     * @en Cache miss count
+     */
+    cacheMisses: number;
+    /**
+     * @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: number, y: number, walkable: boolean): void;
+    /**
+     * @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: number, y: number, rectWidth: number, rectHeight: number, walkable: boolean): void;
+    /**
+     * @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: number, y: number): boolean;
+    /**
+     * @zh 重置统计信息
+     * @en Reset statistics
+     */
+    resetStats(): void;
+    /**
+     * @zh 获取剩余迭代预算
+     * @en Get remaining iteration budget
+     *
+     * @returns @zh 剩余预算 @en Remaining budget
+     */
+    getRemainingBudget(): number;
+    /**
+     * @zh 获取缓存统计信息
+     * @en Get cache statistics
+     *
+     * @returns @zh 缓存统计 @en Cache statistics
+     */
+    getCacheStats(): {
+        enabled: boolean;
+        hits: number;
+        misses: number;
+        hitRate: number;
+    };
+    /**
+     * @zh 组件从实体移除时调用
+     * @en Called when component is removed from entity
+     */
+    onRemovedFromEntity(): void;
+}
+
+/**
+ * @zh 寻路系统
+ * @en Pathfinding System
+ */
+
+/**
+ * @zh 寻路系统
+ * @en Pathfinding System
+ *
+ * @zh 处理所有 PathfindingAgentComponent，支持时间切片和动态重规划
+ * @en Processes all PathfindingAgentComponents, supports time slicing and dynamic replanning
+ *
+ * @example
+ * ```typescript
+ * // Add system to scene
+ * scene.addSystem(new PathfindingSystem());
+ *
+ * // Create map entity
+ * const mapEntity = scene.createEntity('Map');
+ * mapEntity.addComponent(new PathfindingMapComponent());
+ *
+ * // Create agents
+ * const agent = scene.createEntity('Agent');
+ * const pathAgent = agent.addComponent(new PathfindingAgentComponent());
+ * pathAgent.requestPathTo(50, 50);
+ *
+ * // System handles pathfinding automatically each frame
+ * ```
+ */
+declare class PathfindingSystem extends EntitySystem {
+    private mapEntity;
+    private mapComponent;
+    private pathValidator;
+    private agentQueue;
+    private frameCounter;
+    constructor();
+    /**
+     * @zh 系统初始化
+     * @en System initialization
+     */
+    protected onInitialize(): void;
+    /**
+     * @zh 系统激活时调用
+     * @en Called when system is enabled
+     */
+    protected onEnable(): void;
+    /**
+     * @zh 处理实体
+     * @en Process entities
+     */
+    protected process(entities: readonly Entity[]): void;
+    /**
+     * @zh 查找地图实体
+     * @en Find map entity
+     */
+    private findMapEntity;
+    /**
+     * @zh 初始化地图
+     * @en Initialize map
+     */
+    private initializeMap;
+    /**
+     * @zh 构建代理优先级队列
+     * @en Build agent priority queue
+     */
+    private buildAgentQueue;
+    /**
+     * @zh 使用预算处理代理
+     * @en Process agents with budget
+     */
+    private processAgentsWithBudget;
+    /**
+     * @zh 启动新的寻路请求
+     * @en Start new pathfinding request
+     */
+    private startNewRequest;
+    /**
+     * @zh 从进度更新代理状态
+     * @en Update agent state from progress
+     */
+    private updateAgentFromProgress;
+    /**
+     * @zh 周期性验证路径有效性
+     * @en Periodically validate path validity
+     */
+    private validatePaths;
+}
+
+export { PathfindingAgentComponent, PathfindingMapComponent, type PathfindingMapType, PathfindingSystem };