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: what the player asks for and what the character did are different
* things, and only the second one reaches the animator or the transform.
*/
import { describe, it, expect } from 'vitest';
import {
ThirdPersonController, ThirdPersonCamera, requestMotion, observeMotion, updateCameras,
TPC_SPEED, TPC_GROUNDED, TPC_DODGE, cameraGroundBasis, desiredDirection, approachVelocity,
facingYaw, turnToward, rootMotionVelocity, DODGE_KEY,
type ThirdPersonControllerData, type ThirdPersonCameraData,
} from '../src/gameplay';
import { CharacterController3D, type CharacterController3DData } from '../src/physics3d/Physics3DComponents';
import {
Animator, AnimatorControllerAPI, AnimatorRootMotion,
type AnimatorData, type AnimatorRootMotionData,
} from '../src/animation';
import { Transform, type TransformData } from '../src/ecs/component';
import { q } from '../src/math/quat';
const PLAYER = 1;
const CAMERA = 2;
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); },
update(e: number, c: unknown, edit: (d: any) => void) {
const d = mapOf(c).get(e);
if (d === undefined) throw new Error('update: entity does not carry it');
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;
}
/** A keyboard held down on the named keys, and a pointer that never moves. */
function stubInput(keys: string[] = [], pointer = { x: 0, y: 0 }, dragging = false) {
const held = new Set(keys);
return {
isKeyDown: (k: string) => held.has(k),
isKeyPressed: (k: string) => held.has(k),
getMousePosition: () => pointer,
isMouseButtonDown: () => dragging,
} as any;
}
const transform = (): TransformData => ({
position: { x: 0, y: 0, z: 0 },
rotation: { w: 1, x: 0, y: 0, z: 0 },
scale: { x: 1, y: 1, z: 1 },
} as TransformData);
const character = (over: Partial<CharacterController3DData> = {}): CharacterController3DData => ({
velocity: { x: 0, y: 0, z: 0 },
radius: 0.3, halfHeight: 0.5, maxSlope: 0.87, layer: 0,
stepHeight: 0.4, snapDown: 0.5, mass: 70, pushForce: 5000, enabled: true,
isOnFloor: true, floorNormal: { x: 0, y: 1, z: 0 },
realVelocity: { x: 0, y: 0, z: 0 },
...over,
} as CharacterController3DData);
const controller = (over: Partial<ThirdPersonControllerData> = {}): ThirdPersonControllerData => ({
moveSpeed: 4, acceleration: 1000, deceleration: 1000, rotationSpeed: 720,
jumpSpeed: 0, airControl: 0.3, cameraRelative: true, camera: 0 as never,
idleThreshold: 0.1, enabled: true, ...over,
});
const camera = (over: Partial<ThirdPersonCameraData> = {}): ThirdPersonCameraData => ({
target: PLAYER as never, distance: 6, yaw: 0, pitch: 0,
minPitch: -30, maxPitch: 70, sensitivity: 0.2,
followDamping: 0,
targetOffset: { x: 0, y: 0, z: 0 },
obstruction: true, obstructionRadius: 0.2, obstructionLayers: 0, enabled: true,
...over,
});
/** A player standing on the floor, with a camera at `yaw` looking at it. */
function scene(yaw = 0, over: Partial<ThirdPersonControllerData> = {}) {
const world = makeWorld();
world.insert(PLAYER, Transform, transform());
world.insert(PLAYER, CharacterController3D, character());
world.insert(PLAYER, ThirdPersonController, controller(over));
world.insert(PLAYER, Animator, { controller: 'x', currentState: '', enabled: true } as AnimatorData);
world.insert(CAMERA, Transform, transform());
world.insert(CAMERA, ThirdPersonCamera, camera({ yaw }));
return world;
}
const askedVelocity = (world: any) =>
(world.get(PLAYER, CharacterController3D) as CharacterController3DData).velocity;
describe('the stick is read in the camera ground plane', () => {
it('walks along -Z with the camera behind the player', () => {
const world = scene(0);
requestMotion(world, stubInput(['KeyW']), 1 / 60);
const v = askedVelocity(world);
expect(v.z).toBeCloseTo(-4, 5);
expect(Math.abs(v.x)).toBeLessThan(1e-6);
});
it('walks along -X once the camera has turned a quarter', () => {
const world = scene(90);
requestMotion(world, stubInput(['KeyW']), 1 / 60);
const v = askedVelocity(world);
expect(v.x).toBeCloseTo(-4, 5);
expect(Math.abs(v.z)).toBeLessThan(1e-5);
});
it('ignores camera pitch, so looking down does not walk into the floor', () => {
// The basis is built from yaw alone; a steep pitch must not tilt it.
const level = cameraGroundBasis(0);
const direction = desiredDirection({ x: 0, y: 1 }, level);
expect(direction.y).toBe(0);
expect(direction.z).toBeCloseTo(-1, 6);
});
});
describe('the animator hears what happened, not what was asked', () => {
it('reports the speed the character reached', () => {
const world = scene(0);
const animator = new AnimatorControllerAPI();
requestMotion(world, stubInput(['KeyW']), 1 / 60);
// The physics step's answer: it moved at 3, not the 4 it asked for.
world.update(PLAYER, CharacterController3D, (c: CharacterController3DData) => {
c.realVelocity.z = -3;
});
observeMotion(world, animator, 1 / 60);
expect(animator.getFloat(PLAYER, TPC_SPEED)).toBeCloseTo(3, 5);
});
it('says standing still when a wall takes the motion away', () => {
const world = scene(0);
const animator = new AnimatorControllerAPI();
requestMotion(world, stubInput(['KeyW']), 1 / 60);
// The stick is full: the character ASKED to move.
expect(Math.hypot(askedVelocity(world).x, askedVelocity(world).z)).toBeCloseTo(4, 5);
// And the world gave it nothing, which is what a wall does.
world.update(PLAYER, CharacterController3D, (c: CharacterController3DData) => {
c.realVelocity.x = 0; c.realVelocity.z = 0;
});
observeMotion(world, animator, 1 / 60);
expect(animator.getFloat(PLAYER, TPC_SPEED)).toBe(0);
});
it('passes the floor contact through as it stands', () => {
const world = scene(0);
const animator = new AnimatorControllerAPI();
world.update(PLAYER, CharacterController3D, (c: CharacterController3DData) => {
c.isOnFloor = false;
});
observeMotion(world, animator, 1 / 60);
expect(animator.getBool(PLAYER, TPC_GROUNDED)).toBe(false);
});
});
describe('movement goes through the character controller', () => {
it('asks for a velocity and moves no transform itself', () => {
const world = scene(0);
const before = { ...(world.get(PLAYER, Transform) as TransformData).position };
requestMotion(world, stubInput(['KeyW']), 1 / 60);
const after = (world.get(PLAYER, Transform) as TransformData).position;
expect(after).toEqual(before);
expect(askedVelocity(world).z).toBeCloseTo(-4, 5);
});
it('leaves the vertical alone so the controller keeps carrying it', () => {
const world = scene(0);
requestMotion(world, stubInput(['KeyW']), 1 / 60);
expect(askedVelocity(world).y).toBe(0);
});
it('starts a jump only from the floor', () => {
const world = scene(0, { jumpSpeed: 5 });
requestMotion(world, stubInput(['Space']), 1 / 60);
expect(askedVelocity(world).y).toBeCloseTo(5, 5);
world.update(PLAYER, CharacterController3D, (c: CharacterController3DData) => {
c.isOnFloor = false;
});
requestMotion(world, stubInput(['Space']), 1 / 60);
expect(askedVelocity(world).y).toBe(0);
});
});
describe('a centred stick stops the character', () => {
it('decelerates to nothing', () => {
const world = scene(0, { deceleration: 50 });
requestMotion(world, stubInput(['KeyW']), 1 / 60);
expect(Math.hypot(askedVelocity(world).x, askedVelocity(world).z)).toBeGreaterThan(0);
for (let i = 0; i < 60; i++) requestMotion(world, stubInput([]), 1 / 60);
expect(Math.hypot(askedVelocity(world).x, askedVelocity(world).z)).toBeCloseTo(0, 6);
});
it('keeps the heading it stopped at rather than snapping to world forward', () => {
const world = scene(0);
const animator = new AnimatorControllerAPI();
world.update(PLAYER, CharacterController3D, (c: CharacterController3DData) => {
c.realVelocity.x = -3;
});
observeMotion(world, animator, 1);
const facing = { ...(world.get(PLAYER, Transform) as TransformData).rotation };
world.update(PLAYER, CharacterController3D, (c: CharacterController3DData) => {
c.realVelocity.x = 0;
});
observeMotion(world, animator, 1);
expect((world.get(PLAYER, Transform) as TransformData).rotation).toEqual(facing);
});
});
describe('the camera keeps out of walls', () => {
const noWall = { sphereCast: () => null } as any;
/** A wall halfway along whatever the camera sweeps. */
const wallAtHalf = { sphereCast: () => ({ entity: 9, fraction: 0.5, x: 0, y: 0, z: 0,
normalX: 0, normalY: 0, normalZ: 1 }) } as any;
const cameraDistance = (world: any): number => {
const p = (world.get(CAMERA, Transform) as TransformData).position;
const t = (world.get(PLAYER, Transform) as TransformData).position;
return Math.hypot(p.x - t.x, p.y - t.y, p.z - t.z);
};
it('sits at its full distance with nothing in the way', () => {
const world = scene(0);
updateCameras(world, stubInput(), noWall, 1 / 60);
expect(cameraDistance(world)).toBeCloseTo(6, 4);
});
it('pulls in when something stands between', () => {
const world = scene(0);
updateCameras(world, stubInput(), wallAtHalf, 1 / 60);
expect(cameraDistance(world)).toBeCloseTo(3, 4);
});
it('goes back out once the way is clear', () => {
const world = scene(0);
updateCameras(world, stubInput(), wallAtHalf, 1 / 60);
expect(cameraDistance(world)).toBeCloseTo(3, 4);
updateCameras(world, stubInput(), noWall, 1 / 60);
expect(cameraDistance(world)).toBeCloseTo(6, 4);
});
it('moves the camera and never the character', () => {
const world = scene(0);
const before = { ...(world.get(PLAYER, Transform) as TransformData).position };
updateCameras(world, stubInput(), wallAtHalf, 1 / 60);
expect((world.get(PLAYER, Transform) as TransformData).position).toEqual(before);
});
});
describe('the pure decisions', () => {
it('accelerates and decelerates at their own rates', () => {
const up = approachVelocity({ x: 0, z: 0 }, { x: 10, z: 0 }, 10, 1000, 0.1);
expect(up.x).toBeCloseTo(1, 6);
const down = approachVelocity({ x: 10, z: 0 }, { x: 0, z: 0 }, 10, 100, 0.1);
expect(down.x).toBeCloseTo(0, 6);
});
it('faces along -Z at zero yaw', () => {
expect(facingYaw({ x: 0, y: 0, z: -1 })).toBeCloseTo(0, 6);
expect(facingYaw({ x: -1, y: 0, z: 0 })).toBeCloseTo(90, 6);
});
it('turns the short way across the seam', () => {
expect(turnToward(170, -170, 3600, 1 / 60)).toBeCloseTo(-170, 6);
expect(turnToward(170, -170, 60, 0.1)).toBeCloseTo(176, 6);
});
});
// =============================================================================
// An animation that drives the character
// =============================================================================
/** Give the player a root-motion request of `delta` over `seconds`. */
function asksToMove(
world: any, delta: { x: number; y: number; z: number },
seconds: number, turnDeg = 0, active = true,
): void {
world.insert(PLAYER, AnimatorRootMotion, {
enabled: true,
active,
deltaPosition: { ...delta },
deltaRotation: q.axis('y', (turnDeg * Math.PI) / 180),
deltaTime: seconds,
} as AnimatorRootMotionData);
}
describe('a root-motion request becomes a rate', () => {
it('is the displacement over the seconds it covers', () => {
expect(rootMotionVelocity({ x: 2, z: -6 }, 0.5)).toEqual({ x: 4, z: -12 });
});
it('is nothing at all when it covers no time', () => {
expect(rootMotionVelocity({ x: 2, z: -6 }, 0)).toEqual({ x: 0, z: 0 });
});
});
describe('while an animation is driving', () => {
it('the character controller is asked for the animation, not the stick', () => {
const world = scene(0);
asksToMove(world, { x: 0, y: 0, z: -0.2 }, 1 / 60);
// A full stick the other way: if it reached the controller at all, the
// sign of x would show it.
requestMotion(world, stubInput(['KeyD']), 1 / 60);
const v = askedVelocity(world);
expect(v.z).toBeCloseTo(-12, 5);
expect(v.x).toBeCloseTo(0, 6);
});
it('and the stick is back in charge the moment it stops', () => {
const world = scene(0);
asksToMove(world, { x: 0, y: 0, z: -0.2 }, 1 / 60, 0, false);
requestMotion(world, stubInput(['KeyD']), 1 / 60);
expect(askedVelocity(world).x).toBeCloseTo(4, 5);
});
it('a jump is refused, so nothing else is setting the vertical', () => {
const world = scene(0, { jumpSpeed: 5 });
asksToMove(world, { x: 0, y: 0, z: -0.2 }, 1 / 60);
requestMotion(world, stubInput(['Space']), 1 / 60);
expect(askedVelocity(world).y).toBe(0);
});
it('the request still moves no transform of its own', () => {
const world = scene(0);
asksToMove(world, { x: 0, y: 0, z: -0.2 }, 1 / 60);
const before = { ...(world.get(PLAYER, Transform) as TransformData).position };
requestMotion(world, stubInput([]), 1 / 60);
expect((world.get(PLAYER, Transform) as TransformData).position).toEqual(before);
});
it('what the animator hears is still what the world allowed', () => {
const world = scene(0);
const animator = new AnimatorControllerAPI();
asksToMove(world, { x: 0, y: 0, z: -0.2 }, 1 / 60);
requestMotion(world, stubInput([]), 1 / 60);
// The request is large and the wall gave nothing back.
expect(askedVelocity(world).z).toBeCloseTo(-12, 5);
observeMotion(world, animator, 1 / 60);
expect(animator.getFloat(PLAYER, TPC_SPEED)).toBe(0);
});
it('the heading is the animation’s turn, spent over the steps of its frame', () => {
const world = scene(0);
const animator = new AnimatorControllerAPI();
// One rendered frame's worth of turn, consumed by two fixed steps.
asksToMove(world, { x: 0, y: 0, z: -0.2 }, 1 / 30, 90);
observeMotion(world, animator, 1 / 60);
observeMotion(world, animator, 1 / 60);
const rotation = (world.get(PLAYER, Transform) as TransformData).rotation;
expect(q.toEuler(rotation)[1]).toBeCloseTo(90, 4);
});
it('and the character does not also turn to face where it went', () => {
const world = scene(0);
const animator = new AnimatorControllerAPI();
// Moving hard along -X, which turn-to-face would answer with a quarter turn.
world.update(PLAYER, CharacterController3D, (c: CharacterController3DData) => {
c.realVelocity.x = -4;
});
asksToMove(world, { x: -0.2, y: 0, z: 0 }, 1 / 60, 0);
observeMotion(world, animator, 1 / 60);
const rotation = (world.get(PLAYER, Transform) as TransformData).rotation;
expect(q.toEuler(rotation)[1]).toBeCloseTo(0, 6);
});
});
describe('asking for a dodge', () => {
/** Idle until something sets the trigger; the controller names no state. */
const graph = {
parameters: [{ name: TPC_DODGE, type: 'trigger' as const }],
initialState: 'Idle',
states: [
{
name: 'Idle',
transitions: [{ to: 'Dodge', conditions: [{ param: TPC_DODGE, op: 'trigger' as const }] }],
},
{ name: 'Dodge', transitions: [] },
],
};
function press(keys: string[]): string {
const world = scene(0);
const animator = new AnimatorControllerAPI();
animator.registerController('x', graph);
requestMotion(world, stubInput(keys), 1 / 60, animator);
animator.update(world, 1 / 60);
return (world.get(PLAYER, Animator) as AnimatorData).currentState;
}
it('lets the graph decide there is one', () => {
expect(press([DODGE_KEY])).toBe('Dodge');
});
it('and stays put when nobody asked', () => {
expect(press([])).toBe('Idle');
});
});