@arcane-engine/runtime 0.1.0 → 0.2.0

package/src/tweening/easing.test.ts

@@ -0,0 +1,134 @@
+/**
+ * Tests for easing functions
+ */
+
+import { describe, it, assert } from "../testing/harness.ts";
+import {
+  linear,
+  easeInQuad,
+  easeOutQuad,
+  easeInOutQuad,
+  easeInCubic,
+  easeOutCubic,
+  easeInOutCubic,
+  easeInSine,
+  easeOutSine,
+  easeInOutSine,
+  easeInExpo,
+  easeOutExpo,
+  easeInOutExpo,
+  easeInCirc,
+  easeOutCirc,
+  easeInOutCirc,
+  easeInBack,
+  easeOutBack,
+  easeInOutBack,
+  easeInElastic,
+  easeOutElastic,
+  easeInOutElastic,
+  easeInBounce,
+  easeOutBounce,
+  easeInOutBounce,
+  Easing,
+} from "./easing.ts";
+
+describe("Easing Functions", () => {
+  // Helper to test that easing function has correct boundary behavior
+  function testEasingBoundaries(name: string, easingFn: (t: number) => number) {
+    it(`${name} should return 0 at t=0`, () => {
+      const result = easingFn(0);
+      assert.ok(Math.abs(result - 0) < 0.001, `Expected ~0, got ${result}`);
+    });
+
+    it(`${name} should return 1 at t=1`, () => {
+      const result = easingFn(1);
+      assert.ok(Math.abs(result - 1) < 0.001, `Expected ~1, got ${result}`);
+    });
+
+    it(`${name} should return values in range [0,1] for t in [0,1]`, () => {
+      for (let t = 0; t <= 1; t += 0.1) {
+        const result = easingFn(t);
+        // Some easing functions (like back, elastic) can go slightly outside [0,1] during animation
+        // But they should end at the right place
+        assert.ok(!isNaN(result), `Result should not be NaN for t=${t}`);
+      }
+    });
+  }
+
+  // Test all easing functions have correct boundaries
+  testEasingBoundaries("linear", linear);
+  testEasingBoundaries("easeInQuad", easeInQuad);
+  testEasingBoundaries("easeOutQuad", easeOutQuad);
+  testEasingBoundaries("easeInOutQuad", easeInOutQuad);
+  testEasingBoundaries("easeInCubic", easeInCubic);
+  testEasingBoundaries("easeOutCubic", easeOutCubic);
+  testEasingBoundaries("easeInOutCubic", easeInOutCubic);
+  testEasingBoundaries("easeInSine", easeInSine);
+  testEasingBoundaries("easeOutSine", easeOutSine);
+  testEasingBoundaries("easeInOutSine", easeInOutSine);
+  testEasingBoundaries("easeInExpo", easeInExpo);
+  testEasingBoundaries("easeOutExpo", easeOutExpo);
+  testEasingBoundaries("easeInOutExpo", easeInOutExpo);
+  testEasingBoundaries("easeInCirc", easeInCirc);
+  testEasingBoundaries("easeOutCirc", easeOutCirc);
+  testEasingBoundaries("easeInOutCirc", easeInOutCirc);
+  testEasingBoundaries("easeInBack", easeInBack);
+  testEasingBoundaries("easeOutBack", easeOutBack);
+  testEasingBoundaries("easeInOutBack", easeInOutBack);
+  testEasingBoundaries("easeInElastic", easeInElastic);
+  testEasingBoundaries("easeOutElastic", easeOutElastic);
+  testEasingBoundaries("easeInOutElastic", easeInOutElastic);
+  testEasingBoundaries("easeInBounce", easeInBounce);
+  testEasingBoundaries("easeOutBounce", easeOutBounce);
+  testEasingBoundaries("easeInOutBounce", easeInOutBounce);
+
+  it("linear should return t", () => {
+    assert.equal(linear(0.5), 0.5);
+    assert.equal(linear(0.25), 0.25);
+    assert.equal(linear(0.75), 0.75);
+  });
+
+  it("easeInQuad should be slower at start", () => {
+    // At t=0.5, quadratic should be at 0.25 (slower than linear)
+    assert.ok(easeInQuad(0.5) < 0.5);
+  });
+
+  it("easeOutQuad should be faster at start", () => {
+    // At t=0.5, ease-out should be past 0.5 (faster than linear)
+    assert.ok(easeOutQuad(0.5) > 0.5);
+  });
+
+  it("easeInOutQuad should be symmetric", () => {
+    // At t=0.5, should be at 0.5
+    const mid = easeInOutQuad(0.5);
+    assert.ok(Math.abs(mid - 0.5) < 0.01);
+  });
+
+  it("Easing map contains all functions", () => {
+    assert.equal(typeof Easing.linear, "function");
+    assert.equal(typeof Easing.easeInQuad, "function");
+    assert.equal(typeof Easing.easeOutQuad, "function");
+    assert.equal(typeof Easing.easeInOutQuad, "function");
+    assert.equal(typeof Easing.easeInCubic, "function");
+    assert.equal(typeof Easing.easeOutCubic, "function");
+    assert.equal(typeof Easing.easeInOutCubic, "function");
+    assert.equal(typeof Easing.easeInSine, "function");
+    assert.equal(typeof Easing.easeOutSine, "function");
+    assert.equal(typeof Easing.easeInOutSine, "function");
+    assert.equal(typeof Easing.easeInExpo, "function");
+    assert.equal(typeof Easing.easeOutExpo, "function");
+    assert.equal(typeof Easing.easeInOutExpo, "function");
+    assert.equal(typeof Easing.easeInCirc, "function");
+    assert.equal(typeof Easing.easeOutCirc, "function");
+    assert.equal(typeof Easing.easeInOutCirc, "function");
+    assert.equal(typeof Easing.easeInBack, "function");
+    assert.equal(typeof Easing.easeOutBack, "function");
+    assert.equal(typeof Easing.easeInOutBack, "function");
+    assert.equal(typeof Easing.easeInElastic, "function");
+    assert.equal(typeof Easing.easeOutElastic, "function");
+    assert.equal(typeof Easing.easeInOutElastic, "function");
+    assert.equal(typeof Easing.easeInBounce, "function");
+    assert.equal(typeof Easing.easeOutBounce, "function");
+    assert.equal(typeof Easing.easeInOutBounce, "function");
+  });
+});

package/src/tweening/easing.ts

@@ -0,0 +1,288 @@
+/**
+ * 30 easing functions for tweens, organized into 10 families.
+ *
+ * All functions take `t` (0 to 1) and return an eased value.
+ * Most return 0..1, but back and elastic easings may overshoot.
+ *
+ * Families: linear, quad, cubic, quart, quint, sine, expo, circ, back, elastic, bounce.
+ * Each family (except linear) has easeIn (slow start), easeOut (slow end),
+ * and easeInOut (slow start + end) variants.
+ *
+ * Based on https://easings.net/ and Robert Penner's easing equations.
+ *
+ * @example
+ * ```ts
+ * import { easeOutQuad } from "./easing.ts";
+ * tween(sprite, { x: 100 }, 0.5, { easing: easeOutQuad });
+ * ```
+ */
+
+import type { EasingFunction } from "./types.ts";
+
+// --- Linear ---
+
+/** No easing: constant speed from start to end. */
+export const linear: EasingFunction = (t) => t;
+
+// --- Quadratic ---
+
+/** Quadratic ease-in: slow start, accelerating. t^2 curve. */
+export const easeInQuad: EasingFunction = (t) => t * t;
+
+/** Quadratic ease-out: fast start, decelerating. Reverse t^2 curve. */
+export const easeOutQuad: EasingFunction = (t) => t * (2 - t);
+
+/** Quadratic ease-in-out: slow start and end, fast in the middle. */
+export const easeInOutQuad: EasingFunction = (t) =>
+  t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t;
+
+// --- Cubic ---
+
+/** Cubic ease-in: slow start with t^3 curve. Slightly more pronounced than quad. */
+export const easeInCubic: EasingFunction = (t) => t * t * t;
+
+/** Cubic ease-out: fast start, decelerating with t^3 curve. */
+export const easeOutCubic: EasingFunction = (t) => {
+  const t1 = t - 1;
+  return t1 * t1 * t1 + 1;
+};
+
+/** Cubic ease-in-out: smooth acceleration then deceleration. */
+export const easeInOutCubic: EasingFunction = (t) =>
+  t < 0.5 ? 4 * t * t * t : (t - 1) * (2 * t - 2) * (2 * t - 2) + 1;
+
+// --- Quartic ---
+
+/** Quartic ease-in: very slow start with t^4 curve. */
+export const easeInQuart: EasingFunction = (t) => t * t * t * t;
+
+/** Quartic ease-out: fast start, strong deceleration. */
+export const easeOutQuart: EasingFunction = (t) => {
+  const t1 = t - 1;
+  return 1 - t1 * t1 * t1 * t1;
+};
+
+/** Quartic ease-in-out: pronounced slow start/end, fast middle. */
+export const easeInOutQuart: EasingFunction = (t) => {
+  if (t < 0.5) {
+    return 8 * t * t * t * t;
+  }
+  const t1 = t - 1;
+  return 1 - 8 * t1 * t1 * t1 * t1;
+};
+
+// --- Quintic ---
+
+/** Quintic ease-in: very slow start with t^5 curve. Most dramatic polynomial ease-in. */
+export const easeInQuint: EasingFunction = (t) => t * t * t * t * t;
+
+/** Quintic ease-out: fast start, very strong deceleration. */
+export const easeOutQuint: EasingFunction = (t) => {
+  const t1 = t - 1;
+  return 1 + t1 * t1 * t1 * t1 * t1;
+};
+
+/** Quintic ease-in-out: extremely slow start/end, very fast middle. */
+export const easeInOutQuint: EasingFunction = (t) => {
+  if (t < 0.5) {
+    return 16 * t * t * t * t * t;
+  }
+  const t1 = t - 1;
+  return 1 + 16 * t1 * t1 * t1 * t1 * t1;
+};
+
+// --- Sine ---
+
+/** Sine ease-in: gentle slow start following a sine curve. */
+export const easeInSine: EasingFunction = (t) =>
+  1 - Math.cos((t * Math.PI) / 2);
+
+/** Sine ease-out: gentle deceleration following a sine curve. */
+export const easeOutSine: EasingFunction = (t) =>
+  Math.sin((t * Math.PI) / 2);
+
+/** Sine ease-in-out: smooth sinusoidal acceleration and deceleration. */
+export const easeInOutSine: EasingFunction = (t) =>
+  -(Math.cos(Math.PI * t) - 1) / 2;
+
+// --- Exponential ---
+
+/** Exponential ease-in: near-zero at start, rapidly accelerating. Returns 0 when t=0. */
+export const easeInExpo: EasingFunction = (t) =>
+  t === 0 ? 0 : Math.pow(2, 10 * t - 10);
+
+/** Exponential ease-out: fast start, asymptotically approaching 1. Returns 1 when t=1. */
+export const easeOutExpo: EasingFunction = (t) =>
+  t === 1 ? 1 : 1 - Math.pow(2, -10 * t);
+
+/** Exponential ease-in-out: dramatic acceleration/deceleration with near-flat start/end. */
+export const easeInOutExpo: EasingFunction = (t) => {
+  if (t === 0) return 0;
+  if (t === 1) return 1;
+  if (t < 0.5) {
+    return Math.pow(2, 20 * t - 10) / 2;
+  }
+  return (2 - Math.pow(2, -20 * t + 10)) / 2;
+};
+
+// --- Circular ---
+
+/** Circular ease-in: quarter-circle curve, slow start. */
+export const easeInCirc: EasingFunction = (t) =>
+  1 - Math.sqrt(1 - t * t);
+
+/** Circular ease-out: quarter-circle curve, fast start. */
+export const easeOutCirc: EasingFunction = (t) =>
+  Math.sqrt(1 - Math.pow(t - 1, 2));
+
+/** Circular ease-in-out: half-circle curve, slow at both ends. */
+export const easeInOutCirc: EasingFunction = (t) => {
+  if (t < 0.5) {
+    return (1 - Math.sqrt(1 - Math.pow(2 * t, 2))) / 2;
+  }
+  return (Math.sqrt(1 - Math.pow(-2 * t + 2, 2)) + 1) / 2;
+};
+
+// --- Back ---
+
+/** Back ease-in: pulls back slightly before accelerating forward. Overshoots below 0. */
+export const easeInBack: EasingFunction = (t) => {
+  const c1 = 1.70158;
+  const c3 = c1 + 1;
+  return c3 * t * t * t - c1 * t * t;
+};
+
+/** Back ease-out: overshoots past 1 then settles back. */
+export const easeOutBack: EasingFunction = (t) => {
+  const c1 = 1.70158;
+  const c3 = c1 + 1;
+  return 1 + c3 * Math.pow(t - 1, 3) + c1 * Math.pow(t - 1, 2);
+};
+
+/** Back ease-in-out: pulls back, accelerates, overshoots, then settles. */
+export const easeInOutBack: EasingFunction = (t) => {
+  const c1 = 1.70158;
+  const c2 = c1 * 1.525;
+  if (t < 0.5) {
+    return (Math.pow(2 * t, 2) * ((c2 + 1) * 2 * t - c2)) / 2;
+  }
+  return (Math.pow(2 * t - 2, 2) * ((c2 + 1) * (t * 2 - 2) + c2) + 2) / 2;
+};
+
+// --- Elastic ---
+
+/** Elastic ease-in: spring-like oscillation at the start. Overshoots below 0. */
+export const easeInElastic: EasingFunction = (t) => {
+  const c4 = (2 * Math.PI) / 3;
+  if (t === 0) return 0;
+  if (t === 1) return 1;
+  return -Math.pow(2, 10 * t - 10) * Math.sin((t * 10 - 10.75) * c4);
+};
+
+/** Elastic ease-out: spring-like oscillation at the end. Overshoots above 1. */
+export const easeOutElastic: EasingFunction = (t) => {
+  const c4 = (2 * Math.PI) / 3;
+  if (t === 0) return 0;
+  if (t === 1) return 1;
+  return Math.pow(2, -10 * t) * Math.sin((t * 10 - 0.75) * c4) + 1;
+};
+
+/** Elastic ease-in-out: spring oscillation at both start and end. */
+export const easeInOutElastic: EasingFunction = (t) => {
+  const c5 = (2 * Math.PI) / 4.5;
+  if (t === 0) return 0;
+  if (t === 1) return 1;
+  if (t < 0.5) {
+    return -(Math.pow(2, 20 * t - 10) * Math.sin((20 * t - 11.125) * c5)) / 2;
+  }
+  return (Math.pow(2, -20 * t + 10) * Math.sin((20 * t - 11.125) * c5)) / 2 + 1;
+};
+
+// --- Bounce ---
+
+/** Bounce ease-out: simulates a ball bouncing to rest. Stays within 0..1. */
+export const easeOutBounce: EasingFunction = (t) => {
+  const n1 = 7.5625;
+  const d1 = 2.75;
+
+  if (t < 1 / d1) {
+    return n1 * t * t;
+  } else if (t < 2 / d1) {
+    const t2 = t - 1.5 / d1;
+    return n1 * t2 * t2 + 0.75;
+  } else if (t < 2.5 / d1) {
+    const t2 = t - 2.25 / d1;
+    return n1 * t2 * t2 + 0.9375;
+  } else {
+    const t2 = t - 2.625 / d1;
+    return n1 * t2 * t2 + 0.984375;
+  }
+};
+
+/** Bounce ease-in: reverse bouncing at the start. Stays within 0..1. */
+export const easeInBounce: EasingFunction = (t) =>
+  1 - easeOutBounce(1 - t);
+
+/** Bounce ease-in-out: bouncing at both start and end. */
+export const easeInOutBounce: EasingFunction = (t) => {
+  if (t < 0.5) {
+    return (1 - easeOutBounce(1 - 2 * t)) / 2;
+  }
+  return (1 + easeOutBounce(2 * t - 1)) / 2;
+};
+
+// --- Convenience map ---
+
+/**
+ * Lookup object containing all 30 easing functions keyed by name.
+ * Useful for selecting an easing function dynamically (e.g., from config or UI).
+ *
+ * @example
+ * ```ts
+ * const easingName = "easeOutQuad";
+ * tween(obj, { x: 100 }, 1, { easing: Easing[easingName] });
+ * ```
+ */
+export const Easing = {
+  linear,
+
+  easeInQuad,
+  easeOutQuad,
+  easeInOutQuad,
+
+  easeInCubic,
+  easeOutCubic,
+  easeInOutCubic,
+
+  easeInQuart,
+  easeOutQuart,
+  easeInOutQuart,
+
+  easeInQuint,
+  easeOutQuint,
+  easeInOutQuint,
+
+  easeInSine,
+  easeOutSine,
+  easeInOutSine,
+
+  easeInExpo,
+  easeOutExpo,
+  easeInOutExpo,
+
+  easeInCirc,
+  easeOutCirc,
+  easeInOutCirc,
+
+  easeInBack,
+  easeOutBack,
+  easeInOutBack,
+
+  easeInElastic,
+  easeOutElastic,
+  easeInOutElastic,
+
+  easeInBounce,
+  easeOutBounce,
+  easeInOutBounce,
+} as const;

package/src/tweening/helpers.test.ts

@@ -0,0 +1,185 @@
+/**
+ * Tests for tweening helpers (camera shake, screen flash)
+ */
+
+import { describe, it, assert } from "../testing/harness.ts";
+import {
+  shakeCamera,
+  getCameraShakeOffset,
+  isCameraShaking,
+  stopCameraShake,
+  flashScreen,
+  getScreenFlash,
+  isScreenFlashing,
+  stopScreenFlash,
+} from "./helpers.ts";
+import { updateTweens, stopAllTweens } from "./tween.ts";
+
+describe("Camera Shake", () => {
+  it("should start inactive", () => {
+    stopAllTweens();
+    stopCameraShake();
+
+    assert.equal(isCameraShaking(), false);
+    const offset = getCameraShakeOffset();
+    assert.equal(offset.x, 0);
+    assert.equal(offset.y, 0);
+  });
+
+  it("should activate when shake is triggered", () => {
+    stopAllTweens();
+    stopCameraShake();
+
+    shakeCamera(10, 1.0);
+    assert.equal(isCameraShaking(), true);
+  });
+
+  it("should produce non-zero offsets during shake", () => {
+    stopAllTweens();
+    stopCameraShake();
+
+    shakeCamera(10, 1.0);
+    updateTweens(0.1);
+
+    const offset = getCameraShakeOffset();
+    // Offset should be non-zero (with high probability due to randomness)
+    const hasOffset = Math.abs(offset.x) > 0 || Math.abs(offset.y) > 0;
+    assert.equal(hasOffset, true);
+  });
+
+  it("should decay intensity over time", () => {
+    stopAllTweens();
+    stopCameraShake();
+
+    shakeCamera(100, 1.0);
+    updateTweens(0.1);
+
+    const offset1 = getCameraShakeOffset();
+    const magnitude1 = Math.sqrt(offset1.x ** 2 + offset1.y ** 2);
+
+    updateTweens(0.5);
+
+    const offset2 = getCameraShakeOffset();
+    const magnitude2 = Math.sqrt(offset2.x ** 2 + offset2.y ** 2);
+
+    // Later magnitude should generally be smaller (decay)
+    // Note: Due to randomness, this might occasionally fail, but with high intensity
+    // and sufficient time, it should be reliable
+    assert.ok(magnitude2 < magnitude1 + 50, "Shake should decay over time");
+  });
+
+  it("should stop after duration completes", () => {
+    stopAllTweens();
+    stopCameraShake();
+
+    shakeCamera(10, 1.0);
+    assert.equal(isCameraShaking(), true);
+
+    updateTweens(1.0);
+    assert.equal(isCameraShaking(), false);
+
+    const offset = getCameraShakeOffset();
+    assert.equal(offset.x, 0);
+    assert.equal(offset.y, 0);
+  });
+
+  it("should stop immediately when stopCameraShake is called", () => {
+    stopAllTweens();
+    stopCameraShake();
+
+    shakeCamera(10, 1.0);
+    updateTweens(0.5);
+    assert.equal(isCameraShaking(), true);
+
+    stopCameraShake();
+    assert.equal(isCameraShaking(), false);
+
+    const offset = getCameraShakeOffset();
+    assert.equal(offset.x, 0);
+    assert.equal(offset.y, 0);
+  });
+});
+
+describe("Screen Flash", () => {
+  it("should start inactive", () => {
+    stopAllTweens();
+    stopScreenFlash();
+
+    assert.equal(isScreenFlashing(), false);
+    assert.equal(getScreenFlash(), null);
+  });
+
+  it("should activate when flash is triggered", () => {
+    stopAllTweens();
+    stopScreenFlash();
+
+    flashScreen(1, 1, 1, 1.0);
+    assert.equal(isScreenFlashing(), true);
+  });
+
+  it("should return flash color and opacity", () => {
+    stopAllTweens();
+    stopScreenFlash();
+
+    flashScreen(1, 0.5, 0.2, 1.0, 0.8);
+    const flash = getScreenFlash();
+
+    assert.ok(flash !== null);
+    assert.equal(flash!.r, 1);
+    assert.equal(flash!.g, 0.5);
+    assert.equal(flash!.b, 0.2);
+    assert.equal(flash!.opacity, 0.8);
+  });
+
+  it("should fade opacity over time", () => {
+    stopAllTweens();
+    stopScreenFlash();
+
+    flashScreen(1, 1, 1, 1.0, 0.8);
+    updateTweens(0.5);
+
+    const flash = getScreenFlash();
+    assert.ok(flash !== null);
+    assert.ok(flash!.opacity < 0.8, "Opacity should decrease over time");
+    assert.ok(flash!.opacity > 0, "Opacity should still be positive");
+  });
+
+  it("should stop after duration completes", () => {
+    stopAllTweens();
+    stopScreenFlash();
+
+    flashScreen(1, 1, 1, 1.0);
+    assert.equal(isScreenFlashing(), true);
+
+    updateTweens(1.0);
+    assert.equal(isScreenFlashing(), false);
+    assert.equal(getScreenFlash(), null);
+  });
+
+  it("should stop immediately when stopScreenFlash is called", () => {
+    stopAllTweens();
+    stopScreenFlash();
+
+    flashScreen(1, 1, 1, 1.0);
+    updateTweens(0.5);
+    assert.equal(isScreenFlashing(), true);
+
+    stopScreenFlash();
+    assert.equal(isScreenFlashing(), false);
+    assert.equal(getScreenFlash(), null);
+  });
+
+  it("should preserve color during fade", () => {
+    stopAllTweens();
+    stopScreenFlash();
+
+    flashScreen(0.5, 0.3, 0.7, 1.0);
+    updateTweens(0.5);
+
+    const flash = getScreenFlash();
+    assert.ok(flash !== null);
+    assert.equal(flash!.r, 0.5);
+    assert.equal(flash!.g, 0.3);
+    assert.equal(flash!.b, 0.7);
+  });
+});