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
import { describe, bench, beforeAll } from 'vitest';
import { World } from '../src/ecs/world';
import { defineBuiltin } from '../src/ecs/component';
import type { CppRegistry, ESEngineModule } from '../src/wasm';
import type { PhysicsWasmModule } from '../src/physics/PhysicsModuleLoader';
import { syncDynamicTransforms } from '../src/physics/PhysicsSystem';
import type { Entity } from '../src/types';
import { loadWasmModule, loadSideModule } from '../tests/helpers/loadWasm';
let wasmModule: ESEngineModule;
let physicsMod: PhysicsWasmModule;
beforeAll(async () => {
wasmModule = await loadWasmModule();
physicsMod = await loadSideModule<PhysicsWasmModule>('physics');
physicsMod._physics_init(0, -9.81, 1 / 30, 4, 30, 10, 3);
});
const Transform = defineBuiltin('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 },
});
const RigidBody2D = defineBuiltin('RigidBody2D', {
bodyType: 2, gravityScale: 1, linearDamping: 0, angularDamping: 0,
fixedRotation: false, bullet: false, enabled: true,
});
const PPU = 100;
const INV_PPU = 1 / PPU;
const TRANSFORM_DATA = {
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 },
};
const RIGIDBODY_DATA = {
bodyType: 2, gravityScale: 1, linearDamping: 0.1, angularDamping: 0.05,
fixedRotation: false, bullet: false, enabled: true,
};
function createBodies(count: number, reg: CppRegistry) {
const ids: number[] = [];
for (let i = 0; i < count; i++) {
const e = reg.create!();
(reg as any).addTransform(e, TRANSFORM_DATA);
physicsMod._physics_createBody(e, 2, i * 0.5 * INV_PPU, i * 0.3 * INV_PPU, 0, 1, 0, 0, 0, 0);
physicsMod._physics_addBoxShape(e, 0.5, 0.5, 0, 0, 0.05, 1, 0.3, 0, 0, 0x0001, 0xFFFF);
ids.push(e as number);
}
return ids;
}
function destroyBodies(ids: number[]) {
for (const e of ids) physicsMod._physics_destroyBody(e);
}
// =============================================================================
// _physics_step — Box2D simulation cost
// =============================================================================
describe('Physics - _physics_step (Box2D simulation)', () => {
bench('step (0 bodies)', () => {
physicsMod._physics_step(1 / 60);
});
bench('step (50 bodies)', () => {
const reg = new wasmModule.Registry();
const ids = createBodies(50, reg as unknown as CppRegistry);
physicsMod._physics_step(1 / 60);
destroyBodies(ids);
reg.delete();
});
bench('step (200 bodies)', () => {
const reg = new wasmModule.Registry();
const ids = createBodies(200, reg as unknown as CppRegistry);
physicsMod._physics_step(1 / 60);
destroyBodies(ids);
reg.delete();
});
bench('step (500 bodies)', () => {
const reg = new wasmModule.Registry();
const ids = createBodies(500, reg as unknown as CppRegistry);
physicsMod._physics_step(1 / 60);
destroyBodies(ids);
reg.delete();
});
});
// =============================================================================
// syncDynamicTransforms — read from physics, write to ECS
// =============================================================================
describe('Physics - syncDynamicTransforms', () => {
bench('50 bodies', () => {
const reg = new wasmModule.Registry();
const ids = createBodies(50, reg as unknown as CppRegistry);
physicsMod._physics_step(1 / 60);
const world = new World();
world.connectCpp(reg as unknown as CppRegistry, wasmModule);
syncDynamicTransforms({ world } as any, physicsMod, PPU, new Set());
destroyBodies(ids);
reg.delete();
});
bench('200 bodies', () => {
const reg = new wasmModule.Registry();
const ids = createBodies(200, reg as unknown as CppRegistry);
physicsMod._physics_step(1 / 60);
const world = new World();
world.connectCpp(reg as unknown as CppRegistry, wasmModule);
syncDynamicTransforms({ world } as any, physicsMod, PPU, new Set());
destroyBodies(ids);
reg.delete();
});
bench('500 bodies', () => {
const reg = new wasmModule.Registry();
const ids = createBodies(500, reg as unknown as CppRegistry);
physicsMod._physics_step(1 / 60);
const world = new World();
world.connectCpp(reg as unknown as CppRegistry, wasmModule);
syncDynamicTransforms({ world } as any, physicsMod, PPU, new Set());
destroyBodies(ids);
reg.delete();
});
});
// =============================================================================
// Body creation cost
// =============================================================================
describe('Physics - body creation (createBody + addBoxShape)', () => {
bench('create + shape x50', () => {
const reg = new wasmModule.Registry();
const ids: number[] = [];
for (let i = 0; i < 50; i++) {
const e = (reg as any).create();
physicsMod._physics_createBody(e, 2, i * INV_PPU, 0, 0, 1, 0, 0, 0, 0);
physicsMod._physics_addBoxShape(e, 0.5, 0.5, 0, 0, 0.05, 1, 0.3, 0, 0, 0x0001, 0xFFFF);
ids.push(e);
}
for (const e of ids) physicsMod._physics_destroyBody(e);
reg.delete();
});
bench('create + shape x200', () => {
const reg = new wasmModule.Registry();
const ids: number[] = [];
for (let i = 0; i < 200; i++) {
const e = (reg as any).create();
physicsMod._physics_createBody(e, 2, i * INV_PPU, 0, 0, 1, 0, 0, 0, 0);
physicsMod._physics_addBoxShape(e, 0.5, 0.5, 0, 0, 0.05, 1, 0.3, 0, 0, 0x0001, 0xFFFF);
ids.push(e);
}
for (const e of ids) physicsMod._physics_destroyBody(e);
reg.delete();
});
});
// =============================================================================
// collectEvents
// =============================================================================
describe('Physics - collectEvents', () => {
bench('collectEvents (0 collisions)', () => {
physicsMod._physics_collectEvents();
physicsMod._physics_getCollisionEnterCount();
physicsMod._physics_getCollisionExitCount();
physicsMod._physics_getSensorEnterCount();
physicsMod._physics_getSensorExitCount();
});
bench('step + collectEvents (50 stacked bodies)', () => {
const reg = new wasmModule.Registry();
const ids: number[] = [];
for (let i = 0; i < 50; i++) {
const e = (reg as any).create();
physicsMod._physics_createBody(e, 2, 0, i * 1.1, 0, 1, 0, 0, 0, 0);
physicsMod._physics_addBoxShape(e, 0.5, 0.5, 0, 0, 0, 1, 0.3, 0.1, 0, 0x0001, 0xFFFF);
ids.push(e);
}
physicsMod._physics_step(1 / 60);
physicsMod._physics_collectEvents();
const enterCount = physicsMod._physics_getCollisionEnterCount();
if (enterCount > 0) {
const enterPtr = physicsMod._physics_getCollisionEnterBuffer() >> 2;
for (let i = 0; i < enterCount; i++) {
const base = enterPtr + i * 6;
const _a = physicsMod.HEAPU32[base];
const _b = physicsMod.HEAPU32[base + 1];
}
}
for (const e of ids) physicsMod._physics_destroyBody(e);
reg.delete();
});
});
// =============================================================================
// Full physics frame — step + sync + events
// =============================================================================
describe('Physics - full frame (step + sync + events)', () => {
bench('50 bodies', () => {
const reg = new wasmModule.Registry();
const ids = createBodies(50, reg as unknown as CppRegistry);
const world = new World();
world.connectCpp(reg as unknown as CppRegistry, wasmModule);
physicsMod._physics_step(1 / 60);
syncDynamicTransforms({ world } as any, physicsMod, PPU, new Set());
physicsMod._physics_collectEvents();
destroyBodies(ids);
reg.delete();
});
bench('200 bodies', () => {
const reg = new wasmModule.Registry();
const ids = createBodies(200, reg as unknown as CppRegistry);
const world = new World();
world.connectCpp(reg as unknown as CppRegistry, wasmModule);
physicsMod._physics_step(1 / 60);
syncDynamicTransforms({ world } as any, physicsMod, PPU, new Set());
physicsMod._physics_collectEvents();
destroyBodies(ids);
reg.delete();
});
bench('500 bodies', () => {
const reg = new wasmModule.Registry();
const ids = createBodies(500, reg as unknown as CppRegistry);
const world = new World();
world.connectCpp(reg as unknown as CppRegistry, wasmModule);
physicsMod._physics_step(1 / 60);
syncDynamicTransforms({ world } as any, physicsMod, PPU, new Set());
physicsMod._physics_collectEvents();
destroyBodies(ids);
reg.delete();
});
});
// =============================================================================
// addTransform writeback isolation (embind vs ptr)
// =============================================================================
describe('Physics - addTransform writeback (embind vs ptr)', () => {
bench('registry.addTransform x200 (embind)', () => {
const reg = new wasmModule.Registry();
const entities: number[] = [];
for (let i = 0; i < 200; i++) {
const e = (reg as any).create();
(reg as any).addTransform(e, TRANSFORM_DATA);
entities.push(e);
}
for (const e of entities) (reg as any).addTransform(e, TRANSFORM_DATA);
reg.delete();
});
bench('ptr setter x200 (resolvedSetter)', () => {
const world = new World();
const reg = new wasmModule.Registry();
world.connectCpp(reg as unknown as CppRegistry, wasmModule);
const entities: Entity[] = [];
for (let i = 0; i < 200; i++) {
const e = world.spawn();
world.insert(e, Transform, TRANSFORM_DATA as any);
entities.push(e);
}
const setter = world.resolveSetter(Transform)!;
for (const e of entities) setter(e, TRANSFORM_DATA);
reg.delete();
});
});
// =============================================================================
// Entity query overhead
// =============================================================================
describe('Physics - entity sync query', () => {
bench('getEntitiesWithComponents([RigidBody2D, Transform]) x10 (200 entities)', () => {
const world = new World();
const reg = new wasmModule.Registry();
world.connectCpp(reg as unknown as CppRegistry, wasmModule);
for (let i = 0; i < 200; i++) {
const e = world.spawn();
world.insert(e, Transform, TRANSFORM_DATA as any);
world.insert(e, RigidBody2D, RIGIDBODY_DATA as any);
}
for (let i = 0; i < 10; i++) {
world.getEntitiesWithComponents([RigidBody2D, Transform]);
}
reg.delete();
});
});
// =============================================================================
// syncDynamicTransforms — isolated batch vs embind comparison
// =============================================================================
describe('Physics - syncDynamicTransforms (batch vs embind)', () => {
let reg: CppRegistry;
let worldBatch: World;
let worldEmbind: World;
function ensureSetup() {
if (reg) return;
reg = new wasmModule.Registry() as unknown as CppRegistry;
createBodies(200, reg);
physicsMod._physics_step(1 / 60);
worldBatch = new World();
worldBatch.connectCpp(reg, wasmModule);
worldEmbind = new World();
worldEmbind.connectCpp(reg);
}
bench('batch sync (200 bodies)', () => {
ensureSetup();
syncDynamicTransforms({ world: worldBatch } as any, physicsMod, PPU, new Set());
});
bench('embind sync (200 bodies)', () => {
ensureSetup();
syncDynamicTransforms({ world: worldEmbind } as any, physicsMod, PPU, new Set());
});
});
// =============================================================================
// _physics_step — isolated: sleeping vs active bodies
// =============================================================================
describe('Physics - step cost: sleeping vs active (200 bodies)', () => {
let sleepReg: CppRegistry | null = null;
let sleepIds: number[] = [];
let activeReg: CppRegistry | null = null;
let activeIds: number[] = [];
function ensureSleepSetup() {
if (sleepReg) return;
physicsMod._physics_shutdown();
physicsMod._physics_init(0, -9.81, 1 / 60, 4, 30, 10, 3);
sleepReg = new wasmModule.Registry() as unknown as CppRegistry;
sleepIds = createBodies(200, sleepReg);
for (let i = 0; i < 120; i++) physicsMod._physics_step(1 / 60);
}
function ensureActiveSetup() {
if (activeReg) return;
physicsMod._physics_shutdown();
physicsMod._physics_init(0, -9.81, 1 / 60, 4, 30, 10, 3);
activeReg = new wasmModule.Registry() as unknown as CppRegistry;
activeIds = [];
for (let i = 0; i < 200; i++) {
const e = (activeReg as any).create();
(activeReg as any).addTransform(e, TRANSFORM_DATA);
physicsMod._physics_createBody(e, 2, (i % 20) * 0.5 * INV_PPU, Math.floor(i / 20) * 0.6 * INV_PPU, 0, 1, 0, 0, 0, 0);
physicsMod._physics_addBoxShape(e, 0.25, 0.25, 0, 0, 0.02, 1, 0.3, 0.1, 0, 0x0001, 0xFFFF);
activeIds.push(e);
}
physicsMod._physics_step(1 / 60);
}
bench('sleeping bodies (settled)', () => {
ensureSleepSetup();
physicsMod._physics_step(1 / 60);
});
bench('active bodies (perturbed each frame)', () => {
ensureActiveSetup();
for (let i = 0; i < activeIds.length; i += 10) {
physicsMod._physics_setLinearVelocity(activeIds[i], (i % 3 - 1) * 0.5, 2);
}
physicsMod._physics_step(1 / 60);
});
});
// =============================================================================
// _physics_step — subStepCount tuning (active bodies)
// =============================================================================
describe('Physics - step tuning: subStepCount (200 active bodies)', () => {
let setupDone = false;
let bodyIds: number[] = [];
let curSubSteps = -1;
function setupForSubSteps(subSteps: number) {
if (curSubSteps === subSteps) return;
physicsMod._physics_shutdown();
physicsMod._physics_init(0, -9.81, 1 / 60, subSteps, 30, 10, 3);
const reg = new wasmModule.Registry() as unknown as CppRegistry;
bodyIds = [];
for (let i = 0; i < 200; i++) {
const e = (reg as any).create();
(reg as any).addTransform(e, TRANSFORM_DATA);
physicsMod._physics_createBody(e, 2, (i % 20) * 0.5 * INV_PPU, Math.floor(i / 20) * 0.6 * INV_PPU, 0, 1, 0, 0, 0, 0);
physicsMod._physics_addBoxShape(e, 0.25, 0.25, 0, 0, 0.02, 1, 0.3, 0.1, 0, 0x0001, 0xFFFF);
bodyIds.push(e);
}
physicsMod._physics_step(1 / 60);
curSubSteps = subSteps;
}
function perturbAndStep() {
for (let i = 0; i < bodyIds.length; i += 10) {
physicsMod._physics_setLinearVelocity(bodyIds[i], (i % 3 - 1) * 0.5, 2);
}
physicsMod._physics_step(1 / 60);
}
bench('subSteps=1', () => { setupForSubSteps(1); perturbAndStep(); });
bench('subSteps=2', () => { setupForSubSteps(2); perturbAndStep(); });
bench('subSteps=4 (default)', () => { setupForSubSteps(4); perturbAndStep(); });
});
// =============================================================================
// Full physics frame — isolated (step + batch sync + events)
// =============================================================================
describe('Physics - full frame isolated (200 active bodies)', () => {
let reg: CppRegistry;
let world: World;
let bodyIds: number[];
let ready = false;
function ensureSetup() {
if (ready) return;
physicsMod._physics_shutdown();
physicsMod._physics_init(0, -9.81, 1 / 60, 4, 30, 10, 3);
reg = new wasmModule.Registry() as unknown as CppRegistry;
bodyIds = [];
for (let i = 0; i < 200; i++) {
const e = (reg as any).create();
(reg as any).addTransform(e, TRANSFORM_DATA);
physicsMod._physics_createBody(e, 2, (i % 20) * 0.5 * INV_PPU, Math.floor(i / 20) * 0.6 * INV_PPU, 0, 1, 0, 0, 0, 0);
physicsMod._physics_addBoxShape(e, 0.25, 0.25, 0, 0, 0.02, 1, 0.3, 0.1, 0, 0x0001, 0xFFFF);
bodyIds.push(e);
}
world = new World();
world.connectCpp(reg, wasmModule);
physicsMod._physics_step(1 / 60);
ready = true;
}
bench('full frame (step + sync + events)', () => {
ensureSetup();
for (let i = 0; i < bodyIds.length; i += 10) {
physicsMod._physics_setLinearVelocity(bodyIds[i], (i % 3 - 1) * 0.5, 2);
}
physicsMod._physics_step(1 / 60);
syncDynamicTransforms({ world } as any, physicsMod, PPU, new Set());
physicsMod._physics_collectEvents();
});
});
// =============================================================================
// Trig cost baseline
// =============================================================================
describe('Physics - trig overhead (per-body math)', () => {
bench('Math.cos + Math.sin x500 (angle→quat)', () => {
let sumW = 0, sumZ = 0;
for (let i = 0; i < 500; i++) {
const half = i * 0.005;
sumW += Math.cos(half);
sumZ += Math.sin(half);
}
if (sumW + sumZ === -Infinity) throw new Error();
});
bench('Math.atan2 x500 (quat→angle)', () => {
let sum = 0;
for (let i = 0; i < 500; i++) {
const w = Math.cos(i * 0.005);
const z = Math.sin(i * 0.005);
sum += Math.atan2(2 * w * z, 1 - 2 * z * z);
}
if (sum === -Infinity) throw new Error();
});
});