@arcane-engine/runtime 0.1.0 → 0.2.1

package/src/tweening/helpers.ts

@@ -0,0 +1,166 @@
+/**
+ * Tweening helper functions for common game "juice" effects.
+ *
+ * Camera shake and screen flash are implemented as global singletons.
+ * Only one shake and one flash can be active at a time; starting a new one
+ * replaces the previous.
+ *
+ * Usage: call the effect function, then read the offset/flash state each frame
+ * when rendering.
+ */
+
+import { tween } from "./tween.ts";
+import { easeOutQuad } from "./easing.ts";
+
+/** Internal camera shake state (global singleton). */
+let shakeState = {
+  offsetX: 0,
+  offsetY: 0,
+  active: false,
+};
+
+/**
+ * Start a camera shake effect that decays over time using easeOutQuad.
+ *
+ * Each frame, read the offset via {@link getCameraShakeOffset} and add it
+ * to your camera position. The offset oscillates randomly and decays to zero.
+ *
+ * @param intensity - Maximum shake offset in pixels. Higher = more violent. Must be > 0.
+ * @param duration - Duration of the shake in seconds. Must be > 0.
+ * @param frequency - Unused currently; reserved for future use. Default: 20.
+ */
+export function shakeCamera(
+  intensity: number,
+  duration: number,
+  frequency: number = 20,
+): void {
+  shakeState.active = true;
+
+  // Store original intensity for interpolation
+  const startIntensity = intensity;
+
+  // Create a decay tween
+  const decay = { value: 1.0 };
+  tween(decay, { value: 0 }, duration, {
+    easing: easeOutQuad,
+    onUpdate: (progress) => {
+      // Decay intensity over time
+      const currentIntensity = startIntensity * (1 - progress);
+
+      // Generate random offsets with current intensity
+      // Use a simple pseudo-random pattern based on time
+      const angle = Math.random() * Math.PI * 2;
+      shakeState.offsetX = Math.cos(angle) * currentIntensity;
+      shakeState.offsetY = Math.sin(angle) * currentIntensity;
+    },
+    onComplete: () => {
+      shakeState.active = false;
+      shakeState.offsetX = 0;
+      shakeState.offsetY = 0;
+    },
+  });
+}
+
+/**
+ * Get the current camera shake offset for this frame.
+ * Returns {0, 0} when no shake is active.
+ *
+ * @returns Object with `x` and `y` pixel offsets to add to camera position.
+ */
+export function getCameraShakeOffset(): { x: number; y: number } {
+  return {
+    x: shakeState.offsetX,
+    y: shakeState.offsetY,
+  };
+}
+
+/**
+ * Check whether a camera shake effect is currently active.
+ * @returns True if shake is in progress, false otherwise.
+ */
+export function isCameraShaking(): boolean {
+  return shakeState.active;
+}
+
+/**
+ * Stop the camera shake immediately, resetting the offset to zero.
+ */
+export function stopCameraShake(): void {
+  shakeState.active = false;
+  shakeState.offsetX = 0;
+  shakeState.offsetY = 0;
+}
+
+/** Internal screen flash state (global singleton). */
+let flashState = {
+  opacity: 0,
+  r: 1,
+  g: 1,
+  b: 1,
+  active: false,
+};
+
+/**
+ * Flash the screen with a colored overlay that fades out using easeOutQuad.
+ *
+ * Each frame, read the flash state via {@link getScreenFlash} and render
+ * a full-screen rectangle with the returned color and opacity.
+ *
+ * @param r - Red component, 0.0 (none) to 1.0 (full).
+ * @param g - Green component, 0.0 (none) to 1.0 (full).
+ * @param b - Blue component, 0.0 (none) to 1.0 (full).
+ * @param duration - Fade-out duration in seconds. Must be > 0.
+ * @param startOpacity - Initial opacity of the flash overlay. Default: 0.8. Range: 0.0..1.0.
+ */
+export function flashScreen(
+  r: number,
+  g: number,
+  b: number,
+  duration: number,
+  startOpacity: number = 0.8,
+): void {
+  flashState.active = true;
+  flashState.r = r;
+  flashState.g = g;
+  flashState.b = b;
+  flashState.opacity = startOpacity;
+
+  // Fade out the flash
+  tween(flashState, { opacity: 0 }, duration, {
+    easing: easeOutQuad,
+    onComplete: () => {
+      flashState.active = false;
+    },
+  });
+}
+
+/**
+ * Get the current screen flash color and opacity for this frame.
+ *
+ * @returns Flash state with `r`, `g`, `b` (0..1) and `opacity` (0..1), or `null` if no flash is active.
+ */
+export function getScreenFlash(): { r: number; g: number; b: number; opacity: number } | null {
+  if (!flashState.active) return null;
+  return {
+    r: flashState.r,
+    g: flashState.g,
+    b: flashState.b,
+    opacity: flashState.opacity,
+  };
+}
+
+/**
+ * Check whether a screen flash effect is currently active.
+ * @returns True if flash is in progress, false otherwise.
+ */
+export function isScreenFlashing(): boolean {
+  return flashState.active;
+}
+
+/**
+ * Stop the screen flash immediately, resetting opacity to zero.
+ */
+export function stopScreenFlash(): void {
+  flashState.active = false;
+  flashState.opacity = 0;
+}

package/src/tweening/index.ts

@@ -0,0 +1,76 @@
+/**
+ * Tweening system
+ *
+ * Provides smooth animation of numeric properties over time.
+ */
+
+export type {
+  EasingFunction,
+  TweenCallback,
+  TweenUpdateCallback,
+  TweenOptions,
+  TweenProps,
+  Tween,
+} from "./types.ts";
+export { TweenState } from "./types.ts";
+
+export {
+  tween,
+  updateTweens,
+  stopTween,
+  pauseTween,
+  resumeTween,
+  reverseTween,
+  stopAllTweens,
+  getActiveTweenCount,
+  linear,
+} from "./tween.ts";
+
+export {
+  linear as easingLinear,
+  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,
+  Easing,
+} from "./easing.ts";
+
+export type { TweenConfig } from "./chain.ts";
+export { sequence, parallel, stagger } from "./chain.ts";
+
+export {
+  shakeCamera,
+  getCameraShakeOffset,
+  isCameraShaking,
+  stopCameraShake,
+  flashScreen,
+  getScreenFlash,
+  isScreenFlashing,
+  stopScreenFlash,
+} from "./helpers.ts";

package/src/tweening/tween.test.ts

@@ -0,0 +1,322 @@
+/**
+ * Tests for core tweening system
+ */
+
+import { describe, it, assert } from "../testing/harness.ts";
+import {
+  tween,
+  updateTweens,
+  stopTween,
+  pauseTween,
+  resumeTween,
+  stopAllTweens,
+  getActiveTweenCount,
+} from "./tween.ts";
+import { TweenState } from "./types.ts";
+
+describe("Core Tweening", () => {
+  it("should tween a single property", () => {
+    stopAllTweens();
+    const target = { x: 0 };
+    tween(target, { x: 100 }, 1.0);
+
+    // At 0s
+    assert.equal(target.x, 0);
+
+    // At 0.5s (halfway)
+    updateTweens(0.5);
+    assert.equal(target.x, 50);
+
+    // At 1.0s (complete)
+    updateTweens(0.5);
+    assert.equal(target.x, 100);
+  });
+
+  it("should tween multiple properties", () => {
+    stopAllTweens();
+    const target = { x: 0, y: 0, scale: 1 };
+    tween(target, { x: 100, y: 50, scale: 2 }, 1.0);
+
+    updateTweens(0.5);
+    assert.equal(target.x, 50);
+    assert.equal(target.y, 25);
+    assert.equal(target.scale, 1.5);
+
+    updateTweens(0.5);
+    assert.equal(target.x, 100);
+    assert.equal(target.y, 50);
+    assert.equal(target.scale, 2);
+  });
+
+  it("should handle delay", () => {
+    const target = { x: 0 };
+    const t = tween(target, { x: 100 }, 1.0, { delay: 0.5 });
+
+    // Initially pending
+    assert.equal(t.state, TweenState.PENDING);
+
+    // During delay, target unchanged
+    updateTweens(0.3);
+    assert.equal(target.x, 0);
+    assert.equal(t.state, TweenState.PENDING);
+
+    // After delay, tween starts
+    updateTweens(0.2);
+    assert.equal(t.state, TweenState.ACTIVE);
+
+    // Now tweening
+    updateTweens(0.5);
+    assert.equal(target.x, 50);
+  });
+
+  it("should call onStart callback after delay", () => {
+    let started = false;
+    const target = { x: 0 };
+
+    tween(target, { x: 100 }, 1.0, {
+      delay: 0.5,
+      onStart: () => {
+        started = true;
+      },
+    });
+
+    assert.equal(started, false);
+
+    // Before delay ends
+    updateTweens(0.3);
+    assert.equal(started, false);
+
+    // After delay ends
+    updateTweens(0.2);
+    assert.equal(started, true);
+  });
+
+  it("should call onUpdate callback", () => {
+    let updateCount = 0;
+    let lastProgress = 0;
+    const target = { x: 0 };
+
+    tween(target, { x: 100 }, 1.0, {
+      onUpdate: (progress) => {
+        updateCount++;
+        lastProgress = progress;
+      },
+    });
+
+    updateTweens(0.5);
+    assert.equal(updateCount, 1);
+    assert.ok(Math.abs(lastProgress - 0.5) < 0.01, `Expected progress ~0.5, got ${lastProgress}`);
+
+    updateTweens(0.5);
+    assert.equal(updateCount, 2);
+    assert.ok(Math.abs(lastProgress - 1.0) < 0.01, `Expected progress ~1.0, got ${lastProgress}`);
+  });
+
+  it("should call onComplete callback", () => {
+    let completed = false;
+    const target = { x: 0 };
+
+    tween(target, { x: 100 }, 1.0, {
+      onComplete: () => {
+        completed = true;
+      },
+    });
+
+    updateTweens(0.5);
+    assert.equal(completed, false);
+
+    updateTweens(0.5);
+    assert.equal(completed, true);
+  });
+
+  it("should remove completed tweens from active list", () => {
+    const target = { x: 0 };
+    tween(target, { x: 100 }, 1.0);
+
+    assert.equal(getActiveTweenCount(), 1);
+
+    updateTweens(1.0);
+    assert.equal(getActiveTweenCount(), 0);
+  });
+
+  it("should handle repeat", () => {
+    let repeatCount = 0;
+    const target = { x: 0 };
+
+    tween(target, { x: 100 }, 1.0, {
+      repeat: 2,
+      onRepeat: () => {
+        repeatCount++;
+      },
+    });
+
+    // First iteration
+    updateTweens(1.0);
+    assert.equal(target.x, 100);
+    assert.equal(repeatCount, 1);
+
+    // Second iteration
+    updateTweens(1.0);
+    assert.equal(target.x, 100);
+    assert.equal(repeatCount, 2);
+
+    // Third iteration (completes)
+    updateTweens(1.0);
+    assert.equal(target.x, 100);
+    assert.equal(repeatCount, 2);
+    assert.equal(getActiveTweenCount(), 0);
+  });
+
+  it("should handle infinite repeat", () => {
+    const target = { x: 0 };
+    tween(target, { x: 100 }, 1.0, { repeat: -1 });
+
+    for (let i = 0; i < 10; i++) {
+      updateTweens(1.0);
+      assert.equal(target.x, 100);
+    }
+
+    // Should still be active
+    assert.equal(getActiveTweenCount(), 1);
+  });
+
+  it("should handle yoyo mode", () => {
+    stopAllTweens();
+    const target = { x: 0 };
+    tween(target, { x: 100 }, 1.0, { repeat: 1, yoyo: true });
+
+    // Forward
+    updateTweens(1.0);
+    assert.equal(target.x, 100);
+
+    // Backward
+    updateTweens(1.0);
+    assert.equal(target.x, 0);
+
+    assert.equal(getActiveTweenCount(), 0);
+  });
+
+  it("should stop a tween", () => {
+    stopAllTweens();
+    const target = { x: 0 };
+    const t = tween(target, { x: 100 }, 1.0);
+
+    updateTweens(0.5);
+    assert.equal(target.x, 50);
+
+    stopTween(t);
+    assert.equal(t.state, TweenState.STOPPED);
+    assert.equal(getActiveTweenCount(), 0);
+
+    // Further updates do nothing
+    updateTweens(0.5);
+    assert.equal(target.x, 50);
+  });
+
+  it("should pause and resume a tween", () => {
+    const target = { x: 0 };
+    const t = tween(target, { x: 100 }, 1.0);
+
+    updateTweens(0.3);
+    assert.equal(target.x, 30);
+
+    pauseTween(t);
+    assert.equal(t.state, TweenState.PAUSED);
+
+    // No update while paused
+    updateTweens(0.5);
+    assert.equal(target.x, 30);
+
+    resumeTween(t);
+    assert.equal(t.state, TweenState.ACTIVE);
+
+    // Continues from where it left off
+    updateTweens(0.5);
+    assert.equal(target.x, 80);
+  });
+
+  it("should handle multiple simultaneous tweens", () => {
+    stopAllTweens();
+    const target1 = { x: 0 };
+    const target2 = { y: 0 };
+    const target3 = { z: 0 };
+
+    tween(target1, { x: 100 }, 1.0);
+    tween(target2, { y: 200 }, 2.0);
+    tween(target3, { z: 50 }, 0.5);
+
+    assert.equal(getActiveTweenCount(), 3);
+
+    updateTweens(0.5);
+    assert.equal(target1.x, 50);
+    assert.equal(target2.y, 50);
+    assert.equal(target3.z, 50);
+    assert.equal(getActiveTweenCount(), 2); // target3 completed
+
+    updateTweens(0.5);
+    assert.equal(target1.x, 100);
+    assert.equal(target2.y, 100);
+    assert.equal(getActiveTweenCount(), 1); // target1 completed
+
+    updateTweens(1.0);
+    assert.equal(target2.y, 200);
+    assert.equal(getActiveTweenCount(), 0); // all completed
+  });
+
+  it("should stop all tweens", () => {
+    stopAllTweens();
+    tween({ x: 0 }, { x: 100 }, 1.0);
+    tween({ y: 0 }, { y: 100 }, 1.0);
+    tween({ z: 0 }, { z: 100 }, 1.0);
+
+    assert.equal(getActiveTweenCount(), 3);
+
+    stopAllTweens();
+    assert.equal(getActiveTweenCount(), 0);
+  });
+
+  it("should handle custom easing function", () => {
+    const target = { x: 0 };
+    // Square easing: t^2
+    tween(target, { x: 100 }, 1.0, {
+      easing: (t) => t * t,
+    });
+
+    updateTweens(0.5);
+    // With square easing: 0.5^2 = 0.25
+    assert.equal(target.x, 25);
+
+    updateTweens(0.5);
+    assert.equal(target.x, 100);
+  });
+
+  it("should handle negative target values", () => {
+    const target = { x: 100 };
+    tween(target, { x: -50 }, 1.0);
+
+    updateTweens(0.5);
+    assert.equal(target.x, 25); // Halfway between 100 and -50
+
+    updateTweens(0.5);
+    assert.equal(target.x, -50);
+  });
+
+  it("should initialize missing properties to zero", () => {
+    const target: any = {};
+    tween(target, { x: 100 }, 1.0);
+
+    updateTweens(0.5);
+    assert.equal(target.x, 50);
+  });
+
+  it("should handle zero duration", () => {
+    stopAllTweens();
+    const target = { x: 0 };
+    tween(target, { x: 100 }, 0);
+
+    // Should complete immediately
+    updateTweens(0);
+    assert.equal(target.x, 100);
+    assert.equal(getActiveTweenCount(), 0);
+  });
+});