Skip to content

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

12.0 KB
Raw Blame
/**
 * Voronoi destruction: a mesh layer stays whole (a fixed collider of its
 * own shape) until its fracture frame, or until a body hits it, then its
 * pieces wake as rigid bodies and fly apart. The pieces' recorded poses go
 * into the node (`fracture3d.track`), where the renderer turns them into
 * the joints of one rigidly skinned mesh.
 */
import {
	type AnimatedLayer,
	type Fracture3DSpec,
	type LayoutNode,
	sampleLayerProp,
} from "@framefields/compositions/program";
import {
	createRandom,
	fractureModel,
	type Mat4,
	Matrix4Math,
	type Model3DData,
} from "@framefields/webgpu-renderers";
import type { Quat, Vec3 } from "./backend.js";
import {
	type Body3DOptions,
	type LayerLike,
	type PhysicsBody3D,
	type PhysicsWorld3D,
	quatFromEuler,
	rotateByQuat,
} from "./world3d.js";

export interface Fracture3DOptions {
	/** Voronoi pieces (2..256). Default 48. */
	cells?: number;
	/** Same seed, same pieces. Default 1. */
	seed?: number;
	/** Scene point (px) the pieces crowd around and fly from. */
	impactPoint?: [number, number, number];
	/**
	 * Composition frame the layer breaks at, or `"onImpact"` (default): the
	 * first frame a body hits it. An animated layer (position, rotation)
	 * collides along its path while whole and breaks where it is, its pieces
	 * carrying its motion.
	 */
	fractureFrame?: number | "onImpact";
	/** Color of the faces the break exposes. Default "#d8d2c4". */
	interiorColor?: string;
	/** Roughness of the exposed faces. Default 0.9. */
	interiorRoughness?: number;
	/** Outward speed at the impact point, px/s, fading with distance. Default 0. */
	explosionSpeed?: number;
	/** Random tumble, degrees per second. Default a third of `explosionSpeed`. */
	spin?: number;
	/** Share of the hitting body's velocity the nearest pieces take. Default 0.35. */
	momentumTransfer?: number;
	density?: number;
	friction?: number;
	restitution?: number;
}

/** A fractured layer: its pieces, and the collider that stands in for it while whole. */
export class Fracture3D {
	/** @internal */ brokeAt?: number;

	/** @internal */
	constructor(
		readonly node: LayoutNode,
		readonly pieces: readonly PhysicsBody3D[],
		readonly intact: PhysicsBody3D,
		private readonly world: PhysicsWorld3D,
	) {}

	/** Composition frame it broke at (after simulating); undefined if it never did. */
	get frame(): number | undefined {
		return this.brokeAt === undefined
			? undefined
			: this.world.startFrame + this.brokeAt;
	}
}

const NEVER = Number.MAX_SAFE_INTEGER;
const num = (v: unknown, fallback: number) =>
	typeof v === "number" && Number.isFinite(v) ? v : fallback;

interface NodePose {
	position: Vec3;
	rotation: Vec3;
	scale: Vec3;
	matrix: Mat4;
}

/** The node's placement as the renderer builds it: T · Rz · Ry · Rx · S. */
function nodePose(t: LayerLike): NodePose {
	const position: Vec3 = [num(t.x, 0), num(t.y, 0), num(t.z, 0)];
	const rotation: Vec3 = [
		num(t.rotateX, 0),
		num(t.rotateY, 0),
		num(t.rotateZ, num(t.rotation, 0)),
	];
	const s = num(t.scale, 1);
	const scale: Vec3 = [
		s * num(t.scaleX, 1),
		s * num(t.scaleY, 1),
		s * num(t.scaleZ, 1),
	];
	const rad = (d: number) => (d * Math.PI) / 180;
	let m = Matrix4Math.translate(...position);
	m = Matrix4Math.multiply(m, Matrix4Math.rotateZ(rad(rotation[2])));
	m = Matrix4Math.multiply(m, Matrix4Math.rotateY(rad(rotation[1])));
	m = Matrix4Math.multiply(m, Matrix4Math.rotateX(rad(rotation[0])));
	m = Matrix4Math.multiply(m, Matrix4Math.scale(...scale));
	return { position, rotation, scale, matrix: m };
}

const apply = (m: Mat4, p: Vec3): Vec3 => [
	m[0] * p[0] + m[4] * p[1] + m[8] * p[2] + m[12],
	m[1] * p[0] + m[5] * p[1] + m[9] * p[2] + m[13],
	m[2] * p[0] + m[6] * p[1] + m[10] * p[2] + m[14],
];

const SCALE_PROPS = ["scale", "scaleX", "scaleY", "scaleZ"];

/** The animated props among `props` (tracks on them). */
function animatedProps(node: LayerLike, props: readonly string[]): string[] {
	const tracks = (node.animation as AnimatedLayer["animation"])?.tracks ?? [];
	return props.filter((p) => tracks.some((t) => t.prop === p));
}

/** Rigid pieces cannot change size: a fractured layer's scale holds still. */
function assertRigid(node: LayerLike): void {
	const scaling = animatedProps(node, SCALE_PROPS);
	if (!scaling.length) return;
	const id = typeof node.id === "string" ? ` "${node.id}"` : "";
	throw new Error(
		`Physics.fracture: layer${id} animates ${scaling.join(", ")}; rigid pieces cannot change size. Keep a fractured layer's scale still (position and rotation may animate).`,
	);
}

/**
 * The layer's animated position and rotation as kinematic drivers, sampled
 * as the compositor draws them (GSAP eases, stepped timing, signals), so the
 * stand-in collider is where the layer is; undefined when it holds still.
 * Read lazily: animation added after `fracture()` counts.
 */
function followLayer(
	node: LayerLike,
	fps: number,
): Body3DOptions["follow"] | undefined {
	const layer = node as AnimatedLayer;
	const at = (prop: string) => (frame: number) =>
		sampleLayerProp(layer, prop, frame, fps);
	// The renderer reads rotateZ, falling back to the 2D `rotation`.
	const rotateZ = (frame: number) =>
		animatedProps(node, ["rotateZ"]).length || typeof node.rotateZ === "number"
			? sampleLayerProp(layer, "rotateZ", frame, fps)
			: sampleLayerProp(layer, "rotation", frame, fps);
	return {
		x: at("x"),
		y: at("y"),
		z: at("z"),
		rotateX: at("rotateX"),
		rotateY: at("rotateY"),
		rotateZ,
	};
}

const MOVING_PROPS = [
	"x",
	"y",
	"z",
	"rotateX",
	"rotateY",
	"rotateZ",
	"rotation",
];

/** @internal */
export function createFracture(
	world: PhysicsWorld3D,
	target: LayoutNode,
	options: Fracture3DOptions,
): Fracture3D {
	const node = target as unknown as LayerLike;
	const model = node.modelData as Model3DData | undefined;
	if (!model?.meshes?.length) {
		const id = typeof node.id === "string" ? ` "${node.id}"` : "";
		throw new Error(
			`Physics.fracture: layer${id} has no mesh. Fracture a Layer3D primitive, extruded text, or a model node that carries modelData.`,
		);
	}
	assertRigid(node);
	const pose = nodePose(node);
	const toObject = Matrix4Math.invert(pose.matrix) ?? Matrix4Math.identity();
	const spec: Fracture3DSpec = {
		cells: Math.max(2, Math.min(256, Math.round(options.cells ?? 48))),
		seed: options.seed ?? 1,
		...(options.impactPoint && {
			impactPoint: apply(toObject, options.impactPoint),
		}),
		...(options.interiorColor && { interiorColor: options.interiorColor }),
		...(options.interiorRoughness !== undefined && {
			interiorRoughness: options.interiorRoughness,
		}),
	};
	const { cells } = fractureModel(model, spec);
	node.fracture3d = spec;

	// While whole, a collider of its own shape stands in: fixed, or kinematic
	// along the layer's animation.
	const moving = animatedProps(node, MOVING_PROPS).length > 0;
	const intact = world.body(
		target,
		moving
			? {
					type: "kinematic",
					output: "none",
					follow: followLayer(node, world.fps),
				}
			: { type: "fixed", output: "none" },
	);
	const pieces = cells.map((cell) =>
		world.shapedBody(
			undefined,
			apply(pose.matrix, cell.centroid),
			pose.rotation,
			{
				kind: "hull",
				// A hair smaller than the piece, so neighbors start apart.
				points: cell.hull.map((v, i) => v * pose.scale[i % 3]! * 0.97),
			},
			{
				type: "dynamic",
				startFrame: NEVER,
				output: "none",
				density: options.density,
				friction: options.friction,
				restitution: options.restitution ?? 0.2,
			},
		),
	);
	const fracture = new Fracture3D(target, pieces, intact, world);
	const radius = model.bounds.boundingSphereRadius * Math.max(...pose.scale);

	world.onStep((f, pairs) => {
		if (fracture.brokeAt !== undefined) return;
		const ff = options.fractureFrame ?? "onImpact";
		const hit = pairs.find(
			([a, b]) =>
				(a === intact && b.type === "dynamic") ||
				(b === intact && a.type === "dynamic"),
		);
		const hitter = hit ? (hit[0] === intact ? hit[1] : hit[0]) : undefined;
		const due =
			ff === "onImpact" ? Boolean(hitter) : f >= ff - world.startFrame;
		if (!due) return;
		fracture.brokeAt = f;
		intact.sim.setEnabled(false);
		breakApart(world, pieces, options, radius, intact, pose, hitter, f);
	});
	world.onSimulated(() => {
		assertRigid(node);
		spec.track = recordTrack(pieces, world.startFrame + world.frames);
	});
	return fracture;
}

/** Where the stand-in is and how it moves (px, quaternion, px/s, rad/s). */
function standInState(world: PhysicsWorld3D, intact: PhysicsBody3D) {
	const ppm = world.pixelsPerMeter;
	return {
		position: intact.sim.position().map((v) => v * ppm) as Vec3,
		rotation: intact.sim.rotation(),
		velocity: intact.sim.velocity().map((v) => v * ppm) as Vec3,
		spin: intact.sim.angularVelocity() as Vec3,
	};
}

/**
 * Wakes every piece where the layer is now (the stand-in's pose, which
 * follows its animation), carrying the layer's own motion, plus a burst
 * outward from the impact and some of the hitter's momentum.
 */
function breakApart(
	world: PhysicsWorld3D,
	pieces: readonly PhysicsBody3D[],
	options: Fracture3DOptions,
	radius: number,
	intact: PhysicsBody3D,
	rest: NodePose,
	hitter: PhysicsBody3D | undefined,
	frame: number,
): void {
	const ppm = world.pixelsPerMeter;
	const layer = standInState(world, intact);
	const q0 = quatFromEuler(...rest.rotation);
	const undoRest: Quat = [-q0[0], -q0[1], -q0[2], q0[3]];
	const hitAt = hitter?.sim.position().map((v) => v * ppm) as Vec3 | undefined;
	const transfer = options.momentumTransfer ?? 0.35;
	// The stand-in collider just bounced the hitter; it should have gone on
	// through, handing some of its momentum to the pieces.
	const hitVel: Vec3 = [0, 0, 0];
	if (hitter) {
		const at = world.startFrame + frame - 1;
		const rec = hitter.recording;
		hitVel[0] = rec.channel("vx")[at] ?? 0;
		hitVel[1] = rec.channel("vy")[at] ?? 0;
		hitVel[2] = rec.channel("vz")[at] ?? 0;
		hitter.sim.setVelocity(
			hitVel.map((v) => (v * (1 - transfer)) / ppm) as Vec3,
			hitter.sim.angularVelocity(),
		);
	}
	const impact = options.impactPoint ?? hitAt ?? layer.position;
	const speed = options.explosionSpeed ?? 0;
	const spin = options.spin ?? speed / 3;
	const rand = createRandom((options.seed ?? 1) * 7717 + 3);
	for (const piece of pieces) {
		// The piece rests at the layer's authored pose: move it with the layer.
		const c = piece.center();
		const local = rotateByQuat(
			[
				c[0] - rest.position[0],
				c[1] - rest.position[1],
				c[2] - rest.position[2],
			],
			undoRest,
		);
		const arm = rotateByQuat(local, layer.rotation);
		const p: Vec3 = [
			layer.position[0] + arm[0],
			layer.position[1] + arm[1],
			layer.position[2] + arm[2],
		];
		// Rigid motion of the layer at this point: v + ω × r.
		const w0 = layer.spin;
		const carried: Vec3 = [
			layer.velocity[0] + w0[1] * arm[2] - w0[2] * arm[1],
			layer.velocity[1] + w0[2] * arm[0] - w0[0] * arm[2],
			layer.velocity[2] + w0[0] * arm[1] - w0[1] * arm[0],
		];
		const d: Vec3 = [p[0] - impact[0], p[1] - impact[1], p[2] - impact[2]];
		const dist = Math.hypot(...d) || 1;
		const falloff = 1 / (1 + (dist / Math.max(1, radius)) ** 2);
		const v = d.map(
			(x, i) =>
				carried[i]! +
				(x / dist) * speed * falloff +
				hitVel[i]! * transfer * falloff,
		) as Vec3;
		const axis = [rand() - 0.5, rand() - 0.5, rand() - 0.5];
		const len = Math.hypot(...axis) || 1;
		const w = axis.map(
			(a, i) => (a / len) * spin * (0.5 + rand()) + (w0[i]! * 180) / Math.PI,
		) as Vec3;
		piece.wake(frame, v, w, { position: p, rotation: layer.rotation });
	}
}

/** Every piece's pose per composition frame: [x, y, z, qx, qy, qz, qw] each. */
function recordTrack(
	pieces: readonly PhysicsBody3D[],
	frames: number,
): number[] {
	const channels = pieces.map((b) =>
		["x", "y", "z", "qx", "qy", "qz", "qw"].map((c) => b.recording.channel(c)),
	);
	const out: number[] = new Array(frames * pieces.length * 7);
	let k = 0;
	for (let f = 0; f < frames; f++) {
		for (const ch of channels) {
			for (let c = 0; c < 7; c++) {
				const v = ch[c]![f] ?? 0;
				// 1e-5 px and 1e-7 per quaternion component: compact JSON, and
				// pieces resting side by side stay sealed (no sub-pixel cracks).
				out[k++] =
					c < 3 ? Math.round(v * 1e5) / 1e5 : Math.round(v * 1e7) / 1e7;
			}
		}
	}
	return out;
}