/* ============================================================================
physics-engine.js — reusable 2D physics core (built on Matter.js)
A small, project-agnostic wrapper around Matter.js that gives games, tools
and simulations a stable API without touching Matter internals:
- plain-data body / constraint descriptors (JSON-friendly, serializable)
- fixed-timestep simulation with an accumulator (stable at any refresh
rate, speed multiplier, spiral-of-death protection)
- optional body sleeping for large resting scenes
- constraint management with lifecycle cleanup: soft constraints
(stiffness < 0.99) are Hooke-force springs (F = -k*C - c*vn,
applied once per substep, no Matter constraint built), rigid
ones (stiffness >= 0.99) keep the iterative Matter solve
- physics-based dragging (throwable bodies), picking, property setters
that keep the engine as the single source of truth
It knows nothing about any particular app: no DOM, no rendering, no file
format. Rendering and persistence belong to the host project.
Usage (browser):
Matter.js must be available as a global `Matter` (script tag) or injected:
PhysicsEngine.setMatter(Matter) / new PhysicsEngine({ matter })
In Node tests: globalThis.Matter = require('matter-js') before importing.
Version: 1.13.0 (exported as VERSION / PhysicsEngine.VERSION)
1.0.0 — extracted from MotionLab as a project-agnostic core
1.1.0 — substeps anti-tunnelling (setSubsteps)
1.2.0 — spatial queries (queryRegion / raycast), impulse helpers
(addVelocity / applyRadialImpulse), allocation-free pick()
1.3.0 — seeded RNG (seed option, random / randomRange / randomInt /
choice / shuffle, setSeed; RNG state rides along in snapshots)
1.4.0 — named bodies (name / renameBody / getBodyByName), pairwise
gravitation, fluid regions (buoyancy + drag), a Formulas
library of pure physics helpers, and stability hardening
(descriptor validation, non-finite setter guards, maxSpeed)
1.5.0 — magnetism (descriptor `magnet`: signed pole strength; poles
attract/repel each other and pull unmagnetised "iron" bodies,
range-limited, momentum-conserving), wind regions (addWind —
a target-velocity field, the gaseous sibling of fluids), and
a faster pairwise-force pass (positions/masses hoisted into
typed arrays once per step, one unified pass for gravitation
+ magnetism, uniform-grid range culling for magnet pairs)
1.5.1 — magnetism fix: a pole pair involving a static magnet is no
longer skipped when the dynamic pole was added first (the
pair-dedup now only applies when the earlier pass can run)
1.6.0 — performance pass, no behaviour change: the pairwise-force
pass reuses grow-only typed buffers, a cached body->index
map and magnet list, and a numeric-keyed pooled grid
(zero allocation per fixed step); gravitation is split into
a symmetric dynamic–dynamic loop plus a one-way
dynamic–static loop, so static–static pairs are never
evaluated (static-heavy worlds: pair pass ~40% faster);
fluids skip sleeping bodies (Matter discards their forces
anyway) and reuse a scratch force vector;
constraintSegments pools its segment records;
new allocation-free forEachFluid / forEachWind iterators
1.7.0 — machinery: revolute hinges (addHinge — pin two bodies, or a
body to a fixed mount, at a shared point) with optional
motors (target relative angular velocity in rad/step,
acceleration-capped, reaction split by inverse inertia);
hinges ride snapshots/load, are cleaned up with their
bodies, and expose hingeAnchors() for rendering/picking
1.7.1 — solver: default constraintIterations raised 2 -> 4 (option
`constraintIterations` overrides). Simultaneous rigid
constraints (hinge clusters, triangulated crosses) left
multi-pixel anchor errors at 2 iterations (measured on a
ferris wheel: hub drift 28px, cross error 5.6°); at 4 the
same machine holds its hub exactly and its cross angle
1.12.0 — the self-developed Native backend lands (MotionLab 1.41):
BACKENDS' native entry moves from planned to experimental
and PhysicsEngine.create({ backend: 'native' }) now
constructs it (a from-scratch impulse solver in
native-engine.js — no physics library inside — honouring
this API's full surface: bodies, constraints, hinges with
motors, fluids, winds, magnetism, gravitation, sleeping,
snapshots, queries, seeded RNG). Matter stays the default
and the reference behaviour; native is opt-in and labelled
experimental while its feel is validated on real scenes.
The 'native' backend is formally named Impulse from 1.12.10
(id unchanged for compatibility; internal codename
Native67). It also graduates from experimental to
stable with the solver-stability work below.
1.13.0 — observability surface (MotionLab 1.61): both backends
expose the same stats getter (steps, bodies, sleeping,
contacts, plus Impulse-only cumulative counters:
wake-touch gate firings, pre-wake firings, wakes,
sleeps, spawns) and, on Impulse, an onEvent stream
(impact / sleep / wake / spawn). The Matter facade
reports null for the solver-internal fields — it has
no equivalent hooks. Counters are never serialized;
resetStats() zeroes them. No solver numerics change.
1.12.12 — native wake-touch gating (MotionLab 1.60): 1.59's
live verification caught what its Node protocol had
missed — a FAST, chunked drag (pointer targets jumping
~80 px at a time, as real pointer events do) still
detonated the pyramid on the first attempt, while a
second identical attempt behaved: unreliable. Cause:
the frozen first-touch solve that 1.59 deliberately
kept is an amplifier at speed. A contact created
against a sleeping body is solved as if that body
were a wall; for gentle touches that hands a touching
chain its clean transfer (the cradle's drift-45
behaviour depends on it — disabling sleep measures
235), but a wrecking ball arriving at 34 px/step
transfers through the slept rows at 58 -> 132 ->
210 px/step, each row waking the next through a
frozen contact. Pre-wake cannot see this wave coming:
resting rows have zero penetration, so no contact
exists to pre-wake from until the wave arrives. Fix:
contacts record wakeTouch (exactly one body asleep
at creation); on the solve's first iteration, a
wake-touch whose approach speed exceeds 12 px/step
is re-based on the honest live effective mass.
Gentle wake-touches keep the frozen transfer.
Measured: chunked-drag pyramid peak box speed
210 -> 42.7 (the Matter backend under the same
protocol measures 87 — the drag itself is violent;
the solver no longer multiplies it); cradle drift
unchanged at 45; slow press 10.1, rolling impact
10.1, bowling replay peak pin 3.61 — all unchanged.
1.12.11 — native wake timing (MotionLab 1.59): pressing a
dragged body into a SLEPT stack detonated it (boxes
leaving at 50-266 px/step, one reaching the stage top).
Contacts are created in _collide BEFORE the wake-on-
impact pass, so a contact against a sleeping body
carries that body's zero inverse mass baked into its
effective mass (measured imN 8.49 vs the true ~1.66);
when the wake pass then wakes the body mid-substep,
the oversized impulses pump energy iteration after
iteration, and the stack explodes chain-by-chain as
each disturbed body wakes the next through a frozen
contact. Fix: a pre-wake pass — a sleeper that last
substep's contacts say is still being pressed by a
moving body wakes BEFORE _collide, so sustained
contacts are created with honest masses. First-touch
contacts deliberately keep the historical one-substep
frozen solve: it is what hands a Newton's-cradle
chain its clean equal-mass transfer (recomputing the
masses at the wake instead measured cradle drift
45 -> 132; a drag-servo contact cap measured WORSE,
peak box 181 — a slow hydraulic press maximises
penetration build-up). Re-test on the Pyramid preset:
servo-press peak box speed 34.1 -> 10.1, no box rises
above the tower's own top row; cradle drift unchanged
at 45; bowling replay unchanged.
1.12.10 — native solver stability (MotionLab 1.58): touching
chains (Newton's cradle) no longer drift apart over
time. Contact solving is now symmetric (the sweep
direction alternates every iteration, cancelling the
one-way bias), iterations 10 -> 30, and restitution
answers the approach velocity sampled BEFORE the
warm-start pre-application (between 1.12.9's
chain-starving collide-time sample and the live vn
that launched wedged pins). Cradle middle-body drift
184 -> 45 px, flat out to 3600 steps; bowling-wedge
peak pin speed 2.46 -> 0.87; an e=0.8 drop still
rebounds to exactly e^2*h.
1.12.9 — native solver: no more launched light bodies (MotionLab
1.57). Restitution now answers the approach velocity
captured at contact creation (before warm-start impulses
and solver iterations can inflate the contact-point
velocity — a wedged pin showed vn = -61 from a 2.4
px/step tap and left at 19.6 px/step), and the Baumgarte
penetration bias is capped at 4 px/step (deep overlap is
resolved by the positional correction over a few steps
instead). Peak pin speed in the repro: 19.6 -> 2.5;
an honest restitution-0.8 drop still rebounds to e^2*h.
1.12.8 — emitters (MotionLab 1.56): addEmitter registers a point
spawner { x, y, angle, rate, kind, size, speed, cap,
enabled } that creates a body every round(60/rate) fixed
steps at the END of the step, so spawning is a pure
function of the step index (the sim clock rides
snapshots, therefore recordings and replays spawn
identically). Spawned bodies carry an `emitter` tag in
their descriptor (round-trips through describeBody /
snapshots); at the cap the oldest spawned body is
removed to make room. Both backends.
1.12.7 — noSleep descriptor flag (MotionLab 1.55): a body created
with noSleep: true never enters sleep on either backend
(Matter: sleepThreshold Infinity; Native: the sleep pass
skips it). For slow-instability bodies (dominoes), whose
leaning motion decays under the sleep threshold mid-push.
1.12.6 — snapshot fidelity (MotionLab 1.54): describeBody now
carries angular velocity (va) and the sleeping flag, and
addBody restores both (both backends) — previously a
snapshot restored mid-motion silently zeroed spin and woke
every sleeper, so a replay recorded after the scene had
warmed up diverged from its own recording. Solver behaviour
otherwise unchanged.
1.12.5 — performance pass (MotionLab 1.51), no behaviour change:
the orphan-sleeper probe (both backends) finds candidate
pairs through a uniform grid instead of O(sleepers x bodies)
scans — it measured ~31% of all step time at ~800 bodies;
Native: numeric contact-sort and warm-start keys (were
template strings built per contact per substep), shared
solver scratch vectors, support marking by per-substep
stamp, motor-driven set resolved once per substep, and the
post-solve shape sync skips sleeping bodies.
1.12.4 — API parity (MotionLab 1.47): Native gains wake /
setMaxSpeed / maxSpeed / clearFluids / clearWinds /
dragBody, and `dragging` is boolean on both backends
(it returned the body on Native). No solver changes.
1.12.3 — orphan-sleeper wake (MotionLab 1.44, BOTH backends):
a probe every 15 fixed steps wakes sleeping bodies whose
support chain is gone (deleted/dragged-away support left
towers hovering in mid-air forever); support = touching
chain to a non-sleeping body (statics count — Matter
marks statics sleeping too), constraint/hinge attachment,
or fluid overlap; zero/disabled gravity opts out.
1.12.2 — native robustness (MotionLab 1.43): reference-face
clipping no longer crashes on exactly-aligned stacks (the
796-body stress scene froze mid-run); sleeping uses a
smoothed motion metric with remembered support (dense
piles: 72 -> 163 of 705 asleep at 15 s); warm-start
impulses apply on the first substep only (they persist in
the velocities — re-applying them leaked energy scaled by
the substep count).
1.12.1 — native host-contract fix (MotionLab 1.42): native circle
bodies now expose a vertices polygon approximation (10–25
sides, mirroring Matter circle bodies). Hosts draw every
body through body.vertices — 1.12.0 shipped circles with
vertices = [] and the MotionLab canvas rendered only the
grid while the physics ran. No solver behaviour changes.
1.11.0 — backend interface formalised: a BACKENDS registry (also
PhysicsEngine.BACKENDS) names every solver backend behind
this API, PhysicsEngine.create({ backend }) constructs
through the registry, and every instance reports its
backendId. The Matter.js backend is the only active one;
a self-developed Native backend is registered as planned
(MotionLab 1.41) — hosts code against this API only and
can render engine pickers from the registry.
1.10.0 — buoyancy obeys its preconditions: the displaced volume
is the body's TRUE submerged area (part polygons clipped
to the fluid rectangle — circles and rotated bodies get
their real submerged fraction, and horizontal straddling
counts), the force is applied at the centre of buoyancy
(the submerged centroid — tilted floaters right or capsize
physically), and the underside-seal condition is checked:
if the body's underside is sealed against another body
(flush on the tank floor), fluid pressure cannot act
upward there, so buoyancy fades with the sealed fraction
and a submerged top face is pressed down by the fluid
column above it (the bridge-pier case). Fluid drag/flow
now scale with the same true submerged fraction
1.9.0 — module coupling: fluid drag also bleeds ANGULAR velocity
(a spinning bar or paddle in water now feels the water;
before, drag only touched linear velocity at the centre of
mass, so rotors whose centre barely moved felt nothing);
fluids gain a flow velocity (vx, vy — drag blends toward
the flow instead of toward zero); wind regions overlapping
a fluid drive a surface current in it (40% of the
gust-adjusted wind velocity, scaled by horizontal overlap)
— read it back with fluidFlow(id); fluid drag/flow no
longer switch off in zero-gravity worlds (only buoyancy
needs gravity)
1.8.0 — wind gusts: wind regions gain `gust` (0..0.9) and
`gustPeriod` (seconds, 2..30); the effective wind velocity
oscillates as (1 + gust * sin(2π * t / period)) on a
simulated-time clock that rides snapshots (simMs), so all
regions breathe together like weather and a loaded world
keeps its gust phase. Steady wind is unchanged (gust = 0)
========================================================================== */
import { NativeEngine } from './native-engine.js';
let _M = null;
function matter() {
if (_M) return _M;
if (typeof globalThis !== 'undefined' && globalThis.Matter) return globalThis.Matter;
if (typeof window !== 'undefined' && window.Matter) return window.Matter;
throw new Error('physics-engine: Matter.js not found. Load matter.min.js first or call PhysicsEngine.setMatter().');
}
/** Body-local offset -> world coordinates (accounts for body rotation). */
/** Hooke-spring scale (1.13.3): twin of SPRING_K / SPRING_DAMP_F in
* native-engine.js — soft constraints on BOTH backends are the same
* Hooke-force model (k = stiffness * SPRING_K, c from damping scaled
* to the pair's reduced mass), so a spring scene behaves the same
* whichever backend simulates it. */
const SPRING_K = 0.22;
const SPRING_DAMP_F = 1;
function localToWorld(M, body, pt) {
const c = Math.cos(body.angle), s = Math.sin(body.angle);
return { x: body.position.x + pt.x * c - pt.y * s, y: body.position.y + pt.x * s + pt.y * c };
}
/** Allocation-free twin of localToWorld: writes the world point into `out`. */
function localToWorldInto(M, body, pt, out) {
const c = Math.cos(body.angle), s = Math.sin(body.angle);
out.x = body.position.x + pt.x * c - pt.y * s;
out.y = body.position.y + pt.x * s + pt.y * c;
return out;
}
const num = (v, fb) => (Number.isFinite(Number(v)) ? Number(v) : fb);
export const BODY_KINDS = ['circle', 'rect', 'polygon'];
/** PhysicsEngine core version — the single source of truth for the core. */
export const VERSION = '1.13.3';
/* ============================================================================
Backends (1.11.0) — the solver behind this API is pluggable.
A "backend" is whatever implements this class's public surface:
body / constraint / hinge management, fluid / wind / magnet regions,
fixed-timestep advance(), snapshots, spatial queries and the seeded
RNG. Hosts must code against that API only — never against a
backend's internals — so backends can be swapped without host
changes. This registry is the single source of truth: hosts render
engine pickers from it, and PhysicsEngine.create({ backend })
constructs through it. Statuses: 'active' backends are the
reference behaviour; 'experimental' backends construct normally
but hosts should label them as such; a 'planned' entry is a
published intention, not a usable engine — create() says so
plainly instead of silently falling back.
========================================================================== */
export const BACKENDS = [
{
id: 'matter', name: 'Matter.js', status: 'active', since: '1.0.0',
summary: 'The original solver: Matter.js 0.20 rigid-body engine behind the PhysicsEngine API, plus the engine-level force models (gravitation, buoyancy, magnetism, wind).',
},
{
id: 'native', name: 'Impulse', status: 'stable', since: '1.12.0',
summary: 'A self-developed solver written for this API (sequential impulses, warm starting, sleeping, SAT + face-clipping contacts). Experimental since 1.12.0: covers the full API surface, validated by its own behaviour suite; Matter remains the default.',
},
];
/* ============================================================================
Formulas — pure physics helpers (no engine state).
Units follow the engine's world: distances in px, velocities in px/step,
mass = density × area. `gravity` parameters are accelerations in
px/step² (a falling body under engine gravity y=1 gains ≈0.28 px/step
per step; measure your world with a test drop if you need it exactly).
========================================================================== */
export const Formulas = {
/** Kinetic energy of translation: ½·m·|v|² */
kineticEnergy: (mass, vx, vy) => 0.5 * mass * (vx * vx + vy * vy),
/** Rotational kinetic energy: ½·I·ω² */
rotationalEnergy: (inertia, angularVelocity) => 0.5 * inertia * angularVelocity * angularVelocity,
/** Linear momentum vector: m·v */
momentum: (mass, vx, vy) => ({ x: mass * vx, y: mass * vy }),
/** Impulse needed to change a body's velocity by (dvx, dvy): m·Δv */
impulseForDeltaV: (mass, dvx, dvy) => ({ x: mass * dvx, y: mass * dvy }),
/** Newton's law of gravitation — force magnitude: G·m1·m2 / r² */
gravitationalForce: (G, m1, m2, distance) => (distance > 0 ? (G * m1 * m2) / (distance * distance) : 0),
/** Magnetic pole interaction — signed force scalar: K·s1·s2 / (d² + ε²).
* Positive = repulsion (like poles), negative = attraction. This is the
* exact scalar the engine's magnetism pass applies along the pair axis. */
magneticForce: (K, s1, s2, distSq, softening) => (K * s1 * s2) / (distSq + Math.max(0, softening)),
/** Circular-orbit speed around a central mass: √(G·M / r) */
orbitVelocity: (G, centralMass, radius) => Math.sqrt((G * centralMass) / Math.max(1e-9, radius)),
/** Escape velocity from a central mass at radius r: √(2·G·M / r) */
escapeVelocity: (G, centralMass, radius) => Math.sqrt((2 * G * centralMass) / Math.max(1e-9, radius)),
/** Hooke's law — spring force magnitude: k·x (direction opposes stretch) */
springForce: (stiffness, displacement) => stiffness * displacement,
/** Elastic potential energy stored in a spring: ½·k·x² */
springEnergy: (stiffness, displacement) => 0.5 * stiffness * displacement * displacement,
/** Small-angle pendulum period: 2π·√(L / g) */
pendulumPeriod: (length, gravity) => 2 * Math.PI * Math.sqrt(length / Math.max(1e-9, gravity)),
/** Archimedes (2D) — buoyant force: ρ_fluid · submergedArea · g */
buoyancyForce: (fluidDensity, submergedArea, gravity) => fluidDensity * submergedArea * gravity,
/** Quadratic drag force magnitude: c·v² (apply opposite the motion) */
dragForce: (coefficient, speed) => coefficient * speed * speed,
/** Maximum static friction force: μ·N */
frictionForce: (mu, normalForce) => mu * normalForce,
/** Projectile range on flat ground: v²·sin(2θ) / g */
projectileRange: (speed, angleRad, gravity) => (speed * speed * Math.sin(2 * angleRad)) / Math.max(1e-9, gravity),
/** Centripetal acceleration for circular motion: v² / r */
centripetalAcceleration: (speed, radius) => (speed * speed) / Math.max(1e-9, radius),
/** Gravitational potential energy relative to a reference: m·g·h */
potentialEnergy: (mass, gravity, height) => mass * gravity * height,
};
export class PhysicsEngine {
/** Core version; same value as the module-level VERSION export. */
static get VERSION() { return VERSION; }
/** The backend registry (also exported standalone as `BACKENDS`). */
static get BACKENDS() { return BACKENDS; }
/**
* Construct an engine through the backend registry (1.11.0).
* `opts.backend` names a BACKENDS entry ('matter' when omitted).
* 'active' and 'experimental' backends construct normally (native
* since 1.12.0); a registered-but-planned backend — and an unknown
* id — throws a plain error: silently falling back to another
* solver would change simulation results without telling the host.
*/
static create(opts = {}) {
const backend = opts.backend || 'matter';
if (backend === 'matter') return new PhysicsEngine(opts);
if (backend === 'native') return new NativeEngine(opts);
const known = BACKENDS.find((b) => b.id === backend);
if (known) {
throw new Error(`PhysicsEngine: backend "${backend}" (${known.name}) is registered but not available in ${VERSION} — status: ${known.status}`);
}
throw new Error(`PhysicsEngine: unknown backend "${backend}" (known: ${BACKENDS.map((b) => b.id).join(', ')})`);
}
/** The pure-formula library (also exported standalone as `Formulas`). */
static get Formulas() { return Formulas; }
/**
* Check a body descriptor without creating anything. Returns a list of
* human-readable problems (empty = valid). addBody() itself stays lenient
* (it coerces bad values to defaults); use this in tools/importers that
* would rather reject bad data than silently fix it.
*/
static validateDescriptor(d) {
const problems = [];
if (!d || typeof d !== 'object') return ['descriptor is not an object'];
if (d.kind !== undefined && !BODY_KINDS.includes(d.kind)) problems.push(`unknown kind: ${String(d.kind)}`);
for (const k of ['x', 'y', 'angle', 'density', 'friction', 'frictionAir', 'restitution']) {
if (d[k] !== undefined && !Number.isFinite(Number(d[k]))) problems.push(`${k} is not a finite number`);
}
const kind = d.kind || 'rect';
if (kind === 'circle' || kind === 'polygon') {
if (d.radius !== undefined && !(Number(d.radius) > 0)) problems.push('radius must be > 0');
} else {
if (d.width !== undefined && !(Number(d.width) > 0)) problems.push('width must be > 0');
if (d.height !== undefined && !(Number(d.height) > 0)) problems.push('height must be > 0');
}
if (d.density !== undefined && Number(d.density) < 0) problems.push('density must be >= 0');
if (d.name !== undefined && typeof d.name !== 'string') problems.push('name must be a string');
if (d.magnet !== undefined && !Number.isFinite(Number(d.magnet))) problems.push('magnet is not a finite number');
return problems;
}
/** Inject the Matter.js module explicitly (optional; global fallback works). */
static setMatter(m) { _M = m; }
/**
* @param {object} [opts]
* @param {object} [opts.matter] Matter.js module (defaults to global Matter)
* @param {{x:number,y:number}} [opts.gravity] default {x:0, y:1}
* @param {boolean} [opts.enableSleeping] let resting bodies sleep (big perf
* win for stacks/piles; bodies wake on collision, edits and dragging)
* @param {number} [opts.fixedDt] fixed timestep in ms (default 1000/60)
* @param {number} [opts.maxSteps] max fixed steps per advance() (default 5)
* @param {number} [opts.substeps] physics sub-updates per fixed step
* (default 1). Higher values shrink per-update displacement, which
* prevents fast bodies tunnelling through thin colliders; 2 is a
* good default for scenes with thin statics. User dragging is
* exempt by design (the drag constraint is position-driven).
* @param {number} [opts.seed] seed for the engine's RNG stream (see
* random()). Omit it and a random seed is chosen — read it back
* via `pe.seed` to reproduce the run later.
* @param {number} [opts.maxSpeed] velocity cap in px/step (0 = off).
* A stability guard: no dynamic body ever exceeds it, so a bad
* impulse cannot explode a scene or tunnel through everything.
* @param {{G:number, softening?:number}|number} [opts.gravitation]
* pairwise Newtonian attraction between all bodies (see
* setGravitation). Off by default.
* @param {{K:number, range?:number, softening?:number}|number} [opts.magnetism]
* global magnetism tuning (see setMagnetism). Bodies only feel it
* when their descriptor carries a `magnet` pole strength; the
* default (K = 1.2, range 320) is active out of the box.
*/
constructor(opts = {}) {
const M = opts.matter || matter();
this.M = M;
const { Engine } = M;
this.engine = Engine.create({ enableSleeping: opts.enableSleeping === true });
this.enableSleeping = opts.enableSleeping === true;
// Rigid machines (hinge clusters, rod-locked crosses) need more
// constraint iterations than Matter's default 2, or simultaneous
// rigid constraints leave multi-pixel anchor errors that read as
// hub drift and shape wobble (measured on the ferris wheel: hub
// drift 28px -> 4px, cross error 5.6° -> 1° at 6 iterations).
// 4 is the measured cost/quality balance; overridable per engine.
this.engine.constraintIterations = Math.max(1, Math.round(num(opts.constraintIterations, 4)));
this.world = this.engine.world;
this.backendId = 'matter'; // registry id of the solver behind this instance (1.11.0)
this.fixedDt = num(opts.fixedDt, 1000 / 60);
this.maxSteps = Math.max(1, Math.round(num(opts.maxSteps, 5)));
this.substeps = Math.max(1, Math.min(8, Math.round(num(opts.substeps, 1))));
this._acc = 0;
this._simMs = 0; // simulated ms elapsed — the wind-gust clock (1.8.0); rides snapshots
this._byId = new Map(); // id -> Matter body
this._bodiesCache = null; // cached array view of _byId (invalidated on structure change)
this._locked = new Set(); // bodies with lockRotation — the per-step lock pass touches only these
this._cons = new Map(); // id -> {constraint, desc}
this._hinges = new Map(); // id -> {constraint, desc} revolute joints (1.7.0)
this._seq = 1;
this._drag = null;
this._pickPt = { x: 0, y: 0 }; // scratch point for pick() — no per-call allocation
this._seed = 0; // RNG: the seed the current stream started from
this._rngState = 0; // RNG: mulberry32 state (uint32)
this.setSeed(opts.seed === undefined ? (Math.random() * 4294967296) >>> 0 : opts.seed);
this._maxSpeed = Math.max(0, num(opts.maxSpeed, 0)); // 0 = uncapped
this._gravitation = null; // { G, softening } | null
if (opts.gravitation !== undefined && opts.gravitation !== null) {
const g = typeof opts.gravitation === 'number' ? { G: opts.gravitation } : opts.gravitation;
this.setGravitation(g.G, g);
}
this._fluids = new Map(); // id -> {id, x, y, width, height, density, drag, vx, vy}
this._fluidFlow = new Map(); // id -> last computed effective flow {x, y} (base + wind-driven, 1.9.0)
this._winds = new Map(); // id -> {id, x, y, width, height, vx, vy, power}
this._emitters = new Map(); // id -> {id, x, y, angle, rate, kind, size, speed, cap, enabled} (1.12.8)
this._magnets = new Set(); // Matter bodies whose descriptor magnet !== 0
this._magnetism = { K: 1.2, range: 320, softening: 900 };
// 1.6.0 perf scratch state: reused across steps so the fixed-step loop
// allocates nothing (pair-force buffers, magnet grid, segment pool).
this._pairBuf = null; // {px, py, ms, axs, ays} grow-only Float64Arrays
this._magnetCache = null; // {list, ordinal} — invalidated whenever _magnets changes
this._indexCache = null; // Map body -> index in _bodies() (structural changes)
this._grid = new Map(); // numeric cell key -> pooled index array
this._gridPool = [];
this._segPool = []; // pooled constraint-segment records
this._forceVec = { x: 0, y: 0 }; // scratch force vector for fluids
if (opts.magnetism !== undefined && opts.magnetism !== null) {
const m = typeof opts.magnetism === 'number' ? { K: opts.magnetism } : opts.magnetism;
this.setMagnetism(m.K, m);
}
this.onChange = null; // () => void, structural changes
this._collisionCbs = [];
if (opts.gravity) this.setGravity(opts.gravity.x, opts.gravity.y, opts.gravity.enabled !== false);
M.Events.on(this.engine, 'collisionStart', (ev) => {
if (!this._collisionCbs.length) return;
for (const pair of ev.pairs) {
for (const cb of this._collisionCbs) cb(pair.bodyA, pair.bodyB, pair);
}
});
}
/* ---------------- gravity ---------------- */
setGravity(x, y, enabled = true) {
this.engine.gravity.x = enabled ? num(x, 0) : 0;
this.engine.gravity.y = enabled ? num(y, 0) : 0;
}
get gravity() { return this.engine.gravity; }
/* ---------------- bodies ---------------- */
/**
* Create a body from a plain descriptor and add it to the world.
* desc: { id?, kind:'circle'|'rect'|'polygon', x, y, angle?(rad), width,
* height, radius, sides, density, friction, frictionAir, restitution,
* isStatic, lockRotation, vx, vy, label, name, magnet, userData }
* `magnet` is a signed pole strength in [-100, 100] (0 = not magnetic);
* see the magnetism section for how poles interact.
* `name` is a developer-facing identifier (see getBodyByName); it is
* independent of Matter's `label`. Returns the Matter body. The
* (normalized) descriptor is kept on the body and can be read back
* with describeBody().
*/
addBody(partial = {}) {
const M = this.M;
const { Bodies, Body, Composite } = M;
const kind = BODY_KINDS.includes(partial.kind) ? partial.kind : 'rect';
const desc = {
id: typeof partial.id === 'string' && partial.id ? partial.id : `body-${this._seq++}`,
kind,
x: num(partial.x, 0), y: num(partial.y, 0),
angle: num(partial.angle, 0),
width: num(partial.width, 64), height: num(partial.height, 64),
radius: num(partial.radius, 30),
sides: Math.max(3, Math.round(num(partial.sides, 6))),
density: num(partial.density, 0.001),
friction: num(partial.friction, 0.3),
frictionAir: num(partial.frictionAir, 0.01),
restitution: num(partial.restitution, 0.2),
isStatic: partial.isStatic === true,
lockRotation: partial.lockRotation === true,
magnet: Math.min(100, Math.max(-100, num(partial.magnet, 0))),
vx: num(partial.vx, 0), vy: num(partial.vy, 0),
va: num(partial.va, 0),
sleeping: partial.sleeping === true,
// 1.13.2: sleep progress rides the descriptor so a snapshot
// round-trip restores it (see the addBody tail below).
sleepCounter: Math.max(0, Math.floor(num(partial.sleepCounter, 0))),
// 1.13.2: Matter's constraint warm-start impulse (see the
// addBody tail). Null for fresh bodies; snapshots carry it.
constraintImpulse: (partial.constraintImpulse && typeof partial.constraintImpulse === 'object')
? { x: num(partial.constraintImpulse.x, 0), y: num(partial.constraintImpulse.y, 0), angle: num(partial.constraintImpulse.angle, 0) }
: null,
noSleep: partial.noSleep === true,
// Emitter tag (1.12.8): id of the emitter that spawned this body
// ('' for hand-placed bodies). Rides describeBody/snapshots so an
// emitter's alive-count survives a snapshot round-trip.
emitter: typeof partial.emitter === 'string' ? partial.emitter : '',
label: typeof partial.label === 'string' ? partial.label : '',
name: typeof partial.name === 'string' ? partial.name : '',
userData: partial.userData && typeof partial.userData === 'object' ? partial.userData : {},
};
const opts = {
angle: desc.angle, density: desc.density, friction: desc.friction,
frictionAir: desc.frictionAir, restitution: desc.restitution,
isStatic: desc.isStatic, label: desc.label || kind,
...(desc.lockRotation ? { inertia: Infinity } : {}),
// noSleep (1.12.7): never enter sleep — for bodies whose whole job
// is a slow instability (dominoes): Matter's motion threshold put
// a leaning domino to sleep mid-push and froze the cascade.
...(desc.noSleep ? { sleepThreshold: Infinity } : {}),
};
let body;
if (kind === 'circle') body = Bodies.circle(desc.x, desc.y, desc.radius, opts);
else if (kind === 'polygon') body = Bodies.polygon(desc.x, desc.y, desc.sides, desc.radius, opts);
else body = Bodies.rectangle(desc.x, desc.y, desc.width, desc.height, opts);
body.plugin = body.plugin || {};
body.plugin.pe = { id: desc.id, kind, desc };
if (Number.isFinite(body.inertia)) body._peInertia0 = body.inertia;
// Snapshot fidelity (1.13.2): this engine steps in substeps, so
// a live body's deltaTime is fixedDt/substeps — but a fresh
// body's is Matter's baseDelta, and Body.setVelocity scales by
// deltaTime/baseDelta. Restoring velocity onto a fresh body
// therefore wrote a positionPrev off by the substep ratio (2x
// at substeps 2), and a checkpoint restored mid-motion
// diverged on the very next step (single body, 0.0018 px at
// step 61 after a step-60 restore). Pin deltaTime first so
// the velocity round-trip lands exactly.
if (!desc.isStatic) body.deltaTime = this.fixedDt / this.substeps;
if (!desc.isStatic && (desc.vx || desc.vy)) Body.setVelocity(body, { x: desc.vx, y: desc.vy });
// Snapshot fidelity (1.12.6): spin and sleep state round-trip too.
// Before this, a snapshot restored mid-motion silently zeroed both —
// a replay recorded after the scene had warmed up diverged from its
// own recording (Newton's cradle: >14 px after 21 s).
if (!desc.isStatic && Number.isFinite(desc.va) && desc.va !== 0) Body.setAngularVelocity(body, desc.va);
if (!desc.isStatic && desc.sleeping) this.M.Sleeping.set(body, true);
// Snapshot fidelity (1.13.2): the sleep counter is solver state
// too — a body 118/120 of the way to sleep must not restart
// its count on restore, or sleep timing (and the replay hash)
// shifts. Restored after Sleeping.set so the count survives.
if (!desc.isStatic && Number.isFinite(desc.sleepCounter)) body.sleepCounter = Math.max(0, Math.floor(desc.sleepCounter));
// Snapshot fidelity (1.13.2): Matter's constraint warm-start
// impulse is persistent decaying state — postSolveAll
// multiplies it by _warming instead of zeroing it, and
// preSolveAll applies it at the next substep. A restored body
// with zero impulse misses the warm-start correction and a
// mid-drag checkpoint restore diverges. Restored last, after
// Sleeping.set, so the snapshot value survives verbatim.
const ci = desc.constraintImpulse;
if (ci && typeof ci === 'object') {
body.constraintImpulse.x = num(ci.x, 0);
body.constraintImpulse.y = num(ci.y, 0);
body.constraintImpulse.angle = num(ci.angle, 0);
}
Composite.add(this.world, body);
this._byId.set(desc.id, body);
if (desc.lockRotation) this._locked.add(body);
if (desc.magnet !== 0) { this._magnets.add(body); this._magnetCache = null; }
this._emitChange();
return body;
}
removeBody(id) {
const body = this._byId.get(id);
if (!body) return false;
if (this._drag && this._drag.bodyB === body) this.endDrag();
for (const [cid, rec] of [...this._cons]) {
if (rec.desc.bodyA === id || rec.desc.bodyB === id) this.removeConstraint(cid, false);
}
for (const [hid, rec] of [...this._hinges]) {
if (rec.desc.bodyA === id || rec.desc.bodyB === id) this.removeHinge(hid, false);
}
this.M.Composite.remove(this.world, body);
this._byId.delete(id);
this._locked.delete(body);
if (this._magnets.delete(body)) this._magnetCache = null;
this._emitChange();
return true;
}
clear() {
for (const { constraint } of this._cons.values()) if (constraint) this.M.Composite.remove(this.world, constraint);
this._cons.clear();
for (const { constraint } of this._hinges.values()) this.M.Composite.remove(this.world, constraint);
this._hinges.clear();
for (const b of this._byId.values()) this.M.Composite.remove(this.world, b);
this._byId.clear();
this._locked.clear();
this._magnets.clear();
this._magnetCache = null;
this._fluids.clear();
this._winds.clear();
this._emitters.clear();
this.endDrag();
this._acc = 0;
this._emitChange();
}
bodyById(id) { return this._byId.get(id) || null; }
idOf(body) { return body && body.plugin && body.plugin.pe ? body.plugin.pe.id : null; }
kindOf(body) { return body && body.plugin && body.plugin.pe ? body.plugin.pe.kind : 'rect'; }
userDataOf(body) { return body && body.plugin && body.plugin.pe ? body.plugin.pe.desc.userData : {}; }
/* ---------------- names ----------------
Bodies can carry a developer-facing `name` (descriptor field, kept in
snapshots). Names need NOT be unique — scenes often reuse them
("peg", "ball") — so lookups come in two forms: first match, or all
matches, both in insertion order. */
/** The body's name ('' when unnamed or not an engine body). */
nameOf(body) { return body && body.plugin && body.plugin.pe ? body.plugin.pe.desc.name : ''; }
/** First body with this name, or null. */
getBodyByName(name) {
for (const b of this._byId.values()) if (b.plugin.pe.desc.name === name) return b;
return null;
}
/** All bodies with this name, in insertion order. */
getBodiesByName(name) {
const out = [];
for (const b of this._byId.values()) if (b.plugin.pe.desc.name === name) out.push(b);
return out;
}
/** Rename a body (accepts the body itself or its id). Returns success. */
renameBody(bodyOrId, name) {
const body = typeof bodyOrId === 'string' ? this._byId.get(bodyOrId) : bodyOrId;
if (!body || !body.plugin || !body.plugin.pe) return false;
body.plugin.pe.desc.name = typeof name === 'string' ? name : '';
return true;
}
/** Cached array view (insertion order). Rebuilt only after a structural change;
* internal use — callers must not mutate it. */
_bodies() {
if (!this._bodiesCache) this._bodiesCache = [...this._byId.values()];
return this._bodiesCache;
}
/** All bodies as an array (insertion order). Allocates a copy; use in UI code, not per-frame loops. */
allBodies() { return [...this._bodies()]; }
/** Allocation-free iteration for render loops. */
forEachBody(fn) { for (const b of this._byId.values()) fn(b); }
get count() { return this._byId.size; }
/** Topmost body containing the world point, or null. */
pick(wx, wy) {
const arr = this._bodies();
const pt = this._pickPt;
pt.x = wx; pt.y = wy;
for (let i = arr.length - 1; i >= 0; i--) {
const b = arr[i];
if (this.M.Bounds.contains(b.bounds, pt) &&
this.M.Vertices.contains(b.vertices, pt)) return b;
}
return null;
}
/** All bodies whose AABB intersects the rectangle (x, y, w, h). Broadphase
* only (bounds, not exact shape) — ideal for area effects and culling. */
queryRegion(x, y, w, h) {
const x2 = x + w, y2 = y + h;
const out = [];
for (const b of this._bodies()) {
const bd = b.bounds;
if (bd.min.x <= x2 && bd.max.x >= x && bd.min.y <= y2 && bd.max.y >= y) out.push(b);
}
return out;
}
/**
* Bodies intersected by the segment (x1, y1) -> (x2, y2), nearest first.
* Each hit: { id, body, point, distance } — point is the contact support
* closest to the segment start. Built on Matter's Query.ray.
*/
raycast(x1, y1, x2, y2) {
const hits = this.M.Query.ray(this._bodies(), { x: x1, y: y1 }, { x: x2, y: y2 });
const seen = new Map();
for (const h of hits) {
const body = h.body && h.body.parent ? h.body.parent : h.body;
if (!body || seen.has(body)) continue;
const s = (h.collision && h.collision.supports && h.collision.supports[0]) || body.position;
seen.set(body, {
id: this.idOf(body), body,
point: { x: s.x, y: s.y },
distance: Math.hypot(s.x - x1, s.y - y1),
});
}
return [...seen.values()].sort((a, b) => a.distance - b.distance);
}
/** Live snapshot of one body merged over its stored descriptor. */
describeBody(body) {
const rec = body.plugin.pe;
const d = rec.desc;
return {
...d,
userData: { ...d.userData },
x: body.position.x, y: body.position.y, angle: body.angle,
vx: body.velocity.x, vy: body.velocity.y, va: body.angularVelocity,
sleeping: body.isSleeping === true,
// 1.13.2: sleep progress round-trips with the snapshot, so a
// checkpoint restored mid-count keeps the live sleep timing.
sleepCounter: body.sleepCounter || 0,
// 1.13.2: Matter's constraint warm-start impulse (see
// addBody). Without it, checkpoint restores lose the
// warm-start correction and diverge.
constraintImpulse: { x: body.constraintImpulse.x, y: body.constraintImpulse.y, angle: body.constraintImpulse.angle },
density: body.density, friction: body.friction, frictionAir: body.frictionAir,
restitution: body.restitution, isStatic: body.isStatic,
lockRotation: rec.desc.lockRotation === true,
mass: body.mass,
};
}
/* ---------------- constraints (springs / rods) ---------------- */
/**
* desc: { id?, bodyA (id or null for a fixed world anchor), bodyB (id),
* pointA, pointB (body-local offsets; world coords when bodyA is null),
* stiffness 0..1 (1 = rigid rod), damping, length (null = current distance) }
* Stiffness >= 0.99 creates a Matter constraint (rigid rod); softer
* values are Hooke-force springs with no Matter constraint (1.13.3).
* Returns the Matter constraint for rods, a desc copy for springs.
*/
addConstraint(partial = {}) {
const M = this.M;
const bodyB = this._byId.get(partial.bodyB);
if (!bodyB) return null;
const bodyA = partial.bodyA ? this._byId.get(partial.bodyA) : null;
if (partial.bodyA && !bodyA) return null;
const pt = (p) => ({ x: num(p && p.x, 0), y: num(p && p.y, 0) });
const desc = {
id: typeof partial.id === 'string' && partial.id ? partial.id : `con-${this._seq++}`,
bodyA: bodyA ? this.idOf(bodyA) : null,
bodyB: this.idOf(bodyB),
pointA: pt(partial.pointA), pointB: pt(partial.pointB),
stiffness: Math.min(1, Math.max(0.001, num(partial.stiffness, 0.08))),
damping: Math.min(1, Math.max(0, num(partial.damping, 0.05))),
length: partial.length === null || partial.length === undefined ? null : Math.max(0, num(partial.length, 0)),
};
if (desc.length === null) {
const a = bodyA ? localToWorld(M, bodyA, desc.pointA) : desc.pointA;
const b = localToWorld(M, bodyB, desc.pointB);
desc.length = Math.round(Math.hypot(b.x - a.x, b.y - a.y) * 100) / 100;
}
// Rigid constraints (stiffness >= 0.99) stay Matter constraints;
// soft ones are Hooke-force springs (1.13.3): Matter's iterative
// solve converges them to rigid rods, the same failure the native
// backend had. Springs get no Matter constraint — _applySpringForces
// applies F = -k*x - c*vn per substep instead.
const rigid = desc.stiffness >= 0.99;
const constraint = rigid ? this._makeMatterConstraint(desc) : null;
if (constraint) M.Composite.add(this.world, constraint);
this._cons.set(desc.id, { constraint, desc });
this._emitChange();
return rigid ? constraint : { ...desc, pointA: { ...desc.pointA }, pointB: { ...desc.pointB } };
}
_makeMatterConstraint(desc) {
const bodyA = desc.bodyA ? this._byId.get(desc.bodyA) : null;
const bodyB = this._byId.get(desc.bodyB);
return this.M.Constraint.create({
bodyA: bodyA || undefined, bodyB,
pointA: desc.pointA, pointB: desc.pointB,
stiffness: desc.stiffness, damping: desc.damping, length: desc.length,
});
}
/** Update one stored property of a constraint (spring editor) — twin of
* NativeEngine.setConstraintProp. Crossing the 0.99 stiffness boundary
* swaps the representation (Matter constraint <-> Hooke spring). */
setConstraintProp(id, key, value) {
const rec = this._cons.get(id);
if (!rec) return false;
const desc = rec.desc;
if (key === 'stiffness') desc.stiffness = Math.min(1, Math.max(0.001, num(value, desc.stiffness)));
else if (key === 'damping') desc.damping = Math.min(1, Math.max(0, num(value, desc.damping)));
else if (key === 'length') desc.length = Math.max(0, num(value, desc.length));
else return false;
const wantRigid = desc.stiffness >= 0.99;
const hasRigid = !!rec.constraint;
if (wantRigid && !hasRigid) {
rec.constraint = this._makeMatterConstraint(desc);
this.M.Composite.add(this.world, rec.constraint);
} else if (!wantRigid && hasRigid) {
this.M.Composite.remove(this.world, rec.constraint);
rec.constraint = null;
} else if (hasRigid) {
rec.constraint.stiffness = desc.stiffness;
rec.constraint.damping = desc.damping;
rec.constraint.length = desc.length;
}
this._emitChange();
return true;
}
removeConstraint(id, emit = true) {
const rec = this._cons.get(id);
if (!rec) return false;
if (rec.constraint) this.M.Composite.remove(this.world, rec.constraint);
this._cons.delete(id);
if (emit) this._emitChange();
return true;
}
get constraintCount() { return this._cons.size; }
describeConstraints() { return [...this._cons.values()].map(({ desc }) => ({ ...desc, pointA: { ...desc.pointA }, pointB: { ...desc.pointB } })); }
/** Resolved world-space endpoints for rendering / picking.
* Pass a reusable array to avoid per-frame allocation: it is cleared and
* refilled. Since 1.6.0 the segment records and their endpoint points
* are pooled per instance too, so a steady-state render loop allocates
* nothing here — but callers must consume them immediately and never
* retain a segment across calls. */
constraintSegments(out = []) {
out.length = 0;
let k = 0;
for (const { desc } of this._cons.values()) {
let seg = this._segPool[k];
if (!seg) seg = this._segPool[k] = { id: '', a: { x: 0, y: 0 }, b: { x: 0, y: 0 }, stiffness: 0 };
seg.id = desc.id;
seg.stiffness = desc.stiffness;
const bA = desc.bodyA ? this._byId.get(desc.bodyA) : null;
if (bA) localToWorldInto(this.M, bA, desc.pointA, seg.a);
else { seg.a.x = desc.pointA.x; seg.a.y = desc.pointA.y; }
localToWorldInto(this.M, this._byId.get(desc.bodyB), desc.pointB, seg.b);
out.push(seg);
k++;
}
return out;
}
/* Hooke-force springs (1.13.3): twin of NativeEngine._applySpringForces.
Soft constraints get a velocity kick per substep, scaled by frac
(the substep's fraction of a fixed step), so a fixed step applies
the same total impulse as the native backend's two half-step kicks
— both backends share the spring model, sag, period and damping
behaviour. Sleeping/static bodies are skipped, same as the native
twin. Applied in _subStep (not _stepOnce) so step() callers get
spring forces too, as they did with Matter constraints. */
_applySpringForces(frac) {
const { Body } = this.M;
for (const { desc } of this._cons.values()) {
if (desc.stiffness >= 0.99) continue;
const B = this._byId.get(desc.bodyB);
if (!B) continue;
const A = desc.bodyA ? this._byId.get(desc.bodyA) : null;
const imb = (!B.isStatic && !B.isSleeping) ? B.inverseMass : 0;
const ima = (A && !A.isStatic && !A.isSleeping) ? A.inverseMass : 0;
const invRed = ima + imb;
if (invRed <= 0) continue;
const pa = A ? localToWorld(this.M, A, desc.pointA) : desc.pointA;
const pb = localToWorld(this.M, B, desc.pointB);
const dx = pb.x - pa.x, dy = pb.y - pa.y;
const dist = Math.hypot(dx, dy);
if (dist < 1e-9) continue;
const nx = dx / dist, ny = dy / dist;
const C = dist - desc.length;
const rax = A ? pa.x - A.position.x : 0, ray = A ? pa.y - A.position.y : 0;
const rbx = pb.x - B.position.x, rby = pb.y - B.position.y;
const vax = A ? A.velocity.x - A.angularVelocity * ray : 0;
const vay = A ? A.velocity.y + A.angularVelocity * rax : 0;
const vbx = B.velocity.x - B.angularVelocity * rby;
const vby = B.velocity.y + B.angularVelocity * rbx;
const vn = (vbx - vax) * nx + (vby - vay) * ny;
const k = desc.stiffness * SPRING_K;
const cc = desc.damping * SPRING_DAMP_F * Math.sqrt(k / invRed);
const J = (-k * C - cc * vn) * frac;
if (ima > 0) {
Body.setVelocity(A, { x: A.velocity.x - J * nx * ima, y: A.velocity.y - J * ny * ima });
const iia = A.inverseInertia;
if (Number.isFinite(iia) && iia > 0) Body.setAngularVelocity(A, A.angularVelocity - iia * (rax * J * ny - ray * J * nx));
}
if (imb > 0) {
Body.setVelocity(B, { x: B.velocity.x + J * nx * imb, y: B.velocity.y + J * ny * imb });
const iib = B.inverseInertia;
if (Number.isFinite(iib) && iib > 0) Body.setAngularVelocity(B, B.angularVelocity + iib * (rbx * J * ny - rby * J * nx));
}
}
}
/* ---------------- hinges & motors (revolute joints, 1.7.0) ----------------
A hinge pins two bodies (or one body to a fixed world mount) at a
shared point so they can only ROTATE around it — implemented as a
rigid zero-length constraint, the same mechanism the app already
trusts for pendulum rods. A hinge may carry a MOTOR: a target
relative angular velocity (rad/step, signed) that the step loop
drives toward with a per-step acceleration cap, applying the
reaction to the other body when it is dynamic (momentum-honest,
split by inverse inertia). Motors skip lockRotation bodies, whose
inertia is infinite by design. */
/**
* Add a hinge: { id?, bodyA (id or null = fixed world mount), bodyB,
* pointA, pointB (body-local offsets; world coords when bodyA null),
* motorSpeed = 0 (rad/step, ±0.3), motorPower = 0.0025 (max Δω/step) }.
* Returns a copy of the stored descriptor, or null when bodyB (or a
* named bodyA) does not exist.
*/
addHinge(partial = {}) {
const M = this.M;
const bodyB = this._byId.get(partial.bodyB);
if (!bodyB) return null;
const bodyA = partial.bodyA ? this._byId.get(partial.bodyA) : null;
if (partial.bodyA && !bodyA) return null;
const pt = (p) => ({ x: num(p && p.x, 0), y: num(p && p.y, 0) });
const desc = {
id: typeof partial.id === 'string' && partial.id ? partial.id : `hinge-${this._seq++}`,
bodyA: bodyA ? this.idOf(bodyA) : null,
bodyB: this.idOf(bodyB),
pointA: pt(partial.pointA), pointB: pt(partial.pointB),
motorSpeed: Math.min(0.3, Math.max(-0.3, num(partial.motorSpeed, 0))),
motorPower: Math.min(0.05, Math.max(0.0001, num(partial.motorPower, 0.0025))),
};
const constraint = M.Constraint.create({
bodyA: bodyA || undefined, bodyB,
pointA: desc.pointA, pointB: desc.pointB,
stiffness: 1, damping: 0, length: 0,
});
M.Composite.add(this.world, constraint);
this._hinges.set(desc.id, { constraint, desc });
this._syncHingeCollisionGroups();
this._emitChange();
return { ...desc, pointA: { ...desc.pointA }, pointB: { ...desc.pointB } };
}
/**
* Bodies joined by hinges form a machine: parts of one machine must
* be able to swing THROUGH each other around their pins (two bars
* pinned end-to-end would otherwise jam on their own corners after a
* few degrees). Each connected hinge cluster therefore shares a
* negative Matter collision group — cluster members never collide
* with each other, but collide normally with everything else.
* Recomputed from scratch on every hinge add/remove (hinge counts
* are small); bodies outside any cluster return to group 0.
*/
_syncHingeCollisionGroups() {
const parent = new Map();
const find = (x) => { let r = x; while (parent.get(r) !== r) r = parent.get(r); return r; };
const link = (a, b) => {
if (!parent.has(a)) parent.set(a, a);
if (!parent.has(b)) parent.set(b, b);
const ra = find(a), rb = find(b);
if (ra !== rb) parent.set(ra, rb);
};
for (const { desc } of this._hinges.values()) if (desc.bodyA) link(desc.bodyA, desc.bodyB);
const clusters = new Map();
for (const id of parent.keys()) {
const root = find(id);
if (!clusters.has(root)) clusters.set(root, []);
clusters.get(root).push(id);
}
const grouped = new Set();
let g = 0;
for (const ids of clusters.values()) {
if (ids.length < 2) continue;
g -= 1;
for (const id of ids) {
const body = this._byId.get(id);
if (body) { body.collisionFilter.group = g; grouped.add(id); }
}
}
for (const [id, body] of this._byId) {
if (!grouped.has(id) && body.collisionFilter.group < 0) body.collisionFilter.group = 0;
}
}
removeHinge(id, emit = true) {
const rec = this._hinges.get(id);
if (!rec) return false;
this.M.Composite.remove(this.world, rec.constraint);
this._hinges.delete(id);
this._syncHingeCollisionGroups();
if (emit) this._emitChange();
return true;
}
get hingeCount() { return this._hinges.size; }
hingeById(id) {
const rec = this._hinges.get(id);
return rec ? { ...rec.desc, pointA: { ...rec.desc.pointA }, pointB: { ...rec.desc.pointB } } : null;
}
describeHinges() {
return [...this._hinges.values()].map(({ desc }) => ({ ...desc, pointA: { ...desc.pointA }, pointB: { ...desc.pointB } }));
}
/** Resolved world-space pin points for rendering / picking:
* [{ id, x, y, motorSpeed }]. The two endpoints coincide by
* construction; bodyB's side is reported. */
hingeAnchors() {
const out = [];
for (const { constraint, desc } of this._hinges.values()) {
const p = localToWorld(this.M, constraint.bodyB, desc.pointB);
out.push({ id: desc.id, x: p.x, y: p.y, motorSpeed: desc.motorSpeed });
}
return out;
}
/** Set a hinge's motor target speed (rad/step, clamped to ±0.3).
* Non-finite input is ignored; affected bodies are woken. */
setHingeMotor(id, speed) {
const rec = this._hinges.get(id);
if (!rec || !Number.isFinite(Number(speed))) return false;
rec.desc.motorSpeed = Math.min(0.3, Math.max(-0.3, Number(speed)));
const a = rec.desc.bodyA ? this._byId.get(rec.desc.bodyA) : null;
const b = this._byId.get(rec.desc.bodyB);
if (a) this.wake(a);
if (b) this.wake(b);
return true;
}
_applyMotors() {
const { Body, Sleeping } = this.M;
for (const { desc } of this._hinges.values()) {
const target = desc.motorSpeed;
if (!target) continue;
const b = this._byId.get(desc.bodyB);
if (!b || b.isStatic || !Number.isFinite(b.inertia)) continue;
const a = desc.bodyA ? this._byId.get(desc.bodyA) : null;
const aFree = a && !a.isStatic && Number.isFinite(a.inertia);
const rel = b.angularVelocity - (aFree ? a.angularVelocity : 0);
const err = target - rel;
// A motor-driven body must not doze off: Matter zeroes velocity
// when a body falls asleep, which would fight the drive every
// step. Holding the sleep counter at zero keeps driven bodies
// awake for as long as their motor is on.
b.sleepCounter = 0;
if (aFree) a.sleepCounter = 0;
if (!err) continue;
const step = Math.max(-desc.motorPower, Math.min(desc.motorPower, err));
if (aFree) {
// split the impulse by inverse inertia: Δrel = step exactly,
// with the reaction carried by bodyA (momentum conserved)
const invB = 1 / b.inertia, invA = 1 / a.inertia;
const j = step / (invB + invA);
if (b.isSleeping) Sleeping.set(b, false);
if (a.isSleeping) Sleeping.set(a, false);
Body.setAngularVelocity(b, b.angularVelocity + j * invB);
Body.setAngularVelocity(a, a.angularVelocity - j * invA);
} else {
if (b.isSleeping) Sleeping.set(b, false);
Body.setAngularVelocity(b, b.angularVelocity + step);
}
}
}
/* ---------------- bulk load ---------------- */
/**
* Replace the world from plain data ({ bodies, constraints, fluids?,
* winds?, gravity?, rng? }). Malformed entries (non-objects) are skipped
* rather than crashing the load. Returns how many of each kind were loaded.
*/
load(data = {}) {
this.clear();
let bodies = 0, constraints = 0, fluids = 0, winds = 0;
for (const d of data.bodies || []) { if (d && typeof d === 'object') { this.addBody(d); bodies++; } }
for (const c of data.constraints || []) { if (c && typeof c === 'object' && this.addConstraint(c)) constraints++; }
let hinges = 0;
for (const h of data.hinges || []) { if (h && typeof h === 'object' && this.addHinge(h)) hinges++; }
for (const f of data.fluids || []) { if (f && typeof f === 'object') { this.addFluid(f); fluids++; } }
for (const w of data.winds || []) { if (w && typeof w === 'object') { this.addWind(w); winds++; } }
let emitters = 0;
for (const e of data.emitters || []) { if (e && typeof e === 'object') { this.addEmitter(e); emitters++; } }
if (data.gravity) this.setGravity(data.gravity.x, data.gravity.y, data.gravity.enabled !== false);
if (data.rng && Number.isFinite(data.rng.state)) {
// Restore the RNG stream exactly where the snapshot left it, so a
// loaded world keeps producing the same random sequence.
this._seed = num(data.rng.seed, this._seed) >>> 0;
this._rngState = data.rng.state >>> 0;
}
if (Number.isFinite(data.simMs)) this._simMs = Math.max(0, data.simMs);
// Keep the id sequence ahead of every loaded id (1.12.8): a host
// that loads a snapshot into a FRESH engine and then adds entries
// with auto ids would otherwise reissue an existing id and
// silently overwrite a loaded entry in its map (found via emitter
// spawns after a snapshot load — five spawned balls "vanished"
// into overwritten map slots while the originals kept simulating
// as orphans in the composite).
const bump = (id) => { const m = /-(\d+)$/.exec(id || ''); if (m) this._seq = Math.max(this._seq, Number(m[1]) + 1); };
for (const id of this._byId.keys()) bump(id);
for (const id of this._cons.keys()) bump(id);
for (const id of this._hinges.keys()) bump(id);
for (const id of this._fluids.keys()) bump(id);
for (const id of this._winds.keys()) bump(id);
for (const id of this._emitters.keys()) bump(id);
// 1.13.2: restore the drag constraint a checkpoint captured,
// with its original grab offset and solver-tracked angleB
// (see snapshot()). A snapshot from the native backend
// carries no ox/oy/angleB; fall back to the beginDrag
// computation from the target, the best available.
const dg = data.drag;
if (dg && typeof dg === 'object') {
const db = this._byId.get(dg.id);
if (db && !db.isStatic) {
this.wake(db);
this._attachDrag(db, num(dg.x, db.position.x), num(dg.y, db.position.y),
Number.isFinite(dg.ox) ? dg.ox : num(dg.x, db.position.x) - db.position.x,
Number.isFinite(dg.oy) ? dg.oy : num(dg.y, db.position.y) - db.position.y,
dg.angleB);
}
}
return { bodies, constraints, fluids, winds, hinges, emitters };
}
snapshot() {
return {
bodies: this.allBodies().map((b) => this.describeBody(b)),
constraints: this.describeConstraints(),
hinges: this.describeHinges(),
fluids: this.fluids(),
winds: this.winds(),
emitters: this.emitters(),
rng: { seed: this._seed, state: this._rngState },
simMs: this._simMs,
// 1.13.2: the active drag constraint, if any — target
// (pointA) plus the ORIGINAL grab offset (pointB) and the
// solver-tracked angleB. A checkpoint taken mid-drag must
// restore all three: recomputing pointB or angleB from the
// moved body changes the constraint and the replay diverges
// (Ryan's 1.66 report). Snapshots from <=1.13.1 carry no
// drag field and restore drag-free.
drag: this._drag ? { id: this.idOf(this._drag.bodyB), x: this._drag.pointA.x, y: this._drag.pointA.y, ox: this._drag.pointB.x, oy: this._drag.pointB.y, angleB: this._drag.angleB } : null,
};
}
/* ---------------- simulation ---------------- */
/**
* Advance the simulation by elapsed wall-clock ms at the given speed,
* using fixed timesteps. Returns the number of fixed steps executed.
* Excess time beyond maxSteps is dropped (no spiral of death).
*/
advance(elapsedMs, speed = 1) {
this._acc += Math.min(Math.max(0, num(elapsedMs, 0)), 250) * num(speed, 1);
let steps = 0;
while (this._acc >= this.fixedDt && steps < this.maxSteps) {
this._stepOnce();
this._acc -= this.fixedDt;
steps++;
}
if (steps === this.maxSteps) this._acc = 0;
return steps;
}
/** Run exactly one fixed step (for step-through / tests). */
stepOnce() { this._stepOnce(); }
/** Compatibility helper: advance a single chunk of dt (sub-stepped). */
step(dtMs, speed = 1) {
const total = Math.min(num(dtMs, 0), 50) * num(speed, 1);
const n = Math.max(1, Math.min(8, Math.ceil(total / this.fixedDt)));
const sub = total / n;
for (let i = 0; i < n; i++) this._subStep(sub);
}
_stepOnce() {
this._simMs += this.fixedDt;
// Pairwise forces (gravitation + magnetism) kick velocities once per
// fixed step (not per substep), so their strength does not depend on
// the anti-tunnelling setting.
if (this._gravitation || (this._magnetism.K > 0 && this._magnets.size)) this._applyPairForces();
// Hinge motors likewise drive once per fixed step (1.7.0).
if (this._hinges.size) this._applyMotors();
// Split the fixed step into `substeps` engine updates (anti-tunnelling:
// a body can move at most fixedDt/substeps worth of travel per update).
const n = this.substeps;
const dt = this.fixedDt / n;
for (let i = 0; i < n; i++) this._subStep(dt);
// Orphan-sleeper probe (every 15 fixed steps): a sleeper whose
// support was deleted or dragged away must fall, not hover.
if (this.enableSleeping && Math.round(this._simMs / this.fixedDt) % 15 === 0) this._wakeOrphans();
// Emitters fire at the very end of the fixed step (1.12.8): the new
// body first participates in the NEXT step, and the schedule is a
// pure function of the step index, so replays reproduce it exactly.
if (this._emitters.size) this._runEmitters(Math.round(this._simMs / this.fixedDt));
}
/** Wake sleeping bodies that have lost every support (see the
* NativeEngine twin for the rationale — deleting the bottom box of
* a sleeping tower left the rest hovering forever, in BOTH
* backends). Support = a touching chain (bounds grown 3 px) to a
* non-sleeping body, a constraint/hinge attachment, or a fluid
* region overlap. Zero/disabled gravity opts out. */
_wakeOrphans() {
const g = this.engine.gravity;
if (!g || (g.x === 0 && g.y === 0)) return;
const arr = this._bodies();
const sleepers = arr.filter((b) => b.isSleeping && !b.isStatic);
if (!sleepers.length) return;
const supported = new Set();
for (const rec of this._cons.values()) { if (rec.desc.bodyA) supported.add(rec.desc.bodyA); if (rec.desc.bodyB) supported.add(rec.desc.bodyB); }
for (const rec of this._hinges.values()) { if (rec.desc.bodyA) supported.add(rec.desc.bodyA); if (rec.desc.bodyB) supported.add(rec.desc.bodyB); }
const touch = (A, B) => A.min.x - 3 <= B.max.x && A.max.x + 3 >= B.min.x && A.min.y - 3 <= B.max.y && A.max.y + 3 >= B.min.y;
const fluidBounds = [...this._fluids.values()].map((f) => ({
min: { x: f.x - f.width / 2, y: f.y - f.height / 2 },
max: { x: f.x + f.width / 2, y: f.y + f.height / 2 },
}));
// 1.12.5: candidate pairs come from a uniform grid over grown bounds
// instead of O(sleepers x bodies) scans. At ~800 bodies (nearly all
// asleep at rest) the naive probe measured ~31% of ALL step time.
// Semantics unchanged: the touch predicate and the support rules are
// identical; the grid only prunes pairs that cannot touch (touching
// grown bounds always share a cell both were inserted into).
const CELL = 96;
const cells = new Map();
for (const b of arr) {
const bd = b.bounds;
const x0 = Math.floor((bd.min.x - 3) / CELL), x1 = Math.floor((bd.max.x + 3) / CELL);
const y0 = Math.floor((bd.min.y - 3) / CELL), y1 = Math.floor((bd.max.y + 3) / CELL);
for (let cx = x0; cx <= x1; cx++) for (let cy = y0; cy <= y1; cy++) {
const key = cx * 100000 + cy;
let cell = cells.get(key);
if (!cell) cells.set(key, (cell = []));
cell.push(b);
}
}
const near = (bd, fn) => {
const stamp = (this._probeSeq = (this._probeSeq || 0) + 1);
const x0 = Math.floor((bd.min.x - 3) / CELL), x1 = Math.floor((bd.max.x + 3) / CELL);
const y0 = Math.floor((bd.min.y - 3) / CELL), y1 = Math.floor((bd.max.y + 3) / CELL);
for (let cx = x0; cx <= x1; cx++) for (let cy = y0; cy <= y1; cy++) {
const cell = cells.get(cx * 100000 + cy);
if (!cell) continue;
for (const o of cell) {
if (o._peProbe === stamp) continue;
o._peProbe = stamp;
if (fn(o)) return true;
}
}
return false;
};
const queue = [];
for (const s of sleepers) {
const id = s.plugin.pe.id;
if (supported.has(id)) { queue.push(s); continue; }
let ok = fluidBounds.some((fb) => touch(s.bounds, fb));
if (!ok) ok = near(s.bounds, (o) => o !== s && (o.isStatic || !o.isSleeping) && touch(s.bounds, o.bounds));
if (ok) { supported.add(id); queue.push(s); }
}
for (let i = 0; i < queue.length; i++) {
const cur = queue[i];
near(cur.bounds, (o) => {
if (o.isSleeping && !o.isStatic) {
const id = o.plugin.pe.id;
if (!supported.has(id) && touch(cur.bounds, o.bounds)) { supported.add(id); queue.push(o); }
}
return false;
});
}
for (const s of sleepers) if (!supported.has(s.plugin.pe.id)) this.M.Sleeping.set(s, false);
}
/** Change the anti-tunnelling substep count (1..8). */
setSubsteps(n) { this.substeps = Math.max(1, Math.min(8, Math.round(num(n, 1)))); }
_subStep(dt) {
// Rotation lock is a hard guarantee: zero residual angular velocity each
// step (infinite inertia alone does not stop an explicitly set spin).
// Only bodies in the lock set are visited — O(locked), not O(all bodies).
if (this._locked.size) {
for (const b of this._locked) {
if (!b.isStatic && b.angularVelocity !== 0) this.M.Body.setAngularVelocity(b, 0);
}
}
// Stability guard: cap speeds before the solver sees them, so one bad
// impulse can never poison the world with a runaway body.
if (this._maxSpeed > 0) {
const cap = this._maxSpeed, capSq = cap * cap;
const arr = this._bodies();
for (let i = 0; i < arr.length; i++) {
const b = arr[i];
// sleeping bodies sit far below any sane cap by definition
if (b.isStatic || b.isSleeping) continue;
const v = b.velocity, spSq = v.x * v.x + v.y * v.y;
if (spSq > capSq) {
const s = cap / Math.sqrt(spSq);
this.M.Body.setVelocity(b, { x: v.x * s, y: v.y * s });
}
}
}
// Hooke springs kick right before the update too (1.13.3), scaled
// by the substep fraction — see _applySpringForces.
if (this._cons.size) this._applySpringForces(dt / this.fixedDt);
// Fluid forces must be applied right before the update: Matter clears
// accumulated forces as part of every Engine.update.
if (this._fluids.size) this._applyFluids();
if (this._winds.size) this._applyWinds();
this.M.Engine.update(this.engine, dt);
}
/* ---------------- gravitation (pairwise, Newtonian) ----------------
Every body attracts every other body: a = G · m_other · d / (|d|² + ε²)^1.5
applied as a velocity kick once per fixed step. G is in engine units
(px/step² per unit mass); ε (softening, px²) avoids the singularity
when bodies overlap. Static bodies attract but are not moved; their
effective mass is area × density (Matter reports Infinity for them).
Cost is O(n²) per step — built for tens of bodies, not thousands. */
/** Enable/retune pairwise gravitation. `setGravitation(0)` disables. */
setGravitation(G, opts = {}) {
const g = num(G, 0);
if (!(g > 0)) { this._gravitation = null; return; }
this._gravitation = { G: g, softening: Math.max(0, num(opts.softening, 100)) };
}
/** Current gravitation config ({ G, softening }) or null when off. */
get gravitation() { return this._gravitation ? { ...this._gravitation } : null; }
_gravMass(body) {
if (!body.isStatic) return body.mass;
// Matter sets a static body's density to Infinity; the descriptor
// keeps the density the body was created (or last set) with.
const d = body.plugin && body.plugin.pe ? body.plugin.pe.desc.density : 0;
return body.area * (Number.isFinite(d) ? d : 0);
}
/* ---------------- magnetism (pairwise, range-limited) ----------------
A body's descriptor `magnet` is a signed pole strength in [-100, 100];
the sign is the pole (positive = "N", negative = "S"). Two magnetic
bodies interact with the signed scalar F = K · s1 · s2 / (d² + ε²)
(Formulas.magneticForce): same signs repel, opposite signs attract —
exactly like real poles. A magnetic body also attracts UNMAGNETISED
dynamic bodies ("iron") with an effective strength of IRON = 35,
always attractively. Kicks are force ÷ mass on both sides, so total
momentum is conserved, and light bodies respond more than heavy ones.
Unlike gravitation, magnetism is short-ranged: pairs beyond `range`
(default 320px) feel nothing, which also keeps the cost local. */
/** Retune global magnetism. `setMagnetism(0)` disables it entirely. */
setMagnetism(K, opts = {}) {
const k = num(K, 0);
this._magnetism = {
K: Math.max(0, k),
range: Math.max(10, num(opts.range, this._magnetism ? this._magnetism.range : 320)),
softening: Math.max(0, num(opts.softening, this._magnetism ? this._magnetism.softening : 900)),
};
}
/** Current magnetism config ({ K, range, softening }). */
get magnetism() { return { ...this._magnetism }; }
/** Number of bodies currently carrying a pole strength. */
get magnetCount() { return this._magnets.size; }
/* One unified pairwise pass for gravitation + magnetism (1.5.0).
Positions and effective masses are hoisted into typed arrays once,
instead of property lookups and a _gravMass() call per pair (the
1.4.0 inner loop). Gravitation stays O(n²) (it is infinite-ranged);
magnetism queries a uniform grid (cell = range) so its cost scales
with the number of magnets × local density, not with n².
1.6.0: the typed arrays, the body->index map, the magnet list and the
grid (numeric keys, pooled cell arrays) are all reused across steps —
a fixed step of this pass now allocates nothing. */
_applyPairForces() {
const arr = this._bodies();
const n = arr.length;
if (!n) return;
let buf = this._pairBuf;
if (!buf || buf.px.length < n) {
const cap = Math.max(64, n * 2);
buf = this._pairBuf = {
px: new Float64Array(cap), py: new Float64Array(cap), ms: new Float64Array(cap),
axs: new Float64Array(cap), ays: new Float64Array(cap),
dynIdx: new Int32Array(cap),
dpx: new Float64Array(cap), dpy: new Float64Array(cap), dms: new Float64Array(cap),
spx: new Float64Array(cap), spy: new Float64Array(cap), sms: new Float64Array(cap),
};
}
const { px, py, ms } = buf;
// Hoist positions/masses AND partition dynamic vs static bodies into
// contiguous arrays for the gravitation loops (see below).
let nd = 0, ns = 0;
const { dynIdx, dpx, dpy, dms, spx, spy, sms } = buf;
for (let i = 0; i < n; i++) {
const b = arr[i];
px[i] = b.position.x; py[i] = b.position.y;
ms[i] = this._gravMass(b);
if (b.isStatic) { spx[ns] = px[i]; spy[ns] = py[i]; sms[ns] = ms[i]; ns++; }
else { dynIdx[nd] = i; dpx[nd] = px[i]; dpy[nd] = py[i]; dms[nd] = ms[i]; nd++; }
}
buf.nd = nd; buf.ns = ns;
const { Body, Sleeping } = this.M;
const kick = (i, kx, ky) => {
if (!kx && !ky) return;
const b = arr[i];
if (b.isSleeping) Sleeping.set(b, false);
Body.setVelocity(b, { x: b.velocity.x + kx, y: b.velocity.y + ky });
};
if (this._gravitation) {
const { G, softening } = this._gravitation;
// Symmetric dynamic–dynamic pairs: each unordered pair is evaluated
// ONCE and both accelerations accumulated — half the sqrt work of
// the naive double loop. Static bodies then contribute a one-way
// pass over the dynamics. Splitting the loops this way (instead of
// a static check inside one O(n²) loop) matters: a per-pair branch
// measurably de-optimises the hot loop (~20%), and static–static
// pairs — which can never move anything — are never evaluated.
const axs = buf.axs, ays = buf.ays;
axs.fill(0, 0, nd); ays.fill(0, 0, nd);
for (let a = 0; a < nd; a++) {
for (let b = a + 1; b < nd; b++) {
const dx = dpx[b] - dpx[a], dy = dpy[b] - dpy[a];
const dSq = dx * dx + dy * dy + softening;
const inv = 1 / (dSq * Math.sqrt(dSq));
const sa = G * dms[b] * inv, sb = G * dms[a] * inv;
axs[a] += dx * sa; ays[a] += dy * sa;
axs[b] -= dx * sb; ays[b] -= dy * sb;
}
}
for (let a = 0; a < nd; a++) {
for (let s = 0; s < ns; s++) {
const dx = spx[s] - dpx[a], dy = spy[s] - dpy[a];
const dSq = dx * dx + dy * dy + softening;
const inv = 1 / (dSq * Math.sqrt(dSq));
const sa = G * sms[s] * inv;
axs[a] += dx * sa; ays[a] += dy * sa;
}
}
for (let a = 0; a < nd; a++) kick(dynIdx[a], axs[a], ays[a]);
}
const { K, range, softening } = this._magnetism;
if (K > 0 && this._magnets.size) {
const IRON = 35;
const rangeSq = range * range;
if (!this._indexCache) {
this._indexCache = new Map();
for (let i = 0; i < n; i++) this._indexCache.set(arr[i], i);
}
const indexOf = this._indexCache;
if (!this._magnetCache) {
const list = [...this._magnets];
this._magnetCache = { list, ordinal: new Map(list.map((b, i) => [b, i])) };
}
const { list: magnets, ordinal } = this._magnetCache;
// uniform grid over all bodies (cell = range): neighbours within
// `range` live in the 3×3 block of cells around the source. Keys are
// numeric ((cx+32768)*65536 + (cy+32768)) — no per-step strings.
const grid = this._grid, pool = this._gridPool;
for (const cell of grid.values()) { cell.length = 0; pool.push(cell); }
grid.clear();
const keyOf = (cx, cy) => (cx + 32768) * 65536 + (cy + 32768);
for (let i = 0; i < n; i++) {
const key = keyOf(Math.floor(px[i] / range), Math.floor(py[i] / range));
let cell = grid.get(key);
if (!cell) { cell = pool.pop() || []; grid.set(key, cell); }
cell.push(i);
}
for (const src of magnets) {
const si = indexOf.get(src);
if (si === undefined) continue;
const ss = src.plugin.pe.desc.magnet;
const cx = Math.floor(px[si] / range), cy = Math.floor(py[si] / range);
for (let gx = cx - 1; gx <= cx + 1; gx++) for (let gy = cy - 1; gy <= cy + 1; gy++) {
const cell = grid.get(keyOf(gx, gy));
if (!cell) continue;
for (const ti of cell) {
if (ti === si) continue;
const tgt = arr[ti];
if (tgt.isStatic) continue; // statics exert (as sources) but never move
const tm = tgt.plugin.pe.desc.magnet;
// Magnet–magnet pairs are handled once, from the earlier source —
// but only when that earlier pass can actually process the pair:
// a static target is skipped above, so when the source is static
// the pair must be handled HERE even if the target was added
// earlier (1.5.1 fix: pole pairs no longer depend on add order).
if (tm !== 0 && !src.isStatic && ordinal.get(tgt) < ordinal.get(src)) continue;
const dx = px[ti] - px[si], dy = py[ti] - py[si];
const dSq = dx * dx + dy * dy;
if (dSq > rangeSq || dSq < 1e-9 || ms[ti] <= 0) continue;
const d = Math.sqrt(dSq);
const ux = dx / d, uy = dy / d;
// signed scalar along source->target: >0 pushes apart, <0 pulls together
const f = tm !== 0
? (K * ss * tm) / (dSq + softening)
: -(K * Math.abs(ss) * IRON) / (dSq + softening);
// Per-step kick clamp: at contact distance the raw force is
// huge; an uncapped kick makes stuck bodies buzz against the
// contact solver and can sling overlap pairs across the world.
const MAXK = 0.8;
let kx = ux * f / ms[ti], ky = uy * f / ms[ti];
const km = Math.hypot(kx, ky);
if (km > MAXK) { kx *= MAXK / km; ky *= MAXK / km; }
kick(ti, kx, ky);
if (!src.isStatic && ms[si] > 0) {
let sx = -ux * f / ms[si], sy = -uy * f / ms[si];
const sm = Math.hypot(sx, sy);
if (sm > MAXK) { sx *= MAXK / sm; sy *= MAXK / sm; }
kick(si, sx, sy);
}
}
}
}
}
}
/* ---------------- fluid regions (buoyancy + drag) ----------------
A fluid is an axis-aligned rectangle given by its CENTER (x, y) and
size; the surface is its top edge. A dynamic body overlapping the
region feels an upward force mirroring world gravity, scaled by
(fluid density / body density) × submerged fraction of its bounds —
so a body floats when the submerged fraction balances its density
ratio, exactly Archimedes' principle in 2D. `drag` (0..1) bleeds
velocity per substep while submerged — from 1.9.0 toward the
fluid's flow velocity (its own current plus wind-driven surface
current) instead of toward zero, and it bleeds angular velocity
by the same factor, so spinning/paddling bodies feel the fluid. */
/**
* Add a fluid region: { id?, x, y, width, height, density = 0.0012,
* drag = 0.02, vx = 0, vy = 0 }. (vx, vy) is the fluid's own flow
* (current) in px/step: drag blends submerged bodies toward the
* flow, and bleeds their angular velocity too (1.9.0). Wind regions
* overlapping the fluid add a wind-driven surface current on top —
* see fluidFlow(id) for the effective flow. Returns a copy.
*/
addFluid(partial = {}) {
const rec = {
id: typeof partial.id === 'string' && partial.id ? partial.id : `fluid-${this._seq++}`,
x: num(partial.x, 0), y: num(partial.y, 0),
width: Math.max(1, num(partial.width, 200)), height: Math.max(1, num(partial.height, 200)),
density: Math.max(0, num(partial.density, 0.0012)),
drag: Math.min(1, Math.max(0, num(partial.drag, 0.02))),
vx: Math.min(16, Math.max(-16, num(partial.vx, 0))),
vy: Math.min(16, Math.max(-16, num(partial.vy, 0))),
};
this._fluids.set(rec.id, rec);
return { ...rec };
}
removeFluid(id) { return this._fluids.delete(id); }
clearFluids() { this._fluids.clear(); }
fluidById(id) { const f = this._fluids.get(id); return f ? { ...f } : null; }
/** All fluid regions (copies), in insertion order. */
fluids() { return [...this._fluids.values()].map((f) => ({ ...f })); }
/** Allocation-free iteration over the LIVE fluid records — read-only:
* for render loops and other per-frame readers (1.6.0). */
forEachFluid(fn) { for (const f of this._fluids.values()) fn(f); }
get fluidCount() { return this._fluids.size; }
/** Effective flow of a fluid right now: its own (vx, vy) plus any
* wind-driven surface current (1.9.0). Before the first simulated
* step (or in a zero-wind world) this is just the base flow. */
fluidFlow(id) {
const e = this._fluidFlow.get(id);
if (e) return { x: e.x, y: e.y };
const f = this._fluids.get(id);
return f ? { x: f.vx, y: f.vy } : null;
}
_applyFluids() {
const g = this.engine.gravity;
const scale = g && g.scale !== undefined ? g.scale : 0.001;
// Only buoyancy needs gravity (1.9.0): drag and currents keep
// working in zero-gravity worlds instead of switching off whole.
const hasG = !!(g && (g.x !== 0 || g.y !== 0));
const { Body } = this.M;
const arr = this._bodies();
const fv = this._forceVec;
for (const f of this._fluids.values()) {
const top = f.y - f.height / 2, bottom = f.y + f.height / 2;
const left = f.x - f.width / 2, right = f.x + f.width / 2;
// Effective flow (1.9.0): the fluid's own current plus a
// wind-driven surface current from every overlapping wind
// region — 40% of its gust-adjusted velocity, scaled by power
// and by the horizontal overlap fraction. Derived per step and
// never written back into the record (snapshots stay clean).
let fx = f.vx, fy = f.vy;
if (this._winds.size) {
for (const w of this._winds.values()) {
if (w.power <= 0) continue;
const ox = Math.min(right, w.x + w.width / 2) - Math.max(left, w.x - w.width / 2);
if (ox <= 0) continue;
const oy = Math.min(bottom, w.y + w.height / 2) - Math.max(top, w.y - w.height / 2);
if (oy <= 0) continue;
const v = this._windVel(w);
const k = 0.4 * w.power * (ox / f.width);
fx += v.x * k; fy += v.y * k;
}
}
this._fluidFlow.set(f.id, { x: fx, y: fy });
for (let i = 0; i < arr.length; i++) {
const b = arr[i];
// Sleeping bodies are skipped: Matter discards forces on them
// without integrating, and their (near-zero) velocity makes the
// drag branch a no-op too — the first substep after they wake
// re-applies everything, so behaviour is unchanged.
if (b.isStatic || b.isSleeping) continue;
const bd = b.bounds;
if (bd.max.x < left || bd.min.x > right || bd.max.y < top || bd.min.y > bottom) continue;
// True submerged geometry (1.10.0): clip every part polygon
// to the fluid rectangle — the clipped area is the displaced
// volume (in 2D), its centroid is the centre of buoyancy.
// This replaces the old bounding-box depth fraction, which
// ignored horizontal straddling entirely and over-credited
// rotated shapes.
const sub = this._submerged(b, left, top, right, bottom);
if (!sub) continue;
const frac = Math.min(1, sub.area / Math.max(1, b.area));
if (frac <= 0) continue;
if (hasG) {
const ratio = b.density > 0 ? f.density / b.density : 0;
// Archimedes has a precondition most models skip: fluid
// pressure can only push the body up where fluid can reach
// the underside. A body sealed flush against the tank floor
// (or another body) has no upward pressure there — buoyancy
// fades with the sealed fraction, and if its top face is
// submerged, the fluid column above presses it DOWN
// (the bridge-pier / suction case).
const seal = this._undersideSeal(b, arr, left, right);
fv.x = -g.x * b.mass * ratio * frac * (1 - seal) * scale;
fv.y = -g.y * b.mass * ratio * frac * (1 - seal) * scale;
if (seal > 0) {
const bh = Math.max(1, bd.max.y - bd.min.y);
const topDepth = Math.min(1, Math.max(0, (bd.min.y - top) / bh));
fv.x += g.x * b.mass * ratio * seal * topDepth * scale;
fv.y += g.y * b.mass * ratio * seal * topDepth * scale;
}
// Buoyancy through Matter's own force channel, mirroring
// how gravity itself is applied (force = mass · g · scale),
// so a fully submerged unsealed body with ratio 1 is exactly
// neutrally buoyant — but applied at the CENTRE OF BUOYANCY
// (the submerged centroid), not the centre of mass, which
// is what makes tilted floaters right themselves or capsize.
Body.applyForce(b, sub, fv);
}
if (f.drag > 0) {
const keep = 1 - f.drag * frac;
// Blend toward the effective flow (identical to the old
// bleed-to-zero when the flow is zero), and bleed spin with
// a stronger coefficient: rotational drag acts over the
// body's whole submerged sweep, not just at its centre —
// a rotor whose centre barely moves still feels the water
// through its angular velocity (1.9.0).
Body.setVelocity(b, { x: fx + (b.velocity.x - fx) * keep, y: fy + (b.velocity.y - fy) * keep });
Body.setAngularVelocity(b, b.angularVelocity * Math.max(0, 1 - f.drag * frac * 2.5));
}
}
}
}
/* ---------------- wind regions (target-velocity fields) ----------------
A wind is an axis-aligned rectangle (given by its CENTER and size)
carrying a target velocity (vx, vy) in px/step. A dynamic body
overlapping the region is blended toward that velocity — the gaseous
sibling of fluid drag. The blend rate scales with the bounds-overlap
fraction and with (reference density / body density), so light, airy
bodies are blown around while dense blocks barely stir; `power`
(0..2, default 1) scales the effect per region. */
/**
* Add a wind region: { id?, x, y, width, height, vx = 3, vy = 0,
* power = 1, gust = 0, gustPeriod = 6 }. `gust` (0..0.9) makes the
* wind breathe: the effective velocity is multiplied by
* (1 + gust * sin(2π * simTime / gustPeriod)) — all regions share
* the engine's simulated-time clock, like one weather system.
* Returns the stored record (a copy).
*/
addWind(partial = {}) {
const rec = {
id: typeof partial.id === 'string' && partial.id ? partial.id : `wind-${this._seq++}`,
x: num(partial.x, 0), y: num(partial.y, 0),
width: Math.max(1, num(partial.width, 400)), height: Math.max(1, num(partial.height, 240)),
vx: Math.min(16, Math.max(-16, num(partial.vx, 3))),
vy: Math.min(16, Math.max(-16, num(partial.vy, 0))),
power: Math.min(2, Math.max(0, num(partial.power, 1))),
gust: Math.min(0.9, Math.max(0, num(partial.gust, 0))),
gustPeriod: Math.min(30, Math.max(2, num(partial.gustPeriod, 6))),
};
this._winds.set(rec.id, rec);
return { ...rec };
}
removeWind(id) { return this._winds.delete(id); }
clearWinds() { this._winds.clear(); }
windById(id) { const w = this._winds.get(id); return w ? { ...w } : null; }
/** All wind regions (copies), in insertion order. */
winds() { return [...this._winds.values()].map((w) => ({ ...w })); }
/** Allocation-free iteration over the LIVE wind records — read-only:
* for render loops and other per-frame readers (1.6.0). */
forEachWind(fn) { for (const w of this._winds.values()) fn(w); }
get windCount() { return this._winds.size; }
/* ---------------- emitters (point spawners, 1.12.8) ----------------
An emitter is a fixed point that creates bodies on a schedule:
every round(60 / rate) fixed steps it spawns one body of the
template kind ('circle' | 'rect'), `size` px (circle radius; rect
side = 2·size), launched at `speed` px/step along `angle`. The
schedule derives only from the fixed-step index, and the sim
clock rides snapshots — so a recorded run and its replay spawn
the same bodies at the same steps. Spawned bodies are tagged
(desc.emitter = emitter id); when the alive count reaches `cap`
the OLDEST spawned body is removed to make room, so fountains
run forever without unbounded growth. A global ceiling (1500
bodies) additionally stops spawning in packed worlds. Template
physics is fixed for now: density 0.001, friction 0.3,
frictionAir 0.001, restitution 0.3. */
/**
* Add an emitter: { id?, x, y, angle = 0 (rad), rate = 4 (/s),
* kind = 'circle', size = 16, speed = 8 (px/step), cap = 60,
* enabled = true }. Returns the stored record (a copy).
*/
addEmitter(partial = {}) {
const rec = {
id: typeof partial.id === 'string' && partial.id ? partial.id : `emitter-${this._seq++}`,
x: num(partial.x, 0), y: num(partial.y, 0),
angle: num(partial.angle, 0),
rate: Math.min(30, Math.max(0.2, num(partial.rate, 4))),
kind: partial.kind === 'rect' ? 'rect' : 'circle',
size: Math.min(80, Math.max(6, num(partial.size, 16))),
speed: Math.min(30, Math.max(0, num(partial.speed, 8))),
cap: Math.min(200, Math.max(1, Math.round(num(partial.cap, 60)))),
enabled: partial.enabled !== false,
};
this._emitters.set(rec.id, rec);
this._emitChange();
return { ...rec };
}
removeEmitter(id) {
const ok = this._emitters.delete(id);
if (ok) this._emitChange();
return ok;
}
clearEmitters() { this._emitters.clear(); }
emitterById(id) { const e = this._emitters.get(id); return e ? { ...e } : null; }
/** All emitters (copies), in insertion order. */
emitters() { return [...this._emitters.values()].map((e) => ({ ...e })); }
/** Allocation-free iteration over the LIVE emitter records — read-only. */
forEachEmitter(fn) { for (const e of this._emitters.values()) fn(e); }
get emitterCount() { return this._emitters.size; }
_runEmitters(stepIdx) {
for (const e of this._emitters.values()) {
if (!e.enabled) continue;
const interval = Math.max(1, Math.round(60 / e.rate));
if (stepIdx % interval !== 0) continue;
if (this._byId.size >= 1500) continue;
let alive = 0, oldestId = null;
for (const b of this._bodies()) {
if (b.plugin.pe.desc.emitter === e.id) { alive++; if (oldestId === null) oldestId = b.plugin.pe.id; }
}
if (alive >= e.cap && oldestId !== null) this.removeBody(oldestId);
const c = Math.cos(e.angle), s = Math.sin(e.angle);
const off = e.size + 4;
this.addBody({
kind: e.kind, x: e.x + c * off, y: e.y + s * off,
radius: e.size, width: e.size * 2, height: e.size * 2,
density: 0.001, friction: 0.3, frictionAir: 0.001, restitution: 0.3,
vx: c * e.speed, vy: s * e.speed,
emitter: e.id, label: 'Emitter',
});
}
}
/** Simulated milliseconds elapsed (the gust clock); rides snapshots. */
get simTime() { return this._simMs; }
/** Clip a polygon to the fluid rectangle (Sutherland–Hodgman). */
_clipRect(poly, left, top, right, bottom) {
const clip = (pts, inside, cross) => {
if (!pts.length) return pts;
const out = [];
for (let j = 0; j < pts.length; j++) {
const cur = pts[j], prv = pts[(j + pts.length - 1) % pts.length];
const ci = inside(cur), pi = inside(prv);
if (ci) { if (!pi) out.push(cross(prv, cur)); out.push(cur); }
else if (pi) out.push(cross(prv, cur));
}
return out;
};
const lerp = (a, b, t) => ({ x: a.x + (b.x - a.x) * t, y: a.y + (b.y - a.y) * t });
// Skip the edges the polygon's bounds never cross — most bodies
// in a fluid only cross the surface line, so typically one of
// the four passes actually runs.
let mnx = Infinity, mxx = -Infinity, mny = Infinity, mxy = -Infinity;
for (const p of poly) { if (p.x < mnx) mnx = p.x; if (p.x > mxx) mxx = p.x; if (p.y < mny) mny = p.y; if (p.y > mxy) mxy = p.y; }
if (mnx < left) poly = clip(poly, (p) => p.x >= left, (a, b) => lerp(a, b, (left - a.x) / ((b.x - a.x) || 1e-12)));
if (mxx > right) poly = clip(poly, (p) => p.x <= right, (a, b) => lerp(a, b, (right - a.x) / ((b.x - a.x) || 1e-12)));
if (mny < top) poly = clip(poly, (p) => p.y >= top, (a, b) => lerp(a, b, (top - a.y) / ((b.y - a.y) || 1e-12)));
if (mxy > bottom) poly = clip(poly, (p) => p.y <= bottom, (a, b) => lerp(a, b, (bottom - a.y) / ((b.y - a.y) || 1e-12)));
return poly;
}
/** The body's submerged geometry inside a fluid rectangle: total
* clipped area and its centroid (the centre of buoyancy), or null
* when nothing is submerged. Compound bodies clip per part. */
_submerged(b, left, top, right, bottom) {
const bd = b.bounds;
// Fast path: fully inside — the whole body is the submerged part.
if (bd.min.x >= left && bd.max.x <= right && bd.min.y >= top && bd.max.y <= bottom) {
return { x: b.position.x, y: b.position.y, area: b.area };
}
let area = 0, cx = 0, cy = 0;
const parts = b.parts.length > 1 ? b.parts.slice(1) : b.parts;
for (const part of parts) {
const poly = this._clipRect(part.vertices, left, top, right, bottom);
if (poly.length < 3) continue;
let a2 = 0, sx = 0, sy = 0;
for (let j = 0; j < poly.length; j++) {
const p = poly[j], q = poly[(j + 1) % poly.length];
const cr = p.x * q.y - q.x * p.y;
a2 += cr; sx += (p.x + q.x) * cr; sy += (p.y + q.y) * cr;
}
if (Math.abs(a2) < 1e-9) continue;
const a = a2 / 2, wgt = Math.abs(a);
cx += (sx / (6 * a)) * wgt; cy += (sy / (6 * a)) * wgt; area += wgt;
}
return area > 0 ? { x: cx / area, y: cy / area, area } : null;
}
/** Fraction of the body's underside (within the fluid's horizontal
* span) that is sealed against another body — sampled at three
* points just below the body's bounds. 0 = fluid reaches the whole
* underside, 1 = fully sealed (flush on the floor). */
_undersideSeal(b, arr, left, right) {
const bd = b.bounds;
const x0 = Math.max(bd.min.x, left), x1 = Math.min(bd.max.x, right);
if (x1 <= x0) return 0;
// Cheap gate first: another body's bounds must reach into the
// thin probe slab under the underside before any point test
// runs — a body falling through open water skips the seal check
// entirely (three full Query.point scans per body per substep
// measurably slowed dense fluid scenes).
let candidates = null;
const yTop = bd.max.y - 1, yBot = bd.max.y + 3;
for (let j = 0; j < arr.length; j++) {
const o = arr[j];
if (o === b) continue;
const ob = o.bounds;
if (ob.max.x < x0 || ob.min.x > x1 || ob.max.y < yTop || ob.min.y > yBot) continue;
(candidates || (candidates = [])).push(o);
}
if (!candidates) return 0;
const y = bd.max.y + 1.5;
let blocked = 0;
for (const t of [0.25, 0.5, 0.75]) {
const pt = { x: x0 + (x1 - x0) * t, y };
for (const o of candidates) {
const parts = o.parts.length > 1 ? o.parts.slice(1) : o.parts;
let hit = false;
for (const part of parts) if (this.M.Vertices.contains(part.vertices, pt)) { hit = true; break; }
if (hit) { blocked++; break; }
}
}
return blocked / 3;
}
/** Gust-adjusted wind velocity of a region right now (shared by
* _applyWinds and the wind→fluid surface-current coupling, 1.9.0). */
_windVel(w) {
if (!(w.gust > 0)) return { x: w.vx, y: w.vy };
const m = 1 + w.gust * Math.sin(6.283185307179586 * (this._simMs / (1000 * w.gustPeriod)));
return { x: w.vx * m, y: w.vy * m };
}
_applyWinds() {
const { Body, Sleeping } = this.M;
const arr = this._bodies();
for (const w of this._winds.values()) {
if (w.power <= 0) continue;
const { x: mvx, y: mvy } = this._windVel(w);
const top = w.y - w.height / 2, bottom = w.y + w.height / 2;
const left = w.x - w.width / 2, right = w.x + w.width / 2;
for (let i = 0; i < arr.length; i++) {
const b = arr[i];
if (b.isStatic) continue;
const bd = b.bounds;
const ox = Math.min(bd.max.x, right) - Math.max(bd.min.x, left);
const oy = Math.min(bd.max.y, bottom) - Math.max(bd.min.y, top);
if (ox <= 0 || oy <= 0) continue;
const area = Math.max(1, (bd.max.x - bd.min.x) * (bd.max.y - bd.min.y));
const frac = Math.min(1, (ox * oy) / area);
const densityRatio = 0.0012 / Math.max(0.0001, b.density);
const rate = Math.min(0.5, 0.06 * w.power * frac * densityRatio);
if (rate <= 0.001) continue;
if (b.isSleeping) Sleeping.set(b, false);
Body.setVelocity(b, {
x: b.velocity.x + (mvx - b.velocity.x) * rate,
y: b.velocity.y + (mvy - b.velocity.y) * rate,
});
}
}
}
/* ---------------- measurements (live Formulas over world state) -------- */
/** Kinetic energy of one body (translation + rotation). */
bodyKineticEnergy(body) {
if (!body) return 0;
return Formulas.kineticEnergy(body.mass, body.velocity.x, body.velocity.y)
+ (Number.isFinite(body.inertia) ? Formulas.rotationalEnergy(body.inertia, body.angularVelocity) : 0);
}
/** Total kinetic energy of all dynamic bodies. */
totalKineticEnergy() {
let e = 0;
for (const b of this._byId.values()) if (!b.isStatic) e += this.bodyKineticEnergy(b);
return e;
}
/** Momentum vector of one body. */
bodyMomentum(body) { return body ? Formulas.momentum(body.mass, body.velocity.x, body.velocity.y) : { x: 0, y: 0 }; }
/** Total momentum of all dynamic bodies — conserved in collisions and
* under symmetric internal forces like gravitation. */
totalMomentum() {
let x = 0, y = 0;
for (const b of this._byId.values()) {
if (b.isStatic) continue;
x += b.mass * b.velocity.x; y += b.mass * b.velocity.y;
}
return { x, y };
}
/** Centre of mass of all dynamic bodies: { x, y, mass } (mass 0 → origin). */
centerOfMass() {
let m = 0, x = 0, y = 0;
for (const b of this._byId.values()) {
if (b.isStatic) continue;
m += b.mass; x += b.position.x * b.mass; y += b.position.y * b.mass;
}
return m > 0 ? { x: x / m, y: y / m, mass: m } : { x: 0, y: 0, mass: 0 };
}
/* ---------------- property setters (engine stays source of truth) ----------------
Stability rule: setters IGNORE non-finite inputs (NaN / Infinity)
instead of letting them into the world — a single NaN position would
otherwise poison every body it touches. Use findNonFiniteBodies() to
audit a world that came from untrusted data. */
wake(body) { if (body.isSleeping) this.M.Sleeping.set(body, false); }
setPosition(body, x, y) {
if (!Number.isFinite(x) || !Number.isFinite(y)) return;
this.wake(body); this.M.Body.setPosition(body, { x, y });
}
setVelocity(body, vx, vy) {
if (!Number.isFinite(vx) || !Number.isFinite(vy)) return;
if (!body.isStatic) { this.wake(body); this.M.Body.setVelocity(body, { x: vx, y: vy }); }
}
setAngleDeg(body, deg) {
if (!Number.isFinite(deg)) return;
this.wake(body); this.M.Body.setAngle(body, deg * Math.PI / 180);
}
/** Velocity cap in px/step (0 = off) — see the constructor option. */
setMaxSpeed(v) { this._maxSpeed = Math.max(0, num(v, 0)); }
get maxSpeed() { return this._maxSpeed; }
/** Ids of bodies whose position or velocity is NaN/Infinity (should
* always be empty in a healthy world). */
findNonFiniteBodies() {
const out = [];
for (const b of this._byId.values()) {
if (!Number.isFinite(b.position.x) || !Number.isFinite(b.position.y)
|| !Number.isFinite(b.velocity.x) || !Number.isFinite(b.velocity.y)) out.push(this.idOf(b));
}
return out;
}
setDensity(body, v) {
this.M.Body.setDensity(body, Math.max(0.00001, v));
if (body.plugin.pe.desc.lockRotation && !body.isStatic) this.M.Body.setInertia(body, Infinity);
body.plugin.pe.desc.density = body.density;
}
setMass(body, v) {
this.M.Body.setMass(body, Math.max(0.01, v));
if (body.plugin.pe.desc.lockRotation && !body.isStatic) this.M.Body.setInertia(body, Infinity);
}
setFriction(body, v) { body.friction = v; body.plugin.pe.desc.friction = v; }
setFrictionAir(body, v) { body.frictionAir = Math.min(1, Math.max(0, v)); body.plugin.pe.desc.frictionAir = body.frictionAir; }
setRestitution(body, v) { body.restitution = v; body.plugin.pe.desc.restitution = v; }
/** Set a body's magnetic pole strength (signed, clamped to [-100, 100]).
* Keeps the magnet registry in sync; non-finite input is ignored. */
setMagnet(body, v) {
if (!body || !body.plugin || !body.plugin.pe || !Number.isFinite(Number(v))) return;
const val = Math.min(100, Math.max(-100, Number(v)));
body.plugin.pe.desc.magnet = val;
if (val !== 0) this._magnets.add(body); else this._magnets.delete(body);
this._magnetCache = null;
this.wake(body);
}
/** A body's current magnetic pole strength (0 when not magnetic). */
magnetOf(body) { return body && body.plugin && body.plugin.pe ? body.plugin.pe.desc.magnet : 0; }
setStatic(body, flag) {
this.M.Body.setStatic(body, flag);
body.plugin.pe.desc.isStatic = flag;
if (!flag && body.plugin.pe.desc.lockRotation) this.M.Body.setInertia(body, Infinity);
}
setLockRotation(body, flag) {
const rec = body.plugin.pe;
rec.desc.lockRotation = flag;
if (flag) this._locked.add(body); else this._locked.delete(body);
if (body.isStatic) return;
if (flag) {
if (Number.isFinite(body.inertia)) body._peInertia0 = body.inertia;
this.M.Body.setInertia(body, Infinity);
this.M.Body.setAngularVelocity(body, 0);
} else if (Number.isFinite(body._peInertia0)) {
this.M.Body.setInertia(body, body._peInertia0);
}
}
stopMotion(body) {
if (body.isStatic) return;
this.wake(body);
this.M.Body.setVelocity(body, { x: 0, y: 0 });
this.M.Body.setAngularVelocity(body, 0);
}
/** Add to a body's velocity (an impulse-like shove). Static bodies are ignored. */
addVelocity(body, dvx, dvy) {
if (!body || body.isStatic) return;
if (!Number.isFinite(dvx) || !Number.isFinite(dvy)) return;
this.wake(body);
this.M.Body.setVelocity(body, { x: body.velocity.x + dvx, y: body.velocity.y + dvy });
}
/**
* Radial shove: every non-static body within `radius` of (cx, cy) gains
* velocity pointing away from the centre, with magnitude
* base + power * (1 - distance / radius)
* Bodies at the exact centre are pushed straight up. An optional
* `filter(body)` may veto bodies (e.g. host-level boundary walls).
* Returns the number of bodies affected.
*/
applyRadialImpulse(cx, cy, opts = {}) {
const radius = Math.max(1, num(opts.radius, 200));
const base = num(opts.base, 0), power = num(opts.power, 10);
const filter = typeof opts.filter === 'function' ? opts.filter : null;
let hit = 0;
for (const b of this._bodies()) {
if (b.isStatic) continue;
if (filter && !filter(b)) continue;
const dx = b.position.x - cx, dy = b.position.y - cy;
const dist = Math.hypot(dx, dy);
if (dist > radius) continue;
const mag = base + power * (1 - dist / radius);
const ux = dist > 1 ? dx / dist : 0, uy = dist > 1 ? dy / dist : -1;
this.addVelocity(b, ux * mag, uy * mag);
hit++;
}
return hit;
}
/** Resize by rebuilding in place: keeps id, material, velocity and userData. */
resize(body, patch) {
const desc = this.describeBody(body);
Object.assign(desc, patch);
const vel = { x: body.velocity.x, y: body.velocity.y };
const id = desc.id;
this.removeBody(id);
const nb = this.addBody(desc);
if (!nb.isStatic) this.M.Body.setVelocity(nb, vel);
return nb;
}
/* ---------------- dragging (real physics constraint; bodies can be thrown) ---------------- */
beginDrag(body, wx, wy) {
this.endDrag();
if (!body || body.isStatic) return;
this.wake(body);
// The grab offset is the pointer minus the body centre, in
// world-aligned coordinates (Matter rotates pointB by the body
// angle, so the offset is only exact for the angle at grab
// time — which is why a checkpoint restore must carry the
// original pointB instead of recomputing it; see load()).
this._attachDrag(body, wx, wy, wx - body.position.x, wy - body.position.y);
}
/** Create the drag constraint with an EXACT grab offset. beginDrag
* computes the offset from the grab point; load() restores the
* offset AND the solver-tracked angleB a snapshot captured —
* angleB lags the body angle (it is only refreshed when the
* constraint solves), so recomputing it from the current angle
* rotates the grab offset by the lag and the replay diverges
* by whole pixels on the next step (1.13.2). */
_attachDrag(body, ax, ay, ox, oy, angleB) {
this._drag = this.M.Constraint.create({
pointA: { x: ax, y: ay },
bodyB: body,
pointB: { x: ox, y: oy },
stiffness: 0.12, damping: 0.08, length: 0,
});
if (Number.isFinite(angleB)) this._drag.angleB = angleB;
this.M.Composite.add(this.world, this._drag);
}
moveDrag(wx, wy) { if (this._drag) this._drag.pointA = { x: wx, y: wy }; }
endDrag() {
if (this._drag) { this.M.Composite.remove(this.world, this._drag); this._drag = null; }
}
get dragging() { return !!this._drag; }
get dragBody() { return this._drag ? this._drag.bodyB : null; }
/* ---------------- seeded RNG ----------------
A mulberry32 stream owned by this engine instance: same seed -> same
sequence, independent of Math.random and of other engines. Use it for
anything that must be reproducible (procedural scenes, spawn jitter,
random impulses) — share the seed and the run can be replayed exactly.
Setting a seed also aligns Matter's own Common._seed, so Matter-level
helpers that draw randomness start from the same origin. */
setSeed(n) {
this._seed = (Number.isFinite(Number(n)) ? Number(n) : 0) >>> 0;
this._rngState = this._seed;
if (this.M && this.M.Common) this.M.Common._seed = this._seed;
}
/** The seed the current RNG stream started from. */
get seed() { return this._seed; }
/** Next float in [0, 1). */
random() {
this._rngState = (this._rngState + 0x6D2B79F5) >>> 0;
let t = this._rngState;
t = Math.imul(t ^ (t >>> 15), t | 1);
t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
}
/** Float in [min, max). */
randomRange(min, max) { return min + this.random() * (max - min); }
/** Integer in [min, max], both ends inclusive. */
randomInt(min, max) { return Math.floor(min + this.random() * (Math.floor(max) - min + 1)); }
/** A random element of the array (undefined for an empty array). */
choice(arr) { return arr && arr.length ? arr[Math.floor(this.random() * arr.length)] : undefined; }
/** Fisher–Yates shuffle driven by this stream; in place, returns the array. */
shuffle(arr) {
for (let i = arr.length - 1; i > 0; i--) {
const j = Math.floor(this.random() * (i + 1));
const tmp = arr[i]; arr[i] = arr[j]; arr[j] = tmp;
}
return arr;
}
/* ---------------- events ---------------- */
onCollision(cb) { if (typeof cb === 'function') this._collisionCbs.push(cb); }
/* --------------------- observability (1.13.0) -----------------------
Console surface, twin of the NativeEngine API. The common fields
are computed live; the solver-internal counters (wake-touch gate,
pre-wake, sleep/wake/spawn tallies) are Impulse-only and report
null here — Matter exposes no equivalent solver hooks. */
get stats() {
const bodies = this._bodies();
let sleeping = 0;
for (const b of bodies) if (b.isSleeping) sleeping++;
return {
steps: Math.round(this._simMs / this.fixedDt), bodies: bodies.length, sleeping,
contacts: (this.engine && this.engine.pairs && this.engine.pairs.list) ? this.engine.pairs.list.length : null,
gateFirings: null, preWakeFirings: null, wakes: null, sleeps: null, spawns: null,
};
}
onEvent() { return () => {}; }
resetStats() {}
_emitChange() {
this._bodiesCache = null; // any structural change invalidates the cached view
this._indexCache = null; // body -> position-in-array map used by the pair pass
if (typeof this.onChange === 'function') this.onChange();
}
}
export default PhysicsEngine;