@aura3d/scripting 1.0.6

package/src/index.ts

@@ -0,0 +1,175 @@
+export type { Behavior, BehaviorPhase } from "./Behavior";
+export {
+  BehaviorAction,
+  BehaviorCondition,
+  BehaviorSelector,
+  BehaviorSequence,
+  BehaviorTree,
+  BehaviorTreeNode,
+  Blackboard
+} from "./BehaviorTree";
+export type {
+  BehaviorTreeContext,
+  BehaviorTreeStatus,
+  BehaviorTreeTickResult,
+  BlackboardChange,
+  BlackboardValue
+} from "./BehaviorTree";
+export { PerceptionSensor } from "./Perception";
+export type {
+  PerceptionHit,
+  PerceptionMemory,
+  PerceptionPoint,
+  PerceptionSensorOptions,
+  PerceptionSnapshot,
+  PerceptionTarget
+} from "./Perception";
+export { UtilityAI, UtilityAction, UtilityConsideration } from "./UtilityAI";
+export type {
+  UtilityActionOptions,
+  UtilityActionScore,
+  UtilityConsiderationOptions,
+  UtilityContext,
+  UtilityCurve,
+  UtilityScoring
+} from "./UtilityAI";
+export { State, StateMachine } from "./StateMachine";
+export type { StateMachineSnapshot, StateTransition, StateTransitionCondition } from "./StateMachine";
+export { GOAPAction, GOAPPlanner, WorldState } from "./GOAP";
+export type { GOAPActionOptions, GOAPPlan, GOAPPlannerOptions, GOAPStateShape, GOAPValue } from "./GOAP";
+export { HTNPlanner, HTNTask } from "./HTN";
+export type { HTNCompoundTaskOptions, HTNPlan, HTNPlannerOptions, HTNPrimitiveTaskOptions, HTNTaskMethod, HTNTaskResult, HTNTaskType } from "./HTN";
+export { DecisionTree } from "./DecisionTree";
+export type { DecisionAction, DecisionCondition, DecisionTreeContext, DecisionTreeDecision, DecisionTreeNode, DecisionTreeNodeType, DecisionTreeStats } from "./DecisionTree";
+export { sampleAdaptiveDifficultyFixture } from "./AdaptiveDifficultyFixtures";
+export type {
+  AdaptiveDifficultyAdjustment,
+  AdaptiveDifficultyChangeType,
+  AdaptiveDifficultyFixture,
+  AdaptiveDifficultyFixtureOptions,
+  AdaptiveDifficultyMetricSummary,
+  AdaptiveDifficultyMetricType,
+  AdaptiveDifficultyStrategy,
+  AdaptiveDifficultyTriggeredRule
+} from "./AdaptiveDifficultyFixtures";
+export { sampleAnalyticsPrivacyFixture } from "./AnalyticsPrivacyFixtures";
+export type {
+  AnalyticsConsentCategory,
+  AnalyticsPrivacyFixture,
+  AnalyticsPrivacyFixtureOptions,
+  AnalyticsProviderMode
+} from "./AnalyticsPrivacyFixtures";
+export { sampleCulturalBehaviorFixture } from "./CulturalBehaviorFixtures";
+export type {
+  CulturalBehaviorFixture,
+  CulturalBehaviorFixtureOptions,
+  CulturalCommunicationStyle,
+  CulturalEntityFixture,
+  CulturalPersonalSpace,
+  CulturalRelationship,
+  CultureDescriptor,
+  ProxemicZone
+} from "./CulturalBehaviorFixtures";
+export { sampleCloudServiceFixture } from "./CloudServiceFixtures";
+export type { CloudFixtureServiceStatus, CloudServiceFixture, CloudServiceFixtureOptions } from "./CloudServiceFixtures";
+export { sampleLearningAgentFixture } from "./LearningAgentFixtures";
+export type { LearningAgentFixture, LearningAgentFixtureOptions } from "./LearningAgentFixtures";
+export { sampleNetworkReplicationFixture } from "./NetworkReplicationFixtures";
+export type {
+  NetworkDeltaSummary,
+  NetworkEntityState,
+  NetworkInputFrame,
+  NetworkInterestSummary,
+  NetworkInterpolationSummary,
+  NetworkPredictionSummary,
+  NetworkReplicationFixture,
+  NetworkReplicationFixtureOptions,
+  NetworkReplicationMode
+} from "./NetworkReplicationFixtures";
+export { samplePlayerBehaviorTelemetryFixture } from "./PlayerBehaviorTelemetryFixtures";
+export type {
+  PlayerBehaviorPatternTelemetry,
+  PlayerBehaviorTelemetryFixture,
+  PlayerBehaviorTelemetryOptions,
+  PlayerEngagementLevel,
+  PlayerEventCategory,
+  PlayerEventSeverity,
+  PlayerPlaystyle,
+  PlayerSkillAssessmentTelemetry,
+  PlayerSkillLevel
+} from "./PlayerBehaviorTelemetryFixtures";
+export { sampleProceduralContentAdaptationFixture } from "./ProceduralContentAdaptationFixtures";
+export type {
+  AdaptiveAiStrategy,
+  GeneratedContentDifficulty,
+  GeneratedContentTelemetry,
+  GeneratedContentType,
+  ProceduralContentAdaptationFixture,
+  ProceduralContentAdaptationOptions
+} from "./ProceduralContentAdaptationFixtures";
+export { sampleFpsEnemyTactics, sampleFpsHudOverlay, sampleFpsLevelLayout, sampleFpsWeaponCycle, samplePowerUpEffect, sampleSpaceShooterWave, sampleWeaponBurst } from "./WeaponSystem";
+export type {
+  FpsEnemyTacticalState,
+  FpsEnemyTacticsInput,
+  FpsEnemyTacticsSample,
+  FpsFiringMode,
+  FpsHudOverlayInput,
+  FpsHudOverlaySample,
+  FpsLevelCorridor,
+  FpsLevelLayoutInput,
+  FpsLevelLayoutSample,
+  FpsLevelPickup,
+  FpsLevelPoint,
+  FpsLevelRoom,
+  FpsPickupType,
+  FpsWeaponCycleInput,
+  FpsWeaponCycleSample,
+  FpsWeaponType,
+  PowerUpEffectInput,
+  PowerUpEffectSample,
+  SpaceShooterEnemyType,
+  SpaceShooterFormation,
+  SpaceShooterPowerUpType,
+  SpaceShooterSpawn,
+  SpaceShooterWaveInput,
+  SpaceShooterWaveSample,
+  WeaponBurst,
+  WeaponBurstInput,
+  WeaponKind,
+  WeaponProjectile
+} from "./WeaponSystem";
+export { BehaviorHost } from "./BehaviorHost";
+export type { BehaviorHostOptions } from "./BehaviorHost";
+export { BehaviorRegistry } from "./BehaviorRegistry";
+export type { BehaviorFactory } from "./BehaviorRegistry";
+export { BehaviorSystem } from "./BehaviorSystem";
+export type { BehaviorError, BehaviorSystemUpdateOptions } from "./BehaviorSystem";
+export { ScriptContext } from "./ScriptContext";
+export type { ScriptContextOptions } from "./ScriptContext";
+export { deserializeGraph, serializeGraph, validateGraph } from "./VisualGraph";
+export type { SerializedVisualGraph, VisualEdge, VisualGraph } from "./VisualGraph";
+export { VisualGraphExecutor } from "./VisualGraphExecutor";
+export type { VisualExecutionResult } from "./VisualGraphExecutor";
+export type {
+  VisualAnimationControllerState,
+  VisualAnimationEvent,
+  VisualCameraState,
+  VisualCollisionEvent,
+  VisualCombatEvent,
+  VisualGraphDiagnostic,
+  VisualGraphExecutionContext,
+  VisualGraphSideEffect,
+  VisualGraphValidationOptions,
+  VisualInputSet,
+  VisualInputSnapshot,
+  VisualOverlapResult,
+  VisualPhysicsBodyState,
+  VisualRaycastHit,
+  VisualRuntimeNodeState,
+  VisualStateCollection,
+  VisualVector3
+} from "./VisualGraphContext";
+export { createVisualNode, getVisualNodeDefinition, listVisualNodeDefinitions } from "./VisualNodeCatalog";
+export type { VisualNodeCategory, VisualNodeDefinition } from "./VisualNodeCatalog";
+export { validateNode } from "./VisualNode";
+export type { VisualNode, VisualPort, VisualPortDirection, VisualPortType } from "./VisualNode";

package/tests/scripting.test.ts

@@ -0,0 +1,229 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  BehaviorHost,
+  BehaviorSystem,
+  createVisualNode,
+  listVisualNodeDefinitions,
+  validateGraph,
+  VisualGraphExecutor,
+  type VisualGraphExecutionContext
+} from "../src/index";
+
+test("BehaviorSystem runs start before update and fixed phase separately", async () => {
+  const calls: string[] = [];
+  const host = new BehaviorHost();
+  host.attach({
+    onStart: () => calls.push("start"),
+    onFixedUpdate: () => calls.push("fixed"),
+    onUpdate: () => calls.push("update")
+  });
+
+  const system = new BehaviorSystem();
+  system.registerHost(host);
+  await system.fixedUpdate({ fixedDeltaSeconds: 1 / 60 });
+  await system.update({ deltaSeconds: 1 / 30 });
+  await system.update({ deltaSeconds: 1 / 30 });
+
+  assert.deepEqual(calls, ["fixed", "start", "update", "update"]);
+});
+
+test("Visual graph validates ports and executes simple constants plus add", () => {
+  const graph = {
+    nodes: [
+      { id: "a", kind: "const", data: { value: 2 }, ports: [{ id: "out", direction: "output", type: "number" }] },
+      { id: "b", kind: "const", data: { value: 3 }, ports: [{ id: "out", direction: "output", type: "number" }] },
+      { id: "sum", kind: "add", ports: [{ id: "in", direction: "input", type: "number" }] }
+    ],
+    edges: [
+      { fromNode: "a", fromPort: "out", toNode: "sum", toPort: "in" },
+      { fromNode: "b", fromPort: "out", toNode: "sum", toPort: "in" }
+    ]
+  } as const;
+
+  assert.deepEqual(validateGraph(graph), []);
+  assert.equal(new VisualGraphExecutor().execute(graph).values.get("sum"), 5);
+});
+
+test("Visual graph executes catalog math and logic nodes", () => {
+  const graph = {
+    nodes: [
+      createVisualNode("const", "a", { value: 12 }),
+      createVisualNode("const", "b", { value: 5 }),
+      createVisualNode("subtract", "delta"),
+      createVisualNode("lessEqual", "bounded", { b: 7 })
+    ],
+    edges: [
+      { fromNode: "a", fromPort: "out", toNode: "delta", toPort: "a" },
+      { fromNode: "b", fromPort: "out", toNode: "delta", toPort: "b" },
+      { fromNode: "delta", fromPort: "out", toNode: "bounded", toPort: "a" }
+    ]
+  };
+
+  const result = new VisualGraphExecutor().execute(graph);
+
+  assert.equal(result.values.get("delta"), 7);
+  assert.equal(result.values.get("bounded"), true);
+});
+
+test("Visual graph executes bounded flow-control catalog nodes", () => {
+  const graph = {
+    nodes: [
+      createVisualNode("branch", "branch", { condition: false }),
+      createVisualNode("forRange", "loop", { startIndex: 1, endIndex: 4 }),
+      createVisualNode("gate", "gate", { startClosed: true })
+    ],
+    edges: []
+  };
+
+  const result = new VisualGraphExecutor().execute(graph);
+
+  assert.equal(result.values.get("branch.selected"), "false");
+  assert.equal(result.values.get("branch.false"), true);
+  assert.deepEqual(result.values.get("loop.indices"), [1, 2, 3]);
+  assert.equal(result.values.get("gate.isOpen"), false);
+  assert.equal(result.values.get("gate.out"), false);
+  assert.ok(result.blockedClaims.includes("Unreal Blueprint parity"));
+});
+
+test("Visual node catalog exposes Aura3D 1.0.5 runtime-facing node families", () => {
+  const definitions = listVisualNodeDefinitions();
+  const byCategory = new Map(definitions.map((definition) => [definition.kind, definition.category]));
+
+  for (const [kind, category] of Object.entries({
+    onFrame: "runtime",
+    translate: "runtime",
+    pressed: "input",
+    combo: "input",
+    restartClip: "animation",
+    onAnimationEvent: "animation",
+    setVelocity: "physics",
+    onCollisionEnter: "physics",
+    openHitbox: "combat",
+    onHit: "combat",
+    follow: "camera",
+    captureSnapshot: "evidence",
+    assertState: "evidence"
+  })) {
+    assert.equal(byCategory.get(kind), category);
+  }
+});
+
+test("Visual graph validation catches missing inputs and invalid deterministic context references", () => {
+  const context: VisualGraphExecutionContext = {
+    runtimeNodes: [{ id: "player" }],
+    animationControllers: [{ id: "playerAnim", clips: ["Idle", "LightPunch"], morphTargets: ["AA", "FV"] }],
+    physicsBodies: [{ id: "playerBody" }]
+  };
+
+  const missingInputGraph = {
+    nodes: [createVisualNode("getNode", "missing-node-id")],
+    edges: []
+  };
+
+  assert.ok(validateGraph(missingInputGraph).some((error) => error.includes("Missing required input")));
+
+  const invalidGraph = {
+    nodes: [
+      createVisualNode("getNode", "bad-runtime-node", { nodeId: "ghost" }),
+      createVisualNode("playClip", "bad-clip", { controllerId: "playerAnim", clip: "Uppercut" }),
+      createVisualNode("setMorphTarget", "bad-morph", { controllerId: "playerAnim", morphTarget: "ZZ", weight: 1 }),
+      createVisualNode("setVelocity", "bad-body", { bodyId: "ghostBody", velocity: { x: 1, y: 0, z: 0 } })
+    ],
+    edges: []
+  };
+
+  const errors = validateGraph(invalidGraph, { context, strictReferences: true });
+
+  assert.ok(errors.some((error) => error.includes("Unknown runtime node id")));
+  assert.ok(errors.some((error) => error.includes("Unknown animation clip")));
+  assert.ok(errors.some((error) => error.includes("Unknown morph target")));
+  assert.ok(errors.some((error) => error.includes("Unknown physics body id")));
+
+  const cycleGraph = {
+    nodes: [createVisualNode("add", "a"), createVisualNode("add", "b")],
+    edges: [
+      { fromNode: "a", fromPort: "out", toNode: "b", toPort: "in" },
+      { fromNode: "b", fromPort: "out", toNode: "a", toPort: "in" }
+    ]
+  };
+
+  assert.ok(validateGraph(cycleGraph).some((error) => error.includes("Visual graph cycle detected")));
+});
+
+test("Visual graph executes deterministic runtime input animation physics combat camera and evidence hooks", () => {
+  const context: VisualGraphExecutionContext = {
+    frame: 12,
+    time: 0.2,
+    dt: 1 / 60,
+    runtimeNodes: [{ id: "player", position: { x: 1, y: 0, z: 0 }, visible: true }],
+    input: {
+      pressed: ["attack"],
+      held: { right: true },
+      buffered: ["dash"],
+      combos: ["light-light"],
+      axes: { moveX: 1 }
+    },
+    animationControllers: [
+      {
+        id: "playerAnim",
+        currentClip: "Idle",
+        clipTime: 0.24,
+        clips: ["Idle", "LightPunch"],
+        morphTargets: ["AA"],
+        events: [{ type: "hitbox.open", controllerId: "playerAnim", clip: "LightPunch", time: 0.12, payload: { hitboxId: "player.light" } }]
+      }
+    ],
+    physicsBodies: [{ id: "playerBody", velocity: { x: 0, y: 0, z: 0 }, grounded: true }],
+    collisionEvents: [{ type: "enter", bodyId: "playerBody", otherBodyId: "dummyBody" }],
+    combatEvents: [{ type: "hit", actorId: "player", targetId: "dummy", hitboxId: "player.light", amount: 8 }],
+    camera: { id: "mainCamera", position: { x: 0, y: 2, z: 5 } },
+    evidence: { proofId: "visual-scripting-runtime" }
+  };
+
+  const graph = {
+    nodes: [
+      createVisualNode("onFrame", "frame"),
+      createVisualNode("pressed", "attack-pressed", { action: "attack" }),
+      createVisualNode("axis", "move-axis", { axis: "moveX" }),
+      createVisualNode("translate", "move", { nodeId: "player", delta: { x: 0.25, y: 0, z: 0 } }),
+      createVisualNode("restartClip", "attack-clip", { controllerId: "playerAnim", clip: "LightPunch" }),
+      createVisualNode("onAnimationEvent", "hitbox-event", { controllerId: "playerAnim", eventType: "hitbox.open", clip: "LightPunch" }),
+      createVisualNode("openHitbox", "open-hitbox", { hitboxId: "player.light", ownerId: "player", damage: 8 }),
+      createVisualNode("setMorphTarget", "mouth-aa", { controllerId: "playerAnim", morphTarget: "AA", weight: 0.7 }),
+      createVisualNode("setVelocity", "velocity", { bodyId: "playerBody", velocity: { x: 3, y: 0, z: 0 } }),
+      createVisualNode("onCollisionEnter", "collision", { bodyId: "playerBody", otherBodyId: "dummyBody" }),
+      createVisualNode("onHit", "hit", { actorId: "player", hitboxId: "player.light" }),
+      createVisualNode("follow", "camera-follow", { targetId: "player", stiffness: 0.85 }),
+      createVisualNode("captureSnapshot", "snapshot", { label: "visual-scripting-runtime" }),
+      createVisualNode("assertState", "assert-attack", { actual: true, expected: true })
+    ],
+    edges: []
+  };
+
+  assert.deepEqual(validateGraph(graph, { context }), []);
+
+  const result = new VisualGraphExecutor(context).execute(graph);
+  const second = new VisualGraphExecutor(context).execute(graph);
+
+  assert.equal(result.values.get("attack-pressed"), true);
+  assert.equal(result.values.get("move-axis"), 1);
+  assert.equal(result.values.get("hitbox-event.fired"), true);
+  assert.equal(result.values.get("collision.collided"), true);
+  assert.equal(result.values.get("hit.hit"), true);
+  assert.equal(result.values.get("assert-attack.passed"), true);
+
+  assert.deepEqual((result.values.get("move.command") as { position: unknown }).position, { x: 1.25, y: 0, z: 0 });
+  assert.deepEqual(result.sideEffects.map((effect) => effect.kind), [
+    "runtime.translate",
+    "animation.restartClip",
+    "combat.openHitbox",
+    "animation.setMorphTarget",
+    "physics.setVelocity",
+    "camera.follow",
+    "evidence.captureSnapshot",
+    "evidence.assertState"
+  ]);
+  assert.deepEqual(result.sideEffects, second.sideEffects);
+  assert.deepEqual(result.diagnostics, []);
+});

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"]
+}