@ludra/core 0.5.0 → 0.7.0

package/dist/ascii.js

@@ -39,8 +39,8 @@ export function renderAscii(world, options = {}) {
         ["G", (e) => !!e.goal],
         ["^", (e) => !!e.hazard && e.body.type !== "kinematic"],
         ["E", (e) => !!e.hazard && e.body.type === "kinematic"],
-        ["D", (e) => e.body.type === "dynamic" && !e.platformer],
-        ["@", (e) => !!e.platformer],
+        ["D", (e) => e.body.type === "dynamic" && !e.platformer && !e.topdown],
+        ["@", (e) => !!(e.platformer || e.topdown)],
     ];
     for (const [char, test] of passes) {
         for (const e of withBody.filter(test))

package/dist/browser.js

@@ -11,6 +11,7 @@ import { parseFrames } from "./components.js";
 import { collectAssetPaths } from "./effects.js";
 import { InputScript } from "./input.js";
 import { ParticleSystem } from "./particles.js";
+import { PostFx } from "./postfx.js";
 import { FIXED_DT } from "./time.js";
 import { World } from "./world.js";
 const KEYMAP = {
@@ -44,6 +45,76 @@ async function loadScripts(scene, options) {
     }));
     return scripts;
 }
+/** Fonts load from Google Fonts or project files; a slow or offline font never blocks the game for long. */
+async function loadFonts(scene, assetBase) {
+    const fonts = Object.entries(scene.fonts ?? {});
+    if (fonts.length === 0)
+        return;
+    const load = async ([family, src]) => {
+        if (src === "google") {
+            const name = encodeURIComponent(family).replace(/%20/g, "+");
+            // Not every family has every weight, and Google rejects the request if one is missing.
+            for (const weights of [":wght@400;500;600;700;800;900", ":wght@400;700", ""]) {
+                const response = await fetch(`https://fonts.googleapis.com/css2?family=${name}${weights}&display=block`);
+                if (!response.ok)
+                    continue;
+                const style = document.createElement("style");
+                style.textContent = await response.text();
+                document.head.append(style);
+                break;
+            }
+            await Promise.all(["400", "700", "900"].map((weight) => document.fonts.load(`${weight} 16px "${family}"`)));
+        }
+        else {
+            const face = new FontFace(family, `url("${assetBase}${src}")`);
+            // FontFaceSet.add is missing from some TypeScript DOM typings.
+            document.fonts.add(await face.load());
+        }
+    };
+    const all = Promise.all(fonts.map((font) => load(font).catch((err) => console.warn(`[ludra] could not load font "${font[0]}": ${err}`))));
+    await Promise.race([all, new Promise((resolve) => setTimeout(resolve, 4000))]);
+}
+/**
+ * Loads everything a scene needs and sets up its canvases. With `postfx`, `canvas`
+ * becomes the offscreen source and a WebGL canvas takes its place in the page.
+ */
+async function prepare(canvas, scene, options) {
+    const ctx = canvas.getContext("2d");
+    if (!ctx)
+        throw new Error("Canvas 2D context is not available.");
+    const assetBase = options.assetBase ?? "";
+    const shaderPath = scene.postfx?.shader;
+    const [images, scripts, shader] = await Promise.all([
+        loadImages(scene, assetBase),
+        loadScripts(scene, options),
+        shaderPath
+            ? fetch(assetBase + shaderPath).then(async (r) => (r.ok ? r.text() : new Error(`could not load ${shaderPath} (${r.status})`)))
+            : undefined,
+        loadFonts(scene, assetBase),
+    ]);
+    const stage = { ctx, output: canvas, images, scripts, present: () => { } };
+    if (scene.postfx && shader !== undefined) {
+        try {
+            if (shader instanceof Error)
+                throw shader;
+            const fx = new PostFx(canvas.width, canvas.height, shader, scene.postfx);
+            fx.canvas.id = canvas.id;
+            fx.canvas.className = canvas.className;
+            fx.canvas.style.cssText = canvas.style.cssText;
+            canvas.replaceWith(fx.canvas);
+            stage.output = fx.canvas;
+            stage.present = (time) => fx.render(canvas, time);
+        }
+        catch (err) {
+            stage.error = `postfx: ${message(err)}`;
+            console.error("[ludra]", err);
+        }
+    }
+    return stage;
+}
+function message(err) {
+    return err instanceof Error ? err.message : String(err);
+}
 /**
  * Runs a scene in a canvas with keyboard controls, images, particles and
  * sound. The simulation uses the same fixed step as headless runs, so what
@@ -51,19 +122,15 @@ async function loadScripts(scene, options) {
  * Resolves (after images load) to a function that stops the game.
  */
 export async function startGame(canvas, scene, options = {}) {
-    const ctx = canvas.getContext("2d");
-    if (!ctx)
-        throw new Error("Canvas 2D context is not available.");
-    const assetBase = options.assetBase ?? "";
-    const [images, scripts] = await Promise.all([loadImages(scene, assetBase), loadScripts(scene, options)]);
-    const sounds = new SoundPlayer(assetBase);
+    const { ctx, images, scripts, present, error } = await prepare(canvas, scene, options);
+    const sounds = new SoundPlayer(options.assetBase ?? "");
     const view = new View(scene, images);
     let world = new World(scene, { scripts });
-    let crash;
+    let crash = error;
     const restart = () => {
         world = new World(scene, { scripts });
         view.reset();
-        crash = undefined;
+        crash = error;
     };
     const held = new Set();
     // Keys pressed since the last step. A tap shorter than one frame still reaches the simulation.
@@ -105,16 +172,25 @@ export async function startGame(canvas, scene, options = {}) {
             }
             catch (err) {
                 // A script threw: freeze the game and show why, instead of failing silently.
-                crash = err instanceof Error ? err.message : String(err);
+                crash = message(err);
                 console.error("[ludra]", err);
             }
             tapped.clear();
             view.step(world, (sound) => sounds.play(sound));
             accumulator -= FIXED_DT;
         }
-        view.draw(ctx, world, sounds.muted);
+        try {
+            view.draw(ctx, world, sounds.muted);
+        }
+        catch (err) {
+            // A draw hook threw. Same treatment as a simulation error.
+            if (!crash)
+                console.error("[ludra]", err);
+            crash ??= message(err);
+        }
         if (crash)
             drawCrash(ctx, crash);
+        present(world.time);
         raf = requestAnimationFrame(frame);
     };
     raf = requestAnimationFrame(frame);
@@ -132,10 +208,9 @@ export async function startGame(canvas, scene, options = {}) {
  * `ludra play --screenshot`.
  */
 export async function captureFrames(canvas, scene, options) {
-    const ctx = canvas.getContext("2d");
-    if (!ctx)
-        throw new Error("Canvas 2D context is not available.");
-    const [images, scripts] = await Promise.all([loadImages(scene, options.assetBase ?? ""), loadScripts(scene, options)]);
+    const { ctx, output, images, scripts, present, error } = await prepare(canvas, scene, options);
+    if (error)
+        throw new Error(error);
     const view = new View(scene, images);
     const world = new World(scene, { scripts });
     const script = InputScript.parse(options.inputs ?? "");
@@ -145,7 +220,8 @@ export async function captureFrames(canvas, scene, options) {
     for (let frame = 0;; frame++) {
         if (wanted.has(frame)) {
             view.draw(ctx, world, false);
-            captured.push({ frame, time: frame * FIXED_DT, png: canvas.toDataURL("image/png") });
+            present(world.time);
+            captured.push({ frame, time: frame * FIXED_DT, png: output.toDataURL("image/png") });
         }
         if (frame >= last)
             break;
@@ -201,6 +277,8 @@ class View {
     facing = new Map();
     emitTimers = new Map();
     frameCache = new Map();
+    /** ctx.local for each entity's draw hooks. */
+    local = new Map();
     shake = 0;
     handledEvents = 0;
     scene;
@@ -213,6 +291,7 @@ class View {
         this.particles.clear();
         this.facing.clear();
         this.emitTimers.clear();
+        this.local.clear();
         this.shake = 0;
         this.handledEvents = 0;
     }
@@ -251,7 +330,7 @@ class View {
         ctx.imageSmoothingEnabled = false;
         ctx.fillStyle = world.background;
         ctx.fillRect(0, 0, viewWidth, viewHeight);
-        const target = world.entities.find((e) => e.camera) ?? world.entities.find((e) => e.platformer);
+        const target = world.entities.find((e) => e.camera) ?? world.entities.find((e) => e.platformer || e.topdown);
         const zoom = target?.camera?.zoom ?? 1;
         const visibleWidth = viewWidth / zoom;
         const visibleHeight = viewHeight / zoom;
@@ -261,14 +340,27 @@ class View {
             cameraX += (this.particles.random() - 0.5) * 2 * this.shake;
             cameraY += (this.particles.random() - 0.5) * 2 * this.shake;
         }
+        const viewInfo = { width: viewWidth, height: viewHeight, cameraX, cameraY, zoom };
         ctx.save();
         ctx.scale(zoom, zoom);
         ctx.translate(-cameraX, -cameraY);
-        const visible = world.entities.filter((e) => e.sprite).sort((a, b) => a.sprite.layer - b.sprite.layer);
-        for (const e of visible)
-            this.drawSprite(ctx, e, world.time);
+        const layer = (e) => e.sprite?.layer ?? 0;
+        const visible = world.entities.filter((e) => e.sprite || e.script?.module.draw).sort((a, b) => layer(a) - layer(b));
+        for (const e of visible) {
+            if (e.sprite)
+                this.drawSprite(ctx, e, world.time);
+            if (e.script?.module.draw)
+                this.drawHook(ctx, world, e, "draw", viewInfo);
+        }
         this.particles.draw(ctx);
         ctx.restore();
+        if (world.hasHook("drawUI")) {
+            // The game draws its own interface.
+            for (const e of [...world.entities])
+                if (e.script?.module.drawUI)
+                    this.drawHook(ctx, world, e, "drawUI", viewInfo);
+            return;
+        }
         ctx.textAlign = "left";
         ctx.font = "600 18px system-ui, sans-serif";
         ctx.fillStyle = "#ffffff";
@@ -289,6 +381,31 @@ class View {
             ctx.fillText(`Score ${world.score} · ${winTime.toFixed(1)}s · Press R to play again`, viewWidth / 2, viewHeight / 2 + 30);
         }
     }
+    drawHook(ctx, world, e, hook, view) {
+        let local = this.local.get(e.id);
+        if (!local)
+            this.local.set(e.id, (local = {}));
+        ctx.save();
+        try {
+            world.callDrawHook(e, hook, {
+                g: ctx,
+                time: world.time,
+                local,
+                view,
+                recent: (name, seconds = 0.5) => recentEvents(world, name, seconds),
+                image: (path) => this.images.get(path),
+                burst: (x, y, particles = {}) => this.particles.burst(x, y, particles),
+                shake: (amount) => {
+                    this.shake = Math.max(this.shake, amount);
+                },
+                random: () => this.particles.random(),
+            });
+        }
+        finally {
+            // Whatever the hook changed (transform, alpha, blend mode, filter) ends with it.
+            ctx.restore();
+        }
+    }
     drawSprite(ctx, e, time) {
         const sprite = e.sprite;
         const width = sprite.width || e.body?.width || 16;
@@ -356,6 +473,21 @@ class View {
         return [0];
     }
 }
+function recentEvents(world, name, seconds) {
+    const since = world.time - seconds;
+    const result = [];
+    // Events are in time order, so walk back until they get too old.
+    for (let i = world.events.length - 1; i >= 0; i--) {
+        const event = world.events[i];
+        if (event.time < since)
+            break;
+        const eventName = event.type === "custom" ? event.name : event.type;
+        if (name !== undefined && eventName !== name)
+            continue;
+        result.push({ name: eventName, time: event.time, x: event.x, y: event.y, entity: event.entity, data: event.type === "custom" ? event.data : undefined });
+    }
+    return result.reverse();
+}
 function animationState(e) {
     const b = e.body;
     if (!b)

package/dist/components.d.ts

@@ -35,7 +35,7 @@ export interface ComponentSpec {
     /** Fields without a default are required. */
     fields: Record<string, FieldSpec>;
 }
-export declare const COMPONENT_NAMES: readonly ["transform", "body", "sprite", "platformer", "collectible", "patrol", "hazard", "goal", "emitter", "script", "camera"];
+export declare const COMPONENT_NAMES: readonly ["transform", "body", "sprite", "platformer", "topdown", "collectible", "patrol", "hazard", "goal", "emitter", "script", "camera"];
 export type ComponentName = (typeof COMPONENT_NAMES)[number];
 /** Shared by the `emitter` component and the particles of scene `effects`. Purely visual. */
 export declare const PARTICLE_FIELDS: Record<string, FieldSpec>;
@@ -55,6 +55,7 @@ export interface Body {
     height: number;
     sensor: boolean;
     gravityScale: number;
+    bounce: number;
     vx: number;
     vy: number;
 }
@@ -99,6 +100,11 @@ export interface Platformer {
     jumpBuffer: number;
     variableJump: boolean;
 }
+export interface Topdown {
+    speed: number;
+    directions: "8" | "4" | "x" | "y";
+    clampToWorld: boolean;
+}
 export interface Collectible {
     score: number;
 }

package/dist/components.js

@@ -3,6 +3,7 @@ export const COMPONENT_NAMES = [
     "body",
     "sprite",
     "platformer",
+    "topdown",
     "collectible",
     "patrol",
     "hazard",
@@ -44,6 +45,12 @@ export const COMPONENTS = {
             height: { type: "number", min: 1, description: "Collider height in pixels." },
             sensor: { type: "boolean", default: false, description: "Sensors detect overlaps but never block movement (coins, triggers)." },
             gravityScale: { type: "number", default: 1, description: "Multiplier on world gravity for dynamic bodies." },
+            bounce: {
+                type: "number",
+                min: 0,
+                default: 0,
+                description: "How much speed a dynamic body keeps when it hits a solid: 0 stops it, 1 bounces it back at full speed (balls, pinballs).",
+            },
             vx: { type: "number", default: 0, description: "Initial horizontal velocity in px/s." },
             vy: { type: "number", default: 0, description: "Initial vertical velocity in px/s." },
         },
@@ -80,8 +87,22 @@ export const COMPONENTS = {
             variableJump: { type: "boolean", default: true, description: "Releasing jump early cuts the jump short." },
         },
     },
+    topdown: {
+        description: "Player control seen from above or for vehicles: moves with the arrow keys, no gravity. directions picks 8-way, 4-way, or one axis (\"x\" for a breakout paddle or a shooter ship). Needs a dynamic body (collides with walls) or a kinematic one (passes through, use clampToWorld).",
+        requires: ["transform", "body"],
+        fields: {
+            speed: { type: "number", min: 0, default: 200, description: "Move speed in px/s." },
+            directions: {
+                type: "enum",
+                values: ["8", "4", "x", "y"],
+                default: "8",
+                description: '"8": any direction (diagonals keep the same speed). "4": up/down/left/right only. "x" or "y": one axis.',
+            },
+            clampToWorld: { type: "boolean", default: true, description: "Keep the entity inside the world bounds." },
+        },
+    },
     collectible: {
-        description: "Removed when a platformer entity touches it and adds to the score. Its body must be a sensor.",
+        description: "Removed when a player (platformer or topdown) touches it and adds to the score. Its body must be a sensor.",
         requires: ["transform", "body"],
         fields: {
             score: { type: "number", default: 1, description: "Points added when collected." },

package/dist/drawcheck.d.ts

@@ -0,0 +1,7 @@
+import { type ScriptModules } from "./script.ts";
+import type { Diagnostic, SceneDef } from "./types.ts";
+/**
+ * Runs every `draw` and `drawUI` hook against a mock canvas at a few points of
+ * an idle run, and reports hooks that throw. Used by `ludra check`.
+ */
+export declare function checkDrawHooks(scene: SceneDef, scripts: ScriptModules): Diagnostic[];

package/dist/drawcheck.js

@@ -0,0 +1,81 @@
+import { ScriptError } from "./script.js";
+import { World } from "./world.js";
+/** Simulation frames at which `checkDrawHooks` paints: the start, and after things have moved. */
+const CHECK_FRAMES = [0, 30, 120];
+/**
+ * A stand-in for CanvasRenderingContext2D that accepts every call and property,
+ * so draw hooks can run outside a browser. It catches the hook's own mistakes
+ * (typos, undefined values, changing the game while drawing), not what it looks like.
+ */
+function mockCanvas() {
+    const handler = {
+        get: (_target, key) => (key === Symbol.toPrimitive ? () => 0 : key === "then" ? undefined : any),
+        set: () => true,
+        apply: () => any,
+    };
+    const any = new Proxy(() => undefined, handler);
+    return any;
+}
+/**
+ * Runs every `draw` and `drawUI` hook against a mock canvas at a few points of
+ * an idle run, and reports hooks that throw. Used by `ludra check`.
+ */
+export function checkDrawHooks(scene, scripts) {
+    let world;
+    try {
+        world = new World(scene, { scripts });
+    }
+    catch {
+        return []; // Load problems are reported elsewhere.
+    }
+    const reported = new Set();
+    const diagnostics = [];
+    const g = mockCanvas();
+    const view = { width: world.width, height: world.height, cameraX: 0, cameraY: 0, zoom: 1 };
+    const locals = new Map();
+    for (let frame = 0; frame <= CHECK_FRAMES.at(-1); frame++) {
+        if (CHECK_FRAMES.includes(frame)) {
+            for (const e of [...world.entities]) {
+                for (const hook of ["draw", "drawUI"]) {
+                    if (!e.script?.module[hook])
+                        continue;
+                    if (!locals.has(e.id))
+                        locals.set(e.id, {});
+                    try {
+                        world.callDrawHook(e, hook, {
+                            g,
+                            time: world.time,
+                            local: locals.get(e.id),
+                            view,
+                            recent: () => [],
+                            image: () => undefined,
+                            burst: () => { },
+                            shake: () => { },
+                            random: () => 0.5,
+                        });
+                    }
+                    catch (err) {
+                        const key = `${e.script.src}:${hook}`;
+                        if (reported.has(key))
+                            continue;
+                        reported.add(key);
+                        diagnostics.push({
+                            severity: "error",
+                            code: "E_DRAW_HOOK",
+                            path: `${e.script.src} → ${hook}`,
+                            message: err instanceof ScriptError ? err.message : String(err),
+                            fix: "Draw hooks run every rendered frame in the browser. Fix the error; ctx.image() can return undefined, so check it before drawing.",
+                        });
+                    }
+                }
+            }
+        }
+        try {
+            world.step(new Set());
+        }
+        catch {
+            break; // Simulation errors surface in play and test.
+        }
+    }
+    return diagnostics;
+}

package/dist/effects.d.ts

@@ -5,6 +5,7 @@ export declare const SOUND_PRESETS: readonly ["jump", "coin", "hit", "explosion"
 export type SoundPreset = (typeof SOUND_PRESETS)[number];
 export declare const AUDIO_EXTENSIONS: readonly [".wav", ".mp3", ".ogg"];
 export declare const IMAGE_EXTENSIONS: readonly [".svg", ".png", ".jpg", ".jpeg", ".gif", ".webp"];
+export declare const FONT_EXTENSIONS: readonly [".woff2", ".woff", ".ttf", ".otf"];
 export declare const EFFECT_FIELDS: Record<string, FieldSpec>;
 export declare const EFFECTS_DESCRIPTION = "Scene-level \"effects\" map a game event (jump, land, collect, die, stomp, win) to feedback: a particle burst at the event position, a sound and a screen shake. They never affect gameplay.";
 export declare function isSoundPreset(sound: string): sound is SoundPreset;
@@ -13,7 +14,7 @@ export interface AssetReference {
     path: string;
     /** JSON path of the field that references it. */
     at: string;
-    kind: "image" | "audio" | "script";
+    kind: "image" | "audio" | "script" | "font" | "shader";
 }
 /** Every file a scene points at, so tools can check that they exist. */
 export declare function collectAssetPaths(scene: SceneDef): AssetReference[];

package/dist/effects.js

@@ -2,6 +2,7 @@
 export const SOUND_PRESETS = ["jump", "coin", "hit", "explosion", "powerup", "blip", "thud"];
 export const AUDIO_EXTENSIONS = [".wav", ".mp3", ".ogg"];
 export const IMAGE_EXTENSIONS = [".svg", ".png", ".jpg", ".jpeg", ".gif", ".webp"];
+export const FONT_EXTENSIONS = [".woff2", ".woff", ".ttf", ".otf"];
 export const EFFECT_FIELDS = {
     sound: {
         type: "string",
@@ -24,11 +25,26 @@ export function collectAssetPaths(scene) {
         const src = entity.components.script?.src;
         if (typeof src === "string" && src !== "")
             refs.push({ path: src, at: `entities[${i}].components.script.src`, kind: "script" });
+        // Images named in script params are preloaded for draw hooks (ctx.image).
+        const params = entity.components.script?.params;
+        if (params && typeof params === "object") {
+            for (const [key, value] of Object.entries(params)) {
+                if (typeof value === "string" && IMAGE_EXTENSIONS.some((ext) => value.toLowerCase().endsWith(ext))) {
+                    refs.push({ path: value, at: `entities[${i}].components.script.params.${key}`, kind: "image" });
+                }
+            }
+        }
     });
     for (const [event, effect] of Object.entries(scene.effects ?? {})) {
         const sound = effect?.sound;
         if (typeof sound === "string" && sound !== "" && !isSoundPreset(sound))
             refs.push({ path: sound, at: `effects.${event}.sound`, kind: "audio" });
     }
+    for (const [family, src] of Object.entries(scene.fonts ?? {})) {
+        if (typeof src === "string" && src !== "google")
+            refs.push({ path: src, at: `fonts.${family}`, kind: "font" });
+    }
+    if (typeof scene.postfx?.shader === "string" && scene.postfx.shader !== "")
+        refs.push({ path: scene.postfx.shader, at: "postfx.shader", kind: "shader" });
     return refs;
 }

package/dist/index.d.ts

@@ -9,3 +9,4 @@ export * from "./world.ts";
 export * from "./simulate.ts";
 export * from "./assertions.ts";
 export * from "./ascii.ts";
+export * from "./drawcheck.ts";

package/dist/index.js

@@ -9,3 +9,4 @@ export * from "./world.js";
 export * from "./simulate.js";
 export * from "./assertions.js";
 export * from "./ascii.js";
+export * from "./drawcheck.js";

package/dist/postfx.d.ts

@@ -0,0 +1,18 @@
+import type { PostFxDef } from "./types.ts";
+/**
+ * Runs a scene's GLSL fragment shader over each rendered frame. The game draws
+ * into an offscreen 2D canvas; this uploads it as a texture and draws it
+ * through the shader onto a WebGL canvas.
+ */
+export declare class PostFx {
+    readonly canvas: HTMLCanvasElement;
+    private readonly gl;
+    private readonly program;
+    private readonly texture;
+    private readonly uniforms;
+    private readonly time;
+    /** Throws with the GLSL compiler's message if the shader doesn't compile. */
+    constructor(width: number, height: number, source: string, def: PostFxDef);
+    /** Draws `source` (the frame the game just rendered) through the shader. */
+    render(source: HTMLCanvasElement, time: number): void;
+}

package/dist/postfx.js

@@ -0,0 +1,100 @@
+/** Declared by the engine for every postfx shader, so shaders only write `main`. */
+const ENGINE_HEADER = `precision mediump float;
+uniform sampler2D u_image;
+uniform vec2 u_resolution;
+uniform float u_time;
+varying vec2 v_uv;
+`;
+const VERTEX_SHADER = `attribute vec2 a_position;
+varying vec2 v_uv;
+void main() {
+  v_uv = a_position * 0.5 + 0.5;
+  gl_Position = vec4(a_position, 0.0, 1.0);
+}`;
+/**
+ * Runs a scene's GLSL fragment shader over each rendered frame. The game draws
+ * into an offscreen 2D canvas; this uploads it as a texture and draws it
+ * through the shader onto a WebGL canvas.
+ */
+export class PostFx {
+    canvas;
+    gl;
+    program;
+    texture;
+    uniforms;
+    time;
+    /** Throws with the GLSL compiler's message if the shader doesn't compile. */
+    constructor(width, height, source, def) {
+        this.canvas = document.createElement("canvas");
+        this.canvas.width = width;
+        this.canvas.height = height;
+        // preserveDrawingBuffer keeps the frame readable for screenshots.
+        const gl = this.canvas.getContext("webgl", { preserveDrawingBuffer: true, premultipliedAlpha: false });
+        if (!gl)
+            throw new Error("postfx needs WebGL, which this browser doesn't provide.");
+        this.gl = gl;
+        const custom = Object.keys(def.uniforms ?? {});
+        // #line 1 makes compiler errors point at lines of the shader file itself.
+        const header = ENGINE_HEADER + custom.map((name) => `uniform float ${name};\n`).join("") + "#line 1\n";
+        this.program = link(gl, VERTEX_SHADER, header + stripDeclarations(source, ["u_image", "u_resolution", "u_time", "v_uv", ...custom]), def.shader);
+        gl.useProgram(this.program);
+        const buffer = gl.createBuffer();
+        gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+        gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 1, -1, -1, 1, -1, 1, 1, -1, 1, 1]), gl.STATIC_DRAW);
+        const position = gl.getAttribLocation(this.program, "a_position");
+        gl.enableVertexAttribArray(position);
+        gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 0, 0);
+        this.texture = gl.createTexture();
+        gl.bindTexture(gl.TEXTURE_2D, this.texture);
+        for (const [key, value] of [
+            [gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE],
+            [gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE],
+            [gl.TEXTURE_MIN_FILTER, gl.LINEAR],
+            [gl.TEXTURE_MAG_FILTER, gl.LINEAR],
+        ]) {
+            gl.texParameteri(gl.TEXTURE_2D, key, value);
+        }
+        gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+        gl.uniform1i(gl.getUniformLocation(this.program, "u_image"), 0);
+        gl.uniform2f(gl.getUniformLocation(this.program, "u_resolution"), width, height);
+        this.time = gl.getUniformLocation(this.program, "u_time");
+        this.uniforms = custom.map((name) => ({ location: gl.getUniformLocation(this.program, name), value: def.uniforms[name] }));
+    }
+    /** Draws `source` (the frame the game just rendered) through the shader. */
+    render(source, time) {
+        const gl = this.gl;
+        gl.viewport(0, 0, this.canvas.width, this.canvas.height);
+        gl.bindTexture(gl.TEXTURE_2D, this.texture);
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, source);
+        gl.uniform1f(this.time, time);
+        for (const u of this.uniforms)
+            gl.uniform1f(u.location, u.value);
+        gl.drawArrays(gl.TRIANGLES, 0, 6);
+    }
+}
+/** Drops the shader's own declarations of names the engine already declares, so either style compiles. */
+function stripDeclarations(source, names) {
+    return source
+        .split("\n")
+        .map((line) => (/^\s*(uniform|varying)\b/.test(line) && names.some((name) => new RegExp(`\\b${name}\\b`).test(line)) ? "" : line))
+        .join("\n");
+}
+function link(gl, vertex, fragment, path) {
+    const program = gl.createProgram();
+    gl.attachShader(program, compile(gl, gl.VERTEX_SHADER, vertex, "the engine's vertex shader"));
+    gl.attachShader(program, compile(gl, gl.FRAGMENT_SHADER, fragment, path));
+    gl.linkProgram(program);
+    if (!gl.getProgramParameter(program, gl.LINK_STATUS))
+        throw new Error(`${path} failed to link: ${gl.getProgramInfoLog(program)}`);
+    return program;
+}
+function compile(gl, type, source, path) {
+    const shader = gl.createShader(type);
+    gl.shaderSource(shader, source);
+    gl.compileShader(shader);
+    if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+        const log = String(gl.getShaderInfoLog(shader)).trim();
+        throw new Error(`${path} failed to compile: ${log}`);
+    }
+    return shader;
+}