@auraindustry/aurajs 0.1.3 → 0.1.5

package/templates/create/shared/src/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/templates/create/shared/src/starter-utils/scene-audio-2d.js

@@ -0,0 +1,236 @@
+function finiteNumber(value, fallback) {
+  const numeric = Number(value)
+  return Number.isFinite(numeric) ? numeric : fallback
+}
+
+function nonNegativeNumber(value, fallback) {
+  return Math.max(0, finiteNumber(value, fallback))
+}
+
+function hasAudioMethod(sceneAudio, name) {
+  return !!sceneAudio?.aura?.audio
+    && sceneAudio.aura.audio.supported !== false
+    && typeof sceneAudio.aura.audio[name] === 'function'
+}
+
+function mixerTracksHandle(sceneAudio, handle) {
+  if (handle == null || !hasAudioMethod(sceneAudio, 'getMixerState')) {
+    return true
+  }
+  try {
+    const mixer = sceneAudio.aura.audio.getMixerState()
+    return Array.isArray(mixer?.tracks)
+      ? mixer.tracks.some((track) => Number(track?.handle) === Number(handle))
+      : true
+  } catch {
+    return true
+  }
+}
+
+export function createSceneAudio2D(aura, options = {}) {
+  return {
+    aura,
+    configured: false,
+    musicHandle: null,
+    musicPath: '',
+    musicBus: typeof options.musicBus === 'string' && options.musicBus.trim().length > 0
+      ? options.musicBus.trim()
+      : 'music',
+    sfxBus: typeof options.sfxBus === 'string' && options.sfxBus.trim().length > 0
+      ? options.sfxBus.trim()
+      : 'sfx',
+    busVolumes: {
+      music: nonNegativeNumber(options.musicBusVolume, 0.18),
+      sfx: nonNegativeNumber(options.sfxBusVolume, 0.82),
+    },
+    defaultMusicOptions: {
+      volume: nonNegativeNumber(options.defaultMusicOptions?.volume, 0.58),
+      pitch: finiteNumber(options.defaultMusicOptions?.pitch, 0.98),
+    },
+    defaultStingerOptions: {
+      volume: nonNegativeNumber(options.defaultStingerOptions?.volume, 0.84),
+      pitch: finiteNumber(options.defaultStingerOptions?.pitch, 1),
+    },
+    musicVolume: -1,
+    pauseVolume: nonNegativeNumber(options.pauseVolume, 0.08),
+    paused: false,
+    duckTimer: 0,
+    duckVolume: null,
+  }
+}
+
+export function configureSceneAudio2D(sceneAudio) {
+  if (!sceneAudio || sceneAudio.configured || !sceneAudio.aura?.audio) {
+    return !!sceneAudio?.aura?.audio
+  }
+  sceneAudio.configured = true
+  if (hasAudioMethod(sceneAudio, 'setBusVolume')) {
+    try {
+      sceneAudio.aura.audio.setBusVolume(sceneAudio.musicBus, sceneAudio.busVolumes.music)
+    } catch {}
+    try {
+      sceneAudio.aura.audio.setBusVolume(sceneAudio.sfxBus, sceneAudio.busVolumes.sfx)
+    } catch {}
+  }
+  return true
+}
+
+export function setSceneMusicVolume2D(sceneAudio, volume) {
+  if (!sceneAudio || !hasAudioMethod(sceneAudio, 'setBusVolume')) {
+    return
+  }
+  const resolvedVolume = nonNegativeNumber(volume, sceneAudio.busVolumes.music)
+  if (Math.abs(sceneAudio.musicVolume - resolvedVolume) <= 0.01) {
+    return
+  }
+  sceneAudio.musicVolume = resolvedVolume
+  try {
+    sceneAudio.aura.audio.setBusVolume(sceneAudio.musicBus, resolvedVolume)
+  } catch {}
+}
+
+export function stopSceneAudio2D(sceneAudio, options = {}) {
+  if (!sceneAudio) {
+    return
+  }
+  if (sceneAudio.musicHandle != null && hasAudioMethod(sceneAudio, 'stop')) {
+    try {
+      sceneAudio.aura.audio.stop(sceneAudio.musicHandle)
+    } catch {}
+  }
+  sceneAudio.musicHandle = null
+  sceneAudio.musicPath = ''
+  sceneAudio.duckTimer = 0
+  sceneAudio.duckVolume = null
+  if (options.clearPause !== false) {
+    sceneAudio.paused = false
+  }
+  if (options.resetConfiguration === true) {
+    sceneAudio.musicVolume = -1
+    sceneAudio.configured = false
+  }
+}
+
+export function ensureSceneMusic2D(sceneAudio, path, options = {}) {
+  configureSceneAudio2D(sceneAudio)
+  if (!sceneAudio || typeof path !== 'string' || path.trim().length === 0 || !hasAudioMethod(sceneAudio, 'play')) {
+    return null
+  }
+  const resolvedPath = path.trim()
+  if (
+    sceneAudio.musicHandle != null
+    && sceneAudio.musicPath === resolvedPath
+    && mixerTracksHandle(sceneAudio, sceneAudio.musicHandle)
+  ) {
+    return sceneAudio.musicHandle
+  }
+  stopSceneAudio2D(sceneAudio, {
+    clearPause: false,
+    resetConfiguration: false,
+  })
+  try {
+    sceneAudio.musicHandle = sceneAudio.aura.audio.play(resolvedPath, {
+      loop: true,
+      bus: sceneAudio.musicBus,
+      ...sceneAudio.defaultMusicOptions,
+      ...options,
+    })
+    sceneAudio.musicPath = resolvedPath
+  } catch {}
+  return sceneAudio.musicHandle
+}
+
+export function duckSceneMusic2D(sceneAudio, options = {}) {
+  if (!sceneAudio) {
+    return
+  }
+  const duration = nonNegativeNumber(options.duration, 0.16)
+  const volume = nonNegativeNumber(options.volume, 0.14)
+  sceneAudio.duckTimer = Math.max(sceneAudio.duckTimer, duration)
+  sceneAudio.duckVolume = sceneAudio.duckVolume == null
+    ? volume
+    : Math.min(sceneAudio.duckVolume, volume)
+}
+
+export function playSceneStinger2D(sceneAudio, path, options = {}) {
+  configureSceneAudio2D(sceneAudio)
+  if (!sceneAudio || typeof path !== 'string' || path.trim().length === 0 || !hasAudioMethod(sceneAudio, 'play')) {
+    return null
+  }
+  const resolvedPath = path.trim()
+  const playOptions = {
+    loop: false,
+    bus: sceneAudio.sfxBus,
+    ...sceneAudio.defaultStingerOptions,
+    ...options,
+  }
+  delete playOptions.duck
+  let handle = null
+  try {
+    handle = sceneAudio.aura.audio.play(resolvedPath, playOptions)
+  } catch {}
+  if (options.duck) {
+    duckSceneMusic2D(sceneAudio, options.duck === true ? {} : options.duck)
+  }
+  return handle
+}
+
+export function pauseSceneAudio2D(sceneAudio, options = {}) {
+  if (!sceneAudio) {
+    return
+  }
+  sceneAudio.paused = true
+  sceneAudio.pauseVolume = nonNegativeNumber(options.volume, sceneAudio.pauseVolume)
+  if (options.pauseMusic !== false && sceneAudio.musicHandle != null && hasAudioMethod(sceneAudio, 'pause')) {
+    try {
+      sceneAudio.aura.audio.pause(sceneAudio.musicHandle)
+    } catch {}
+  }
+}
+
+export function resumeSceneAudio2D(sceneAudio, options = {}) {
+  if (!sceneAudio) {
+    return
+  }
+  sceneAudio.paused = false
+  if (options.resumeMusic !== false && sceneAudio.musicHandle != null && hasAudioMethod(sceneAudio, 'resume')) {
+    try {
+      sceneAudio.aura.audio.resume(sceneAudio.musicHandle)
+    } catch {}
+  }
+}
+
+export function syncSceneAudio2D(sceneAudio, dt, options = {}) {
+  configureSceneAudio2D(sceneAudio)
+  if (!sceneAudio) {
+    return null
+  }
+  const safeDt = nonNegativeNumber(dt, 0)
+  if (hasAudioMethod(sceneAudio, 'update')) {
+    try {
+      sceneAudio.aura.audio.update(safeDt)
+    } catch {}
+  }
+  if (typeof options.musicPath === 'string' && options.musicPath.trim().length > 0) {
+    ensureSceneMusic2D(sceneAudio, options.musicPath, options.musicOptions)
+  }
+
+  if (sceneAudio.duckTimer > 0) {
+    sceneAudio.duckTimer = Math.max(0, sceneAudio.duckTimer - safeDt)
+    if (sceneAudio.duckTimer <= 0) {
+      sceneAudio.duckVolume = null
+    }
+  }
+
+  let targetVolume = options.musicVolume != null
+    ? nonNegativeNumber(options.musicVolume, sceneAudio.busVolumes.music)
+    : sceneAudio.busVolumes.music
+  if (sceneAudio.paused) {
+    targetVolume = Math.min(targetVolume, sceneAudio.pauseVolume)
+  }
+  if (sceneAudio.duckTimer > 0 && sceneAudio.duckVolume != null) {
+    targetVolume = Math.min(targetVolume, sceneAudio.duckVolume)
+  }
+  setSceneMusicVolume2D(sceneAudio, targetVolume)
+  return sceneAudio.musicHandle
+}