js-game-zero 0.0.0-placeholder → 0.3.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Taha Rafiq
+Copyright (c) 2001 Robert Penner (easing equations)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,7 +1,139 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Leaf-Learning/js-game-zero/main/docs/media/logo-lockup-dark.svg">
+  <img src="https://raw.githubusercontent.com/Leaf-Learning/js-game-zero/main/docs/media/logo-lockup-light.svg" alt="js-game-zero" width="280">
+</picture>
+
 # js-game-zero
 
-This version only holds the package name. Install 0.3.0 or later:
+A framework that teaches beginners to build browser games in JavaScript, with
+as little boilerplate as possible, in the spirit of
+[Pygame Zero](https://github.com/lordmauve/pgzero). Declare `WIDTH` and
+`HEIGHT`, write a `draw()` function, and you have a game window: no build
+step, no canvas setup, no game loop to write. Actors, drawing, geometry,
+input, animation, sound and storage are all there.
+
+```js
+WIDTH = 480;
+HEIGHT = 360;
+
+let ship = new Actor("player.svg", { midBottom: [240, 350] });
+
+function update(dt) {
+  if (keyboard.left) ship.x -= 220 * dt;
+  if (keyboard.right) ship.x += 220 * dt;
+}
+
+function draw() {
+  screen.fill("#0b1220", "#132a43");
+  ship.draw();
+}
+```
+
+```sh
+bun add js-game-zero
+# or
+npm install js-game-zero
+```
+
+## Use
+
+`run()` takes a game's source as a string and runs it with the framework's
+globals (`Actor`, `screen`, `keyboard`, `clock` and the rest) in its own scope:
+
+```js
+import { run } from "js-game-zero";
+
+run(`
+  WIDTH = 320;
+  HEIGHT = 180;
+  function draw() { screen.fill("navy"); }
+`);
+```
+
+For a game written as an ordinary module with imports, `defineGame()` gives it
+its own set of services, so two games on one page never share state:
+
+```ts
+import { defineGame, run } from "js-game-zero";
+
+run(
+  defineGame(({ Actor, screen, keyboard }) => {
+    const player = new Actor("player.svg");
+    return {
+      WIDTH: 320,
+      HEIGHT: 180,
+      update(dt) {
+        if (keyboard.right) player.x += 120 * dt;
+      },
+      draw() {
+        screen.clear();
+        player.draw();
+      },
+    };
+  }),
+);
+```
+
+`run()` also takes a plain object of hooks.
+
+## Script tag
+
+`js-game-zero/iife` (the file `dist/jgz.js`) is one self-contained script for
+pages with no bundler. It puts the whole API on `window.JGZ`, with the host
+APIs a page needs to start, drive and read a game it runs: `loadImages`,
+`getGameInspector`, `serializeGameValue`, `parseStatePath` and
+`createSeededRandom`.
+
+Load it from a CDN such as jsDelivr, or copy the file next to your page.
+`JGZ.run` adds the game's canvas to the page's `<body>`:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/js-game-zero@0.3/dist/jgz.js"></script>
+<script>
+  JGZ.run(`
+    WIDTH = 320;
+    HEIGHT = 180;
+    function draw() { screen.fill("navy"); }
+  `);
+</script>
+```
+
+Problems with the game, from a misspelled name to an image that won't load,
+go to the browser console, or to a `diagnostics` callback if you pass one. A
+game that fails stops, and its canvas is removed. [Getting
+started](https://github.com/Leaf-Learning/js-game-zero/blob/main/docs/getting-started.md#a-game-in-one-web-page)
+has a complete page that shows them on the page, with images and sounds.
+
+In TypeScript, `/// <reference types="js-game-zero/iife" />` declares
+`window.JGZ`.
+
+The file opens with its license notice, so a page that inlines it carries it.
+
+## Entry points
+
+| Import                             | What it holds                                                                                                         |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `js-game-zero`                     | The game API: `run`, `defineGame`, `Actor`, `Rect`, `screen`, `keyboard`, `clock`, `animate`, `storage` and the rest. |
+| `js-game-zero/host`                | For pages and tools that embed games: asset loaders, browser adapters, the game inspector and the value serialiser.   |
+| `js-game-zero/node`                | A file-system storage adapter for sandbox projects, under Node or Bun.                                                |
+| `js-game-zero/iife`                | The script-tag build, `dist/jgz.js`, which puts the API on `window.JGZ`.                                              |
+| `js-game-zero/reference`           | The API reference: `reference`, every page's Markdown by its file name (`reference["actor.md"]`).                     |
+| `js-game-zero/reference/<page>.md` | Each reference page as a Markdown file.                                                                               |
+
+To test a game from the terminal, press its keys and read its state, there's
+the [`jgz` CLI](https://www.npmjs.com/package/@js-game-zero/cli).
+
+## Docs
+
+- [Tutorial](https://github.com/Leaf-Learning/js-game-zero/blob/main/docs/tutorial.md):
+  build a complete game step by step.
+- [API reference](https://github.com/Leaf-Learning/js-game-zero/tree/main/docs/reference):
+  every symbol, with a signature, an explanation and an example. The
+  [runtime page](https://github.com/Leaf-Learning/js-game-zero/blob/main/docs/reference/runtime.md)
+  covers `run()`, its options and embedding games in a host page.
+- [Cookbook](https://github.com/Leaf-Learning/js-game-zero/blob/main/docs/cookbook.md):
+  short recipes for specific tasks.
 
-    npm install js-game-zero
+## License
 
-https://github.com/Leaf-Learning/js-game-zero
+MIT. See [LICENSE](LICENSE).

package/dist/active-service.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Well-known brand answered by every active-service proxy's `get` trap.
+ * Lets callers (e.g. `RunOptions` resolvers) detect "this is the ambient
+ * public export" and treat it as "use the default" instead of installing it
+ * as its own backing target, which would otherwise resolve back to itself
+ * and recurse infinitely.
+ */
+export declare const activeServiceProxyBrand: unique symbol;
+/** True when `value` is a proxy created by {@link createActiveServiceProxy}. */
+export declare function isActiveServiceProxy(value: unknown): boolean;
+/**
+ * Creates the process-level compatibility proxy used by learner-facing
+ * singleton services. Runtime callbacks choose the active run-scoped target;
+ * property access outside a callback falls back through `getActive`.
+ *
+ * Keeping the complete proxy behavior here prevents clock, input, audio,
+ * rendering, and storage from drifting apart as new reflective operations are
+ * added. Methods are bound to the resolved target so private fields and class
+ * receivers continue to work through the proxy.
+ */
+export declare function createActiveServiceProxy<T extends object>(getActive: () => T): T;

package/dist/actor.d.ts

@@ -0,0 +1,182 @@
+import { type AssetLoader, type SurfaceLike } from "./assets.js";
+import { type Clock } from "./clock.js";
+import { Rect, type Point, type RectLike } from "./geometry.js";
+import { type Screen } from "./rendering.js";
+export type ActorAnchor = readonly [
+    HorizontalActorAnchor | number,
+    VerticalActorAnchor | number
+];
+export type HorizontalActorAnchor = "left" | "center" | "middle" | "right";
+export type VerticalActorAnchor = "top" | "center" | "middle" | "bottom";
+export type ActorPositionKey = "pos" | "topLeft" | "topRight" | "bottomLeft" | "bottomRight" | "midTop" | "midLeft" | "midRight" | "midBottom" | "center";
+export type ActorOptions = Partial<Record<ActorPositionKey, Point>> & {
+    readonly anchor?: ActorAnchor;
+    readonly angle?: number;
+    readonly opacity?: number;
+    /** Draw the image at this multiple of its native size (hitbox follows). */
+    readonly scale?: number;
+    /** Draw the image this many pixels wide, keeping its proportions. */
+    readonly width?: number;
+    /** Draw the image this many pixels tall, keeping its proportions. */
+    readonly height?: number;
+    /** Pictures to cycle through, in order, as a flip-book animation. */
+    readonly images?: readonly string[];
+    /** How many pictures of `images` to show per second (default 10). */
+    readonly fps?: number;
+    /** Whether `images` starts over after the last picture (default true). */
+    readonly loop?: boolean;
+    /** The clock whose time drives `images` (the running game's by default). */
+    readonly clock?: Pick<Clock, "now">;
+    readonly screen?: Screen;
+    readonly loader?: Pick<AssetLoader<SurfaceLike>, "load" | "get" | "unload">;
+    readonly imageLoader?: Pick<AssetLoader<SurfaceLike>, "load" | "get" | "unload">;
+};
+export declare class Actor {
+    private readonly loader;
+    private readonly screen?;
+    private _image;
+    private _surface;
+    private _pos;
+    private _anchor;
+    private _angle;
+    private _opacity;
+    private _scale;
+    /** The native image, before inflateIp/normalize wrap the hitbox size. */
+    private _native;
+    private sizeSource;
+    private positionSource;
+    private imageLoadPromise;
+    private _images;
+    private _fps;
+    private _loop;
+    /** Clock time when `images` was last set; frame 0 starts here. */
+    private animationStart;
+    private readonly clockSource;
+    constructor(image: string, pos?: Point | ActorOptions, options?: ActorOptions);
+    get image(): string;
+    set image(value: string);
+    /**
+     * Pictures to cycle through like a flip book, `fps` per second, using the
+     * game's clock (so the animation pauses with the game). Setting it starts
+     * from the first picture and loads the rest; `null` stops animating.
+     */
+    get images(): string[] | null;
+    set images(value: readonly string[] | null);
+    /** Pictures per second for `images`. */
+    get fps(): number;
+    set fps(value: number);
+    /** Whether `images` starts over after the last picture. */
+    get loop(): boolean;
+    set loop(value: boolean);
+    /** Which picture of `images` is showing (0 for the first). */
+    get frame(): number;
+    /** True once a non-looping `images` animation has shown its last picture. */
+    get finished(): boolean;
+    private elapsedFrames;
+    private now;
+    get pos(): Point;
+    set pos(value: Point);
+    get x(): number;
+    set x(value: number);
+    get y(): number;
+    set y(value: number);
+    get anchor(): ActorAnchor;
+    set anchor(value: ActorAnchor);
+    get angle(): number;
+    set angle(value: number);
+    get opacity(): number;
+    set opacity(value: number);
+    /**
+     * Size multiplier applied when drawing: `2` doubles the sprite, `0.5`
+     * halves it. The hitbox and every position property follow the drawn
+     * size, and the anchored position (a `midBottom` on the floor) stays put.
+     */
+    get scale(): number;
+    set scale(value: number);
+    /** The current (possibly rotated) bounding-box width. Setting it resizes
+     * the sprite to that width, keeping its proportions (like `scale`). */
+    get width(): number;
+    set width(value: number);
+    get height(): number;
+    set height(value: number);
+    get topLeft(): Point;
+    set topLeft(value: Point);
+    get topRight(): Point;
+    set topRight(value: Point);
+    get bottomLeft(): Point;
+    set bottomLeft(value: Point);
+    get bottomRight(): Point;
+    set bottomRight(value: Point);
+    get midTop(): Point;
+    set midTop(value: Point);
+    get midLeft(): Point;
+    set midLeft(value: Point);
+    get midRight(): Point;
+    set midRight(value: Point);
+    get midBottom(): Point;
+    set midBottom(value: Point);
+    get center(): Point;
+    set center(value: Point);
+    get left(): number;
+    set left(value: number);
+    get top(): number;
+    set top(value: number);
+    get right(): number;
+    set right(value: number);
+    get bottom(): number;
+    set bottom(value: number);
+    ready(): Promise<SurfaceLike>;
+    rect(): Rect;
+    draw(screen?: Screen): void;
+    unloadImage(): void;
+    angleTo(target: Actor | Point): number;
+    distanceTo(target: Actor | Point): number;
+    copy(): Rect;
+    move(x: number, y: number): Rect;
+    move(offset: Point): Rect;
+    moveIp(x: number, y: number): void;
+    moveIp(offset: Point): void;
+    inflate(x: number, y: number): Rect;
+    inflate(size: Point): Rect;
+    inflateIp(x: number, y: number): void;
+    inflateIp(size: Point): void;
+    normalize(): void;
+    clamp(other: RectLike): Rect;
+    /**
+     * Moves the actor (without resizing it) so its bounding box fits inside
+     * `other` — `player.clampIp(screen.bounds())` keeps it on screen.
+     */
+    clampIp(other: RectLike): void;
+    clip(other: RectLike): Rect;
+    union(other: RectLike): Rect;
+    unionAll(others: RectLike[]): Rect;
+    fit(other: RectLike): Rect;
+    collidePoint(point: Point): boolean;
+    collidePoint(x: number, y: number): boolean;
+    /**
+     * True when the actor overlaps `target`: another actor, a rect, or an
+     * `[x, y]` point such as a click position.
+     */
+    touches(target: Actor | RectLike | Point): boolean;
+    collideRect(other: RectLike): boolean;
+    collideList(others: RectLike[]): number;
+    collideListAll(others: RectLike[]): number[];
+    contains(other: RectLike): boolean;
+    private baseRect;
+    private surfaceWidth;
+    private surfaceHeight;
+    private adoptSurface;
+    /** Turns the requested size (scale, width or height) into `_scale` once
+     * the native image size is known, then re-applies the anchored position
+     * so the actor stays where the learner put it. */
+    private applySizeSource;
+    private setRectPosition;
+    /** Moves the actor so `rect()` becomes `rect`, a moved copy of it. */
+    private setPosFromRect;
+    private applyBaseRectGeometry;
+    private applyPositionSource;
+    /** Where `pos` is from the top-left of `rect()`: the anchor offset, unless
+     * the actor is rotated and its bounding box isn't the base rect. */
+    private rectOffset;
+    private anchorOffset;
+}

package/dist/animation.d.ts

@@ -0,0 +1,61 @@
+import { Clock } from "./clock.js";
+export type TweenName = keyof typeof tweens;
+export type AnimationOptions<T extends object> = Partial<Record<keyof T, unknown>> & {
+    tween?: TweenName | string;
+    duration?: number;
+    onFinished?: () => void;
+};
+export declare const tweens: Readonly<{
+    linear(n: number): number;
+    accelerate(n: number): number;
+    decelerate(n: number): number;
+    accelDecel(n: number): number;
+    inElastic(n: number): number;
+    outElastic(n: number): number;
+    inOutElastic(n: number): number;
+    bounceEnd(n: number): number;
+    bounceStart(n: number): number;
+    bounceStartEnd(n: number): number;
+    endElastic(n: number): number;
+    startElastic(n: number): number;
+    bothElastic(n: number): number;
+    easeIn(n: number): number;
+    easeOut(n: number): number;
+    easeInOut(n: number): number;
+    bounce(n: number): number;
+    spring(n: number): number;
+}>;
+export declare const tweenNames: readonly ("linear" | "accelerate" | "decelerate" | "accelDecel" | "inElastic" | "outElastic" | "inOutElastic" | "bounceEnd" | "bounceStart" | "bounceStartEnd" | "endElastic" | "startElastic" | "bothElastic" | "easeIn" | "easeOut" | "easeInOut" | "bounce" | "spring")[];
+export declare class Animation<T extends object = object> {
+    onFinished: (() => void) | undefined;
+    readonly object: T;
+    readonly duration: number;
+    readonly tween: TweenName;
+    private elapsed;
+    private targetValues;
+    private initialValues;
+    private readonly scheduler;
+    private readonly tickCallback;
+    private _running;
+    constructor(object: T, options: AnimationOptions<T>, scheduler?: Clock);
+    get running(): boolean;
+    update(dt: number): void;
+    stop(complete?: boolean): void;
+    removeTarget(property: string, stopIfEmpty?: boolean): void;
+    private completeNaturally;
+    private apply;
+}
+export declare class ValueError extends Error {
+    constructor(message: string);
+}
+export declare function animate<T extends object>(object: T, options: AnimationOptions<T>): Animation<T>;
+/**
+ * `Animation` and `animate` as a game's code gets them: they run on the
+ * game's own clock wherever they're called, so one started outside a hook,
+ * as in a promise callback, doesn't go to a clock that never ticks.
+ */
+export declare function animationsOn(scheduler: Clock): {
+    readonly Animation: typeof Animation;
+    readonly animate: typeof animate;
+};
+export declare function withAnimationClock<T>(scheduler: Clock, callback: () => T): T;

package/dist/assets.d.ts

@@ -0,0 +1,148 @@
+import { Rect, type Point, type RectLike } from "./geometry.js";
+export type AssetKind = "image" | "sound" | "music" | "font";
+/**
+ * A game's assets by path (`images/cat.svg`, `sounds/pop.wav`), each with
+ * the URL to load it from, such as a data URL. When a run is given one, its
+ * assets come only from here, so a page needs no asset server.
+ */
+export type AssetUrls = Readonly<Record<string, string>>;
+export type AssetLoadOptions<T> = {
+    readonly kind: AssetKind;
+    readonly directory: string;
+    readonly extensions: readonly string[];
+    readonly projectId?: string;
+    readonly assetBaseUrl?: string;
+    /** Where each asset is, by path; when set, `assetBaseUrl` isn't used. */
+    readonly assetUrls?: AssetUrls;
+    readonly loadAsset?: (url: string, name: string) => Promise<T>;
+};
+export type AssetLoaderOptions<T> = Partial<Omit<AssetLoadOptions<T>, "kind" | "directory" | "extensions">>;
+export type DrawableImage = CanvasImageSource & {
+    readonly width?: number;
+    readonly height?: number;
+    readonly naturalWidth?: number;
+    readonly naturalHeight?: number;
+};
+export type SurfaceRectOptions = Partial<Record<PositionKey, Point>>;
+export interface SurfaceLike {
+    readonly source: DrawableImage;
+    getWidth(): number;
+    getHeight(): number;
+    getSize(): Point;
+    getRect(options?: SurfaceRectOptions): Rect;
+}
+export type LoadedAsset = {
+    readonly kind: AssetKind;
+    readonly name: string;
+    readonly url: string;
+    readonly bytes?: ArrayBuffer;
+};
+export type SoundAsset = LoadedAsset & {
+    play(loops?: number): void;
+    /** Plays the sound over and over until `stop()`. */
+    loop(): void;
+    stop(): void;
+    getLength(): number;
+    setVolume(volume: number): void;
+    getVolume(): number;
+};
+export type MusicAsset = LoadedAsset;
+export type FontAsset = LoadedAsset & {
+    readonly family: string;
+    readonly face?: FontFace;
+};
+export type AssetLoader<T> = {
+    readonly kind: AssetKind;
+    readonly projectId: string;
+    readonly assetBaseUrl: string;
+    /** The asset map this loader reads instead of `assetBaseUrl`, if it was given one. */
+    readonly assetUrls?: AssetUrls | undefined;
+    readonly extensions: readonly string[];
+    readonly directory: string;
+    load(name: string): Promise<T>;
+    get(name: string): T | undefined;
+    has(name: string): boolean;
+    define(name: string, asset: T): T;
+    unload(name: string): boolean;
+    unloadAll(): void;
+    cacheKeys(): string[];
+    /**
+     * Number of loads currently in flight (started but not yet settled).
+     * Used by the runtime's preload gate to hold frames until assets that
+     * were requested during module evaluation (or mid-game) have resolved.
+     */
+    pendingCount(): number;
+    /**
+     * Resolves once there are no in-flight loads, or rejects with failures
+     * settled since the previous idle wait. Re-checks after each settle so
+     * loads triggered while waiting are also awaited.
+     */
+    waitForIdle(): Promise<void>;
+};
+export type AssetLoaders = {
+    images: AssetLoader<SurfaceLike>;
+    sounds: AssetLoader<SoundAsset>;
+    music: AssetLoader<MusicAsset>;
+    fonts: AssetLoader<FontAsset>;
+};
+type PositionKey = "topLeft" | "topRight" | "bottomLeft" | "bottomRight" | "midTop" | "midLeft" | "midRight" | "midBottom" | "center";
+export declare class MissingAssetError extends Error {
+    readonly kind: AssetKind;
+    readonly assetName: string;
+    readonly attemptedUrls: readonly string[];
+    constructor(kind: AssetKind, name: string, options?: {
+        readonly attemptedUrls?: readonly string[];
+        readonly cause?: unknown;
+        /** Why a file that's there couldn't be loaded, when that's known. */
+        readonly why?: string;
+    });
+}
+export declare class InvalidAssetNameError extends TypeError {
+    constructor(kind: AssetKind, name: string, reason: string);
+}
+export declare class ImageSurface implements SurfaceLike {
+    readonly source: DrawableImage;
+    private readonly width;
+    private readonly height;
+    constructor(source: DrawableImage, width?: number, height?: number);
+    getWidth(): number;
+    getHeight(): number;
+    getSize(): Point;
+    getRect(options?: SurfaceRectOptions): Rect;
+}
+export declare function createImageLoader(options?: AssetLoaderOptions<SurfaceLike>): AssetLoader<SurfaceLike>;
+/**
+ * Decodes every image in an asset map, by name under `images/`, for
+ * `RunOptions.preloadedAssets`. `run()` starts a game's code at once, so an
+ * image the run loads itself has no size yet while the top level runs: an
+ * Actor placed by `midBottom` and then moved lands as if it were 0×0.
+ * Images handed over decoded are ready from the first line, as Pygame
+ * Zero's are. One that fails to decode is left out, so the run loads it
+ * itself and reports the failure only if the game uses it.
+ */
+export declare function loadImages(assetUrls: AssetUrls): Promise<Record<string, SurfaceLike>>;
+export declare function createSoundLoader(options?: AssetLoaderOptions<SoundAsset>): AssetLoader<SoundAsset>;
+export declare function createMusicLoader(options?: AssetLoaderOptions<MusicAsset>): AssetLoader<MusicAsset>;
+export declare function createFontLoader(options?: AssetLoaderOptions<FontAsset>): AssetLoader<FontAsset>;
+export declare function createAssetLoaders(options?: {
+    readonly projectId?: string;
+    readonly assetBaseUrl?: string;
+    readonly assetUrls?: AssetUrls;
+}): AssetLoaders;
+export declare function validateAssetName(kind: AssetKind, name: string, extensions: readonly string[]): string;
+export declare function assetUrl(assetBaseUrl: string, projectId: string, directory: string, name: string): string;
+/** Where a loader finds the asset with this exact name, or undefined when its asset map doesn't list it. */
+export declare function locateAsset(loader: {
+    readonly assetBaseUrl: string;
+    readonly assetUrls?: AssetUrls | undefined;
+    readonly projectId: string;
+    readonly directory: string;
+}, name: string): string | undefined;
+export declare const defaultAssetLoaders: AssetLoaders;
+export declare function setActiveAssetLoaders(loaders: AssetLoaders | null): AssetLoaders | null;
+export declare const images: AssetLoader<SurfaceLike>;
+export declare const sounds: AssetLoader<SoundAsset>;
+export declare const musicAssets: AssetLoader<LoadedAsset>;
+export declare const fonts: AssetLoader<FontAsset>;
+export declare function rectFromBlitTarget(target: Point | RectLike): Rect | Point;
+export {};