@nice2dev/game-engine 1.3.13 → 1.3.14

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

@@ -1,637 +0,0 @@
-/**
- * NiceAI - Comprehensive AI Behavior System
- *
- * Professional AI system for NPCs, enemies, and game agents.
- * Supports behavior trees, utility AI, GOAP, blackboards, and steering.
- *
- * Features:
- * - Behavior Trees (BT) with all node types
- * - Utility AI with considerations
- * - Goal-Oriented Action Planning (GOAP)
- * - Hierarchical Task Networks (HTN)
- * - Blackboard knowledge sharing
- * - Perception systems (sight, hearing)
- * - Steering behaviors
- * - Group/squad coordination
- * - Memory and learning
- * - Debug visualization
- *
- * @packageDocumentation
- */
-import { EventEmitter } from 'eventemitter3';
-/** Unique identifier for AI agents */
-export type AgentId = string;
-/** Unique identifier for behaviors */
-export type BehaviorId = string;
-/** Unique identifier for actions */
-export type ActionId = string;
-/** Unique identifier for goals */
-export type GoalId = string;
-/** Unique identifier for squads */
-export type SquadId = string;
-/** Behavior node status */
-export type NodeStatus = 'running' | 'success' | 'failure';
-/** Node type in behavior tree */
-export type BehaviorNodeType = 'selector' | 'sequence' | 'parallel' | 'decorator' | 'condition' | 'action' | 'wait' | 'random' | 'loop' | 'inverter' | 'succeeder' | 'failer' | 'repeater' | 'limiter' | 'subtree';
-/** 2D Vector */
-export interface Vec2 {
-    x: number;
-    y: number;
-}
-/** 3D Vector */
-export interface Vec3 {
-    x: number;
-    y: number;
-    z: number;
-}
-/** Blackboard entry */
-export interface BlackboardEntry<T = unknown> {
-    key: string;
-    value: T;
-    timestamp: number;
-    ttl?: number;
-    source?: AgentId;
-}
-/** Blackboard for knowledge sharing */
-export interface Blackboard {
-    entries: Map<string, BlackboardEntry>;
-    parent?: Blackboard;
-}
-/** Perception target */
-export interface PerceptionTarget {
-    id: string;
-    type: string;
-    position: Vec3;
-    lastSeen: number;
-    confidence: number;
-    isVisible: boolean;
-    isAudible: boolean;
-    threat: number;
-    metadata: Map<string, unknown>;
-}
-/** Perception config */
-export interface PerceptionConfig {
-    sightRange: number;
-    sightAngle: number;
-    hearingRange: number;
-    memoryDuration: number;
-    updateInterval: number;
-}
-/** Steering behavior output */
-export interface SteeringOutput {
-    linear: Vec3;
-    angular: number;
-}
-/** Steering behavior type */
-export type SteeringType = 'seek' | 'flee' | 'arrive' | 'pursue' | 'evade' | 'wander' | 'avoid' | 'separate' | 'align' | 'cohere' | 'follow' | 'hide';
-/** Steering config */
-export interface SteeringConfig {
-    maxSpeed: number;
-    maxForce: number;
-    maxRotation: number;
-    arriveRadius: number;
-    slowRadius: number;
-    avoidanceRadius: number;
-    separationRadius: number;
-    cohesionRadius: number;
-    alignmentRadius: number;
-}
-/** Base behavior node */
-export interface BehaviorNode {
-    id: string;
-    type: BehaviorNodeType;
-    name?: string;
-    children?: BehaviorNode[];
-    decorator?: DecoratorConfig;
-    condition?: ConditionConfig;
-    action?: ActionConfig;
-    metadata?: Record<string, unknown>;
-}
-/** Decorator configuration */
-export interface DecoratorConfig {
-    type: 'inverter' | 'succeeder' | 'failer' | 'repeater' | 'limiter' | 'cooldown' | 'timeout' | 'guard';
-    count?: number;
-    cooldown?: number;
-    timeout?: number;
-    condition?: ConditionConfig;
-}
-/** Condition configuration */
-export interface ConditionConfig {
-    type: 'blackboard' | 'function' | 'distance' | 'health' | 'time' | 'random' | 'custom';
-    key?: string;
-    operator?: '==' | '!=' | '>' | '<' | '>=' | '<=' | 'exists' | 'notExists';
-    value?: unknown;
-    functionName?: string;
-    probability?: number;
-    args?: unknown[];
-}
-/** Action configuration */
-export interface ActionConfig {
-    name: string;
-    duration?: number;
-    interruptible?: boolean;
-    parameters?: Record<string, unknown>;
-}
-/** Behavior tree definition */
-export interface BehaviorTree {
-    id: BehaviorId;
-    name: string;
-    root: BehaviorNode;
-    metadata?: Record<string, unknown>;
-}
-/** Node execution context */
-export interface NodeContext {
-    agent: AIAgent;
-    blackboard: Blackboard;
-    deltaTime: number;
-    nodeStates: Map<string, NodeState>;
-}
-/** Node state tracking */
-export interface NodeState {
-    status: NodeStatus;
-    startTime?: number;
-    lastRunTime?: number;
-    runCount: number;
-    data: Map<string, unknown>;
-}
-/** Consideration for utility AI */
-export interface Consideration {
-    id: string;
-    name: string;
-    inputType: 'blackboard' | 'function' | 'distance' | 'health' | 'time' | 'custom';
-    inputKey?: string;
-    functionName?: string;
-    curve: ResponseCurve;
-    weight: number;
-    parameters?: Record<string, unknown>;
-}
-/** Response curve for utility scoring */
-export interface ResponseCurve {
-    type: 'linear' | 'quadratic' | 'exponential' | 'logistic' | 'sine' | 'step' | 'custom';
-    slope?: number;
-    exponent?: number;
-    xShift?: number;
-    yShift?: number;
-    invert?: boolean;
-    customFn?: (x: number) => number;
-}
-/** Utility action */
-export interface UtilityAction {
-    id: ActionId;
-    name: string;
-    considerations: Consideration[];
-    weight: number;
-    cooldown?: number;
-    lastExecuted?: number;
-    execute: (agent: AIAgent, context: AIContext) => void | Promise<void>;
-    metadata?: Record<string, unknown>;
-}
-/** Utility AI system */
-export interface UtilityBrain {
-    actions: UtilityAction[];
-    defaultAction?: ActionId;
-    momentumFactor: number;
-    randomFactor: number;
-    currentAction?: ActionId;
-}
-/** World state for GOAP */
-export interface WorldState {
-    [key: string]: boolean | number | string;
-}
-/** GOAP action */
-export interface GOAPAction {
-    id: ActionId;
-    name: string;
-    cost: number;
-    preconditions: WorldState;
-    effects: WorldState;
-    execute: (agent: AIAgent, context: AIContext) => Promise<boolean>;
-    isValid?: (agent: AIAgent, worldState: WorldState) => boolean;
-    getDynamicCost?: (agent: AIAgent, worldState: WorldState) => number;
-    metadata?: Record<string, unknown>;
-}
-/** GOAP goal */
-export interface GOAPGoal {
-    id: GoalId;
-    name: string;
-    priority: number;
-    targetState: WorldState;
-    isValid?: (agent: AIAgent, worldState: WorldState) => boolean;
-    onActivate?: (agent: AIAgent) => void;
-    onDeactivate?: (agent: AIAgent) => void;
-    metadata?: Record<string, unknown>;
-}
-/** GOAP plan */
-export interface GOAPPlan {
-    goalId: GoalId;
-    actions: GOAPAction[];
-    totalCost: number;
-    currentIndex: number;
-    isValid: boolean;
-}
-/** GOAP planner */
-export interface GOAPPlanner {
-    actions: Map<ActionId, GOAPAction>;
-    goals: Map<GoalId, GOAPGoal>;
-    maxPlanLength: number;
-    maxIterations: number;
-}
-/** AI agent state */
-export type AgentState = 'idle' | 'active' | 'paused' | 'disabled';
-/** AI agent definition */
-export interface AIAgentConfig {
-    id: AgentId;
-    type: 'bt' | 'utility' | 'goap' | 'hybrid';
-    behaviorTree?: BehaviorTree;
-    utilityBrain?: UtilityBrain;
-    goapPlanner?: GOAPPlanner;
-    perception?: PerceptionConfig;
-    steering?: SteeringConfig;
-    updateInterval: number;
-    position: Vec3;
-    rotation: number;
-    metadata?: Record<string, unknown>;
-}
-/** AI agent instance */
-export interface AIAgent {
-    config: AIAgentConfig;
-    state: AgentState;
-    blackboard: Blackboard;
-    perception: {
-        targets: Map<string, PerceptionTarget>;
-        lastUpdate: number;
-    };
-    steering: {
-        velocity: Vec3;
-        acceleration: Vec3;
-        currentBehaviors: SteeringType[];
-    };
-    bt: {
-        currentTree?: BehaviorId;
-        nodeStates: Map<string, NodeState>;
-        lastTick: number;
-    };
-    utility: {
-        currentAction?: ActionId;
-        actionScores: Map<ActionId, number>;
-        lastEvaluation: number;
-    };
-    goap: {
-        currentPlan?: GOAPPlan;
-        worldState: WorldState;
-        lastPlan: number;
-    };
-    squadId?: SquadId;
-    createdAt: number;
-    lastUpdate: number;
-}
-/** AI execution context */
-export interface AIContext {
-    deltaTime: number;
-    time: number;
-    agents: Map<AgentId, AIAgent>;
-    squads: Map<SquadId, Squad>;
-    globalBlackboard: Blackboard;
-}
-/** Squad/group */
-export interface Squad {
-    id: SquadId;
-    name: string;
-    leader?: AgentId;
-    members: AgentId[];
-    formation: FormationType;
-    blackboard: Blackboard;
-    tactics: SquadTactics;
-}
-/** Formation type */
-export type FormationType = 'none' | 'line' | 'column' | 'wedge' | 'circle' | 'scattered';
-/** Squad tactics */
-export interface SquadTactics {
-    aggression: number;
-    spacing: number;
-    coordination: number;
-    retreatThreshold: number;
-}
-/** AI event types */
-export type AIEventType = 'agent:created' | 'agent:destroyed' | 'agent:stateChanged' | 'behavior:started' | 'behavior:completed' | 'behavior:failed' | 'action:started' | 'action:completed' | 'action:failed' | 'goal:activated' | 'goal:achieved' | 'goal:failed' | 'plan:created' | 'plan:failed' | 'perception:targetAcquired' | 'perception:targetLost' | 'squad:formed' | 'squad:disbanded' | 'squad:memberJoined' | 'squad:memberLeft' | 'blackboard:changed' | 'error';
-/** AI event */
-export interface AIEvent {
-    type: AIEventType;
-    agentId?: AgentId;
-    squadId?: SquadId;
-    behaviorId?: BehaviorId;
-    actionId?: ActionId;
-    goalId?: GoalId;
-    targetId?: string;
-    key?: string;
-    value?: unknown;
-    oldState?: AgentState;
-    newState?: AgentState;
-    error?: Error;
-    timestamp: number;
-}
-/** Event callback */
-export type AIEventCallback = (event: AIEvent) => void;
-/** AI system configuration */
-export interface AIConfig {
-    /** Default update interval (ms) */
-    defaultUpdateInterval: number;
-    /** Maximum agents per frame */
-    maxAgentsPerFrame: number;
-    /** Enable debug logging */
-    debug: boolean;
-    /** Default perception config */
-    defaultPerception: PerceptionConfig;
-    /** Default steering config */
-    defaultSteering: SteeringConfig;
-}
-export declare const DEFAULT_AI_CONFIG: AIConfig;
-export declare class NiceAI extends EventEmitter<Record<AIEventType, [AIEvent]>> {
-    private config;
-    private agents;
-    private behaviorTrees;
-    private squads;
-    private globalBlackboard;
-    private conditionFunctions;
-    private actionHandlers;
-    private inputFunctions;
-    private updateTimer?;
-    private lastUpdateTime;
-    private agentCounter;
-    private squadCounter;
-    constructor(config?: Partial<AIConfig>);
-    /**
-     * Create a new blackboard
-     */
-    createBlackboard(parent?: Blackboard): Blackboard;
-    /**
-     * Set blackboard value
-     */
-    setBlackboardValue<T>(blackboard: Blackboard, key: string, value: T, ttl?: number, source?: AgentId): void;
-    /**
-     * Get blackboard value
-     */
-    getBlackboardValue<T>(blackboard: Blackboard, key: string): T | undefined;
-    /**
-     * Check if blackboard has key
-     */
-    hasBlackboardKey(blackboard: Blackboard, key: string): boolean;
-    /**
-     * Delete blackboard key
-     */
-    deleteBlackboardKey(blackboard: Blackboard, key: string): boolean;
-    /**
-     * Clear blackboard
-     */
-    clearBlackboard(blackboard: Blackboard): void;
-    /**
-     * Get global blackboard
-     */
-    getGlobalBlackboard(): Blackboard;
-    /**
-     * Create an AI agent
-     */
-    createAgent(config: Partial<AIAgentConfig> & {
-        id?: AgentId;
-    }): AIAgent;
-    /**
-     * Get agent
-     */
-    getAgent(id: AgentId): AIAgent | undefined;
-    /**
-     * Remove agent
-     */
-    removeAgent(id: AgentId): boolean;
-    /**
-     * Set agent state
-     */
-    setAgentState(id: AgentId, state: AgentState): boolean;
-    /**
-     * Get all agents
-     */
-    getAllAgents(): AIAgent[];
-    /**
-     * Get active agents
-     */
-    getActiveAgents(): AIAgent[];
-    /**
-     * Register behavior tree
-     */
-    registerBehaviorTree(tree: BehaviorTree): void;
-    /**
-     * Get behavior tree
-     */
-    getBehaviorTree(id: BehaviorId): BehaviorTree | undefined;
-    /**
-     * Set agent behavior tree
-     */
-    setAgentBehaviorTree(agentId: AgentId, treeId: BehaviorId): boolean;
-    /**
-     * Tick behavior tree
-     */
-    tickBehaviorTree(agent: AIAgent, deltaTime: number): NodeStatus;
-    /**
-     * Execute behavior node
-     */
-    private executeNode;
-    private executeSelector;
-    private executeSequence;
-    private executeParallel;
-    private executeCondition;
-    private executeAction;
-    private executeWait;
-    private executeRandom;
-    private executeInverter;
-    private executeDecorator;
-    private executeSubtree;
-    /**
-     * Evaluate condition
-     */
-    private evaluateCondition;
-    private compareValues;
-    /**
-     * Evaluate utility actions
-     */
-    evaluateUtilityActions(agent: AIAgent): ActionId | undefined;
-    /**
-     * Calculate utility score for action
-     */
-    private calculateUtilityScore;
-    /**
-     * Get consideration input value
-     */
-    private getConsiderationInput;
-    /**
-     * Evaluate response curve
-     */
-    private evaluateResponseCurve;
-    /**
-     * Plan with GOAP
-     */
-    planGOAP(agent: AIAgent, goal: GOAPGoal): GOAPPlan | null;
-    private goapHeuristic;
-    private goapStateMatches;
-    /**
-     * Execute GOAP plan step
-     */
-    executeGOAPStep(agent: AIAgent): Promise<boolean>;
-    /**
-     * Calculate steering
-     */
-    calculateSteering(agent: AIAgent, behaviors: SteeringType[], targets: Map<SteeringType, Vec3>): SteeringOutput;
-    private calculateSteeringBehavior;
-    private steerSeek;
-    private steerFlee;
-    private steerArrive;
-    private steerWander;
-    /**
-     * Apply steering to agent
-     */
-    applySteering(agent: AIAgent, steering: SteeringOutput, deltaTime: number): void;
-    /**
-     * Create squad
-     */
-    createSquad(name: string, leaderId?: AgentId): Squad;
-    /**
-     * Join squad
-     */
-    joinSquad(agentId: AgentId, squadId: SquadId): boolean;
-    /**
-     * Leave squad
-     */
-    leaveSquad(agentId: AgentId): boolean;
-    /**
-     * Get squad
-     */
-    getSquad(id: SquadId): Squad | undefined;
-    /**
-     * Register condition function
-     */
-    registerCondition(name: string, fn: (agent: AIAgent, ...args: unknown[]) => boolean): void;
-    /**
-     * Register action handler
-     */
-    registerAction(name: string, handler: (agent: AIAgent, context: AIContext, params: Record<string, unknown>) => NodeStatus | Promise<NodeStatus>): void;
-    /**
-     * Register input function for utility AI
-     */
-    registerInput(name: string, fn: (agent: AIAgent) => number): void;
-    /**
-     * Register built-in conditions
-     */
-    private registerBuiltInConditions;
-    /**
-     * Register built-in input functions
-     */
-    private registerBuiltInInputs;
-    /**
-     * Start update loop
-     */
-    start(intervalMs?: number): void;
-    /**
-     * Stop update loop
-     */
-    stop(): void;
-    /**
-     * Manual update
-     */
-    update(deltaTime: number): void;
-    /**
-     * Update single agent
-     */
-    private updateAgent;
-    /**
-     * Update perception
-     */
-    private updatePerception;
-    /**
-     * Update GOAP agent
-     */
-    private updateGOAP;
-    private distance3D;
-    /**
-     * Get statistics
-     */
-    getStats(): {
-        agentCount: number;
-        activeAgents: number;
-        squadCount: number;
-        behaviorTreeCount: number;
-    };
-    /**
-     * Destroy the AI system
-     */
-    destroy(): void;
-}
-/**
- * Create an AI system
- */
-export declare function createAISystem(config?: Partial<AIConfig>): NiceAI;
-/**
- * Create a selector node
- */
-export declare function selector(id: string, ...children: BehaviorNode[]): BehaviorNode;
-/**
- * Create a sequence node
- */
-export declare function sequence(id: string, ...children: BehaviorNode[]): BehaviorNode;
-/**
- * Create a parallel node
- */
-export declare function parallel(id: string, ...children: BehaviorNode[]): BehaviorNode;
-/**
- * Create a condition node
- */
-export declare function condition(id: string, config: ConditionConfig): BehaviorNode;
-/**
- * Create an action node
- */
-export declare function action(id: string, name: string, params?: Record<string, unknown>): BehaviorNode;
-/**
- * Create a wait node
- */
-export declare function wait(id: string, duration: number): BehaviorNode;
-/**
- * Create a decorator node
- */
-export declare function decorator(id: string, config: DecoratorConfig, child: BehaviorNode): BehaviorNode;
-/**
- * Create an inverter decorator
- */
-export declare function inverter(id: string, child: BehaviorNode): BehaviorNode;
-/**
- * Create a repeater decorator
- */
-export declare function repeater(id: string, count: number, child: BehaviorNode): BehaviorNode;
-/**
- * Create a cooldown decorator
- */
-export declare function cooldown(id: string, ms: number, child: BehaviorNode): BehaviorNode;
-/**
- * Create a behavior tree
- */
-export declare function behaviorTree(id: BehaviorId, name: string, root: BehaviorNode): BehaviorTree;
-/**
- * Create a utility action
- */
-export declare function utilityAction(id: ActionId, name: string, considerations: Consideration[], execute: (agent: AIAgent, context: AIContext) => void | Promise<void>, weight?: number): UtilityAction;
-/**
- * Create a consideration
- */
-export declare function consideration(id: string, name: string, inputType: Consideration['inputType'], curve: ResponseCurve, options?: {
-    inputKey?: string;
-    functionName?: string;
-    weight?: number;
-}): Consideration;
-/**
- * Create a response curve
- */
-export declare function curve(type: ResponseCurve['type'], options?: Partial<ResponseCurve>): ResponseCurve;
-/**
- * Create a GOAP action
- */
-export declare function goapAction(id: ActionId, name: string, cost: number, preconditions: WorldState, effects: WorldState, execute: (agent: AIAgent, context: AIContext) => Promise<boolean>): GOAPAction;
-/**
- * Create a GOAP goal
- */
-export declare function goapGoal(id: GoalId, name: string, priority: number, targetState: WorldState): GOAPGoal;