Skip to content

Code-first video & image, rendered natively on WebGPU.

14.7 KB
Raw Blame
import { describe, expect, it } from "vitest";
import { Layer, Layer3D, Signal } from "../index.js";
import { simplifyKeys, unwrapDegrees } from "./core.js";
import { Physics } from "./index.js";
import { eulerFromQuat, quatFromEuler } from "./world3d.js";

const FPS = 30;
const at = (s: { get(ctx?: never): number }, frame: number) =>
	s.get({ frame, fps: FPS } as never);

function card(
	id: string,
	x: number,
	y: number,
	extra: Record<string, unknown> = {},
) {
	return Layer.box({
		id,
		position: "absolute",
		x,
		y,
		width: 200,
		height: 100,
		background: "#fff",
		...extra,
	});
}

type Track = {
	prop: string;
	source?: { type: string };
	keyframes: Array<{ frame: number; value: number }>;
};
const tracksOf = (layer: unknown) =>
	((layer as { animation?: { tracks: Track[] } }).animation?.tracks ??
		[]) as Track[];

describe("Physics.world2d", () => {
	it("drops a box onto the ground and binds the layer to signals", async () => {
		const world = await Physics.world2d({ fps: FPS, frames: 90 });
		world.ground({ y: 1000 });
		const layer = card("a", 860, 100);
		const body = world.body(layer, { restitution: 0 });
		world.simulate();

		expect(at(body.y, 0)).toBeCloseTo(100, 3);
		// Rests on the ground: bottom edge at y = 1000.
		expect(at(body.y, 89) + 100).toBeCloseTo(1000, 0);
		expect(Math.abs(at(body.x, 89) - 860)).toBeLessThan(2);
		expect(at(body.sleeping, 89)).toBe(1);

		const props = tracksOf(layer).map((t) => [t.prop, t.source?.type]);
		expect(props).toEqual([
			["x", "signal"],
			["y", "signal"],
			["rotation", "signal"],
		]);
	});

	it("records first contacts and an impact envelope that decays", async () => {
		const world = await Physics.world2d({
			fps: FPS,
			frames: 60,
			impactDecay: 4,
		});
		const ground = world.ground({ y: 1000 });
		const body = world.body(card("a", 860, 500), { restitution: 0 });
		world.simulate();

		expect(body.collisions.length).toBeGreaterThan(0);
		const hit = body.collisions[0];
		expect(hit.with).toBe(ground);
		expect(hit.speed).toBeGreaterThan(500);
		expect(world.collisions[0].frame).toBe(hit.frame);

		expect(at(body.impact, hit.frame - 1)).toBe(0);
		const peak = at(body.impact, hit.frame);
		expect(peak).toBeGreaterThan(0.3);
		expect(at(body.impact, hit.frame + 4)).toBeLessThan(peak * 0.5);
		// The ground hears the hit too, and the world takes the loudest.
		expect(at(ground.impact, hit.frame)).toBeCloseTo(peak, 5);
		expect(at(world.impact, hit.frame)).toBeCloseTo(peak, 5);
	});

	it("is deterministic", async () => {
		const run = async () => {
			const world = await Physics.world2d({ fps: FPS, frames: 120 });
			world.walls({ width: 1920, height: 1080 });
			const bodies = Array.from({ length: 12 }, (_, i) =>
				world.body(
					card(`c${i}`, 200 + (i % 4) * 300, -200 - i * 140, {
						rotation: i * 13,
					}),
					{
						angularVelocity: i * 20,
					},
				),
			);
			world.simulate();
			return bodies.flatMap((b) => [
				at(b.x, 119),
				at(b.y, 119),
				at(b.rotation, 119),
			]);
		};
		expect(await run()).toEqual(await run());
	});

	it("starts from the layer's pose with any pivot, scale and rotation", async () => {
		const world = await Physics.world2d({ fps: FPS, frames: 2, gravity: 0 });
		const layer = card("a", 300, 400, {
			rotation: 30,
			anchorX: 0,
			anchorY: 0,
			scale: 1.5,
		});
		const body = world.body(layer);
		world.simulate();
		expect(at(body.x, 1)).toBeCloseTo(300, 3);
		expect(at(body.y, 1)).toBeCloseTo(400, 3);
		expect(at(body.rotation, 1)).toBeCloseTo(30, 3);
		// Center of a 300×150 box pivoting on its top-left corner, turned 30° clockwise.
		const a = Math.PI / 6;
		expect(at(body.centerX, 1)).toBeCloseTo(
			300 + 150 * Math.cos(a) - 75 * Math.sin(a),
			2,
		);
		expect(at(body.centerY, 1)).toBeCloseTo(
			400 + 150 * Math.sin(a) + 75 * Math.cos(a),
			2,
		);
	});

	it("holds a body until its start frame and the signals until the world's", async () => {
		const world = await Physics.world2d({
			fps: FPS,
			frames: 40,
			startFrame: 100,
		});
		const body = world.body(card("a", 0, 0), { startFrame: 10 });
		world.simulate();
		expect(at(body.y, 0)).toBe(0);
		expect(at(body.y, 110)).toBe(0);
		expect(at(body.y, 112)).toBeGreaterThan(0);
		expect(at(body.vy, 139)).toBeGreaterThan(0);
	});

	it("uses circles and convex hulls for shape layers", async () => {
		const world = await Physics.world2d({ fps: FPS, frames: 90 });
		world.ground({ y: 1000 });
		const ball = world.body(
			Layer.shape("circle", {
				position: "absolute",
				x: 100,
				y: 0,
				width: 200,
				height: 200,
			}),
			{ restitution: 0 },
		);
		const star = world.body(
			Layer.shape("star", {
				position: "absolute",
				x: 600,
				y: 0,
				width: 200,
				height: 200,
			}),
		);
		const text = world.body(card("t", 1200, 0), {
			shape: "circle",
			size: [100, 100],
		});
		world.simulate();
		expect(at(ball.y, 89) + 200).toBeCloseTo(1000, 0);
		expect(at(star.y, 89)).toBeGreaterThan(600);
		expect(at(text.centerY, 89)).toBeCloseTo(950, 0);
	});

	it("bakes simplified keyframes instead of signals", async () => {
		const world = await Physics.world2d({ fps: FPS, frames: 90 });
		world.ground({ y: 1000 });
		const layer = card("a", 860, 100);
		const body = world.body(layer, { restitution: 0, lockRotation: true });
		world.bakeKeyframes();

		const tracks = tracksOf(layer);
		expect(tracks.map((t) => t.prop)).toEqual(["x", "y"]);
		const y = tracks.find((t) => t.prop === "y") as Track;
		expect(y.source?.type ?? "keyframes").not.toBe("signal");
		expect(y.keyframes.length).toBeGreaterThan(2);
		expect(y.keyframes.length).toBeLessThan(90);
		expect(y.keyframes[0]).toMatchObject({ frame: 0, value: 100 });
		const last = y.keyframes[y.keyframes.length - 1];
		expect(last.frame).toBe(89);
		expect(last.value).toBeCloseTo(at(body.y, 89), 2);
		const x = tracks.find((t) => t.prop === "x") as Track;
		expect(x.keyframes).toHaveLength(1);
	});

	it("moves kinematic bodies from drivers and lets them push", async () => {
		const world = await Physics.world2d({ fps: FPS, frames: 60, gravity: 0 });
		const pusher = world.body(card("p", 0, 400), {
			type: "kinematic",
			follow: {
				x: Signal.fromArray(
					Array.from({ length: 60 }, (_, f) => f * 20),
					FPS,
				),
			},
		});
		const target = world.body(card("t", 500, 400));
		world.simulate();
		expect(at(pusher.x, 30)).toBeCloseTo(600, 0);
		expect(at(target.x, 59)).toBeGreaterThan(700);
	});

	it("applies forces, impulses and joints", async () => {
		const world = await Physics.world2d({ fps: FPS, frames: 60, gravity: 0 });
		const pushed = world.body(card("a", 0, 0));
		world.force(pushed, { x: (frame) => (frame < 30 ? 600 : 0) });
		const kicked = world.body(card("b", 0, 300));
		world.impulse(kicked, 10, [0, -900]);
		const swing = world.body(card("c", 1000, 0), { gravityScale: 1 });
		world.pin(swing, [1000, 50]);
		world.force(swing, { y: 2400 });
		world.simulate();
		expect(at(pushed.vx, 29)).toBeCloseTo(580, -1);
		expect(at(pushed.vx, 59)).toBeCloseTo(at(pushed.vx, 31), 1);
		expect(at(kicked.vy, 9)).toBe(0);
		expect(at(kicked.vy, 10)).toBeCloseTo(-900, 0);
		// Pinned at its left edge's middle: swings down around the pin, never falls away.
		const swingAngles = Array.from({ length: 60 }, (_, f) =>
			Math.abs(at(swing.rotation, f)),
		);
		expect(Math.max(...swingAngles)).toBeGreaterThan(60);
		expect(
			Math.hypot(at(swing.centerX, 59) - 1000, at(swing.centerY, 59) - 50),
		).toBeCloseTo(100, -1);
	});

	it("pushes bodies with a position-dependent field", async () => {
		const world = await Physics.world2d({ fps: FPS, frames: 30, gravity: 0 });
		const left = world.body(card("l", 300, 500));
		const right = world.body(card("r", 1400, 500));
		const still = world.body(card("s", 800, 0));
		// Away from x = 960, only for the first two bodies.
		world.field((s) => [s.x < 960 ? -1200 : 1200, 0], {
			bodies: [left, right],
		});
		world.simulate();
		expect(at(left.vx, 29)).toBeLessThan(-1000);
		expect(at(right.vx, 29)).toBeGreaterThan(1000);
		expect(at(still.vx, 29)).toBe(0);
		// A field is not a contact: no impacts.
		expect(at(left.impact, 29)).toBe(0);
	});

	it("rejects layers without a position and locks after simulating", async () => {
		const world = await Physics.world2d({ fps: FPS, frames: 2 });
		expect(() => world.body(Layer.box({ width: 10, height: 10 }))).toThrow(
			/x.*y/,
		);
		const b = world.body(card("a", 0, 0));
		// Holding a signal is fine; reading a value runs the simulation and locks.
		const y = b.y;
		world.body(card("b", 0, 0));
		at(y, 0);
		expect(() => world.body(card("c", 0, 0))).toThrow(/already started/);
	});
});

describe("live worlds", () => {
	/** A stand-in composition: collects prepare hooks, records which frames were prepared. */
	function host() {
		const hooks: Array<(ctx: { frame: number }) => Promise<void> | void> = [];
		const prepared: number[] = [];
		return {
			prepared,
			onPrepareFrame(cb: (ctx: { frame: number }) => Promise<void> | void) {
				hooks.push(cb);
			},
			async prepareVision(frame: number) {
				prepared.push(frame);
			},
			async render(frame: number) {
				for (const h of hooks) await h({ frame });
			},
		};
	}

	async function scene() {
		const world = await Physics.world2d({ fps: FPS, frames: 60 });
		world.walls({ width: 1920, height: 1080 });
		const layers = Array.from({ length: 6 }, (_, i) =>
			card(`c${i}`, 300 + i * 200, -100 - i * 150, { rotation: i * 11 }),
		);
		const bodies = layers.map((l, i) => world.body(l, { startFrame: i * 3 }));
		world.force(bodies[0], { x: (f) => (f > 20 ? 900 : 0) });
		return { world, layers, bodies };
	}

	it("steps on demand and matches simulate() exactly, in any request order", async () => {
		const batch = await scene();
		batch.world.simulate();

		const live = await scene();
		const comp = host();
		live.world.live(comp);
		// Layers are bound before anything is simulated.
		expect(tracksOf(live.layers[0]).map((t) => t.source?.type)).toEqual([
			"signal",
			"signal",
			"signal",
		]);
		await comp.render(40);
		await comp.render(10); // scrubbing back: already simulated
		await comp.render(59);
		expect(comp.prepared).toEqual(Array.from({ length: 60 }, (_, f) => f));

		for (let i = 0; i < batch.bodies.length; i++) {
			for (const f of [0, 10, 33, 59]) {
				expect(at(live.bodies[i].x, f)).toBe(at(batch.bodies[i].x, f));
				expect(at(live.bodies[i].rotation, f)).toBe(
					at(batch.bodies[i].rotation, f),
				);
				expect(at(live.bodies[i].impact, f)).toBe(
					at(batch.bodies[i].impact, f),
				);
			}
		}
		expect(live.world.collisions.length).toBe(batch.world.collisions.length);
	});

	it("holds the start pose for frames not simulated yet", async () => {
		const { world, bodies } = await scene();
		const comp = host();
		world.live(comp);
		await comp.render(5);
		expect(at(bodies[0].y, 30)).toBe(-100);
		expect(at(bodies[0].y, 5)).toBeGreaterThan(-100);
	});

	it("waits for extra inputs before each frame and locks the world", async () => {
		const { world } = await scene();
		const comp = host();
		const seen: number[] = [];
		world.live(comp, { inputs: [{ ready: async (f) => void seen.push(f) }] });
		await comp.render(3);
		expect(seen).toEqual([0, 1, 2, 3]);
		expect(() => world.simulate()).toThrow(/live/);
		expect(() => world.body(card("late", 0, 0))).toThrow(/already started/);
	});
});

describe("Physics.world3d", () => {
	it("drops a sphere and a box onto the ground", async () => {
		const world = await Physics.world3d({ fps: FPS, frames: 120 });
		world.ground({ y: 600 });
		const sphere = Layer3D.sphere({ id: "s", radius: 80, x: 0, y: 0, z: 0 });
		const box = Layer3D.roundedBox({
			id: "b",
			width: 160,
			height: 100,
			depth: 160,
			radius: 10,
			x: 400,
			y: -200,
			z: 0,
			rotateZ: 20,
		});
		const s = world.body(sphere, { restitution: 0, angularDamping: 2 });
		const b = world.body(box, { restitution: 0 });
		world.simulate();
		expect(at(s.y, 119)).toBeCloseTo(520, 0);
		expect(at(b.y, 119)).toBeCloseTo(550, 0);
		expect(Math.abs(at(b.rotateZ, 119)) % 90).toBeLessThan(1);
		expect(tracksOf(box).map((t) => t.prop)).toEqual([
			"x",
			"y",
			"z",
			"rotateX",
			"rotateY",
			"rotateZ",
		]);
	});

	it("drops thin rounded slabs (rounding never empties the core)", async () => {
		const world = await Physics.world3d({ fps: FPS, frames: 40 });
		world.ground({ y: 800 });
		const slab = world.body(
			Layer3D.roundedBox({
				width: 300,
				height: 120,
				depth: 34,
				radius: 18,
				x: 400,
				y: 100,
				z: 0,
			}),
			{ lockRotation: true },
		);
		const pill = await Physics.world2d({ fps: FPS, frames: 40 });
		pill.ground({ y: 800 });
		const p = pill.body(card("pill", 0, 100, { borderRadius: 50 }));
		world.simulate();
		pill.simulate();
		expect(at(slab.y, 39)).toBeGreaterThan(400);
		expect(at(p.y, 39)).toBeGreaterThan(400);
	});

	it("locks rotation per axis", async () => {
		const world = await Physics.world3d({ fps: FPS, frames: 60 });
		world.ground({ y: 600 });
		const card3 = world.body(
			Layer3D.roundedBox({
				width: 200,
				height: 60,
				depth: 30,
				x: 0,
				y: 0,
				z: 0,
				rotateZ: 30,
				rotateX: 0,
			}),
			{ lockRotation: { x: true, y: true }, angularVelocity: [200, 200, 0] },
		);
		world.simulate();
		expect(Math.abs(at(card3.rotateX, 59))).toBeLessThan(0.01);
		expect(Math.abs(at(card3.rotateY, 59))).toBeLessThan(0.01);
	});

	it("converts rotations with the renderer's Euler order", () => {
		for (const e of [
			[10, 20, 30],
			[-75, 40, 170],
			[0, 89, 0],
			[120, -30, -60],
		] as const) {
			const back = eulerFromQuat(quatFromEuler(e[0], e[1], e[2]), [
				e[0],
				e[1],
				e[2],
			]);
			expect(back[0]).toBeCloseTo(e[0], 3);
			expect(back[1]).toBeCloseTo(e[1], 3);
			expect(back[2]).toBeCloseTo(e[2], 3);
		}
	});

	it("is deterministic", async () => {
		const run = async () => {
			const world = await Physics.world3d({ fps: FPS, frames: 90 });
			world.walls({ x: 0, y: 0, z: 0, width: 800, height: 800, depth: 800 });
			const bodies = Array.from({ length: 10 }, (_, i) =>
				world.body(
					Layer3D.roundedBox({
						width: 80,
						height: 80,
						depth: 80,
						x: (i % 3) * 60 - 60,
						y: -300 - i * 100,
						z: 0,
						rotateX: i * 17,
					}),
				),
			);
			world.simulate();
			return bodies.flatMap((b) => [
				at(b.x, 89),
				at(b.y, 89),
				at(b.rotateY, 89),
			]);
		};
		expect(await run()).toEqual(await run());
	});
});

describe("helpers", () => {
	it("unwraps angles across ±180", () => {
		expect(unwrapDegrees(170, -170)).toBe(190);
		expect(unwrapDegrees(-350, 5)).toBe(-355);
	});

	it("keeps only the keyframes a linear track needs", () => {
		const line = Array.from({ length: 50 }, (_, i) => i * 2);
		expect(simplifyKeys(line, 0.1).map((k) => k[0])).toEqual([0, 49]);
		const vee = Array.from({ length: 21 }, (_, i) => Math.abs(i - 10));
		expect(simplifyKeys(vee, 0.1).map((k) => k[0])).toEqual([0, 10, 20]);
	});
});