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 PhysicsModuleLoader.ts
* @brief Loads and initializes the Physics WASM module (standalone or side module)
*/
export interface PhysicsWasmModule {
_physics_init(gx: number, gy: number, timestep: number, substeps: number,
contactHertz: number, contactDampingRatio: number, contactSpeed: number): void;
/** World-level tuning (sleeping/continuous/restitution threshold/max speed). */
_physics_setWorldConfig(enableSleep: number, enableContinuous: number,
restitutionThreshold: number, maxLinearSpeed: number): void;
_physics_shutdown(): void;
_physics_createBody(entityId: number, bodyType: number, x: number, y: number, angle: number,
gravityScale: number, linearDamping: number, angularDamping: number,
fixedRotation: number, bullet: number): void;
_physics_destroyBody(entityId: number): void;
_physics_hasBody(entityId: number): number;
/** Enable/disable a body in place (keeps shapes/velocity/joints). */
_physics_setBodyEnabled(entityId: number, enabled: number): void;
/** Destroy all of an entity's shapes, keeping the body, for in-place rebuild. */
_physics_clearShapes(entityId: number): void;
_physics_addBoxShape(entityId: number, halfW: number, halfH: number,
offX: number, offY: number, radius: number,
density: number, friction: number, restitution: number, isSensor: number,
categoryBits: number, maskBits: number): void;
_physics_addCircleShape(entityId: number, radius: number,
offX: number, offY: number,
density: number, friction: number, restitution: number, isSensor: number,
categoryBits: number, maskBits: number): void;
_physics_addCapsuleShape(entityId: number, radius: number, halfHeight: number,
offX: number, offY: number,
density: number, friction: number, restitution: number, isSensor: number,
categoryBits: number, maskBits: number): void;
_physics_addSegmentShape(entityId: number, x1: number, y1: number, x2: number, y2: number,
density: number, friction: number, restitution: number, isSensor: number,
categoryBits: number, maskBits: number): void;
_physics_addPolygonShape(entityId: number, verticesPtr: number, vertexCount: number, radius: number,
density: number, friction: number, restitution: number, isSensor: number,
categoryBits: number, maskBits: number): void;
_physics_addChainShape(entityId: number, pointsPtr: number, pointCount: number, isLoop: number,
friction: number, restitution: number,
categoryBits: number, maskBits: number): void;
_physics_step(dt: number): void;
_physics_setBodyTransform(entityId: number, x: number, y: number, angle: number): void;
/** Batch world-pixel poses; returns how many live bodies actually moved. */
_physics_setBodyTransforms?(bufferPtr: number, count: number, ppu: number): number;
_physics_setBodyTargetTransform(entityId: number, x: number, y: number, angle: number, dt: number): void;
_physics_getDynamicBodyCount(): number;
_physics_getBodyCount(): number;
_physics_getShapeCount(): number;
_physics_getJointCount(): number;
_physics_getTrackingRows(): number;
_physics_getDynamicBodyTransforms(): number;
/**
* Render interpolation, done by the module. It keeps the two most recent
* fixed-step snapshots itself and lerps them, because that loop runs over
* every dynamic body every frame — the shape of work the no-JIT budget keeps
* off the JS path (docs/REARCH_NATIVE.md §3.2).
*/
_physics_capturePoses(): void;
_physics_getInterpolatedCount(): number;
_physics_getInterpolatedTransforms(alpha: number): number;
_physics_collectEvents(): void;
_physics_getCollisionEnterCount(): number;
_physics_getCollisionEnterBuffer(): number;
/** High-speed impact events: [entityA, entityB, px, py, nx, ny, approachSpeed]. */
_physics_getHitEventCount(): number;
_physics_getHitEventBuffer(): number;
_physics_getCollisionExitCount(): number;
_physics_getCollisionExitBuffer(): number;
_physics_getSensorEnterCount(): number;
_physics_getSensorEnterBuffer(): number;
_physics_getSensorExitCount(): number;
_physics_getSensorExitBuffer(): number;
_physics_applyForce(entityId: number, forceX: number, forceY: number): void;
_physics_applyImpulse(entityId: number, impulseX: number, impulseY: number): void;
_physics_setLinearVelocity(entityId: number, vx: number, vy: number): void;
_physics_getLinearVelocity(entityId: number): number;
_physics_setGravity(gx: number, gy: number): void;
_physics_getGravity(): number;
_physics_setAngularVelocity(entityId: number, omega: number): void;
_physics_getAngularVelocity(entityId: number): number;
_physics_applyTorque(entityId: number, torque: number): void;
_physics_applyAngularImpulse(entityId: number, impulse: number): void;
_physics_updateBodyProperties(entityId: number, bodyType: number,
gravityScale: number, linearDamping: number, angularDamping: number,
fixedRotation: number, bullet: number): void;
_physics_setOneWayPlatform(entityId: number, nx: number, ny: number, enable: number): void;
_physics_setOneWayPlatformLocal(entityId: number, nx: number, ny: number, enable: number): void;
_physics_createRevoluteJoint(entityIdA: number, entityIdB: number,
anchorAx: number, anchorAy: number, anchorBx: number, anchorBy: number,
enableMotor: number, motorSpeed: number, maxMotorTorque: number,
enableLimit: number, lowerAngle: number, upperAngle: number,
collideConnected: number): number;
_physics_destroyJoint(entityId: number): void;
_physics_hasJoint(entityId: number): number;
_physics_setRevoluteMotorSpeed(entityId: number, speed: number): void;
_physics_setRevoluteMaxMotorTorque(entityId: number, torque: number): void;
_physics_enableRevoluteMotor(entityId: number, enable: number): void;
_physics_enableRevoluteLimit(entityId: number, enable: number): void;
_physics_setRevoluteLimits(entityId: number, lower: number, upper: number): void;
_physics_getRevoluteAngle(entityId: number): number;
_physics_getRevoluteMotorTorque(entityId: number): number;
_physics_createDistanceJoint(entityIdA: number, entityIdB: number,
anchorAx: number, anchorAy: number, anchorBx: number, anchorBy: number,
length: number, enableSpring: number, hertz: number, dampingRatio: number,
enableLimit: number, minLength: number, maxLength: number,
enableMotor: number, maxMotorForce: number, motorSpeed: number,
collideConnected: number): number;
_physics_createPrismaticJoint(entityIdA: number, entityIdB: number,
anchorAx: number, anchorAy: number, anchorBx: number, anchorBy: number,
axisX: number, axisY: number,
enableSpring: number, hertz: number, dampingRatio: number,
enableLimit: number, lowerTranslation: number, upperTranslation: number,
enableMotor: number, maxMotorForce: number, motorSpeed: number,
collideConnected: number): number;
_physics_createWeldJoint(entityIdA: number, entityIdB: number,
anchorAx: number, anchorAy: number, anchorBx: number, anchorBy: number,
linearHertz: number, angularHertz: number,
linearDampingRatio: number, angularDampingRatio: number,
collideConnected: number): number;
_physics_createWheelJoint(entityIdA: number, entityIdB: number,
anchorAx: number, anchorAy: number, anchorBx: number, anchorBy: number,
axisX: number, axisY: number,
enableSpring: number, hertz: number, dampingRatio: number,
enableLimit: number, lowerTranslation: number, upperTranslation: number,
enableMotor: number, maxMotorTorque: number, motorSpeed: number,
collideConnected: number): number;
_physics_createMotorJoint(entityIdA: number, entityIdB: number,
linearVelX: number, linearVelY: number, maxVelocityForce: number,
angularVelocity: number, maxVelocityTorque: number,
linearHertz: number, linearDampingRatio: number, maxSpringForce: number,
angularHertz: number, angularDampingRatio: number, maxSpringTorque: number,
collideConnected: number): number;
_physics_setMotorJointLinearVelocity(entityId: number, vx: number, vy: number): void;
_physics_setMotorJointAngularVelocity(entityId: number, omega: number): void;
_physics_setMotorJointMaxVelocityForce(entityId: number, force: number): void;
_physics_setMotorJointMaxVelocityTorque(entityId: number, torque: number): void;
_physics_createMouseJoint(entityId: number, targetX: number, targetY: number,
hertz: number, dampingRatio: number, maxForce: number): number;
_physics_setMouseTarget(targetX: number, targetY: number): void;
_physics_destroyMouseJoint(): void;
_physics_hasMouseJoint(): number;
_physics_raycast(originX: number, originY: number, dirX: number, dirY: number,
maxDistance: number, maskBits: number): number;
_physics_getRaycastBuffer(): number;
_physics_overlapCircle(centerX: number, centerY: number, radius: number, maskBits: number): number;
_physics_getOverlapBuffer(): number;
_physics_setAwake(entityId: number, awake: number): void;
_physics_isAwake(entityId: number): number;
_physics_shapeCastCircle(centerX: number, centerY: number, radius: number,
translationX: number, translationY: number, maskBits: number): number;
_physics_shapeCastBox(centerX: number, centerY: number, halfW: number, halfH: number, angle: number,
translationX: number, translationY: number, maskBits: number): number;
_physics_shapeCastCapsule(center1X: number, center1Y: number, center2X: number, center2Y: number,
radius: number, translationX: number, translationY: number, maskBits: number): number;
_physics_getShapeCastBuffer(): number;
_physics_moveCharacter(px: number, py: number, c1x: number, c1y: number, c2x: number, c2y: number,
radius: number, velX: number, velY: number, dt: number, upX: number, upY: number, floorCos: number,
maskBits: number, selfEntity: number,
skinWidth: number, maxSlides: number, snapLength: number, slideOnCeiling: number,
carryX: number, carryY: number, flags: number, stepHeight: number): number;
_physics_getMoveCharacterBuffer(): number;
_physics_overlapAABB(minX: number, minY: number, maxX: number, maxY: number, maskBits: number): number;
_physics_getBodyMass(entityId: number): number;
_physics_getBodyInertia(entityId: number): number;
_physics_getBodyCenterOfMass(entityId: number): number;
_physics_getDistanceJointLength(entityId: number): number;
_physics_getDistanceJointCurrentLength(entityId: number): number;
_physics_setDistanceJointLength(entityId: number, length: number): void;
_physics_enableDistanceJointSpring(entityId: number, enable: number): void;
_physics_enableDistanceJointLimit(entityId: number, enable: number): void;
_physics_setDistanceJointLimits(entityId: number, minLength: number, maxLength: number): void;
_physics_enableDistanceJointMotor(entityId: number, enable: number): void;
_physics_setDistanceJointMotorSpeed(entityId: number, speed: number): void;
_physics_setDistanceJointMaxMotorForce(entityId: number, force: number): void;
_physics_getDistanceJointMotorForce(entityId: number): number;
_physics_getPrismaticJointTranslation(entityId: number): number;
_physics_getPrismaticJointSpeed(entityId: number): number;
_physics_enablePrismaticJointSpring(entityId: number, enable: number): void;
_physics_enablePrismaticJointLimit(entityId: number, enable: number): void;
_physics_setPrismaticJointLimits(entityId: number, lower: number, upper: number): void;
_physics_enablePrismaticJointMotor(entityId: number, enable: number): void;
_physics_setPrismaticJointMotorSpeed(entityId: number, speed: number): void;
_physics_setPrismaticJointMaxMotorForce(entityId: number, force: number): void;
_physics_getPrismaticJointMotorForce(entityId: number): number;
_physics_enableWheelJointSpring(entityId: number, enable: number): void;
_physics_enableWheelJointLimit(entityId: number, enable: number): void;
_physics_setWheelJointLimits(entityId: number, lower: number, upper: number): void;
_physics_enableWheelJointMotor(entityId: number, enable: number): void;
_physics_setWheelJointMotorSpeed(entityId: number, speed: number): void;
_physics_setWheelJointMaxMotorTorque(entityId: number, torque: number): void;
_physics_getWheelJointMotorTorque(entityId: number): number;
HEAPF32: Float32Array;
HEAPU8: Uint8Array;
HEAPU32: Uint32Array;
_malloc(size: number): number;
_free(ptr: number): void;
}
export type PhysicsModuleFactory = (config?: Record<string, unknown>) => Promise<PhysicsWasmModule>;
export async function loadPhysicsModule(
wasmUrl: string,
factory?: PhysicsModuleFactory
): Promise<PhysicsWasmModule> {
if (!factory) {
throw new Error(
'PhysicsModuleLoader: factory parameter is required. ' +
'Pass the Physics WASM factory function explicitly via loadPhysicsModule(url, factory).'
);
}
return factory();
}