@holoscript/framework 6.0.3

package/dist/behavior.cjs

@@ -0,0 +1,449 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/behavior.ts
+var behavior_exports = {};
+__export(behavior_exports, {
+  ActionNode: () => ActionNode,
+  BehaviorTree: () => BehaviorTree,
+  ConditionNode: () => ConditionNode,
+  InverterNode: () => InverterNode,
+  RepeaterNode: () => RepeaterNode,
+  SelectorNode: () => SelectorNode,
+  SequenceNode: () => SequenceNode,
+  StateMachine: () => StateMachine,
+  WaitNode: () => WaitNode,
+  createAlertBehavior: () => createAlertBehavior,
+  createFollowBehavior: () => createFollowBehavior,
+  createIdleBehavior: () => createIdleBehavior,
+  createInteractBehavior: () => createInteractBehavior,
+  createPatrolBehavior: () => createPatrolBehavior,
+  getNodeStateMachine: () => getNodeStateMachine,
+  stateTraitHandler: () => stateTraitHandler
+});
+module.exports = __toCommonJS(behavior_exports);
+
+// src/behavior/BehaviorTree.ts
+var ActionNode = class {
+  constructor(name, fn) {
+    this.name = name;
+    this.fn = fn;
+  }
+  type = "action";
+  tick(context, delta) {
+    return this.fn(context, delta);
+  }
+};
+var ConditionNode = class {
+  constructor(name, predicate) {
+    this.name = name;
+    this.predicate = predicate;
+  }
+  type = "condition";
+  tick(context) {
+    return this.predicate(context) ? "success" : "failure";
+  }
+};
+var WaitNode = class {
+  constructor(duration) {
+    this.duration = duration;
+  }
+  type = "wait";
+  elapsed = 0;
+  tick(_context, delta) {
+    this.elapsed += delta;
+    if (this.elapsed >= this.duration) {
+      return "success";
+    }
+    return "running";
+  }
+  reset() {
+    this.elapsed = 0;
+  }
+};
+var SequenceNode = class {
+  constructor(children) {
+    this.children = children;
+  }
+  type = "sequence";
+  currentIndex = 0;
+  tick(context, delta) {
+    while (this.currentIndex < this.children.length) {
+      const status = this.children[this.currentIndex].tick(context, delta);
+      if (status === "failure") {
+        this.currentIndex = 0;
+        return "failure";
+      }
+      if (status === "running") {
+        return "running";
+      }
+      this.currentIndex++;
+    }
+    this.currentIndex = 0;
+    return "success";
+  }
+  reset() {
+    this.currentIndex = 0;
+    for (const child of this.children) child.reset?.();
+  }
+};
+var SelectorNode = class {
+  constructor(children) {
+    this.children = children;
+  }
+  type = "selector";
+  currentIndex = 0;
+  tick(context, delta) {
+    while (this.currentIndex < this.children.length) {
+      const status = this.children[this.currentIndex].tick(context, delta);
+      if (status === "success") {
+        this.currentIndex = 0;
+        return "success";
+      }
+      if (status === "running") {
+        return "running";
+      }
+      this.currentIndex++;
+    }
+    this.currentIndex = 0;
+    return "failure";
+  }
+  reset() {
+    this.currentIndex = 0;
+    for (const child of this.children) child.reset?.();
+  }
+};
+var InverterNode = class {
+  constructor(child) {
+    this.child = child;
+  }
+  type = "inverter";
+  tick(context, delta) {
+    const status = this.child.tick(context, delta);
+    if (status === "success") return "failure";
+    if (status === "failure") return "success";
+    return "running";
+  }
+  reset() {
+    this.child.reset?.();
+  }
+};
+var RepeaterNode = class {
+  constructor(child, maxCount = -1) {
+    this.child = child;
+    this.maxCount = maxCount;
+  }
+  type = "repeater";
+  count = 0;
+  tick(context, delta) {
+    const status = this.child.tick(context, delta);
+    if (status === "running") return "running";
+    this.count++;
+    this.child.reset?.();
+    if (this.maxCount !== -1 && this.count >= this.maxCount) {
+      this.count = 0;
+      return "success";
+    }
+    return "running";
+  }
+  reset() {
+    this.count = 0;
+    this.child.reset?.();
+  }
+};
+var BehaviorTree = class {
+  root;
+  context;
+  constructor(root, context = {}) {
+    this.root = root;
+    this.context = context;
+  }
+  tick(delta) {
+    return this.root.tick(this.context, delta);
+  }
+  getContext() {
+    return this.context;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- matches BTContext index signature
+  setContext(key, value) {
+    this.context[key] = value;
+  }
+  reset() {
+    this.root.reset?.();
+  }
+};
+
+// src/behavior/BehaviorPresets.ts
+function createPatrolBehavior(waypointCount = 3, pauseDuration = 2) {
+  return new RepeaterNode(
+    new SequenceNode([
+      new ActionNode("selectNextWaypoint", (ctx) => {
+        ctx.waypointIndex = ((ctx.waypointIndex || 0) + 1) % waypointCount;
+        ctx.targetReached = false;
+        return "success";
+      }),
+      new ActionNode("moveToWaypoint", (ctx, delta) => {
+        ctx.moveProgress = (ctx.moveProgress || 0) + delta * 0.5;
+        if (ctx.moveProgress >= 1) {
+          ctx.moveProgress = 0;
+          ctx.targetReached = true;
+          return "success";
+        }
+        return "running";
+      }),
+      new WaitNode(pauseDuration)
+    ]),
+    -1
+    // Infinite loop
+  );
+}
+function createIdleBehavior(idleDuration = 3) {
+  return new RepeaterNode(
+    new SequenceNode([
+      new WaitNode(idleDuration),
+      new ActionNode("lookAround", (ctx) => {
+        ctx.lookAngle = Math.random() * Math.PI * 2;
+        return "success";
+      })
+    ]),
+    -1
+  );
+}
+function createInteractBehavior() {
+  return new SequenceNode([
+    new ConditionNode("hasTarget", (ctx) => !!ctx.interactTarget),
+    new ActionNode("approach", (ctx, delta) => {
+      ctx.approachProgress = (ctx.approachProgress || 0) + delta;
+      if (ctx.approachProgress >= 1.5) {
+        ctx.approachProgress = 0;
+        return "success";
+      }
+      return "running";
+    }),
+    new ActionNode("interact", (ctx) => {
+      ctx.interactionCount = (ctx.interactionCount || 0) + 1;
+      ctx.interactTarget = null;
+      return "success";
+    })
+  ]);
+}
+function createFollowBehavior(minDist = 1.5) {
+  return new RepeaterNode(
+    new SelectorNode([
+      // If close enough, idle
+      new SequenceNode([
+        new ConditionNode("closeEnough", (ctx) => {
+          const dist = ctx.distanceToTarget || 0;
+          return dist <= minDist;
+        }),
+        new WaitNode(0.5)
+      ]),
+      // Otherwise, move toward target
+      new ActionNode("moveToTarget", (ctx, delta) => {
+        ctx.distanceToTarget = Math.max(0, (ctx.distanceToTarget || 5) - delta * 2);
+        return ctx.distanceToTarget <= minDist ? "success" : "running";
+      })
+    ]),
+    -1
+  );
+}
+function createAlertBehavior() {
+  return new SelectorNode([
+    // Fight if brave
+    new SequenceNode([
+      new ConditionNode("isBrave", (ctx) => ctx.courage > 0.5),
+      new ConditionNode("hasThreat", (ctx) => !!ctx.threat),
+      new ActionNode("fight", (ctx) => {
+        ctx.fightCount = (ctx.fightCount || 0) + 1;
+        ctx.threat = null;
+        return "success";
+      })
+    ]),
+    // Flee if threatened
+    new SequenceNode([
+      new ConditionNode("hasThreat", (ctx) => !!ctx.threat),
+      new ActionNode("flee", (ctx, delta) => {
+        ctx.fleeProgress = (ctx.fleeProgress || 0) + delta;
+        if (ctx.fleeProgress >= 2) {
+          ctx.fleeProgress = 0;
+          ctx.threat = null;
+          return "success";
+        }
+        return "running";
+      })
+    ]),
+    // Default: idle
+    new WaitNode(1)
+  ]);
+}
+
+// src/behavior/StateMachine.ts
+var StateMachine = class {
+  states = /* @__PURE__ */ new Map();
+  transitions = [];
+  currentStateName = "";
+  previousStateName = "";
+  context;
+  history = [];
+  maxHistory = 50;
+  constructor(config) {
+    this.context = config.context || {};
+    for (const state of config.states) {
+      this.states.set(state.name, state);
+    }
+    this.transitions = config.transitions;
+    this.enterState(config.initialState);
+  }
+  /**
+   * Get the current state name.
+   */
+  getCurrentState() {
+    return this.currentStateName;
+  }
+  /**
+   * Get the previous state name.
+   */
+  getPreviousState() {
+    return this.previousStateName;
+  }
+  /**
+   * Get the shared context.
+   */
+  getContext() {
+    return this.context;
+  }
+  /**
+   * Get state transition history.
+   */
+  getHistory() {
+    return [...this.history];
+  }
+  /**
+   * Send an event to the state machine. May trigger a transition.
+   */
+  send(event) {
+    const transition = this.transitions.find(
+      (t) => t.from === this.currentStateName && t.event === event && (!t.guard || t.guard(this.context))
+    );
+    if (!transition) return false;
+    this.executeTransition(transition);
+    return true;
+  }
+  /**
+   * Try to transition based on guards (no event, just check conditions).
+   * Called automatically during update, or manually.
+   */
+  evaluate() {
+    const transition = this.transitions.find(
+      (t) => t.from === this.currentStateName && !t.event && t.guard && t.guard(this.context)
+    );
+    if (!transition) return false;
+    this.executeTransition(transition);
+    return true;
+  }
+  /**
+   * Force a transition to a specific state (bypasses guards).
+   */
+  forceTransition(stateName) {
+    if (!this.states.has(stateName)) return;
+    const currentState = this.states.get(this.currentStateName);
+    if (currentState?.onExit) currentState.onExit(this.context);
+    this.enterState(stateName);
+  }
+  /**
+   * Update the state machine. Call every frame.
+   */
+  update(delta) {
+    const state = this.states.get(this.currentStateName);
+    if (state?.onUpdate) {
+      state.onUpdate(this.context, delta);
+    }
+    this.evaluate();
+  }
+  /**
+   * Check if we're in a specific state.
+   */
+  isInState(stateName) {
+    return this.currentStateName === stateName;
+  }
+  executeTransition(transition) {
+    const fromState = this.states.get(this.currentStateName);
+    if (fromState?.onExit) fromState.onExit(this.context);
+    if (transition.action) transition.action(this.context);
+    this.enterState(transition.to);
+  }
+  enterState(stateName) {
+    this.previousStateName = this.currentStateName;
+    this.currentStateName = stateName;
+    this.history.push(stateName);
+    if (this.history.length > this.maxHistory) {
+      this.history.shift();
+    }
+    const state = this.states.get(stateName);
+    if (state?.onEnter) state.onEnter(this.context);
+  }
+};
+
+// src/behavior/StateTrait.ts
+var nodeStateMachines = /* @__PURE__ */ new Map();
+var stateTraitHandler = {
+  name: "state",
+  defaultConfig: { machine: { initialState: "idle", states: [], transitions: [] } },
+  onAttach(node, config, _context) {
+    const nodeId = node.id;
+    const sm = new StateMachine(config.machine);
+    nodeStateMachines.set(nodeId, sm);
+    if (node.properties) {
+      node.properties._state = sm.getCurrentState();
+    }
+  },
+  onDetach(node, _config, _context) {
+    nodeStateMachines.delete(node.id);
+  },
+  onUpdate(node, _config, _context, delta) {
+    const sm = nodeStateMachines.get(node.id);
+    if (!sm) return;
+    sm.update(delta);
+    if (node.properties) {
+      node.properties._state = sm.getCurrentState();
+    }
+  }
+};
+function getNodeStateMachine(nodeId) {
+  return nodeStateMachines.get(nodeId);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ActionNode,
+  BehaviorTree,
+  ConditionNode,
+  InverterNode,
+  RepeaterNode,
+  SelectorNode,
+  SequenceNode,
+  StateMachine,
+  WaitNode,
+  createAlertBehavior,
+  createFollowBehavior,
+  createIdleBehavior,
+  createInteractBehavior,
+  createPatrolBehavior,
+  getNodeStateMachine,
+  stateTraitHandler
+});

package/dist/behavior.d.cts

@@ -0,0 +1,130 @@
+import { B as BTNode } from './BehaviorTree-BrBFECv5.cjs';
+export { A as ActionNode, a as BTContext, b as BehaviorTree, C as ConditionNode, I as InverterNode, N as NodeStatus, R as RepeaterNode, S as SelectorNode, c as SequenceNode, W as WaitNode } from './BehaviorTree-BrBFECv5.cjs';
+import { TraitHandler } from '@holoscript/core';
+
+/**
+ * BehaviorPresets.ts
+ *
+ * Pre-built behavior tree patterns for common NPC and object behaviors.
+ */
+
+/**
+ * Patrol: Move between waypoints with pauses.
+ */
+declare function createPatrolBehavior(waypointCount?: number, pauseDuration?: number): BTNode;
+/**
+ * Idle: Wait, look around, repeat.
+ */
+declare function createIdleBehavior(idleDuration?: number): BTNode;
+/**
+ * Interact: Approach target, interact, return to origin.
+ */
+declare function createInteractBehavior(): BTNode;
+/**
+ * Follow: Follow a target entity, maintaining distance.
+ */
+declare function createFollowBehavior(minDist?: number): BTNode;
+/**
+ * Alert: Check for threats, flee or fight.
+ */
+declare function createAlertBehavior(): BTNode;
+
+/**
+ * StateMachine.ts
+ *
+ * Finite State Machine (FSM) for game logic, NPC AI, and UI state management.
+ * Supports:
+ * - Named states with enter/update/exit callbacks
+ * - Guarded transitions (conditions that must be true to transition)
+ * - Transition actions (side effects on transition)
+ * - Event-driven and tick-driven transitions
+ * - State history tracking
+ */
+interface StateConfig {
+    name: string;
+    onEnter?: (context: Record<string, unknown>) => void;
+    onUpdate?: (context: Record<string, unknown>, delta: number) => void;
+    onExit?: (context: Record<string, unknown>) => void;
+}
+interface TransitionConfig {
+    from: string;
+    to: string;
+    event?: string;
+    guard?: (context: Record<string, unknown>) => boolean;
+    action?: (context: Record<string, unknown>) => void;
+}
+interface StateMachineConfig {
+    initialState: string;
+    states: StateConfig[];
+    transitions: TransitionConfig[];
+    context?: Record<string, unknown>;
+}
+declare class StateMachine {
+    private states;
+    private transitions;
+    private currentStateName;
+    private previousStateName;
+    private context;
+    private history;
+    private maxHistory;
+    constructor(config: StateMachineConfig);
+    /**
+     * Get the current state name.
+     */
+    getCurrentState(): string;
+    /**
+     * Get the previous state name.
+     */
+    getPreviousState(): string;
+    /**
+     * Get the shared context.
+     */
+    getContext(): Record<string, unknown>;
+    /**
+     * Get state transition history.
+     */
+    getHistory(): string[];
+    /**
+     * Send an event to the state machine. May trigger a transition.
+     */
+    send(event: string): boolean;
+    /**
+     * Try to transition based on guards (no event, just check conditions).
+     * Called automatically during update, or manually.
+     */
+    evaluate(): boolean;
+    /**
+     * Force a transition to a specific state (bypasses guards).
+     */
+    forceTransition(stateName: string): void;
+    /**
+     * Update the state machine. Call every frame.
+     */
+    update(delta: number): void;
+    /**
+     * Check if we're in a specific state.
+     */
+    isInState(stateName: string): boolean;
+    private executeTransition;
+    private enterState;
+}
+
+/**
+ * StateTrait.ts
+ *
+ * Declarative FSM attachment to HoloScript+ nodes.
+ * Allows nodes to define states and transitions as trait config.
+ *
+ * @trait state
+ */
+
+interface StateTraitConfig {
+    machine: StateMachineConfig;
+}
+declare const stateTraitHandler: TraitHandler<StateTraitConfig>;
+/**
+ * Get the StateMachine for a given node (for external event sending).
+ */
+declare function getNodeStateMachine(nodeId: string): StateMachine | undefined;
+
+export { BTNode, type StateConfig, StateMachine, type StateMachineConfig, type StateTraitConfig, type TransitionConfig, createAlertBehavior, createFollowBehavior, createIdleBehavior, createInteractBehavior, createPatrolBehavior, getNodeStateMachine, stateTraitHandler };

package/dist/behavior.d.ts

@@ -0,0 +1,130 @@
+import { B as BTNode } from './BehaviorTree-BrBFECv5.js';
+export { A as ActionNode, a as BTContext, b as BehaviorTree, C as ConditionNode, I as InverterNode, N as NodeStatus, R as RepeaterNode, S as SelectorNode, c as SequenceNode, W as WaitNode } from './BehaviorTree-BrBFECv5.js';
+import { TraitHandler } from '@holoscript/core';
+
+/**
+ * BehaviorPresets.ts
+ *
+ * Pre-built behavior tree patterns for common NPC and object behaviors.
+ */
+
+/**
+ * Patrol: Move between waypoints with pauses.
+ */
+declare function createPatrolBehavior(waypointCount?: number, pauseDuration?: number): BTNode;
+/**
+ * Idle: Wait, look around, repeat.
+ */
+declare function createIdleBehavior(idleDuration?: number): BTNode;
+/**
+ * Interact: Approach target, interact, return to origin.
+ */
+declare function createInteractBehavior(): BTNode;
+/**
+ * Follow: Follow a target entity, maintaining distance.
+ */
+declare function createFollowBehavior(minDist?: number): BTNode;
+/**
+ * Alert: Check for threats, flee or fight.
+ */
+declare function createAlertBehavior(): BTNode;
+
+/**
+ * StateMachine.ts
+ *
+ * Finite State Machine (FSM) for game logic, NPC AI, and UI state management.
+ * Supports:
+ * - Named states with enter/update/exit callbacks
+ * - Guarded transitions (conditions that must be true to transition)
+ * - Transition actions (side effects on transition)
+ * - Event-driven and tick-driven transitions
+ * - State history tracking
+ */
+interface StateConfig {
+    name: string;
+    onEnter?: (context: Record<string, unknown>) => void;
+    onUpdate?: (context: Record<string, unknown>, delta: number) => void;
+    onExit?: (context: Record<string, unknown>) => void;
+}
+interface TransitionConfig {
+    from: string;
+    to: string;
+    event?: string;
+    guard?: (context: Record<string, unknown>) => boolean;
+    action?: (context: Record<string, unknown>) => void;
+}
+interface StateMachineConfig {
+    initialState: string;
+    states: StateConfig[];
+    transitions: TransitionConfig[];
+    context?: Record<string, unknown>;
+}
+declare class StateMachine {
+    private states;
+    private transitions;
+    private currentStateName;
+    private previousStateName;
+    private context;
+    private history;
+    private maxHistory;
+    constructor(config: StateMachineConfig);
+    /**
+     * Get the current state name.
+     */
+    getCurrentState(): string;
+    /**
+     * Get the previous state name.
+     */
+    getPreviousState(): string;
+    /**
+     * Get the shared context.
+     */
+    getContext(): Record<string, unknown>;
+    /**
+     * Get state transition history.
+     */
+    getHistory(): string[];
+    /**
+     * Send an event to the state machine. May trigger a transition.
+     */
+    send(event: string): boolean;
+    /**
+     * Try to transition based on guards (no event, just check conditions).
+     * Called automatically during update, or manually.
+     */
+    evaluate(): boolean;
+    /**
+     * Force a transition to a specific state (bypasses guards).
+     */
+    forceTransition(stateName: string): void;
+    /**
+     * Update the state machine. Call every frame.
+     */
+    update(delta: number): void;
+    /**
+     * Check if we're in a specific state.
+     */
+    isInState(stateName: string): boolean;
+    private executeTransition;
+    private enterState;
+}
+
+/**
+ * StateTrait.ts
+ *
+ * Declarative FSM attachment to HoloScript+ nodes.
+ * Allows nodes to define states and transitions as trait config.
+ *
+ * @trait state
+ */
+
+interface StateTraitConfig {
+    machine: StateMachineConfig;
+}
+declare const stateTraitHandler: TraitHandler<StateTraitConfig>;
+/**
+ * Get the StateMachine for a given node (for external event sending).
+ */
+declare function getNodeStateMachine(nodeId: string): StateMachine | undefined;
+
+export { BTNode, type StateConfig, StateMachine, type StateMachineConfig, type StateTraitConfig, type TransitionConfig, createAlertBehavior, createFollowBehavior, createIdleBehavior, createInteractBehavior, createPatrolBehavior, getNodeStateMachine, stateTraitHandler };