yuuna-engine 0.2.1 → 0.3.0

package/README.md

@@ -1,135 +1,194 @@
-<p align="center">
-  <img src="dist/resources/yuuna.png" alt="Yuuna" width="120" height="120" />
-</p>
-
-# 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";
-
-type GameState = { cookies: number };
-
-runEngine<GameState>({
-  initialState: { cookies: 0 },
-
-  // Optional — size and color the canvas from code instead of HTML/CSS
-  canvas: { width: 960, height: 540, backgroundColor: "#0d1831" },
-
-  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,
-      },
-    ],
-  }),
-
-  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`, and `LINE`. Give one an `id` plus
-  `isClickable` / `isHoverable` / `trackMouseMovement` to make it
-  interactive.
-- **Events** — your `nextState` function receives one `GameEvent` per call:
-  `TIME` (frame tick with `delta`), `CLICK`, `HOVER_IN`, `HOVER_OUT`, or
-  `MOUSE_MOVE`.
-- **Keyboard** — `nextState` also receives a `keyboard` map keyed by
-  `KeyCode`-style keys (e.g. `"KeyW"`, `"ArrowLeft"`, `"Space"`), each with
-  `isPressed` / `isJustPressed` / `isJustReleased`.
-- **Sprites** — pass a `resources` map of `{ src, size, slices }` to
-  `runEngine` to load spritesheets, then reference them by id with a
-  `SPRITE` renderable's `resourceId` and `frame`. Set `flipX: true` to
-  mirror a sprite horizontally — useful when the art is drawn facing one
-  direction but needs to move the other way.
-- **Canvas** — pass `canvas: { width, height, backgroundColor }` to
-  `runEngine` to size and color the canvas from code. All three are
-  optional; anything you don't set falls back to the canvas element's
-  existing HTML/CSS.
-- **Mechanics** — `nextState` can also be an array of small
-  `NextStateFunction`s instead of one big function. Each one is run in
-  order for every event, and can return:
-  - a new state, to update to
-  - `undefined` (or no `return` at all) — no change, but the rest of the
-    list still runs, so a guard can just be `if (...) return;`
-  - `STOP` (imported from `yuuna-engine`) — no change, and the rest of
-    the list is skipped for this event, so a shared rule (like "nothing
-    happens once the game is over") only needs to be written once
-
-  ```ts
-  import { runEngine, STOP, type NextStateFunction } from "yuuna-engine";
-
-  const freezeOnGameOver: NextStateFunction<GameState> = ({ state }) => {
-    if (state.lives <= 0) return STOP;
-  };
-
-  const moveEnemies: NextStateFunction<GameState> = ({ state, event }) => {
-    if (event.tag === "TIME") {
-      return { ...state, enemies: move(state.enemies, event.delta) };
-    }
-  };
-
-  runEngine<GameState>({
-    initialState,
-    render,
-    nextState: [freezeOnGameOver, moveEnemies /* ... */],
-  });
-  ```
-
-## 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.
-
-## 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 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";
+
+type GameState = { cookies: number };
+
+runEngine<GameState>({
+  initialState: { cookies: 0 },
+
+  // Optional — size and color the canvas from code instead of HTML/CSS
+  canvas: { width: 960, height: 540, backgroundColor: "#0d1831" },
+
+  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,
+      },
+    ],
+  }),
+
+  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`, `LINE`, `GROUP`, and `ANIMATED_SPRITE`. Give
+  one an `id` plus `isClickable` / `isHoverable` / `trackMouseMovement` to
+  make it interactive. `TEXT` also takes a `fontSize` (defaults to `30`).
+  `GROUP` draws nothing itself — it's just a `position` (plus the usual
+  `scale`/`modulate`/`layer` below) for `children` to hang off of, for
+  grouping renderables that should move/scale/tint together without
+  needing a shape of its own; it's never interactable, since it has no
+  shape to hit-test. `ANIMATED_SPRITE` is `SPRITE` with an `animation`
+  (name of one defined on that resource — see Sprites below) and an
+  optional `timeScale` instead of a `frame` number; the engine picks the
+  frame for you based on how long it's been playing. Unlike every other
+  renderable, its `id` is required — that's how the engine recognizes
+  "this is the same sprite as last frame" across renders (and switches to
+  frame 0 if `animation` changes for that `id`), so reusing an id across
+  two different entities will make their animations bleed together.
+  Every renderable also takes:
+  - `layer` — higher values render later, i.e. in front of lower ones.
+    Defaults to `0`; renderables on the same layer keep `render()`'s order.
+  - `scale` — `{ x, y }` multiplier on the renderable's size, anchored at
+    its `position` (or `from`, for `LINE`). Defaults to `{ x: 1, y: 1 }`.
+    A `CIRCLE` scaled unevenly draws (and hit-tests) as an ellipse.
+  - `modulate` — a CSS color string that multiplies the renderable's color
+    channel-by-channel, the same way Godot's `modulate` works — e.g.
+    `"#808080"` halves brightness, `"#ff0000"` keeps only the red channel.
+  - `children` — nested renderables, positioned relative to this one, like
+    Godot's parent/child nodes. A child's `position` is added to its
+    parent's (scaled by the parent's own `scale`), and `scale` / `modulate`
+    / `layer` all compose down the tree — a child's effective scale is the
+    parent's times its own, `modulate` multiplies the same way, and
+    `layer` adds (relative to the parent's, matching Godot's default: a
+    deeply-nested child can still end up drawn in front of an unrelated
+    top-level renderable if its accumulated layer says so). A child is a
+    full `Renderable`, so it can have its own `id` / `isClickable` / even
+    its own `children`. `screenSpace: true` makes a renderable (and its
+    whole subtree) ignore the camera below and stay fixed to the screen —
+    for UI/HUD that shouldn't pan or zoom with the game world.
+- **Camera** — pass `camera: (state) => ({ x, y, zoom })` to `runEngine` to
+  pan/zoom every world-space renderable (anything without
+  `screenSpace: true`) as a group, the same way a `GROUP` parent works for
+  its children — `{ x, y }` is the world position mapped to canvas
+  `(0, 0)`, and `zoom` scales everything around that same point. It's a
+  function of state, so the camera can follow something or react to a
+  zoom level you're tracking yourself.
+- **Events** — your `nextState` function receives one `GameEvent` per call:
+  `TIME` (frame tick with `delta`), `CLICK`, `HOVER_IN`, `HOVER_OUT`, or
+  `MOUSE_MOVE`. The mouse-carrying ones include both `mouse` (raw canvas
+  pixels — use for `screenSpace`/UI logic) and `worldMouse` (that same
+  position run through the camera's inverse transform — use to
+  place/locate world-space things, e.g. build a turret where the player
+  clicked). With no `camera` set, `worldMouse` always equals `mouse`.
+- **Keyboard** — `nextState` also receives a `keyboard` map keyed by
+  `KeyCode`-style keys (e.g. `"KeyW"`, `"ArrowLeft"`, `"Space"`), each with
+  `isPressed` / `isJustPressed` / `isJustReleased`.
+- **Sprites** — pass a `resources` map of `{ src, size, slices }` to
+  `runEngine` to load spritesheets, then reference them by id with a
+  `SPRITE` renderable's `resourceId` and `frame`. Set `flipX: true` to
+  mirror a sprite horizontally — useful when the art is drawn facing one
+  direction but needs to move the other way. Add an `animations` map to a
+  resource — `{ frames: number[], frameDuration, loop }` each — to play
+  one with `ANIMATED_SPRITE` instead of managing `frame` by hand.
+- **Sound effects** — pass a `sounds` map of `{ src }` to `runEngine`, then
+  call the `playSound(id)` function `nextState` receives to play one, e.g.
+  `playSound("collect")` when a cookie is clicked. Calling it again while
+  a sound is still playing overlaps a new copy instead of cutting the
+  first one off.
+- **Music** — pass a `music` map of `{ src }` to `runEngine`, then use the
+  `playMusic(id)` / `pauseMusic()` functions `nextState` receives to
+  control a looping background track. Unlike `playSound`, only one track
+  plays at a time and it keeps running in the background across frames
+  instead of firing once; `pauseMusic()` leaves it where it stopped, so
+  calling `playMusic(id)` again resumes it instead of starting over.
+- **Canvas** — pass `canvas: { width, height, backgroundColor }` to
+  `runEngine` to size and color the canvas from code. All three are
+  optional; anything you don't set falls back to the canvas element's
+  existing HTML/CSS.
+- **Mechanics** — `nextState` can also be an array of small
+  `NextStateFunction`s instead of one big function. Each one is run in
+  order for every event, and can return:
+  - a new state, to update to
+  - `undefined` (or no `return` at all) — no change, but the rest of the
+    list still runs, so a guard can just be `if (...) return;`
+  - `STOP` (imported from `yuuna-engine`) — no change, and the rest of
+    the list is skipped for this event, so a shared rule (like "nothing
+    happens once the game is over") only needs to be written once
+
+  ```ts
+  import { runEngine, STOP, type NextStateFunction } from "yuuna-engine";
+
+  const freezeOnGameOver: NextStateFunction<GameState> = ({ state }) => {
+    if (state.lives <= 0) return STOP;
+  };
+
+  const moveEnemies: NextStateFunction<GameState> = ({ state, event }) => {
+    if (event.tag === "TIME") {
+      return { ...state, enemies: move(state.enemies, event.delta) };
+    }
+  };
+
+  runEngine<GameState>({
+    initialState,
+    render,
+    nextState: [freezeOnGameOver, moveEnemies /* ... */],
+  });
+  ```
+
+## 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.
+
+## License
+
+MIT © [lucy-dot-exe](https://github.com/lucy-dot-exe)

package/lib/engine/types.d.ts

@@ -1,4 +1,18 @@
-export type RectangleRenderable = {
+type BaseRenderable = {
+    layer?: number;
+    scale?: {
+        x: number;
+        y: number;
+    };
+    modulate?: string;
+    children?: Renderable[];
+    screenSpace?: boolean;
+    id?: string;
+    isClickable?: boolean;
+    isHoverable?: boolean;
+    trackMouseMovement?: boolean;
+};
+export type RectangleRenderable = BaseRenderable & {
     type: "RECTANGLE";
     position: {
         x: number;
@@ -9,12 +23,8 @@ export type RectangleRenderable = {
         height: number;
     };
     color: string;
-    id?: string;
-    isClickable?: boolean;
-    isHoverable?: boolean;
-    trackMouseMovement?: boolean;
 };
-export type CircleRenderable = {
+export type CircleRenderable = BaseRenderable & {
     type: "CIRCLE";
     position: {
         x: number;
@@ -22,12 +32,8 @@ export type CircleRenderable = {
     };
     radius: number;
     color: string;
-    id?: string;
-    isClickable?: boolean;
-    isHoverable?: boolean;
-    trackMouseMovement?: boolean;
 };
-export type TextRenderable = {
+export type TextRenderable = BaseRenderable & {
     type: "TEXT";
     text: string;
     color: string;
@@ -39,12 +45,9 @@ export type TextRenderable = {
         x: "left" | "center" | "right";
         y: "bottom" | "middle" | "top";
     };
-    id?: string;
-    isClickable?: boolean;
-    isHoverable?: boolean;
-    trackMouseMovement?: boolean;
+    fontSize?: number;
 };
-export type SpriteRenderable = {
+export type SpriteRenderable = BaseRenderable & {
     type: "SPRITE";
     position: {
         x: number;
@@ -52,15 +55,10 @@ export type SpriteRenderable = {
     };
     resourceId: string;
     frame: number;
-    scale?: number;
     opacity?: number;
     flipX?: boolean;
-    id?: string;
-    isClickable?: boolean;
-    isHoverable?: boolean;
-    trackMouseMovement?: boolean;
 };
-export type LineRenderable = {
+export type LineRenderable = BaseRenderable & {
     type: "LINE";
     from: {
         x: number;
@@ -72,12 +70,29 @@ export type LineRenderable = {
     };
     color: string;
     width?: number;
-    id?: string;
-    isClickable?: boolean;
-    isHoverable?: boolean;
-    trackMouseMovement?: boolean;
 };
-export type Renderable = RectangleRenderable | CircleRenderable | SpriteRenderable | TextRenderable | LineRenderable;
+export type AnimatedSpriteRenderable = BaseRenderable & {
+    type: "ANIMATED_SPRITE";
+    position: {
+        x: number;
+        y: number;
+    };
+    resourceId: string;
+    animation: string;
+    timeScale?: number;
+    paused?: boolean;
+    opacity?: number;
+    flipX?: boolean;
+    id: string;
+};
+export type GroupRenderable = BaseRenderable & {
+    type: "GROUP";
+    position: {
+        x: number;
+        y: number;
+    };
+};
+export type Renderable = RectangleRenderable | CircleRenderable | SpriteRenderable | TextRenderable | LineRenderable | GroupRenderable | AnimatedSpriteRenderable;
 export type TimeEvent = {
     tag: "TIME";
     delta: number;
@@ -89,6 +104,10 @@ export type ClickEvent = {
         x: number;
         y: number;
     };
+    worldMouse: {
+        x: number;
+        y: number;
+    };
 };
 export type HoverInEvent = {
     tag: "HOVER_IN";
@@ -97,6 +116,10 @@ export type HoverInEvent = {
         x: number;
         y: number;
     };
+    worldMouse: {
+        x: number;
+        y: number;
+    };
 };
 export type HoverOutEvent = {
     tag: "HOVER_OUT";
@@ -105,6 +128,10 @@ export type HoverOutEvent = {
         x: number;
         y: number;
     };
+    worldMouse: {
+        x: number;
+        y: number;
+    };
 };
 export type MouseMoveEvent = {
     tag: "MOUSE_MOVE";
@@ -113,6 +140,10 @@ export type MouseMoveEvent = {
         x: number;
         y: number;
     };
+    worldMouse: {
+        x: number;
+        y: number;
+    };
 };
 export type GameEvent = TimeEvent | ClickEvent | HoverInEvent | HoverOutEvent | MouseMoveEvent;
 export type NextStateProps<State> = {
@@ -123,6 +154,9 @@ export type NextStateProps<State> = {
         isJustPressed: boolean;
         isJustReleased: boolean;
     }>;
+    playSound: (id: string) => void;
+    playMusic: (id: string) => void;
+    pauseMusic: () => void;
 };
 export declare const STOP: "Yuuna.STOP";
 export type NextStateFunction<State> = (props: NextStateProps<State>) => State | typeof STOP | undefined;
@@ -143,12 +177,28 @@ export type RunEngineProps<State> = {
             vertical: number;
             horizontal: number;
         };
+        animations?: Record<string, {
+            frames: number[];
+            frameDuration: number;
+            loop: boolean;
+        }>;
+    }>;
+    sounds?: Record<string, {
+        src: string;
+    }>;
+    music?: Record<string, {
+        src: string;
     }>;
     canvas?: {
         width?: number;
         height?: number;
         backgroundColor?: string;
     };
+    camera?: (state: State) => {
+        x: number;
+        y: number;
+        zoom: number;
+    };
 };
 export type RunEngineFunction = <State>(props: RunEngineProps<State>) => 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"];
@@ -158,3 +208,4 @@ export declare var Yuuna: {
     runEngine: RunEngineFunction;
     STOP: typeof STOP;
 };
+export {};