@arcane-engine/runtime 0.1.0

package/src/rendering/animation.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, assert } from "../../runtime/testing/harness.ts";
+import {
+  createAnimation,
+  playAnimation,
+  updateAnimation,
+  getAnimationUV,
+  drawAnimatedSprite,
+  resetAnimation,
+  stopAnimation,
+} from "./animation.ts";
+
+describe("animation", () => {
+  it("createAnimation returns incrementing IDs", () => {
+    const id1 = createAnimation(1, 32, 32, 4, 10);
+    const id2 = createAnimation(2, 16, 16, 8, 12);
+    assert.equal(id2, id1 + 1);
+  });
+
+  it("playAnimation returns initial state", () => {
+    const id = createAnimation(1, 32, 32, 4, 10);
+    const state = playAnimation(id);
+    assert.equal(state.defId, id);
+    assert.equal(state.elapsed, 0);
+    assert.equal(state.frame, 0);
+    assert.equal(state.finished, false);
+  });
+
+  it("updateAnimation advances frame correctly", () => {
+    const id = createAnimation(1, 32, 32, 4, 10);
+    const state = playAnimation(id);
+    // At 10 fps, 0.15s = frame 1
+    const next = updateAnimation(state, 0.15);
+    assert.equal(next.frame, 1);
+    assert.equal(next.finished, false);
+  });
+
+  it("updateAnimation loops back to frame 0", () => {
+    const id = createAnimation(1, 32, 32, 4, 10);
+    const state = playAnimation(id);
+    // At 10 fps, 0.45s = frame 4, loops to 0
+    const next = updateAnimation(state, 0.45);
+    assert.equal(next.frame, 4 % 4);
+    assert.equal(next.finished, false);
+  });
+
+  it("updateAnimation non-loop stops at last frame", () => {
+    const id = createAnimation(1, 32, 32, 4, 10, { loop: false });
+    const state = playAnimation(id);
+    // At 10 fps, 1.0s = frame 10, clamped to frame 3
+    const next = updateAnimation(state, 1.0);
+    assert.equal(next.frame, 3);
+  });
+
+  it("updateAnimation non-loop sets finished=true", () => {
+    const id = createAnimation(1, 32, 32, 4, 10, { loop: false });
+    const state = playAnimation(id);
+    const next = updateAnimation(state, 1.0);
+    assert.equal(next.finished, true);
+  });
+
+  it("getAnimationUV returns correct UV for frame 0", () => {
+    const id = createAnimation(1, 32, 32, 4, 10);
+    const state = playAnimation(id);
+    const uv = getAnimationUV(state);
+    assert.equal(uv.x, 0);
+    assert.equal(uv.y, 0);
+    assert.equal(uv.w, 0.25);
+    assert.equal(uv.h, 1);
+  });
+
+  it("getAnimationUV returns correct UV for frame N", () => {
+    const id = createAnimation(1, 32, 32, 4, 10);
+    let state = playAnimation(id);
+    // Advance to frame 2: 0.25s at 10fps = frame 2
+    state = updateAnimation(state, 0.25);
+    assert.equal(state.frame, 2);
+    const uv = getAnimationUV(state);
+    assert.equal(uv.x, 0.5);
+    assert.equal(uv.y, 0);
+    assert.equal(uv.w, 0.25);
+    assert.equal(uv.h, 1);
+  });
+
+  it("resetAnimation resets elapsed and frame", () => {
+    const id = createAnimation(1, 32, 32, 4, 10);
+    let state = playAnimation(id);
+    state = updateAnimation(state, 0.25);
+    assert.ok(state.elapsed > 0);
+    const reset = resetAnimation(state);
+    assert.equal(reset.elapsed, 0);
+    assert.equal(reset.frame, 0);
+    assert.equal(reset.finished, false);
+    assert.equal(reset.defId, id);
+  });
+
+  it("stopAnimation sets finished", () => {
+    const id = createAnimation(1, 32, 32, 4, 10);
+    const state = playAnimation(id);
+    const stopped = stopAnimation(state);
+    assert.equal(stopped.finished, true);
+    assert.equal(stopped.defId, id);
+  });
+
+  it("updateAnimation returns new object (immutability)", () => {
+    const id = createAnimation(1, 32, 32, 4, 10);
+    const state = playAnimation(id);
+    const next = updateAnimation(state, 0.1);
+    assert.notEqual(state, next);
+    assert.equal(state.elapsed, 0);
+    assert.equal(state.frame, 0);
+  });
+
+  it("drawAnimatedSprite doesn't throw (smoke test in headless)", () => {
+    const id = createAnimation(1, 32, 32, 4, 10);
+    const state = playAnimation(id);
+    // Should not throw even in headless (drawSprite is a no-op)
+    drawAnimatedSprite(state, 100, 200, 32, 32, { layer: 1 });
+  });
+});

package/src/rendering/animation.ts

@@ -0,0 +1,132 @@
+import type { TextureId } from "./types.ts";
+import { drawSprite } from "./sprites.ts";
+
+export type AnimationId = number;
+
+export type AnimationDef = {
+  textureId: TextureId;
+  frameW: number;
+  frameH: number;
+  frameCount: number;
+  fps: number;
+  loop: boolean;
+};
+
+export type AnimationState = {
+  defId: AnimationId;
+  elapsed: number;
+  frame: number;
+  finished: boolean;
+};
+
+const registry = new Map<number, AnimationDef>();
+let nextId = 1;
+
+export function createAnimation(
+  textureId: TextureId,
+  frameW: number,
+  frameH: number,
+  frameCount: number,
+  fps: number,
+  options?: { loop?: boolean },
+): AnimationId {
+  const id = nextId++;
+  registry.set(id, {
+    textureId,
+    frameW,
+    frameH,
+    frameCount,
+    fps,
+    loop: options?.loop ?? true,
+  });
+  return id;
+}
+
+export function playAnimation(defId: AnimationId): AnimationState {
+  return { defId, elapsed: 0, frame: 0, finished: false };
+}
+
+export function updateAnimation(
+  anim: AnimationState,
+  dt: number,
+): AnimationState {
+  const def = registry.get(anim.defId);
+  if (!def || anim.finished) return { ...anim };
+
+  const elapsed = anim.elapsed + dt;
+  const rawFrame = Math.floor(elapsed * def.fps);
+
+  if (def.loop) {
+    return {
+      defId: anim.defId,
+      elapsed,
+      frame: rawFrame % def.frameCount,
+      finished: false,
+    };
+  }
+
+  const lastFrame = def.frameCount - 1;
+  if (rawFrame >= lastFrame) {
+    return {
+      defId: anim.defId,
+      elapsed,
+      frame: lastFrame,
+      finished: true,
+    };
+  }
+
+  return {
+    defId: anim.defId,
+    elapsed,
+    frame: rawFrame,
+    finished: false,
+  };
+}
+
+export function getAnimationUV(
+  anim: AnimationState,
+): { x: number; y: number; w: number; h: number } {
+  const def = registry.get(anim.defId);
+  if (!def) return { x: 0, y: 0, w: 1, h: 1 };
+
+  return {
+    x: anim.frame / def.frameCount,
+    y: 0,
+    w: 1 / def.frameCount,
+    h: 1,
+  };
+}
+
+export function drawAnimatedSprite(
+  anim: AnimationState,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+  options?: {
+    layer?: number;
+    tint?: { r: number; g: number; b: number; a: number };
+  },
+): void {
+  const def = registry.get(anim.defId);
+  if (!def) return;
+
+  drawSprite({
+    textureId: def.textureId,
+    x,
+    y,
+    w,
+    h,
+    layer: options?.layer,
+    uv: getAnimationUV(anim),
+    tint: options?.tint,
+  });
+}
+
+export function resetAnimation(anim: AnimationState): AnimationState {
+  return { ...anim, elapsed: 0, frame: 0, finished: false };
+}
+
+export function stopAnimation(anim: AnimationState): AnimationState {
+  return { ...anim, finished: true };
+}

package/src/rendering/audio.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, assert } from "../../runtime/testing/harness.ts";
+import { loadSound, playSound, playMusic, stopSound, stopAll, setVolume } from "./audio.ts";
+
+describe("audio", () => {
+  it("loadSound returns 0 in headless mode", () => {
+    assert.equal(loadSound("test.wav"), 0);
+  });
+
+  it("playSound does not throw in headless mode", () => {
+    playSound(0);
+    playSound(1, { volume: 0.5, loop: true });
+  });
+
+  it("playMusic returns 0 in headless mode", () => {
+    const id = playMusic("music.ogg", 0.8);
+    assert.equal(id, 0);
+  });
+
+  it("stopSound does not throw in headless mode", () => {
+    stopSound(0);
+    stopSound(42);
+  });
+
+  it("stopAll does not throw in headless mode", () => {
+    stopAll();
+  });
+
+  it("setVolume does not throw in headless mode", () => {
+    setVolume(0.5);
+    setVolume(0);
+    setVolume(1);
+  });
+});

package/src/rendering/audio.ts

@@ -0,0 +1,70 @@
+/** Opaque handle to a loaded sound. */
+export type SoundId = number;
+
+export type PlayOptions = {
+  volume?: number;
+  loop?: boolean;
+};
+
+const hasRenderOps =
+  typeof (globalThis as any).Deno !== "undefined" &&
+  typeof (globalThis as any).Deno?.core?.ops?.op_load_sound === "function";
+
+/**
+ * Load a sound file (WAV, OGG, MP3). Returns a sound handle.
+ * Caches by path — loading the same path twice returns the same handle.
+ * Returns 0 in headless mode.
+ */
+export function loadSound(path: string): SoundId {
+  if (!hasRenderOps) return 0;
+  return (globalThis as any).Deno.core.ops.op_load_sound(path);
+}
+
+/**
+ * Play a loaded sound.
+ * No-op in headless mode.
+ */
+export function playSound(id: SoundId, options?: PlayOptions): void {
+  if (!hasRenderOps) return;
+  const volume = options?.volume ?? 1.0;
+  const loop_ = options?.loop ?? false;
+  (globalThis as any).Deno.core.ops.op_play_sound(id, volume, loop_);
+}
+
+/**
+ * Convenience: load and play a sound file as looping music.
+ * Returns the sound ID for later stopping.
+ * Returns 0 in headless mode.
+ */
+export function playMusic(path: string, volume: number = 1.0): SoundId {
+  const id = loadSound(path);
+  playSound(id, { volume, loop: true });
+  return id;
+}
+
+/**
+ * Stop a specific sound.
+ * No-op in headless mode.
+ */
+export function stopSound(id: SoundId): void {
+  if (!hasRenderOps) return;
+  (globalThis as any).Deno.core.ops.op_stop_sound(id);
+}
+
+/**
+ * Stop all playing sounds.
+ * No-op in headless mode.
+ */
+export function stopAll(): void {
+  if (!hasRenderOps) return;
+  (globalThis as any).Deno.core.ops.op_stop_all_sounds();
+}
+
+/**
+ * Set the master volume (0.0 = mute, 1.0 = full).
+ * No-op in headless mode.
+ */
+export function setVolume(volume: number): void {
+  if (!hasRenderOps) return;
+  (globalThis as any).Deno.core.ops.op_set_master_volume(volume);
+}

package/src/rendering/camera.ts

@@ -0,0 +1,35 @@
+import type { CameraState } from "./types.ts";
+
+const hasRenderOps =
+  typeof (globalThis as any).Deno !== "undefined" &&
+  typeof (globalThis as any).Deno?.core?.ops?.op_set_camera === "function";
+
+/**
+ * Set the camera position and zoom.
+ * No-op in headless mode.
+ */
+export function setCamera(x: number, y: number, zoom: number = 1): void {
+  if (!hasRenderOps) return;
+  (globalThis as any).Deno.core.ops.op_set_camera(x, y, zoom);
+}
+
+/**
+ * Get the current camera state.
+ * Returns default values in headless mode.
+ */
+export function getCamera(): CameraState {
+  if (!hasRenderOps) return { x: 0, y: 0, zoom: 1 };
+  const [x, y, zoom] = (globalThis as any).Deno.core.ops.op_get_camera();
+  return { x, y, zoom };
+}
+
+/**
+ * Center the camera on a target position.
+ */
+export function followTarget(
+  targetX: number,
+  targetY: number,
+  zoom: number = 1,
+): void {
+  setCamera(targetX, targetY, zoom);
+}

package/src/rendering/index.ts

@@ -0,0 +1,56 @@
+// Types
+export type {
+  TextureId,
+  SpriteOptions,
+  CameraState,
+  MousePosition,
+} from "./types.ts";
+
+// Sprites
+export { drawSprite, clearSprites } from "./sprites.ts";
+
+// Camera
+export { setCamera, getCamera, followTarget } from "./camera.ts";
+
+// Input
+export {
+  isKeyDown,
+  isKeyPressed,
+  getMousePosition,
+  getViewportSize,
+  screenToWorld,
+  getMouseWorldPosition,
+} from "./input.ts";
+
+// Textures
+export { loadTexture, createSolidTexture } from "./texture.ts";
+
+// Game loop
+export { onFrame, getDeltaTime } from "./loop.ts";
+
+// Tilemap
+export type { TilemapId, TilemapOptions } from "./types.ts";
+export { createTilemap, setTile, getTile, drawTilemap } from "./tilemap.ts";
+
+// Lighting
+export { setAmbientLight, addPointLight, clearLights } from "./lighting.ts";
+
+// Text
+export type { BitmapFont, TextOptions, TextMeasurement } from "./text.ts";
+export { loadFont, getDefaultFont, measureText, drawText } from "./text.ts";
+
+// Animation
+export type { AnimationId, AnimationDef, AnimationState } from "./animation.ts";
+export {
+  createAnimation,
+  playAnimation,
+  updateAnimation,
+  getAnimationUV,
+  drawAnimatedSprite,
+  resetAnimation,
+  stopAnimation,
+} from "./animation.ts";
+
+// Audio
+export type { SoundId, PlayOptions } from "./audio.ts";
+export { loadSound, playSound, playMusic, stopSound, stopAll, setVolume } from "./audio.ts";

package/src/rendering/input.test.ts

@@ -0,0 +1,70 @@
+import { describe, it } from "../testing/harness.ts";
+import { screenToWorld } from "./input.ts";
+
+describe("input", () => {
+  describe("screenToWorld", () => {
+    it("converts screen center to camera position (headless defaults)", () => {
+      // In headless mode: camera at (0, 0), zoom 1.0, viewport 800x600
+      // Screen center (400, 300) should map to camera position (0, 0)
+      const world = screenToWorld(400, 300);
+
+      // Allow small floating point error
+      const epsilon = 0.01;
+      if (Math.abs(world.x - 0) > epsilon || Math.abs(world.y - 0) > epsilon) {
+        throw new Error(`Expected ~(0, 0), got (${world.x}, ${world.y})`);
+      }
+    });
+
+    it("converts screen corners correctly (headless defaults)", () => {
+      // In headless mode: camera at (0, 0), zoom 1.0, viewport 800x600
+      // Top-left (0, 0) should map to (-400, -300)
+      // Bottom-right (800, 600) should map to (400, 300)
+      const topLeft = screenToWorld(0, 0);
+      const bottomRight = screenToWorld(800, 600);
+
+      const epsilon = 0.01;
+      if (Math.abs(topLeft.x - (-400)) > epsilon || Math.abs(topLeft.y - (-300)) > epsilon) {
+        throw new Error(`Top-left: expected ~(-400, -300), got (${topLeft.x}, ${topLeft.y})`);
+      }
+      if (Math.abs(bottomRight.x - 400) > epsilon || Math.abs(bottomRight.y - 300) > epsilon) {
+        throw new Error(`Bottom-right: expected ~(400, 300), got (${bottomRight.x}, ${bottomRight.y})`);
+      }
+    });
+
+    it("converts arbitrary screen position correctly", () => {
+      // In headless mode: camera at (0, 0), zoom 1.0, viewport 800x600
+      // Screen position (600, 450) should map to:
+      // normX = 600/800 = 0.75, normY = 450/600 = 0.75
+      // halfW = 400, halfH = 300
+      // worldX = -400 + 0.75 * 800 = -400 + 600 = 200
+      // worldY = -300 + 0.75 * 600 = -300 + 450 = 150
+      const world = screenToWorld(600, 450);
+
+      const epsilon = 0.01;
+      if (Math.abs(world.x - 200) > epsilon || Math.abs(world.y - 150) > epsilon) {
+        throw new Error(`Expected ~(200, 150), got (${world.x}, ${world.y})`);
+      }
+    });
+
+    it("handles edge cases", () => {
+      // Test negative coordinates (should still work mathematically)
+      const negativeScreen = screenToWorld(-100, -50);
+      // normX = -100/800 = -0.125, normY = -50/600 = -0.0833
+      // worldX = -400 + (-0.125) * 800 = -400 - 100 = -500
+      // worldY = -300 + (-0.0833) * 600 = -300 - 50 = -350
+      const epsilon = 0.01;
+      if (Math.abs(negativeScreen.x - (-500)) > epsilon || Math.abs(negativeScreen.y - (-350)) > epsilon) {
+        throw new Error(`Negative coords: expected ~(-500, -350), got (${negativeScreen.x}, ${negativeScreen.y})`);
+      }
+
+      // Test large coordinates (beyond viewport)
+      const largeScreen = screenToWorld(1600, 1200);
+      // normX = 1600/800 = 2, normY = 1200/600 = 2
+      // worldX = -400 + 2 * 800 = -400 + 1600 = 1200
+      // worldY = -300 + 2 * 600 = -300 + 1200 = 900
+      if (Math.abs(largeScreen.x - 1200) > epsilon || Math.abs(largeScreen.y - 900) > epsilon) {
+        throw new Error(`Large coords: expected ~(1200, 900), got (${largeScreen.x}, ${largeScreen.y})`);
+      }
+    });
+  });
+});

package/src/rendering/input.ts

@@ -0,0 +1,82 @@
+import type { MousePosition } from "./types.ts";
+import { getCamera } from "./camera.ts";
+
+const hasRenderOps =
+  typeof (globalThis as any).Deno !== "undefined" &&
+  typeof (globalThis as any).Deno?.core?.ops?.op_is_key_down === "function";
+
+const hasViewportOp =
+  typeof (globalThis as any).Deno !== "undefined" &&
+  typeof (globalThis as any).Deno?.core?.ops?.op_get_viewport_size === "function";
+
+/**
+ * Check if a key is currently held down.
+ * Key names match web standards: "ArrowUp", "ArrowDown", "a", "Space", etc.
+ * Returns false in headless mode.
+ */
+export function isKeyDown(key: string): boolean {
+  if (!hasRenderOps) return false;
+  return (globalThis as any).Deno.core.ops.op_is_key_down(key);
+}
+
+/**
+ * Check if a key was pressed this frame (just went down).
+ * Returns false in headless mode.
+ */
+export function isKeyPressed(key: string): boolean {
+  if (!hasRenderOps) return false;
+  return (globalThis as any).Deno.core.ops.op_is_key_pressed(key);
+}
+
+/**
+ * Get the current mouse position in window/screen coordinates.
+ * Returns (0, 0) in headless mode.
+ */
+export function getMousePosition(): MousePosition {
+  if (!hasRenderOps) return { x: 0, y: 0 };
+  const [x, y] = (globalThis as any).Deno.core.ops.op_get_mouse_position();
+  return { x, y };
+}
+
+/**
+ * Get the current viewport size in pixels.
+ * Returns [800, 600] in headless mode.
+ */
+export function getViewportSize(): { width: number; height: number } {
+  if (!hasViewportOp) return { width: 800, height: 600 };
+  const [w, h] = (globalThis as any).Deno.core.ops.op_get_viewport_size();
+  return { width: w, height: h };
+}
+
+/**
+ * Convert screen/window coordinates to world coordinates using the current camera.
+ * Screen coordinates: (0, 0) = top-left, (viewport_width, viewport_height) = bottom-right
+ * World coordinates: transformed by camera position and zoom
+ */
+export function screenToWorld(screenX: number, screenY: number): MousePosition {
+  const viewport = getViewportSize();
+  const camera = getCamera();
+
+  // Calculate the world space bounds visible on screen
+  const halfW = viewport.width / (2.0 * camera.zoom);
+  const halfH = viewport.height / (2.0 * camera.zoom);
+
+  // Normalize screen position to 0..1
+  const normX = screenX / viewport.width;
+  const normY = screenY / viewport.height;
+
+  // Map to world space
+  const worldX = (camera.x - halfW) + normX * (2 * halfW);
+  const worldY = (camera.y - halfH) + normY * (2 * halfH);
+
+  return { x: worldX, y: worldY };
+}
+
+/**
+ * Get the mouse position in world coordinates (accounting for camera transform).
+ * This is a convenience function that combines getMousePosition() and screenToWorld().
+ */
+export function getMouseWorldPosition(): MousePosition {
+  const screenPos = getMousePosition();
+  return screenToWorld(screenPos.x, screenPos.y);
+}

package/src/rendering/lighting.ts

@@ -0,0 +1,38 @@
+const hasRenderOps =
+  typeof (globalThis as any).Deno !== "undefined" &&
+  typeof (globalThis as any).Deno?.core?.ops?.op_set_ambient_light ===
+    "function";
+
+/** Set the ambient light color (0-1 per channel). Default is (1,1,1) = full white. */
+export function setAmbientLight(r: number, g: number, b: number): void {
+  if (!hasRenderOps) return;
+  (globalThis as any).Deno.core.ops.op_set_ambient_light(r, g, b);
+}
+
+/** Add a point light at world position (x,y) with the given radius, color, and intensity. */
+export function addPointLight(
+  x: number,
+  y: number,
+  radius: number,
+  r: number = 1,
+  g: number = 1,
+  b: number = 1,
+  intensity: number = 1,
+): void {
+  if (!hasRenderOps) return;
+  (globalThis as any).Deno.core.ops.op_add_point_light(
+    x,
+    y,
+    radius,
+    r,
+    g,
+    b,
+    intensity,
+  );
+}
+
+/** Clear all point lights for this frame. Called automatically at frame start. */
+export function clearLights(): void {
+  if (!hasRenderOps) return;
+  (globalThis as any).Deno.core.ops.op_clear_lights();
+}

package/src/rendering/loop.ts

@@ -0,0 +1,21 @@
+const hasRenderOps =
+  typeof (globalThis as any).Deno !== "undefined" &&
+  typeof (globalThis as any).Deno?.core?.ops?.op_get_delta_time === "function";
+
+/**
+ * Register a callback to be called each frame.
+ * Only one callback can be active at a time (last one wins).
+ * No-op in headless mode.
+ */
+export function onFrame(callback: () => void): void {
+  (globalThis as any).__frameCallback = callback;
+}
+
+/**
+ * Get the time elapsed since the last frame, in seconds.
+ * Returns 0 in headless mode.
+ */
+export function getDeltaTime(): number {
+  if (!hasRenderOps) return 0;
+  return (globalThis as any).Deno.core.ops.op_get_delta_time();
+}