@forgeax/engine-animation 0.1.2

package/src/animation-target.ts

@@ -0,0 +1,257 @@
+import {
+  defineComponent,
+  defineRelationship,
+  Entity,
+  type EntityHandle,
+  type World,
+} from '@forgeax/engine-ecs';
+import { ChildOf, Name, Transform } from '@forgeax/engine-scene';
+import { type AnimationTargetIdValue, err, ok, type Result } from '@forgeax/engine-types';
+import { AnimationPlayer } from './animation-player';
+import { deriveAnimationTargetId, isAnimationTargetId } from './target-id';
+
+export const AnimationTargetId = defineComponent('AnimationTargetId', {
+  value: { type: 'string' },
+});
+
+export const { target: AnimationTargets, source: AnimatedBy } = defineRelationship({
+  sourceName: 'AnimatedBy',
+  sourceField: 'player',
+  targetName: 'AnimationTargets',
+  targetField: 'targets',
+  exclusive: true,
+  linkedSpawn: false,
+  allowSelf: true,
+});
+
+export type BindAnimationTargetsErrorCode =
+  | 'animation-target-player-invalid'
+  | 'animation-target-invalid'
+  | 'animation-target-outside-player-root'
+  | 'animation-target-name-missing'
+  | 'animation-target-id-invalid'
+  | 'animation-target-id-duplicate'
+  | 'animation-target-player-conflict'
+  | 'animation-target-capacity-reserve-failed'
+  | 'animation-target-bind-failed';
+
+export class BindAnimationTargetsError extends Error {
+  override readonly name = 'BindAnimationTargetsError';
+
+  constructor(
+    readonly code: BindAnimationTargetsErrorCode,
+    readonly expected: string,
+    readonly hint: string,
+    readonly detail: Readonly<Record<string, unknown>>,
+  ) {
+    super(`[BindAnimationTargetsError ${code}] expected: ${expected}; hint: ${hint}`);
+  }
+}
+
+interface Candidate {
+  readonly entity: EntityHandle;
+  readonly id: AnimationTargetIdValue;
+  readonly needsId: boolean;
+  readonly owner: EntityHandle | null | undefined;
+}
+
+function bindError(
+  code: BindAnimationTargetsErrorCode,
+  expected: string,
+  hint: string,
+  detail: Readonly<Record<string, unknown>>,
+): Result<never, BindAnimationTargetsError> {
+  return err(new BindAnimationTargetsError(code, expected, hint, detail));
+}
+
+function targetLineage(
+  world: World,
+  player: EntityHandle,
+  target: EntityHandle,
+): Result<readonly EntityHandle[], BindAnimationTargetsError> {
+  const reversed: EntityHandle[] = [];
+  const visited = new Set<number>();
+  let current = target;
+
+  while (!visited.has(current as number)) {
+    visited.add(current as number);
+    reversed.push(current);
+    if (current === player) return ok(reversed.reverse());
+
+    const parent = world.get(current, ChildOf);
+    if (!parent.ok || parent.value.parent === null) break;
+    current = parent.value.parent;
+  }
+
+  return bindError(
+    'animation-target-outside-player-root',
+    'the target to be the player itself or one of its descendants',
+    'parent the target below the animation player or bind it to the correct player',
+    { player: player as number, target: target as number },
+  );
+}
+
+function inspectTarget(
+  world: World,
+  player: EntityHandle,
+  target: EntityHandle,
+): Result<Candidate, BindAnimationTargetsError> {
+  if (!world.get(target, Entity).ok || !world.get(target, Transform).ok) {
+    return bindError(
+      'animation-target-invalid',
+      'a live target entity carrying Transform',
+      'spawn or retain the Transform target before binding it',
+      { player: player as number, target: target as number },
+    );
+  }
+
+  const lineage = targetLineage(world, player, target);
+  if (!lineage.ok) return lineage;
+
+  const storedId = world.get(target, AnimationTargetId);
+  let id: AnimationTargetIdValue;
+  if (storedId.ok) {
+    if (!isAnimationTargetId(storedId.value.value)) {
+      return bindError(
+        'animation-target-id-invalid',
+        'a 32-character lowercase hexadecimal AnimationTargetId wire',
+        'replace the stored value with deriveAnimationTargetId(path)',
+        { target: target as number, value: storedId.value.value },
+      );
+    }
+    id = storedId.value.value;
+  } else {
+    const path: string[] = [];
+    for (const entity of lineage.value) {
+      const name = world.get(entity, Name);
+      if (!name.ok) {
+        return bindError(
+          'animation-target-name-missing',
+          'a Name on every entity from the animation root through the target',
+          'attach Name before deriving the target ID',
+          { player: player as number, target: target as number, entity: entity as number },
+        );
+      }
+      path.push(name.value.value);
+    }
+    id = deriveAnimationTargetId(path);
+  }
+
+  const owner = world.get(target, AnimatedBy);
+  if (
+    owner.ok &&
+    owner.value.player !== null &&
+    owner.value.player !== player &&
+    world.get(owner.value.player, Entity).ok
+  ) {
+    return bindError(
+      'animation-target-player-conflict',
+      'an unowned target, a stale owner, or the same animation player',
+      'remove AnimatedBy or bind the target through its current live owner',
+      {
+        player: player as number,
+        target: target as number,
+        owner: owner.value.player as number,
+      },
+    );
+  }
+
+  return ok({
+    entity: target,
+    id,
+    needsId: !storedId.ok,
+    owner: owner.ok ? owner.value.player : undefined,
+  });
+}
+
+export function bindAnimationTargets(
+  world: World,
+  player: EntityHandle,
+  targets: readonly EntityHandle[],
+): Result<void, BindAnimationTargetsError> {
+  if (!world.get(player, Entity).ok || !world.get(player, AnimationPlayer).ok) {
+    return bindError(
+      'animation-target-player-invalid',
+      'a live entity carrying AnimationPlayer',
+      'spawn or retain the AnimationPlayer before binding targets',
+      { player: player as number },
+    );
+  }
+
+  const uniqueTargets = [...new Map(targets.map((target) => [target as number, target])).values()];
+  const mirror = world.get(player, AnimationTargets);
+  const candidates: Candidate[] = [];
+  const ids = new Map<AnimationTargetIdValue, EntityHandle[]>();
+  if (mirror.ok) {
+    for (const targetRaw of mirror.value.targets) {
+      const target = targetRaw as EntityHandle;
+      if (!world.get(target, Entity).ok) continue;
+      const storedId = world.get(target, AnimationTargetId);
+      if (!storedId.ok || !isAnimationTargetId(storedId.value.value)) continue;
+      const matching = ids.get(storedId.value.value);
+      if (matching) {
+        if (!matching.includes(target)) matching.push(target);
+      } else {
+        ids.set(storedId.value.value, [target]);
+      }
+    }
+  }
+  for (const target of uniqueTargets) {
+    const candidate = inspectTarget(world, player, target);
+    if (!candidate.ok) return candidate;
+    const matching = ids.get(candidate.value.id);
+    const previous = matching?.find((entity) => entity !== target);
+    if (previous !== undefined) {
+      return bindError(
+        'animation-target-id-duplicate',
+        'one target entity per AnimationTargetId within a batch',
+        'rename one target path or preserve distinct authored target IDs',
+        {
+          id: candidate.value.id,
+          first: previous as number,
+          second: target as number,
+        },
+      );
+    }
+    if (matching) {
+      if (!matching.includes(target)) matching.push(target);
+    } else {
+      ids.set(candidate.value.id, [target]);
+    }
+    candidates.push(candidate.value);
+  }
+
+  const existing = new Set(mirror.ok ? [...mirror.value.targets] : []);
+
+  for (const candidate of candidates) {
+    if (candidate.needsId) {
+      const added = world.addComponent(candidate.entity, {
+        component: AnimationTargetId,
+        data: { value: candidate.id },
+      });
+      if (!added.ok) {
+        return bindError(
+          'animation-target-bind-failed',
+          'the preflighted AnimationTargetId write to succeed',
+          'inspect the ECS error before retrying the batch',
+          { target: candidate.entity as number, cause: added.error.code },
+        );
+      }
+    }
+    if (candidate.owner !== player || !existing.has(candidate.entity)) {
+      const added = world.addComponent(candidate.entity, {
+        component: AnimatedBy,
+        data: { player },
+      });
+      if (!added.ok) {
+        return bindError(
+          'animation-target-bind-failed',
+          'the preflighted AnimatedBy write to succeed',
+          'inspect the ECS error before retrying the batch',
+          { target: candidate.entity as number, cause: added.error.code },
+        );
+      }
+    }
+  }
+  return ok(undefined);
+}

package/src/assets/animation-decoder.ts

@@ -0,0 +1,107 @@
+import {
+  type AnimationClip,
+  type AnimationGraph,
+  type AnimationGraphNode,
+  type AssetDecoderContribution,
+  type AssetKind,
+  err,
+  ok,
+} from '@forgeax/engine-types';
+
+const invalid = (guid: string, expected: string) =>
+  err({
+    code: 'asset-package-invalid' as const,
+    expected,
+    hint: 'recook the animation asset and publish its complete payload',
+    detail: { guid, reason: 'animation owner validation failed' },
+  });
+
+function refGuid(value: unknown, refs: readonly string[]): string | undefined {
+  if (typeof value === 'string' && value.length > 0) return value;
+  if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0) {
+    return refs[value];
+  }
+  return undefined;
+}
+
+function graphNode(value: unknown, refs: readonly string[]): AnimationGraphNode | undefined {
+  if (value === null || typeof value !== 'object') return undefined;
+  const source = value as Record<string, unknown>;
+  if (typeof source.weight !== 'number' || !Number.isFinite(source.weight)) return undefined;
+  if (source.type === 'clip') {
+    const clip = refGuid(source.clip, refs);
+    return clip === undefined ? undefined : { type: 'clip', clip, weight: source.weight };
+  }
+  if (source.type === 'blend') {
+    return Array.isArray(source.children) &&
+      source.children.every((child) => Number.isSafeInteger(child) && (child as number) >= 0)
+      ? { type: 'blend', children: source.children as number[], weight: source.weight }
+      : undefined;
+  }
+  if (source.type === 'add') {
+    return typeof source.base === 'number' &&
+      Number.isSafeInteger(source.base) &&
+      source.base >= 0 &&
+      Array.isArray(source.additive) &&
+      source.additive.every((child) => Number.isSafeInteger(child) && (child as number) >= 0)
+      ? {
+          type: 'add',
+          base: source.base,
+          additive: source.additive as number[],
+          weight: source.weight,
+        }
+      : undefined;
+  }
+  return undefined;
+}
+
+export const animationClipContribution: AssetDecoderContribution<AnimationClip, 'animation-clip'> =
+  {
+    kind: { kind: 'animation-clip' } as AssetKind<AnimationClip, 'animation-clip'>,
+    consumer: 'AnimationPlayer',
+    decoder: {
+      async decode({ envelope }) {
+        return envelope.payload.kind === 'animation-clip' &&
+          Array.isArray(envelope.payload.channels) &&
+          Number.isFinite(envelope.payload.duration) &&
+          envelope.payload.duration >= 0
+          ? ok(envelope.payload)
+          : invalid(envelope.guid, 'an animation clip with channels and non-negative duration');
+      },
+    },
+  };
+
+export const animationGraphContribution: AssetDecoderContribution<
+  AnimationGraph,
+  'animation-graph'
+> = {
+  kind: { kind: 'animation-graph' } as AssetKind<AnimationGraph, 'animation-graph'>,
+  consumer: 'evaluateAnimationGraph',
+  decoder: {
+    async decode({ envelope }) {
+      const payload = envelope.payload as unknown;
+      if (payload === null || typeof payload !== 'object') {
+        return invalid(envelope.guid, 'an animation graph with at least one node');
+      }
+      const source = payload as Record<string, unknown>;
+      if (
+        source.kind !== 'animation-graph' ||
+        !Array.isArray(source.nodes) ||
+        source.nodes.length === 0 ||
+        !Number.isSafeInteger(source.root) ||
+        (source.root as number) < 0
+      ) {
+        return invalid(envelope.guid, 'an animation graph with at least one node');
+      }
+      const nodes: AnimationGraphNode[] = [];
+      for (const value of source.nodes) {
+        const node = graphNode(value, envelope.refs);
+        if (node === undefined) {
+          return invalid(envelope.guid, 'an animation graph with resolvable node references');
+        }
+        nodes.push(node);
+      }
+      return ok({ kind: 'animation-graph', nodes, root: source.root as number });
+    },
+  },
+};

package/src/errors.ts

@@ -0,0 +1,201 @@
+// @forgeax/engine-animation -- AnimationGraph cluster structured errors.
+//
+// feat-20260713-animation-state-machine-plugin M2 / w14: defineAnimationGraph
+// validates graph topology at CONSTRUCTION time (plan D-5) -- before a GUID
+// handle is minted, so an illegal graph can never be registered or serialized
+// into a pack (AC-14). Each illegal shape returns a structured error carrying a
+// machine-readable `.code` / `.hint` / `.detail` so AI users self-repair by
+// property access without parsing prose (requirements AC-11, charter P3). This
+// mirrors the player-errors.ts convention (code/expected/hint/detail
+// four-field surface + closed code union + closed error union).
+
+// -- AnimationGraphEmptyError ----------------------------------------------------
+
+/**
+ * Structured error for an empty graph (zero nodes).
+ *
+ *   - `.code = 'animation-graph-empty'`
+ *   - `.expected` -- a graph declares at least one node
+ *   - `.hint` -- add at least one clip/blend/add node before returning the root
+ */
+export class AnimationGraphEmptyError extends Error {
+  readonly code = 'animation-graph-empty' as const;
+  readonly expected: string;
+  readonly hint: string;
+
+  constructor() {
+    super('AnimationGraph is empty: the builder produced zero nodes');
+    this.name = 'AnimationGraphEmptyError';
+    this.expected = 'an AnimationGraph declares at least one node';
+    this.hint =
+      'declare at least one clip/blend/add node inside defineAnimationGraph(...) and return its ref as the root';
+  }
+}
+
+// -- AnimationGraphNodeOutOfRangeError -------------------------------------------
+
+/** Detail for `'animation-graph-node-out-of-range'`. */
+export interface AnimationGraphNodeOutOfRangeDetail {
+  /** Index of the node holding the offending reference, or the graph root. */
+  readonly node: number;
+  /** The out-of-range reference value that was encountered. */
+  readonly ref: number;
+  /** Total node count -- valid refs live in `[0, nodeCount)`. */
+  readonly nodeCount: number;
+}
+
+/**
+ * Structured error for a node reference that points outside `[0, nodeCount)`.
+ *
+ *   - `.code = 'animation-graph-node-out-of-range'`
+ *   - `.expected` -- every child/base/additive/root ref is in `[0, nodeCount)`
+ *   - `.hint` -- reference only node refs returned by the builder in this graph
+ *   - `.detail = { node, ref, nodeCount }`
+ */
+export class AnimationGraphNodeOutOfRangeError extends Error {
+  readonly code = 'animation-graph-node-out-of-range' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: AnimationGraphNodeOutOfRangeDetail;
+
+  constructor(detail: AnimationGraphNodeOutOfRangeDetail) {
+    const { node, ref, nodeCount } = detail;
+    super(
+      `AnimationGraph node ${node} references out-of-range node ${ref} (graph has ${nodeCount} nodes)`,
+    );
+    this.name = 'AnimationGraphNodeOutOfRangeError';
+    this.expected = 'every node reference is a valid index in [0, nodeCount)';
+    this.hint = `node ${node} references index ${ref}, but valid indices are 0..${nodeCount - 1}; reference only node refs returned by the builder in this graph`;
+    this.detail = detail;
+  }
+}
+
+// -- AnimationGraphNodeWeightInvalidError ----------------------------------------
+
+/** Detail for `'animation-graph-node-weight-invalid'`. */
+export interface AnimationGraphNodeWeightInvalidDetail {
+  /** Index of the node whose static weight is invalid. */
+  readonly node: number;
+  /** The offending weight value (negative or non-finite / NaN). */
+  readonly weight: number;
+}
+
+/**
+ * Structured error for a negative or non-finite (NaN / Infinity) static weight.
+ *
+ *   - `.code = 'animation-graph-node-weight-invalid'`
+ *   - `.expected` -- every node static weight is a finite value `>= 0`
+ *   - `.hint` -- pass a finite non-negative weight (Add layers may exceed 1)
+ *   - `.detail = { node, weight }`
+ */
+export class AnimationGraphNodeWeightInvalidError extends Error {
+  readonly code = 'animation-graph-node-weight-invalid' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: AnimationGraphNodeWeightInvalidDetail;
+
+  constructor(detail: AnimationGraphNodeWeightInvalidDetail) {
+    const { node, weight } = detail;
+    super(`AnimationGraph node ${node} has an invalid static weight ${weight}`);
+    this.name = 'AnimationGraphNodeWeightInvalidError';
+    this.expected = 'every node static weight is a finite number >= 0';
+    this.hint = `node ${node} has weight ${weight}; pass a finite non-negative static weight (Add layers may sum above 1, but a single node weight must be >= 0)`;
+    this.detail = detail;
+  }
+}
+
+// -- AnimationGraphCycleError ----------------------------------------------------
+
+/** Detail for `'animation-graph-cycle'`. */
+export interface AnimationGraphCycleDetail {
+  /** A node index that participates in the detected cycle (the back edge). */
+  readonly node: number;
+}
+
+/**
+ * Structured error for a cycle in the (must-be-acyclic) graph.
+ *
+ *   - `.code = 'animation-graph-cycle'`
+ *   - `.expected` -- the graph is a DAG (no node reaches itself)
+ *   - `.hint` -- remove the self/back reference so the graph is acyclic
+ *   - `.detail = { node }`
+ */
+export class AnimationGraphCycleError extends Error {
+  readonly code = 'animation-graph-cycle' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: AnimationGraphCycleDetail;
+
+  constructor(detail: AnimationGraphCycleDetail) {
+    const { node } = detail;
+    super(`AnimationGraph contains a cycle reachable from node ${node}`);
+    this.name = 'AnimationGraphCycleError';
+    this.expected = 'the AnimationGraph is a DAG (no node reaches itself)';
+    this.hint = `node ${node} participates in a cycle; a graph must be acyclic -- remove the self/back reference so no node transitively references itself`;
+    this.detail = detail;
+  }
+}
+
+// -- AnimationGraphClipMissingError ----------------------------------------------
+
+/** Detail for `'animation-graph-clip-missing'`. */
+export interface AnimationGraphClipMissingDetail {
+  /** Index of the clip node whose `shared<AnimationClip>` handle failed to resolve. */
+  readonly node: number;
+  /** The raw clip handle that did not resolve (never registered / rc released). */
+  readonly clip: number;
+}
+
+/**
+ * Structured error for a graph clip leaf whose `shared<AnimationClip>` handle
+ * cannot be resolved at evaluation time (never registered, or its refcount was
+ * released). Raised by `evaluateAnimationGraph` (M3 / w25) BEFORE any derived
+ * slot is written, so a dangling clip never leaves a dirty pose (requirements
+ * AC-11 clip-missing branch, plan §8). Unlike the construction-time
+ * {@link AnimationGraphError} shapes, this is an EVALUATION-time error: it is not
+ * part of `defineAnimationGraph`'s `Result` (topology is validated at build, clip
+ * liveness only at eval), so it stays out of the construction closed union.
+ *
+ *   - `.code = 'animation-graph-clip-missing'`
+ *   - `.expected` -- every clip node's handle resolves to a live AnimationClip
+ *   - `.hint` -- keep the clip asset registered (rc retained) while the graph
+ *     references it
+ *   - `.detail = { node, clip }`
+ */
+export class AnimationGraphClipMissingError extends Error {
+  readonly code = 'animation-graph-clip-missing' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: AnimationGraphClipMissingDetail;
+
+  constructor(detail: AnimationGraphClipMissingDetail) {
+    const { node, clip } = detail;
+    super(`AnimationGraph clip node ${node} references unresolved AnimationClip handle ${clip}`);
+    this.name = 'AnimationGraphClipMissingError';
+    this.expected = 'every clip node handle resolves to a live AnimationClip';
+    this.hint = `clip node ${node} references AnimationClip handle ${clip}, which did not resolve; keep the clip asset registered (refcount retained) for as long as the graph references it`;
+    this.detail = detail;
+  }
+}
+
+// -- AnimationGraphErrorCode / AnimationGraphError closed unions ------------------
+
+/**
+ * Closed union of AnimationGraph-cluster error codes. AI users perform
+ * exhaustive `switch (err.code)` without default; TS guards completeness.
+ */
+export type AnimationGraphErrorCode =
+  | 'animation-graph-empty'
+  | 'animation-graph-node-out-of-range'
+  | 'animation-graph-node-weight-invalid'
+  | 'animation-graph-cycle';
+
+/**
+ * Closed union of the AnimationGraph-cluster structured error classes, each
+ * carrying an `AnimationGraphErrorCode` discriminant on `.code`.
+ */
+export type AnimationGraphError =
+  | AnimationGraphEmptyError
+  | AnimationGraphNodeOutOfRangeError
+  | AnimationGraphNodeWeightInvalidError
+  | AnimationGraphCycleError;