@auraindustry/aurajs 0.1.1 → 0.1.5

package/templates/create/shared/src/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;
+}