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
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.jsindex 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.mjsindex 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.tsindex 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.tsindex 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.mdnew file mode 100644index 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.jsonindex 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.jsindex 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.jsindex 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.tsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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',