melonjs 19.6.0 → 19.7.1

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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"}

package/build/camera/frustum.d.ts

@@ -0,0 +1,162 @@
+import { Matrix3d } from "../math/matrix3d.ts";
+/**
+ * A plane in 3D space, expressed as `Ax + By + Cz + D = 0`.
+ * `normal` is `(A, B, C)`; `constant` is `D`. Used by {@link Frustum}
+ * to represent the six bounding planes for culling.
+ * @category Camera
+ */
+export interface Plane {
+    /** plane normal (A, B, C in the plane equation) — not necessarily unit-length */
+    nx: number;
+    ny: number;
+    nz: number;
+    /** plane constant (D in the plane equation) */
+    d: number;
+}
+export interface FrustumOptions {
+    /** vertical field of view in radians (default: π / 3 = 60°) */
+    fov?: number;
+    /** aspect ratio (width / height) — default 1.0 (square) */
+    aspect?: number;
+    /** distance to the near clipping plane (default 0.1) */
+    near?: number;
+    /** distance to the far clipping plane (default 1000) */
+    far?: number;
+}
+/**
+ * A view frustum — the truncated pyramid that defines a perspective
+ * camera's visible volume. Holds the four projection parameters
+ * (`fov`, `aspect`, `near`, `far`) and the matching projection matrix.
+ *
+ * Used by {@link Camera3d} as its source of truth for perspective
+ * projection. The matrix follows melonJS conventions: Y-down (sprite
+ * at higher `y` appears lower on screen, matching Camera2d) and +Z
+ * forward (sprite at higher `pos.z` is farther from the camera and
+ * renders smaller). This differs from the OpenGL default of Y-up and
+ * -Z forward, but matches the rest of the engine and lets Camera2d
+ * code translate directly to Camera3d.
+ *
+ * Plane-based frustum culling is available via {@link Frustum#planes}
+ * (rebuilt by {@link Frustum#setFromViewProjection} per frame) plus
+ * {@link Frustum#containsPoint} / {@link Frustum#intersectsSphere} for
+ * culling tests. `Camera3d.update` calls `setFromViewProjection` once
+ * per frame so its `isVisible(obj)` queries against current planes —
+ * no per-frame setup needed from user code.
+ * @category Camera
+ * @example
+ * const frustum = new Frustum({ fov: Math.PI / 3, aspect: 16 / 9 });
+ * frustum.near = 0.5;
+ * frustum.update();
+ * renderer.setProjection(frustum.projectionMatrix);
+ */
+export default class Frustum {
+    /**
+     * vertical field of view in radians.
+     * Mutating this field requires calling {@link Frustum#update} to
+     * rebuild the projection matrix — or use {@link Frustum#set} to
+     * change multiple parameters and update in one call.
+     */
+    fov: number;
+    /**
+     * aspect ratio (width / height). Camera3d sets this automatically
+     * from its viewport on resize.
+     */
+    aspect: number;
+    /**
+     * distance to the near clipping plane (positive — measured along
+     * +Z, the camera's forward direction).
+     */
+    near: number;
+    /**
+     * distance to the far clipping plane.
+     */
+    far: number;
+    /**
+     * the perspective projection matrix derived from `fov`, `aspect`,
+     * `near` and `far`. Rebuilt by {@link Frustum#update}.
+     */
+    projectionMatrix: Matrix3d;
+    /**
+     * The six bounding planes of this frustum in world space, in order:
+     * left, right, bottom, top, near, far. Each plane is oriented so
+     * its `(nx, ny, nz)` normal points **inward** — a point with
+     * positive signed distance to a plane is on the visible side.
+     *
+     * Populated by {@link Frustum#setFromViewProjection}. Callers that
+     * use {@link Frustum#intersectsSphere} or {@link Frustum#containsPoint}
+     * must first call `setFromViewProjection` each frame the camera
+     * moves; otherwise the planes describe a stale frustum.
+     */
+    planes: Plane[];
+    /**
+     * @param [opts] - initial parameters; any omitted field uses the
+     *   class default
+     */
+    constructor(opts?: FrustumOptions);
+    /**
+     * Atomically set all four parameters and rebuild the projection
+     * matrix in one call.
+     * @param fov - vertical field of view in radians
+     * @param aspect - aspect ratio (width / height)
+     * @param near - distance to the near clipping plane
+     * @param far - distance to the far clipping plane
+     * @returns this Frustum for chaining
+     */
+    set(fov: number, aspect: number, near: number, far: number): this;
+    /**
+     * Rebuild {@link Frustum#projectionMatrix} from the current
+     * parameter values. Call this after mutating any of `fov`,
+     * `aspect`, `near`, `far` individually.
+     *
+     * The matrix is the standard OpenGL perspective post-multiplied by
+     * `scale(1, -1, -1)` so that:
+     * - Y-down matches melonJS screen + Camera2d conventions
+     * - +Z is forward (positive `pos.z` = farther from camera)
+     */
+    update(): void;
+    /**
+     * Rebuild the six bounding {@link Frustum#planes} from the world →
+     * clip matrix. Standard Gribb–Hartmann extraction: each plane is
+     * one of the six combinations of the matrix's row 3 (the "w" row)
+     * ± rows 0, 1, 2.
+     *
+     * Call this once per frame after the camera has moved (typically
+     * from `Camera3d.update`); the planes are then valid in world
+     * space for that frame and can be tested against world-space
+     * bounds via {@link Frustum#intersectsSphere} /
+     * {@link Frustum#containsPoint}.
+     *
+     * **Pass `projectionMatrix × viewMatrix`** — column-major /
+     * gl-matrix convention: a world-space point becomes a clip-space
+     * point via `clip = projection × view × world`, so the combined
+     * matrix is `projection × view`. The parameter name says
+     * `viewProjection` for that reason — it's the matrix uploaded to
+     * `uProjectionMatrix` in the vertex shader (after Camera3d bakes
+     * the per-frame world translate into the view via
+     * `container.translate`).
+     * @param viewProjection - the `projectionMatrix × viewMatrix` matrix
+     */
+    setFromViewProjection(viewProjection: Matrix3d): void;
+    /**
+     * Test whether a world-space sphere overlaps this frustum.
+     * Conservative — a sphere that touches even one plane's positive
+     * side is reported visible. Always run {@link Frustum#setFromViewProjection}
+     * first so the planes describe the current camera view.
+     * @param x - sphere center x in world coords
+     * @param y - sphere center y in world coords
+     * @param z - sphere center z in world coords
+     * @param radius - sphere radius in world units
+     * @returns true if the sphere is at least partially inside the frustum
+     */
+    intersectsSphere(x: number, y: number, z: number, radius: number): boolean;
+    /**
+     * Test whether a world-space point is inside this frustum.
+     * Always run {@link Frustum#setFromViewProjection} first.
+     * @param x - world x
+     * @param y - world y
+     * @param z - world z
+     * @returns true if the point is inside (on the positive side of every plane)
+     */
+    containsPoint(x: number, y: number, z: number): boolean;
+}
+//# sourceMappingURL=frustum.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"frustum.d.ts","sourceRoot":"","sources":["../../src/camera/frustum.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,WAAW,KAAK;IACrB,iFAAiF;IACjF,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,+CAA+C;IAC/C,CAAC,EAAE,MAAM,CAAC;CACV;AAED,MAAM,WAAW,cAAc;IAC9B,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,OAAO,OAAO,OAAO;IAC3B;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;;OAGG;IACH,gBAAgB,EAAE,QAAQ,CAAC;IAE3B;;;;;;;;;;OAUG;IACH,MAAM,EAAE,KAAK,EAAE,CAAC;IAEhB;;;OAGG;gBACS,IAAI,CAAC,EAAE,cAAc;IAoBjC;;;;;;;;OAQG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IASjE;;;;;;;;;OASG;IACH,MAAM,IAAI,IAAI;IAWd;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,qBAAqB,CAAC,cAAc,EAAE,QAAQ,GAAG,IAAI;IAqDrD;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAc1E;;;;;;;OAOG;IACH,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO;CASvD"}

package/build/const.d.ts

@@ -1,13 +1,40 @@
 /**
- * constant to select the HTML5 Canvas renderer
+ * Select the HTML5 Canvas renderer. Lower performance and no shader /
+ * mesh / Camera3d support, but supported on every browser including
+ * environments where WebGL is unavailable (some embedded webviews,
+ * stripped-down kiosk browsers, GPU blocklisted by driver policy).
+ *
+ * Use when the example / game uses only 2D sprites + primitives and you
+ * want the broadest possible reach. Anything depending on `ShaderEffect`,
+ * `Mesh`, `Camera3d`, GPU TMX tile rendering or `Light2d` will silently
+ * not work — those subsystems are WebGL-only.
  */
 export declare const CANVAS = 0;
 /**
- * constant to select select the WebGL renderer
+ * Require the WebGL renderer. **Throws at `new Application(...)` time
+ * if WebGL is unavailable** (driver-blocklisted GPU, software fallback
+ * failing the `failIfMajorPerformanceCaveat` check, no `WebGLRenderingContext`
+ * in the environment, etc.) — does NOT silently fall back to Canvas.
+ *
+ * Use this when your scene needs WebGL (Camera3d, Mesh, ShaderEffect,
+ * Light2d, GPU tilemap) and you'd rather fail fast with a clear error
+ * than have the engine render a stuck blank canvas.
+ *
+ * If Canvas fallback is acceptable when WebGL isn't there, use
+ * {@link AUTO} instead.
  */
 export declare const WEBGL = 1;
 /**
- * constant to auto-select the renderer (Attempt WebGL first, with fallback to Canvas)
+ * Auto-select the renderer: prefer WebGL when available, silently fall
+ * back to Canvas otherwise. Application construction always succeeds.
+ *
+ * Use this when your scene works under both renderers (2D sprites,
+ * primitives, basic tile maps) and you want the engine to pick the
+ * best available backend. Note: subsystems that require WebGL
+ * (Camera3d, Mesh, ShaderEffect, Light2d, GPU tilemap) will silently
+ * stop working under the Canvas fallback path — if your scene depends
+ * on any of those, use {@link WEBGL} so the failure surfaces at
+ * construction time instead of as a black canvas at runtime.
  */
 export declare const AUTO = 2;
 export type RendererType = typeof CANVAS | typeof WEBGL | typeof AUTO;

package/build/const.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"const.d.ts","sourceRoot":"","sources":["../src/const.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,MAAM,IAAI,CAAC;AAExB;;GAEG;AACH,eAAO,MAAM,KAAK,IAAI,CAAC;AAEvB;;GAEG;AACH,eAAO,MAAM,IAAI,IAAI,CAAC;AAEtB,MAAM,MAAM,YAAY,GAAG,OAAO,MAAM,GAAG,OAAO,KAAK,GAAG,OAAO,IAAI,CAAC"}
+{"version":3,"file":"const.d.ts","sourceRoot":"","sources":["../src/const.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,MAAM,IAAI,CAAC;AAExB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,KAAK,IAAI,CAAC;AAEvB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,IAAI,IAAI,CAAC;AAEtB,MAAM,MAAM,YAAY,GAAG,OAAO,MAAM,GAAG,OAAO,KAAK,GAAG,OAAO,IAAI,CAAC"}

package/build/geometries/sphere.d.ts

@@ -0,0 +1,105 @@
+import { Vector3d } from "../math/vector3d.ts";
+import { AABB3d } from "../physics/broadphase/aabb3d.ts";
+/**
+ * A 3D sphere — `{ centre, radius }`. Sibling of {@link Ellipse} in
+ * the geometry surface; used by {@link Octree} / `adapter.querySphere`
+ * as the canonical 3D region-query shape, and by user code for any
+ * sphere-vs-sphere / sphere-vs-AABB collision check under
+ * {@link Camera3d}.
+ *
+ * Not currently part of the {@link BodyShape} union — `Body` is 2D-
+ * only in melonJS today; Sphere is a math/geometry primitive that
+ * would slot in once a 3D physics adapter ships.
+ * @category Geometry
+ * @example
+ * import { Sphere } from "melonjs";
+ *
+ * const a = new Sphere(0, 0, 0, 10);
+ * const b = new Sphere(15, 0, 0, 10);
+ * a.overlaps(b); // true — surfaces touch at x = 5
+ */
+export declare class Sphere {
+    /** Centre coordinates of the sphere (Y-down, +Z forward — Camera3d convention). */
+    pos: Vector3d;
+    /** Sphere radius. Negative values are treated like their absolute value in {@link Sphere.overlaps} / {@link Sphere.contains}. */
+    radius: number;
+    /**
+     * Cached AABB for this sphere. Allocated lazily on the first
+     * {@link Sphere.getBounds} call so a sphere used only for inline
+     * `overlaps` checks doesn't pay for the AABB.
+     * @ignore
+     */
+    _bounds?: AABB3d;
+    /**
+     * @param x - centre x
+     * @param y - centre y
+     * @param z - centre z
+     * @param radius - sphere radius
+     */
+    constructor(x: number, y: number, z: number, radius: number);
+    /**
+     * Re-position and resize the sphere in one shot. Mirrors
+     * {@link Ellipse.setShape}.
+     * @param x - centre x
+     * @param y - centre y
+     * @param z - centre z
+     * @param radius - sphere radius
+     * @returns this sphere for chaining
+     */
+    setShape(x: number, y: number, z: number, radius: number): this;
+    /**
+     * Test whether a point lies inside the sphere (boundary inclusive).
+     * Squared-distance test — no `sqrt` on the hot path. Matches the
+     * boundary convention of {@link AABB3d.contains}.
+     * @param x - point x
+     * @param y - point y
+     * @param z - point z
+     */
+    contains(x: number, y: number, z: number): boolean;
+    /**
+     * Vector form of {@link Sphere.contains}.
+     * @param v - point
+     */
+    contains(v: Vector3d): boolean;
+    /**
+     * Test whether this sphere overlaps another. Boundary inclusive
+     * (touching surfaces count as overlap), matching
+     * {@link AABB3d.overlaps}.
+     * @param other - the other sphere
+     */
+    overlaps(other: Sphere): boolean;
+    /**
+     * Test whether this sphere overlaps an axis-aligned box. Delegates
+     * to {@link AABB3d.overlapsSphere} so the two shapes agree on
+     * boundary semantics.
+     * @param aabb - the box
+     */
+    overlapsAABB(aabb: AABB3d): boolean;
+    /**
+     * Smallest {@link AABB3d} containing this sphere. Cached — repeat
+     * calls without a `setShape` between return the same instance and
+     * the same values.
+     */
+    getBounds(): AABB3d;
+    /** @ignore */
+    _updateBounds(): void;
+    /**
+     * Reset the sphere to a zero-radius point at the origin.
+     */
+    clear(): this;
+    /**
+     * Deep copy of this sphere. The clone shares NOTHING with the
+     * original — independent `pos` Vector3d, independent AABB cache.
+     * Pulls from {@link spherePool} so back-to-back clones are
+     * allocation-free.
+     */
+    clone(): Sphere;
+}
+/**
+ * A pool of {@link Sphere} instances. Mirrors {@link ellipsePool} —
+ * `spherePool.get(x, y, z, r)` recycles an existing instance via
+ * `setShape` before allocating a new one; release via the
+ * matching `.release()` (the `createPool` contract).
+ */
+export declare const spherePool: import("../system/pool.ts").Pool<Sphere, [x: number, y: number, z: number, radius: number]>;
+//# sourceMappingURL=sphere.d.ts.map

package/build/geometries/sphere.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sphere.d.ts","sourceRoot":"","sources":["../../src/geometries/sphere.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAC;AAGzD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,MAAM;IAClB,mFAAmF;IACnF,GAAG,EAAE,QAAQ,CAAC;IAEd,iIAAiI;IACjI,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;OAKG;gBACS,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAK3D;;;;;;;;OAQG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAUxD;;;;;;;OAOG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO;IAClD;;;OAGG;IACH,QAAQ,CAAC,CAAC,EAAE,QAAQ,GAAG,OAAO;IAsB9B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAahC;;;;;OAKG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAInC;;;;OAIG;IACH,SAAS,IAAI,MAAM;IAQnB,cAAc;IACd,aAAa;IAYb;;OAEG;IACH,KAAK;IASL;;;;;OAKG;IACH,KAAK;CAGL;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,6FAWrB,CAAC"}