@auraindustry/aurajs 0.1.3 → 0.1.5

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

@@ -0,0 +1,253 @@
+function finite(value, fallback = 0) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : fallback;
+}
+
+function positiveInteger(value, fallback = null) {
+  const numeric = Math.floor(finite(value, Number.NaN));
+  if (numeric >= 1) return numeric;
+  return fallback;
+}
+
+function normalizeText(value, fallback) {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : fallback;
+}
+
+function resolveAura(auraRef = globalThis.aura) {
+  return auraRef && typeof auraRef === 'object' ? auraRef : null;
+}
+
+function normalizeStageIds(value) {
+  if (!Array.isArray(value) || value.length === 0) {
+    return ['scene', 'light', 'final'];
+  }
+
+  const stageIds = [];
+  const seen = new Set();
+  for (const entry of value) {
+    const id = normalizeText(entry, null);
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    stageIds.push(id);
+  }
+  return stageIds.length > 0 ? stageIds : ['scene', 'light', 'final'];
+}
+
+function createTarget(aura, width, height) {
+  if (!aura?.draw2d || typeof aura.draw2d.createRenderTarget !== 'function') return null;
+  const target = aura.draw2d.createRenderTarget(width, height);
+  return target && typeof target === 'object' && target.ok === true ? target : null;
+}
+
+function destroyTarget(aura, target) {
+  if (!target || typeof target !== 'object' || target.ok !== true) return false;
+  if (!aura?.draw2d || typeof aura.draw2d.destroyRenderTarget !== 'function') return false;
+  aura.draw2d.destroyRenderTarget(target);
+  return true;
+}
+
+function resolveDimensions(compositor, options = {}) {
+  const width = positiveInteger(
+    options.width ?? compositor.fixedWidth,
+    null,
+  );
+  const height = positiveInteger(
+    options.height ?? compositor.fixedHeight,
+    null,
+  );
+  if (width == null || height == null) return null;
+  return { width, height };
+}
+
+function getStageRecord(compositor, stageId) {
+  return Array.isArray(compositor?.stages)
+    ? compositor.stages.find((entry) => entry.id === stageId) || null
+    : null;
+}
+
+function normalizeStageDefinitions(compositor, stageDefinitions) {
+  if (Array.isArray(stageDefinitions)) {
+    return compositor.stageIds.map((stageId) => (
+      stageDefinitions.find((entry) => entry?.id === stageId) || { id: stageId }
+    ));
+  }
+
+  if (stageDefinitions && typeof stageDefinitions === 'object') {
+    return compositor.stageIds.map((stageId) => {
+      const entry = stageDefinitions[stageId];
+      if (typeof entry === 'function') {
+        return { id: stageId, draw: entry };
+      }
+      if (entry && typeof entry === 'object') {
+        return { id: stageId, ...entry };
+      }
+      return { id: stageId };
+    });
+  }
+
+  return compositor.stageIds.map((stageId) => ({ id: stageId }));
+}
+
+export function createWorldCompositor2D(options = {}) {
+  const stageIds = normalizeStageIds(options.stageIds);
+  const finalStageId = stageIds.includes(options.finalStageId)
+    ? options.finalStageId
+    : stageIds[stageIds.length - 1];
+  return {
+    graphName: normalizeText(options.graphName, 'world-compositor-2d'),
+    stageIds,
+    finalStageId,
+    fixedWidth: positiveInteger(options.width ?? options.fixedWidth, null),
+    fixedHeight: positiveInteger(options.height ?? options.fixedHeight, null),
+    width: 0,
+    height: 0,
+    targets: null,
+    stages: null,
+  };
+}
+
+export function destroyWorldCompositor2D(compositor, auraRef = globalThis.aura) {
+  const aura = resolveAura(auraRef);
+  if (!compositor || typeof compositor !== 'object') return false;
+  if (compositor.targets && typeof compositor.targets === 'object') {
+    for (const stageId of compositor.stageIds || []) {
+      destroyTarget(aura, compositor.targets[stageId]);
+    }
+  }
+  compositor.width = 0;
+  compositor.height = 0;
+  compositor.targets = null;
+  compositor.stages = null;
+  return true;
+}
+
+export function ensureWorldCompositorTargets2D(compositor, options = {}, auraRef = globalThis.aura) {
+  const aura = resolveAura(auraRef);
+  if (!compositor || typeof compositor !== 'object') {
+    throw new Error('world compositor state is required.');
+  }
+
+  const dimensions = resolveDimensions(compositor, options);
+  if (!dimensions) return null;
+  if (
+    compositor.targets
+    && compositor.width === dimensions.width
+    && compositor.height === dimensions.height
+  ) {
+    return compositor.targets;
+  }
+
+  destroyWorldCompositor2D(compositor, aura);
+
+  const targets = {};
+  for (const stageId of compositor.stageIds) {
+    const target = createTarget(aura, dimensions.width, dimensions.height);
+    if (!target) {
+      for (const created of Object.values(targets)) {
+        destroyTarget(aura, created);
+      }
+      return null;
+    }
+    targets[stageId] = target;
+  }
+
+  compositor.width = dimensions.width;
+  compositor.height = dimensions.height;
+  compositor.targets = targets;
+  return targets;
+}
+
+export function runWorldCompositor2D(
+  compositor,
+  stageDefinitions,
+  options = {},
+  auraRef = globalThis.aura,
+) {
+  const aura = resolveAura(auraRef);
+  if (!compositor || typeof compositor !== 'object') {
+    throw new Error('world compositor state is required.');
+  }
+
+  const dimensions = resolveDimensions(compositor, options);
+  const fallbackDraw = typeof options.fallbackDraw === 'function' ? options.fallbackDraw : null;
+  if (!dimensions) {
+    if (fallbackDraw) fallbackDraw({ reasonCode: 'invalid_world_compositor_size' });
+    return {
+      ok: false,
+      reasonCode: 'invalid_world_compositor_size',
+      graph: null,
+      targets: null,
+      finalStage: null,
+      width: 0,
+      height: 0,
+    };
+  }
+
+  const targets = ensureWorldCompositorTargets2D(compositor, dimensions, aura);
+  if (!targets) {
+    if (fallbackDraw) fallbackDraw({ reasonCode: 'draw2d_render_target_unavailable' });
+    return {
+      ok: false,
+      reasonCode: 'draw2d_render_target_unavailable',
+      graph: null,
+      targets: null,
+      finalStage: null,
+      width: dimensions.width,
+      height: dimensions.height,
+    };
+  }
+
+  const definitions = normalizeStageDefinitions(compositor, stageDefinitions);
+  compositor.stages = definitions;
+  if (!aura?.draw2d || typeof aura.draw2d.runCompositorGraph !== 'function') {
+    if (fallbackDraw) {
+      fallbackDraw({
+        reasonCode: 'draw2d_compositor_unavailable',
+        width: dimensions.width,
+        height: dimensions.height,
+        targets,
+      });
+    }
+    return {
+      ok: false,
+      reasonCode: 'draw2d_compositor_unavailable',
+      graph: null,
+      targets,
+      finalStage: targets[compositor.finalStageId] || null,
+      width: dimensions.width,
+      height: dimensions.height,
+    };
+  }
+
+  const graph = aura.draw2d.runCompositorGraph(
+    compositor.graphName,
+    definitions.map((entry) => ({
+      id: entry.id,
+      target: targets[entry.id],
+      draw: () => {
+        if (typeof entry.draw !== 'function') return;
+        entry.draw({
+          id: entry.id,
+          width: dimensions.width,
+          height: dimensions.height,
+          graphName: compositor.graphName,
+          targets,
+          aura,
+          stage: getStageRecord(compositor, entry.id),
+          finalStageId: compositor.finalStageId,
+        });
+      },
+    })),
+  );
+
+  const finalStageIndex = compositor.stageIds.indexOf(compositor.finalStageId);
+  return {
+    ok: graph?.ok === true,
+    reasonCode: graph?.reasonCode || null,
+    graph,
+    targets,
+    finalStage: graph?.stages?.[finalStageIndex] || targets[compositor.finalStageId] || null,
+    width: dimensions.width,
+    height: dimensions.height,
+  };
+}

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

@@ -0,0 +1,180 @@
+import { syncStreamedWorldFocus2D } from './streamed-world-2d.js';
+
+function cloneSnapshot(value) {
+  if (value == null) return value;
+  return JSON.parse(JSON.stringify(value));
+}
+
+function resolveStorage(auraRef = globalThis.aura) {
+  const storage = auraRef?.storage;
+  if (!storage || typeof storage !== 'object') return null;
+  return storage;
+}
+
+function storageSave(storage, key, value) {
+  if (!storage || typeof key !== 'string' || key.length === 0) return false;
+  if (typeof storage.save === 'function') {
+    storage.save(key, value);
+    return true;
+  }
+  if (typeof storage.set === 'function') {
+    storage.set(key, value);
+    return true;
+  }
+  return false;
+}
+
+function storageLoad(storage, key, fallback = null) {
+  if (!storage || typeof key !== 'string' || key.length === 0) return fallback;
+  if (typeof storage.load === 'function') {
+    return storage.load(key, fallback);
+  }
+  if (typeof storage.get === 'function') {
+    return storage.get(key, fallback);
+  }
+  return fallback;
+}
+
+function storageDelete(storage, key) {
+  if (!storage || typeof key !== 'string' || key.length === 0) return false;
+  if (typeof storage.delete === 'function') {
+    storage.delete(key);
+    return true;
+  }
+  return false;
+}
+
+function normalizeSnapshot(snapshot) {
+  if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot)) return null;
+  return {
+    version: Number.isFinite(Number(snapshot.version)) ? Number(snapshot.version) : 1,
+    scope: typeof snapshot.scope === 'string' ? snapshot.scope : 'streamed-world-2d',
+    activeRegionId: typeof snapshot.activeRegionId === 'string' ? snapshot.activeRegionId : null,
+    focus: snapshot.focus && typeof snapshot.focus === 'object'
+      ? {
+        x: Number(snapshot.focus.x) || 0,
+        y: Number(snapshot.focus.y) || 0,
+      }
+      : null,
+    world: snapshot.world == null ? null : cloneSnapshot(snapshot.world),
+    regions: Array.isArray(snapshot.regions)
+      ? snapshot.regions
+        .filter((entry) => entry && typeof entry === 'object' && typeof entry.id === 'string')
+        .map((entry) => ({
+          id: entry.id,
+          data: cloneSnapshot(entry.data),
+        }))
+      : [],
+  };
+}
+
+export function captureStreamedWorldSnapshot2D(stream, options = {}) {
+  if (!stream || !(stream.regionById instanceof Map)) {
+    return null;
+  }
+  const captureRegion = typeof options.captureRegion === 'function' ? options.captureRegion : null;
+  const captureWorld = typeof options.captureWorld === 'function' ? options.captureWorld : null;
+  const regionIds = Array.isArray(options.regionIds)
+    ? options.regionIds.filter((entry) => typeof entry === 'string')
+    : stream.regions.map((entry) => entry.id);
+  const regions = [];
+
+  regionIds.forEach((regionId) => {
+    const descriptor = stream.regionById.get(regionId) || null;
+    if (!descriptor || !captureRegion) return;
+    const record = stream.loaded?.get(regionId) || null;
+    const data = captureRegion(descriptor, record, stream, options);
+    if (data == null) return;
+    regions.push({
+      id: regionId,
+      data: cloneSnapshot(data),
+    });
+  });
+
+  return {
+    version: 1,
+    scope: options.scope ?? 'streamed-world-2d',
+    activeRegionId: stream.activeRegionId ?? null,
+    focus: stream.focus ? { x: Number(stream.focus.x) || 0, y: Number(stream.focus.y) || 0 } : null,
+    world: captureWorld ? cloneSnapshot(captureWorld(stream, options)) : null,
+    regions,
+  };
+}
+
+export function applyStreamedWorldSnapshot2D(stream, snapshot, options = {}) {
+  if (!stream || !(stream.regionById instanceof Map)) {
+    return {
+      ok: false,
+      reasonCode: 'invalid_stream',
+      appliedRegionIds: [],
+    };
+  }
+  const normalized = normalizeSnapshot(snapshot);
+  if (!normalized) {
+    return {
+      ok: false,
+      reasonCode: 'invalid_snapshot',
+      appliedRegionIds: [],
+    };
+  }
+  const applyRegion = typeof options.applyRegion === 'function' ? options.applyRegion : null;
+  const applyWorld = typeof options.applyWorld === 'function' ? options.applyWorld : null;
+  const appliedRegionIds = [];
+
+  if (applyWorld && normalized.world != null) {
+    applyWorld(cloneSnapshot(normalized.world), stream, options);
+  }
+
+  normalized.regions.forEach((entry) => {
+    const descriptor = stream.regionById.get(entry.id) || null;
+    if (!descriptor || !applyRegion) return;
+    const record = stream.loaded?.get(entry.id) || null;
+    applyRegion(descriptor, record, cloneSnapshot(entry.data), stream, options);
+    appliedRegionIds.push(entry.id);
+  });
+
+  if (options.restoreFocus === true && normalized.focus) {
+    syncStreamedWorldFocus2D(stream, options.auraRef, normalized.focus);
+  }
+
+  return {
+    ok: true,
+    reasonCode: null,
+    appliedRegionIds,
+    restoredFocus: options.restoreFocus === true && normalized.focus != null,
+  };
+}
+
+export function saveStreamedWorldSnapshot2D(key, stream, auraRef = globalThis.aura, options = {}) {
+  const storage = resolveStorage(auraRef);
+  const snapshot = captureStreamedWorldSnapshot2D(stream, options);
+  if (!snapshot) {
+    return {
+      ok: false,
+      reasonCode: 'invalid_stream',
+      snapshot: null,
+    };
+  }
+  if (!storageSave(storage, key, snapshot)) {
+    return {
+      ok: false,
+      reasonCode: 'storage_unavailable',
+      snapshot,
+    };
+  }
+  return {
+    ok: true,
+    reasonCode: null,
+    snapshot,
+  };
+}
+
+export function loadStreamedWorldSnapshot2D(key, auraRef = globalThis.aura, fallback = null) {
+  const storage = resolveStorage(auraRef);
+  const snapshot = storageLoad(storage, key, fallback);
+  return normalizeSnapshot(snapshot);
+}
+
+export function deleteStreamedWorldSnapshot2D(key, auraRef = globalThis.aura) {
+  return storageDelete(resolveStorage(auraRef), key);
+}