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 Physics3DModule.ts
* @brief The 3D physics wasm module's surface, and how it is loaded.
*/
import { defineResource } from '../ecs/resource';
import type { Entity } from '../types';
/** What the module exports. Kept in step with Physics3DModuleEntry.cpp by
* {@link assertPhysics3DContract} — a TypeScript interface is gone at run time,
* and a module built before the JS that drives it installs happily and then
* throws once per frame for the length of the session. */
export interface Physics3DWasmModule {
_physics3d_init(gx: number, gy: number, gz: number, maxBodies: number): void;
_physics3d_shutdown(): void;
_physics3d_isReady(): number;
_physics3d_step(dt: number, collisionSteps: number): void;
_physics3d_optimize(): void;
_physics3d_setLayerMask(layer: number, mask: number): void;
/** Each value <= 0 keeps the backend's own default; after init, before bodies. */
_physics3d_setSolver(velocityIterations: number, positionIterations: number, allowSleep: number,
bounceThreshold: number): void;
_physics3d_addBox(entity: number, hx: number, hy: number, hz: number,
px: number, py: number, pz: number,
qx: number, qy: number, qz: number, qw: number,
motion: number, gravityScale: number, linearDamping: number,
angularDamping: number, fixedRotation: number, layer: number,
continuous: number, friction: number, restitution: number,
isSensor: number, cx: number, cy: number, cz: number): number;
_physics3d_addSphere(entity: number, radius: number,
px: number, py: number, pz: number,
qx: number, qy: number, qz: number, qw: number,
motion: number, gravityScale: number, linearDamping: number,
angularDamping: number, fixedRotation: number, layer: number,
continuous: number, friction: number, restitution: number,
isSensor: number, cx: number, cy: number, cz: number): number;
_physics3d_addCapsule(entity: number, radius: number, halfHeight: number,
px: number, py: number, pz: number,
qx: number, qy: number, qz: number, qw: number,
motion: number, gravityScale: number, linearDamping: number,
angularDamping: number, fixedRotation: number, layer: number,
continuous: number, friction: number, restitution: number,
isSensor: number, cx: number, cy: number, cz: number): number;
_physics3d_addMeshBody(entity: number, vertexPtr: number, vertexCount: number,
indexPtr: number, indexCount: number,
px: number, py: number, pz: number,
qx: number, qy: number, qz: number, qw: number,
layer: number, friction: number, restitution: number): number;
_physics3d_addConvexBody(entity: number, vertexPtr: number, vertexCount: number,
px: number, py: number, pz: number,
qx: number, qy: number, qz: number, qw: number,
motion: number, gravityScale: number, linearDamping: number,
angularDamping: number, fixedRotation: number, layer: number,
continuous: number, friction: number, restitution: number,
isSensor: number): number;
_physics3d_removeBody(bodyId: number): void;
/** Optional for older binaries. Required by CompoundCollider3D, never silently approximated. */
_physics3d_addCompound?(entity: number, parts: number, count: number,
px: number, py: number, pz: number, qx: number, qy: number, qz: number, qw: number,
motion: number, gravityScale: number, linearDamping: number, angularDamping: number,
fixedRotation: number, layer: number, continuous: number, friction: number,
restitution: number, isSensor: number, mass: number): number;
_malloc(bytes: number): number;
_free(ptr: number): void;
_physics3d_setTransform(bodyId: number, px: number, py: number, pz: number,
qx: number, qy: number, qz: number, qw: number): void;
_physics3d_setLinearVelocity(bodyId: number, vx: number, vy: number, vz: number): void;
_physics3d_getBodyState(bodyId: number): number;
/** Writes (mass, wx, wy, wz) to the query buffer; 0 when the body is gone or does not move. */
_physics3d_getBodyDynamics?(bodyId: number): number;
/** A force in newtons at a world point, over the next step. */
_physics3d_addForce?(bodyId: number, fx: number, fy: number, fz: number, px: number, py: number, pz: number): void;
/** A torque in newton metres, over the next step. */
_physics3d_addTorque?(bodyId: number, tx: number, ty: number, tz: number): void;
_physics3d_addCharacter(entity: number, radius: number, halfHeight: number,
px: number, py: number, pz: number,
maxSlope: number, mass: number, layer: number,
pushForce: number): number;
_physics3d_removeCharacter(characterId: number): void;
_physics3d_moveCharacter(characterId: number, vx: number, vy: number, vz: number,
dt: number, stepUp: number, stepDown: number): void;
_physics3d_setCharacterPosition(characterId: number, px: number, py: number,
pz: number): void;
/** `_physics3d_raycast` with flags: bit 0 also meets characters. */
_physics3d_raycastWith(ox: number, oy: number, oz: number, dx: number, dy: number, dz: number,
layerMask: number, flags: number): number;
_physics3d_raycast(ox: number, oy: number, oz: number,
dx: number, dy: number, dz: number, layerMask: number): number;
_physics3d_sphereCast(px: number, py: number, pz: number, radius: number,
dx: number, dy: number, dz: number, layerMask: number): number;
_physics3d_overlapSphere(px: number, py: number, pz: number, radius: number,
layerMask: number): number;
_physics3d_overlapBox(px: number, py: number, pz: number,
hx: number, hy: number, hz: number, layerMask: number): number;
_physics3d_addSwingTwistJoint(entity: number, bodyA: number, bodyB: number,
px: number, py: number, pz: number, ax: number, ay: number, az: number,
nx: number, ny: number, nz: number, normalHalf: number, planeHalf: number,
twistMin: number, twistMax: number, collideConnected: number): number;
_physics3d_addSixDOFJoint(entity: number, bodyA: number, bodyB: number,
px: number, py: number, pz: number, ax: number, ay: number, az: number,
nx: number, ny: number, nz: number, translationMotion: number, rotationMotion: number,
lx: number, ly: number, lz: number, hx: number, hy: number, hz: number,
rx: number, ry: number, rz: number, sx: number, sy: number, sz: number,
collideConnected: number): number;
_physics3d_setAdvancedJointMotor(entity: number, enable: number,
vx: number, vy: number, vz: number, wx: number, wy: number, wz: number,
maxForce: number, maxTorque: number): void;
_physics3d_addPointJoint(entity: number, bodyA: number, bodyB: number,
px: number, py: number, pz: number,
collideConnected: number): number;
_physics3d_addHingeJoint(entity: number, bodyA: number, bodyB: number,
px: number, py: number, pz: number,
ax: number, ay: number, az: number,
enableLimit: number, lower: number, upper: number,
enableMotor: number, motorSpeed: number, maxTorque: number,
collideConnected: number): number;
_physics3d_addSliderJoint(entity: number, bodyA: number, bodyB: number,
px: number, py: number, pz: number,
ax: number, ay: number, az: number,
enableLimit: number, lower: number, upper: number,
enableMotor: number, motorSpeed: number, maxForce: number,
collideConnected: number): number;
_physics3d_addDistanceJoint(entity: number, bodyA: number, bodyB: number,
ax: number, ay: number, az: number,
bx: number, by: number, bz: number,
minLength: number, maxLength: number,
frequency: number, damping: number,
collideConnected: number): number;
_physics3d_addFixedJoint(entity: number, bodyA: number, bodyB: number,
collideConnected: number): number;
_physics3d_removeJoint(entity: number, bodyA: number, bodyB: number): void;
_physics3d_setJointMotor(entity: number, enable: number, speed: number): void;
/** Optional for older binaries: (force N, torque N m) the joint held with over the last step, to the query buffer. */
_physics3d_jointForce?(entity: number): number;
/** Optional for older binaries: every body on a line, (entity, entry, exit, point, normal) each, nearest first. */
_physics3d_raycastAll?(ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, layerMask: number, maxHits: number): number;
/** Optional for older binaries: what characters ran into this step, ten floats a meeting. */
_physics3d_characterHits?(): number;
_physics3d_characterHitsBytes?(): number;
/** Optional for older binaries: a live hinge's or slider's range, its motor's limit, a distance joint's shape. */
_physics3d_setJointLimits?(entity: number, enable: number, lower: number, upper: number): void;
_physics3d_setJointMotorLimit?(entity: number, limit: number): void;
_physics3d_setDistanceJoint?(entity: number, minLength: number, maxLength: number, frequency: number, damping: number): void;
_physics3d_jointValue(entity: number): number;
_physics3d_contactEnters(): number;
_physics3d_contactEntersBytes(): number;
/** Optional for older binaries: one closing speed for each contact begun. */
_physics3d_contactEnterSpeeds?(): number;
_physics3d_contactEnterSpeedsBytes?(): number;
/** Optional for older binaries: the mass, in kilograms, each contact begun met with. */
_physics3d_contactEnterMasses?(): number;
_physics3d_contactEnterMassesBytes?(): number;
/** Optional for older binaries: a moving body's mass in kilograms. */
_physics3d_setMass?(bodyId: number, mass: number): void;
/** Optional for older binaries: a blow in newton seconds at a world point, or the centre of mass for NaN. */
_physics3d_addImpulse?(bodyId: number, ix: number, iy: number, iz: number, px: number, py: number, pz: number): void;
_physics3d_addAngularImpulse?(bodyId: number, ix: number, iy: number, iz: number): void;
_physics3d_setAngularVelocity?(bodyId: number, wx: number, wy: number, wz: number): void;
_physics3d_setGravity?(gx: number, gy: number, gz: number): void;
_physics3d_setAwake?(bodyId: number, awake: number): void;
_physics3d_isAwake?(bodyId: number): number;
/** Optional for older binaries: (mass, centre x/y/z in metres, moments about its own axes in kg m^2) to the query buffer. */
_physics3d_getBodyMassData?(bodyId: number): number;
/** Optional for older binaries: a turned box or an upright capsule swept, written as a sphere cast is. */
_physics3d_boxCast?(px: number, py: number, pz: number, hx: number, hy: number, hz: number,
qx: number, qy: number, qz: number, qw: number, dx: number, dy: number, dz: number, layerMask: number): number;
_physics3d_capsuleCast?(px: number, py: number, pz: number, radius: number, halfHeight: number,
qx: number, qy: number, qz: number, qw: number, dx: number, dy: number, dz: number, layerMask: number): number;
_physics3d_contactExits(): number;
_physics3d_contactExitsBytes(): number;
_physics3d_sensorEnters(): number;
_physics3d_sensorEntersBytes(): number;
_physics3d_sensorExits(): number;
_physics3d_sensorExitsBytes(): number;
_physics3d_transforms(): number;
_physics3d_transformsBytes(): number;
_physics3d_queryResult(): number;
_physics3d_queryResultBytes(): number;
HEAPF32: Float32Array;
HEAPU32: Uint32Array;
}
export type Physics3DModuleFactory =
(options?: { wasmBinary?: ArrayBuffer }) => Promise<Physics3DWasmModule>;
/** One readback record: entity, position, rotation. */
export const PHYSICS3D_TRANSFORM_STRIDE = 8;
const REQUIRED_EXPORTS = [
'_physics3d_init', '_physics3d_shutdown', '_physics3d_isReady', '_physics3d_step', '_physics3d_setSolver',
'_physics3d_addBox', '_physics3d_addSphere', '_physics3d_addCapsule',
'_physics3d_removeBody', '_physics3d_setTransform', '_physics3d_raycast', '_physics3d_raycastWith',
'_physics3d_transforms', '_physics3d_transformsBytes',
'_physics3d_addCharacter', '_physics3d_moveCharacter', '_physics3d_removeCharacter',
'_physics3d_setCharacterPosition',
'_physics3d_sphereCast', '_physics3d_overlapSphere', '_physics3d_overlapBox',
'_physics3d_contactEnters', '_physics3d_contactEntersBytes',
'_physics3d_sensorEnters', '_physics3d_sensorEntersBytes',
'_physics3d_addHingeJoint', '_physics3d_removeJoint',
'_physics3d_addSwingTwistJoint', '_physics3d_addSixDOFJoint', '_physics3d_setAdvancedJointMotor',
] as const;
/** Throws naming what is missing, rather than letting the first frame do it. */
export function assertPhysics3DContract(module: unknown): void {
const bag = module as Record<string, unknown>;
const missing = REQUIRED_EXPORTS.filter((name) => typeof bag?.[name] !== 'function');
if (missing.length > 0) {
throw new Error(`physics3d.wasm is missing ${missing.join(', ')} — it was built `
+ 'from sources older than the code driving it');
}
}
/** Load the module from `url`, or adopt a factory a host already resolved. */
export async function loadPhysics3DModule(
url: string, factory?: Physics3DModuleFactory,
): Promise<Physics3DWasmModule> {
const resolved = factory
?? ((await import(/* @vite-ignore */ url)) as { default: Physics3DModuleFactory }).default;
const module = await resolved();
assertPhysics3DContract(module);
return module;
}
// =============================================================================
// Events
// =============================================================================
/** Two bodies met, and where. */
export interface Contact3DEvent {
entityA: Entity;
entityB: Entity;
normalX: number;
normalY: number;
normalZ: number;
pointX: number;
pointY: number;
pointZ: number;
/**
* How fast A was closing on B where they met, along the normal, in world units a second, read before the solver
* answered: a ball dropped on a floor from a metre lands at about 4.4 m/s. Undefined from a binary too old to say.
*/
speed?: number;
/**
* The mass they met with, in kilograms: 1 / (1/a + 1/b), where a body that does not move counts as having no
* inverse mass, so a stone landing on a floor meets it with the stone's own. Infinity where neither moves of itself.
*/
mass?: number;
/**
* How hard: `speed` times `mass`, in kilograms by world units a second, the push it takes to stop the two coming
* together. A 1 kg stone landing at 10 m/s in a scene of 100 units to the metre is 1000.
*/
impulse?: number;
}
/** A character ran into something it was not already touching, as a contact between bodies would say it. */
export interface CharacterHit3DEvent {
character: Entity;
other: Entity;
pointX: number;
pointY: number;
pointZ: number;
/** Toward the character. */
normalX: number;
normalY: number;
normalZ: number;
/** How fast it closed on what it met, world units a second. */
speed: number;
/** The mass they met with, kilograms: the character's own against something that does not move. */
mass: number;
/** `speed` times `mass`, as a contact's: what a Breakable it ran into is struck with. */
impulse: number;
}
/** A joint gave way: which, and what it was holding when it did. */
export interface JointBreak3DEvent {
entity: Entity;
/** Newtons. */
force: number;
/** Newton metres. */
torque: number;
}
/** A sensor was entered or left. The SENSOR is always named first. */
export interface Sensor3DEvent {
sensorEntity: Entity;
visitorEntity: Entity;
}
export interface Physics3DEventsData {
contactEnters: Contact3DEvent[];
/** Ends carry only the pair: at that moment the bodies are locked and one may
* already be gone, so there is no geometry left to report. */
contactExits: Array<{ entityA: Entity; entityB: Entity }>;
sensorEnters: Sensor3DEvent[];
sensorExits: Sensor3DEvent[];
/** What characters ran into this step; empty from a binary too old to say. */
characterHits?: CharacterHit3DEvent[];
/** Joints that gave way this step. */
jointBreaks?: JointBreak3DEvent[];
}
/**
* This step's 3D collision and trigger events. Drained per fixed step, so a
* system reading it must run inside one — a read from `Update` sees whatever the
* last step left.
*
* @experimental
*/
export const Physics3DEvents = defineResource<Physics3DEventsData>({
contactEnters: [],
contactExits: [],
sensorEnters: [],
sensorExits: [],
}, 'Physics3DEvents');
/**
* Refill `events` from the module's four buffers. A contact point is made in the world's own
* units, so `pixelsPerUnit` brings it into the space `Transform` and the queries speak.
*/
export function drainPhysics3DEvents(module: Physics3DWasmModule,
events: Physics3DEventsData,
pixelsPerUnit = 1): void {
const f32 = module.HEAPF32;
const read = <T>(ptr: number, bytes: number, stride: number,
make: (base: number) => T): T[] => {
const out: T[] = [];
const base = ptr >> 2;
for (let i = 0; i < bytes / 4; i += stride) out.push(make(base + i));
return out;
};
events.contactEnters = read(
module._physics3d_contactEnters(), module._physics3d_contactEntersBytes(), 8,
(o) => ({
entityA: f32[o] as Entity, entityB: f32[o + 1] as Entity,
normalX: f32[o + 2]!, normalY: f32[o + 3]!, normalZ: f32[o + 4]!,
pointX: f32[o + 5]! * pixelsPerUnit, pointY: f32[o + 6]! * pixelsPerUnit, pointZ: f32[o + 7]! * pixelsPerUnit,
}));
if (module._physics3d_contactEnterSpeeds && module._physics3d_contactEnterSpeedsBytes) {
const speeds = read(module._physics3d_contactEnterSpeeds(), module._physics3d_contactEnterSpeedsBytes(), 1, (o) => f32[o]!);
// One for each contact, in its order; a count that does not match is a binary that writes something else.
if (speeds.length === events.contactEnters.length) events.contactEnters.forEach((c, i) => { c.speed = speeds[i]! * pixelsPerUnit; });
}
if (module._physics3d_contactEnterMasses && module._physics3d_contactEnterMassesBytes) {
const masses = read(module._physics3d_contactEnterMasses(), module._physics3d_contactEnterMassesBytes(), 1, (o) => f32[o]!);
if (masses.length === events.contactEnters.length) {
events.contactEnters.forEach((c, i) => {
c.mass = masses[i]!;
// Nothing pushes at no speed, however heavy: an unmoving pair is no blow.
if (c.speed !== undefined) c.impulse = c.speed > 0 ? c.speed * c.mass : 0;
});
}
}
if (module._physics3d_characterHits && module._physics3d_characterHitsBytes) {
events.characterHits = read(module._physics3d_characterHits(), module._physics3d_characterHitsBytes(), 10, (o) => {
const speed = f32[o + 8]! * pixelsPerUnit, mass = f32[o + 9]!;
return {
character: f32[o] as Entity, other: f32[o + 1] as Entity,
pointX: f32[o + 2]! * pixelsPerUnit, pointY: f32[o + 3]! * pixelsPerUnit, pointZ: f32[o + 4]! * pixelsPerUnit,
normalX: f32[o + 5]!, normalY: f32[o + 6]!, normalZ: f32[o + 7]!,
speed, mass, impulse: speed > 0 ? speed * mass : 0,
};
});
}
events.jointBreaks = [];
events.contactExits = read(
module._physics3d_contactExits(), module._physics3d_contactExitsBytes(), 2,
(o) => ({ entityA: f32[o] as Entity, entityB: f32[o + 1] as Entity }));
events.sensorEnters = read(
module._physics3d_sensorEnters(), module._physics3d_sensorEntersBytes(), 2,
(o) => ({ sensorEntity: f32[o] as Entity, visitorEntity: f32[o + 1] as Entity }));
events.sensorExits = read(
module._physics3d_sensorExits(), module._physics3d_sensorExitsBytes(), 2,
(o) => ({ sensorEntity: f32[o] as Entity, visitorEntity: f32[o + 1] as Entity }));
}