@auraindustry/aurajs 0.1.3 → 0.1.5

package/templates/create/shared/src/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/templates/create/shared/src/starter-utils/animation-packaging-2d.js

@@ -0,0 +1,203 @@
+import {
+  createSpriteAnimationLibrary2D,
+  createSpriteAnimator2D,
+  hasSpriteAnimationState2D,
+  registerSpriteAnimationLibrary2D,
+} from './animation-2d.js'
+
+let nextAnimationPackageId = 1
+
+function normalizePackageName(value) {
+  if (typeof value === 'string' && value.trim().length > 0) {
+    return value.trim()
+  }
+  return `animation-package-${nextAnimationPackageId}`
+}
+
+function normalizePackageClipName(value) {
+  const name = typeof value === 'string' ? value.trim() : ''
+  if (!name) {
+    throw new Error('animation package clip names must be non-empty strings.')
+  }
+  return name
+}
+
+function normalizePackageStateName(value) {
+  const name = typeof value === 'string' ? value.trim() : ''
+  if (!name) {
+    throw new Error('animation package state names must be non-empty strings.')
+  }
+  return name
+}
+
+function normalizePackageStateSpec(stateName, spec, knownClips) {
+  if (typeof spec === 'string') {
+    const clip = spec.trim()
+    if (!knownClips.has(clip)) {
+      throw new Error(`animation package state "${stateName}" references unknown clip "${clip}".`)
+    }
+    return { clip }
+  }
+
+  if (!spec || typeof spec !== 'object') {
+    throw new Error(`animation package state "${stateName}" must be a clip name or object.`)
+  }
+
+  const clip = typeof spec.clip === 'string' ? spec.clip.trim() : ''
+  if (!clip) {
+    throw new Error(`animation package state "${stateName}" must declare a clip.`)
+  }
+  if (!knownClips.has(clip)) {
+    throw new Error(`animation package state "${stateName}" references unknown clip "${clip}".`)
+  }
+
+  const state = { clip }
+  if (spec.frameDuration != null) {
+    state.frameDuration = spec.frameDuration
+  }
+  if (spec.loop != null) {
+    state.loop = spec.loop
+  }
+  return state
+}
+
+function cloneClipSpec(clipName, spec) {
+  if (Array.isArray(spec)) {
+    if (spec.length === 0) {
+      throw new Error(`animation package clip "${clipName}" must include at least one frame.`)
+    }
+    return { frames: [...spec] }
+  }
+
+  if (Number.isInteger(spec) && spec >= 0) {
+    return { frame: spec }
+  }
+
+  if (!spec || typeof spec !== 'object') {
+    throw new Error(`animation package clip "${clipName}" must be an integer, frame array, or object.`)
+  }
+
+  const cloned = { ...spec }
+  if (Array.isArray(spec.frames)) {
+    if (spec.frames.length === 0) {
+      throw new Error(`animation package clip "${clipName}" must include at least one frame.`)
+    }
+    cloned.frames = [...spec.frames]
+  }
+  return cloned
+}
+
+function buildLibraryStates(packageDefinition) {
+  const states = {}
+  for (const [stateName, stateSpec] of Object.entries(packageDefinition.states)) {
+    const clipSpec = cloneClipSpec(stateSpec.clip, packageDefinition.clips[stateSpec.clip])
+    if (stateSpec.frameDuration != null) {
+      clipSpec.frameDuration = stateSpec.frameDuration
+    }
+    if (stateSpec.loop != null) {
+      clipSpec.loop = stateSpec.loop
+    }
+    states[stateName] = clipSpec
+  }
+  return states
+}
+
+export function createAnimationPackage2D(options = {}) {
+  const rawClips = options.clips && typeof options.clips === 'object' ? options.clips : null
+  const rawStates = options.states && typeof options.states === 'object' ? options.states : null
+
+  if (!rawClips || Object.keys(rawClips).length === 0) {
+    throw new Error('animation packages must declare at least one clip.')
+  }
+  if (!rawStates || Object.keys(rawStates).length === 0) {
+    throw new Error('animation packages must declare at least one state.')
+  }
+
+  const packageId = `anim-pack-${nextAnimationPackageId}`
+  nextAnimationPackageId += 1
+
+  const name = normalizePackageName(options.name)
+  const clips = {}
+  for (const [rawClipName, spec] of Object.entries(rawClips)) {
+    const clipName = normalizePackageClipName(rawClipName)
+    clips[clipName] = cloneClipSpec(clipName, spec)
+  }
+
+  const knownClips = new Set(Object.keys(clips))
+  const states = {}
+  for (const [rawStateName, spec] of Object.entries(rawStates)) {
+    const stateName = normalizePackageStateName(rawStateName)
+    states[stateName] = normalizePackageStateSpec(stateName, spec, knownClips)
+  }
+
+  const defaultState = (
+    typeof options.defaultState === 'string'
+    && Object.prototype.hasOwnProperty.call(states, options.defaultState.trim())
+      ? options.defaultState.trim()
+      : Object.keys(states)[0]
+  )
+  const source = options.source && typeof options.source === 'object'
+    ? { ...options.source }
+    : { type: 'inline-animation-package' }
+
+  const library = createSpriteAnimationLibrary2D({
+    image: options.image,
+    frameWidth: options.frameWidth,
+    frameHeight: options.frameHeight,
+    columns: options.columns,
+    anchorX: options.anchorX,
+    anchorY: options.anchorY,
+    defaultFrameDuration: options.defaultFrameDuration,
+    defaultState,
+    name,
+    states: buildLibraryStates({ clips, states }),
+  })
+
+  return {
+    packageId,
+    name,
+    defaultState: library.defaultState,
+    clips,
+    states,
+    library,
+    source,
+  }
+}
+
+export function hasAnimationPackageState2D(animationPackage, stateName) {
+  return !!animationPackage && typeof stateName === 'string'
+    && Object.prototype.hasOwnProperty.call(animationPackage.states || {}, stateName)
+}
+
+export function registerAnimationPackage2D(runtime, animationPackage) {
+  if (!animationPackage?.library) {
+    throw new Error('animation package is required.')
+  }
+  return registerSpriteAnimationLibrary2D(runtime, animationPackage.library)
+}
+
+export function createPackagedSpriteAnimator2D(runtime, animationPackage, options = {}) {
+  if (registerAnimationPackage2D(runtime, animationPackage) !== true) {
+    throw new Error(`failed to register animation package "${animationPackage?.packageId || 'unknown'}".`)
+  }
+
+  const initialState = hasAnimationPackageState2D(animationPackage, options.initialState)
+    ? options.initialState
+    : animationPackage.defaultState
+  const animator = createSpriteAnimator2D(runtime, animationPackage.library, { initialState })
+
+  return {
+    ...animator,
+    packageId: animationPackage.packageId,
+  }
+}
+
+export function getAnimationPackageLibrary2D(animationPackage) {
+  return animationPackage?.library || null
+}
+
+export function getAnimationPackageState2D(animationPackage, stateName) {
+  return hasAnimationPackageState2D(animationPackage, stateName)
+    ? animationPackage.states[stateName]
+    : null
+}

package/templates/create/shared/src/starter-utils/atlas-assets-2d.js

@@ -0,0 +1,111 @@
+import { createAnimationPackage2D } from './animation-packaging-2d.js'
+
+let nextAtlasAssetManifestId = 1
+
+function cloneSpecMap(value, label) {
+  if (!value || typeof value !== 'object') {
+    throw new Error(`${label} must be an object.`)
+  }
+  const entries = Object.entries(value)
+  if (entries.length === 0) {
+    throw new Error(`${label} must not be empty.`)
+  }
+  return Object.fromEntries(entries.map(([key, spec]) => {
+    if (Array.isArray(spec)) {
+      return [key, [...spec]]
+    }
+    if (spec && typeof spec === 'object') {
+      return [key, { ...spec, frames: Array.isArray(spec.frames) ? [...spec.frames] : spec.frames }]
+    }
+    return [key, spec]
+  }))
+}
+
+function readPositiveNumber(value, fallback, label) {
+  const numeric = Number(value)
+  const resolved = Number.isFinite(numeric) ? numeric : fallback
+  if (!(resolved > 0)) {
+    throw new Error(`${label} must be a positive number.`)
+  }
+  return resolved
+}
+
+function readFiniteNumber(value, fallback) {
+  const numeric = Number(value)
+  return Number.isFinite(numeric) ? numeric : fallback
+}
+
+function normalizeAtlasManifestName(value, fallback) {
+  if (typeof value === 'string' && value.trim().length > 0) {
+    return value.trim()
+  }
+  return fallback
+}
+
+export function createAtlasAssetManifest2D(options = {}) {
+  const image = typeof options.image === 'string' && options.image.trim().length > 0
+    ? options.image.trim()
+    : null
+  if (!image) {
+    throw new Error('atlas asset manifest image is required.')
+  }
+
+  const manifest = options.manifest && typeof options.manifest === 'object'
+    ? options.manifest
+    : options
+  const name = normalizeAtlasManifestName(
+    options.name ?? manifest.name,
+    `atlas-asset-manifest-${nextAtlasAssetManifestId}`,
+  )
+  const atlasManifestId = `atlas-asset-manifest-${nextAtlasAssetManifestId}`
+  nextAtlasAssetManifestId += 1
+
+  return {
+    atlasManifestId,
+    assetType: 'atlasAssetManifest2d',
+    name,
+    image,
+    frameWidth: readPositiveNumber(manifest.frameWidth, 0, 'atlas asset manifest frameWidth'),
+    frameHeight: readPositiveNumber(manifest.frameHeight, 0, 'atlas asset manifest frameHeight'),
+    columns: Math.max(1, Math.floor(readPositiveNumber(manifest.columns, 1, 'atlas asset manifest columns'))),
+    defaultFrameDuration: readPositiveNumber(
+      manifest.defaultFrameDuration,
+      1 / 12,
+      'atlas asset manifest defaultFrameDuration',
+    ),
+    anchorX: readFiniteNumber(manifest.anchorX, 0.5),
+    anchorY: readFiniteNumber(manifest.anchorY, 0.5),
+    defaultState: typeof manifest.defaultState === 'string' ? manifest.defaultState.trim() : '',
+    clips: cloneSpecMap(manifest.clips, 'atlas asset manifest clips'),
+    states: cloneSpecMap(manifest.states, 'atlas asset manifest states'),
+  }
+}
+
+export function createAnimationPackageFromAtlasAsset2D(atlasAsset, overrides = {}) {
+  if (!atlasAsset?.atlasManifestId) {
+    throw new Error('atlas asset manifest is required.')
+  }
+
+  return createAnimationPackage2D({
+    name: normalizeAtlasManifestName(overrides.name, atlasAsset.name),
+    image: typeof overrides.image === 'string' && overrides.image.trim().length > 0
+      ? overrides.image.trim()
+      : atlasAsset.image,
+    frameWidth: overrides.frameWidth ?? atlasAsset.frameWidth,
+    frameHeight: overrides.frameHeight ?? atlasAsset.frameHeight,
+    columns: overrides.columns ?? atlasAsset.columns,
+    anchorX: overrides.anchorX ?? atlasAsset.anchorX,
+    anchorY: overrides.anchorY ?? atlasAsset.anchorY,
+    defaultFrameDuration: overrides.defaultFrameDuration ?? atlasAsset.defaultFrameDuration,
+    clips: cloneSpecMap(atlasAsset.clips, 'atlas asset manifest clips'),
+    states: cloneSpecMap(atlasAsset.states, 'atlas asset manifest states'),
+    defaultState: typeof overrides.defaultState === 'string' && overrides.defaultState.trim().length > 0
+      ? overrides.defaultState.trim()
+      : atlasAsset.defaultState,
+    source: {
+      type: 'atlas-asset-manifest',
+      atlasManifestId: atlasAsset.atlasManifestId,
+      image: atlasAsset.image,
+    },
+  })
+}