@aura3d/scripting 1.4.0 → 1.4.1

package/src/UtilityAI.ts

@@ -1,158 +0,0 @@
-import type { Blackboard } from "./BehaviorTree";
-
-export type UtilityCurve = "linear" | "inverse" | "quadratic" | "cubic" | "boolean" | "logistic";
-export type UtilityScoring = "multiply" | "average" | "min" | "max" | "sum";
-
-export interface UtilityContext {
-  readonly blackboard?: Blackboard;
-  readonly values?: Record<string, number | boolean | string | undefined>;
-}
-
-export interface UtilityConsiderationOptions {
-  readonly name: string;
-  readonly input: (context: UtilityContext) => number | boolean;
-  readonly curve?: UtilityCurve;
-  readonly weight?: number;
-  readonly threshold?: number;
-  readonly slope?: number;
-}
-
-export interface UtilityActionOptions {
-  readonly name: string;
-  readonly considerations: readonly UtilityConsideration[];
-  readonly scoring?: UtilityScoring;
-  readonly baseScore?: number;
-  readonly enabled?: boolean;
-}
-
-export interface UtilityActionScore {
-  readonly action: string;
-  readonly score: number;
-  readonly considerationScores: Record<string, number>;
-}
-
-export class UtilityConsideration {
-  readonly name: string;
-  readonly curve: UtilityCurve;
-  readonly weight: number;
-  readonly threshold: number;
-  readonly slope: number;
-  private readonly input: (context: UtilityContext) => number | boolean;
-
-  constructor(options: UtilityConsiderationOptions) {
-    this.name = options.name;
-    this.input = options.input;
-    this.curve = options.curve ?? "linear";
-    this.weight = options.weight ?? 1;
-    this.threshold = options.threshold ?? 0.5;
-    this.slope = options.slope ?? 10;
-  }
-
-  evaluate(context: UtilityContext): number {
-    const raw = this.input(context);
-    const value = typeof raw === "boolean" ? (raw ? 1 : 0) : clamp01(raw);
-    return round3(clamp01(applyCurve(value, this.curve, this.threshold, this.slope) * this.weight));
-  }
-}
-
-export class UtilityAction {
-  readonly name: string;
-  readonly considerations: readonly UtilityConsideration[];
-  readonly scoring: UtilityScoring;
-  readonly baseScore: number;
-  enabled: boolean;
-
-  constructor(options: UtilityActionOptions) {
-    this.name = options.name;
-    this.considerations = options.considerations;
-    this.scoring = options.scoring ?? "multiply";
-    this.baseScore = options.baseScore ?? 0;
-    this.enabled = options.enabled ?? true;
-  }
-
-  score(context: UtilityContext): UtilityActionScore {
-    const considerationScores = Object.fromEntries(this.considerations.map((consideration) => [consideration.name, consideration.evaluate(context)]));
-    const values = Object.values(considerationScores);
-    const combined = values.length === 0 ? 0 : combineScores(values, this.scoring);
-    return {
-      action: this.name,
-      score: round3(clamp01(combined + this.baseScore)),
-      considerationScores
-    };
-  }
-}
-
-export class UtilityAI {
-  private readonly actions: UtilityAction[] = [];
-
-  addAction(action: UtilityAction): void {
-    if (this.actions.some((entry) => entry.name === action.name)) {
-      throw new Error(`Utility action already registered: ${action.name}`);
-    }
-    this.actions.push(action);
-  }
-
-  removeAction(name: string): boolean {
-    const index = this.actions.findIndex((action) => action.name === name);
-    if (index < 0) return false;
-    this.actions.splice(index, 1);
-    return true;
-  }
-
-  setActionEnabled(name: string, enabled: boolean): void {
-    const action = this.actions.find((entry) => entry.name === name);
-    if (!action) throw new Error(`Utility action is not registered: ${name}`);
-    action.enabled = enabled;
-  }
-
-  evaluate(context: UtilityContext): readonly UtilityActionScore[] {
-    return this.actions
-      .filter((action) => action.enabled)
-      .map((action) => action.score(context))
-      .sort((left, right) => right.score - left.score || left.action.localeCompare(right.action));
-  }
-
-  select(context: UtilityContext): UtilityActionScore | undefined {
-    return this.evaluate(context)[0];
-  }
-}
-
-function combineScores(values: readonly number[], scoring: UtilityScoring): number {
-  switch (scoring) {
-    case "average":
-      return values.reduce((sum, value) => sum + value, 0) / values.length;
-    case "min":
-      return Math.min(...values);
-    case "max":
-      return Math.max(...values);
-    case "sum":
-      return Math.min(1, values.reduce((sum, value) => sum + value, 0));
-    case "multiply":
-      return values.reduce((product, value) => product * value, 1);
-  }
-}
-
-function applyCurve(value: number, curve: UtilityCurve, threshold: number, slope: number): number {
-  switch (curve) {
-    case "inverse":
-      return 1 - value;
-    case "quadratic":
-      return value * value;
-    case "cubic":
-      return value * value * value;
-    case "boolean":
-      return value >= threshold ? 1 : 0;
-    case "logistic":
-      return 1 / (1 + Math.exp(-slope * (value - threshold)));
-    case "linear":
-      return value;
-  }
-}
-
-function clamp01(value: number): number {
-  return Math.max(0, Math.min(1, Number.isFinite(value) ? value : 0));
-}
-
-function round3(value: number): number {
-  return Number(value.toFixed(3));
-}

package/src/VisualGraph.ts

@@ -1,236 +0,0 @@
-import { validateNode, type VisualNode } from "./VisualNode";
-import { getVisualNodeDefinition } from "./VisualNodeCatalog";
-import {
-  type VisualGraphExecutionContext,
-  type VisualGraphValidationOptions,
-  type VisualStateCollection
-} from "./VisualGraphContext";
-
-export interface VisualEdge {
-  readonly fromNode: string;
-  readonly fromPort: string;
-  readonly toNode: string;
-  readonly toPort: string;
-}
-
-export interface VisualGraph {
-  readonly nodes: readonly VisualNode[];
-  readonly edges: readonly VisualEdge[];
-}
-
-export type SerializedVisualGraph = {
-  readonly nodes: readonly VisualNode[];
-  readonly edges: readonly VisualEdge[];
-};
-
-export function validateGraph(graph: VisualGraph, options: VisualGraphValidationOptions = {}): readonly string[] {
-  const errors: string[] = [];
-  const nodes = new Map(graph.nodes.map((node) => [node.id, node]));
-  const seenNodeIds = new Set<string>();
-
-  for (const node of graph.nodes) {
-    if (seenNodeIds.has(node.id)) {
-      errors.push(`Duplicate node id: ${node.id}`);
-    }
-    seenNodeIds.add(node.id);
-    errors.push(...validateNode(node));
-    const definition = getVisualNodeDefinition(node.kind);
-    if (!definition) {
-      errors.push(`Unknown visual node kind: ${node.kind}`);
-    } else {
-      for (const port of definition.ports.filter((entry) => entry.direction === "input")) {
-        if (!port.optional && port.defaultValue === undefined && !hasInputOrLiteral(graph, node, port.id)) {
-          errors.push(`Missing required input on node ${node.id}: ${port.id}`);
-        }
-      }
-    }
-    errors.push(...validateContextReferences(graph, node, options.context, options.strictReferences === true));
-  }
-
-  for (const edge of graph.edges) {
-    const from = nodes.get(edge.fromNode);
-    const to = nodes.get(edge.toNode);
-    if (!from) {
-      errors.push(`Missing edge source node: ${edge.fromNode}`);
-      continue;
-    }
-    if (!to) {
-      errors.push(`Missing edge target node: ${edge.toNode}`);
-      continue;
-    }
-
-    const fromPort = from.ports.find((port) => port.id === edge.fromPort);
-    const toPort = to.ports.find((port) => port.id === edge.toPort);
-    if (!fromPort || fromPort.direction !== "output") {
-      errors.push(`Invalid source port: ${edge.fromNode}.${edge.fromPort}`);
-    }
-    if (!toPort || toPort.direction !== "input") {
-      errors.push(`Invalid target port: ${edge.toNode}.${edge.toPort}`);
-    }
-    if (fromPort && toPort && fromPort.type !== toPort.type && fromPort.type !== "any" && toPort.type !== "any") {
-      errors.push(`Port type mismatch: ${edge.fromNode}.${edge.fromPort} -> ${edge.toNode}.${edge.toPort}`);
-    }
-  }
-
-  if (options.allowCycles !== true) {
-    errors.push(...validateAcyclic(graph));
-  }
-
-  return errors;
-}
-
-export function serializeGraph(graph: VisualGraph): SerializedVisualGraph {
-  const errors = validateGraph(graph);
-  if (errors.length > 0) {
-    throw new Error(errors.join("; "));
-  }
-  return {
-    nodes: graph.nodes.map((node) => ({
-      id: node.id,
-      kind: node.kind,
-      ports: node.ports.map((port) => ({ ...port })),
-      data: cloneData(node.data)
-    })),
-    edges: graph.edges.map((edge) => ({ ...edge }))
-  };
-}
-
-export function deserializeGraph(serialized: SerializedVisualGraph): VisualGraph {
-  const graph: VisualGraph = {
-    nodes: serialized.nodes.map((node) => ({
-      id: node.id,
-      kind: node.kind,
-      ports: node.ports.map((port) => ({ ...port })),
-      data: cloneData(node.data)
-    })),
-    edges: serialized.edges.map((edge) => ({ ...edge }))
-  };
-  const errors = validateGraph(graph);
-  if (errors.length > 0) {
-    throw new Error(errors.join("; "));
-  }
-  return graph;
-}
-
-function cloneData(data: Readonly<Record<string, unknown>> | undefined): Readonly<Record<string, unknown>> | undefined {
-  if (data === undefined) return undefined;
-  return JSON.parse(JSON.stringify(data)) as Readonly<Record<string, unknown>>;
-}
-
-function hasInputOrLiteral(graph: VisualGraph, node: VisualNode, portId: string): boolean {
-  if (node.data && node.data[portId] !== undefined) return true;
-  return graph.edges.some((edge) => edge.toNode === node.id && edge.toPort === portId);
-}
-
-function validateAcyclic(graph: VisualGraph): readonly string[] {
-  const errors: string[] = [];
-  const adjacency = new Map<string, string[]>();
-  for (const node of graph.nodes) {
-    adjacency.set(node.id, []);
-  }
-  for (const edge of graph.edges) {
-    if (adjacency.has(edge.fromNode)) {
-      adjacency.get(edge.fromNode)?.push(edge.toNode);
-    }
-  }
-
-  const visiting = new Set<string>();
-  const visited = new Set<string>();
-
-  const visit = (nodeId: string, path: readonly string[]): void => {
-    if (visited.has(nodeId)) return;
-    if (visiting.has(nodeId)) {
-      errors.push(`Visual graph cycle detected: ${[...path, nodeId].join(" -> ")}`);
-      return;
-    }
-    visiting.add(nodeId);
-    for (const next of adjacency.get(nodeId) ?? []) {
-      visit(next, [...path, nodeId]);
-    }
-    visiting.delete(nodeId);
-    visited.add(nodeId);
-  };
-
-  for (const node of graph.nodes) {
-    visit(node.id, []);
-  }
-
-  return errors;
-}
-
-function validateContextReferences(
-  graph: VisualGraph,
-  node: VisualNode,
-  context: VisualGraphExecutionContext | undefined,
-  strictReferences: boolean
-): readonly string[] {
-  const errors: string[] = [];
-  const nodeId = literalString(node, "nodeId");
-  const controllerId = literalString(node, "controllerId");
-  const bodyId = literalString(node, "bodyId");
-
-  if (runtimeNodeKinds.has(node.kind)) {
-    if (strictReferences && !hasInputOrLiteral(graph, node, "nodeId")) {
-      errors.push(`Missing runtime node id on node ${node.id}`);
-    }
-    if (nodeId && context?.runtimeNodes && !collectionHas(context.runtimeNodes, nodeId)) {
-      errors.push(`Unknown runtime node id on node ${node.id}: ${nodeId}`);
-    }
-  }
-
-  if (animationNodeKinds.has(node.kind)) {
-    if (strictReferences && !hasInputOrLiteral(graph, node, "controllerId")) {
-      errors.push(`Missing animation controller id on node ${node.id}`);
-    }
-    const controller = controllerId && context?.animationControllers ? collectionGet(context.animationControllers, controllerId) : undefined;
-    if (controllerId && context?.animationControllers && !controller) {
-      errors.push(`Unknown animation controller id on node ${node.id}: ${controllerId}`);
-    }
-    const clip = literalString(node, "clip");
-    if (controller && clip && controller.clips && !controller.clips.includes(clip)) {
-      errors.push(`Unknown animation clip on node ${node.id}: ${clip}`);
-    }
-    const morphTarget = literalString(node, "morphTarget");
-    if (controller && morphTarget && controller.morphTargets && !controller.morphTargets.includes(morphTarget)) {
-      errors.push(`Unknown morph target on node ${node.id}: ${morphTarget}`);
-    }
-  }
-
-  if (physicsNodeKinds.has(node.kind)) {
-    if (strictReferences && physicsBodyRequiredKinds.has(node.kind) && !hasInputOrLiteral(graph, node, "bodyId")) {
-      errors.push(`Missing physics body id on node ${node.id}`);
-    }
-    if (bodyId && context?.physicsBodies && !collectionHas(context.physicsBodies, bodyId)) {
-      errors.push(`Unknown physics body id on node ${node.id}: ${bodyId}`);
-    }
-  }
-
-  return errors;
-}
-
-function literalString(node: VisualNode, key: string): string | undefined {
-  const value = node.data?.[key];
-  return typeof value === "string" && value.length > 0 ? value : undefined;
-}
-
-function collectionHas<T extends { readonly id: string }>(collection: VisualStateCollection<T>, id: string): boolean {
-  return collectionGet(collection, id) !== undefined;
-}
-
-function collectionGet<T extends { readonly id: string }>(collection: VisualStateCollection<T>, id: string): T | undefined {
-  return Array.isArray(collection) ? collection.find((entry) => entry.id === id) : (collection as Readonly<Record<string, T>>)[id];
-}
-
-const runtimeNodeKinds = new Set(["getNode", "setPosition", "translate", "rotate", "setVisible", "setMaterial"]);
-const animationNodeKinds = new Set([
-  "playClip",
-  "restartClip",
-  "crossFade",
-  "setLayerWeight",
-  "onAnimationEvent",
-  "setMorphTarget",
-  "setMorphTargets",
-  "getClipTime"
-]);
-const physicsNodeKinds = new Set(["setVelocity", "jump", "dash", "onCollisionEnter", "onCollisionExit", "raycast", "overlap"]);
-const physicsBodyRequiredKinds = new Set(["setVelocity", "jump", "dash", "onCollisionEnter", "onCollisionExit"]);

package/src/VisualGraphContext.ts

@@ -1,138 +0,0 @@
-export type VisualVector3 = readonly [number, number, number] | {
-  readonly x?: number;
-  readonly y?: number;
-  readonly z?: number;
-};
-
-export type VisualInputSet = readonly string[] | Readonly<Record<string, boolean>>;
-
-export type VisualStateCollection<T extends { readonly id: string }> =
-  | readonly T[]
-  | Readonly<Record<string, T>>;
-
-export interface VisualRuntimeNodeState {
-  readonly id: string;
-  readonly position?: VisualVector3;
-  readonly rotation?: VisualVector3;
-  readonly scale?: VisualVector3;
-  readonly visible?: boolean;
-  readonly material?: Readonly<Record<string, unknown>>;
-  readonly morphTargets?: Readonly<Record<string, number>>;
-  readonly tags?: readonly string[];
-}
-
-export interface VisualInputSnapshot {
-  readonly pressed?: VisualInputSet;
-  readonly held?: VisualInputSet;
-  readonly released?: VisualInputSet;
-  readonly buffered?: VisualInputSet;
-  readonly combos?: VisualInputSet;
-  readonly axes?: Readonly<Record<string, number>>;
-}
-
-export interface VisualAnimationEvent {
-  readonly id?: string;
-  readonly type: string;
-  readonly controllerId?: string;
-  readonly clip?: string;
-  readonly time?: number;
-  readonly bone?: string;
-  readonly payload?: unknown;
-}
-
-export interface VisualAnimationControllerState {
-  readonly id: string;
-  readonly nodeId?: string;
-  readonly currentClip?: string;
-  readonly clipTime?: number;
-  readonly clips?: readonly string[];
-  readonly layers?: Readonly<Record<string, number>>;
-  readonly morphTargets?: readonly string[];
-  readonly events?: readonly VisualAnimationEvent[];
-}
-
-export interface VisualPhysicsBodyState {
-  readonly id: string;
-  readonly position?: VisualVector3;
-  readonly velocity?: VisualVector3;
-  readonly grounded?: boolean;
-}
-
-export interface VisualCollisionEvent {
-  readonly id?: string;
-  readonly type: "enter" | "exit";
-  readonly bodyId?: string;
-  readonly otherBodyId?: string;
-  readonly point?: VisualVector3;
-  readonly normal?: VisualVector3;
-  readonly payload?: unknown;
-}
-
-export interface VisualRaycastHit {
-  readonly id: string;
-  readonly hit: boolean;
-  readonly bodyId?: string;
-  readonly point?: VisualVector3;
-  readonly normal?: VisualVector3;
-  readonly distance?: number;
-}
-
-export interface VisualOverlapResult {
-  readonly id: string;
-  readonly bodyIds: readonly string[];
-}
-
-export interface VisualCombatEvent {
-  readonly id?: string;
-  readonly type: "hit" | "blocked" | "damage" | "knockback";
-  readonly actorId?: string;
-  readonly targetId?: string;
-  readonly hitboxId?: string;
-  readonly amount?: number;
-  readonly payload?: unknown;
-}
-
-export interface VisualCameraState {
-  readonly id?: string;
-  readonly position?: VisualVector3;
-  readonly targetIds?: readonly string[];
-}
-
-export interface VisualGraphExecutionContext {
-  readonly frame?: number;
-  readonly time?: number;
-  readonly dt?: number;
-  readonly runtimeNodes?: VisualStateCollection<VisualRuntimeNodeState>;
-  readonly input?: VisualInputSnapshot;
-  readonly animationControllers?: VisualStateCollection<VisualAnimationControllerState>;
-  readonly animationEvents?: readonly VisualAnimationEvent[];
-  readonly physicsBodies?: VisualStateCollection<VisualPhysicsBodyState>;
-  readonly collisionEvents?: readonly VisualCollisionEvent[];
-  readonly raycastHits?: VisualStateCollection<VisualRaycastHit>;
-  readonly overlaps?: VisualStateCollection<VisualOverlapResult>;
-  readonly combatEvents?: readonly VisualCombatEvent[];
-  readonly camera?: VisualCameraState;
-  readonly evidence?: Readonly<Record<string, unknown>>;
-}
-
-export interface VisualGraphValidationOptions {
-  readonly context?: VisualGraphExecutionContext;
-  readonly strictReferences?: boolean;
-  readonly allowCycles?: boolean;
-}
-
-export interface VisualGraphSideEffect {
-  readonly kind: string;
-  readonly nodeId: string;
-  readonly target?: string;
-  readonly frame?: number;
-  readonly time?: number;
-  readonly payload: unknown;
-}
-
-export interface VisualGraphDiagnostic {
-  readonly level: "info" | "warning" | "error";
-  readonly code: string;
-  readonly message: string;
-  readonly nodeId?: string;
-}