@zylem/game-lib 0.6.3 → 0.7.0

package/dist/core-DAkskq6Y.d.ts

@@ -1,498 +0,0 @@
-import { ak as InputPlayerNumber, al as InputProvider, am as Inputs, L as SetupContext, U as UpdateContext, M as DestroyContext, an as GameEntityLifeCycle, N 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-BpbZqg19.js';
-import { G as GameInputConfig, e as StageInterface, B as BaseGlobals, b as Stage, Z as ZylemGameConfig } from './stage-types-BFsm3qsZ.js';
-import { Z as ZylemCamera, R as RendererManager } from './camera-B5e4c78l.js';
-import { Vector3 } from 'three';
-import { Vector3 as Vector3$1 } from '@dimforge/rapier3d-compat';
-import './global-change-Dc8uCKi2.js';
-
-declare class InputManager {
-    private inputMap;
-    private currentInputs;
-    private previousInputs;
-    constructor(config?: GameInputConfig);
-    /**
-     * Reconfigure keyboard providers at runtime without affecting gamepad providers.
-     * Disposes existing keyboard 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 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;
-    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;
-}
-
-type RetroResolution = {
-    key: string;
-    width: number;
-    height: number;
-    notes?: string;
-};
-type RetroPreset = {
-    displayAspect: number;
-    resolutions: RetroResolution[];
-};
-/**
- * Retro and console 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;
-
-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 resolution (e.g., '256x240' or { width, height }) */
-    resolution: string | {
-        width: number;
-        height: number;
-    };
-    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;
-    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;
-    static FRAME_LIMIT: number;
-    static FRAME_DURATION: number;
-    static MAX_DELTA_SECONDS: number;
-    constructor(options: ZylemGameOptions<TGlobals>, wrapperRef: Game<TGlobals>);
-    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;
-    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>;
-    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;
-    /**
-     * 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 { Game as G, type Vect3 as V, createGame as c, gameConfig as g, vessel as v };