@auraindustry/aurajs 0.1.3 → 0.1.5

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

@@ -0,0 +1,615 @@
+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 positiveInteger(value, fallback, label) {
+  const numeric = Math.floor(finite(value, fallback));
+  if (!(numeric >= 1)) {
+    throw new Error(`${label} must be a positive integer.`);
+  }
+  return numeric;
+}
+
+function normalizePath(path) {
+  if (Array.isArray(path) && path.length > 0) {
+    return path.map((segment) => {
+      if ((typeof segment !== 'string' && typeof segment !== 'number') || String(segment).length === 0) {
+        throw new Error('tween path segments must be non-empty strings or numbers.');
+      }
+      return String(segment);
+    });
+  }
+
+  if (typeof path === 'string' && path.trim().length > 0) {
+    return path
+      .split('.')
+      .map((segment) => segment.trim())
+      .filter(Boolean);
+  }
+
+  throw new Error('tween path must be a non-empty string or path array.');
+}
+
+function getPathParent(target, pathSegments) {
+  let current = target;
+  for (let index = 0; index < pathSegments.length - 1; index += 1) {
+    const key = pathSegments[index];
+    if (!current || typeof current !== 'object' || !(key in current)) {
+      throw new Error(`tween path "${pathSegments.join('.')}" is missing segment "${key}".`);
+    }
+    current = current[key];
+  }
+  return current;
+}
+
+function getNumericPathValue(target, pathSegments) {
+  const parent = getPathParent(target, pathSegments);
+  const key = pathSegments[pathSegments.length - 1];
+  const value = parent?.[key];
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) {
+    throw new Error(`tween path "${pathSegments.join('.')}" must resolve to a finite numeric value.`);
+  }
+  return numeric;
+}
+
+function setNumericPathValue(target, pathSegments, value) {
+  const parent = getPathParent(target, pathSegments);
+  const key = pathSegments[pathSegments.length - 1];
+  parent[key] = value;
+}
+
+function normalizeEasing(value, fallback = 'linear') {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    return fallback;
+  }
+  return value.trim();
+}
+
+function clonePlan(plan) {
+  return JSON.parse(JSON.stringify(plan));
+}
+
+function buildPlanState(motionId) {
+  return {
+    motionId,
+    active: true,
+    completed: false,
+    cancelled: false,
+  };
+}
+
+function requireTween(aura) {
+  if (
+    !aura?.tween
+    || typeof aura.tween.create !== 'function'
+    || typeof aura.tween.pause !== 'function'
+    || typeof aura.tween.resume !== 'function'
+    || typeof aura.tween.cancel !== 'function'
+    || typeof aura.tween.onUpdate !== 'function'
+    || typeof aura.tween.onComplete !== 'function'
+    || typeof aura.tween.update !== 'function'
+    || typeof aura.tween.getState !== 'function'
+  ) {
+    throw new Error('tween 2d helpers require aura.tween create/pause/resume/cancel/onUpdate/onComplete/update/getState support.');
+  }
+}
+
+function createController(onCancel = null) {
+  return {
+    active: true,
+    completed: false,
+    cancelled: false,
+    reversePlan: null,
+    listeners: [],
+    finish(reversePlan = null) {
+      if (!this.active) return;
+      this.active = false;
+      this.completed = true;
+      this.reversePlan = reversePlan ? clonePlan(reversePlan) : null;
+      for (const listener of this.listeners.splice(0)) {
+        listener(this);
+      }
+    },
+    cancel() {
+      if (!this.active) return false;
+      this.active = false;
+      this.cancelled = true;
+      if (typeof onCancel === 'function') {
+        onCancel();
+      }
+      for (const listener of this.listeners.splice(0)) {
+        listener(this);
+      }
+      return true;
+    },
+    onSettled(listener) {
+      if (typeof listener !== 'function') return;
+      if (!this.active) {
+        listener(this);
+        return;
+      }
+      this.listeners.push(listener);
+    },
+  };
+}
+
+function tweenResultOk(result, label) {
+  if (!result || result.ok !== true) {
+    throw new Error(`${label} failed: ${result?.reason || 'unknown_reason'}.`);
+  }
+  return result;
+}
+
+function propertyReversePlan(plan, from, to) {
+  return propertyTween2D(plan.path, {
+    from: to,
+    to: from,
+    duration: plan.duration,
+    easing: plan.easing,
+  });
+}
+
+function runTweenPlanInternal(runtime, target, plan) {
+  if (!plan || typeof plan !== 'object') {
+    throw new Error('tween plans must be plain objects.');
+  }
+
+  switch (plan.type) {
+    case 'property': {
+      const pathSegments = normalizePath(plan.path);
+      const from = Object.prototype.hasOwnProperty.call(plan, 'from')
+        ? finite(plan.from, NaN)
+        : getNumericPathValue(target, pathSegments);
+      if (!Number.isFinite(from)) {
+        throw new Error(`tween property "${pathSegments.join('.')}" must start from a finite numeric value.`);
+      }
+
+      let to = null;
+      if (Object.prototype.hasOwnProperty.call(plan, 'to')) {
+        to = finite(plan.to, NaN);
+      } else if (Object.prototype.hasOwnProperty.call(plan, 'by')) {
+        to = from + finite(plan.by, NaN);
+      }
+      if (!Number.isFinite(to)) {
+        throw new Error(`tween property "${pathSegments.join('.')}" must declare a finite "to" or "by" value.`);
+      }
+
+      const duration = positiveNumber(plan.duration, 0, `tween property "${pathSegments.join('.')}" duration`);
+      const easing = normalizeEasing(plan.easing, 'linear');
+      setNumericPathValue(target, pathSegments, from);
+      const created = tweenResultOk(
+        runtime.aura.tween.create({ from, to, duration, easing, playing: true }),
+        `tween property "${pathSegments.join('.')}" create`,
+      );
+      const tweenId = created.tweenId;
+      tweenResultOk(
+        runtime.aura.tween.onUpdate(tweenId, ({ value }) => {
+          setNumericPathValue(target, pathSegments, value);
+        }),
+        `tween property "${pathSegments.join('.')}" onUpdate`,
+      );
+
+      const controller = createController(() => {
+        runtime.aura.tween.cancel(tweenId);
+      });
+      tweenResultOk(
+        runtime.aura.tween.onComplete(tweenId, () => {
+          setNumericPathValue(target, pathSegments, to);
+          controller.finish(propertyReversePlan(plan, from, to));
+        }),
+        `tween property "${pathSegments.join('.')}" onComplete`,
+      );
+      return controller;
+    }
+    case 'delay': {
+      const duration = positiveNumber(plan.duration, 0, 'tween delay duration');
+      const created = tweenResultOk(
+        runtime.aura.tween.create({ from: 0, to: 1, duration, easing: 'linear', playing: true }),
+        'tween delay create',
+      );
+      const tweenId = created.tweenId;
+      const controller = createController(() => {
+        runtime.aura.tween.cancel(tweenId);
+      });
+      tweenResultOk(
+        runtime.aura.tween.onComplete(tweenId, () => {
+          controller.finish(delayTween2D(duration));
+        }),
+        'tween delay onComplete',
+      );
+      return controller;
+    }
+    case 'sequence': {
+      const steps = Array.isArray(plan.steps) ? plan.steps.slice() : [];
+      let activeChild = null;
+      const reverseSteps = [];
+      const controller = createController(() => {
+        activeChild?.cancel();
+      });
+      let index = 0;
+
+      const startNext = () => {
+        if (!controller.active) return;
+        if (index >= steps.length) {
+          controller.finish(reverseSteps.length > 0 ? sequenceTweens2D(reverseSteps.slice().reverse()) : null);
+          return;
+        }
+        activeChild = runTweenPlanInternal(runtime, target, steps[index]);
+        activeChild.onSettled((childState) => {
+          if (!controller.active) return;
+          if (childState.cancelled) {
+            controller.cancel();
+            return;
+          }
+          if (childState.reversePlan) {
+            reverseSteps.push(childState.reversePlan);
+          }
+          index += 1;
+          startNext();
+        });
+      };
+
+      startNext();
+      return controller;
+    }
+    case 'parallel': {
+      const steps = Array.isArray(plan.steps) ? plan.steps.slice() : [];
+      if (steps.length === 0) {
+        const controller = createController();
+        controller.finish(null);
+        return controller;
+      }
+
+      const children = [];
+      const reverseSteps = [];
+      let remaining = steps.length;
+      const controller = createController(() => {
+        for (const child of children) {
+          child.cancel();
+        }
+      });
+
+      for (const childPlan of steps) {
+        const child = runTweenPlanInternal(runtime, target, childPlan);
+        children.push(child);
+        child.onSettled((childState) => {
+          if (!controller.active) return;
+          if (childState.cancelled) {
+            controller.cancel();
+            return;
+          }
+          if (childState.reversePlan) {
+            reverseSteps.push(childState.reversePlan);
+          }
+          remaining -= 1;
+          if (remaining <= 0) {
+            controller.finish(reverseSteps.length > 0 ? parallelTweens2D(reverseSteps) : null);
+          }
+        });
+      }
+
+      return controller;
+    }
+    case 'repeat': {
+      const count = positiveInteger(plan.count, 1, 'repeat tween count');
+      let activeChild = null;
+      const reverseSteps = [];
+      let index = 0;
+      const controller = createController(() => {
+        activeChild?.cancel();
+      });
+
+      const runIteration = () => {
+        if (!controller.active) return;
+        if (index >= count) {
+          controller.finish(reverseSteps.length > 0 ? sequenceTweens2D(reverseSteps.slice().reverse()) : null);
+          return;
+        }
+        activeChild = runTweenPlanInternal(runtime, target, plan.step);
+        activeChild.onSettled((childState) => {
+          if (!controller.active) return;
+          if (childState.cancelled) {
+            controller.cancel();
+            return;
+          }
+          if (childState.reversePlan) {
+            reverseSteps.push(childState.reversePlan);
+          }
+          index += 1;
+          runIteration();
+        });
+      };
+
+      runIteration();
+      return controller;
+    }
+    case 'yoyo': {
+      const cycles = positiveInteger(plan.count, 1, 'yoyo tween count');
+      let activeChild = null;
+      let completedCycles = 0;
+      const controller = createController(() => {
+        activeChild?.cancel();
+      });
+
+      const runForward = () => {
+        if (!controller.active) return;
+        activeChild = runTweenPlanInternal(runtime, target, plan.step);
+        activeChild.onSettled((childState) => {
+          if (!controller.active) return;
+          if (childState.cancelled) {
+            controller.cancel();
+            return;
+          }
+          if (!childState.reversePlan) {
+            completedCycles += 1;
+            if (completedCycles >= cycles) {
+              controller.finish(null);
+            } else {
+              runForward();
+            }
+            return;
+          }
+          runReverse(childState.reversePlan);
+        });
+      };
+
+      const runReverse = (reversePlan) => {
+        if (!controller.active) return;
+        activeChild = runTweenPlanInternal(runtime, target, reversePlan);
+        activeChild.onSettled((childState) => {
+          if (!controller.active) return;
+          if (childState.cancelled) {
+            controller.cancel();
+            return;
+          }
+          completedCycles += 1;
+          if (completedCycles >= cycles) {
+            controller.finish(clonePlan(plan.step));
+            return;
+          }
+          runForward();
+        });
+      };
+
+      runForward();
+      return controller;
+    }
+    case 'settle': {
+      const pathSegments = normalizePath(plan.path);
+      const current = getNumericPathValue(target, pathSegments);
+      const targetValue = finite(plan.to, NaN);
+      if (!Number.isFinite(targetValue)) {
+        throw new Error(`settle tween "${pathSegments.join('.')}" requires a finite "to" value.`);
+      }
+      const duration = positiveNumber(plan.duration, 0, `settle tween "${pathSegments.join('.')}" duration`);
+      const overshoot = Math.abs(finite(plan.overshoot, 0.1));
+      const direction = current <= targetValue ? 1 : -1;
+      const overshootValue = targetValue + (overshoot * direction);
+      const sequence = sequenceTweens2D([
+        propertyTween2D(pathSegments, {
+          from: current,
+          to: overshootValue,
+          duration: duration * 0.45,
+          easing: normalizeEasing(plan.easingOut, 'easeOutCubic'),
+        }),
+        propertyTween2D(pathSegments, {
+          from: overshootValue,
+          to: targetValue,
+          duration: duration * 0.55,
+          easing: normalizeEasing(plan.easingIn, 'easeInOutQuad'),
+        }),
+      ]);
+      return runTweenPlanInternal(runtime, target, sequence);
+    }
+    default:
+      throw new Error(`unsupported tween plan type "${plan.type}".`);
+  }
+}
+
+export function propertyTween2D(path, options = {}) {
+  const plan = {
+    type: 'property',
+    path: normalizePath(path),
+    duration: positiveNumber(options.duration, 0, 'property tween duration'),
+    easing: normalizeEasing(options.easing, 'linear'),
+  };
+  if (Object.prototype.hasOwnProperty.call(options, 'from')) {
+    plan.from = finite(options.from, NaN);
+  }
+  if (Object.prototype.hasOwnProperty.call(options, 'to')) {
+    plan.to = finite(options.to, NaN);
+  }
+  if (Object.prototype.hasOwnProperty.call(options, 'by')) {
+    plan.by = finite(options.by, NaN);
+  }
+  return plan;
+}
+
+export function delayTween2D(duration) {
+  return {
+    type: 'delay',
+    duration: positiveNumber(duration, 0, 'delay tween duration'),
+  };
+}
+
+export function sequenceTweens2D(steps = []) {
+  return {
+    type: 'sequence',
+    steps: Array.isArray(steps) ? steps.map((step) => clonePlan(step)) : [],
+  };
+}
+
+export function parallelTweens2D(steps = []) {
+  return {
+    type: 'parallel',
+    steps: Array.isArray(steps) ? steps.map((step) => clonePlan(step)) : [],
+  };
+}
+
+export function repeatTween2D(step, count = 1) {
+  return {
+    type: 'repeat',
+    step: clonePlan(step),
+    count: positiveInteger(count, 1, 'repeat tween count'),
+  };
+}
+
+export function yoyoTween2D(step, count = 1) {
+  return {
+    type: 'yoyo',
+    step: clonePlan(step),
+    count: positiveInteger(count, 1, 'yoyo tween count'),
+  };
+}
+
+export function moveTo2D(options = {}) {
+  const duration = positiveNumber(options.duration, 0, 'moveTo2D duration');
+  const easing = normalizeEasing(options.easing, 'easeOutQuad');
+  const steps = [];
+  if (Number.isFinite(Number(options.x))) {
+    steps.push(propertyTween2D('x', { to: Number(options.x), duration, easing }));
+  }
+  if (Number.isFinite(Number(options.y))) {
+    steps.push(propertyTween2D('y', { to: Number(options.y), duration, easing }));
+  }
+  if (steps.length === 0) {
+    throw new Error('moveTo2D requires at least one of x or y.');
+  }
+  return steps.length === 1 ? steps[0] : parallelTweens2D(steps);
+}
+
+export function driftTo2D(options = {}) {
+  return moveTo2D({
+    ...options,
+    easing: normalizeEasing(options.easing, 'easeInOutQuad'),
+  });
+}
+
+export function fadeTo2D(options = {}) {
+  return propertyTween2D(options.path || 'alpha', {
+    to: finite(options.alpha, NaN),
+    duration: positiveNumber(options.duration, 0, 'fadeTo2D duration'),
+    easing: normalizeEasing(options.easing, 'linear'),
+  });
+}
+
+export function scaleTo2D(options = {}) {
+  return propertyTween2D(options.path || 'scale', {
+    to: finite(options.scale, NaN),
+    duration: positiveNumber(options.duration, 0, 'scaleTo2D duration'),
+    easing: normalizeEasing(options.easing, 'easeOutQuad'),
+  });
+}
+
+export function rotateTo2D(options = {}) {
+  return propertyTween2D(options.path || 'rotation', {
+    to: finite(options.rotation, NaN),
+    duration: positiveNumber(options.duration, 0, 'rotateTo2D duration'),
+    easing: normalizeEasing(options.easing, 'easeOutQuad'),
+  });
+}
+
+export function pulse2D(options = {}) {
+  const duration = positiveNumber(options.duration, 0.18, 'pulse2D duration');
+  return yoyoTween2D(
+    propertyTween2D(options.path || 'scale', {
+      by: finite(options.amount, 0.08),
+      duration: duration * 0.5,
+      easing: normalizeEasing(options.easing, 'easeOutQuad'),
+    }),
+    positiveInteger(options.repeats, 1, 'pulse2D repeats'),
+  );
+}
+
+export function punch2D(options = {}) {
+  const duration = positiveNumber(options.duration, 0.14, 'punch2D duration');
+  return yoyoTween2D(
+    propertyTween2D(options.path || 'scale', {
+      by: finite(options.amount, 0.12),
+      duration: duration * 0.5,
+      easing: normalizeEasing(options.easing, 'easeOutCubic'),
+    }),
+    positiveInteger(options.repeats, 1, 'punch2D repeats'),
+  );
+}
+
+export function settleTo2D(options = {}) {
+  return {
+    type: 'settle',
+    path: normalizePath(options.path || 'y'),
+    to: finite(options.to, NaN),
+    overshoot: Math.abs(finite(options.overshoot, 0.12)),
+    duration: positiveNumber(options.duration, 0.24, 'settleTo2D duration'),
+    easingOut: normalizeEasing(options.easingOut, 'easeOutCubic'),
+    easingIn: normalizeEasing(options.easingIn, 'easeInOutQuad'),
+  };
+}
+
+export function createTweenComposer2D(aura) {
+  requireTween(aura);
+  return {
+    aura,
+    nextMotionId: 1,
+    motions: new Map(),
+  };
+}
+
+export function playTweenPlan2D(runtime, target, plan, options = {}) {
+  if (!runtime?.aura) {
+    throw new Error('tween composer runtime is required.');
+  }
+  const motionId = runtime.nextMotionId++;
+  const controller = runTweenPlanInternal(runtime, target, plan);
+  const state = buildPlanState(motionId);
+  const handle = {
+    motionId,
+    target,
+    plan: clonePlan(plan),
+    state,
+    cancel() {
+      if (!state.active) return false;
+      controller.cancel();
+      return true;
+    },
+  };
+
+  runtime.motions.set(motionId, handle);
+  controller.onSettled((controllerState) => {
+    state.active = false;
+    state.completed = controllerState.completed;
+    state.cancelled = controllerState.cancelled;
+    runtime.motions.delete(motionId);
+    if (controllerState.completed && typeof options.onComplete === 'function') {
+      options.onComplete(handle);
+    }
+  });
+  return handle;
+}
+
+export function cancelTweenPlan2D(runtime, handle) {
+  if (!runtime?.motions || !handle?.motionId) return false;
+  const active = runtime.motions.get(handle.motionId);
+  return active ? active.cancel() : false;
+}
+
+export function stepTweenComposer2D(runtime, dt) {
+  return runtime.aura.tween.update(dt);
+}
+
+export function getTweenHandleState2D(handle) {
+  return handle?.state ? { ...handle.state } : null;
+}
+
+export function isTweenHandleActive2D(handle) {
+  return handle?.state?.active === true;
+}

package/src/helpers/starter-utils/wave-director.js

@@ -0,0 +1,101 @@
+import { createIntervalSpawner, tickIntervalSpawner } from './core.js';
+
+export function createWaveDirector(options = {}) {
+  const waves = Array.isArray(options.waves) ? options.waves : [];
+  const loop = options.loop === true;
+  const initialDelay = Math.max(0, Number(options.initialDelay) || 0);
+  const betweenWaveDelay = Math.max(0, Number(options.betweenWaveDelay) || 0);
+
+  return {
+    waves,
+    loop,
+    initialDelay,
+    betweenWaveDelay,
+    delayRemaining: initialDelay,
+    waveIndex: 0,
+    waveElapsed: 0,
+    waveSpawned: 0,
+    activeSpawner: null,
+    completed: waves.length === 0,
+  };
+}
+
+export function activeWave(director) {
+  if (!director || director.completed) return null;
+  return director.waves[director.waveIndex] || null;
+}
+
+export function stepWaveDirector(director, dt, onSpawn = null) {
+  if (!director || director.completed) {
+    return { spawned: 0, waveIndex: -1, completed: true };
+  }
+
+  const frameDt = Math.max(0, Number(dt) || 0);
+  if (director.delayRemaining > 0) {
+    director.delayRemaining = Math.max(0, director.delayRemaining - frameDt);
+    return { spawned: 0, waveIndex: director.waveIndex, completed: director.completed };
+  }
+
+  const wave = activeWave(director);
+  if (!wave) {
+    director.completed = true;
+    return { spawned: 0, waveIndex: -1, completed: true };
+  }
+
+  if (!director.activeSpawner) {
+    const interval = Math.max(0.04, Number(wave.spawnEvery) || 0.8);
+    director.activeSpawner = createIntervalSpawner(interval, { startReady: true });
+    director.waveElapsed = 0;
+    director.waveSpawned = 0;
+  }
+
+  director.waveElapsed += frameDt;
+
+  const maxSpawns = Number.isFinite(Number(wave.maxSpawns))
+    ? Math.max(0, Math.floor(Number(wave.maxSpawns)))
+    : Number.POSITIVE_INFINITY;
+  const maxDuration = Number.isFinite(Number(wave.durationSeconds))
+    ? Math.max(0, Number(wave.durationSeconds))
+    : Number.POSITIVE_INFINITY;
+
+  let spawned = 0;
+  tickIntervalSpawner(director.activeSpawner, frameDt, () => {
+    if (director.waveSpawned >= maxSpawns) return;
+    director.waveSpawned += 1;
+    spawned += 1;
+    if (typeof onSpawn === 'function') {
+      onSpawn({
+        waveIndex: director.waveIndex,
+        wave,
+        spawnedInWave: director.waveSpawned,
+      });
+    }
+  });
+
+  const waveDone = (
+    director.waveSpawned >= maxSpawns
+    || director.waveElapsed >= maxDuration
+  );
+
+  if (waveDone) {
+    director.waveIndex += 1;
+    if (director.waveIndex >= director.waves.length) {
+      if (director.loop) {
+        director.waveIndex = 0;
+      } else {
+        director.completed = true;
+      }
+    }
+
+    director.delayRemaining = director.completed ? 0 : director.betweenWaveDelay;
+    director.waveElapsed = 0;
+    director.waveSpawned = 0;
+    director.activeSpawner = null;
+  }
+
+  return {
+    spawned,
+    waveIndex: director.completed ? -1 : director.waveIndex,
+    completed: director.completed,
+  };
+}