melonjs 19.6.0 → 19.7.0

package/README.md

@@ -54,7 +54,7 @@ Graphics
 - Built-in effects such as tinting, masking and 2D lighting (with optional per-pixel normal-map shading on sprites for 3D-looking dynamic lights)
 - Standard spritesheet, single and multiple Packed Textures support
 - Compressed texture support (DDS, KTX, KTX2, PVR, PKM) with automatic format detection and fallback
-- 3D mesh rendering with OBJ/MTL model loading, perspective projection and hardware depth testing
+- 3D mesh rendering with OBJ/MTL model loading, multi-material support, perspective projection and hardware depth testing
 - Built-in shader effects (Flash, Outline, Glow, Dissolve, CRT, Hologram, etc.) with multi-pass chaining via `postEffects`, plus custom shader support via `ShaderEffect` for per-sprite fragment effects (WebGL)
 - Trail renderable for fading, tapering ribbons behind moving objects (speed lines, sword slashes, magic trails)
 - System & Bitmap Text with built-in typewriter effect
@@ -67,8 +67,8 @@ Sound
 
 Physics
 - Polygon (SAT) based collision algorithm for accurate detection and response
-- Fast broad-phase collision detection using spatial partitioning (QuadTree)
-- Raycast and AABB region queries with precise entry geometry
+- Fast broad-phase collision detection using spatial partitioning (QuadTree in 2D, Octree in 3D, swapped automatically)
+- Raycast, AABB and sphere region queries with precise entry geometry, including 3D raycasts (`raycast3d`)
 - Collision lifecycle hooks on every `Renderable`
 - Collision filtering for optimized automatic collision detection
 - Multiple shapes per body for complex hitboxes
@@ -82,7 +82,8 @@ Input
 
 Camera
 - Multi-camera support (split-screen, minimaps, multiple viewports)
-- Camera follow with configurable deadzone and damping
+- Optional perspective camera (`Camera3d`) with frustum culling for 2.5D / 3D-projected scenes — drop-in subclass of the default 2D camera
+- Camera follow with configurable deadzone and frame-rate-independent damping
 - Built-in shake, fade, flash, and mask-based transition effects
 - Per-camera post-processing pipeline with stackable shader effects and color grading (ColorMatrix)
 

package/build/application/application.d.ts

@@ -137,8 +137,8 @@ export default class Application {
      * Accepted values : "x", "y", "z", "depth"
      * @see {@link World.sortOn}
      */
-    get sortOn(): string;
-    set sortOn(value: string);
+    get sortOn(): "x" | "y" | "z" | "depth";
+    set sortOn(value: "x" | "y" | "z" | "depth");
     /**
      * Fired when a level is fully loaded and all renderable instantiated. <br>
      * Additionally the level id will also be passed to the called function.
@@ -158,6 +158,38 @@ export default class Application {
      * @returns the parent HTML element
      */
     getParentElement(): HTMLElement;
+    /**
+     * Returns `true` if the browser/device is currently in fullscreen mode.
+     * Thin convenience around {@link device.isFullscreen} so the
+     * fullscreen trio (`isFullscreen` / `requestFullscreen` /
+     * `exitFullscreen`) lives together on the app instance.
+     * @category Application
+     */
+    isFullscreen(): boolean;
+    /**
+     * Trigger a fullscreen request for this application. Defaults to this
+     * application's `parentElement` (the container the canvas was appended
+     * into — see {@link Application#getParentElement}), so the canvas and
+     * any sibling HUD / overlay markup inside that container go fullscreen
+     * together.
+     * @param element - optional element to fullscreen instead of `this.parentElement`
+     * @example
+     * // bind F to toggle fullscreen
+     * me.input.bindKey(me.input.KEY.F, "toggleFullscreen");
+     * me.event.on(me.event.KEYDOWN, (action) => {
+     *   if (action === "toggleFullscreen") {
+     *     if (!app.isFullscreen()) app.requestFullscreen();
+     *     else app.exitFullscreen();
+     *   }
+     * });
+     * @category Application
+     */
+    requestFullscreen(element?: Element): void;
+    /**
+     * Exit fullscreen mode for this application.
+     * @category Application
+     */
+    exitFullscreen(): void;
     /**
      * The HTML canvas element associated with this application's renderer.
      * @example

package/build/application/application.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"application.d.ts","sourceRoot":"","sources":["../../src/application/application.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"application.d.ts","sourceRoot":"","sources":["../../src/application/application.ts"],"names":[],"mappings":"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"}

package/build/application/settings.d.ts

@@ -2,6 +2,7 @@
  * additional import for TypeScript
  * @import Renderer from "./../video/renderer.js";
  */
+import type Camera2d from "../camera/camera2d";
 import { RendererType } from "../const";
 import { PhysicsAdapter } from "../physics/adapter";
 import Renderer from "../video/renderer";
@@ -23,7 +24,22 @@ type PhysicsType = "builtin" | "none" | PhysicsAdapter | {
 type PowerPreference = "default" | "low-power";
 export type ApplicationSettings = {
     /**
-     * renderer to use (CANVAS, WEBGL, AUTO), or a custom renderer class
+     * Renderer to use. Three built-in modes (constants from `me.video`):
+     *
+     * - {@link CANVAS} — HTML5 Canvas backend. No shader / mesh /
+     *   Camera3d support.
+     * - {@link WEBGL} — **requires WebGL**. Throws at `new Application(...)`
+     *   time if WebGL is unavailable (driver-blocklisted GPU, perf-caveat
+     *   failure, etc.). Use this when your scene needs Camera3d, Mesh,
+     *   ShaderEffect, Light2d or GPU tilemap — you'd rather fail fast
+     *   than render a stuck blank canvas.
+     * - {@link AUTO} — try WebGL, silently fall back to Canvas if
+     *   unavailable. Application construction always succeeds. The
+     *   WebGL-only subsystems (Camera3d, Mesh, ShaderEffect, Light2d,
+     *   GPU tilemap) silently stop working under the Canvas fallback —
+     *   if your scene depends on any of those, use `WEBGL` instead.
+     *
+     * Or pass a custom `Renderer` subclass instance for full control.
      * @default AUTO
      */
     renderer: RendererType | Renderer;
@@ -153,6 +169,26 @@ export type ApplicationSettings = {
      * a custom batcher class (WebGL only)
      */
     batcher?: (new (renderer: any) => Batcher) | undefined;
+    /**
+     * Default camera class instantiated for any {@link Stage} that does not
+     * explicitly provide its own cameras. Set to {@link Camera3d} to opt
+     * every stage in the app into perspective rendering by default. Stages
+     * can still override per-instance via `super({ cameras: [...] })` or
+     * per-class via `super({ cameraClass: Camera2d })`. Built-in stages
+     * (e.g. the loader screen) explicitly use {@link Camera2d} regardless
+     * of this setting.
+     *
+     * **WebGL requirement.** Camera classes whose
+     * `static defaultSortOn === "depth"` (Camera3d and any subclass) need
+     * the WebGL renderer — perspective projection, depth attachment and
+     * mesh draw all live in the WebGL backend. Pairing such a
+     * `cameraClass` with `renderer: video.AUTO` on a system where AUTO
+     * falls back to Canvas emits a `console.warn` at construction time
+     * and produces a non-functional render. Use `renderer: video.WEBGL`
+     * to get a hard throw instead.
+     * @default Camera2d
+     */
+    cameraClass?: new (minX: number, minY: number, maxX: number, maxY: number) => Camera2d;
 } & ({
     /**
      * the DOM parent element (or its string ID) to hold the canvas in the HTML file

package/build/application/settings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../src/application/settings.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,QAAQ,MAAM,mBAAmB,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,KAAK,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE3E;;;;;;;;GAQG;AACH,KAAK,WAAW,GACb,SAAS,GACT,MAAM,GACN,cAAc,GACd;IAAE,OAAO,EAAE,cAAc,CAAA;CAAE,CAAC;AAE/B,KAAK,eAAe,GAAG,SAAS,GAAG,WAAW,CAAC;AAE/C,MAAM,MAAM,mBAAmB,GAAG;IACjC;;;OAGG;IACH,QAAQ,EAAE,YAAY,GAAG,QAAQ,CAAC;IAElC;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAEvB;;;OAGG;IACH,WAAW,EAAE,WAAW,CAAC;IAEzB;;OAEG;IACH,WAAW,EAAE,WAAW,CAAC;IAEzB;;;OAGG;IACH,YAAY,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,eAAe,EAAE,eAAe,CAAC;IAEjC;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,SAAS,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAC;IAEvB;;;OAGG;IACH,SAAS,EAAE,SAAS,CAAC;IAErB;;;;;;;;;;;;;;OAcG;IACH,MAAM,EAAE,WAAW,CAAC;IAEpB;;;;;;;;;;OAUG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,4BAA4B,EAAE,OAAO,CAAC;IAEtC;;;;;;;;;;;;;;OAcG;IACH,mBAAmB,EAAE,OAAO,CAAC;IAE7B;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;;;;OAKG;IACH,eAAe,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,QAAQ,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;IAE1D;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,QAAQ,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;CACvD,GAAG,CACD;IACA;;OAEG;IACH,MAAM,EAAE,MAAM,GAAG,WAAW,CAAC;IAC7B,MAAM,CAAC,EAAE,KAAK,CAAC;CACd,GACD;IACA,MAAM,CAAC,EAAE,KAAK,CAAC;IACf;;;OAGG;IACH,MAAM,EAAE,iBAAiB,CAAC;CACzB,CACH,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,GAAG,mBAAmB,GAAG;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACd,CAAC"}
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../src/application/settings.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,OAAO,KAAK,QAAQ,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,QAAQ,MAAM,mBAAmB,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,KAAK,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE3E;;;;;;;;GAQG;AACH,KAAK,WAAW,GACb,SAAS,GACT,MAAM,GACN,cAAc,GACd;IAAE,OAAO,EAAE,cAAc,CAAA;CAAE,CAAC;AAE/B,KAAK,eAAe,GAAG,SAAS,GAAG,WAAW,CAAC;AAE/C,MAAM,MAAM,mBAAmB,GAAG;IACjC;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,EAAE,YAAY,GAAG,QAAQ,CAAC;IAElC;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAEvB;;;OAGG;IACH,WAAW,EAAE,WAAW,CAAC;IAEzB;;OAEG;IACH,WAAW,EAAE,WAAW,CAAC;IAEzB;;;OAGG;IACH,YAAY,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,eAAe,EAAE,eAAe,CAAC;IAEjC;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,SAAS,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAC;IAEvB;;;OAGG;IACH,SAAS,EAAE,SAAS,CAAC;IAErB;;;;;;;;;;;;;;OAcG;IACH,MAAM,EAAE,WAAW,CAAC;IAEpB;;;;;;;;;;OAUG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,4BAA4B,EAAE,OAAO,CAAC;IAEtC;;;;;;;;;;;;;;OAcG;IACH,mBAAmB,EAAE,OAAO,CAAC;IAE7B;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;;;;OAKG;IACH,eAAe,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,QAAQ,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;IAE1D;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,QAAQ,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;IAEvD;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAAW,CAAC,EAAE,KACb,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,KACR,QAAQ,CAAC;CACd,GAAG,CACD;IACA;;OAEG;IACH,MAAM,EAAE,MAAM,GAAG,WAAW,CAAC;IAC7B,MAAM,CAAC,EAAE,KAAK,CAAC;CACd,GACD;IACA,MAAM,CAAC,EAAE,KAAK,CAAC;IACf;;;OAGG;IACH,MAAM,EAAE,iBAAiB,CAAC;CACzB,CACH,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,GAAG,mBAAmB,GAAG;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACd,CAAC"}

package/build/camera/camera2d.d.ts

@@ -38,6 +38,15 @@ interface AxisEnum {
  * this.cameras.set("minimap", minimap);
  */
 export default class Camera2d extends Renderable {
+    /**
+     * Preferred `Container.sortOn` mode for this camera type. Read by
+     * `Application` (and `Stage`) at bootstrap to initialize the world
+     * container's sort. Camera2d uses `"z"` (painter's-algorithm 2D
+     * layering, higher pos.z draws on top); `Camera3d` overrides to
+     * `"depth"` (camera-distance sort required by perspective).
+     * Subclasses can override to declare their own preferred mode.
+     */
+    static defaultSortOn: "x" | "y" | "z" | "depth";
     /**
      * Axis definition
      * NONE no axis
@@ -56,19 +65,37 @@ export default class Camera2d extends Renderable {
      */
     smoothFollow: boolean;
     /**
-     * Camera damping for smooth transition [0 .. 1].
-     * 1 being the maximum value and will snap the camera to the target position
+     * Camera damping for smooth follow `[0 .. 1]`. `1` snaps the camera
+     * to the target every frame (no smoothing); lower values produce a
+     * trailing follow — `0.1` is a soft springy follow, `0.5` is snappy.
+     *
+     * **Frame-rate independent (since 19.7 / #1478).** The value is the
+     * fraction of the gap covered per frame at the engine's target
+     * framerate ({@link timer.maxfps}, default 60). The underlying
+     * implementation switched from `pos.lerp` to `pos.damp` with
+     * `lambda = -ln(1 - damping) * timer.maxfps`, so the legacy
+     * per-frame fraction is recovered exactly at the target rate AND
+     * the wall-clock convergence stays constant when the actual frame
+     * rate drifts (slow machine, throttled tab, high-refresh display).
+     * Existing `damping` tuning carries over with no changes.
      * @default 1.0
      */
     damping: number;
     /**
-     * the closest point relative to the camera
-     * @default -1000
+     * the closest point relative to the camera. Widened from `-1000` in
+     * 19.7 to accommodate sprites at large `depth` values now that
+     * `aVertex.z` participates in clip-space (PR A): the default
+     * `Container.autoDepth = true` assigns `pos.z = childCount` so any
+     * container with >1000 children would otherwise clip-cull, and the
+     * common Y-sort pattern `sprite.depth = sprite.pos.y` exceeds 1000
+     * on tall maps. Override per-camera if you need tighter z clipping.
+     * @default -1e6
      */
     near: number;
     /**
-     * the furthest point relative to the camera.
-     * @default 1000
+     * the furthest point relative to the camera. Widened from `1000` in
+     * 19.7 — see {@link Camera2d#near}.
+     * @default 1e6
      */
     far: number;
     /**
@@ -253,7 +280,7 @@ export default class Camera2d extends Renderable {
      */
     moveTo(x: number, y: number): void;
     /** @ignore */
-    updateTarget(_dt?: number): void;
+    updateTarget(dt?: number): void;
     /** @ignore */
     update(dt?: number): boolean;
     /**
@@ -347,6 +374,16 @@ export default class Camera2d extends Renderable {
      * @returns a vector with the converted local coordinates
      */
     worldToLocal(x: number, y: number, v?: Vector2d): Vector2d;
+    /**
+     * Build and install the world + screen projections used when this
+     * camera is non-default (split-screen, picture-in-picture, etc.).
+     * Default behavior is a shifted ortho that places the camera's
+     * world view at the camera's screen-rect within the full renderer
+     * viewport. Subclasses (e.g. Camera3d) override this to install a
+     * perspective `worldProjection` instead.
+     * @ignore
+     */
+    _setupNonDefaultProjection(renderer: Renderer): void;
     /**
      * render the camera effects
      * @ignore
@@ -357,6 +394,21 @@ export default class Camera2d extends Renderable {
      * @ignore
      */
     draw(renderer: Renderer, container: Container): void;
+    /**
+     * Apply the world-to-camera-view transform to the container before
+     * its draw walk. Camera2d translates by `-camera.pos` (plus shake
+     * offset); Camera3d overrides this to additionally rotate by
+     * `-camera.pitch` / `-camera.yaw` in the correct order.
+     * @ignore
+     */
+    _applyContainerViewTransform(container: Container, translateX: number, translateY: number): void;
+    /**
+     * Revert the transform applied by {@link Camera2d#_applyContainerViewTransform}.
+     * Must undo each mutation in reverse order. Subclasses overriding
+     * `_applyContainerViewTransform` should override this too.
+     * @ignore
+     */
+    _revertContainerViewTransform(container: Container, translateX: number, translateY: number): void;
     /**
      * @ignore
      */

package/build/camera/camera2d.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"camera2d.d.ts","sourceRoot":"","sources":["../../src/camera/camera2d.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"camera2d.d.ts","sourceRoot":"","sources":["../../src/camera/camera2d.ts"],"names":[],"mappings":"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"}

package/build/camera/camera3d.d.ts

@@ -0,0 +1,335 @@
+import type { ObservableVector3d } from "../math/observableVector3d.ts";
+import { Vector3d } from "../math/vector3d.ts";
+import type Container from "./../renderable/container.js";
+import type Renderable from "./../renderable/renderable.js";
+import type Renderer from "./../video/renderer.js";
+import Camera2d from "./camera2d.ts";
+import Frustum, { type FrustumOptions } from "./frustum.ts";
+/**
+ * A perspective camera that extends {@link Camera2d} with a view
+ * {@link Frustum} (fov / aspect / near / far) and orientation
+ * (pitch / yaw / roll). Slots into `Stage.cameras` as a drop-in
+ * replacement for `Camera2d` — inherits the post-effect FBO bracket,
+ * color-matrix, fade / shake / follow plumbing, and screen viewport.
+ *
+ * **WebGL required.** Camera3d's perspective projection, depth-buffer
+ * painter sort and mesh draw path all live in the WebGL renderer; the
+ * Canvas backend has none of these and would render a stuck blank scene.
+ * Construct the Application with `renderer: video.WEBGL` to get a hard
+ * throw at construction time if WebGL is unavailable. Pairing
+ * `cameraClass: Camera3d` with `video.AUTO` will emit a `console.warn`
+ * at construction (and silently misrender) when AUTO falls back to
+ * Canvas — see {@link ApplicationSettings.renderer} for the contract.
+ *
+ * Conventions:
+ * - **Y-down + +Z forward.** Sprite at higher `pos.y` appears lower
+ *   on screen (same as Camera2d). Sprite at higher `pos.z` is
+ *   farther from the camera and renders smaller. Matches melonJS's
+ *   2D conventions so existing Camera2d code translates directly.
+ * - **Rotations are extrinsic XYZ.** `pitch` (X axis, look up/down),
+ *   `yaw` (Y axis, look left/right), `roll` (Z axis, screen-plane
+ *   bank — also exposed as `Camera2d.rotation` via Renderable
+ *   inheritance for backward compatibility).
+ * - **Follow offset (PR B scope).** When a target is set,
+ *   `followOffset` is applied in **world space**:
+ *   `camera.pos = target.pos + followOffset`. Target-rotation-aware
+ *   follow (Cinemachine / Unreal spring-arm style, where the offset
+ *   rotates with the target's orientation) is deferred until a
+ *   showcase needs it (e.g. AfterBurner's banking jet).
+ *
+ * Known limitations (PR B scope):
+ * - `Light2d` is 2D-only — visible artifacts under perspective.
+ *   Avoid combining with Camera3d for now.
+ * - `localToWorld` / `worldToLocal` overrides fall back to the
+ *   ortho-equivalent 2D projection at z=0. Full 3D unproject for
+ *   arbitrary depth is future work.
+ * @category Camera
+ * @example
+ * // opt in app-wide:
+ * const app = new Application(1024, 768, {
+ *   parent: "screen",
+ *   cameraClass: Camera3d,
+ * });
+ *
+ * // or per-stage with custom fov:
+ * class GameStage extends Stage {
+ *   constructor() {
+ *     super({
+ *       cameras: [new Camera3d(0, 0, 1024, 768, { fov: Math.PI / 3 })],
+ *     });
+ *   }
+ * }
+ */
+export default class Camera3d extends Camera2d {
+    /**
+     * Override `Camera2d.defaultSortOn` to declare `"depth"` as this
+     * camera's preferred sort mode. `Application` / `Stage` apply this
+     * to `world.sortOn` at bootstrap, so games opting into Camera3d via
+     * `cameraClass: Camera3d` get camera-distance painter's sort for
+     * free — the only correct sort for alpha-blended sprites under
+     * perspective.
+     */
+    static defaultSortOn: "x" | "y" | "z" | "depth";
+    /**
+     * the view frustum (perspective parameters + projection matrix).
+     * Mutating `frustum.fov` / `aspect` / `near` / `far` directly
+     * requires calling `frustum.update()` to rebuild the matrix;
+     * the proxy setters on this camera (`camera.fov = ...`) handle
+     * that automatically.
+     */
+    frustum: Frustum;
+    /**
+     * X-axis rotation in radians (look up/down). Positive values
+     * pitch the camera up.
+     * @default 0
+     */
+    pitch: number;
+    /**
+     * Y-axis rotation in radians (look left/right). Positive values
+     * yaw the camera to the right.
+     * @default 0
+     */
+    yaw: number;
+    /**
+     * World-space offset from the followed target. When `target` is
+     * set via {@link Camera2d#follow}, the camera position resolves to
+     * `target.pos + followOffset`. Common usage: `(0, -2, -8)` for a
+     * behind-and-above third-person view.
+     *
+     * Treated as world-space in this release — target-rotation-aware
+     * follow (where the offset rotates with the target's orientation,
+     * Cinemachine / Unreal spring-arm style) is deferred until a
+     * showcase needs it (e.g. AfterBurner's banking jet).
+     * @default (0, 0, 0)
+     */
+    followOffset: Vector3d;
+    /**
+     * Reserved for future follow-look-ahead support — currently unused
+     * by `updateTarget`. The intent is: when wired in, the camera will
+     * look at `target.pos + lookAhead` instead of `target.pos`, so a
+     * follow-cam stays slightly ahead of its target (e.g. for a
+     * cinematic forward-looking shot in AfterBurner). Field is exposed
+     * now so user code can set it without waiting for the wiring.
+     * @default (0, 0, 1)
+     */
+    lookAhead: Vector3d;
+    /**
+     * @param minX - start x offset
+     * @param minY - start y offset
+     * @param maxX - end x offset
+     * @param maxY - end y offset
+     * @param [opts] - perspective parameters (see {@link FrustumOptions})
+     */
+    constructor(minX: number, minY: number, maxX: number, maxY: number, opts?: FrustumOptions);
+    /**
+     * vertical field of view in radians. Setting this rebuilds the
+     * projection matrix. Proxies to `frustum.fov`.
+     */
+    get fov(): number;
+    set fov(value: number);
+    /**
+     * aspect ratio (width / height). Auto-updated on `resize()`.
+     * Setting manually overrides the auto-derived value until the
+     * next resize. Proxies to `frustum.aspect`.
+     */
+    get aspect(): number;
+    set aspect(value: number);
+    /**
+     * Update the perspective near/far clip distances and rebuild the
+     * projection matrix in one shot. Anything closer than `near` or
+     * farther than `far` is clipped by the GPU; projection math also
+     * degrades sharply just before `far`, so size the far plane to the
+     * deepest object in your scene with a little headroom. Defaults are
+     * `near = 0.1`, `far = 1000` — typical AfterBurner-class scenes
+     * with enemies spawning at z = 3000+ need to push `far` out.
+     *
+     * **This is the supported way to change near/far at runtime.** The
+     * inherited `Camera2d.near` / `.far` are plain instance fields —
+     * direct assignment (`camera.near = 5`) updates the cached value
+     * but leaves the projection matrix stale until the next
+     * `resize()`. TypeScript's property-vs-accessor rule prevents
+     * shadowing the inherited fields with accessor pairs, so the
+     * convenience method is the public contract instead.
+     * @param near - near clip distance
+     * @param far - far clip distance
+     * @returns this camera (chainable)
+     */
+    setClipPlanes(near: number, far: number): this;
+    /**
+     * Rebuild the projection matrix from the frustum. Called by the
+     * base `Camera2d` constructor and by `resize()`. Camera3d's
+     * version replaces the ortho matrix with the frustum's perspective.
+     * @ignore
+     */
+    _updateProjectionMatrix(): void;
+    /**
+     * Override Camera2d's non-default projection setup so that a Camera3d
+     * used in split-screen / picture-in-picture still renders the world
+     * with perspective instead of falling back to a 2D ortho. The
+     * camera's perspective `projectionMatrix` is mirrored into
+     * `worldProjection`; the surrounding `clipRect` set by the base
+     * `draw()` handles confining the draw region to the camera's
+     * sub-screen rect, and the frustum's `aspect` is already in sync
+     * with the camera's width/height. `screenProjection` is left alone
+     * because it was already set up correctly in
+     * {@link Camera3d#_updateProjectionMatrix}.
+     * @ignore
+     */
+    _setupNonDefaultProjection(renderer: Renderer): void;
+    /**
+     * Resize the camera viewport and recompute aspect ratio.
+     * @param w - new width
+     * @param h - new height
+     * @returns this camera
+     */
+    resize(w: number, h: number): this;
+    /**
+     * Apply the camera's full 3D view transform to the world container.
+     * Order: rotate first (pitch, yaw), then translate by `-camera.pos`.
+     * Post-multiplication semantics give us
+     * `currentTransform = R⁻¹ ∘ T(-pos)` — applied to a world point,
+     * this subtracts the camera position then rotates by the camera's
+     * inverse orientation, which is the standard view transform.
+     * @ignore
+     */
+    _applyContainerViewTransform(container: Container, translateX: number, translateY: number): void;
+    /**
+     * Revert {@link Camera3d#_applyContainerViewTransform} in reverse
+     * order to restore the container's `currentTransform` to its
+     * pre-camera state.
+     * @ignore
+     */
+    _revertContainerViewTransform(container: Container, translateX: number, translateY: number): void;
+    /**
+     * Point the camera at a world-space target by deriving pitch and
+     * yaw from the direction (target − camera.pos). Roll is unaffected.
+     *
+     * Three call shapes:
+     * - `lookAt(x, y, z)` — raw world coordinates
+     * - `lookAt(vector3d)` — a 3D point
+     * - `lookAt(renderable)` — uses `renderable.pos` (matches the
+     *   `Renderable.lookAt(target)` signature so Camera3d is a structural
+     *   drop-in replacement for Camera2d / Renderable in user code).
+     *
+     * Last-write-wins with manual `pitch` / `yaw` assignment: if you
+     * call `lookAt(...)` then set `camera.pitch = 0.1` directly, the
+     * next frame renders with the manual pitch.
+     * @param xOrTarget - target world x, or a target with `pos` / `x`,`y`,`z`
+     * @param y - target world y (only when first arg is a number)
+     * @param z - target world z (only when first arg is a number)
+     * @returns this camera
+     */
+    lookAt(xOrTarget: number | {
+        x: number;
+        y: number;
+        z?: number;
+        pos?: ObservableVector3d;
+    }, y?: number, z?: number): this;
+    /**
+     * Convenience overload of `lookAt` accepting a {@link Vector3d}.
+     * @param target - world-space point to look at
+     * @returns this camera
+     */
+    setLookAt(target: Vector3d): this;
+    /**
+     * Set the target-local follow offset. Called once when configuring
+     * a follow-cam (e.g. behind-and-above third person:
+     * `setFollowOffset(0, -2, -8)`).
+     * @param x - target-local x offset
+     * @param y - target-local y offset
+     * @param z - target-local z offset
+     * @returns this camera
+     */
+    setFollowOffset(x: number, y: number, z: number): this;
+    /**
+     * Override Camera2d's 2D follow logic to additionally resolve
+     * `followOffset` against the target's z. When `target` is set, the
+     * camera's world position becomes `target.pos + followOffset`.
+     *
+     * **Semantic change vs Camera2d.follow:** this override **does not
+     * honor `follow_axis`, `deadzone`, or `smoothFollow` / `damping`**.
+     * Camera3d tracks its target exactly each frame because the typical
+     * 3D use case (behind-the-plane follow-cam, third-person orbit) wants
+     * 1:1 tracking with no scroll-deadzone. If you need damped or
+     * axis-constrained follow under perspective, set `target = null` and
+     * lerp `camera.pos` toward the target manually in your `update()`.
+     *
+     * **PR B scope:** `followOffset` is treated as **world-space**.
+     * Target-rotation-aware follow (where the offset rotates with the
+     * target's orientation, Cinemachine / Unreal-style) lands when a
+     * showcase (AfterBurner's banking jet) demands it.
+     * @param dt - delta time in milliseconds (ignored — no damping)
+     * @ignore
+     */
+    updateTarget(dt?: number): void;
+    /**
+     * Visibility check used by `Container.update` (in turn driving
+     * `Container.draw`) to skip rendering off-screen children.
+     *
+     * Camera2d's implementation tests a 2D bounds-rectangle overlap
+     * against `this.worldView` — that test is invalid under perspective:
+     * the visible region is a frustum that widens with distance and
+     * rotates with the camera's pitch / yaw, not a fixed axis-aligned
+     * rect at the camera's x / y. Camera3d substitutes plane-based
+     * frustum culling — each non-floating renderable's bounding sphere
+     * is tested against the six frustum planes that were extracted in
+     * the most recent `update()` call. Floating elements (HUD / UI)
+     * still use Camera2d's 2D rect test because their bounds are
+     * screen-space and the perspective transform doesn't apply to them.
+     * @param obj - the renderable to test
+     * @param [floating] - test against screen coordinates instead of frustum
+     * @returns true if the renderable's bounds overlap the frustum
+     */
+    isVisible(obj: Renderable, floating?: boolean): boolean;
+    /**
+     * Bulk frustum cull via the world's {@link Octree}. Returns every
+     * renderable whose octant the current frustum overlaps —
+     * conservative (some renderables may still narrow-cull out
+     * via {@link Camera3d#isVisible}'s per-sphere test) but
+     * O(visible + walk) instead of O(scene).
+     *
+     * Only applicable under `cameraClass: Camera3d` (or any setup
+     * where `world.sortOn === "depth"` and the broadphase is an
+     * Octree). Returns an empty array under a 2D broadphase — call
+     * sites can guard on the array length or branch on
+     * `world.sortOn`.
+     *
+     * For a 1000-renderable scene with ~50 visible, expect a 5-20×
+     * speedup over walking every renderable and per-item
+     * {@link Camera3d#isVisible}.
+     * @param world - the world to cull (its broadphase must be an Octree); typed structurally to sidestep the Camera3d → World import cycle
+     * @param world.broadphase - the world's spatial broadphase
+     * @param world.sortOn - guard: returns empty unless this equals `"depth"`
+     * @param [out] - caller-supplied result array (re-entrancy-safe)
+     * @returns visible-renderable candidates
+     * @example
+     * const visible = camera.queryVisible(app.world);
+     * for (const r of visible) {
+     *   // narrow-phase per-renderable visibility (sphere / OBB) if needed
+     *   if (camera.isVisible(r)) r.draw(renderer);
+     * }
+     */
+    queryVisible(world: {
+        broadphase: unknown;
+        sortOn: string;
+    }, out?: Renderable[]): Renderable[];
+    /**
+     * Per-frame update — extends Camera2d's behavior (target follow,
+     * camera effects) with rebuilding the frustum's six bounding
+     * planes so {@link Camera3d#isVisible} returns accurate results
+     * for the current camera state.
+     * @param dt - delta time in milliseconds
+     * @returns true if the camera's state changed
+     * @ignore
+     */
+    update(dt?: number): boolean;
+    /**
+     * Recompute the frustum's six bounding planes from the current
+     * `projectionMatrix × viewMatrix` (the world → clip matrix).
+     * Called from {@link Camera3d#update} each frame; `isVisible`
+     * then tests against the cached planes.
+     * @ignore
+     */
+    _rebuildFrustumPlanes(): void;
+}
+//# sourceMappingURL=camera3d.d.ts.map

package/build/camera/camera3d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera3d.d.ts","sourceRoot":"","sources":["../../src/camera/camera3d.ts"],"names":[],"mappings":"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"}