@auraindustry/aurajs 0.0.7 → 0.1.0

package/templates/create/shared/src/starter-utils/combat-feedback-2d.js

@@ -0,0 +1,320 @@
+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 clamp01(value) {
+  return Math.max(0, Math.min(1, finite(value, 0)));
+}
+
+const EPSILON = 1e-9;
+
+function easeOutQuad(value) {
+  const t = clamp01(value);
+  return t * (2 - t);
+}
+
+function defaultTextAlign(value, fallback = 'center') {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : fallback;
+}
+
+export function createFloatingTextLayer2D(options = {}) {
+  return {
+    nextId: 1,
+    entries: [],
+    maxEntries: positiveInteger(options.maxEntries, 32, 'floating text maxEntries'),
+    defaultRise: positiveNumber(options.rise, 28, 'floating text rise'),
+    defaultLifetime: positiveNumber(options.lifetime, 0.6, 'floating text lifetime'),
+    defaultSize: positiveNumber(options.size, 14, 'floating text size'),
+    defaultDriftX: finite(options.driftX, 0),
+    defaultAlign: defaultTextAlign(options.align, 'center'),
+    defaultColor: Object.prototype.hasOwnProperty.call(options, 'color') ? options.color : null,
+  };
+}
+
+function updateFloatingTextEntry(entry) {
+  const progress = clamp01(entry.elapsed / entry.lifetime);
+  entry.x = entry.baseX + (entry.driftX * progress);
+  entry.y = entry.baseY - (entry.rise * easeOutQuad(progress));
+  entry.alpha = 1 - progress;
+}
+
+export function spawnFloatingText2D(layer, options = {}) {
+  if (!layer?.entries || !Array.isArray(layer.entries)) {
+    throw new Error('floating text layer is required.');
+  }
+
+  const entry = {
+    id: layer.nextId++,
+    text: String(
+      Object.prototype.hasOwnProperty.call(options, 'text')
+        ? options.text
+        : (Object.prototype.hasOwnProperty.call(options, 'value') ? options.value : ''),
+    ),
+    baseX: finite(options.x, 0),
+    baseY: finite(options.y, 0),
+    x: finite(options.x, 0),
+    y: finite(options.y, 0),
+    driftX: finite(options.driftX, layer.defaultDriftX),
+    rise: positiveNumber(options.rise, layer.defaultRise, 'floating text rise'),
+    lifetime: positiveNumber(options.lifetime, layer.defaultLifetime, 'floating text lifetime'),
+    elapsed: 0,
+    size: positiveNumber(options.size, layer.defaultSize, 'floating text size'),
+    align: defaultTextAlign(options.align, layer.defaultAlign),
+    color: Object.prototype.hasOwnProperty.call(options, 'color') ? options.color : layer.defaultColor,
+    alpha: 1,
+  };
+
+  if (layer.entries.length >= layer.maxEntries) {
+    layer.entries.shift();
+  }
+  layer.entries.push(entry);
+  return entry;
+}
+
+export function stepFloatingTextLayer2D(layer, dt) {
+  if (!layer?.entries || !Array.isArray(layer.entries)) {
+    throw new Error('floating text layer is required.');
+  }
+
+  const stepDt = Math.max(0, finite(dt, 0));
+  for (let index = layer.entries.length - 1; index >= 0; index -= 1) {
+    const entry = layer.entries[index];
+    entry.elapsed = Math.min(entry.lifetime, entry.elapsed + stepDt);
+    updateFloatingTextEntry(entry);
+    if (entry.elapsed >= entry.lifetime) {
+      layer.entries.splice(index, 1);
+    }
+  }
+  return layer.entries.length;
+}
+
+export function getFloatingTextRenderState2D(entry) {
+  if (!entry) return null;
+  return {
+    id: entry.id,
+    text: entry.text,
+    x: entry.x,
+    y: entry.y,
+    size: entry.size,
+    align: entry.align,
+    color: entry.color,
+    alpha: entry.alpha,
+  };
+}
+
+export function drawFloatingTextLayer2D(aura, layer, options = {}) {
+  if (!aura?.draw2d || typeof aura.draw2d.text !== 'function') {
+    throw new Error('floating text drawing requires aura.draw2d.text support.');
+  }
+  if (!layer?.entries || !Array.isArray(layer.entries)) {
+    throw new Error('floating text layer is required.');
+  }
+
+  const resolveColor = typeof options.resolveColor === 'function' ? options.resolveColor : null;
+  let drawCount = 0;
+  for (const entry of layer.entries) {
+    const renderState = getFloatingTextRenderState2D(entry);
+    const color = resolveColor ? resolveColor(renderState, entry) : renderState.color;
+    aura.draw2d.text(renderState.text, renderState.x, renderState.y, {
+      size: renderState.size,
+      align: renderState.align,
+      color,
+    });
+    drawCount += 1;
+  }
+  return drawCount;
+}
+
+export function createHitFlash2D(options = {}) {
+  return {
+    duration: positiveNumber(options.duration, 0.4, 'hit flash duration'),
+    flashesPerSecond: positiveNumber(options.flashesPerSecond, 12, 'hit flash flashesPerSecond'),
+    timeRemaining: 0,
+    active: false,
+  };
+}
+
+export function triggerHitFlash2D(flash, options = {}) {
+  if (!flash || typeof flash !== 'object') {
+    throw new Error('hit flash state is required.');
+  }
+  flash.duration = positiveNumber(options.duration, flash.duration, 'hit flash duration');
+  flash.flashesPerSecond = positiveNumber(
+    options.flashesPerSecond,
+    flash.flashesPerSecond,
+    'hit flash flashesPerSecond',
+  );
+  flash.timeRemaining = flash.duration;
+  flash.active = true;
+  return flash.timeRemaining;
+}
+
+export function stepHitFlash2D(flash, dt) {
+  if (!flash || typeof flash !== 'object') {
+    throw new Error('hit flash state is required.');
+  }
+  const stepDt = Math.max(0, finite(dt, 0));
+  const remaining = flash.timeRemaining - stepDt;
+  flash.timeRemaining = remaining > EPSILON ? remaining : 0;
+  flash.active = flash.timeRemaining > 0;
+  return flash.timeRemaining;
+}
+
+export function isHitFlashVisible2D(flash) {
+  if (!flash?.active || !(flash.timeRemaining > 0)) return false;
+  return Math.floor(flash.timeRemaining * flash.flashesPerSecond) % 2 === 0;
+}
+
+export function createHitSparkLayer2D(options = {}) {
+  return {
+    nextId: 1,
+    bursts: [],
+    maxEntries: positiveInteger(options.maxEntries, 24, 'hit spark maxEntries'),
+    defaultCount: positiveInteger(options.count, 6, 'hit spark count'),
+    defaultRadius: positiveNumber(options.radius, 18, 'hit spark radius'),
+    defaultInnerRadius: positiveNumber(options.innerRadius, 2.5, 'hit spark innerRadius'),
+    defaultLifetime: positiveNumber(options.lifetime, 0.16, 'hit spark lifetime'),
+    defaultLineWidth: positiveNumber(options.lineWidth, 2, 'hit spark lineWidth'),
+    defaultColor: Object.prototype.hasOwnProperty.call(options, 'color') ? options.color : null,
+  };
+}
+
+export function spawnHitSpark2D(layer, options = {}) {
+  if (!layer?.bursts || !Array.isArray(layer.bursts)) {
+    throw new Error('hit spark layer is required.');
+  }
+
+  const count = positiveInteger(options.count, layer.defaultCount, 'hit spark count');
+  const rotation = finite(options.rotation, 0);
+  const burst = {
+    id: layer.nextId++,
+    x: finite(options.x, 0),
+    y: finite(options.y, 0),
+    radius: positiveNumber(options.radius, layer.defaultRadius, 'hit spark radius'),
+    innerRadius: positiveNumber(options.innerRadius, layer.defaultInnerRadius, 'hit spark innerRadius'),
+    lifetime: positiveNumber(options.lifetime, layer.defaultLifetime, 'hit spark lifetime'),
+    lineWidth: positiveNumber(options.lineWidth, layer.defaultLineWidth, 'hit spark lineWidth'),
+    elapsed: 0,
+    color: Object.prototype.hasOwnProperty.call(options, 'color') ? options.color : layer.defaultColor,
+    angles: Array.from({ length: count }, (_, index) => rotation + ((Math.PI * 2 * index) / count)),
+  };
+
+  if (layer.bursts.length >= layer.maxEntries) {
+    layer.bursts.shift();
+  }
+  layer.bursts.push(burst);
+  return burst;
+}
+
+export function stepHitSparkLayer2D(layer, dt) {
+  if (!layer?.bursts || !Array.isArray(layer.bursts)) {
+    throw new Error('hit spark layer is required.');
+  }
+
+  const stepDt = Math.max(0, finite(dt, 0));
+  for (let index = layer.bursts.length - 1; index >= 0; index -= 1) {
+    const burst = layer.bursts[index];
+    burst.elapsed = Math.min(burst.lifetime, burst.elapsed + stepDt);
+    if (burst.elapsed >= burst.lifetime) {
+      layer.bursts.splice(index, 1);
+    }
+  }
+  return layer.bursts.length;
+}
+
+function resolveHitSparkGeometry(burst) {
+  const progress = clamp01(burst.elapsed / burst.lifetime);
+  const eased = easeOutQuad(progress);
+  return {
+    progress,
+    alpha: 1 - progress,
+    innerRadius: burst.innerRadius * (1 - (progress * 0.35)),
+    reach: burst.radius * (0.45 + (eased * 0.55)),
+  };
+}
+
+export function drawHitSparkLayer2D(aura, layer, options = {}) {
+  if (!aura?.draw2d || typeof aura.draw2d.line !== 'function') {
+    throw new Error('hit spark drawing requires aura.draw2d.line support.');
+  }
+  if (!layer?.bursts || !Array.isArray(layer.bursts)) {
+    throw new Error('hit spark layer is required.');
+  }
+
+  const resolveColor = typeof options.resolveColor === 'function' ? options.resolveColor : null;
+  let drawCount = 0;
+  for (const burst of layer.bursts) {
+    const geometry = resolveHitSparkGeometry(burst);
+    const color = resolveColor ? resolveColor(burst, geometry) : burst.color;
+    if (typeof aura.draw2d.circleFill === 'function' && geometry.innerRadius > 0.25) {
+      aura.draw2d.circleFill(burst.x, burst.y, geometry.innerRadius, color);
+      drawCount += 1;
+    }
+    for (const angle of burst.angles) {
+      const startX = burst.x + (Math.cos(angle) * geometry.innerRadius);
+      const startY = burst.y + (Math.sin(angle) * geometry.innerRadius);
+      const endX = burst.x + (Math.cos(angle) * geometry.reach);
+      const endY = burst.y + (Math.sin(angle) * geometry.reach);
+      aura.draw2d.line(startX, startY, endX, endY, color, burst.lineWidth);
+      drawCount += 1;
+    }
+  }
+  return drawCount;
+}
+
+export function createHoverLift2D(options = {}) {
+  return {
+    active: false,
+    lift: positiveNumber(options.lift, 12, 'hover lift amount'),
+    bob: finite(options.bob, 1.5),
+    phase: finite(options.phase, 0),
+    travel: clamp01(options.travel),
+    travelSpeed: positiveNumber(options.travelSpeed, 12, 'hover lift travelSpeed'),
+    bobSpeed: positiveNumber(options.bobSpeed, 7, 'hover lift bobSpeed'),
+  };
+}
+
+export function setHoverLiftActive2D(state, active) {
+  if (!state || typeof state !== 'object') {
+    throw new Error('hover lift state is required.');
+  }
+  state.active = active === true;
+  return state.active;
+}
+
+export function stepHoverLift2D(state, dt) {
+  if (!state || typeof state !== 'object') {
+    throw new Error('hover lift state is required.');
+  }
+  const stepDt = Math.max(0, finite(dt, 0));
+  const targetTravel = state.active ? 1 : 0;
+  const mix = Math.min(1, stepDt * state.travelSpeed);
+  state.travel = state.travel + ((targetTravel - state.travel) * mix);
+  state.phase += stepDt * state.bobSpeed;
+  return getHoverLiftOffset2D(state);
+}
+
+export function getHoverLiftOffset2D(state) {
+  if (!state || typeof state !== 'object') {
+    throw new Error('hover lift state is required.');
+  }
+  const bobOffset = state.travel > 0 ? (Math.sin(state.phase) * state.bob * state.travel) : 0;
+  return -((state.lift * state.travel) + bobOffset);
+}

package/templates/create/shared/src/starter-utils/core.js

@@ -70,6 +70,27 @@ export function rectsOverlap(a, b) {
   );
 }
 
+function resolvePosition2D(value) {
+  if (!value || typeof value !== 'object') {
+    return { x: 0, y: 0 };
+  }
+  if (typeof value.x === 'number' && typeof value.y === 'number') {
+    return value;
+  }
+  if (value.position && typeof value.position === 'object') {
+    return resolvePosition2D(value.position);
+  }
+  return { x: 0, y: 0 };
+}
+
+export function distanceSquared2D(a, b) {
+  const left = resolvePosition2D(a);
+  const right = resolvePosition2D(b);
+  const dx = left.x - right.x;
+  const dy = left.y - right.y;
+  return (dx * dx) + (dy * dy);
+}
+
 export function removeWhere(items, predicate) {
   let removed = 0;
   for (let i = items.length - 1; i >= 0; i -= 1) {
@@ -80,10 +101,25 @@ export function removeWhere(items, predicate) {
   return removed;
 }
 
+function resolvePosition3D(value) {
+  if (!value || typeof value !== 'object') {
+    return { x: 0, y: 0, z: 0 };
+  }
+  if (typeof value.x === 'number' && typeof value.y === 'number' && typeof value.z === 'number') {
+    return value;
+  }
+  if (value.position && typeof value.position === 'object') {
+    return resolvePosition3D(value.position);
+  }
+  return { x: 0, y: 0, z: 0 };
+}
+
 export function distanceSquared3D(a, b) {
-  const dx = a.x - b.x;
-  const dy = a.y - b.y;
-  const dz = a.z - b.z;
+  const left = resolvePosition3D(a);
+  const right = resolvePosition3D(b);
+  const dx = left.x - right.x;
+  const dy = left.y - right.y;
+  const dz = left.z - right.z;
   return (dx * dx) + (dy * dy) + (dz * dz);
 }
 

package/templates/create/shared/src/starter-utils/index.js

@@ -1,6 +1,12 @@
-import { clamp, axisFromKeys, createCooldown, tickCooldown, consumeCooldown, createIntervalSpawner, tickIntervalSpawner, centeredRect, rectsOverlap, removeWhere, distanceSquared3D, tryJump, stepVerticalMotion } from './core.js';
+import { clamp, axisFromKeys, createCooldown, tickCooldown, consumeCooldown, createIntervalSpawner, tickIntervalSpawner, centeredRect, rectsOverlap, removeWhere, distanceSquared2D, distanceSquared3D, tryJump, stepVerticalMotion } from './core.js';
+import { createSpriteAnimationLibrary2D, hasSpriteAnimationState2D, createSpriteAnimationRuntime2D, registerSpriteAnimationLibrary2D, createSpriteAnimator2D, playSpriteAnimator2D, syncSpriteAnimatorState2D, stepSpriteAnimationRuntime2D, getSpriteAnimatorState2D, resolveSpriteAnimatorFrame2D, drawSpriteAnimator2D, resolveSpriteFrameRect2D } from './animation-2d.js';
+import { propertyTween2D, delayTween2D, sequenceTweens2D, parallelTweens2D, repeatTween2D, yoyoTween2D, moveTo2D, driftTo2D, fadeTo2D, scaleTo2D, rotateTo2D, pulse2D, punch2D, settleTo2D, createTweenComposer2D, playTweenPlan2D, cancelTweenPlan2D, stepTweenComposer2D, getTweenHandleState2D, isTweenHandleActive2D } from './tween-2d.js';
+import { createFloatingTextLayer2D, spawnFloatingText2D, stepFloatingTextLayer2D, getFloatingTextRenderState2D, drawFloatingTextLayer2D, createHitFlash2D, triggerHitFlash2D, stepHitFlash2D, isHitFlashVisible2D, createHitSparkLayer2D, spawnHitSpark2D, stepHitSparkLayer2D, drawHitSparkLayer2D, createHoverLift2D, setHoverLiftActive2D, stepHoverLift2D, getHoverLiftOffset2D } from './combat-feedback-2d.js';
+import { createRectTrigger2D, createProximityTrigger3D, createVolumeTrigger3D, createTriggerTracker, getTriggerTrackerSnapshot, stepRectTriggers2D, stepVolumeTriggers3D, stepTriggerTracker, resolveTriggerInteraction, createInteractionPromptState, updateInteractionPromptState } from './triggers.js';
 import { createWaveDirector, activeWave, stepWaveDirector } from './wave-director.js';
 import { listEnemyArchetypeIds2D, getEnemyArchetype2D, pickEnemyArchetypeForWave2D, spawnEnemy2D } from './enemy-archetypes-2d.js';
 import { createCheckpointSystem, updateCheckpointProgress, activeCheckpoint, respawnAtCheckpoint, createGoalZone, isGoalReached, createMovingPlatform3D, stepMovingPlatform3D } from './platformer-3d.js';
+import { createCharacterAvatar3D, setAvatarInput3D, setAvatarVisual3D, spawnCharacterAvatar3D, tickCharacterAvatar3D, getAvatarState3D, getAvatarRenderTransform3D } from './avatar-3d.js';
+import { createAdventureObjectives, resetAdventureObjectives, countCompletedObjectives, objectivesComplete, firstPendingObjective, collectAdventureObjectives2D, collectAdventureObjectives3D } from './adventure-objectives.js';
 
-export { clamp, axisFromKeys, createCooldown, tickCooldown, consumeCooldown, createIntervalSpawner, tickIntervalSpawner, centeredRect, rectsOverlap, removeWhere, distanceSquared3D, tryJump, stepVerticalMotion, createWaveDirector, activeWave, stepWaveDirector, listEnemyArchetypeIds2D, getEnemyArchetype2D, pickEnemyArchetypeForWave2D, spawnEnemy2D, createCheckpointSystem, updateCheckpointProgress, activeCheckpoint, respawnAtCheckpoint, createGoalZone, isGoalReached, createMovingPlatform3D, stepMovingPlatform3D };
+export { clamp, axisFromKeys, createCooldown, tickCooldown, consumeCooldown, createIntervalSpawner, tickIntervalSpawner, centeredRect, rectsOverlap, removeWhere, distanceSquared2D, distanceSquared3D, tryJump, stepVerticalMotion, createSpriteAnimationLibrary2D, hasSpriteAnimationState2D, createSpriteAnimationRuntime2D, registerSpriteAnimationLibrary2D, createSpriteAnimator2D, playSpriteAnimator2D, syncSpriteAnimatorState2D, stepSpriteAnimationRuntime2D, getSpriteAnimatorState2D, resolveSpriteAnimatorFrame2D, drawSpriteAnimator2D, resolveSpriteFrameRect2D, propertyTween2D, delayTween2D, sequenceTweens2D, parallelTweens2D, repeatTween2D, yoyoTween2D, moveTo2D, driftTo2D, fadeTo2D, scaleTo2D, rotateTo2D, pulse2D, punch2D, settleTo2D, createTweenComposer2D, playTweenPlan2D, cancelTweenPlan2D, stepTweenComposer2D, getTweenHandleState2D, isTweenHandleActive2D, createFloatingTextLayer2D, spawnFloatingText2D, stepFloatingTextLayer2D, getFloatingTextRenderState2D, drawFloatingTextLayer2D, createHitFlash2D, triggerHitFlash2D, stepHitFlash2D, isHitFlashVisible2D, createHitSparkLayer2D, spawnHitSpark2D, stepHitSparkLayer2D, drawHitSparkLayer2D, createHoverLift2D, setHoverLiftActive2D, stepHoverLift2D, getHoverLiftOffset2D, createRectTrigger2D, createProximityTrigger3D, createVolumeTrigger3D, createTriggerTracker, getTriggerTrackerSnapshot, stepRectTriggers2D, stepVolumeTriggers3D, stepTriggerTracker, resolveTriggerInteraction, createInteractionPromptState, updateInteractionPromptState, createWaveDirector, activeWave, stepWaveDirector, listEnemyArchetypeIds2D, getEnemyArchetype2D, pickEnemyArchetypeForWave2D, spawnEnemy2D, createCheckpointSystem, updateCheckpointProgress, activeCheckpoint, respawnAtCheckpoint, createGoalZone, isGoalReached, createMovingPlatform3D, stepMovingPlatform3D, createCharacterAvatar3D, setAvatarInput3D, setAvatarVisual3D, spawnCharacterAvatar3D, tickCharacterAvatar3D, getAvatarState3D, getAvatarRenderTransform3D, createAdventureObjectives, resetAdventureObjectives, countCompletedObjectives, objectivesComplete, firstPendingObjective, collectAdventureObjectives2D, collectAdventureObjectives3D };

package/templates/create/shared/src/starter-utils/platformer-3d.js

@@ -1,5 +1,12 @@
 import { clamp, distanceSquared3D } from './core.js';
 
+function resolveRespawnTarget(body) {
+  if (body && typeof body === 'object' && body.position && typeof body.position === 'object') {
+    return body.position;
+  }
+  return body;
+}
+
 export function createCheckpointSystem(options = {}) {
   const checkpoints = Array.isArray(options.checkpoints)
     ? options.checkpoints.map((entry) => ({
@@ -38,9 +45,33 @@ export function respawnAtCheckpoint(system, body) {
   const checkpoint = activeCheckpoint(system);
   if (!checkpoint) return false;
 
-  body.x = checkpoint.x;
-  body.y = checkpoint.y;
-  body.z = checkpoint.z;
+  const target = resolveRespawnTarget(body);
+  if (!target || typeof target !== 'object') return false;
+
+  target.x = checkpoint.x;
+  target.y = checkpoint.y;
+  target.z = checkpoint.z;
+
+  if (body && typeof body === 'object' && body !== target) {
+    body.velocityY = 0;
+    body.grounded = false;
+    body.onSlope = false;
+    body.locomotion = 'idle';
+    body.motion = {
+      moveX: 0,
+      moveZ: 0,
+      magnitude: 0,
+      speed: 0,
+    };
+    body.input = {
+      moveX: 0,
+      moveZ: 0,
+      jump: false,
+      run: false,
+    };
+    return true;
+  }
+
   body.vy = 0;
   body.onGround = false;
   return true;