@esengine/pathfinding 12.1.2 → 13.1.0

package/dist/{chunk-GTFFYRZM.js.map → chunk-YKA3PWU3.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/core/IIncrementalPathfinding.ts"],"sourcesContent":["/**\n * @zh 增量寻路系统接口\n * @en Incremental Pathfinding System Interfaces\n */\n\nimport type { IPoint, IPathResult, IPathfindingOptions, IPathfindingMap } from './IPathfinding';\n\n// =============================================================================\n// 状态枚举 | State Enum\n// =============================================================================\n\n/**\n * @zh 增量寻路状态\n * @en Incremental pathfinding state\n */\nexport enum PathfindingState {\n    /** @zh 空闲，等待请求 @en Idle, waiting for request */\n    Idle = 'idle',\n    /** @zh 正在搜索中 @en Search in progress */\n    InProgress = 'in_progress',\n    /** @zh 已暂停 @en Paused */\n    Paused = 'paused',\n    /** @zh 搜索完成，找到路径 @en Completed, path found */\n    Completed = 'completed',\n    /** @zh 搜索失败，无法找到路径 @en Failed, no path found */\n    Failed = 'failed',\n    /** @zh 已取消 @en Cancelled */\n    Cancelled = 'cancelled'\n}\n\n// =============================================================================\n// 请求和进度接口 | Request and Progress Interfaces\n// =============================================================================\n\n/**\n * @zh 增量寻路请求\n * @en Incremental pathfinding request\n */\nexport interface IPathRequest {\n    /**\n     * @zh 请求唯一标识符\n     * @en Unique request identifier\n     */\n    readonly id: number;\n\n    /**\n     * @zh 起点 X 坐标\n     * @en Start X coordinate\n     */\n    readonly startX: number;\n\n    /**\n     * @zh 起点 Y 坐标\n     * @en Start Y coordinate\n     */\n    readonly startY: number;\n\n    /**\n     * @zh 终点 X 坐标\n     * @en End X coordinate\n     */\n    readonly endX: number;\n\n    /**\n     * @zh 终点 Y 坐标\n     * @en End Y coordinate\n     */\n    readonly endY: number;\n\n    /**\n     * @zh 寻路配置选项\n     * @en Pathfinding options\n     */\n    readonly options?: IPathfindingOptions;\n\n    /**\n     * @zh 优先级（数值越小优先级越高）\n     * @en Priority (lower number = higher priority)\n     */\n    readonly priority: number;\n\n    /**\n     * @zh 创建时间戳\n     * @en Creation timestamp\n     */\n    readonly createdAt: number;\n}\n\n/**\n * @zh 增量寻路进度\n * @en Incremental pathfinding progress\n */\nexport interface IPathProgress {\n    /**\n     * @zh 当前寻路状态\n     * @en Current pathfinding state\n     */\n    readonly state: PathfindingState;\n\n    /**\n     * @zh 已搜索的节点数量\n     * @en Number of nodes searched\n     */\n    readonly nodesSearched: number;\n\n    /**\n     * @zh 开放列表当前大小\n     * @en Current open list size\n     */\n    readonly openListSize: number;\n\n    /**\n     * @zh 估计的搜索进度 (0-1)\n     * @en Estimated search progress (0-1)\n     */\n    readonly estimatedProgress: number;\n\n    /**\n     * @zh 当前最佳部分路径（可选）\n     * @en Current best partial path (optional)\n     */\n    readonly partialPath?: readonly IPoint[];\n}\n\n/**\n * @zh 增量寻路结果（扩展自 IPathResult）\n * @en Incremental pathfinding result (extends IPathResult)\n */\nexport interface IIncrementalPathResult extends IPathResult {\n    /**\n     * @zh 关联的请求 ID\n     * @en Associated request ID\n     */\n    readonly requestId: number;\n\n    /**\n     * @zh 完成搜索所用的帧数\n     * @en Number of frames used to complete search\n     */\n    readonly framesUsed: number;\n\n    /**\n     * @zh 是否为部分路径（未到达终点）\n     * @en Whether this is a partial path (not reaching goal)\n     */\n    readonly isPartial: boolean;\n}\n\n// =============================================================================\n// 增量寻路器接口 | Incremental Pathfinder Interface\n// =============================================================================\n\n/**\n * @zh 增量寻路请求选项\n * @en Incremental pathfinding request options\n */\nexport interface IIncrementalPathfindingOptions extends IPathfindingOptions {\n    /**\n     * @zh 优先级（数值越小优先级越高，默认 50）\n     * @en Priority (lower = higher, default 50)\n     */\n    priority?: number;\n}\n\n/**\n * @zh 增量寻路器接口\n * @en Incremental pathfinder interface\n *\n * @zh 支持时间切片的寻路器，可跨多帧执行搜索\n * @en Pathfinder with time slicing support, can execute search across multiple frames\n */\nexport interface IIncrementalPathfinder {\n    /**\n     * @zh 请求寻路（非阻塞）\n     * @en Request pathfinding (non-blocking)\n     *\n     * @param startX - @zh 起点 X 坐标 @en Start X coordinate\n     * @param startY - @zh 起点 Y 坐标 @en Start Y coordinate\n     * @param endX - @zh 终点 X 坐标 @en End X coordinate\n     * @param endY - @zh 终点 Y 坐标 @en End Y coordinate\n     * @param options - @zh 寻路选项 @en Pathfinding options\n     * @returns @zh 寻路请求对象 @en Path request object\n     */\n    requestPath(\n        startX: number,\n        startY: number,\n        endX: number,\n        endY: number,\n        options?: IIncrementalPathfindingOptions\n    ): IPathRequest;\n\n    /**\n     * @zh 执行一步搜索\n     * @en Execute one step of search\n     *\n     * @param requestId - @zh 请求 ID @en Request ID\n     * @param maxIterations - @zh 本步最大迭代次数 @en Maximum iterations this step\n     * @returns @zh 当前进度 @en Current progress\n     */\n    step(requestId: number, maxIterations: number): IPathProgress;\n\n    /**\n     * @zh 暂停寻路\n     * @en Pause pathfinding\n     *\n     * @param requestId - @zh 请求 ID @en Request ID\n     */\n    pause(requestId: number): void;\n\n    /**\n     * @zh 恢复寻路\n     * @en Resume pathfinding\n     *\n     * @param requestId - @zh 请求 ID @en Request ID\n     */\n    resume(requestId: number): void;\n\n    /**\n     * @zh 取消寻路\n     * @en Cancel pathfinding\n     *\n     * @param requestId - @zh 请求 ID @en Request ID\n     */\n    cancel(requestId: number): void;\n\n    /**\n     * @zh 获取寻路结果（仅当状态为 Completed 或 Failed 时可用）\n     * @en Get pathfinding result (only available when state is Completed or Failed)\n     *\n     * @param requestId - @zh 请求 ID @en Request ID\n     * @returns @zh 寻路结果或 null @en Path result or null\n     */\n    getResult(requestId: number): IIncrementalPathResult | null;\n\n    /**\n     * @zh 获取当前进度\n     * @en Get current progress\n     *\n     * @param requestId - @zh 请求 ID @en Request ID\n     * @returns @zh 当前进度或 null @en Current progress or null\n     */\n    getProgress(requestId: number): IPathProgress | null;\n\n    /**\n     * @zh 清理已完成的请求（释放内存）\n     * @en Clean up completed request (release memory)\n     *\n     * @param requestId - @zh 请求 ID @en Request ID\n     */\n    cleanup(requestId: number): void;\n\n    /**\n     * @zh 通知障碍物变化（用于动态重规划）\n     * @en Notify obstacle change (for dynamic replanning)\n     *\n     * @param minX - @zh 变化区域最小 X @en Changed area min X\n     * @param minY - @zh 变化区域最小 Y @en Changed area min Y\n     * @param maxX - @zh 变化区域最大 X @en Changed area max X\n     * @param maxY - @zh 变化区域最大 Y @en Changed area max Y\n     */\n    notifyObstacleChange(\n        minX: number,\n        minY: number,\n        maxX: number,\n        maxY: number\n    ): void;\n\n    /**\n     * @zh 清理所有请求\n     * @en Clear all requests\n     */\n    clear(): void;\n}\n\n// =============================================================================\n// 路径验证接口 | Path Validation Interface\n// =============================================================================\n\n/**\n * @zh 路径验证结果\n * @en Path validation result\n */\nexport interface IPathValidationResult {\n    /**\n     * @zh 路径是否有效\n     * @en Whether the path is valid\n     */\n    readonly valid: boolean;\n\n    /**\n     * @zh 第一个无效点的索引（-1 表示全部有效）\n     * @en Index of first invalid point (-1 if all valid)\n     */\n    readonly invalidIndex: number;\n}\n\n/**\n * @zh 路径验证器接口\n * @en Path validator interface\n */\nexport interface IPathValidator {\n    /**\n     * @zh 验证路径段的有效性\n     * @en Validate path segment validity\n     *\n     * @param path - @zh 要验证的路径 @en Path to validate\n     * @param fromIndex - @zh 起始索引 @en Start index\n     * @param toIndex - @zh 结束索引 @en End index\n     * @param map - @zh 地图实例 @en Map instance\n     * @returns @zh 验证结果 @en Validation result\n     */\n    validatePath(\n        path: readonly IPoint[],\n        fromIndex: number,\n        toIndex: number,\n        map: IPathfindingMap\n    ): IPathValidationResult;\n}\n\n// =============================================================================\n// 动态重规划配置 | Dynamic Replanning Configuration\n// =============================================================================\n\n/**\n * @zh 动态重规划配置\n * @en Dynamic replanning configuration\n */\nexport interface IReplanningConfig {\n    /**\n     * @zh 是否启用动态重规划\n     * @en Whether dynamic replanning is enabled\n     */\n    enabled: boolean;\n\n    /**\n     * @zh 路径检查间隔（帧数）\n     * @en Path check interval (in frames)\n     */\n    checkInterval: number;\n\n    /**\n     * @zh 触发重规划的距离阈值\n     * @en Distance threshold to trigger replanning\n     */\n    distanceThreshold: number;\n\n    /**\n     * @zh 向前探测的距离（路径点数）\n     * @en Lookahead distance (in path points)\n     */\n    lookaheadDistance: number;\n}\n\n/**\n * @zh 默认重规划配置\n * @en Default replanning configuration\n */\nexport const DEFAULT_REPLANNING_CONFIG: IReplanningConfig = {\n    enabled: true,\n    checkInterval: 10,\n    distanceThreshold: 2,\n    lookaheadDistance: 5\n};\n\n// =============================================================================\n// 空进度常量 | Empty Progress Constant\n// =============================================================================\n\n/**\n * @zh 空进度（用于无效请求）\n * @en Empty progress (for invalid requests)\n */\nexport const EMPTY_PROGRESS: IPathProgress = {\n    state: PathfindingState.Idle,\n    nodesSearched: 0,\n    openListSize: 0,\n    estimatedProgress: 0\n};\n"],"mappings":";;;;;;AAeO,IAAKA,mBAAAA,0BAAAA,mBAAAA;AACsC,EAAAA,kBAAA,MAAA,IAAA;AAET,EAAAA,kBAAA,YAAA,IAAA;AAEd,EAAAA,kBAAA,QAAA,IAAA;AAEqB,EAAAA,kBAAA,WAAA,IAAA;AAEE,EAAAA,kBAAA,QAAA,IAAA;AAEpB,EAAAA,kBAAA,WAAA,IAAA;SAXlBA;;AAsVL,IAAMC,4BAA+C;EACxDC,SAAS;EACTC,eAAe;EACfC,mBAAmB;EACnBC,mBAAmB;AACvB;AAUO,IAAMC,iBAAgC;EACzCC,OAAK;EACLC,eAAe;EACfC,cAAc;EACdC,mBAAmB;AACvB;","names":["PathfindingState","DEFAULT_REPLANNING_CONFIG","enabled","checkInterval","distanceThreshold","lookaheadDistance","EMPTY_PROGRESS","state","nodesSearched","openListSize","estimatedProgress"]}
+{"version":3,"sources":["../src/core/IIncrementalPathfinding.ts"],"sourcesContent":["/**\n * @zh 增量寻路系统接口\n * @en Incremental Pathfinding System Interfaces\n */\n\nimport type { IPoint, IPathResult, IPathfindingOptions, IPathfindingMap } from './IPathfinding';\n\n// =============================================================================\n// 状态枚举 | State Enum\n// =============================================================================\n\n/**\n * @zh 增量寻路状态\n * @en Incremental pathfinding state\n */\nexport enum PathfindingState {\n    /** @zh 空闲，等待请求 @en Idle, waiting for request */\n    Idle = 'idle',\n    /** @zh 正在搜索中 @en Search in progress */\n    InProgress = 'in_progress',\n    /** @zh 已暂停 @en Paused */\n    Paused = 'paused',\n    /** @zh 搜索完成，找到路径 @en Completed, path found */\n    Completed = 'completed',\n    /** @zh 搜索失败，无法找到路径 @en Failed, no path found */\n    Failed = 'failed',\n    /** @zh 已取消 @en Cancelled */\n    Cancelled = 'cancelled'\n}\n\n// =============================================================================\n// 请求和进度接口 | Request and Progress Interfaces\n// =============================================================================\n\n/**\n * @zh 增量寻路请求\n * @en Incremental pathfinding request\n */\nexport interface IPathRequest {\n    /**\n     * @zh 请求唯一标识符\n     * @en Unique request identifier\n     */\n    readonly id: number;\n\n    /**\n     * @zh 起点 X 坐标\n     * @en Start X coordinate\n     */\n    readonly startX: number;\n\n    /**\n     * @zh 起点 Y 坐标\n     * @en Start Y coordinate\n     */\n    readonly startY: number;\n\n    /**\n     * @zh 终点 X 坐标\n     * @en End X coordinate\n     */\n    readonly endX: number;\n\n    /**\n     * @zh 终点 Y 坐标\n     * @en End Y coordinate\n     */\n    readonly endY: number;\n\n    /**\n     * @zh 寻路配置选项\n     * @en Pathfinding options\n     */\n    readonly options?: IPathfindingOptions;\n\n    /**\n     * @zh 优先级（数值越小优先级越高）\n     * @en Priority (lower number = higher priority)\n     */\n    readonly priority: number;\n\n    /**\n     * @zh 创建时间戳\n     * @en Creation timestamp\n     */\n    readonly createdAt: number;\n}\n\n/**\n * @zh 增量寻路进度\n * @en Incremental pathfinding progress\n */\nexport interface IPathProgress {\n    /**\n     * @zh 当前寻路状态\n     * @en Current pathfinding state\n     */\n    readonly state: PathfindingState;\n\n    /**\n     * @zh 已搜索的节点数量\n     * @en Number of nodes searched\n     */\n    readonly nodesSearched: number;\n\n    /**\n     * @zh 开放列表当前大小\n     * @en Current open list size\n     */\n    readonly openListSize: number;\n\n    /**\n     * @zh 估计的搜索进度 (0-1)\n     * @en Estimated search progress (0-1)\n     */\n    readonly estimatedProgress: number;\n\n    /**\n     * @zh 当前最佳部分路径（可选）\n     * @en Current best partial path (optional)\n     */\n    readonly partialPath?: readonly IPoint[];\n}\n\n/**\n * @zh 增量寻路结果（扩展自 IPathResult）\n * @en Incremental pathfinding result (extends IPathResult)\n */\nexport interface IIncrementalPathResult extends IPathResult {\n    /**\n     * @zh 关联的请求 ID\n     * @en Associated request ID\n     */\n    readonly requestId: number;\n\n    /**\n     * @zh 完成搜索所用的帧数\n     * @en Number of frames used to complete search\n     */\n    readonly framesUsed: number;\n\n    /**\n     * @zh 是否为部分路径（未到达终点）\n     * @en Whether this is a partial path (not reaching goal)\n     */\n    readonly isPartial: boolean;\n}\n\n// =============================================================================\n// 增量寻路器接口 | Incremental Pathfinder Interface\n// =============================================================================\n\n/**\n * @zh 增量寻路请求选项\n * @en Incremental pathfinding request options\n */\nexport interface IIncrementalPathfindingOptions extends IPathfindingOptions {\n    /**\n     * @zh 优先级（数值越小优先级越高，默认 50）\n     * @en Priority (lower = higher, default 50)\n     */\n    priority?: number;\n}\n\n/**\n * @zh 增量寻路器接口\n * @en Incremental pathfinder interface\n *\n * @zh 支持时间切片的寻路器，可跨多帧执行搜索\n * @en Pathfinder with time slicing support, can execute search across multiple frames\n */\nexport interface IIncrementalPathfinder {\n    /**\n     * @zh 请求寻路（非阻塞）\n     * @en Request pathfinding (non-blocking)\n     *\n     * @param startX - @zh 起点 X 坐标 @en Start X coordinate\n     * @param startY - @zh 起点 Y 坐标 @en Start Y coordinate\n     * @param endX - @zh 终点 X 坐标 @en End X coordinate\n     * @param endY - @zh 终点 Y 坐标 @en End Y coordinate\n     * @param options - @zh 寻路选项 @en Pathfinding options\n     * @returns @zh 寻路请求对象 @en Path request object\n     */\n    requestPath(\n        startX: number,\n        startY: number,\n        endX: number,\n        endY: number,\n        options?: IIncrementalPathfindingOptions\n    ): IPathRequest;\n\n    /**\n     * @zh 执行一步搜索\n     * @en Execute one step of search\n     *\n     * @param requestId - @zh 请求 ID @en Request ID\n     * @param maxIterations - @zh 本步最大迭代次数 @en Maximum iterations this step\n     * @returns @zh 当前进度 @en Current progress\n     */\n    step(requestId: number, maxIterations: number): IPathProgress;\n\n    /**\n     * @zh 暂停寻路\n     * @en Pause pathfinding\n     *\n     * @param requestId - @zh 请求 ID @en Request ID\n     */\n    pause(requestId: number): void;\n\n    /**\n     * @zh 恢复寻路\n     * @en Resume pathfinding\n     *\n     * @param requestId - @zh 请求 ID @en Request ID\n     */\n    resume(requestId: number): void;\n\n    /**\n     * @zh 取消寻路\n     * @en Cancel pathfinding\n     *\n     * @param requestId - @zh 请求 ID @en Request ID\n     */\n    cancel(requestId: number): void;\n\n    /**\n     * @zh 获取寻路结果（仅当状态为 Completed 或 Failed 时可用）\n     * @en Get pathfinding result (only available when state is Completed or Failed)\n     *\n     * @param requestId - @zh 请求 ID @en Request ID\n     * @returns @zh 寻路结果或 null @en Path result or null\n     */\n    getResult(requestId: number): IIncrementalPathResult | null;\n\n    /**\n     * @zh 获取当前进度\n     * @en Get current progress\n     *\n     * @param requestId - @zh 请求 ID @en Request ID\n     * @returns @zh 当前进度或 null @en Current progress or null\n     */\n    getProgress(requestId: number): IPathProgress | null;\n\n    /**\n     * @zh 清理已完成的请求（释放内存）\n     * @en Clean up completed request (release memory)\n     *\n     * @param requestId - @zh 请求 ID @en Request ID\n     */\n    cleanup(requestId: number): void;\n\n    /**\n     * @zh 通知障碍物变化（用于动态重规划）\n     * @en Notify obstacle change (for dynamic replanning)\n     *\n     * @param minX - @zh 变化区域最小 X @en Changed area min X\n     * @param minY - @zh 变化区域最小 Y @en Changed area min Y\n     * @param maxX - @zh 变化区域最大 X @en Changed area max X\n     * @param maxY - @zh 变化区域最大 Y @en Changed area max Y\n     */\n    notifyObstacleChange(\n        minX: number,\n        minY: number,\n        maxX: number,\n        maxY: number\n    ): void;\n\n    /**\n     * @zh 清理所有请求\n     * @en Clear all requests\n     */\n    clear(): void;\n}\n\n// =============================================================================\n// 路径验证接口 | Path Validation Interface\n// =============================================================================\n\n/**\n * @zh 路径验证结果\n * @en Path validation result\n */\nexport interface IPathValidationResult {\n    /**\n     * @zh 路径是否有效\n     * @en Whether the path is valid\n     */\n    readonly valid: boolean;\n\n    /**\n     * @zh 第一个无效点的索引（-1 表示全部有效）\n     * @en Index of first invalid point (-1 if all valid)\n     */\n    readonly invalidIndex: number;\n}\n\n/**\n * @zh 路径验证器接口\n * @en Path validator interface\n */\nexport interface IPathValidator {\n    /**\n     * @zh 验证路径段的有效性\n     * @en Validate path segment validity\n     *\n     * @param path - @zh 要验证的路径 @en Path to validate\n     * @param fromIndex - @zh 起始索引 @en Start index\n     * @param toIndex - @zh 结束索引 @en End index\n     * @param map - @zh 地图实例 @en Map instance\n     * @returns @zh 验证结果 @en Validation result\n     */\n    validatePath(\n        path: readonly IPoint[],\n        fromIndex: number,\n        toIndex: number,\n        map: IPathfindingMap\n    ): IPathValidationResult;\n}\n\n// =============================================================================\n// 动态重规划配置 | Dynamic Replanning Configuration\n// =============================================================================\n\n/**\n * @zh 动态重规划配置\n * @en Dynamic replanning configuration\n */\nexport interface IReplanningConfig {\n    /**\n     * @zh 是否启用动态重规划\n     * @en Whether dynamic replanning is enabled\n     */\n    enabled: boolean;\n\n    /**\n     * @zh 路径检查间隔（帧数）\n     * @en Path check interval (in frames)\n     */\n    checkInterval: number;\n\n    /**\n     * @zh 触发重规划的距离阈值\n     * @en Distance threshold to trigger replanning\n     */\n    distanceThreshold: number;\n\n    /**\n     * @zh 向前探测的距离（路径点数）\n     * @en Lookahead distance (in path points)\n     */\n    lookaheadDistance: number;\n}\n\n/**\n * @zh 默认重规划配置\n * @en Default replanning configuration\n */\nexport const DEFAULT_REPLANNING_CONFIG: IReplanningConfig = {\n    enabled: true,\n    checkInterval: 10,\n    distanceThreshold: 2,\n    lookaheadDistance: 5\n};\n\n// =============================================================================\n// 空进度常量 | Empty Progress Constant\n// =============================================================================\n\n/**\n * @zh 空进度（用于无效请求）\n * @en Empty progress (for invalid requests)\n */\nexport const EMPTY_PROGRESS: IPathProgress = {\n    state: PathfindingState.Idle,\n    nodesSearched: 0,\n    openListSize: 0,\n    estimatedProgress: 0\n};\n"],"mappings":";AAeO,IAAKA,mBAAAA,0BAAAA,mBAAAA;AACsC,EAAAA,kBAAA,MAAA,IAAA;AAET,EAAAA,kBAAA,YAAA,IAAA;AAEd,EAAAA,kBAAA,QAAA,IAAA;AAEqB,EAAAA,kBAAA,WAAA,IAAA;AAEE,EAAAA,kBAAA,QAAA,IAAA;AAEpB,EAAAA,kBAAA,WAAA,IAAA;SAXlBA;;AAsVL,IAAMC,4BAA+C;EACxDC,SAAS;EACTC,eAAe;EACfC,mBAAmB;EACnBC,mBAAmB;AACvB;AAUO,IAAMC,iBAAgC;EACzCC,OAAK;EACLC,eAAe;EACfC,cAAc;EACdC,mBAAmB;AACvB;","names":["PathfindingState","DEFAULT_REPLANNING_CONFIG","enabled","checkInterval","distanceThreshold","lookaheadDistance","EMPTY_PROGRESS","state","nodesSearched","openListSize","estimatedProgress"]}

package/dist/ecs.d.ts

@@ -1,5 +1,7 @@
 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 { O as ORCASolver, K as KDTree, b as IObstacle, c as IORCASolverConfig } from './KDTree-2rs2EXvm.js';
+import '@esengine/ecs-framework-math';
 
 /**
  * @zh 寻路代理组件
@@ -500,4 +502,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 };