@holoscript/framework 6.0.3

package/src/ai/BehaviorTree.ts

@@ -0,0 +1,153 @@
+/**
+ * BehaviorTree.ts
+ *
+ * Behavior tree runner: tick-based evaluation, status propagation,
+ * subtree mounting, conditional abort, and debug tracing.
+ *
+ * @module ai
+ */
+
+import { BTNode, BTStatus } from './BTNodes';
+import { Blackboard } from './Blackboard';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface BTContext {
+  blackboard: Blackboard;
+  deltaTime: number;
+  entity: string;
+}
+
+export interface BTTreeDef {
+  id: string;
+  root: BTNode;
+  context: BTContext;
+  status: BTStatus;
+  tickCount: number;
+  aborted: boolean;
+}
+
+// =============================================================================
+// BEHAVIOR TREE
+// =============================================================================
+
+export class BehaviorTree {
+  private trees: Map<string, BTTreeDef> = new Map();
+  private subtrees: Map<string, BTNode> = new Map();
+  private debugTrace: Array<{ tree: string; node: string; status: BTStatus; tick: number }> = [];
+  private tracing = false;
+
+  // ---------------------------------------------------------------------------
+  // Tree Management
+  // ---------------------------------------------------------------------------
+
+  createTree(id: string, root: BTNode, entity: string, blackboard?: Blackboard): BTTreeDef {
+    const tree: BTTreeDef = {
+      id,
+      root,
+      context: { blackboard: blackboard ?? new Blackboard(), deltaTime: 0, entity },
+      status: 'ready',
+      tickCount: 0,
+      aborted: false,
+    };
+    this.trees.set(id, tree);
+    return tree;
+  }
+
+  removeTree(id: string): boolean {
+    return this.trees.delete(id);
+  }
+  getTree(id: string): BTTreeDef | undefined {
+    return this.trees.get(id);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Subtree Registry
+  // ---------------------------------------------------------------------------
+
+  registerSubtree(name: string, root: BTNode): void {
+    this.subtrees.set(name, root);
+  }
+
+  getSubtree(name: string): BTNode | undefined {
+    return this.subtrees.get(name);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Tick
+  // ---------------------------------------------------------------------------
+
+  tick(id: string, dt: number): BTStatus {
+    const tree = this.trees.get(id);
+    if (!tree) return 'failure';
+
+    tree.context.deltaTime = dt;
+    tree.tickCount++;
+    tree.aborted = false;
+
+    const status = this.tickNode(tree.root, tree.context, tree);
+    tree.status = status;
+    return status;
+  }
+
+  tickAll(dt: number): void {
+    for (const id of this.trees.keys()) {
+      this.tick(id, dt);
+    }
+  }
+
+  private tickNode(node: BTNode, ctx: BTContext, tree: BTTreeDef): BTStatus {
+    if (tree.aborted) return 'failure';
+
+    const status = node.tick(ctx);
+
+    if (this.tracing) {
+      this.debugTrace.push({ tree: tree.id, node: node.name, status, tick: tree.tickCount });
+      if (this.debugTrace.length > 500) this.debugTrace.shift();
+    }
+
+    return status;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Abort
+  // ---------------------------------------------------------------------------
+
+  abort(id: string): void {
+    const tree = this.trees.get(id);
+    if (tree) {
+      tree.aborted = true;
+      tree.status = 'failure';
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Debug
+  // ---------------------------------------------------------------------------
+
+  enableTracing(): void {
+    this.tracing = true;
+  }
+  disableTracing(): void {
+    this.tracing = false;
+  }
+  getTrace(): typeof this.debugTrace {
+    return [...this.debugTrace];
+  }
+  clearTrace(): void {
+    this.debugTrace = [];
+  }
+
+  // ---------------------------------------------------------------------------
+  // Queries
+  // ---------------------------------------------------------------------------
+
+  getTreeCount(): number {
+    return this.trees.size;
+  }
+  getStatus(id: string): BTStatus {
+    return this.trees.get(id)?.status ?? 'failure';
+  }
+}

package/src/ai/Blackboard.ts

@@ -0,0 +1,165 @@
+/**
+ * Blackboard.ts
+ *
+ * Shared key-value state for behavior trees: scoped data,
+ * observer notifications, and history tracking.
+ *
+ * @module ai
+ */
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface BBEntry {
+  key: string;
+  value: unknown;
+  scope: string;
+  version: number;
+  timestamp: number;
+}
+
+// =============================================================================
+// BLACKBOARD
+// =============================================================================
+
+export class Blackboard {
+  private data: Map<string, BBEntry> = new Map();
+  private observers: Map<string, Array<(key: string, value: unknown, old: unknown) => void>> =
+    new Map();
+  private scopes: Map<string, Set<string>> = new Map(); // scope → keys
+  private history: Array<{ key: string; old: unknown; value: unknown; timestamp: number }> = [];
+  private maxHistory = 100;
+
+  // ---------------------------------------------------------------------------
+  // Get / Set
+  // ---------------------------------------------------------------------------
+
+  set(key: string, value: unknown, scope = 'global'): void {
+    const existing = this.data.get(key);
+    const old = existing?.value;
+
+    this.data.set(key, {
+      key,
+      value,
+      scope,
+      version: existing ? existing.version + 1 : 0,
+      timestamp: Date.now(),
+    });
+
+    // Track scope
+    if (!this.scopes.has(scope)) this.scopes.set(scope, new Set());
+    this.scopes.get(scope)!.add(key);
+
+    // History
+    this.history.push({ key, old, value, timestamp: Date.now() });
+    if (this.history.length > this.maxHistory) this.history.shift();
+
+    // Notify
+    this.notifyObservers(key, value, old);
+  }
+
+  get<T = unknown>(key: string): T | undefined {
+    return this.data.get(key)?.value as T | undefined;
+  }
+
+  has(key: string): boolean {
+    return this.data.has(key);
+  }
+
+  delete(key: string): boolean {
+    const entry = this.data.get(key);
+    if (!entry) return false;
+    this.scopes.get(entry.scope)?.delete(key);
+    return this.data.delete(key);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Scopes
+  // ---------------------------------------------------------------------------
+
+  getByScope(scope: string): Map<string, unknown> {
+    const result = new Map<string, unknown>();
+    const keys = this.scopes.get(scope);
+    if (!keys) return result;
+    for (const key of keys) {
+      const entry = this.data.get(key);
+      if (entry) result.set(key, entry.value);
+    }
+    return result;
+  }
+
+  clearScope(scope: string): number {
+    const keys = this.scopes.get(scope);
+    if (!keys) return 0;
+    let count = 0;
+    for (const key of keys) {
+      if (this.data.delete(key)) count++;
+    }
+    keys.clear();
+    return count;
+  }
+
+  getScopes(): string[] {
+    return [...this.scopes.keys()];
+  }
+
+  // ---------------------------------------------------------------------------
+  // Observers
+  // ---------------------------------------------------------------------------
+
+  observe(key: string, callback: (key: string, value: unknown, old: unknown) => void): void {
+    if (!this.observers.has(key)) this.observers.set(key, []);
+    this.observers.get(key)!.push(callback);
+  }
+
+  observeAll(callback: (key: string, value: unknown, old: unknown) => void): void {
+    this.observe('*', callback);
+  }
+
+  private notifyObservers(key: string, value: unknown, old: unknown): void {
+    const specific = this.observers.get(key);
+    if (specific) for (const cb of specific) cb(key, value, old);
+    const wildcard = this.observers.get('*');
+    if (wildcard) for (const cb of wildcard) cb(key, value, old);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Queries
+  // ---------------------------------------------------------------------------
+
+  getEntryCount(): number {
+    return this.data.size;
+  }
+  getKeys(): string[] {
+    return [...this.data.keys()];
+  }
+  getVersion(key: string): number {
+    return this.data.get(key)?.version ?? -1;
+  }
+  getHistory(): typeof this.history {
+    return [...this.history];
+  }
+
+  clear(): void {
+    this.data.clear();
+    this.scopes.clear();
+    this.history = [];
+  }
+
+  // ---------------------------------------------------------------------------
+  // Serialization
+  // ---------------------------------------------------------------------------
+
+  toJSON(): Record<string, unknown> {
+    const result: Record<string, unknown> = {};
+    for (const [key, entry] of this.data) result[key] = entry.value;
+    return result;
+  }
+
+  fromJSON(data: Record<string, unknown>, scope = 'global'): void {
+    for (const [key, value] of Object.entries(data)) {
+      this.set(key, value, scope);
+    }
+  }
+}