@auraindustry/aurajs 0.0.6 → 0.1.0

package/templates/create/3d/content/gameplay/checkpoints.json

@@ -0,0 +1,33 @@
+{
+  "schema": "aurajs.checkpoints.v1",
+  "checkpoints": [
+    {
+      "id": "spawn",
+      "x": 0,
+      "y": 1.1,
+      "z": 5.5,
+      "radius": 1.4
+    },
+    {
+      "id": "ridge-a",
+      "x": -3.2,
+      "y": 2,
+      "z": -2.4,
+      "radius": 1.25
+    },
+    {
+      "id": "ridge-b",
+      "x": 1.4,
+      "y": 3.2,
+      "z": -0.8,
+      "radius": 1.25
+    },
+    {
+      "id": "goal",
+      "x": 4.4,
+      "y": 4.6,
+      "z": -3,
+      "radius": 1.3
+    }
+  ]
+}

package/templates/create/3d/content/gameplay/course.js

@@ -0,0 +1,40 @@
+export const PLAYER_HALF = { x: 0.45, y: 0.55, z: 0.45 };
+export const MOVE_SPEED = 5.3;
+export const JUMP_SPEED = 8.2;
+export const GRAVITY = 20.0;
+export const WORLD_LIMIT = 9.0;
+export const HUD_TARGET_PICKUPS = 3;
+
+export const FLOOR_SCALE = { x: 24, y: 1, z: 24 };
+export const PLAYER_SPAWN = { x: 0, y: 1.1, z: 5.5 };
+export const CAMERA_OFFSET = { x: 7.4, y: 6.0, z: 8.8 };
+export const CAMERA_LOOK_OFFSET = { x: 0, y: 0.2, z: 0 };
+
+export const STATIC_PLATFORMS = [
+  { x: -3.2, y: 1.2, z: -2.4, sx: 3.0, sy: 0.5, sz: 2.2 },
+  { x: 1.4, y: 2.4, z: -0.8, sx: 2.8, sy: 0.5, sz: 2.0 },
+  { x: 4.4, y: 3.8, z: -3.0, sx: 3.4, sy: 0.5, sz: 2.0 },
+];
+
+export const CHECKPOINTS = [
+  { x: 0, y: 1.1, z: 5.5, radius: 1.4 },
+  { x: -3.2, y: 2.0, z: -2.4, radius: 1.25 },
+  { x: 1.4, y: 3.2, z: -0.8, radius: 1.25 },
+  { x: 4.4, y: 4.6, z: -3.0, radius: 1.3 },
+];
+
+export const MOVING_PLATFORM = {
+  from: { x: -0.2, y: 1.8, z: 2.2 },
+  to: { x: 3.1, y: 3.0, z: 0.8 },
+  size: { x: 2.4, y: 0.4, z: 2.0 },
+  periodSeconds: 3.2,
+};
+
+export const PICKUP_START = { x: 4.4, y: 4.6, z: -3.0 };
+export const PICKUP_RESPAWNS = {
+  odd: { x: 1.4, y: 3.2, z: -0.8 },
+  even: { x: -3.2, y: 2.0, z: -2.4 },
+  triple: { x: 0, y: 3.0, z: -4.0 },
+};
+
+export const GOAL_ZONE = { x: 4.4, y: 4.8, z: -3.0, radius: 1.15 };

package/templates/create/3d/content/registries/.gitkeep

@@ -0,0 +1 @@
+

package/templates/create/3d/docs/design/.gitkeep

@@ -0,0 +1 @@
+

package/templates/create/3d/docs/design/loop.md

@@ -0,0 +1,5 @@
+# 3D Platformer Loop
+
+1. Traverse the course, hit checkpoints, collect pickups, and reach the goal.
+1. Keep authored route nouns in `content/gameplay/course.js`, checkpoint data in `content/gameplay/checkpoints.json`, and shared starter/runtime wiring in `src/runtime/`.
+1. If you add template-specific tuning beyond `game.config.json`, keep it in `config/gameplay/` instead of burying it in scene constants.

package/templates/create/3d/prefabs/checkpoint.prefab.js

@@ -0,0 +1,15 @@
+const checkpointPrefab = {
+  id: 'checkpoint',
+  kind: 'prefab',
+  role: 'world',
+  view: { kind: 'marker3d' },
+  components: {},
+  hooks: {},
+  notes: ['Attach VFX/material state here as platformer polish increases.'],
+};
+
+export function createCheckpointPrefab() {
+  return checkpointPrefab;
+}
+
+export default checkpointPrefab;

package/templates/create/3d/prefabs/player.prefab.js

@@ -0,0 +1,204 @@
+import {
+  activeCheckpoint,
+  createCharacterAvatar3D,
+  setAvatarVisual3D,
+} from '../src/starter-utils/index.js';
+import {
+  CAMERA_LOOK_OFFSET,
+  CAMERA_OFFSET,
+  JUMP_SPEED,
+  MOVE_SPEED,
+  PLAYER_HALF,
+} from '../content/gameplay/course.js';
+
+export const PLAYER_AVATAR_MODEL_PATH = 'assets/models/starter-avatar.gltf';
+
+const PLAYER_BODY_HEIGHT = PLAYER_HALF.y * 2;
+const PLAYER_RUN_SPEED = MOVE_SPEED * 1.35;
+const PLAYER_VISUAL_OFFSET = { x: 0, y: -PLAYER_HALF.y, z: 0 };
+const PLAYER_VISUAL_SCALE = { x: 1, y: 1, z: 1 };
+
+const playerPrefab = {
+  id: 'player',
+  kind: 'prefab',
+  role: 'player',
+  view: {
+    kind: 'avatar3d',
+    collider: { shape: 'capsule', size: { x: PLAYER_HALF.x * 2, y: PLAYER_BODY_HEIGHT, z: PLAYER_HALF.z * 2 } },
+    asset: { path: PLAYER_AVATAR_MODEL_PATH, clips: ['Idle', 'Walk', 'Run', 'Jump', 'Fall'] },
+  },
+  components: {
+    avatar: {
+      model: PLAYER_AVATAR_MODEL_PATH,
+      clips: ['Idle', 'Walk', 'Run', 'Jump', 'Fall'],
+    },
+  },
+  hooks: {
+    bindVisual: 'bindPlayerAvatarVisual',
+  },
+  notes: ['This starter keeps the player prefab avatar-first so the shipped 3D loop exercises imported animation immediately.'],
+};
+
+function normalizeImportedSceneRecord(entry) {
+  if (entry && entry.ok === true && Number.isInteger(entry.importId) && entry.importId > 0) {
+    return entry;
+  }
+  if (entry && Number.isInteger(entry.importId) && entry.importId > 0) {
+    return { ok: true, ...entry };
+  }
+  return null;
+}
+
+function resolveImportId(entry) {
+  if (Number.isInteger(entry) && entry > 0) return entry;
+  if (Number.isInteger(entry?.importId) && entry.importId > 0) return entry.importId;
+  return null;
+}
+
+function resolveRootSceneNodeId(record) {
+  if (!record || !Array.isArray(record.nodeHandles) || record.nodeHandles.length === 0) {
+    return null;
+  }
+
+  const rootSourceIndex = Array.isArray(record.rootSourceNodeIndices) && record.rootSourceNodeIndices.length > 0
+    ? Number(record.rootSourceNodeIndices[0])
+    : null;
+  if (Number.isInteger(rootSourceIndex) && rootSourceIndex >= 0) {
+    const match = record.nodeHandles.find((entry) => Number(entry?.sourceNodeIndex) === rootSourceIndex);
+    if (Number.isInteger(match?.nodeId) && match.nodeId > 0) {
+      return match.nodeId;
+    }
+  }
+
+  const first = record.nodeHandles.find((entry) => Number.isInteger(entry?.nodeId) && entry.nodeId > 0);
+  return Number.isInteger(first?.nodeId) ? first.nodeId : null;
+}
+
+function createPlayerClipMap(importId) {
+  return {
+    idle: { importId, animation: 'Idle', loop: true, transitionSeconds: 0.18 },
+    walk: { importId, animation: 'Walk', loop: true, transitionSeconds: 0.14 },
+    run: { importId, animation: 'Run', loop: true, transitionSeconds: 0.1 },
+    jump: { importId, animation: 'Jump', loop: false, transitionSeconds: 0.08 },
+    fall: { importId, animation: 'Fall', loop: true, transitionSeconds: 0.08 },
+  };
+}
+
+export function createPlayerAvatar(spawn) {
+  return createCharacterAvatar3D({
+    position: spawn,
+    radius: PLAYER_HALF.x,
+    height: PLAYER_BODY_HEIGHT,
+    moveSpeed: MOVE_SPEED,
+    runSpeed: PLAYER_RUN_SPEED,
+    jumpSpeed: JUMP_SPEED,
+    visual: {
+      offset: PLAYER_VISUAL_OFFSET,
+      scale: PLAYER_VISUAL_SCALE,
+    },
+    camera: {
+      offset: CAMERA_OFFSET,
+      lookOffset: CAMERA_LOOK_OFFSET,
+      rotateWithFacing: false,
+    },
+  });
+}
+
+export function resetPlayerAvatar(avatar, spawn) {
+  avatar.position = { x: spawn.x, y: spawn.y, z: spawn.z };
+  avatar.grounded = false;
+  avatar.onSlope = false;
+  avatar.velocityY = 0;
+  avatar.facingYaw = 0;
+  avatar.locomotion = 'idle';
+  avatar.motion = {
+    moveX: 0,
+    moveZ: 0,
+    magnitude: 0,
+    speed: 0,
+  };
+  avatar.input = {
+    moveX: 0,
+    moveZ: 0,
+    jump: false,
+    run: false,
+  };
+  avatar.visual.activeClipKey = null;
+  avatar.visual.activeClipId = null;
+  return avatar;
+}
+
+export function loadPlayerAvatarVisual() {
+  const loaded = aura.scene3d.loadGltfScene(PLAYER_AVATAR_MODEL_PATH, {
+    bindRenderNodes: true,
+    visible: true,
+    cull: false,
+  });
+  const importId = resolveImportId(loaded);
+  if (!importId) {
+    throw new Error(`[3d-platformer-template] failed to load starter avatar model: ${PLAYER_AVATAR_MODEL_PATH}`);
+  }
+
+  const record = normalizeImportedSceneRecord(loaded)
+    || normalizeImportedSceneRecord(aura.scene3d.getImportedScene(importId));
+  const sceneNodeId = resolveRootSceneNodeId(record);
+  if (!sceneNodeId) {
+    throw new Error('[3d-platformer-template] starter avatar model missing a bindable root scene node');
+  }
+
+  return {
+    importId,
+    path: PLAYER_AVATAR_MODEL_PATH,
+    sceneNodeId,
+  };
+}
+
+export function bindPlayerAvatarVisual(avatar, visual) {
+  return setAvatarVisual3D(avatar, {
+    sceneNodeId: visual.sceneNodeId,
+    offset: PLAYER_VISUAL_OFFSET,
+    scale: PLAYER_VISUAL_SCALE,
+    clipMap: createPlayerClipMap(visual.importId),
+  });
+}
+
+export function createPlayerPrefab() {
+  return playerPrefab;
+}
+
+export function drawPlatformerActors({ mesh, materials, state, goalZone }) {
+  aura.draw3d.drawMesh(mesh, materials.pickup, {
+    position: {
+      x: state.pickup.x,
+      y: state.pickup.y + (Math.sin(state.elapsed * 2.5) * 0.2),
+      z: state.pickup.z,
+    },
+    rotation: {
+      x: state.elapsed * 0.4,
+      y: state.elapsed * 1.5,
+      z: state.elapsed * 0.3,
+    },
+    scale: { x: 0.55, y: 0.55, z: 0.55 },
+  });
+
+  const checkpoint = activeCheckpoint(state.checkpointSystem);
+  if (checkpoint) {
+    aura.draw3d.drawMesh(mesh, materials.checkpoint, {
+      position: { x: checkpoint.x, y: checkpoint.y - 0.4, z: checkpoint.z },
+      rotation: { x: 0, y: state.elapsed * 0.7, z: 0 },
+      scale: { x: 0.45, y: 0.45, z: 0.45 },
+    });
+  }
+
+  aura.draw3d.drawMesh(mesh, materials.goal, {
+    position: { x: goalZone.x, y: goalZone.y, z: goalZone.z },
+    rotation: { x: 0, y: state.elapsed * 0.9, z: 0 },
+    scale: {
+      x: goalZone.radius * 1.2,
+      y: goalZone.radius * 1.2,
+      z: goalZone.radius * 1.2,
+    },
+  });
+}
+
+export default playerPrefab;

package/templates/create/3d/prefabs/world.prefab.js

@@ -0,0 +1,112 @@
+import { FLOOR_SCALE, STATIC_PLATFORMS } from '../content/gameplay/course.js';
+
+const worldPrefab = {
+  id: 'world',
+  kind: 'prefab',
+  role: 'world',
+  view: {
+    kind: 'environment3d',
+  },
+  hooks: {},
+  notes: ['Treat this as the authored course descriptor before you move to richer scene data.'],
+};
+
+export function createWorldPrefab() {
+  return {
+    ...worldPrefab,
+    platformCount: STATIC_PLATFORMS.length,
+  };
+}
+
+function addObstacleBox(platform) {
+  const halfX = platform.sx * 0.5;
+  const halfY = platform.sy * 0.5;
+  const halfZ = platform.sz * 0.5;
+  aura.character3d.addObstacle(
+    { x: platform.x - halfX, y: platform.y - halfY, z: platform.z - halfZ },
+    { x: platform.x + halfX, y: platform.y + halfY, z: platform.z + halfZ },
+  );
+}
+
+export function findSupportTop(x, z, movingPlatform) {
+  let top = 0;
+
+  const includePlatform = (platform) => {
+    const halfX = platform.sx * 0.5;
+    const halfZ = platform.sz * 0.5;
+    if (Math.abs(x - platform.x) > halfX || Math.abs(z - platform.z) > halfZ) return;
+    top = Math.max(top, platform.y + (platform.sy * 0.5));
+  };
+
+  for (const platform of STATIC_PLATFORMS) {
+    includePlatform(platform);
+  }
+
+  includePlatform({
+    x: movingPlatform.position.x,
+    y: movingPlatform.position.y,
+    z: movingPlatform.position.z,
+    sx: movingPlatform.size.x,
+    sy: movingPlatform.size.y,
+    sz: movingPlatform.size.z,
+  });
+
+  return top;
+}
+
+export function syncPlatformerCharacterObstacles(movingPlatform) {
+  if (typeof aura?.character3d?.clearObstacles !== 'function' || typeof aura?.character3d?.addObstacle !== 'function') {
+    return;
+  }
+
+  aura.character3d.clearObstacles();
+  aura.character3d.addObstacle(
+    { x: -FLOOR_SCALE.x * 0.5, y: -1.0, z: -FLOOR_SCALE.z * 0.5 },
+    { x: FLOOR_SCALE.x * 0.5, y: 0.0, z: FLOOR_SCALE.z * 0.5 },
+  );
+
+  for (const platform of STATIC_PLATFORMS) {
+    addObstacleBox(platform);
+  }
+
+  addObstacleBox({
+    x: movingPlatform.position.x,
+    y: movingPlatform.position.y,
+    z: movingPlatform.position.z,
+    sx: movingPlatform.size.x,
+    sy: movingPlatform.size.y,
+    sz: movingPlatform.size.z,
+  });
+}
+
+export function drawPlatformerCourse({ mesh, floorMaterial, platformMaterial, movingPlatform }) {
+  aura.draw3d.drawMesh(mesh, floorMaterial, {
+    position: { x: 0, y: -0.5, z: 0 },
+    rotation: { x: 0, y: 0, z: 0 },
+    scale: FLOOR_SCALE,
+  });
+
+  for (const platform of STATIC_PLATFORMS) {
+    aura.draw3d.drawMesh(mesh, platformMaterial, {
+      position: { x: platform.x, y: platform.y, z: platform.z },
+      rotation: { x: 0, y: 0, z: 0 },
+      scale: { x: platform.sx, y: platform.sy, z: platform.sz },
+    });
+  }
+
+  aura.draw3d.drawMesh(mesh, platformMaterial, {
+    position: {
+      x: movingPlatform.position.x,
+      y: movingPlatform.position.y,
+      z: movingPlatform.position.z,
+    },
+    rotation: { x: 0, y: 0, z: 0 },
+    scale: {
+      x: movingPlatform.size.x,
+      y: movingPlatform.size.y,
+      z: movingPlatform.size.z,
+    },
+  });
+}
+
+export default worldPrefab;

package/templates/create/3d/scenes/boot.scene.js

@@ -0,0 +1,12 @@
+export function createBootScene() {
+  return {
+    id: 'boot',
+    template: '3d-platformer',
+    nextSceneId: 'gameplay',
+    notes: [
+      'Use this scene for splash, loading, title flow, and session handoff.',
+      'Keep long-lived boot orchestration here instead of bloating src/main.js.',
+      'Keep checkpoint resume and route handoff in appState or scene data instead of ad hoc globals.',
+    ],
+  };
+}

package/templates/create/3d/scenes/checkpoint.scene.js

@@ -0,0 +1,9 @@
+export function createCheckpointScene() {
+  return {
+    id: "checkpoint",
+    nextSceneId: "gameplay",
+    notes: [
+  "Use this to stage checkpoint intros, tutorials, or route previews."
+],
+  };
+}