@aura3d/scripting 1.3.3 → 1.4.1

package/src/HTN.ts

@@ -1,178 +0,0 @@
-import { WorldState, type GOAPStateShape } from "./GOAP";
-
-export type HTNTaskResult = "success" | "running" | "failure";
-export type HTNTaskType = "primitive" | "compound";
-
-export interface HTNTaskMethod {
-  readonly name: string;
-  readonly preconditions?: GOAPStateShape;
-  readonly subtasks: readonly HTNTask[];
-  readonly priority?: number;
-  readonly check?: (state: WorldState, context: unknown) => boolean;
-}
-
-export interface HTNPrimitiveTaskOptions {
-  readonly name: string;
-  readonly preconditions?: GOAPStateShape;
-  readonly effects?: GOAPStateShape;
-  readonly execute?: (state: WorldState, context: unknown) => HTNTaskResult;
-}
-
-export interface HTNCompoundTaskOptions {
-  readonly name: string;
-  readonly methods?: readonly HTNTaskMethod[];
-}
-
-export interface HTNPlannerOptions {
-  readonly maxDepth?: number;
-  readonly maxIterations?: number;
-}
-
-export interface HTNPlan {
-  readonly valid: boolean;
-  readonly rootTask: string;
-  readonly tasks: readonly string[];
-  readonly methodTrace: readonly string[];
-  readonly decompositions: number;
-  readonly maxDepthReached: number;
-  readonly iterations: number;
-  readonly finalState: GOAPStateShape;
-}
-
-type DecomposeStats = {
-  decompositions: number;
-  iterations: number;
-  maxDepthReached: number;
-  methodTrace: string[];
-};
-
-type DecomposeResult = {
-  readonly valid: boolean;
-  readonly tasks: readonly HTNTask[];
-  readonly state: WorldState;
-};
-
-export class HTNTask {
-  readonly name: string;
-  readonly type: HTNTaskType;
-  readonly preconditions: GOAPStateShape;
-  readonly effects: GOAPStateShape;
-  private readonly methods: HTNTaskMethod[];
-  private readonly executeCallback?: (state: WorldState, context: unknown) => HTNTaskResult;
-
-  private constructor(options: {
-    readonly name: string;
-    readonly type: HTNTaskType;
-    readonly preconditions?: GOAPStateShape;
-    readonly effects?: GOAPStateShape;
-    readonly methods?: readonly HTNTaskMethod[];
-    readonly execute?: (state: WorldState, context: unknown) => HTNTaskResult;
-  }) {
-    if (options.name.trim().length === 0) throw new Error("HTN task name cannot be empty.");
-    this.name = options.name;
-    this.type = options.type;
-    this.preconditions = options.preconditions ?? {};
-    this.effects = options.effects ?? {};
-    this.methods = [...(options.methods ?? [])].sort((left, right) => (right.priority ?? 0) - (left.priority ?? 0) || left.name.localeCompare(right.name));
-    this.executeCallback = options.execute;
-  }
-
-  static primitive(options: HTNPrimitiveTaskOptions): HTNTask {
-    return new HTNTask({ ...options, type: "primitive" });
-  }
-
-  static compound(options: HTNCompoundTaskOptions): HTNTask {
-    return new HTNTask({ ...options, type: "compound" });
-  }
-
-  getMethods(): readonly HTNTaskMethod[] {
-    return this.methods;
-  }
-
-  canRun(state: WorldState): boolean {
-    return state.matches(this.preconditions);
-  }
-
-  applyEffects(state: WorldState): WorldState {
-    return state.apply(this.effects);
-  }
-
-  execute(state: WorldState, context: unknown): HTNTaskResult {
-    if (this.type !== "primitive") return "failure";
-    return this.executeCallback?.(state, context) ?? "success";
-  }
-}
-
-export class HTNPlanner {
-  private readonly maxDepth: number;
-  private readonly maxIterations: number;
-
-  constructor(options: HTNPlannerOptions = {}) {
-    this.maxDepth = options.maxDepth ?? 12;
-    this.maxIterations = options.maxIterations ?? 128;
-    if (!Number.isInteger(this.maxDepth) || this.maxDepth < 1) throw new RangeError("HTN maxDepth must be a positive integer.");
-    if (!Number.isInteger(this.maxIterations) || this.maxIterations < 1) throw new RangeError("HTN maxIterations must be a positive integer.");
-  }
-
-  plan(rootTask: HTNTask, initialState: WorldState, context: unknown = {}): HTNPlan {
-    const stats: DecomposeStats = {
-      decompositions: 0,
-      iterations: 0,
-      maxDepthReached: 0,
-      methodTrace: []
-    };
-    const result = this.decompose([rootTask], initialState.clone(), context, 0, stats);
-    return {
-      valid: result.valid,
-      rootTask: rootTask.name,
-      tasks: result.tasks.map((task) => task.name),
-      methodTrace: stats.methodTrace,
-      decompositions: stats.decompositions,
-      maxDepthReached: stats.maxDepthReached,
-      iterations: stats.iterations,
-      finalState: result.state.toObject()
-    };
-  }
-
-  isPlanValid(plan: HTNPlan, rootTask: HTNTask, initialState: WorldState, context: unknown = {}): boolean {
-    if (!plan.valid) return false;
-    const nextPlan = this.plan(rootTask, initialState, context);
-    return nextPlan.valid && nextPlan.tasks.join(">") === plan.tasks.join(">");
-  }
-
-  private decompose(tasks: readonly HTNTask[], state: WorldState, context: unknown, depth: number, stats: DecomposeStats): DecomposeResult {
-    stats.maxDepthReached = Math.max(stats.maxDepthReached, depth);
-    if (depth > this.maxDepth || stats.iterations >= this.maxIterations) {
-      return { valid: false, tasks: [], state };
-    }
-    if (tasks.length === 0) {
-      return { valid: true, tasks: [], state };
-    }
-    stats.iterations += 1;
-    const [currentTask, ...remainingTasks] = tasks;
-    if (!currentTask) return { valid: true, tasks: [], state };
-
-    if (currentTask.type === "primitive") {
-      if (!currentTask.canRun(state)) return { valid: false, tasks: [], state };
-      const executed = currentTask.execute(state, context);
-      if (executed === "failure") return { valid: false, tasks: [], state };
-      const nextState = currentTask.applyEffects(state);
-      const remainder = this.decompose(remainingTasks, nextState, context, depth, stats);
-      return remainder.valid
-        ? { valid: true, tasks: [currentTask, ...remainder.tasks], state: remainder.state }
-        : { valid: false, tasks: [], state };
-    }
-
-    stats.decompositions += 1;
-    for (const method of currentTask.getMethods()) {
-      const preconditionsMet = method.check ? method.check(state, context) : state.matches(method.preconditions ?? {});
-      if (!preconditionsMet) continue;
-      const traceLength = stats.methodTrace.length;
-      stats.methodTrace.push(`${currentTask.name}:${method.name}`);
-      const result = this.decompose([...method.subtasks, ...remainingTasks], state, context, depth + 1, stats);
-      if (result.valid) return result;
-      stats.methodTrace.length = traceLength;
-    }
-    return { valid: false, tasks: [], state };
-  }
-}

package/src/LearningAgentFixtures.ts

@@ -1,184 +0,0 @@
-export interface LearningAgentFixtureOptions {
-  readonly seed?: number;
-  readonly targetDistance?: number;
-  readonly health?: number;
-  readonly energy?: number;
-  readonly nearbyCount?: number;
-}
-
-export interface LearningAgentFixture {
-  readonly source: "origin-master-ml-agent-adapted";
-  readonly observation: {
-    readonly featureSize: number;
-    readonly normalizedPosition: readonly [number, number, number];
-    readonly normalizedVelocity: readonly [number, number, number];
-    readonly targetDistance: number;
-    readonly health: number;
-    readonly energy: number;
-    readonly nearbyEntitySlots: number;
-    readonly featureHash: string;
-  };
-  readonly behaviorCloning: {
-    readonly demonstrations: number;
-    readonly trainLoss: number;
-    readonly validationLoss: number;
-    readonly trainAccuracy: number;
-    readonly validationAccuracy: number;
-    readonly earlyStoppingEpoch: number;
-    readonly selectedAction: "move-to-target" | "hold-position" | "recover";
-  };
-  readonly reinforcementLearning: {
-    readonly gamma: number;
-    readonly lambda: number;
-    readonly clipRange: number;
-    readonly policyLoss: number;
-    readonly valueLoss: number;
-    readonly totalLoss: number;
-    readonly avgAdvantage: number;
-    readonly avgReturn: number;
-    readonly entropy: number;
-    readonly klDivergence: number;
-    readonly explainedVariance: number;
-  };
-  readonly reward: {
-    readonly progress: number;
-    readonly survival: number;
-    readonly energyPenalty: number;
-    readonly proximityBonus: number;
-    readonly total: number;
-  };
-  readonly productionReadiness: {
-    readonly featureExtractionTelemetry: true;
-    readonly behaviorCloningTelemetry: true;
-    readonly ppoStatsTelemetry: true;
-    readonly rewardBreakdownTelemetry: true;
-  };
-  readonly blockedClaims: readonly string[];
-  readonly claimBoundary: string;
-  readonly hash: string;
-}
-
-export function sampleLearningAgentFixture(options: LearningAgentFixtureOptions = {}): LearningAgentFixture {
-  const seed = normalizeSeed(options.seed ?? 0x1ea5);
-  const targetDistance = positive(options.targetDistance ?? 6.2, "targetDistance");
-  const health = clamp01(options.health ?? 0.72);
-  const energy = clamp01(options.energy ?? 0.58);
-  const nearbyEntitySlots = Math.max(0, Math.min(5, Math.trunc(options.nearbyCount ?? 3)));
-  const normalizedPosition: readonly [number, number, number] = [
-    Number((seededUnit(seed) * 0.12).toFixed(4)),
-    0,
-    Number((seededUnit(seed ^ 0x5167) * 0.08).toFixed(4))
-  ];
-  const normalizedVelocity: readonly [number, number, number] = [
-    Number((0.06 + seededUnit(seed ^ 0x78ab) * 0.04).toFixed(4)),
-    0,
-    Number((seededUnit(seed ^ 0x4312) * 0.02).toFixed(4))
-  ];
-  const featureCore = [
-    ...normalizedPosition,
-    ...normalizedVelocity,
-    1,
-    0,
-    0,
-    Number((targetDistance / 100).toFixed(4)),
-    health,
-    energy,
-    nearbyEntitySlots
-  ];
-  const progress = Number(Math.max(0, 1 - targetDistance / 12).toFixed(4));
-  const survival = Number((health * 0.35).toFixed(4));
-  const energyPenalty = Number(((1 - energy) * -0.18).toFixed(4));
-  const proximityBonus = Number((nearbyEntitySlots > 0 ? 0.08 : 0).toFixed(4));
-  const totalReward = Number((progress + survival + energyPenalty + proximityBonus).toFixed(4));
-  const selectedAction = health < 0.35 ? "recover" : targetDistance > 1.5 ? "move-to-target" : "hold-position";
-  const behaviorCloning = {
-    demonstrations: 24 + nearbyEntitySlots * 4,
-    trainLoss: Number((0.18 - progress * 0.06).toFixed(4)),
-    validationLoss: Number((0.22 - progress * 0.05).toFixed(4)),
-    trainAccuracy: Number((0.74 + progress * 0.12).toFixed(4)),
-    validationAccuracy: Number((0.7 + progress * 0.1).toFixed(4)),
-    earlyStoppingEpoch: 7 + nearbyEntitySlots,
-    selectedAction
-  } satisfies LearningAgentFixture["behaviorCloning"];
-  const reinforcementLearning = {
-    gamma: 0.99,
-    lambda: 0.95,
-    clipRange: 0.2,
-    policyLoss: Number((-0.04 - progress * 0.03).toFixed(4)),
-    valueLoss: Number((0.21 - totalReward * 0.08).toFixed(4)),
-    totalLoss: Number((0.15 - totalReward * 0.05).toFixed(4)),
-    avgAdvantage: Number((totalReward * 0.42).toFixed(4)),
-    avgReturn: totalReward,
-    entropy: Number((0.52 - progress * 0.08).toFixed(4)),
-    klDivergence: Number((0.009 + seededUnit(seed ^ 0xacab) * 0.004).toFixed(4)),
-    explainedVariance: Number((0.66 + progress * 0.18).toFixed(4))
-  };
-  const core = {
-    featureCore,
-    behaviorCloning,
-    reinforcementLearning,
-    reward: { progress, survival, energyPenalty, proximityBonus, total: totalReward }
-  };
-  return {
-    source: "origin-master-ml-agent-adapted",
-    observation: {
-      featureSize: 27,
-      normalizedPosition,
-      normalizedVelocity,
-      targetDistance,
-      health,
-      energy,
-      nearbyEntitySlots,
-      featureHash: stableHash(JSON.stringify(featureCore))
-    },
-    behaviorCloning,
-    reinforcementLearning,
-    reward: core.reward,
-    productionReadiness: {
-      featureExtractionTelemetry: true,
-      behaviorCloningTelemetry: true,
-      ppoStatsTelemetry: true,
-      rewardBreakdownTelemetry: true
-    },
-    blockedClaims: [
-      "real neural-network training",
-      "ONNX runtime inference parity",
-      "Unity ML-Agents parity",
-      "Unreal Learning Agents parity",
-      "production reinforcement-learning deployment"
-    ],
-    claimBoundary: "This fixture ports old ML-agent concepts into deterministic feature-extraction, behavior-cloning, PPO-stat, and reward telemetry. It does not train neural networks, run ONNX inference, or claim Unity ML-Agents or Unreal Learning Agents parity.",
-    hash: stableHash(JSON.stringify(core))
-  };
-}
-
-function positive(value: number, name: string): number {
-  if (!Number.isFinite(value) || value < 0) throw new Error(`${name} must be a non-negative finite number.`);
-  return Number(value.toFixed(4));
-}
-
-function normalizeSeed(seed: number): number {
-  if (!Number.isInteger(seed) || seed < 0) throw new Error("seed must be a non-negative integer.");
-  return seed >>> 0;
-}
-
-function clamp01(value: number): number {
-  return Math.max(0, Math.min(1, Number.isFinite(value) ? value : 0));
-}
-
-function seededUnit(seed: number): number {
-  let value = seed >>> 0;
-  value ^= value << 13;
-  value ^= value >>> 17;
-  value ^= value << 5;
-  return (value >>> 0) / 0xffffffff;
-}
-
-function stableHash(value: string): string {
-  let hash = 2166136261;
-  for (let index = 0; index < value.length; index += 1) {
-    hash ^= value.charCodeAt(index);
-    hash = Math.imul(hash, 16777619);
-  }
-  return (hash >>> 0).toString(16).padStart(8, "0");
-}