@holoscript/framework 6.0.3

package/src/ai/StateMachine.ts

@@ -0,0 +1,196 @@
+/**
+ * StateMachine.ts
+ *
+ * Hierarchical state machine: states with enter/exit/update hooks,
+ * transitions with guards, sub-state machines, and event dispatch.
+ *
+ * @module ai
+ */
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export type StateAction = (context: Record<string, unknown>) => void;
+export type GuardFn = (context: Record<string, unknown>) => boolean;
+
+export interface StateConfig {
+  id: string;
+  onEnter?: StateAction;
+  onExit?: StateAction;
+  onUpdate?: StateAction;
+  parent?: string; // Parent state ID for hierarchy
+}
+
+export interface TransitionConfig {
+  from: string;
+  to: string;
+  event: string;
+  guard?: GuardFn;
+  action?: StateAction;
+}
+
+// =============================================================================
+// STATE MACHINE
+// =============================================================================
+
+export class StateMachine {
+  private states: Map<string, StateConfig> = new Map();
+  private transitions: TransitionConfig[] = [];
+  private currentStateId: string | null = null;
+  private context: Record<string, unknown> = {};
+  private history: string[] = [];
+  private maxHistory = 50;
+
+  // ---------------------------------------------------------------------------
+  // State Management
+  // ---------------------------------------------------------------------------
+
+  addState(config: StateConfig): void {
+    this.states.set(config.id, config);
+  }
+  removeState(id: string): void {
+    this.states.delete(id);
+  }
+
+  setInitialState(id: string): void {
+    this.currentStateId = id;
+    const chain = this.getStateChain(id);
+    for (const stateId of chain) {
+      const state = this.states.get(stateId);
+      if (state?.onEnter) state.onEnter(this.context);
+    }
+    this.history.push(id);
+  }
+
+  getCurrentState(): string | null {
+    return this.currentStateId;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Transitions
+  // ---------------------------------------------------------------------------
+
+  addTransition(config: TransitionConfig): void {
+    this.transitions.push(config);
+  }
+
+  send(event: string): boolean {
+    if (!this.currentStateId) return false;
+
+    // Check transitions from current state (and parent states)
+    const candidates = this.getTransitionsFor(this.currentStateId, event);
+
+    for (const transition of candidates) {
+      if (transition.guard && !transition.guard(this.context)) continue;
+
+      const fromChain = this.getStateChain(this.currentStateId);
+      const toChain = this.getStateChain(transition.to);
+
+      let lcaIndex = 0;
+      while (
+        lcaIndex < fromChain.length &&
+        lcaIndex < toChain.length &&
+        fromChain[lcaIndex] === toChain[lcaIndex]
+      ) {
+        lcaIndex++;
+      }
+
+      // Exit states up to Lowest Common Ancestor
+      for (let i = fromChain.length - 1; i >= lcaIndex; i--) {
+        const state = this.states.get(fromChain[i]);
+        if (state?.onExit) state.onExit(this.context);
+      }
+
+      // Run transition action
+      if (transition.action) transition.action(this.context);
+
+      // Enter new states from LCA down to target
+      for (let i = lcaIndex; i < toChain.length; i++) {
+        const state = this.states.get(toChain[i]);
+        if (state?.onEnter) state.onEnter(this.context);
+      }
+
+      this.currentStateId = transition.to;
+
+      this.history.push(transition.to);
+      if (this.history.length > this.maxHistory) this.history.shift();
+
+      return true;
+    }
+
+    return false;
+  }
+
+  private getTransitionsFor(stateId: string, event: string): TransitionConfig[] {
+    const result: TransitionConfig[] = [];
+
+    // Direct transitions
+    result.push(...this.transitions.filter((t) => t.from === stateId && t.event === event));
+
+    // Check parent state transitions (hierarchy)
+    const state = this.states.get(stateId);
+    if (state?.parent) {
+      result.push(...this.getTransitionsFor(state.parent, event));
+    }
+
+    return result;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Enter/Exit with Hierarchy (Chained)
+  // ---------------------------------------------------------------------------
+
+  private getStateChain(id: string): string[] {
+    const chain: string[] = [];
+    let currentId: string | undefined = id;
+    while (currentId) {
+      chain.unshift(currentId);
+      currentId = this.states.get(currentId)?.parent;
+    }
+    return chain;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Update
+  // ---------------------------------------------------------------------------
+
+  update(): void {
+    if (!this.currentStateId) return;
+    const state = this.states.get(this.currentStateId);
+    if (state?.onUpdate) state.onUpdate(this.context);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Context
+  // ---------------------------------------------------------------------------
+
+  setContext(key: string, value: unknown): void {
+    this.context[key] = value;
+  }
+  getContext(key: string): unknown {
+    return this.context[key];
+  }
+
+  // ---------------------------------------------------------------------------
+  // Queries
+  // ---------------------------------------------------------------------------
+
+  getStateCount(): number {
+    return this.states.size;
+  }
+  getHistory(): string[] {
+    return [...this.history];
+  }
+  isInState(id: string): boolean {
+    return this.currentStateId === id;
+  }
+
+  getChildStates(parentId: string): string[] {
+    const children: string[] = [];
+    for (const [id, state] of this.states) {
+      if (state.parent === parentId) children.push(id);
+    }
+    return children;
+  }
+}

package/src/ai/SteeringBehavior.ts

@@ -0,0 +1,150 @@
+/**
+ * SteeringBehavior — Seek/flee/arrive/wander/avoid with weighted blending
+ *
+ * @version 1.0.0
+ */
+
+export interface Vec2 {
+  x: number;
+  z: number;
+}
+
+export type SteeringType = 'seek' | 'flee' | 'arrive' | 'wander' | 'avoid' | 'pursue' | 'evade';
+
+export interface SteeringAgent {
+  position: Vec2;
+  velocity: Vec2;
+  maxSpeed: number;
+  maxForce: number;
+  mass: number;
+}
+
+export interface SteeringOutput {
+  force: Vec2;
+  type: SteeringType;
+  weight: number;
+}
+
+export class SteeringBehavior {
+  /**
+   * Seek — steer toward a target
+   */
+  static seek(agent: SteeringAgent, target: Vec2): Vec2 {
+    const desired = { x: target.x - agent.position.x, z: target.z - agent.position.z };
+    const mag = Math.sqrt(desired.x ** 2 + desired.z ** 2);
+    if (mag === 0) return { x: 0, z: 0 };
+    desired.x = (desired.x / mag) * agent.maxSpeed;
+    desired.z = (desired.z / mag) * agent.maxSpeed;
+    return {
+      x: desired.x - agent.velocity.x,
+      z: desired.z - agent.velocity.z,
+    };
+  }
+
+  /**
+   * Flee — steer away from a target
+   */
+  static flee(agent: SteeringAgent, target: Vec2): Vec2 {
+    const force = this.seek(agent, target);
+    return { x: -force.x, z: -force.z };
+  }
+
+  /**
+   * Arrive — seek with deceleration near target
+   */
+  static arrive(agent: SteeringAgent, target: Vec2, slowRadius: number = 5): Vec2 {
+    const toTarget = { x: target.x - agent.position.x, z: target.z - agent.position.z };
+    const dist = Math.sqrt(toTarget.x ** 2 + toTarget.z ** 2);
+    if (dist === 0) return { x: 0, z: 0 };
+
+    const speed = dist < slowRadius ? agent.maxSpeed * (dist / slowRadius) : agent.maxSpeed;
+
+    const desired = {
+      x: (toTarget.x / dist) * speed,
+      z: (toTarget.z / dist) * speed,
+    };
+
+    return {
+      x: desired.x - agent.velocity.x,
+      z: desired.z - agent.velocity.z,
+    };
+  }
+
+  /**
+   * Wander — random jitter-based steering
+   */
+  static wander(
+    agent: SteeringAgent,
+    wanderRadius: number = 2,
+    wanderDistance: number = 4,
+    jitter: number = 0.5
+  ): Vec2 {
+    const angle = Math.random() * Math.PI * 2;
+    const wanderTarget = {
+      x: agent.position.x + Math.cos(angle) * wanderRadius * jitter,
+      z: agent.position.z + Math.sin(angle) * wanderRadius * jitter,
+    };
+
+    const velMag = Math.sqrt(agent.velocity.x ** 2 + agent.velocity.z ** 2);
+    const forward =
+      velMag > 0
+        ? {
+            x: (agent.velocity.x / velMag) * wanderDistance,
+            z: (agent.velocity.z / velMag) * wanderDistance,
+          }
+        : { x: wanderDistance, z: 0 };
+
+    const circleCenter = {
+      x: agent.position.x + forward.x,
+      z: agent.position.z + forward.z,
+    };
+
+    return this.seek(agent, {
+      x: circleCenter.x + wanderTarget.x - agent.position.x,
+      z: circleCenter.z + wanderTarget.z - agent.position.z,
+    });
+  }
+
+  /**
+   * Obstacle avoidance
+   */
+  static avoid(
+    agent: SteeringAgent,
+    obstacles: { position: Vec2; radius: number }[],
+    lookAhead: number = 5
+  ): Vec2 {
+    const force: Vec2 = { x: 0, z: 0 };
+
+    for (const obs of obstacles) {
+      const toObs = { x: obs.position.x - agent.position.x, z: obs.position.z - agent.position.z };
+      const dist = Math.sqrt(toObs.x ** 2 + toObs.z ** 2);
+
+      if (dist < lookAhead + obs.radius) {
+        const pushStrength = (lookAhead + obs.radius - dist) / (lookAhead + obs.radius);
+        force.x -= (toObs.x / dist) * pushStrength * agent.maxForce;
+        force.z -= (toObs.z / dist) * pushStrength * agent.maxForce;
+      }
+    }
+
+    return force;
+  }
+
+  /**
+   * Blend multiple steering outputs by weight
+   */
+  static blend(outputs: SteeringOutput[], maxForce: number): Vec2 {
+    const result: Vec2 = { x: 0, z: 0 };
+    for (const out of outputs) {
+      result.x += out.force.x * out.weight;
+      result.z += out.force.z * out.weight;
+    }
+
+    const mag = Math.sqrt(result.x ** 2 + result.z ** 2);
+    if (mag > maxForce) {
+      result.x = (result.x / mag) * maxForce;
+      result.z = (result.z / mag) * maxForce;
+    }
+
+    return result;
+  }
+}

package/src/ai/SteeringBehaviors.ts

@@ -0,0 +1,244 @@
+/**
+ * SteeringBehaviors.ts
+ *
+ * Autonomous agent steering: seek, flee, arrive, wander,
+ * flock (separation/alignment/cohesion), and obstacle avoidance.
+ *
+ * @module ai
+ */
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface SteeringAgent {
+  position: { x: number; y: number; z: number };
+  velocity: { x: number; y: number; z: number };
+  maxSpeed: number;
+  maxForce: number;
+  mass: number;
+}
+
+export interface FlockConfig {
+  separationWeight: number;
+  alignmentWeight: number;
+  cohesionWeight: number;
+  neighborRadius: number;
+}
+
+export interface ObstacleCircle {
+  center: { x: number; y: number; z: number };
+  radius: number;
+}
+
+type Vec3 = { x: number; y: number; z: number };
+
+// =============================================================================
+// STEERING BEHAVIORS
+// =============================================================================
+
+export class SteeringBehaviors {
+  // ---------------------------------------------------------------------------
+  // Basic Behaviors
+  // ---------------------------------------------------------------------------
+
+  static seek(agent: SteeringAgent, target: Vec3): Vec3 {
+    const desired = SteeringBehaviors.sub(target, agent.position);
+    const norm = SteeringBehaviors.normalize(desired);
+    const scaled = SteeringBehaviors.scale(norm, agent.maxSpeed);
+    return SteeringBehaviors.truncate(
+      SteeringBehaviors.sub(scaled, agent.velocity),
+      agent.maxForce
+    );
+  }
+
+  static flee(agent: SteeringAgent, threat: Vec3): Vec3 {
+    const desired = SteeringBehaviors.sub(agent.position, threat);
+    const norm = SteeringBehaviors.normalize(desired);
+    const scaled = SteeringBehaviors.scale(norm, agent.maxSpeed);
+    return SteeringBehaviors.truncate(
+      SteeringBehaviors.sub(scaled, agent.velocity),
+      agent.maxForce
+    );
+  }
+
+  static arrive(agent: SteeringAgent, target: Vec3, slowRadius: number): Vec3 {
+    const toTarget = SteeringBehaviors.sub(target, agent.position);
+    const dist = SteeringBehaviors.vecLength(toTarget);
+    if (dist < 0.001) return { x: 0, y: 0, z: 0 };
+
+    const speed = dist < slowRadius ? agent.maxSpeed * (dist / slowRadius) : agent.maxSpeed;
+    const desired = SteeringBehaviors.scale(SteeringBehaviors.normalize(toTarget), speed);
+    return SteeringBehaviors.truncate(
+      SteeringBehaviors.sub(desired, agent.velocity),
+      agent.maxForce
+    );
+  }
+
+  static wander(
+    agent: SteeringAgent,
+    circleDistance: number,
+    circleRadius: number,
+    angleJitter: number,
+    currentAngle: number
+  ): { force: Vec3; newAngle: number } {
+    const angle = currentAngle + (Math.random() - 0.5) * angleJitter;
+    const vel = SteeringBehaviors.normalize(agent.velocity);
+    const circleCenter = SteeringBehaviors.add(
+      agent.position,
+      SteeringBehaviors.scale(vel, circleDistance)
+    );
+    const offset = { x: Math.cos(angle) * circleRadius, y: 0, z: Math.sin(angle) * circleRadius };
+    const target = SteeringBehaviors.add(circleCenter, offset);
+    return { force: SteeringBehaviors.seek(agent, target), newAngle: angle };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Flock
+  // ---------------------------------------------------------------------------
+
+  static flock(agent: SteeringAgent, neighbors: SteeringAgent[], config: FlockConfig): Vec3 {
+    const nearby = neighbors.filter((n) => {
+      if (n === agent) return false;
+      return SteeringBehaviors.distance(agent.position, n.position) < config.neighborRadius;
+    });
+
+    if (nearby.length === 0) return { x: 0, y: 0, z: 0 };
+
+    const sep = SteeringBehaviors.separation(agent, nearby);
+    const ali = SteeringBehaviors.alignment(agent, nearby);
+    const coh = SteeringBehaviors.cohesion(agent, nearby);
+
+    return {
+      x:
+        sep.x * config.separationWeight +
+        ali.x * config.alignmentWeight +
+        coh.x * config.cohesionWeight,
+      y:
+        sep.y * config.separationWeight +
+        ali.y * config.alignmentWeight +
+        coh.y * config.cohesionWeight,
+      z:
+        sep.z * config.separationWeight +
+        ali.z * config.alignmentWeight +
+        coh.z * config.cohesionWeight,
+    };
+  }
+
+  private static separation(agent: SteeringAgent, neighbors: SteeringAgent[]): Vec3 {
+    let fx = 0,
+      fy = 0,
+      fz = 0;
+    for (const n of neighbors) {
+      const d = SteeringBehaviors.sub(agent.position, n.position);
+      const dist = SteeringBehaviors.vecLength(d) || 0.001;
+      fx += d.x / (dist * dist);
+      fy += d.y / (dist * dist);
+      fz += d.z / (dist * dist);
+    }
+    return SteeringBehaviors.normalize({ x: fx, y: fy, z: fz });
+  }
+
+  private static alignment(_agent: SteeringAgent, neighbors: SteeringAgent[]): Vec3 {
+    let vx = 0,
+      vy = 0,
+      vz = 0;
+    for (const n of neighbors) {
+      vx += n.velocity.x;
+      vy += n.velocity.y;
+      vz += n.velocity.z;
+    }
+    const avg = { x: vx / neighbors.length, y: vy / neighbors.length, z: vz / neighbors.length };
+    return SteeringBehaviors.normalize(avg);
+  }
+
+  private static cohesion(agent: SteeringAgent, neighbors: SteeringAgent[]): Vec3 {
+    let cx = 0,
+      cy = 0,
+      cz = 0;
+    for (const n of neighbors) {
+      cx += n.position.x;
+      cy += n.position.y;
+      cz += n.position.z;
+    }
+    const center = { x: cx / neighbors.length, y: cy / neighbors.length, z: cz / neighbors.length };
+    return SteeringBehaviors.normalize(SteeringBehaviors.sub(center, agent.position));
+  }
+
+  // ---------------------------------------------------------------------------
+  // Obstacle Avoidance
+  // ---------------------------------------------------------------------------
+
+  static obstacleAvoidance(
+    agent: SteeringAgent,
+    obstacles: ObstacleCircle[],
+    lookAhead: number
+  ): Vec3 {
+    const ahead = SteeringBehaviors.add(
+      agent.position,
+      SteeringBehaviors.scale(SteeringBehaviors.normalize(agent.velocity), lookAhead)
+    );
+
+    let nearest: ObstacleCircle | null = null;
+    let nearestDist = Infinity;
+
+    for (const obs of obstacles) {
+      const dist = SteeringBehaviors.distance(ahead, obs.center);
+      if (dist < obs.radius && dist < nearestDist) {
+        nearest = obs;
+        nearestDist = dist;
+      }
+    }
+
+    if (!nearest) return { x: 0, y: 0, z: 0 };
+
+    const avoidance = SteeringBehaviors.sub(ahead, nearest.center);
+    return SteeringBehaviors.truncate(SteeringBehaviors.normalize(avoidance), agent.maxForce);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Integration
+  // ---------------------------------------------------------------------------
+
+  static applyForce(agent: SteeringAgent, force: Vec3, dt: number): void {
+    const ax = force.x / agent.mass,
+      ay = force.y / agent.mass,
+      az = force.z / agent.mass;
+    agent.velocity.x += ax * dt;
+    agent.velocity.y += ay * dt;
+    agent.velocity.z += az * dt;
+    agent.velocity = SteeringBehaviors.truncate(agent.velocity, agent.maxSpeed);
+    agent.position.x += agent.velocity.x * dt;
+    agent.position.y += agent.velocity.y * dt;
+    agent.position.z += agent.velocity.z * dt;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Vec3 Helpers
+  // ---------------------------------------------------------------------------
+
+  private static sub(a: Vec3, b: Vec3): Vec3 {
+    return { x: a.x - b.x, y: a.y - b.y, z: a.z - b.z };
+  }
+  private static add(a: Vec3, b: Vec3): Vec3 {
+    return { x: a.x + b.x, y: a.y + b.y, z: a.z + b.z };
+  }
+  private static scale(v: Vec3, s: number): Vec3 {
+    return { x: v.x * s, y: v.y * s, z: v.z * s };
+  }
+  private static vecLength(v: Vec3): number {
+    return Math.sqrt(v.x * v.x + v.y * v.y + v.z * v.z);
+  }
+  private static distance(a: Vec3, b: Vec3): number {
+    return SteeringBehaviors.vecLength(SteeringBehaviors.sub(a, b));
+  }
+  private static normalize(v: Vec3): Vec3 {
+    const len = SteeringBehaviors.vecLength(v) || 1;
+    return { x: v.x / len, y: v.y / len, z: v.z / len };
+  }
+  private static truncate(v: Vec3, max: number): Vec3 {
+    const len = SteeringBehaviors.vecLength(v);
+    if (len <= max) return v;
+    return SteeringBehaviors.scale(SteeringBehaviors.normalize(v), max);
+  }
+}