@nice2dev/game-engine 1.1.5 → 1.1.6

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

@@ -0,0 +1,637 @@
+/**
+ * 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;