@auraindustry/aurajs 0.1.1 → 0.1.5

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

@@ -0,0 +1,221 @@
+import {
+  createInteractionPromptState,
+  createRectTrigger2D,
+  createTriggerTracker,
+  stepRectTriggers2D,
+  updateInteractionPromptState,
+} from './triggers.js';
+import { addInventoryItem2D, hasInventoryItem2D, removeInventoryItem2D } from './inventory-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 normalizeKind(value) {
+  switch (value) {
+    case 'pickup':
+    case 'lock':
+    case 'checkpoint':
+    case 'prop':
+      return value;
+    default:
+      return 'prop';
+  }
+}
+
+function objectProperty(object, name) {
+  if (!object || typeof object !== 'object') return null;
+  const properties = object.properties && typeof object.properties === 'object' ? object.properties : null;
+  return properties && Object.prototype.hasOwnProperty.call(properties, name) ? properties[name] : null;
+}
+
+function normalizeInteractable(definition, index) {
+  const fallbackId = `interactable-${index + 1}`;
+  const id = normalizeText(definition?.id, fallbackId);
+  const width = Math.max(4, finite(definition?.w ?? definition?.width, definition?.point === true ? 16 : 0));
+  const height = Math.max(4, finite(definition?.h ?? definition?.height, definition?.point === true ? 16 : 0));
+  const x = definition?.point === true
+    ? finite(definition?.x) - (width * 0.5)
+    : finite(definition?.x);
+  const y = definition?.point === true
+    ? finite(definition?.y) - (height * 0.5)
+    : finite(definition?.y);
+  return {
+    id,
+    label: normalizeText(definition?.label ?? definition?.name, id),
+    kind: normalizeKind(normalizeText(definition?.kind ?? definition?.type)),
+    x,
+    y,
+    w: width,
+    h: height,
+    priority: Number.isFinite(Number(definition?.priority)) ? Number(definition.priority) : 0,
+    promptText: normalizeText(definition?.promptText ?? definition?.prompt),
+    lockedPromptText: normalizeText(definition?.lockedPromptText),
+    openedPromptText: normalizeText(definition?.openedPromptText),
+    interactionKey: normalizeText(definition?.interactionKey, 'E'),
+    requiredItemId: normalizeText(definition?.requiredItemId),
+    requiredQuantity: Math.max(1, finite(definition?.requiredQuantity, 1)),
+    consumeRequiredItem: definition?.consumeRequiredItem === true,
+    grantItem: definition?.grantItem && typeof definition.grantItem === 'object' ? { ...definition.grantItem } : null,
+    checkpointId: normalizeText(definition?.checkpointId, id),
+    once: definition?.once !== false,
+    collected: definition?.collected === true,
+    opened: definition?.opened === true,
+    activated: definition?.activated === true,
+    disabled: definition?.disabled === true,
+  };
+}
+
+function promptForInteractable(interactable, inventory) {
+  if (!interactable || interactable.disabled === true) return null;
+  if (interactable.kind === 'pickup' && interactable.collected === true) return null;
+  if (interactable.kind === 'lock') {
+    if (interactable.opened === true) return interactable.openedPromptText || null;
+    if (interactable.requiredItemId && !hasInventoryItem2D(inventory, interactable.requiredItemId, interactable.requiredQuantity)) {
+      return interactable.lockedPromptText || `${interactable.label} is locked`;
+    }
+  }
+  if (interactable.kind === 'checkpoint' && interactable.activated === true && interactable.once === true) {
+    return null;
+  }
+  if (interactable.kind === 'prop' && interactable.activated === true && interactable.once === true) {
+    return null;
+  }
+  return interactable.promptText || `Interact with ${interactable.label}`;
+}
+
+function buildTrigger(interactable, inventory) {
+  const promptText = promptForInteractable(interactable, inventory);
+  if (!promptText) return null;
+  return createRectTrigger2D(interactable.id, interactable.x, interactable.y, interactable.w, interactable.h, {
+    kind: interactable.kind,
+    role: interactable.kind,
+    priority: interactable.priority,
+    promptText,
+    interactionKey: interactable.interactionKey,
+  });
+}
+
+function successfulInteraction(interactable) {
+  if (!interactable) return false;
+  return interactable.kind === 'pickup'
+    ? interactable.collected === true
+    : interactable.kind === 'lock'
+      ? interactable.opened === true
+      : interactable.activated === true;
+}
+
+export function createAdventureInteractable2D(definition = {}, index = 0) {
+  return normalizeInteractable(definition, index);
+}
+
+export function createAdventureInteractablesFromTilemapObjects2D(objects = [], defaults = {}) {
+  return (Array.isArray(objects) ? objects : []).map((object, index) => createAdventureInteractable2D({
+    id: normalizeText(object?.id != null ? String(object.id) : null, `object-${index + 1}`),
+    label: object?.name,
+    kind: normalizeText(object?.type, normalizeText(objectProperty(object, 'kind'), defaults.kind)),
+    x: finite(object?.worldX ?? object?.x),
+    y: finite(object?.worldY ?? object?.y),
+    width: finite(object?.width, defaults.width),
+    height: finite(object?.height, defaults.height),
+    point: object?.point === true,
+    promptText: normalizeText(objectProperty(object, 'promptText'), defaults.promptText),
+    lockedPromptText: normalizeText(objectProperty(object, 'lockedPromptText'), defaults.lockedPromptText),
+    requiredItemId: normalizeText(objectProperty(object, 'requiredItemId'), defaults.requiredItemId),
+    requiredQuantity: finite(objectProperty(object, 'requiredQuantity'), defaults.requiredQuantity),
+    checkpointId: normalizeText(objectProperty(object, 'checkpointId'), defaults.checkpointId),
+  }, index));
+}
+
+export function createAdventureInteractionState2D(options = {}) {
+  return {
+    tracker: createTriggerTracker({ subjectId: normalizeText(options.subjectId, 'player'), dimension: '2d' }),
+    prompt: createInteractionPromptState({ prompt: normalizeText(options.prompt, 'Interact') }),
+    activeCheckpointId: normalizeText(options.activeCheckpointId),
+    lastResult: null,
+  };
+}
+
+export function stepAdventureInteractables2D(
+  state,
+  subjectBounds,
+  interactables = [],
+  options = {},
+) {
+  const inventory = options.inventory || null;
+  const normalized = (Array.isArray(interactables) ? interactables : []).map((entry, index) => createAdventureInteractable2D(entry, index));
+  const triggers = normalized
+    .map((entry) => buildTrigger(entry, inventory))
+    .filter(Boolean);
+  const triggerStep = stepRectTriggers2D(state?.tracker, subjectBounds, triggers);
+  updateInteractionPromptState(state.prompt, triggerStep, {
+    interactPressed: options.interactPressed === true,
+  });
+
+  const result = {
+    reasonCode: state.prompt.reasonCode,
+    acceptedId: state.prompt.acceptedTriggerId || null,
+    collectedIds: [],
+    openedIds: [],
+    activatedIds: [],
+    checkpointId: null,
+    promptText: state.prompt.prompt,
+  };
+
+  if (!result.acceptedId) {
+    state.lastResult = result;
+    return result;
+  }
+
+  const interactable = normalized.find((entry) => entry.id === result.acceptedId) || null;
+  if (!interactable) {
+    state.lastResult = result;
+    return result;
+  }
+
+  if (interactable.kind === 'pickup') {
+    if (!interactable.collected && interactable.grantItem && inventory) {
+      addInventoryItem2D(inventory, interactable.grantItem);
+    }
+    interactable.collected = true;
+    result.collectedIds.push(interactable.id);
+  } else if (interactable.kind === 'lock') {
+    const unlocked = !interactable.requiredItemId
+      || hasInventoryItem2D(inventory, interactable.requiredItemId, interactable.requiredQuantity);
+    if (!unlocked) {
+      result.reasonCode = 'interaction_locked';
+      state.lastResult = result;
+      return result;
+    }
+    if (interactable.consumeRequiredItem === true && interactable.requiredItemId) {
+      removeInventoryItem2D(inventory, interactable.requiredItemId, interactable.requiredQuantity);
+    }
+    interactable.opened = true;
+    result.openedIds.push(interactable.id);
+  } else if (interactable.kind === 'checkpoint') {
+    interactable.activated = true;
+    state.activeCheckpointId = interactable.checkpointId;
+    result.checkpointId = interactable.checkpointId;
+    result.activatedIds.push(interactable.id);
+  } else {
+    interactable.activated = true;
+    result.activatedIds.push(interactable.id);
+  }
+
+  if (interactable.once === true && successfulInteraction(interactable) && interactable.kind !== 'checkpoint') {
+    interactable.disabled = true;
+  }
+  if (result.reasonCode === 'interaction_accepted') {
+    result.reasonCode = `interaction_${interactable.kind}_accepted`;
+  }
+  state.lastResult = result;
+  return result;
+}

package/src/helpers/starter-utils/animation-2d.js

@@ -0,0 +1,337 @@
+let nextSpriteLibraryId = 1;
+let nextSpriteAnimatorId = 1;
+
+function finite(value, fallback = 0) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : fallback;
+}
+
+function positiveNumber(value, fallback, label) {
+  const numeric = finite(value, fallback);
+  if (!(numeric > 0)) {
+    throw new Error(`${label} must be a positive number.`);
+  }
+  return numeric;
+}
+
+function normalizeIdentifier(value, fallbackPrefix) {
+  const raw = typeof value === 'string' && value.trim().length > 0
+    ? value.trim()
+    : `${fallbackPrefix}-${nextSpriteLibraryId}`;
+  const normalized = raw
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return normalized || `${fallbackPrefix}-${nextSpriteLibraryId}`;
+}
+
+function normalizeStateName(value) {
+  const name = typeof value === 'string' ? value.trim() : '';
+  if (!name) {
+    throw new Error('sprite animation state names must be non-empty strings.');
+  }
+  return name;
+}
+
+function normalizeFrameEntry(value, stateName) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(`sprite animation state "${stateName}" must use non-negative integer frame indices.`);
+  }
+  return value;
+}
+
+function buildFrameSequence(spec, stateName) {
+  if (Array.isArray(spec)) {
+    if (spec.length === 0) {
+      throw new Error(`sprite animation state "${stateName}" must include at least one frame.`);
+    }
+    return spec.map((entry) => normalizeFrameEntry(entry, stateName));
+  }
+
+  if (Number.isInteger(spec) && spec >= 0) {
+    return [spec];
+  }
+
+  const from = Number.isInteger(spec?.from) ? spec.from : null;
+  const count = Number.isInteger(spec?.count) ? spec.count : null;
+  if (from != null && count != null) {
+    if (from < 0 || count <= 0) {
+      throw new Error(`sprite animation state "${stateName}" must use a non-negative from index and positive count.`);
+    }
+    return Array.from({ length: count }, (_, index) => from + index);
+  }
+
+  if (Array.isArray(spec?.frames)) {
+    if (spec.frames.length === 0) {
+      throw new Error(`sprite animation state "${stateName}" must include at least one frame.`);
+    }
+    return spec.frames.map((entry) => normalizeFrameEntry(entry, stateName));
+  }
+
+  if (Number.isInteger(spec?.frame) && spec.frame >= 0) {
+    return [spec.frame];
+  }
+
+  throw new Error(`sprite animation state "${stateName}" must declare frames or from/count.`);
+}
+
+function normalizeStateSpec(stateName, spec, defaultFrameDuration) {
+  const frames = buildFrameSequence(spec, stateName);
+  return {
+    frames,
+    frameDuration: positiveNumber(spec?.frameDuration, defaultFrameDuration, `sprite animation state "${stateName}" frameDuration`),
+    loop: spec?.loop !== false,
+  };
+}
+
+function clipNameForState(library, stateName) {
+  return `${library.libraryId}__${stateName}`;
+}
+
+function libraryStateEntries(library) {
+  return Object.entries(library.states || {});
+}
+
+function resolveMachineState(runtime, animator) {
+  return runtime.aura.anim2d.getState(animator.machineId);
+}
+
+function resolveLibraryFromRuntime(runtime, animator) {
+  return runtime.libraries.get(animator.libraryId) || null;
+}
+
+function resolveFrameRect(library, frameIndex) {
+  const frame = Number.isInteger(frameIndex) && frameIndex >= 0 ? frameIndex : 0;
+  const column = frame % library.columns;
+  const row = Math.floor(frame / library.columns);
+  return {
+    frame,
+    frameX: column * library.frameWidth,
+    frameY: row * library.frameHeight,
+    frameW: library.frameWidth,
+    frameH: library.frameHeight,
+  };
+}
+
+function requireAnim2d(aura) {
+  if (
+    !aura?.anim2d
+    || typeof aura.anim2d.registerClip !== 'function'
+    || typeof aura.anim2d.createMachine !== 'function'
+    || typeof aura.anim2d.defineState !== 'function'
+    || typeof aura.anim2d.play !== 'function'
+    || typeof aura.anim2d.update !== 'function'
+    || typeof aura.anim2d.getState !== 'function'
+  ) {
+    throw new Error('sprite animation helpers require aura.anim2d register/create/define/play/update/getState support.');
+  }
+}
+
+export function createSpriteAnimationLibrary2D(options = {}) {
+  const image = typeof options.image === 'string' && options.image.trim().length > 0
+    ? options.image.trim()
+    : null;
+  if (!image) {
+    throw new Error('sprite animation library image is required.');
+  }
+
+  const frameWidth = positiveNumber(options.frameWidth, 0, 'sprite animation frameWidth');
+  const frameHeight = positiveNumber(options.frameHeight, 0, 'sprite animation frameHeight');
+  const columns = Math.max(1, Math.floor(positiveNumber(options.columns, 1, 'sprite animation columns')));
+  const defaultFrameDuration = positiveNumber(options.defaultFrameDuration, 1 / 12, 'sprite animation defaultFrameDuration');
+  const anchorX = finite(options.anchorX, 0.5);
+  const anchorY = finite(options.anchorY, 0.5);
+  const rawStates = options.states && typeof options.states === 'object' ? options.states : null;
+
+  if (!rawStates || Object.keys(rawStates).length === 0) {
+    throw new Error('sprite animation libraries must declare at least one state.');
+  }
+
+  const states = {};
+  for (const [rawStateName, spec] of Object.entries(rawStates)) {
+    const stateName = normalizeStateName(rawStateName);
+    states[stateName] = normalizeStateSpec(stateName, spec, defaultFrameDuration);
+  }
+
+  const orderedStateNames = Object.keys(states);
+  const defaultState = (
+    typeof options.defaultState === 'string'
+    && Object.prototype.hasOwnProperty.call(states, options.defaultState.trim())
+      ? options.defaultState.trim()
+      : orderedStateNames[0]
+  );
+  const name = typeof options.name === 'string' && options.name.trim().length > 0
+    ? options.name.trim()
+    : image;
+  const libraryId = `sprite-lib-${nextSpriteLibraryId}-${normalizeIdentifier(name, 'sprite-lib')}`;
+  nextSpriteLibraryId += 1;
+
+  return {
+    libraryId,
+    name,
+    image,
+    frameWidth,
+    frameHeight,
+    columns,
+    anchorX,
+    anchorY,
+    defaultFrameDuration,
+    defaultState,
+    states,
+  };
+}
+
+export function hasSpriteAnimationState2D(library, stateName) {
+  return !!library && typeof stateName === 'string' && Object.prototype.hasOwnProperty.call(library.states || {}, stateName);
+}
+
+export function createSpriteAnimationRuntime2D(aura) {
+  requireAnim2d(aura);
+  return {
+    aura,
+    libraries: new Map(),
+    registeredLibraries: new Set(),
+    animators: new Map(),
+  };
+}
+
+export function registerSpriteAnimationLibrary2D(runtime, library) {
+  if (!runtime?.aura) {
+    throw new Error('sprite animation runtime is required.');
+  }
+  requireAnim2d(runtime.aura);
+  if (!library?.libraryId) {
+    throw new Error('sprite animation library is required.');
+  }
+  runtime.libraries.set(library.libraryId, library);
+  if (runtime.registeredLibraries.has(library.libraryId)) {
+    return true;
+  }
+
+  for (const [stateName, state] of libraryStateEntries(library)) {
+    const registered = runtime.aura.anim2d.registerClip(
+      clipNameForState(library, stateName),
+      state.frames,
+      {
+        frameDuration: state.frameDuration,
+        loop: state.loop,
+      },
+    );
+    if (registered !== true) {
+      return false;
+    }
+  }
+
+  runtime.registeredLibraries.add(library.libraryId);
+  return true;
+}
+
+export function createSpriteAnimator2D(runtime, library, options = {}) {
+  if (registerSpriteAnimationLibrary2D(runtime, library) !== true) {
+    throw new Error(`failed to register sprite animation library "${library?.libraryId || 'unknown'}".`);
+  }
+
+  const machineId = runtime.aura.anim2d.createMachine(null);
+  for (const [stateName] of libraryStateEntries(library)) {
+    const defined = runtime.aura.anim2d.defineState(machineId, stateName, clipNameForState(library, stateName));
+    if (defined !== true) {
+      throw new Error(`failed to define sprite animation state "${stateName}".`);
+    }
+  }
+
+  const initialState = hasSpriteAnimationState2D(library, options.initialState) ? options.initialState : library.defaultState;
+  const animator = {
+    animatorId: nextSpriteAnimatorId,
+    libraryId: library.libraryId,
+    machineId,
+    defaultState: initialState,
+  };
+  nextSpriteAnimatorId += 1;
+  runtime.animators.set(animator.animatorId, animator);
+
+  if (initialState) {
+    runtime.aura.anim2d.play(machineId, initialState);
+  }
+
+  return animator;
+}
+
+export function playSpriteAnimator2D(runtime, animator, stateName) {
+  if (!hasSpriteAnimationState2D(resolveLibraryFromRuntime(runtime, animator), stateName)) {
+    return false;
+  }
+  return runtime.aura.anim2d.play(animator.machineId, stateName) === true;
+}
+
+export function syncSpriteAnimatorState2D(runtime, animator, stateName) {
+  const snapshot = resolveMachineState(runtime, animator);
+  if (snapshot?.state === stateName) {
+    return true;
+  }
+  return playSpriteAnimator2D(runtime, animator, stateName);
+}
+
+export function stepSpriteAnimationRuntime2D(runtime, dt) {
+  runtime.aura.anim2d.update(dt);
+  return true;
+}
+
+export function getSpriteAnimatorState2D(runtime, animator) {
+  return resolveMachineState(runtime, animator);
+}
+
+export function resolveSpriteAnimatorFrame2D(runtime, animator) {
+  const library = resolveLibraryFromRuntime(runtime, animator);
+  const snapshot = resolveMachineState(runtime, animator);
+  if (!library || !snapshot) {
+    return null;
+  }
+
+  return {
+    ...snapshot,
+    image: library.image,
+    anchorX: library.anchorX,
+    anchorY: library.anchorY,
+    ...resolveFrameRect(library, snapshot.frame),
+  };
+}
+
+export function drawSpriteAnimator2D(runtime, animator, x, y, options = {}) {
+  const frame = resolveSpriteAnimatorFrame2D(runtime, animator);
+  if (!frame || typeof runtime?.aura?.draw2d?.sprite !== 'function') {
+    return false;
+  }
+
+  const width = positiveNumber(options.width, frame.frameW, 'sprite draw width');
+  const height = positiveNumber(options.height, frame.frameH, 'sprite draw height');
+  const anchorX = finite(options.anchorX, frame.anchorX);
+  const anchorY = finite(options.anchorY, frame.anchorY);
+  const spriteOptions = { ...options };
+  delete spriteOptions.anchorX;
+  delete spriteOptions.anchorY;
+  delete spriteOptions.width;
+  delete spriteOptions.height;
+
+  runtime.aura.draw2d.sprite(
+    frame.image,
+    x - (width * anchorX),
+    y - (height * anchorY),
+    {
+      ...spriteOptions,
+      width,
+      height,
+      frameX: frame.frameX,
+      frameY: frame.frameY,
+      frameW: frame.frameW,
+      frameH: frame.frameH,
+    },
+  );
+  return true;
+}
+
+export function resolveSpriteFrameRect2D(library, frameIndex) {
+  if (!library?.libraryId) {
+    throw new Error('sprite animation library is required.');
+  }
+  return resolveFrameRect(library, frameIndex);
+}