@auraindustry/aurajs 0.1.3 → 0.1.5

package/src/helpers/starter-utils/avatar-3d.js

@@ -0,0 +1,404 @@
+import { clamp } from './core.js';
+
+function finite(value, fallback = 0) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : fallback;
+}
+
+function normalizeVec3(value, fallback = {}) {
+  return {
+    x: finite(value?.x, finite(fallback?.x, 0)),
+    y: finite(value?.y, finite(fallback?.y, 0)),
+    z: finite(value?.z, finite(fallback?.z, 0)),
+  };
+}
+
+function normalizeScale(value, fallback = {}) {
+  return {
+    x: Math.max(0.001, finite(value?.x, Math.max(0.001, finite(fallback?.x, 1)))),
+    y: Math.max(0.001, finite(value?.y, Math.max(0.001, finite(fallback?.y, 1)))),
+    z: Math.max(0.001, finite(value?.z, Math.max(0.001, finite(fallback?.z, 1)))),
+  };
+}
+
+function normalizeClipMapEntry(entry) {
+  if (Number.isInteger(entry) && entry > 0) {
+    return { clipId: entry };
+  }
+  if (!entry || typeof entry !== 'object') {
+    return null;
+  }
+  return {
+    clipId: Number.isInteger(entry.clipId) && entry.clipId > 0 ? entry.clipId : null,
+    importId: Number.isInteger(entry.importId) && entry.importId > 0 ? entry.importId : null,
+    animation: typeof entry.animation === 'string' && entry.animation.trim().length > 0
+      ? entry.animation.trim()
+      : null,
+    loop: typeof entry.loop === 'boolean' ? entry.loop : null,
+    speed: Number.isFinite(Number(entry.speed)) ? Number(entry.speed) : null,
+    transitionSeconds: Math.max(0, finite(entry.transitionSeconds, 0.16)),
+  };
+}
+
+function cloneState(avatar) {
+  return {
+    bodyId: avatar.bodyId,
+    locomotion: avatar.locomotion,
+    grounded: avatar.grounded,
+    onSlope: avatar.onSlope,
+    velocityY: avatar.velocityY,
+    facingYaw: avatar.facingYaw,
+    position: { ...avatar.position },
+    movement: { ...avatar.motion },
+    camera: {
+      position: { ...avatar.cameraState.position },
+      target: { ...avatar.cameraState.target },
+    },
+    visual: {
+      activeClipKey: avatar.visual.activeClipKey,
+      activeClipId: avatar.visual.activeClipId,
+      sceneNodeId: avatar.visual.sceneNodeId,
+      renderTransform: getAvatarRenderTransform3D(avatar),
+    },
+  };
+}
+
+function clipCandidatesForLocomotion(locomotion) {
+  switch (locomotion) {
+    case 'run':
+      return ['run', 'walk', 'idle', 'default'];
+    case 'fall':
+      return ['fall', 'jump', 'idle', 'default'];
+    case 'jump':
+      return ['jump', 'fall', 'idle', 'default'];
+    case 'walk':
+      return ['walk', 'run', 'idle', 'default'];
+    default:
+      return [locomotion, 'idle', 'default'];
+  }
+}
+
+function resolveAvatarClipEntry(avatar, locomotion) {
+  const clipMap = avatar.visual.clipMap || {};
+  for (const candidate of clipCandidatesForLocomotion(locomotion)) {
+    if (!Object.prototype.hasOwnProperty.call(clipMap, candidate)) {
+      continue;
+    }
+    return normalizeClipMapEntry(clipMap[candidate]);
+  }
+  return null;
+}
+
+function ensureClipId(aura, avatar, locomotion) {
+  const entry = resolveAvatarClipEntry(avatar, locomotion);
+  if (!entry) return null;
+  if (Number.isInteger(entry.clipId) && entry.clipId > 0) {
+    return { ...entry, clipId: entry.clipId };
+  }
+  if (!entry.importId || !entry.animation || typeof aura?.scene3d?.playImportedAnimation !== 'function') {
+    return null;
+  }
+
+  const cacheKey = `${entry.importId}:${entry.animation}:${entry.loop === false ? '0' : '1'}:${entry.speed ?? 1}`;
+  const cached = avatar.visual.importedClipCache[cacheKey];
+  if (Number.isInteger(cached) && cached > 0) {
+    return { ...entry, clipId: cached };
+  }
+
+  const playback = aura.scene3d.playImportedAnimation(entry.importId, entry.animation, {
+    loop: entry.loop !== false,
+    speed: entry.speed ?? 1,
+  });
+  if (playback?.ok === true && Number.isInteger(playback.clipId) && playback.clipId > 0) {
+    avatar.visual.importedClipCache[cacheKey] = playback.clipId;
+    return { ...entry, clipId: playback.clipId };
+  }
+  return null;
+}
+
+function applyClipState(aura, avatar, locomotion) {
+  if (!aura?.scene3d || typeof aura.scene3d !== 'object') return;
+  const entry = ensureClipId(aura, avatar, locomotion);
+  if (!entry || !Number.isInteger(entry.clipId) || entry.clipId <= 0) return;
+
+  const nextClipId = entry.clipId;
+  const previousClipId = avatar.visual.activeClipId;
+  const stateChanged = avatar.visual.activeClipKey !== locomotion || previousClipId !== nextClipId;
+  if (!stateChanged) return;
+
+  if (typeof entry.loop === 'boolean' && typeof aura.scene3d.setClipLoop === 'function') {
+    aura.scene3d.setClipLoop(nextClipId, entry.loop);
+  }
+
+  const transitionSeconds = Math.max(0, finite(entry.transitionSeconds, 0.16));
+  if (
+    Number.isInteger(previousClipId)
+    && previousClipId > 0
+    && previousClipId !== nextClipId
+    && transitionSeconds > 0
+    && typeof aura.scene3d.crossfadeClips === 'function'
+  ) {
+    aura.scene3d.crossfadeClips(previousClipId, nextClipId, {
+      duration: transitionSeconds,
+    });
+  } else if (typeof aura.scene3d.playClip === 'function') {
+    aura.scene3d.playClip(nextClipId);
+  }
+
+  avatar.visual.activeClipKey = locomotion;
+  avatar.visual.activeClipId = nextClipId;
+}
+
+function syncSceneNodeTransform(aura, avatar) {
+  if (!Number.isInteger(avatar.visual.sceneNodeId) || avatar.visual.sceneNodeId <= 0) {
+    return;
+  }
+  if (typeof aura?.scene3d?.setLocalTransform !== 'function') {
+    return;
+  }
+  aura.scene3d.setLocalTransform(avatar.visual.sceneNodeId, getAvatarRenderTransform3D(avatar));
+}
+
+function syncCamera(aura, avatar) {
+  if (avatar.camera.enabled !== true) return;
+  if (typeof aura?.camera3d?.setPosition !== 'function' || typeof aura?.camera3d?.lookAt !== 'function') {
+    return;
+  }
+
+  let cameraOffset = avatar.camera.offset;
+  if (avatar.camera.rotateWithFacing === true) {
+    const cosine = Math.cos(avatar.facingYaw);
+    const sine = Math.sin(avatar.facingYaw);
+    cameraOffset = {
+      x: (avatar.camera.offset.x * cosine) - (avatar.camera.offset.z * sine),
+      y: avatar.camera.offset.y,
+      z: (avatar.camera.offset.x * sine) + (avatar.camera.offset.z * cosine),
+    };
+  }
+
+  const target = {
+    x: avatar.position.x + avatar.camera.lookOffset.x,
+    y: avatar.position.y + avatar.camera.lookOffset.y,
+    z: avatar.position.z + avatar.camera.lookOffset.z,
+  };
+  const position = {
+    x: avatar.position.x + cameraOffset.x,
+    y: avatar.position.y + cameraOffset.y,
+    z: avatar.position.z + cameraOffset.z,
+  };
+
+  avatar.cameraState = { position, target };
+  aura.camera3d.setPosition(position.x, position.y, position.z);
+  aura.camera3d.lookAt(target.x, target.y, target.z);
+}
+
+function resolveLocomotion(avatar, magnitude) {
+  if (!avatar.grounded) {
+    return avatar.velocityY > 0.2 ? 'jump' : 'fall';
+  }
+  if (magnitude >= 0.85) return 'run';
+  if (magnitude >= 0.1) return 'walk';
+  return 'idle';
+}
+
+export function createCharacterAvatar3D(options = {}) {
+  const radius = Math.max(0.1, finite(options.radius, 0.45));
+  const height = Math.max(radius * 2, finite(options.height, 1.1));
+  const visualScale = normalizeScale(options.visual?.scale, {
+    x: radius * 2,
+    y: height,
+    z: radius * 2,
+  });
+
+  return {
+    bodyId: null,
+    position: normalizeVec3(options.position, { x: 0, y: height * 0.5, z: 0 }),
+    grounded: false,
+    onSlope: false,
+    velocityY: 0,
+    facingYaw: finite(options.facingYaw, 0),
+    locomotion: 'idle',
+    motion: {
+      moveX: 0,
+      moveZ: 0,
+      magnitude: 0,
+      speed: 0,
+    },
+    input: {
+      moveX: 0,
+      moveZ: 0,
+      jump: false,
+      run: false,
+    },
+    movement: {
+      radius,
+      height,
+      stepHeight: Math.max(0.05, finite(options.stepHeight, 0.45)),
+      slopeLimit: Math.max(1, finite(options.slopeLimit, 48)),
+      gravity: Math.max(0, finite(options.gravity, 20)),
+      moveSpeed: Math.max(0, finite(options.moveSpeed, 5.3)),
+      runSpeed: Math.max(0, finite(options.runSpeed, Math.max(6.4, finite(options.moveSpeed, 5.3)))),
+      jumpSpeed: Math.max(0, finite(options.jumpSpeed, 8.2)),
+    },
+    visual: {
+      offset: normalizeVec3(options.visual?.offset),
+      scale: visualScale,
+      sceneNodeId: Number.isInteger(options.visual?.sceneNodeId) ? options.visual.sceneNodeId : null,
+      clipMap: options.visual?.clipMap && typeof options.visual.clipMap === 'object'
+        ? { ...options.visual.clipMap }
+        : {},
+      importedClipCache: {},
+      activeClipKey: null,
+      activeClipId: null,
+    },
+    camera: {
+      enabled: options.camera?.enabled !== false,
+      offset: normalizeVec3(options.camera?.offset, { x: 7.4, y: 6.0, z: 8.8 }),
+      lookOffset: normalizeVec3(options.camera?.lookOffset, { x: 0, y: 0.2, z: 0 }),
+      rotateWithFacing: options.camera?.rotateWithFacing === true,
+    },
+    cameraState: {
+      position: normalizeVec3(options.position, { x: 0, y: height * 0.5, z: 0 }),
+      target: normalizeVec3(options.position, { x: 0, y: height * 0.5, z: 0 }),
+    },
+  };
+}
+
+export function setAvatarInput3D(avatar, input = {}) {
+  avatar.input.moveX = clamp(finite(input.moveX, avatar.input.moveX), -1, 1);
+  avatar.input.moveZ = clamp(finite(input.moveZ, avatar.input.moveZ), -1, 1);
+  avatar.input.jump = input.jump === true;
+  avatar.input.run = input.run === true;
+  return avatar.input;
+}
+
+export function setAvatarVisual3D(avatar, options = {}) {
+  avatar.visual.offset = normalizeVec3(options.offset, avatar.visual.offset);
+  avatar.visual.scale = normalizeScale(options.scale, avatar.visual.scale);
+  if (Object.prototype.hasOwnProperty.call(options, 'sceneNodeId')) {
+    avatar.visual.sceneNodeId = Number.isInteger(options.sceneNodeId) ? options.sceneNodeId : null;
+  }
+  if (options.clipMap && typeof options.clipMap === 'object') {
+    avatar.visual.clipMap = { ...options.clipMap };
+    avatar.visual.activeClipKey = null;
+    avatar.visual.activeClipId = null;
+    avatar.visual.importedClipCache = {};
+  }
+  return avatar.visual;
+}
+
+export function spawnCharacterAvatar3D(aura, avatar, options = {}) {
+  const position = normalizeVec3(options.position, avatar.position);
+  avatar.position = position;
+
+  if (!Number.isInteger(avatar.bodyId) || avatar.bodyId <= 0) {
+    avatar.bodyId = aura.character3d.create({
+      x: position.x,
+      y: position.y,
+      z: position.z,
+      radius: avatar.movement.radius,
+      height: avatar.movement.height,
+      stepHeight: avatar.movement.stepHeight,
+      slopeLimit: avatar.movement.slopeLimit,
+      gravity: avatar.movement.gravity,
+    });
+  } else if (typeof aura?.character3d?.setPosition === 'function') {
+    aura.character3d.setPosition(avatar.bodyId, position.x, position.y, position.z);
+  }
+
+  const nextState = typeof aura?.character3d?.getState === 'function'
+    ? aura.character3d.getState(avatar.bodyId)
+    : null;
+  if (nextState && typeof nextState === 'object') {
+    avatar.position = normalizeVec3(nextState, position);
+    avatar.grounded = nextState.grounded === true;
+    avatar.velocityY = finite(nextState.velocityY, 0);
+    avatar.onSlope = nextState.onSlope === true;
+  }
+
+  syncSceneNodeTransform(aura, avatar);
+  syncCamera(aura, avatar);
+  return avatar.bodyId;
+}
+
+export function tickCharacterAvatar3D(aura, avatar, dt) {
+  const frameDt = Math.max(0, finite(dt, 0));
+  if (!Number.isInteger(avatar.bodyId) || avatar.bodyId <= 0) {
+    spawnCharacterAvatar3D(aura, avatar);
+  }
+
+  const rawMoveX = clamp(finite(avatar.input.moveX, 0), -1, 1);
+  const rawMoveZ = clamp(finite(avatar.input.moveZ, 0), -1, 1);
+  let moveX = rawMoveX;
+  let moveZ = rawMoveZ;
+  const magnitude = Math.hypot(moveX, moveZ);
+  if (magnitude > 1e-6) {
+    moveX /= magnitude;
+    moveZ /= magnitude;
+    avatar.facingYaw = Math.atan2(moveX, moveZ);
+  }
+
+  const speed = avatar.input.run === true ? avatar.movement.runSpeed : avatar.movement.moveSpeed;
+  if (typeof aura?.character3d?.move === 'function') {
+    aura.character3d.move(avatar.bodyId, {
+      x: moveX * speed * frameDt,
+      y: 0,
+      z: moveZ * speed * frameDt,
+    });
+  }
+
+  if (avatar.input.jump === true && typeof aura?.character3d?.jump === 'function') {
+    aura.character3d.jump(avatar.bodyId, avatar.movement.jumpSpeed);
+  }
+
+  if (typeof aura?.character3d?.update === 'function') {
+    aura.character3d.update(frameDt);
+  }
+  const state = typeof aura?.character3d?.getState === 'function'
+    ? aura.character3d.getState(avatar.bodyId)
+    : null;
+  if (state && typeof state === 'object') {
+    avatar.position = normalizeVec3(state, avatar.position);
+    avatar.grounded = state.grounded === true;
+    avatar.velocityY = finite(state.velocityY, 0);
+    avatar.onSlope = state.onSlope === true;
+  }
+
+  avatar.motion = {
+    moveX,
+    moveZ,
+    magnitude,
+    speed: magnitude > 1e-6 ? speed : 0,
+  };
+  avatar.locomotion = resolveLocomotion(avatar, magnitude);
+  applyClipState(aura, avatar, avatar.locomotion);
+
+  if (typeof aura?.scene3d?.updateClips === 'function') {
+    aura.scene3d.updateClips(frameDt);
+  }
+
+  syncSceneNodeTransform(aura, avatar);
+  syncCamera(aura, avatar);
+  avatar.input.jump = false;
+  return cloneState(avatar);
+}
+
+export function getAvatarRenderTransform3D(avatar) {
+  return {
+    position: {
+      x: avatar.position.x + avatar.visual.offset.x,
+      y: avatar.position.y + avatar.visual.offset.y,
+      z: avatar.position.z + avatar.visual.offset.z,
+    },
+    rotation: {
+      x: 0,
+      y: avatar.facingYaw,
+      z: 0,
+    },
+    scale: { ...avatar.visual.scale },
+  };
+}
+
+export function getAvatarState3D(avatar) {
+  return cloneState(avatar);
+}