melonjs 19.5.0 → 19.7.0

package/build/physics/broadphase/aabb3d.d.ts

@@ -0,0 +1,115 @@
+import { Vector3d } from "../../math/vector3d.ts";
+import type { XYZPoint } from "../../utils/types.ts";
+/**
+ * A 3D axis-aligned bounding box — the 3D sibling of {@link Bounds}.
+ *
+ * Used by {@link Octree} as the bounding primitive of every node
+ * (root, subnodes, queries). Intentionally minimal: only the
+ * operations the {@link Octree} hot path needs are implemented, with
+ * a small handful of helpers ({@link AABB3d#contains},
+ * {@link AABB3d#overlaps}, {@link AABB3d#overlapsSphere}) for
+ * test-driven `querySphere` / `queryAABB` callers.
+ *
+ * Coordinate convention matches the rest of melonJS 3D code (see
+ * {@link Camera3d}): **Y-down, +Z forward / away from the camera.**
+ *
+ * Lives next to {@link Octree} under `physics/broadphase/` rather
+ * than `math/` to mirror {@link Bounds} (which lives in `physics/`,
+ * not `math/`). Aabb is a primitive of the broadphase, not a generic
+ * math primitive — it never escapes a query result.
+ * @category Geometry
+ */
+export declare class AABB3d {
+    min: XYZPoint;
+    max: XYZPoint;
+    /**
+     * Construct an empty AABB (min = +∞, max = −∞). The empty AABB
+     * satisfies `addPoint(p)` => `min = max = p` for the first point
+     * added, and `overlaps(b)` => `false` against any other AABB —
+     * same convention as {@link Bounds}.
+     * @param [min] - optional initial minimum corner
+     * @param [max] - optional initial maximum corner
+     */
+    constructor(min?: XYZPoint, max?: XYZPoint);
+    /**
+     * Reset the AABB to its empty state.
+     */
+    clear(): void;
+    /**
+     * Set min and max corners directly. Mirror of `Bounds.setMinMax`.
+     * @param minX - minimum corner x
+     * @param minY - minimum corner y
+     * @param minZ - minimum corner z
+     * @param maxX - maximum corner x
+     * @param maxY - maximum corner y
+     * @param maxZ - maximum corner z
+     */
+    setMinMax(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): void;
+    get x(): number;
+    get y(): number;
+    get z(): number;
+    get width(): number;
+    get height(): number;
+    get depth(): number;
+    get left(): number;
+    get right(): number;
+    get top(): number;
+    get bottom(): number;
+    get front(): number;
+    get back(): number;
+    get centerX(): number;
+    get centerY(): number;
+    get centerZ(): number;
+    /**
+     * True if every coordinate is a finite number. Used by the
+     * {@link Octree} to reject inserts whose bounding box is the
+     * empty AABB (a sprite with no shape and never updated) — without
+     * this guard a `±Infinity` corner would silently classify into
+     * an arbitrary octant and never come back out via `remove`.
+     */
+    isFinite(): boolean;
+    /**
+     * True if this AABB fully encloses the given point.
+     * @param x - point x
+     * @param y - point y
+     * @param z - point z
+     */
+    contains(x: number, y: number, z: number): boolean;
+    /**
+     * True if this AABB overlaps the given AABB on every axis. The
+     * intersection includes the boundary (shared face/edge/corner
+     * counts as overlap), same convention as {@link Bounds.overlaps}
+     * so {@link Octree} candidate sets don't drop items that sit
+     * exactly on an octant boundary.
+     * @param aabb - the other AABB to test against
+     */
+    overlaps(aabb: AABB3d): boolean;
+    /**
+     * True if this AABB overlaps a sphere. Computes the squared
+     * distance from the sphere center to the nearest point on the
+     * AABB and compares against `r²` — avoids the `sqrt` on the hot
+     * path. Used by `Octree.querySphere`.
+     * @param cx - sphere center x
+     * @param cy - sphere center y
+     * @param cz - sphere center z
+     * @param r - sphere radius (must be ≥ 0; `r=0` becomes a point-in-AABB test)
+     */
+    overlapsSphere(cx: number, cy: number, cz: number, r: number): boolean;
+    /**
+     * Expand this AABB to include the given point.
+     * @param p - the point to fold in
+     */
+    addPoint(p: XYZPoint | Vector3d): void;
+    /**
+     * Expand this AABB to include the given AABB. With `clear=true`,
+     * copies the input AABB directly — same shape as {@link Bounds.addBounds}.
+     * @param aabb - the AABB to fold in
+     * @param [clear] - reset this AABB before folding
+     */
+    addAABB(aabb: AABB3d, clear?: boolean): void;
+    /**
+     * Returns a deep copy of this AABB.
+     */
+    clone(): AABB3d;
+}
+//# sourceMappingURL=aabb3d.d.ts.map

package/build/physics/broadphase/aabb3d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aabb3d.d.ts","sourceRoot":"","sources":["../../../src/physics/broadphase/aabb3d.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,MAAM;IAClB,GAAG,EAAE,QAAQ,CAAC;IACd,GAAG,EAAE,QAAQ,CAAC;IAEd;;;;;;;OAOG;gBACS,GAAG,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,EAAE,QAAQ;IAQ1C;;OAEG;IACH,KAAK;IASL;;;;;;;;OAQG;IACH,SAAS,CACR,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM;IAUb,IAAI,CAAC,IAAI,MAAM,CAEd;IACD,IAAI,CAAC,IAAI,MAAM,CAEd;IACD,IAAI,CAAC,IAAI,MAAM,CAEd;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;IACD,IAAI,MAAM,IAAI,MAAM,CAEnB;IACD,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IACD,IAAI,KAAK,IAAI,MAAM,CAElB;IACD,IAAI,GAAG,IAAI,MAAM,CAEhB;IACD,IAAI,MAAM,IAAI,MAAM,CAEnB;IACD,IAAI,KAAK,IAAI,MAAM,CAElB;IACD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IACD,IAAI,OAAO,IAAI,MAAM,CAEpB;IACD,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED;;;;;;OAMG;IACH,QAAQ;IAWR;;;;;OAKG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM;IAWxC;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM;IAWrB;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM;IAW5D;;;OAGG;IACH,QAAQ,CAAC,CAAC,EAAE,QAAQ,GAAG,QAAQ;IAS/B;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,UAAQ;IAkBnC;;OAEG;IACH,KAAK;CAGL"}

package/build/physics/broadphase/broadphase.d.ts

@@ -0,0 +1,74 @@
+import type Container from "../../renderable/container.js";
+/**
+ * Common surface shared by every broadphase implementation in
+ * melonJS. Selected at runtime by {@link World.broadphase} based on
+ * `world.sortOn`:
+ *   - 2D (`sortOn` ∈ `"x"` / `"y"` / `"z"`) → {@link QuadTree}
+ *   - 3D (`sortOn === "depth"`)             → {@link Octree}
+ *
+ * Internal contract — not exported from the package entry. The
+ * documented user-facing 3D spatial-query surface is
+ * `world.adapter.queryAABB(rect)`, `world.adapter.querySphere(sphere)`,
+ * `world.adapter.raycast(from, to)`, `world.adapter.raycast3d?(from, to)`.
+ * `world.broadphase` is reachable for engine internals and tooling
+ * (e.g. `@melonjs/debug-plugin` reads it to draw the spatial overlay),
+ * but user game code shouldn't need it directly.
+ *
+ * The generic `TItem` lets each implementation narrow to its own
+ * item shape (`QuadTreeItem` / `OctreeItem`) without losing the
+ * shared contract. The 3D `Octree`-only region queries
+ * (`queryAABB`, `querySphere`, `queryFrustum`, `queryRay`) are NOT
+ * part of this interface — they live on `Octree` directly because
+ * `QuadTree` has no equivalent.
+ */
+export interface Broadphase<TItem = unknown> {
+    /** depth in the tree; 0 at the root. */
+    readonly level: number;
+    /** node-capacity threshold; exceeding it triggers a split. */
+    max_objects: number;
+    /** maximum subdivision depth; the root won't split past this. */
+    max_levels: number;
+    /** items held at this node level (not in subnodes). */
+    objects: TItem[];
+    /** subnodes (empty until {@link Broadphase.split} fires). */
+    nodes: Broadphase<TItem>[];
+    /**
+     * Total items in this subtree (own `objects` + descendants).
+     * Maintained by `insert` / `remove` so {@link Broadphase.isPrunable}
+     * and {@link Broadphase.hasChildren} are O(1) reads.
+     * @ignore
+     */
+    _subtreeCount: number;
+    /** Insert one item. Splits + redistributes if `max_objects` is exceeded. */
+    insert(item: TItem): void;
+    /**
+     * Remove one item. Returns `true` if the item was found.
+     * Includes a stale-bounds fallback walk for items that moved
+     * between insert and remove without a rebuild in between.
+     */
+    remove(item: TItem): boolean;
+    /**
+     * Return every item that could collide with `item`. Re-entrancy
+     * contract: the no-`result` form reuses a shared scratch array;
+     * pass an explicit `result` to be re-entrancy-safe.
+     */
+    retrieve(item: TItem, fn?: (a: TItem, b: TItem) => number, result?: TItem[]): TItem[];
+    /** Recursively insert every non-kinematic child of `container`. */
+    insertContainer(container: Container): void;
+    /** Inverse of {@link Broadphase.insertContainer}. */
+    removeContainer(container: Container): void;
+    /** Empty this node + every subnode; optionally resize the root bounds. */
+    clear(bounds?: unknown): void;
+    /** True if this subtree holds no items at any level. */
+    isPrunable(): boolean;
+    /** True if this node has any descendants (items in subnodes). */
+    hasChildren(): boolean;
+    /**
+     * Classify `item` into a subnode index, or `-1` if it spans a
+     * midpoint / sits outside the node's bounds.
+     */
+    getIndex(item: TItem): number;
+    /** Subdivide this node into its subnodes (4 for 2D, 8 for 3D). */
+    split(): void;
+}
+//# sourceMappingURL=broadphase.d.ts.map

package/build/physics/broadphase/broadphase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"broadphase.d.ts","sourceRoot":"","sources":["../../../src/physics/broadphase/broadphase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,+BAA+B,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,UAAU,CAAC,KAAK,GAAG,OAAO;IAC1C,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,OAAO,EAAE,KAAK,EAAE,CAAC;IACjB,6DAA6D;IAC7D,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;IAC3B;;;;;OAKG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB,4EAA4E;IAC5E,MAAM,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC;IAC1B;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CACP,IAAI,EAAE,KAAK,EACX,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,KAAK,MAAM,EACnC,MAAM,CAAC,EAAE,KAAK,EAAE,GACd,KAAK,EAAE,CAAC;IACX,mEAAmE;IACnE,eAAe,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IAC5C,qDAAqD;IACrD,eAAe,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IAC5C,0EAA0E;IAC1E,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,wDAAwD;IACxD,UAAU,IAAI,OAAO,CAAC;IACtB,iEAAiE;IACjE,WAAW,IAAI,OAAO,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,MAAM,CAAC;IAC9B,kEAAkE;IAClE,KAAK,IAAI,IAAI,CAAC;CACd"}

package/build/physics/broadphase/factory.d.ts

@@ -0,0 +1,30 @@
+import type World from "../world.js";
+import type { Broadphase } from "./broadphase.ts";
+/**
+ * Build the spatial broadphase that matches `world.sortOn`. Called
+ * by `World` on construction and on every 2D↔3D sortOn flip; not
+ * part of the user-facing surface.
+ *
+ * - `sortOn === "depth"` → {@link Octree} rooted at an origin-
+ *   centred ±10000 box. Camera3d games conventionally centre the
+ *   play area on the world origin (items at e.g.
+ *   `x ∈ [-PLAY_BOUND_X, PLAY_BOUND_X]`); `world.getBounds()` returns
+ *   the 2D viewport rect `(0..w, 0..h)` which doesn't contain those
+ *   items. Using viewport bounds as the octree root would
+ *   misclassify negative-coord items into octants whose AABBs don't
+ *   contain them, breaking `querySphere`'s spatial pruning. ±10000
+ *   covers arcade-3D scales (AfterBurner ≈ ±350 xy, ±1000 z); items
+ *   outside still work — `getIndex` keeps them at `root.objects` so
+ *   queries walk them via the root-level pass, just without the
+ *   spatial-partition win.
+ * - any other sortOn → {@link QuadTree} rooted at
+ *   `world.getBounds().clone()` (the viewport rect).
+ *
+ * Lives in `physics/broadphase/` (not on `World`) so the World class
+ * doesn't need to know which concrete tree class implements the
+ * spatial index, or what bounds shape each class wants — those are
+ * broadphase concerns.
+ * @param world - the world this broadphase will index
+ */
+export declare function createBroadphase(world: World): Broadphase;
+//# sourceMappingURL=factory.d.ts.map

package/build/physics/broadphase/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../src/physics/broadphase/factory.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,aAAa,CAAC;AAErC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAIlD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,UAAU,CAYzD"}

package/build/physics/broadphase/octree.d.ts

@@ -0,0 +1,325 @@
+import { Sphere } from "../../geometries/sphere.ts";
+import type World from "../world.js";
+import { AABB3d } from "./aabb3d.ts";
+import type { Broadphase } from "./broadphase.ts";
+/**
+ * 8-octant spatial subdivision for `Camera3d` workloads. Sibling to
+ * {@link QuadTree}: same public surface (`insert`, `remove`,
+ * `retrieve`, `insertContainer`, `removeContainer`, `clear`,
+ * `getIndex`, `isPrunable`, `hasChildren`), plus 3D-specific
+ * region queries (`queryAABB`, `querySphere`). Selected
+ * automatically by {@link World} when `world.sortOn === "depth"`
+ * (which `Camera3d.defaultSortOn` sets on stage reset).
+ *
+ * Implementation notes:
+ * - Bounding primitive is {@link AABB3d}; subnode bounds are POJOs
+ *   with the same shape so node split is allocation-free apart from
+ *   the eight literal objects (recycled via the global node pool).
+ * - Per-frame clear/insert reuses both an octree-node pool
+ *   (`OT_ARRAY`) and a result scratch (`_retrieveScratch`), so the
+ *   steady state allocates nothing.
+ * - Item z is read via `getAbsolutePosition()` — same convention as
+ *   `Camera3d.isVisible` and the container depth sort, so the
+ *   broadphase agrees with the renderer on which octant an item
+ *   lives in even under nested transforms.
+ */
+/**
+ * Minimal axis-aligned box shape consumed by `Octree`. Both
+ * {@link AABB3d} and the POJOs emitted by `split` satisfy it
+ * structurally.
+ */
+export interface OctRect {
+    left: number;
+    top: number;
+    front: number;
+    width: number;
+    height: number;
+    depth: number;
+}
+/**
+ * Structural shape for an item inserted into the `Octree`. Same
+ * shape as {@link QuadTree}'s item, with the addition that
+ * `getAbsolutePosition()` is consulted for z (so nested transforms
+ * still classify into the right octant).
+ */
+export interface OctreeItem {
+    getBounds(): {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    getAbsolutePosition?(): {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /**
+     * 2D items expose Vector2d here (no z); 3D items expose Vector3d.
+     * `getAbsolutePosition()` is the preferred path; this fallback
+     * applies only to test doubles that skip `getAbsolutePosition`.
+     */
+    pos?: {
+        x: number;
+        y: number;
+        z?: number;
+    };
+    isFloating?: boolean;
+    isKinematic?: boolean;
+    name?: string;
+}
+export type OctreeSortFn = (a: OctreeItem, b: OctreeItem) => number;
+/**
+ * Structural shape consumed by {@link Octree.queryFrustum} —
+ * matches the shape exposed by `Frustum#planes` (see
+ * `camera/frustum.ts`). Each plane satisfies `nx·x + ny·y + nz·z + d = 0`;
+ * positive side is the interior of the frustum.
+ */
+export interface FrustumPlane {
+    nx: number;
+    ny: number;
+    nz: number;
+    d: number;
+}
+/**
+ * an Octree implementation for 3D broadphase / spatial queries
+ * under `Camera3d`.
+ * @category Physics
+ * @see World.broadphase
+ */
+export default class Octree implements Broadphase<OctreeItem> {
+    world: World;
+    bounds: OctRect | AABB3d;
+    max_objects: number;
+    max_levels: number;
+    level: number;
+    objects: OctreeItem[];
+    nodes: Octree[];
+    /**
+     * see {@link QuadTree._subtreeCount} — same invariant.
+     * @ignore
+     */
+    _subtreeCount: number;
+    /**
+     * see {@link QuadTree._retrieveScratch} — same contract.
+     * @ignore
+     */
+    _retrieveScratch: OctreeItem[] | null;
+    /**
+     * @param world - the physic world this Octree belongs to
+     * @param bounds - bounds of the node
+     * @param [max_objects=4] - max objects a node can hold before splitting into 8 subnodes
+     * @param [max_levels=4] - total max levels inside root Octree
+     * @param [level] - depth level, required for subnodes
+     */
+    constructor(world: World, bounds: OctRect | AABB3d, max_objects?: number, max_levels?: number, level?: number);
+    /**
+     * Split this node into 8 octants. The naming mirrors the
+     * QuadTree's `top` / `bottom` / `left` / `right` ordering, with
+     * `near` (smaller z) before `far` (larger z) — matches the
+     * Y-down + +Z forward convention from {@link Camera3d}.
+     *
+     * Octant index layout (used by `getIndex`):
+     * ```
+     *   near (lower z)        far (higher z)
+     *   0: TR-near  1: TL-near   4: TR-far  5: TL-far
+     *   3: BR-near  2: BL-near   7: BR-far  6: BL-far
+     * ```
+     */
+    split(): void;
+    /**
+     * Classify an item into an octant.
+     *
+     * Returns -1 (keep at this level) when the item straddles ANY
+     * midpoint OR sits outside this node's bounds entirely. The
+     * out-of-bounds guard matters for `querySphere`: a sphere walks
+     * subnodes by AABB overlap, so an item assigned to a subnode
+     * whose bounds don't actually contain it would be invisible to
+     * any query whose sphere doesn't overlap that subnode's AABB.
+     * Items outside the root live at `root.objects` and are visited
+     * by every query unconditionally — they degrade to a linear scan
+     * but stay findable.
+     * @param item - the object to classify
+     * @returns octant index (0-7) or -1
+     */
+    getIndex(item: OctreeItem): number;
+    /**
+     * Insert the given object container into the node — recursively
+     * walks `Container.getChildren()` and inserts each non-kinematic
+     * leaf. Mirrors `QuadTree.insertContainer`.
+     * @param container - group of objects to be added
+     */
+    insertContainer(container: ContainerLike): void;
+    /**
+     * Insert the given object into the node. If this node exceeds
+     * `max_objects`, it splits and redistributes existing items into
+     * subnodes. Mirrors `QuadTree.insert` — same subtree-count
+     * accounting (bump on insert, no bump on redistribution).
+     * @param item - object to be added
+     */
+    insert(item: OctreeItem): void;
+    /**
+     * Recursively remove the given container and its descendants from
+     * the octree. Mirror of `QuadTree.removeContainer`.
+     * @param container - group of objects to be removed
+     */
+    removeContainer(container: ContainerLikeOptional): void;
+    /**
+     * Return every object that could collide with the given item.
+     * Re-entrancy contract identical to {@link QuadTree.retrieve}: the
+     * default (scratch) path is allocation-free but cannot be safely
+     * re-entered while iterating; pass an explicit `result` for safe
+     * re-entry.
+     * @param item - object to be checked against
+     * @param [fn] - sorter applied to the returned array (root only)
+     * @param [result] - caller-supplied result array (re-entrancy-safe)
+     * @returns the collected candidates
+     */
+    retrieve(item: OctreeItem, fn?: OctreeSortFn, result?: OctreeItem[]): OctreeItem[];
+    /**
+     * Return every object whose subtree overlaps the given AABB.
+     * Walks only octants whose bounds overlap the query — same
+     * pruning shape as `retrieve(item)`, just driven by an explicit
+     * region instead of an item's own bounds.
+     *
+     * Re-entrancy: same contract as {@link Octree.retrieve}. Pass an
+     * explicit `result` for safe re-entry.
+     * @param aabb - the AABB region to query
+     * @param [result] - caller-supplied result array (re-entrancy-safe)
+     * @returns the collected candidates
+     */
+    queryAABB(aabb: AABB3d, result?: OctreeItem[]): OctreeItem[];
+    /**
+     * Return every object whose containing octant overlaps the given
+     * sphere. Replaces the hand-rolled O(n²) sphere-vs-sphere loops
+     * common in arcade 3D code with a broadphase that scales.
+     *
+     * Two call shapes — both forms route to the same internal walk:
+     * - `querySphere(cx, cy, cz, r, result?)` — loose floats
+     * - `querySphere(sphere, result?)` — packaged {@link Sphere}
+     *
+     * Re-entrancy: same contract as {@link Octree.retrieve}.
+     */
+    querySphere(sphere: Sphere, result?: OctreeItem[]): OctreeItem[];
+    /**
+     * @param cx - sphere center x
+     * @param cy - sphere center y
+     * @param cz - sphere center z
+     * @param r - sphere radius (must be ≥ 0; r=0 becomes a point query)
+     * @param [result] - caller-supplied result array (re-entrancy-safe)
+     * @returns the collected candidates
+     */
+    querySphere(cx: number, cy: number, cz: number, r: number, result?: OctreeItem[]): OctreeItem[];
+    /**
+     * Loose-floats implementation. Recursive subnode walks call this
+     * directly to bypass the Sphere/floats dispatch on every node.
+     * @ignore
+     */
+    _querySphereInternal(cx: number, cy: number, cz: number, r: number, result?: OctreeItem[]): OctreeItem[];
+    /**
+     * Return every object whose containing octant lies on the
+     * positive side of all six frustum planes — i.e. every potential
+     * candidate the frustum can see. Uses Gribb–Hartmann positive-
+     * vertex pruning at each node: a subtree is skipped iff its
+     * octant's most-positive corner along a plane normal is on that
+     * plane's negative side (i.e. wholly outside the frustum).
+     *
+     * Mirrors {@link Frustum#intersectsSphere} on the renderer side —
+     * use this as the broadphase pass before per-item narrow-phase
+     * checks (sphere / OBB / etc.).
+     *
+     * Re-entrancy: same contract as {@link Octree.retrieve}. Pass an
+     * explicit `result` for safe re-entry.
+     * @param planes - 6 frustum planes (left, right, bottom, top, near, far) — `Frustum#planes` shape
+     * @param [result] - caller-supplied result array (re-entrancy-safe)
+     * @returns the collected candidates
+     */
+    queryFrustum(planes: FrustumPlane[], result?: OctreeItem[]): OctreeItem[];
+    /**
+     * Return every object whose containing octant the ray segment
+     * `from + t·dir`, `t ∈ [0, tMax]`, crosses. Slab AABB test prunes
+     * subtrees the ray misses entirely — much tighter than enclosing
+     * the segment in a single AABB and walking `queryAABB`. The
+     * candidates aren't sorted by hit-distance (front-to-back walk
+     * would require a per-octant DDA step); callers that need
+     * nearest-hit sort the narrow-phase results themselves.
+     *
+     * Re-entrancy: same contract as {@link Octree.retrieve}.
+     * @param fromX - ray origin x
+     * @param fromY - ray origin y
+     * @param fromZ - ray origin z
+     * @param dirX - ray direction x (`to - from`; not unit-length)
+     * @param dirY - ray direction y
+     * @param dirZ - ray direction z
+     * @param tMax - maximum t along the ray (usually `1` if `dir = to - from`)
+     * @param [result] - caller-supplied result array (re-entrancy-safe)
+     * @returns the collected candidates
+     */
+    queryRay(fromX: number, fromY: number, fromZ: number, dirX: number, dirY: number, dirZ: number, tMax: number, result?: OctreeItem[]): OctreeItem[];
+    /**
+     * Remove the given item from the octree. Mirror of
+     * `QuadTree.remove` — same stale-bounds fallback walk, same
+     * collapse-on-removal pool recycling.
+     * @param item - object to be removed
+     * @returns true if the item was found and removed.
+     */
+    remove(item: OctreeItem): boolean;
+    /**
+     * @returns true if this subtree holds no items at any level.
+     */
+    isPrunable(): boolean;
+    /**
+     * @returns true if this node has any descendants (items in
+     * subnodes, not at this level).
+     */
+    hasChildren(): boolean;
+    /**
+     * Empty this octree and recycle every subnode back to the pool.
+     * If `bounds` is supplied, resizes the root bounds to match —
+     * called by `World` on `LEVEL_LOADED` so the broadphase tracks
+     * level boundary changes.
+     * @param [bounds] - the new root bounds (resize on clear)
+     */
+    clear(bounds?: AABB3d): void;
+    /**
+     * Conservative outside-frustum test using the positive-vertex
+     * method (Gribb–Hartmann). Returns true iff the octant is
+     * provably outside ANY one plane, i.e. wholly outside the
+     * frustum.
+     * @ignore
+     */
+    _outsideFrustum(planes: FrustumPlane[]): boolean;
+    /**
+     * Slab method for ray–AABB intersection. Returns true iff the
+     * segment `from + t·dir`, `t ∈ [0, tMax]`, intersects this
+     * node's octant. dir components may be zero; the axis with zero
+     * direction degenerates to a point-in-slab test.
+     * @ignore
+     */
+    _overlapsRay(fromX: number, fromY: number, fromZ: number, dirX: number, dirY: number, dirZ: number, tMax: number): boolean;
+    /** @ignore */
+    _overlapsAABB(aabb: AABB3d): boolean;
+    /** @ignore */
+    _overlapsSphere(cx: number, cy: number, cz: number, r: number): boolean;
+}
+/**
+ * Structural shape consumed by `insertContainer` / `removeContainer`
+ * — captures only the fields the walk inspects. Same approach as
+ * QuadTree. `getChildren` is optional because leaf renderables don't
+ * have it; the recursive walk narrows via {@link hasGetChildren}.
+ * @ignore
+ */
+interface ContainerOrChild extends OctreeItem {
+    addChild?: (...args: unknown[]) => unknown;
+    getChildren?: () => ContainerOrChild[];
+}
+/** @ignore */
+type ContainerLike = {
+    getChildren(): ContainerOrChild[];
+};
+/** @ignore */
+type ContainerLikeOptional = {
+    getChildren?(): ContainerOrChild[];
+};
+export {};
+//# sourceMappingURL=octree.d.ts.map

package/build/physics/broadphase/octree.d.ts.map

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