yuuna-engine 0.6.0 → 0.8.0

package/README.md

@@ -1,156 +1,177 @@
-<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 — 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
+
+```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.
+- **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
+[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.
+
+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.
+- **[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
+
+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;
@@ -199,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) => {
@@ -206,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;
     }>;
@@ -234,17 +240,20 @@ export type RunEngineProps<State, Custom = never> = {
         height?: number;
         backgroundColor?: string;
         resize?: "none" | "fit" | "stretch";
+        pixelRatio?: number | true;
     };
     camera?: (state: State) => {
         x: number;
         y: number;
         zoom: number;
     };
+    timeScale?: (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];
@@ -252,5 +261,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 {};