js-game-zero 0.0.0-stage → 0.4.0

package/dist/clock.d.ts

@@ -0,0 +1,29 @@
+type ClockCallback = () => void;
+type TickCallback = (dt: number) => void;
+export type ClockOptions = {
+    /** Receives callback failures after the failing callback is unscheduled. */
+    readonly onError?: (error: unknown) => void;
+};
+export declare class Clock {
+    private readonly options;
+    private time;
+    private nextOrder;
+    private scheduled;
+    private active;
+    private tickCallbacks;
+    constructor(options?: ClockOptions);
+    schedule(callback: ClockCallback, delay: number): void;
+    scheduleUnique(callback: ClockCallback, delay: number): void;
+    scheduleInterval(callback: ClockCallback, interval: number): void;
+    unschedule(callback: Function): void;
+    eachTick(callback: TickCallback): void;
+    clear(): void;
+    tick(dt: number): void;
+    now(): number;
+    private nextDueEvent;
+    private reportCallbackError;
+}
+export declare function setActiveClock(nextClock: Clock | null): Clock | null;
+export declare function getActiveClock(): Clock;
+export declare const clock: Clock;
+export {};

package/dist/color.d.ts

@@ -0,0 +1,15 @@
+export type Color = string | readonly [number, number, number] | readonly [number, number, number, number];
+/**
+ * Turns a color into a canvas style string. A canvas silently ignores a
+ * color it can't read and keeps drawing with the previous one, so anything
+ * that isn't a recognizable color fails here, with a suggestion.
+ */
+export declare function normalizeColor(color: Color): string;
+/**
+ * A color mixed from red, green and blue light, each 0 to 255, with an
+ * optional alpha from 0 (invisible) to 255 (solid). It returns the matching
+ * list, so it works anywhere a color does, but `rgb(255, 140, 105)` reads
+ * plainly to learners who haven't met lists yet.
+ */
+export declare function rgb(red: number, green: number, blue: number, alpha?: number): [number, number, number] | [number, number, number, number];
+export declare function verticalGradient(context: CanvasRenderingContext2D, top: number, height: number, color: Color, gcolor: Color): CanvasGradient;

package/dist/events.d.ts

@@ -0,0 +1,145 @@
+import { type Point } from "./geometry.js";
+import { KeyboardState, MouseState } from "./input.js";
+type HookArgs = Record<string, unknown>;
+/**
+ * A hook a game defines. Its arguments are matched by parameter name, in
+ * whatever order the game declares them (see the hooks reference), so their
+ * types can't be given by position: `onKeyDown(key: number, mod: number)`
+ * and `onKeyDown(mod: number)` both fit.
+ */
+export type Hook = (...args: any[]) => void;
+export type InputHooks = {
+    onMouseDown?: Hook;
+    onMouseUp?: Hook;
+    onMouseMove?: Hook;
+    onKeyDown?: Hook;
+    onKeyUp?: Hook;
+    onMusicEnd?: Hook;
+};
+export type BrowserKeyboardLike = {
+    code?: string;
+    key?: string;
+    shiftKey?: boolean;
+    ctrlKey?: boolean;
+    altKey?: boolean;
+    metaKey?: boolean;
+    repeat?: boolean;
+    getModifierState?: (key: string) => boolean;
+};
+export type BrowserMouseLike = {
+    clientX: number;
+    clientY: number;
+    button?: number;
+    buttons?: number;
+    movementX?: number;
+    movementY?: number;
+};
+export type BrowserWheelLike = {
+    clientX: number;
+    clientY: number;
+    deltaY: number;
+    buttons?: number;
+};
+type TargetBounds = {
+    left: number;
+    top: number;
+    width?: number;
+    height?: number;
+};
+type BoundsTarget = {
+    /**
+     * Logical screen size (the game's WIDTH/HEIGHT; the runtime passes its
+     * screen's, since pixel density multiplies `canvas.width`). When the
+     * canvas is displayed at a different CSS size (e.g. the sandbox preview
+     * scales it to fit its pane), positions are mapped back into game
+     * coordinates so `pos` always matches what the game draws with.
+     */
+    width?: number;
+    height?: number;
+    ownerDocument?: EventTarget & {
+        readonly hidden?: boolean;
+        readonly visibilityState?: string;
+    };
+    getBoundingClientRect?: () => TargetBounds;
+};
+export type MappedKeyboardEvent = {
+    key: number;
+    mod: number;
+    unicode: string;
+    repeat: boolean;
+};
+export type MappedMouseEvent = {
+    pos: Point;
+    button: number | null;
+    buttons: Set<number>;
+    rel: Point;
+};
+/** Every input hook a game can define, besides `draw` and `update`. */
+export declare const INPUT_HOOK_NAMES: readonly ["onMouseDown", "onMouseUp", "onMouseMove", "onKeyDown", "onKeyUp", "onMusicEnd"];
+export type InputHookName = (typeof INPUT_HOOK_NAMES)[number];
+/**
+ * The values each input hook can receive, in the order an ordinary
+ * (positional) reading of its parameter list hands them out.
+ */
+export declare const HOOK_PARAMETERS: Readonly<Record<InputHookName, readonly string[]>>;
+/**
+ * Calls `handler` with the values from `args` its parameters ask for. A
+ * parameter named like a value (`pos`, `key`, `mod`, ...) receives that
+ * value wherever it sits in the list, Pygame Zero style. Any other name
+ * receives the next value in `order` not already claimed by name, the way an
+ * ordinary JavaScript function would — so `onKeyDown(k)` still gets the
+ * key. A lone `event` parameter receives the whole `args` object.
+ */
+export declare function dispatchHook(handler: Hook | undefined, args: HookArgs, order?: readonly string[]): void;
+/** Marks `handler` to receive the whole event object, as `event` would. */
+export declare function markWholeEventHook<T extends Function>(handler: T): T;
+/** Whether `handler` receives the whole event object: it was marked, or its
+ * one parameter is called `event`. */
+export declare function takesWholeEvent(handler: Function): boolean;
+/**
+ * Which value each declared parameter receives: its own name when that is a
+ * known value, otherwise the next known value not claimed by name.
+ */
+export declare function resolveHookParameters(declared: readonly string[], known: readonly string[]): (string | undefined)[];
+export declare function getParameterNames(callback: Function): string[];
+export declare function mapBrowserKeyEvent(event: BrowserKeyboardLike): MappedKeyboardEvent | null;
+export declare function mapBrowserMouseEvent(event: BrowserMouseLike, target?: BoundsTarget, previousPos?: Point | null): MappedMouseEvent;
+export declare function mapBrowserMouseButton(button: number | undefined): number | null;
+/**
+ * Maps a native `wheel` DOM event to a mouse-down-shaped event, matching
+ * pygame's convention of reporting scroll wheel motion as button 4 (up) /
+ * button 5 (down) presses (see pgzero.constants.mouse.WHEEL_UP/WHEEL_DOWN).
+ *
+ * Returns null for a zero (or missing) deltaY, since that carries no
+ * wheel-button semantics.
+ */
+export declare function mapBrowserWheelEvent(event: BrowserWheelLike, target?: BoundsTarget): MappedMouseEvent | null;
+export declare function buttonsFromBrowserButtons(buttons: number): Set<number>;
+export declare class InputDispatcher {
+    readonly keyboard: KeyboardState;
+    readonly mouseState: MouseState;
+    hooks: InputHooks;
+    private lastMousePos;
+    private readonly physicalKeys;
+    private readonly virtualKeys;
+    constructor(hooks?: InputHooks, keyboard?: KeyboardState, mouseState?: MouseState);
+    handleKeyDown(event: BrowserKeyboardLike): boolean;
+    handleKeyUp(event: BrowserKeyboardLike): boolean;
+    handleFocusLoss(): void;
+    /** Each pointer owns its press, so releasing one input cannot release another. */
+    handleVirtualKeyDown(key: number, source: unknown): void;
+    handleVirtualKeyUp(source: unknown): void;
+    handleMouseDown(event: BrowserMouseLike, target?: BoundsTarget): boolean;
+    handleMouseUp(event: BrowserMouseLike, target?: BoundsTarget): boolean;
+    handleMouseMove(event: BrowserMouseLike, target?: BoundsTarget): boolean;
+    /**
+     * Handles a native `wheel` event. pygame/pgzero report scroll wheel
+     * motion through the same channel as mouse button presses (button 4/5),
+     * so this dispatches `onMouseDown` just like handleMouseDown.
+     */
+    handleWheel(event: BrowserWheelLike, target?: BoundsTarget): boolean;
+    private trackMouse;
+    attach(mouseTarget: EventTarget & BoundsTarget, keyboardTarget?: EventTarget): () => void;
+}
+export declare function createInputDispatcher(hooks?: InputHooks, keyboard?: KeyboardState, mouseState?: MouseState): InputDispatcher;
+export {};

package/dist/friendly-names.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The lowercase spellings of a camelCase name, with or without an underscore
+ * between each pair of its words: `collideListAll` gives `collidelistall`,
+ * `collide_list_all`, `collidelist_all` and `collide_listall`. Pygame Zero's
+ * names (`colliderect`, `angle_to`, `unionall_ip`) are all among them.
+ */
+export declare function otherSpellings(name: string): string[];
+/**
+ * Makes the other spellings of `target`'s camelCase members throw when read
+ * or written, naming the member: reading `actor.angle_to` throws
+ * "actor.angle_to doesn't exist. Did you mean actor.angleTo?". `fields`
+ * names members that each instance sets on itself rather than inheriting
+ * from `target`. A spelling `target` already has is left alone, and guards
+ * are non-enumerable, so they never show up as data.
+ */
+export declare function guardSpellings(target: object, label: string, fields?: readonly string[]): void;
+/**
+ * The real member a spelling guard on `target` or its prototypes stands in
+ * for (`colliderect` → `collideRect`), or undefined for any other name.
+ */
+export declare function guardedMember(target: object, property: string): string | undefined;
+export type FriendlyServiceOptions = {
+    /** Members learners shouldn't reach (internal helpers). */
+    readonly hidden?: readonly string[];
+    /** Plain-object members to wrap the same way (`screen.draw`). */
+    readonly nested?: readonly string[];
+    /**
+     * Suggestions for guesses that belong somewhere else, by loose name
+     * (lowercase, without underscores): `{ drawrect: "screen.draw.rect" }`
+     * answers `screen.drawRect`.
+     */
+    readonly hints?: Readonly<Record<string, string>>;
+};
+/**
+ * Wraps a library service (`screen`, `clock`, `keys`, ...) so reading a
+ * member it doesn't have throws
+ * `screen.draw.cirlce doesn't exist. Did you mean screen.draw.circle?`,
+ * including another spelling of a real member
+ * (`screen.draw.filled_circle` suggests `screen.draw.filledCircle`).
+ * Plain-object members (`screen.draw`) are wrapped the same way. Methods
+ * stay bound to the service, so they can be passed around as callbacks.
+ */
+export declare function friendlyService<T extends object>(target: T, label: string, options?: FriendlyServiceOptions): T;

package/dist/geometry.d.ts

@@ -0,0 +1,125 @@
+export type Point = [number, number];
+export type Size = [number, number];
+export type RectTuple = [number, number, number, number];
+export type RectLike = Rect | RectTuple | readonly [number, number, number, number] | {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+} | {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+} | {
+    readonly rect: RectLike | (() => RectLike);
+};
+/** A dictionary-like collision target: a `Map`, or a plain object keyed by string. */
+export type RectDict<V> = Map<unknown, V> | Record<string, V>;
+type PairLike = readonly [number, number];
+export declare class Rect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    constructor(left: number, top: number, width: number, height: number);
+    constructor(topLeft: PairLike, size: PairLike);
+    constructor(rect: RectLike);
+    get x(): number;
+    set x(value: number);
+    get y(): number;
+    set y(value: number);
+    get w(): number;
+    set w(value: number);
+    get h(): number;
+    set h(value: number);
+    get right(): number;
+    set right(value: number);
+    get bottom(): number;
+    set bottom(value: number);
+    get centerX(): number;
+    set centerX(value: number);
+    get centerY(): number;
+    set centerY(value: number);
+    get topLeft(): Point;
+    set topLeft(value: PairLike);
+    get topRight(): Point;
+    set topRight(value: PairLike);
+    get bottomLeft(): Point;
+    set bottomLeft(value: PairLike);
+    get bottomRight(): Point;
+    set bottomRight(value: PairLike);
+    get midTop(): Point;
+    set midTop(value: PairLike);
+    get midLeft(): Point;
+    set midLeft(value: PairLike);
+    get midRight(): Point;
+    set midRight(value: PairLike);
+    get midBottom(): Point;
+    set midBottom(value: PairLike);
+    get center(): Point;
+    set center(value: PairLike);
+    get size(): Size;
+    set size(value: PairLike);
+    /** Index 0: `left`. Mirrors pygame/pgzero's `rect[0]`. */
+    get 0(): number;
+    /** Index 1: `top`. Mirrors pygame/pgzero's `rect[1]`. */
+    get 1(): number;
+    /** Index 2: `width`. Mirrors pygame/pgzero's `rect[2]`. */
+    get 2(): number;
+    /** Index 3: `height`. Mirrors pygame/pgzero's `rect[3]`. */
+    get 3(): number;
+    /** Iterates as `[left, top, width, height]`, so `[...rect]` works like pgzero's ZRect. */
+    [Symbol.iterator](): Iterator<number>;
+    copy(): Rect;
+    move(x: number, y: number): Rect;
+    move(offset: PairLike): Rect;
+    moveIp(x: number, y: number): void;
+    moveIp(offset: PairLike): void;
+    inflate(x: number, y: number): Rect;
+    inflate(size: PairLike): Rect;
+    inflateIp(x: number, y: number): void;
+    inflateIp(size: PairLike): void;
+    normalize(): void;
+    clamp(other: RectLike): Rect;
+    /** Mutating form of {@link clamp}. */
+    clampIp(other: RectLike): void;
+    clip(other: RectLike): Rect;
+    /** Mutating form of {@link clip}. */
+    clipIp(other: RectLike): void;
+    union(other: RectLike): Rect;
+    /** Mutating form of {@link union}. */
+    unionIp(other: RectLike): void;
+    unionAll(others: RectLike[]): Rect;
+    /** Mutating form of {@link unionAll}. */
+    unionAllIp(others: RectLike[]): void;
+    fit(other: RectLike): Rect;
+    contains(other: RectLike): boolean;
+    collidePoint(point: PairLike): boolean;
+    collidePoint(x: number, y: number): boolean;
+    /**
+     * True when this rectangle overlaps `target`: another rect (or anything
+     * with a rect, like an Actor), or an `[x, y]` point inside it.
+     */
+    touches(target: RectLike | PairLike): boolean;
+    collideRect(other: RectLike): boolean;
+    collideList(others: RectLike[]): number;
+    collideListAll(others: RectLike[]): number[];
+    /**
+     * Returns the first `[key, value]` entry of `dict` that collides with this
+     * rect, or `undefined` if none do. By default the *values* are treated as
+     * rect-likes (matching rect.py's `use_values=True`); pass `useValues:
+     * false` to instead treat the *keys* as rect-likes (only meaningful for a
+     * `Map` whose keys are themselves rect-likes, since plain object keys are
+     * always strings).
+     */
+    collideDict<V>(dict: RectDict<V>, useValues?: boolean): [unknown, V] | undefined;
+    /** Same as {@link collideDict}, but returns every colliding entry. */
+    collideDictAll<V>(dict: RectDict<V>, useValues?: boolean): Array<[unknown, V]>;
+    private applyGeometry;
+}
+export declare class ZRect extends Rect {
+}
+export declare function angleTo(from: PairLike, to: PairLike): number;
+export declare function distanceTo(from: PairLike, to: PairLike): number;
+export {};

package/dist/helpers.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Small helpers for the things almost every game hand-writes: a random
+ * whole number, a random pick from a list, and keeping a value in range.
+ * The random ones read the running game's random source, so a seeded run
+ * (`run(source, { seed })`) repeats them too.
+ */
+import { type RandomSource } from "./random.js";
+/**
+ * A random whole number from `min` to `max`, including both ends:
+ * `randomInt(1, 6)` rolls a die.
+ */
+export declare function randomInt(min: number, max: number): number;
+/** A random item from a list: `randomChoice(["red", "green", "blue"])`. */
+export declare function randomChoice<T>(items: readonly T[]): T;
+/**
+ * `randomInt` and `randomChoice` that always draw from one game's source,
+ * so they repeat with its seed even when called outside its hooks, as the
+ * CLI's `call` does.
+ */
+export declare function randomHelpersFor(source: RandomSource): {
+    randomInt: typeof randomInt;
+    randomChoice: typeof randomChoice;
+};
+/**
+ * `value`, moved inside `min`..`max` if it's outside:
+ * `player.x = clamp(player.x, 0, WIDTH)`.
+ */
+export declare function clamp(value: number, min: number, max: number): number;

package/dist/host.d.ts

@@ -0,0 +1,58 @@
+/** Advanced host-integration APIs. Learner games import the core root. */
+import * as assets from "./assets.js";
+import * as audio from "./audio.js";
+import * as events from "./events.js";
+import * as inspection from "./inspection.js";
+import * as rendering from "./rendering.js";
+import * as random from "./random.js";
+import * as runtime from "./runtime.js";
+import * as storage from "./storage.js";
+import * as tone from "./tone.js";
+export { AudioUnlockState, BrowserSoundAsset, MusicPlayer } from "./audio.js";
+export { InputDispatcher } from "./events.js";
+export { ToneGenerator } from "./tone.js";
+export declare const assetUrl: typeof assets.assetUrl;
+export declare const audioUnlock: audio.AudioUnlockState;
+export declare const buttonsFromBrowserButtons: typeof events.buttonsFromBrowserButtons;
+export declare const clampVolume: typeof audio.clampVolume;
+export declare const collectRuntimeDiagnostics: typeof runtime.collectRuntimeDiagnostics;
+export declare const createAssetLoaders: typeof assets.createAssetLoaders;
+export declare const createBrowserSoundAsset: typeof audio.createBrowserSoundAsset;
+export declare const createFontLoader: typeof assets.createFontLoader;
+export declare const createImageLoader: typeof assets.createImageLoader;
+export declare const createInputDispatcher: typeof events.createInputDispatcher;
+export declare const createLocalStorageAdapter: typeof storage.createLocalStorageAdapter;
+export declare const createSeededRandom: typeof random.createSeededRandom;
+export declare const createMusicLoader: typeof assets.createMusicLoader;
+export declare const createMusicPlayer: typeof audio.createMusicPlayer;
+export declare const createSoundLoader: typeof assets.createSoundLoader;
+export declare const createStorage: typeof storage.createStorage;
+export declare const createToneGenerator: typeof tone.createToneGenerator;
+export declare const dispatchHook: typeof events.dispatchHook;
+export declare const fitTextboxFontSize: typeof rendering.fitTextboxFontSize;
+export declare const getParameterNames: typeof events.getParameterNames;
+export declare const getGameInspector: typeof inspection.getGameInspector;
+export declare const getScreen: typeof rendering.getScreen;
+export declare const layoutText: typeof rendering.layoutText;
+export declare const loadImages: typeof assets.loadImages;
+export declare const mapBrowserKeyEvent: typeof events.mapBrowserKeyEvent;
+export declare const mapBrowserMouseButton: typeof events.mapBrowserMouseButton;
+export declare const mapBrowserMouseEvent: typeof events.mapBrowserMouseEvent;
+export declare const mapBrowserWheelEvent: typeof events.mapBrowserWheelEvent;
+export declare const normalizeColor: typeof rendering.normalizeColor;
+export declare const normalizeWaveform: typeof tone.normalizeWaveform;
+export declare const parseStatePath: typeof inspection.parseStatePath;
+export declare const noteToFrequency: typeof tone.noteToFrequency;
+export declare const parseToneFrequency: typeof tone.parseToneFrequency;
+export declare const serializeGameValue: typeof inspection.serializeGameValue;
+export declare const setScreen: typeof rendering.setScreen;
+export declare const validateAssetName: typeof assets.validateAssetName;
+export type { AssetLoader, AssetLoaderOptions, AssetLoaders, AssetUrls, DrawableImage, FontAsset, MusicAsset, SoundAsset, SurfaceLike, } from "./assets.js";
+export type { AudioElementFactory, AudioElementLike, BrowserSoundDebugState, BrowserSoundOptions, MusicPlayerOptions, TimeoutScheduler, } from "./audio.js";
+export type { BrowserKeyboardLike, BrowserMouseLike, BrowserWheelLike, MappedKeyboardEvent, MappedMouseEvent, } from "./events.js";
+export type { GameInspector, JsonSafe, StatePath } from "./inspection.js";
+export type { RandomSeed, RandomSource } from "./random.js";
+export type { CanvasLike, TextLayout } from "./rendering.js";
+export type { PreloadedAssets, RuntimeCanvas, RuntimeDiagnostic, RuntimeFailure, RuntimeFailurePhase, RuntimeScheduler, } from "./runtime.js";
+export type { BrowserStorageLike, LocalStorageAdapterOptions, StorageAdapter, StorageOptions, } from "./storage.js";
+export type { AudioContextLike, AudioParamLike, GainNodeLike, OscillatorNodeLike, ToneOptions, } from "./tone.js";