@arcane-engine/runtime 0.1.0 → 0.2.1

package/src/tweening/tween.ts

@@ -0,0 +1,296 @@
+/**
+ * Core tweening implementation.
+ *
+ * Manages a global list of active tweens. Call {@link updateTweens} once per
+ * frame (typically inside your `onFrame` callback) to advance all tweens.
+ */
+
+import type {
+  Tween,
+  TweenOptions,
+  TweenProps,
+  EasingFunction,
+} from "./types.ts";
+import { TweenState } from "./types.ts";
+
+/** Active tweens being updated */
+const activeTweens: Tween[] = [];
+
+/** Counter for generating unique tween IDs */
+let tweenIdCounter = 0;
+
+/**
+ * Linear easing function (identity). Used as the default when no easing is specified.
+ * @param t - Progress from 0 to 1.
+ * @returns The same value `t`, unchanged.
+ */
+export function linear(t: number): number {
+  return t;
+}
+
+/**
+ * Create and start a tween that interpolates numeric properties on `target`
+ * from their current values to the values specified in `props`.
+ *
+ * The tween is automatically added to the global update list. Call
+ * {@link updateTweens} each frame to advance it.
+ *
+ * @param target - Object whose numeric properties will be interpolated.
+ * @param props - Map of property names to their target (end) values.
+ * @param duration - Animation duration in seconds. Use 0 for instant.
+ * @param options - Optional easing, delay, repeat, yoyo, and lifecycle callbacks.
+ * @returns The created {@link Tween} instance for further control.
+ *
+ * @example
+ * ```ts
+ * const sprite = { x: 0, y: 0, alpha: 1 };
+ * // Move sprite to (100, 50) over 0.5 seconds with ease-out
+ * const t = tween(sprite, { x: 100, y: 50 }, 0.5, {
+ *   easing: easeOutQuad,
+ *   onComplete: () => console.log("done!"),
+ * });
+ * ```
+ */
+export function tween(
+  target: any,
+  props: TweenProps,
+  duration: number,
+  options: TweenOptions = {},
+): Tween {
+  const tweenInstance: Tween = {
+    id: `tween_${tweenIdCounter++}`,
+    state: options.delay && options.delay > 0 ? TweenState.PENDING : TweenState.ACTIVE,
+    target,
+    props,
+    startValues: {}, // Will be captured when tween starts
+    duration,
+    options: {
+      easing: options.easing ?? linear,
+      delay: options.delay ?? 0,
+      repeat: options.repeat ?? 0,
+      yoyo: options.yoyo ?? false,
+      onStart: options.onStart,
+      onUpdate: options.onUpdate,
+      onComplete: options.onComplete,
+      onRepeat: options.onRepeat,
+    },
+    elapsed: 0,
+    delayElapsed: 0,
+    currentRepeat: 0,
+    isReversed: false,
+  };
+
+  // If no delay, capture start values and call onStart immediately
+  if (tweenInstance.options.delay === 0) {
+    captureStartValues(tweenInstance);
+    if (tweenInstance.options.onStart) {
+      tweenInstance.options.onStart();
+    }
+  }
+
+  activeTweens.push(tweenInstance);
+  return tweenInstance;
+}
+
+/**
+ * Advance all active tweens by the given delta time.
+ *
+ * Call this once per frame in your game loop. Handles delay, easing,
+ * property interpolation, repeat/yoyo, and lifecycle callbacks.
+ * Completed and stopped tweens are automatically removed from the list.
+ *
+ * @param dt - Elapsed time since last frame, in seconds. Must be >= 0.
+ */
+export function updateTweens(dt: number): void {
+  for (let i = activeTweens.length - 1; i >= 0; i--) {
+    const t = activeTweens[i];
+
+    if (t.state === TweenState.PAUSED) {
+      continue;
+    }
+
+    if (t.state === TweenState.PENDING) {
+      // Handle delay
+      t.delayElapsed += dt;
+      if (t.delayElapsed >= t.options.delay) {
+        t.state = TweenState.ACTIVE;
+        captureStartValues(t);
+        if (t.options.onStart) {
+          t.options.onStart();
+        }
+      }
+      continue;
+    }
+
+    if (t.state !== TweenState.ACTIVE) {
+      continue;
+    }
+
+    // Update elapsed time
+    t.elapsed += dt;
+
+    // Calculate progress (0 to 1)
+    // Handle zero duration specially
+    let progress = t.duration === 0 ? 1.0 : Math.min(t.elapsed / t.duration, 1.0);
+
+    // Apply easing
+    const easedProgress = t.options.easing(progress);
+
+    // Update target properties
+    updateTargetProps(t, easedProgress);
+
+    // Call onUpdate callback
+    if (t.options.onUpdate) {
+      t.options.onUpdate(progress);
+    }
+
+    // Check if tween is complete
+    if (progress >= 1.0) {
+      handleTweenComplete(t, i);
+    }
+  }
+}
+
+/**
+ * Capture start values from target
+ */
+function captureStartValues(t: Tween): void {
+  for (const key in t.props) {
+    t.startValues[key] = t.target[key] ?? 0;
+  }
+}
+
+/**
+ * Update target properties based on progress
+ */
+function updateTargetProps(t: Tween, easedProgress: number): void {
+  for (const key in t.props) {
+    const start = t.startValues[key];
+    const end = t.props[key];
+    const delta = end - start;
+    t.target[key] = start + delta * easedProgress;
+  }
+}
+
+/**
+ * Handle tween completion
+ */
+function handleTweenComplete(t: Tween, index: number): void {
+  // Check for repeat
+  if (t.options.repeat === -1 || t.currentRepeat < t.options.repeat) {
+    t.currentRepeat++;
+    t.elapsed = 0;
+
+    // Handle yoyo
+    if (t.options.yoyo) {
+      // Swap start and target values to reverse direction
+      const temp = { ...t.startValues };
+      t.startValues = { ...t.props };
+      t.props = temp;
+    } else {
+      // Reset to original start values
+      captureStartValues(t);
+    }
+
+    if (t.options.onRepeat) {
+      t.options.onRepeat();
+    }
+  } else {
+    // Tween complete
+    t.state = TweenState.COMPLETED;
+
+    if (t.options.onComplete) {
+      t.options.onComplete();
+    }
+
+    // Remove from active tweens
+    activeTweens.splice(index, 1);
+  }
+}
+
+/**
+ * Stop a tween immediately and remove it from the update list.
+ * Sets state to {@link TweenState.STOPPED}. The `onComplete` callback is NOT called.
+ *
+ * @param t - The tween to stop.
+ */
+export function stopTween(t: Tween): void {
+  t.state = TweenState.STOPPED;
+  const index = activeTweens.indexOf(t);
+  if (index !== -1) {
+    activeTweens.splice(index, 1);
+  }
+}
+
+/**
+ * Pause a tween, freezing it at its current progress.
+ * Only affects tweens in "active" or "pending" state. Use {@link resumeTween} to continue.
+ *
+ * @param t - The tween to pause.
+ */
+export function pauseTween(t: Tween): void {
+  if (t.state === TweenState.ACTIVE || t.state === TweenState.PENDING) {
+    t.state = TweenState.PAUSED;
+  }
+}
+
+/**
+ * Resume a paused tween from where it left off.
+ * Restores the tween to "active" or "pending" state depending on whether the delay had elapsed.
+ * No-op if the tween is not paused.
+ *
+ * @param t - The tween to resume.
+ */
+export function resumeTween(t: Tween): void {
+  if (t.state === TweenState.PAUSED) {
+    t.state = t.delayElapsed < t.options.delay ? TweenState.PENDING : TweenState.ACTIVE;
+  }
+}
+
+/**
+ * Stop all active tweens and clear the update list.
+ * Sets every tween's state to {@link TweenState.STOPPED}. No `onComplete` callbacks are called.
+ */
+export function stopAllTweens(): void {
+  for (const t of activeTweens) {
+    t.state = TweenState.STOPPED;
+  }
+  activeTweens.length = 0;
+}
+
+/**
+ * Reverse a tween's direction mid-flight.
+ *
+ * Captures the target's current property values as the new start,
+ * and sets the original start values as the new target. Resets elapsed
+ * time so the tween animates back from the current position.
+ *
+ * @param t - The tween to reverse.
+ */
+export function reverseTween(t: Tween): void {
+  // Capture current values as the new start
+  const currentValues: Record<string, number> = {};
+  for (const key in t.props) {
+    currentValues[key] = t.target[key];
+  }
+
+  // New target is the old start
+  const newTarget = { ...t.startValues };
+
+  // Update tween
+  t.startValues = currentValues;
+  t.props = newTarget;
+
+  // Reset elapsed to animate from current position
+  t.elapsed = 0;
+}
+
+/**
+ * Get the number of tweens currently in the update list (active, pending, or paused).
+ * Useful for debugging and testing.
+ *
+ * @returns Count of tweens that have not yet completed or been stopped.
+ */
+export function getActiveTweenCount(): number {
+  return activeTweens.length;
+}

package/src/tweening/types.ts

@@ -0,0 +1,134 @@
+/**
+ * Tweening system type definitions.
+ *
+ * Tweens smoothly interpolate numeric properties on any object over time.
+ * Used for animations, UI transitions, camera effects, and game juice.
+ */
+
+/**
+ * A function that maps linear progress to eased progress.
+ * See `runtime/tweening/easing.ts` for 30 built-in easing functions.
+ *
+ * @param t - Linear progress, clamped to 0..1 by the tween system.
+ * @returns Eased value. Usually 0..1, but may overshoot for back/elastic easings.
+ */
+export type EasingFunction = (t: number) => number;
+
+/**
+ * Callback invoked at tween lifecycle events (start, complete, repeat).
+ */
+export type TweenCallback = () => void;
+
+/**
+ * Callback invoked every frame while a tween is active.
+ * @param progress - Linear progress from 0 to 1 (before easing).
+ */
+export type TweenUpdateCallback = (progress: number) => void;
+
+/**
+ * Options for creating a tween via {@link tween}.
+ *
+ * All fields are optional; sensible defaults are applied (linear easing, no delay, no repeat).
+ */
+export interface TweenOptions {
+  /** Easing function applied to progress. Default: linear (no easing). */
+  easing?: EasingFunction;
+  /** Delay in seconds before the tween starts animating. Default: 0. Must be >= 0. */
+  delay?: number;
+  /** Number of additional times to repeat after the first play. 0 = play once, -1 = infinite. Default: 0. */
+  repeat?: number;
+  /** When true, alternates direction on each repeat (ping-pong). Default: false. */
+  yoyo?: boolean;
+  /** Called once when the tween transitions from pending to active (after delay elapses). */
+  onStart?: TweenCallback;
+  /** Called every frame while the tween is active. Receives linear progress (0..1). */
+  onUpdate?: TweenUpdateCallback;
+  /** Called once when the tween finishes all iterations. Not called if stopped manually. */
+  onComplete?: TweenCallback;
+  /** Called each time the tween starts a new repeat iteration. */
+  onRepeat?: TweenCallback;
+}
+
+/**
+ * A map of property names to their target numeric values.
+ * Each key must correspond to a numeric property on the tween target object.
+ */
+export type TweenProps = Record<string, number>;
+
+/**
+ * Lifecycle state of a tween instance.
+ *
+ * Transitions: pending -> active -> completed (normal flow),
+ * active <-> paused (via pauseTween/resumeTween),
+ * any -> stopped (via stopTween).
+ */
+export type TweenState = "pending" | "active" | "paused" | "completed" | "stopped";
+
+/**
+ * Tween state constants for comparing against {@link Tween.state}.
+ *
+ * @example
+ * ```ts
+ * if (myTween.state === TweenState.ACTIVE) { ... }
+ * ```
+ */
+export const TweenState = {
+  /** Waiting for delay to elapse before starting. */
+  PENDING: "pending" as const,
+  /** Currently animating properties each frame. */
+  ACTIVE: "active" as const,
+  /** Temporarily paused; resumes from current progress via resumeTween(). */
+  PAUSED: "paused" as const,
+  /** All iterations complete. The tween has been removed from the update list. */
+  COMPLETED: "completed" as const,
+  /** Manually stopped via stopTween(). The tween has been removed from the update list. */
+  STOPPED: "stopped" as const,
+};
+
+/**
+ * A tween instance returned by {@link tween}.
+ *
+ * Inspect `state` to check lifecycle. Use `stopTween()`, `pauseTween()`,
+ * `resumeTween()`, or `reverseTween()` to control playback.
+ */
+export interface Tween {
+  /** Unique identifier, auto-generated as "tween_0", "tween_1", etc. */
+  id: string;
+  /** Current lifecycle state. See {@link TweenState}. */
+  state: TweenState;
+  /** The object whose properties are being interpolated. */
+  target: any;
+  /** Target values for each property being tweened. */
+  props: TweenProps;
+  /** Start values captured when the tween becomes active (after delay). */
+  startValues: TweenProps;
+  /** Total animation duration in seconds (excluding delay). Must be >= 0. */
+  duration: number;
+  /** Resolved options with defaults applied. */
+  options: {
+    /** Easing function applied to progress. */
+    easing: EasingFunction;
+    /** Delay in seconds before animation starts. */
+    delay: number;
+    /** Number of additional repeat iterations. -1 = infinite. */
+    repeat: number;
+    /** Whether direction alternates on repeat. */
+    yoyo: boolean;
+    /** Called when tween transitions to active. */
+    onStart?: TweenCallback;
+    /** Called every frame with linear progress (0..1). */
+    onUpdate?: TweenUpdateCallback;
+    /** Called when all iterations complete. */
+    onComplete?: TweenCallback;
+    /** Called at the start of each repeat iteration. */
+    onRepeat?: TweenCallback;
+  };
+  /** Seconds elapsed since the tween became active (resets on repeat). */
+  elapsed: number;
+  /** Seconds elapsed during the delay phase. */
+  delayElapsed: number;
+  /** Zero-based index of the current repeat iteration. */
+  currentRepeat: number;
+  /** True when playing in reverse direction (yoyo mode). */
+  isReversed: boolean;
+}

package/src/ui/colors.ts

@@ -0,0 +1,129 @@
+/**
+ * Standard color palette and layout helpers for consistent UI styling.
+ */
+
+import type { Color } from "./types.ts";
+
+/**
+ * Arcane UI Color Palette.
+ * Pre-defined colors (0.0-1.0 RGBA) for consistent visual style across all demos.
+ */
+export const Colors = {
+  // Primary UI Colors
+  /** Bright blue. */
+  PRIMARY: { r: 0.2, g: 0.6, b: 1.0, a: 1.0 },
+  /** Green (success state). */
+  SUCCESS: { r: 0.2, g: 0.8, b: 0.3, a: 1.0 },
+  /** Orange/Yellow (warning state). */
+  WARNING: { r: 1.0, g: 0.7, b: 0.0, a: 1.0 },
+  /** Red (danger/error state). */
+  DANGER: { r: 1.0, g: 0.3, b: 0.3, a: 1.0 },
+  /** Cyan (informational). */
+  INFO: { r: 0.4, g: 0.8, b: 0.9, a: 1.0 },
+
+  // Grayscale
+  /** Pure white. */
+  WHITE: { r: 1.0, g: 1.0, b: 1.0, a: 1.0 },
+  /** Light gray. */
+  LIGHT_GRAY: { r: 0.8, g: 0.8, b: 0.8, a: 1.0 },
+  /** Medium gray. */
+  GRAY: { r: 0.5, g: 0.5, b: 0.5, a: 1.0 },
+  /** Dark gray. */
+  DARK_GRAY: { r: 0.3, g: 0.3, b: 0.3, a: 1.0 },
+  /** Pure black. */
+  BLACK: { r: 0.0, g: 0.0, b: 0.0, a: 1.0 },
+
+  // HUD backgrounds (semi-transparent)
+  /** Dark semi-transparent background for HUD panels. */
+  HUD_BG: { r: 0.1, g: 0.1, b: 0.15, a: 0.85 },
+  /** Lighter semi-transparent background for HUD panels. */
+  HUD_BG_LIGHT: { r: 0.2, g: 0.2, b: 0.25, a: 0.75 },
+
+  // Common game colors
+  /** Gold color for scores, coins, rewards. */
+  GOLD: { r: 1.0, g: 0.84, b: 0.0, a: 1.0 },
+  /** Silver color for secondary rewards. */
+  SILVER: { r: 0.75, g: 0.75, b: 0.75, a: 1.0 },
+  /** Bronze color for tertiary rewards. */
+  BRONZE: { r: 0.8, g: 0.5, b: 0.2, a: 1.0 },
+
+  // Game state colors
+  /** Bright green for victory/win state. */
+  WIN: { r: 0.2, g: 1.0, b: 0.4, a: 1.0 },
+  /** Bright red for defeat/lose state. */
+  LOSE: { r: 1.0, g: 0.2, b: 0.2, a: 1.0 },
+  /** Yellow for paused state. */
+  PAUSED: { r: 0.9, g: 0.9, b: 0.2, a: 1.0 },
+} as const;
+
+/**
+ * Standard HUD layout positions and spacing for an 800x600 viewport.
+ * Provides consistent anchor points for common HUD element placement.
+ */
+export const HUDLayout = {
+  /** Standard padding from screen edges in pixels. */
+  PADDING: 10,
+  /** Vertical spacing between HUD lines in pixels. */
+  LINE_HEIGHT: 25,
+  /** Default text scale for main HUD text. */
+  TEXT_SCALE: 2,
+  /** Smaller text scale for secondary HUD text. */
+  SMALL_TEXT_SCALE: 1.5,
+
+  // Standard positions (screen-space pixel coordinates)
+  /** Top-left corner position. */
+  TOP_LEFT: { x: 10, y: 10 },
+  /** Top-right corner position. */
+  TOP_RIGHT: { x: 700, y: 10 },
+  /** Bottom-left corner position. */
+  BOTTOM_LEFT: { x: 10, y: 560 },
+  /** Bottom-right corner position. */
+  BOTTOM_RIGHT: { x: 700, y: 560 },
+  /** Screen center position. */
+  CENTER: { x: 400, y: 300 },
+} as const;
+
+/**
+ * Create a semi-transparent version of a color.
+ *
+ * @param color - Source color.
+ * @param alpha - New alpha value, 0.0 (transparent) to 1.0 (opaque).
+ * @returns New Color with the same RGB but the specified alpha.
+ */
+export function withAlpha(color: Color, alpha: number): Color {
+  return { ...color, a: alpha };
+}
+
+/**
+ * Lighten a color by adding a fixed amount to each RGB channel (clamped to 1.0).
+ * Useful for hover effects and highlights.
+ *
+ * @param color - Source color.
+ * @param amount - Amount to add to each RGB channel, 0.0-1.0. Default: 0.2.
+ * @returns New lightened Color (alpha unchanged).
+ */
+export function lighten(color: Color, amount: number = 0.2): Color {
+  return {
+    r: Math.min(1.0, color.r + amount),
+    g: Math.min(1.0, color.g + amount),
+    b: Math.min(1.0, color.b + amount),
+    a: color.a,
+  };
+}
+
+/**
+ * Darken a color by subtracting a fixed amount from each RGB channel (clamped to 0.0).
+ * Useful for pressed states and shadows.
+ *
+ * @param color - Source color.
+ * @param amount - Amount to subtract from each RGB channel, 0.0-1.0. Default: 0.2.
+ * @returns New darkened Color (alpha unchanged).
+ */
+export function darken(color: Color, amount: number = 0.2): Color {
+  return {
+    r: Math.max(0.0, color.r - amount),
+    g: Math.max(0.0, color.g - amount),
+    b: Math.max(0.0, color.b - amount),
+    a: color.a,
+  };
+}

package/src/ui/index.ts

@@ -1,3 +1,4 @@
 export type { Color, RectOptions, PanelOptions, BarOptions, LabelOptions } from "./types.ts";
 export { rgb } from "./types.ts";
 export { drawRect, drawPanel, drawBar, drawLabel } from "./primitives.ts";
+export { Colors, HUDLayout, withAlpha, lighten, darken } from "./colors.ts";

package/src/ui/primitives.ts

@@ -63,6 +63,19 @@ function toWorld(
 /**
  * Draw a filled rectangle.
  * No-op in headless mode.
+ *
+ * @param x - X position (screen pixels if screenSpace, world units otherwise).
+ * @param y - Y position (screen pixels if screenSpace, world units otherwise).
+ * @param w - Width in pixels (screenSpace) or world units.
+ * @param h - Height in pixels (screenSpace) or world units.
+ * @param options - Color, layer, and screenSpace options.
+ *
+ * @example
+ * // Draw a red rectangle in screen space (HUD)
+ * drawRect(10, 10, 200, 30, {
+ *   color: { r: 1, g: 0, b: 0, a: 0.8 },
+ *   screenSpace: true,
+ * });
  */
 export function drawRect(
   x: number,
@@ -85,9 +98,23 @@ export function drawRect(
 }
 
 /**
- * Draw a panel with border and fill.
- * Uses 5 sprites: 4 border edges + 1 fill.
+ * Draw a panel with border and fill (5 sprites: 4 border edges + 1 fill).
  * No-op in headless mode.
+ *
+ * @param x - X position (screen pixels if screenSpace, world units otherwise).
+ * @param y - Y position (screen pixels if screenSpace, world units otherwise).
+ * @param w - Total width including border.
+ * @param h - Total height including border.
+ * @param options - Fill color, border color, border width, layer, and screenSpace options.
+ *
+ * @example
+ * // Draw a HUD panel
+ * drawPanel(10, 10, 200, 100, {
+ *   fillColor: { r: 0.1, g: 0.1, b: 0.2, a: 0.9 },
+ *   borderColor: { r: 0.5, g: 0.5, b: 0.5, a: 1 },
+ *   borderWidth: 2,
+ *   screenSpace: true,
+ * });
  */
 export function drawPanel(
   x: number,
@@ -148,9 +175,15 @@ export function drawPanel(
 }
 
 /**
- * Draw a progress/health bar.
- * fillRatio is 0.0 to 1.0 (clamped).
+ * Draw a progress/health bar with background, fill, and optional border.
  * No-op in headless mode.
+ *
+ * @param x - X position (screen pixels if screenSpace, world units otherwise).
+ * @param y - Y position (screen pixels if screenSpace, world units otherwise).
+ * @param w - Total width.
+ * @param h - Total height.
+ * @param fillRatio - Fill amount, 0.0 (empty) to 1.0 (full). Clamped to this range.
+ * @param options - Colors, border, layer, and screenSpace options.
  */
 export function drawBar(
   x: number,
@@ -222,8 +255,14 @@ export function drawBar(
 }
 
 /**
- * Draw a text label with optional background panel.
+ * Draw a text label with an automatic background panel.
+ * Panel size is computed from the text measurement + padding.
  * No-op in headless mode.
+ *
+ * @param text - The text string to display.
+ * @param x - X position (screen pixels if screenSpace, world units otherwise).
+ * @param y - Y position (screen pixels if screenSpace, world units otherwise).
+ * @param options - Text color, background, border, padding, scale, layer, and screenSpace.
  */
 export function drawLabel(
   text: string,