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 A 3D collider can be seen — and what is seen is what collides.
*
* The wireframe exists so an author can tell whether a shape is the size and
* place they meant. That only helps if it draws the shape the SOLVER built, so
* the shape-selection half of these checks runs the real stepPhysics3D over the
* same world and asserts the two agree: whichever `add*` the system called is
* the instance the reader marked active. Restating the priority order here
* instead would pass happily while the two drifted apart.
*/
import { describe, it, expect, beforeEach } from 'vitest';
import { Transform } from '../src/ecs/component';
import type { TransformData } from '../src/ecs/component.generated';
import {
RigidBody3D, BoxCollider3D, SphereCollider3D, CapsuleCollider3D, CharacterController3D,
MeshCollider3D, ConvexCollider3D,
} from '../src/physics3d/Physics3DComponents';
import {
readCollider3DShapes, collider3DWireframe, placeCollider3DWireframe,
type Collider3DShape,
} from '../src/physics3d/ColliderShape3D';
import { registerMeshCollision, releaseMeshCollision } from '../src/asset/meshCollision';
import { stepPhysics3D, DEFAULT_PHYSICS3D_CONFIG } from '../src/physics3d/Physics3DSystem';
import type { Physics3DWasmModule } from '../src/physics3d/Physics3DModule';
import type { World } from '../src/ecs/world';
import type { App } from '../src/app/app';
import type { Entity, Vec3 } from '../src/types';
/** Records which shape the system asked the module to build. */
function fakeModule(): Physics3DWasmModule & { calls: string[] } {
const calls: string[] = [];
const heap = new Float32Array(1024);
const record = (name: string) => (...args: number[]): number => {
calls.push(name);
return args.length > 0 ? calls.length : calls.length;
};
return {
calls,
HEAPF32: heap,
HEAPU32: new Uint32Array(heap.buffer),
_physics3d_init: record('init'),
_physics3d_isReady: () => 1,
_physics3d_step: record('step'),
_physics3d_addBox: record('addBox'),
_physics3d_addSphere: record('addSphere'),
_physics3d_addCapsule: record('addCapsule'),
_physics3d_addMeshBody: record('addMeshBody'),
_physics3d_addConvexBody: record('addConvexBody'),
_physics3d_removeBody: record('removeBody'),
_physics3d_addCharacter: record('addCharacter'),
_physics3d_moveCharacter: record('moveCharacter'),
_physics3d_removeCharacter: record('removeCharacter'),
_physics3d_characterStates: () => 0,
_physics3d_characterStatesBytes: () => 0,
_physics3d_transforms: () => 0,
_physics3d_transformsBytes: () => 0,
_physics3d_contacts: () => 0,
_physics3d_contactsBytes: () => 0,
_malloc: () => 4,
_free: () => undefined,
} as unknown as Physics3DWasmModule & { calls: string[] };
}
function fakeWorld() {
const store = new Map<Entity, Map<unknown, Record<string, unknown>>>();
let next = 1;
return {
spawn(): Entity {
const e = next++ as Entity;
store.set(e, new Map());
return e;
},
insert<T>(e: Entity, def: unknown, data?: Partial<T>): T {
const defaults = (def as { _default?: object })._default ?? {};
const value = structuredClone({ ...defaults, ...(data ?? {}) });
store.get(e)!.set(def, value as Record<string, unknown>);
return value as T;
},
get(e: Entity, def: unknown): unknown { return store.get(e)?.get(def); },
has(e: Entity, def: unknown): boolean { return store.get(e)?.has(def) ?? false; },
valid(e: Entity): boolean { return store.has(e); },
// Nothing composes here, so this is the honest answer for a store with no
// composer: what the solver's world pose becomes under a PARENT is
// checked against the real one in physics3d-transform-space.
ensureTransformsComposed(): void {},
queryEntities(defs: unknown[]): Entity[] {
return [...store.entries()]
.filter(([, comps]) => defs.every((d) => comps.has(d)))
.map(([e]) => e);
},
};
}
/** The module call each collider component turns into, so the two halves can be compared. */
const CALL_FOR: Record<string, string> = {
BoxCollider3D: 'addBox',
SphereCollider3D: 'addSphere',
CapsuleCollider3D: 'addCapsule',
MeshCollider3D: 'addMeshBody',
ConvexCollider3D: 'addConvexBody',
};
function bounds(lines: Vec3[][]): { min: Vec3; max: Vec3 } {
const min = { x: Infinity, y: Infinity, z: Infinity };
const max = { x: -Infinity, y: -Infinity, z: -Infinity };
for (const line of lines) {
for (const p of line) {
min.x = Math.min(min.x, p.x); max.x = Math.max(max.x, p.x);
min.y = Math.min(min.y, p.y); max.y = Math.max(max.y, p.y);
min.z = Math.min(min.z, p.z); max.z = Math.max(max.z, p.z);
}
}
return { min, max };
}
const size = (lines: Vec3[][]): Vec3 => {
const b = bounds(lines);
return { x: b.max.x - b.min.x, y: b.max.y - b.min.y, z: b.max.z - b.min.z };
};
describe('what a 3D collider looks like', () => {
let world: ReturnType<typeof fakeWorld>;
let app: App;
let module: ReturnType<typeof fakeModule>;
beforeEach(() => {
world = fakeWorld();
app = { world } as unknown as App;
module = fakeModule();
});
const spawn = (withBody = true): Entity => {
const e = world.spawn();
world.insert<TransformData>(e, Transform, {
position: { x: 0, y: 0, z: 0 },
rotation: { x: 0, y: 0, z: 0, w: 1 },
scale: { x: 1, y: 1, z: 1 },
worldPosition: { x: 0, y: 0, z: 0 },
worldRotation: { x: 0, y: 0, z: 0, w: 1 },
worldScale: { x: 1, y: 1, z: 1 },
});
if (withBody) world.insert(e, RigidBody3D);
return e;
};
const read = (e: Entity) => readCollider3DShapes(world as unknown as World, e);
/** Which component the solver actually built a body from, per the real system. */
const built = (): string | null => {
module.calls.length = 0;
stepPhysics3D(app, module, new Map(), DEFAULT_PHYSICS3D_CONFIG);
const call = module.calls.find((c) => Object.values(CALL_FOR).includes(c));
return call ?? null;
};
describe('the shape it reports is the shape the world builds', () => {
it('marks the box active when box and sphere are both authored', () => {
const e = spawn();
world.insert(e, SphereCollider3D);
world.insert(e, BoxCollider3D);
const active = read(e).filter((i) => i.active);
expect(active).toHaveLength(1);
expect(CALL_FOR[active[0]!.component]).toBe(built());
});
it('follows the world past a disabled collider to the next one', () => {
const e = spawn();
world.insert(e, BoxCollider3D, { enabled: false });
world.insert(e, SphereCollider3D);
const active = read(e).filter((i) => i.active);
expect(active).toHaveLength(1);
expect(active[0]!.component).toBe('SphereCollider3D');
expect(built()).toBe('addSphere');
});
it('lets a mesh collider shadow a capsule, as the world does', () => {
registerMeshCollision(4242, {
positions: new Float32Array([0, 0, 0, 100, 0, 0, 0, 0, 100, 100, 0, 100]),
indices: new Uint32Array([0, 2, 1, 2, 3, 1]),
});
const e = spawn();
world.insert(e, MeshCollider3D, { mesh: 4242 });
world.insert(e, CapsuleCollider3D);
const active = read(e).filter((i) => i.active);
expect(active.map((i) => i.component)).toEqual(['MeshCollider3D']);
expect(built()).toBe('addMeshBody');
releaseMeshCollision(4242);
});
it('draws a convex hull as the shape the world builds from it', () => {
registerMeshCollision(555, {
positions: new Float32Array([-2, 0, -2, 2, 0, -2, 0, 6, 0, 0, 0, 4]),
indices: new Uint32Array([0, 1, 2, 0, 2, 3]),
});
const e = spawn();
world.insert(e, ConvexCollider3D, { mesh: 555 });
const [inst] = read(e);
expect(inst!.component).toBe('ConvexCollider3D');
expect(inst!.active).toBe(true);
expect(CALL_FOR[inst!.component]).toBe(built());
if (inst!.shape.kind !== 'box') throw new Error('unreachable');
expect(inst!.shape.halfExtents).toEqual({ x: 2, y: 3, z: 3 });
releaseMeshCollision(555);
});
// Unity's rule, and how an imported level collides: a MeshCollider3D on each mesh and nothing else.
it('reports a collider with no rigid body as a static body, and the world builds it', () => {
const e = spawn(false);
world.insert(e, BoxCollider3D);
expect(read(e)).toHaveLength(1);
expect(read(e)[0]!.active).toBe(true);
expect(built()).toBe('addBox');
});
it('reports no active shape for a disabled body', () => {
const e = spawn();
world.insert(e, RigidBody3D, { enabled: false });
world.insert(e, BoxCollider3D);
expect(read(e)[0]!.active).toBe(false);
expect(built()).toBeNull();
});
it('draws a character beside the body shape rather than instead of it', () => {
const e = spawn();
world.insert(e, BoxCollider3D);
world.insert(e, CharacterController3D);
const active = read(e).filter((i) => i.active).map((i) => i.component);
expect(active).toEqual(['BoxCollider3D', 'CharacterController3D']);
});
it('carries the sensor flag through, so an overlay can tell them apart', () => {
const e = spawn();
world.insert(e, SphereCollider3D, { isSensor: true });
expect(read(e)[0]!.isSensor).toBe(true);
});
});
describe('the wireframe', () => {
it('spans exactly the box it describes', () => {
const shape: Collider3DShape = {
kind: 'box',
halfExtents: { x: 10, y: 20, z: 30 },
center: { x: 0, y: 0, z: 0 },
};
expect(size(collider3DWireframe(shape))).toEqual({ x: 20, y: 40, z: 60 });
});
it('gives the box its twelve edges', () => {
const shape: Collider3DShape = {
kind: 'box', halfExtents: { x: 1, y: 1, z: 1 }, center: { x: 0, y: 0, z: 0 },
};
const lines = collider3DWireframe(shape);
const segments = lines.reduce((n, l) => n + l.length - 1, 0);
expect(segments).toBe(12);
const corners = new Set(lines.flat().map((p) => `${p.x},${p.y},${p.z}`));
expect(corners.size).toBe(8);
});
it('keeps every sphere point on the sphere', () => {
const lines = collider3DWireframe({ kind: 'sphere', radius: 7 });
for (const p of lines.flat()) {
expect(Math.hypot(p.x, p.y, p.z)).toBeCloseTo(7, 5);
}
expect(size(lines)).toEqual({ x: 14, y: 14, z: 14 });
});
it('moves a sphere and a capsule to where their collider sits', () => {
const center = { x: 10, y: -20, z: 30 };
for (const shape of [{ kind: 'sphere', radius: 7, center }, { kind: 'capsule', radius: 7, halfHeight: 5, center }] as const) {
const points = collider3DWireframe(shape).flat();
const mid = (axis: 'x' | 'y' | 'z') => (Math.min(...points.map((p) => p[axis])) + Math.max(...points.map((p) => p[axis]))) / 2;
expect([mid('x'), mid('y'), mid('z')]).toEqual([10, -20, 30]);
}
});
it('is as tall AND as wide as the capsule', () => {
// Height alone cannot tell radius from halfHeight: 30 + 50 and 50 + 30
// stand the same. The width is what separates them.
const lines = collider3DWireframe({ kind: 'capsule', radius: 30, halfHeight: 50 });
const s = size(lines);
expect(s.y).toBeCloseTo(2 * (30 + 50), 3);
expect(s.x).toBeCloseTo(60, 3);
expect(s.z).toBeCloseTo(60, 3);
});
it('bulges only at the caps of the capsule', () => {
const lines = collider3DWireframe({ kind: 'capsule', radius: 10, halfHeight: 40 });
for (const p of lines.flat()) {
const lateral = Math.hypot(p.x, p.z);
if (Math.abs(p.y) <= 40) expect(lateral).toBeLessThanOrEqual(10.001);
else {
const overshoot = Math.abs(p.y) - 40;
expect(lateral ** 2 + overshoot ** 2).toBeLessThanOrEqual(10 ** 2 + 1e-3);
}
}
});
it('takes the mesh collider from the triangles that will be collided against', () => {
registerMeshCollision(99, {
positions: new Float32Array([-4, 0, -2, 6, 8, -2, 6, 0, 10]),
indices: new Uint32Array([0, 1, 2]),
});
const e = spawn();
world.insert(e, MeshCollider3D, { mesh: 99 });
const shape = read(e)[0]!.shape;
expect(shape.kind).toBe('box');
if (shape.kind !== 'box') throw new Error('unreachable');
expect(shape.center).toEqual({ x: 1, y: 4, z: 4 });
expect(shape.halfExtents).toEqual({ x: 5, y: 4, z: 6 });
releaseMeshCollision(99);
});
it('draws nothing for a mesh whose triangles never loaded', () => {
const e = spawn();
world.insert(e, MeshCollider3D, { mesh: 12345 });
expect(read(e)).toHaveLength(0);
});
});
describe('placing it in the world', () => {
it('turns the box with the entity', () => {
const shape: Collider3DShape = {
kind: 'box', halfExtents: { x: 10, y: 20, z: 30 }, center: { x: 0, y: 0, z: 0 },
};
const half = Math.PI / 4; // 90° about Y
const turned = placeCollider3DWireframe(
collider3DWireframe(shape),
{ x: 0, y: 0, z: 0 },
{ x: 0, y: Math.sin(half), z: 0, w: Math.cos(half) },
);
const s = size(turned);
expect(s.x).toBeCloseTo(60, 3); // the 30-deep half is now the wide one
expect(s.y).toBeCloseTo(40, 3);
expect(s.z).toBeCloseTo(20, 3);
});
it('lands the shape on the entity', () => {
const placed = placeCollider3DWireframe(
collider3DWireframe({ kind: 'sphere', radius: 5 }),
{ x: 100, y: -50, z: 20 },
{ x: 0, y: 0, z: 0, w: 1 },
);
const b = bounds(placed);
expect(b.min).toEqual({ x: 95, y: -55, z: 15 });
expect(b.max).toEqual({ x: 105, y: -45, z: 25 });
});
});
});