Skip to content

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

6.8 KB
Raw Blame
/**
 * Skeletons for rigged characters: joints placed at their rest positions in
 * model space (glTF: +y up, the character faces +z, its left side at +x),
 * built bone by bone or from a proportioned preset, with left/right
 * mirroring. Joints rest unrotated unless given an `orient`, so a joint's
 * local axes are the model's: `pose: { LeftArm: { rotateZ: … } }` turns
 * about the same axis on every joint, and `aim` / retargeting find a bone's
 * direction from its child. Rigs authored elsewhere (DNA files) bring rest
 * orientations, which the writer keeps.
 */

export type Vec3 = [number, number, number];
/** A rotation as a unit quaternion x, y, z, w. */
export type Quat = [number, number, number, number];

const IDENTITY: Quat = [0, 0, 0, 1];

/** Hamilton product a · b (b applied first). */
export function quatMultiply(a: Quat, b: Quat): Quat {
	return [
		a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1],
		a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0],
		a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3],
		a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2],
	];
}

export function quatConjugate(q: Quat): Quat {
	return [-q[0], -q[1], -q[2], q[3]];
}

/** `v` turned by `q`. */
export function quatRotate(q: Quat, v: Vec3): Vec3 {
	const r = quatMultiply(
		quatMultiply(q, [v[0], v[1], v[2], 0]),
		quatConjugate(q),
	);
	return [r[0], r[1], r[2]];
}

export interface JointSpec {
	name: string;
	/** Rest position in model space. */
	at: Vec3;
	parent?: string;
	/** Rest orientation in model space. Default: unrotated. */
	orient?: Quat;
	/** Free data written to the joint's glTF node `extras`. */
	extras?: Record<string, unknown>;
}

export interface Joint extends JointSpec {
	readonly index: number;
}

export interface MirrorOptions {
	/** Name fragment of the joints to copy. Default "Left". */
	from?: string;
	/** What it becomes on the copies. Default "Right". */
	to?: string;
	/** Model axis to reflect across. Default "x" (left ↔ right). */
	axis?: "x" | "y" | "z";
}

const AXIS = { x: 0, y: 1, z: 2 } as const;

export class Skeleton {
	private readonly list: Joint[] = [];
	private readonly byName = new Map<string, Joint>();

	/** Adds a joint; a parent must already exist. */
	add(name: string, spec: Omit<JointSpec, "name">): this {
		if (this.byName.has(name))
			throw new Error(`skeleton: joint "${name}" already exists`);
		if (spec.parent !== undefined && !this.byName.has(spec.parent))
			throw new Error(
				`skeleton: joint "${name}" has unknown parent "${spec.parent}"`,
			);
		if (!spec.at.every(Number.isFinite))
			throw new Error(`skeleton: joint "${name}" has a non-finite position`);
		if (spec.orient && !spec.orient.every(Number.isFinite))
			throw new Error(`skeleton: joint "${name}" has a non-finite orientation`);
		const joint: Joint = {
			name,
			at: [spec.at[0], spec.at[1], spec.at[2]],
			...(spec.parent === undefined ? {} : { parent: spec.parent }),
			...(spec.orient ? { orient: normalized(spec.orient) } : {}),
			...(spec.extras ? { extras: spec.extras } : {}),
			index: this.list.length,
		};
		this.list.push(joint);
		this.byName.set(name, joint);
		return this;
	}

	/**
	 * A chain of joints through `points`, named `${base}1`, `${base}2`, …
	 * (tails, braids, cloak columns, fingers). Returns the names, root first.
	 */
	chain(
		base: string,
		points: readonly Vec3[],
		options: { parent?: string; start?: number } = {},
	): string[] {
		const start = options.start ?? 1;
		let parent = options.parent;
		return points.map((at, i) => {
			const name = `${base}${start + i}`;
			this.add(name, { at, ...(parent === undefined ? {} : { parent }) });
			parent = name;
			return name;
		});
	}

	/**
	 * Copies every joint whose name contains `from` (default "Left") across
	 * the `axis` (default x), renamed with `to` (default "Right"). A copy's
	 * parent is the mirrored parent where there is one, else the same parent
	 * (`LeftShoulder` under `Spine2` becomes `RightShoulder` under `Spine2`).
	 */
	mirror(options: MirrorOptions = {}): this {
		const from = options.from ?? "Left";
		const to = options.to ?? "Right";
		const axis = AXIS[options.axis ?? "x"];
		const sources = this.list.filter((j) => j.name.includes(from));
		if (!sources.length)
			throw new Error(`skeleton: no joint names contain "${from}" to mirror`);
		const rename = (n: string) => n.split(from).join(to);
		for (const j of sources) {
			const at: Vec3 = [j.at[0], j.at[1], j.at[2]];
			at[axis] = -at[axis];
			const parent =
				j.parent === undefined
					? undefined
					: j.parent.includes(from)
						? rename(j.parent)
						: j.parent;
			// Reflected across the axis: keep that component, negate the others.
			const orient = j.orient?.map((c, k) =>
				k === axis || k === 3 ? c : -c,
			) as Quat | undefined;
			this.add(rename(j.name), {
				at,
				...(parent === undefined ? {} : { parent }),
				...(orient ? { orient } : {}),
				...(j.extras ? { extras: j.extras } : {}),
			});
		}
		return this;
	}

	/** Joints in order: every parent before its children. */
	get joints(): readonly Joint[] {
		return this.list;
	}

	has(name: string): boolean {
		return this.byName.has(name);
	}

	joint(name: string): Joint {
		const j = this.byName.get(name);
		if (!j) throw new Error(`skeleton: no joint "${name}"`);
		return j;
	}

	children(name: string): Joint[] {
		return this.list.filter((j) => j.parent === name);
	}

	/** The rest position in the parent's frame (the glTF node translation). */
	local(name: string): Vec3 {
		const j = this.joint(name);
		if (j.parent === undefined) return [...j.at];
		const p = this.joint(j.parent);
		const d: Vec3 = [j.at[0] - p.at[0], j.at[1] - p.at[1], j.at[2] - p.at[2]];
		return p.orient ? quatRotate(quatConjugate(p.orient), d) : d;
	}

	/** The rest orientation in model space. */
	orientation(name: string): Quat {
		return this.joint(name).orient ?? IDENTITY;
	}

	/** The rest orientation in the parent's frame (the glTF node rotation). */
	localRotation(name: string): Quat {
		const j = this.joint(name);
		const own = j.orient ?? IDENTITY;
		if (j.parent === undefined) return own;
		return quatMultiply(quatConjugate(this.orientation(j.parent)), own);
	}

	/** Whether any joint rests rotated. */
	get oriented(): boolean {
		return this.list.some((j) => j.orient !== undefined);
	}

	/** Distance from a joint to its parent. */
	length(name: string): number {
		const [x, y, z] = this.local(name);
		return this.joint(name).parent === undefined ? 0 : Math.hypot(x, y, z);
	}

	/** Every joint moved by `offset` (e.g. to stand the feet on y = 0). */
	translate(offset: Vec3): this {
		for (const j of this.list) {
			j.at[0] += offset[0];
			j.at[1] += offset[1];
			j.at[2] += offset[2];
		}
		return this;
	}
}

function normalized(q: Quat): Quat {
	const l = Math.hypot(q[0], q[1], q[2], q[3]);
	if (!(l > 0)) throw new Error("skeleton: zero quaternion");
	return [q[0] / l, q[1] / l, q[2] / l, q[3] / l];
}