@zylem/game-lib 0.6.2 → 0.6.4

package/dist/camera-4XO5gbQH.d.ts

@@ -0,0 +1,905 @@
+import { Object3D, WebGLRenderer, Vector2, Scene, Camera, Vector3, Quaternion, WebGLRenderTarget, Texture } from 'three';
+import { S as StageEntity } from './entity-Bq_eNEDI.js';
+import { WebGPURenderer } from 'three/webgpu';
+import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer.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 for choosing rendering backend
+ * - 'auto': Try WebGPU first, fall back to WebGL
+ * - 'webgpu': Force WebGPU (error if not supported)
+ * - 'webgl': Force WebGL
+ */
+type RendererType = 'auto' | 'webgpu' | 'webgl';
+/**
+ * Union type for renderer instances
+ */
+type ZylemRenderer = WebGLRenderer | 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
+ */
+declare function isWebGPUSupported(): Promise<boolean>;
+/**
+ * RendererManager owns the shared WebGL/WebGPU renderer, canvas element,
+ * effect composer, and render loop. There is one RendererManager per game.
+ *
+ * It iterates active cameras and renders each with its configured viewport.
+ */
+declare class RendererManager {
+    renderer: ZylemRenderer;
+    composer: EffectComposer;
+    screenResolution: Vector2;
+    rendererType: RendererType;
+    private _isWebGPU;
+    private _initialized;
+    private _sceneRef;
+    private _lastAnimationTimestamp;
+    constructor(screenResolution?: Vector2, rendererType?: RendererType);
+    /**
+     * Check if the renderer has been initialized
+     */
+    get initialized(): boolean;
+    /**
+     * Check if using WebGPU renderer
+     */
+    get isWebGPU(): boolean;
+    /**
+     * Initialize the renderer (must be called before rendering).
+     * Async because WebGPU requires async initialization.
+     */
+    initRenderer(): Promise<void>;
+    /**
+     * Set the current scene reference for rendering.
+     */
+    setScene(scene: Scene): void;
+    /**
+     * Setup post-processing render pass for a camera (WebGL only).
+     */
+    setupRenderPass(scene: Scene, camera: Camera): void;
+    /**
+     * 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 based on the camera's viewport config.
+     */
+    renderCamera(scene: Scene, camera: ZylemCamera): void;
+    /**
+     * Render a camera to its offscreen render target (WebGL only).
+     * Bypasses the EffectComposer since post-processing is not needed
+     * for render-to-texture output.
+     *
+     * 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).
+     */
+    renderCameras(scene: Scene, cameras: ZylemCamera[]): void;
+    /**
+     * Simple single-camera render (backwards compatible).
+     * Uses the full viewport for a single camera.
+     */
+    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, composer, 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().
+     */
+    renderTarget: WebGLRenderTarget | 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;
+    /**
+     * 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): WebGLRenderTarget;
+    /**
+     * 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 Composer 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;
+    /**
+     * 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;
+}
+
+/**
+ * Configuration for the third-person perspective.
+ */
+interface ThirdPersonOptions {
+    /** Distance behind the target. Default 8. */
+    distance?: number;
+    /** Height above the target. Default 5. */
+    height?: number;
+    /** Lateral offset from the target (shoulder cam). Default 0. */
+    shoulderOffset?: number;
+    /** Key in CameraContext.targets to follow. Default 'primary'. */
+    targetKey?: string;
+    /** Perspective field of view. Default 75. */
+    fov?: number;
+    /** Padding multiplier when framing multiple targets. Default 1.5. */
+    paddingFactor?: number;
+    /** Minimum camera distance when multi-framing. Default 5. */
+    minDistance?: number;
+    /** Fallback camera position when no targets exist (e.g. the user-specified initial position). */
+    initialPosition?: Vector3;
+    /** Fallback lookAt point when no targets exist. */
+    initialLookAt?: Vector3;
+}
+/**
+ * Third-person 3D perspective.
+ *
+ * - 0 targets: returns a static pose behind the origin.
+ * - 1 target: camera positioned behind and above the target, looking at it.
+ * - 2+ targets: weighted-centroid framing with dynamic distance.
+ */
+declare class ThirdPersonPerspective implements CameraPerspective {
+    readonly id = "third-person";
+    readonly defaults: {
+        damping: number;
+    };
+    private opts;
+    private initialPosition?;
+    private initialLookAt?;
+    constructor(options?: ThirdPersonOptions);
+    getBasePose(ctx: CameraContext): CameraPose;
+    /**
+     * No targets: use the user-specified initial position if available,
+     * otherwise fall back to a default pose behind the origin.
+     */
+    private staticPose;
+    /**
+     * Single target: position = target + offset, lookAt = target.
+     */
+    private singleTargetPose;
+    /**
+     * Multi-target: compute centroid and adjust distance to frame all targets.
+     */
+    private multiTargetPose;
+}
+
+/**
+ * Configuration for the fixed 2D perspective.
+ */
+interface Fixed2DOptions {
+    /** Fixed camera position. Default (0, 0, 10). */
+    position?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Orthographic zoom (frustum size). Default 10. */
+    zoom?: number;
+}
+/**
+ * Fixed 2D perspective.
+ *
+ * Returns a static orthographic pose looking down the Z-axis.
+ * No target following -- the camera stays at the configured position.
+ */
+declare class Fixed2DPerspective implements CameraPerspective {
+    readonly id = "fixed-2d";
+    readonly defaults: {
+        damping: number;
+    };
+    private opts;
+    constructor(options?: Fixed2DOptions);
+    getBasePose(_ctx: CameraContext): CameraPose;
+}
+
+/**
+ * Configuration for the first-person perspective.
+ */
+interface FirstPersonOptions {
+    /** Vertical offset above the target entity's position (eye height). @default 1.7 */
+    eyeHeight?: number;
+    /** Default field of view in degrees. @default 75 */
+    defaultFov?: number;
+    /** Maximum pitch angle in radians. @default Math.PI/2 - 0.01 */
+    pitchLimit?: number;
+    /** Lerp speed for smooth look-at transitions. @default 5 */
+    lookAtLerpSpeed?: number;
+    /** Lerp speed for FOV zoom transitions. @default 8 */
+    fovLerpSpeed?: number;
+    /** Key in CameraContext.targets to follow. @default 'primary' */
+    targetKey?: string;
+    /** Fallback position when no target entity is attached. */
+    initialPosition?: Vector3;
+    /** Fallback look-at point used to derive initial yaw/pitch when no target. */
+    initialLookAt?: Vector3;
+}
+/**
+ * First-person camera perspective.
+ *
+ * Position is derived from the attached target entity (+ eye height).
+ * Rotation is driven via `look()` / `setLook()` methods called by game code
+ * or a future FPS behavior. Supports smooth FOV zoom and lerp'd look-at.
+ */
+declare class FirstPersonPerspective implements CameraPerspective {
+    readonly id = "first-person";
+    readonly defaults: {
+        damping: number;
+    };
+    private opts;
+    /** Fallback position when no target entity is attached. Mutate directly for manual movement. */
+    initialPosition?: Vector3;
+    private initialLookAt?;
+    private _yaw;
+    private _pitch;
+    private _currentFov;
+    private _targetFov;
+    private _lookAtTarget;
+    private _lookAtLerpSpeed;
+    private _currentRotation;
+    private _rotationInitialized;
+    constructor(options?: FirstPersonOptions);
+    /** Accumulate yaw and pitch deltas. Pitch is clamped to the configured limit. */
+    look(deltaYaw: number, deltaPitch: number): void;
+    /** Set absolute yaw and pitch. Pitch is clamped to the configured limit. */
+    setLook(yaw: number, pitch: number): void;
+    /** Current yaw in radians. */
+    get yaw(): number;
+    /** Current pitch in radians. */
+    get pitch(): number;
+    /** Set the target FOV for a smooth zoom transition (e.g. sniper scope). */
+    zoom(fov: number): void;
+    /** Return to the default FOV. */
+    resetZoom(): void;
+    /** Current field of view. */
+    get currentFov(): number;
+    /**
+     * Enable smooth look-at toward a world position.
+     * The camera will slerp from the current rotation toward the look-at direction.
+     */
+    lookAt(target: Vector3, lerpSpeed?: number): void;
+    /** Disable look-at and return to manual yaw/pitch control. */
+    clearLookAt(): void;
+    getBasePose(ctx: CameraContext): CameraPose;
+    private computePosition;
+    private computeRotation;
+    private lerpFov;
+    private deriveYawPitchFromLookAt;
+    private deriveYawPitchFromQuaternion;
+}
+
+/**
+ * Perspective-specific options union.
+ * Extend as new perspective types are added.
+ */
+type PerspectiveOptions = ThirdPersonOptions | Fixed2DOptions | FirstPersonOptions;
+/**
+ * Factory: create a CameraPerspective from a PerspectiveType string.
+ * Unrecognized types default to ThirdPersonPerspective.
+ */
+declare function createPerspective(type: PerspectiveType, options?: PerspectiveOptions): CameraPerspective;
+
+interface CameraOptions {
+    perspective?: PerspectiveType;
+    position?: Vector3 | {
+        x: number;
+        y: number;
+        z: number;
+    };
+    target?: Vector3 | {
+        x: number;
+        y: number;
+        z: number;
+    } | any;
+    zoom?: number;
+    screenResolution?: Vector2;
+    /**
+     * Renderer type: 'auto' | 'webgpu' | 'webgl'
+     * Use 'webgpu' for TSL shaders
+     * @default 'webgl'
+     */
+    rendererType?: RendererType;
+    /**
+     * Enable orbital controls for this camera.
+     * Can be toggled at runtime via enableOrbitalControls() / disableOrbitalControls().
+     * @default false
+     */
+    useOrbitalControls?: boolean;
+    /**
+     * Viewport in normalized coordinates (0-1).
+     * Defines where this camera renders on the canvas.
+     * @default { x: 0, y: 0, width: 1, height: 1 } (fullscreen)
+     */
+    viewport?: Viewport;
+    /**
+     * Optional name for camera manager lookup.
+     */
+    name?: string;
+    /**
+     * Initial behaviors to attach to the camera pipeline.
+     * Keys are used for idempotent add/remove.
+     */
+    behaviors?: Record<string, CameraBehavior>;
+    /**
+     * Pipeline smoothing factor (0-1).
+     * 1 = instant snap, 0 = no movement.
+     * @default 0.15
+     */
+    damping?: number;
+    /**
+     * When set, the camera renders to an offscreen texture instead of a
+     * screen viewport. Use with setCameraFeed() to display the feed on
+     * an in-scene mesh (jumbotron, security monitor, portal, etc.).
+     *
+     * @default undefined (renders to screen)
+     */
+    renderToTexture?: {
+        /** Texture width in pixels. @default 512 */
+        width?: number;
+        /** Texture height in pixels. @default 512 */
+        height?: number;
+    };
+    /**
+     * When true, this camera will not activate orbital controls in debug mode.
+     * The pipeline (and its behaviors) will always run for this camera.
+     * Use for cameras with custom behaviors (e.g. FPS mouse-look) that must
+     * control the camera through the pipeline rather than debug orbit controls.
+     * @default false
+     */
+    skipDebugOrbit?: boolean;
+}
+/**
+ * CameraWrapper is the user-facing camera handle returned by createCamera().
+ * It provides convenience methods for target management, orbital controls,
+ * viewport configuration, and the camera pose pipeline.
+ */
+declare class CameraWrapper {
+    cameraRef: ZylemCamera;
+    constructor(camera: ZylemCamera);
+    /**
+     * Add a target entity for the camera to follow/frame.
+     * With multiple targets, the camera auto-frames to include all of them.
+     */
+    addTarget(entity: StageEntity): void;
+    /**
+     * Remove a target entity from the camera.
+     */
+    removeTarget(entity: StageEntity): void;
+    /**
+     * Clear all targets. Camera will look at world origin.
+     */
+    clearTargets(): void;
+    /**
+     * Enable orbital controls for this camera.
+     * Allows the user to orbit, pan, and zoom the camera.
+     */
+    enableOrbitalControls(): void;
+    /**
+     * Disable orbital controls for this camera.
+     */
+    disableOrbitalControls(): void;
+    /**
+     * Set the viewport for this camera (normalized 0-1 coordinates).
+     * @param x Left edge (0 = left of canvas)
+     * @param y Bottom edge (0 = bottom of canvas)
+     * @param width Width as fraction of canvas
+     * @param height Height as fraction of canvas
+     */
+    setViewport(x: number, y: number, width: number, height: number): void;
+    /**
+     * Add or replace a behavior by key (idempotent).
+     * Behaviors modify the desired camera pose each frame.
+     *
+     * @param key   Unique key for this behavior (used for replacement/removal).
+     * @param behavior  The CameraBehavior implementation.
+     */
+    addBehavior(key: string, behavior: CameraBehavior): void;
+    /**
+     * Remove a behavior by key.
+     */
+    removeBehavior(key: string): boolean;
+    /**
+     * Add a transient action (screenshake, recoil, etc.).
+     * Actions apply additive deltas and self-expire when isDone() returns true.
+     */
+    addAction(action: CameraAction): void;
+    /**
+     * Switch the camera's active perspective at runtime.
+     * The first frame after switching snaps to the new pose (no lerp).
+     *
+     * @param type     Perspective type string (e.g. Perspectives.ThirdPerson).
+     * @param options  Perspective-specific options (distance, height, zoom, etc.).
+     */
+    setPerspective(type: PerspectiveType, options?: PerspectiveOptions): void;
+    /**
+     * Retrieve the active perspective instance, cast to the desired type.
+     * Useful for calling perspective-specific methods (e.g. FirstPersonPerspective.look()).
+     *
+     * @example
+     * const fps = camera.getPerspective<FirstPersonPerspective>();
+     * fps.look(dx, dy);
+     */
+    getPerspective<T extends CameraPerspective = CameraPerspective>(): T;
+    /**
+     * Return a debug snapshot of the camera pipeline state.
+     * Includes: active perspective, desired/final pose, behavior keys, action count.
+     */
+    getState(): CameraPipelineState;
+    /**
+     * Get the offscreen render texture for this camera.
+     * Returns null if the camera was not created with renderToTexture.
+     * Use with setCameraFeed() or apply directly to a mesh material.
+     */
+    getRenderTexture(): Texture | null;
+}
+/**
+ * Create a camera with the given options.
+ * Returns a CameraWrapper for convenient access to camera features.
+ */
+declare function createCamera(options: CameraOptions): CameraWrapper;
+
+export { CameraManager as C, FirstPersonPerspective as F, type PerspectiveType as P, RendererManager as R, type TransformLike as T, type Viewport as V, ZylemCamera as Z, CameraWrapper as a, type CameraBehavior as b, createCamera as c, type CameraOptions as d, Perspectives as e, type RendererType as f, type ZylemRenderer as g, type CameraPose as h, isWebGPUSupported as i, type PoseDelta as j, type CameraContext as k, type CameraPerspective as l, type CameraAction as m, type CameraPipelineState as n, CameraPipeline as o, ThirdPersonPerspective as p, Fixed2DPerspective as q, createPerspective as r, type ThirdPersonOptions as s, type Fixed2DOptions as t, type FirstPersonOptions as u, type PerspectiveOptions as v };