@holoscript/framework 6.0.3

package/src/ai/InfluenceMap.ts

@@ -0,0 +1,180 @@
+/**
+ * InfluenceMap.ts
+ *
+ * Grid-based influence map: propagation, decay, multi-layer
+ * support, and spatial queries.
+ *
+ * @module ai
+ */
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface InfluenceConfig {
+  width: number;
+  height: number;
+  cellSize: number;
+  decayRate: number; // 0-1 per update
+  propagationRate: number; // 0-1 spread to neighbors
+  maxValue: number;
+}
+
+// =============================================================================
+// INFLUENCE MAP
+// =============================================================================
+
+export class InfluenceMap {
+  private layers: Map<string, Float32Array> = new Map();
+  private config: InfluenceConfig;
+
+  constructor(config: InfluenceConfig) {
+    this.config = config;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Layer Management
+  // ---------------------------------------------------------------------------
+
+  addLayer(name: string): void {
+    const size = this.config.width * this.config.height;
+    this.layers.set(name, new Float32Array(size));
+  }
+
+  removeLayer(name: string): void {
+    this.layers.delete(name);
+  }
+  getLayerNames(): string[] {
+    return [...this.layers.keys()];
+  }
+
+  // ---------------------------------------------------------------------------
+  // Influence Modification
+  // ---------------------------------------------------------------------------
+
+  setInfluence(layer: string, gx: number, gy: number, value: number): void {
+    const grid = this.layers.get(layer);
+    if (!grid || gx < 0 || gx >= this.config.width || gy < 0 || gy >= this.config.height) return;
+    grid[gy * this.config.width + gx] = Math.min(
+      this.config.maxValue,
+      Math.max(-this.config.maxValue, value)
+    );
+  }
+
+  addInfluence(layer: string, gx: number, gy: number, value: number): void {
+    const grid = this.layers.get(layer);
+    if (!grid || gx < 0 || gx >= this.config.width || gy < 0 || gy >= this.config.height) return;
+    const idx = gy * this.config.width + gx;
+    grid[idx] = Math.min(this.config.maxValue, Math.max(-this.config.maxValue, grid[idx] + value));
+  }
+
+  stampRadius(layer: string, cx: number, cy: number, radius: number, value: number): void {
+    for (
+      let y = Math.max(0, cy - radius);
+      y <= Math.min(this.config.height - 1, cy + radius);
+      y++
+    ) {
+      for (
+        let x = Math.max(0, cx - radius);
+        x <= Math.min(this.config.width - 1, cx + radius);
+        x++
+      ) {
+        const dx = x - cx,
+          dy = y - cy;
+        const dist = Math.sqrt(dx * dx + dy * dy);
+        if (dist <= radius) {
+          const falloff = 1 - dist / radius;
+          this.addInfluence(layer, x, y, value * falloff);
+        }
+      }
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Propagation & Decay
+  // ---------------------------------------------------------------------------
+
+  update(): void {
+    for (const [name, grid] of this.layers) {
+      const { width, height, decayRate, propagationRate } = this.config;
+      const next = new Float32Array(grid.length);
+
+      for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+          const idx = y * width + x;
+          let neighborSum = 0;
+          let neighborCount = 0;
+
+          // 4-directional neighbors
+          if (x > 0) {
+            neighborSum += grid[idx - 1];
+            neighborCount++;
+          }
+          if (x < width - 1) {
+            neighborSum += grid[idx + 1];
+            neighborCount++;
+          }
+          if (y > 0) {
+            neighborSum += grid[idx - width];
+            neighborCount++;
+          }
+          if (y < height - 1) {
+            neighborSum += grid[idx + width];
+            neighborCount++;
+          }
+
+          const avgNeighbor = neighborCount > 0 ? neighborSum / neighborCount : 0;
+          const propagated = grid[idx] + (avgNeighbor - grid[idx]) * propagationRate;
+          next[idx] = propagated * (1 - decayRate);
+        }
+      }
+
+      this.layers.set(name, next);
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Queries
+  // ---------------------------------------------------------------------------
+
+  getInfluence(layer: string, gx: number, gy: number): number {
+    const grid = this.layers.get(layer);
+    if (!grid || gx < 0 || gx >= this.config.width || gy < 0 || gy >= this.config.height) return 0;
+    return grid[gy * this.config.width + gx];
+  }
+
+  getInfluenceAtWorld(layer: string, wx: number, wy: number): number {
+    const gx = Math.floor(wx / this.config.cellSize);
+    const gy = Math.floor(wy / this.config.cellSize);
+    return this.getInfluence(layer, gx, gy);
+  }
+
+  getMaxCell(layer: string): { x: number; y: number; value: number } {
+    const grid = this.layers.get(layer);
+    if (!grid) return { x: 0, y: 0, value: 0 };
+
+    let maxIdx = 0,
+      maxVal = grid[0];
+    for (let i = 1; i < grid.length; i++) {
+      if (grid[i] > maxVal) {
+        maxVal = grid[i];
+        maxIdx = i;
+      }
+    }
+
+    return {
+      x: maxIdx % this.config.width,
+      y: Math.floor(maxIdx / this.config.width),
+      value: maxVal,
+    };
+  }
+
+  clear(layer: string): void {
+    const grid = this.layers.get(layer);
+    if (grid) grid.fill(0);
+  }
+
+  clearAll(): void {
+    for (const grid of this.layers.values()) grid.fill(0);
+  }
+}

package/src/ai/NavMesh.ts

@@ -0,0 +1,168 @@
+/**
+ * NavMesh — Navigation mesh with polygon walk and path smoothing
+ *
+ * @version 1.0.0
+ */
+
+export interface NavPolygon {
+  id: number;
+  vertices: { x: number; z: number }[];
+  neighbors: number[];
+  center: { x: number; z: number };
+  walkable: boolean;
+  cost: number;
+}
+
+export interface NavPath {
+  waypoints: { x: number; z: number }[];
+  totalCost: number;
+  polygonIds: number[];
+}
+
+export class NavMesh {
+  private polygons: Map<number, NavPolygon> = new Map();
+  private nextId: number = 0;
+
+  /**
+   * Add a navigation polygon
+   */
+  addPolygon(
+    vertices: { x: number; z: number }[],
+    walkable: boolean = true,
+    cost: number = 1
+  ): number {
+    const id = this.nextId++;
+    const cx = vertices.reduce((s, v) => s + v.x, 0) / vertices.length;
+    const cz = vertices.reduce((s, v) => s + v.z, 0) / vertices.length;
+    this.polygons.set(id, {
+      id,
+      vertices,
+      neighbors: [],
+      center: { x: cx, z: cz },
+      walkable,
+      cost,
+    });
+    return id;
+  }
+
+  /**
+   * Connect two polygons as neighbors
+   */
+  connect(a: number, b: number): boolean {
+    const pa = this.polygons.get(a);
+    const pb = this.polygons.get(b);
+    if (!pa || !pb) return false;
+    if (!pa.neighbors.includes(b)) pa.neighbors.push(b);
+    if (!pb.neighbors.includes(a)) pb.neighbors.push(a);
+    return true;
+  }
+
+  /**
+   * Find path using A*
+   */
+  findPath(startPoly: number, endPoly: number): NavPath | null {
+    const start = this.polygons.get(startPoly);
+    const end = this.polygons.get(endPoly);
+    if (!start || !end || !start.walkable || !end.walkable) return null;
+
+    const openSet = new Set<number>([startPoly]);
+    const cameFrom = new Map<number, number>();
+    const gScore = new Map<number, number>();
+    const fScore = new Map<number, number>();
+
+    gScore.set(startPoly, 0);
+    fScore.set(startPoly, this.heuristic(start.center, end.center));
+
+    while (openSet.size > 0) {
+      // Get node with lowest fScore
+      let current = -1;
+      let lowestF = Infinity;
+      for (const id of openSet) {
+        const f = fScore.get(id) ?? Infinity;
+        if (f < lowestF) {
+          lowestF = f;
+          current = id;
+        }
+      }
+
+      if (current === endPoly) {
+        return this.reconstructPath(cameFrom, current, gScore.get(current) ?? 0);
+      }
+
+      openSet.delete(current);
+      const currentPoly = this.polygons.get(current)!;
+
+      for (const neighborId of currentPoly.neighbors) {
+        const neighbor = this.polygons.get(neighborId);
+        if (!neighbor || !neighbor.walkable) continue;
+
+        const tentativeG =
+          (gScore.get(current) ?? Infinity) +
+          this.heuristic(currentPoly.center, neighbor.center) * neighbor.cost;
+
+        if (tentativeG < (gScore.get(neighborId) ?? Infinity)) {
+          cameFrom.set(neighborId, current);
+          gScore.set(neighborId, tentativeG);
+          fScore.set(neighborId, tentativeG + this.heuristic(neighbor.center, end.center));
+          openSet.add(neighborId);
+        }
+      }
+    }
+
+    return null; // No path
+  }
+
+  /**
+   * Smooth a path using string-pulling (funnel algorithm simplified)
+   */
+  smoothPath(path: NavPath): NavPath {
+    if (path.waypoints.length <= 2) return path;
+
+    const smoothed: { x: number; z: number }[] = [path.waypoints[0]];
+    let i = 0;
+
+    while (i < path.waypoints.length - 1) {
+      let farthest = i + 1;
+      for (let j = i + 2; j < path.waypoints.length; j++) {
+        // Simple line-of-sight check via distance
+        const dx = path.waypoints[j].x - path.waypoints[i].x;
+        const dz = path.waypoints[j].z - path.waypoints[i].z;
+        const dist = Math.sqrt(dx * dx + dz * dz);
+        if (dist < 50) farthest = j; // Simplified — skip intermediate points within range
+      }
+      smoothed.push(path.waypoints[farthest]);
+      i = farthest;
+    }
+
+    return { waypoints: smoothed, totalCost: path.totalCost, polygonIds: path.polygonIds };
+  }
+
+  private reconstructPath(
+    cameFrom: Map<number, number>,
+    current: number,
+    totalCost: number
+  ): NavPath {
+    const polygonIds: number[] = [current];
+    while (cameFrom.has(current)) {
+      current = cameFrom.get(current)!;
+      polygonIds.unshift(current);
+    }
+    const waypoints = polygonIds.map((id) => this.polygons.get(id)!.center);
+    return { waypoints, totalCost, polygonIds };
+  }
+
+  private heuristic(a: { x: number; z: number }, b: { x: number; z: number }): number {
+    return Math.sqrt((a.x - b.x) ** 2 + (a.z - b.z) ** 2);
+  }
+
+  getPolygon(id: number): NavPolygon | undefined {
+    return this.polygons.get(id);
+  }
+  getPolygonCount(): number {
+    return this.polygons.size;
+  }
+  setWalkable(id: number, walkable: boolean): void {
+    const p = this.polygons.get(id);
+    if (p) p.walkable = walkable;
+  }
+}

package/src/ai/PerceptionSystem.ts

@@ -0,0 +1,178 @@
+/**
+ * PerceptionSystem.ts
+ *
+ * AI perception: sight/hearing/smell sense cones, stimulus memory,
+ * priority scoring, and detection events.
+ *
+ * @module ai
+ */
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export type SenseType = 'sight' | 'hearing' | 'smell';
+
+export interface Stimulus {
+  id: string;
+  type: SenseType;
+  sourceId: string;
+  position: { x: number; y: number; z: number };
+  intensity: number; // 0-1
+  timestamp: number;
+  data?: unknown;
+}
+
+export interface SenseConfig {
+  type: SenseType;
+  range: number;
+  fov: number; // Degrees (360 = omnidirectional)
+  sensitivity: number; // Multiplier on intensity
+}
+
+export interface PerceivedStimulus extends Stimulus {
+  awareness: number; // 0-1 (increases with exposure)
+  lastSeen: number;
+}
+
+// =============================================================================
+// PERCEPTION SYSTEM
+// =============================================================================
+
+export class PerceptionSystem {
+  // Per-entity: senses config, memory of perceived stimuli
+  private entities: Map<
+    string,
+    {
+      senses: SenseConfig[];
+      facing: { x: number; y: number; z: number };
+      position: { x: number; y: number; z: number };
+      memory: Map<string, PerceivedStimulus>;
+      memoryDuration: number;
+    }
+  > = new Map();
+
+  // Active stimuli in the world
+  private stimuli: Map<string, Stimulus> = new Map();
+
+  // ---------------------------------------------------------------------------
+  // Entity Registration
+  // ---------------------------------------------------------------------------
+
+  registerEntity(id: string, senses: SenseConfig[], memoryDuration = 10): void {
+    this.entities.set(id, {
+      senses,
+      facing: { x: 0, y: 0, z: 1 },
+      position: { x: 0, y: 0, z: 0 },
+      memory: new Map(),
+      memoryDuration,
+    });
+  }
+
+  setEntityTransform(
+    entityId: string,
+    position: { x: number; y: number; z: number },
+    facing: { x: number; y: number; z: number }
+  ): void {
+    const e = this.entities.get(entityId);
+    if (e) {
+      e.position = position;
+      e.facing = facing;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Stimuli
+  // ---------------------------------------------------------------------------
+
+  addStimulus(stimulus: Stimulus): void {
+    this.stimuli.set(stimulus.id, stimulus);
+  }
+  removeStimulus(id: string): void {
+    this.stimuli.delete(id);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Perception Update
+  // ---------------------------------------------------------------------------
+
+  update(time: number): void {
+    for (const [entityId, entity] of this.entities) {
+      // Expire old memories
+      for (const [stimId, mem] of entity.memory) {
+        if (time - mem.lastSeen > entity.memoryDuration) {
+          entity.memory.delete(stimId);
+        }
+      }
+
+      // Check each stimulus against senses
+      for (const stim of this.stimuli.values()) {
+        if (stim.sourceId === entityId) continue; // Can't sense yourself
+
+        for (const sense of entity.senses) {
+          if (sense.type !== stim.type) continue;
+
+          const dx = stim.position.x - entity.position.x;
+          const dy = stim.position.y - entity.position.y;
+          const dz = stim.position.z - entity.position.z;
+          const dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
+
+          // Range check
+          if (dist > sense.range) continue;
+
+          // FOV check (only for directional senses)
+          if (sense.fov < 360 && dist > 0) {
+            const fLen =
+              Math.sqrt(entity.facing.x ** 2 + entity.facing.y ** 2 + entity.facing.z ** 2) || 1;
+            const dot =
+              (dx * entity.facing.x + dy * entity.facing.y + dz * entity.facing.z) / (dist * fLen);
+            const halfFovRad = (sense.fov / 2) * (Math.PI / 180);
+            if (dot < Math.cos(halfFovRad)) continue;
+          }
+
+          // Perceived!
+          const distFactor = 1 - dist / sense.range;
+          const effectiveIntensity = stim.intensity * distFactor * sense.sensitivity;
+
+          const existing = entity.memory.get(stim.id);
+          if (existing) {
+            existing.awareness = Math.min(1, existing.awareness + effectiveIntensity * 0.1);
+            existing.lastSeen = time;
+            existing.position = { ...stim.position };
+          } else {
+            entity.memory.set(stim.id, {
+              ...stim,
+              awareness: Math.min(1, effectiveIntensity),
+              lastSeen: time,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Queries
+  // ---------------------------------------------------------------------------
+
+  getPerceivedStimuli(entityId: string): PerceivedStimulus[] {
+    const e = this.entities.get(entityId);
+    return e ? [...e.memory.values()] : [];
+  }
+
+  getHighestPriority(entityId: string): PerceivedStimulus | null {
+    const perceived = this.getPerceivedStimuli(entityId);
+    if (perceived.length === 0) return null;
+    return perceived.reduce((best, s) =>
+      s.awareness * s.intensity > best.awareness * best.intensity ? s : best
+    );
+  }
+
+  isAwareOf(entityId: string, stimulusId: string): boolean {
+    return this.entities.get(entityId)?.memory.has(stimulusId) ?? false;
+  }
+
+  getStimulusCount(): number {
+    return this.stimuli.size;
+  }
+}