@arcane-engine/runtime 0.1.0 → 0.2.0

package/src/particles/emitter.ts

@@ -0,0 +1,409 @@
+/**
+ * Particle emitter implementation.
+ *
+ * Manages a global list of emitters. Call {@link updateParticles} once per frame
+ * to spawn new particles and advance existing ones. Then read particles via
+ * {@link getAllParticles} for rendering.
+ */
+
+import type {
+  Particle,
+  Emitter,
+  EmitterConfig,
+  Affector,
+} from "./types.ts";
+
+/** Active emitters being updated each frame. */
+const emitters: Emitter[] = [];
+
+/** Counter for generating unique emitter IDs. */
+let emitterIdCounter = 0;
+
+/**
+ * Create a new particle emitter and add it to the global update list.
+ *
+ * The emitter immediately begins spawning particles according to its
+ * configuration (mode, rate, shape, etc.).
+ *
+ * @param config - Emitter configuration describing shape, mode, particle properties, and colors.
+ * @returns The created {@link Emitter} instance.
+ *
+ * @example
+ * ```ts
+ * const sparks = createEmitter({
+ *   shape: "point",
+ *   x: 100, y: 100,
+ *   mode: "burst",
+ *   burstCount: 20,
+ *   lifetime: [0.3, 0.8],
+ *   velocityX: [-50, 50],
+ *   velocityY: [-100, -20],
+ *   startColor: { r: 1, g: 0.8, b: 0, a: 1 },
+ *   endColor: { r: 1, g: 0, b: 0, a: 0 },
+ *   textureId: sparkTexture,
+ * });
+ * ```
+ */
+export function createEmitter(config: EmitterConfig): Emitter {
+  const emitter: Emitter = {
+    id: `emitter_${emitterIdCounter++}`,
+    config,
+    particles: [],
+    pool: [],
+    affectors: [],
+    emissionAccumulator: 0,
+    active: true,
+    used: false,
+  };
+
+  emitters.push(emitter);
+  return emitter;
+}
+
+/**
+ * Remove an emitter from the global update list.
+ * Its particles will no longer be updated or included in {@link getAllParticles}.
+ *
+ * @param emitter - The emitter to remove.
+ */
+export function removeEmitter(emitter: Emitter): void {
+  const index = emitters.indexOf(emitter);
+  if (index !== -1) {
+    emitters.splice(index, 1);
+  }
+}
+
+/**
+ * Get a particle from the pool or create a new one
+ */
+function getParticle(emitter: Emitter): Particle {
+  // Try to reuse from pool
+  for (const p of emitter.pool) {
+    if (!p.alive) {
+      p.alive = true;
+      return p;
+    }
+  }
+
+  // Create new particle
+  const particle: Particle = {
+    x: 0,
+    y: 0,
+    vx: 0,
+    vy: 0,
+    ax: 0,
+    ay: 0,
+    rotation: 0,
+    rotationSpeed: 0,
+    scale: 1,
+    scaleSpeed: 0,
+    color: { r: 1, g: 1, b: 1, a: 1 },
+    startColor: { r: 1, g: 1, b: 1, a: 1 },
+    endColor: { r: 1, g: 1, b: 1, a: 1 },
+    lifetime: 1,
+    age: 0,
+    alive: true,
+    textureId: 0,
+  };
+
+  emitter.pool.push(particle);
+  return particle;
+}
+
+/**
+ * Random number in range [min, max]
+ */
+function randomRange(min: number, max: number): number {
+  return min + Math.random() * (max - min);
+}
+
+/**
+ * Interpolate between colors based on t (0 to 1)
+ */
+function lerpColor(start: any, end: any, t: number) {
+  return {
+    r: start.r + (end.r - start.r) * t,
+    g: start.g + (end.g - start.g) * t,
+    b: start.b + (end.b - start.b) * t,
+    a: start.a + (end.a - start.a) * t,
+  };
+}
+
+/**
+ * Spawn a single particle from an emitter
+ */
+function spawnParticle(emitter: Emitter): void {
+  const { config } = emitter;
+
+  // Check max particles limit
+  const aliveCount = emitter.particles.filter((p) => p.alive).length;
+  if (config.maxParticles && aliveCount >= config.maxParticles) {
+    return;
+  }
+
+  const particle = getParticle(emitter);
+
+  // Set position based on emitter shape
+  switch (config.shape) {
+    case "point":
+      particle.x = config.x;
+      particle.y = config.y;
+      break;
+
+    case "line": {
+      const t = Math.random();
+      const x2 = config.shapeParams?.x2 ?? config.x;
+      const y2 = config.shapeParams?.y2 ?? config.y;
+      particle.x = config.x + (x2 - config.x) * t;
+      particle.y = config.y + (y2 - config.y) * t;
+      break;
+    }
+
+    case "area": {
+      const w = config.shapeParams?.width ?? 100;
+      const h = config.shapeParams?.height ?? 100;
+      particle.x = config.x + Math.random() * w;
+      particle.y = config.y + Math.random() * h;
+      break;
+    }
+
+    case "ring": {
+      const inner = config.shapeParams?.innerRadius ?? 0;
+      const outer = config.shapeParams?.outerRadius ?? 50;
+      const angle = Math.random() * Math.PI * 2;
+      const radius = randomRange(inner, outer);
+      particle.x = config.x + Math.cos(angle) * radius;
+      particle.y = config.y + Math.sin(angle) * radius;
+      break;
+    }
+  }
+
+  // Set velocity
+  particle.vx = randomRange(config.velocityX[0], config.velocityX[1]);
+  particle.vy = randomRange(config.velocityY[0], config.velocityY[1]);
+
+  // Set acceleration
+  if (config.accelerationX) {
+    particle.ax = randomRange(config.accelerationX[0], config.accelerationX[1]);
+  }
+  if (config.accelerationY) {
+    particle.ay = randomRange(config.accelerationY[0], config.accelerationY[1]);
+  }
+
+  // Set rotation
+  if (config.rotation) {
+    particle.rotation = randomRange(config.rotation[0], config.rotation[1]);
+  }
+  if (config.rotationSpeed) {
+    particle.rotationSpeed = randomRange(config.rotationSpeed[0], config.rotationSpeed[1]);
+  }
+
+  // Set scale
+  if (config.scale) {
+    particle.scale = randomRange(config.scale[0], config.scale[1]);
+  }
+  if (config.scaleSpeed) {
+    particle.scaleSpeed = randomRange(config.scaleSpeed[0], config.scaleSpeed[1]);
+  }
+
+  // Set colors
+  particle.startColor = { ...config.startColor };
+  particle.endColor = { ...config.endColor };
+  particle.color = { ...config.startColor };
+
+  // Set lifetime
+  particle.lifetime = randomRange(config.lifetime[0], config.lifetime[1]);
+  particle.age = 0;
+
+  // Set texture
+  particle.textureId = config.textureId;
+
+  // Add to active particles
+  if (!emitter.particles.includes(particle)) {
+    emitter.particles.push(particle);
+  }
+}
+
+/**
+ * Emit particles based on emitter mode and rate
+ */
+function emitParticles(emitter: Emitter, dt: number): void {
+  const { config, used } = emitter;
+
+  if (!emitter.active) return;
+
+  switch (config.mode) {
+    case "continuous": {
+      const rate = config.rate ?? 10;
+      emitter.emissionAccumulator += dt * rate;
+
+      while (emitter.emissionAccumulator >= 1) {
+        spawnParticle(emitter);
+        emitter.emissionAccumulator -= 1;
+      }
+      break;
+    }
+
+    case "burst": {
+      if (!used) {
+        const count = config.burstCount ?? 10;
+        for (let i = 0; i < count; i++) {
+          spawnParticle(emitter);
+        }
+        emitter.used = true;
+      }
+      break;
+    }
+
+    case "one-shot": {
+      if (!used) {
+        spawnParticle(emitter);
+        emitter.used = true;
+      }
+      break;
+    }
+  }
+}
+
+/**
+ * Update a single particle
+ */
+function updateParticle(particle: Particle, dt: number, affectors: Affector[]): void {
+  // Age the particle
+  particle.age += dt;
+
+  if (particle.age >= particle.lifetime) {
+    particle.alive = false;
+    return;
+  }
+
+  // Apply affectors
+  for (const affector of affectors) {
+    switch (affector.type) {
+      case "gravity":
+      case "wind": {
+        particle.ax += affector.forceX ?? 0;
+        particle.ay += affector.forceY ?? 0;
+        break;
+      }
+
+      case "attractor":
+      case "repulsor": {
+        const dx = (affector.centerX ?? 0) - particle.x;
+        const dy = (affector.centerY ?? 0) - particle.y;
+        const distSq = dx * dx + dy * dy;
+        const dist = Math.sqrt(distSq);
+
+        if (affector.radius === 0 || dist < affector.radius!) {
+          const strength = affector.strength ?? 100;
+          const force = (affector.type === "attractor" ? 1 : -1) * strength / Math.max(distSq, 1);
+          particle.ax += (dx / dist) * force;
+          particle.ay += (dy / dist) * force;
+        }
+        break;
+      }
+
+      case "turbulence": {
+        const turb = affector.turbulence ?? 10;
+        particle.ax += (Math.random() - 0.5) * turb;
+        particle.ay += (Math.random() - 0.5) * turb;
+        break;
+      }
+    }
+  }
+
+  // Update velocity
+  particle.vx += particle.ax * dt;
+  particle.vy += particle.ay * dt;
+
+  // Update position
+  particle.x += particle.vx * dt;
+  particle.y += particle.vy * dt;
+
+  // Update rotation
+  particle.rotation += particle.rotationSpeed * dt;
+
+  // Update scale
+  particle.scale += particle.scaleSpeed * dt;
+
+  // Interpolate color over lifetime
+  const t = particle.age / particle.lifetime;
+  particle.color = lerpColor(particle.startColor, particle.endColor, t);
+
+  // Reset acceleration (will be reapplied by affectors next frame)
+  particle.ax = 0;
+  particle.ay = 0;
+}
+
+/**
+ * Update all emitters and their particles by one frame.
+ *
+ * Spawns new particles based on each emitter's mode and rate, then
+ * advances all alive particles (velocity, position, rotation, scale,
+ * color interpolation, affectors, lifetime). Dead particles are marked
+ * `alive = false` and returned to the pool.
+ *
+ * Call this once per frame in your game loop.
+ *
+ * @param dt - Elapsed time since last frame in seconds. Must be >= 0.
+ */
+export function updateParticles(dt: number): void {
+  for (const emitter of emitters) {
+    // Emit new particles
+    emitParticles(emitter, dt);
+
+    // Update existing particles
+    for (const particle of emitter.particles) {
+      if (particle.alive) {
+        updateParticle(particle, dt, emitter.affectors);
+      }
+    }
+  }
+}
+
+/**
+ * Collect all alive particles from all active emitters.
+ *
+ * Use this each frame to get the particles to render (e.g., via drawSprite).
+ *
+ * @returns A new array of all alive {@link Particle} instances across all emitters.
+ */
+export function getAllParticles(): Particle[] {
+  const result: Particle[] = [];
+  for (const emitter of emitters) {
+    for (const particle of emitter.particles) {
+      if (particle.alive) {
+        result.push(particle);
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Add a particle affector to an emitter.
+ * Affectors modify particle acceleration each frame (gravity, wind, attraction, etc.).
+ *
+ * @param emitter - The emitter to add the affector to.
+ * @param affector - The affector configuration. See {@link Affector} for field details.
+ */
+export function addAffector(emitter: Emitter, affector: Affector): void {
+  emitter.affectors.push(affector);
+}
+
+/**
+ * Remove all emitters and their particles from the global update list.
+ */
+export function clearEmitters(): void {
+  emitters.length = 0;
+}
+
+/**
+ * Get the number of emitters currently in the global update list.
+ * Useful for debugging and testing.
+ *
+ * @returns Count of registered emitters (active or inactive).
+ */
+export function getEmitterCount(): number {
+  return emitters.length;
+}

package/src/particles/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Particle system
+ *
+ * Provides particle emitters with various shapes, emission modes, and affectors.
+ */
+
+export type {
+  Particle,
+  EmitterShape,
+  EmissionMode,
+  EmitterConfig,
+  AffectorType,
+  Affector,
+  Emitter,
+} from "./types.ts";
+
+export {
+  createEmitter,
+  removeEmitter,
+  updateParticles,
+  getAllParticles,
+  addAffector,
+  clearEmitters,
+  getEmitterCount,
+} from "./emitter.ts";

package/src/particles/types.ts

@@ -0,0 +1,236 @@
+/**
+ * Particle system type definitions.
+ *
+ * Particles are small, short-lived visual elements (sparks, smoke, debris, etc.)
+ * spawned by {@link Emitter}s and optionally modified by {@link Affector}s.
+ */
+
+import type { Color } from "../ui/types.ts";
+
+/**
+ * A single particle managed by an emitter.
+ *
+ * Particles are pooled and reused. Check `alive` before rendering.
+ * Color interpolates from `startColor` to `endColor` over the particle's lifetime.
+ */
+export interface Particle {
+  /** X position in world pixels. */
+  x: number;
+  /** Y position in world pixels. */
+  y: number;
+
+  /** X velocity in pixels per second. */
+  vx: number;
+  /** Y velocity in pixels per second. */
+  vy: number;
+
+  /** X acceleration in pixels per second squared. Reset each frame after affectors run. */
+  ax: number;
+  /** Y acceleration in pixels per second squared. Reset each frame after affectors run. */
+  ay: number;
+
+  /** Current rotation in radians. */
+  rotation: number;
+
+  /** Rotation speed in radians per second. */
+  rotationSpeed: number;
+
+  /** Current scale multiplier. 1.0 = original size. */
+  scale: number;
+
+  /** Scale change rate per second (positive = growing, negative = shrinking). */
+  scaleSpeed: number;
+
+  /** Current interpolated color (between startColor and endColor based on age/lifetime). */
+  color: Color;
+
+  /** Color at birth (age = 0). */
+  startColor: Color;
+
+  /** Color at death (age = lifetime). */
+  endColor: Color;
+
+  /** Total lifetime in seconds. The particle dies when age >= lifetime. */
+  lifetime: number;
+
+  /** Seconds since this particle was spawned. */
+  age: number;
+
+  /** Whether this particle is alive and should be updated/rendered. */
+  alive: boolean;
+
+  /** Texture ID used to render this particle via drawSprite(). */
+  textureId: number;
+}
+
+/**
+ * Shape of the emitter's spawn area.
+ * - `"point"` — all particles spawn at the emitter's (x, y).
+ * - `"line"` — particles spawn along a line from (x, y) to (x2, y2).
+ * - `"area"` — particles spawn randomly within a rectangle.
+ * - `"ring"` — particles spawn in an annular region between innerRadius and outerRadius.
+ */
+export type EmitterShape = "point" | "line" | "area" | "ring";
+
+/**
+ * How the emitter spawns particles.
+ * - `"continuous"` — spawns at a steady rate (particles/second) every frame.
+ * - `"burst"` — spawns `burstCount` particles all at once, then stops.
+ * - `"one-shot"` — spawns a single particle, then stops.
+ */
+export type EmissionMode = "continuous" | "burst" | "one-shot";
+
+/**
+ * Configuration for creating a particle emitter via {@link createEmitter}.
+ *
+ * Range fields like `lifetime`, `velocityX`, etc. are `[min, max]` tuples.
+ * Each spawned particle picks a random value within the range.
+ */
+export interface EmitterConfig {
+  /** Shape of the spawn area. See {@link EmitterShape}. */
+  shape: EmitterShape;
+
+  /** X position of the emitter in world pixels. */
+  x: number;
+  /** Y position of the emitter in world pixels. */
+  y: number;
+
+  /** Shape-specific parameters. Which fields are used depends on `shape`. */
+  shapeParams?: {
+    /** End X for "line" shape. Default: same as emitter x. */
+    x2?: number;
+    /** End Y for "line" shape. Default: same as emitter y. */
+    y2?: number;
+
+    /** Width in pixels for "area" shape. Default: 100. */
+    width?: number;
+    /** Height in pixels for "area" shape. Default: 100. */
+    height?: number;
+
+    /** Inner radius in pixels for "ring" shape. Default: 0. */
+    innerRadius?: number;
+    /** Outer radius in pixels for "ring" shape. Default: 50. */
+    outerRadius?: number;
+  };
+
+  /** How particles are spawned. See {@link EmissionMode}. */
+  mode: EmissionMode;
+
+  /** Spawn rate in particles per second. Used when mode is "continuous". Default: 10. */
+  rate?: number;
+
+  /** Number of particles to spawn at once. Used when mode is "burst". Default: 10. */
+  burstCount?: number;
+
+  /** Particle lifetime range [min, max] in seconds. Each particle gets a random value in range. */
+  lifetime: [number, number];
+
+  /** Initial X velocity range [min, max] in pixels/second. */
+  velocityX: [number, number];
+  /** Initial Y velocity range [min, max] in pixels/second. */
+  velocityY: [number, number];
+
+  /** Initial X acceleration range [min, max] in pixels/second^2. Optional. */
+  accelerationX?: [number, number];
+  /** Initial Y acceleration range [min, max] in pixels/second^2. Optional. */
+  accelerationY?: [number, number];
+
+  /** Initial rotation range [min, max] in radians. Optional. */
+  rotation?: [number, number];
+
+  /** Rotation speed range [min, max] in radians/second. Optional. */
+  rotationSpeed?: [number, number];
+
+  /** Initial scale range [min, max]. 1.0 = original size. Optional. */
+  scale?: [number, number];
+
+  /** Scale change rate range [min, max] per second. Optional. */
+  scaleSpeed?: [number, number];
+
+  /** Color at particle birth. RGBA with components 0.0..1.0. */
+  startColor: Color;
+
+  /** Color at particle death. Interpolated linearly from startColor over lifetime. */
+  endColor: Color;
+
+  /** Texture ID for rendering particles. Obtain via loadTexture() or createSolidTexture(). */
+  textureId: number;
+
+  /** Maximum alive particles for this emitter. New particles are not spawned if at limit. Default: unlimited. */
+  maxParticles?: number;
+}
+
+/**
+ * Types of particle affectors that modify particle behavior each frame.
+ * - `"gravity"` — constant downward (or any direction) force.
+ * - `"wind"` — constant directional force (same as gravity, semantic distinction).
+ * - `"attractor"` — pulls particles toward a point.
+ * - `"repulsor"` — pushes particles away from a point.
+ * - `"turbulence"` — random jitter applied to acceleration each frame.
+ */
+export type AffectorType = "gravity" | "wind" | "attractor" | "repulsor" | "turbulence";
+
+/**
+ * A particle affector that modifies particle acceleration each frame.
+ * Attach to an emitter via {@link addAffector}.
+ *
+ * Which fields are used depends on `type`:
+ * - gravity/wind: `forceX`, `forceY`
+ * - attractor/repulsor: `centerX`, `centerY`, `strength`, `radius`
+ * - turbulence: `turbulence`
+ */
+export interface Affector {
+  /** The type of force this affector applies. See {@link AffectorType}. */
+  type: AffectorType;
+
+  /** X component of force vector. Used by "gravity" and "wind". Default: 0. */
+  forceX?: number;
+  /** Y component of force vector. Used by "gravity" and "wind". Default: 0. */
+  forceY?: number;
+
+  /** X position of attraction/repulsion center. Used by "attractor" and "repulsor". Default: 0. */
+  centerX?: number;
+  /** Y position of attraction/repulsion center. Used by "attractor" and "repulsor". Default: 0. */
+  centerY?: number;
+
+  /** Force strength for attractor/repulsor. Higher = stronger pull/push. Default: 100. */
+  strength?: number;
+
+  /** Effect radius in pixels for attractor/repulsor. 0 = infinite range. Default: 0. */
+  radius?: number;
+
+  /** Turbulence intensity. Higher = more random jitter. Default: 10. */
+  turbulence?: number;
+}
+
+/**
+ * A particle emitter instance returned by {@link createEmitter}.
+ *
+ * Manages a pool of particles and spawns them according to its config.
+ * Updated each frame by {@link updateParticles}.
+ */
+export interface Emitter {
+  /** Unique identifier, auto-generated as "emitter_0", "emitter_1", etc. */
+  id: string;
+
+  /** The emitter's configuration (shape, mode, ranges, colors, etc.). */
+  config: EmitterConfig;
+
+  /** All particles (alive and dead) managed by this emitter. */
+  particles: Particle[];
+
+  /** Object pool for particle reuse to reduce GC pressure. */
+  pool: Particle[];
+
+  /** Affectors that modify this emitter's particles each frame. */
+  affectors: Affector[];
+
+  /** Internal accumulator for continuous emission rate timing. */
+  emissionAccumulator: number;
+
+  /** Whether the emitter is actively spawning particles. Set to false to pause spawning. */
+  active: boolean;
+
+  /** Whether the emitter has fired (used by "burst" and "one-shot" modes to prevent re-firing). */
+  used: boolean;
+}

package/src/pathfinding/astar.ts

@@ -76,6 +76,33 @@ function selectHeuristic(name: string): (dx: number, dy: number) => number {
 
 // --- A* ---
 
+/**
+ * Find the shortest path between two tiles on a grid using A* search
+ * with a binary min-heap for the open set.
+ *
+ * Returns immediately if start equals goal, or if either endpoint is
+ * out of bounds / unwalkable. Stops early if `maxIterations` is exceeded.
+ *
+ * @param grid - The pathfinding grid with dimensions, walkability, and optional cost function.
+ * @param start - Starting tile position (integer coordinates).
+ * @param goal - Goal tile position (integer coordinates).
+ * @param options - Optional search parameters: diagonal movement, max iterations, heuristic.
+ * @returns A {@link PathResult} with `found`, `path`, `cost`, and `explored` count.
+ *
+ * @example
+ * ```ts
+ * const grid: PathGrid = {
+ *   width: 10, height: 10,
+ *   isWalkable: (x, y) => map[y][x] !== "wall",
+ * };
+ * const result = findPath(grid, { x: 0, y: 0 }, { x: 9, y: 9 }, { diagonal: true });
+ * if (result.found) {
+ *   for (const step of result.path) {
+ *     console.log(`Move to (${step.x}, ${step.y})`);
+ *   }
+ * }
+ * ```
+ */
 export function findPath(
   grid: PathGrid,
   start: Vec2,