@zylem/game-lib 0.6.2 → 0.6.3

package/dist/camera-B5e4c78l.d.ts

@@ -0,0 +1,468 @@
+import { Object3D, WebGLRenderer, Vector2, Scene, Camera, Vector3 } 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";
+};
+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;
+    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 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;
+}
+
+/**
+ * Interface for perspective-specific camera controllers
+ */
+interface PerspectiveController {
+    setup(params: {
+        screenResolution: Vector2;
+        renderer: ZylemRenderer;
+        scene: Scene;
+        camera: ZylemCamera;
+    }): void;
+    update(delta: number): void;
+    resize(width: number, height: number): void;
+}
+/**
+ * ZylemCamera is a lightweight camera wrapper that manages the Three.js camera,
+ * perspective controller, and viewport configuration. It no longer owns a renderer;
+ * rendering is handled by RendererManager.
+ */
+declare class ZylemCamera {
+    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.
+     * Replaces the old single `target` property.
+     */
+    targets: StageEntity[];
+    /**
+     * @deprecated Use `targets` array instead. This getter/setter is kept for backward compatibility.
+     */
+    get target(): StageEntity | null;
+    set target(entity: StageEntity | null);
+    perspectiveController: PerspectiveController | null;
+    private orbitController;
+    private _useOrbitalControls;
+    /** Reference to the shared renderer manager (set during setup) */
+    private _rendererManager;
+    constructor(perspective: PerspectiveType, screenResolution: Vector2, frustumSize?: number, rendererType?: RendererType);
+    /**
+     * Setup the camera with a scene and renderer manager.
+     * The renderer manager provides shared rendering infrastructure.
+     */
+    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 camera controllers (called each frame).
+     * Does NOT render -- rendering is handled by RendererManager.
+     */
+    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;
+    /**
+     * Dispose camera resources (not the renderer -- that's managed by RendererManager).
+     */
+    destroy(): void;
+    /**
+     * Attach a delegate to react to debug state changes.
+     */
+    setDebugDelegate(delegate: CameraDebugDelegate | null): void;
+    /**
+     * Resize camera projection.
+     */
+    resize(width: number, height: number): void;
+    /**
+     * Set the viewport for this camera (normalized 0-1 coordinates).
+     */
+    setViewport(x: number, y: number, width: number, height: number): void;
+    /**
+     * Create camera based on perspective type
+     */
+    private createCameraForPerspective;
+    /**
+     * Initialize perspective-specific controller
+     */
+    private initializePerspectiveController;
+    private createThirdPersonCamera;
+    private createFirstPersonCamera;
+    private createIsometricCamera;
+    private createFlat2DCamera;
+    private createFixed2DCamera;
+    private moveCamera;
+    move(position: Vector3): void;
+    rotate(pitch: number, yaw: number, roll: number): void;
+    /**
+     * Check if this perspective type needs a camera rig
+     */
+    private needsRig;
+    /**
+     * 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;
+}
+
+/**
+ * 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.
+     */
+    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;
+}
+
+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;
+}
+/**
+ * CameraWrapper is the user-facing camera handle returned by createCamera().
+ * It provides convenience methods for target management, orbital controls, and viewport configuration.
+ */
+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;
+}
+/**
+ * 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, type PerspectiveType as P, RendererManager as R, type Viewport as V, ZylemCamera as Z, type CameraDebugDelegate as a, type CameraDebugState as b, CameraWrapper as c, createCamera as d, type CameraOptions as e, Perspectives as f, type RendererType as g, type ZylemRenderer as h, isWebGPUSupported as i };

package/dist/camera.d.ts

@@ -1,5 +1,6 @@
-export { P as PerspectiveType, d as Perspectives, c as createCamera } from './camera-CeJPAgGg.js';
+export { C as CameraManager, e as CameraOptions, c as CameraWrapper, P as PerspectiveType, f as Perspectives, g as RendererType, V as Viewport, h as ZylemRenderer, d as createCamera, i as isWebGPUSupported } from './camera-B5e4c78l.js';
 import 'three';
-import 'three/examples/jsm/postprocessing/EffectComposer.js';
 import './entity-Bq_eNEDI.js';
 import '@dimforge/rapier3d-compat';
+import 'three/webgpu';
+import 'three/examples/jsm/postprocessing/EffectComposer.js';