@flare-engine/dynamics 0.4.8 → 0.4.11

package/dist/index.js

@@ -107,6 +107,58 @@ function writeAabb(verts, vOffset, out, offset) {
 	out[offset + 2] = maxX;
 	out[offset + 3] = maxY;
 }
+// src/timeline.ts
+const DEFAULT_STRIDE = 3;
+const DEFAULT_MAX_FRAMES = 900;
+function assertCount(name, value, min) {
+	if (!Number.isInteger(value) || value < min) throw new RangeError(`createTimeline: ${name} must be an integer >= ${min}, got ${value}`);
+}
+function createTimeline(elementCount, dt, opts = {}) {
+	assertCount("elementCount", elementCount, 0);
+	if (!Number.isFinite(dt) || dt <= 0) throw new RangeError(`createTimeline: dt must be a finite number > 0, got ${dt}`);
+	const stride = opts.stride ?? DEFAULT_STRIDE;
+	const maxFrames = opts.maxFrames ?? DEFAULT_MAX_FRAMES;
+	assertCount("stride", stride, 1);
+	assertCount("maxFrames", maxFrames, 1);
+	const frameStride = elementCount * stride;
+	const buf = new Float32Array(Math.max(1, frameStride) * maxFrames);
+	let frameCount = 0;
+	return {
+		elementCount,
+		get frameCount() {
+			return frameCount;
+		},
+		get duration() {
+			return frameCount > 1 ? (frameCount - 1) * dt : 0;
+		},
+		record(writer, until) {
+			if (elementCount === 0) return;
+			while (frameCount < maxFrames) {
+				writer(buf, frameCount * frameStride);
+				frameCount++;
+				if (until === void 0 || until()) return;
+			}
+		},
+		sampleInto(progress, out) {
+			const n = frameStride;
+			if (frameCount === 0) {
+				out.fill(0, 0, n);
+				return;
+			}
+			const f = (progress > 1 ? 1 : progress >= 0 ? progress : 0) * (frameCount - 1);
+			const i0 = Math.floor(f);
+			const a = f - i0;
+			const i1 = i0 + 1 < frameCount ? i0 + 1 : i0;
+			const b0 = i0 * n;
+			const b1 = i1 * n;
+			for (let o = 0; o < n; o++) {
+				const lo = buf[b0 + o];
+				const hi = buf[b1 + o];
+				out[o] = lo + (hi - lo) * a;
+			}
+		}
+	};
+}
 // src/manifold.ts
 /** OBB-OBB collision: separating-axis test + reference/incident face clipping,
 *  building a 1-2 point contact manifold with per-point penetration depth.
@@ -317,6 +369,12 @@ function createManifold() {
 	return {
 		a: void 0,
 		b: void 0,
+		ai: 0,
+		bi: 0,
+		aInvMass: 0,
+		aInvInertia: 0,
+		bInvMass: 0,
+		bInvInertia: 0,
 		normalX: 0,
 		normalY: 0,
 		tangentX: 0,
@@ -326,19 +384,24 @@ function createManifold() {
 		points: [createManifoldPoint(), createManifoldPoint()]
 	};
 }
-function createPool() {
+function createPool(sleep = null) {
 	return {
 		manifolds: [],
 		manifoldCount: 0,
 		verts: /* @__PURE__ */ new Float64Array(0),
 		normals: /* @__PURE__ */ new Float64Array(0),
 		aabbs: /* @__PURE__ */ new Float64Array(0),
-		capacityBodies: 0
+		capacityBodies: 0,
+		sleep,
+		sleepCounter: /* @__PURE__ */ new Int32Array(0),
+		asleep: /* @__PURE__ */ new Uint8Array(0),
+		sleepSnapshot: /* @__PURE__ */ new Float64Array(0),
+		sleepOwner: []
 	};
 }
-/** Grows the per-body geometry buffers to hold at least `count` bodies (8
-*  doubles per body for verts/normals, 4 for the AABB). No-op if already
-*  large enough. */
+/** Grows the per-body buffers to hold at least `count` bodies (8 doubles per
+*  body for verts/normals, 4 for the AABB, 3 for the sleep snapshot). No-op
+*  if already large enough. */
 function ensureBodyCapacity(pool, count) {
 	if (count <= pool.capacityBodies) return;
 	let cap = pool.capacityBodies === 0 ? 8 : pool.capacityBodies;
@@ -346,6 +409,16 @@ function ensureBodyCapacity(pool, count) {
 	pool.verts = new Float64Array(cap * 8);
 	pool.normals = new Float64Array(cap * 8);
 	pool.aabbs = new Float64Array(cap * 4);
+	const sleepCounter = new Int32Array(cap);
+	sleepCounter.set(pool.sleepCounter);
+	pool.sleepCounter = sleepCounter;
+	const asleep = new Uint8Array(cap);
+	asleep.set(pool.asleep);
+	pool.asleep = asleep;
+	const sleepSnapshot = new Float64Array(cap * 3);
+	sleepSnapshot.set(pool.sleepSnapshot);
+	pool.sleepSnapshot = sleepSnapshot;
+	while (pool.sleepOwner.length < cap) pool.sleepOwner.push(void 0);
 	pool.capacityBodies = cap;
 }
 /** Grows `pool.manifolds` to hold at least `count` entries, appending
@@ -359,6 +432,23 @@ function ensureManifoldCapacity(pool, count) {
 const BAUMGARTE = .2;
 const PENETRATION_SLOP = .5;
 const pools = /* @__PURE__ */ new WeakMap();
+function nowMs() {
+	if (typeof performance !== "undefined" && typeof performance.now === "function") return performance.now();
+	return Date.now();
+}
+function copySleepOptions(sleep) {
+	const { linearThreshold, angularThreshold, steps } = sleep;
+	if (!Number.isFinite(linearThreshold) || linearThreshold < 0) throw new RangeError(`createWorld: sleep.linearThreshold must be a finite number >= 0, got ${linearThreshold}`);
+	if (!Number.isFinite(angularThreshold) || angularThreshold < 0) throw new RangeError(`createWorld: sleep.angularThreshold must be a finite number >= 0, got ${angularThreshold}`);
+	if (!Number.isInteger(steps) || steps < 1) throw new RangeError(`createWorld: sleep.steps must be an integer >= 1, got ${steps}`);
+	return {
+		linearThreshold,
+		angularThreshold,
+		steps
+	};
+}
+/** Throws `RangeError` when `opts.sleep` has a negative or non-finite
+*  threshold or a `steps` that is not an integer >= 1. */
 function createWorld(opts = {}) {
 	const world = {
 		bodies: [],
@@ -371,7 +461,7 @@ function createWorld(opts = {}) {
 		},
 		iterations: opts.iterations ?? 10
 	};
-	pools.set(world, createPool());
+	pools.set(world, createPool(opts.sleep ? copySleepOptions(opts.sleep) : null));
 	return world;
 }
 function addBody(world, body) {
@@ -387,16 +477,37 @@ function relativeVelocityAlong(a, b, raX, raY, rbX, rbY, dx, dy) {
 	const vby = b.velocity.y + b.angularVelocity * rbX;
 	return (vbx - vax) * dx + (vby - vay) * dy;
 }
-function applyImpulse(body, ix, iy, rx, ry) {
-	if (body.invMass === 0) return;
-	body.velocity.x += ix * body.invMass;
-	body.velocity.y += iy * body.invMass;
-	body.angularVelocity += body.invInertia * (rx * iy - ry * ix);
+function applyImpulse(body, invMass, invInertia, ix, iy, rx, ry) {
+	if (invMass === 0) return;
+	body.velocity.x += ix * invMass;
+	body.velocity.y += iy * invMass;
+	body.angularVelocity += invInertia * (rx * iy - ry * ix);
+}
+/** Binds every slot to the body now at its index, resetting a slot whose body
+*  changed (awake, counter 0), then wakes any sleeper the consumer wrote to:
+*  a non-zero velocity (sleepers are held at exactly 0) or a position/angle
+*  that differs from the snapshot taken at sleep. */
+function syncSleepSlots(pool, bodies) {
+	const { sleepOwner, asleep, sleepCounter, sleepSnapshot } = pool;
+	for (let i = 0; i < bodies.length; i++) {
+		const body = bodies[i];
+		if (sleepOwner[i] !== body) {
+			sleepOwner[i] = body;
+			asleep[i] = 0;
+			sleepCounter[i] = 0;
+			continue;
+		}
+		if (asleep[i] === 0) continue;
+		const s = i * 3;
+		if (body.velocity.x !== 0 || body.velocity.y !== 0 || body.angularVelocity !== 0 || body.position.x !== sleepSnapshot[s] || body.position.y !== sleepSnapshot[s + 1] || body.angle !== sleepSnapshot[s + 2]) {
+			asleep[i] = 0;
+			sleepCounter[i] = 0;
+		}
+	}
 }
 /** Writes every body's world-space vertices, outward normals, and AABB into
 *  `pool`, once per step, so the broadphase pair loop never recomputes them. */
 function writeGeometry(pool, bodies) {
-	ensureBodyCapacity(pool, bodies.length);
 	for (let i = 0; i < bodies.length; i++) {
 		const b = bodies[i];
 		const vOffset = i * 8;
@@ -407,12 +518,14 @@ function writeGeometry(pool, bodies) {
 	}
 }
 /** Broadphase (precomputed-AABB reject) + narrowphase (OBB manifold),
-*  writing surviving contacts into `pool.manifolds[0..manifoldCount)`. */
+*  writing surviving contacts into `pool.manifolds[0..manifoldCount)`. A pair
+*  whose two bodies are each static or asleep is skipped. */
 function collectManifolds(pool, bodies) {
 	pool.manifoldCount = 0;
-	const aabbs = pool.aabbs;
+	const { aabbs, asleep } = pool;
 	for (let i = 0; i < bodies.length; i++) {
 		const a = bodies[i];
+		const aResting = isStatic(a) || asleep[i] === 1;
 		const aOff = i * 4;
 		const aMinX = aabbs[aOff];
 		const aMinY = aabbs[aOff + 1];
@@ -420,7 +533,7 @@ function collectManifolds(pool, bodies) {
 		const aMaxY = aabbs[aOff + 3];
 		for (let j = i + 1; j < bodies.length; j++) {
 			const b = bodies[j];
-			if (isStatic(a) && isStatic(b)) continue;
+			if (aResting && (isStatic(b) || asleep[j] === 1)) continue;
 			const bOff = j * 4;
 			const bMinX = aabbs[bOff];
 			const bMinY = aabbs[bOff + 1];
@@ -429,17 +542,52 @@ function collectManifolds(pool, bodies) {
 			if (aMaxX < bMinX || aMinX > bMaxX || aMaxY < bMinY || aMinY > bMaxY) continue;
 			ensureManifoldCapacity(pool, pool.manifoldCount + 1);
 			const m = pool.manifolds[pool.manifoldCount];
-			if (collideInto(a, b, pool.verts, pool.normals, i, j, m)) pool.manifoldCount++;
+			if (collideInto(a, b, pool.verts, pool.normals, i, j, m)) {
+				m.ai = i;
+				m.bi = j;
+				pool.manifoldCount++;
+			}
 		}
 	}
 }
+/** Wakes a sleeper touched by an awake body that was moving on the previous
+*  step (sleep counter 0), giving it this step's gravity so it continues as
+*  if it had been awake for the integration. A sleeper touched only by a
+*  settling body stays asleep. Pairs of two resting bodies never reach here,
+*  so a manifold with one sleeper always has an awake dynamic partner. */
+function wakeByContact(pool, gravity, dt) {
+	const { asleep, sleepCounter } = pool;
+	for (let mi = 0; mi < pool.manifoldCount; mi++) {
+		const m = pool.manifolds[mi];
+		const aAsleep = asleep[m.ai] === 1;
+		if (aAsleep === (asleep[m.bi] === 1)) continue;
+		const sleeperIdx = aAsleep ? m.ai : m.bi;
+		if (sleepCounter[aAsleep ? m.bi : m.ai] !== 0) continue;
+		asleep[sleeperIdx] = 0;
+		sleepCounter[sleeperIdx] = 0;
+		const sleeper = aAsleep ? m.a : m.b;
+		sleeper.velocity.x += gravity.x * dt;
+		sleeper.velocity.y += gravity.y * dt;
+	}
+}
 /** Derives per-point solver mass terms and the velocity/position bias for
 *  every live manifold, writing them onto the manifold's own contact points. */
 function prepare(pool, gravity, dt) {
 	const restThreshold = Math.hypot(gravity.x, gravity.y) * dt;
+	const { asleep } = pool;
 	for (let mi = 0; mi < pool.manifoldCount; mi++) {
 		const m = pool.manifolds[mi];
 		const { a, b } = m;
+		const aAsleep = asleep[m.ai] === 1;
+		const bAsleep = asleep[m.bi] === 1;
+		const aInvMass = aAsleep ? 0 : a.invMass;
+		const aInvInertia = aAsleep ? 0 : a.invInertia;
+		const bInvMass = bAsleep ? 0 : b.invMass;
+		const bInvInertia = bAsleep ? 0 : b.invInertia;
+		m.aInvMass = aInvMass;
+		m.aInvInertia = aInvInertia;
+		m.bInvMass = bInvMass;
+		m.bInvInertia = bInvInertia;
 		const normalX = m.normalX;
 		const normalY = m.normalY;
 		const tangentX = m.tangentX;
@@ -453,10 +601,10 @@ function prepare(pool, gravity, dt) {
 			const rbY = cp.y - b.position.y;
 			const rnA = raX * normalY - raY * normalX;
 			const rnB = rbX * normalY - rbY * normalX;
-			const kNormal = a.invMass + b.invMass + a.invInertia * rnA * rnA + b.invInertia * rnB * rnB;
+			const kNormal = aInvMass + bInvMass + aInvInertia * rnA * rnA + bInvInertia * rnB * rnB;
 			const rtA = raX * tangentY - raY * tangentX;
 			const rtB = rbX * tangentY - rbY * tangentX;
-			const kTangent = a.invMass + b.invMass + a.invInertia * rtA * rtA + b.invInertia * rtB * rtB;
+			const kTangent = aInvMass + bInvMass + aInvInertia * rtA * rtA + bInvInertia * rtB * rtB;
 			const vn = relativeVelocityAlong(a, b, raX, raY, rbX, rbY, normalX, normalY);
 			const restitutionBias = vn < -restThreshold ? -restitution * vn : 0;
 			const baumgarte = BAUMGARTE / dt * Math.max(0, cp.penetration - PENETRATION_SLOP);
@@ -474,7 +622,7 @@ function prepare(pool, gravity, dt) {
 function solve(pool) {
 	for (let mi = 0; mi < pool.manifoldCount; mi++) {
 		const m = pool.manifolds[mi];
-		const { a, b, friction } = m;
+		const { a, b, friction, aInvMass, aInvInertia, bInvMass, bInvInertia } = m;
 		const normalX = m.normalX;
 		const normalY = m.normalY;
 		const tangentX = m.tangentX;
@@ -492,8 +640,8 @@ function solve(pool) {
 			cp.normalImpulse = newNormal;
 			const pnX = normalX * dPn;
 			const pnY = normalY * dPn;
-			applyImpulse(a, -pnX, -pnY, raX, raY);
-			applyImpulse(b, pnX, pnY, rbX, rbY);
+			applyImpulse(a, aInvMass, aInvInertia, -pnX, -pnY, raX, raY);
+			applyImpulse(b, bInvMass, bInvInertia, pnX, pnY, rbX, rbY);
 			const vt = relativeVelocityAlong(a, b, raX, raY, rbX, rbY, tangentX, tangentY);
 			let dPt = cp.massTangent * -vt;
 			const maxPt = friction * cp.normalImpulse;
@@ -502,20 +650,55 @@ function solve(pool) {
 			cp.tangentImpulse = newTangent;
 			const ptX = tangentX * dPt;
 			const ptY = tangentY * dPt;
-			applyImpulse(a, -ptX, -ptY, raX, raY);
-			applyImpulse(b, ptX, ptY, rbX, rbY);
+			applyImpulse(a, aInvMass, aInvInertia, -ptX, -ptY, raX, raY);
+			applyImpulse(b, bInvMass, bInvInertia, ptX, ptY, rbX, rbY);
 		}
 	}
 }
+/** Puts every awake dynamic body that stayed under both thresholds for
+*  `sleep.steps` consecutive steps to sleep: velocities zeroed, flag set,
+*  position/angle snapshotted for the write-wake check. */
+function updateSleep(pool, sleep, bodies) {
+	const { asleep, sleepCounter, sleepSnapshot } = pool;
+	const linear2 = sleep.linearThreshold * sleep.linearThreshold;
+	const angular2 = sleep.angularThreshold * sleep.angularThreshold;
+	for (let i = 0; i < bodies.length; i++) {
+		const body = bodies[i];
+		if (isStatic(body) || asleep[i] === 1) continue;
+		const vx = body.velocity.x;
+		const vy = body.velocity.y;
+		const w = body.angularVelocity;
+		if (vx * vx + vy * vy < linear2 && w * w < angular2) {
+			const count = sleepCounter[i] + 1;
+			sleepCounter[i] = count;
+			if (count < sleep.steps) continue;
+			body.velocity.x = 0;
+			body.velocity.y = 0;
+			body.angularVelocity = 0;
+			asleep[i] = 1;
+			const s = i * 3;
+			sleepSnapshot[s] = body.position.x;
+			sleepSnapshot[s + 1] = body.position.y;
+			sleepSnapshot[s + 2] = body.angle;
+		} else sleepCounter[i] = 0;
+	}
+}
 /** Advance the world by `dt` seconds (fixed steps recommended).
 *
-*  Resting contacts settle to a stable *position* but retain a small, bounded
-*  velocity oscillation at the penetration-slop equilibrium — a sequential-
-*  impulse solver with Baumgarte bias and no sleeping does not converge
-*  velocity to exactly zero at rest, only the position does. This is
-*  inherent to the algorithm, not a bug; sleeping and damping are
-*  deliberately out of scope for v1. A consumer needing pixel-exact
-*  stillness should clamp small resting velocities at its own layer. */
+*  By default (no `WorldOptions.sleep`) resting contacts settle to a stable
+*  *position* but retain a small, bounded velocity oscillation at the
+*  penetration-slop equilibrium — a sequential-impulse solver with Baumgarte
+*  bias does not converge velocity to exactly zero at rest, only the position
+*  does. `WorldOptions.sleep` opts into per-body sleeping: a dynamic body
+*  under both thresholds for `steps` consecutive steps has its velocities
+*  zeroed and is skipped by integration and by pair tests against other
+*  resting bodies until an awake body touches it, the consumer writes its
+*  velocity, position or angle, or `wakeBody` is called. There are no
+*  islands, so a woken stack wakes one level per step, and a sleeper does not
+*  follow a static body that is moved under it. Damping stays out of scope.
+*
+*  A world that never went through `createWorld` (a spread copy or a
+*  `structuredClone`) is adopted on its first `step` with sleeping off. */
 function step(world, dt) {
 	if (dt <= 0) return;
 	let pool = pools.get(world);
@@ -524,28 +707,114 @@ function step(world, dt) {
 		pools.set(world, pool);
 	}
 	const { bodies } = world;
+	ensureBodyCapacity(pool, bodies.length);
+	const { sleep, asleep } = pool;
+	if (sleep !== null) syncSleepSlots(pool, bodies);
 	for (let i = 0; i < bodies.length; i++) {
 		const body = bodies[i];
-		if (isStatic(body)) continue;
+		if (isStatic(body) || asleep[i] === 1) continue;
 		body.velocity.x += world.gravity.x * dt;
 		body.velocity.y += world.gravity.y * dt;
 	}
 	writeGeometry(pool, bodies);
 	collectManifolds(pool, bodies);
+	if (sleep !== null) wakeByContact(pool, world.gravity, dt);
 	prepare(pool, world.gravity, dt);
 	for (let iter = 0; iter < world.iterations; iter++) solve(pool);
 	for (let i = 0; i < bodies.length; i++) {
 		const body = bodies[i];
-		if (isStatic(body)) continue;
+		if (isStatic(body) || asleep[i] === 1) continue;
 		body.position.x += body.velocity.x * dt;
 		body.position.y += body.velocity.y * dt;
 		body.angle += body.angularVelocity * dt;
 	}
+	if (sleep !== null) updateSleep(pool, sleep, bodies);
+}
+/** `true` when `body` is asleep in `world`. `false` when the world has
+*  sleeping off or never went through `createWorld`, when `body` is not in
+*  `world.bodies`, or when its slot has not been bound to it by a `step` yet.
+*  O(n) in `world.bodies.length` (an `indexOf`); poll it per body, not per
+*  contact. */
+function isSleeping(world, body) {
+	const pool = pools.get(world);
+	if (!pool || pool.sleep === null) return false;
+	const i = world.bodies.indexOf(body);
+	if (i < 0 || pool.sleepOwner[i] !== body) return false;
+	return pool.asleep[i] === 1;
+}
+/** `true` when every dynamic body in `world.bodies` is asleep — vacuously
+*  true with no dynamic bodies, `false` with sleeping off and at least one.
+*  The bake stop rule for `stepUntil`: `done: () => isAtRest(world)`. */
+function isAtRest(world) {
+	const pool = pools.get(world);
+	const { bodies } = world;
+	for (let i = 0; i < bodies.length; i++) {
+		const body = bodies[i];
+		if (isStatic(body)) continue;
+		if (!pool || pool.sleep === null || pool.sleepOwner[i] !== body || pool.asleep[i] !== 1) return false;
+	}
+	return true;
+}
+/** Wakes `body` if it is asleep in `world` (flag cleared, counter 0, its
+*  velocities stay 0); the next `step` integrates it again. No-op otherwise,
+*  including with sleeping off or a body not in `world.bodies`. Use it for a
+*  sleeper whose support was removed from `world.bodies` or moved — nothing
+*  else wakes it. */
+function wakeBody(world, body) {
+	const pool = pools.get(world);
+	if (!pool || pool.sleep === null) return;
+	const i = world.bodies.indexOf(body);
+	if (i < 0 || pool.sleepOwner[i] !== body || pool.asleep[i] !== 1) return;
+	pool.asleep[i] = 0;
+	pool.sleepCounter[i] = 0;
+}
+/** Repeats `step(world, dt)` until, checked in this order after each step,
+*  `done()` returns true (`complete: true`), `steps >= maxSteps`, or
+*  `now() - start >= budgetMs` (both `complete: false`). Always takes at least
+*  one step, so a zero budget still makes progress. Writes `out` and returns it;
+*  the zero-alloc per-frame form of `stepUntil`. Throws `RangeError` for a
+*  non-finite or non-positive `dt`, a negative or non-finite `budgetMs`, or a
+*  `maxSteps` that is not an integer >= 1. */
+function stepUntilInto(world, dt, opts, out) {
+	if (!Number.isFinite(dt) || dt <= 0) throw new RangeError(`stepUntil: dt must be a finite number > 0, got ${dt}`);
+	const { budgetMs, maxSteps, done } = opts;
+	if (!Number.isFinite(budgetMs) || budgetMs < 0) throw new RangeError(`stepUntil: budgetMs must be a finite number >= 0, got ${budgetMs}`);
+	if (maxSteps !== void 0 && (!Number.isInteger(maxSteps) || maxSteps < 1)) throw new RangeError(`stepUntil: maxSteps must be an integer >= 1, got ${maxSteps}`);
+	const now = opts.now ?? nowMs;
+	const start = now();
+	let steps = 0;
+	let complete = false;
+	for (;;) {
+		step(world, dt);
+		steps++;
+		if (done?.()) {
+			complete = true;
+			break;
+		}
+		if (maxSteps !== void 0 && steps >= maxSteps) break;
+		if (now() - start >= budgetMs) break;
+	}
+	out.steps = steps;
+	out.complete = complete;
+	return out;
+}
+/** Allocating form of `stepUntilInto`; see it for the stop rules. */
+function stepUntil(world, dt, opts) {
+	return stepUntilInto(world, dt, opts, {
+		steps: 0,
+		complete: false
+	});
 }
 exports.addBody = addBody;
 exports.createBody = createBody;
+exports.createTimeline = createTimeline;
 exports.createWorld = createWorld;
+exports.isAtRest = isAtRest;
+exports.isSleeping = isSleeping;
 exports.isStatic = isStatic;
 exports.step = step;
+exports.stepUntil = stepUntil;
+exports.stepUntilInto = stepUntilInto;
+exports.wakeBody = wakeBody;
 
 //# sourceMappingURL=index.js.map