@zylem/game-lib 0.6.3 → 0.7.0

package/dist/zylem-stage-runtime-Cs-UDEVU.d.ts

@@ -0,0 +1,777 @@
+import { h as SetupFunction, a as Inputs } from './base-node-life-cycle-CnJ-7zX-.js';
+import { G as GameEntity } from './entity-DNkYKfdp.js';
+import { Object3D, Vector2, Scene, Camera, Vector3, Quaternion, RenderTarget, Texture, Color } from 'three';
+import { S as StageEntity, E as Entity, L as LifecycleFunction, Z as ZylemWorld } from './world-C9zdyl5d.js';
+import { WebGPURenderer, RenderPipeline } from 'three/webgpu';
+import { o as ZylemShader } from './material-Wz83vTTp.js';
+
+declare const Perspectives: {
+    readonly FirstPerson: "first-person";
+    readonly ThirdPerson: "third-person";
+    readonly Isometric: "isometric";
+    readonly Flat2D: "flat-2d";
+    readonly Fixed2D: "fixed-2d";
+    readonly TopDown: "top-down";
+};
+type PerspectiveType = (typeof Perspectives)[keyof typeof Perspectives];
+
+interface CameraDebugState {
+    enabled: boolean;
+    selected: string[];
+}
+interface CameraDebugDelegate {
+    subscribe(listener: (state: CameraDebugState) => void): () => void;
+    resolveTarget(uuid: string): Object3D | null;
+}
+
+/**
+ * Renderer type option.
+ *
+ * @deprecated game-lib now always renders with WebGPU (Three.js
+ * {@link WebGPURenderer}, which keeps its own internal WebGL2 fallback for
+ * devices without WebGPU). This type is retained only so existing public
+ * APIs (e.g. `CameraOptions.rendererType`) keep type-checking; the value is
+ * ignored by the renderer.
+ */
+type RendererType = 'auto' | 'webgpu' | 'webgl';
+/**
+ * The renderer instance type. game-lib standardizes on {@link WebGPURenderer}.
+ */
+type ZylemRenderer = WebGPURenderer;
+/**
+ * Viewport definition in normalized coordinates (0-1).
+ * Represents a rectangular region of the canvas for camera rendering.
+ */
+interface Viewport {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Check if WebGPU is supported in the current browser.
+ *
+ * Informational only — game-lib always constructs a {@link WebGPURenderer},
+ * which transparently falls back to a WebGL2 backend when the WebGPU adapter
+ * is unavailable. Callers can use this to surface device capabilities.
+ */
+declare function isWebGPUSupported(): Promise<boolean>;
+/**
+ * RendererManager owns the shared WebGPU renderer, canvas element, the
+ * optional post-processing pipeline, and the render loop. There is one
+ * RendererManager per game.
+ *
+ * It iterates active cameras and renders each with its configured viewport.
+ */
+declare class RendererManager {
+    renderer: ZylemRenderer;
+    /**
+     * Optional TSL post-processing pipeline. Bound to a single fullscreen
+     * scene+camera via {@link setupPostProcessing}. When present and the
+     * frame is a single fullscreen viewport, the pipeline drives the final
+     * draw instead of `renderer.render(...)`.
+     */
+    postProcessing: RenderPipeline | null;
+    /**
+     * Supersampling (SSAA) multiplier for the scene pass. `1` renders at native
+     * resolution (default). Values > 1 render the scene pass larger and let the
+     * post pipeline downsample it, trading GPU cost for smoother shading/edges
+     * (this is what the legacy WebGL pipeline did implicitly). Applied on the
+     * next {@link setupPostProcessing}.
+     */
+    renderScale: number;
+    screenResolution: Vector2;
+    /**
+     * @deprecated Always `'webgpu'`. Retained for backward compatibility.
+     */
+    rendererType: RendererType;
+    private _initialized;
+    private _sceneRef;
+    private _lastAnimationTimestamp;
+    constructor(screenResolution?: Vector2, _rendererType?: RendererType);
+    /**
+     * Check if the renderer has been initialized
+     */
+    get initialized(): boolean;
+    /**
+     * Whether the active renderer is WebGPU. Always true; retained for
+     * backward compatibility with callers that branched on backend.
+     *
+     * @deprecated game-lib is WebGPU-only.
+     */
+    get isWebGPU(): boolean;
+    /**
+     * Initialize the renderer (must be called before rendering).
+     * Async because WebGPU requires async initialization.
+     *
+     * The renderer keeps Three.js's built-in WebGL2 fallback backend, so it
+     * still initializes on devices without native WebGPU.
+     */
+    initRenderer(): Promise<void>;
+    /**
+     * Set the current scene reference for rendering.
+     */
+    setScene(scene: Scene): void;
+    /**
+     * Set up the post-processing pipeline for a scene + camera.
+     *
+     * Builds a TSL `pass(scene, camera)` (HalfFloat + MSAA) and composes the
+     * final output ourselves so a display-space dither can be added: the dither
+     * breaks up 8-bit gradient banding (e.g. on terrain/sky) that the legacy
+     * WebGL pipeline hid via implicit supersampling. This is the WebGPU
+     * replacement for the old `EffectComposer` + `RenderPass`.
+     */
+    setupPostProcessing(scene: Scene, camera: Camera): void;
+    /**
+     * Set the supersampling (SSAA) multiplier. Takes effect on the next
+     * {@link setupPostProcessing}. `1` = native resolution (default).
+     */
+    setRenderScale(scale: number): void;
+    /**
+     * Dispose the current post-processing pipeline, if any.
+     */
+    private disposePostProcessing;
+    /**
+     * Start the render loop. Calls the provided callback each frame.
+     */
+    startRenderLoop(onFrame: (delta: number) => void): void;
+    /**
+     * Stop the render loop.
+     */
+    stopRenderLoop(): void;
+    /**
+     * Render a scene from a single camera's perspective.
+     * Sets the viewport/scissor based on the camera's viewport config so
+     * split-screen / picture-in-picture layouts render to their region.
+     *
+     * @param usePostProcessing When true and a pipeline is configured, the
+     * post-processing pipeline drives the draw (fullscreen only).
+     */
+    renderCamera(scene: Scene, camera: ZylemCamera, usePostProcessing?: boolean): void;
+    /**
+     * Render a camera to its offscreen render target.
+     * Bypasses post-processing since render-to-texture output is consumed by
+     * an in-scene material (jumbotron / security-camera / portal effects).
+     *
+     * The camera must have a non-null renderTarget.
+     */
+    renderCameraToTarget(scene: Scene, camera: ZylemCamera): void;
+    /**
+     * Render a scene from multiple cameras, each with their own viewport.
+     * Cameras are rendered in order (first = bottom layer, last = top layer).
+     *
+     * Post-processing is applied only when there is a single fullscreen
+     * camera; split-screen layouts render directly per-viewport (a single
+     * fullscreen post pass cannot honor per-camera scissor regions).
+     */
+    renderCameras(scene: Scene, cameras: ZylemCamera[]): void;
+    /**
+     * Simple single-camera render (backwards compatible).
+     * Uses post-processing when configured.
+     */
+    render(scene: Scene, camera: Camera): void;
+    /**
+     * Resize the renderer and update resolution.
+     */
+    resize(width: number, height: number): void;
+    /**
+     * Update renderer pixel ratio (DPR).
+     */
+    setPixelRatio(dpr: number): void;
+    /**
+     * Get the DOM element for the renderer.
+     */
+    getDomElement(): HTMLCanvasElement;
+    /**
+     * Dispose renderer, post-processing, and related resources.
+     */
+    dispose(): void;
+}
+
+/**
+ * Represents a full camera pose: position, rotation, projection params, and optional lookAt.
+ * This is the canonical data structure that flows through the camera pipeline.
+ */
+interface CameraPose {
+    position: Vector3;
+    rotation: Quaternion;
+    fov?: number;
+    zoom?: number;
+    near?: number;
+    far?: number;
+    /** When set, the camera orients to look at this point (takes priority over rotation). */
+    lookAt?: Vector3;
+}
+/**
+ * An additive delta applied on top of a CameraPose.
+ * Used by CameraActions to apply transient offsets (shake, recoil, etc.).
+ */
+interface PoseDelta {
+    position?: Vector3;
+    rotation?: Quaternion;
+    fov?: number;
+    zoom?: number;
+}
+/**
+ * Minimal transform representation for pipeline targets.
+ */
+interface TransformLike {
+    position: Vector3;
+    rotation?: Quaternion;
+}
+/**
+ * Per-frame context passed to every pipeline module (perspectives, behaviors, actions).
+ */
+interface CameraContext {
+    /** Frame delta time in seconds. */
+    dt: number;
+    /** Elapsed time in seconds since camera started updating. */
+    time: number;
+    /** Current viewport dimensions and aspect ratio. */
+    viewport: {
+        width: number;
+        height: number;
+        aspect: number;
+    };
+    /** Named targets the camera can track. 'primary' is targets[0] by convention. */
+    targets: Record<string, TransformLike>;
+}
+/**
+ * A perspective produces the base camera pose each frame.
+ * Exactly one perspective is active per camera at a time.
+ */
+interface CameraPerspective {
+    id: string;
+    /** Compute the raw desired pose for this frame given the current context. */
+    getBasePose(ctx: CameraContext): CameraPose;
+    /** Optional defaults for smoothing and other pipeline settings. */
+    defaults?: {
+        damping?: number;
+    };
+}
+/**
+ * Behaviors modify the desired pose each frame.
+ * They are keyed by name (idempotent add) and sorted by priority.
+ */
+interface CameraBehavior {
+    /** Receive current context and pose, return a modified pose. */
+    update(ctx: CameraContext, pose: CameraPose): CameraPose;
+    /** Called when the behavior is attached to the pipeline. */
+    onAttach?(ctx: CameraContext): void;
+    /** Called when the behavior is removed from the pipeline. */
+    onDetach?(ctx: CameraContext): void;
+    /** Sort order: lower runs first. Default 0. */
+    priority?: number;
+    /** When false, the behavior is skipped during the pipeline run. */
+    enabled?: boolean;
+}
+/**
+ * Actions are transient effects that apply additive deltas (screenshake, recoil, etc.).
+ * They self-expire when isDone() returns true and are automatically removed.
+ */
+interface CameraAction {
+    /** Return the additive delta for this frame. */
+    update(ctx: CameraContext): PoseDelta;
+    /** Return true when the action has completed and should be removed. */
+    isDone(ctx: CameraContext): boolean;
+    /** Sort order for action application. Default 0. */
+    priority?: number;
+}
+/**
+ * Debug snapshot returned by pipeline.getState().
+ */
+interface CameraPipelineState {
+    perspectiveId: string | null;
+    desiredPose: CameraPose | null;
+    finalPose: CameraPose | null;
+    activeBehaviors: string[];
+    activeActionCount: number;
+}
+
+/**
+ * CameraPipeline runs a deterministic per-frame update:
+ *
+ *   Perspective -> Behaviors (priority) -> Actions (deltas) -> Smoothing -> finalPose
+ *
+ * It separates "desired pose" from "final pose". Everything writes to desired;
+ * only smoothing converts desired into the final committed pose.
+ */
+declare class CameraPipeline {
+    /** Active perspective (exactly one at a time). */
+    perspective: CameraPerspective | null;
+    /** Keyed behaviors, sorted by priority each frame. */
+    private behaviors;
+    /** Active transient actions. Expired actions are auto-removed. */
+    private actions;
+    /** The desired pose after perspective + behaviors + actions. */
+    private _desiredPose;
+    /** The smoothed final pose committed to the Three.js camera. */
+    private _finalPose;
+    /** Whether the pipeline has run at least once (prevents lerp from origin on first frame). */
+    private _initialized;
+    /** Smoothing factor: 0 = no movement, 1 = instant snap. */
+    damping: number;
+    constructor(perspective?: CameraPerspective);
+    /**
+     * Run the full pipeline for one frame.
+     * Returns the final pose that should be committed to the Three.js camera.
+     */
+    run(ctx: CameraContext): CameraPose;
+    /**
+     * Add or replace a behavior by key (idempotent).
+     * Calls onDetach on the old behavior and onAttach on the new one.
+     */
+    addBehavior(key: string, behavior: CameraBehavior, ctx?: CameraContext): void;
+    /**
+     * Remove a behavior by key. Calls onDetach if a context is provided.
+     */
+    removeBehavior(key: string, ctx?: CameraContext): boolean;
+    /**
+     * Check whether a behavior with the given key exists.
+     */
+    hasBehavior(key: string): boolean;
+    /**
+     * Add a transient action. Actions self-expire via isDone().
+     */
+    addAction(action: CameraAction): void;
+    /**
+     * Return a debug snapshot of the pipeline state.
+     */
+    getState(): CameraPipelineState;
+    /**
+     * Set a new perspective. Resets the pipeline initialization flag so the
+     * first frame with the new perspective snaps instead of lerping from the old pose.
+     */
+    setPerspective(perspective: CameraPerspective): void;
+    private getSortedBehaviors;
+}
+
+/**
+ * ZylemCamera is a lightweight camera wrapper that manages the Three.js camera,
+ * the camera pose pipeline, and viewport configuration. Rendering is handled
+ * by RendererManager.
+ *
+ * The pipeline runs: Perspective -> Behaviors -> Actions -> Smoothing -> Commit.
+ * When orbit/debug controls are active, the pipeline is bypassed.
+ */
+declare class ZylemCamera {
+    /**
+     * @deprecated No longer used. Kept as null for backward compatibility
+     * with code that checks `camera.cameraRig` (e.g. scene graph insertion).
+     */
+    cameraRig: Object3D | null;
+    camera: Camera;
+    screenResolution: Vector2;
+    _perspective: PerspectiveType;
+    frustumSize: number;
+    rendererType: RendererType;
+    sceneRef: Scene | null;
+    /** Name for camera manager lookup. */
+    name: string;
+    /**
+     * Viewport in normalized coordinates (0-1).
+     * Default is fullscreen: { x: 0, y: 0, width: 1, height: 1 }
+     */
+    viewport: Viewport;
+    /**
+     * Multiple targets for the camera to follow/frame.
+     */
+    targets: StageEntity[];
+    /**
+     * The camera pose pipeline.
+     * Exposed so CameraWrapper can delegate addBehavior/addAction/getState.
+     */
+    pipeline: CameraPipeline;
+    /**
+     * Offscreen render target for render-to-texture (RTT) cameras.
+     * When set, the camera renders to this target instead of the screen viewport.
+     * Created via createRenderTarget() or automatically by setCameraFeed().
+     *
+     * Uses the backend-agnostic {@link RenderTarget} so it works with the
+     * WebGPU renderer (and Three's internal WebGL2 fallback).
+     */
+    renderTarget: RenderTarget | null;
+    /**
+     * @deprecated Use `targets` array instead. Kept for backward compatibility.
+     */
+    get target(): StageEntity | null;
+    set target(entity: StageEntity | null);
+    private orbitController;
+    private _useOrbitalControls;
+    /** When true, debug-mode orbital controls are not attached to this camera. */
+    _skipDebugOrbit: boolean;
+    /** Reference to the shared renderer manager (set during setup). */
+    private _rendererManager;
+    /** Elapsed time tracker for CameraContext. */
+    private _elapsedTime;
+    constructor(perspective: PerspectiveType, screenResolution: Vector2, frustumSize?: number, rendererType?: RendererType);
+    /**
+     * Setup the camera with a scene and renderer manager.
+     */
+    setup(scene: Scene, rendererManager?: RendererManager): Promise<void>;
+    /**
+     * Legacy setup method for backward compatibility.
+     * Creates a temporary RendererManager internally.
+     * @deprecated Use setup(scene, rendererManager) instead.
+     */
+    setupLegacy(scene: Scene): Promise<void>;
+    /**
+     * Update the camera each frame.
+     *
+     * When orbit/debug controls are active, the pipeline is skipped and
+     * orbit controls manage the camera directly. Otherwise, the pipeline
+     * runs: Perspective -> Behaviors -> Actions -> Smoothing -> Commit.
+     */
+    update(delta: number): void;
+    /**
+     * Check if debug mode is active (orbit controls taking over camera).
+     */
+    isDebugModeActive(): boolean;
+    /**
+     * True when debug orbit or user orbital controls are enabled (orbit controller is driving the camera).
+     */
+    get isOrbitActive(): boolean;
+    /**
+     * Advance OrbitControls (damping, pointer release) and follow the debug-selection orbit target.
+     * Intended to run once per render frame — see `CameraManager.render` and legacy `setupLegacy` render loop.
+     */
+    updateOrbitControls(): void;
+    /**
+     * Enable user-configured orbital controls (not debug mode).
+     */
+    enableOrbitalControls(): void;
+    /**
+     * Disable user-configured orbital controls.
+     */
+    disableOrbitalControls(): void;
+    /**
+     * Whether user orbital controls are enabled.
+     */
+    get useOrbitalControls(): boolean;
+    /**
+     * Add a target entity for the camera to follow/frame.
+     */
+    addTarget(entity: StageEntity): void;
+    /**
+     * Remove a target entity.
+     */
+    removeTarget(entity: StageEntity): void;
+    /**
+     * Clear all targets.
+     */
+    clearTargets(): void;
+    /**
+     * Set the viewport for this camera (normalized 0-1 coordinates).
+     */
+    setViewport(x: number, y: number, width: number, height: number): void;
+    /**
+     * Resize camera projection.
+     */
+    resize(width: number, height: number): void;
+    /**
+     * Create an offscreen render target for this camera.
+     * When a render target is present, CameraManager renders this camera
+     * to the target instead of the screen viewport.
+     *
+     * @param width  Texture width in pixels (default 512)
+     * @param height Texture height in pixels (default 512)
+     */
+    createRenderTarget(width?: number, height?: number): RenderTarget;
+    /**
+     * Get the texture from the render target (for applying to a mesh material).
+     * Returns null if no render target has been created.
+     */
+    getRenderTexture(): Texture | null;
+    /**
+     * Dispose camera resources.
+     */
+    destroy(): void;
+    /**
+     * Attach a delegate to react to debug state changes.
+     * Skipped when _skipDebugOrbit is true so the pipeline always runs.
+     */
+    setDebugDelegate(delegate: CameraDebugDelegate | null): void;
+    /**
+     * Directly set the camera position.
+     */
+    move(position: Vector3): void;
+    /**
+     * Apply incremental rotation to the camera.
+     */
+    rotate(pitch: number, yaw: number, roll: number): void;
+    /**
+     * Get the DOM element for the renderer.
+     * @deprecated Access via RendererManager instead.
+     */
+    getDomElement(): HTMLCanvasElement;
+    /**
+     * Get the renderer manager reference.
+     */
+    getRendererManager(): RendererManager | null;
+    /**
+     * Set the renderer manager reference (used by CameraManager during setup).
+     */
+    setRendererManager(manager: RendererManager): void;
+    /** @deprecated Renderer is now owned by RendererManager */
+    get renderer(): any;
+    /** @deprecated Post-processing is now owned by RendererManager */
+    get composer(): any;
+    /** @deprecated Use RendererManager.setPixelRatio() instead */
+    setPixelRatio(dpr: number): void;
+    /**
+     * Build a CameraContext from current ZylemCamera state.
+     * Converts StageEntity[] targets into Record<string, TransformLike>.
+     */
+    private buildContext;
+    /**
+     * Apply the final pipeline pose to the Three.js camera.
+     */
+    private commitPose;
+    /**
+     * Create a Three.js camera based on perspective type.
+     */
+    private createCameraForPerspective;
+}
+
+/**
+ * CameraManager orchestrates multiple cameras per stage.
+ *
+ * Responsibilities:
+ * - Named camera registry (add/remove/get by name or reference)
+ * - Active camera list management (determines which cameras render)
+ * - Always-available debug camera with orbit controls
+ * - Per-frame update of all active cameras' perspective controllers
+ * - Coordinating rendering via RendererManager for all active viewports
+ */
+declare class CameraManager {
+    /** Named camera registry */
+    private cameras;
+    /** Currently active cameras, ordered by render layer (first = bottom) */
+    private _activeCameras;
+    /** Auto-created debug camera with orbit controls */
+    private _debugCamera;
+    /** Reference to the shared renderer manager */
+    private _rendererManager;
+    /** Scene reference */
+    private _sceneRef;
+    /** Counter for auto-generated camera names */
+    private _autoNameCounter;
+    constructor();
+    /**
+     * Get the list of currently active cameras.
+     */
+    get activeCameras(): ReadonlyArray<ZylemCamera>;
+    /**
+     * Get the primary active camera (first in the active list).
+     */
+    get primaryCamera(): ZylemCamera | null;
+    /**
+     * Get the debug camera.
+     */
+    get debugCamera(): ZylemCamera | null;
+    /**
+     * Get all registered cameras.
+     */
+    get allCameras(): ReadonlyArray<ZylemCamera>;
+    /**
+     * Add a camera to the manager.
+     * If no name is provided, one is auto-generated.
+     * The first camera added becomes the active camera.
+     *
+     * @param camera The ZylemCamera instance to add
+     * @param name Optional name for lookup
+     * @returns The assigned name
+     */
+    addCamera(camera: ZylemCamera, name?: string): string;
+    /**
+     * Remove a camera by name or reference.
+     * Cannot remove the debug camera via this method.
+     */
+    removeCamera(nameOrRef: string | ZylemCamera): boolean;
+    /**
+     * Set a camera as the primary active camera (replaces all active cameras
+     * except additional viewport cameras).
+     *
+     * @param nameOrRef Camera name or reference to activate
+     */
+    setActiveCamera(nameOrRef: string | ZylemCamera): boolean;
+    /**
+     * Add a camera as an additional active camera (for split-screen or PiP).
+     */
+    addActiveCamera(nameOrRef: string | ZylemCamera): boolean;
+    /**
+     * Remove a camera from the active render list (does not remove from registry).
+     */
+    deactivateCamera(nameOrRef: string | ZylemCamera): boolean;
+    /**
+     * Get a camera by name.
+     */
+    getCamera(name: string): ZylemCamera | null;
+    /**
+     * Setup all cameras with the given scene and renderer manager.
+     * Also creates the debug camera.
+     */
+    setup(scene: Scene, rendererManager: RendererManager): Promise<void>;
+    /**
+     * Update all active cameras' controllers.
+     */
+    update(delta: number): void;
+    /**
+     * Render all active cameras through the renderer manager.
+     * RTT cameras (those with a renderTarget) are rendered first to their
+     * offscreen textures, then viewport cameras are rendered to the screen.
+     */
+    render(scene: Scene): void;
+    private updateOrbitingCamerasForRender;
+    /**
+     * Create a default third-person camera if no cameras have been added.
+     */
+    ensureDefaultCamera(): ZylemCamera;
+    /**
+     * Dispose all cameras and cleanup.
+     */
+    dispose(): void;
+    /**
+     * Create the always-available debug camera with orbit controls.
+     */
+    private createDebugCamera;
+    /**
+     * Resolve a camera from a name or reference.
+     */
+    private resolveCamera;
+}
+
+interface SceneState {
+    backgroundColor: Color | string;
+    backgroundImage: string | null;
+    backgroundShader?: ZylemShader | null;
+    /**
+     * When `false`, skip the engine's built-in ambient + directional lights so
+     * the caller can configure the scene's lighting entirely via
+     * `createLight(...)` entities. Defaults to `true` for backward
+     * compatibility with existing demos.
+     */
+    defaultLighting?: boolean;
+}
+declare class ZylemScene implements Entity<ZylemScene> {
+    type: string;
+    _setup?: SetupFunction<ZylemScene>;
+    scene: Scene;
+    /** @deprecated Use cameraManager instead */
+    zylemCamera: ZylemCamera;
+    cameraManager: CameraManager | null;
+    containerElement: HTMLElement | null;
+    update: LifecycleFunction<ZylemScene>;
+    _collision?: ((entity: any, other: any, globals?: any) => void) | undefined;
+    _destroy?: ((globals?: any) => void) | undefined;
+    name?: string | undefined;
+    tag?: Set<string> | undefined;
+    private skyboxMaterial;
+    private skyboxMesh;
+    constructor(id: string, camera: ZylemCamera, state: SceneState);
+    /**
+     * Create a large inverted box with the shader for a skybox effect.
+     *
+     * WebGPU-only: background shaders must be authored in TSL
+     * ({@link ZylemTSLShader}). A GLSL shader logs a warning and is ignored
+     * (the solid background color is kept).
+     */
+    private setupBackgroundShader;
+    setup(): void;
+    destroy(): void;
+    /**
+     * Setup camera with the scene.
+     * Supports both legacy single camera and CameraManager modes.
+     */
+    setupCamera(scene: Scene, camera: ZylemCamera, rendererManager?: RendererManager): Promise<void>;
+    /**
+     * Setup with a CameraManager (multi-camera support).
+     */
+    setupCameraManager(scene: Scene, cameraManager: CameraManager, rendererManager: RendererManager): Promise<void>;
+    /**
+     * Add a camera (rig or direct) to the scene graph.
+     */
+    private addCameraToScene;
+    /**
+     * Setup scene lighting
+     */
+    setupLighting(scene: Scene): void;
+    /**
+     * Update renderer size - delegates to camera manager or camera
+     */
+    updateRenderer(width: number, height: number): void;
+    /**
+     * Add object to scene
+     */
+    add(object: Object3D, position?: Vector3): void;
+    /**
+     * Add game entity to scene
+     */
+    addEntity(entity: GameEntity<any>): void;
+    /**
+     * Add an entity's group or mesh to the scene (for late-loaded models).
+     * Uses entity's current body position if physics is active.
+     *
+     * Fog entities ({@link ZylemFog}) are routed through the normal add
+     * pipeline so their empty placeholder group is parented for cleanup,
+     * but they also get an `attachToScene` call that wires `scene.fog`
+     * and starts the optional material patcher.
+     */
+    addEntityGroup(entity: GameEntity<any>): void;
+    private isAttachedOutsideScene;
+    /**
+     * Add debug helpers to scene
+     */
+    debugScene(): void;
+    /**
+     * Per-frame skybox hook. Ensures the skybox cube follows the active camera
+     * position so it always appears infinitely far away regardless of camera
+     * movement. TSL background shaders animate via the `time` node, which the
+     * renderer advances automatically.
+     */
+    updateSkybox(_delta: number): void;
+}
+
+/**
+ * Host-provided debug signals for wasm runtime adapters (no direct `debugState` import in adapters).
+ */
+interface RuntimeDebugBinding {
+    /** When true, show wasm-side diagnostics (e.g. instanced collision heat tint). */
+    runtimeDiagnostics(): boolean;
+}
+interface StageRuntimeContext {
+    scene: ZylemScene;
+    world: ZylemWorld;
+    camera: ZylemCamera;
+    /** Optional; when set, adapters may enable extra runtime visualization. */
+    debug?: RuntimeDebugBinding;
+}
+interface StageRuntimeStepContext extends StageRuntimeContext {
+    delta: number;
+    inputs: Inputs;
+}
+interface StageRuntimeAdapter {
+    init(context: StageRuntimeContext): Promise<void> | void;
+    step(context: StageRuntimeStepContext): void;
+    destroy(context: StageRuntimeContext | null): void;
+    ownsEntity(entity: GameEntity<any>): boolean;
+    rendersEntity(entity: GameEntity<any>): boolean;
+    registerEntity(entity: GameEntity<any>): void;
+    unregisterEntity(entity: GameEntity<any>): void;
+    /**
+     * Optional: when implemented, the stage debug delegate will draw the
+     * returned line segments alongside the TS Rapier debug overlay so wasm
+     * runtime adapters can visualize their own colliders. Returning `null`
+     * (or omitting the method entirely) disables the second pass.
+     */
+    getDebugRender?(): {
+        vertices: Float32Array;
+        colors: Float32Array;
+    } | null;
+}
+interface ZylemRuntimeStageAdapterSource {
+    source: RequestInfo | URL | ArrayBuffer;
+}
+declare function createZylemRuntimeStageAdapter(options: ZylemRuntimeStageAdapterSource): StageRuntimeAdapter;
+
+export { type CameraBehavior as C, type PerspectiveType as P, type RuntimeDebugBinding as R, type StageRuntimeAdapter as S, type TransformLike as T, type Viewport as V, type ZylemRenderer as Z, type StageRuntimeContext as a, type StageRuntimeStepContext as b, createZylemRuntimeStageAdapter as c, Perspectives as d, type RendererType as e, CameraManager as f, type CameraPose as g, type PoseDelta as h, isWebGPUSupported as i, type CameraContext as j, type CameraPerspective as k, type CameraAction as l, type CameraPipelineState as m, CameraPipeline as n, ZylemCamera as o, ZylemScene as p, RendererManager as q };