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
/**
* The claim: a constraint puts the joint it names WHERE it names, measured as a
* distance rather than as "the limb looks bent". It reads the pose this frame
* stated, not the world's record of the last one.
*/
import { describe, it, expect } from 'vitest';
import {
Animator, AnimatorControllerAPI, solveAnimatorIK, Pose,
type AnimatorData, type AnimatorControllerDef, type AnimatorIK,
} from '../src/animation';
import { Parent, Children, Name, Transform } from '../src/ecs/component';
import { q } from '../src/math/quat';
import { createTimelineMotionDriver, TIMELINE_MOTION } from '../src/timeline';
import { TimelineAPI } from '../src/timeline/TimelineControl';
import { WrapMode, TrackType, InterpType, type TimelineAsset } from '../src/timeline/TimelineTypes';
interface Vec3 { x: number; y: number; z: number }
function makeWorld() {
const store = new Map<unknown, Map<number, unknown>>();
const mapOf = (c: unknown) => {
let m = store.get(c);
if (!m) { m = new Map(); store.set(c, m); }
return m;
};
return {
insert(e: number, c: unknown, d: unknown) { mapOf(c).set(e, d); },
get(e: number, c: unknown) { return mapOf(c).get(e); },
has(e: number, c: unknown) { return mapOf(c).has(e); },
set(e: number, c: unknown, d: unknown) { mapOf(c).set(e, d); },
tryGet(e: number, c: unknown) { return mapOf(c).get(e) ?? null; },
update(e: number, c: unknown, edit: (d: any) => void) {
const d = mapOf(c).get(e); edit(d); mapOf(c).set(e, d);
},
getEntitiesWithComponents(comps: unknown[]) {
const [first, ...rest] = comps;
return [...mapOf(first).keys()].filter(e => rest.every(c => mapOf(c).has(e)));
},
} as any;
}
const RIG = 1;
const identity = () => ({ w: 1, x: 0, y: 0, z: 0 });
/**
* A straight arm along +X: rig → upper → fore → hand, each one unit out, plus a
* target the game moves. Straight on purpose — a limb already bent would hide a
* solver that only ever keeps the bend it found.
*/
function arm(world: any, targetAt: Vec3) {
const ids = { rig: RIG, upper: 2, fore: 3, hand: 4, target: 5, pole: 6 };
const node = (id: number, parent: number | null, name: string, at: Vec3) => {
world.insert(id, Name, { value: name });
world.insert(id, Transform, { position: at, rotation: identity(), scale: { x: 1, y: 1, z: 1 } });
if (parent !== null) {
world.insert(id, Parent, { entity: parent });
const held = world.tryGet(parent, Children) as { entities: number[] } | null;
world.insert(parent, Children, { entities: [...(held?.entities ?? []), id] });
}
};
node(ids.rig, null, 'Rig', { x: 0, y: 0, z: 0 });
node(ids.upper, ids.rig, 'Upper', { x: 1, y: 0, z: 0 });
node(ids.fore, ids.upper, 'Fore', { x: 1, y: 0, z: 0 });
node(ids.hand, ids.fore, 'Hand', { x: 1, y: 0, z: 0 });
node(ids.target, ids.rig, 'Target', targetAt);
node(ids.pole, ids.rig, 'Pole', { x: 1, y: 0, z: 2 });
return ids;
}
/** Where `childPath` ends up in rig space once `pose` is written to the world. */
function placeOf(world: any, path: string): Vec3 {
const names = path.split('/');
let at = { x: 0, y: 0, z: 0 };
let rot = identity();
let entity = RIG;
for (const name of names) {
const children = (world.tryGet(entity, Children) as { entities: number[] } | null)?.entities ?? [];
const found = children.find((c) => (world.tryGet(c, Name) as { value: string }).value === name);
entity = found!;
const t = world.get(entity, Transform) as { position: Vec3; rotation: any };
const offset = q.rotate(rot, t.position);
at = { x: at.x + offset.x, y: at.y + offset.y, z: at.z + offset.z };
rot = q.normalize(q.mul(rot, t.rotation));
}
return at;
}
const dist = (a: Vec3, b: Vec3) => Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z);
/** Solve `ik` against a fresh straight arm reaching for `targetAt`. */
function reach(targetAt: Vec3, ik: Partial<AnimatorIK> = {}): { world: any; hand: Vec3 } {
const world = makeWorld();
arm(world, targetAt);
const pose = new Pose();
pose.reset();
solveAnimatorIK(world, RIG, pose, [{
kind: 'two-bone', tip: 'Upper/Fore/Hand', target: 'Target', ...ik,
} as AnimatorIK], {});
pose.applyTo(world);
return { world, hand: placeOf(world, 'Upper/Fore/Hand') };
}
describe('two-bone IK', () => {
it('puts the tip on a target inside its reach', () => {
// The arm is 2 units long and the target is 1.5 away: a triangle exists,
// so the hand lands ON it, not near it.
const target = { x: 1.0, y: 1.118033988, z: 0 };
const { hand } = reach(target);
expect(dist(hand, target)).toBeLessThan(1e-3);
});
it('reaches as far as it can toward one it cannot get to', () => {
// Five units from a two-unit arm. The hand cannot arrive, so the limb
// straightens ALONG the line instead — a solver that quietly gave up
// would leave it where the clip put it.
const shoulder = { x: 1, y: 0, z: 0 };
const target = { x: 0, y: 5, z: 0 };
const { hand } = reach(target);
expect(dist(hand, shoulder)).toBeCloseTo(2, 2);
const unit = (a: Vec3, b: Vec3) => {
const d = { x: a.x - b.x, y: a.y - b.y, z: a.z - b.z };
const l = Math.hypot(d.x, d.y, d.z);
return { x: d.x / l, y: d.y / l, z: d.z / l };
};
const went = unit(hand, shoulder);
const wanted = unit(target, shoulder);
expect(went.x).toBeCloseTo(wanted.x, 3);
expect(went.y).toBeCloseTo(wanted.y, 3);
});
it('leaves the pose alone at weight zero', () => {
const { hand } = reach({ x: 1, y: 1, z: 0 }, { weight: 0 });
expect(hand).toEqual({ x: 3, y: 0, z: 0 });
});
it('goes part of the way at a partial weight', () => {
// Not "somewhere between": closer than untouched and further than solved,
// which is what makes this different from having no weight at all.
const target = { x: 1.0, y: 1.118033988, z: 0 };
const full = dist(reach(target).hand, target);
const half = dist(reach(target, { weight: 0.5 }).hand, target);
const none = dist(reach(target, { weight: 0 }).hand, target);
expect(full).toBeLessThan(half);
expect(half).toBeLessThan(none);
});
it('scales the authored weight by the parameter a game drives', () => {
const world = makeWorld();
arm(world, { x: 1.0, y: 1.118033988, z: 0 });
const pose = new Pose();
pose.reset();
solveAnimatorIK(world, RIG, pose, [{
kind: 'two-bone', tip: 'Upper/Fore/Hand', target: 'Target', parameter: 'plant',
}], { plant: 0 });
pose.applyTo(world);
expect(placeOf(world, 'Upper/Fore/Hand')).toEqual({ x: 3, y: 0, z: 0 });
});
it('bends toward the pole it was given', () => {
// The same target, two poles: the elbow has to end up on opposite sides,
// or the pole is a field nothing reads.
const target = { x: 1.0, y: 1.118033988, z: 0 };
const front = reach(target, { pole: 'Pole' });
const elbowFront = placeOf(front.world, 'Upper/Fore');
const world = makeWorld();
const ids = arm(world, target);
world.update(ids.pole, Transform, (t: any) => { t.position = { x: 1, y: 0, z: -2 }; });
const pose = new Pose();
pose.reset();
solveAnimatorIK(world, RIG, pose, [{
kind: 'two-bone', tip: 'Upper/Fore/Hand', target: 'Target', pole: 'Pole',
}], {});
pose.applyTo(world);
const elbowBack = placeOf(world, 'Upper/Fore');
expect(Math.sign(elbowFront.z)).not.toBe(Math.sign(elbowBack.z));
expect(Math.abs(elbowFront.z)).toBeGreaterThan(0.1);
});
it('states nothing for a joint that is not under the rig', () => {
const world = makeWorld();
arm(world, { x: 1, y: 1, z: 0 });
const pose = new Pose();
pose.reset();
solveAnimatorIK(world, RIG, pose, [{
kind: 'two-bone', tip: 'Upper/Nothing/Here', target: 'Target',
}], {});
expect(pose.tracks.filter((t) => t.touched.size > 0)).toHaveLength(0);
});
});
describe('look-at IK', () => {
it('turns the joint so its own axis points at the target', () => {
const world = makeWorld();
arm(world, { x: 1, y: 0, z: 3 });
const pose = new Pose();
pose.reset();
solveAnimatorIK(world, RIG, pose, [{
kind: 'look-at', tip: 'Upper/Fore/Hand', target: 'Target', axis: 'x',
}], {});
pose.applyTo(world);
// The hand sits at (3,0,0) and the target at (1,0,3): its +X must end up
// along (-2, 0, 3) normalized.
const hand = world.get(4, Transform) as { rotation: { w: number; x: number; y: number; z: number } };
const rot = hand.rotation;
const { w, x, y, z } = rot;
const facing = {
x: 1 - 2 * (y * y + z * z), y: 2 * (x * y + w * z), z: 2 * (x * z - w * y),
};
const want = { x: -2 / Math.hypot(2, 3), y: 0, z: 3 / Math.hypot(2, 3) };
expect(facing.x).toBeCloseTo(want.x, 3);
expect(facing.z).toBeCloseTo(want.z, 3);
});
});
describe('a constraint through the animator', () => {
/**
* A rig with a joint ABOVE the chain: Rig → Spine → Upper → Fore → Hand. What
* the spine does moves the shoulder, so where the arm can reach depends on the
* pose this frame — which is the only geometry where reading the world instead
* gives a different answer at all.
*/
function spined(world: any, targetAt: Vec3) {
const node = (id: number, parent: number | null, name: string, at: Vec3) => {
world.insert(id, Name, { value: name });
world.insert(id, Transform, { position: at, rotation: identity(), scale: { x: 1, y: 1, z: 1 } });
if (parent !== null) {
world.insert(id, Parent, { entity: parent });
const held = world.tryGet(parent, Children) as { entities: number[] } | null;
world.insert(parent, Children, { entities: [...(held?.entities ?? []), id] });
}
};
node(RIG, null, 'Rig', { x: 0, y: 0, z: 0 });
node(2, RIG, 'Spine', { x: 0, y: 1, z: 0 });
node(3, 2, 'Upper', { x: 1, y: 0, z: 0 });
node(4, 3, 'Fore', { x: 1, y: 0, z: 0 });
node(5, 4, 'Hand', { x: 1, y: 0, z: 0 });
node(6, RIG, 'Target', targetAt);
}
/** A clip turning the spine a quarter turn about Z, every frame. */
function turnsSpine(): TimelineAsset {
const key = (value: number) => ([
{ time: 0, value, inTangent: 0, outTangent: 0, interpolation: InterpType.Linear },
]);
return {
version: '1.2', type: 'timeline', duration: 10, wrapMode: WrapMode.Loop,
tracks: [{
type: TrackType.Property, component: 'Transform', childPath: 'Spine', name: 's',
channels: [
{ property: 'rotation.x', keyframes: key(0) },
{ property: 'rotation.y', keyframes: key(0) },
{ property: 'rotation.z', keyframes: key(-Math.SQRT1_2) },
{ property: 'rotation.w', keyframes: key(Math.SQRT1_2) },
],
}],
} as TimelineAsset;
}
it('bends the pose the layers just stated, not the world before them', () => {
// Spine turned: the shoulder is at the origin, the target 1.5 away and
// reachable. Read from the world, where it has not turned yet, the
// shoulder is at (1,1,0) and the target 2.7 away — out of reach.
const world = makeWorld();
const target = { x: 0, y: -1.5, z: 0 };
spined(world, target);
const timeline = new TimelineAPI();
timeline.registerAsset('turn.estimeline', turnsSpine());
const ctrl = new AnimatorControllerAPI();
ctrl.registerMotionDriver(TIMELINE_MOTION, createTimelineMotionDriver(timeline));
ctrl.registerController('rig', {
version: 2, parameters: [], initialState: 'Turn',
states: [{
name: 'Turn', transitions: [],
motion: { kind: TIMELINE_MOTION, clip: 'turn.estimeline', loop: true },
}],
ik: [{ kind: 'two-bone', tip: 'Spine/Upper/Fore/Hand', target: 'Target' }],
} as AnimatorControllerDef);
world.insert(RIG, Animator, {
controller: 'rig', avatar: '', currentState: '', layerStates: [], enabled: true,
} as AnimatorData);
ctrl.update(world, 0.016);
expect(dist(placeOf(world, 'Spine/Upper/Fore/Hand'), target)).toBeLessThan(1e-3);
});
});