@auraindustry/aurajs 0.1.3 → 0.1.5

package/src/helpers/starter-utils/inventory-2d.js

@@ -0,0 +1,268 @@
+function normalizeId(value, fallback) {
+  if (typeof value === 'string' && value.trim().length > 0) {
+    return value.trim();
+  }
+  return fallback;
+}
+
+function normalizeLabel(value, fallback) {
+  if (typeof value === 'string' && value.trim().length > 0) {
+    return value.trim();
+  }
+  return fallback;
+}
+
+function normalizeQuantity(value, fallback = 1) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return Math.max(0, fallback);
+  return Math.max(0, Math.round(numeric));
+}
+
+function normalizeCategoryEntry(entry, index) {
+  const fallbackId = `category-${index + 1}`;
+  const id = normalizeId(entry?.id, fallbackId);
+  return {
+    id,
+    label: normalizeLabel(entry?.label ?? entry?.name, id),
+  };
+}
+
+function deriveMissingCategories(entries = [], items = []) {
+  const categories = Array.isArray(entries)
+    ? entries.map((entry, index) => normalizeCategoryEntry(entry, index))
+    : [];
+  const known = new Set(categories.map((entry) => entry.id));
+  for (const item of Array.isArray(items) ? items : []) {
+    const categoryId = normalizeId(item?.categoryId ?? item?.category, null);
+    if (!categoryId || known.has(categoryId)) continue;
+    categories.push({
+      id: categoryId,
+      label: normalizeLabel(item?.categoryLabel, categoryId),
+    });
+    known.add(categoryId);
+  }
+  return categories;
+}
+
+function normalizeItemEntry(entry, index, categories = []) {
+  const fallbackId = `item-${index + 1}`;
+  const id = normalizeId(entry?.id, fallbackId);
+  const categoryId = normalizeId(entry?.categoryId ?? entry?.category, categories[0]?.id || 'inventory');
+  return {
+    id,
+    label: normalizeLabel(entry?.label ?? entry?.name, id),
+    description: typeof entry?.description === 'string' ? entry.description : null,
+    detail: typeof entry?.detail === 'string' ? entry.detail : null,
+    badge: typeof entry?.badge === 'string' && entry.badge.trim().length > 0 ? entry.badge.trim() : null,
+    categoryId,
+    categoryLabel: normalizeLabel(entry?.categoryLabel, categoryId),
+    quantity: normalizeQuantity(entry?.quantity, 1),
+    equipped: entry?.equipped === true,
+    disabled: entry?.disabled === true,
+  };
+}
+
+function ensureCategory(inventory, categoryId, categoryLabel = null) {
+  if (!inventory || !Array.isArray(inventory.categories)) return null;
+  const existing = inventory.categories.find((entry) => entry.id === categoryId) || null;
+  if (existing) return existing;
+  const category = {
+    id: normalizeId(categoryId, `category-${inventory.categories.length + 1}`),
+    label: normalizeLabel(categoryLabel, categoryId),
+  };
+  inventory.categories.push(category);
+  return category;
+}
+
+function firstItemInCategory(inventory, categoryId = null) {
+  const items = listInventoryItems2D(inventory, categoryId);
+  return items[0] || null;
+}
+
+function activeCategoryId(inventory) {
+  if (!inventory || !Array.isArray(inventory.categories) || inventory.categories.length <= 0) return null;
+  if (inventory.selectedCategoryId && inventory.categories.some((entry) => entry.id === inventory.selectedCategoryId)) {
+    return inventory.selectedCategoryId;
+  }
+  return inventory.categories[0].id;
+}
+
+function touchInventory(inventory) {
+  if (!inventory || typeof inventory !== 'object') return;
+  inventory.revision = Number(inventory.revision || 0) + 1;
+}
+
+export function createInventory2D(options = {}) {
+  const categories = deriveMissingCategories(options.categories, options.items);
+  const inventory = {
+    categories,
+    items: [],
+    selectedCategoryId: categories[0]?.id || null,
+    selectedItemId: null,
+    revision: 0,
+  };
+
+  for (const [index, entry] of (Array.isArray(options.items) ? options.items : []).entries()) {
+    const item = normalizeItemEntry(entry, index, categories);
+    if (item.quantity <= 0) continue;
+    ensureCategory(inventory, item.categoryId, item.categoryLabel);
+    inventory.items.push(item);
+  }
+
+  if (typeof options.selectedCategoryId === 'string') {
+    selectInventoryCategory2D(inventory, options.selectedCategoryId);
+  }
+  if (typeof options.selectedItemId === 'string') {
+    selectInventoryItem2D(inventory, options.selectedItemId);
+  }
+  if (!inventory.selectedItemId) {
+    const first = firstItemInCategory(inventory, inventory.selectedCategoryId);
+    inventory.selectedItemId = first?.id || null;
+  }
+
+  return inventory;
+}
+
+export function addInventoryItem2D(inventory, entry, quantity = null) {
+  if (!inventory || !Array.isArray(inventory.items)) return null;
+  const item = normalizeItemEntry(entry, inventory.items.length, inventory.categories);
+  const delta = quantity == null ? item.quantity : normalizeQuantity(quantity, item.quantity);
+  if (delta <= 0) return null;
+
+  ensureCategory(inventory, item.categoryId, item.categoryLabel);
+  const existing = inventory.items.find((candidate) => candidate.id === item.id) || null;
+  if (existing) {
+    existing.label = item.label;
+    existing.description = item.description;
+    existing.detail = item.detail;
+    existing.badge = item.badge;
+    existing.categoryId = item.categoryId;
+    existing.categoryLabel = item.categoryLabel;
+    existing.equipped = item.equipped === true ? true : existing.equipped === true;
+    existing.disabled = item.disabled === true;
+    existing.quantity += delta;
+    touchInventory(inventory);
+    if (!inventory.selectedCategoryId) inventory.selectedCategoryId = existing.categoryId;
+    if (!inventory.selectedItemId) inventory.selectedItemId = existing.id;
+    return existing;
+  }
+
+  item.quantity = delta;
+  inventory.items.push(item);
+  if (!inventory.selectedCategoryId) inventory.selectedCategoryId = item.categoryId;
+  if (!inventory.selectedItemId) inventory.selectedItemId = item.id;
+  touchInventory(inventory);
+  return item;
+}
+
+export function removeInventoryItem2D(inventory, itemId, quantity = 1) {
+  if (!inventory || !Array.isArray(inventory.items)) return false;
+  const targetId = normalizeId(itemId, null);
+  if (!targetId) return false;
+  const index = inventory.items.findIndex((entry) => entry.id === targetId);
+  if (index < 0) return false;
+  const item = inventory.items[index];
+  const delta = normalizeQuantity(quantity, 1);
+  if (delta <= 0) return false;
+
+  item.quantity = Math.max(0, item.quantity - delta);
+  if (item.quantity <= 0) {
+    inventory.items.splice(index, 1);
+  }
+  if (inventory.selectedItemId === targetId) {
+    inventory.selectedItemId = firstItemInCategory(inventory, inventory.selectedCategoryId)?.id || null;
+  }
+  if (!inventory.selectedItemId) {
+    inventory.selectedCategoryId = activeCategoryId(inventory);
+    inventory.selectedItemId = firstItemInCategory(inventory, inventory.selectedCategoryId)?.id || null;
+  }
+  touchInventory(inventory);
+  return true;
+}
+
+export function hasInventoryItem2D(inventory, itemId, quantity = 1) {
+  if (!inventory || !Array.isArray(inventory.items)) return false;
+  const targetId = normalizeId(itemId, null);
+  if (!targetId) return false;
+  const item = inventory.items.find((entry) => entry.id === targetId) || null;
+  return Boolean(item) && item.quantity >= normalizeQuantity(quantity, 1);
+}
+
+export function listInventoryItems2D(inventory, categoryId = null) {
+  if (!inventory || !Array.isArray(inventory.items)) return [];
+  const targetCategory = normalizeId(categoryId, null) || activeCategoryId(inventory);
+  if (!targetCategory) return [...inventory.items];
+  return inventory.items.filter((entry) => entry.categoryId === targetCategory);
+}
+
+export function selectInventoryCategory2D(inventory, categoryId) {
+  if (!inventory || !Array.isArray(inventory.categories)) return null;
+  const targetId = normalizeId(categoryId, null);
+  if (!targetId || !inventory.categories.some((entry) => entry.id === targetId)) return inventory.selectedCategoryId || null;
+  inventory.selectedCategoryId = targetId;
+  const first = firstItemInCategory(inventory, targetId);
+  if (!first) {
+    inventory.selectedItemId = null;
+  } else if (!hasInventoryItem2D(inventory, inventory.selectedItemId)) {
+    inventory.selectedItemId = first.id;
+  } else if (!listInventoryItems2D(inventory, targetId).some((entry) => entry.id === inventory.selectedItemId)) {
+    inventory.selectedItemId = first.id;
+  }
+  touchInventory(inventory);
+  return inventory.selectedCategoryId;
+}
+
+export function selectInventoryItem2D(inventory, itemId) {
+  if (!inventory || !Array.isArray(inventory.items)) return null;
+  const targetId = normalizeId(itemId, null);
+  const item = inventory.items.find((entry) => entry.id === targetId) || null;
+  if (!item) return inventory.selectedItemId || null;
+  inventory.selectedCategoryId = item.categoryId;
+  inventory.selectedItemId = item.id;
+  touchInventory(inventory);
+  return inventory.selectedItemId;
+}
+
+export function getSelectedInventoryItem2D(inventory) {
+  if (!inventory || !Array.isArray(inventory.items)) return null;
+  return inventory.items.find((entry) => entry.id === inventory.selectedItemId) || null;
+}
+
+export function setInventoryItemEquipped2D(inventory, itemId, equipped = true) {
+  if (!inventory || !Array.isArray(inventory.items)) return false;
+  const targetId = normalizeId(itemId, null);
+  const item = inventory.items.find((entry) => entry.id === targetId) || null;
+  if (!item) return false;
+  item.equipped = equipped === true;
+  touchInventory(inventory);
+  return true;
+}
+
+export function getInventoryView2D(inventory) {
+  const categories = Array.isArray(inventory?.categories) ? inventory.categories : [];
+  const items = listInventoryItems2D(inventory);
+  const selectedItem = getSelectedInventoryItem2D(inventory);
+  return {
+    selectedCategoryId: activeCategoryId(inventory),
+    selectedItemId: selectedItem?.id || null,
+    categories: categories.map((entry) => ({
+      id: entry.id,
+      label: entry.label,
+      selected: entry.id === activeCategoryId(inventory),
+      count: listInventoryItems2D(inventory, entry.id).reduce((total, item) => total + item.quantity, 0),
+    })),
+    items: items.map((entry) => ({
+      id: entry.id,
+      label: entry.label,
+      description: entry.description,
+      detail: entry.detail,
+      badge: entry.badge,
+      quantity: entry.quantity,
+      equipped: entry.equipped === true,
+      selected: entry.id === selectedItem?.id,
+      disabled: entry.disabled === true,
+    })),
+    selectedItem,
+    revision: Number(inventory?.revision || 0),
+  };
+}

package/src/helpers/starter-utils/journal-2d.js

@@ -0,0 +1,267 @@
+function normalizeId(value, fallback) {
+  if (typeof value === 'string' && value.trim().length > 0) {
+    return value.trim();
+  }
+  return fallback;
+}
+
+function normalizeLabel(value, fallback) {
+  if (typeof value === 'string' && value.trim().length > 0) {
+    return value.trim();
+  }
+  return fallback;
+}
+
+function normalizeStatus(value, fallback = 'active') {
+  switch (String(value || '').trim()) {
+    case 'active':
+    case 'completed':
+    case 'archived':
+    case 'optional':
+      return String(value).trim();
+    default:
+      return fallback;
+  }
+}
+
+function normalizeCategoryEntry(entry, index) {
+  const fallbackId = `category-${index + 1}`;
+  const id = normalizeId(entry?.id, fallbackId);
+  return {
+    id,
+    label: normalizeLabel(entry?.label ?? entry?.name, id),
+  };
+}
+
+function deriveMissingCategories(entries = [], journalEntries = []) {
+  const categories = Array.isArray(entries)
+    ? entries.map((entry, index) => normalizeCategoryEntry(entry, index))
+    : [];
+  const known = new Set(categories.map((entry) => entry.id));
+  for (const entry of Array.isArray(journalEntries) ? journalEntries : []) {
+    const categoryId = normalizeId(entry?.categoryId ?? entry?.category, null);
+    if (!categoryId || known.has(categoryId)) continue;
+    categories.push({
+      id: categoryId,
+      label: normalizeLabel(entry?.categoryLabel, categoryId),
+    });
+    known.add(categoryId);
+  }
+  return categories;
+}
+
+function normalizeJournalEntry(entry, index, categories = []) {
+  const fallbackId = `entry-${index + 1}`;
+  const id = normalizeId(entry?.id, fallbackId);
+  const categoryId = normalizeId(entry?.categoryId ?? entry?.category, categories[0]?.id || 'journal');
+  const status = normalizeStatus(entry?.status, entry?.completed === true ? 'completed' : 'active');
+  return {
+    id,
+    label: normalizeLabel(entry?.label ?? entry?.title ?? entry?.name, id),
+    description: typeof entry?.description === 'string'
+      ? entry.description
+      : (typeof entry?.summary === 'string' ? entry.summary : null),
+    detail: typeof entry?.detail === 'string'
+      ? entry.detail
+      : (typeof entry?.body === 'string' ? entry.body : null),
+    badge: typeof entry?.badge === 'string' && entry.badge.trim().length > 0
+      ? entry.badge.trim()
+      : null,
+    categoryId,
+    categoryLabel: normalizeLabel(entry?.categoryLabel, categoryId),
+    status,
+    active: status === 'active',
+    completed: status === 'completed',
+    optional: status === 'optional',
+    archived: status === 'archived',
+    disabled: entry?.disabled === true,
+    meta: typeof entry?.meta === 'string' && entry.meta.trim().length > 0
+      ? entry.meta.trim()
+      : (typeof entry?.updatedAt === 'string' && entry.updatedAt.trim().length > 0
+        ? entry.updatedAt.trim()
+        : null),
+  };
+}
+
+function ensureCategory(journal, categoryId, categoryLabel = null) {
+  if (!journal || !Array.isArray(journal.categories)) return null;
+  const existing = journal.categories.find((entry) => entry.id === categoryId) || null;
+  if (existing) return existing;
+  const category = {
+    id: normalizeId(categoryId, `category-${journal.categories.length + 1}`),
+    label: normalizeLabel(categoryLabel, categoryId),
+  };
+  journal.categories.push(category);
+  return category;
+}
+
+function activeCategoryId(journal) {
+  if (!journal || !Array.isArray(journal.categories) || journal.categories.length <= 0) return null;
+  if (journal.selectedCategoryId && journal.categories.some((entry) => entry.id === journal.selectedCategoryId)) {
+    return journal.selectedCategoryId;
+  }
+  return journal.categories[0].id;
+}
+
+function firstEntryInCategory(journal, categoryId = null) {
+  const entries = listJournalEntries2D(journal, categoryId);
+  return entries[0] || null;
+}
+
+function touchJournal(journal) {
+  if (!journal || typeof journal !== 'object') return;
+  journal.revision = Number(journal.revision || 0) + 1;
+}
+
+export function createJournal2D(options = {}) {
+  const categories = deriveMissingCategories(options.categories, options.entries);
+  const journal = {
+    categories,
+    entries: [],
+    selectedCategoryId: categories[0]?.id || null,
+    selectedEntryId: null,
+    revision: 0,
+  };
+
+  for (const [index, entry] of (Array.isArray(options.entries) ? options.entries : []).entries()) {
+    const normalized = normalizeJournalEntry(entry, index, categories);
+    ensureCategory(journal, normalized.categoryId, normalized.categoryLabel);
+    journal.entries.push(normalized);
+  }
+
+  if (typeof options.selectedCategoryId === 'string') {
+    selectJournalCategory2D(journal, options.selectedCategoryId);
+  }
+  if (typeof options.selectedEntryId === 'string') {
+    selectJournalEntry2D(journal, options.selectedEntryId);
+  }
+  if (!journal.selectedEntryId) {
+    const first = firstEntryInCategory(journal, journal.selectedCategoryId);
+    journal.selectedEntryId = first?.id || null;
+  }
+
+  return journal;
+}
+
+export function upsertJournalEntry2D(journal, entry) {
+  if (!journal || !Array.isArray(journal.entries)) return null;
+  const normalized = normalizeJournalEntry(entry, journal.entries.length, journal.categories);
+  ensureCategory(journal, normalized.categoryId, normalized.categoryLabel);
+
+  const existing = journal.entries.find((candidate) => candidate.id === normalized.id) || null;
+  if (existing) {
+    Object.assign(existing, normalized);
+    touchJournal(journal);
+    if (!journal.selectedCategoryId) journal.selectedCategoryId = existing.categoryId;
+    if (!journal.selectedEntryId) journal.selectedEntryId = existing.id;
+    return existing;
+  }
+
+  journal.entries.push(normalized);
+  if (!journal.selectedCategoryId) journal.selectedCategoryId = normalized.categoryId;
+  if (!journal.selectedEntryId) journal.selectedEntryId = normalized.id;
+  touchJournal(journal);
+  return normalized;
+}
+
+export function setJournalEntryStatus2D(journal, entryId, status, updates = {}) {
+  if (!journal || !Array.isArray(journal.entries)) return false;
+  const targetId = normalizeId(entryId, null);
+  const entry = journal.entries.find((candidate) => candidate.id === targetId) || null;
+  if (!entry) return false;
+  const nextStatus = normalizeStatus(status, entry.status);
+  entry.status = nextStatus;
+  entry.active = nextStatus === 'active';
+  entry.completed = nextStatus === 'completed';
+  entry.optional = nextStatus === 'optional';
+  entry.archived = nextStatus === 'archived';
+  if (typeof updates.badge === 'string') {
+    entry.badge = updates.badge.trim().length > 0 ? updates.badge.trim() : null;
+  }
+  if (typeof updates.meta === 'string') {
+    entry.meta = updates.meta.trim().length > 0 ? updates.meta.trim() : null;
+  }
+  if (typeof updates.description === 'string') {
+    entry.description = updates.description;
+  }
+  if (typeof updates.detail === 'string') {
+    entry.detail = updates.detail;
+  }
+  touchJournal(journal);
+  return true;
+}
+
+export function listJournalEntries2D(journal, categoryId = null, options = {}) {
+  if (!journal || !Array.isArray(journal.entries)) return [];
+  const targetCategory = normalizeId(categoryId, null) || activeCategoryId(journal);
+  const statusFilter = normalizeId(options.status, null);
+  return journal.entries.filter((entry) => {
+    if (targetCategory && entry.categoryId !== targetCategory) return false;
+    if (statusFilter && entry.status !== statusFilter) return false;
+    return true;
+  });
+}
+
+export function selectJournalCategory2D(journal, categoryId) {
+  if (!journal || !Array.isArray(journal.categories)) return null;
+  const targetId = normalizeId(categoryId, null);
+  if (!targetId || !journal.categories.some((entry) => entry.id === targetId)) {
+    return journal.selectedCategoryId || null;
+  }
+  journal.selectedCategoryId = targetId;
+  const first = firstEntryInCategory(journal, targetId);
+  if (!first) {
+    journal.selectedEntryId = null;
+  } else if (!journal.entries.some((entry) => entry.id === journal.selectedEntryId && entry.categoryId === targetId)) {
+    journal.selectedEntryId = first.id;
+  }
+  touchJournal(journal);
+  return journal.selectedCategoryId;
+}
+
+export function selectJournalEntry2D(journal, entryId) {
+  if (!journal || !Array.isArray(journal.entries)) return null;
+  const targetId = normalizeId(entryId, null);
+  const entry = journal.entries.find((candidate) => candidate.id === targetId) || null;
+  if (!entry) return journal.selectedEntryId || null;
+  journal.selectedCategoryId = entry.categoryId;
+  journal.selectedEntryId = entry.id;
+  touchJournal(journal);
+  return journal.selectedEntryId;
+}
+
+export function getSelectedJournalEntry2D(journal) {
+  if (!journal || !Array.isArray(journal.entries)) return null;
+  return journal.entries.find((entry) => entry.id === journal.selectedEntryId) || null;
+}
+
+export function getJournalView2D(journal) {
+  const categories = Array.isArray(journal?.categories) ? journal.categories : [];
+  const entries = listJournalEntries2D(journal);
+  const selectedEntry = getSelectedJournalEntry2D(journal);
+  return {
+    selectedCategoryId: activeCategoryId(journal),
+    selectedEntryId: selectedEntry?.id || null,
+    categories: categories.map((entry) => ({
+      id: entry.id,
+      label: entry.label,
+      selected: entry.id === activeCategoryId(journal),
+      count: listJournalEntries2D(journal, entry.id).length,
+      activeCount: listJournalEntries2D(journal, entry.id, { status: 'active' }).length,
+      completedCount: listJournalEntries2D(journal, entry.id, { status: 'completed' }).length,
+    })),
+    entries: entries.map((entry) => ({
+      id: entry.id,
+      label: entry.label,
+      description: entry.description,
+      detail: entry.detail,
+      badge: entry.badge || (entry.completed ? 'Completed' : entry.active ? 'Active' : normalizeLabel(entry.status, 'Journal')),
+      status: entry.status,
+      selected: entry.id === selectedEntry?.id,
+      disabled: entry.disabled === true,
+      meta: entry.meta,
+    })),
+    selectedEntry,
+    revision: Number(journal?.revision || 0),
+  };
+}

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

@@ -0,0 +1,132 @@
+import { clamp, distanceSquared3D } from './core.js';
+
+function resolveRespawnTarget(body) {
+  if (body && typeof body === 'object' && body.position && typeof body.position === 'object') {
+    return body.position;
+  }
+  return body;
+}
+
+export function createCheckpointSystem(options = {}) {
+  const checkpoints = Array.isArray(options.checkpoints)
+    ? options.checkpoints.map((entry) => ({
+      x: Number(entry?.x) || 0,
+      y: Number(entry?.y) || 0,
+      z: Number(entry?.z) || 0,
+      radius: Math.max(0.2, Number(entry?.radius) || 1.25),
+    }))
+    : [];
+
+  return {
+    checkpoints,
+    activeIndex: checkpoints.length > 0 ? 0 : -1,
+  };
+}
+
+export function updateCheckpointProgress(system, player) {
+  if (!system || system.activeIndex < 0) return false;
+  const nextIndex = Math.min(system.activeIndex + 1, system.checkpoints.length - 1);
+  const next = system.checkpoints[nextIndex];
+  if (!next) return false;
+
+  const reached = distanceSquared3D(player, next) <= (next.radius * next.radius);
+  if (!reached) return false;
+
+  system.activeIndex = nextIndex;
+  return true;
+}
+
+export function activeCheckpoint(system) {
+  if (!system || system.activeIndex < 0) return null;
+  return system.checkpoints[system.activeIndex] || null;
+}
+
+export function respawnAtCheckpoint(system, body) {
+  const checkpoint = activeCheckpoint(system);
+  if (!checkpoint) return false;
+
+  const target = resolveRespawnTarget(body);
+  if (!target || typeof target !== 'object') return false;
+
+  target.x = checkpoint.x;
+  target.y = checkpoint.y;
+  target.z = checkpoint.z;
+
+  if (body && typeof body === 'object' && body !== target) {
+    body.velocityY = 0;
+    body.grounded = false;
+    body.onSlope = false;
+    body.locomotion = 'idle';
+    body.motion = {
+      moveX: 0,
+      moveZ: 0,
+      magnitude: 0,
+      speed: 0,
+    };
+    body.input = {
+      moveX: 0,
+      moveZ: 0,
+      jump: false,
+      run: false,
+    };
+    return true;
+  }
+
+  body.vy = 0;
+  body.onGround = false;
+  return true;
+}
+
+export function createGoalZone(options = {}) {
+  return {
+    x: Number(options.x) || 0,
+    y: Number(options.y) || 0,
+    z: Number(options.z) || 0,
+    radius: Math.max(0.2, Number(options.radius) || 1.1),
+  };
+}
+
+export function isGoalReached(goalZone, player) {
+  if (!goalZone) return false;
+  return distanceSquared3D(goalZone, player) <= (goalZone.radius * goalZone.radius);
+}
+
+export function createMovingPlatform3D(options = {}) {
+  const from = {
+    x: Number(options?.from?.x) || 0,
+    y: Number(options?.from?.y) || 0,
+    z: Number(options?.from?.z) || 0,
+  };
+  const to = {
+    x: Number(options?.to?.x) || from.x,
+    y: Number(options?.to?.y) || from.y,
+    z: Number(options?.to?.z) || from.z,
+  };
+
+  return {
+    from,
+    to,
+    size: {
+      x: Math.max(0.1, Number(options?.size?.x) || 2.4),
+      y: Math.max(0.1, Number(options?.size?.y) || 0.4),
+      z: Math.max(0.1, Number(options?.size?.z) || 2.0),
+    },
+    periodSeconds: Math.max(0.2, Number(options.periodSeconds) || 2.8),
+    t: 0,
+    position: { ...from },
+  };
+}
+
+export function stepMovingPlatform3D(platform, dt) {
+  const frameDt = Math.max(0, Number(dt) || 0);
+  platform.t += frameDt;
+
+  const cycle = (platform.t / platform.periodSeconds) * Math.PI * 2;
+  const pingPong = (Math.sin(cycle) * 0.5) + 0.5;
+  const alpha = clamp(pingPong, 0, 1);
+
+  platform.position.x = platform.from.x + ((platform.to.x - platform.from.x) * alpha);
+  platform.position.y = platform.from.y + ((platform.to.y - platform.from.y) * alpha);
+  platform.position.z = platform.from.z + ((platform.to.z - platform.from.z) * alpha);
+  return platform.position;
+}