@auraindustry/aurajs 0.0.6 → 0.1.0

package/src/authoring/avatar-animation-graph.mjs

@@ -0,0 +1,648 @@
+const DEFAULT_AVATAR_LOCOMOTION_KEYS = Object.freeze([
+  'idle',
+  'walk',
+  'run',
+  'jump',
+  'fall',
+  'land',
+]);
+
+const DEFAULT_AVATAR_ACTION_KEYS = Object.freeze([
+  'attack',
+  'hurt',
+]);
+
+const AVATAR_RUNTIME_METHODS = Object.freeze([
+  'spawn',
+  'destroy',
+  'setInput',
+  'setAnimations',
+  'setAnimationState',
+  'defineSocket',
+  'attach',
+  'detach',
+  'onAnimationEvent',
+  'playAnimation',
+  'clearAnimation',
+  'tick',
+  'getState',
+]);
+
+export {
+  DEFAULT_AVATAR_ACTION_KEYS,
+  DEFAULT_AVATAR_LOCOMOTION_KEYS,
+};
+
+export function normalizeAvatarAnimationGraphConfig(config = {}) {
+  if (!isPlainObject(config)) {
+    throw new TypeError('Avatar animation graph config must be an object.');
+  }
+
+  const normalized = {
+    avatar: isAvatarRuntime(config.avatar) ? config.avatar : null,
+    avatarOptions: isAvatarRuntime(config.avatar)
+      ? {}
+      : collectAvatarCreationOptions(config),
+    animations: normalizeAnimationMap(config.animations),
+    animationState: normalizeAnimationState(config.animationState),
+    sockets: normalizeSocketMap(config.sockets),
+    actions: normalizeActionMap(
+      config.actions,
+      normalizeAnimationMap(config.animations),
+    ),
+    onAnimationEvent: typeof config.onAnimationEvent === 'function'
+      ? config.onAnimationEvent
+      : null,
+  };
+
+  if (!normalized.avatar && !Object.keys(normalized.avatarOptions).length) {
+    normalized.avatarOptions = {};
+  }
+
+  return normalized;
+}
+
+export function createAvatarAnimationGraph(aura, config = {}) {
+  const normalized = normalizeAvatarAnimationGraphConfig(config);
+  const avatar = normalized.avatar ?? createRuntimeAvatar(aura, normalized.avatarOptions);
+
+  const state = {
+    config: normalized,
+    avatar,
+    listeners: [],
+    nextListenerId: 1,
+    runtimeUnsubscribe: null,
+    lastAvatarState: null,
+    cooldowns: Object.create(null),
+    activeAction: null,
+    lastTriggeredAction: null,
+    lastCompletedAction: null,
+    lastEvent: null,
+    lastActionEvent: null,
+  };
+
+  bindRuntimeEventBridge(state);
+  applyNormalizedGraphConfig(state, normalized, { resetActions: true });
+
+  if (normalized.onAnimationEvent) {
+    addGraphListener(state, normalized.onAnimationEvent);
+  }
+
+  syncGraphState(state);
+
+  const controller = {
+    aura,
+    avatar,
+    configure(nextConfig = {}) {
+      const merged = mergeGraphConfig(state.config, nextConfig);
+      applyNormalizedGraphConfig(state, merged, { resetActions: false });
+      syncGraphState(state);
+      return controller.getState();
+    },
+    spawn(spawnOptions = {}) {
+      const result = avatar.spawn(isPlainObject(spawnOptions) ? spawnOptions : {});
+      syncGraphState(state);
+      return result;
+    },
+    destroy() {
+      const result = avatar.destroy();
+      if (typeof state.runtimeUnsubscribe === 'function') {
+        state.runtimeUnsubscribe();
+        state.runtimeUnsubscribe = null;
+      }
+      return result;
+    },
+    setInput(input = {}) {
+      const snapshot = avatar.setInput(isPlainObject(input) ? input : {});
+      syncGraphState(state, snapshot);
+      return controller.getState();
+    },
+    setAnimations(animations = {}, animationOptions = {}) {
+      const patch = { animations };
+      if (isPlainObject(animationOptions) && Object.keys(animationOptions).length > 0) {
+        patch.visual = {};
+        if (Object.prototype.hasOwnProperty.call(animationOptions, 'importId')) {
+          patch.visual.importId = animationOptions.importId;
+        }
+        if (Object.prototype.hasOwnProperty.call(animationOptions, 'autoMatchAnimations')) {
+          patch.visual.autoMatchAnimations = animationOptions.autoMatchAnimations;
+        }
+      }
+      return controller.configure(patch);
+    },
+    setAnimationState(animationState = {}) {
+      return controller.configure({ animationState });
+    },
+    defineSocket(name, socketOptions = {}) {
+      const normalizedName = normalizeString(name);
+      if (!normalizedName) {
+        throw new TypeError('Socket names must be non-empty strings.');
+      }
+      const result = avatar.defineSocket(normalizedName, socketOptions);
+      if (!isPlainObject(state.config.sockets)) {
+        state.config.sockets = {};
+      }
+      state.config.sockets[normalizedName] = cloneValue(socketOptions);
+      syncGraphState(state);
+      return result;
+    },
+    attach(socketName, sceneNodeId, attachmentOptions = {}) {
+      const result = avatar.attach(socketName, sceneNodeId, attachmentOptions);
+      syncGraphState(state);
+      return result;
+    },
+    detach(socketName) {
+      const result = avatar.detach(socketName);
+      syncGraphState(state);
+      return result;
+    },
+    getSockets() {
+      return avatar.getSockets();
+    },
+    onAnimationEvent(callback) {
+      return addGraphListener(state, callback);
+    },
+    playAction(name, playOptions = {}) {
+      return playGraphAction(state, name, playOptions);
+    },
+    clearAction() {
+      const result = avatar.clearAnimation();
+      syncGraphState(state);
+      return result;
+    },
+    tick(dtSeconds, input = null) {
+      if (input != null) {
+        controller.setInput(input);
+      }
+      reduceCooldowns(state, dtSeconds);
+      const snapshot = avatar.tick(dtSeconds);
+      syncGraphState(state, snapshot);
+      return controller.getState();
+    },
+    getState() {
+      return buildGraphSnapshot(state);
+    },
+  };
+
+  for (const actionName of DEFAULT_AVATAR_ACTION_KEYS) {
+    controller[actionName] = (playOptions = {}) => controller.playAction(actionName, playOptions);
+  }
+
+  return controller;
+}
+
+export default createAvatarAnimationGraph;
+
+function createRuntimeAvatar(aura, avatarOptions) {
+  if (!aura || typeof aura !== 'object' || !aura.scene3d || typeof aura.scene3d.createAvatar !== 'function') {
+    throw new TypeError('Avatar animation graph requires aura.scene3d.createAvatar() when no existing avatar is provided.');
+  }
+  const avatar = aura.scene3d.createAvatar(avatarOptions);
+  if (!isAvatarRuntime(avatar)) {
+    throw new Error('aura.scene3d.createAvatar() did not return an avatar runtime object.');
+  }
+  return avatar;
+}
+
+function bindRuntimeEventBridge(state) {
+  if (typeof state.avatar.onAnimationEvent !== 'function') return;
+  state.runtimeUnsubscribe = state.avatar.onAnimationEvent((event) => {
+    const normalizedEvent = normalizeRuntimeEvent(event, state.config.actions);
+    state.lastEvent = normalizedEvent;
+    state.lastActionEvent = normalizedEvent.action ? normalizedEvent : state.lastActionEvent;
+    for (const listener of state.listeners.slice().sort((left, right) => left.id - right.id)) {
+      try {
+        listener.callback(normalizedEvent, buildGraphSnapshot(state));
+      } catch {
+        // Author callbacks should never break deterministic graph updates.
+      }
+    }
+  });
+}
+
+function applyNormalizedGraphConfig(state, normalized, options = {}) {
+  state.config = normalized;
+  const animationOptions = {};
+  const importId = normalized.avatarOptions?.visual?.importId;
+  const autoMatchAnimations = normalized.avatarOptions?.visual?.autoMatchAnimations;
+  if (Number.isInteger(importId) && importId > 0) {
+    animationOptions.importId = importId;
+  }
+  if (typeof autoMatchAnimations === 'boolean') {
+    animationOptions.autoMatchAnimations = autoMatchAnimations;
+  }
+  state.avatar.setAnimations(normalized.animations, animationOptions);
+  state.avatar.setAnimationState(normalized.animationState);
+  for (const [socketName, socketOptions] of Object.entries(normalized.sockets)) {
+    state.avatar.defineSocket(socketName, socketOptions);
+  }
+  if (options.resetActions === true) {
+    state.cooldowns = Object.create(null);
+    state.activeAction = null;
+    state.lastTriggeredAction = null;
+    state.lastCompletedAction = null;
+    state.lastActionEvent = null;
+  }
+}
+
+function buildGraphSnapshot(state) {
+  const avatarState = cloneValue(state.lastAvatarState || state.avatar.getState());
+  const cooldowns = {};
+  for (const [name, remaining] of Object.entries(state.cooldowns)) {
+    cooldowns[name] = round6(remaining);
+  }
+
+  return {
+    avatar: avatarState,
+    graph: {
+      locomotionKeys: listConfiguredLocomotionKeys(state.config.animations),
+      actionKeys: Object.keys(state.config.actions).sort((left, right) => left.localeCompare(right)),
+      sockets: Object.keys(state.config.sockets).sort((left, right) => left.localeCompare(right)),
+      activeAction: state.activeAction ? cloneValue(state.activeAction) : null,
+      lastTriggeredAction: state.lastTriggeredAction ? cloneValue(state.lastTriggeredAction) : null,
+      lastCompletedAction: state.lastCompletedAction ? cloneValue(state.lastCompletedAction) : null,
+      cooldowns,
+      lastEvent: state.lastEvent ? cloneValue(state.lastEvent) : null,
+      lastActionEvent: state.lastActionEvent ? cloneValue(state.lastActionEvent) : null,
+    },
+  };
+}
+
+function playGraphAction(state, name, playOptions = {}) {
+  const actionName = normalizeString(name);
+  if (!actionName) {
+    return { ok: false, reason: 'invalid_action', reasonCode: 'invalid_action' };
+  }
+  const action = resolveGraphAction(state.config.actions, actionName);
+  if (!action) {
+    return { ok: false, reason: 'missing_action', reasonCode: 'missing_action' };
+  }
+  const cooldownRemaining = Number(state.cooldowns[action.name] || 0);
+  if (cooldownRemaining > 0) {
+    return {
+      ok: false,
+      reason: 'action_cooldown',
+      reasonCode: 'action_cooldown',
+      cooldownRemaining: round6(cooldownRemaining),
+    };
+  }
+  if (state.activeAction && action.interrupt !== true && state.activeAction.name !== action.name) {
+    return {
+      ok: false,
+      reason: 'action_locked',
+      reasonCode: 'action_locked',
+      activeAction: state.activeAction.name,
+    };
+  }
+
+  const playback = buildActionPlayback(action, playOptions);
+  const result = state.avatar.playAnimation(playback.clipKeyOrEntry, playback.playOptions);
+  if (!result || result.ok !== true) {
+    return {
+      ok: false,
+      reason: 'action_play_failed',
+      reasonCode: 'action_play_failed',
+      playback: cloneValue(result),
+    };
+  }
+
+  state.cooldowns[action.name] = action.cooldownSeconds;
+  state.lastTriggeredAction = {
+    name: action.name,
+    clipKey: action.clipKey,
+    cooldownSeconds: round6(action.cooldownSeconds),
+  };
+  syncGraphState(state);
+
+  return {
+    ok: true,
+    action: action.name,
+    playback: cloneValue(result),
+    state: buildGraphSnapshot(state),
+  };
+}
+
+function buildActionPlayback(action, playOptions = {}) {
+  const overrides = isPlainObject(playOptions) ? playOptions : {};
+  const clipKeyOrEntry = action.entry ?? action.clipKey;
+  return {
+    clipKeyOrEntry,
+    playOptions: {
+      holdSeconds: finiteOr(overrides.holdSeconds, action.holdSeconds),
+      waitForCompletion: overrides.waitForCompletion === true || action.waitForCompletion === true,
+      interrupt: overrides.interrupt !== false && action.interrupt === true,
+      loop: Object.prototype.hasOwnProperty.call(overrides, 'loop')
+        ? overrides.loop === true
+        : action.loop,
+      speed: finiteOr(overrides.speed, action.speed),
+      transitionSeconds: finiteOr(overrides.transitionSeconds, action.transitionSeconds),
+      key: typeof overrides.key === 'string' && overrides.key.trim().length > 0
+        ? overrides.key.trim()
+        : action.name,
+    },
+  };
+}
+
+function reduceCooldowns(state, dtSeconds) {
+  const delta = Number(dtSeconds);
+  if (!Number.isFinite(delta) || delta <= 0) return;
+  for (const name of Object.keys(state.cooldowns)) {
+    state.cooldowns[name] = Math.max(0, Number(state.cooldowns[name] || 0) - delta);
+    if (state.cooldowns[name] <= 0) {
+      delete state.cooldowns[name];
+    }
+  }
+}
+
+function syncGraphState(state, avatarSnapshot = null) {
+  const avatarState = cloneValue(avatarSnapshot || state.avatar.getState());
+  state.lastAvatarState = avatarState;
+
+  const overrideKey = normalizeString(avatarState?.animation?.overrideKey);
+  const nextAction = overrideKey ? resolveGraphAction(state.config.actions, overrideKey) : null;
+
+  if (state.activeAction && !nextAction) {
+    state.lastCompletedAction = {
+      name: state.activeAction.name,
+      clipKey: state.activeAction.clipKey,
+    };
+  }
+
+  state.activeAction = nextAction
+    ? {
+      name: nextAction.name,
+      clipKey: nextAction.clipKey,
+      cooldownRemaining: round6(Number(state.cooldowns[nextAction.name] || 0)),
+    }
+    : null;
+
+  return avatarState;
+}
+
+function addGraphListener(state, callback) {
+  if (typeof callback !== 'function') {
+    throw new TypeError('Avatar animation graph listeners must be functions.');
+  }
+  const listener = {
+    id: state.nextListenerId++,
+    callback,
+  };
+  state.listeners.push(listener);
+  return () => {
+    const index = state.listeners.indexOf(listener);
+    if (index >= 0) state.listeners.splice(index, 1);
+  };
+}
+
+function resolveGraphAction(actionMap, name) {
+  const normalizedName = normalizeString(name);
+  if (!normalizedName || !isPlainObject(actionMap)) return null;
+  const direct = actionMap[normalizedName];
+  if (direct) return direct;
+  for (const entry of Object.values(actionMap)) {
+    if (entry && entry.clipKey === normalizedName) {
+      return entry;
+    }
+  }
+  return null;
+}
+
+function normalizeRuntimeEvent(event, actionMap) {
+  const normalized = isPlainObject(event) ? cloneValue(event) : {};
+  const action = resolveGraphAction(actionMap, normalized.clipKey || normalized.name || '');
+  return {
+    ...normalized,
+    action: action
+      ? {
+        name: action.name,
+        clipKey: action.clipKey,
+      }
+      : null,
+  };
+}
+
+function mergeGraphConfig(previous, patch) {
+  const nextPatch = normalizeAvatarAnimationGraphConfig({
+    ...collectAvatarCreationOptions(previous.avatarOptions || {}),
+    ...cloneValue(patch),
+  });
+  return {
+    avatar: previous.avatar,
+    avatarOptions: mergePlainObjects(previous.avatarOptions, nextPatch.avatarOptions),
+    animations: {
+      ...cloneValue(previous.animations),
+      ...cloneValue(nextPatch.animations),
+    },
+    animationState: {
+      ...cloneValue(previous.animationState),
+      ...cloneValue(nextPatch.animationState),
+    },
+    sockets: {
+      ...cloneValue(previous.sockets),
+      ...cloneValue(nextPatch.sockets),
+    },
+    actions: {
+      ...cloneValue(previous.actions),
+      ...cloneValue(nextPatch.actions),
+    },
+    onAnimationEvent: nextPatch.onAnimationEvent || previous.onAnimationEvent || null,
+  };
+}
+
+function collectAvatarCreationOptions(config) {
+  const source = isPlainObject(config) ? config : {};
+  const out = {};
+  const directKeys = [
+    'position',
+    'radius',
+    'height',
+    'stepHeight',
+    'slopeLimit',
+    'gravity',
+    'moveSpeed',
+    'runSpeed',
+    'jumpSpeed',
+    'facingYaw',
+    'spawn',
+    'sceneNodeId',
+    'importId',
+    'body',
+  ];
+  for (const key of directKeys) {
+    if (Object.prototype.hasOwnProperty.call(source, key)) {
+      out[key] = cloneValue(source[key]);
+    }
+  }
+  if (isPlainObject(source.visual)) out.visual = cloneValue(source.visual);
+  if (isPlainObject(source.camera)) out.camera = cloneValue(source.camera);
+  return out;
+}
+
+function listConfiguredLocomotionKeys(animationMap) {
+  return DEFAULT_AVATAR_LOCOMOTION_KEYS.filter((key) => Object.prototype.hasOwnProperty.call(animationMap, key));
+}
+
+function normalizeAnimationMap(animations) {
+  if (!isPlainObject(animations)) return {};
+  const out = {};
+  for (const [key, value] of Object.entries(animations)) {
+    const normalizedKey = normalizeString(key);
+    if (!normalizedKey) continue;
+    out[normalizedKey] = cloneValue(value);
+  }
+  return out;
+}
+
+function normalizeAnimationState(animationState) {
+  if (!isPlainObject(animationState)) return {};
+  const out = {};
+  if (Object.prototype.hasOwnProperty.call(animationState, 'walkThreshold')) {
+    out.walkThreshold = clamp01(animationState.walkThreshold, 0.1);
+  }
+  if (Object.prototype.hasOwnProperty.call(animationState, 'runThreshold')) {
+    out.runThreshold = Math.max(
+      Object.prototype.hasOwnProperty.call(out, 'walkThreshold') ? out.walkThreshold : 0,
+      clamp01(animationState.runThreshold, 0.82),
+    );
+  }
+  if (Object.prototype.hasOwnProperty.call(animationState, 'jumpVelocityThreshold')) {
+    out.jumpVelocityThreshold = finiteOr(animationState.jumpVelocityThreshold, 0.2);
+  }
+  if (Object.prototype.hasOwnProperty.call(animationState, 'landHoldSeconds')) {
+    out.landHoldSeconds = Math.max(0, finiteOr(animationState.landHoldSeconds, 0.14));
+  }
+  return out;
+}
+
+function normalizeSocketMap(sockets) {
+  if (!isPlainObject(sockets)) return {};
+  const out = {};
+  for (const [name, value] of Object.entries(sockets)) {
+    const normalizedName = normalizeString(name);
+    if (!normalizedName) continue;
+    out[normalizedName] = cloneValue(value);
+  }
+  return out;
+}
+
+function normalizeActionMap(actions, animationMap) {
+  const out = {};
+  if (isPlainObject(actions)) {
+    for (const [name, value] of Object.entries(actions)) {
+      const normalized = normalizeActionDefinition(name, value);
+      if (!normalized) continue;
+      out[normalized.name] = normalized;
+    }
+  }
+  for (const fallbackName of DEFAULT_AVATAR_ACTION_KEYS) {
+    if (out[fallbackName]) continue;
+    if (!Object.prototype.hasOwnProperty.call(animationMap, fallbackName)) continue;
+    const normalized = normalizeActionDefinition(fallbackName, animationMap[fallbackName]);
+    if (!normalized) continue;
+    out[normalized.name] = normalized;
+  }
+  return out;
+}
+
+function normalizeActionDefinition(name, value) {
+  const normalizedName = normalizeString(name);
+  if (!normalizedName) return null;
+
+  if (value === true || value == null) {
+    return createActionDefinition(normalizedName, normalizedName, null, {});
+  }
+  if (typeof value === 'string') {
+    return createActionDefinition(normalizedName, value.trim(), null, {});
+  }
+  if (!isPlainObject(value)) {
+    return null;
+  }
+
+  const clipKey = normalizeString(value.clipKey)
+    || normalizeString(value.key)
+    || normalizeString(value.animation)
+    || normalizedName;
+  const entry = hasActionEntryShape(value)
+    ? cloneValue(value)
+    : null;
+
+  return createActionDefinition(normalizedName, clipKey, entry, value);
+}
+
+function createActionDefinition(name, clipKey, entry, options) {
+  const source = isPlainObject(options) ? options : {};
+  return {
+    name,
+    clipKey,
+    entry,
+    cooldownSeconds: Math.max(0, finiteOr(source.cooldownSeconds, 0)),
+    holdSeconds: source.holdSeconds === Infinity ? Infinity : Math.max(0, finiteOr(source.holdSeconds, 0)),
+    waitForCompletion: source.waitForCompletion !== false,
+    interrupt: source.interrupt !== false,
+    loop: source.loop === true,
+    speed: finiteOr(source.speed, 1),
+    transitionSeconds: Math.max(0, finiteOr(source.transitionSeconds, 0.12)),
+  };
+}
+
+function hasActionEntryShape(value) {
+  if (!isPlainObject(value)) return false;
+  return (
+    Object.prototype.hasOwnProperty.call(value, 'clipId')
+    || Object.prototype.hasOwnProperty.call(value, 'importId')
+    || Object.prototype.hasOwnProperty.call(value, 'animation')
+    || Object.prototype.hasOwnProperty.call(value, 'events')
+    || Object.prototype.hasOwnProperty.call(value, 'tags')
+    || Object.prototype.hasOwnProperty.call(value, 'loop')
+    || Object.prototype.hasOwnProperty.call(value, 'speed')
+  );
+}
+
+function isAvatarRuntime(value) {
+  return isPlainObject(value)
+    && AVATAR_RUNTIME_METHODS.every((method) => typeof value[method] === 'function');
+}
+
+function isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizeString(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function finiteOr(value, fallback) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : fallback;
+}
+
+function clamp01(value, fallback) {
+  return Math.min(1, Math.max(0, finiteOr(value, fallback)));
+}
+
+function round6(value) {
+  return Number(Number(value || 0).toFixed(6));
+}
+
+function cloneValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => cloneValue(entry));
+  }
+  if (isPlainObject(value)) {
+    const out = {};
+    for (const [key, entry] of Object.entries(value)) {
+      out[key] = cloneValue(entry);
+    }
+    return out;
+  }
+  return value;
+}
+
+function mergePlainObjects(left, right) {
+  return {
+    ...(isPlainObject(left) ? cloneValue(left) : {}),
+    ...(isPlainObject(right) ? cloneValue(right) : {}),
+  };
+}