@zylem/game-lib 0.6.4 → 0.8.0

package/dist/core-CARRaS55.d.ts

@@ -1,541 +0,0 @@
-import { ak as InputPlayerNumber, al as InputProvider, am as Inputs, L as SetupContext, U as UpdateContext, M as DestroyContext, an as GameEntityLifeCycle, O as BaseNode, ao as IGame, S as SetupFunction, J as UpdateFunction, K as DestroyFunction, aa as GameEvents, ap as LoadedContext, aq as CleanupContext, ar as NodeInterface } from './entity-vj-HTjzU.js';
-import { G as GameInputConfig, e as StageInterface, B as BaseGlobals, b as Stage, Z as ZylemGameConfig } from './stage-types-C19IhuzA.js';
-import { Z as ZylemCamera, R as RendererManager } from './camera-4XO5gbQH.js';
-import { Vector3 } from 'three';
-import { Vector3 as Vector3$1 } from '@dimforge/rapier3d-compat';
-import './global-change-2JvMaz44.js';
-
-declare class InputManager {
-    private inputMap;
-    private currentInputs;
-    private previousInputs;
-    constructor(config?: GameInputConfig);
-    /**
-     * Reconfigure keyboard and mouse providers at runtime without affecting gamepad providers.
-     * Disposes existing keyboard/mouse providers and creates new ones from the given config.
-     */
-    configure(config: GameInputConfig): void;
-    addInputProvider(playerNumber: InputPlayerNumber, provider: InputProvider): void;
-    getInputs(delta: number): Inputs;
-    private buildPlayerEntries;
-    private mergeInputs;
-}
-
-/**
- * This class is an alternative to {@link Clock} with a different API design and behavior.
- * The goal is to avoid the conceptual flaws that became apparent in `Clock` over time.
- *
- * - `Timer` has an `update()` method that updates its internal state. That makes it possible to
- * call `getDelta()` and `getElapsed()` multiple times per simulation step without getting different values.
- * - The class can make use of the Page Visibility API to avoid large time delta values when the app
- * is inactive (e.g. tab switched or browser hidden).
- *
- * ```js
- * const timer = new Timer();
- * timer.connect( document ); // use Page Visibility API
- * ```
- *
- * @three_import import { Timer } from 'three/addons/misc/Timer.js';
- */
-declare class Timer {
-    protected _previousTime: number;
-    protected _currentTime: number;
-    protected _startTime: number;
-    protected _delta: number;
-    protected _elapsed: number;
-    protected _timescale: number;
-    protected _document: Document | null;
-    protected _pageVisibilityHandler: (() => void) | null;
-    /**
-     * Constructs a new timer.
-     */
-    constructor();
-    /**
-     * Connect the timer to the given document.Calling this method is not mandatory to
-     * use the timer but enables the usage of the Page Visibility API to avoid large time
-     * delta values.
-     *
-     * @param {Document} document - The document.
-     */
-    connect(document: Document): void;
-    /**
-     * Disconnects the timer from the DOM and also disables the usage of the Page Visibility API.
-     */
-    disconnect(): void;
-    /**
-     * Returns the time delta in seconds.
-     *
-     * @return {number} The time delta in second.
-     */
-    getDelta(): number;
-    /**
-     * Returns the elapsed time in seconds.
-     *
-     * @return {number} The elapsed time in second.
-     */
-    getElapsed(): number;
-    /**
-     * Returns the timescale.
-     *
-     * @return {number} The timescale.
-     */
-    getTimescale(): number;
-    /**
-     * Sets the given timescale which scale the time delta computation
-     * in `update()`.
-     *
-     * @param {number} timescale - The timescale to set.
-     * @return {Timer} A reference to this timer.
-     */
-    setTimescale(timescale: number): Timer;
-    /**
-     * Resets the time computation for the current simulation step.
-     *
-     * @return {Timer} A reference to this timer.
-     */
-    reset(): Timer;
-    /**
-     * Can be used to free all internal resources. Usually called when
-     * the timer instance isn't required anymore.
-     */
-    dispose(): void;
-    /**
-     * Updates the internal state of the timer. This method should be called
-     * once per simulation step and before you perform queries against the timer
-     * (e.g. via `getDelta()`).
-     *
-     * @param {number} timestamp - The current time in milliseconds. Can be obtained
-     * from the `requestAnimationFrame` callback argument. If not provided, the current
-     * time will be determined with `performance.now`.
-     * @return {Timer} A reference to this timer.
-     */
-    update(timestamp?: number): Timer;
-}
-
-declare const AspectRatio: {
-    readonly FourByThree: number;
-    readonly SixteenByNine: number;
-    readonly NineBySixteen: number;
-    readonly TwentyOneByNine: number;
-    readonly OneByOne: number;
-};
-type AspectRatioValue = (typeof AspectRatio)[keyof typeof AspectRatio] | number;
-/**
- * AspectRatioDelegate manages sizing a canvas to fit within a container
- * while preserving a target aspect ratio. It notifies a consumer via
- * onResize when the final width/height are applied so renderers/cameras
- * can update their viewports.
- */
-declare class AspectRatioDelegate {
-    container: HTMLElement;
-    canvas: HTMLCanvasElement;
-    aspectRatio: number;
-    onResize?: (width: number, height: number) => void;
-    private handleResizeBound;
-    private resizeObserver;
-    constructor(params: {
-        container: HTMLElement;
-        canvas: HTMLCanvasElement;
-        aspectRatio: AspectRatioValue;
-        onResize?: (width: number, height: number) => void;
-    });
-    /** Attach window resize listener and apply once. */
-    attach(): void;
-    /** Detach window resize listener. */
-    detach(): void;
-    /** Compute the largest size that fits container while preserving aspect. */
-    measure(): {
-        width: number;
-        height: number;
-    };
-    /** Apply measured size to canvas and notify. */
-    apply(): void;
-}
-
-interface ViewportSize {
-    width: number;
-    height: number;
-}
-
-type RetroResolution = {
-    key: string;
-    width: number;
-    height: number;
-    notes?: string;
-};
-type RetroPreset = {
-    displayAspect: number;
-    resolutions: RetroResolution[];
-};
-/**
- * Retro, console, and device display presets.
- * displayAspect represents the intended display aspect (letterboxing target),
- * not necessarily the raw pixel aspect of internal buffers.
- */
-declare const RetroPresets: Record<string, RetroPreset>;
-type RetroPresetKey = keyof typeof RetroPresets;
-declare function getDisplayAspect(preset: RetroPresetKey): number;
-declare function getPresetResolution(preset: RetroPresetKey, key?: string): RetroResolution | undefined;
-declare function parseResolution(text: string): {
-    width: number;
-    height: number;
-} | null;
-
-type ResolutionInput = string | {
-    width: number;
-    height: number;
-};
-type DeviceProfile = 'auto' | 'desktop' | 'mobile';
-interface ResolveGameConfigRuntime {
-    deviceProfile?: DeviceProfile;
-    viewportSize?: ViewportSize;
-}
-type GameDeviceConfig = Partial<{
-    /** numeric value or key in AspectRatio */
-    aspectRatio: AspectRatioValue | keyof typeof AspectRatio;
-    /** console/display preset to derive aspect ratio */
-    preset: RetroPresetKey;
-    /** lock internal render buffer for this device profile */
-    resolution: ResolutionInput;
-}>;
-type GameConfigLike = Partial<{
-    id: string;
-    globals: Record<string, any>;
-    stages: StageInterface[];
-    debug: boolean;
-    time: number;
-    input: GameInputConfig;
-    /** numeric value or key in AspectRatio */
-    aspectRatio: AspectRatioValue | keyof typeof AspectRatio;
-    /** console/display preset to derive aspect ratio */
-    preset: RetroPresetKey;
-    /** lock internal render buffer to this desktop/default resolution */
-    resolution: ResolutionInput;
-    /** mobile-specific aspect/preset/resolution overrides */
-    mobile: GameDeviceConfig;
-    fullscreen: boolean;
-    /** CSS background value for document body */
-    bodyBackground: string;
-    /** existing container by reference */
-    container: HTMLElement;
-    /** create/find container by id */
-    containerId: string;
-    /** optional canvas if caller wants to manage it */
-    canvas: HTMLCanvasElement;
-}>;
-declare class GameConfig {
-    id: string;
-    globals: Record<string, any>;
-    stages: StageInterface[];
-    debug: boolean;
-    time: number;
-    input: GameInputConfig | undefined;
-    aspectRatio: number;
-    internalResolution: {
-        width: number;
-        height: number;
-    } | undefined;
-    fullscreen: boolean;
-    bodyBackground: string | undefined;
-    container: HTMLElement;
-    containerId?: string | undefined;
-    canvas?: HTMLCanvasElement | undefined;
-    constructor(id: string, globals: Record<string, any>, stages: StageInterface[], debug: boolean, time: number, input: GameInputConfig | undefined, aspectRatio: number, internalResolution: {
-        width: number;
-        height: number;
-    } | undefined, fullscreen: boolean, bodyBackground: string | undefined, container: HTMLElement, containerId?: string | undefined, canvas?: HTMLCanvasElement | undefined);
-}
-/**
- * Factory for authoring configuration objects in user code.
- * Returns a plain object that can be passed to `game(...)`.
- */
-declare function gameConfig(config: GameConfigLike): GameConfigLike;
-
-interface GameCanvasOptions {
-    id: string;
-    container?: HTMLElement;
-    containerId?: string;
-    canvas?: HTMLCanvasElement;
-    bodyBackground?: string;
-    fullscreen?: boolean;
-    aspectRatio: AspectRatioValue | number;
-}
-/**
- * GameCanvas is a DOM delegate that owns:
- * - container lookup/creation and styling (including fullscreen centering)
- * - body background application
- * - canvas mounting into container
- * - aspect ratio sizing via AspectRatioDelegate
- */
-declare class GameCanvas {
-    id: string;
-    container: HTMLElement;
-    canvas: HTMLCanvasElement;
-    bodyBackground?: string;
-    fullscreen: boolean;
-    aspectRatio: number;
-    private ratioDelegate;
-    constructor(options: GameCanvasOptions);
-    applyBodyBackground(): void;
-    mountCanvas(): void;
-    mountRenderer(rendererDom: HTMLCanvasElement, onResize: (width: number, height: number) => void): void;
-    centerIfFullscreen(): void;
-    attachAspectRatio(onResize: (width: number, height: number) => void): void;
-    setAspectRatio(aspectRatio: number): void;
-    reapplyLayout(): void;
-    destroy(): void;
-    private ensureContainer;
-}
-
-/**
- * Game-level loading event that includes stage context.
- */
-interface GameLoadingEvent {
-    type: 'start' | 'progress' | 'complete';
-    stageName?: string;
-    stageIndex?: number;
-    message: string;
-    progress: number;
-    current?: number;
-    total?: number;
-}
-
-type ZylemGameOptions<TGlobals extends BaseGlobals> = ZylemGameConfig<Stage, ZylemGame<TGlobals>, TGlobals> & Partial<GameConfig>;
-declare class ZylemGame<TGlobals extends BaseGlobals> {
-    id: string;
-    initialGlobals: TGlobals;
-    customSetup: ((params: SetupContext<ZylemGame<TGlobals>, TGlobals>) => void) | null;
-    customUpdate: ((params: UpdateContext<ZylemGame<TGlobals>, TGlobals>) => void) | null;
-    customDestroy: ((params: DestroyContext<ZylemGame<TGlobals>, TGlobals>) => void) | null;
-    stages: Stage[];
-    stageMap: Map<string, Stage>;
-    currentStageId: string;
-    previousTimeStamp: number;
-    totalTime: number;
-    timer: Timer;
-    inputManager: InputManager;
-    wrapperRef: Game<TGlobals>;
-    globalInputConfig: GameInputConfig | undefined;
-    defaultCamera: ZylemCamera | null;
-    /** Shared renderer manager for all stages */
-    rendererManager: RendererManager | null;
-    container: HTMLElement | null;
-    canvas: HTMLCanvasElement | null;
-    aspectRatioDelegate: AspectRatioDelegate | null;
-    resolvedConfig: GameConfig | null;
-    gameCanvas: GameCanvas | null;
-    private animationFrameId;
-    private isDisposed;
-    private debugDelegate;
-    private loadingDelegate;
-    private rendererObserver;
-    private eventBusUnsubscribes;
-    private readonly gameUpdateParams;
-    private readonly stageSetupParams;
-    private readonly stageUpdateParams;
-    private readonly frameCallback;
-    private readonly sourceOptions;
-    private displayRuntime;
-    static FRAME_LIMIT: number;
-    static FRAME_DURATION: number;
-    static MAX_DELTA_SECONDS: number;
-    constructor(options: ZylemGameOptions<TGlobals>, wrapperRef: Game<TGlobals>, displayRuntime?: ResolveGameConfigRuntime);
-    setDisplayRuntime(runtime: ResolveGameConfigRuntime): void;
-    loadGameCanvas(config: GameConfig): void;
-    loadDebugOptions(options: ZylemGameOptions<TGlobals>): void;
-    loadStage(stage: Stage, stageIndex?: number): Promise<void>;
-    /**
-     * Merges game-level global input config with the stage's per-stage overrides
-     * and reconfigures the InputManager.
-     */
-    applyInputConfig(stage: Stage): void;
-    /**
-     * Update the game-level global input config and re-apply to the current stage.
-     */
-    setGlobalInputConfig(config: GameInputConfig): void;
-    unloadCurrentStage(): void;
-    setGlobals(options: ZylemGameConfig<Stage, ZylemGame<TGlobals>, TGlobals>): void;
-    params(): UpdateContext<ZylemGame<TGlobals>, TGlobals>;
-    start(): void;
-    /**
-     * Execute a single frame update.
-     * This method can be called directly for testing or from the game loop.
-     * @param deltaTime Optional delta time in seconds. If not provided, uses timer delta.
-     */
-    step(deltaTime?: number): void;
-    loop(timestamp: number): void;
-    dispose(): void;
-    outOfLoop(): void;
-    getStage(id: string): Stage | undefined;
-    currentStage(): Stage | undefined;
-    /**
-     * Subscribe to loading events from the game.
-     * Events include stage context (stageName, stageIndex).
-     * @param callback Invoked for each loading event
-     * @returns Unsubscribe function
-     */
-    onLoading(callback: (event: GameLoadingEvent) => void): () => void;
-    /**
-     * Build the stage config payload for the current stage.
-     */
-    private buildStageConfigPayload;
-    /**
-     * Build the entities payload for the current stage.
-     */
-    private buildEntitiesPayload;
-    /**
-     * Emit a state:dispatch event to the zylemEventBus.
-     * Called after stage load and on global state changes.
-     */
-    private emitStateDispatch;
-    /**
-     * Inspect a stage's options to determine the renderer type.
-     * Looks for CameraWrapper instances in the stage options and uses
-     * the first camera's rendererType. Falls back to 'webgl'.
-     */
-    private resolveRendererType;
-    /**
-     * Subscribe to the game event bus for stage loading and state events.
-     * Emits events to zylemEventBus for cross-package communication.
-     */
-    private subscribeToEventBus;
-}
-
-type GameOptions<TGlobals extends BaseGlobals> = Array<ZylemGameConfig<Stage, any, TGlobals> | GameConfigLike | Stage | GameEntityLifeCycle | BaseNode>;
-
-declare class Game<TGlobals extends BaseGlobals> implements IGame<TGlobals> {
-    private wrappedGame;
-    options: GameOptions<TGlobals>;
-    private setupCallbacks;
-    private updateCallbacks;
-    private destroyCallbacks;
-    private pendingLoadingCallbacks;
-    private globalChangeCallbacks;
-    private globalChangesCallbacks;
-    private activeGlobalSubscriptions;
-    private eventDelegate;
-    /** Pending global input config set before the game starts. */
-    private pendingInputConfig;
-    private displayRuntime;
-    refErrorMessage: string;
-    constructor(options: GameOptions<TGlobals>);
-    onSetup(...callbacks: Array<SetupFunction<ZylemGame<TGlobals>, TGlobals>>): this;
-    onUpdate(...callbacks: Array<UpdateFunction<ZylemGame<TGlobals>, TGlobals>>): this;
-    onDestroy(...callbacks: Array<DestroyFunction<ZylemGame<TGlobals>, TGlobals>>): this;
-    /**
-     * Set composable input configuration as global defaults for the entire game.
-     * Multiple configs are deep-merged (later configs win on key conflicts).
-     * Per-stage overrides (via stage.setInputConfiguration) are merged on top.
-     * Can be called before or after start().
-     * @example game.setInputConfiguration(useArrowsForAxes('p1'), useWASDForDirections('p2'));
-     */
-    setInputConfiguration(...configs: GameInputConfig[]): this;
-    start(): Promise<this>;
-    setDisplayRuntime(runtime: Partial<ResolveGameConfigRuntime>): this;
-    setDeviceProfile(profile: DeviceProfile): this;
-    setViewportSize(width: number, height: number): this;
-    private load;
-    private setOverrides;
-    /**
-     * Subscribe to changes on a global value. Subscriptions are registered
-     * when the game starts and cleaned up when disposed.
-     * The callback receives the value and the current stage.
-     * @example game.onGlobalChange('score', (val, stage) => console.log(val));
-     */
-    onGlobalChange<T = unknown>(path: string, callback: (value: T, stage: Stage | null) => void): this;
-    /**
-     * Subscribe to changes on multiple global paths. Subscriptions are registered
-     * when the game starts and cleaned up when disposed.
-     * The callback receives the values and the current stage.
-     * @example game.onGlobalChanges(['score', 'lives'], ([score, lives], stage) => console.log(score, lives));
-     */
-    onGlobalChanges<T extends unknown[] = unknown[]>(paths: string[], callback: (values: T, stage: Stage | null) => void): this;
-    /**
-     * Register all stored global change callbacks.
-     * Called internally during start().
-     */
-    private registerGlobalSubscriptions;
-    /**
-     * Get the current stage wrapper.
-     */
-    getCurrentStage(): Stage | null;
-    pause(): Promise<void>;
-    resume(): Promise<void>;
-    /**
-     * Execute a single frame update.
-     * Useful for testing or manual frame stepping.
-     * @param deltaTime Optional delta time in seconds (defaults to 1/60)
-     */
-    step(deltaTime?: number): void;
-    reset(): Promise<void>;
-    previousStage(): void;
-    loadStageFromId(stageId: string): Promise<void>;
-    nextStage(): void;
-    goToStage(): Promise<void>;
-    end(): Promise<void>;
-    dispose(): void;
-    /**
-     * Dispatch an event from the game.
-     * Events are emitted both locally and to the global event bus.
-     */
-    dispatch<K extends keyof GameEvents>(event: K, payload: GameEvents[K]): void;
-    /**
-     * Listen for events on this game instance.
-     * @returns Unsubscribe function
-     */
-    listen<K extends keyof GameEvents>(event: K, handler: (payload: GameEvents[K]) => void): () => void;
-    /**
-     * Subscribe to loading events from the game.
-     * Events include stage context (stageName, stageIndex).
-     * @param callback Invoked for each loading event
-     * @returns Unsubscribe function
-     */
-    onLoading(callback: (event: GameLoadingEvent) => void): () => void;
-}
-/**
- * create a new game
- * @param options GameOptions - Array of IGameOptions, Stage, GameEntity, or BaseNode objects
- * @param options.id Game name string (when using IGameOptions)
- * @param options.globals Game globals object (when using IGameOptions)
- * @param options.stages Array of stage objects (when using IGameOptions)
- * @returns Game
- */
-declare function createGame<TGlobals extends BaseGlobals>(...options: GameOptions<TGlobals>): Game<TGlobals>;
-
-/**
- * A Vessel is an empty container entity that holds child entities.
- * It has no geometry, physics, or rendering of its own, but propagates
- * lifecycle events to its children and provides a logical grouping mechanism.
- *
- * Child entities added to a Vessel will be individually spawned into the
- * stage's physics world and render scene when the Vessel is spawned.
- */
-declare class Vessel extends BaseNode<{}, Vessel> {
-    static type: symbol;
-    protected _setup(_params: SetupContext<this>): void;
-    protected _loaded(_params: LoadedContext<this>): Promise<void>;
-    protected _update(_params: UpdateContext<this>): void;
-    protected _destroy(_params: DestroyContext<this>): void;
-    protected _cleanup(_params: CleanupContext<this>): void;
-    create(): this;
-    clone(): this;
-    /**
-     * Add one or more child entities to this vessel.
-     * Overrides parent to support multiple arguments.
-     * @returns this for chaining
-     */
-    add(...nodes: NodeInterface[]): this;
-}
-/**
- * Create a vessel containing the given child entities.
- * @param args Child BaseNode entities to add
- * @returns A new Vessel with the children added
- */
-declare function vessel(...args: Array<BaseNode>): Vessel;
-
-/**
- * @deprecated This type is deprecated.
- */
-type Vect3 = Vector3 | Vector3$1;
-
-export { AspectRatio as A, type DeviceProfile as D, Game as G, type ResolutionInput as R, type Vect3 as V, type GameConfigLike as a, type GameDeviceConfig as b, createGame as c, type ResolveGameConfigRuntime as d, type AspectRatioValue as e, getDisplayAspect as f, gameConfig as g, getPresetResolution as h, type RetroPreset as i, type RetroPresetKey as j, type RetroResolution as k, parseResolution as p, vessel as v };