yuuna-engine 0.7.0 → 0.9.0

package/README.md

@@ -9,8 +9,10 @@
 A lightweight, state-machine-based TypeScript game engine — drop it into a
 page and it's running, no editor or build step required. You describe your
 game as a `state`, a `render(state)` function, and a
-`nextState({ state, event, keyboard })` function — Yuuna owns the render
-loop, input handling, and canvas drawing.
+`nextState({ state, event, keyboard })` function — the reducer pattern
+(`(state, event) => nextState`, same shape as a Redux reducer or
+`useReducer`) — and Yuuna owns the render loop, input handling, and canvas
+drawing.
 
 ## Install
 
@@ -90,6 +92,10 @@ runEngine<GameState>({
   canvas config, and mechanics pipelines** all follow the same idea:
   small, focused props and functions `runEngine`/`nextState` take, that
   compose with everything above instead of replacing it.
+- **Mechanics pipelines** — `nextState` can be an array of small reducers
+  instead of one big function; each runs in order per event, the way
+  Redux middleware chains do, and any of them can return `STOP` to end
+  the pipeline early for that event.
 
 This README stays intentionally thin — the full concept-by-concept
 reference, with every option and example, lives on the
@@ -148,12 +154,23 @@ run without them — just with placeholder art in place of the real
 thing. Drop the real files in locally (or restore them from wherever
 you got this repo from) to see them for real.
 
+Only MIT- or CC0-licensed assets are used, so nothing here needs
+attribution to run or redistribute — the credits below are given by
+choice, not requirement.
+
 Currently used:
 
 - **[Free Pixel Food!](https://henrysoftware.itch.io/pixel-food)** by
   [Henry Software](https://henrysoftware.itch.io/) — the food icons in
-  the Food Clicker and Sprites examples. CC0; credited here by choice,
-  not requirement.
+  the Food Clicker and Sprites examples. CC0.
+- **[Sunny Land Pixel Game Art](https://ansimuz.itch.io/sunny-land-pixel-game-art)**
+  by [ansimuz](https://ansimuz.itch.io/) — the fox (idle/walk/jump), the
+  ground/platform tile, and the parallax sky background in the
+  Platformer example. CC0.
+- **[Mini Pixel Pack 3](https://grafxkid.itch.io/mini-pixel-pack-3)** by
+  [GrafxKid](https://grafxkid.itch.io/) — the ship, the charged-beam
+  bullet, Alan (the enemy), and the parallax starfield in the Shoot Em
+  Up example. CC0.
 
 ## License
 

package/lib/engine/types.d.ts

@@ -204,6 +204,22 @@ export type NextStateProps<State, Custom = never> = {
 };
 export declare const STOP: "Yuuna.STOP";
 export type NextStateFunction<State, Custom = never> = (props: NextStateProps<State, Custom>) => State | typeof STOP | undefined;
+export type ResourceConfig = {
+    src: string;
+    size?: {
+        width: number;
+        height: number;
+    };
+    slices?: {
+        vertical: number;
+        horizontal: number;
+    };
+    animations?: Record<string, {
+        frames: number[];
+        frameDuration: number;
+        loop: boolean;
+    }>;
+};
 export type RunEngineProps<State, Custom = never> = {
     initialState: State;
     render: (state: State) => {
@@ -211,22 +227,7 @@ export type RunEngineProps<State, Custom = never> = {
         renderables: Renderable[];
     };
     nextState: NextStateFunction<State, Custom> | NextStateFunction<State, Custom>[];
-    resources?: Record<string, {
-        src: string;
-        size?: {
-            width: number;
-            height: number;
-        };
-        slices?: {
-            vertical: number;
-            horizontal: number;
-        };
-        animations?: Record<string, {
-            frames: number[];
-            frameDuration: number;
-            loop: boolean;
-        }>;
-    }>;
+    resources?: Record<string, ResourceConfig>;
     sounds?: Record<string, {
         src: string;
     }>;
@@ -246,11 +247,14 @@ export type RunEngineProps<State, Custom = never> = {
         y: number;
         zoom: number;
     };
+    timeScale?: (state: State) => number;
+    maxFps?: (state: State) => number;
 };
 export type RunEngineFunction = <State, Custom = never>(props: RunEngineProps<State, Custom>) => Promise<{
     sendEvent: (event: Custom) => void;
     requestFullscreen: () => Promise<void>;
     exitFullscreen: () => Promise<void>;
+    addResource: (id: string, resource: ResourceConfig) => Promise<void>;
 }>;
 export declare const keyboardKeys: readonly ["ControlLeft", "ControlRight", "AltLeft", "AltRight", "CapsLock", "End", "Delete", "Tab", "Space", "Enter", "ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown", "Numpad0", "Numpad1", "Numpad2", "Numpad3", "Numpad4", "Numpad5", "Numpad6", "Numpad7", "Numpad8", "Numpad9", "Digit0", "Digit1", "Digit2", "Digit3", "Digit4", "Digit5", "Digit6", "Digit7", "Digit8", "Digit9", "KeyA", "KeyB", "KeyC", "KeyD", "KeyE", "KeyF", "KeyG", "KeyH", "KeyI", "KeyJ", "KeyK", "KeyL", "KeyM", "KeyN", "KeyO", "KeyP", "KeyQ", "KeyR", "KeyS", "KeyT", "KeyU", "KeyV", "KeyW", "KeyX", "KeyY", "KeyZ"];
 export type KeyboardKeys = (typeof keyboardKeys)[number];

package/lib/index.cjs

@@ -155,6 +155,42 @@ const createPlaceholderSheet = (size) => {
 // all. An arbitrary, small-but-visible size, purely so the placeholder
 // still draws as *something* instead of a 0x0/NaN canvas.
 const DEFAULT_PLACEHOLDER_SIZE = { width: 64, height: 64 };
+// Loads a single resources[id] entry into a ResourceEntry — shared by the
+// startup resources (below) and addResource (returned from runEngine, at
+// the bottom of this file) so a resource registered later loads exactly
+// the same way, placeholder fallback included.
+const loadResource = (value) => new Promise((resolve) => {
+    const image = new Image();
+    // A single, unsliced image (1x1) if unset — only an actual
+    // spritesheet needs this declared.
+    const slices = value.slices ?? { horizontal: 1, vertical: 1 };
+    // sheetSize is the whole loaded sheet's pixel dimensions — value's
+    // declared `size` if set, otherwise whatever the image actually
+    // measures once it's loaded (or DEFAULT_PLACEHOLDER_SIZE if even
+    // that isn't available, i.e. no `size` declared *and* the image
+    // failed to load too).
+    const settle = (loadedImage, sheetSize) => {
+        resolve({
+            image: loadedImage,
+            size: {
+                width: sheetSize.width / slices.horizontal,
+                height: sheetSize.height / slices.vertical,
+            },
+            slices,
+            animations: value.animations ?? {},
+        });
+    };
+    image.src = value.src;
+    image.onload = () => settle(image, value.size ?? { width: image.naturalWidth, height: image.naturalHeight });
+    // Missing/failed-to-load asset (see .gitignore's dist/resources/
+    // note) — a placeholder sheet, sized to match what this resource
+    // declared, keeps every frame/slice/animation index the caller
+    // already computes valid instead of drawing nothing or throwing.
+    image.onerror = () => {
+        const placeholderSize = value.size ?? DEFAULT_PLACEHOLDER_SIZE;
+        settle(createPlaceholderSheet(placeholderSize), placeholderSize);
+    };
+});
 const runEngine = async (props) => {
     const runId = ++latestRunId;
     resetCanvas?.();
@@ -246,38 +282,14 @@ const runEngine = async (props) => {
         events.push({ tag: "CUSTOM", event });
     };
     const resources = props.resources ?? {};
-    const resourceById = await iterateRecordAsync(resources, async ({ value }) => new Promise((resolve) => {
-        const image = new Image();
-        // A single, unsliced image (1x1) if unset — only an actual
-        // spritesheet needs this declared.
-        const slices = value.slices ?? { horizontal: 1, vertical: 1 };
-        // sheetSize is the whole loaded sheet's pixel dimensions — value's
-        // declared `size` if set, otherwise whatever the image actually
-        // measures once it's loaded (or DEFAULT_PLACEHOLDER_SIZE if even
-        // that isn't available, i.e. no `size` declared *and* the image
-        // failed to load too).
-        const settle = (loadedImage, sheetSize) => {
-            resolve({
-                image: loadedImage,
-                size: {
-                    width: sheetSize.width / slices.horizontal,
-                    height: sheetSize.height / slices.vertical,
-                },
-                slices,
-                animations: value.animations ?? {},
-            });
-        };
-        image.src = value.src;
-        image.onload = () => settle(image, value.size ?? { width: image.naturalWidth, height: image.naturalHeight });
-        // Missing/failed-to-load asset (see .gitignore's dist/resources/
-        // note) — a placeholder sheet, sized to match what this resource
-        // declared, keeps every frame/slice/animation index the example
-        // already computes valid instead of drawing nothing or throwing.
-        image.onerror = () => {
-            const placeholderSize = value.size ?? DEFAULT_PLACEHOLDER_SIZE;
-            settle(createPlaceholderSheet(placeholderSize), placeholderSize);
-        };
-    }));
+    const resourceById = await iterateRecordAsync(resources, ({ value }) => loadResource(value));
+    // Registers a resource after startup — loads it exactly like the
+    // resources above (loadResource is the same function), then adds it to
+    // the same resourceById map every SPRITE/ANIMATED_SPRITE lookup already
+    // reads from, so it's usable by `resourceId` as soon as this resolves.
+    const addResource = async (id, resource) => {
+        resourceById[id] = await loadResource(resource);
+    };
     const loadAudio = (src) => new Promise((resolve) => {
         const audio = new Audio(src);
         audio.oncanplaythrough = function () {
@@ -357,7 +369,12 @@ const runEngine = async (props) => {
     // fullscreen functions are no-ops here since this run never gets far
     // enough to own the canvas — the newer run's are the ones that matter.
     if (runId !== latestRunId) {
-        return { sendEvent, requestFullscreen: () => Promise.resolve(), exitFullscreen: () => Promise.resolve() };
+        return {
+            sendEvent,
+            requestFullscreen: () => Promise.resolve(),
+            exitFullscreen: () => Promise.resolve(),
+            addResource,
+        };
     }
     context.imageSmoothingEnabled = false;
     // An offscreen 1x1 canvas used only to resolve a CSS color string (a
@@ -445,7 +462,12 @@ const runEngine = async (props) => {
         seenAnimationIds.add(renderable.id);
         const resource = resourceById[renderable.resourceId];
         const animation = resource.animations[renderable.animation];
-        const timeScale = renderable.timeScale ?? 1;
+        // Composed with RunEngineProps.timeScale (currentTimeScale, set once
+        // per tick below) — this renderable's own speed multiplied by
+        // whatever the whole game's currently running at, so a global 2x/4x/
+        // stop control speeds up (or freezes) every animation right along
+        // with the rest of the simulation, not just movement/timers.
+        const timeScale = (renderable.timeScale ?? 1) * currentTimeScale;
         const paused = renderable.paused ?? false;
         const now = Date.now();
         const tracked = animationStateById.get(renderable.id);
@@ -658,7 +680,18 @@ const runEngine = async (props) => {
     };
     const nextStateFns = Array.isArray(props.nextState) ? props.nextState : [props.nextState];
     let lastFrame = Date.now();
+    // When the next tick is due under RunEngineProps.maxFps — only read
+    // or advanced while a cap is set (see the top of the loop below).
+    let nextTickAt = 0;
     let hoveredId = null;
+    // How much this tick's simulated time is scaled by (see
+    // RunEngineProps.timeScale) — set once per tick, right before that
+    // tick's own TIME event delta is computed, and read again later the
+    // same tick by resolveAnimatedSprite (below) so a single number
+    // governs both game logic and animation playback consistently within
+    // one tick rather than each recomputing props.timeScale(state)
+    // separately (state may itself have just changed this same tick).
+    let currentTimeScale = 1;
     // Shared by the mouse "click" listener and the touch handlers below —
     // firing a CLICK is the same "is whatever's currently hovered
     // isClickable" check either way; only how `mouse` was determined
@@ -971,7 +1004,35 @@ const runEngine = async (props) => {
     };
     const intervalId = setInterval(() => {
         const now = Date.now();
-        const delta = now - lastFrame;
+        const rawDelta = now - lastFrame;
+        // Skipped rather than delayed (see RunEngineProps.maxFps) — returning
+        // before anything else runs leaves `events`, keyboard/mouse state and
+        // lastFrame all untouched, so whatever happened in the meantime is
+        // still delivered by the next tick that does run, and its TIME delta
+        // covers this skipped one too.
+        const maxFps = props.maxFps?.(state);
+        if (maxFps !== undefined && maxFps > 0) {
+            if (now < nextTickAt) {
+                return;
+            }
+            // Scheduled from the previous target rather than from `now`: the
+            // interval only fires every ~4ms, so "at least 1000/maxFps since
+            // the last tick" would always round late (a 60 cap landing on
+            // 20ms ticks, i.e. 50 FPS), while this lets the early and late
+            // ticks average out to the cap itself. Falling more than a whole
+            // interval behind (a hitch, a backgrounded tab, the cap having
+            // just been turned on) restarts the schedule from now instead of
+            // bursting through every missed tick to catch up.
+            const interval = 1000 / maxFps;
+            nextTickAt = now - nextTickAt > interval ? now + interval : nextTickAt + interval;
+        }
+        // Read from state as this tick starts (i.e. still last tick's own
+        // result) — resolveAnimatedSprite (below, during this same tick's
+        // render pass) reads this same currentTimeScale rather than calling
+        // props.timeScale itself, so a single value governs both the TIME
+        // event about to fire and every animation's playback consistently.
+        currentTimeScale = props.timeScale?.(state) ?? 1;
+        const delta = rawDelta * currentTimeScale;
         events.push({ tag: "TIME", delta: delta });
         for (const event of events) {
             const keyboard = iterateRecord(previousState.keyboardState, ({ key, value: previouslyPressed }) => {
@@ -1164,7 +1225,7 @@ const runEngine = async (props) => {
         // Same pile-up risk as the canvas listeners above, but on `window`.
         window.removeEventListener("resize", applyResize);
     };
-    return { sendEvent, requestFullscreen, exitFullscreen };
+    return { sendEvent, requestFullscreen, exitFullscreen, addResource };
 };
 
 // One factory per Renderable variant — literally just `{ type: "X",

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

@@ -2,4 +2,4 @@ import { runEngine } from "./engine/runEngine";
 import { STOP } from "./engine/types";
 import { animatedSprite, circle, group, line, rectangle, sprite, text } from "./engine/renderables";
 export { runEngine, STOP, rectangle, circle, text, sprite, animatedSprite, line, group };
-export type { NextStateFunction, NextStateProps, Renderable, GameEvent, CustomGameEvent, } from "./engine/types";
+export type { NextStateFunction, NextStateProps, Renderable, ResourceConfig, GameEvent, CustomGameEvent, } from "./engine/types";

package/lib/index.js

@@ -153,6 +153,42 @@ const createPlaceholderSheet = (size) => {
 // all. An arbitrary, small-but-visible size, purely so the placeholder
 // still draws as *something* instead of a 0x0/NaN canvas.
 const DEFAULT_PLACEHOLDER_SIZE = { width: 64, height: 64 };
+// Loads a single resources[id] entry into a ResourceEntry — shared by the
+// startup resources (below) and addResource (returned from runEngine, at
+// the bottom of this file) so a resource registered later loads exactly
+// the same way, placeholder fallback included.
+const loadResource = (value) => new Promise((resolve) => {
+    const image = new Image();
+    // A single, unsliced image (1x1) if unset — only an actual
+    // spritesheet needs this declared.
+    const slices = value.slices ?? { horizontal: 1, vertical: 1 };
+    // sheetSize is the whole loaded sheet's pixel dimensions — value's
+    // declared `size` if set, otherwise whatever the image actually
+    // measures once it's loaded (or DEFAULT_PLACEHOLDER_SIZE if even
+    // that isn't available, i.e. no `size` declared *and* the image
+    // failed to load too).
+    const settle = (loadedImage, sheetSize) => {
+        resolve({
+            image: loadedImage,
+            size: {
+                width: sheetSize.width / slices.horizontal,
+                height: sheetSize.height / slices.vertical,
+            },
+            slices,
+            animations: value.animations ?? {},
+        });
+    };
+    image.src = value.src;
+    image.onload = () => settle(image, value.size ?? { width: image.naturalWidth, height: image.naturalHeight });
+    // Missing/failed-to-load asset (see .gitignore's dist/resources/
+    // note) — a placeholder sheet, sized to match what this resource
+    // declared, keeps every frame/slice/animation index the caller
+    // already computes valid instead of drawing nothing or throwing.
+    image.onerror = () => {
+        const placeholderSize = value.size ?? DEFAULT_PLACEHOLDER_SIZE;
+        settle(createPlaceholderSheet(placeholderSize), placeholderSize);
+    };
+});
 const runEngine = async (props) => {
     const runId = ++latestRunId;
     resetCanvas?.();
@@ -244,38 +280,14 @@ const runEngine = async (props) => {
         events.push({ tag: "CUSTOM", event });
     };
     const resources = props.resources ?? {};
-    const resourceById = await iterateRecordAsync(resources, async ({ value }) => new Promise((resolve) => {
-        const image = new Image();
-        // A single, unsliced image (1x1) if unset — only an actual
-        // spritesheet needs this declared.
-        const slices = value.slices ?? { horizontal: 1, vertical: 1 };
-        // sheetSize is the whole loaded sheet's pixel dimensions — value's
-        // declared `size` if set, otherwise whatever the image actually
-        // measures once it's loaded (or DEFAULT_PLACEHOLDER_SIZE if even
-        // that isn't available, i.e. no `size` declared *and* the image
-        // failed to load too).
-        const settle = (loadedImage, sheetSize) => {
-            resolve({
-                image: loadedImage,
-                size: {
-                    width: sheetSize.width / slices.horizontal,
-                    height: sheetSize.height / slices.vertical,
-                },
-                slices,
-                animations: value.animations ?? {},
-            });
-        };
-        image.src = value.src;
-        image.onload = () => settle(image, value.size ?? { width: image.naturalWidth, height: image.naturalHeight });
-        // Missing/failed-to-load asset (see .gitignore's dist/resources/
-        // note) — a placeholder sheet, sized to match what this resource
-        // declared, keeps every frame/slice/animation index the example
-        // already computes valid instead of drawing nothing or throwing.
-        image.onerror = () => {
-            const placeholderSize = value.size ?? DEFAULT_PLACEHOLDER_SIZE;
-            settle(createPlaceholderSheet(placeholderSize), placeholderSize);
-        };
-    }));
+    const resourceById = await iterateRecordAsync(resources, ({ value }) => loadResource(value));
+    // Registers a resource after startup — loads it exactly like the
+    // resources above (loadResource is the same function), then adds it to
+    // the same resourceById map every SPRITE/ANIMATED_SPRITE lookup already
+    // reads from, so it's usable by `resourceId` as soon as this resolves.
+    const addResource = async (id, resource) => {
+        resourceById[id] = await loadResource(resource);
+    };
     const loadAudio = (src) => new Promise((resolve) => {
         const audio = new Audio(src);
         audio.oncanplaythrough = function () {
@@ -355,7 +367,12 @@ const runEngine = async (props) => {
     // fullscreen functions are no-ops here since this run never gets far
     // enough to own the canvas — the newer run's are the ones that matter.
     if (runId !== latestRunId) {
-        return { sendEvent, requestFullscreen: () => Promise.resolve(), exitFullscreen: () => Promise.resolve() };
+        return {
+            sendEvent,
+            requestFullscreen: () => Promise.resolve(),
+            exitFullscreen: () => Promise.resolve(),
+            addResource,
+        };
     }
     context.imageSmoothingEnabled = false;
     // An offscreen 1x1 canvas used only to resolve a CSS color string (a
@@ -443,7 +460,12 @@ const runEngine = async (props) => {
         seenAnimationIds.add(renderable.id);
         const resource = resourceById[renderable.resourceId];
         const animation = resource.animations[renderable.animation];
-        const timeScale = renderable.timeScale ?? 1;
+        // Composed with RunEngineProps.timeScale (currentTimeScale, set once
+        // per tick below) — this renderable's own speed multiplied by
+        // whatever the whole game's currently running at, so a global 2x/4x/
+        // stop control speeds up (or freezes) every animation right along
+        // with the rest of the simulation, not just movement/timers.
+        const timeScale = (renderable.timeScale ?? 1) * currentTimeScale;
         const paused = renderable.paused ?? false;
         const now = Date.now();
         const tracked = animationStateById.get(renderable.id);
@@ -656,7 +678,18 @@ const runEngine = async (props) => {
     };
     const nextStateFns = Array.isArray(props.nextState) ? props.nextState : [props.nextState];
     let lastFrame = Date.now();
+    // When the next tick is due under RunEngineProps.maxFps — only read
+    // or advanced while a cap is set (see the top of the loop below).
+    let nextTickAt = 0;
     let hoveredId = null;
+    // How much this tick's simulated time is scaled by (see
+    // RunEngineProps.timeScale) — set once per tick, right before that
+    // tick's own TIME event delta is computed, and read again later the
+    // same tick by resolveAnimatedSprite (below) so a single number
+    // governs both game logic and animation playback consistently within
+    // one tick rather than each recomputing props.timeScale(state)
+    // separately (state may itself have just changed this same tick).
+    let currentTimeScale = 1;
     // Shared by the mouse "click" listener and the touch handlers below —
     // firing a CLICK is the same "is whatever's currently hovered
     // isClickable" check either way; only how `mouse` was determined
@@ -969,7 +1002,35 @@ const runEngine = async (props) => {
     };
     const intervalId = setInterval(() => {
         const now = Date.now();
-        const delta = now - lastFrame;
+        const rawDelta = now - lastFrame;
+        // Skipped rather than delayed (see RunEngineProps.maxFps) — returning
+        // before anything else runs leaves `events`, keyboard/mouse state and
+        // lastFrame all untouched, so whatever happened in the meantime is
+        // still delivered by the next tick that does run, and its TIME delta
+        // covers this skipped one too.
+        const maxFps = props.maxFps?.(state);
+        if (maxFps !== undefined && maxFps > 0) {
+            if (now < nextTickAt) {
+                return;
+            }
+            // Scheduled from the previous target rather than from `now`: the
+            // interval only fires every ~4ms, so "at least 1000/maxFps since
+            // the last tick" would always round late (a 60 cap landing on
+            // 20ms ticks, i.e. 50 FPS), while this lets the early and late
+            // ticks average out to the cap itself. Falling more than a whole
+            // interval behind (a hitch, a backgrounded tab, the cap having
+            // just been turned on) restarts the schedule from now instead of
+            // bursting through every missed tick to catch up.
+            const interval = 1000 / maxFps;
+            nextTickAt = now - nextTickAt > interval ? now + interval : nextTickAt + interval;
+        }
+        // Read from state as this tick starts (i.e. still last tick's own
+        // result) — resolveAnimatedSprite (below, during this same tick's
+        // render pass) reads this same currentTimeScale rather than calling
+        // props.timeScale itself, so a single value governs both the TIME
+        // event about to fire and every animation's playback consistently.
+        currentTimeScale = props.timeScale?.(state) ?? 1;
+        const delta = rawDelta * currentTimeScale;
         events.push({ tag: "TIME", delta: delta });
         for (const event of events) {
             const keyboard = iterateRecord(previousState.keyboardState, ({ key, value: previouslyPressed }) => {
@@ -1162,7 +1223,7 @@ const runEngine = async (props) => {
         // Same pile-up risk as the canvas listeners above, but on `window`.
         window.removeEventListener("resize", applyResize);
     };
-    return { sendEvent, requestFullscreen, exitFullscreen };
+    return { sendEvent, requestFullscreen, exitFullscreen, addResource };
 };
 
 // One factory per Renderable variant — literally just `{ type: "X",

package/lib/index.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yuuna-engine",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "A lightweight, state-machine-based TypeScript game engine for quick prototypes. Runs directly in the browser.",
   "type": "module",
   "main": "./lib/index.cjs",