yuuna-engine 0.5.0 → 0.6.0

package/README.md

@@ -107,10 +107,14 @@ hand? Grab one from [`templates/`](templates):
   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

package/lib/engine/types.d.ts

@@ -174,7 +174,11 @@ export type MusicEndEvent = {
     tag: "MUSIC_END";
     id: string;
 };
-export type GameEvent = TimeEvent | ClickEvent | HoverInEvent | HoverOutEvent | MouseMoveEvent | MouseLeaveEvent | TabBlurEvent | TabFocusEvent | MusicEndEvent;
+export type FullscreenChangeEvent = {
+    tag: "FULLSCREEN_CHANGE";
+    isFullscreen: boolean;
+};
+export type GameEvent = TimeEvent | ClickEvent | HoverInEvent | HoverOutEvent | MouseMoveEvent | MouseLeaveEvent | TabBlurEvent | TabFocusEvent | MusicEndEvent | FullscreenChangeEvent;
 export type CustomGameEvent<Custom> = {
     tag: "CUSTOM";
     event: Custom;
@@ -229,6 +233,7 @@ export type RunEngineProps<State, Custom = never> = {
         width?: number;
         height?: number;
         backgroundColor?: string;
+        resize?: "none" | "fit" | "stretch";
     };
     camera?: (state: State) => {
         x: number;
@@ -238,6 +243,8 @@ export type RunEngineProps<State, Custom = never> = {
 };
 export type RunEngineFunction = <State, Custom = never>(props: RunEngineProps<State, Custom>) => Promise<{
     sendEvent: (event: Custom) => void;
+    requestFullscreen: () => Promise<void>;
+    exitFullscreen: () => 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

@@ -175,6 +175,31 @@ const runEngine = async (props) => {
     // 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;
+    // 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
+    // of that math. See RunEngineProps.canvas.resize for the mode semantics.
+    const applyResize = () => {
+        const mode = props.canvas?.resize;
+        if (mode === undefined || mode === "none") {
+            return;
+        }
+        if (mode === "stretch") {
+            canvas.style.width = `${window.innerWidth}px`;
+            canvas.style.height = `${window.innerHeight}px`;
+            return;
+        }
+        const scale = Math.min(window.innerWidth / canvas.width, window.innerHeight / canvas.height);
+        canvas.style.width = `${canvas.width * scale}px`;
+        canvas.style.height = `${canvas.height * scale}px`;
+    };
+    applyResize();
+    window.addEventListener("resize", applyResize);
+    const requestFullscreen = () => canvas.requestFullscreen();
+    // exitFullscreen() rejects with a TypeError if nothing is fullscreen —
+    // guarded into a no-op instead, so callers don't need to track that
+    // state themselves just to call this safely.
+    const exitFullscreen = () => window.document.fullscreenElement === null ? Promise.resolve() : window.document.exitFullscreen();
     let state = props.initialState;
     const events = [];
     // Lets a caller report something that happened outside the render loop
@@ -281,9 +306,11 @@ const runEngine = async (props) => {
     };
     // A newer runEngine() call started while this one was still loading
     // resources (e.g. a spritesheet) — abandon this run instead of setting
-    // up a second, orphaned render loop alongside the newer one.
+    // up a second, orphaned render loop alongside the newer one. The
+    // 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 };
+        return { sendEvent, requestFullscreen: () => Promise.resolve(), exitFullscreen: () => Promise.resolve() };
     }
     context.imageSmoothingEnabled = false;
     // An offscreen 1x1 canvas used only to resolve a CSS color string (a
@@ -668,6 +695,17 @@ const runEngine = async (props) => {
         events.push({ tag: window.document.hidden ? "TAB_BLUR" : "TAB_FOCUS" });
     };
     window.document.addEventListener("visibilitychange", handleVisibilityChange);
+    // Fullscreen is a document-level concern too, and fires for every way
+    // fullscreen can change — the requestFullscreen()/exitFullscreen()
+    // above, but also things neither of those causes directly, like the
+    // user pressing Esc. Re-running applyResize() here (rather than relying
+    // solely on the "resize" listener) covers browsers that don't also fire
+    // a window resize when fullscreen is toggled.
+    const handleFullscreenChange = () => {
+        events.push({ tag: "FULLSCREEN_CHANGE", isFullscreen: window.document.fullscreenElement === canvas });
+        applyResize();
+    };
+    window.document.addEventListener("fullscreenchange", handleFullscreenChange);
     context.imageSmoothingEnabled = false;
     // Scale is a canvas transform around the renderable's anchor, applied
     // before its type-specific drawing runs below — everything drawn under
@@ -946,8 +984,11 @@ const runEngine = async (props) => {
         // 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);
+        window.document.removeEventListener("fullscreenchange", handleFullscreenChange);
+        // Same pile-up risk as the canvas listeners above, but on `window`.
+        window.removeEventListener("resize", applyResize);
     };
-    return { sendEvent };
+    return { sendEvent, requestFullscreen, exitFullscreen };
 };
 
 exports.STOP = STOP;

package/lib/index.cjs.map

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

package/lib/index.js

@@ -173,6 +173,31 @@ const runEngine = async (props) => {
     // 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;
+    // 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
+    // of that math. See RunEngineProps.canvas.resize for the mode semantics.
+    const applyResize = () => {
+        const mode = props.canvas?.resize;
+        if (mode === undefined || mode === "none") {
+            return;
+        }
+        if (mode === "stretch") {
+            canvas.style.width = `${window.innerWidth}px`;
+            canvas.style.height = `${window.innerHeight}px`;
+            return;
+        }
+        const scale = Math.min(window.innerWidth / canvas.width, window.innerHeight / canvas.height);
+        canvas.style.width = `${canvas.width * scale}px`;
+        canvas.style.height = `${canvas.height * scale}px`;
+    };
+    applyResize();
+    window.addEventListener("resize", applyResize);
+    const requestFullscreen = () => canvas.requestFullscreen();
+    // exitFullscreen() rejects with a TypeError if nothing is fullscreen —
+    // guarded into a no-op instead, so callers don't need to track that
+    // state themselves just to call this safely.
+    const exitFullscreen = () => window.document.fullscreenElement === null ? Promise.resolve() : window.document.exitFullscreen();
     let state = props.initialState;
     const events = [];
     // Lets a caller report something that happened outside the render loop
@@ -279,9 +304,11 @@ const runEngine = async (props) => {
     };
     // A newer runEngine() call started while this one was still loading
     // resources (e.g. a spritesheet) — abandon this run instead of setting
-    // up a second, orphaned render loop alongside the newer one.
+    // up a second, orphaned render loop alongside the newer one. The
+    // 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 };
+        return { sendEvent, requestFullscreen: () => Promise.resolve(), exitFullscreen: () => Promise.resolve() };
     }
     context.imageSmoothingEnabled = false;
     // An offscreen 1x1 canvas used only to resolve a CSS color string (a
@@ -666,6 +693,17 @@ const runEngine = async (props) => {
         events.push({ tag: window.document.hidden ? "TAB_BLUR" : "TAB_FOCUS" });
     };
     window.document.addEventListener("visibilitychange", handleVisibilityChange);
+    // Fullscreen is a document-level concern too, and fires for every way
+    // fullscreen can change — the requestFullscreen()/exitFullscreen()
+    // above, but also things neither of those causes directly, like the
+    // user pressing Esc. Re-running applyResize() here (rather than relying
+    // solely on the "resize" listener) covers browsers that don't also fire
+    // a window resize when fullscreen is toggled.
+    const handleFullscreenChange = () => {
+        events.push({ tag: "FULLSCREEN_CHANGE", isFullscreen: window.document.fullscreenElement === canvas });
+        applyResize();
+    };
+    window.document.addEventListener("fullscreenchange", handleFullscreenChange);
     context.imageSmoothingEnabled = false;
     // Scale is a canvas transform around the renderable's anchor, applied
     // before its type-specific drawing runs below — everything drawn under
@@ -944,8 +982,11 @@ const runEngine = async (props) => {
         // 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);
+        window.document.removeEventListener("fullscreenchange", handleFullscreenChange);
+        // Same pile-up risk as the canvas listeners above, but on `window`.
+        window.removeEventListener("resize", applyResize);
     };
-    return { sendEvent };
+    return { sendEvent, requestFullscreen, exitFullscreen };
 };
 
 export { STOP, runEngine };

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.5.0",
+  "version": "0.6.0",
   "description": "A lightweight, state-machine-based TypeScript game engine for quick prototypes. Runs directly in the browser.",
   "type": "module",
   "main": "./lib/index.cjs",