@esengine/pathfinding 12.1.2 → 13.0.0

package/dist/ecs.d.ts

@@ -1,5 +1,6 @@
 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';
+import { P as PathfindingState, e as IPoint, a as IPathfindingMap, f as IIncrementalPathfinder, m as IPathSmoother, O as ORCASolver, K as KDTree, x as IObstacle, y as IORCASolverConfig } from './KDTree-Bw4Faf2O.js';
+import '@esengine/ecs-framework-math';
 
 /**
  * @zh 寻路代理组件
@@ -500,4 +501,383 @@ declare class PathfindingSystem extends EntitySystem {
     private validatePaths;
 }
 
-export { PathfindingAgentComponent, PathfindingMapComponent, type PathfindingMapType, PathfindingSystem };
+/**
+ * @zh 避让代理组件
+ * @en Avoidance Agent Component
+ */
+
+/**
+ * @zh 避让代理组件
+ * @en Avoidance Agent Component
+ *
+ * @zh 附加到需要局部避让的实体上，与 ORCA 系统配合使用
+ * @en Attach to entities that need local avoidance, works with ORCA system
+ *
+ * @example
+ * ```typescript
+ * const entity = scene.createEntity('Monster');
+ *
+ * // 添加避让代理
+ * const avoidance = entity.addComponent(new AvoidanceAgentComponent());
+ * avoidance.radius = 0.5;
+ * avoidance.maxSpeed = 5.0;
+ *
+ * // 设置首选速度（朝向目标）
+ * avoidance.setPreferredVelocityTowards(targetX, targetY, currentX, currentY);
+ *
+ * // 系统计算后，使用新速度更新位置
+ * // After system computes, use new velocity to update position
+ * x += avoidance.newVelocityX * deltaTime;
+ * y += avoidance.newVelocityY * deltaTime;
+ * ```
+ */
+declare class AvoidanceAgentComponent extends Component {
+    /**
+     * @zh 代理半径
+     * @en Agent radius
+     *
+     * @zh 用于碰撞检测和避让计算
+     * @en Used for collision detection and avoidance computation
+     */
+    radius: number;
+    /**
+     * @zh 最大速度
+     * @en Maximum speed
+     */
+    maxSpeed: number;
+    /**
+     * @zh 邻居检测距离
+     * @en Neighbor detection distance
+     *
+     * @zh 只考虑此范围内的其他代理
+     * @en Only considers other agents within this range
+     */
+    neighborDist: number;
+    /**
+     * @zh 最大邻居数量
+     * @en Maximum number of neighbors to consider
+     *
+     * @zh 限制计算量，优先考虑最近的邻居
+     * @en Limits computation, prioritizes closest neighbors
+     */
+    maxNeighbors: number;
+    /**
+     * @zh 代理避让时间视野（秒）
+     * @en Time horizon for agent avoidance (seconds)
+     *
+     * @zh 更大的值会让代理更早开始避让，但可能导致过于保守
+     * @en Larger values make agents start avoiding earlier, but may be too conservative
+     */
+    timeHorizon: number;
+    /**
+     * @zh 障碍物避让时间视野（秒）
+     * @en Time horizon for obstacle avoidance (seconds)
+     */
+    timeHorizonObst: number;
+    /**
+     * @zh 当前位置 X
+     * @en Current position X
+     *
+     * @zh 如果实体有 Transform 组件，系统会自动同步
+     * @en If entity has Transform component, system will sync automatically
+     */
+    positionX: number;
+    /**
+     * @zh 当前位置 Y
+     * @en Current position Y
+     */
+    positionY: number;
+    /**
+     * @zh 当前速度 X
+     * @en Current velocity X
+     */
+    velocityX: number;
+    /**
+     * @zh 当前速度 Y
+     * @en Current velocity Y
+     */
+    velocityY: number;
+    /**
+     * @zh 首选速度 X（通常指向目标方向）
+     * @en Preferred velocity X (usually towards target)
+     */
+    preferredVelocityX: number;
+    /**
+     * @zh 首选速度 Y
+     * @en Preferred velocity Y
+     */
+    preferredVelocityY: number;
+    /**
+     * @zh ORCA 计算的新速度 X
+     * @en New velocity X computed by ORCA
+     */
+    newVelocityX: number;
+    /**
+     * @zh ORCA 计算的新速度 Y
+     * @en New velocity Y computed by ORCA
+     */
+    newVelocityY: number;
+    /**
+     * @zh 是否启用避让
+     * @en Whether avoidance is enabled
+     */
+    enabled: boolean;
+    /**
+     * @zh 是否自动应用新速度
+     * @en Whether to automatically apply new velocity
+     *
+     * @zh 如果为 true，系统会在计算后自动将 newVelocity 赋值给 velocity
+     * @en If true, system will automatically assign newVelocity to velocity after computation
+     */
+    autoApplyVelocity: boolean;
+    /**
+     * @zh 设置位置
+     * @en Set position
+     */
+    setPosition(x: number, y: number): void;
+    /**
+     * @zh 设置当前速度
+     * @en Set current velocity
+     */
+    setVelocity(x: number, y: number): void;
+    /**
+     * @zh 设置首选速度
+     * @en Set preferred velocity
+     */
+    setPreferredVelocity(x: number, y: number): void;
+    /**
+     * @zh 设置首选速度朝向目标
+     * @en Set preferred velocity towards target
+     *
+     * @param targetX - @zh 目标 X @en Target X
+     * @param targetY - @zh 目标 Y @en Target Y
+     * @param currentX - @zh 当前 X（可选，默认使用 positionX）@en Current X (optional, defaults to positionX)
+     * @param currentY - @zh 当前 Y（可选，默认使用 positionY）@en Current Y (optional, defaults to positionY)
+     */
+    setPreferredVelocityTowards(targetX: number, targetY: number, currentX?: number, currentY?: number): void;
+    /**
+     * @zh 应用 ORCA 计算的新速度
+     * @en Apply new velocity computed by ORCA
+     */
+    applyNewVelocity(): void;
+    /**
+     * @zh 获取新速度的长度
+     * @en Get length of new velocity
+     */
+    getNewSpeed(): number;
+    /**
+     * @zh 获取当前速度的长度
+     * @en Get length of current velocity
+     */
+    getCurrentSpeed(): number;
+    /**
+     * @zh 停止代理
+     * @en Stop the agent
+     */
+    stop(): void;
+    /**
+     * @zh 重置组件状态
+     * @en Reset component state
+     */
+    reset(): void;
+    /**
+     * @zh 组件从实体移除时调用
+     * @en Called when component is removed from entity
+     */
+    onRemovedFromEntity(): void;
+}
+
+/**
+ * @zh 避让世界组件
+ * @en Avoidance World Component
+ */
+
+/**
+ * @zh 避让世界组件
+ * @en Avoidance World Component
+ *
+ * @zh 挂载在场景实体上，持有 ORCA 求解器和静态障碍物
+ * @en Attached to scene entity, holds ORCA solver and static obstacles
+ *
+ * @example
+ * ```typescript
+ * const worldEntity = scene.createEntity('AvoidanceWorld');
+ * const world = worldEntity.addComponent(new AvoidanceWorldComponent());
+ *
+ * // 添加静态障碍物（墙壁）
+ * world.addObstacle({
+ *     vertices: [
+ *         { x: 0, y: 0 },
+ *         { x: 10, y: 0 },
+ *         { x: 10, y: 1 },
+ *         { x: 0, y: 1 }
+ *     ]
+ * });
+ *
+ * // LocalAvoidanceSystem 会自动使用此组件
+ * ```
+ */
+declare class AvoidanceWorldComponent extends Component {
+    /**
+     * @zh 默认时间视野（代理）
+     * @en Default time horizon for agents
+     */
+    defaultTimeHorizon: number;
+    /**
+     * @zh 默认时间视野（障碍物）
+     * @en Default time horizon for obstacles
+     */
+    defaultTimeHorizonObst: number;
+    /**
+     * @zh 时间步长
+     * @en Time step
+     */
+    timeStep: number;
+    /**
+     * @zh ORCA 求解器实例
+     * @en ORCA solver instance
+     */
+    solver: ORCASolver | null;
+    /**
+     * @zh KD-Tree 实例
+     * @en KD-Tree instance
+     */
+    kdTree: KDTree | null;
+    /**
+     * @zh 静态障碍物列表
+     * @en List of static obstacles
+     */
+    obstacles: IObstacle[];
+    /**
+     * @zh 是否已初始化
+     * @en Whether initialized
+     */
+    initialized: boolean;
+    /**
+     * @zh 当前代理数量
+     * @en Current agent count
+     */
+    agentCount: number;
+    /**
+     * @zh 本帧处理的代理数
+     * @en Agents processed this frame
+     */
+    agentsProcessedThisFrame: number;
+    /**
+     * @zh 本帧 ORCA 计算耗时（毫秒）
+     * @en ORCA computation time this frame (ms)
+     */
+    computeTimeMs: number;
+    /**
+     * @zh 获取 ORCA 配置
+     * @en Get ORCA configuration
+     */
+    getConfig(): IORCASolverConfig;
+    /**
+     * @zh 添加静态障碍物
+     * @en Add static obstacle
+     *
+     * @param obstacle - @zh 障碍物（顶点列表，逆时针顺序）@en Obstacle (vertex list, counter-clockwise)
+     */
+    addObstacle(obstacle: IObstacle): void;
+    /**
+     * @zh 添加矩形障碍物
+     * @en Add rectangular obstacle
+     *
+     * @param x - @zh 左下角 X @en Bottom-left X
+     * @param y - @zh 左下角 Y @en Bottom-left Y
+     * @param width - @zh 宽度 @en Width
+     * @param height - @zh 高度 @en Height
+     */
+    addRectObstacle(x: number, y: number, width: number, height: number): void;
+    /**
+     * @zh 移除所有障碍物
+     * @en Remove all obstacles
+     */
+    clearObstacles(): void;
+    /**
+     * @zh 重置统计信息
+     * @en Reset statistics
+     */
+    resetStats(): void;
+    /**
+     * @zh 组件从实体移除时调用
+     * @en Called when component is removed from entity
+     */
+    onRemovedFromEntity(): void;
+}
+
+/**
+ * @zh 局部避让系统
+ * @en Local Avoidance System
+ */
+
+/**
+ * @zh 局部避让系统
+ * @en Local Avoidance System
+ *
+ * @zh 使用 ORCA 算法计算代理的避让速度
+ * @en Uses ORCA algorithm to compute avoidance velocities for agents
+ *
+ * @example
+ * ```typescript
+ * // 添加系统到场景
+ * scene.addSystem(new LocalAvoidanceSystem());
+ *
+ * // 创建避让世界（可选，用于静态障碍物）
+ * const worldEntity = scene.createEntity('AvoidanceWorld');
+ * worldEntity.addComponent(new AvoidanceWorldComponent());
+ *
+ * // 创建代理
+ * const agent = scene.createEntity('Agent');
+ * const avoidance = agent.addComponent(new AvoidanceAgentComponent());
+ *
+ * // 可选：同时添加寻路代理，系统会自动同步位置
+ * agent.addComponent(new PathfindingAgentComponent());
+ *
+ * // 每帧设置首选速度（朝向目标）
+ * avoidance.setPreferredVelocityTowards(targetX, targetY);
+ *
+ * // 系统计算后，newVelocity 会被更新
+ * // 如果 autoApplyVelocity = true，velocity 也会自动更新
+ * ```
+ */
+declare class LocalAvoidanceSystem extends EntitySystem {
+    private worldEntity;
+    private worldComponent;
+    private solver;
+    private kdTree;
+    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 world entity
+     */
+    private findWorldEntity;
+    /**
+     * @zh 初始化求解器
+     * @en Initialize solver
+     */
+    private initializeSolver;
+    /**
+     * @zh 收集代理数据
+     * @en Collect agent data
+     */
+    private collectAgentData;
+}
+
+export { AvoidanceAgentComponent, AvoidanceWorldComponent, LocalAvoidanceSystem, PathfindingAgentComponent, PathfindingMapComponent, type PathfindingMapType, PathfindingSystem };