yuuna-engine 0.2.1 → 0.4.0

package/lib/index.cjs

@@ -107,6 +107,19 @@ const keyboardKeys = [
 
 let resetCanvas = null;
 let latestRunId = 0;
+// Shared between drawing TEXT renderables and hit-testing them for
+// clicks/hovers, so the clickable area always matches what's on screen.
+const DEFAULT_TEXT_FONT_SIZE = 30;
+const textFont = (fontSize) => `${fontSize}px Arial`;
+// Renderables with the same layer keep render()'s order — Array#sort is
+// stable — so `layer` only needs to move something relative to the rest,
+// not say anything about where exactly it lands among equal layers.
+const sortByLayer = (renderables) => [...renderables].sort((a, b) => (a.layer ?? 0) - (b.layer ?? 0));
+// A LINE has no `position`, just two endpoints — `from` anchors its scale
+// the same way `position` anchors every other renderable's.
+const anchorOf = (renderable) => renderable.type === "LINE" ? renderable.from : renderable.position;
+// No RunEngineProps.camera set is the same as one that doesn't pan or zoom.
+const DEFAULT_CAMERA = { x: 0, y: 0, zoom: 1 };
 const runEngine = async (props) => {
     const runId = ++latestRunId;
     resetCanvas?.();
@@ -134,6 +147,14 @@ const runEngine = async (props) => {
     // leaking to the rest of the page (e.g. arrow keys scrolling the window).
     canvas.tabIndex = 0;
     let state = props.initialState;
+    const events = [];
+    // Lets a caller report something that happened outside the render loop
+    // (e.g. a fetch().then() callback) back into it — the event is queued
+    // here and delivered to nextState as a CustomGameEvent on the next tick,
+    // the same as any built-in event.
+    const sendEvent = (event) => {
+        events.push({ tag: "CUSTOM", event });
+    };
     const resources = props.resources ?? {};
     const resourceById = await iterateRecordAsync(resources, async ({ value }) => new Promise((resolve) => {
         const image = new Image();
@@ -146,28 +167,260 @@ const runEngine = async (props) => {
                     height: value.size.height / value.slices.vertical,
                 },
                 slices: value.slices,
+                animations: value.animations ?? {},
             });
         };
     }));
+    const loadAudio = (src) => new Promise((resolve) => {
+        const audio = new Audio(src);
+        audio.oncanplaythrough = function () {
+            resolve(audio);
+        };
+    });
+    const sounds = props.sounds ?? {};
+    const audioById = await iterateRecordAsync(sounds, ({ value }) => loadAudio(value.src));
+    // Cloning the loaded element per play (instead of reusing it directly)
+    // lets the same sound overlap itself — e.g. rapid clicks each get their
+    // own playback instead of restarting/cutting off the previous one.
+    const playSound = (id) => {
+        const audio = audioById[id];
+        if (audio === undefined) {
+            return;
+        }
+        const instance = audio.cloneNode();
+        instance.play();
+    };
+    const music = props.music ?? {};
+    const musicById = await iterateRecordAsync(music, ({ value }) => loadAudio(value.src));
+    // Registered once per track at load time — fires only for a track
+    // whose `loop` is false, since a looping <audio> never reaches "ended"
+    // (the browser restarts it before the event would fire).
+    for (const id of getKeys(musicById)) {
+        musicById[id].addEventListener("ended", () => {
+            events.push({ tag: "MUSIC_END", id });
+        });
+    }
+    // Unlike sounds, music reuses the same element instead of cloning it —
+    // there's only ever one track playing, and reusing it is what lets
+    // pauseMusic()/playMusic() resume from where playback left off instead
+    // of starting over.
+    let currentMusic = null;
+    // Volume is a property of each HTMLAudioElement, not global — tracked
+    // separately here and (re)applied on every playMusic() so switching
+    // tracks keeps the volume the game last set instead of resetting to
+    // each element's default of 1.
+    let musicVolume = 1;
+    const playMusic = (id) => {
+        const audio = musicById[id];
+        if (audio === undefined) {
+            return;
+        }
+        if (currentMusic !== null && currentMusic !== audio) {
+            currentMusic.pause();
+        }
+        audio.loop = music[id]?.loop ?? true;
+        audio.volume = musicVolume;
+        audio.play();
+        currentMusic = audio;
+    };
+    const pauseMusic = () => {
+        currentMusic?.pause();
+    };
+    const resumeMusic = () => {
+        currentMusic?.play();
+    };
+    const setMusicVolume = (volume) => {
+        musicVolume = Math.min(1, Math.max(0, volume));
+        if (currentMusic !== null) {
+            currentMusic.volume = musicVolume;
+        }
+    };
     // A newer runEngine() call started while this one was still loading
     // resources (e.g. a spritesheet) — abandon this run instead of setting
     // up a second, orphaned render loop alongside the newer one.
     if (runId !== latestRunId) {
-        return;
+        return { sendEvent };
     }
     context.imageSmoothingEnabled = false;
-    function getFocusedElement(position, r) {
-        const isNonInteractable = r.type === "TEXT" ||
-            r.type === "LINE" ||
+    // An offscreen 1x1 canvas used only to resolve a CSS color string (a
+    // name, hex, rgb(), hsl(), ...) into concrete RGBA bytes: paint it that
+    // color and read the pixel back. Lets modulateColor() below multiply
+    // any two colors together without hand-rolling a CSS color parser.
+    const colorSwatchContext = window.document.createElement("canvas").getContext("2d");
+    // Color strings are almost always the same literal reused every frame,
+    // and getImageData is one of the slower canvas operations — cached so a
+    // given color only actually gets resolved once.
+    const resolvedColorByString = {};
+    const resolveColor = (color) => {
+        const cached = resolvedColorByString[color];
+        if (cached !== undefined) {
+            return cached;
+        }
+        if (colorSwatchContext === null) {
+            return [255, 255, 255, 255];
+        }
+        colorSwatchContext.clearRect(0, 0, 1, 1);
+        colorSwatchContext.fillStyle = color;
+        colorSwatchContext.fillRect(0, 0, 1, 1);
+        const [r, g, b, a] = colorSwatchContext.getImageData(0, 0, 1, 1).data;
+        const resolved = [r, g, b, a];
+        resolvedColorByString[color] = resolved;
+        return resolved;
+    };
+    // Multiplies two colors channel-by-channel, the same way Godot's
+    // `modulate` works — e.g. modulating "white" by "#808080" halves
+    // brightness, by "#ff0000" keeps only the red channel.
+    const modulateColor = (color, modulate) => {
+        const [r1, g1, b1, a1] = resolveColor(color);
+        const [r2, g2, b2, a2] = resolveColor(modulate);
+        const mixChannel = (c1, c2) => (c1 * c2) / 255;
+        return `rgba(${mixChannel(r1, r2)}, ${mixChannel(g1, g2)}, ${mixChannel(b1, b2)}, ${mixChannel(a1, a2) / 255})`;
+    };
+    // Combines a parent's already-composed modulate with a child's own —
+    // undefined means "no tint from this side", so it just passes the
+    // other one through instead of multiplying against an implicit white.
+    const composeModulate = (parent, own) => {
+        if (parent === undefined)
+            return own;
+        if (own === undefined)
+            return parent;
+        return modulateColor(parent, own);
+    };
+    const IDENTITY_TRANSFORM = {
+        anchor: { x: 0, y: 0 },
+        scale: { x: 1, y: 1 },
+        modulate: undefined,
+        layer: 0,
+    };
+    // A child's own position is authored relative to its parent, in the
+    // parent's local (unscaled) units — the same way Godot composes
+    // Node2D transforms — so it needs both the parent's scale and its
+    // accumulated offset applied to land in absolute canvas coordinates.
+    const transformPoint = (parent, localPoint) => ({
+        x: parent.anchor.x + localPoint.x * parent.scale.x,
+        y: parent.anchor.y + localPoint.y * parent.scale.y,
+    });
+    // Each id's accumulated playback time for its current animation, plus
+    // when that was last updated — keyed by id, since an ANIMATED_SPRITE
+    // has no state of its own (render() returns brand-new objects every
+    // frame). elapsedMs only advances while not paused (see
+    // resolveAnimatedSprite), so pausing genuinely stops the clock rather
+    // than just freezing which frame gets drawn — unpausing resumes from
+    // the same frame instead of skipping ahead by however long it was
+    // paused. Accumulating incrementally like this (instead of computing
+    // elapsed from an absolute start time every call) is also what makes
+    // pausing possible at all, and as a side effect means a `timeScale`
+    // that changes over an animation's lifetime scales each tick as it
+    // happens rather than retroactively rescaling the whole duration so
+    // far. Pruned each renderState() call (see seenAnimationIds there) to
+    // only ids actually present that frame, so a game that spawns entities
+    // with ever-incrementing ids doesn't leak one entry per entity ever
+    // spawned.
+    const animationStateById = new Map();
+    const seenAnimationIds = new Set();
+    // Resolves an ANIMATED_SPRITE down to a plain SPRITE with `frame`
+    // computed from how long its current animation has been playing —
+    // everything past this point (flattenRenderable's position/scale/
+    // modulate/layer composition, hit-testing, drawing) treats the result
+    // exactly like any other SPRITE, with no idea ANIMATED_SPRITE exists.
+    const resolveAnimatedSprite = (renderable) => {
+        seenAnimationIds.add(renderable.id);
+        const resource = resourceById[renderable.resourceId];
+        const animation = resource.animations[renderable.animation];
+        const timeScale = renderable.timeScale ?? 1;
+        const paused = renderable.paused ?? false;
+        const now = Date.now();
+        const tracked = animationStateById.get(renderable.id);
+        // A new id, or the same id switching to a different animation, both
+        // start that animation over from frame 0 rather than picking up
+        // wherever the previous timer happened to be.
+        const previous = tracked !== undefined && tracked.animation === renderable.animation
+            ? tracked
+            : { animation: renderable.animation, elapsedMs: 0, lastUpdateTime: now };
+        const elapsedMs = paused
+            ? previous.elapsedMs
+            : previous.elapsedMs + Math.max(0, now - previous.lastUpdateTime) * timeScale;
+        // lastUpdateTime always moves forward, paused or not — otherwise the
+        // first tick after unpausing would see a gap stretching back to
+        // whenever it was paused, and (dis)count that whole gap as elapsed
+        // playback time in one jump.
+        animationStateById.set(renderable.id, { animation: renderable.animation, elapsedMs, lastUpdateTime: now });
+        const frameCursor = Math.floor(elapsedMs / animation.frameDuration);
+        const frameIndex = animation.loop
+            ? frameCursor % animation.frames.length
+            : Math.min(frameCursor, animation.frames.length - 1);
+        return { ...renderable, type: "SPRITE", frame: animation.frames[frameIndex] };
+    };
+    // Turns a render() tree into the flat list the rest of the engine
+    // already knows how to sort/draw/hit-test — each renderable's own
+    // position/from/to/scale/modulate/layer replaced by the *effective*
+    // (absolute, fully composed with its ancestors') values, and its
+    // children peeled off into their own entries in the returned list
+    // instead of staying nested. Nothing past this point needs to know
+    // parent/child relationships existed at all.
+    const flattenRenderable = (renderable, parent) => {
+        const resolved = renderable.type === "ANIMATED_SPRITE" ? resolveAnimatedSprite(renderable) : renderable;
+        const localScale = resolved.scale ?? { x: 1, y: 1 };
+        const scale = { x: parent.scale.x * localScale.x, y: parent.scale.y * localScale.y };
+        const modulate = composeModulate(parent.modulate, resolved.modulate);
+        const layer = parent.layer + (resolved.layer ?? 0);
+        const effective = resolved.type === "LINE"
+            ? {
+                ...resolved,
+                from: transformPoint(parent, resolved.from),
+                to: transformPoint(parent, resolved.to),
+                scale,
+                modulate,
+                layer,
+                children: undefined,
+            }
+            : {
+                ...resolved,
+                position: transformPoint(parent, resolved.position),
+                scale,
+                modulate,
+                layer,
+                children: undefined,
+            };
+        const childTransform = { anchor: anchorOf(effective), scale, modulate, layer };
+        const children = (resolved.children ?? []).flatMap((child) => flattenRenderable(child, childTransform));
+        return [effective, ...children];
+    };
+    // parent defaults to the identity transform (used for screen-space
+    // renderables, and by everything before the camera existed) — callers
+    // that need a different root, like renderState's camera below, pass
+    // their own.
+    const flattenRenderables = (renderables, parent = IDENTITY_TRANSFORM) => renderables.flatMap((renderable) => flattenRenderable(renderable, parent));
+    const getFocusedElement = (position, r) => {
+        const isNonInteractable = r.type === "LINE" ||
+            r.type === "GROUP" ||
+            // Unreachable — flattenRenderable always resolves ANIMATED_SPRITE
+            // to a plain SPRITE before hit-testing ever sees one. Listed here
+            // (rather than left for exhaust() to catch) so getFocusedElement
+            // itself type-checks as exhaustive.
+            r.type === "ANIMATED_SPRITE" ||
             ((r.isHoverable === undefined || !r.isHoverable) &&
                 (r.isClickable === undefined || !r.isClickable));
         if (isNonInteractable) {
             return false;
         }
+        // Scale is applied around the renderable's anchor as a draw-time canvas
+        // transform (see applyScale below) rather than by inflating its
+        // size — so hit-testing does the inverse instead: bring the mouse
+        // position into the renderable's own unscaled coordinate space, then
+        // run the exact same math below as if scale were untouched. For
+        // CIRCLE this also happens to be the standard "is this point inside
+        // this ellipse" test, for free, once it's drawing as one.
+        const { x: scaleX, y: scaleY } = r.scale ?? { x: 1, y: 1 };
+        const anchor = anchorOf(r);
+        const localPosition = {
+            x: anchor.x + (position.x - anchor.x) / scaleX,
+            y: anchor.y + (position.y - anchor.y) / scaleY,
+        };
         if (r.type === "CIRCLE") {
             const delta = {
-                x: Math.abs(position.x - r.position.x),
-                y: Math.abs(position.y - r.position.y),
+                x: Math.abs(localPosition.x - r.position.x),
+                y: Math.abs(localPosition.y - r.position.y),
             };
             const distance = Math.sqrt(delta.x * delta.x + delta.y * delta.y);
             const isHovered = distance < r.radius;
@@ -179,26 +432,86 @@ const runEngine = async (props) => {
                 x: r.position.x + r.size.width,
                 y: r.position.y + r.size.height,
             };
-            const isInsideX = position.x > topLeft.x && position.x < bottomRight.x;
-            const isInsideY = position.y > topLeft.y && position.y < bottomRight.y;
+            const isInsideX = localPosition.x > topLeft.x && localPosition.x < bottomRight.x;
+            const isInsideY = localPosition.y > topLeft.y && localPosition.y < bottomRight.y;
             const isHovered = isInsideX && isInsideY;
             return isHovered;
         }
         if (r.type === "SPRITE") {
             const topLeft = { x: r.position.x, y: r.position.y };
             const resource = resourceById[r.resourceId];
-            const { scale = 1 } = r;
             const bottomRight = {
-                x: r.position.x + resource.size.width * scale,
-                y: r.position.y + resource.size.height * scale,
+                x: r.position.x + resource.size.width,
+                y: r.position.y + resource.size.height,
             };
-            const isInsideX = position.x > topLeft.x && position.x < bottomRight.x;
-            const isInsideY = position.y > topLeft.y && position.y < bottomRight.y;
+            const isInsideX = localPosition.x > topLeft.x && localPosition.x < bottomRight.x;
+            const isInsideY = localPosition.y > topLeft.y && localPosition.y < bottomRight.y;
             const isHovered = isInsideX && isInsideY;
             return isHovered;
         }
+        if (r.type === "TEXT") {
+            // Text has no explicit size, so its clickable area is derived from
+            // measuring it the same way it's drawn (see the TEXT branch in the
+            // render loop below) — anchored the same way its `align` positions
+            // it relative to `position`.
+            const fontSize = r.fontSize ?? DEFAULT_TEXT_FONT_SIZE;
+            context.font = textFont(fontSize);
+            const width = context.measureText(r.text).width;
+            const height = fontSize;
+            const alignX = r.align?.x ?? "left";
+            const left = alignX === "center" ? r.position.x - width / 2 : alignX === "right" ? r.position.x - width : r.position.x;
+            const alignY = r.align?.y ?? "top";
+            const top = alignY === "middle" ? r.position.y - height / 2 : alignY === "bottom" ? r.position.y - height : r.position.y;
+            const isInsideX = localPosition.x > left && localPosition.x < left + width;
+            const isInsideY = localPosition.y > top && localPosition.y < top + height;
+            return isInsideX && isInsideY;
+        }
         exhaust(r);
-    }
+    };
+    // The camera is just another ancestor transform, exactly like a
+    // renderable's own parent — { x, y } is the world position mapped to
+    // canvas (0, 0), so it's the anchor transformPoint already expects:
+    // screen = (world - camera.position) * zoom.
+    const cameraTransformOf = (camera) => ({
+        anchor: { x: -camera.x * camera.zoom, y: -camera.y * camera.zoom },
+        scale: { x: camera.zoom, y: camera.zoom },
+        modulate: undefined,
+        layer: 0,
+    });
+    // The inverse of cameraTransformOf, for turning a raw canvas position
+    // (mouse) into a world position (worldMouse) — see ClickEvent etc.
+    const toWorldPosition = (position, camera) => ({
+        x: camera.x + position.x / camera.zoom,
+        y: camera.y + position.y / camera.zoom,
+    });
+    // Every call site needs renderables flattened and in draw order — the
+    // mousemove/click handlers below to find whichever's topmost under the
+    // mouse, the draw loop to actually draw them that way — so both are
+    // applied once here instead of separately wherever props.render() gets
+    // called. Screen-space renderables skip the camera entirely (flattened
+    // from the identity transform, same as before there was a camera);
+    // everything else is flattened as if the camera were its shared parent.
+    const renderState = (state) => {
+        const result = props.render(state);
+        const camera = props.camera?.(state) ?? DEFAULT_CAMERA;
+        const cameraTransform = cameraTransformOf(camera);
+        const worldRenderables = result.renderables.filter((r) => !r.screenSpace);
+        const screenRenderables = result.renderables.filter((r) => r.screenSpace);
+        seenAnimationIds.clear();
+        const renderables = sortByLayer([
+            ...flattenRenderables(worldRenderables, cameraTransform),
+            ...flattenRenderables(screenRenderables),
+        ]);
+        // Anything not seen this pass is no longer being rendered (e.g. the
+        // entity it belonged to died) — drop its tracked start time instead
+        // of keeping it forever.
+        for (const id of animationStateById.keys()) {
+            if (!seenAnimationIds.has(id)) {
+                animationStateById.delete(id);
+            }
+        }
+        return { cursor: result.cursor, renderables, camera };
+    };
     // ev.offsetX/offsetY are in CSS-rendered pixels, which differ from the
     // canvas's drawing-buffer resolution whenever it's displayed at a
     // different size (e.g. scaled down to fit its container). Renderable
@@ -216,15 +529,14 @@ const runEngine = async (props) => {
     const nextStateFns = Array.isArray(props.nextState) ? props.nextState : [props.nextState];
     let lastFrame = Date.now();
     let hoveredId = null;
-    const events = [];
     canvas.addEventListener("click", (ev) => {
         const mouse = getCanvasPosition(ev);
         if (hoveredId === null)
             return;
-        const { renderables } = props.render(state);
+        const { renderables, camera } = renderState(state);
         const hovered = renderables.find((e) => e.id === hoveredId);
         if (hovered !== undefined && hovered.isClickable) {
-            events.push({ tag: "CLICK", id: hovered.id, mouse });
+            events.push({ tag: "CLICK", id: hovered.id, mouse, worldMouse: toWorldPosition(mouse, camera) });
         }
     });
     const initialState = {
@@ -255,17 +567,18 @@ const runEngine = async (props) => {
     });
     canvas.addEventListener("mousemove", (ev) => {
         const mouse = getCanvasPosition(ev);
-        const { renderables } = props.render(state);
+        const { renderables, camera } = renderState(state);
+        const worldMouse = toWorldPosition(mouse, camera);
         const hovered = [...renderables]
             .reverse()
             .find((r) => getFocusedElement(mouse, r));
         if (hovered !== undefined && hovered.isHoverable) {
-            events.push({ tag: "HOVER_IN", id: hovered.id, mouse });
+            events.push({ tag: "HOVER_IN", id: hovered.id, mouse, worldMouse });
         }
         if (hoveredId !== null) {
             const lastHovered = renderables.find((r) => r.id === hoveredId);
             if (lastHovered !== undefined && lastHovered.id !== hovered?.id) {
-                events.push({ tag: "HOVER_OUT", id: lastHovered.id, mouse });
+                events.push({ tag: "HOVER_OUT", id: lastHovered.id, mouse, worldMouse });
             }
         }
         hoveredId = hovered === undefined ? null : hovered.id ?? null;
@@ -275,13 +588,62 @@ const runEngine = async (props) => {
         if (hoveredId === null) {
             return;
         }
-        const { renderables } = props.render(state);
+        const { renderables, camera } = renderState(state);
         const hovered = renderables.find((r) => r.id === hoveredId);
         if (hovered !== undefined && hovered.trackMouseMovement) {
-            events.push({ tag: "MOUSE_MOVE", mouse, id: hovered.id });
+            events.push({ tag: "MOUSE_MOVE", mouse, worldMouse: toWorldPosition(mouse, camera), id: hovered.id });
         }
     });
     context.imageSmoothingEnabled = false;
+    // Scale is a canvas transform around the renderable's anchor, applied
+    // before its type-specific drawing runs below — everything drawn under
+    // it (fills, strokes, images, even font size) comes out scaled without
+    // each renderable type needing its own size math, and a CIRCLE drawn
+    // under a non-uniform scale comes out an ellipse for free.
+    const applyScale = (renderable) => {
+        const { x: scaleX, y: scaleY } = renderable.scale ?? { x: 1, y: 1 };
+        if (scaleX === 1 && scaleY === 1) {
+            return;
+        }
+        const anchor = anchorOf(renderable);
+        context.translate(anchor.x, anchor.y);
+        context.scale(scaleX, scaleY);
+        context.translate(-anchor.x, -anchor.y);
+    };
+    // Reused across every tinted SPRITE draw this run, instead of allocating
+    // a fresh offscreen canvas per sprite per frame — see tintedSpriteFrame.
+    const tintBuffer = window.document.createElement("canvas");
+    const tintBufferContext = tintBuffer.getContext("2d");
+    // Renders one frame of a spritesheet, tinted by `modulate`, onto the
+    // shared offscreen buffer and returns it ready to draw — multiply-
+    // blending a filled rectangle over the frame would also color its
+    // fully-transparent pixels, so this clips that back down to the
+    // frame's own shape afterward with `destination-in`.
+    //
+    // This has to happen on an *isolated* buffer rather than directly on
+    // the main canvas: destination-in isn't scoped to this draw call's own
+    // area, it's a whole-buffer operation that erases anything the new
+    // draw doesn't cover. Doing it on the main canvas would erase whatever
+    // was already drawn underneath the sprite's transparent pixels (e.g.
+    // terrain showing through the gaps in a character) instead of leaving
+    // it alone. The buffer starts out empty, so there's nothing under it
+    // to lose — only the finished, correctly-masked result ever reaches
+    // the main canvas, via a normal (source-over) drawImage.
+    const tintedSpriteFrame = (image, source, modulate) => {
+        if (tintBufferContext === null) {
+            return image;
+        }
+        tintBuffer.width = source.width;
+        tintBuffer.height = source.height;
+        tintBufferContext.drawImage(image, source.x, source.y, source.width, source.height, 0, 0, source.width, source.height);
+        tintBufferContext.globalCompositeOperation = "multiply";
+        tintBufferContext.fillStyle = modulate;
+        tintBufferContext.fillRect(0, 0, source.width, source.height);
+        tintBufferContext.globalCompositeOperation = "destination-in";
+        tintBufferContext.drawImage(image, source.x, source.y, source.width, source.height, 0, 0, source.width, source.height);
+        tintBufferContext.globalCompositeOperation = "source-over";
+        return tintBuffer;
+    };
     const intervalId = setInterval(() => {
         const now = Date.now();
         const delta = now - lastFrame;
@@ -296,7 +658,16 @@ const runEngine = async (props) => {
                 };
             });
             for (const nextState of nextStateFns) {
-                const result = nextState({ state, event, keyboard });
+                const result = nextState({
+                    state,
+                    event,
+                    keyboard,
+                    playSound,
+                    playMusic,
+                    pauseMusic,
+                    resumeMusic,
+                    setMusicVolume,
+                });
                 // STOP stops the rest of the list from running for this event,
                 // instead of every later mechanic needing to repeat the same
                 // guard. undefined just means this mechanic made no change, so
@@ -311,63 +682,102 @@ const runEngine = async (props) => {
         }
         events.splice(0, events.length);
         context.clearRect(0, 0, canvas.width, canvas.height);
-        const { cursor, renderables } = props.render(state);
+        const { cursor, renderables } = renderState(state);
         canvas.style.cursor = cursor ?? "default";
         for (const renderable of renderables) {
+            context.save();
+            applyScale(renderable);
             if (renderable.type === "RECTANGLE") {
-                context.fillStyle = renderable.color;
+                context.fillStyle =
+                    renderable.modulate === undefined ? renderable.color : modulateColor(renderable.color, renderable.modulate);
                 context.fillRect(renderable.position.x, renderable.position.y, renderable.size.width, renderable.size.height);
+                context.restore();
                 continue;
             }
             if (renderable.type === "CIRCLE") {
-                context.fillStyle = renderable.color;
+                context.fillStyle =
+                    renderable.modulate === undefined ? renderable.color : modulateColor(renderable.color, renderable.modulate);
                 context.beginPath();
                 context.arc(renderable.position.x, renderable.position.y, renderable.radius, 0, 2 * Math.PI);
                 context.fill();
+                context.restore();
                 continue;
             }
             if (renderable.type === "TEXT") {
-                const { color, position: { x, y }, text, align, } = renderable;
-                context.fillStyle = color;
-                context.font = "30px Arial";
+                const { color, position: { x, y }, text, align, fontSize, modulate, } = renderable;
+                context.fillStyle = modulate === undefined ? color : modulateColor(color, modulate);
+                context.font = textFont(fontSize ?? DEFAULT_TEXT_FONT_SIZE);
                 context.textAlign = align?.x ?? "left";
                 context.textBaseline = align?.y ?? "top";
                 context.fillText(text, x, y);
+                context.restore();
                 continue;
             }
             if (renderable.type === "SPRITE") {
-                const { scale = 1, opacity = 1, flipX = false } = renderable;
+                const { opacity = 1, flipX = false, modulate } = renderable;
                 const resource = resourceById[renderable.resourceId];
                 const frame = {
                     x: renderable.frame % resource.slices.horizontal,
                     y: Math.floor(renderable.frame / resource.slices.horizontal) %
                         resource.slices.vertical,
                 };
-                const destWidth = resource.size.width * scale;
-                const destHeight = resource.size.height * scale;
+                const source = {
+                    x: frame.x * resource.size.width,
+                    y: frame.y * resource.size.height,
+                    width: resource.size.width,
+                    height: resource.size.height,
+                };
+                const destWidth = resource.size.width;
+                const destHeight = resource.size.height;
+                // Tinting swaps in an already-tinted offscreen copy of this frame
+                // as the image to draw — everything past this point (flipX,
+                // positioning) treats it exactly like the untinted spritesheet,
+                // just drawn starting at (0, 0) instead of cropped from a sheet.
+                const image = modulate === undefined ? resource.image : tintedSpriteFrame(resource.image, source, modulate);
+                const imageSource = modulate === undefined ? source : { x: 0, y: 0, width: source.width, height: source.height };
                 context.globalAlpha = opacity;
+                const drawSprite = (destX, destY) => {
+                    context.drawImage(image, imageSource.x, imageSource.y, imageSource.width, imageSource.height, destX, destY, destWidth, destHeight);
+                };
                 if (flipX) {
                     context.save();
                     context.translate(renderable.position.x + destWidth, renderable.position.y);
                     context.scale(-1, 1);
-                    context.drawImage(resource.image, frame.x * resource.size.width, frame.y * resource.size.height, resource.size.width, resource.size.height, 0, 0, destWidth, destHeight);
+                    drawSprite(0, 0);
                     context.restore();
                 }
                 else {
-                    context.drawImage(resource.image, frame.x * resource.size.width, frame.y * resource.size.height, resource.size.width, resource.size.height, renderable.position.x, renderable.position.y, destWidth, destHeight);
+                    drawSprite(renderable.position.x, renderable.position.y);
                 }
                 context.globalAlpha = 1;
+                context.restore();
                 continue;
             }
             if (renderable.type === "LINE") {
-                context.strokeStyle = renderable.color;
+                context.strokeStyle =
+                    renderable.modulate === undefined ? renderable.color : modulateColor(renderable.color, renderable.modulate);
                 context.lineWidth = renderable.width ?? 2;
                 context.beginPath();
                 context.moveTo(renderable.from.x, renderable.from.y);
                 context.lineTo(renderable.to.x, renderable.to.y);
                 context.stroke();
+                context.restore();
                 continue;
             }
+            if (renderable.type === "GROUP") {
+                // Draws nothing itself — it only exists to give its children
+                // (already peeled off into their own entries by flattenRenderables)
+                // something to be positioned/scaled/tinted relative to.
+                context.restore();
+                continue;
+            }
+            if (renderable.type === "ANIMATED_SPRITE") {
+                // Unreachable — flattenRenderable always resolves ANIMATED_SPRITE
+                // to a plain SPRITE before it gets here. A real error (not a
+                // silent skip) if it's somehow still one, since that would mean
+                // an actual engine bug rather than anything a game author did.
+                throw new Error("ANIMATED_SPRITE reached the draw loop unresolved — this is an engine bug");
+            }
             exhaust(renderable);
         }
         lastFrame = now;
@@ -376,6 +786,7 @@ const runEngine = async (props) => {
     resetCanvas = () => {
         clearInterval(intervalId);
     };
+    return { sendEvent };
 };
 
 exports.STOP = STOP;

package/lib/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/lib/index.d.ts

@@ -1,4 +1,4 @@
 import { runEngine } from "./engine/runEngine";
 import { STOP } from "./engine/types";
 export { runEngine, STOP };
-export type { NextStateFunction, NextStateProps, Renderable, GameEvent } from "./engine/types";
+export type { NextStateFunction, NextStateProps, Renderable, GameEvent, CustomGameEvent, } from "./engine/types";