@auraindustry/aurajs 0.1.1 → 0.1.5

package/src/helpers/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
+}

package/src/helpers/starter-utils/streamed-world-2d.js

@@ -0,0 +1,378 @@
+import {
+  createTilemapWorld2D,
+  ensureTilemapWorldLoaded2D,
+  unloadTilemapWorld2D,
+  queryTilemapWorldPoint2D,
+  queryTilemapWorldAABB2D,
+} from './tilemap-world-2d.js';
+
+function finite(value, fallback = 0) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : fallback;
+}
+
+function normalizeText(value, fallback = null) {
+  if (typeof value === 'string' && value.trim().length > 0) {
+    return value.trim();
+  }
+  return fallback;
+}
+
+function resolveAura(auraRef = globalThis.aura) {
+  return auraRef && typeof auraRef === 'object' ? auraRef : null;
+}
+
+function cloneBounds(bounds = {}) {
+  return {
+    x: finite(bounds.x),
+    y: finite(bounds.y),
+    w: Math.max(0, finite(bounds.w ?? bounds.width)),
+    h: Math.max(0, finite(bounds.h ?? bounds.height)),
+  };
+}
+
+function boundsEmpty(bounds) {
+  return !bounds || bounds.w <= 0 || bounds.h <= 0;
+}
+
+function pointInBounds(bounds, point = {}) {
+  if (boundsEmpty(bounds)) return false;
+  const x = finite(point.x, Number.NaN);
+  const y = finite(point.y, Number.NaN);
+  if (!Number.isFinite(x) || !Number.isFinite(y)) return false;
+  return x >= bounds.x
+    && y >= bounds.y
+    && x < (bounds.x + bounds.w)
+    && y < (bounds.y + bounds.h);
+}
+
+function boundsIntersect(a, b) {
+  if (boundsEmpty(a) || boundsEmpty(b)) return false;
+  return a.x < (b.x + b.w)
+    && (a.x + a.w) > b.x
+    && a.y < (b.y + b.h)
+    && (a.y + a.h) > b.y;
+}
+
+function focusBounds(point = {}, marginX = 0, marginY = marginX) {
+  const x = finite(point.x);
+  const y = finite(point.y);
+  const w = Math.max(0, finite(marginX)) * 2;
+  const h = Math.max(0, finite(marginY)) * 2;
+  return {
+    x: x - (w * 0.5),
+    y: y - (h * 0.5),
+    w,
+    h,
+  };
+}
+
+function normalizeRegion(entry, index) {
+  if (!entry || typeof entry !== 'object') return null;
+  const bounds = cloneBounds(entry.bounds ?? entry);
+  if (bounds.w <= 0 || bounds.h <= 0) return null;
+  return {
+    id: normalizeText(entry.id, `region-${index + 1}`),
+    label: normalizeText(entry.label, normalizeText(entry.id, `Region ${index + 1}`)),
+    order: Number.isFinite(Number(entry.order)) ? Number(entry.order) : index,
+    bounds,
+    meta: entry.meta && typeof entry.meta === 'object' ? { ...entry.meta } : null,
+    build: typeof entry.build === 'function' ? entry.build : null,
+  };
+}
+
+function sortRegions(entries = []) {
+  return [...entries].sort((a, b) => {
+    return a.order - b.order
+      || a.bounds.y - b.bounds.y
+      || a.bounds.x - b.bounds.x
+      || a.id.localeCompare(b.id);
+  });
+}
+
+function normalizeQueryHit(hit, record) {
+  if (!hit || typeof hit !== 'object') return hit;
+  return {
+    ...hit,
+    localX: finite(hit.x),
+    localY: finite(hit.y),
+    x: finite(hit.x) + finite(record.state?.tileLeft),
+    y: finite(hit.y) + finite(record.state?.tileTop),
+    regionId: record.id,
+    regionLabel: record.label,
+    worldTileX: finite(hit.x) + finite(record.state?.tileLeft),
+    worldTileY: finite(hit.y) + finite(record.state?.tileTop),
+  };
+}
+
+function normalizeRayResult(result, record) {
+  if (!result || typeof result !== 'object') return null;
+  if (result.hit !== true) {
+    return {
+      ...result,
+      regionId: record.id,
+      regionLabel: record.label,
+    };
+  }
+  const point = result.point && typeof result.point === 'object'
+    ? {
+      x: finite(result.point.x) + finite(record.world.offsetX),
+      y: finite(result.point.y) + finite(record.world.offsetY),
+    }
+    : null;
+  const hitCell = result.hitCell && typeof result.hitCell === 'object'
+    ? {
+      ...result.hitCell,
+      localX: finite(result.hitCell.x),
+      localY: finite(result.hitCell.y),
+      x: finite(result.hitCell.x) + finite(record.state?.tileLeft),
+      y: finite(result.hitCell.y) + finite(record.state?.tileTop),
+      regionId: record.id,
+      regionLabel: record.label,
+      worldTileX: finite(result.hitCell.x) + finite(record.state?.tileLeft),
+      worldTileY: finite(result.hitCell.y) + finite(record.state?.tileTop),
+    }
+    : null;
+  return {
+    ...result,
+    regionId: record.id,
+    regionLabel: record.label,
+    point,
+    hitCell,
+    hits: Array.isArray(result.hits) ? result.hits.map((hit) => normalizeQueryHit(hit, record)) : [],
+  };
+}
+
+function createLoadedRecord(stream, descriptor, built) {
+  const world = built?.world ?? createTilemapWorld2D({
+    mapSource: built?.mapSource ?? null,
+    offsetX: descriptor.bounds.x,
+    offsetY: descriptor.bounds.y,
+    cull: built?.cull,
+    includeHidden: built?.includeHidden,
+  });
+  return {
+    id: descriptor.id,
+    label: descriptor.label,
+    order: descriptor.order,
+    descriptor,
+    bounds: descriptor.bounds,
+    world,
+    nav: built?.nav ?? built?.state?.nav ?? null,
+    state: built?.state ?? null,
+    anchors: built?.anchors ?? null,
+    lastTouchedSync: stream.syncCount,
+  };
+}
+
+function ensureRegionLoaded(stream, descriptor, auraRef = globalThis.aura) {
+  if (!stream || !descriptor) return null;
+  const existing = stream.loaded.get(descriptor.id);
+  if (existing) {
+    existing.lastTouchedSync = stream.syncCount;
+    ensureTilemapWorldLoaded2D(existing.world, auraRef);
+    return existing;
+  }
+  const built = typeof descriptor.build === 'function'
+    ? descriptor.build(descriptor, stream) || null
+    : (typeof stream.buildRegion === 'function' ? stream.buildRegion(descriptor, stream) || null : null);
+  const record = createLoadedRecord(stream, descriptor, built);
+  ensureTilemapWorldLoaded2D(record.world, auraRef);
+  stream.loaded.set(record.id, record);
+  return record;
+}
+
+function loadedRecordsForBounds(stream, bounds) {
+  return listLoadedStreamedWorldRegions2D(stream).filter((record) => boundsIntersect(record.bounds, bounds));
+}
+
+function pickActiveRegion(stream, point = {}) {
+  return findStreamedWorldRegionAtPoint2D(stream, point, { loadedOnly: false });
+}
+
+export function createStreamedWorld2D(options = {}) {
+  const regions = sortRegions((Array.isArray(options.regions) ? options.regions : [])
+    .map((entry, index) => normalizeRegion(entry, index))
+    .filter(Boolean));
+  return {
+    regions,
+    regionById: new Map(regions.map((entry) => [entry.id, entry])),
+    buildRegion: typeof options.buildRegion === 'function' ? options.buildRegion : null,
+    focusMarginX: Math.max(0, finite(options.focusMarginX ?? options.focusMargin ?? 0)),
+    focusMarginY: Math.max(0, finite(options.focusMarginY ?? options.focusMargin ?? 0)),
+    unloadMarginX: Math.max(0, finite(options.unloadMarginX ?? options.unloadMargin ?? options.focusMarginX ?? options.focusMargin ?? 0)),
+    unloadMarginY: Math.max(0, finite(options.unloadMarginY ?? options.unloadMargin ?? options.focusMarginY ?? options.focusMargin ?? 0)),
+    loaded: new Map(),
+    focus: null,
+    activeRegionId: null,
+    syncCount: 0,
+    lastSync: null,
+  };
+}
+
+export function listLoadedStreamedWorldRegions2D(stream) {
+  if (!stream || !(stream.loaded instanceof Map)) return [];
+  return sortRegions([...stream.loaded.values()]);
+}
+
+export function findStreamedWorldRegionAtPoint2D(stream, point = {}, options = {}) {
+  if (!stream) return null;
+  const entries = options.loadedOnly === false
+    ? stream.regions
+    : listLoadedStreamedWorldRegions2D(stream);
+  return entries.find((entry) => pointInBounds(entry.bounds, point)) || null;
+}
+
+export function syncStreamedWorldFocus2D(stream, auraRef = globalThis.aura, point = {}) {
+  if (!stream || !Array.isArray(stream.regions) || stream.regions.length === 0) {
+    return {
+      activeRegionId: null,
+      activeRegion: null,
+      enteredRegionIds: [],
+      exitedRegionIds: [],
+      loadedRegionIds: [],
+    };
+  }
+
+  const aura = resolveAura(auraRef);
+  stream.syncCount += 1;
+  stream.focus = { x: finite(point.x), y: finite(point.y) };
+
+  const activeDescriptor = pickActiveRegion(stream, stream.focus);
+  const activeRegionId = activeDescriptor?.id ?? null;
+  const activeBounds = focusBounds(stream.focus, stream.focusMarginX, stream.focusMarginY);
+  const retainBounds = focusBounds(stream.focus, stream.unloadMarginX, stream.unloadMarginY);
+  const desired = new Set();
+  stream.regions.forEach((descriptor) => {
+    if (descriptor.id === activeRegionId || boundsIntersect(descriptor.bounds, activeBounds)) {
+      desired.add(descriptor.id);
+    }
+  });
+
+  const enteredRegionIds = [];
+  desired.forEach((regionId) => {
+    const descriptor = stream.regionById.get(regionId);
+    const wasLoaded = stream.loaded.has(regionId);
+    const record = ensureRegionLoaded(stream, descriptor, aura);
+    if (record) {
+      record.lastTouchedSync = stream.syncCount;
+      if (!wasLoaded) enteredRegionIds.push(regionId);
+    }
+  });
+
+  const exitedRegionIds = [];
+  for (const record of listLoadedStreamedWorldRegions2D(stream)) {
+    if (desired.has(record.id)) continue;
+    if (boundsIntersect(record.bounds, retainBounds)) continue;
+    if (unloadTilemapWorld2D(record.world, aura)) {
+      stream.loaded.delete(record.id);
+      exitedRegionIds.push(record.id);
+    }
+  }
+
+  stream.activeRegionId = activeRegionId;
+  const activeRegion = activeRegionId ? (stream.loaded.get(activeRegionId) ?? ensureRegionLoaded(stream, activeDescriptor, aura)) : null;
+  const loadedRegionIds = listLoadedStreamedWorldRegions2D(stream).map((record) => record.id);
+  stream.lastSync = {
+    focus: { ...stream.focus },
+    activeRegionId,
+    enteredRegionIds,
+    exitedRegionIds,
+    loadedRegionIds,
+  };
+  return {
+    focus: { ...stream.focus },
+    activeRegionId,
+    activeRegion,
+    enteredRegionIds,
+    exitedRegionIds,
+    loadedRegionIds,
+  };
+}
+
+export function queryStreamedWorldPoint2D(stream, auraRef = globalThis.aura, point = {}) {
+  const record = findStreamedWorldRegionAtPoint2D(stream, point);
+  if (!record) {
+    return { ok: false, hit: false, hits: [], reasonCode: 'region_not_loaded' };
+  }
+  const result = queryTilemapWorldPoint2D(record.world, auraRef, point) || null;
+  if (!result || typeof result !== 'object') return result;
+  return {
+    ...result,
+    regionId: record.id,
+    regionLabel: record.label,
+    hits: Array.isArray(result.hits) ? result.hits.map((hit) => normalizeQueryHit(hit, record)) : [],
+  };
+}
+
+export function queryStreamedWorldAABB2D(stream, auraRef = globalThis.aura, bounds = {}) {
+  const targetBounds = cloneBounds(bounds);
+  const candidates = loadedRecordsForBounds(stream, targetBounds);
+  if (candidates.length === 0) {
+    return { ok: false, hit: false, hits: [], reasonCode: 'region_not_loaded' };
+  }
+  const hits = [];
+  candidates.forEach((record) => {
+    const result = queryTilemapWorldAABB2D(record.world, auraRef, targetBounds) || null;
+    if (!Array.isArray(result?.hits)) return;
+    result.hits.forEach((hit) => {
+      hits.push(normalizeQueryHit(hit, record));
+    });
+  });
+  return {
+    ok: true,
+    hit: hits.length > 0,
+    hits,
+  };
+}
+
+export function queryStreamedWorldRay2D(stream, auraRef = globalThis.aura, ray = {}) {
+  const aura = resolveAura(auraRef);
+  if (!aura?.tilemap || typeof aura.tilemap.queryRay !== 'function') {
+    return { ok: false, hit: false, hits: [], reasonCode: 'query_ray_unavailable' };
+  }
+  const candidates = listLoadedStreamedWorldRegions2D(stream);
+  let best = null;
+  candidates.forEach((record) => {
+    if (!ensureTilemapWorldLoaded2D(record.world, aura)) return;
+    const localRay = {
+      x: finite(ray.x) - finite(record.world.offsetX),
+      y: finite(ray.y) - finite(record.world.offsetY),
+      dx: finite(ray.dx),
+      dy: finite(ray.dy),
+      maxDistance: Math.max(0, finite(ray.maxDistance, 0)),
+    };
+    const result = aura.tilemap.queryRay(record.world.mapId, localRay) || null;
+    if (!result || result.hit !== true || !Number.isFinite(Number(result.distance))) return;
+    const normalized = normalizeRayResult(result, record);
+    if (!best || Number(normalized.distance) < Number(best.distance)) {
+      best = normalized;
+    }
+  });
+  if (best) {
+    return best;
+  }
+  return {
+    ok: true,
+    hit: false,
+    hits: [],
+    hitCell: null,
+    distance: null,
+    point: null,
+    reasonCode: null,
+  };
+}
+
+export function unloadStreamedWorld2D(stream, auraRef = globalThis.aura) {
+  if (!stream || !(stream.loaded instanceof Map)) return false;
+  const aura = resolveAura(auraRef);
+  let unloaded = false;
+  for (const record of listLoadedStreamedWorldRegions2D(stream)) {
+    unloaded = unloadTilemapWorld2D(record.world, aura) || unloaded;
+  }
+  stream.loaded.clear();
+  stream.focus = null;
+  stream.activeRegionId = null;
+  stream.lastSync = null;
+  return unloaded;
+}