@zylem/game-lib 0.6.4 → 0.8.0

package/dist/zylem-camera-C3bn6BTI.d.ts

@@ -0,0 +1,575 @@
+import { Object3D, Vector2, Scene, Camera, Vector3, Quaternion, RenderTarget, Texture } from 'three';
+import { S as StageEntity } from './entity-DZbFQ1Wg.js';
+import { WebGPURenderer, RenderPipeline } from 'three/webgpu';
+import { R as ResolvedStageTransition } from './stage-transition-CmGpV4tc.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;
+}
+
+/**
+ * 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;
+}
+/**
+ * A postprocessing effect for the render pipeline. Receives the current
+ * pipeline node (initially the scene pass) and returns the transformed node.
+ * `ctx.scenePass` is the original scene `PassNode` for effects that need
+ * extra channels (depth, velocity, ...). `ctx.scene`/`ctx.camera` are the
+ * rendered scene and camera, for effects that build their own scene pass
+ * (e.g. pixelation, retro). Such pass-replacing effects should be first in
+ * the effect chain — the default scene pass simply goes unused.
+ *
+ * Structurally compatible with `ZylemPostEffect` from `@zylem/shaders`.
+ */
+type ZylemPostEffect = (inputNode: any, ctx: {
+    scenePass: any;
+    scene: any;
+    camera: any;
+}) => any;
+/**
+ * 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;
+    private _initialized;
+    private _sceneRef;
+    private _lastAnimationTimestamp;
+    /** Registered postprocessing effects, applied in order over the scene pass. */
+    private _postEffects;
+    /** Scene/camera the current pipeline was built for (for rebuilds). */
+    private _postSceneRef;
+    private _postCameraRef;
+    /** In-flight stage transition, if any. */
+    private _transition;
+    constructor(screenResolution?: Vector2);
+    /**
+     * 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;
+    /** Whether a stage transition is currently in flight. */
+    get transitionActive(): boolean;
+    /**
+     * Arm a stage transition: renders one final frame of the outgoing scene
+     * into a texture, to be blended with the incoming stage's frames once
+     * its pipeline is set up. Call before tearing down the outgoing stage.
+     */
+    beginSnapshotTransition(resolved: ResolvedStageTransition, scene: Scene, camera: Camera): void;
+    /**
+     * Complete the active transition immediately: rebuild the normal
+     * pipeline, release transition resources, and fire `onComplete`.
+     * No-op when no transition is active.
+     */
+    finishTransition(): void;
+    /**
+     * Drop the active transition without rebuilding the pipeline (renderer
+     * teardown path). Still fires `onComplete`.
+     */
+    private cancelTransition;
+    private releaseTransitionResources;
+    /** Advance transition progress; called once per render-loop frame. */
+    private advanceTransition;
+    /**
+     * Register postprocessing effects (e.g. from `@zylem/shaders`). Effects
+     * are applied in order between the scene pass and the display output
+     * transform. If a pipeline is already active it is rebuilt immediately;
+     * otherwise the effects apply on the next {@link setupPostProcessing}.
+     */
+    setPostProcessingEffects(effects: ZylemPostEffect[]): 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;
+    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);
+    /**
+     * 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;
+    /**
+     * Frame the debug orbit camera on an Object3D (AABB fit).
+     */
+    frameObject(object: Object3D): 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;
+}
+
+export { type CameraPose as C, type PerspectiveType as P, RendererManager as R, type TransformLike as T, type Viewport as V, type ZylemPostEffect as Z, Perspectives as a, type ZylemRenderer as b, type PoseDelta as c, type CameraContext as d, type CameraPerspective as e, type CameraBehavior as f, type CameraAction as g, type CameraPipelineState as h, isWebGPUSupported as i, CameraPipeline as j, ZylemCamera as k };