melonjs 20.7.0 → 20.8.0

package/README.md

@@ -61,14 +61,15 @@ Graphics
     - **2D** — `Light2d` as a first-class `Renderable` (multiple dynamic lights, radial-gradient falloff, illumination-only mode, procedural rendering via `drawLight`), plus optional per-pixel normal-map shading on sprites for 3D-looking dynamic lights
     - **3D** — `Light3d` directional, point, spot and ambient lights, added to the world like `Light2d` (half-Lambert diffuse + ambient fill, quadratic falloff and cone angles on the punctual types, runtime-manipulable for day/night), auto-loaded from a glTF scene's authored suns and lamps
     - up to **32 simultaneous lights** on either path, with light data travelling in a uniform buffer — a static light rig costs zero GPU state changes per frame
-- Ground ("blob") shadows for 3D objects — **on by default** — so characters and props read as standing on the floor instead of hovering. An ellipse matching the caster's own footprint and rotation, shrinking and fading with height above the ground; one extra draw per object, and **one for an entire `InstancedMesh` scatter regardless of instance count**. Controllable per object, per glTF scene (`level.load(name, { castGroundShadow })`) or application-wide. Deliberately not shadow mapping: it answers "where is this standing", which is what a 2.5D scene needs
-- Built-in shader effects (Flash, Outline, Glow, Dissolve, CRT, Hologram, etc.) with multi-pass chaining via `addPostEffect()`, plus custom shader support on both GPU backends: `ShaderEffect` for per-sprite fragment effects (GLSL and/or WGSL bodies) and complete custom mesh shader programs via `mesh.shader` (a dual-language `GLShader`: GLSL pair and/or WGSL module)
+- Ground ("blob") shadows for 3D objects — **on by default** — so characters and props read as standing on the floor instead of hovering. An ellipse matching the caster's own footprint and rotation, shrinking and fading with height above the ground; one extra draw per object, and **one for an entire `InstancedMesh` scatter regardless of instance count**. Shaped by the light rather than always straight down: `shadowLight` points a blob at a `Light3d` and is re-read every draw, so a day/night cycle carries every shadow with it, while `shadowOffset` slides it out from the caster's feet, `shadowStretch` lengthens it for a low sun, `shadowScale` sizes it independently of the object, and `shadowGroundNormal` lays it on a floor that is not level. All of them work on an `InstancedMesh` too, as one value for the whole set. Controllable per object, per glTF scene (`level.load(name, { castGroundShadow, shadowLight, … })`) or application-wide. Deliberately not shadow mapping: it answers "where is this standing", which is what a 2.5D scene needs
+- Built-in shader effects (Flash, Outline, Glow, Bloom, ToneMapping, Dissolve, CRT, Hologram, etc.) with multi-pass chaining via `addPostEffect()`, plus custom shader support on both GPU backends: `ShaderEffect` for per-sprite fragment effects (GLSL and/or WGSL bodies) and complete custom mesh shader programs via `mesh.shader` (a dual-language `GLShader`: GLSL pair and/or WGSL module)
+- Optional HDR rendering (`hdr: true`) — the camera's render targets become half-float, so additive light stops saturating on every write and `BloomEffect` thresholds on genuinely over-bright pixels instead of merely bright ones, with `ToneMappingEffect` and a `toneMapping` setting to compress the result back into display range when your art calls for it. Off by default and additive: nothing is inserted into your effect chain, so turning it on does not restyle a game whose look is built on clipped whites. On WebGPU it goes one step further — `hdrOutput: true` presents the frame in the display's own dynamic range rather than clamping it to SDR at the last step
 - Trail renderable for fading, tapering ribbons behind moving objects (speed lines, sword slashes, magic trails)
 - System & Bitmap Text with built-in typewriter effect
 - Video sprite playback
 
 Sound
-- Web Audio support with 3D spatial audio and stereo panning based on [Howler](https://howlerjs.com)
+- Web Audio support with 3D spatial audio and stereo panning, plus a procedural tone/noise API. The playback backend began as [howler.js](https://howlerjs.com) and is now a customized derivative vendored into the engine, so this is **not** a runtime dependency (see `src/audio/backend/LICENSE`)
 - Built-in procedural audio primitives (envelope-shaped oscillators, white/pink/brown noise) for SFX without sample assets
 - Direct `AudioContext` / master-gain accessors for custom WebAudio graphs that mix with the engine's master volume / mute
 
@@ -191,6 +192,8 @@ Examples
 * [3D Mesh](https://melonjs.github.io/melonJS/examples/#/mesh-3d) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/mesh3d))
 * [3D Mesh Material](https://melonjs.github.io/melonJS/examples/#/mesh-3d-material) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/mesh3dMaterial))
 * [AfterBurner Clone](https://melonjs.github.io/melonJS/examples/#/after-burner) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/afterBurner)) — `Camera3d` + 3D Mesh arcade shooter
+* [Ground Shadows](https://melonjs.github.io/melonJS/examples/#/ground-shadows) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/groundShadows)) — every blob-shadow setting side by side under an orbiting sun, including blobs lying on a slope and a 70-instance scatter that costs one extra draw
+* [Jungle Rabbit](https://melonjs.github.io/melonJS/examples/#/jungle-rabbit) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/jungleRabbit)) — a low-poly river endless runner: Blender-modelled props through `InstancedMesh`, a rigged paddling boat, a procedural valley and shadows laid on its banks
 * [glTF Scene](https://melonjs.github.io/melonJS/examples/#/gltf) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/gltf)) — a Blender-authored, lit 3D scene loaded with `level.load`
 * [glTF Animated Model](https://melonjs.github.io/melonJS/examples/#/gltf-character) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/gltf)) — a rigged character (Kenney Blocky Characters) with node animation, driven by the Sprite-aligned `setCurrentAnimation` / `play` / `pause` / `stop` API
 * [Trail](https://melonjs.github.io/melonJS/examples/#/trail) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/trail))

package/build/application/defaultApplicationSettings.d.ts

@@ -5,6 +5,11 @@ export declare const defaultApplicationSettings: {
     powerPreference: "default";
     transparent: false;
     antiAlias: false;
+    hdr: false;
+    hdrOutput: false;
+    toneMapping: "none";
+    toneMappingExposure: number;
+    toneMappingWhite: number;
     prewarm: true;
     textureFilter: "auto";
     maxTextures: "auto";

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

@@ -1 +1 @@
-{"version":3,"file":"defaultApplicationSettings.d.ts","sourceRoot":"","sources":["../../src/application/defaultApplicationSettings.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;CAoBC,CAAC"}
+{"version":3,"file":"defaultApplicationSettings.d.ts","sourceRoot":"","sources":["../../src/application/defaultApplicationSettings.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;CAyBC,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"header.d.ts","sourceRoot":"","sources":["../../src/application/header.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAC;AAEhD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CA0BpD"}
+{"version":3,"file":"header.d.ts","sourceRoot":"","sources":["../../src/application/header.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAC;AAEhD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CA+CpD"}

package/build/application/settings.d.ts

@@ -100,6 +100,94 @@ export type ApplicationSettings = {
      * @default false
      */
     antiAlias: boolean;
+    /**
+     * Let the post-effect chain carry color values above 1 instead of
+     * clamping at every write.
+     *
+     * Render targets become half-float rather than 8 bits per channel, which
+     * is what gives {@link BloomEffect} genuinely over-bright pixels to
+     * threshold on and {@link ToneMappingEffect} a range to compress. Off by
+     * default, for the same reasons `antiAlias` is: it costs GPU memory, and
+     * a game gets a different pipeline depending on the driver underneath.
+     *
+     * The cost is narrow. Render targets exist only while something is
+     * actually running a multi-pass effect chain, and only the CAMERA pair
+     * takes the half-float format, at 8 bytes per pixel instead of 4. Sprite
+     * chains and the advanced-blend target stay 8-bit whatever this says. A
+     * game with no camera post-effects allocates nothing either way.
+     *
+     * **Not HDR output on its own.** This is headroom THROUGH the chain:
+     * the frame is presented in SDR, so anything still above 1 at the end
+     * clamps on the blit, exactly as it did before this setting existed. See
+     * `hdrOutput` to remove that last clamp as well, on the backends that
+     * can. Nothing is added to your effect
+     * chain, so turning this on does not restyle your game. Add a
+     * `ToneMappingEffect` to the camera if you want a curve rather than that
+     * clamp, bearing in mind that every curve maps 1 to less than 1, so a
+     * look built on clipped whites will change.
+     *
+     * Ignored where it cannot be honoured: the Canvas renderer has no render
+     * targets, and a WebGL2 driver missing either half-float extension warns
+     * once, naming which half, and stays at 8 bits. Read
+     * {@link Renderer#supportsHDR} for what you actually got, and branch a
+     * grade on that rather than on this, which is only the request.
+     * @default false
+     */
+    hdr: boolean;
+    /**
+     * Tone curve applied to the camera at the very end of its effect chain,
+     * or `"none"` to leave the frame alone.
+     *
+     * `"none"` by default, and that default is deliberate. Every curve maps 1
+     * to less than 1, so a 2D look built on clipped whites and saturated
+     * colour goes matte the moment one is applied, at any exposure. Turn it
+     * on when your art is authored in linear light and you want the
+     * highlights rolled off, not as a companion to `hdr`.
+     *
+     * Independent of `hdr`: a curve without headroom is a grade on an
+     * already-clamped frame, which is a legitimate thing to want, and
+     * headroom without a curve is the additive-accumulation win on its own.
+     * @default "none"
+     */
+    /**
+     * Present the frame in the display's full dynamic range, instead of
+     * clamping it to SDR on the way to the screen.
+     *
+     * `hdr` gives the effect chain headroom and then clamps at the very last
+     * step, because the surface the browser presents is 8 bits per channel.
+     * This changes that surface: values above 1 reach the compositor and, on
+     * a display that has the range, are actually shown brighter.
+     *
+     * **Requires `hdr`, and changes how your game looks on an HDR display.**
+     * A 2D look built on clipped whites relies on that final clamp; remove it
+     * and everything you drove above 1 gets brighter rather than saturating.
+     * That is the point, and it is why this is a separate opt-in rather than
+     * part of `hdr`.
+     *
+     * **WebGPU only.** The WebGL2 equivalent is an unapproved specification
+     * change that no browser implements, so that backend reports `false` and
+     * presents in SDR as it always has. Query
+     * {@link Renderer#supportsHDROutput} for what was granted, and expect it
+     * to differ per backend on the same machine.
+     * @default false
+     */
+    hdrOutput: boolean;
+    toneMapping: "none" | "aces" | "reinhard" | "exponential";
+    /**
+     * Multiplier applied before the tone curve. Above `1` lifts the image
+     * into the curve's shoulder; below `1` pulls it down. Ignored while
+     * `toneMapping` is `"none"`.
+     * @default 1
+     */
+    toneMappingExposure: number;
+    /**
+     * The post-exposure value the tone curve should map to display white, or
+     * `0` to leave the curve its own shoulder. This is what a "brightness" or
+     * "peak" slider in a settings screen drives. Ignored while `toneMapping`
+     * is `"none"`.
+     * @default 0
+     */
+    toneMappingWhite: number;
     /**
      * Warm the renderer up during `loader.preload()`, behind the loading
      * screen, instead of paying for it on the frame that first draws (GPU

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

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

package/build/audio/backend/engine.d.ts

@@ -1,5 +1,4 @@
 import type { Sound } from "./sound.ts";
-import { type HTMLAudioElementWithUnlocked } from "./types.ts";
 export declare class AudioEngine {
     html5PoolSize: number;
     sounds: Sound[];

package/build/audio/backend/sound.d.ts

@@ -1,5 +1,4 @@
 import { type HTMLAudioElementWithUnlocked, type SoundOptions } from "./types.ts";
-import { Voice } from "./voice.ts";
 declare class Sound {
     constructor(o: SoundOptions);
     init(o: SoundOptions): this;

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

@@ -29,12 +29,16 @@ export type { Fog3dState, FogMode, FogOptions } from "./fog.ts";
  *   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 XY.** `pitch` (X axis, look up/down) and
+ * - **Three rotation angles.** `pitch` (X axis, look up/down) and
  *   `yaw` (Y axis, look left/right) and `roll` (Z axis, bank the horizon).
  *   The view is `R(yaw) ∘ R(pitch) ∘ R(roll)` inverted; the frustum planes are
  *   extracted from that same matrix, so culling follows a banked view. The
  *   inherited `currentTransform` is still NOT read — `camera.rotate()` on a
  *   3D camera does nothing, so set `roll` rather than rotating the camera.
+ *   The basis those angles produce is readable with
+ *   {@link Camera3d#getBasis} and writable with {@link Camera3d#setBasis},
+ *   which is how a camera is posed over a curved surface where up is the
+ *   surface normal and no pitch and yaw pair expresses it.
  * - **Follow offset (PR B scope).** When a target is set,
  *   `followOffset` is applied in **world space**:
  *   `camera.pos = target.pos + followOffset`. Target-rotation-aware
@@ -275,6 +279,66 @@ export default class Camera3d extends Camera2d {
      * @returns this camera, for chaining
      */
     getBasis(right: Vector3d, up: Vector3d, forward: Vector3d): this;
+    /**
+     * Restore the camera to its initial state: at the given position, looking
+     * straight down the z axis with a level horizon.
+     *
+     * Overridden because the inherited 2D version resets only what a 2D
+     * camera has. It clears `roll`, since in 2D the roll IS the transform
+     * matrix it identity-resets, and it writes `pos.x` and `pos.y`. A 3D
+     * camera also has `pitch`, `yaw` and a depth, none of which it knows
+     * about, so `reset()` used to leave a camera pointing wherever it had
+     * been left and standing at whatever depth it had reached.
+     * @param [x=0] - world x to reset to
+     * @param [y=0] - world y to reset to
+     * @param [z=0] - depth to reset to
+     */
+    reset(x?: number, y?: number, z?: number): void;
+    /**
+     * Pose the camera FROM a basis: the writable counterpart of
+     * {@link Camera3d#getBasis}, taking the same three vectors in the same
+     * order. `setBasis(...)` straight after `getBasis(...)` is the identity.
+     *
+     * This is what a view over a curved surface needs. Up there is the
+     * surface normal and differs at every point, so no pitch and yaw pair
+     * expresses it, and integrating angles towards it drifts and gimbals at
+     * the poles. Hand over the frame the game already has instead.
+     *
+     * The basis is decoded into `pitch`, `yaw` and `roll`, which remain the
+     * camera's only orientation state, so the view transform, the frustum
+     * planes, the fog axis and {@link Sprite3d} billboards all follow with
+     * nothing to invalidate. A consequence worth knowing: the camera can
+     * never end up holding something that is not a rotation. A non-unit or
+     * slightly sheared triple is absorbed rather than rejected, `forward`
+     * winning, then the component of `up` perpendicular to it, with `right`
+     * consulted only when `up` decides nothing. A surface frame integrated
+     * over thousands of steps drifts off orthonormal, and this is the
+     * difference between a camera that tolerates that and one that renders a
+     * sheared view.
+     *
+     * The vectors passed in are never modified.
+     *
+     * Note `up` here is the camera's local +Y column, which under this
+     * engine's Y-down render space points DOWN the screen. That is the
+     * opposite of {@link Camera3d#lookAt}'s `up`, which is the direction that
+     * should appear up on screen. The two are one negation apart, and each
+     * is the natural sense for its own call.
+     * @param right - the camera's local +X axis, in world space
+     * @param up - the camera's local +Y axis, in world space
+     * @param forward - the camera's local +Z axis: where it looks
+     * @returns this camera, for chaining
+     * @throws {Error} if any component is not finite, or every component of
+     * `forward` is zero. The axes need not be unit, or even close to it: only
+     * their directions are read.
+     * @see Camera3d#getBasis
+     * @example
+     * // a camera standing on the surface of a globe, looking along it
+     * const up = surfaceNormal(player);          // differs at every point
+     * const forward = heading(player);
+     * const right = forward.clone().cross(up).normalize();
+     * camera.setBasis(right, up, forward);
+     */
+    setBasis(right: Vector3d, up: Vector3d, forward: Vector3d): this;
     /**
      * The camera's world-space right axis (unit). See {@link Camera3d#getBasis}.
      * @param out - vector to write into (returned)
@@ -303,7 +367,7 @@ export default class Camera3d extends Camera2d {
     resize(w: number, h: number): this;
     /**
      * Point the camera at a world-space target by deriving pitch and
-     * yaw from the direction (target − camera.pos). Roll is unaffected.
+     * yaw from the direction (target − camera.pos).
      *
      * Three call shapes:
      * - `lookAt(x, y, z)` — raw world coordinates
@@ -312,26 +376,49 @@ export default class Camera3d extends Camera2d {
      *   `Renderable.lookAt(target)` signature so Camera3d is a structural
      *   drop-in replacement for Camera2d / Renderable in user code).
      *
+     * **With no `up`, roll is untouched**, exactly as before this argument
+     * existed. Pass one to bank the horizon as well: it is the direction that
+     * should appear UP ON SCREEN, so a level horizon is `(0, -1, 0)` — this
+     * engine renders Y-down, which is why the visual up axis is negative Y.
+     * It is given no default on purpose, because defaulting it would silently
+     * zero the roll of every camera that had one.
+     *
+     * Note this is the opposite sense to {@link Camera3d#setBasis}'s `up`,
+     * which is the camera's local +Y column and points down the screen. Each
+     * is the natural reading for its own call, and they are one negation
+     * apart.
+     *
+     * When the direction to the target is parallel to `up` there is no
+     * rotation about the view axis to solve, so the roll is left as it was
+     * and the camera still points exactly at the target.
+     *
      * 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)
+     * next frame renders with the manual pitch. The same holds for
+     * {@link Camera3d#setBasis}.
+     * @param xOrTarget - target world x, or a target to look at: any renderable, or anything carrying `pos` or `x`/`y`/`z`
+     * @param yOrUp - target world y when the first argument is a number, otherwise the up direction
      * @param z - target world z (only when first arg is a number)
+     * @param up - the direction to appear up on screen (only when first arg is a number)
      * @returns this camera
+     * @example
+     * camera.lookAt(target);                        // pitch and yaw only
+     * camera.lookAt(target, surfaceNormal);         // and bank to the surface
      */
-    lookAt(xOrTarget: number | {
+    lookAt(target: Renderable | {
         x: number;
         y: number;
         z?: number;
         pos?: ObservableVector3d;
-    }, y?: number, z?: number): this;
+    }, up?: Vector3d): this;
+    lookAt(x: number, y?: number, z?: number, up?: Vector3d): this;
     /**
      * Convenience overload of `lookAt` accepting a {@link Vector3d}.
      * @param target - world-space point to look at
+     * @param up - optional direction to appear up on screen; see {@link Camera3d#lookAt}
      * @returns this camera
      */
-    setLookAt(target: Vector3d): this;
+    setLookAt(target: Vector3d, up?: Vector3d): this;
     /**
      * Set the target-local follow offset. Called once when configuring
      * a follow-cam (e.g. behind-and-above third person:

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

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

package/build/geometries/box3d.d.ts

@@ -4,12 +4,16 @@ import { AABB3d } from "../physics/broadphase/aabb3d.ts";
 /**
  * An axis-aligned 3D box, usable as a {@link Body} collision shape.
  *
- * This is the shape that lets a body collide along **Z** as well as X and Y.
- * Every other built-in shape ({@link Polygon}, {@link Rect}, {@link RoundRect},
- * {@link Ellipse}) is planar and is resolved by the 2D SAT narrowphase, which
- * can only ever produce a 2D pushback — see {@link ResponseObject#overlapV}.
- * A `Box3d` pair is instead resolved by an AABB-vs-AABB narrowphase that also
- * fills {@link ResponseObject#overlapZ}.
+ * One of the two shapes that let a body collide along **Z** as well as X and
+ * Y, the other being {@link Sphere}. The planar shapes ({@link Polygon},
+ * {@link Rect}, {@link RoundRect}, {@link Ellipse}) are resolved by the 2D SAT
+ * narrowphase, which can only ever produce a 2D pushback — see
+ * {@link ResponseObject#overlapV}. A `Box3d` pair is instead resolved by an
+ * AABB-vs-AABB narrowphase that also fills {@link ResponseObject#overlapZ}.
+ *
+ * A `Box3d` is world-axis-aligned and cannot be oriented, which makes it the
+ * shape for walls, floors and crates, and the wrong one for anything that
+ * turns. Reach for a `Sphere` there.
  *
  * Coordinate convention matches the rest of melonJS 3D code (see
  * {@link Camera3d}): **Y-down, +Z forward / away from the camera.**
@@ -53,6 +57,20 @@ export declare class Box3d {
      * @default "Box3d"
      */
     type: string;
+    /**
+     * Optional per-shape collision settings, honoured by {@link Body#addShape}
+     * and defaulted there. Declared rather than initialized: the body writes
+     * them when the shape joins it, so a class field here would emit an
+     * `undefined` own property on every shape ever built. See `addShape` for
+     * the table of defaults and what each one does.
+     * @see Body#addShape
+     */
+    collisionType?: number;
+    collisionMask?: number;
+    /** `false` takes this shape out of collision without removing it */
+    isActive?: boolean;
+    /** `true` reports contacts but skips the position correction */
+    isTrigger?: boolean;
     /**
      * @param x - center of the box on the horizontal axis
      * @param y - center of the box on the vertical axis

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

@@ -1 +1 @@
-{"version":3,"file":"box3d.d.ts","sourceRoot":"","sources":["../../src/geometries/box3d.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAC;AAYzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,KAAK;IACjB;;OAEG;IACH,GAAG,EAAE,QAAQ,CAAC;IAEd;;;;OAIG;IACH,WAAW,EAAE,QAAQ,CAAC;IAEtB;;;OAGG;IACH,IAAI,SAAW;IAsBf;;;;;;;OAOG;gBACS,CAAC,SAAI,EAAE,CAAC,SAAI,EAAE,CAAC,SAAI,EAAE,KAAK,SAAI,EAAE,MAAM,SAAI,EAAE,KAAK,SAAI;IAcjE;;;;;;;;;OASG;IACH,QAAQ,CACP,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM;IAiDd;;OAEG;IACH,IAAI,KAAK,IAAI,MAAM,CAElB;IACD,IAAI,KAAK,CAAC,KAAK,EAAE,MAAM,EAGtB;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;IACD,IAAI,MAAM,CAAC,KAAK,EAAE,MAAM,EAGvB;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,MAAM,CAElB;IACD,IAAI,KAAK,CAAC,KAAK,EAAE,MAAM,EAGtB;IAED;;;;;;OAMG;IACH,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,QAAQ,EAAE,CAAC,SAAI,EAAE,CAAC,SAAI;IAUxC;;;;;;;OAOG;IACH,SAAS,IAAI,MAAM;IAInB;;;;OAIG;IACH,WAAW,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM;IAgBjC;;;;;OAKG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,QAAQ,EAAE,CAAC,SAAI,EAAE,CAAC,SAAI,GAAG,OAAO;IAYrD;;;OAGG;IACH,KAAK,IAAI,KAAK;CAUd;AAED,eAAO,MAAM,SAAS,gIAmBpB,CAAC"}
+{"version":3,"file":"box3d.d.ts","sourceRoot":"","sources":["../../src/geometries/box3d.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAC;AAYzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,KAAK;IACjB;;OAEG;IACH,GAAG,EAAE,QAAQ,CAAC;IAEd;;;;OAIG;IACH,WAAW,EAAE,QAAQ,CAAC;IAEtB;;;OAGG;IACH,IAAI,SAAW;IAEf;;;;;;;OAOG;IACK,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IAC/B,oEAAoE;IAC5D,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC3B,gEAAgE;IACxD,SAAS,CAAC,EAAE,OAAO,CAAC;IAsB5B;;;;;;;OAOG;gBACS,CAAC,SAAI,EAAE,CAAC,SAAI,EAAE,CAAC,SAAI,EAAE,KAAK,SAAI,EAAE,MAAM,SAAI,EAAE,KAAK,SAAI;IAcjE;;;;;;;;;OASG;IACH,QAAQ,CACP,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM;IAiDd;;OAEG;IACH,IAAI,KAAK,IAAI,MAAM,CAElB;IACD,IAAI,KAAK,CAAC,KAAK,EAAE,MAAM,EAGtB;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;IACD,IAAI,MAAM,CAAC,KAAK,EAAE,MAAM,EAGvB;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,MAAM,CAElB;IACD,IAAI,KAAK,CAAC,KAAK,EAAE,MAAM,EAGtB;IAED;;;;;;OAMG;IACH,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,QAAQ,EAAE,CAAC,SAAI,EAAE,CAAC,SAAI;IAUxC;;;;;;;OAOG;IACH,SAAS,IAAI,MAAM;IAInB;;;;OAIG;IACH,WAAW,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM;IAgBjC;;;;;OAKG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,QAAQ,EAAE,CAAC,SAAI,EAAE,CAAC,SAAI,GAAG,OAAO;IAYrD;;;OAGG;IACH,KAAK,IAAI,KAAK;CAUd;AAED,eAAO,MAAM,SAAS,gIAmBpB,CAAC"}

package/build/geometries/ellipse.d.ts

@@ -36,6 +36,20 @@ export declare class Ellipse {
      * the shape type (used internally)
      */
     type: string;
+    /**
+     * Optional per-shape collision settings, honoured by {@link Body#addShape}
+     * and defaulted there. Declared rather than initialized: the body writes
+     * them when the shape joins it, so a class field here would emit an
+     * `undefined` own property on every shape ever built. See `addShape` for
+     * the table of defaults and what each one does.
+     * @see Body#addShape
+     */
+    collisionType?: number;
+    collisionMask?: number;
+    /** `false` takes this shape out of collision without removing it */
+    isActive?: boolean;
+    /** `true` reports contacts but skips the position correction */
+    isTrigger?: boolean;
     /**
      * @param x - the center x coordinate of the ellipse
      * @param y - the center y coordinate of the ellipse

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

@@ -1 +1 @@
-{"version":3,"file":"ellipse.d.ts","sourceRoot":"","sources":["../../src/geometries/ellipse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAgB,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,MAAM,EAAc,MAAM,sBAAsB,CAAC;AAE1D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC;;;GAGG;AACH,qBAAa,OAAO;IACnB;;OAEG;IACH,GAAG,EAAE,QAAQ,CAAC;IASd;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,OAAO,EAAE,QAAQ,CAAC;IAElB;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAW;IAE3B;;OAEG;IACH,KAAK,EAAE,QAAQ,CAAC;IA8BhB;;OAEG;IACH,IAAI,KAAK,WAER;IACD,IAAI,KAAK,CAAC,KAAK,QAAA,EAMd;IAED;;OAEG;IACH,IAAI,SAAa;IAEjB;;;;;OAKG;gBACS,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM;IAatD;;;;;;;OAOG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM;IAuBnD;;OAEG;IACH,OAAO,CAAC,YAAY;IA6BpB;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,QAAQ;IAQlC;;;;;OAKG;IACH,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,SAAI;IAStB;;;;OAIG;IACH,MAAM,CAAC,CAAC,EAAE,QAAQ;IAIlB;;;;OAIG;IACH,SAAS,CAAC,CAAC,EAAE,QAAQ;IA6BrB;;;;;;;;;OASG;IACH,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO;IACxC,SAAS,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO;IAoBpC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO;IACvC,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO;IA+BnC;;;OAGG;IACH,SAAS;IAOT;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,SAAK;IA2BvB;;;OAGG;IACH,KAAK;CAaL;AAED,eAAO,MAAM,WAAW,kGAYtB,CAAC"}
+{"version":3,"file":"ellipse.d.ts","sourceRoot":"","sources":["../../src/geometries/ellipse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAgB,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,MAAM,EAAc,MAAM,sBAAsB,CAAC;AAE1D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC;;;GAGG;AACH,qBAAa,OAAO;IACnB;;OAEG;IACH,GAAG,EAAE,QAAQ,CAAC;IASd;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,OAAO,EAAE,QAAQ,CAAC;IAElB;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAW;IAE3B;;OAEG;IACH,KAAK,EAAE,QAAQ,CAAC;IA8BhB;;OAEG;IACH,IAAI,KAAK,WAER;IACD,IAAI,KAAK,CAAC,KAAK,QAAA,EAMd;IAED;;OAEG;IACH,IAAI,SAAa;IAEjB;;;;;;;OAOG;IACK,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IAC/B,oEAAoE;IAC5D,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC3B,gEAAgE;IACxD,SAAS,CAAC,EAAE,OAAO,CAAC;IAE5B;;;;;OAKG;gBACS,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM;IAatD;;;;;;;OAOG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM;IAuBnD;;OAEG;IACH,OAAO,CAAC,YAAY;IA6BpB;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,QAAQ;IAQlC;;;;;OAKG;IACH,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,SAAI;IAStB;;;;OAIG;IACH,MAAM,CAAC,CAAC,EAAE,QAAQ;IAIlB;;;;OAIG;IACH,SAAS,CAAC,CAAC,EAAE,QAAQ;IA6BrB;;;;;;;;;OASG;IACH,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO;IACxC,SAAS,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO;IAoBpC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO;IACvC,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO;IA+BnC;;;OAGG;IACH,SAAS;IAOT;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,SAAK;IA2BvB;;;OAGG;IACH,KAAK;CAaL;AAED,eAAO,MAAM,WAAW,kGAYtB,CAAC"}

package/build/geometries/polygon.d.ts

@@ -43,6 +43,20 @@ export declare class Polygon {
      * the shape type (used internally)
      */
     type: string;
+    /**
+     * Optional per-shape collision settings, honoured by {@link Body#addShape}
+     * and defaulted there. Declared rather than initialized: the body writes
+     * them when the shape joins it, so a class field here would emit an
+     * `undefined` own property on every shape ever built. See `addShape` for
+     * the table of defaults and what each one does.
+     * @see Body#addShape
+     */
+    collisionType?: number;
+    collisionMask?: number;
+    /** `false` takes this shape out of collision without removing it */
+    isActive?: boolean;
+    /** `true` reports contacts but skips the position correction */
+    isTrigger?: boolean;
     /**
      * @param [x=0] - origin point of the Polygon
      * @param [y=0] - origin point of the Polygon

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

@@ -1 +1 @@
-{"version":3,"file":"polygon.d.ts","sourceRoot":"","sources":["../../src/geometries/polygon.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAgB,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,MAAM,EAAc,MAAM,sBAAsB,CAAC;AAE1D,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAG5C,MAAM,MAAM,eAAe,GACxB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC,GACzC,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,QAAQ,EAAE,CAAC,GAC7C,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;AAEjE,MAAM,MAAM,YAAY,GACrB,CAAC,OAAO,EAAE,OAAO,CAAC,GAClB,CAAC,QAAQ,EAAE,QAAQ,CAAC,GACpB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAEpC;;;;;;;;GAQG;AACH,qBAAa,OAAO;IACnB;;OAEG;IACH,GAAG,EAAE,QAAQ,CAAC;IAEd;;;OAGG;IACH,MAAM,EAAE,QAAQ,EAAE,CAAC;IAEnB;;;;OAIG;IACH,KAAK,EAAE,QAAQ,EAAE,CAAC;IAElB;;;;;;;;OAQG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;IA4BlB;;OAEG;IACH,IAAI,SAAa;IAEjB;;;;OAIG;gBACS,CAAC,oBAAI,EAAE,CAAC,oBAAI,EAAE,QAAQ,EAAE,eAAe,GAAG,YAAY;IAUlE;;;;;;OAMG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,YAAY;IAMrE;;;;OAIG;IACH,WAAW,CAAC,QAAQ,EAAE,eAAe,GAAG,YAAY;IAiCpD;;;;OAIG;IACH,SAAS,CAAC,CAAC,EAAE,QAAQ;IAWrB;;;OAGG;IACH,KAAK;IAIL;;;OAGG;IACH,IAAI;IAIJ;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,QAAQ,GAAG,OAAO;IA0C5C;;;;;OAKG;IACH,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,SAAI;IAWtB;;;;OAIG;IACH,MAAM,CAAC,CAAC,EAAE,QAAQ;IAIlB;;;;OAIG;IACH,MAAM;IA8DN;;;OAGG;IACH,UAAU;IAcV;;;OAGG;IACH,QAAQ;IAoCR;;;;;;;;;OASG;IACH,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO;IACxC,SAAS,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO;IAoBpC;;;;;;;;OAQG;IACH,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI;IACjC,KAAK,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI;IAgB7B;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO;IACvC,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO;IAmCnC;;;OAGG;IACH,SAAS;IAIT;;;OAGG;IACH,YAAY;IASZ;;;OAGG;IACH,KAAK;CAYL;AAED,eAAO,MAAM,WAAW,8FAYtB,CAAC"}
+{"version":3,"file":"polygon.d.ts","sourceRoot":"","sources":["../../src/geometries/polygon.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAgB,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,MAAM,EAAc,MAAM,sBAAsB,CAAC;AAE1D,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAG5C,MAAM,MAAM,eAAe,GACxB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC,GACzC,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,QAAQ,EAAE,CAAC,GAC7C,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;AAEjE,MAAM,MAAM,YAAY,GACrB,CAAC,OAAO,EAAE,OAAO,CAAC,GAClB,CAAC,QAAQ,EAAE,QAAQ,CAAC,GACpB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAEpC;;;;;;;;GAQG;AACH,qBAAa,OAAO;IACnB;;OAEG;IACH,GAAG,EAAE,QAAQ,CAAC;IAEd;;;OAGG;IACH,MAAM,EAAE,QAAQ,EAAE,CAAC;IAEnB;;;;OAIG;IACH,KAAK,EAAE,QAAQ,EAAE,CAAC;IAElB;;;;;;;;OAQG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;IA4BlB;;OAEG;IACH,IAAI,SAAa;IAEjB;;;;;;;OAOG;IACK,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IAC/B,oEAAoE;IAC5D,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC3B,gEAAgE;IACxD,SAAS,CAAC,EAAE,OAAO,CAAC;IAE5B;;;;OAIG;gBACS,CAAC,oBAAI,EAAE,CAAC,oBAAI,EAAE,QAAQ,EAAE,eAAe,GAAG,YAAY;IAUlE;;;;;;OAMG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,YAAY;IAMrE;;;;OAIG;IACH,WAAW,CAAC,QAAQ,EAAE,eAAe,GAAG,YAAY;IAiCpD;;;;OAIG;IACH,SAAS,CAAC,CAAC,EAAE,QAAQ;IAWrB;;;OAGG;IACH,KAAK;IAIL;;;OAGG;IACH,IAAI;IAIJ;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,QAAQ,GAAG,OAAO;IA0C5C;;;;;OAKG;IACH,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,SAAI;IAWtB;;;;OAIG;IACH,MAAM,CAAC,CAAC,EAAE,QAAQ;IAIlB;;;;OAIG;IACH,MAAM;IA8DN;;;OAGG;IACH,UAAU;IAcV;;;OAGG;IACH,QAAQ;IAoCR;;;;;;;;;OASG;IACH,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO;IACxC,SAAS,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO;IAoBpC;;;;;;;;OAQG;IACH,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI;IACjC,KAAK,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI;IAgB7B;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO;IACvC,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO;IAmCnC;;;OAGG;IACH,SAAS;IAIT;;;OAGG;IACH,YAAY;IASZ;;;OAGG;IACH,KAAK;CAYL;AAED,eAAO,MAAM,WAAW,8FAYtB,CAAC"}

package/build/geometries/sphere.d.ts

@@ -7,9 +7,12 @@ import { AABB3d } from "../physics/broadphase/aabb3d.ts";
  * 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.
+ * Also a BODY SHAPE. A `Body` carrying a Sphere is resolved by the
+ * builtin 3D narrowphase against another Sphere or a {@link Box3d},
+ * which is what makes it the right primitive for anything that tumbles
+ * or is laid out over a curved surface: a {@link Box3d} is
+ * world-axis-aligned and cannot be oriented, so every object whose "up"
+ * points a different way needs a shape that has no "up" at all.
  * @category Geometry
  * @example
  * import { Sphere } from "melonjs";
@@ -19,6 +22,27 @@ import { AABB3d } from "../physics/broadphase/aabb3d.ts";
  * a.overlaps(b); // true — surfaces touch at x = 5
  */
 export declare class Sphere {
+    /**
+     * Shape tag, as the narrowphase's pair table keys on. That table is a
+     * string concat of the two shapes' types and a missing entry is a hard
+     * failure rather than a missed collision, so this has to match the
+     * entries registered in the detector exactly.
+     */
+    type: string;
+    /**
+     * Optional per-shape collision settings, honoured by {@link Body#addShape}
+     * and defaulted there. Declared rather than initialized: the body writes
+     * them when the shape joins it, so a class field here would emit an
+     * `undefined` own property on every shape ever built. See `addShape` for
+     * the table of defaults and what each one does.
+     * @see Body#addShape
+     */
+    collisionType?: number;
+    collisionMask?: number;
+    /** `false` takes this shape out of collision without removing it */
+    isActive?: boolean;
+    /** `true` reports contacts but skips the position correction */
+    isTrigger?: boolean;
     /** 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}. */
@@ -69,9 +93,14 @@ export declare class Sphere {
      */
     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.
+     * Smallest {@link AABB3d} containing this sphere. The same instance
+     * every time, refreshed from the current centre and radius on each
+     * call, so it is never stale: as a body shape a sphere gets moved by
+     * whoever owns it — directly through `pos`, not only through
+     * {@link Sphere.setShape} — and a cache that only refreshed on
+     * `setShape` reported the position the sphere was first asked about
+     * for the rest of its life. Callers must not hold the instance across
+     * a move and expect the old values.
      */
     getBounds(): AABB3d;
     /**

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

@@ -1 +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;IAWf;;;;;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;IAwBnB;;OAEG;IACH,KAAK;IASL;;;;;OAKG;IACH,KAAK;CAGL;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,6FAWrB,CAAC"}
+{"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;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,MAAM;IAClB;;;;;OAKG;IACH,IAAI,SAAY;IAEhB;;;;;;;OAOG;IACK,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IAC/B,oEAAoE;IAC5D,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC3B,gEAAgE;IACxD,SAAS,CAAC,EAAE,OAAO,CAAC;IAE5B,mFAAmF;IACnF,GAAG,EAAE,QAAQ,CAAC;IAEd,iIAAiI;IACjI,MAAM,EAAE,MAAM,CAAC;IAYf;;;;;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;IAMxD;;;;;;;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;;;;;;;;;OASG;IACH,SAAS,IAAI,MAAM;IAwBnB;;OAEG;IACH,KAAK;IAML;;;;;OAKG;IACH,KAAK;CAGL;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,6FAWrB,CAAC"}