@arcane-engine/runtime 0.1.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcane-engine/runtime",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Agent-native 2D game engine runtime - TypeScript APIs for state management, rendering, and game logic",
   "type": "module",
   "main": "./index.ts",
@@ -14,7 +14,9 @@
     "./pathfinding": "./src/pathfinding/index.ts",
     "./systems": "./src/systems/index.ts",
     "./agent": "./src/agent/index.ts",
-    "./testing": "./src/testing/harness.ts"
+    "./testing": "./src/testing/harness.ts",
+    "./tweening": "./src/tweening/index.ts",
+    "./particles": "./src/particles/index.ts"
   },
   "files": [
     "src",

package/src/agent/protocol.ts

@@ -17,7 +17,41 @@ function deepClone<T>(value: T): T {
   return JSON.parse(JSON.stringify(value));
 }
 
-/** Register an agent protocol, installing it on globalThis.__arcaneAgent */
+/**
+ * Register this game with Arcane's agent protocol.
+ *
+ * Must be called once at startup. Installs a protocol object on
+ * `globalThis.__arcaneAgent` that enables:
+ * - `arcane describe <entry.ts>` — text description of game state.
+ * - `arcane inspect <entry.ts> <path>` — query specific state values.
+ * - `arcane dev <entry.ts> --inspector <port>` — HTTP inspector for live interaction.
+ *
+ * The protocol supports executing/simulating actions, rewinding to initial state,
+ * and capturing snapshots.
+ *
+ * @typeParam S - The game state type.
+ * @param config - Agent configuration with name, state accessors, optional actions, and describe function.
+ *   Provide either a `store` (GameStore) or `getState`/`setState` functions.
+ * @returns The created {@link AgentProtocol} instance (also installed on globalThis).
+ *
+ * @example
+ * ```ts
+ * let state = { score: 0, player: { x: 0, y: 0, hp: 100 } };
+ *
+ * registerAgent({
+ *   name: "my-game",
+ *   getState: () => state,
+ *   setState: (s) => { state = s; },
+ *   describe: (s, opts) => `Score: ${s.score}, HP: ${s.player.hp}`,
+ *   actions: {
+ *     heal: {
+ *       handler: (s) => ({ ...s, player: { ...s.player, hp: 100 } }),
+ *       description: "Restore player to full health",
+ *     },
+ *   },
+ * });
+ * ```
+ */
 export function registerAgent<S>(config: AgentConfig<S>): AgentProtocol<S> {
   const getState = "store" in config
     ? () => config.store.getState() as S

package/src/agent/types.ts

@@ -1,73 +1,158 @@
 import type { GameStore } from "../state/store.ts";
 
-/** Verbosity levels for describe() output */
+/**
+ * Verbosity levels for the describe() output.
+ * - `"minimal"` — one-line summary (e.g., for logs).
+ * - `"normal"` — standard detail (default).
+ * - `"detailed"` — full state dump for debugging.
+ */
 export type Verbosity = "minimal" | "normal" | "detailed";
 
-/** Options passed to describe() */
+/**
+ * Options passed to the agent's describe function.
+ */
 export type DescribeOptions = Readonly<{
+  /** Detail level for the description. Default: "normal". */
   verbosity?: Verbosity;
+  /** Optional dot-path to focus description on a sub-tree of state (e.g., "player.inventory"). */
   path?: string;
 }>;
 
-/** Information about a registered action */
+/**
+ * Metadata about a registered agent action, returned by `listActions()`.
+ * Used by AI agents and the HTTP inspector to discover available commands.
+ */
 export type ActionInfo = Readonly<{
+  /** Action name used to invoke via executeAction(). */
   name: string;
+  /** Human-readable description of what the action does. */
   description: string;
+  /** Optional argument schema for the action. */
   args?: readonly ArgInfo[];
 }>;
 
-/** Describes a single argument to an action */
+/**
+ * Describes a single argument accepted by an agent action.
+ */
 export type ArgInfo = Readonly<{
+  /** Argument name (used as key in the args JSON object). */
   name: string;
+  /** Type hint (e.g., "string", "number", "EntityId"). */
   type: string;
+  /** Optional description of the argument's purpose and valid values. */
   description?: string;
 }>;
 
-/** Result of executing an action */
+/**
+ * Result of executing an action via the agent protocol.
+ * @typeParam S - The game state type.
+ */
 export type ActionResult<S> = Readonly<{
+  /** True if the action executed successfully. */
   ok: boolean;
+  /** The game state after execution (unchanged if ok is false). */
   state: S;
+  /** Error message if ok is false. */
   error?: string;
 }>;
 
-/** Result of simulating an action (state not committed) */
+/**
+ * Result of simulating an action without committing the state change.
+ * The original game state is not modified.
+ * @typeParam S - The game state type.
+ */
 export type SimulateResult<S> = Readonly<{
+  /** True if the simulation executed successfully. */
   ok: boolean;
+  /** The hypothetical state after the action (original state is untouched). */
   state: S;
+  /** Error message if ok is false. */
   error?: string;
 }>;
 
-/** A captured state snapshot for rewind */
+/**
+ * A captured snapshot of game state at a point in time, used for rewind.
+ * @typeParam S - The game state type.
+ */
 export type SnapshotData<S> = Readonly<{
+  /** Deep clone of the game state at capture time. */
   state: S;
+  /** Unix timestamp (ms) when the snapshot was captured. */
   timestamp: number;
 }>;
 
-/** An action handler: takes current state and parsed args, returns new state */
+/**
+ * A pure function that handles an agent action.
+ * Takes current state and parsed arguments, returns new state.
+ * Must not mutate the input state.
+ *
+ * @typeParam S - The game state type.
+ * @param state - Current game state.
+ * @param args - Parsed arguments from the action invocation.
+ * @returns New game state.
+ */
 export type ActionHandler<S> = (state: S, args: Record<string, unknown>) => S;
 
-/** Custom describe function */
+/**
+ * Custom function for generating a text description of the game state.
+ * Used by `arcane describe` and the HTTP inspector.
+ *
+ * @typeParam S - The game state type.
+ * @param state - Current game state.
+ * @param options - Verbosity and optional path focus.
+ * @returns Human-readable text description.
+ */
 export type DescribeFn<S> = (state: S, options: DescribeOptions) => string;
 
-/** Agent configuration — either store-backed or get/setState-backed */
+/**
+ * Configuration for registering an agent via {@link registerAgent}.
+ *
+ * Supports two state access patterns:
+ * - **Store-backed**: provide a `store` (GameStore) — state access is automatic.
+ * - **Manual**: provide `getState()` and `setState()` functions.
+ *
+ * @typeParam S - The game state type.
+ */
 export type AgentConfig<S> = {
+  /** Display name for the game/agent (shown in CLI and inspector). */
   name: string;
+  /**
+   * Optional map of named actions the agent can execute.
+   * Each action has a handler, description, and optional argument schema.
+   */
   actions?: Record<string, { handler: ActionHandler<S>; description: string; args?: ArgInfo[] }>;
+  /** Optional custom describe function. Falls back to defaultDescribe() if not provided. */
   describe?: DescribeFn<S>;
 } & (
-  | { store: GameStore<S> }
-  | { getState: () => S; setState: (s: S) => void }
+  | { /** GameStore instance for automatic state access. */ store: GameStore<S> }
+  | { /** Function to get current state. */ getState: () => S; /** Function to replace current state. */ setState: (s: S) => void }
 );
 
-/** The protocol object installed on globalThis */
+/**
+ * The agent protocol object installed on `globalThis.__arcaneAgent`.
+ *
+ * Provides the interface that Rust CLI commands (`describe`, `inspect`, `dev --inspector`)
+ * use to interact with the game. Created by {@link registerAgent}.
+ *
+ * @typeParam S - The game state type.
+ */
 export type AgentProtocol<S> = Readonly<{
+  /** Game/agent display name. */
   name: string;
+  /** Get a deep reference to the current game state. */
   getState: () => S;
+  /** Query a value at a dot-separated path in the state tree. */
   inspect: (path: string) => unknown;
+  /** Generate a text description of the current state. */
   describe: (options?: DescribeOptions) => string;
+  /** List all registered actions with their metadata. */
   listActions: () => readonly ActionInfo[];
+  /** Execute a named action with optional JSON arguments. Commits state changes. */
   executeAction: (name: string, argsJson?: string) => ActionResult<S>;
+  /** Simulate a named action without committing. Returns hypothetical state. */
   simulate: (name: string, argsJson?: string) => SimulateResult<S>;
+  /** Reset state to the initial snapshot captured at registerAgent() time. */
   rewind: () => S;
+  /** Capture a deep clone of the current state as a snapshot. */
   captureSnapshot: () => SnapshotData<S>;
 }>;

package/src/particles/emitter.test.ts

@@ -0,0 +1,323 @@
+/**
+ * Tests for particle system
+ */
+
+import { describe, it, assert } from "../testing/harness.ts";
+import {
+  createEmitter,
+  removeEmitter,
+  updateParticles,
+  getAllParticles,
+  addAffector,
+  clearEmitters,
+  getEmitterCount,
+} from "./emitter.ts";
+import type { EmitterConfig } from "./types.ts";
+
+describe("Particle System", () => {
+  it("should create an emitter", () => {
+    clearEmitters();
+
+    const config: EmitterConfig = {
+      shape: "point",
+      x: 100,
+      y: 100,
+      mode: "burst",
+      burstCount: 10,
+      lifetime: [1, 2],
+      velocityX: [-50, 50],
+      velocityY: [-50, 50],
+      startColor: { r: 1, g: 0, b: 0, a: 1 },
+      endColor: { r: 1, g: 1, b: 0, a: 0 },
+      textureId: 1,
+    };
+
+    const emitter = createEmitter(config);
+    assert.ok(emitter.id);
+    assert.equal(getEmitterCount(), 1);
+  });
+
+  it("should emit particles in burst mode", () => {
+    clearEmitters();
+
+    const config: EmitterConfig = {
+      shape: "point",
+      x: 100,
+      y: 100,
+      mode: "burst",
+      burstCount: 10,
+      lifetime: [1, 1],
+      velocityX: [0, 0],
+      velocityY: [0, 0],
+      startColor: { r: 1, g: 0, b: 0, a: 1 },
+      endColor: { r: 1, g: 1, b: 0, a: 0 },
+      textureId: 1,
+    };
+
+    createEmitter(config);
+    updateParticles(0.1);
+
+    const particles = getAllParticles();
+    assert.equal(particles.length, 10);
+  });
+
+  it("should emit particles continuously", () => {
+    clearEmitters();
+
+    const config: EmitterConfig = {
+      shape: "point",
+      x: 100,
+      y: 100,
+      mode: "continuous",
+      rate: 10, // 10 particles per second
+      lifetime: [10, 10], // Long lifetime so they don't die during test
+      velocityX: [0, 0],
+      velocityY: [0, 0],
+      startColor: { r: 1, g: 0, b: 0, a: 1 },
+      endColor: { r: 1, g: 1, b: 0, a: 0 },
+      textureId: 1,
+    };
+
+    createEmitter(config);
+
+    // After 1 second, should have ~10 particles
+    updateParticles(1.0);
+    const particles = getAllParticles();
+    assert.ok(particles.length >= 9 && particles.length <= 11, `Expected ~10 particles, got ${particles.length}`);
+  });
+
+  it("should update particle positions", () => {
+    clearEmitters();
+
+    const config: EmitterConfig = {
+      shape: "point",
+      x: 0,
+      y: 0,
+      mode: "one-shot",
+      lifetime: [10, 10], // Long lifetime
+      velocityX: [100, 100], // Constant velocity
+      velocityY: [0, 0],
+      startColor: { r: 1, g: 0, b: 0, a: 1 },
+      endColor: { r: 1, g: 1, b: 0, a: 0 },
+      textureId: 1,
+    };
+
+    createEmitter(config);
+    updateParticles(0); // Spawn particle
+
+    const particles1 = getAllParticles();
+    assert.equal(particles1.length, 1);
+    const initialX = particles1[0].x;
+
+    // Update for 1 second
+    updateParticles(1.0);
+
+    const particles2 = getAllParticles();
+    assert.equal(particles2.length, 1);
+
+    // Should have moved 100 pixels to the right
+    const expectedX = initialX + 100;
+    assert.ok(Math.abs(particles2[0].x - expectedX) < 1, `Expected x ~${expectedX}, got ${particles2[0].x}`);
+  });
+
+  it("should kill particles after lifetime", () => {
+    clearEmitters();
+
+    const config: EmitterConfig = {
+      shape: "point",
+      x: 0,
+      y: 0,
+      mode: "burst",
+      burstCount: 5,
+      lifetime: [0.5, 0.5],
+      velocityX: [0, 0],
+      velocityY: [0, 0],
+      startColor: { r: 1, g: 0, b: 0, a: 1 },
+      endColor: { r: 1, g: 1, b: 0, a: 0 },
+      textureId: 1,
+    };
+
+    createEmitter(config);
+    updateParticles(0);
+
+    assert.equal(getAllParticles().length, 5);
+
+    // After 0.6 seconds, all should be dead
+    updateParticles(0.6);
+    assert.equal(getAllParticles().length, 0);
+  });
+
+  it("should interpolate colors over lifetime", () => {
+    clearEmitters();
+
+    const config: EmitterConfig = {
+      shape: "point",
+      x: 0,
+      y: 0,
+      mode: "one-shot",
+      lifetime: [1, 1],
+      velocityX: [0, 0],
+      velocityY: [0, 0],
+      startColor: { r: 1, g: 0, b: 0, a: 1 },
+      endColor: { r: 0, g: 1, b: 0, a: 0 },
+      textureId: 1,
+    };
+
+    createEmitter(config);
+    updateParticles(0);
+
+    const particles = getAllParticles();
+    assert.equal(particles.length, 1);
+
+    // At start, color should be red
+    assert.ok(Math.abs(particles[0].color.r - 1) < 0.1);
+    assert.ok(Math.abs(particles[0].color.g - 0) < 0.1);
+
+    // After 0.5 seconds, color should be halfway
+    updateParticles(0.5);
+    assert.ok(Math.abs(particles[0].color.r - 0.5) < 0.1);
+    assert.ok(Math.abs(particles[0].color.g - 0.5) < 0.1);
+  });
+
+  it("should apply gravity affector", () => {
+    clearEmitters();
+
+    const config: EmitterConfig = {
+      shape: "point",
+      x: 0,
+      y: 0,
+      mode: "one-shot",
+      lifetime: [10, 10],
+      velocityX: [0, 0],
+      velocityY: [0, 0],
+      startColor: { r: 1, g: 0, b: 0, a: 1 },
+      endColor: { r: 1, g: 1, b: 0, a: 0 },
+      textureId: 1,
+    };
+
+    const emitter = createEmitter(config);
+    addAffector(emitter, {
+      type: "gravity",
+      forceX: 0,
+      forceY: 100, // Downward gravity
+    });
+
+    updateParticles(0);
+
+    const particles = getAllParticles();
+    const initialY = particles[0].y;
+
+    // After 1 second with gravity, should have fallen
+    updateParticles(1.0);
+    assert.ok(particles[0].y > initialY, "Particle should have fallen");
+  });
+
+  it("should remove emitters", () => {
+    clearEmitters();
+
+    const config: EmitterConfig = {
+      shape: "point",
+      x: 0,
+      y: 0,
+      mode: "burst",
+      burstCount: 5,
+      lifetime: [1, 1],
+      velocityX: [0, 0],
+      velocityY: [0, 0],
+      startColor: { r: 1, g: 0, b: 0, a: 1 },
+      endColor: { r: 1, g: 1, b: 0, a: 0 },
+      textureId: 1,
+    };
+
+    const emitter = createEmitter(config);
+    assert.equal(getEmitterCount(), 1);
+
+    removeEmitter(emitter);
+    assert.equal(getEmitterCount(), 0);
+  });
+
+  it("should respect maxParticles limit", () => {
+    clearEmitters();
+
+    const config: EmitterConfig = {
+      shape: "point",
+      x: 0,
+      y: 0,
+      mode: "continuous",
+      rate: 100,
+      lifetime: [10, 10], // Long lifetime so they don't die
+      velocityX: [0, 0],
+      velocityY: [0, 0],
+      startColor: { r: 1, g: 0, b: 0, a: 1 },
+      endColor: { r: 1, g: 1, b: 0, a: 0 },
+      textureId: 1,
+      maxParticles: 10,
+    };
+
+    createEmitter(config);
+    updateParticles(1.0); // Try to spawn 100 particles
+
+    const particles = getAllParticles();
+    assert.ok(particles.length <= 10, `Should not exceed maxParticles, got ${particles.length}`);
+  });
+
+  it("should spawn particles in area shape", () => {
+    clearEmitters();
+
+    const config: EmitterConfig = {
+      shape: "area",
+      x: 100,
+      y: 100,
+      shapeParams: { width: 50, height: 50 },
+      mode: "burst",
+      burstCount: 10,
+      lifetime: [1, 1],
+      velocityX: [0, 0],
+      velocityY: [0, 0],
+      startColor: { r: 1, g: 0, b: 0, a: 1 },
+      endColor: { r: 1, g: 1, b: 0, a: 0 },
+      textureId: 1,
+    };
+
+    createEmitter(config);
+    updateParticles(0);
+
+    const particles = getAllParticles();
+
+    // All particles should be within the area
+    for (const p of particles) {
+      assert.ok(p.x >= 100 && p.x <= 150);
+      assert.ok(p.y >= 100 && p.y <= 150);
+    }
+  });
+
+  it("should spawn particles in ring shape", () => {
+    clearEmitters();
+
+    const config: EmitterConfig = {
+      shape: "ring",
+      x: 0,
+      y: 0,
+      shapeParams: { innerRadius: 10, outerRadius: 20 },
+      mode: "burst",
+      burstCount: 10,
+      lifetime: [1, 1],
+      velocityX: [0, 0],
+      velocityY: [0, 0],
+      startColor: { r: 1, g: 0, b: 0, a: 1 },
+      endColor: { r: 1, g: 1, b: 0, a: 0 },
+      textureId: 1,
+    };
+
+    createEmitter(config);
+    updateParticles(0);
+
+    const particles = getAllParticles();
+
+    // All particles should be within the ring
+    for (const p of particles) {
+      const dist = Math.sqrt(p.x * p.x + p.y * p.y);
+      assert.ok(dist >= 10 && dist <= 20, `Particle at distance ${dist} should be in ring [10, 20]`);
+    }
+  });
+});