nova64 0.2.6 → 0.2.8

package/dist/runtime/api-2d.js

@@ -0,0 +1,1158 @@
+// runtime/api-2d.js
+// Nova64 Enhanced 2D Drawing API
+// All primitives operate on the framebuffer (the 2D overlay that composites over the 3D scene).
+//
+// Exposed globals: drawGradient, drawRadialGradient, drawRoundedRect, poly, tristrip,
+//   printCentered, printRight, drawScanlines, drawNoise, drawProgressBar,
+//   drawGlowText, drawPixelBorder, drawCheckerboard, colorLerp, colorMix, hexColor,
+//   drawStarburst, drawDiamond, drawTriangle, drawWave, drawSpiral, scrollingText,
+//   drawPanel, drawHealthBar, createMinimap, drawMinimap, n64Palette
+
+import { rgba8 } from './api.js';
+
+// ─── colour helpers ───────────────────────────────────────────────────────────
+
+/** Unpack an rgba8() BigInt into {r,g,b,a} 0-255 floats */
+function _unpack(c) {
+  if (typeof c === 'bigint') {
+    return {
+      r: Number((c >> 48n) & 0xffffn) / 257,
+      g: Number((c >> 32n) & 0xffffn) / 257,
+      b: Number((c >> 16n) & 0xffffn) / 257,
+      a: Number(c & 0xffffn) / 257,
+    };
+  }
+  const bc = BigInt(Math.floor(c));
+  return {
+    r: Number((bc >> 48n) & 0xffffn) / 257,
+    g: Number((bc >> 32n) & 0xffffn) / 257,
+    b: Number((bc >> 16n) & 0xffffn) / 257,
+    a: Number(bc & 0xffffn) / 257,
+  };
+}
+
+/** Linearly interpolate two rgba8 colours. t = 0..1 */
+function colorLerp(c1, c2, t) {
+  const a = _unpack(c1),
+    b = _unpack(c2);
+  return rgba8(
+    a.r + (b.r - a.r) * t,
+    a.g + (b.g - a.g) * t,
+    a.b + (b.b - a.b) * t,
+    a.a + (b.a - a.a) * t
+  );
+}
+
+/** Multiply/tint a colour by a brightness factor 0..2 */
+function colorMix(c, factor) {
+  const { r, g, b, a } = _unpack(c);
+  return rgba8(Math.min(255, r * factor), Math.min(255, g * factor), Math.min(255, b * factor), a);
+}
+
+/** Convert 0xRRGGBB hex number to rgba8 */
+function hexColor(hex, alpha = 255) {
+  return rgba8((hex >> 16) & 0xff, (hex >> 8) & 0xff, hex & 0xff, alpha);
+}
+
+/** Convert HSL(0-360, 0-1, 0-1) to rgba8 */
+function hslColor(h, s = 1, l = 0.5, alpha = 255) {
+  h = ((h % 360) + 360) % 360;
+  const c = (1 - Math.abs(2 * l - 1)) * s;
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+  const m = l - c / 2;
+  let r, g, b;
+  if (h < 60) {
+    r = c;
+    g = x;
+    b = 0;
+  } else if (h < 120) {
+    r = x;
+    g = c;
+    b = 0;
+  } else if (h < 180) {
+    r = 0;
+    g = c;
+    b = x;
+  } else if (h < 240) {
+    r = 0;
+    g = x;
+    b = c;
+  } else if (h < 300) {
+    r = x;
+    g = 0;
+    b = c;
+  } else {
+    r = c;
+    g = 0;
+    b = x;
+  }
+  return rgba8(
+    Math.round((r + m) * 255),
+    Math.round((g + m) * 255),
+    Math.round((b + m) * 255),
+    alpha
+  );
+}
+
+// ─── Math utilities ──────────────────────────────────────────────────────────
+
+/** Linear interpolation: lerp(a, b, t) → a + (b - a) * t */
+function lerp(a, b, t) {
+  return a + (b - a) * t;
+}
+
+/** Clamp value between min and max */
+function clamp(v, min = 0, max = 1) {
+  return v < min ? min : v > max ? max : v;
+}
+
+/** Random float in [min, max) */
+function randRange(min, max) {
+  return min + Math.random() * (max - min);
+}
+
+/** Random integer in [min, max] inclusive */
+function randInt(min, max) {
+  return (min + Math.random() * (max - min + 1)) | 0;
+}
+
+/** Distance between two 2D points */
+function dist(x1, y1, x2, y2) {
+  const dx = x2 - x1,
+    dy = y2 - y1;
+  return Math.sqrt(dx * dx + dy * dy);
+}
+
+/** Distance between two 3D points */
+function dist3d(x1, y1, z1, x2, y2, z2) {
+  const dx = x2 - x1,
+    dy = y2 - y1,
+    dz = z2 - z1;
+  return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}
+
+/** Map a value from one range to another */
+function remap(value, inMin, inMax, outMin, outMax) {
+  return outMin + ((value - inMin) * (outMax - outMin)) / (inMax - inMin);
+}
+
+/** Smooth pulse: returns 0-1-0 based on time with given frequency */
+function pulse(time, frequency = 1) {
+  return Math.sin(time * frequency * Math.PI * 2) * 0.5 + 0.5;
+}
+
+/** Convert degrees to radians */
+function deg2rad(d) {
+  return (d * Math.PI) / 180;
+}
+
+/** Convert radians to degrees */
+function rad2deg(r) {
+  return (r * 180) / Math.PI;
+}
+
+// ─── Classic N64 / PS1 limited palette ───────────────────────────────────────
+const n64Palette = {
+  black: rgba8(0, 0, 0),
+  white: rgba8(255, 255, 255),
+  red: rgba8(220, 30, 30),
+  green: rgba8(30, 200, 60),
+  blue: rgba8(30, 80, 220),
+  yellow: rgba8(255, 220, 0),
+  cyan: rgba8(0, 220, 220),
+  magenta: rgba8(200, 0, 200),
+  orange: rgba8(255, 140, 0),
+  purple: rgba8(120, 0, 200),
+  teal: rgba8(0, 160, 160),
+  brown: rgba8(140, 80, 30),
+  grey: rgba8(128, 128, 128),
+  darkGrey: rgba8(60, 60, 60),
+  lightGrey: rgba8(200, 200, 200),
+  sky: rgba8(70, 130, 200),
+  gold: rgba8(255, 210, 50),
+  silver: rgba8(192, 192, 210),
+};
+
+// ─── actual drawing functions ─────────────────────────────────────────────────
+
+export function api2d(gpu) {
+  const fb = gpu.getFramebuffer();
+  const W = fb.width; // 640
+  const H = fb.height; // 360
+
+  // cached camRef from std api - unused for 2D (no camera offset)
+  // const cam = { x: 0, y: 0 };
+
+  // helper: write a pixel with alpha blending
+  function _blend(x, y, r, g, b, a) {
+    if (x < 0 || y < 0 || x >= W || y >= H) return;
+    if (a >= 255) {
+      fb.pset(x, y, r * 257, g * 257, b * 257, 65535);
+      return;
+    }
+    const i = (y * W + x) * 4;
+    const p = fb.pixels;
+    const af = a / 255;
+    const bf = 1 - af;
+    p[i] = Math.round(r * af + (p[i] / 257) * bf) * 257;
+    p[i + 1] = Math.round(g * af + (p[i + 1] / 257) * bf) * 257;
+    p[i + 2] = Math.round(b * af + (p[i + 2] / 257) * bf) * 257;
+    p[i + 3] = 65535;
+  }
+
+  /** pset with color as rgba8 bigint */
+  function _pset(x, y, color) {
+    const c = _unpack(color);
+    _blend(x | 0, y | 0, c.r, c.g, c.b, c.a);
+  }
+
+  // ── Gradient fills ──────────────────────────────────────────────────────────
+
+  /**
+   * drawGradient(x, y, w, h, c1, c2, dir)
+   * dir: 'v' vertical (top→bottom), 'h' horizontal (left→right), 'd' diagonal
+   */
+  function drawGradient(x, y, w, h, c1, c2, dir = 'v') {
+    x |= 0;
+    y |= 0;
+    w |= 0;
+    h |= 0;
+    const a1 = _unpack(c1),
+      a2 = _unpack(c2);
+    const x1 = Math.max(0, x),
+      y1 = Math.max(0, y);
+    const x2 = Math.min(W, x + w),
+      y2 = Math.min(H, y + h);
+    for (let py = y1; py < y2; py++) {
+      for (let px = x1; px < x2; px++) {
+        let t;
+        if (dir === 'h') {
+          t = w > 0 ? (px - x) / w : 0;
+        } else if (dir === 'd') {
+          t = w + h > 0 ? (px - x + (py - y)) / (w + h) : 0;
+        } else {
+          t = h > 0 ? (py - y) / h : 0;
+        }
+        t = Math.max(0, Math.min(1, t));
+        _blend(
+          px,
+          py,
+          (a1.r + (a2.r - a1.r) * t) | 0,
+          (a1.g + (a2.g - a1.g) * t) | 0,
+          (a1.b + (a2.b - a1.b) * t) | 0,
+          (a1.a + (a2.a - a1.a) * t) | 0
+        );
+      }
+    }
+  }
+
+  /**
+   * drawRadialGradient(cx, cy, radius, innerColor, outerColor)
+   * Great for glows, halos, spot lights.
+   */
+  function drawRadialGradient(cx, cy, radius, innerColor, outerColor) {
+    cx |= 0;
+    cy |= 0;
+    radius = radius | 0;
+    const ci = _unpack(innerColor),
+      co = _unpack(outerColor);
+    const x1 = Math.max(0, cx - radius),
+      y1 = Math.max(0, cy - radius);
+    const x2 = Math.min(W, cx + radius),
+      y2 = Math.min(H, cy + radius);
+    const r2 = radius * radius;
+    for (let py = y1; py < y2; py++) {
+      for (let px = x1; px < x2; px++) {
+        const dx = px - cx,
+          dy = py - cy;
+        const d2 = dx * dx + dy * dy;
+        if (d2 > r2) continue;
+        const t = Math.sqrt(d2) / radius;
+        _blend(
+          px,
+          py,
+          (ci.r + (co.r - ci.r) * t) | 0,
+          (ci.g + (co.g - ci.g) * t) | 0,
+          (ci.b + (co.b - ci.b) * t) | 0,
+          (ci.a + (co.a - ci.a) * t) | 0
+        );
+      }
+    }
+  }
+
+  // ── Rounded rect ────────────────────────────────────────────────────────────
+
+  /**
+   * drawRoundedRect(x, y, w, h, radius, color, fill=true)
+   * PS1/N64-style rounded panel corners.
+   */
+  function drawRoundedRect(x, y, w, h, radius, color, fill = true) {
+    x |= 0;
+    y |= 0;
+    w |= 0;
+    h |= 0;
+    radius = Math.min(radius | 0, Math.min(w, h) >> 1);
+    const { r, g, b, a } = _unpack(color);
+
+    if (fill) {
+      // Fill main body (three rects)
+      for (let py = y + radius; py < y + h - radius; py++) {
+        for (let px = x; px < x + w; px++) _blend(px, py, r, g, b, a);
+      }
+      for (let py = y; py < y + radius; py++) {
+        for (let px = x + radius; px < x + w - radius; px++) _blend(px, py, r, g, b, a);
+      }
+      for (let py = y + h - radius; py < y + h; py++) {
+        for (let px = x + radius; px < x + w - radius; px++) _blend(px, py, r, g, b, a);
+      }
+      // Fill corners with quarter-circles
+      const corners = [
+        [x + radius, y + radius],
+        [x + w - radius - 1, y + radius],
+        [x + radius, y + h - radius - 1],
+        [x + w - radius - 1, y + h - radius - 1],
+      ];
+      for (const [cx, cy] of corners) {
+        for (let dy = -radius; dy <= radius; dy++) {
+          for (let dx = -radius; dx <= radius; dx++) {
+            if (dx * dx + dy * dy <= radius * radius) _blend(cx + dx, cy + dy, r, g, b, a);
+          }
+        }
+      }
+    } else {
+      // Outline only — top/bottom edges
+      for (let px = x + radius; px < x + w - radius; px++) {
+        _blend(px, y, r, g, b, a);
+        _blend(px, y + h - 1, r, g, b, a);
+      }
+      // Left/right edges
+      for (let py = y + radius; py < y + h - radius; py++) {
+        _blend(x, py, r, g, b, a);
+        _blend(x + w - 1, py, r, g, b, a);
+      }
+      // Corners (just the arc outline)
+      const corners = [
+        [x + radius, y + radius, -1, -1],
+        [x + w - radius - 1, y + radius, 1, -1],
+        [x + radius, y + h - radius - 1, -1, 1],
+        [x + w - radius - 1, y + h - radius - 1, 1, 1],
+      ];
+      for (const [cx, cy, sx, sy] of corners) {
+        for (let angle = 0; angle <= 90; angle += 1) {
+          const rad = (angle * Math.PI) / 180;
+          const px = (cx + sx * Math.cos(rad) * radius) | 0;
+          const py = (cy + sy * Math.sin(rad) * radius) | 0;
+          _blend(px, py, r, g, b, a);
+        }
+      }
+    }
+  }
+
+  // ── Polygon ─────────────────────────────────────────────────────────────────
+
+  /**
+   * poly(points, color, fill=true)
+   * points: [[x0,y0],[x1,y1],...] — convex or concave polygon
+   * Uses scanline fill for filled, Bresenham for outline.
+   */
+  function poly(points, color, fill = true) {
+    if (points.length < 3) return;
+    const { r, g, b, a } = _unpack(color);
+
+    if (fill) {
+      const minY = Math.max(0, Math.min(...points.map(p => p[1])) | 0);
+      const maxY = Math.min(H - 1, Math.max(...points.map(p => p[1])) | 0);
+      for (let py = minY; py <= maxY; py++) {
+        const intersections = [];
+        const n = points.length;
+        for (let i = 0; i < n; i++) {
+          const [x0, y0] = points[i];
+          const [x1, y1] = points[(i + 1) % n];
+          if ((y0 <= py && py < y1) || (y1 <= py && py < y0)) {
+            const t = (py - y0) / (y1 - y0);
+            intersections.push(x0 + t * (x1 - x0));
+          }
+        }
+        intersections.sort((a, b) => a - b);
+        for (let i = 0; i + 1 < intersections.length; i += 2) {
+          const lx = Math.max(0, intersections[i] | 0);
+          const rx = Math.min(W - 1, intersections[i + 1] | 0);
+          for (let px = lx; px <= rx; px++) _blend(px, py, r, g, b, a);
+        }
+      }
+    } else {
+      // Outline
+      const n = points.length;
+      for (let i = 0; i < n; i++) {
+        const [x0, y0] = points[i];
+        const [x1, y1] = points[(i + 1) % n];
+        // Bresenham
+        let dx = Math.abs(x1 - x0),
+          dy = -Math.abs(y1 - y0);
+        let sx = x0 < x1 ? 1 : -1,
+          sy = y0 < y1 ? 1 : -1;
+        let err = dx + dy,
+          px = x0 | 0,
+          py = y0 | 0;
+        for (;;) {
+          _blend(px, py, r, g, b, a);
+          if (px === (x1 | 0) && py === (y1 | 0)) break;
+          const e2 = 2 * err;
+          if (e2 >= dy) {
+            err += dy;
+            px += sx;
+          }
+          if (e2 <= dx) {
+            err += dx;
+            py += sy;
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * drawTriangle(x0,y0, x1,y1, x2,y2, color, fill=true)
+   */
+  function drawTriangle(x0, y0, x1, y1, x2, y2, color, fill = true) {
+    poly(
+      [
+        [x0, y0],
+        [x1, y1],
+        [x2, y2],
+      ],
+      color,
+      fill
+    );
+  }
+
+  /**
+   * drawDiamond(cx, cy, halfW, halfH, color, fill=true)
+   */
+  function drawDiamond(cx, cy, halfW, halfH, color, fill = true) {
+    poly(
+      [
+        [cx, cy - halfH],
+        [cx + halfW, cy],
+        [cx, cy + halfH],
+        [cx - halfW, cy],
+      ],
+      color,
+      fill
+    );
+  }
+
+  // ── Text helpers ─────────────────────────────────────────────────────────────
+
+  // We reach into the gpu's exposed stdApi print via globalThis
+  function _print(text, x, y, color, scale) {
+    if (typeof globalThis.print === 'function') globalThis.print(text, x, y, color, scale);
+  }
+
+  function measureText(text, scale = 1) {
+    // 5px glyph + 1px spacing = 6px per character; 7px tall
+    const s = Math.max(1, Math.round(scale));
+    return { width: text.length * 6 * s, height: 7 * s };
+  }
+
+  /** printCentered(text, cx, y, color, scale=1) — centre on x */
+  function printCentered(text, cx, y, color, scale = 1) {
+    const w = measureText(text, scale).width;
+    _print(text, (cx - w / 2) | 0, y, color, scale);
+  }
+
+  /** printRight(text, rightX, y, color, scale=1) — right-align */
+  function printRight(text, rightX, y, color, scale = 1) {
+    const w = measureText(text, scale).width;
+    _print(text, (rightX - w) | 0, y, color, scale);
+  }
+
+  /**
+   * drawGlowText(text, x, y, color, glowColor, scale=1)
+   * Prints text with a soft glow halo by drawing the glowColor in 8 surrounding offsets
+   * then the main color on top. Pure N64/Dreamcast HUD aesthetic.
+   */
+  function drawGlowText(text, x, y, color, glowColor, scale = 1) {
+    const offsets = [
+      [-1, -1],
+      [0, -1],
+      [1, -1],
+      [-1, 0],
+      [1, 0],
+      [-1, 1],
+      [0, 1],
+      [1, 1],
+    ];
+    for (const [dx, dy] of offsets) {
+      _print(text, x + dx, y + dy, glowColor, scale);
+    }
+    _print(text, x, y, color, scale);
+  }
+
+  /**
+   * drawGlowTextCentered(text, cx, y, color, glowColor, scale=1)
+   */
+  function drawGlowTextCentered(text, cx, y, color, glowColor, scale = 1) {
+    const w = measureText(text, scale).width;
+    drawGlowText(text, (cx - w / 2) | 0, y, color, glowColor, scale);
+  }
+
+  /**
+   * drawPulsingText(text, cx, y, color, time, opts)
+   * Centered text that pulses opacity and/or scale over time.
+   * opts: { frequency, minAlpha, glowColor, scale }
+   */
+  function drawPulsingText(text, cx, y, color, time, opts = {}) {
+    const freq = opts.frequency ?? 3;
+    const minAlpha = opts.minAlpha ?? 120;
+    const scale = opts.scale ?? 1;
+    const alpha = Math.floor((Math.sin(time * freq) * 0.5 + 0.5) * (255 - minAlpha) + minAlpha);
+    const { r, g, b } = _unpack(color);
+    const pulsedColor = rgba8(r, g, b, alpha);
+    if (opts.glowColor) {
+      drawGlowTextCentered(text, cx, y, pulsedColor, opts.glowColor, scale);
+    } else {
+      printCentered(text, cx, y, pulsedColor, scale);
+    }
+  }
+
+  // ── Screen overlays ──────────────────────────────────────────────────────────
+
+  /**
+   * drawScanlines(alpha=80, spacing=2)
+   * CRT scanline overlay — horizontal dark bands every `spacing` rows.
+   */
+  function drawScanlines(alpha = 80, spacing = 2) {
+    const p = fb.pixels;
+    const af = (255 - alpha) / 255;
+    for (let y = 0; y < H; y += spacing) {
+      for (let x = 0; x < W; x++) {
+        const i = (y * W + x) * 4;
+        p[i] = (p[i] * af) | 0;
+        p[i + 1] = (p[i + 1] * af) | 0;
+        p[i + 2] = (p[i + 2] * af) | 0;
+      }
+    }
+  }
+
+  /**
+   * drawNoise(x, y, w, h, alpha=40, seed=0)
+   * Deterministic LCG grain/static overlay. Good for title card grit.
+   */
+  function drawNoise(x, y, w, h, alpha = 40, seed = 0) {
+    x |= 0;
+    y |= 0;
+    w |= 0;
+    h |= 0;
+    let s = seed | 12345;
+    const x1 = Math.max(0, x),
+      y1 = Math.max(0, y);
+    const x2 = Math.min(W, x + w),
+      y2 = Math.min(H, y + h);
+    for (let py = y1; py < y2; py++) {
+      for (let px = x1; px < x2; px++) {
+        s = (s * 1664525 + 1013904223) & 0xffffffff;
+        const n = (s >>> 16) & 0xff;
+        _blend(px, py, n, n, n, ((n / 255) * alpha) | 0);
+      }
+    }
+  }
+
+  /**
+   * drawCheckerboard(x, y, w, h, c1, c2, size=8)
+   * N64 loading pattern / retro background filler.
+   */
+  function drawCheckerboard(x, y, w, h, c1, c2, size = 8) {
+    x |= 0;
+    y |= 0;
+    w |= 0;
+    h |= 0;
+    size |= 0;
+    const x1 = Math.max(0, x),
+      y1 = Math.max(0, y);
+    const x2 = Math.min(W, x + w),
+      y2 = Math.min(H, y + h);
+    for (let py = y1; py < y2; py++) {
+      for (let px = x1; px < x2; px++) {
+        const cell = ((((px - x) / size) | 0) + (((py - y) / size) | 0)) % 2;
+        _pset(px, py, cell === 0 ? c1 : c2);
+      }
+    }
+  }
+
+  // ── Progress / HUD bars ───────────────────────────────────────────────────────
+
+  /**
+   * drawProgressBar(x, y, w, h, t, fgColor, bgColor, borderColor)
+   * t = 0..1  fill fraction.
+   */
+  function drawProgressBar(x, y, w, h, t, fgColor, bgColor, borderColor) {
+    t = Math.max(0, Math.min(1, t));
+    // Background
+    if (bgColor !== undefined) {
+      const bg = _unpack(bgColor);
+      for (let py = y; py < y + h; py++)
+        for (let px = x; px < x + w; px++) _blend(px, py, bg.r, bg.g, bg.b, bg.a);
+    }
+    // Fill
+    const fill = (w * t) | 0;
+    const fg = _unpack(fgColor);
+    for (let py = y; py < y + h; py++)
+      for (let px = x; px < x + fill; px++) _blend(px, py, fg.r, fg.g, fg.b, fg.a);
+    // Border
+    if (borderColor !== undefined) {
+      const bc = _unpack(borderColor);
+      for (let px = x; px < x + w; px++) {
+        _blend(px, y, bc.r, bc.g, bc.b, bc.a);
+        _blend(px, y + h - 1, bc.r, bc.g, bc.b, bc.a);
+      }
+      for (let py = y; py < y + h; py++) {
+        _blend(x, py, bc.r, bc.g, bc.b, bc.a);
+        _blend(x + w - 1, py, bc.r, bc.g, bc.b, bc.a);
+      }
+    }
+  }
+
+  /**
+   * drawHealthBar(x, y, w, h, current, max, opts)
+   * opts: { barColor, backgroundColor, borderColor, dangerColor, dangerThreshold }
+   * Auto-switches to dangerColor when hp < dangerThreshold (default 0.25).
+   */
+  function drawHealthBar(x, y, w, h, current, max, opts = {}) {
+    const t = max > 0 ? current / max : 0;
+    const danger = opts.dangerThreshold ?? 0.25;
+    const fg =
+      t < danger ? (opts.dangerColor ?? rgba8(220, 40, 40)) : (opts.barColor ?? rgba8(50, 220, 80));
+    drawProgressBar(
+      x,
+      y,
+      w,
+      h,
+      t,
+      fg,
+      opts.backgroundColor ?? rgba8(30, 30, 30, 200),
+      opts.borderColor ?? rgba8(200, 200, 200, 180)
+    );
+  }
+
+  // ── PS1/N64 panel border ──────────────────────────────────────────────────────
+
+  /**
+   * drawPixelBorder(x, y, w, h, lightColor, darkColor, thickness=2)
+   * 3D-embossed bevel — PS1/SNES-style UI panel border.
+   */
+  function drawPixelBorder(x, y, w, h, lightColor, darkColor, thickness = 2) {
+    const lc = _unpack(lightColor),
+      dc = _unpack(darkColor);
+    for (let i = 0; i < thickness; i++) {
+      // Top & left (light)
+      for (let px = x + i; px < x + w - i; px++) _blend(px, y + i, lc.r, lc.g, lc.b, lc.a);
+      for (let py = y + i; py < y + h - i; py++) _blend(x + i, py, lc.r, lc.g, lc.b, lc.a);
+      // Bottom & right (dark)
+      for (let px = x + i; px < x + w - i; px++) _blend(px, y + h - 1 - i, dc.r, dc.g, dc.b, dc.a);
+      for (let py = y + i; py < y + h - i; py++) _blend(x + w - 1 - i, py, dc.r, dc.g, dc.b, dc.a);
+    }
+  }
+
+  // ── Decorative shapes ─────────────────────────────────────────────────────────
+
+  /**
+   * drawStarburst(cx, cy, outerR, innerR, spikes, color, fill=true)
+   * Classic star shape — great for score popups and collectible icons.
+   */
+  function drawStarburst(cx, cy, outerR, innerR, spikes, color, fill = true) {
+    const pts = [];
+    for (let i = 0; i < spikes * 2; i++) {
+      const angle = (i * Math.PI) / spikes - Math.PI / 2;
+      const r = i % 2 === 0 ? outerR : innerR;
+      pts.push([cx + Math.cos(angle) * r, cy + Math.sin(angle) * r]);
+    }
+    poly(pts, color, fill);
+  }
+
+  /**
+   * drawWave(x, y, w, amplitude, frequency, phase, color, thickness=2)
+   * Animated sine wave — good for water, plasma, audio visualizers.
+   * phase = time * speed for animation.
+   */
+  function drawWave(x, y, w, amplitude, frequency, phase, color, thickness = 2) {
+    const { r, g, b, a } = _unpack(color);
+    for (let px = x; px < x + w && px < W; px++) {
+      const py = (y + Math.sin((px - x) * frequency + phase) * amplitude) | 0;
+      for (let t = -thickness >> 1; t <= thickness >> 1; t++) {
+        const ny = py + t;
+        if (ny >= 0 && ny < H) _blend(px, ny, r, g, b, a);
+      }
+    }
+  }
+
+  /**
+   * drawSpiral(cx, cy, turns, spacing, color)
+   * Decorative Archimedean spiral — psychedelic demoscene / loading screen art.
+   */
+  function drawSpiral(cx, cy, turns, spacing, color) {
+    const { r, g, b, a } = _unpack(color);
+    const steps = turns * 360;
+    for (let i = 0; i < steps; i++) {
+      const angle = (i / 180) * Math.PI;
+      const rad = (i / 360) * spacing;
+      const px = (cx + Math.cos(angle) * rad) | 0;
+      const py = (cy + Math.sin(angle) * rad) | 0;
+      if (px >= 0 && px < W && py >= 0 && py < H) _blend(px, py, r, g, b, a);
+    }
+  }
+
+  // ── Composite widgets ─────────────────────────────────────────────────────────
+
+  /**
+   * drawPanel(x, y, w, h, opts)
+   * A complete PS1/N64-style info panel with background, border, and optional title.
+   * opts: { bgColor, borderLight, borderDark, title, titleColor, padding, alpha }
+   */
+  function drawPanel(x, y, w, h, opts = {}) {
+    const bg = opts.bgColor ?? rgba8(10, 10, 30, 200);
+    const bl = opts.borderLight ?? rgba8(180, 180, 220, 255);
+    const bd = opts.borderDark ?? rgba8(30, 30, 60, 255);
+    // opts.alpha available for callers but not used in fill path
+
+    // Fill panel (re-use opts.bgColor with alpha override)
+    const bgc = _unpack(bg);
+    for (let py = y + 2; py < y + h - 2; py++)
+      for (let px = x + 2; px < x + w - 2; px++) _blend(px, py, bgc.r, bgc.g, bgc.b, bgc.a);
+
+    // 3D border
+    drawPixelBorder(x, y, w, h, bl, bd, 2);
+
+    // Optional title text at top
+    if (opts.title) {
+      const tc = opts.titleColor ?? rgba8(255, 255, 255, 255);
+      const pad = opts.padding ?? 6;
+      printCentered(opts.title, x + w / 2, y + pad, tc);
+    }
+  }
+
+  // ── Minimap System ─────────────────────────────────────────────────────────
+
+  /**
+   * createMinimap(opts) — create a reusable minimap configuration.
+   *
+   * opts:
+   *   x, y          — screen position (default: bottom-right corner)
+   *   width, height  — pixel dimensions (default: 80×80)
+   *   bgColor       — background fill (default: semi-transparent black)
+   *   borderLight, borderDark — border colours (null to disable border)
+   *   shape         — 'rect' | 'circle' (default: 'rect')
+   *   follow        — entity to center on (object with .x, .y in world coords)
+   *   worldW, worldH — world-space bounds for coordinate mapping
+   *   tileW, tileH  — if set, map is tile-based (grid cells)
+   *   tileScale     — pixels per tile (default: 2)
+   *   tiles         — fn(tx,ty)→color|null or 2D array; null/0 = skip
+   *   fogOfWar      — if set, only reveal tiles within this radius of follow entity
+   *   entities      — array of { x, y, color, size?, label? }
+   *   player        — shorthand for the player entity { x, y, color?, blink? }
+   *   sweep         — { speed, color } for animated radar sweep line
+   *   gridLines     — number of grid divisions (0 = none)
+   *   gridColor     — colour for grid lines
+   *
+   * Returns a minimap object you pass to drawMinimap().
+   * You can mutate its properties between frames (e.g. update entities).
+   */
+  function createMinimap(opts = {}) {
+    return {
+      x: opts.x ?? W - 90,
+      y: opts.y ?? 10,
+      width: opts.width ?? 80,
+      height: opts.height ?? 80,
+      bgColor: opts.bgColor ?? rgba8(0, 0, 0, 180),
+      borderLight: opts.borderLight !== undefined ? opts.borderLight : rgba8(150, 150, 150),
+      borderDark: opts.borderDark !== undefined ? opts.borderDark : rgba8(50, 50, 50),
+      shape: opts.shape ?? 'rect',
+      follow: opts.follow ?? null,
+      worldW: opts.worldW ?? 100,
+      worldH: opts.worldH ?? 100,
+      tileW: opts.tileW ?? 0,
+      tileH: opts.tileH ?? 0,
+      tileScale: opts.tileScale ?? 2,
+      tiles: opts.tiles ?? null,
+      fogOfWar: opts.fogOfWar ?? 0,
+      entities: opts.entities ?? [],
+      player: opts.player ?? null,
+      sweep: opts.sweep ?? null,
+      gridLines: opts.gridLines ?? 0,
+      gridColor: opts.gridColor ?? rgba8(40, 60, 40, 120),
+    };
+  }
+
+  /** Internal: check if pixel is inside a circle */
+  function _inCircle(px, py, cx, cy, r) {
+    const dx = px - cx,
+      dy = py - cy;
+    return dx * dx + dy * dy <= r * r;
+  }
+
+  /**
+   * drawMinimap(minimap, time?)
+   *
+   * Accepts EITHER a createMinimap() object, OR the legacy signature:
+   *   drawMinimap(x, y, size, entities, bgColor)
+   *
+   * time is optional — only needed for sweep animation and player blinking.
+   */
+  function drawMinimap(minimapOrX, timeOrY, sizeArg, entitiesArg, bgColorArg) {
+    // Legacy compat: drawMinimap(x, y, size, entities, bgColor)
+    let mm;
+    let time = 0;
+    if (typeof minimapOrX === 'number') {
+      mm = createMinimap({
+        x: minimapOrX,
+        y: timeOrY,
+        width: sizeArg,
+        height: sizeArg,
+        worldW: 100,
+        worldH: 100,
+        bgColor: bgColorArg,
+      });
+      // Convert legacy entities (they carry worldW/worldH per-entity)
+      if (Array.isArray(entitiesArg)) {
+        mm.entities = entitiesArg.map(e => ({
+          x: e.x,
+          y: e.y,
+          color: e.color ?? rgba8(255, 255, 255),
+          size: 2,
+        }));
+        // Use first entity's world bounds if provided
+        if (entitiesArg.length > 0) {
+          mm.worldW = entitiesArg[0].worldW ?? 100;
+          mm.worldH = entitiesArg[0].worldH ?? 100;
+        }
+      }
+    } else {
+      mm = minimapOrX;
+      time = timeOrY ?? 0;
+    }
+
+    const { x, y, width: mw, height: mh, shape } = mm;
+    const cx = x + mw / 2,
+      cy = y + mh / 2;
+    const isCircle = shape === 'circle';
+    const radius = Math.min(mw, mh) / 2;
+
+    // 1. Background fill
+    const bgc = _unpack(mm.bgColor);
+    for (let py = y; py < y + mh; py++) {
+      for (let px = x; px < x + mw; px++) {
+        if (isCircle && !_inCircle(px, py, cx, cy, radius)) continue;
+        _blend(px, py, bgc.r, bgc.g, bgc.b, bgc.a);
+      }
+    }
+
+    // 2. Tile map rendering
+    if (mm.tiles && mm.tileW > 0 && mm.tileH > 0) {
+      const ts = mm.tileScale;
+      const isFunc = typeof mm.tiles === 'function';
+      const followTX = mm.follow ? Math.floor(mm.follow.x) : 0;
+      const followTY = mm.follow ? Math.floor(mm.follow.y) : 0;
+
+      for (let ty = 0; ty < mm.tileH; ty++) {
+        for (let tx = 0; tx < mm.tileW; tx++) {
+          // Fog of war check
+          if (mm.fogOfWar > 0 && mm.follow) {
+            const dist = Math.abs(tx - followTX) + Math.abs(ty - followTY);
+            if (dist > mm.fogOfWar) continue;
+          }
+
+          const tileColor = isFunc ? mm.tiles(tx, ty) : mm.tiles[ty] ? mm.tiles[ty][tx] : null;
+          if (!tileColor) continue;
+
+          const tc = _unpack(tileColor);
+          const px0 = x + tx * ts;
+          const py0 = y + ty * ts;
+          for (let dy = 0; dy < ts; dy++) {
+            for (let dx = 0; dx < ts; dx++) {
+              const px = px0 + dx,
+                py = py0 + dy;
+              if (isCircle && !_inCircle(px, py, cx, cy, radius)) continue;
+              _blend(px, py, tc.r, tc.g, tc.b, tc.a);
+            }
+          }
+        }
+      }
+    }
+
+    // 3. Grid lines
+    if (mm.gridLines > 0) {
+      const gc = _unpack(mm.gridColor);
+      for (let i = 1; i < mm.gridLines; i++) {
+        // Vertical line
+        const gx = (x + (mw / mm.gridLines) * i) | 0;
+        for (let py2 = y; py2 < y + mh; py2++) {
+          if (isCircle && !_inCircle(gx, py2, cx, cy, radius)) continue;
+          _blend(gx, py2, gc.r, gc.g, gc.b, gc.a);
+        }
+        // Horizontal line
+        const gy = (y + (mh / mm.gridLines) * i) | 0;
+        for (let px2 = x; px2 < x + mw; px2++) {
+          if (isCircle && !_inCircle(px2, gy, cx, cy, radius)) continue;
+          _blend(px2, gy, gc.r, gc.g, gc.b, gc.a);
+        }
+      }
+    }
+
+    // 4. Radar sweep line
+    if (mm.sweep) {
+      const angle = time * (mm.sweep.speed ?? 2);
+      const sc = _unpack(mm.sweep.color ?? rgba8(0, 255, 0, 100));
+      const sx = Math.cos(angle) * radius;
+      const sy = Math.sin(angle) * radius;
+      // Bresenham-ish sweep from center
+      const steps = Math.max(Math.abs(sx), Math.abs(sy)) | 0;
+      if (steps > 0) {
+        for (let s = 0; s <= steps; s++) {
+          const t = s / steps;
+          const px = (cx + sx * t) | 0;
+          const py = (cy + sy * t) | 0;
+          if (px < x || px >= x + mw || py < y || py >= y + mh) continue;
+          if (isCircle && !_inCircle(px, py, cx, cy, radius)) continue;
+          _blend(px, py, sc.r, sc.g, sc.b, sc.a);
+        }
+      }
+    }
+
+    // Helper: convert world coords to screen pixel
+    function worldToScreen(wx, wy) {
+      if (mm.tiles && mm.tileW > 0) {
+        // Tile-based — wx/wy are tile coords
+        return [(x + wx * mm.tileScale) | 0, (y + wy * mm.tileScale) | 0];
+      }
+      // World-space normalised
+      let nx, ny;
+      if (mm.follow) {
+        // Center on follow entity
+        nx = 0.5 + (wx - mm.follow.x) / mm.worldW;
+        ny = 0.5 + (wy - mm.follow.y) / mm.worldH;
+      } else {
+        nx = wx / mm.worldW;
+        ny = wy / mm.worldH;
+      }
+      return [(x + nx * mw) | 0, (y + ny * mh) | 0];
+    }
+
+    // 5. Entity dots
+    for (const e of mm.entities) {
+      const [ex, ey] = worldToScreen(e.x, e.y);
+      const dotSize = e.size ?? 2;
+      if (ex < x - dotSize || ex >= x + mw + dotSize || ey < y - dotSize || ey >= y + mh + dotSize)
+        continue;
+      const ec = _unpack(e.color ?? rgba8(255, 255, 255));
+      const half = (dotSize / 2) | 0;
+      for (let dy = -half; dy < dotSize - half; dy++) {
+        for (let dx = -half; dx < dotSize - half; dx++) {
+          const px = ex + dx,
+            py = ey + dy;
+          if (px < x || px >= x + mw || py < y || py >= y + mh) continue;
+          if (isCircle && !_inCircle(px, py, cx, cy, radius)) continue;
+          _blend(px, py, ec.r, ec.g, ec.b, ec.a);
+        }
+      }
+    }
+
+    // 6. Player marker (with optional blink)
+    if (mm.player) {
+      const blink = mm.player.blink !== false;
+      const visible = !blink || Math.sin(time * 8) > 0;
+      if (visible) {
+        const [px, py] = worldToScreen(mm.player.x, mm.player.y);
+        const pc = _unpack(mm.player.color ?? rgba8(50, 150, 255));
+        const ps = mm.player.size ?? 3;
+        const half = (ps / 2) | 0;
+        for (let dy = -half; dy < ps - half; dy++) {
+          for (let dx = -half; dx < ps - half; dx++) {
+            const ppx = px + dx,
+              ppy = py + dy;
+            if (ppx < x || ppx >= x + mw || ppy < y || ppy >= y + mh) continue;
+            if (isCircle && !_inCircle(ppx, ppy, cx, cy, radius)) continue;
+            _blend(ppx, ppy, pc.r, pc.g, pc.b, pc.a);
+          }
+        }
+      }
+    }
+
+    // 7. Border
+    if (mm.borderLight !== null) {
+      if (isCircle) {
+        // Circle border — draw a ring
+        const bc = _unpack(mm.borderLight);
+        const r2inner = (radius - 1) * (radius - 1);
+        const r2outer = radius * radius;
+        for (let py = y; py < y + mh; py++) {
+          for (let px = x; px < x + mw; px++) {
+            const dx = px - cx,
+              dy = py - cy;
+            const d2 = dx * dx + dy * dy;
+            if (d2 >= r2inner && d2 <= r2outer) {
+              _blend(px, py, bc.r, bc.g, bc.b, bc.a);
+            }
+          }
+        }
+      } else {
+        drawPixelBorder(x, y, mw, mh, mm.borderLight, mm.borderDark, 1);
+      }
+    }
+  }
+
+  /**
+   * scrollingText(text, y, speed, time, color, scale=1, width=640)
+   * Marquee text scrolling left across the screen.
+   * time = accumulated seconds (from novaStore or cart-local variable).
+   */
+  function scrollingText(text, y, speed, time, color, scale = 1, width = 640) {
+    const tw = measureText(text, scale).width;
+    const x = (width - ((time * speed) % (width + tw))) | 0;
+    _print(text, x, y, color, scale);
+  }
+
+  /**
+   * drawFloatingTexts(system, offsetX?, offsetY?)
+   * Render all active texts from a createFloatingTextSystem().
+   * offsetX/offsetY allow camera offset (for screen shake, etc.)
+   */
+  function drawFloatingTexts(system, offsetX = 0, offsetY = 0) {
+    const texts = system.getTexts();
+    for (const t of texts) {
+      const alpha = Math.min(255, Math.floor((t.timer / t.maxTimer) * 255));
+      const r = (t.color >> 16) & 0xff;
+      const g = (t.color >> 8) & 0xff;
+      const b = t.color & 0xff;
+      _print(t.text, (t.x + offsetX) | 0, (t.y + offsetY) | 0, rgba8(r, g, b, alpha), t.scale);
+    }
+  }
+
+  /**
+   * drawFloatingTexts3D(system, projectFn)
+   * Render 3D floating texts using a user-supplied projection function.
+   * projectFn(x, y, z) should return [screenX, screenY].
+   * Use with spawn(..., { z: worldZ }) for 3D world-space floating texts.
+   */
+  function drawFloatingTexts3D(system, projectFn) {
+    const texts = system.getTexts();
+    for (const t of texts) {
+      const [sx, sy] = projectFn(t.x, t.y, t.z ?? 0);
+      const alpha = Math.min(255, Math.floor((t.timer / t.maxTimer) * 255));
+      const r = (t.color >> 16) & 0xff;
+      const g = (t.color >> 8) & 0xff;
+      const b = t.color & 0xff;
+      _print(t.text, sx | 0, sy | 0, rgba8(r, g, b, alpha), t.scale);
+    }
+  }
+
+  // ── Full-screen helpers ───────────────────────────────────────────────────────
+
+  /** Full-screen vertical gradient — great for sky/title backgrounds */
+  function drawSkyGradient(topColor, bottomColor) {
+    drawGradient(0, 0, W, H, topColor, bottomColor, 'v');
+  }
+
+  /** Full-screen flash — use alpha 0..255 for a fade effect */
+  function drawFlash(color) {
+    const { r, g, b, a } = _unpack(color);
+    for (let py = 0; py < H; py++) for (let px = 0; px < W; px++) _blend(px, py, r, g, b, a);
+  }
+
+  /**
+   * Draw a crosshair / reticle at (cx, cy).
+   * @param {number} cx - centre X in screen pixels
+   * @param {number} cy - centre Y in screen pixels
+   * @param {number} [size=8] - half-length of each arm in pixels
+   * @param {number} [color=0xffffffff] - rgba8 or 0xRRGGBB colour
+   * @param {'cross'|'dot'|'circle'} [style='cross'] - reticle style
+   */
+  function drawCrosshair(cx, cy, size = 8, color = 0xffffffff, style = 'cross') {
+    if (style === 'cross' || style === 'dot') {
+      // Horizontal arm
+      for (let x = cx - size; x <= cx + size; x++) _pset(x, cy, color);
+      // Vertical arm
+      for (let y = cy - size; y <= cy + size; y++) _pset(cx, y, color);
+    }
+    if (style === 'circle') {
+      // Thin circle
+      const steps = Math.max(32, size * 4);
+      for (let i = 0; i < steps; i++) {
+        const a = (i / steps) * Math.PI * 2;
+        _pset(Math.round(cx + Math.cos(a) * size), Math.round(cy + Math.sin(a) * size), color);
+      }
+    }
+    if (style === 'dot') {
+      // Centre dot (extra pixels around the intersection)
+      _pset(cx - 1, cy, color);
+      _pset(cx + 1, cy, color);
+      _pset(cx, cy - 1, color);
+      _pset(cx, cy + 1, color);
+    }
+  }
+
+  // ─── expose ──────────────────────────────────────────────────────────────────
+  return {
+    exposeTo(target) {
+      Object.assign(target, {
+        // Colour helpers
+        colorLerp,
+        colorMix,
+        hexColor,
+        hslColor,
+        n64Palette,
+
+        // Math utilities
+        lerp,
+        clamp,
+        randRange,
+        randInt,
+        dist,
+        dist3d,
+        remap,
+        pulse,
+        deg2rad,
+        rad2deg,
+
+        // Gradient fills
+        drawGradient,
+        drawRadialGradient,
+        drawSkyGradient,
+        drawFlash,
+
+        // Shapes
+        drawRoundedRect,
+        poly,
+        drawTriangle,
+        drawDiamond,
+        drawStarburst,
+        drawWave,
+        drawSpiral,
+        drawCheckerboard,
+
+        // Text
+        measureText,
+        printCentered,
+        printRight,
+        drawGlowText,
+        drawGlowTextCentered,
+        drawPulsingText,
+
+        // Overlays
+        drawScanlines,
+        drawNoise,
+
+        // HUD Widgets
+        drawProgressBar,
+        drawHealthBar,
+        drawPixelBorder,
+        drawPanel,
+        drawCrosshair,
+        createMinimap,
+        drawMinimap,
+        drawFloatingTexts,
+        drawFloatingTexts3D,
+        scrollingText,
+      });
+    },
+  };
+}