js-game-zero 0.0.0-placeholder → 0.3.0

package/dist/audio.d.ts

@@ -0,0 +1,150 @@
+import { type AssetLoader, type LoadedAsset, type MusicAsset, type SoundAsset } from "./assets.js";
+export type AudioElementLike = {
+    src: string;
+    loop: boolean;
+    currentTime: number;
+    volume: number;
+    duration: number;
+    paused?: boolean;
+    play(): Promise<void> | void;
+    pause(): void;
+    addEventListener(type: "ended", listener: () => void): void;
+    removeEventListener(type: "ended", listener: () => void): void;
+};
+export type AudioElementFactory = (url: string) => AudioElementLike;
+export declare class AudioUnlockState {
+    private unlocked;
+    isUnlocked(): boolean;
+    markUnlocked(): void;
+}
+export declare const audioUnlock: AudioUnlockState;
+export type BrowserSoundDebugState = {
+    readonly active: boolean;
+    readonly loop: boolean;
+    readonly volume: number;
+    readonly unlocked: boolean;
+    readonly lastError: string | null;
+};
+export type BrowserSoundOptions = {
+    readonly createAudioElement?: AudioElementFactory;
+    readonly unlockState?: AudioUnlockState;
+    readonly volume?: number;
+};
+export declare class BrowserSoundAsset implements SoundAsset {
+    readonly kind: "sound";
+    readonly name: string;
+    readonly url: string;
+    readonly bytes?: ArrayBuffer;
+    private readonly createElement;
+    private readonly unlockState;
+    private readonly activeInstances;
+    private metadataElement;
+    private volumeValue;
+    private lastErrorMessage;
+    constructor(asset: LoadedAsset, options?: BrowserSoundOptions);
+    play(loops?: number): void;
+    loop(): void;
+    stop(): void;
+    getLength(): number;
+    setVolume(volume: number): void;
+    getVolume(): number;
+    debugState(): BrowserSoundDebugState;
+    /** Number of currently overlapping playback instances of this sound. */
+    debugInstanceCount(): number;
+    private handleInstanceEnded;
+    private firstActiveElement;
+    private getMetadataElement;
+    private playElement;
+    private removeInstance;
+}
+export declare function createBrowserSoundAsset(asset: LoadedAsset, options?: BrowserSoundOptions): BrowserSoundAsset;
+export type MusicMode = "loop" | "once";
+export type MusicPlayerOptions = {
+    readonly loader?: AssetLoader<MusicAsset>;
+    readonly createAudioElement?: AudioElementFactory;
+    readonly onMusicEnd?: () => void;
+    readonly onError?: (error: unknown) => void;
+    readonly scheduler?: TimeoutScheduler;
+    readonly volume?: number;
+};
+export type TimeoutScheduler = {
+    setTimeout(callback: () => void, delayMs: number): unknown;
+    clearTimeout(handle: unknown): void;
+};
+export type MusicDebugState = {
+    readonly current: string | null;
+    readonly queued: readonly string[];
+    readonly isPlaying: boolean;
+    readonly volume: number;
+    readonly lastError: string | null;
+};
+export declare class MusicPlayer {
+    private loaderValue;
+    private readonly createElement;
+    private readonly scheduler;
+    private currentTrack;
+    private queuedNames;
+    private onEnd;
+    private readonly onError;
+    private fadeoutHandles;
+    private volumeValue;
+    private lastErrorMessage;
+    private operationGeneration;
+    private pendingStart;
+    constructor(options?: MusicPlayerOptions);
+    play(name: string): Promise<void>;
+    playOnce(name: string): Promise<void>;
+    queue(name: string): Promise<void>;
+    stop(): void;
+    pause(): void;
+    unpause(): void;
+    /** Restarts the current track from the beginning (pygame.mixer.music.rewind). */
+    rewind(): void;
+    /**
+     * Milliseconds the current track has been playing for, or -1 if nothing
+     * is loaded (matches pygame.mixer.music.get_pos()).
+     */
+    getPos(): number;
+    /**
+     * Seconds into the current track (0 when nothing is loaded); set it to
+     * jump there. Unlike `getPos()`, which reports milliseconds for Pygame
+     * compatibility, this reads and writes the same unit.
+     */
+    get position(): number;
+    set position(seconds: number);
+    /** Seeks the current track to the given position in seconds. */
+    setPos(seconds: number): void;
+    fadeOut(seconds: number): void;
+    setVolume(volume: number): void;
+    getVolume(): number;
+    /**
+     * True if music is currently playing (and not paused). Accepts and
+     * ignores an optional track name argument, matching pgzero's
+     * `music.is_playing(name)` signature.
+     */
+    isPlaying(_name?: string): boolean;
+    setOnMusicEnd(callback: (() => void) | undefined): void;
+    debugState(): MusicDebugState;
+    debugCurrentElement(): AudioElementLike | null;
+    private get loader();
+    /**
+     * Starts loading and playing a track, reporting (but never throwing past
+     * `play`/`playOnce`) load failures. Returns whether the track actually
+     * started, so callers that need to react to a failure — like queue
+     * advancement — can do so without relying on a rejected promise.
+     */
+    private beginTrackStart;
+    private startTrack;
+    private playNextQueuedTrack;
+    private handleTrackEnded;
+    private playElement;
+    private reportError;
+    private replacePlayback;
+    private disposeCurrent;
+    private clearFadeout;
+}
+export declare function createMusicPlayer(options?: MusicPlayerOptions): MusicPlayer;
+export declare function setActiveMusicPlayer(nextMusicPlayer: MusicPlayer | null): MusicPlayer | null;
+export declare function getActiveMusicPlayer(): MusicPlayer;
+export declare const music: MusicPlayer;
+export declare function clampVolume(volume: number): number;

package/dist/browser-asset-backends.d.ts

@@ -0,0 +1,8 @@
+import type { FontAsset, MusicAsset, SoundAsset, SurfaceLike } from "./assets.js";
+export declare const fontExtensions: readonly ["ttf", "otf", "woff", "woff2"];
+export declare function loadBrowserImage(url: string, createSurface: (image: HTMLImageElement) => SurfaceLike): Promise<SurfaceLike>;
+export declare function loadSoundAsset(url: string, name: string): Promise<SoundAsset>;
+export declare function loadMusicAsset(url: string, name: string): Promise<MusicAsset>;
+export declare function loadFontAsset(url: string, name: string): Promise<FontAsset>;
+/** The bytes of a `data:` URL, base64 or percent-encoded. */
+export declare function decodeDataUrl(url: string): ArrayBuffer;

package/dist/browser.d.ts

@@ -0,0 +1,10 @@
+import type * as hostApi from "./host.js";
+import * as framework from "./index.js";
+type Host = Pick<typeof hostApi, "createSeededRandom" | "getGameInspector" | "loadImages" | "parseStatePath" | "serializeGameValue">;
+declare const host: Host;
+declare global {
+    interface Window {
+        JGZ?: typeof framework & typeof host;
+    }
+}
+export * from "./index.js";