yuuna-engine 0.6.0 → 0.7.0

package/README.md

@@ -1,156 +1,160 @@
-<p align="center">
-  <img src="dist/resources/yuuna.png" alt="Yuuna" width="120" height="120" />
-</p>
-
-# Yuuna
-
-[Live demo & playground](https://lucy-dot-exe.github.io/yuuna/) · [GitHub](https://github.com/lucy-dot-exe/yuuna)
-
-A lightweight, state-machine-based TypeScript game engine built for quick
-prototypes — 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. It's scratch paper for game
-ideas, not a replacement for Godot or Unity.
-
-## Install
-
-```sh
-npm install yuuna-engine
-```
-
-## Quick start
-
-Add a canvas with `id="yuuna"` to your page:
-
-```html
-<canvas id="yuuna"></canvas>
-```
-
-Then describe your game as state + render + nextState:
-
-```ts
-import { runEngine } from "yuuna-engine";
-
-// The shape of your game's data — whatever it takes to fully describe
-// what's on screen and how it behaves
-type GameState = { cookies: number };
-
-// What that state looks like before anything has happened yet
-const initialState: GameState = { cookies: 0 };
-
-runEngine<GameState>({
-  initialState,
-
-  // Given the current state, what should be drawn this frame? Called
-  // every frame — always derive the picture from state, instead of
-  // reaching for the canvas directly.
-  render: (state) => ({
-    renderables: [
-      {
-        type: "TEXT",
-        text: `${state.cookies} cookies`,
-        color: "black",
-        position: { x: 100, y: 50 },
-      },
-      {
-        type: "CIRCLE",
-        id: "cookie",
-        isClickable: true,
-        color: "brown",
-        position: { x: 50, y: 50 },
-        radius: 25,
-      },
-    ],
-  }),
-
-  // Given the current state and something that just happened, what's the
-  // next state? Called once per event (a click, a frame tick, ...) — the
-  // only place game logic lives.
-  nextState: ({ state, event }) => {
-    if (event.tag === "CLICK" && event.id === "cookie") {
-      return { cookies: state.cookies + 1 };
-    }
-
-    return state;
-  },
-});
-```
-
-## Concepts
-
-- **Renderables** — declarative shapes drawn each frame: `RECTANGLE`,
-  `CIRCLE`, `TEXT`, `SPRITE`, `ANIMATED_SPRITE`, `LINE`, and `GROUP`. Give
-  one an `id` plus `isClickable`/`isHoverable` to make it interactive.
-- **Events** — `nextState` receives one `GameEvent` per call: `TIME`,
-  `CLICK`, `HOVER_IN`, `HOVER_OUT`, `MOUSE_MOVE`, `MOUSE_LEAVE`,
-  `MUSIC_END`, or a `CUSTOM` event of a type you define yourself, for
-  reporting things like an async `fetch()` resolving back into your
-  state machine.
-- **Keyboard, camera, sprites & animation, sound effects & music,
-  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.
-
-This README stays intentionally thin — the full concept-by-concept
-reference, with every option and example, lives on the
-[wiki](https://github.com/lucy-dot-exe/yuuna/wiki). The
-[playground](https://lucy-dot-exe.github.io/yuuna/#playground) also has a
-small, focused example for most of these you can run and edit directly.
-
-## Templates
-
-Prefer a working starting point over typing the quick start out by
-hand? Grab one from [`templates/`](templates):
-
-- **[blank](templates/blank)** — a single `index.html`, zero install —
-  open it in a browser and it runs.
-- **[npm](templates/npm)** — TypeScript + a dev server with hot reload
-  (via Vite), for a real local project.
-- **[neutralino-desktop](templates/neutralino-desktop)** — the `npm`
-  template wrapped in [Neutralino](https://neutralino.js.org) to run as a
-  native desktop window instead of a browser tab.
-
-```sh
-npx degit lucy-dot-exe/yuuna/templates/blank my-game
-# or: npx degit lucy-dot-exe/yuuna/templates/npm my-game
-# or: npx degit lucy-dot-exe/yuuna/templates/neutralino-desktop my-game
-```
-
-[`degit`](https://github.com/Rich-Harris/degit) copies the folder without
-its git history — no cloning or forking the whole engine repo needed.
-Each template's own README has more on running it once copied.
-
-## Development
-
-```sh
-yarn install
-yarn build   # builds lib/ (npm package) and dist/bundle.js (landing page)
-yarn watch   # rebuild on change
-```
-
-`dist/index.html` is the landing page — it loads `dist/bundle.js` in the
-browser via a global `Yuuna` object and embeds a live Monaco editor so
-visitors can edit and run a game directly on the page.
-
-## Assets
-
-The examples' art/sound/music lives in `dist/resources/`, gitignored
-rather than committed — this repo being open source doesn't make every
-asset in it free to redistribute. `runEngine()` falls back to a
-generated placeholder for any image that isn't there (and simply plays
-nothing for missing audio) instead of failing, so the examples still
-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.
-
-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.
-
-## License
-
-MIT © [lucy-dot-exe](https://github.com/lucy-dot-exe)
+<p align="center">
+  <img src="dist/resources/yuuna.png" alt="Yuuna" width="120" height="120" />
+</p>
+
+# Yuuna
+
+[Live demo & playground](https://lucy-dot-exe.github.io/yuuna/) · [GitHub](https://github.com/lucy-dot-exe/yuuna)
+
+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.
+
+## Install
+
+```sh
+npm install yuuna-engine
+```
+
+## Quick start
+
+Add a canvas with `id="yuuna"` to your page:
+
+```html
+<canvas id="yuuna"></canvas>
+```
+
+Then describe your game as state + render + nextState:
+
+```ts
+import { runEngine } from "yuuna-engine";
+
+// The shape of your game's data — whatever it takes to fully describe
+// what's on screen and how it behaves
+type GameState = { cookies: number };
+
+// What that state looks like before anything has happened yet
+const initialState: GameState = { cookies: 0 };
+
+runEngine<GameState>({
+  initialState,
+
+  // Given the current state, what should be drawn this frame? Called
+  // every frame — always derive the picture from state, instead of
+  // reaching for the canvas directly.
+  render: (state) => ({
+    renderables: [
+      {
+        type: "TEXT",
+        text: `${state.cookies} cookies`,
+        color: "black",
+        position: { x: 100, y: 50 },
+      },
+      {
+        type: "CIRCLE",
+        id: "cookie",
+        isClickable: true,
+        color: "brown",
+        position: { x: 50, y: 50 },
+        radius: 25,
+      },
+    ],
+  }),
+
+  // Given the current state and something that just happened, what's the
+  // next state? Called once per event (a click, a frame tick, ...) — the
+  // only place game logic lives.
+  nextState: ({ state, event }) => {
+    if (event.tag === "CLICK" && event.id === "cookie") {
+      return { cookies: state.cookies + 1 };
+    }
+
+    return state;
+  },
+});
+```
+
+## Concepts
+
+- **Renderables** — declarative shapes drawn each frame: `RECTANGLE`,
+  `CIRCLE`, `TEXT`, `SPRITE`, `ANIMATED_SPRITE`, `LINE`, and `GROUP`. Give
+  one an `id` plus `isClickable`/`isHoverable` to make it interactive.
+- **Events** — `nextState` receives one `GameEvent` per call: `TIME`,
+  `CLICK`, `HOVER_IN`, `HOVER_OUT`, `MOUSE_MOVE`, `MOUSE_LEAVE`,
+  `MUSIC_END`, or a `CUSTOM` event of a type you define yourself, for
+  reporting things like an async `fetch()` resolving back into your
+  state machine.
+- **Keyboard, camera, sprites & animation, sound effects & music,
+  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.
+
+This README stays intentionally thin — the full concept-by-concept
+reference, with every option and example, lives on the
+[wiki](https://github.com/lucy-dot-exe/yuuna/wiki). The
+[playground](https://lucy-dot-exe.github.io/yuuna/#playground) also has a
+small, focused example for most of these you can run and edit directly.
+
+## Templates
+
+Prefer a working starting point over typing the quick start out by
+hand? Grab one from [`templates/`](templates):
+
+- **[blank](templates/blank)** — a single `index.html`, zero install —
+  open it in a browser and it runs.
+- **[npm](templates/npm)** — TypeScript + a dev server with hot reload
+  (via Vite), for a real local project.
+- **[neutralino-desktop](templates/neutralino-desktop)** — the `npm`
+  template wrapped in [Neutralino](https://neutralino.js.org) to run as a
+  native desktop window.
+
+```sh
+npx degit lucy-dot-exe/yuuna/templates/blank my-game
+# or: npx degit lucy-dot-exe/yuuna/templates/npm my-game
+# or: npx degit lucy-dot-exe/yuuna/templates/neutralino-desktop my-game
+```
+
+[`degit`](https://github.com/Rich-Harris/degit) copies the folder without
+its git history — no cloning or forking the whole engine repo needed.
+Each template's own README has more on running it once copied.
+
+## Made with Yuuna
+
+- **[Yuuna's Heroes](https://lucinaexe.itch.io/yuunas-td)** — a game made
+  using Yuuna.
+
+## Development
+
+```sh
+yarn install
+yarn build   # builds lib/ (npm package) and dist/bundle.js (landing page)
+yarn watch   # rebuild on change
+```
+
+`dist/index.html` is the landing page — it loads `dist/bundle.js` in the
+browser via a global `Yuuna` object and embeds a live Monaco editor so
+visitors can edit and run a game directly on the page.
+
+## Assets
+
+The examples' art/sound/music lives in `dist/resources/`, gitignored
+rather than committed — this repo being open source doesn't make every
+asset in it free to redistribute. `runEngine()` falls back to a
+generated placeholder for any image that isn't there (and simply plays
+nothing for missing audio) instead of failing, so the examples still
+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.
+
+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.
+
+## License
+
+MIT © [lucy-dot-exe](https://github.com/lucy-dot-exe)

package/lib/engine/renderables.d.ts

@@ -0,0 +1,8 @@
+import { AnimatedSpriteRenderable, CircleRenderable, GroupRenderable, LineRenderable, RectangleRenderable, SpriteRenderable, TextRenderable } from "./types";
+export declare const rectangle: (props: Omit<RectangleRenderable, "type">) => RectangleRenderable;
+export declare const circle: (props: Omit<CircleRenderable, "type">) => CircleRenderable;
+export declare const text: (props: Omit<TextRenderable, "type">) => TextRenderable;
+export declare const sprite: (props: Omit<SpriteRenderable, "type">) => SpriteRenderable;
+export declare const animatedSprite: (props: Omit<AnimatedSpriteRenderable, "type">) => AnimatedSpriteRenderable;
+export declare const line: (props: Omit<LineRenderable, "type">) => LineRenderable;
+export declare const group: (props: Omit<GroupRenderable, "type">) => GroupRenderable;

package/lib/engine/types.d.ts

@@ -54,7 +54,7 @@ export type SpriteRenderable = BaseRenderable & {
         y: number;
     };
     resourceId: string;
-    frame: number;
+    frame?: number;
     opacity?: number;
     flipX?: boolean;
     swapColors?: {
@@ -191,6 +191,11 @@ export type NextStateProps<State, Custom = never> = {
         isJustPressed: boolean;
         isJustReleased: boolean;
     }>;
+    mouseButton: {
+        isPressed: boolean;
+        isJustPressed: boolean;
+        isJustReleased: boolean;
+    };
     playSound: (id: string) => void;
     playMusic: (id: string) => void;
     pauseMusic: () => void;
@@ -208,11 +213,11 @@ export type RunEngineProps<State, Custom = never> = {
     nextState: NextStateFunction<State, Custom> | NextStateFunction<State, Custom>[];
     resources?: Record<string, {
         src: string;
-        size: {
+        size?: {
             width: number;
             height: number;
         };
-        slices: {
+        slices?: {
             vertical: number;
             horizontal: number;
         };
@@ -234,6 +239,7 @@ export type RunEngineProps<State, Custom = never> = {
         height?: number;
         backgroundColor?: string;
         resize?: "none" | "fit" | "stretch";
+        pixelRatio?: number | true;
     };
     camera?: (state: State) => {
         x: number;
@@ -252,5 +258,12 @@ export type KeyboardState = Record<KeyboardKeys, boolean>;
 export declare var Yuuna: {
     runEngine: RunEngineFunction;
     STOP: typeof STOP;
+    rectangle: (props: Omit<RectangleRenderable, "type">) => RectangleRenderable;
+    circle: (props: Omit<CircleRenderable, "type">) => CircleRenderable;
+    text: (props: Omit<TextRenderable, "type">) => TextRenderable;
+    sprite: (props: Omit<SpriteRenderable, "type">) => SpriteRenderable;
+    animatedSprite: (props: Omit<AnimatedSpriteRenderable, "type">) => AnimatedSpriteRenderable;
+    line: (props: Omit<LineRenderable, "type">) => LineRenderable;
+    group: (props: Omit<GroupRenderable, "type">) => GroupRenderable;
 };
 export {};

package/lib/index.cjs

@@ -149,6 +149,12 @@ const createPlaceholderSheet = (size) => {
     }
     return canvas;
 };
+// Used only when a resource declares neither `size` (see settle() below)
+// nor actually loads — there's no image to measure and nothing declared
+// to fall back to, so there's no way to know the intended dimensions at
+// 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 };
 const runEngine = async (props) => {
     const runId = ++latestRunId;
     resetCanvas?.();
@@ -172,9 +178,39 @@ const runEngine = async (props) => {
     if (props.canvas?.backgroundColor !== undefined) {
         canvas.style.backgroundColor = props.canvas.backgroundColor;
     }
+    // The canvas's *logical* resolution — the fixed space every renderable
+    // position, and every mouse/touch coordinate, is expressed in. Captured
+    // here, before pixelRatio (below) scales the actual backing buffer past
+    // it, so both stay anchored to this regardless of what pixelRatio does.
+    const logicalWidth = canvas.width;
+    const logicalHeight = canvas.height;
+    // Scales the backing buffer beyond logicalWidth/logicalHeight so text
+    // and vector shapes (fillText, arc, ...) render crisply on a HiDPI
+    // screen — most phones — instead of the same logical-resolution buffer
+    // just being stretched larger by applyResize below. `true` follows the
+    // display's own devicePixelRatio; a number sets it explicitly; leaving
+    // this unset keeps today's 1x behavior. Sprites are unaffected either
+    // way — imageSmoothingEnabled stays false below regardless — so pixel
+    // art has no reason to turn this on.
+    const pixelRatio = props.canvas?.pixelRatio === true ? window.devicePixelRatio || 1 : props.canvas?.pixelRatio ?? 1;
+    if (pixelRatio !== 1) {
+        // Resizing the backing buffer resets the 2D context's transform (and
+        // everything else about its state), so context.scale below has to
+        // come after this, not before.
+        canvas.width = logicalWidth * pixelRatio;
+        canvas.height = logicalHeight * pixelRatio;
+        canvas.style.width = `${logicalWidth}px`;
+        canvas.style.height = `${logicalHeight}px`;
+        context.scale(pixelRatio, pixelRatio);
+    }
     // Make the canvas focusable so keyboard input is scoped to it instead of
     // leaking to the rest of the page (e.g. arrow keys scrolling the window).
     canvas.tabIndex = 0;
+    // Stops the browser from treating a drag/pinch on the canvas as page
+    // scroll/zoom — backs up the touchstart/touchmove preventDefault calls
+    // below for gestures (e.g. a pinch starting on the canvas) preventDefault
+    // alone doesn't reliably stop.
+    canvas.style.touchAction = "none";
     // Resizes the *display* size only (CSS width/height) — canvas.width/
     // height above stays the fixed logical resolution every renderable's
     // position is already expressed in, so this never needs to touch any
@@ -212,24 +248,35 @@ const runEngine = async (props) => {
     const resources = props.resources ?? {};
     const resourceById = await iterateRecordAsync(resources, async ({ value }) => new Promise((resolve) => {
         const image = new Image();
-        const settle = (loadedImage) => {
+        // 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: value.size.width / value.slices.horizontal,
-                    height: value.size.height / value.slices.vertical,
+                    width: sheetSize.width / slices.horizontal,
+                    height: sheetSize.height / slices.vertical,
                 },
-                slices: value.slices,
+                slices,
                 animations: value.animations ?? {},
             });
         };
         image.src = value.src;
-        image.onload = () => settle(image);
+        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 = () => settle(createPlaceholderSheet(value.size));
+        image.onerror = () => {
+            const placeholderSize = value.size ?? DEFAULT_PLACEHOLDER_SIZE;
+            settle(createPlaceholderSheet(placeholderSize), placeholderSize);
+        };
     }));
     const loadAudio = (src) => new Promise((resolve) => {
         const audio = new Audio(src);
@@ -590,8 +637,20 @@ const runEngine = async (props) => {
     // the same conversion to line up.
     const getCanvasPosition = (ev) => {
         return {
-            x: (ev.offsetX * canvas.width) / canvas.clientWidth,
-            y: (ev.offsetY * canvas.height) / canvas.clientHeight,
+            x: (ev.offsetX * logicalWidth) / canvas.clientWidth,
+            y: (ev.offsetY * logicalHeight) / canvas.clientHeight,
+        };
+    };
+    // Touch's equivalent of getCanvasPosition — a Touch has no offsetX/Y
+    // (that's a MouseEvent-only convenience), so this gets there manually
+    // via getBoundingClientRect instead. clientX/Y and the rect are both
+    // viewport-relative, so their difference stays correct regardless of
+    // page scroll.
+    const getTouchPosition = (touch) => {
+        const rect = canvas.getBoundingClientRect();
+        return {
+            x: ((touch.clientX - rect.left) * logicalWidth) / canvas.clientWidth,
+            y: ((touch.clientY - rect.top) * logicalHeight) / canvas.clientHeight,
         };
     };
     const updateState = (updateFn) => {
@@ -600,8 +659,11 @@ const runEngine = async (props) => {
     const nextStateFns = Array.isArray(props.nextState) ? props.nextState : [props.nextState];
     let lastFrame = Date.now();
     let hoveredId = null;
-    const handleClick = (ev) => {
-        const mouse = getCanvasPosition(ev);
+    // 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
+    // differs (a real click event vs. a lifted finger).
+    const fireClick = (mouse) => {
         if (hoveredId === null)
             return;
         const { renderables, camera } = renderState(state);
@@ -610,6 +672,7 @@ const runEngine = async (props) => {
             events.push({ tag: "CLICK", id: hovered.id, mouse, worldMouse: toWorldPosition(mouse, camera) });
         }
     };
+    const handleClick = (ev) => fireClick(getCanvasPosition(ev));
     canvas.addEventListener("click", handleClick);
     const initialState = {
         keyboardState: createRecord(keyboardKeys, () => false),
@@ -639,8 +702,34 @@ const runEngine = async (props) => {
         }
     };
     canvas.addEventListener("keyup", handleKeyUp);
-    const handleMouseMoveHover = (ev) => {
-        const mouse = getCanvasPosition(ev);
+    // mouseButton state (see NextStateProps.mouseButton) — a double-buffer
+    // exactly like keyboardState above, just for the primary mouse button.
+    let previousMouseButtonState = { isPressed: false };
+    const currentMouseButtonState = { isPressed: false };
+    const handleMouseDown = (event) => {
+        // Left/primary button only — matching CLICK, which already only
+        // ever fires for it.
+        if (event.button === 0) {
+            currentMouseButtonState.isPressed = true;
+        }
+    };
+    canvas.addEventListener("mousedown", handleMouseDown);
+    const handleMouseUp = (event) => {
+        if (event.button === 0) {
+            currentMouseButtonState.isPressed = false;
+        }
+    };
+    // On window rather than the canvas — so releasing the button after
+    // having dragged off the canvas while still holding it down still
+    // clears isPressed, instead of leaving it stuck true forever.
+    window.addEventListener("mouseup", handleMouseUp);
+    // Shared by mousemove and the touch handlers below — updates hoveredId
+    // from a canvas position and fires HOVER_IN/HOVER_OUT as whatever's
+    // underneath it changes. Touch has no ambient hover the way a mouse
+    // does (nothing is "hovered" until a finger actually touches down), but
+    // feeding a touch's position through this the same as the mouse's is
+    // what lets an isHoverable renderable react to a tap/drag at all.
+    const updateHover = (mouse) => {
         const { renderables, camera } = renderState(state);
         const worldMouse = toWorldPosition(mouse, camera);
         const hovered = [...renderables]
@@ -657,9 +746,9 @@ const runEngine = async (props) => {
         }
         hoveredId = hovered === undefined ? null : hovered.id ?? null;
     };
+    const handleMouseMoveHover = (ev) => updateHover(getCanvasPosition(ev));
     canvas.addEventListener("mousemove", handleMouseMoveHover);
-    const handleMouseMoveTracking = (ev) => {
-        const mouse = getCanvasPosition(ev);
+    const updateTracking = (mouse) => {
         if (hoveredId === null) {
             return;
         }
@@ -669,13 +758,17 @@ const runEngine = async (props) => {
             events.push({ tag: "MOUSE_MOVE", mouse, worldMouse: toWorldPosition(mouse, camera), id: hovered.id });
         }
     };
+    const handleMouseMoveTracking = (ev) => updateTracking(getCanvasPosition(ev));
     canvas.addEventListener("mousemove", handleMouseMoveTracking);
     // No further mousemove fires once the mouse is off the canvas, so this
     // is also the only chance to report a HOVER_OUT for whatever was
     // hovered when it left — otherwise that hover would just dangle,
     // never explicitly ended.
-    const handleMouseLeave = (ev) => {
-        const mouse = getCanvasPosition(ev);
+    // Shared by mouseleave and the touch handlers below — clears whatever's
+    // hovered (firing HOVER_OUT for it) without a HOVER_IN taking its
+    // place. Returns worldMouse so callers that need it (MOUSE_LEAVE below)
+    // don't have to call renderState() a second time just to get it.
+    const clearHover = (mouse) => {
         const { renderables, camera } = renderState(state);
         const worldMouse = toWorldPosition(mouse, camera);
         if (hoveredId !== null) {
@@ -685,9 +778,79 @@ const runEngine = async (props) => {
             }
         }
         hoveredId = null;
+        return worldMouse;
+    };
+    const handleMouseLeave = (ev) => {
+        const mouse = getCanvasPosition(ev);
+        const worldMouse = clearHover(mouse);
         events.push({ tag: "MOUSE_LEAVE", mouse, worldMouse });
     };
     canvas.addEventListener("mouseleave", handleMouseLeave);
+    // Translates touch into the same HOVER_IN/HOVER_OUT/MOUSE_MOVE/CLICK
+    // events mouse input already produces (via updateHover/updateTracking/
+    // fireClick/clearHover above), so existing game code written against
+    // those events works on a touchscreen with no changes of its own.
+    // Single-touch only — touches[0]/changedTouches[0] — the same "one
+    // active pointer" model mouse input already assumes; a second finger is
+    // ignored rather than tracked as its own pointer.
+    //
+    // preventDefault on start/move keeps a drag/tap on the canvas from also
+    // scrolling, pinch-zooming, or triggering pull-to-refresh — the browser
+    // gestures a touchscreen normally reserves that space for; { passive:
+    // false } is what makes preventDefault actually take effect here.
+    const handleTouchStart = (ev) => {
+        ev.preventDefault();
+        const touch = ev.touches[0];
+        if (touch === undefined)
+            return;
+        currentMouseButtonState.isPressed = true;
+        const mouse = getTouchPosition(touch);
+        updateHover(mouse);
+        updateTracking(mouse);
+    };
+    canvas.addEventListener("touchstart", handleTouchStart, { passive: false });
+    const handleTouchMove = (ev) => {
+        ev.preventDefault();
+        const touch = ev.touches[0];
+        if (touch === undefined)
+            return;
+        const mouse = getTouchPosition(touch);
+        updateHover(mouse);
+        updateTracking(mouse);
+    };
+    canvas.addEventListener("touchmove", handleTouchMove, { passive: false });
+    // A lifted finger both releases (mirroring mouseup) and clicks
+    // (mirroring the browser's own click-after-mouseup) — touch has no
+    // separate "up" and "click" events of its own the way mouse does, so
+    // both happen here together, in that order. hover is updated once more
+    // first so a plain tap (touchstart immediately followed by touchend,
+    // with no touchmove between them to have already done this) still
+    // fires CLICK against whatever's actually under it; hover is then
+    // cleared, since nothing's left touching it once the finger lifts.
+    const handleTouchEnd = (ev) => {
+        ev.preventDefault();
+        currentMouseButtonState.isPressed = false;
+        const touch = ev.changedTouches[0];
+        if (touch === undefined)
+            return;
+        const mouse = getTouchPosition(touch);
+        updateHover(mouse);
+        fireClick(mouse);
+        clearHover(mouse);
+    };
+    canvas.addEventListener("touchend", handleTouchEnd, { passive: false });
+    // A cancelled touch (e.g. an incoming call interrupting the page, or
+    // the OS deciding it's a system gesture instead) never fires touchend —
+    // handled the same as lifting the finger, minus the click, since
+    // there's no tap to speak of once the touch itself has been cancelled.
+    const handleTouchCancel = (ev) => {
+        currentMouseButtonState.isPressed = false;
+        const touch = ev.changedTouches[0];
+        if (touch === undefined)
+            return;
+        clearHover(getTouchPosition(touch));
+    };
+    canvas.addEventListener("touchcancel", handleTouchCancel, { passive: false });
     // Tab switches are a document-level concern (visibilitychange), not
     // something that ever reaches the canvas itself the way mouse/keyboard
     // events do.
@@ -819,11 +982,17 @@ const runEngine = async (props) => {
                     isJustReleased: !isPressed && previouslyPressed,
                 };
             });
+            const mouseButton = {
+                isPressed: currentMouseButtonState.isPressed,
+                isJustPressed: currentMouseButtonState.isPressed && !previousMouseButtonState.isPressed,
+                isJustReleased: !currentMouseButtonState.isPressed && previousMouseButtonState.isPressed,
+            };
             for (const nextState of nextStateFns) {
                 const result = nextState({
                     state,
                     event,
                     keyboard,
+                    mouseButton,
                     playSound,
                     playMusic,
                     pauseMusic,
@@ -843,7 +1012,7 @@ const runEngine = async (props) => {
             }
         }
         events.splice(0, events.length);
-        context.clearRect(0, 0, canvas.width, canvas.height);
+        context.clearRect(0, 0, logicalWidth, logicalHeight);
         const { cursor, renderables } = renderState(state);
         canvas.style.cursor = cursor ?? "default";
         for (const renderable of renderables) {
@@ -876,12 +1045,11 @@ const runEngine = async (props) => {
                 continue;
             }
             if (renderable.type === "SPRITE") {
-                const { opacity = 1, flipX = false, modulate, swapColors } = renderable;
+                const { opacity = 1, flipX = false, frame: frameIndex = 0, modulate, swapColors } = 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,
+                    x: frameIndex % resource.slices.horizontal,
+                    y: Math.floor(frameIndex / resource.slices.horizontal) % resource.slices.vertical,
                 };
                 const source = {
                     x: frame.x * resource.size.width,
@@ -901,7 +1069,7 @@ const runEngine = async (props) => {
                 let image = resource.image;
                 let imageSource = source;
                 if (swapColors !== undefined && swapColors.length > 0) {
-                    image = swappedSpriteFrame(renderable.resourceId, renderable.frame, image, imageSource, swapColors);
+                    image = swappedSpriteFrame(renderable.resourceId, frameIndex, image, imageSource, swapColors);
                     imageSource = { x: 0, y: 0, width: source.width, height: source.height };
                 }
                 if (modulate !== undefined) {
@@ -955,6 +1123,7 @@ const runEngine = async (props) => {
         }
         lastFrame = now;
         previousState.keyboardState = { ...currentState.keyboardState };
+        previousMouseButtonState = { ...currentMouseButtonState };
     }, 0);
     resetCanvas = () => {
         clearInterval(intervalId);
@@ -978,9 +1147,16 @@ const runEngine = async (props) => {
         canvas.removeEventListener("click", handleClick);
         canvas.removeEventListener("keydown", handleKeyDown);
         canvas.removeEventListener("keyup", handleKeyUp);
+        canvas.removeEventListener("mousedown", handleMouseDown);
         canvas.removeEventListener("mousemove", handleMouseMoveHover);
         canvas.removeEventListener("mousemove", handleMouseMoveTracking);
         canvas.removeEventListener("mouseleave", handleMouseLeave);
+        canvas.removeEventListener("touchstart", handleTouchStart);
+        canvas.removeEventListener("touchmove", handleTouchMove);
+        canvas.removeEventListener("touchend", handleTouchEnd);
+        canvas.removeEventListener("touchcancel", handleTouchCancel);
+        // On window, not the canvas — see where it's added above for why.
+        window.removeEventListener("mouseup", handleMouseUp);
         // This one's on `document`, not the canvas — same reasoning as above,
         // just doubly true since `document` isn't even scoped to this canvas.
         window.document.removeEventListener("visibilitychange", handleVisibilityChange);
@@ -991,6 +1167,50 @@ const runEngine = async (props) => {
     return { sendEvent, requestFullscreen, exitFullscreen };
 };
 
+// One factory per Renderable variant — literally just `{ type: "X",
+// ...props }`, so `sprite({...})` (or `Yuuna.sprite({...})` in the
+// browser bundle/playground) reads the same as writing the object
+// literal by hand, minus needing to get `type` right yourself.
+// Deliberately not a place defaults live: besides SpriteRenderable.frame
+// (optional at the type level, see types.ts — the engine itself defaults
+// it to 0), each factory still requires whatever its Renderable type
+// still requires.
+const rectangle = (props) => ({
+    type: "RECTANGLE",
+    ...props,
+});
+const circle = (props) => ({
+    type: "CIRCLE",
+    ...props,
+});
+const text = (props) => ({
+    type: "TEXT",
+    ...props,
+});
+const sprite = (props) => ({
+    type: "SPRITE",
+    ...props,
+});
+const animatedSprite = (props) => ({
+    type: "ANIMATED_SPRITE",
+    ...props,
+});
+const line = (props) => ({
+    type: "LINE",
+    ...props,
+});
+const group = (props) => ({
+    type: "GROUP",
+    ...props,
+});
+
 exports.STOP = STOP;
+exports.animatedSprite = animatedSprite;
+exports.circle = circle;
+exports.group = group;
+exports.line = line;
+exports.rectangle = rectangle;
 exports.runEngine = runEngine;
+exports.sprite = sprite;
+exports.text = text;
 //# sourceMappingURL=index.cjs.map

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,5 @@
 import { runEngine } from "./engine/runEngine";
 import { STOP } from "./engine/types";
-export { runEngine, STOP };
+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";

package/lib/index.js

@@ -147,6 +147,12 @@ const createPlaceholderSheet = (size) => {
     }
     return canvas;
 };
+// Used only when a resource declares neither `size` (see settle() below)
+// nor actually loads — there's no image to measure and nothing declared
+// to fall back to, so there's no way to know the intended dimensions at
+// 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 };
 const runEngine = async (props) => {
     const runId = ++latestRunId;
     resetCanvas?.();
@@ -170,9 +176,39 @@ const runEngine = async (props) => {
     if (props.canvas?.backgroundColor !== undefined) {
         canvas.style.backgroundColor = props.canvas.backgroundColor;
     }
+    // The canvas's *logical* resolution — the fixed space every renderable
+    // position, and every mouse/touch coordinate, is expressed in. Captured
+    // here, before pixelRatio (below) scales the actual backing buffer past
+    // it, so both stay anchored to this regardless of what pixelRatio does.
+    const logicalWidth = canvas.width;
+    const logicalHeight = canvas.height;
+    // Scales the backing buffer beyond logicalWidth/logicalHeight so text
+    // and vector shapes (fillText, arc, ...) render crisply on a HiDPI
+    // screen — most phones — instead of the same logical-resolution buffer
+    // just being stretched larger by applyResize below. `true` follows the
+    // display's own devicePixelRatio; a number sets it explicitly; leaving
+    // this unset keeps today's 1x behavior. Sprites are unaffected either
+    // way — imageSmoothingEnabled stays false below regardless — so pixel
+    // art has no reason to turn this on.
+    const pixelRatio = props.canvas?.pixelRatio === true ? window.devicePixelRatio || 1 : props.canvas?.pixelRatio ?? 1;
+    if (pixelRatio !== 1) {
+        // Resizing the backing buffer resets the 2D context's transform (and
+        // everything else about its state), so context.scale below has to
+        // come after this, not before.
+        canvas.width = logicalWidth * pixelRatio;
+        canvas.height = logicalHeight * pixelRatio;
+        canvas.style.width = `${logicalWidth}px`;
+        canvas.style.height = `${logicalHeight}px`;
+        context.scale(pixelRatio, pixelRatio);
+    }
     // Make the canvas focusable so keyboard input is scoped to it instead of
     // leaking to the rest of the page (e.g. arrow keys scrolling the window).
     canvas.tabIndex = 0;
+    // Stops the browser from treating a drag/pinch on the canvas as page
+    // scroll/zoom — backs up the touchstart/touchmove preventDefault calls
+    // below for gestures (e.g. a pinch starting on the canvas) preventDefault
+    // alone doesn't reliably stop.
+    canvas.style.touchAction = "none";
     // Resizes the *display* size only (CSS width/height) — canvas.width/
     // height above stays the fixed logical resolution every renderable's
     // position is already expressed in, so this never needs to touch any
@@ -210,24 +246,35 @@ const runEngine = async (props) => {
     const resources = props.resources ?? {};
     const resourceById = await iterateRecordAsync(resources, async ({ value }) => new Promise((resolve) => {
         const image = new Image();
-        const settle = (loadedImage) => {
+        // 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: value.size.width / value.slices.horizontal,
-                    height: value.size.height / value.slices.vertical,
+                    width: sheetSize.width / slices.horizontal,
+                    height: sheetSize.height / slices.vertical,
                 },
-                slices: value.slices,
+                slices,
                 animations: value.animations ?? {},
             });
         };
         image.src = value.src;
-        image.onload = () => settle(image);
+        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 = () => settle(createPlaceholderSheet(value.size));
+        image.onerror = () => {
+            const placeholderSize = value.size ?? DEFAULT_PLACEHOLDER_SIZE;
+            settle(createPlaceholderSheet(placeholderSize), placeholderSize);
+        };
     }));
     const loadAudio = (src) => new Promise((resolve) => {
         const audio = new Audio(src);
@@ -588,8 +635,20 @@ const runEngine = async (props) => {
     // the same conversion to line up.
     const getCanvasPosition = (ev) => {
         return {
-            x: (ev.offsetX * canvas.width) / canvas.clientWidth,
-            y: (ev.offsetY * canvas.height) / canvas.clientHeight,
+            x: (ev.offsetX * logicalWidth) / canvas.clientWidth,
+            y: (ev.offsetY * logicalHeight) / canvas.clientHeight,
+        };
+    };
+    // Touch's equivalent of getCanvasPosition — a Touch has no offsetX/Y
+    // (that's a MouseEvent-only convenience), so this gets there manually
+    // via getBoundingClientRect instead. clientX/Y and the rect are both
+    // viewport-relative, so their difference stays correct regardless of
+    // page scroll.
+    const getTouchPosition = (touch) => {
+        const rect = canvas.getBoundingClientRect();
+        return {
+            x: ((touch.clientX - rect.left) * logicalWidth) / canvas.clientWidth,
+            y: ((touch.clientY - rect.top) * logicalHeight) / canvas.clientHeight,
         };
     };
     const updateState = (updateFn) => {
@@ -598,8 +657,11 @@ const runEngine = async (props) => {
     const nextStateFns = Array.isArray(props.nextState) ? props.nextState : [props.nextState];
     let lastFrame = Date.now();
     let hoveredId = null;
-    const handleClick = (ev) => {
-        const mouse = getCanvasPosition(ev);
+    // 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
+    // differs (a real click event vs. a lifted finger).
+    const fireClick = (mouse) => {
         if (hoveredId === null)
             return;
         const { renderables, camera } = renderState(state);
@@ -608,6 +670,7 @@ const runEngine = async (props) => {
             events.push({ tag: "CLICK", id: hovered.id, mouse, worldMouse: toWorldPosition(mouse, camera) });
         }
     };
+    const handleClick = (ev) => fireClick(getCanvasPosition(ev));
     canvas.addEventListener("click", handleClick);
     const initialState = {
         keyboardState: createRecord(keyboardKeys, () => false),
@@ -637,8 +700,34 @@ const runEngine = async (props) => {
         }
     };
     canvas.addEventListener("keyup", handleKeyUp);
-    const handleMouseMoveHover = (ev) => {
-        const mouse = getCanvasPosition(ev);
+    // mouseButton state (see NextStateProps.mouseButton) — a double-buffer
+    // exactly like keyboardState above, just for the primary mouse button.
+    let previousMouseButtonState = { isPressed: false };
+    const currentMouseButtonState = { isPressed: false };
+    const handleMouseDown = (event) => {
+        // Left/primary button only — matching CLICK, which already only
+        // ever fires for it.
+        if (event.button === 0) {
+            currentMouseButtonState.isPressed = true;
+        }
+    };
+    canvas.addEventListener("mousedown", handleMouseDown);
+    const handleMouseUp = (event) => {
+        if (event.button === 0) {
+            currentMouseButtonState.isPressed = false;
+        }
+    };
+    // On window rather than the canvas — so releasing the button after
+    // having dragged off the canvas while still holding it down still
+    // clears isPressed, instead of leaving it stuck true forever.
+    window.addEventListener("mouseup", handleMouseUp);
+    // Shared by mousemove and the touch handlers below — updates hoveredId
+    // from a canvas position and fires HOVER_IN/HOVER_OUT as whatever's
+    // underneath it changes. Touch has no ambient hover the way a mouse
+    // does (nothing is "hovered" until a finger actually touches down), but
+    // feeding a touch's position through this the same as the mouse's is
+    // what lets an isHoverable renderable react to a tap/drag at all.
+    const updateHover = (mouse) => {
         const { renderables, camera } = renderState(state);
         const worldMouse = toWorldPosition(mouse, camera);
         const hovered = [...renderables]
@@ -655,9 +744,9 @@ const runEngine = async (props) => {
         }
         hoveredId = hovered === undefined ? null : hovered.id ?? null;
     };
+    const handleMouseMoveHover = (ev) => updateHover(getCanvasPosition(ev));
     canvas.addEventListener("mousemove", handleMouseMoveHover);
-    const handleMouseMoveTracking = (ev) => {
-        const mouse = getCanvasPosition(ev);
+    const updateTracking = (mouse) => {
         if (hoveredId === null) {
             return;
         }
@@ -667,13 +756,17 @@ const runEngine = async (props) => {
             events.push({ tag: "MOUSE_MOVE", mouse, worldMouse: toWorldPosition(mouse, camera), id: hovered.id });
         }
     };
+    const handleMouseMoveTracking = (ev) => updateTracking(getCanvasPosition(ev));
     canvas.addEventListener("mousemove", handleMouseMoveTracking);
     // No further mousemove fires once the mouse is off the canvas, so this
     // is also the only chance to report a HOVER_OUT for whatever was
     // hovered when it left — otherwise that hover would just dangle,
     // never explicitly ended.
-    const handleMouseLeave = (ev) => {
-        const mouse = getCanvasPosition(ev);
+    // Shared by mouseleave and the touch handlers below — clears whatever's
+    // hovered (firing HOVER_OUT for it) without a HOVER_IN taking its
+    // place. Returns worldMouse so callers that need it (MOUSE_LEAVE below)
+    // don't have to call renderState() a second time just to get it.
+    const clearHover = (mouse) => {
         const { renderables, camera } = renderState(state);
         const worldMouse = toWorldPosition(mouse, camera);
         if (hoveredId !== null) {
@@ -683,9 +776,79 @@ const runEngine = async (props) => {
             }
         }
         hoveredId = null;
+        return worldMouse;
+    };
+    const handleMouseLeave = (ev) => {
+        const mouse = getCanvasPosition(ev);
+        const worldMouse = clearHover(mouse);
         events.push({ tag: "MOUSE_LEAVE", mouse, worldMouse });
     };
     canvas.addEventListener("mouseleave", handleMouseLeave);
+    // Translates touch into the same HOVER_IN/HOVER_OUT/MOUSE_MOVE/CLICK
+    // events mouse input already produces (via updateHover/updateTracking/
+    // fireClick/clearHover above), so existing game code written against
+    // those events works on a touchscreen with no changes of its own.
+    // Single-touch only — touches[0]/changedTouches[0] — the same "one
+    // active pointer" model mouse input already assumes; a second finger is
+    // ignored rather than tracked as its own pointer.
+    //
+    // preventDefault on start/move keeps a drag/tap on the canvas from also
+    // scrolling, pinch-zooming, or triggering pull-to-refresh — the browser
+    // gestures a touchscreen normally reserves that space for; { passive:
+    // false } is what makes preventDefault actually take effect here.
+    const handleTouchStart = (ev) => {
+        ev.preventDefault();
+        const touch = ev.touches[0];
+        if (touch === undefined)
+            return;
+        currentMouseButtonState.isPressed = true;
+        const mouse = getTouchPosition(touch);
+        updateHover(mouse);
+        updateTracking(mouse);
+    };
+    canvas.addEventListener("touchstart", handleTouchStart, { passive: false });
+    const handleTouchMove = (ev) => {
+        ev.preventDefault();
+        const touch = ev.touches[0];
+        if (touch === undefined)
+            return;
+        const mouse = getTouchPosition(touch);
+        updateHover(mouse);
+        updateTracking(mouse);
+    };
+    canvas.addEventListener("touchmove", handleTouchMove, { passive: false });
+    // A lifted finger both releases (mirroring mouseup) and clicks
+    // (mirroring the browser's own click-after-mouseup) — touch has no
+    // separate "up" and "click" events of its own the way mouse does, so
+    // both happen here together, in that order. hover is updated once more
+    // first so a plain tap (touchstart immediately followed by touchend,
+    // with no touchmove between them to have already done this) still
+    // fires CLICK against whatever's actually under it; hover is then
+    // cleared, since nothing's left touching it once the finger lifts.
+    const handleTouchEnd = (ev) => {
+        ev.preventDefault();
+        currentMouseButtonState.isPressed = false;
+        const touch = ev.changedTouches[0];
+        if (touch === undefined)
+            return;
+        const mouse = getTouchPosition(touch);
+        updateHover(mouse);
+        fireClick(mouse);
+        clearHover(mouse);
+    };
+    canvas.addEventListener("touchend", handleTouchEnd, { passive: false });
+    // A cancelled touch (e.g. an incoming call interrupting the page, or
+    // the OS deciding it's a system gesture instead) never fires touchend —
+    // handled the same as lifting the finger, minus the click, since
+    // there's no tap to speak of once the touch itself has been cancelled.
+    const handleTouchCancel = (ev) => {
+        currentMouseButtonState.isPressed = false;
+        const touch = ev.changedTouches[0];
+        if (touch === undefined)
+            return;
+        clearHover(getTouchPosition(touch));
+    };
+    canvas.addEventListener("touchcancel", handleTouchCancel, { passive: false });
     // Tab switches are a document-level concern (visibilitychange), not
     // something that ever reaches the canvas itself the way mouse/keyboard
     // events do.
@@ -817,11 +980,17 @@ const runEngine = async (props) => {
                     isJustReleased: !isPressed && previouslyPressed,
                 };
             });
+            const mouseButton = {
+                isPressed: currentMouseButtonState.isPressed,
+                isJustPressed: currentMouseButtonState.isPressed && !previousMouseButtonState.isPressed,
+                isJustReleased: !currentMouseButtonState.isPressed && previousMouseButtonState.isPressed,
+            };
             for (const nextState of nextStateFns) {
                 const result = nextState({
                     state,
                     event,
                     keyboard,
+                    mouseButton,
                     playSound,
                     playMusic,
                     pauseMusic,
@@ -841,7 +1010,7 @@ const runEngine = async (props) => {
             }
         }
         events.splice(0, events.length);
-        context.clearRect(0, 0, canvas.width, canvas.height);
+        context.clearRect(0, 0, logicalWidth, logicalHeight);
         const { cursor, renderables } = renderState(state);
         canvas.style.cursor = cursor ?? "default";
         for (const renderable of renderables) {
@@ -874,12 +1043,11 @@ const runEngine = async (props) => {
                 continue;
             }
             if (renderable.type === "SPRITE") {
-                const { opacity = 1, flipX = false, modulate, swapColors } = renderable;
+                const { opacity = 1, flipX = false, frame: frameIndex = 0, modulate, swapColors } = 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,
+                    x: frameIndex % resource.slices.horizontal,
+                    y: Math.floor(frameIndex / resource.slices.horizontal) % resource.slices.vertical,
                 };
                 const source = {
                     x: frame.x * resource.size.width,
@@ -899,7 +1067,7 @@ const runEngine = async (props) => {
                 let image = resource.image;
                 let imageSource = source;
                 if (swapColors !== undefined && swapColors.length > 0) {
-                    image = swappedSpriteFrame(renderable.resourceId, renderable.frame, image, imageSource, swapColors);
+                    image = swappedSpriteFrame(renderable.resourceId, frameIndex, image, imageSource, swapColors);
                     imageSource = { x: 0, y: 0, width: source.width, height: source.height };
                 }
                 if (modulate !== undefined) {
@@ -953,6 +1121,7 @@ const runEngine = async (props) => {
         }
         lastFrame = now;
         previousState.keyboardState = { ...currentState.keyboardState };
+        previousMouseButtonState = { ...currentMouseButtonState };
     }, 0);
     resetCanvas = () => {
         clearInterval(intervalId);
@@ -976,9 +1145,16 @@ const runEngine = async (props) => {
         canvas.removeEventListener("click", handleClick);
         canvas.removeEventListener("keydown", handleKeyDown);
         canvas.removeEventListener("keyup", handleKeyUp);
+        canvas.removeEventListener("mousedown", handleMouseDown);
         canvas.removeEventListener("mousemove", handleMouseMoveHover);
         canvas.removeEventListener("mousemove", handleMouseMoveTracking);
         canvas.removeEventListener("mouseleave", handleMouseLeave);
+        canvas.removeEventListener("touchstart", handleTouchStart);
+        canvas.removeEventListener("touchmove", handleTouchMove);
+        canvas.removeEventListener("touchend", handleTouchEnd);
+        canvas.removeEventListener("touchcancel", handleTouchCancel);
+        // On window, not the canvas — see where it's added above for why.
+        window.removeEventListener("mouseup", handleMouseUp);
         // This one's on `document`, not the canvas — same reasoning as above,
         // just doubly true since `document` isn't even scoped to this canvas.
         window.document.removeEventListener("visibilitychange", handleVisibilityChange);
@@ -989,5 +1165,42 @@ const runEngine = async (props) => {
     return { sendEvent, requestFullscreen, exitFullscreen };
 };
 
-export { STOP, runEngine };
+// One factory per Renderable variant — literally just `{ type: "X",
+// ...props }`, so `sprite({...})` (or `Yuuna.sprite({...})` in the
+// browser bundle/playground) reads the same as writing the object
+// literal by hand, minus needing to get `type` right yourself.
+// Deliberately not a place defaults live: besides SpriteRenderable.frame
+// (optional at the type level, see types.ts — the engine itself defaults
+// it to 0), each factory still requires whatever its Renderable type
+// still requires.
+const rectangle = (props) => ({
+    type: "RECTANGLE",
+    ...props,
+});
+const circle = (props) => ({
+    type: "CIRCLE",
+    ...props,
+});
+const text = (props) => ({
+    type: "TEXT",
+    ...props,
+});
+const sprite = (props) => ({
+    type: "SPRITE",
+    ...props,
+});
+const animatedSprite = (props) => ({
+    type: "ANIMATED_SPRITE",
+    ...props,
+});
+const line = (props) => ({
+    type: "LINE",
+    ...props,
+});
+const group = (props) => ({
+    type: "GROUP",
+    ...props,
+});
+
+export { STOP, animatedSprite, circle, group, line, rectangle, runEngine, sprite, text };
 //# sourceMappingURL=index.js.map

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.6.0",
+  "version": "0.7.0",
   "description": "A lightweight, state-machine-based TypeScript game engine for quick prototypes. Runs directly in the browser.",
   "type": "module",
   "main": "./lib/index.cjs",
@@ -39,7 +39,9 @@
   "scripts": {
     "build": "node scripts/generate-playground-assets.mjs && rollup -c",
     "watch": "node scripts/generate-playground-assets.mjs && rollup -c -w",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "sync-assets": "node scripts/sync-playground-assets.mjs",
+    "postinstall": "node -e \"const fs=require('fs');try{if(fs.existsSync('.githooks')&&fs.existsSync('.git')){require('child_process').execSync('git config core.hooksPath .githooks')}}catch(e){}\""
   },
   "devDependencies": {
     "nodemon": "^3.1.0",

package/lib/utils/constants.d.ts

@@ -1,6 +0,0 @@
-export declare const CONSTANTS: {
-    WINDOW: {
-        WIDTH: number;
-        HEIGHT: number;
-    };
-};