@esengine/pathfinding 12.1.2 → 13.1.0

package/dist/KDTree-2rs2EXvm.d.ts

@@ -0,0 +1,407 @@
+import { IVector2 } from '@esengine/ecs-framework-math';
+
+/**
+ * @zh ORCA 局部避让接口定义
+ * @en ORCA Local Avoidance Interface Definitions
+ */
+
+/**
+ * @zh ORCA 约束线（半平面）
+ * @en ORCA constraint line (half-plane)
+ *
+ * @zh 约束线定义了一个半平面，代理的速度必须在允许的一侧
+ * @en A constraint line defines a half-plane, agent's velocity must be on the allowed side
+ */
+interface IORCALine {
+    /**
+     * @zh 线上的一点
+     * @en A point on the line
+     */
+    point: IVector2;
+    /**
+     * @zh 线的方向向量（单位向量，允许区域在左侧）
+     * @en Direction vector of the line (unit vector, allowed region is on the left)
+     */
+    direction: IVector2;
+}
+/**
+ * @zh 避让代理数据
+ * @en Avoidance agent data
+ *
+ * @zh 包含计算 ORCA 所需的所有代理信息
+ * @en Contains all agent information needed for ORCA computation
+ */
+interface IAvoidanceAgent {
+    /**
+     * @zh 代理唯一标识
+     * @en Unique identifier for the agent
+     */
+    id: number;
+    /**
+     * @zh 当前位置
+     * @en Current position
+     */
+    position: IVector2;
+    /**
+     * @zh 当前速度
+     * @en Current velocity
+     */
+    velocity: IVector2;
+    /**
+     * @zh 首选速度（通常指向目标方向）
+     * @en Preferred velocity (usually towards target)
+     */
+    preferredVelocity: IVector2;
+    /**
+     * @zh 代理半径
+     * @en Agent radius
+     */
+    radius: number;
+    /**
+     * @zh 最大速度
+     * @en Maximum speed
+     */
+    maxSpeed: number;
+    /**
+     * @zh 邻居检测距离
+     * @en Neighbor detection distance
+     */
+    neighborDist: number;
+    /**
+     * @zh 最大邻居数量
+     * @en Maximum number of neighbors to consider
+     */
+    maxNeighbors: number;
+    /**
+     * @zh 代理避让时间视野（秒）
+     * @en Time horizon for agent avoidance (seconds)
+     *
+     * @zh 更大的值会让代理更早开始避让
+     * @en Larger values make agents start avoiding earlier
+     */
+    timeHorizon: number;
+    /**
+     * @zh 障碍物避让时间视野（秒）
+     * @en Time horizon for obstacle avoidance (seconds)
+     */
+    timeHorizonObst: number;
+}
+/**
+ * @zh 静态障碍物顶点（链表节点）
+ * @en Static obstacle vertex (linked list node)
+ */
+interface IObstacleVertex {
+    /**
+     * @zh 顶点位置
+     * @en Vertex position
+     */
+    point: IVector2;
+    /**
+     * @zh 下一个顶点（构成障碍物边，循环链表）
+     * @en Next vertex (forms obstacle edge, circular linked list)
+     */
+    next: IObstacleVertex;
+    /**
+     * @zh 前一个顶点（循环链表）
+     * @en Previous vertex (circular linked list)
+     */
+    previous: IObstacleVertex;
+    /**
+     * @zh 边的单位方向向量（从此顶点指向 next 顶点）
+     * @en Unit direction vector of edge (from this vertex towards next vertex)
+     */
+    direction: IVector2;
+    /**
+     * @zh 是否为凸顶点
+     * @en Whether this is a convex vertex
+     */
+    isConvex: boolean;
+    /**
+     * @zh 顶点 ID（用于调试）
+     * @en Vertex ID (for debugging)
+     */
+    id: number;
+}
+/**
+ * @zh 静态障碍物（多边形）
+ * @en Static obstacle (polygon)
+ *
+ * @zh 重要：顶点必须按逆时针（CCW）顺序排列（在 Y 轴向上的坐标系中）
+ * @en Important: Vertices must be in counter-clockwise (CCW) order (in Y-axis up coordinate system)
+ *
+ * @zh 可以使用 math 库中的 Polygon.ensureCCW() 确保正确顺序
+ * @en Use Polygon.ensureCCW() from math library to ensure correct order
+ *
+ * @zh 在 Y 轴向下的坐标系（如 Canvas）中，视觉上的 CCW 需要传入 yAxisDown=true
+ * @en In Y-axis down coordinate system (like Canvas), use yAxisDown=true for visual CCW
+ *
+ * @example
+ * ```typescript
+ * import { Polygon } from '@esengine/ecs-framework-math';
+ *
+ * // 标准 Y 轴向上坐标系
+ * const obstacle: IObstacle = {
+ *     vertices: Polygon.ensureCCW(myVertices)
+ * };
+ *
+ * // Canvas/屏幕坐标系（Y 轴向下）
+ * const obstacle: IObstacle = {
+ *     vertices: Polygon.ensureCCW(myVertices, true)
+ * };
+ * ```
+ */
+interface IObstacle {
+    /**
+     * @zh 顶点列表（逆时针顺序，Y 轴向上坐标系）
+     * @en Vertex list (counter-clockwise order in Y-axis up coordinate system)
+     */
+    vertices: IVector2[];
+}
+/**
+ * @zh ORCA 求解器配置
+ * @en ORCA solver configuration
+ */
+interface IORCASolverConfig {
+    /**
+     * @zh 默认时间视野（代理）
+     * @en Default time horizon for agents
+     */
+    defaultTimeHorizon?: number;
+    /**
+     * @zh 默认时间视野（障碍物）
+     * @en Default time horizon for obstacles
+     */
+    defaultTimeHorizonObst?: number;
+    /**
+     * @zh 时间步长（用于碰撞响应）
+     * @en Time step (for collision response)
+     */
+    timeStep?: number;
+    /**
+     * @zh 数值精度阈值
+     * @en Numerical precision threshold
+     */
+    epsilon?: number;
+}
+/**
+ * @zh ORCA 求解结果
+ * @en ORCA solve result
+ */
+interface IORCAResult {
+    /**
+     * @zh 计算得到的新速度
+     * @en Computed new velocity
+     */
+    velocity: IVector2;
+    /**
+     * @zh 是否找到可行解
+     * @en Whether a feasible solution was found
+     */
+    feasible: boolean;
+    /**
+     * @zh 生成的 ORCA 约束线数量
+     * @en Number of ORCA lines generated
+     */
+    numLines: number;
+}
+/**
+ * @zh ORCA 求解器接口
+ * @en ORCA solver interface
+ */
+interface IORCASolver {
+    /**
+     * @zh 计算代理的新速度
+     * @en Compute new velocity for agent
+     *
+     * @param agent - @zh 当前代理 @en Current agent
+     * @param neighbors - @zh 邻近代理列表 @en List of neighbor agents
+     * @param obstacles - @zh 静态障碍物列表 @en List of static obstacles
+     * @param deltaTime - @zh 时间步长 @en Time step
+     * @returns @zh 新速度 @en New velocity
+     */
+    computeNewVelocity(agent: IAvoidanceAgent, neighbors: readonly IAvoidanceAgent[], obstacles: readonly IObstacle[], deltaTime: number): IVector2;
+}
+/**
+ * @zh 邻居查询结果
+ * @en Neighbor query result
+ */
+interface INeighborResult {
+    /**
+     * @zh 代理数据
+     * @en Agent data
+     */
+    agent: IAvoidanceAgent;
+    /**
+     * @zh 距离的平方
+     * @en Squared distance
+     */
+    distanceSq: number;
+}
+/**
+ * @zh 空间索引接口（用于快速邻居查询）
+ * @en Spatial index interface (for fast neighbor queries)
+ */
+interface ISpatialIndex {
+    /**
+     * @zh 构建空间索引
+     * @en Build spatial index
+     *
+     * @param agents - @zh 代理列表 @en List of agents
+     */
+    build(agents: readonly IAvoidanceAgent[]): void;
+    /**
+     * @zh 查询指定范围内的邻居
+     * @en Query neighbors within specified range
+     *
+     * @param position - @zh 查询位置 @en Query position
+     * @param radius - @zh 查询半径 @en Query radius
+     * @param maxResults - @zh 最大返回数量 @en Maximum number of results
+     * @param excludeId - @zh 排除的代理 ID @en Agent ID to exclude
+     * @returns @zh 邻居列表（按距离排序）@en List of neighbors (sorted by distance)
+     */
+    queryNeighbors(position: IVector2, radius: number, maxResults: number, excludeId?: number): INeighborResult[];
+    /**
+     * @zh 清空索引
+     * @en Clear the index
+     */
+    clear(): void;
+}
+/**
+ * @zh 默认 ORCA 求解器配置
+ * @en Default ORCA solver configuration
+ */
+declare const DEFAULT_ORCA_CONFIG: Required<IORCASolverConfig>;
+/**
+ * @zh 默认代理参数
+ * @en Default agent parameters
+ */
+declare const DEFAULT_AGENT_PARAMS: {
+    radius: number;
+    maxSpeed: number;
+    neighborDist: number;
+    maxNeighbors: number;
+    timeHorizon: number;
+    timeHorizonObst: number;
+};
+
+/**
+ * @zh ORCA 避让算法求解器
+ * @en ORCA Avoidance Algorithm Solver
+ *
+ * @zh 实现最优互惠碰撞避免（ORCA）算法，用于多代理局部避让
+ * @en Implements Optimal Reciprocal Collision Avoidance (ORCA) algorithm for multi-agent local avoidance
+ */
+
+/**
+ * @zh ORCA 求解器实现
+ * @en ORCA Solver implementation
+ *
+ * @zh 实现最优互惠碰撞避免算法，计算代理的安全速度
+ * @en Implements Optimal Reciprocal Collision Avoidance algorithm to compute safe velocities for agents
+ */
+declare class ORCASolver implements IORCASolver {
+    private readonly config;
+    constructor(config?: IORCASolverConfig);
+    /**
+     * @zh 计算代理的新速度
+     * @en Compute new velocity for agent
+     *
+     * @param agent - @zh 当前代理 @en Current agent
+     * @param neighbors - @zh 邻近代理列表 @en List of neighboring agents
+     * @param obstacles - @zh 障碍物列表 @en List of obstacles
+     * @param deltaTime - @zh 时间步长 @en Time step
+     * @returns @zh 计算得到的新速度 @en Computed new velocity
+     */
+    computeNewVelocity(agent: IAvoidanceAgent, neighbors: readonly IAvoidanceAgent[], obstacles: readonly IObstacle[], deltaTime: number): IVector2;
+    /**
+     * @zh 创建代理间的 ORCA 约束线
+     * @en Create ORCA constraint lines for agent-agent avoidance
+     */
+    private createAgentORCALines;
+    /**
+     * @zh 创建障碍物的 ORCA 约束线
+     * @en Create ORCA constraint lines for obstacle avoidance
+     */
+    private createObstacleORCALines;
+}
+/**
+ * @zh 创建 ORCA 求解器
+ * @en Create ORCA solver
+ *
+ * @param config - @zh 可选配置参数 @en Optional configuration parameters
+ * @returns @zh ORCA 求解器实例 @en ORCA solver instance
+ */
+declare function createORCASolver(config?: IORCASolverConfig): ORCASolver;
+
+/**
+ * @zh KD-Tree 空间索引
+ * @en KD-Tree Spatial Index
+ *
+ * @zh 用于快速查询指定范围内的邻近代理
+ * @en Used for fast neighbor queries within specified range
+ */
+
+/**
+ * @zh KD-Tree 空间索引
+ * @en KD-Tree spatial index
+ *
+ * @zh 每帧重建，支持高效的范围查询
+ * @en Rebuilt every frame, supports efficient range queries
+ */
+declare class KDTree implements ISpatialIndex {
+    private agents;
+    private agentIndices;
+    private nodes;
+    /**
+     * @zh 最大叶节点大小
+     * @en Maximum leaf size
+     */
+    private readonly maxLeafSize;
+    /**
+     * @zh 构建 KD-Tree
+     * @en Build KD-Tree
+     */
+    build(agents: readonly IAvoidanceAgent[]): void;
+    /**
+     * @zh 递归构建 KD-Tree
+     * @en Recursively build KD-Tree
+     */
+    private buildRecursive;
+    /**
+     * @zh 按 X 坐标排序
+     * @en Sort by X coordinate
+     */
+    private sortByX;
+    /**
+     * @zh 按 Y 坐标排序
+     * @en Sort by Y coordinate
+     */
+    private sortByY;
+    /**
+     * @zh 查询邻居
+     * @en Query neighbors
+     */
+    queryNeighbors(position: IVector2, radius: number, maxResults: number, excludeId?: number): INeighborResult[];
+    /**
+     * @zh 递归查询
+     * @en Recursive query
+     */
+    private queryRecursive;
+    /**
+     * @zh 清空索引
+     * @en Clear the index
+     */
+    clear(): void;
+    /**
+     * @zh 获取代理数量
+     * @en Get agent count
+     */
+    get agentCount(): number;
+}
+/**
+ * @zh 创建 KD-Tree
+ * @en Create KD-Tree
+ */
+declare function createKDTree(): KDTree;
+
+export { DEFAULT_ORCA_CONFIG as D, type IORCALine as I, KDTree as K, ORCASolver as O, type IAvoidanceAgent as a, type IObstacle as b, type IORCASolverConfig as c, type IORCAResult as d, type IORCASolver as e, type INeighborResult as f, type ISpatialIndex as g, DEFAULT_AGENT_PARAMS as h, createORCASolver as i, createKDTree as j, type IObstacleVertex as k };

package/dist/LinearProgram-DyD3pI6v.d.ts

@@ -0,0 +1,56 @@
+import { IVector2, Vector2 } from '@esengine/ecs-framework-math';
+import { I as IORCALine } from './KDTree-2rs2EXvm.js';
+
+/**
+ * @zh 2D 线性规划求解器
+ * @en 2D Linear Programming Solver
+ *
+ * @zh 用于 ORCA 算法中的速度优化求解
+ * @en Used for velocity optimization in ORCA algorithm
+ */
+
+/**
+ * @zh 2D 线性规划
+ * @en 2D Linear Programming
+ *
+ * @zh 在多个半平面约束下找到最优速度
+ * @en Find optimal velocity under multiple half-plane constraints
+ *
+ * @param lines - @zh 约束线列表 @en List of constraint lines
+ * @param radius - @zh 最大速度（圆盘半径）@en Maximum speed (disk radius)
+ * @param optVelocity - @zh 首选速度 @en Preferred velocity
+ * @param directionOpt - @zh 是否优化方向 @en Whether to optimize direction
+ * @param result - @zh 结果向量（输出）@en Result vector (output)
+ * @returns @zh 第一个失败的约束索引，如果成功则返回 lines.length @en Index of first failed constraint, or lines.length if successful
+ */
+declare function linearProgram2(lines: readonly IORCALine[], radius: number, optVelocity: IVector2, directionOpt: boolean, result: Vector2): number;
+/**
+ * @zh 3D 线性规划（回退方案）
+ * @en 3D Linear Programming (fallback)
+ *
+ * @zh 当 2D 线性规划失败时，使用此方法找到最小穿透的速度
+ * @en When 2D LP fails, use this to find velocity with minimum penetration
+ *
+ * @param lines - @zh 约束线列表 @en List of constraint lines
+ * @param numObstLines - @zh 障碍物约束线数量 @en Number of obstacle constraint lines
+ * @param beginLine - @zh 开始处理的线索引 @en Index of line to start processing
+ * @param radius - @zh 最大速度 @en Maximum speed
+ * @param result - @zh 结果向量（输入/输出）@en Result vector (input/output)
+ */
+declare function linearProgram3(lines: IORCALine[], numObstLines: number, beginLine: number, radius: number, result: Vector2): void;
+/**
+ * @zh 求解 ORCA 线性规划
+ * @en Solve ORCA Linear Programming
+ *
+ * @zh 综合使用 2D 和 3D 线性规划求解最优速度
+ * @en Use both 2D and 3D LP to solve for optimal velocity
+ *
+ * @param lines - @zh ORCA 约束线列表 @en List of ORCA constraint lines
+ * @param numObstLines - @zh 障碍物约束线数量（优先级更高）@en Number of obstacle lines (higher priority)
+ * @param maxSpeed - @zh 最大速度 @en Maximum speed
+ * @param preferredVelocity - @zh 首选速度 @en Preferred velocity
+ * @returns @zh 计算得到的新速度 @en Computed new velocity
+ */
+declare function solveORCALinearProgram(lines: IORCALine[], numObstLines: number, maxSpeed: number, preferredVelocity: IVector2): Vector2;
+
+export { linearProgram3 as a, linearProgram2 as l, solveORCALinearProgram as s };

package/dist/avoidance.d.ts

@@ -0,0 +1,31 @@
+import { k as IObstacleVertex, b as IObstacle } from './KDTree-2rs2EXvm.js';
+export { h as DEFAULT_AGENT_PARAMS, D as DEFAULT_ORCA_CONFIG, a as IAvoidanceAgent, f as INeighborResult, I as IORCALine, d as IORCAResult, e as IORCASolver, c as IORCASolverConfig, g as ISpatialIndex, K as KDTree, O as ORCASolver, j as createKDTree, i as createORCASolver } from './KDTree-2rs2EXvm.js';
+export { l as linearProgram2, a as linearProgram3, s as solveORCALinearProgram } from './LinearProgram-DyD3pI6v.js';
+import { IVector2 } from '@esengine/ecs-framework-math';
+export { IVector2 } from '@esengine/ecs-framework-math';
+
+/**
+ * @zh 障碍物构建器
+ * @en Obstacle Builder
+ */
+
+/**
+ * @zh 从顶点数组创建障碍物链表
+ * @en Create obstacle linked list from vertex array
+ *
+ * @param vertices - @zh 顶点数组（CCW 顺序）@en Vertex array (CCW order)
+ * @param startId - @zh 起始顶点 ID @en Starting vertex ID
+ */
+declare function createObstacleVertices(vertices: readonly IVector2[], startId?: number): IObstacleVertex[];
+/**
+ * @zh 从障碍物数组创建所有障碍物顶点
+ * @en Create all obstacle vertices from obstacle array
+ */
+declare function buildObstacleVertices(obstacles: readonly IObstacle[]): IObstacleVertex[];
+/**
+ * @zh 确保顶点按逆时针顺序排列
+ * @en Ensure vertices are in counter-clockwise order
+ */
+declare function ensureCCW(vertices: IVector2[], yAxisDown?: boolean): IVector2[];
+
+export { IObstacle, IObstacleVertex, buildObstacleVertices, createObstacleVertices, ensureCCW };

package/dist/avoidance.js

@@ -0,0 +1,31 @@
+import "./chunk-KEYTX37K.js";
+import {
+  DEFAULT_AGENT_PARAMS,
+  DEFAULT_ORCA_CONFIG,
+  KDTree,
+  ORCASolver,
+  buildObstacleVertices,
+  createKDTree,
+  createORCASolver,
+  createObstacleVertices,
+  ensureCCW,
+  linearProgram2,
+  linearProgram3,
+  solveORCALinearProgram
+} from "./chunk-JTZP55BJ.js";
+import "./chunk-T626JPC7.js";
+export {
+  DEFAULT_AGENT_PARAMS,
+  DEFAULT_ORCA_CONFIG,
+  KDTree,
+  ORCASolver,
+  buildObstacleVertices,
+  createKDTree,
+  createORCASolver,
+  createObstacleVertices,
+  ensureCCW,
+  linearProgram2,
+  linearProgram3,
+  solveORCALinearProgram
+};
+//# sourceMappingURL=avoidance.js.map

package/dist/avoidance.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}