Skip to content

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.

feat(physics3d): the solid world gets the door the flat one always had

esengine60ca019b89fe
diff --git a/build-tools/tasks/sdk.js b/build-tools/tasks/sdk.js
index 7aa6e7ec7..86a0fad69 100644
--- a/build-tools/tasks/sdk.js
+++ b/build-tools/tasks/sdk.js
@@ -31,6 +31,8 @@ export async function buildSdk(options = {}) {
'esm/spine/index.d.ts',
'esm/physics/index.js',
'esm/physics/index.d.ts',
+ 'esm/physics3d/index.js',
+ 'esm/physics3d/index.d.ts',
'cjs/esengine.wechat.js',
'cjs/index.wechat.js',
];
@@ -110,10 +112,12 @@ async function copyDistOutputs(sdkDir, outputDir) {
const spineDir = path.join(esmDir, 'spine');
const dragonBonesDir = path.join(esmDir, 'dragonbones');
const physicsDir = path.join(esmDir, 'physics');
+ const physics3dDir = path.join(esmDir, 'physics3d');
const sharedDir = path.join(esmDir, 'shared');
await mkdir(spineDir, { recursive: true });
await mkdir(dragonBonesDir, { recursive: true });
await mkdir(physicsDir, { recursive: true });
+ await mkdir(physics3dDir, { recursive: true });
await mkdir(sharedDir, { recursive: true });
const files = [
@@ -129,6 +133,8 @@ async function copyDistOutputs(sdkDir, outputDir) {
{ src: 'dragonbones/index.d.ts', dest: path.join(dragonBonesDir, 'index.d.ts') },
{ src: 'physics/index.js', dest: path.join(physicsDir, 'index.js') },
{ src: 'physics/index.d.ts', dest: path.join(physicsDir, 'index.d.ts') },
+ { src: 'physics3d/index.js', dest: path.join(physics3dDir, 'index.js') },
+ { src: 'physics3d/index.d.ts', dest: path.join(physics3dDir, 'index.d.ts') },
{ src: 'index.wechat.js', dest: path.join(cjsDir, 'index.wechat.js') },
{ src: 'index.wechat.cjs.js', dest: path.join(cjsDir, 'esengine.wechat.js') },
];
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index eb1812cfc..a7ffc8819 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -123,6 +123,7 @@ export default defineConfig({
entryPoints: [
'../../sdk/src/index.ts',
'../../sdk/src/physics/index.ts',
+ '../../sdk/src/physics3d/index.ts',
'../../sdk/src/spine/index.ts',
'../../sdk/src/dragonbones/index.ts',
],
diff --git a/pipeline/src/bundle/esengineResolve.ts b/pipeline/src/bundle/esengineResolve.ts
index 7be8a9cfd..997d254d1 100644
--- a/pipeline/src/bundle/esengineResolve.ts
+++ b/pipeline/src/bundle/esengineResolve.ts
@@ -28,6 +28,7 @@ export function esengineAlias(sdkDir: string, mainEntry = 'index.js'): Record<st
'esengine/spine': path.join(sdkDir, 'spine', 'index.js'),
'esengine/dragonbones': path.join(sdkDir, 'dragonbones', 'index.js'),
'esengine/physics': path.join(sdkDir, 'physics', 'index.js'),
+ 'esengine/physics3d': path.join(sdkDir, 'physics3d', 'index.js'),
'esengine/wasm': path.join(sdkDir, 'wasm.js'),
'esengine/factory': path.join(sdkDir, 'webAppFactory.js'),
};
diff --git a/pipeline/src/bundle/importMap.ts b/pipeline/src/bundle/importMap.ts
index 5cf48fb77..3ab1fd656 100644
--- a/pipeline/src/bundle/importMap.ts
+++ b/pipeline/src/bundle/importMap.ts
@@ -16,6 +16,7 @@ export const IMPORT_MAP = {
'esengine/spine': './sdk/spine/index.js',
'esengine/dragonbones': './sdk/dragonbones/index.js',
'esengine/physics': './sdk/physics/index.js',
+ 'esengine/physics3d': './sdk/physics3d/index.js',
'esengine/wasm': './sdk/wasm.js',
'esengine/factory': './sdk/webAppFactory.js',
},
diff --git a/sdk/etc/physics3d.api.md b/sdk/etc/physics3d.api.md
new file mode 100644
index 000000000..06b741d2f
--- /dev/null
+++ b/sdk/etc/physics3d.api.md
@@ -0,0 +1,468 @@
+# API surface — esengine/physics3d
+
+<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
+Symbols: 0 public · 9 beta · 49 experimental · 0 deprecated
+
+## BoxCollider3D — const @experimental
+```
+BuiltinComponentDef<BoxCollider3DData>
+```
+
+## BoxCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+halfExtents: Vec3
+isSensor: boolean
+restitution: number
+```
+
+## COLLIDER3D_RING_SEGMENTS — const @experimental
+```
+24
+```
+
+## CapsuleCollider3D — const @experimental
+```
+BuiltinComponentDef<CapsuleCollider3DData>
+```
+
+## CapsuleCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+halfHeight: number
+isSensor: boolean
+radius: number
+restitution: number
+```
+
+## Cast3DHit — interface @experimental
+```
+entity: number
+fraction: number
+normalX: number
+normalY: number
+normalZ: number
+x: number
+y: number
+z: number
+```
+
+## CharacterController3D — const @beta
+```
+BuiltinComponentDef<CharacterController3DData>
+```
+
+## CharacterController3DData — interface @experimental
+```
+enabled: boolean
+floorNormal: Vec3
+halfHeight: number
+isOnFloor: boolean
+layer: number
+mass: number
+maxSlope: number
+pushForce: number
+radius: number
+realVelocity: Vec3
+snapDown: number
+stepHeight: number
+velocity: Vec3
+```
+
+## Collider3DComponent — type @experimental
+```
+| 'BoxCollider3D' | 'SphereCollider3D' | 'CapsuleCollider3D'
+ | 'MeshCollider3D' | 'ConvexCollider3D' | 'CharacterController3D'
+```
+
+## Collider3DInstance — interface @experimental
+```
+active: boolean
+component: Collider3DComponent
+isSensor: boolean
+shape: Collider3DShape
+```
+
+## Collider3DShape — type @experimental
+```
+| { kind: 'box'; halfExtents: Vec3; center: Vec3 }
+ | { kind: 'sphere'; radius: number }
+ | { kind: 'capsule'; radius: number; halfHeight: number }
+```
+
+## Contact3DEvent — interface @experimental
+```
+entityA: number
+entityB: number
+normalX: number
+normalY: number
+normalZ: number
+pointX: number
+pointY: number
+pointZ: number
+```
+
+## ConvexCollider3D — const @beta
+```
+BuiltinComponentDef<ConvexCollider3DData>
+```
+
+## ConvexCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+isSensor: boolean
+mesh: number
+restitution: number
+```
+
+## DEFAULT_PHYSICS3D_CONFIG — const @experimental
+```
+Physics3DConfig
+```
+
+## DistanceJoint3D — const @beta
+```
+ComponentDef<DistanceJoint3DData>
+```
+
+## DistanceJoint3DData — interface @experimental
+```
+anchor: Vec3
+collideConnected: boolean
+connectedAnchor: Vec3
+connectedEntity: number
+damping: number
+enabled: boolean
+frequency: number
+maxLength: number
+minLength: number
+```
+
+## FixedJoint3D — const @beta
+```
+ComponentDef<FixedJoint3DData>
+```
+
+## FixedJoint3DData — interface @experimental
+```
+collideConnected: boolean
+connectedEntity: number
+enabled: boolean
+```
+
+## HingeJoint3D — const @beta
+```
+ComponentDef<HingeJoint3DData>
+```
+
+## HingeJoint3DData — interface @experimental
+```
+anchor: Vec3
+angle: number
+axis: Vec3
+collideConnected: boolean
+connectedEntity: number
+enableLimit: boolean
+enableMotor: boolean
+enabled: boolean
+lowerAngle: number
+maxMotorTorque: number
+motorSpeed: number
+upperAngle: number
+```
+
+## Joint3DShape — interface @experimental
+```
+anchor: Vec3 | null
+axis: Vec3 | null
+connectedAnchor: Vec3 | null
+connectedEntity: number
+enabled: boolean
+type: string
+```
+
+## MeshCollider3D — const @beta
+```
+BuiltinComponentDef<MeshCollider3DData>
+```
+
+## MeshCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+layer: number
+mesh: number
+restitution: number
+```
+
+## Overlap3DHit — interface @experimental
+```
+entity: number
+x: number
+y: number
+z: number
+```
+
+## PHYSICS3D_TRANSFORM_STRIDE — const @experimental
+```
+8
+```
+
+## Physics3D — const @experimental
+```
+ResourceDef<Physics3DQueries | null>
+```
+
+## Physics3DConfig — interface @experimental
+```
+collisionSteps: number
+fixedTimestep: number
+gravity: { x: number; y: number; z: number; }
+layerMasks: number[] | undefined
+maxBodies: number
+pixelsPerUnit: number
+```
+
+## Physics3DDebugDraw — const @experimental
+```
+ResourceDef<Physics3DDebugDrawConfig>
+```
+
+## Physics3DDebugDrawConfig — interface @experimental
+```
+enabled: boolean
+showColliders: boolean
+showContacts: boolean
+```
+
+## Physics3DEvents — const @beta
+```
+ResourceDef<Physics3DEventsData>
+```
+
+## Physics3DEventsData — interface @experimental
+```
+contactEnters: Contact3DEvent[]
+contactExits: { entityA: Entity; entityB: Entity; }[]
+sensorEnters: Sensor3DEvent[]
+sensorExits: Sensor3DEvent[]
+```
+
+## Physics3DModuleFactory — type @experimental
+```
+(options?: { wasmBinary?: ArrayBuffer }) => Promise<Physics3DWasmModule>
+```
+
+## Physics3DPlugin — class @experimental
+```
+build: (app: App) => void
+cleanup: () => void
+name: string
+static new (wasmUrl: string, config?: Partial<Physics3DConfig>, factory?: Physics3DModuleFactory): Physics3DPlugin
+static prototype: Physics3DPlugin
+```
+
+## Physics3DQueries — class @experimental
+```
+overlapBox: (centre: { x: number; y: number; z: number; }, halfExtents: { x: number; y: number; z: number; }, layerMask?: number) => Overlap3DHit[]
+overlapSphere: (centre: { x: number; y: number; z: number; }, radius: number, layerMask?: number) => Overlap3DHit[]
+raycast: (origin: { x: number; y: number; z: number; }, direction: { x: number; y: number; z: number; }, layerMask?: number) => Cast3DHit | null
+sphereCast: (origin: { x: number; y: number; z: number; }, radius: number, direction: { x: number; y: number; z: number; }, layerMask?: number) => Cast3DHit | null
+static new (module_: Physics3DWasmModule, ppu_: number): Physics3DQueries
+static prototype: Physics3DQueries
+```
+
+## Physics3DRuntime — interface @experimental
+```
+bodies: Map<number, number>
+characters: Map<number, number>
+initPromise: Promise<unknown> | null
+joints: Joint3DMap
+module: Physics3DWasmModule | null
+```
+
+## Physics3DWasmModule — interface @experimental
+```
+HEAPF32: Float32Array<ArrayBufferLike>
+HEAPU32: Uint32Array<ArrayBufferLike>
+_free: (ptr: number) => void
+_malloc: (bytes: number) => number
+_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) => 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) => number
+_physics3d_addCharacter: (entity: number, radius: number, halfHeight: number, px: number, py: number, pz: number, maxSlope: number, mass: number, layer: number, pushForce: 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_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_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_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_addPointJoint: (entity: number, bodyA: number, bodyB: number, px: number, py: number, pz: 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_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) => number
+_physics3d_contactEnters: () => number
+_physics3d_contactEntersBytes: () => number
+_physics3d_contactExits: () => number
+_physics3d_contactExitsBytes: () => number
+_physics3d_getBodyState: (bodyId: number) => number
+_physics3d_init: (gx: number, gy: number, gz: number, maxBodies: number) => void
+_physics3d_isReady: () => number
+_physics3d_jointValue: (entity: number) => number
+_physics3d_moveCharacter: (characterId: number, vx: number, vy: number, vz: number, dt: number, stepUp: number, stepDown: number) => void
+_physics3d_optimize: () => void
+_physics3d_overlapBox: (px: number, py: number, pz: number, hx: number, hy: number, hz: number, layerMask: number) => number
+_physics3d_overlapSphere: (px: number, py: number, pz: number, radius: number, layerMask: number) => number
+_physics3d_queryResult: () => number
+_physics3d_queryResultBytes: () => number
+_physics3d_raycast: (ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, layerMask: number) => number
+_physics3d_removeBody: (bodyId: number) => void
+_physics3d_removeCharacter: (characterId: number) => void
+_physics3d_removeJoint: (entity: number, bodyA: number, bodyB: number) => void
+_physics3d_sensorEnters: () => number
+_physics3d_sensorEntersBytes: () => number
+_physics3d_sensorExits: () => number
+_physics3d_sensorExitsBytes: () => number
+_physics3d_setCharacterPosition: (characterId: number, px: number, py: number, pz: number) => void
+_physics3d_setJointMotor: (entity: number, enable: number, speed: number) => void
+_physics3d_setLayerMask: (layer: number, mask: number) => void
+_physics3d_setLinearVelocity: (bodyId: number, vx: number, vy: number, vz: number) => void
+_physics3d_setTransform: (bodyId: number, px: number, py: number, pz: number, qx: number, qy: number, qz: number, qw: number) => void
+_physics3d_shutdown: () => void
+_physics3d_sphereCast: (px: number, py: number, pz: number, radius: number, dx: number, dy: number, dz: number, layerMask: number) => number
+_physics3d_step: (dt: number, collisionSteps: number) => void
+_physics3d_transforms: () => number
+_physics3d_transformsBytes: () => number
+```
+
+## PointJoint3D — const @beta
+```
+ComponentDef<PointJoint3DData>
+```
+
+## PointJoint3DData — interface @experimental
+```
+anchor: Vec3
+collideConnected: boolean
+connectedEntity: number
+enabled: boolean
+```
+
+## RigidBody3D — const @experimental
+```
+BuiltinComponentDef<RigidBody3DData>
+```
+
+## RigidBody3DData — interface @experimental
+```
+angularDamping: number
+bodyType: number
+continuousCollision: boolean
+enabled: boolean
+fixedRotation: boolean
+gravityScale: number
+layer: number
+linearDamping: number
+```
+
+## Sensor3DEvent — interface @experimental
+```
+sensorEntity: number
+visitorEntity: number
+```
+
+## SliderJoint3D — const @beta
+```
+ComponentDef<SliderJoint3DData>
+```
+
+## SliderJoint3DData — interface @experimental
+```
+anchor: Vec3
+axis: Vec3
+collideConnected: boolean
+connectedEntity: number
+enableLimit: boolean
+enableMotor: boolean
+enabled: boolean
+lowerTranslation: number
+maxMotorForce: number
+motorSpeed: number
+translation: number
+upperTranslation: number
+```
+
+## SphereCollider3D — const @experimental
+```
+BuiltinComponentDef<SphereCollider3DData>
+```
+
+## SphereCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+isSensor: boolean
+radius: number
+restitution: number
+```
+
+## assertPhysics3DContract — function @experimental
+```
+(module: unknown): void
+```
+
+## collider3DWireframe — function @experimental
+```
+(shape: Collider3DShape, segments?: number): Vec3[][]
+```
+
+## drainPhysics3DEvents — function @experimental
+```
+(module: Physics3DWasmModule, events: Physics3DEventsData): void
+```
+
+## drawPhysics3DDebug — function @experimental
+```
+(app: App, contacts?: readonly Contact3D[]): void
+```
+
+## loadPhysics3DModule — function @experimental
+```
+(url: string, factory?: Physics3DModuleFactory): Promise<Physics3DWasmModule>
+```
+
+## physics3dPlugin — function @experimental
+```
+(wasmUrl: string, config?: Partial<Physics3DConfig>, factory?: Physics3DModuleFactory): Physics3DPlugin
+```
+
+## placeCollider3DWireframe — function @experimental
+```
+(lines: Vec3[][], position: Vec3, rotation: Quat): Vec3[][]
+```
+
+## readCollider3DShapes — function @experimental
+```
+(world: World, entity: number): Collider3DInstance[]
+```
+
+## readJoint3D — function @experimental
+```
+(world: World, entity: number): Joint3DShape | null
+```
+
+## rotateVec3ByQuat — function @experimental
+```
+(rot: Quat, v: Vec3): Vec3
+```
+
+## setupPhysics3DDebugDraw — function @experimental
+```
+(app: App, contacts: () => readonly Contact3D[]): void
+```
+
+## stepPhysics3D — function @experimental
+```
+(app: App, module: Physics3DWasmModule, bodies: BodyMap, config: Physics3DConfig, characters?: BodyMap, events?: Physics3DEventsData, joints?: Joint3DMap): void
+```
+
diff --git a/sdk/package.json b/sdk/package.json
index bc73394dc..1ee703f9c 100644
--- a/sdk/package.json
+++ b/sdk/package.json
@@ -48,6 +48,10 @@
"./physics": {
"import": "./dist/physics/index.js",
"types": "./dist/physics/index.d.ts"
+ },
+ "./physics3d": {
+ "import": "./dist/physics3d/index.js",
+ "types": "./dist/physics3d/index.d.ts"
}
},
"files": [
diff --git a/sdk/rolldown.config.js b/sdk/rolldown.config.js
index e96fc9d59..48d18567b 100644
--- a/sdk/rolldown.config.js
+++ b/sdk/rolldown.config.js
@@ -55,6 +55,7 @@ export default defineConfig([
'index.minigame': 'src/index.minigame.ts',
'index.native': 'src/index.native.ts',
'physics/index': 'src/physics/index.ts',
+ 'physics3d/index': 'src/physics3d/index.ts',
'spine/index': 'src/spine/index.ts',
'dragonbones/index': 'src/dragonbones/index.ts',
'wasm': 'src/wasm.ts',
diff --git a/sdk/rollup.config.js b/sdk/rollup.config.js
index a038e9ac5..563a60b59 100644
--- a/sdk/rollup.config.js
+++ b/sdk/rollup.config.js
@@ -15,6 +15,7 @@ export default [
'index.minigame': 'src/index.minigame.ts',
'index.native': 'src/index.native.ts',
'physics/index': 'src/physics/index.ts',
+ 'physics3d/index': 'src/physics3d/index.ts',
'spine/index': 'src/spine/index.ts',
'dragonbones/index': 'src/dragonbones/index.ts',
'wasm': 'src/wasm.ts',
diff --git a/sdk/src/physics3d/index.ts b/sdk/src/physics3d/index.ts
new file mode 100644
index 000000000..dae622afc
--- /dev/null
+++ b/sdk/src/physics3d/index.ts
@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file index.ts
+ * @brief ESEngine 3D physics module — standalone Jolt WASM integration.
+ *
+ * @details The flat world's twin, entry for entry: `esengine/physics` hands a
+ * game the plugin, the world resource and the contact events, and until this
+ * file existed the solid world handed it none of them. Its components reached
+ * the main entry, so a scene could hold a body and a collider — and nothing a
+ * system could import could cast a ray at one or hear it land.
+ *
+ * @example
+ * ```typescript
+ * import { Physics3DPlugin, Physics3D } from 'esengine/physics3d';
+ * app.addPlugin(new Physics3DPlugin('physics3d.js', { gravity: { x: 0, y: -9.81, z: 0 } }));
+ *
+ * defineSystem([Res(Physics3D)], (queries) => {
+ * const hit = queries?.raycast({ x: 0, y: 100, z: 0 }, { x: 0, y: -200, z: 0 });
+ * });
+ * ```
+ */
+
+export {
+ Physics3DPlugin,
+ physics3dPlugin,
+ Physics3D,
+ Physics3DRuntime,
+} from './Physics3DPlugin';
+
+export {
+ Physics3DQueries,
+ type Cast3DHit,
+ type Overlap3DHit,
+} from './Physics3DQueries';
+
+export {
+ Physics3DEvents,
+ loadPhysics3DModule,
+ assertPhysics3DContract,
+ drainPhysics3DEvents,
+ PHYSICS3D_TRANSFORM_STRIDE,
+ type Physics3DEventsData,
+ type Contact3DEvent,
+ type Sensor3DEvent,
+ type Physics3DWasmModule,
+ type Physics3DModuleFactory,
+} from './Physics3DModule';
+
+export {
+ stepPhysics3D,
+ DEFAULT_PHYSICS3D_CONFIG,
+ type Physics3DConfig,
+} from './Physics3DSystem';
+
+export {
+ RigidBody3D,
+ BoxCollider3D,
+ SphereCollider3D,
+ CapsuleCollider3D,
+ MeshCollider3D,
+ ConvexCollider3D,
+ CharacterController3D,
+ type RigidBody3DData,
+ type BoxCollider3DData,
+ type SphereCollider3DData,
+ type CapsuleCollider3DData,
+ type MeshCollider3DData,
+ type ConvexCollider3DData,
+ type CharacterController3DData,
+} from './Physics3DComponents';
+
+export {
+ PointJoint3D,
+ HingeJoint3D,
+ SliderJoint3D,
+ DistanceJoint3D,
+ FixedJoint3D,
+ readJoint3D,
+ type PointJoint3DData,
+ type HingeJoint3DData,
+ type SliderJoint3DData,
+ type DistanceJoint3DData,
+ type FixedJoint3DData,
+ type Joint3DShape,
+} from './Physics3DJoints';
+
+export {
+ Physics3DDebugDraw,
+ setupPhysics3DDebugDraw,
+ drawPhysics3DDebug,
+ type Physics3DDebugDrawConfig,
+} from './Physics3DDebugDraw';
+
+export {
+ readCollider3DShapes,
+ collider3DWireframe,
+ placeCollider3DWireframe,
+ rotateVec3ByQuat,
+ COLLIDER3D_RING_SEGMENTS,
+ type Collider3DShape,
+ type Collider3DInstance,
+ type Collider3DComponent,
+} from './ColliderShape3D';
diff --git a/tools/check-plugin-door.mjs b/tools/check-plugin-door.mjs
new file mode 100644
index 000000000..b9df2e7a4
--- /dev/null
+++ b/tools/check-plugin-door.mjs
@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-plugin-door.mjs — a subsystem a game cannot add is a subsystem
+ * the engine has and the engine's users do not.
+ * @details 3D physics shipped its components through the main entry, so a scene
+ * could hold a `RigidBody3D` and the runtime loader would quietly wire
+ * the world behind it. What never reached any entry was the door:
+ * `Physics3DPlugin`, the `Physics3D` queries resource, `Physics3DEvents`.
+ * A game could drop a body on the floor and had no way to cast a ray at
+ * it or hear it land — for four releases, with every gate green, because
+ * every gate asks what the surface IS and none asked what is MISSING.
+ *
+ * So: every `implements Plugin` in the SDK is either exported from a
+ * public entry, or composed by a plugin that is. Those are the only two
+ * ways a game gets one. Anything else is a subsystem behind a wall.
+ *
+ * Read off the TypeScript AST, not a regex over the text. The first
+ * version matched names anywhere in the source and called this reachable
+ * on the strength of `from '../physics3d/Physics3DPlugin'` — a module
+ * path in a file that imports something else entirely. An identifier is
+ * a use; a path and a doc comment are not, and only the parser knows
+ * which is which.
+ *
+ * Run: node tools/check-plugin-door.mjs (exit 1 on a walled-off plugin)
+ */
+import { readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ETC, ENTRIES, ts } from './lib/sdkProgram.mjs';
+import { parseSnapshot } from './lib/apiSnapshot.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SRC = path.join(ROOT, 'sdk', 'src');
+
+const rel = (p) => path.relative(ROOT, p);
+
+/** Every `.ts` under the SDK source, generated files included — a generated
+ * plugin is still a plugin somebody has to be able to add. */
+function sources(dir, out = []) {
+ for (const e of readdirSync(dir, { withFileTypes: true })) {
+ const full = path.join(dir, e.name);
+ if (e.isDirectory()) sources(full, out);
+ else if (e.isFile() && e.name.endsWith('.ts')) out.push(full);
+ }
+ return out;
+}
+
+/** class name -> the file declaring it. */
+const declaredIn = new Map();
+/** class name -> the names a game could reach it BY (itself, plus bindings of it). */
+const aliases = new Map();
+/** file -> every identifier the file actually uses. */
+const idents = new Map();
+
+const alias = (cls, name) => {
+ if (!aliases.has(cls)) aliases.set(cls, new Set([cls]));
+ aliases.get(cls).add(name);
+};
+
+for (const file of sources(SRC)) {
+ const sf = ts.createSourceFile(file, readFileSync(file, 'utf8'), ts.ScriptTarget.Latest, true);
+ const used = new Set();
+ idents.set(file, used);
+ const visit = (node) => {
+ if (ts.isIdentifier(node)) used.add(node.text);
+
+ if (ts.isClassDeclaration(node) && node.name) {
+ const implemented = (node.heritageClauses ?? [])
+ .filter((h) => h.token === ts.SyntaxKind.ImplementsKeyword)
+ .flatMap((h) => h.types.map((t) => t.expression.getText(sf)));
+ if (implemented.includes('Plugin')) {
+ declaredIn.set(node.name.text, file);
+ alias(node.name.text, node.name.text);
+ }
+ }
+ // `export const uiPlugin = new UIPlugin()` — the binding IS the door.
+ if (ts.isVariableDeclaration(node) && node.name && ts.isIdentifier(node.name)
+ && node.initializer && ts.isNewExpression(node.initializer)
+ && ts.isIdentifier(node.initializer.expression)) {
+ alias(node.initializer.expression.text, node.name.text);
+ }
+ // `export function physics3dPlugin(...): Physics3DPlugin` — likewise.
+ if (ts.isFunctionDeclaration(node) && node.name && node.type
+ && ts.isTypeReferenceNode(node.type) && ts.isIdentifier(node.type.typeName)) {
+ alias(node.type.typeName.text, node.name.text);
+ }
+ ts.forEachChild(node, visit);
+ };
+ visit(sf);
+}
+
+/** Every symbol any public entry exports. */
+const exported = new Set();
+for (const entry of Object.keys(ENTRIES)) {
+ let snapshot;
+ try { snapshot = readFileSync(path.join(ETC, `${entry}.api.md`), 'utf8'); } catch { continue; }
+ for (const [name] of parseSnapshot(snapshot)) exported.add(name);
+}
+
+const open = new Set();
+for (const cls of declaredIn.keys()) {
+ if ([...aliases.get(cls)].some((n) => exported.has(n))) open.add(cls);
+}
+const byEntry = open.size;
+
+/**
+ * A plugin with no entry of its own is still reachable if a reachable plugin's
+ * file USES it — that is what composition looks like, and the game adds the
+ * composer. Iterated to a fixpoint so a chain of composition counts.
+ */
+for (let grew = true; grew;) {
+ grew = false;
+ for (const [cls, file] of declaredIn) {
+ if (open.has(cls)) continue;
+ const composed = [...declaredIn].some(([other, otherFile]) =>
+ open.has(other) && otherFile !== file
+ && [...aliases.get(cls)].some((n) => idents.get(otherFile).has(n)));
+ if (composed) { open.add(cls); grew = true; }
+ }
+}
+
+const walled = [...declaredIn].filter(([cls]) => !open.has(cls));
+if (walled.length) {
+ console.error('check-plugin-door: a game has no way to add these.\n');
+ for (const [cls, file] of walled) console.error(` ${cls} (${rel(file)})`);
+ console.error('\nExport it from an entry, or have a plugin that IS exported compose it.');
+ process.exit(1);
+}
+
+console.log(`check-plugin-door: ${declaredIn.size} plugin(s), every one reachable — `
+ + `${byEntry} by an entry, ${declaredIn.size - byEntry} by composition.`);
diff --git a/tools/gates.mjs b/tools/gates.mjs
index 6c95ea2ba..6ac32f4c7 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -48,6 +48,10 @@ export const GATES = [
{ id: 'api-surface-baseline', run: 'node tools/api-surface.mjs --check-baseline' },
{ id: 'freeze-bar', run: 'node tools/check-freeze-bar.mjs' },
{ id: 'tier-leaks', run: 'node tools/check-tier-leaks.mjs' },
+ // The three above ask what the surface IS. This asks what it is missing: a
+ // subsystem whose plugin reaches no entry is one the engine has and a game
+ // cannot add — which is what 3D physics was for four releases.
+ { id: 'plugin-door', run: 'node tools/check-plugin-door.mjs' },
// The SDK's tiers are enforced by the three gates above. The editor plugin API
// has no snapshot to enforce, so what is enforced there is the ANSWER: that it
// is experimental, said the same way in every place someone reads it.
diff --git a/tools/lib/sdkProgram.mjs b/tools/lib/sdkProgram.mjs
index 143d5fa47..834ba13f6 100644
--- a/tools/lib/sdkProgram.mjs
+++ b/tools/lib/sdkProgram.mjs
@@ -55,6 +55,7 @@ export const ENTRIES = {
'index.node': 'src/index.node.ts',
'index.native': 'src/index.native.ts',
'physics': 'src/physics/index.ts',
+ 'physics3d': 'src/physics3d/index.ts',
'spine': 'src/spine/index.ts',
'dragonbones': 'src/dragonbones/index.ts',
'wasm': 'src/wasm.ts',