@auraindustry/aurajs 0.1.1 → 0.1.5

package/src/helpers/starter-utils/triggers.js

@@ -0,0 +1,662 @@
+const TRIGGER_TRACKER_SCHEMA = 'aurajs.trigger-tracker.v1';
+const INTERACTION_PROMPT_SCHEMA = 'aurajs.interaction-prompt.v1';
+
+function toFiniteNumber(value, fallback = 0) {
+  return Number.isFinite(value) ? Number(value) : fallback;
+}
+
+function normalizeText(value) {
+  if (typeof value === 'string' && value.trim().length > 0) return value.trim();
+  return null;
+}
+
+function normalizeSubjectId(value) {
+  return normalizeText(value) || 'subject';
+}
+
+function normalizeDimensionHint(value) {
+  return value === '3d' ? '3d' : '2d';
+}
+
+function createFallbackId(prefix, parts) {
+  return `${prefix}:${parts.map((value) => String(value)).join(':')}`;
+}
+
+function toPoint2D(value) {
+  if (!value || typeof value !== 'object') return null;
+  if (Number.isFinite(value.x) && Number.isFinite(value.y)) {
+    return {
+      x: Number(value.x),
+      y: Number(value.y),
+    };
+  }
+  if (value.position && typeof value.position === 'object') {
+    return toPoint2D(value.position);
+  }
+  return null;
+}
+
+function toRect2D(value) {
+  if (!value || typeof value !== 'object') return null;
+  const point = toPoint2D(value);
+  if (!point) return null;
+  const width = Number(value.w ?? value.width);
+  const height = Number(value.h ?? value.height);
+  if (!Number.isFinite(width) || !Number.isFinite(height)) {
+    return {
+      x: point.x,
+      y: point.y,
+      w: 0,
+      h: 0,
+      point: true,
+    };
+  }
+  return {
+    x: point.x,
+    y: point.y,
+    w: Math.max(0, width),
+    h: Math.max(0, height),
+    point: width <= 0 || height <= 0,
+  };
+}
+
+function normalizeRectBounds(options = {}) {
+  const width = Number(options.w ?? options.width);
+  const height = Number(options.h ?? options.height);
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+    return null;
+  }
+
+  if (options.centered === true || Number.isFinite(options.cx) || Number.isFinite(options.cy)) {
+    const cx = toFiniteNumber(options.cx, options.x);
+    const cy = toFiniteNumber(options.cy, options.y);
+    return {
+      x: cx - (width * 0.5),
+      y: cy - (height * 0.5),
+      w: width,
+      h: height,
+    };
+  }
+
+  return {
+    x: toFiniteNumber(options.x),
+    y: toFiniteNumber(options.y),
+    w: width,
+    h: height,
+  };
+}
+
+function toPoint3D(value) {
+  if (!value || typeof value !== 'object') return null;
+  if (Number.isFinite(value.x) && Number.isFinite(value.y) && Number.isFinite(value.z)) {
+    return {
+      x: Number(value.x),
+      y: Number(value.y),
+      z: Number(value.z),
+    };
+  }
+  if (value.position && typeof value.position === 'object') {
+    return toPoint3D(value.position);
+  }
+  return null;
+}
+
+function toRadius3D(value) {
+  if (!value || typeof value !== 'object') return 0;
+  if (Number.isFinite(value.radius)) return Math.max(0, Number(value.radius));
+  if (value.bounds && typeof value.bounds === 'object' && Number.isFinite(value.bounds.radius)) {
+    return Math.max(0, Number(value.bounds.radius));
+  }
+  if (Number.isFinite(value.interactionRadius)) {
+    return Math.max(0, Number(value.interactionRadius));
+  }
+  return 0;
+}
+
+function createTriggerMeta(definition, fallbackKind) {
+  const promptText = normalizeText(definition.promptText) || normalizeText(definition.prompt);
+  const interactionKey = normalizeText(definition.interactionKey) || normalizeText(definition.key);
+  return {
+    id: normalizeText(definition.id),
+    kind: normalizeText(definition.kind) || fallbackKind,
+    role: normalizeText(definition.role) || 'trigger',
+    priority: Number.isFinite(definition.priority) ? Number(definition.priority) : 0,
+    promptText,
+    interactionKey,
+    interactable: definition.interactable === true
+      || definition.interactionEnabled === true
+      || Boolean(promptText)
+      || Boolean(interactionKey),
+  };
+}
+
+function normalizeTriggerDefinition2D(definition) {
+  if (!definition || typeof definition !== 'object') return null;
+  const id = normalizeText(definition.id);
+  if (!id) return null;
+
+  const rectSource = definition.rect && typeof definition.rect === 'object'
+    ? { ...definition, ...definition.rect }
+    : definition;
+  const rect = normalizeRectBounds(rectSource);
+  if (!rect) return null;
+
+  return {
+    ...createTriggerMeta(definition, 'zone'),
+    id,
+    dimension: '2d',
+    shape: 'rect',
+    ...rect,
+  };
+}
+
+function normalizeTriggerDefinition3D(definition) {
+  if (!definition || typeof definition !== 'object') return null;
+  const id = normalizeText(definition.id);
+  if (!id) return null;
+
+  const centerSource = definition.center && typeof definition.center === 'object'
+    ? definition.center
+    : definition;
+  const center = toPoint3D(centerSource);
+  if (!center) return null;
+
+  const shape = definition.shape === 'volume' || definition.kind === 'box' || definition.kind === 'volume'
+    ? 'volume'
+    : 'proximity';
+
+  if (shape === 'proximity') {
+    const radius = Number(definition.radius);
+    if (!Number.isFinite(radius) || radius <= 0) return null;
+    return {
+      ...createTriggerMeta(definition, 'zone'),
+      id,
+      dimension: '3d',
+      shape,
+      x: center.x,
+      y: center.y,
+      z: center.z,
+      radius,
+    };
+  }
+
+  const size = definition.size && typeof definition.size === 'object' ? definition.size : {};
+  const width = Number(definition.w ?? definition.width ?? size.x);
+  const height = Number(definition.h ?? definition.height ?? size.y);
+  const depth = Number(definition.d ?? definition.depth ?? size.z);
+  if (!Number.isFinite(width) || !Number.isFinite(height) || !Number.isFinite(depth)) return null;
+  if (width <= 0 || height <= 0 || depth <= 0) return null;
+  return {
+    ...createTriggerMeta(definition, 'zone'),
+    id,
+    dimension: '3d',
+    shape,
+    x: center.x,
+    y: center.y,
+    z: center.z,
+    size: {
+      x: width,
+      y: height,
+      z: depth,
+    },
+    w: width,
+    h: height,
+    d: depth,
+  };
+}
+
+function rectContainsPoint(rect, point) {
+  return point.x >= rect.x
+    && point.x <= rect.x + rect.w
+    && point.y >= rect.y
+    && point.y <= rect.y + rect.h;
+}
+
+function rectsOverlap(left, right) {
+  return left.x < right.x + right.w
+    && left.x + left.w > right.x
+    && left.y < right.y + right.h
+    && left.y + left.h > right.y;
+}
+
+function isRectTriggerActive(subject, trigger) {
+  if (subject.point) return rectContainsPoint(trigger, subject);
+  return rectsOverlap(subject, trigger);
+}
+
+function isRadiusTriggerActive(subject, trigger) {
+  const subjectRadius = toRadius3D(subject);
+  const maxRadius = trigger.radius + subjectRadius;
+  const dx = subject.x - trigger.x;
+  const dy = subject.y - trigger.y;
+  const dz = subject.z - trigger.z;
+  return ((dx * dx) + (dy * dy) + (dz * dz)) <= (maxRadius * maxRadius);
+}
+
+function isBoxTriggerActive(subject, trigger) {
+  const subjectRadius = toRadius3D(subject);
+  const halfX = trigger.size.x * 0.5;
+  const halfY = trigger.size.y * 0.5;
+  const halfZ = trigger.size.z * 0.5;
+  return Math.abs(subject.x - trigger.x) <= halfX + subjectRadius
+    && Math.abs(subject.y - trigger.y) <= halfY + subjectRadius
+    && Math.abs(subject.z - trigger.z) <= halfZ + subjectRadius;
+}
+
+function createTriggerEntry(trigger, active) {
+  if (!trigger) return null;
+  return {
+    id: trigger.id,
+    kind: trigger.kind,
+    dimension: trigger.dimension,
+    shape: trigger.shape,
+    role: trigger.role,
+    priority: trigger.priority,
+    promptText: trigger.promptText,
+    prompt: trigger.promptText,
+    interactionKey: trigger.interactionKey,
+    interactionEnabled: trigger.interactable,
+    interactable: trigger.interactable,
+    active,
+  };
+}
+
+function cloneEntries(entries) {
+  return entries.map((entry) => ({ ...entry }));
+}
+
+function sortEntries(entries) {
+  entries.sort((left, right) => {
+    const byPriority = right.priority - left.priority;
+    if (byPriority !== 0) return byPriority;
+    return left.id.localeCompare(right.id);
+  });
+  return entries;
+}
+
+function resultErr(reasonCode, extras = {}) {
+  return {
+    ok: false,
+    reasonCode,
+    ...extras,
+  };
+}
+
+function buildStepResult(tracker, entriesById, nextActiveIds, subjectId, dimension) {
+  const previousActiveIds = Array.isArray(tracker.activeIds) ? tracker.activeIds : [];
+  const previousActiveSet = new Set(previousActiveIds);
+  const nextActiveSet = new Set(nextActiveIds);
+  const previousEntriesById = tracker.entriesById && typeof tracker.entriesById === 'object'
+    ? tracker.entriesById
+    : {};
+
+  const active = sortEntries(nextActiveIds
+    .map((triggerId) => createTriggerEntry(entriesById.get(triggerId), true))
+    .filter(Boolean));
+  const activeIds = active.map((entry) => entry.id);
+  const activeIdSet = new Set(activeIds);
+  const entered = sortEntries(active.filter((entry) => !previousActiveSet.has(entry.id)).map((entry) => ({ ...entry })));
+  const stayed = sortEntries(active.filter((entry) => previousActiveSet.has(entry.id)).map((entry) => ({ ...entry })));
+  const left = sortEntries(previousActiveIds
+    .filter((triggerId) => !nextActiveSet.has(triggerId) && !activeIdSet.has(triggerId))
+    .map((triggerId) => createTriggerEntry(entriesById.get(triggerId) || previousEntriesById[triggerId], false))
+    .filter(Boolean));
+
+  tracker.subjectId = subjectId;
+  tracker.dimension = dimension;
+  tracker.stepCount += 1;
+  tracker.mutationCount += 1;
+  tracker.activeIds = [...activeIds];
+  tracker.entriesById = {
+    ...previousEntriesById,
+    ...Object.fromEntries(entriesById.entries()),
+  };
+  tracker.lastStep = {
+    entered: cloneEntries(entered),
+    stayed: cloneEntries(stayed),
+    left: cloneEntries(left),
+    active: cloneEntries(active),
+  };
+
+  return {
+    ok: true,
+    reasonCode: 'trigger_step_ok',
+    schema: TRIGGER_TRACKER_SCHEMA,
+    dimension,
+    subjectId,
+    stepCount: tracker.stepCount,
+    mutationCount: tracker.mutationCount,
+    frame: tracker.stepCount,
+    activeIds,
+    enteredIds: entered.map((entry) => entry.id),
+    stayedIds: stayed.map((entry) => entry.id),
+    leftIds: left.map((entry) => entry.id),
+    entered: cloneEntries(entered),
+    stayed: cloneEntries(stayed),
+    left: cloneEntries(left),
+    active: cloneEntries(active),
+  };
+}
+
+function normalizeActiveTriggerEntries(entries) {
+  return sortEntries(
+    [...entries].filter((entry) => entry && entry.interactable).map((entry) => ({ ...entry })),
+  );
+}
+
+export function createTriggerTracker(options = {}) {
+  return {
+    schema: TRIGGER_TRACKER_SCHEMA,
+    subjectId: normalizeSubjectId(options.subjectId),
+    dimension: normalizeDimensionHint(options.dimension),
+    stepCount: 0,
+    mutationCount: 0,
+    activeIds: [],
+    entriesById: {},
+    lastStep: {
+      entered: [],
+      stayed: [],
+      left: [],
+      active: [],
+    },
+  };
+}
+
+export function getTriggerTrackerSnapshot(tracker) {
+  return {
+    schema: TRIGGER_TRACKER_SCHEMA,
+    subjectId: normalizeSubjectId(tracker?.subjectId),
+    dimension: normalizeDimensionHint(tracker?.dimension),
+    stepCount: toFiniteNumber(tracker?.stepCount),
+    mutationCount: toFiniteNumber(tracker?.mutationCount),
+    activeIds: Array.isArray(tracker?.activeIds) ? [...tracker.activeIds] : [],
+    lastStep: {
+      entered: cloneEntries(Array.isArray(tracker?.lastStep?.entered) ? tracker.lastStep.entered : []),
+      stayed: cloneEntries(Array.isArray(tracker?.lastStep?.stayed) ? tracker.lastStep.stayed : []),
+      left: cloneEntries(Array.isArray(tracker?.lastStep?.left) ? tracker.lastStep.left : []),
+      active: cloneEntries(Array.isArray(tracker?.lastStep?.active) ? tracker.lastStep.active : []),
+    },
+  };
+}
+
+export function stepRectTriggers2D(tracker, subject, triggers = [], options = {}) {
+  const rectSubject = toRect2D(subject);
+  if (!rectSubject) return resultErr('trigger_invalid_subject');
+
+  const subjectId = normalizeSubjectId(options.subjectId ?? tracker?.subjectId);
+  const normalizedTriggers = [];
+  for (const definition of Array.isArray(triggers) ? triggers : []) {
+    const trigger = normalizeTriggerDefinition2D(definition);
+    if (!trigger) return resultErr('trigger_invalid_definition');
+    normalizedTriggers.push(trigger);
+  }
+
+  const entriesById = new Map();
+  const activeIds = [];
+  for (const trigger of normalizedTriggers) {
+    entriesById.set(trigger.id, trigger);
+    if (isRectTriggerActive(rectSubject, trigger)) {
+      activeIds.push(trigger.id);
+    }
+  }
+
+  return buildStepResult(tracker, entriesById, activeIds, subjectId, '2d');
+}
+
+export function stepVolumeTriggers3D(tracker, subject, triggers = [], options = {}) {
+  const pointSubject = toPoint3D(subject);
+  if (!pointSubject) return resultErr('trigger_invalid_subject');
+
+  const subjectId = normalizeSubjectId(options.subjectId ?? tracker?.subjectId);
+  const normalizedTriggers = [];
+  for (const definition of Array.isArray(triggers) ? triggers : []) {
+    const trigger = normalizeTriggerDefinition3D(definition);
+    if (!trigger) return resultErr('trigger_invalid_definition');
+    normalizedTriggers.push(trigger);
+  }
+
+  const entriesById = new Map();
+  const activeIds = [];
+  for (const trigger of normalizedTriggers) {
+    entriesById.set(trigger.id, trigger);
+    const active = trigger.shape === 'volume'
+      ? isBoxTriggerActive(subject, trigger)
+      : isRadiusTriggerActive(subject, trigger);
+    if (active) {
+      activeIds.push(trigger.id);
+    }
+  }
+
+  return buildStepResult(tracker, entriesById, activeIds, subjectId, '3d');
+}
+
+export function resolveTriggerInteraction(stepResult, options = {}) {
+  const activeEntries = normalizeActiveTriggerEntries(Array.isArray(stepResult?.active) ? stepResult.active : []);
+  const promptText = normalizeText(options.promptText) || normalizeText(options.prompt);
+
+  if (activeEntries.length <= 0) {
+    return {
+      ok: false,
+      reasonCode: 'trigger_interaction_unavailable',
+      ready: false,
+      triggerId: null,
+      triggerKind: null,
+      promptText: null,
+      interactionKey: null,
+      interacted: false,
+      activeTriggerIds: [],
+    };
+  }
+
+  const selected = activeEntries[0];
+  return {
+    ok: true,
+    reasonCode: options.interactPressed === true ? 'trigger_interaction_accepted' : 'trigger_interaction_ready',
+    ready: true,
+    triggerId: selected.id,
+    triggerKind: selected.kind,
+    promptText: promptText || selected.promptText,
+    interactionKey: selected.interactionKey || null,
+    interacted: options.interactPressed === true,
+    activeTriggerIds: activeEntries.map((entry) => entry.id),
+  };
+}
+
+function resolveRectTriggerArgs(args) {
+  if (args.length === 1 && args[0] && typeof args[0] === 'object' && !Array.isArray(args[0])) {
+    return args[0];
+  }
+  const [id, x, y, w, h, options = {}] = args;
+  return {
+    ...options,
+    id,
+    x,
+    y,
+    w,
+    h,
+  };
+}
+
+function resolveProximityTriggerArgs(args) {
+  if (args.length === 1 && args[0] && typeof args[0] === 'object' && !Array.isArray(args[0])) {
+    return args[0];
+  }
+  const [id, x, y, z, radius, options = {}] = args;
+  return {
+    ...options,
+    id,
+    x,
+    y,
+    z,
+    radius,
+  };
+}
+
+function resolveVolumeTriggerArgs(args) {
+  if (args.length === 1 && args[0] && typeof args[0] === 'object' && !Array.isArray(args[0])) {
+    return args[0];
+  }
+  const [id, x, y, z, sizeOrWidth, heightOrOptions, depth, options] = args;
+  if (sizeOrWidth && typeof sizeOrWidth === 'object' && !Array.isArray(sizeOrWidth)) {
+    return {
+      ...(heightOrOptions && typeof heightOrOptions === 'object' && !Array.isArray(heightOrOptions) ? heightOrOptions : {}),
+      id,
+      x,
+      y,
+      z,
+      size: sizeOrWidth,
+    };
+  }
+  return {
+    ...(options && typeof options === 'object' && !Array.isArray(options) ? options : {}),
+    id,
+    x,
+    y,
+    z,
+    w: sizeOrWidth,
+    h: heightOrOptions,
+    d: depth,
+  };
+}
+
+export function createRectTrigger2D(...args) {
+  const options = resolveRectTriggerArgs(args);
+  const rect = normalizeRectBounds(options);
+  if (!rect) {
+    throw new TypeError('createRectTrigger2D requires finite positive width and height');
+  }
+  const promptText = normalizeText(options.promptText) || normalizeText(options.prompt);
+  const interactionKey = normalizeText(options.interactionKey) || normalizeText(options.key);
+  return {
+    id: normalizeText(options.id) || createFallbackId('trigger-2d', [rect.x, rect.y, rect.w, rect.h]),
+    kind: normalizeText(options.kind) || 'zone',
+    role: normalizeText(options.role) || 'trigger',
+    priority: Number.isFinite(options.priority) ? Number(options.priority) : 0,
+    promptText,
+    interactionKey,
+    interactable: options.interactable === true
+      || options.interactionEnabled === true
+      || Boolean(promptText)
+      || Boolean(interactionKey),
+    shape: 'rect',
+    ...rect,
+  };
+}
+
+export function createProximityTrigger3D(...args) {
+  const options = resolveProximityTriggerArgs(args);
+  const center = toPoint3D(options.center || options);
+  const radius = Number(options.radius);
+  if (!center || !Number.isFinite(radius) || radius <= 0) {
+    throw new TypeError('createProximityTrigger3D requires a center and positive radius');
+  }
+  const promptText = normalizeText(options.promptText) || normalizeText(options.prompt);
+  const interactionKey = normalizeText(options.interactionKey) || normalizeText(options.key);
+  return {
+    id: normalizeText(options.id) || createFallbackId('trigger-3d-proximity', [center.x, center.y, center.z, radius]),
+    kind: normalizeText(options.kind) || 'zone',
+    role: normalizeText(options.role) || 'trigger',
+    priority: Number.isFinite(options.priority) ? Number(options.priority) : 0,
+    promptText,
+    interactionKey,
+    interactable: options.interactable === true
+      || options.interactionEnabled === true
+      || Boolean(promptText)
+      || Boolean(interactionKey),
+    shape: 'proximity',
+    x: center.x,
+    y: center.y,
+    z: center.z,
+    radius,
+  };
+}
+
+export function createVolumeTrigger3D(...args) {
+  const options = resolveVolumeTriggerArgs(args);
+  const center = toPoint3D(options.center || options);
+  const size = options.size && typeof options.size === 'object' ? options.size : {};
+  const width = Number(options.w ?? options.width ?? size.x);
+  const height = Number(options.h ?? options.height ?? size.y);
+  const depth = Number(options.d ?? options.depth ?? size.z);
+  if (!center || !Number.isFinite(width) || !Number.isFinite(height) || !Number.isFinite(depth) || width <= 0 || height <= 0 || depth <= 0) {
+    throw new TypeError('createVolumeTrigger3D requires a center and positive volume dimensions');
+  }
+  const promptText = normalizeText(options.promptText) || normalizeText(options.prompt);
+  const interactionKey = normalizeText(options.interactionKey) || normalizeText(options.key);
+  return {
+    id: normalizeText(options.id) || createFallbackId('trigger-3d-volume', [center.x, center.y, center.z, width, height, depth]),
+    kind: normalizeText(options.kind) || 'zone',
+    role: normalizeText(options.role) || 'trigger',
+    priority: Number.isFinite(options.priority) ? Number(options.priority) : 0,
+    promptText,
+    interactionKey,
+    interactable: options.interactable === true
+      || options.interactionEnabled === true
+      || Boolean(promptText)
+      || Boolean(interactionKey),
+    shape: 'volume',
+    x: center.x,
+    y: center.y,
+    z: center.z,
+    size: {
+      x: width,
+      y: height,
+      z: depth,
+    },
+    w: width,
+    h: height,
+    d: depth,
+  };
+}
+
+export function stepTriggerTracker(tracker, subject, triggers = [], options = {}) {
+  const dimension = normalizeDimensionHint(
+    options.dimension
+    || tracker?.dimension
+    || (Array.isArray(triggers) && triggers.some((entry) => entry && (entry.shape === 'volume' || entry.shape === 'proximity' || Number.isFinite(entry.z))) ? '3d' : '2d'),
+  );
+  if (dimension === '3d') {
+    return stepVolumeTriggers3D(tracker, subject, triggers, options);
+  }
+  return stepRectTriggers2D(tracker, subject, triggers, options);
+}
+
+export function createInteractionPromptState(options = {}) {
+  return {
+    schema: INTERACTION_PROMPT_SCHEMA,
+    fallbackPrompt: normalizeText(options.fallbackPrompt) || normalizeText(options.prompt) || 'Interact',
+    visible: false,
+    ready: false,
+    accepted: false,
+    triggerId: null,
+    triggerKind: null,
+    prompt: null,
+    interactionKey: null,
+    candidateIds: [],
+    acceptedTriggerId: null,
+    lastAcceptedTriggerId: null,
+    reasonCode: 'interaction_unavailable',
+  };
+}
+
+export function updateInteractionPromptState(promptState, triggerState, options = {}) {
+  const resolved = resolveTriggerInteraction(triggerState, options);
+  promptState.visible = resolved.ready === true;
+  promptState.ready = resolved.ready === true;
+  promptState.accepted = resolved.interacted === true;
+  promptState.triggerId = resolved.triggerId || null;
+  promptState.triggerKind = resolved.triggerKind || null;
+  promptState.prompt = resolved.ready === true
+    ? (resolved.promptText || promptState.fallbackPrompt)
+    : null;
+  promptState.interactionKey = resolved.interactionKey || null;
+  promptState.candidateIds = Array.isArray(resolved.activeTriggerIds) ? [...resolved.activeTriggerIds] : [];
+  promptState.acceptedTriggerId = promptState.accepted ? promptState.triggerId : null;
+  promptState.reasonCode = promptState.accepted
+    ? 'interaction_accepted'
+    : (promptState.ready ? 'interaction_ready' : 'interaction_unavailable');
+  if (promptState.acceptedTriggerId != null) {
+    promptState.lastAcceptedTriggerId = promptState.acceptedTriggerId;
+  }
+  return promptState;
+}