@nice2dev/game-engine 1.1.5 → 1.1.7

package/dist/types/systems/NiceNavigation.d.ts

@@ -0,0 +1,307 @@
+/**
+ * NiceNavigation - Game Engine Navigation & Pathfinding System
+ *
+ * Comprehensive navigation system supporting:
+ * - A* Pathfinding
+ * - Navigation meshes (NavMesh)
+ * - Grid-based navigation
+ * - Waypoint graphs
+ * - Dynamic obstacle avoidance
+ * - Agent steering behaviors
+ * - Flow fields
+ * - Hierarchical pathfinding
+ * - Path smoothing
+ *
+ * @packageDocumentation
+ */
+import { EventEmitter } from 'events';
+export type NavMeshId = string;
+export type AgentId = string;
+export type ObstacleId = string;
+export type WaypointId = string;
+export type AreaId = string;
+export type PathfindingAlgorithm = 'astar' | 'dijkstra' | 'bfs' | 'jps';
+export type HeuristicType = 'manhattan' | 'euclidean' | 'chebyshev' | 'octile';
+export interface Vec2 {
+    x: number;
+    y: number;
+}
+export interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+export type CellType = 'walkable' | 'blocked' | 'water' | 'road' | 'grass' | 'custom';
+export interface GridCell {
+    x: number;
+    y: number;
+    type: CellType;
+    cost: number;
+    elevation?: number;
+    areaId?: AreaId;
+    metadata?: Record<string, unknown>;
+}
+export interface NavigationGrid {
+    id: string;
+    width: number;
+    height: number;
+    cellSize: number;
+    origin: Vec2;
+    cells: (GridCell | null)[][];
+    allowDiagonal: boolean;
+    diagonalCost: number;
+    defaultCost: number;
+}
+export interface GridConfig {
+    width: number;
+    height: number;
+    cellSize?: number;
+    origin?: Vec2;
+    allowDiagonal?: boolean;
+    diagonalCost?: number;
+    defaultCost?: number;
+}
+export interface NavMeshVertex {
+    id: number;
+    position: Vec3;
+}
+export interface NavMeshEdge {
+    v1: number;
+    v2: number;
+    portal?: {
+        left: Vec3;
+        right: Vec3;
+    };
+}
+export interface NavMeshPolygon {
+    id: number;
+    vertices: number[];
+    neighbors: number[];
+    center: Vec3;
+    areaId?: AreaId;
+    cost: number;
+}
+export interface NavMesh {
+    id: NavMeshId;
+    vertices: NavMeshVertex[];
+    edges: NavMeshEdge[];
+    polygons: NavMeshPolygon[];
+    bounds: {
+        min: Vec3;
+        max: Vec3;
+    };
+}
+export interface Waypoint {
+    id: WaypointId;
+    position: Vec3;
+    radius: number;
+    connections: WaypointId[];
+    tags?: string[];
+    cost?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface WaypointGraph {
+    id: string;
+    waypoints: Map<WaypointId, Waypoint>;
+}
+export interface PathNode {
+    position: Vec3;
+    index?: number;
+    cost?: number;
+    polygonId?: number;
+}
+export interface NavigationPath {
+    id: string;
+    nodes: PathNode[];
+    totalCost: number;
+    length: number;
+    isPartial: boolean;
+    timestamp: number;
+}
+export interface PathRequest {
+    start: Vec3;
+    end: Vec3;
+    agentRadius?: number;
+    agentHeight?: number;
+    maxPathLength?: number;
+    algorithm?: PathfindingAlgorithm;
+    heuristic?: HeuristicType;
+    areaFilter?: AreaId[];
+    areaCosts?: Record<AreaId, number>;
+    smoothPath?: boolean;
+}
+export interface PathResult {
+    success: boolean;
+    path?: NavigationPath;
+    error?: string;
+    computeTime: number;
+}
+export type AgentState = 'idle' | 'moving' | 'stuck' | 'arrived' | 'paused';
+export interface NavigationAgent {
+    id: AgentId;
+    position: Vec3;
+    velocity: Vec3;
+    targetPosition?: Vec3;
+    radius: number;
+    height: number;
+    maxSpeed: number;
+    maxAcceleration: number;
+    maxTurnSpeed: number;
+    currentPath?: NavigationPath;
+    currentWaypointIndex: number;
+    state: AgentState;
+    stuckTime: number;
+    avoidanceEnabled: boolean;
+    avoidancePriority: number;
+    separationWeight: number;
+    userData?: unknown;
+}
+export interface AgentConfig {
+    id?: AgentId;
+    position: Vec3;
+    radius?: number;
+    height?: number;
+    maxSpeed?: number;
+    maxAcceleration?: number;
+    maxTurnSpeed?: number;
+    avoidanceEnabled?: boolean;
+    avoidancePriority?: number;
+    userData?: unknown;
+}
+export type ObstacleShape = 'circle' | 'box' | 'polygon';
+export interface DynamicObstacle {
+    id: ObstacleId;
+    shape: ObstacleShape;
+    position: Vec3;
+    radius?: number;
+    size?: Vec3;
+    vertices?: Vec2[];
+    velocity?: Vec3;
+    enabled: boolean;
+}
+export interface FlowField {
+    id: string;
+    target: Vec3;
+    width: number;
+    height: number;
+    cellSize: number;
+    origin: Vec2;
+    directions: Vec2[][];
+    costs: number[][];
+    timestamp: number;
+}
+export interface NavigationArea {
+    id: AreaId;
+    name: string;
+    cost: number;
+    flags: number;
+    color?: string;
+}
+export type NavigationEventType = 'path-found' | 'path-failed' | 'agent-arrived' | 'agent-stuck' | 'agent-state-changed' | 'obstacle-added' | 'obstacle-removed';
+export interface NavigationEvent {
+    type: NavigationEventType;
+    agentId?: AgentId;
+    path?: NavigationPath;
+    obstacle?: DynamicObstacle;
+    error?: string;
+    timestamp: number;
+}
+export type NavigationEventCallback = (event: NavigationEvent) => void;
+export interface NavigationConfig {
+    maxPathNodes: number;
+    pathCacheSize: number;
+    pathCacheTTL: number;
+    agentUpdateRate: number;
+    obstacleUpdateRate: number;
+    stuckThreshold: number;
+    stuckTimeout: number;
+    arrivalThreshold: number;
+    waypointReachThreshold: number;
+    smoothingIterations: number;
+    maxSearchIterations: number;
+}
+export declare const DEFAULT_NAVIGATION_CONFIG: NavigationConfig;
+export declare class NiceNavigation extends EventEmitter {
+    private config;
+    private grids;
+    private navMeshes;
+    private waypointGraphs;
+    private agents;
+    private obstacles;
+    private areas;
+    private flowFields;
+    private pathCache;
+    private agentAccumulator;
+    private obstacleAccumulator;
+    private destroyed;
+    constructor(config?: Partial<NavigationConfig>);
+    createGrid(config: GridConfig): NavigationGrid;
+    getGrid(gridId: string): NavigationGrid | undefined;
+    setCell(gridId: string, x: number, y: number, cell: Partial<GridCell>): void;
+    setCellsBlocked(gridId: string, cells: Array<{
+        x: number;
+        y: number;
+    }>): void;
+    worldToGrid(gridId: string, worldPos: Vec3): {
+        x: number;
+        y: number;
+    } | null;
+    gridToWorld(gridId: string, gridX: number, gridY: number): Vec3 | null;
+    removeGrid(gridId: string): void;
+    createNavMesh(vertices: Vec3[], polygons: number[][]): NavMesh;
+    private polygonsShareEdge;
+    getNavMesh(navMeshId: NavMeshId): NavMesh | undefined;
+    findPolygonAtPoint(navMeshId: NavMeshId, point: Vec3): NavMeshPolygon | null;
+    private isPointInPolygon;
+    removeNavMesh(navMeshId: NavMeshId): void;
+    createWaypointGraph(): WaypointGraph;
+    addWaypoint(graphId: string, position: Vec3, radius?: number, tags?: string[]): Waypoint;
+    connectWaypoints(graphId: string, waypointA: WaypointId, waypointB: WaypointId, bidirectional?: boolean): void;
+    getWaypointGraph(graphId: string): WaypointGraph | undefined;
+    findNearestWaypoint(graphId: string, position: Vec3, maxDistance?: number): Waypoint | null;
+    removeWaypointGraph(graphId: string): void;
+    findPathOnGrid(gridId: string, request: PathRequest): PathResult;
+    findPathOnNavMesh(navMeshId: NavMeshId, request: PathRequest): PathResult;
+    findPathOnWaypoints(graphId: string, request: PathRequest): PathResult;
+    private calculatePathLength;
+    private smoothPath;
+    private smoothNavMeshPath;
+    private hasLineOfSight;
+    createAgent(config: AgentConfig): NavigationAgent;
+    getAgent(agentId: AgentId): NavigationAgent | undefined;
+    setAgentDestination(agentId: AgentId, destination: Vec3, pathResult?: PathResult): boolean;
+    setAgentPath(agentId: AgentId, path: NavigationPath): void;
+    stopAgent(agentId: AgentId): void;
+    removeAgent(agentId: AgentId): void;
+    private setAgentState;
+    addObstacle(obstacle: Omit<DynamicObstacle, 'id' | 'enabled'>): DynamicObstacle;
+    updateObstacle(obstacleId: ObstacleId, updates: Partial<DynamicObstacle>): void;
+    removeObstacle(obstacleId: ObstacleId): void;
+    createFlowField(gridId: string, target: Vec3): FlowField | null;
+    getFlowDirection(flowFieldId: string, position: Vec3): Vec2 | null;
+    removeFlowField(flowFieldId: string): void;
+    update(deltaTime: number): void;
+    private updateAgents;
+    private applyAvoidance;
+    defineArea(area: NavigationArea): void;
+    getArea(areaId: AreaId): NavigationArea | undefined;
+    removeArea(areaId: AreaId): void;
+    getAllAgents(): NavigationAgent[];
+    getMovingAgents(): NavigationAgent[];
+    getStats(): {
+        grids: number;
+        navMeshes: number;
+        waypointGraphs: number;
+        agents: number;
+        obstacles: number;
+        flowFields: number;
+        cachedPaths: number;
+    };
+    on(event: 'navigation', callback: NavigationEventCallback): this;
+    off(event: 'navigation', callback: NavigationEventCallback): this;
+    clear(): void;
+    destroy(): void;
+}
+export declare function createNavigationSystem(config?: Partial<NavigationConfig>): NiceNavigation;
+export declare function pathToPositions(path: NavigationPath): Vec3[];
+export declare function getPathProgress(path: NavigationPath, position: Vec3): number;