@arcane-engine/runtime 0.1.0

package/src/rendering/sprites.ts

@@ -0,0 +1,60 @@
+import type { SpriteOptions } from "./types.ts";
+
+// Detect if we're running inside the Arcane renderer (V8 with render ops).
+const hasRenderOps =
+  typeof (globalThis as any).Deno !== "undefined" &&
+  typeof (globalThis as any).Deno?.core?.ops?.op_draw_sprite === "function";
+
+/**
+ * Queue a sprite to be drawn this frame.
+ * No-op in headless mode (Node or V8 test runner).
+ */
+export function drawSprite(opts: SpriteOptions): void {
+  if (!hasRenderOps) return;
+
+  const uv = opts.uv ?? { x: 0, y: 0, w: 1, h: 1 };
+  const tint = opts.tint ?? { r: 1, g: 1, b: 1, a: 1 };
+
+  // Extract ALL properties to temp variables to work around V8 object literal property access bug
+  // Bug: accessing multiple properties from same object in function args causes all to evaluate to parent
+  const texId = opts.textureId;
+  const x = opts.x;
+  const y = opts.y;
+  const w = opts.w;
+  const h = opts.h;
+  const layer = opts.layer ?? 0;
+  const uvX = uv.x;
+  const uvY = uv.y;
+  const uvW = uv.w;
+  const uvH = uv.h;
+  const tintR = tint.r;
+  const tintG = tint.g;
+  const tintB = tint.b;
+  const tintA = tint.a;
+
+  (globalThis as any).Deno.core.ops.op_draw_sprite(
+    texId,
+    x,
+    y,
+    w,
+    h,
+    layer,
+    uvX,
+    uvY,
+    uvW,
+    uvH,
+    tintR,
+    tintG,
+    tintB,
+    tintA,
+  );
+}
+
+/**
+ * Clear all queued sprites for this frame.
+ * No-op in headless mode.
+ */
+export function clearSprites(): void {
+  if (!hasRenderOps) return;
+  (globalThis as any).Deno.core.ops.op_clear_sprites();
+}

package/src/rendering/text.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, assert } from "../../runtime/testing/harness.ts";
+import {
+  loadFont,
+  getDefaultFont,
+  measureText,
+  drawText,
+} from "./text.ts";
+import type { BitmapFont } from "./text.ts";
+
+describe("text", () => {
+  it("loadFont creates BitmapFont with correct fields", () => {
+    const font = loadFont(42, 16, 16, 8, 12, 0);
+    assert.equal(font.textureId, 42);
+    assert.equal(font.glyphW, 16);
+    assert.equal(font.glyphH, 16);
+    assert.equal(font.columns, 8);
+    assert.equal(font.rows, 12);
+    assert.equal(font.firstChar, 0);
+  });
+
+  it("loadFont uses default firstChar=32", () => {
+    const font = loadFont(1, 8, 8, 16, 6);
+    assert.equal(font.firstChar, 32);
+  });
+
+  it("getDefaultFont returns a font with expected dimensions", () => {
+    const font = getDefaultFont();
+    assert.equal(font.glyphW, 8);
+    assert.equal(font.glyphH, 8);
+    assert.equal(font.columns, 16);
+    assert.equal(font.rows, 6);
+    assert.equal(font.firstChar, 32);
+  });
+
+  it("getDefaultFont returns same instance on second call", () => {
+    const a = getDefaultFont();
+    const b = getDefaultFont();
+    assert.ok(a === b, "expected same object reference");
+  });
+
+  it("measureText returns correct width for known string", () => {
+    const m = measureText("Hello");
+    // Default font: 8px wide glyphs, scale 1 → 5 * 8 = 40
+    assert.equal(m.width, 40);
+    assert.equal(m.height, 8);
+  });
+
+  it("measureText with scale multiplier", () => {
+    const m = measureText("AB", { scale: 3 });
+    // 2 chars * 8 * 3 = 48 wide, 8 * 3 = 24 high
+    assert.equal(m.width, 48);
+    assert.equal(m.height, 24);
+  });
+
+  it("measureText with custom font dimensions", () => {
+    const font = loadFont(0, 12, 16, 16, 6);
+    const m = measureText("Hi!", { font });
+    // 3 chars * 12 * 1 = 36 wide, 16 high
+    assert.equal(m.width, 36);
+    assert.equal(m.height, 16);
+  });
+
+  it("drawText doesn't throw in headless mode", () => {
+    // In headless (Node/V8 test runner), drawText is a no-op
+    drawText("Hello, world!", 10, 20);
+    drawText("Test", 0, 0, { scale: 2, layer: 50 });
+    assert.ok(true, "drawText completed without error");
+  });
+
+  it("UV calculation: char A (code 65) gives correct col and row", () => {
+    // 'A' = charCode 65, minus firstChar 32 = 33
+    // col = 33 % 16 = 1, row = floor(33 / 16) = 2
+    const font = getDefaultFont();
+    const charCode = "A".charCodeAt(0) - font.firstChar; // 33
+    const col = charCode % font.columns;
+    const row = Math.floor(charCode / font.columns);
+    assert.equal(charCode, 33);
+    assert.equal(col, 1);
+    assert.equal(row, 2);
+  });
+
+  it("UV calculation: space (code 32) gives col=0 row=0", () => {
+    const font = getDefaultFont();
+    const charCode = " ".charCodeAt(0) - font.firstChar; // 0
+    const col = charCode % font.columns;
+    const row = Math.floor(charCode / font.columns);
+    assert.equal(charCode, 0);
+    assert.equal(col, 0);
+    assert.equal(row, 0);
+  });
+});

package/src/rendering/text.ts

@@ -0,0 +1,184 @@
+import type { TextureId } from "./types.ts";
+import { drawSprite } from "./sprites.ts";
+import { getCamera } from "./camera.ts";
+
+// --- Types ---
+
+export type BitmapFont = {
+  textureId: TextureId;
+  glyphW: number;
+  glyphH: number;
+  columns: number;
+  rows: number;
+  firstChar: number;
+};
+
+export type TextOptions = {
+  font?: BitmapFont;
+  scale?: number;
+  tint?: { r: number; g: number; b: number; a: number };
+  layer?: number;
+  screenSpace?: boolean;
+};
+
+export type TextMeasurement = {
+  width: number;
+  height: number;
+};
+
+// --- Render ops detection ---
+
+const hasRenderOps =
+  typeof (globalThis as any).Deno !== "undefined" &&
+  typeof (globalThis as any).Deno?.core?.ops?.op_draw_sprite === "function";
+
+const hasFontOp =
+  typeof (globalThis as any).Deno?.core?.ops?.op_create_font_texture ===
+  "function";
+
+const hasViewportOp =
+  typeof (globalThis as any).Deno?.core?.ops?.op_get_viewport_size ===
+  "function";
+
+function getViewportSize(): [number, number] {
+  if (!hasViewportOp) return [800, 600];
+  const [w, h] = (globalThis as any).Deno.core.ops.op_get_viewport_size();
+  return [w, h];
+}
+
+// --- Module state ---
+
+let defaultFont: BitmapFont | null = null;
+
+// --- Functions ---
+
+/**
+ * Create a bitmap font descriptor from a texture atlas.
+ */
+export function loadFont(
+  textureId: TextureId,
+  glyphW: number,
+  glyphH: number,
+  columns: number,
+  rows: number,
+  firstChar: number = 32,
+): BitmapFont {
+  return { textureId, glyphW, glyphH, columns, rows, firstChar };
+}
+
+/**
+ * Get the default 8x8 bitmap font, lazily initialized.
+ * In headless mode returns a dummy font (textureId 0).
+ */
+export function getDefaultFont(): BitmapFont {
+  if (defaultFont !== null) return defaultFont;
+
+  if (hasFontOp) {
+    const textureId: TextureId = (
+      globalThis as any
+    ).Deno.core.ops.op_create_font_texture();
+    defaultFont = {
+      textureId,
+      glyphW: 8,
+      glyphH: 8,
+      columns: 16,
+      rows: 6,
+      firstChar: 32,
+    };
+  } else {
+    defaultFont = {
+      textureId: 0,
+      glyphW: 8,
+      glyphH: 8,
+      columns: 16,
+      rows: 6,
+      firstChar: 32,
+    };
+  }
+
+  return defaultFont;
+}
+
+/**
+ * Measure the pixel dimensions of a text string.
+ * Pure math — works in headless mode.
+ */
+export function measureText(
+  text: string,
+  options?: TextOptions,
+): TextMeasurement {
+  const font = options?.font ?? getDefaultFont();
+  const scale = options?.scale ?? 1;
+  return {
+    width: text.length * font.glyphW * scale,
+    height: font.glyphH * scale,
+  };
+}
+
+/**
+ * Draw a text string using the sprite pipeline.
+ * Each character becomes one drawSprite() call.
+ * No-op in headless mode.
+ */
+export function drawText(
+  text: string,
+  x: number,
+  y: number,
+  options?: TextOptions,
+): void {
+  if (!hasRenderOps) return;
+
+  const font = options?.font ?? getDefaultFont();
+  const scale = options?.scale ?? 1;
+  const layer = options?.layer ?? 100;
+  const tint = options?.tint;
+  const screenSpace = options?.screenSpace ?? false;
+
+  const maxChar = font.columns * font.rows;
+
+  for (let i = 0; i < text.length; i++) {
+    const charCode = text.charCodeAt(i) - font.firstChar;
+    if (charCode < 0 || charCode >= maxChar) continue;
+
+    const col = charCode % font.columns;
+    const row = Math.floor(charCode / font.columns);
+    const uv = {
+      x: col / font.columns,
+      y: row / font.rows,
+      w: 1 / font.columns,
+      h: 1 / font.rows,
+    };
+
+    const drawX = x + i * font.glyphW * scale;
+
+    let worldX: number;
+    let worldY: number;
+    let spriteW: number;
+    let spriteH: number;
+
+    if (screenSpace) {
+      const cam = getCamera();
+      const [viewportW, viewportH] = getViewportSize();
+      worldX = drawX / cam.zoom + cam.x - viewportW / (2 * cam.zoom);
+      worldY = y / cam.zoom + cam.y - viewportH / (2 * cam.zoom);
+      spriteW = (font.glyphW * scale) / cam.zoom;
+      spriteH = (font.glyphH * scale) / cam.zoom;
+    } else {
+      worldX = drawX;
+      worldY = y;
+      spriteW = font.glyphW * scale;
+      spriteH = font.glyphH * scale;
+    }
+
+    drawSprite({
+      textureId: font.textureId,
+      x: worldX,
+      y: worldY,
+      w: spriteW,
+      h: spriteH,
+      layer,
+      uv,
+      tint,
+    });
+  }
+}

package/src/rendering/texture.ts

@@ -0,0 +1,31 @@
+import type { TextureId } from "./types.ts";
+
+const hasRenderOps =
+  typeof (globalThis as any).Deno !== "undefined" &&
+  typeof (globalThis as any).Deno?.core?.ops?.op_load_texture === "function";
+
+/**
+ * Load a texture from a PNG file path. Returns a texture handle.
+ * Caches by path — loading the same path twice returns the same handle.
+ * Returns 0 (no texture) in headless mode.
+ */
+export function loadTexture(path: string): TextureId {
+  if (!hasRenderOps) return 0;
+  return (globalThis as any).Deno.core.ops.op_load_texture(path);
+}
+
+/**
+ * Create a solid-color 1x1 texture. Useful for placeholder sprites.
+ * Colors are 0-255 RGBA.
+ * Returns 0 (no texture) in headless mode.
+ */
+export function createSolidTexture(
+  name: string,
+  r: number,
+  g: number,
+  b: number,
+  a: number = 255,
+): TextureId {
+  if (!hasRenderOps) return 0;
+  return (globalThis as any).Deno.core.ops.op_create_solid_texture(name, r, g, b, a);
+}

package/src/rendering/tilemap.ts

@@ -0,0 +1,46 @@
+import type { TilemapId, TilemapOptions } from "./types.ts";
+
+const hasRenderOps =
+  typeof (globalThis as any).Deno !== "undefined" &&
+  typeof (globalThis as any).Deno?.core?.ops?.op_create_tilemap === "function";
+
+/** Create a tilemap backed by a texture atlas. Returns a TilemapId handle. */
+export function createTilemap(opts: TilemapOptions): TilemapId {
+  if (!hasRenderOps) return 0;
+  return (globalThis as any).Deno.core.ops.op_create_tilemap(
+    opts.textureId,
+    opts.width,
+    opts.height,
+    opts.tileSize,
+    opts.atlasColumns,
+    opts.atlasRows,
+  );
+}
+
+/** Set a tile at grid position (gx, gy). Tile ID 0 = empty. */
+export function setTile(
+  id: TilemapId,
+  gx: number,
+  gy: number,
+  tileId: number,
+): void {
+  if (!hasRenderOps) return;
+  (globalThis as any).Deno.core.ops.op_set_tile(id, gx, gy, tileId);
+}
+
+/** Get the tile ID at grid position (gx, gy). Returns 0 if out of bounds. */
+export function getTile(id: TilemapId, gx: number, gy: number): number {
+  if (!hasRenderOps) return 0;
+  return (globalThis as any).Deno.core.ops.op_get_tile(id, gx, gy);
+}
+
+/** Draw all visible tiles as sprites (camera-culled). */
+export function drawTilemap(
+  id: TilemapId,
+  x: number = 0,
+  y: number = 0,
+  layer: number = 0,
+): void {
+  if (!hasRenderOps) return;
+  (globalThis as any).Deno.core.ops.op_draw_tilemap(id, x, y, layer);
+}

package/src/rendering/types.ts

@@ -0,0 +1,54 @@
+/** Opaque handle to a loaded texture. */
+export type TextureId = number;
+
+/** Options for drawing a sprite. */
+export type SpriteOptions = {
+  /** Texture handle from loadTexture() or createSolidTexture(). */
+  textureId: TextureId;
+  /** World X position (top-left corner). */
+  x: number;
+  /** World Y position (top-left corner). */
+  y: number;
+  /** Width in world units. */
+  w: number;
+  /** Height in world units. */
+  h: number;
+  /** Draw order layer (lower = drawn first / behind). Default: 0. */
+  layer?: number;
+  /** UV sub-rect for atlas sprites. Default: full texture. */
+  uv?: { x: number; y: number; w: number; h: number };
+  /** RGBA tint color (0-1 range). Default: white (1,1,1,1). */
+  tint?: { r: number; g: number; b: number; a: number };
+};
+
+/** Camera state. */
+export type CameraState = {
+  x: number;
+  y: number;
+  zoom: number;
+};
+
+/** Mouse position. */
+export type MousePosition = {
+  x: number;
+  y: number;
+};
+
+/** Opaque handle to a tilemap. */
+export type TilemapId = number;
+
+/** Options for creating a tilemap. */
+export type TilemapOptions = {
+  /** Texture atlas handle from loadTexture(). */
+  textureId: number;
+  /** Grid width in tiles. */
+  width: number;
+  /** Grid height in tiles. */
+  height: number;
+  /** Size of each tile in world units. */
+  tileSize: number;
+  /** Number of columns in the texture atlas. */
+  atlasColumns: number;
+  /** Number of rows in the texture atlas. */
+  atlasRows: number;
+};

package/src/rendering/validate.ts

@@ -0,0 +1,132 @@
+/**
+ * Runtime validation for rendering API calls
+ * Add this to production code to catch errors early
+ */
+
+export interface ValidationOptions {
+  throwOnError?: boolean;
+  logErrors?: boolean;
+}
+
+const defaultOptions: ValidationOptions = {
+  throwOnError: true,
+  logErrors: false,
+};
+
+export function validateNumber(
+  api: string,
+  param: string,
+  value: any,
+  options: ValidationOptions = defaultOptions
+): boolean {
+  if (typeof value !== "number") {
+    const error = `${api}: ${param} must be number, got ${typeof value}`;
+    return handleError(error, options);
+  }
+
+  if (isNaN(value)) {
+    const error = `${api}: ${param} is NaN`;
+    return handleError(error, options);
+  }
+
+  if (!isFinite(value)) {
+    const error = `${api}: ${param} is not finite`;
+    return handleError(error, options);
+  }
+
+  return true;
+}
+
+export function validateColor(
+  api: string,
+  color: any,
+  options: ValidationOptions = defaultOptions
+): boolean {
+  if (typeof color !== "object" || color === null) {
+    const error = `${api}: color must be object`;
+    return handleError(error, options);
+  }
+
+  const { r, g, b } = color;
+
+  if (typeof r !== "number" || r < 0 || r > 1) {
+    const error = `${api}: color.r must be 0.0-1.0, got ${r}`;
+    return handleError(error, options);
+  }
+
+  if (typeof g !== "number" || g < 0 || g > 1) {
+    const error = `${api}: color.g must be 0.0-1.0, got ${g}`;
+    return handleError(error, options);
+  }
+
+  if (typeof b !== "number" || b < 0 || b > 1) {
+    const error = `${api}: color.b must be 0.0-1.0, got ${b}`;
+    return handleError(error, options);
+  }
+
+  return true;
+}
+
+export function validateTextOptions(
+  opts: any,
+  options: ValidationOptions = defaultOptions
+): boolean {
+  if (typeof opts !== "object" || opts === null) {
+    const error = "drawText: options must be object";
+    return handleError(error, options);
+  }
+
+  if (!validateNumber("drawText", "x", opts.x, options)) return false;
+  if (!validateNumber("drawText", "y", opts.y, options)) return false;
+  if (!validateNumber("drawText", "size", opts.size, options)) return false;
+
+  if (opts.color) {
+    if (!validateColor("drawText", opts.color, options)) return false;
+  }
+
+  return true;
+}
+
+export function validateRectParams(
+  x: any,
+  y: any,
+  w: any,
+  h: any,
+  opts?: any,
+  options: ValidationOptions = defaultOptions
+): boolean {
+  if (!validateNumber("drawRect", "x", x, options)) return false;
+  if (!validateNumber("drawRect", "y", y, options)) return false;
+  if (!validateNumber("drawRect", "w", w, options)) return false;
+  if (!validateNumber("drawRect", "h", h, options)) return false;
+
+  if (opts?.color) {
+    if (!validateColor("drawRect", opts.color, options)) return false;
+  }
+
+  return true;
+}
+
+function handleError(message: string, options: ValidationOptions): boolean {
+  if (options.logErrors) {
+    console.error(`[Render Validation] ${message}`);
+  }
+
+  if (options.throwOnError) {
+    throw new Error(message);
+  }
+
+  return false;
+}
+
+// Helper: wrap a rendering function with validation
+export function withValidation<T extends (...args: any[]) => any>(
+  fn: T,
+  validator: (...args: Parameters<T>) => boolean
+): T {
+  return ((...args: Parameters<T>) => {
+    if (validator(...args)) {
+      return fn(...args);
+    }
+  }) as T;
+}

package/src/state/error.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, assert } from "../testing/harness.ts";
+import { createError } from "./error.ts";
+
+describe("createError", () => {
+  it("creates an error with code, message, and context", () => {
+    const err = createError(
+      "COMBAT_TARGET_OUT_OF_RANGE",
+      "Cannot attack goblin_3: distance 7 exceeds weapon range 5",
+      {
+        action: "attack",
+        reason: "target out of range",
+        state: { distance: 7, range: 5 },
+        suggestion: "Move closer or use a ranged weapon",
+      },
+    );
+
+    assert.equal(err.code, "COMBAT_TARGET_OUT_OF_RANGE");
+    assert.equal(err.message, "Cannot attack goblin_3: distance 7 exceeds weapon range 5");
+    assert.equal(err.context.action, "attack");
+    assert.equal(err.context.reason, "target out of range");
+    assert.deepEqual(err.context.state, { distance: 7, range: 5 });
+    assert.equal(err.context.suggestion, "Move closer or use a ranged weapon");
+  });
+
+  it("works without optional fields", () => {
+    const err = createError("INVALID_PATH", "Path not found", {
+      action: "query",
+      reason: "path does not exist",
+    });
+
+    assert.equal(err.context.state, undefined);
+    assert.equal(err.context.suggestion, undefined);
+  });
+
+  it("is JSON-serializable", () => {
+    const err = createError("TEST", "test error", {
+      action: "test",
+      reason: "testing",
+      state: { hp: 0 },
+    });
+
+    const roundTripped = JSON.parse(JSON.stringify(err));
+    assert.deepEqual(roundTripped, err);
+  });
+});

package/src/state/error.ts

@@ -0,0 +1,20 @@
+/** Structured error type — per docs/api-design.md */
+export type ArcaneError = Readonly<{
+  code: string;
+  message: string;
+  context: Readonly<{
+    action: string;
+    reason: string;
+    state?: Readonly<Record<string, unknown>>;
+    suggestion?: string;
+  }>;
+}>;
+
+/** Create an ArcaneError */
+export function createError(
+  code: string,
+  message: string,
+  context: ArcaneError["context"],
+): ArcaneError {
+  return { code, message, context };
+}