@auraindustry/aurajs 0.1.3 → 0.1.5

package/src/helpers/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/src/helpers/starter-utils/combat-runtime-2d.js

@@ -0,0 +1,290 @@
+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 ratio01(value) {
+  return Math.max(0, Math.min(1, finite(value, 0)));
+}
+
+function keyName(value, fallback) {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : fallback;
+}
+
+export function applyShieldedDamage2D(target, amount, options = {}) {
+  if (!target || typeof target !== 'object') {
+    throw new Error('shielded damage target is required.');
+  }
+
+  const hpKey = keyName(options.hpKey, 'hp');
+  const shieldKey = keyName(options.shieldKey, 'shield');
+  const invulnKey = keyName(options.invulnKey, 'invuln');
+  const rechargeDelayKey = keyName(options.rechargeDelayKey, 'shieldRechargeDelay');
+  const rechargeTimerKey = keyName(options.rechargeTimerKey, 'shieldRechargeTimer');
+  const damageAmount = Math.max(0, finite(amount, 0));
+  const invulnDuration = Math.max(0, finite(options.invulnDuration, 0));
+
+  if (damageAmount <= 0) {
+    return {
+      ok: true,
+      applied: false,
+      reasonCode: 'no_damage',
+      defeated: finite(target[hpKey], 0) <= 0,
+      absorbed: 0,
+      hpLost: 0,
+      hp: finite(target[hpKey], 0),
+      shield: finite(target[shieldKey], 0),
+    };
+  }
+
+  if (finite(target[invulnKey], 0) > 0 && options.ignoreInvuln !== true) {
+    return {
+      ok: true,
+      applied: false,
+      reasonCode: 'invulnerable',
+      defeated: finite(target[hpKey], 0) <= 0,
+      absorbed: 0,
+      hpLost: 0,
+      hp: finite(target[hpKey], 0),
+      shield: finite(target[shieldKey], 0),
+    };
+  }
+
+  target[rechargeTimerKey] = finite(target[rechargeDelayKey], 0);
+
+  let remaining = damageAmount;
+  const shield = Math.max(0, finite(target[shieldKey], 0));
+  const absorbed = Math.min(shield, remaining);
+  if (absorbed > 0) {
+    target[shieldKey] = shield - absorbed;
+    remaining -= absorbed;
+  }
+
+  const hpBefore = Math.max(0, finite(target[hpKey], 0));
+  const hpLost = Math.min(hpBefore, remaining);
+  if (hpLost > 0) {
+    target[hpKey] = hpBefore - hpLost;
+  }
+
+  if (invulnDuration > 0) {
+    target[invulnKey] = Math.max(finite(target[invulnKey], 0), invulnDuration);
+  }
+
+  return {
+    ok: true,
+    applied: absorbed > 0 || hpLost > 0,
+    reasonCode: null,
+    defeated: finite(target[hpKey], 0) <= 0,
+    absorbed,
+    hpLost,
+    hp: Math.max(0, finite(target[hpKey], 0)),
+    shield: Math.max(0, finite(target[shieldKey], 0)),
+  };
+}
+
+export function stepShieldRecharge2D(target, dt, options = {}) {
+  if (!target || typeof target !== 'object') {
+    throw new Error('shield recharge target is required.');
+  }
+
+  const shieldKey = keyName(options.shieldKey, 'shield');
+  const maxShieldKey = keyName(options.maxShieldKey, 'maxShield');
+  const rechargeTimerKey = keyName(options.rechargeTimerKey, 'shieldRechargeTimer');
+  const rate = Math.max(0, finite(options.rate, 0));
+  const stepDt = Math.max(0, finite(dt, 0));
+
+  target[rechargeTimerKey] = Math.max(0, finite(target[rechargeTimerKey], 0) - stepDt);
+  if (target[rechargeTimerKey] > 0 || rate <= 0) {
+    return {
+      ok: true,
+      recharged: 0,
+      shield: Math.max(0, finite(target[shieldKey], 0)),
+      timer: target[rechargeTimerKey],
+    };
+  }
+
+  const maxShield = Math.max(0, finite(target[maxShieldKey], 0));
+  const shield = Math.max(0, finite(target[shieldKey], 0));
+  const nextShield = Math.min(maxShield, shield + (rate * stepDt));
+  const recharged = nextShield - shield;
+  target[shieldKey] = nextShield;
+
+  return {
+    ok: true,
+    recharged,
+    shield: nextShield,
+    timer: target[rechargeTimerKey],
+  };
+}
+
+export function restoreShieldedHealth2D(target, options = {}) {
+  if (!target || typeof target !== 'object') {
+    throw new Error('shield restore target is required.');
+  }
+
+  const hpKey = keyName(options.hpKey, 'hp');
+  const maxHpKey = keyName(options.maxHpKey, 'maxHp');
+  const shieldKey = keyName(options.shieldKey, 'shield');
+  const maxShieldKey = keyName(options.maxShieldKey, 'maxShield');
+  const hpAmount = Math.max(0, finite(options.hp, 0));
+  const shieldAmount = Math.max(0, finite(options.shield, 0));
+
+  if (hpAmount > 0) {
+    target[hpKey] = Math.min(Math.max(0, finite(target[maxHpKey], 0)), Math.max(0, finite(target[hpKey], 0)) + hpAmount);
+  }
+  if (shieldAmount > 0) {
+    target[shieldKey] = Math.min(Math.max(0, finite(target[maxShieldKey], 0)), Math.max(0, finite(target[shieldKey], 0)) + shieldAmount);
+  }
+
+  return {
+    ok: true,
+    hp: Math.max(0, finite(target[hpKey], 0)),
+    shield: Math.max(0, finite(target[shieldKey], 0)),
+  };
+}
+
+function normalizeDropEntries(entries = []) {
+  let runningWeight = 0;
+  return (Array.isArray(entries) ? entries : [])
+    .map((entry, index) => {
+      const raw = entry && typeof entry === 'object' && !Array.isArray(entry) ? entry : null;
+      if (!raw) return null;
+      const id = keyName(raw.id, `drop-${index + 1}`);
+      const weight = positiveNumber(raw.weight, 1, `drop "${id}" weight`);
+      runningWeight += weight;
+      return {
+        ...raw,
+        id,
+        weight,
+        cumulativeWeight: runningWeight,
+      };
+    })
+    .filter(Boolean);
+}
+
+export function createWeightedDropTable2D(entries = []) {
+  const normalized = normalizeDropEntries(entries);
+  return {
+    entries: normalized,
+    totalWeight: normalized.length > 0 ? normalized[normalized.length - 1].cumulativeWeight : 0,
+  };
+}
+
+export function rollWeightedDrop2D(table, sample = Math.random()) {
+  if (!table || !Array.isArray(table.entries) || table.entries.length === 0 || !(table.totalWeight > 0)) {
+    return null;
+  }
+
+  const threshold = ratio01(sample) * table.totalWeight;
+  for (const entry of table.entries) {
+    if (threshold <= entry.cumulativeWeight) {
+      return entry;
+    }
+  }
+  return table.entries[table.entries.length - 1] || null;
+}
+
+export function createEncounterPressure2D(options = {}) {
+  return {
+    kills: Math.max(0, Math.floor(finite(options.kills, 0))),
+    wave: Math.max(1, Math.floor(finite(options.wave, 1))),
+    combo: Math.max(0, Math.floor(finite(options.combo, 0))),
+    comboTimer: Math.max(0, finite(options.comboTimer, 0)),
+    comboWindow: positiveNumber(options.comboWindow, 2.1, 'combat pressure comboWindow'),
+    waveEveryKills: positiveInteger(options.waveEveryKills, 10, 'combat pressure waveEveryKills'),
+  };
+}
+
+export function recordEncounterKill2D(pressure, options = {}) {
+  if (!pressure || typeof pressure !== 'object') {
+    throw new Error('encounter pressure state is required.');
+  }
+
+  const comboWindow = positiveNumber(options.comboWindow, pressure.comboWindow, 'combat pressure comboWindow');
+  const waveEveryKills = positiveInteger(options.waveEveryKills, pressure.waveEveryKills, 'combat pressure waveEveryKills');
+
+  pressure.comboWindow = comboWindow;
+  pressure.waveEveryKills = waveEveryKills;
+  pressure.kills = Math.max(0, Math.floor(finite(pressure.kills, 0))) + 1;
+  pressure.combo = Math.max(0, Math.floor(finite(pressure.combo, 0))) + 1;
+  pressure.comboTimer = comboWindow;
+
+  const waveAdvanced = pressure.kills % waveEveryKills === 0;
+  if (waveAdvanced) {
+    pressure.wave = Math.max(1, Math.floor(finite(pressure.wave, 1))) + 1;
+  }
+
+  return {
+    ok: true,
+    waveAdvanced,
+    kills: pressure.kills,
+    combo: pressure.combo,
+    comboTimer: pressure.comboTimer,
+    wave: pressure.wave,
+  };
+}
+
+export function stepEncounterPressure2D(pressure, dt) {
+  if (!pressure || typeof pressure !== 'object') {
+    throw new Error('encounter pressure state is required.');
+  }
+
+  pressure.comboTimer = Math.max(0, finite(pressure.comboTimer, 0) - Math.max(0, finite(dt, 0)));
+  if (pressure.comboTimer <= 0) {
+    pressure.combo = 0;
+  }
+
+  return {
+    ok: true,
+    combo: pressure.combo,
+    comboTimer: pressure.comboTimer,
+    wave: Math.max(1, Math.floor(finite(pressure.wave, 1))),
+    kills: Math.max(0, Math.floor(finite(pressure.kills, 0))),
+  };
+}
+
+export function advanceBossPhase2D(entity, healthRatio, thresholds = [], options = {}) {
+  if (!entity || typeof entity !== 'object') {
+    throw new Error('boss phase entity is required.');
+  }
+
+  const phaseKey = keyName(options.phaseKey, 'phaseStage');
+  const normalizedThresholds = [...(Array.isArray(thresholds) ? thresholds : [])]
+    .map((entry) => ratio01(entry))
+    .sort((left, right) => right - left);
+  const currentPhase = Math.max(0, Math.floor(finite(entity[phaseKey], 0)));
+  let nextPhase = currentPhase;
+
+  for (let index = 0; index < normalizedThresholds.length; index += 1) {
+    if (ratio01(healthRatio) <= normalizedThresholds[index]) {
+      nextPhase = Math.max(nextPhase, index + 1);
+    }
+  }
+
+  if (options.mutate === true) {
+    entity[phaseKey] = nextPhase;
+  }
+
+  return {
+    ok: true,
+    shifted: nextPhase > currentPhase,
+    phaseStage: nextPhase,
+    previousPhaseStage: currentPhase,
+  };
+}