@auraindustry/aurajs 0.1.1 → 0.1.5

package/src/helpers/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/src/helpers/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,
+    },
+  })
+}

package/src/helpers/starter-utils/autoplay-debug-2d.js

@@ -0,0 +1,215 @@
+function finite(value, fallback = 0) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : fallback;
+}
+
+function keyName(value, fallback) {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : fallback;
+}
+
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+
+function normalizeAutoplayAxis(axis) {
+  return {
+    x: clamp(finite(axis?.x, 0), -1, 1),
+    y: clamp(finite(axis?.y, 0), -1, 1),
+  };
+}
+
+function normalizeAutoplayControl(control) {
+  return {
+    axis: normalizeAutoplayAxis(control?.axis),
+    aimAngle: Number.isFinite(Number(control?.aimAngle)) ? Number(control.aimAngle) : null,
+    fire: control?.fire === true,
+    dash: control?.dash === true,
+    extract: control?.extract === true,
+    weaponIndex: Number.isFinite(Number(control?.weaponIndex))
+      ? Math.max(0, Math.floor(Number(control.weaponIndex)))
+      : null,
+  };
+}
+
+export function createAutoplayController2D(options = {}) {
+  return {
+    enabled: options.enabled === true,
+    frameCount: Math.max(0, Math.floor(finite(options.frameCount, 0))),
+    lastReasonCode: keyName(options.lastReasonCode, 'autoplay_idle'),
+    lastControl: options.lastControl ? normalizeAutoplayControl(options.lastControl) : null,
+    buildControl: typeof options.buildControl === 'function' ? options.buildControl : null,
+  };
+}
+
+export function setAutoplayEnabled2D(controller, enabled = true) {
+  if (!controller || typeof controller !== 'object') {
+    throw new Error('autoplay controller is required.');
+  }
+  controller.enabled = enabled === true;
+  controller.lastReasonCode = controller.enabled ? 'autoplay_enabled' : 'autoplay_disabled';
+  return {
+    ok: true,
+    enabled: controller.enabled,
+    reasonCode: controller.lastReasonCode,
+  };
+}
+
+export function toggleAutoplayEnabled2D(controller) {
+  if (!controller || typeof controller !== 'object') {
+    throw new Error('autoplay controller is required.');
+  }
+  return setAutoplayEnabled2D(controller, controller.enabled !== true);
+}
+
+export function resolveAutoplayControl2D(controller, context = {}, buildControl = null) {
+  if (!controller || typeof controller !== 'object') {
+    throw new Error('autoplay controller is required.');
+  }
+  if (controller.enabled !== true) {
+    controller.lastReasonCode = 'autoplay_disabled';
+    return {
+      ok: true,
+      enabled: false,
+      reasonCode: controller.lastReasonCode,
+      frameCount: controller.frameCount,
+      control: null,
+    };
+  }
+
+  const builder = typeof buildControl === 'function' ? buildControl : controller.buildControl;
+  if (typeof builder !== 'function') {
+    controller.lastReasonCode = 'autoplay_builder_missing';
+    return {
+      ok: false,
+      enabled: true,
+      reasonCode: controller.lastReasonCode,
+      frameCount: controller.frameCount,
+      control: null,
+    };
+  }
+
+  try {
+    controller.frameCount += 1;
+    const control = normalizeAutoplayControl(builder(context, controller) || {});
+    controller.lastControl = control;
+    controller.lastReasonCode = 'autoplay_control_ready';
+    return {
+      ok: true,
+      enabled: true,
+      reasonCode: controller.lastReasonCode,
+      frameCount: controller.frameCount,
+      control,
+    };
+  } catch (error) {
+    controller.lastReasonCode = 'autoplay_builder_failed';
+    return {
+      ok: false,
+      enabled: true,
+      reasonCode: controller.lastReasonCode,
+      frameCount: controller.frameCount,
+      control: controller.lastControl,
+      error: String(error && error.message ? error.message : error),
+    };
+  }
+}
+
+export function createRenderTargetExportState2D(options = {}) {
+  return {
+    queued: options.queued === true,
+    path: keyName(options.path, 'aura-export.png'),
+    lastExportReason: keyName(options.lastExportReason, 'draw2d_export_idle'),
+    lastExportOk: options.lastExportOk !== false,
+    exportCount: Math.max(0, Math.floor(finite(options.exportCount, 0))),
+  };
+}
+
+export function queueRenderTargetExport2D(exportState, options = {}) {
+  if (!exportState || typeof exportState !== 'object') {
+    throw new Error('render target export state is required.');
+  }
+  exportState.queued = true;
+  exportState.path = keyName(options.path, exportState.path || 'aura-export.png');
+  return {
+    ok: true,
+    queued: true,
+    path: exportState.path,
+    reasonCode: 'draw2d_render_target_export_queued',
+  };
+}
+
+export function flushRenderTargetExport2D(exportState, renderTarget, aura, options = {}) {
+  if (!exportState || typeof exportState !== 'object') {
+    throw new Error('render target export state is required.');
+  }
+
+  const path = keyName(options.path, exportState.path || 'aura-export.png');
+  exportState.path = path;
+
+  if (exportState.queued !== true) {
+    return {
+      ok: true,
+      exported: false,
+      queued: false,
+      path,
+      reasonCode: 'draw2d_render_target_export_not_queued',
+    };
+  }
+
+  exportState.queued = false;
+
+  if (!renderTarget || typeof renderTarget !== 'object') {
+    exportState.lastExportReason = 'invalid_export_target';
+    exportState.lastExportOk = false;
+    return {
+      ok: false,
+      exported: false,
+      queued: false,
+      path,
+      reasonCode: exportState.lastExportReason,
+    };
+  }
+
+  if (!aura?.draw2d || typeof aura.draw2d.exportRenderTarget !== 'function') {
+    exportState.lastExportReason = 'draw2d_export_unavailable';
+    exportState.lastExportOk = false;
+    return {
+      ok: false,
+      exported: false,
+      queued: false,
+      path,
+      reasonCode: exportState.lastExportReason,
+    };
+  }
+
+  try {
+    const result = aura.draw2d.exportRenderTarget(renderTarget, path) || null;
+    const reasonCode = keyName(result?.reasonCode, 'draw2d_render_target_export_queued');
+    const ok = result?.ok !== false
+      && reasonCode !== 'unsupported_export_format'
+      && reasonCode !== 'invalid_export_target';
+    exportState.lastExportReason = reasonCode;
+    exportState.lastExportOk = ok;
+    if (ok) {
+      exportState.exportCount += 1;
+    }
+    return {
+      ok,
+      exported: ok,
+      queued: false,
+      path: keyName(result?.path, path),
+      reasonCode,
+      result,
+    };
+  } catch (error) {
+    exportState.lastExportReason = 'draw2d_render_target_export_failed';
+    exportState.lastExportOk = false;
+    return {
+      ok: false,
+      exported: false,
+      queued: false,
+      path,
+      reasonCode: exportState.lastExportReason,
+      error: String(error && error.message ? error.message : error),
+    };
+  }
+}