A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file rigRebind.ts
* @brief Changing which bone is which after a rig is bound: a new parent, a whole skeleton from another rig, and what the paths a clip names become.
*
* @details A bone has three names. Its index is what a vertex follows and what joint of the mesh it is, and it moves whenever the list is
* reordered. Its path (`upper/lower`) is what a clip names it by, and it moves when it or a bone above it is renamed or reparented.
* Its `id` never moves: it is what the prefab names the bone's entity by, so what a scene added to one bone (an IK2D, a sword) stays
* on that bone through every edit here. Every function in this file keeps vertices where they are in rig space: rebinding
* changes what follows what, never what the character looks like at rest.
*/
import { ensureRigBoneIds, rigBoneId, rigBoneWorlds, type RigBone, type RigSource } from './rigSource';
/** Each bone's path, as a clip names it below the rig's root. @experimental */
export function rigBonePaths(bones: readonly RigBone[]): string[] {
const out: string[] = [];
bones.forEach((b, i) => { out[i] = b.parent >= 0 && b.parent < i ? `${out[b.parent]}/${b.name}` : b.name; });
return out;
}
/** Whether `bone` is `ancestor` or below it. */
function isUnder(bones: readonly RigBone[], bone: number, ancestor: number): boolean {
for (let at = bone; at >= 0; at = bones[at]!.parent) if (at === ancestor) return true;
return false;
}
/** Reorders bones so every parent comes first, keeping the order otherwise; `order[newIndex] = oldIndex`. */
function parentsFirst(bones: readonly RigBone[]): number[] {
const order: number[] = [], placed = new Set<number>();
const place = (i: number): void => {
if (placed.has(i)) return;
const parent = bones[i]!.parent;
if (parent >= 0) place(parent);
placed.add(i);
order.push(i);
};
bones.forEach((_, i) => place(i));
return order;
}
/** Puts the bones in `order` (`order[newIndex] = oldIndex`), carrying parents and every vertex's weights along. */
function reorderBones(rig: RigSource, order: readonly number[]): void {
const newIndexOf = new Map(order.map((old, i) => [old, i]));
const at = (old: number): number => newIndexOf.get(old)!;
rig.bones = order.map((old) => {
const b = rig.bones[old]!;
return { ...b, parent: b.parent >= 0 ? at(b.parent) : -1 };
});
for (const part of rig.parts) {
part.weights = part.weights.map((w) => w.map((v, i) => (i % 2 === 0 ? at(v) : v)));
}
}
/** Why a bone cannot take this parent, or null when it can. @experimental */
export function rigParentProblem(rig: RigSource, index: number, parent: number): string | null {
if (!rig.bones[index]) return 'there is no such bone';
if (parent < -1 || parent >= rig.bones.length) return 'there is no such parent';
if (parent >= 0 && isUnder(rig.bones, parent, index)) return parent === index ? 'a bone cannot be its own parent' : 'that bone hangs below this one';
return null;
}
/**
* Hangs a bone (and everything below it) off another, or makes it a root with -1, where it stands now: its place and rotation are
* re-expressed in the new parent's space, so nothing moves at rest. The list is reordered when the new parent came after it, and the
* weights with it; ids stay, so the scene keeps what it added to each bone. Returns the bone's index afterwards.
* Throws on a parent {@link rigParentProblem} refuses.
* @experimental
*/
export function setRigBoneParent(rig: RigSource, index: number, parent: number): number {
const problem = rigParentProblem(rig, index, parent);
if (problem) throw new Error(`cannot reparent: ${problem}`);
ensureRigBoneIds(rig);
const bone = rig.bones[index]!;
if (bone.parent === parent) return index;
const worlds = rigBoneWorlds(rig.bones), w = worlds[index]!;
const up = parent >= 0 ? worlds[parent]! : { x: 0, y: 0, rotation: 0 };
const c = Math.cos(up.rotation), s = Math.sin(up.rotation), dx = w.x - up.x, dy = w.y - up.y;
bone.x = c * dx + s * dy;
bone.y = -s * dx + c * dy;
bone.rotation = w.rotation - up.rotation;
bone.parent = parent;
const id = bone.id!;
reorderBones(rig, parentsFirst(rig.bones));
return rig.bones.findIndex(b => b.id === id);
}
/** What {@link rebindRigToSkeleton} did, bone by bone of the rig as it was. @experimental */
export interface RigRebindReport {
/** Old bone names that found a bone of the same name. */
matched: string[];
/** Old bone names that did not, and the new bone their vertices went to. */
moved: { from: string; to: string }[];
}
/**
* Binds the rig to another skeleton, a list of bones as a `.esrig` holds them, matched by name. The rig's bones become a copy of
* `skeleton`, ids included, so two rigs bound to one skeleton have entities of the same ids and names and play the same clips.
* A vertex keeps its weights on every bone that found its namesake. A bone that did not hands them to its nearest ancestor that did,
* or, with none, to the new bone whose head is closest to its own. Vertices stay where they are in rig space; what moves is the bind
* pose, so the skin rests where it did against whatever pose the new skeleton rests in.
* @experimental
*/
export function rebindRigToSkeleton(rig: RigSource, skeleton: readonly RigBone[]): RigRebindReport {
if (skeleton.length === 0) throw new Error('cannot rebind: the skeleton has no bones');
const next = skeleton.map(b => ({ ...b }));
const nextRig: RigSource = { ...rig, bones: next, parts: [] };
ensureRigBoneIds(nextRig);
const byName = new Map(next.map((b, i) => [b.name, i]));
const oldWorlds = rigBoneWorlds(rig.bones), newWorlds = rigBoneWorlds(next);
const report: RigRebindReport = { matched: [], moved: [] };
const target = rig.bones.map((b, i) => {
const same = byName.get(b.name);
if (same !== undefined) { report.matched.push(b.name); return same; }
let to = -1;
for (let up = b.parent; up >= 0 && to < 0; up = rig.bones[up]!.parent) to = byName.get(rig.bones[up]!.name) ?? -1;
if (to < 0) {
const at = oldWorlds[i]!;
let best = Infinity;
newWorlds.forEach((w, j) => {
const d = Math.hypot(w.x - at.x, w.y - at.y);
if (d < best) { best = d; to = j; }
});
}
report.moved.push({ from: b.name, to: next[to]!.name });
return to;
});
for (const part of rig.parts) {
part.weights = part.weights.map((w) => {
const merged = new Map<number, number>();
for (let i = 0; i < w.length; i += 2) {
const bone = target[w[i]!]!;
merged.set(bone, (merged.get(bone) ?? 0) + w[i + 1]!);
}
return [...merged].flat();
});
}
rig.bones = next;
return report;
}
/** How the paths a clip names changed between two saves of one rig, by bone id. @experimental */
export interface RigPathChanges {
/** Old path to new, for every bone still there whose path is not what it was. */
renamed: Map<string, string>;
/** Paths of bones that are gone. */
removed: string[];
/** Every path the rig had before: what a clip must name to be one of this rig's. */
before: Set<string>;
}
/** Compares two saves of a rig. Bones without ids are matched by index, which is what they were saved as. @experimental */
export function rigPathChanges(before: readonly RigBone[], after: readonly RigBone[]): RigPathChanges {
const oldPaths = rigBonePaths(before), newPaths = rigBonePaths(after);
const newById = new Map(after.map((_, i) => [rigBoneId(after, i), newPaths[i]!]));
const renamed = new Map<string, string>(), removed: string[] = [];
before.forEach((_, i) => {
const now = newById.get(rigBoneId(before, i));
if (now === undefined) removed.push(oldPaths[i]!);
else if (now !== oldPaths[i]) renamed.set(oldPaths[i]!, now);
});
return { renamed, removed, before: new Set(oldPaths) };
}
/**
* Where a path named before the change points now. A path below a bone (a sword parented to `arm` in the scene, `arm/sword`) follows the
* deepest bone it starts with. Null when that bone is gone; the path itself when nothing it starts with changed.
* @experimental
*/
export function remapRigPath(path: string, changes: RigPathChanges): string | null {
if (!path) return path;
const parts = path.split('/');
for (let n = parts.length; n > 0; n--) {
const head = parts.slice(0, n).join('/');
if (!changes.before.has(head)) continue;
if (changes.removed.includes(head)) return null;
const now = changes.renamed.get(head);
return now === undefined ? path : [now, ...parts.slice(n)].join('/');
}
return path;
}