@zylem/game-lib 0.6.2 → 0.6.3

package/dist/camera.js

@@ -1,8 +1,8 @@
 // src/lib/camera/camera.ts
-import { Vector2 as Vector23, Vector3 as Vector34 } from "three";
+import { Vector2 as Vector24, Vector3 as Vector34 } from "three";
 
 // src/lib/camera/zylem-camera.ts
-import { PerspectiveCamera, Vector3 as Vector33, Object3D as Object3D2, OrthographicCamera, WebGLRenderer as WebGLRenderer3 } from "three";
+import { PerspectiveCamera as PerspectiveCamera2, Vector3 as Vector33, Object3D as Object3D2, OrthographicCamera } from "three";
 
 // src/lib/camera/perspective.ts
 var Perspectives = {
@@ -21,6 +21,12 @@ var ThirdPersonCamera = class {
   renderer = null;
   scene = null;
   cameraRef = null;
+  /** Padding multiplier when framing multiple targets. Higher = more zoom out. */
+  paddingFactor = 1.5;
+  /** Minimum camera distance when multi-framing (prevents extreme zoom-in). */
+  minDistance = 5;
+  /** Lerp factor for camera position smoothing. */
+  lerpFactor = 0.1;
   constructor() {
     this.distance = new Vector3(0, 5, 8);
   }
@@ -35,15 +41,59 @@ var ThirdPersonCamera = class {
     this.cameraRef = camera;
   }
   /**
-   * Update the third person camera
+   * Update the third person camera.
+   * Handles 0, 1, and multi-target scenarios.
    */
   update(delta) {
-    if (!this.cameraRef.target) {
+    if (!this.cameraRef) return;
+    const targets = this.cameraRef.targets;
+    if (targets.length === 0) {
+      this.cameraRef.camera.lookAt(new Vector3(0, 0, 0));
       return;
     }
-    const desiredCameraPosition = this.cameraRef.target.group.position.clone().add(this.distance);
-    this.cameraRef.camera.position.lerp(desiredCameraPosition, 0.1);
-    this.cameraRef.camera.lookAt(this.cameraRef.target.group.position);
+    if (targets.length === 1) {
+      this.updateSingleTarget(targets[0]);
+      return;
+    }
+    this.updateMultiTarget(targets);
+  }
+  /**
+   * Classic single-target follow: lerp to target position + offset, lookAt target.
+   */
+  updateSingleTarget(target) {
+    const useTarget = target.group?.position || new Vector3(0, 0, 0);
+    const desiredCameraPosition = useTarget.clone().add(this.distance);
+    this.cameraRef.camera.position.lerp(desiredCameraPosition, this.lerpFactor);
+    this.cameraRef.camera.lookAt(useTarget);
+  }
+  /**
+   * Multi-target framing: compute centroid, measure spread, zoom out to fit all.
+   */
+  updateMultiTarget(targets) {
+    const centroid = new Vector3();
+    for (const t of targets) {
+      centroid.add(t.group.position);
+    }
+    centroid.divideScalar(targets.length);
+    let maxDistFromCentroid = 0;
+    for (const t of targets) {
+      const dist = centroid.distanceTo(t.group.position);
+      if (dist > maxDistFromCentroid) {
+        maxDistFromCentroid = dist;
+      }
+    }
+    const dynamicDistance = Math.max(maxDistFromCentroid * this.paddingFactor, this.minDistance);
+    const offsetDirection = this.distance.clone().normalize();
+    const desiredCameraPosition = centroid.clone().add(
+      offsetDirection.multiplyScalar(dynamicDistance)
+    );
+    const baseLen = this.distance.length();
+    if (baseLen > 0) {
+      const heightRatio = this.distance.y / baseLen;
+      desiredCameraPosition.y = centroid.y + dynamicDistance * heightRatio;
+    }
+    this.cameraRef.camera.position.lerp(desiredCameraPosition, this.lerpFactor);
+    this.cameraRef.camera.lookAt(centroid);
   }
   /**
    * Handle resize events
@@ -54,7 +104,7 @@ var ThirdPersonCamera = class {
     }
   }
   /**
-   * Set the distance from the target
+   * Set the distance offset from the target
    */
   setDistance(distance) {
     this.distance = distance;
@@ -97,118 +147,6 @@ var Fixed2DCamera = class {
   }
 };
 
-// src/lib/camera/zylem-camera.ts
-import { EffectComposer } from "three/examples/jsm/postprocessing/EffectComposer.js";
-
-// src/lib/graphics/render-pass.ts
-import * as THREE from "three";
-
-// src/lib/graphics/shaders/vertex/object.shader.ts
-var objectVertexShader = `
-uniform vec2 uvScale;
-varying vec2 vUv;
-
-void main() {
-	vUv = uv;
-	vec4 mvPosition = modelViewMatrix * vec4( position, 1.0 );
-	gl_Position = projectionMatrix * mvPosition;
-}
-`;
-
-// src/lib/graphics/shaders/standard.shader.ts
-var fragment = `
-uniform sampler2D tDiffuse;
-varying vec2 vUv;
-
-void main() {
-	vec4 texel = texture2D( tDiffuse, vUv );
-
-	gl_FragColor = texel;
-}
-`;
-var standardShader = {
-  vertex: objectVertexShader,
-  fragment
-};
-
-// src/lib/graphics/render-pass.ts
-import { WebGLRenderTarget } from "three";
-import { Pass, FullScreenQuad } from "three/addons/postprocessing/Pass.js";
-var RenderPass = class extends Pass {
-  fsQuad;
-  resolution;
-  scene;
-  camera;
-  rgbRenderTarget;
-  normalRenderTarget;
-  normalMaterial;
-  constructor(resolution, scene, camera) {
-    super();
-    this.resolution = resolution;
-    this.fsQuad = new FullScreenQuad(this.material());
-    this.scene = scene;
-    this.camera = camera;
-    this.rgbRenderTarget = new WebGLRenderTarget(resolution.x * 4, resolution.y * 4);
-    this.normalRenderTarget = new WebGLRenderTarget(resolution.x * 4, resolution.y * 4);
-    this.normalMaterial = new THREE.MeshNormalMaterial();
-  }
-  render(renderer, writeBuffer) {
-    renderer.setRenderTarget(this.rgbRenderTarget);
-    renderer.render(this.scene, this.camera);
-    const overrideMaterial_old = this.scene.overrideMaterial;
-    renderer.setRenderTarget(this.normalRenderTarget);
-    this.scene.overrideMaterial = this.normalMaterial;
-    renderer.render(this.scene, this.camera);
-    this.scene.overrideMaterial = overrideMaterial_old;
-    const uniforms = this.fsQuad.material.uniforms;
-    uniforms.tDiffuse.value = this.rgbRenderTarget.texture;
-    uniforms.tDepth.value = this.rgbRenderTarget.depthTexture;
-    uniforms.tNormal.value = this.normalRenderTarget.texture;
-    uniforms.iTime.value += 0.01;
-    if (this.renderToScreen) {
-      renderer.setRenderTarget(null);
-    } else {
-      renderer.setRenderTarget(writeBuffer);
-    }
-    this.fsQuad.render(renderer);
-  }
-  material() {
-    return new THREE.ShaderMaterial({
-      uniforms: {
-        iTime: { value: 0 },
-        tDiffuse: { value: null },
-        tDepth: { value: null },
-        tNormal: { value: null },
-        resolution: {
-          value: new THREE.Vector4(
-            this.resolution.x,
-            this.resolution.y,
-            1 / this.resolution.x,
-            1 / this.resolution.y
-          )
-        }
-      },
-      vertexShader: standardShader.vertex,
-      fragmentShader: standardShader.fragment
-    });
-  }
-  dispose() {
-    try {
-      this.fsQuad?.dispose?.();
-    } catch {
-    }
-    try {
-      this.rgbRenderTarget?.dispose?.();
-      this.normalRenderTarget?.dispose?.();
-    } catch {
-    }
-    try {
-      this.normalMaterial?.dispose?.();
-    } catch {
-    }
-  }
-};
-
 // src/lib/camera/camera-debug-delegate.ts
 import { Vector3 as Vector32 } from "three";
 import { OrbitControls } from "three/addons/controls/OrbitControls.js";
@@ -233,6 +171,8 @@ var CameraOrbitController = class {
   savedDebugCameraQuaternion = null;
   savedDebugCameraZoom = null;
   savedDebugOrbitTarget = null;
+  /** Whether user-configured orbital controls are enabled (independent of debug) */
+  _userOrbitEnabled = false;
   constructor(camera, domElement, cameraRig) {
     this.camera = camera;
     this.domElement = domElement;
@@ -245,11 +185,17 @@ var CameraOrbitController = class {
     this.sceneRef = scene;
   }
   /**
-   * Check if debug mode is currently active (orbit controls enabled).
+   * Check if debug mode is currently active (orbit controls enabled via debug system).
    */
   get isActive() {
     return this.debugStateSnapshot.enabled;
   }
+  /**
+   * Check if any orbit controls are currently active (debug or user).
+   */
+  get isOrbitActive() {
+    return this.debugStateSnapshot.enabled || this._userOrbitEnabled;
+  }
   /**
    * Update orbit controls each frame.
    * Should be called from the camera's update loop.
@@ -261,6 +207,26 @@ var CameraOrbitController = class {
     }
     this.orbitControls?.update();
   }
+  /**
+   * Enable user-configured orbital controls (not debug mode).
+   * These orbit controls persist until explicitly disabled.
+   */
+  enableUserOrbitControls() {
+    this._userOrbitEnabled = true;
+    if (!this.orbitControls) {
+      this.enableOrbitControls();
+    }
+  }
+  /**
+   * Disable user-configured orbital controls.
+   * Will not disable orbit controls if debug mode is active.
+   */
+  disableUserOrbitControls() {
+    this._userOrbitEnabled = false;
+    if (!this.debugStateSnapshot.enabled) {
+      this.disableOrbitControls();
+    }
+  }
   /**
    * Attach a delegate to react to debug state changes.
    */
@@ -309,7 +275,9 @@ var CameraOrbitController = class {
     } else if (!state.enabled && wasEnabled) {
       this.saveDebugCameraState();
       this.orbitTarget = null;
-      this.disableOrbitControls();
+      if (!this._userOrbitEnabled) {
+        this.disableOrbitControls();
+      }
       this.reattachCameraToRig();
       this.restoreCameraState();
     } else if (state.enabled) {
@@ -463,94 +431,314 @@ var CameraOrbitController = class {
   }
 };
 
-// src/lib/camera/zylem-camera.ts
-var ZylemCamera = class {
-  cameraRig = null;
+// src/lib/camera/renderer-manager.ts
+import { Vector2 as Vector22, WebGLRenderer as WebGLRenderer2 } from "three";
+import { WebGPURenderer } from "three/webgpu";
+import { EffectComposer } from "three/examples/jsm/postprocessing/EffectComposer.js";
+
+// src/lib/graphics/render-pass.ts
+import * as THREE from "three";
+
+// src/lib/graphics/shaders/vertex/object.shader.ts
+var objectVertexShader = `
+uniform vec2 uvScale;
+varying vec2 vUv;
+
+void main() {
+	vUv = uv;
+	vec4 mvPosition = modelViewMatrix * vec4( position, 1.0 );
+	gl_Position = projectionMatrix * mvPosition;
+}
+`;
+
+// src/lib/graphics/shaders/standard.shader.ts
+var fragment = `
+uniform sampler2D tDiffuse;
+varying vec2 vUv;
+
+void main() {
+	vec4 texel = texture2D( tDiffuse, vUv );
+
+	gl_FragColor = texel;
+}
+`;
+var standardShader = {
+  vertex: objectVertexShader,
+  fragment
+};
+
+// src/lib/graphics/render-pass.ts
+import { WebGLRenderTarget } from "three";
+import { Pass, FullScreenQuad } from "three/addons/postprocessing/Pass.js";
+var RenderPass = class extends Pass {
+  fsQuad;
+  resolution;
+  scene;
   camera;
-  screenResolution;
-  renderer;
-  composer;
-  _perspective;
-  target = null;
-  sceneRef = null;
-  frustumSize = 10;
-  // Perspective controller delegation
-  perspectiveController = null;
-  // Debug/orbit controls delegation
-  orbitController = null;
-  constructor(perspective, screenResolution, frustumSize = 10) {
-    this._perspective = perspective;
-    this.screenResolution = screenResolution;
-    this.frustumSize = frustumSize;
-    this.renderer = new WebGLRenderer3({ antialias: false, alpha: true });
-    this.renderer.setSize(screenResolution.x, screenResolution.y);
-    this.renderer.shadowMap.enabled = true;
-    this.composer = new EffectComposer(this.renderer);
-    const aspectRatio = screenResolution.x / screenResolution.y;
-    this.camera = this.createCameraForPerspective(aspectRatio);
-    if (this.needsRig()) {
-      this.cameraRig = new Object3D2();
-      this.cameraRig.position.set(0, 3, 10);
-      this.cameraRig.add(this.camera);
-      this.camera.lookAt(new Vector33(0, 2, 0));
-    } else {
-      this.camera.position.set(0, 0, 10);
-      this.camera.lookAt(new Vector33(0, 0, 0));
-    }
-    this.initializePerspectiveController();
-    this.orbitController = new CameraOrbitController(this.camera, this.renderer.domElement, this.cameraRig);
+  rgbRenderTarget;
+  normalRenderTarget;
+  normalMaterial;
+  constructor(resolution, scene, camera) {
+    super();
+    this.resolution = resolution;
+    this.fsQuad = new FullScreenQuad(this.material());
+    this.scene = scene;
+    this.camera = camera;
+    this.rgbRenderTarget = new WebGLRenderTarget(resolution.x * 4, resolution.y * 4);
+    this.normalRenderTarget = new WebGLRenderTarget(resolution.x * 4, resolution.y * 4);
+    this.normalMaterial = new THREE.MeshNormalMaterial();
   }
-  /**
-   * Setup the camera with a scene
-   */
-  async setup(scene) {
-    this.sceneRef = scene;
-    let renderResolution = this.screenResolution.clone().divideScalar(2);
-    renderResolution.x |= 0;
-    renderResolution.y |= 0;
-    const pass = new RenderPass(renderResolution, scene, this.camera);
-    this.composer.addPass(pass);
-    if (this.perspectiveController) {
-      this.perspectiveController.setup({
-        screenResolution: this.screenResolution,
-        renderer: this.renderer,
-        scene,
-        camera: this
-      });
+  render(renderer, writeBuffer) {
+    renderer.setRenderTarget(this.rgbRenderTarget);
+    renderer.render(this.scene, this.camera);
+    const overrideMaterial_old = this.scene.overrideMaterial;
+    renderer.setRenderTarget(this.normalRenderTarget);
+    this.scene.overrideMaterial = this.normalMaterial;
+    renderer.render(this.scene, this.camera);
+    this.scene.overrideMaterial = overrideMaterial_old;
+    const uniforms = this.fsQuad.material.uniforms;
+    uniforms.tDiffuse.value = this.rgbRenderTarget.texture;
+    uniforms.tDepth.value = this.rgbRenderTarget.depthTexture;
+    uniforms.tNormal.value = this.normalRenderTarget.texture;
+    uniforms.iTime.value += 0.01;
+    if (this.renderToScreen) {
+      renderer.setRenderTarget(null);
+    } else {
+      renderer.setRenderTarget(writeBuffer);
     }
-    this.orbitController?.setScene(scene);
-    this.renderer.setAnimationLoop((delta) => {
-      this.update(delta || 0);
-    });
+    this.fsQuad.render(renderer);
   }
-  /**
-   * Update camera and render
-   */
-  update(delta) {
-    this.orbitController?.update();
-    if (this.perspectiveController && !this.isDebugModeActive()) {
-      this.perspectiveController.update(delta);
+  material() {
+    return new THREE.ShaderMaterial({
+      uniforms: {
+        iTime: { value: 0 },
+        tDiffuse: { value: null },
+        tDepth: { value: null },
+        tNormal: { value: null },
+        resolution: {
+          value: new THREE.Vector4(
+            this.resolution.x,
+            this.resolution.y,
+            1 / this.resolution.x,
+            1 / this.resolution.y
+          )
+        }
+      },
+      vertexShader: standardShader.vertex,
+      fragmentShader: standardShader.fragment
+    });
+  }
+  dispose() {
+    try {
+      this.fsQuad?.dispose?.();
+    } catch {
+    }
+    try {
+      this.rgbRenderTarget?.dispose?.();
+      this.normalRenderTarget?.dispose?.();
+    } catch {
+    }
+    try {
+      this.normalMaterial?.dispose?.();
+    } catch {
+    }
+  }
+};
+
+// src/lib/camera/renderer-manager.ts
+var DEFAULT_VIEWPORT = { x: 0, y: 0, width: 1, height: 1 };
+async function isWebGPUSupported() {
+  if (!("gpu" in navigator)) return false;
+  try {
+    const adapter = await navigator.gpu.requestAdapter();
+    return adapter !== null;
+  } catch {
+    return false;
+  }
+}
+var RendererManager = class {
+  renderer;
+  composer;
+  screenResolution;
+  rendererType;
+  _isWebGPU = false;
+  _initialized = false;
+  _sceneRef = null;
+  constructor(screenResolution, rendererType = "webgl") {
+    this.screenResolution = screenResolution || new Vector22(window.innerWidth, window.innerHeight);
+    this.rendererType = rendererType;
+  }
+  /**
+   * Check if the renderer has been initialized
+   */
+  get initialized() {
+    return this._initialized;
+  }
+  /**
+   * Check if using WebGPU renderer
+   */
+  get isWebGPU() {
+    return this._isWebGPU;
+  }
+  /**
+   * Initialize the renderer (must be called before rendering).
+   * Async because WebGPU requires async initialization.
+   */
+  async initRenderer() {
+    if (this._initialized) return;
+    let useWebGPU = false;
+    if (this.rendererType === "webgpu") {
+      useWebGPU = true;
+    } else if (this.rendererType === "auto") {
+      useWebGPU = await isWebGPUSupported();
     }
-    this.composer.render(delta);
+    if (useWebGPU) {
+      try {
+        this.renderer = new WebGPURenderer({ antialias: true });
+        await this.renderer.init();
+        this._isWebGPU = true;
+        console.log("RendererManager: Using WebGPU renderer");
+      } catch (e) {
+        console.warn("RendererManager: WebGPU init failed, falling back to WebGL", e);
+        this.renderer = new WebGLRenderer2({ antialias: false, alpha: true });
+        this._isWebGPU = false;
+      }
+    } else {
+      this.renderer = new WebGLRenderer2({ antialias: false, alpha: true });
+      this._isWebGPU = false;
+      console.log("RendererManager: Using WebGL renderer");
+    }
+    this.renderer.setSize(this.screenResolution.x, this.screenResolution.y);
+    if (this.renderer instanceof WebGLRenderer2) {
+      this.renderer.shadowMap.enabled = true;
+    }
+    if (!this._isWebGPU) {
+      this.composer = new EffectComposer(this.renderer);
+    }
+    this._initialized = true;
   }
   /**
-   * Check if debug mode is active (orbit controls taking over camera)
+   * Set the current scene reference for rendering.
    */
-  isDebugModeActive() {
-    return this.orbitController?.isActive ?? false;
+  setScene(scene) {
+    this._sceneRef = scene;
   }
   /**
-   * Dispose renderer, composer, controls, and detach from scene
+   * Setup post-processing render pass for a camera (WebGL only).
    */
-  destroy() {
+  setupRenderPass(scene, camera) {
+    if (this._isWebGPU || !this.composer) return;
+    if (this.composer.passes.length > 0) {
+      this.composer.passes.forEach((p) => {
+        try {
+          p.dispose?.();
+        } catch {
+        }
+      });
+      this.composer.passes.length = 0;
+    }
+    const renderResolution = this.screenResolution.clone().divideScalar(2);
+    renderResolution.x |= 0;
+    renderResolution.y |= 0;
+    const pass = new RenderPass(renderResolution, scene, camera);
+    this.composer.addPass(pass);
+  }
+  /**
+   * Start the render loop. Calls the provided callback each frame.
+   */
+  startRenderLoop(onFrame) {
+    this.renderer.setAnimationLoop((delta) => {
+      onFrame(delta || 0);
+    });
+  }
+  /**
+   * Stop the render loop.
+   */
+  stopRenderLoop() {
     try {
       this.renderer.setAnimationLoop(null);
     } catch {
     }
-    try {
-      this.orbitController?.dispose();
-    } catch {
+  }
+  /**
+   * Render a scene from a single camera's perspective.
+   * Sets the viewport based on the camera's viewport config.
+   */
+  renderCamera(scene, camera) {
+    const vp = camera.viewport;
+    const w = this.screenResolution.x;
+    const h = this.screenResolution.y;
+    const pixelX = Math.floor(vp.x * w);
+    const pixelY = Math.floor(vp.y * h);
+    const pixelW = Math.floor(vp.width * w);
+    const pixelH = Math.floor(vp.height * h);
+    if (this.renderer instanceof WebGLRenderer2) {
+      this.renderer.setViewport(pixelX, pixelY, pixelW, pixelH);
+      this.renderer.setScissor(pixelX, pixelY, pixelW, pixelH);
+      this.renderer.setScissorTest(true);
+    }
+    if (this._isWebGPU) {
+      this.renderer.render(scene, camera.camera);
+    } else if (this.composer) {
+      this.composer.render(0);
     }
+  }
+  /**
+   * Render a scene from multiple cameras, each with their own viewport.
+   * Cameras are rendered in order (first = bottom layer, last = top layer).
+   */
+  renderCameras(scene, cameras) {
+    if (!scene || cameras.length === 0) return;
+    if (this.renderer instanceof WebGLRenderer2) {
+      this.renderer.setScissorTest(false);
+      this.renderer.clear();
+    }
+    for (const cam of cameras) {
+      this.renderCamera(scene, cam);
+    }
+    if (this.renderer instanceof WebGLRenderer2) {
+      this.renderer.setScissorTest(false);
+    }
+  }
+  /**
+   * Simple single-camera render (backwards compatible).
+   * Uses the full viewport for a single camera.
+   */
+  render(scene, camera) {
+    if (this._isWebGPU) {
+      this.renderer.render(scene, camera);
+    } else if (this.composer) {
+      this.composer.render(0);
+    }
+  }
+  /**
+   * Resize the renderer and update resolution.
+   */
+  resize(width, height) {
+    this.screenResolution.set(width, height);
+    this.renderer.setSize(width, height, false);
+    if (this.composer) {
+      this.composer.setSize(width, height);
+    }
+  }
+  /**
+   * Update renderer pixel ratio (DPR).
+   */
+  setPixelRatio(dpr) {
+    const safe = Math.max(1, Number.isFinite(dpr) ? dpr : 1);
+    this.renderer.setPixelRatio(safe);
+  }
+  /**
+   * Get the DOM element for the renderer.
+   */
+  getDomElement() {
+    return this.renderer.domElement;
+  }
+  /**
+   * Dispose renderer, composer, and related resources.
+   */
+  dispose() {
+    this.stopRenderLoop();
     try {
       this.composer?.passes?.forEach((p) => p.dispose?.());
       this.composer?.dispose?.();
@@ -560,7 +748,195 @@ var ZylemCamera = class {
       this.renderer.dispose();
     } catch {
     }
+    this._sceneRef = null;
+    this._initialized = false;
+  }
+};
+
+// src/lib/camera/zylem-camera.ts
+var ZylemCamera = class {
+  cameraRig = null;
+  camera;
+  screenResolution;
+  _perspective;
+  frustumSize = 10;
+  rendererType;
+  sceneRef = null;
+  /** Name for camera manager lookup */
+  name = "";
+  /**
+   * Viewport in normalized coordinates (0-1).
+   * Default is fullscreen: { x: 0, y: 0, width: 1, height: 1 }
+   */
+  viewport = { ...DEFAULT_VIEWPORT };
+  /**
+   * Multiple targets for the camera to follow/frame.
+   * Replaces the old single `target` property.
+   */
+  targets = [];
+  /**
+   * @deprecated Use `targets` array instead. This getter/setter is kept for backward compatibility.
+   */
+  get target() {
+    return this.targets.length > 0 ? this.targets[0] : null;
+  }
+  set target(entity) {
+    if (entity) {
+      if (this.targets.length === 0) {
+        this.targets.push(entity);
+      } else {
+        this.targets[0] = entity;
+      }
+    } else {
+      this.targets = [];
+    }
+  }
+  // Perspective controller delegation
+  perspectiveController = null;
+  // Orbit controls
+  orbitController = null;
+  _useOrbitalControls = false;
+  /** Reference to the shared renderer manager (set during setup) */
+  _rendererManager = null;
+  constructor(perspective, screenResolution, frustumSize = 10, rendererType = "webgl") {
+    this._perspective = perspective;
+    this.screenResolution = screenResolution;
+    this.frustumSize = frustumSize;
+    this.rendererType = rendererType;
+    const aspectRatio = screenResolution.x / screenResolution.y;
+    this.camera = this.createCameraForPerspective(aspectRatio);
+    if (this.needsRig()) {
+      this.cameraRig = new Object3D2();
+      this.cameraRig.position.set(0, 3, 10);
+      this.cameraRig.add(this.camera);
+      this.camera.lookAt(new Vector33(0, 2, 0));
+    } else {
+      this.camera.position.set(0, 0, 10);
+      this.camera.lookAt(new Vector33(0, 0, 0));
+    }
+    this.initializePerspectiveController();
+  }
+  /**
+   * Setup the camera with a scene and renderer manager.
+   * The renderer manager provides shared rendering infrastructure.
+   */
+  async setup(scene, rendererManager) {
+    this.sceneRef = scene;
+    if (rendererManager) {
+      this._rendererManager = rendererManager;
+    }
+    if (this._rendererManager && !this._rendererManager.initialized) {
+      await this._rendererManager.initRenderer();
+    }
+    if (this.perspectiveController && this._rendererManager) {
+      this.perspectiveController.setup({
+        screenResolution: this.screenResolution,
+        renderer: this._rendererManager.renderer,
+        scene,
+        camera: this
+      });
+    }
+    if (this._rendererManager) {
+      this.orbitController = new CameraOrbitController(
+        this.camera,
+        this._rendererManager.renderer.domElement,
+        this.cameraRig
+      );
+      this.orbitController.setScene(scene);
+      if (this._useOrbitalControls) {
+        this.orbitController.enableUserOrbitControls();
+      }
+    }
+  }
+  /**
+   * Legacy setup method for backward compatibility.
+   * Creates a temporary RendererManager internally.
+   * @deprecated Use setup(scene, rendererManager) instead.
+   */
+  async setupLegacy(scene) {
+    if (!this._rendererManager) {
+      this._rendererManager = new RendererManager(this.screenResolution, this.rendererType);
+      await this._rendererManager.initRenderer();
+      this._rendererManager.setupRenderPass(scene, this.camera);
+      this._rendererManager.startRenderLoop((delta) => {
+        this.update(delta);
+        if (this._rendererManager && this.sceneRef) {
+          this._rendererManager.render(this.sceneRef, this.camera);
+        }
+      });
+    }
+    await this.setup(scene, this._rendererManager);
+  }
+  /**
+   * Update camera controllers (called each frame).
+   * Does NOT render -- rendering is handled by RendererManager.
+   */
+  update(delta) {
+    this.orbitController?.update();
+    if (this.perspectiveController && !this.isDebugModeActive() && !this._useOrbitalControls) {
+      this.perspectiveController.update(delta);
+    }
+  }
+  /**
+   * Check if debug mode is active (orbit controls taking over camera)
+   */
+  isDebugModeActive() {
+    return this.orbitController?.isActive ?? false;
+  }
+  /**
+   * Enable user-configured orbital controls (not debug mode).
+   */
+  enableOrbitalControls() {
+    this._useOrbitalControls = true;
+    this.orbitController?.enableUserOrbitControls();
+  }
+  /**
+   * Disable user-configured orbital controls.
+   */
+  disableOrbitalControls() {
+    this._useOrbitalControls = false;
+    this.orbitController?.disableUserOrbitControls();
+  }
+  /**
+   * Whether user orbital controls are enabled.
+   */
+  get useOrbitalControls() {
+    return this._useOrbitalControls;
+  }
+  /**
+   * Add a target entity for the camera to follow/frame.
+   */
+  addTarget(entity) {
+    if (!this.targets.includes(entity)) {
+      this.targets.push(entity);
+    }
+  }
+  /**
+   * Remove a target entity.
+   */
+  removeTarget(entity) {
+    const index = this.targets.indexOf(entity);
+    if (index !== -1) {
+      this.targets.splice(index, 1);
+    }
+  }
+  /**
+   * Clear all targets.
+   */
+  clearTargets() {
+    this.targets = [];
+  }
+  /**
+   * Dispose camera resources (not the renderer -- that's managed by RendererManager).
+   */
+  destroy() {
+    try {
+      this.orbitController?.dispose();
+    } catch {
+    }
     this.sceneRef = null;
+    this.targets = [];
+    this._rendererManager = null;
   }
   /**
    * Attach a delegate to react to debug state changes.
@@ -569,13 +945,11 @@ var ZylemCamera = class {
     this.orbitController?.setDebugDelegate(delegate);
   }
   /**
-   * Resize camera and renderer
+   * Resize camera projection.
    */
   resize(width, height) {
     this.screenResolution.set(width, height);
-    this.renderer.setSize(width, height, false);
-    this.composer.setSize(width, height);
-    if (this.camera instanceof PerspectiveCamera) {
+    if (this.camera instanceof PerspectiveCamera2) {
       this.camera.aspect = width / height;
       this.camera.updateProjectionMatrix();
     }
@@ -584,11 +958,10 @@ var ZylemCamera = class {
     }
   }
   /**
-   * Update renderer pixel ratio (DPR)
+   * Set the viewport for this camera (normalized 0-1 coordinates).
    */
-  setPixelRatio(dpr) {
-    const safe = Math.max(1, Number.isFinite(dpr) ? dpr : 1);
-    this.renderer.setPixelRatio(safe);
+  setViewport(x, y, width, height) {
+    this.viewport = { x, y, width, height };
   }
   /**
    * Create camera based on perspective type
@@ -625,10 +998,10 @@ var ZylemCamera = class {
     }
   }
   createThirdPersonCamera(aspectRatio) {
-    return new PerspectiveCamera(75, aspectRatio, 0.1, 1e3);
+    return new PerspectiveCamera2(75, aspectRatio, 0.1, 1e3);
   }
   createFirstPersonCamera(aspectRatio) {
-    return new PerspectiveCamera(75, aspectRatio, 0.1, 1e3);
+    return new PerspectiveCamera2(75, aspectRatio, 0.1, 1e3);
   }
   createIsometricCamera(aspectRatio) {
     return new OrthographicCamera(
@@ -685,10 +1058,45 @@ var ZylemCamera = class {
     return this._perspective === Perspectives.ThirdPerson;
   }
   /**
-   * Get the DOM element for the renderer
+   * Get the DOM element for the renderer.
+   * @deprecated Access via RendererManager instead.
    */
   getDomElement() {
-    return this.renderer.domElement;
+    if (this._rendererManager) {
+      return this._rendererManager.getDomElement();
+    }
+    throw new Error("ZylemCamera: No renderer manager available. Call setup() first.");
+  }
+  /**
+   * Get the renderer manager reference.
+   */
+  getRendererManager() {
+    return this._rendererManager;
+  }
+  /**
+   * Set the renderer manager reference (used by CameraManager during setup).
+   */
+  setRendererManager(manager) {
+    this._rendererManager = manager;
+  }
+  // ─── Legacy compatibility methods ────────────────────────────────────────
+  /**
+   * @deprecated Renderer is now owned by RendererManager
+   */
+  get renderer() {
+    return this._rendererManager?.renderer;
+  }
+  /**
+   * @deprecated Composer is now owned by RendererManager
+   */
+  get composer() {
+    return this._rendererManager?.composer;
+  }
+  /**
+   * @deprecated Use RendererManager.setPixelRatio() instead
+   */
+  setPixelRatio(dpr) {
+    this._rendererManager?.setPixelRatio(dpr);
   }
 };
 
@@ -698,20 +1106,301 @@ var CameraWrapper = class {
   constructor(camera) {
     this.cameraRef = camera;
   }
+  // ─── Target management ──────────────────────────────────────────────────
+  /**
+   * Add a target entity for the camera to follow/frame.
+   * With multiple targets, the camera auto-frames to include all of them.
+   */
+  addTarget(entity) {
+    this.cameraRef.addTarget(entity);
+  }
+  /**
+   * Remove a target entity from the camera.
+   */
+  removeTarget(entity) {
+    this.cameraRef.removeTarget(entity);
+  }
+  /**
+   * Clear all targets. Camera will look at world origin.
+   */
+  clearTargets() {
+    this.cameraRef.clearTargets();
+  }
+  // ─── Orbital controls ───────────────────────────────────────────────────
+  /**
+   * Enable orbital controls for this camera.
+   * Allows the user to orbit, pan, and zoom the camera.
+   */
+  enableOrbitalControls() {
+    this.cameraRef.enableOrbitalControls();
+  }
+  /**
+   * Disable orbital controls for this camera.
+   */
+  disableOrbitalControls() {
+    this.cameraRef.disableOrbitalControls();
+  }
+  // ─── Viewport ───────────────────────────────────────────────────────────
+  /**
+   * 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, y, width, height) {
+    this.cameraRef.setViewport(x, y, width, height);
+  }
 };
 function createCamera(options) {
-  const screenResolution = options.screenResolution || new Vector23(window.innerWidth, window.innerHeight);
+  const screenResolution = options.screenResolution || new Vector24(window.innerWidth, window.innerHeight);
   let frustumSize = 10;
   if (options.perspective === "fixed-2d") {
     frustumSize = options.zoom || 10;
   }
-  const zylemCamera = new ZylemCamera(options.perspective || "third-person", screenResolution, frustumSize);
-  zylemCamera.move(options.position || new Vector34(0, 0, 0));
-  zylemCamera.camera.lookAt(options.target || new Vector34(0, 0, 0));
+  const zylemCamera = new ZylemCamera(
+    options.perspective || "third-person",
+    screenResolution,
+    frustumSize,
+    options.rendererType || "webgl"
+  );
+  if (options.name) {
+    zylemCamera.name = options.name;
+  }
+  const position = options.position ? options.position instanceof Vector34 ? options.position : new Vector34(options.position.x, options.position.y, options.position.z) : new Vector34(0, 0, 0);
+  const target = options.target ? options.target instanceof Vector34 ? options.target : new Vector34(options.target.x, options.target.y, options.target.z) : new Vector34(0, 0, 0);
+  zylemCamera.move(position);
+  zylemCamera.camera.lookAt(target);
+  if (options.viewport) {
+    zylemCamera.viewport = { ...options.viewport };
+  }
+  if (options.useOrbitalControls) {
+    zylemCamera._useOrbitalControls = true;
+  }
   return new CameraWrapper(zylemCamera);
 }
+
+// src/lib/camera/camera-manager.ts
+import { Vector2 as Vector25 } from "three";
+var CameraManager = class {
+  /** Named camera registry */
+  cameras = /* @__PURE__ */ new Map();
+  /** Currently active cameras, ordered by render layer (first = bottom) */
+  _activeCameras = [];
+  /** Auto-created debug camera with orbit controls */
+  _debugCamera = null;
+  /** Reference to the shared renderer manager */
+  _rendererManager = null;
+  /** Scene reference */
+  _sceneRef = null;
+  /** Counter for auto-generated camera names */
+  _autoNameCounter = 0;
+  constructor() {
+  }
+  /**
+   * Get the list of currently active cameras.
+   */
+  get activeCameras() {
+    return this._activeCameras;
+  }
+  /**
+   * Get the primary active camera (first in the active list).
+   */
+  get primaryCamera() {
+    return this._activeCameras.length > 0 ? this._activeCameras[0] : null;
+  }
+  /**
+   * Get the debug camera.
+   */
+  get debugCamera() {
+    return this._debugCamera;
+  }
+  /**
+   * Get all registered cameras.
+   */
+  get allCameras() {
+    return Array.from(this.cameras.values());
+  }
+  /**
+   * 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, name) {
+    const resolvedName = name || camera.name || `camera_${this._autoNameCounter++}`;
+    camera.name = resolvedName;
+    this.cameras.set(resolvedName, camera);
+    if (this._activeCameras.length === 0) {
+      this._activeCameras.push(camera);
+    }
+    return resolvedName;
+  }
+  /**
+   * Remove a camera by name or reference.
+   * Cannot remove the debug camera via this method.
+   */
+  removeCamera(nameOrRef) {
+    let name;
+    if (typeof nameOrRef === "string") {
+      name = nameOrRef;
+    } else {
+      for (const [key, cam] of this.cameras.entries()) {
+        if (cam === nameOrRef) {
+          name = key;
+          break;
+        }
+      }
+    }
+    if (!name) return false;
+    const camera = this.cameras.get(name);
+    if (!camera) return false;
+    if (camera === this._debugCamera) {
+      console.warn("CameraManager: Cannot remove the debug camera");
+      return false;
+    }
+    this.cameras.delete(name);
+    const activeIndex = this._activeCameras.indexOf(camera);
+    if (activeIndex !== -1) {
+      this._activeCameras.splice(activeIndex, 1);
+    }
+    return true;
+  }
+  /**
+   * 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) {
+    const camera = this.resolveCamera(nameOrRef);
+    if (!camera) {
+      console.warn(`CameraManager: Camera not found: ${nameOrRef}`);
+      return false;
+    }
+    const pipCameras = this._activeCameras.filter((c) => {
+      return c !== this._activeCameras[0] && c.viewport.width < 1;
+    });
+    this._activeCameras = [camera, ...pipCameras];
+    return true;
+  }
+  /**
+   * Add a camera as an additional active camera (for split-screen or PiP).
+   */
+  addActiveCamera(nameOrRef) {
+    const camera = this.resolveCamera(nameOrRef);
+    if (!camera) return false;
+    if (!this._activeCameras.includes(camera)) {
+      this._activeCameras.push(camera);
+    }
+    return true;
+  }
+  /**
+   * Remove a camera from the active render list (does not remove from registry).
+   */
+  deactivateCamera(nameOrRef) {
+    const camera = this.resolveCamera(nameOrRef);
+    if (!camera) return false;
+    const index = this._activeCameras.indexOf(camera);
+    if (index !== -1) {
+      this._activeCameras.splice(index, 1);
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Get a camera by name.
+   */
+  getCamera(name) {
+    return this.cameras.get(name) ?? null;
+  }
+  /**
+   * Setup all cameras with the given scene and renderer manager.
+   * Also creates the debug camera.
+   */
+  async setup(scene, rendererManager) {
+    this._sceneRef = scene;
+    this._rendererManager = rendererManager;
+    this.createDebugCamera(rendererManager.screenResolution);
+    for (const camera of this.cameras.values()) {
+      camera.setRendererManager(rendererManager);
+      await camera.setup(scene, rendererManager);
+    }
+    if (this._debugCamera) {
+      this._debugCamera.setRendererManager(rendererManager);
+      await this._debugCamera.setup(scene, rendererManager);
+    }
+  }
+  /**
+   * Update all active cameras' controllers.
+   */
+  update(delta) {
+    for (const camera of this._activeCameras) {
+      camera.update(delta);
+    }
+  }
+  /**
+   * Render all active cameras through the renderer manager.
+   */
+  render(scene) {
+    if (!this._rendererManager || this._activeCameras.length === 0) return;
+    this._rendererManager.renderCameras(scene, this._activeCameras);
+  }
+  /**
+   * Create a default third-person camera if no cameras have been added.
+   */
+  ensureDefaultCamera() {
+    if (this.cameras.size === 0 || this._activeCameras.length === 0) {
+      const screenRes = this._rendererManager?.screenResolution || new Vector25(window.innerWidth, window.innerHeight);
+      const defaultCam = new ZylemCamera(Perspectives.ThirdPerson, screenRes);
+      this.addCamera(defaultCam, "default");
+      return defaultCam;
+    }
+    return this._activeCameras[0];
+  }
+  /**
+   * Dispose all cameras and cleanup.
+   */
+  dispose() {
+    for (const camera of this.cameras.values()) {
+      camera.destroy();
+    }
+    this._debugCamera?.destroy();
+    this.cameras.clear();
+    this._activeCameras = [];
+    this._debugCamera = null;
+    this._rendererManager = null;
+    this._sceneRef = null;
+  }
+  /**
+   * Create the always-available debug camera with orbit controls.
+   */
+  createDebugCamera(screenResolution) {
+    this._debugCamera = new ZylemCamera(Perspectives.ThirdPerson, screenResolution);
+    this._debugCamera.name = "__debug__";
+    this._debugCamera.enableOrbitalControls();
+  }
+  /**
+   * Resolve a camera from a name or reference.
+   */
+  resolveCamera(nameOrRef) {
+    if (typeof nameOrRef === "string") {
+      return this.cameras.get(nameOrRef) ?? null;
+    }
+    for (const cam of this.cameras.values()) {
+      if (cam === nameOrRef) return cam;
+    }
+    return null;
+  }
+};
 export {
+  CameraManager,
+  CameraWrapper,
   Perspectives,
-  createCamera
+  createCamera,
+  isWebGPUSupported
 };
 //# sourceMappingURL=camera.js.map