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.

refactor(physics): the flat subsystem surface is spelled the way physics3d/ spells its own

yhh7f3b7d52ff6a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2c795bff6..aacea9984 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -43,11 +43,23 @@ published separately; it ships inside the editor.
**Breaking for code.** A script importing any of these from `esengine` must
import the new name; the data interfaces follow their component
- (`RigidBodyData` → `RigidBody2DData`). The
- SDK's physics *surface* is unchanged in this release — `Physics`,
- `PhysicsPlugin`, `PhysicsEvents` and `ColliderShape` still carry bare names
- against `Physics3DPlugin` and `ColliderShape3D`, and squaring that is an API
- rename with no data in it.
+ (`RigidBodyData` → `RigidBody2DData`).
+
+- **The SDK's flat physics surface follows, spelled the way `physics3d/` already
+ spells its own.** `Physics` → `Physics2D`, `PhysicsAPI` → `Physics2DAPI`,
+ `PhysicsPlugin` / `physicsPlugin` → `Physics2DPlugin` / `physics2dPlugin`,
+ `PhysicsEvents`, `PhysicsEventType`, `PhysicsDebugDraw`, `drawPhysicsDebug`,
+ `setupPhysicsDebugDraw` and the config/event data interfaces all take the
+ suffix; `ColliderShape` / `ColliderInstance` / `ColliderOutline` become
+ `Collider2DShape` / `Collider2DInstance` / `Collider2DOutline`, matching
+ `Collider3DShape` beside them. `Res(Physics)` is `Res(Physics2D)`.
+
+ What kept its name, and why: `loadPhysicsModule`, `PhysicsWasmModule`,
+ `PhysicsModuleFactory` and `PhysicsBridge` name the **side module**, whose id
+ is still `physics` and whose artifact is still `physics.wasm` — a type that
+ names a file should be spelled like the file. The `esengine/physics` entry
+ point is unchanged for the same reason. Nothing on disk was keyed by any of
+ this, so there is no migration: it is an import-line change.
## [0.56.0] - 2026-08-23
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index c55971436..132093a68 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -369,11 +369,14 @@ The correctness and foundation campaigns are **complete**. Landed:
plane from their names (they are the only light and the only mesh renderer);
`ShadowCaster2D` keeps it, because it shadows what has no mesh to rasterize.
Physics is the one place where two worlds really do exist, so both are named
- for their plane: `RigidBody2D` and the four `*Collider2D` shapes beside
- `RigidBody3D` and its five, and neither set owns the bare name. `BodyType` is
- shared — a body is static, kinematic or dynamic in either world — and lives in
- a header of its own rather than in the flat one's, which is where the 3D
- component used to reach for it.
+ for their plane, components and subsystem surface alike: `RigidBody2D`, the
+ six `*Collider2D` shapes, `Physics2D`, `Physics2DPlugin`, `Collider2DShape`,
+ beside `RigidBody3D`, `Physics3DPlugin` and `Collider3DShape`. Neither set
+ owns the bare name. Two things deliberately keep it: `BodyType`, shared
+ because a body is static, kinematic or dynamic in either world (and now in a
+ header of its own rather than the flat one's, which is where the 3D component
+ used to reach for it), and `PhysicsWasmModule` / `loadPhysicsModule`, which
+ name the side module `physics.wasm` rather than a world.
Remaining capability work (see `REARCH_2D_PARITY.md`, gitignored):
- [ ] T2 — editor keyframe/curve editing UI; particle visual editor; native 2D
@@ -381,10 +384,6 @@ Remaining capability work (see `REARCH_2D_PARITY.md`, gitignored):
- [ ] T3 — GPU particles / trails (transform-feedback or compute).
- [ ] T4 — one-way platforms + remaining Box2D joints; editor multi-atlas painting;
tile-gid objects in tilemaps.
-- [ ] The SDK's flat physics surface still carries bare names the components no
- longer do: `Physics`, `PhysicsPlugin`, `PhysicsEvents`, `ColliderShape`,
- against `Physics3DPlugin` / `ColliderShape3D`. Nothing on disk is keyed by
- those, so squaring it is an API rename with no migration in it.
- [ ] Two pixel gates still run on one backend: `camera-render-target` (a frame
holding both an offscreen and a surface pass returns nothing from the
WebGPU readback) and `device-loss`. The other 121 assert on both.
diff --git a/docs/REARCHITECTURE.md b/docs/REARCHITECTURE.md
index d9c091829..dae84b4b0 100644
--- a/docs/REARCHITECTURE.md
+++ b/docs/REARCHITECTURE.md
@@ -241,9 +241,15 @@ CHANGELOG 和提交信息里,这里只写**从那里读不出来的结构性
场景格式进到 3、旧引擎拒绝 3 而不是加载一个没有碰撞体的关卡。
顺带把 `BodyType` 提到自己的头文件——它两个世界共用,此前 `RigidBody3D.hpp` 要 include
`RigidBody.hpp` 才拿得到,"3D 依赖 2D 的头"本身就是这处倒置的一个症状。
-- **余下的是纯 API 面**:SDK 的平面物理仍是裸名(`Physics` / `PhysicsPlugin` / `PhysicsEvents` /
- `ColliderShape`),对面是 `Physics3DPlugin` / `ColliderShape3D`。磁盘上没有任何东西以这些为键,
- 所以收口它是一次纯粹的破坏性改名、零迁移——待拍板,单独一步做。
+- **API 面同日收口(2026-08-23,用户拍板"只改代码面")**:SDK 的平面物理面按 `physics3d/`
+ 已有的拼法对齐——`Physics`→`Physics2D`、`PhysicsAPI`→`Physics2DAPI`、`PhysicsPlugin`/`physicsPlugin`
+ →`Physics2DPlugin`/`physics2dPlugin`、事件与 debug draw 同理,`ColliderShape`/`ColliderInstance`/
+ `ColliderOutline`→`Collider2DShape`/`Collider2DInstance`/`Collider2DOutline`(3D 侧就是
+ `Collider3DShape`,中缀而非后缀,文件名却是 `ColliderShape3D.ts`——两边现在逐字对镜)。
+ **有意保留裸名的两处**:`BodyType`(两个世界共用)与 `PhysicsWasmModule`/`loadPhysicsModule`/
+ `PhysicsBridge`——它们命名的是**侧模块**,其 id 仍是 `physics`、产物仍是 `physics.wasm`,
+ `esengine/physics` 入口亦不变;命名一个文件的类型就该照那个文件拼。磁盘上没有任何东西以这些为键,
+ 所以这一步零迁移,只是 import 行的改动。
### RC6 资产管线 — 📋 已立项(设计文档)
见 [`REARCH_RC6_ASSETS.md`](./REARCH_RC6_ASSETS.md):面向微信/移动端的资产管线根治——GPU 压缩纹理(keystone)、内容寻址身份、显存预算 + LRU 驱逐、运行时分包/流式 + 微信分包映射。属"能力/平台错配"根治,区别于 RC1–RC5 的"正确性根因"。
diff --git a/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx b/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx
index 57ad0b963..c1e3805df 100644
--- a/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx
+++ b/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx
@@ -74,11 +74,11 @@ content stack, in this order:
from `app.sideModules` on demand — nothing loads unless a scene uses Spine).
5. **Your `plugins`**, in the order given.
-Physics is **not** in the default set: `PhysicsPlugin` needs the physics wasm
+Physics is **not** in the default set: `Physics2DPlugin` needs the physics wasm
module. The shipped runtime acquires `'physics'` from the side-module host and
installs the plugin automatically when the project declares physics or the
scene contains physics components; when composing manually, construct
-`PhysicsPlugin` yourself (it and `loadPhysicsModule` are exported from
+`Physics2DPlugin` yourself (it and `loadPhysicsModule` are exported from
`esengine`; the full API lives on `esengine/physics`).
## Headless apps
@@ -241,7 +241,7 @@ systems are flushed before the first frame.
| `app.onError(fn)` | Observe any system throw (`(error, systemName)`). |
| `app.onSystemError(fn)` | Decide per throw: return `'continue'` or `'pause'` (pauses the rest of the frame). |
| `app.onWasmError(fn)` | Observe errors crossing the wasm bridge. |
-| `app.waitForPhysics()` / `app.isPhysicsReady` | Await / query the async physics wasm init (no-op / `false` without `PhysicsPlugin`). |
+| `app.waitForPhysics()` / `app.isPhysicsReady` | Await / query the async physics wasm init (no-op / `false` without `Physics2DPlugin`). |
| `app.enableStats()` | Turn on timing collection. |
| `app.getSystemTimings()` / `app.getPhaseTimings()` / `app.getFrameScopes()` | Per-system / per-schedule / sub-frame CPU timings this frame (`null` when stats are off). |
| `app.measureFrameScope(name, fn)` | Time `fn` as a named sub-frame scope (a single-branch no-op when stats are off). |
@@ -352,7 +352,7 @@ from it when needed.
<Aside type="note">
The main `esengine` barrel mirrors exactly the physics/spine **wiring**
- layer — `PhysicsPlugin`, `PhysicsEvents`, `Physics`, `loadPhysicsModule`,
+ layer — `Physics2DPlugin`, `Physics2DEvents`, `Physics`, `loadPhysicsModule`,
`SpinePlugin`, `SpineEvents`, `Spine` — so hosts can register the plugins
without a subpath import. The full APIs live on the `esengine/physics` and
`esengine/spine` subpaths. See [Physics](/docs/gameplay/physics/) and
diff --git a/docs/astro/src/content/docs/core-concepts/plugins-resources.mdx b/docs/astro/src/content/docs/core-concepts/plugins-resources.mdx
index 88c788c00..858597383 100644
--- a/docs/astro/src/content/docs/core-concepts/plugins-resources.mdx
+++ b/docs/astro/src/content/docs/core-concepts/plugins-resources.mdx
@@ -53,7 +53,7 @@ plugin wiring needed.
Some subsystems also publish **event resources** on the same pattern — a
resource whose contents are this frame's events, read the same frame:
-`Res(PhysicsEvents)` (contacts), `Res(SpineEvents)` (animation events),
+`Res(Physics2DEvents)` (contacts), `Res(SpineEvents)` (animation events),
`Res(UIEvents)` (clicks and input from widgets).
<br />
diff --git a/docs/astro/src/content/docs/gameplay/markers.mdx b/docs/astro/src/content/docs/gameplay/markers.mdx
index e37432551..53d3812b4 100644
--- a/docs/astro/src/content/docs/gameplay/markers.mdx
+++ b/docs/astro/src/content/docs/gameplay/markers.mdx
@@ -40,9 +40,9 @@ in the editor and web runtime the physics module loads automatically when a scen
uses physics components; in a custom app, add the plugin yourself:
```typescript
-import { PhysicsPlugin } from 'esengine/physics';
+import { Physics2DPlugin } from 'esengine/physics';
-app.addPlugin(new PhysicsPlugin('physics.js'));
+app.addPlugin(new Physics2DPlugin('physics.js'));
```
## Place one in the editor
@@ -104,15 +104,15 @@ A **Trigger Area** is the Create preset for a sensor region: a `Transform`, a st
Because the collider is a sensor it detects overlaps **without** a physical response —
nothing bounces off a trigger; it just reports who entered.
-Read entries and exits from the `PhysicsEvents` resource. Each sensor event names the
+Read entries and exits from the `Physics2DEvents` resource. Each sensor event names the
`sensorEntity` (the trigger) and the `visitorEntity` (the body that crossed it), so
you can look up the trigger's `Marker` to decide what it does:
```typescript
import { defineSystem, Res, Query, Marker } from 'esengine';
-import { PhysicsEvents } from 'esengine/physics';
+import { Physics2DEvents } from 'esengine/physics';
-const onTrigger = defineSystem([Res(PhysicsEvents), Query(Marker)], (events, markers) => {
+const onTrigger = defineSystem([Res(Physics2DEvents), Query(Marker)], (events, markers) => {
const markerOf = (e) => {
for (const [entity, marker] of markers) if (entity === e) return marker;
return null;
@@ -167,7 +167,7 @@ if you need a shape's exact vertices.
- [Tilemaps](/docs/world/tilemaps/) — collision (obstacle) layers and Tiled object
layers that feed the same Markers.
- [Physics](/docs/gameplay/physics/) — sensors, collision filtering, and the
- `PhysicsEvents` resource behind Trigger Areas.
+ `Physics2DEvents` resource behind Trigger Areas.
- [Scenes](/docs/world/scenes/) — Markers and Trigger Areas serialize with the scene.
- [Event Binding](/docs/scripting/events/) — run an action when something enters a Trigger
Area, authored on the area itself with no code.
diff --git a/docs/astro/src/content/docs/gameplay/physics.mdx b/docs/astro/src/content/docs/gameplay/physics.mdx
index d1f0a6fc3..d56a44859 100644
--- a/docs/astro/src/content/docs/gameplay/physics.mdx
+++ b/docs/astro/src/content/docs/gameplay/physics.mdx
@@ -17,9 +17,9 @@ automatically when a scene uses physics components. In a custom app, add the plu
yourself (gravity defaults to `{ x: 0, y: -9.81 }`):
```typescript
-import { PhysicsPlugin } from 'esengine/physics';
+import { Physics2DPlugin } from 'esengine/physics';
-app.addPlugin(new PhysicsPlugin('physics.js', { gravity: { x: 0, y: -9.81 } }));
+app.addPlugin(new Physics2DPlugin('physics.js', { gravity: { x: 0, y: -9.81 } }));
```
<Aside type="note">
@@ -148,15 +148,15 @@ dedicated layers so the mask narrows what each sensor considers.
## Moving bodies — forces & velocity
-Read the `Physics` resource — a `PhysicsAPI` instance — to drive bodies. These
+Read the `Physics2D` resource — a `Physics2DAPI` instance — to drive bodies. These
methods talk to the solver directly, so they are all in **meters** (m/s, m/s² —
see [Units](#units)). Every method takes the world entity:
```typescript
import { defineSystem, Query, Res, RigidBody2D } from 'esengine';
-import { Physics } from 'esengine/physics';
+import { Physics2D } from 'esengine/physics';
-const move = defineSystem([Query(RigidBody2D), Res(Physics)], (q, physics) => {
+const move = defineSystem([Query(RigidBody2D), Res(Physics2D)], (q, physics) => {
for (const [entity] of q) {
physics.applyForce(entity, { x: 0, y: 20 }); // continuous force
physics.applyImpulse(entity, { x: 0, y: 5 }); // instant kick (jump)
@@ -218,14 +218,14 @@ Casts return `RaycastHit`s (`ShapeCastHit` is the same shape):
## Collision & sensor events
-The `PhysicsEvents` resource carries this frame's contacts. Set `isSensor: true` on a
+The `Physics2DEvents` resource carries this frame's contacts. Set `isSensor: true` on a
collider to get enter/exit events **without** a physical response (trigger zones):
```typescript
import { defineSystem, Res } from 'esengine';
-import { PhysicsEvents } from 'esengine/physics';
+import { Physics2DEvents } from 'esengine/physics';
-const onHit = defineSystem([Res(PhysicsEvents)], (events) => {
+const onHit = defineSystem([Res(Physics2DEvents)], (events) => {
for (const c of events.collisionEnters) { /* c.entityA, c.entityB, c.normalX/Y, c.contactX/Y */ }
for (const x of events.collisionExits) { /* x.entityA, x.entityB */ }
for (const h of events.collisionHits) { /* h.approachSpeed, h.pointX/Y, h.normalX/Y */ }
@@ -392,21 +392,21 @@ stairs and slopes.</Aside>
## Debug draw
-The physics plugin installs a **`PhysicsDebugDraw`** resource — an in-game overlay
+The physics plugin installs a **`Physics2DDebugDraw`** resource — an in-game overlay
that strokes collider outlines, velocity vectors, and contact points through the
[`Draw`](/docs/graphics/drawing/) API. It ships disabled; flip `enabled` from any
system to see exactly what the solver sees:
```typescript
import { defineSystem, Res, Input } from 'esengine';
-import { PhysicsDebugDraw } from 'esengine/physics';
+import { Physics2DDebugDraw } from 'esengine/physics';
-const toggleDebug = defineSystem([Res(Input), Res(PhysicsDebugDraw)], (input, dbg) => {
+const toggleDebug = defineSystem([Res(Input), Res(Physics2DDebugDraw)], (input, dbg) => {
if (input.isKeyPressed('F1')) dbg.enabled = !dbg.enabled;
});
```
-| `PhysicsDebugDrawConfig` field | Default | Draws |
+| `Physics2DDebugDrawConfig` field | Default | Draws |
|---|---|---|
| `enabled` | `false` | Master switch for the whole overlay. |
| `showColliders` | `true` | Collider outlines, color-coded by body: blue = static, green = dynamic, cyan = kinematic; sensors are yellow. |
@@ -415,9 +415,9 @@ const toggleDebug = defineSystem([Res(Input), Res(PhysicsDebugDraw)], (input, db
The overlay draws in **world pixels** at each body's live transform (scaled by the
live PPU), so what you see is exactly where the queries agree the collider is.
-`setupPhysicsDebugDraw(app, Physics, PhysicsEvents)` is the wiring `PhysicsPlugin`
+`setupPhysics2DDebugDraw(app, Physics2D, Physics2DEvents)` is the wiring `Physics2DPlugin`
runs for you — it inserts the resource and registers the draw callback; call it (or
-the underlying per-frame `drawPhysicsDebug(app, Physics, PhysicsEvents)`) only from
+the underlying per-frame `drawPhysics2DDebug(app, Physics2D, Physics2DEvents)`) only from
a custom host that bypasses the plugin.
<Aside type="note">This is the runtime overlay. The **editor viewport** has its own
@@ -426,7 +426,7 @@ collider/joint gizmos under the Physics Show Flag (see
## Best practices
-- **Fixed timestep**: apply continuous forces and read `PhysicsEvents` *every frame*,
+- **Fixed timestep**: apply continuous forces and read `Physics2DEvents` *every frame*,
since physics substeps independently of the frame delta.
- **`bullet: true`** on fast, thin bodies (bullets, thin platforms) to avoid tunneling.
- **`fixedRotation: true`** for characters so they don't topple.
diff --git a/docs/astro/src/content/docs/scripting/events.mdx b/docs/astro/src/content/docs/scripting/events.mdx
index 824e3125e..5559d88c1 100644
--- a/docs/astro/src/content/docs/scripting/events.mdx
+++ b/docs/astro/src/content/docs/scripting/events.mdx
@@ -148,7 +148,7 @@ shown ─▶ fsm.fire(enter) on "MissionPanel" → Hidden ──enter──
The watching costs nothing until something listens for one of the two, and nothing again on a
frame where no UI moved.
-[Physics](/docs/gameplay/physics/) contacts reach the same channel (`PhysicsEventType`), so a
+[Physics](/docs/gameplay/physics/) contacts reach the same channel (`Physics2DEventType`), so a
[trigger area](/docs/gameplay/markers/) is wired exactly like a button — both participants get
the event, each told about the other:
diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/app-lifecycle.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/app-lifecycle.mdx
index 6428a94f6..165e0f4a2 100644
--- a/docs/astro/src/content/docs/zh-cn/core-concepts/app-lifecycle.mdx
+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/app-lifecycle.mdx
@@ -69,9 +69,9 @@ await app.run();
的 wasm 运行时——场景不用 Spine 就什么也不加载)。
5. **你的 `plugins`**,按给出顺序。
-物理**不在**默认集合里:`PhysicsPlugin` 需要物理 wasm 模块。发行运行时会在项目
+物理**不在**默认集合里:`Physics2DPlugin` 需要物理 wasm 模块。发行运行时会在项目
声明了物理、或场景含有物理组件时,自动从侧模块 host 获取 `'physics'` 并安装插件;
-手动组装时请自己构造 `PhysicsPlugin`(它和 `loadPhysicsModule` 都从 `esengine`
+手动组装时请自己构造 `Physics2DPlugin`(它和 `loadPhysicsModule` 都从 `esengine`
导出;完整 API 在 `esengine/physics` 子路径上)。
## 无头应用
@@ -224,7 +224,7 @@ export const scorePlugin: Plugin = {
| `app.onError(fn)` | 观察任何系统抛错(`(error, systemName)`)。 |
| `app.onSystemError(fn)` | 逐次抛错决策:返回 `'continue'` 或 `'pause'`(暂停本帧余下部分)。 |
| `app.onWasmError(fn)` | 观察跨 wasm 桥的错误。 |
-| `app.waitForPhysics()` / `app.isPhysicsReady` | 等待 / 查询异步的物理 wasm 初始化(没装 `PhysicsPlugin` 时为 no-op / `false`)。 |
+| `app.waitForPhysics()` / `app.isPhysicsReady` | 等待 / 查询异步的物理 wasm 初始化(没装 `Physics2DPlugin` 时为 no-op / `false`)。 |
| `app.enableStats()` | 开启计时采集。 |
| `app.getSystemTimings()` / `app.getPhaseTimings()` / `app.getFrameScopes()` | 本帧的逐系统 / 逐调度 / 子帧 CPU 计时(统计关闭时为 `null`)。 |
| `app.measureFrameScope(name, fn)` | 把 `fn` 作为具名子帧作用域计时(统计关闭时只花一次分支的 no-op)。 |
@@ -319,8 +319,8 @@ host 用 `acquire(id)` 应答,返回已实例化模块的 promise(按 id 缓存,
或 `sideModules`),Spine 插件和物理安装会在需要时从中拉取。
<Aside type="note">
- 主 `esengine` barrel 恰好镜像了物理/Spine 的**接线**层——`PhysicsPlugin`、
- `PhysicsEvents`、`Physics`、`loadPhysicsModule`、`SpinePlugin`、
+ 主 `esengine` barrel 恰好镜像了物理/Spine 的**接线**层——`Physics2DPlugin`、
+ `Physics2DEvents`、`Physics`、`loadPhysicsModule`、`SpinePlugin`、
`SpineEvents`、`Spine`——宿主无需子路径导入即可注册这些插件。完整 API 在
`esengine/physics` 与 `esengine/spine` 子路径上。见[物理](/docs/zh-cn/gameplay/physics/)
与 [Spine](/docs/zh-cn/animation/spine/)。
diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/plugins-resources.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/plugins-resources.mdx
index c4c7d3a99..9dd7c85ed 100644
--- a/docs/astro/src/content/docs/zh-cn/core-concepts/plugins-resources.mdx
+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/plugins-resources.mdx
@@ -48,7 +48,7 @@ defineSystem([Res(Audio)], (audio) => {
包精简;其余都在主 `esengine` 包里。上表的基础子系统都随标准 App 附带——无需接线。
有些子系统还按同一范式发布**事件资源**——内容是本帧事件、当帧读取的资源:
-`Res(PhysicsEvents)`(碰撞接触)、`Res(SpineEvents)`(动画事件)、
+`Res(Physics2DEvents)`(碰撞接触)、`Res(SpineEvents)`(动画事件)、
`Res(UIEvents)`(控件的点击与输入)。
<br />
diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/markers.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/markers.mdx
index dc31cd1a8..cefa4c4fb 100644
--- a/docs/astro/src/content/docs/zh-cn/gameplay/markers.mdx
+++ b/docs/astro/src/content/docs/zh-cn/gameplay/markers.mdx
@@ -35,9 +35,9 @@ Marker 就是 `Marker` 组件(一个 `type` 字符串加一个自由形式的 `p
组件时物理模块会自动加载;在自定义 app 里,请自己加上插件:
```typescript
-import { PhysicsPlugin } from 'esengine/physics';
+import { Physics2DPlugin } from 'esengine/physics';
-app.addPlugin(new PhysicsPlugin('physics.js'));
+app.addPlugin(new Physics2DPlugin('physics.js'));
```
## 在编辑器里放置
@@ -94,14 +94,14 @@ const placePlayer = defineSystem([Commands(), Query(Marker, Transform)], (cmds,
(`bodyType: 0`)、一个 `isSensor: true` 的 `BoxCollider2D`,加一个 `Marker`。因为碰撞体是传感器,
它检测重叠但**不产生**物理响应——没有东西会从触发区弹开;它只报告谁进来了。
-从 `PhysicsEvents` 资源读取进入与离开。每个传感事件都给出 `sensorEntity`(触发区)和
+从 `Physics2DEvents` 资源读取进入与离开。每个传感事件都给出 `sensorEntity`(触发区)和
`visitorEntity`(穿过它的刚体),于是你可以查出触发区的 `Marker` 来决定它做什么:
```typescript
import { defineSystem, Res, Query, Marker } from 'esengine';
-import { PhysicsEvents } from 'esengine/physics';
+import { Physics2DEvents } from 'esengine/physics';
-const onTrigger = defineSystem([Res(PhysicsEvents), Query(Marker)], (events, markers) => {
+const onTrigger = defineSystem([Res(Physics2DEvents), Query(Marker)], (events, markers) => {
const markerOf = (e) => {
for (const [entity, marker] of markers) if (entity === e) return marker;
return null;
@@ -146,6 +146,6 @@ const onTrigger = defineSystem([Res(PhysicsEvents), Query(Marker)], (events, mar
## 参见
- [瓦片地图](/docs/zh-cn/world/tilemaps/) —— 碰撞(障碍)层与喂给同一批 Marker 的 Tiled 对象层。
-- [物理](/docs/zh-cn/gameplay/physics/) —— 传感器、碰撞过滤,以及 Trigger Area 背后的 `PhysicsEvents` 资源。
+- [物理](/docs/zh-cn/gameplay/physics/) —— 传感器、碰撞过滤,以及 Trigger Area 背后的 `Physics2DEvents` 资源。
- [场景](/docs/zh-cn/world/scenes/) —— Marker 与 Trigger Area 随场景序列化。
- [事件绑定](/docs/zh-cn/scripting/events/) —— 有东西进入 Trigger Area 时执行一个动作,直接挂在触发区上,不写代码。
diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/physics.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/physics.mdx
index a3be1620e..acc890ca3 100644
--- a/docs/astro/src/content/docs/zh-cn/gameplay/physics.mdx
+++ b/docs/astro/src/content/docs/zh-cn/gameplay/physics.mdx
@@ -15,9 +15,9 @@ Estella 的物理跑在 C++/WebAssembly 内核里,由 Box2D v3 驱动。你给
应用里,自己加插件(重力默认 `{ x: 0, y: -9.81 }`):
```typescript
-import { PhysicsPlugin } from 'esengine/physics';
+import { Physics2DPlugin } from 'esengine/physics';
-app.addPlugin(new PhysicsPlugin('physics.js', { gravity: { x: 0, y: -9.81 } }));
+app.addPlugin(new Physics2DPlugin('physics.js', { gravity: { x: 0, y: -9.81 } }));
```
<Aside type="note">
@@ -138,14 +138,14 @@ const LAYER_GROUND = 0x0008;
## 移动刚体 —— 力与速度
-读 `Physics` 资源——一个 `PhysicsAPI` 实例——来驱动刚体。这些方法直接和求解器对话,
+读 `Physics2D` 资源——一个 `Physics2DAPI` 实例——来驱动刚体。这些方法直接和求解器对话,
所以全部以**米**计(m/s、m/s²——见[单位](#单位))。每个方法都取世界实体:
```typescript
import { defineSystem, Query, Res, RigidBody2D } from 'esengine';
-import { Physics } from 'esengine/physics';
+import { Physics2D } from 'esengine/physics';
-const move = defineSystem([Query(RigidBody2D), Res(Physics)], (q, physics) => {
+const move = defineSystem([Query(RigidBody2D), Res(Physics2D)], (q, physics) => {
for (const [entity] of q) {
physics.applyForce(entity, { x: 0, y: 20 }); // continuous force
physics.applyImpulse(entity, { x: 0, y: 5 }); // instant kick (jump)
@@ -206,14 +206,14 @@ const swept = physics.shapeCastCircle(/* … */); // sweep a shape
## 碰撞与传感事件
-`PhysicsEvents` 资源携带这一帧的接触。给碰撞体设 `isSensor: true` 即可得到 enter/exit 事件
+`Physics2DEvents` 资源携带这一帧的接触。给碰撞体设 `isSensor: true` 即可得到 enter/exit 事件
而**没有**物理响应(触发区):
```typescript
import { defineSystem, Res } from 'esengine';
-import { PhysicsEvents } from 'esengine/physics';
+import { Physics2DEvents } from 'esengine/physics';
-const onHit = defineSystem([Res(PhysicsEvents)], (events) => {
+const onHit = defineSystem([Res(Physics2DEvents)], (events) => {
for (const c of events.collisionEnters) { /* c.entityA, c.entityB, c.normalX/Y, c.contactX/Y */ }
for (const x of events.collisionExits) { /* x.entityA, x.entityB */ }
for (const h of events.collisionHits) { /* h.approachSpeed, h.pointX/Y, h.normalX/Y */ }
@@ -364,20 +364,20 @@ const drive = defineSystem([Query(Mut(CharacterController2D))], (q) => {
## 调试绘制
-物理插件会安装一个 **`PhysicsDebugDraw`** 资源——一个游戏内叠加层,通过
+物理插件会安装一个 **`Physics2DDebugDraw`** 资源——一个游戏内叠加层,通过
[`Draw`](/docs/zh-cn/graphics/drawing/) API 描出碰撞体轮廓、速度向量和接触点。
它默认关闭;在任何系统里翻转 `enabled`,就能看见求解器眼中的世界:
```typescript
import { defineSystem, Res, Input } from 'esengine';
-import { PhysicsDebugDraw } from 'esengine/physics';
+import { Physics2DDebugDraw } from 'esengine/physics';
-const toggleDebug = defineSystem([Res(Input), Res(PhysicsDebugDraw)], (input, dbg) => {
+const toggleDebug = defineSystem([Res(Input), Res(Physics2DDebugDraw)], (input, dbg) => {
if (input.isKeyPressed('F1')) dbg.enabled = !dbg.enabled;
});
```
-| `PhysicsDebugDrawConfig` 字段 | 默认 | 绘制内容 |
+| `Physics2DDebugDrawConfig` 字段 | 默认 | 绘制内容 |
|---|---|---|
| `enabled` | `false` | 整个叠加层的总开关。 |
| `showColliders` | `true` | 碰撞体轮廓,按刚体类型着色:蓝 = 静态,绿 = 动态,青 = 运动学;传感器为黄色。 |
@@ -385,16 +385,16 @@ const toggleDebug = defineSystem([Res(Input), Res(PhysicsDebugDraw)], (input, db
| `showContacts` | `false` | 本帧新开始的每个接触点画一个红点。 |
叠加层在每个刚体的实时变换处以**世界像素**绘制(按当前 PPU 缩放),你看到的正是查询
-认定的碰撞体位置。`setupPhysicsDebugDraw(app, Physics, PhysicsEvents)` 就是
-`PhysicsPlugin` 替你跑的接线——插入该资源并注册绘制回调;只有在绕开插件的自定义宿主里,
-才需要自己调它(或每帧调底层的 `drawPhysicsDebug(app, Physics, PhysicsEvents)`)。
+认定的碰撞体位置。`setupPhysics2DDebugDraw(app, Physics2D, Physics2DEvents)` 就是
+`Physics2DPlugin` 替你跑的接线——插入该资源并注册绘制回调;只有在绕开插件的自定义宿主里,
+才需要自己调它(或每帧调底层的 `drawPhysics2DDebug(app, Physics2D, Physics2DEvents)`)。
<Aside type="note">这是运行时的叠加层。**编辑器视口**在物理显示标记下有自己的碰撞体/关节
gizmo(见[关节——在编辑器里](#在编辑器里));两者互相独立。</Aside>
## 最佳实践
-- **固定时间步**:*每帧*施加持续力、读 `PhysicsEvents`,因为物理独立于帧 delta 做子步。
+- **固定时间步**:*每帧*施加持续力、读 `Physics2DEvents`,因为物理独立于帧 delta 做子步。
- 快速细小刚体(子弹、薄平台)用 **`bullet: true`** 防穿透。
- 角色用 **`fixedRotation: true`** 免得翻倒。
- **碰撞体与求解器用米,查询和角色控制器用像素**——混用是最常见的 bug;用
diff --git a/docs/astro/src/content/docs/zh-cn/scripting/events.mdx b/docs/astro/src/content/docs/zh-cn/scripting/events.mdx
index 902198626..6922e43ac 100644
--- a/docs/astro/src/content/docs/zh-cn/scripting/events.mdx
+++ b/docs/astro/src/content/docs/zh-cn/scripting/events.mdx
@@ -140,7 +140,7 @@ shown ─▶ fsm.fire(enter) 挂在 "MissionPanel" → Hidden ──enter
在没有人监听这两个事件之前,这份「盯着」不花任何代价;有人监听、但这一帧 UI 没动过时,同样不花。
-[物理](/docs/zh-cn/gameplay/physics/)接触也走同一条通道(`PhysicsEventType`),所以
+[物理](/docs/zh-cn/gameplay/physics/)接触也走同一条通道(`Physics2DEventType`),所以
[触发区](/docs/zh-cn/gameplay/markers/)的接线方式和按钮一模一样——双方都会收到事件,各自拿到对方:
`collision_enter` · `collision_exit` · `collision_hit` · `trigger_enter` · `trigger_exit`
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index be9af316c..b0ebaff23 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -163,8 +163,8 @@
"why": "the corpus reaches three of thirty-seven physics symbols",
"whyZh": "语料只触到 37 个物理符号里的 3 个",
"entry": [
- "Physics",
- "PhysicsEvents",
+ "Physics2D",
+ "Physics2DEvents",
"CharacterController2D"
]
},
@@ -1994,7 +1994,7 @@
]
},
{
- "name": "Physics",
+ "name": "Physics2D",
"kind": "const",
"deprecated": false,
"entries": [
@@ -2007,7 +2007,7 @@
]
},
{
- "name": "PhysicsEvents",
+ "name": "Physics2DEvents",
"kind": "const",
"deprecated": false,
"entries": [
diff --git a/examples/celestial-heights/src/systems/combat.ts b/examples/celestial-heights/src/systems/combat.ts
index c06691fb7..1ca7f557d 100644
--- a/examples/celestial-heights/src/systems/combat.ts
+++ b/examples/celestial-heights/src/systems/combat.ts
@@ -1,5 +1,5 @@
import {
- defineSystem, Query, Mut, Res, Time, Transform, Physics, Commands,
+ defineSystem, Query, Mut, Res, Time, Transform, Physics2D, Commands,
EventWriter, EventReader, GetWorld,
} from 'esengine';
import { Facing, Health, MeleeAttack, Player } from '../components';
@@ -16,7 +16,7 @@ const DEG = Math.PI / 180;
export const meleeResolveSystem = defineSystem(
[
Query(Transform, Facing, Mut(MeleeAttack)),
- Res(Time), Res(Physics), GetWorld(), EventWriter(DamageDealt),
+ Res(Time), Res(Physics2D), GetWorld(), EventWriter(DamageDealt),
],
(attackers, time, physics, world, damage) => {
for (const [attacker, transform, facing, attack] of attackers) {
diff --git a/examples/physics-playground/src/systems/interact.ts b/examples/physics-playground/src/systems/interact.ts
index d9ca73171..3b944a35c 100644
--- a/examples/physics-playground/src/systems/interact.ts
+++ b/examples/physics-playground/src/systems/interact.ts
@@ -3,8 +3,8 @@ import {
Transform, RigidBody2D, BodyType,
} from 'esengine';
import type { UICameraData, RigidBody2DData, TransformData } from 'esengine';
-import { Physics, MotorJoint2D } from 'esengine/physics';
-import type { PhysicsAPI } from 'esengine/physics';
+import { Physics2D, MotorJoint2D } from 'esengine/physics';
+import type { Physics2DAPI } from 'esengine/physics';
const DRAG_BUTTON = 0;
const PICK_RADIUS = 6; // world px around the cursor to grab a body
@@ -12,8 +12,8 @@ const PICK_RADIUS = 6; // world px around the cursor to grab a body
// Click-and-drag any dynamic body with a mouse joint: pick on press, follow the
// cursor while held, release on up. Only one drag is live at a time.
export const dragSystem = defineSystem(
- [Res(Input), Res(UICameraInfo), Res(Physics), Query(RigidBody2D)],
- (input, camera: UICameraData, physics: PhysicsAPI, bodies) => {
+ [Res(Input), Res(UICameraInfo), Res(Physics2D), Query(RigidBody2D)],
+ (input, camera: UICameraData, physics: Physics2DAPI, bodies) => {
if (!camera.valid) return;
const target = { x: camera.worldMouseX, y: camera.worldMouseY };
@@ -41,8 +41,8 @@ const SHUTTLE_MAX_X = 290;
const shuttleDir = new Map<number, number>();
export const shuttleSystem = defineSystem(
- [Res(Physics), Query(Transform, MotorJoint2D)],
- (physics: PhysicsAPI, shuttles) => {
+ [Res(Physics2D), Query(Transform, MotorJoint2D)],
+ (physics: Physics2DAPI, shuttles) => {
for (const [entity, transform] of shuttles as Iterable<[number, TransformData]>) {
let dir = shuttleDir.get(entity) ?? 1;
if (transform.position.x > SHUTTLE_MAX_X && dir > 0) {
diff --git a/examples/platformer/src/systems/coin.ts b/examples/platformer/src/systems/coin.ts
index 1daf24d8f..990f0fc14 100644
--- a/examples/platformer/src/systems/coin.ts
+++ b/examples/platformer/src/systems/coin.ts
@@ -1,6 +1,6 @@
import {
defineSystem, Query, Mut, Res, Time, Transform, Commands,
- PhysicsEvents,
+ Physics2DEvents,
} from 'esengine';
import { Coin, ScoreDisplay } from '../components';
@@ -19,7 +19,7 @@ export const coinBobSystem = defineSystem(
);
export const coinPickupSystem = defineSystem(
- [Res(PhysicsEvents), Query(Coin), Query(Mut(ScoreDisplay)), Commands()],
+ [Res(Physics2DEvents), Query(Coin), Query(Mut(ScoreDisplay)), Commands()],
(events, coins, scores, cmds) => {
for (const ev of events.sensorEnters) {
let isCoin = false;
diff --git a/pipeline/src/project/runtimeConfig.ts b/pipeline/src/project/runtimeConfig.ts
index 3f78d5483..777540e32 100644
--- a/pipeline/src/project/runtimeConfig.ts
+++ b/pipeline/src/project/runtimeConfig.ts
@@ -26,7 +26,7 @@
* fails the build when a field in this shape is not carried by every consumer —
* or is not listed there as a declared, reasoned gap.
*/
-import type { AudioProjectConfig, PackagedGameConfig, PhysicsPluginConfig } from 'esengine';
+import type { AudioProjectConfig, PackagedGameConfig, Physics2DPluginConfig } from 'esengine';
import { resolveScreenFit, SORTING_LAYER_COUNT, type ProjectManifest } from './format';
/** The project's camera fit as a runtime takes it (`scaleMode < 0` ⇒ off). */
@@ -54,7 +54,7 @@ export interface RuntimeProjectConfig {
/** Install physics even when the static scene shows no bodies (runtime-spawned). */
physicsEnabled: boolean;
/** World solver + collision matrix (Project Settings → Physics). */
- physicsConfig: PhysicsPluginConfig;
+ physicsConfig: Physics2DPluginConfig;
/** Mixer state: bus volumes, custom buses, effects, duck rules. */
audioConfig: AudioProjectConfig;
/** Built-in widget theme; 'dark' is the default. */
@@ -102,9 +102,9 @@ export function normalizeCollisionLayerMasks(masks?: number[]): number[] {
* all-collide matrix would otherwise override each single-layer collider's own
* maskBits for nothing.
*/
-function physicsConfigOf(features: ProjectManifest['features']): PhysicsPluginConfig {
+function physicsConfigOf(features: ProjectManifest['features']): Physics2DPluginConfig {
const p = features?.physics;
- const config: PhysicsPluginConfig = {
+ const config: Physics2DPluginConfig = {
gravity: p?.gravity ?? { x: 0, y: -9.81 },
fixedTimestep: p?.fixedTimestep ?? 1 / 60,
subStepCount: p?.subStepCount ?? 4,
@@ -188,7 +188,7 @@ export function packagedRuntimeFields(rc: RuntimeProjectConfig): PackagedRuntime
}
/** Whether the world config is exactly what a runtime would default to anyway. */
-function isDefaultPhysics(config: PhysicsPluginConfig): boolean {
+function isDefaultPhysics(config: Physics2DPluginConfig): boolean {
return JSON.stringify(config) === JSON.stringify(DEFAULT_PHYSICS_CONFIG);
}
@@ -214,4 +214,4 @@ export function cookOptionsOf(manifest: Pick<ProjectManifest, 'packaging'>): Coo
export const DEFAULT_RUNTIME_CONFIG: RuntimeProjectConfig = runtimeConfigOf({});
/** The physics world an undeclared project runs, for "is this worth shipping". */
-const DEFAULT_PHYSICS_CONFIG: PhysicsPluginConfig = DEFAULT_RUNTIME_CONFIG.physicsConfig;
+const DEFAULT_PHYSICS_CONFIG: Physics2DPluginConfig = DEFAULT_RUNTIME_CONFIG.physicsConfig;
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 6ea1f5f82..80f33d6d1 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1975,6 +1975,29 @@ max: Vec3
min: Vec3
```
+## Collider2DInstance — interface @experimental
+```
+enabled: boolean
+isSensor: boolean
+shape: Collider2DShape
+```
+
+## Collider2DOutline — interface @experimental
+```
+circles: { c: Vec2; r: number; }[]
+polylines: Vec2[][]
+```
+
+## Collider2DShape — type @experimental
+```
+| { kind: 'box'; halfExtents: Vec2; offset: Vec2 }
+ | { kind: 'circle'; radius: number; offset: Vec2 }
+ | { kind: 'capsule'; radius: number; halfHeight: number; offset: Vec2 }
+ | { kind: 'segment'; point1: Vec2; point2: Vec2 }
+ | { kind: 'polygon'; vertices: Vec2[] }
+ | { kind: 'chain'; points: Vec2[]; isLoop: boolean }
+```
+
## Collider3DComponent — type @experimental
```
| 'BoxCollider3D' | 'SphereCollider3D' | 'CapsuleCollider3D'
@@ -1996,29 +2019,6 @@ shape: Collider3DShape
| { kind: 'capsule'; radius: number; halfHeight: number }
```
-## ColliderInstance — interface @experimental
-```
-enabled: boolean
-isSensor: boolean
-shape: ColliderShape
-```
-
-## ColliderOutline — interface @experimental
-```
-circles: { c: Vec2; r: number; }[]
-polylines: Vec2[][]
-```
-
-## ColliderShape — type @experimental
-```
-| { kind: 'box'; halfExtents: Vec2; offset: Vec2 }
- | { kind: 'circle'; radius: number; offset: Vec2 }
- | { kind: 'capsule'; radius: number; halfHeight: number; offset: Vec2 }
- | { kind: 'segment'; point1: Vec2; point2: Vec2 }
- | { kind: 'polygon'; vertices: Vec2[] }
- | { kind: 'chain'; points: Vec2[]; isLoop: boolean }
-```
-
## CollisionBrush — interface @experimental
```
collision: ResolvedTileCollision
@@ -4154,7 +4154,7 @@ mouse: boolean | undefined
app: App
module: ESEngineModule | null
physics3dModule: Physics3DWasmModule | undefined
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
physicsModule: PhysicsWasmModule | null | undefined
sceneData: SceneData
@@ -5060,7 +5060,7 @@ colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
entryScene: string
hotUpdate: { remoteRoot?: string; persistUpdateKey?: string; } | undefined
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
renderBackend: "webgl2" | "webgpu" | undefined
scenes: { name: string; path: string; }[] | undefined
@@ -5259,41 +5259,29 @@ static prototype: PerceptionPlugin
ComponentDef<{}>
```
-## Physics — const @beta
-```
-ResourceDef<PhysicsAPI>
-```
-
-## Physics3DDebugDraw — const @experimental
-```
-ResourceDef<Physics3DDebugDrawConfig>
-```
-
-## Physics3DDebugDrawConfig — interface @experimental
+## Physics2D — const @beta
```
-enabled: boolean
-showColliders: boolean
-showContacts: boolean
+ResourceDef<Physics2DAPI>
```
-## PhysicsContactEventData — interface @experimental
+## Physics2DContactEventData — interface @experimental
```
approachSpeed: number | undefined
isSensor: boolean | undefined
other: number
```
-## PhysicsEventType — type @experimental
+## Physics2DEventType — type @experimental
```
-typeof PhysicsEventType[keyof typeof PhysicsEventType]
+typeof Physics2DEventType[keyof typeof Physics2DEventType]
```
-## PhysicsEvents — const @beta
+## Physics2DEvents — const @beta
```
-ResourceDef<PhysicsEventsData>
+ResourceDef<Physics2DEventsData>
```
-## PhysicsEventsData — interface @experimental
+## Physics2DEventsData — interface @experimental
```
collisionEnters: CollisionEnterEvent[]
collisionExits: { entityA: Entity; entityB: Entity; }[]
@@ -5302,21 +5290,16 @@ sensorEnters: SensorEvent[]
sensorExits: SensorEvent[]
```
-## PhysicsModuleFactory — type @experimental
-```
-(config?: Record<string, unknown>) => Promise<PhysicsWasmModule>
-```
-
-## PhysicsPlugin — class @experimental
+## Physics2DPlugin — class @experimental
```
build: (app: App) => void
cleanup: () => void
name: string
-static new (wasmUrl: string, config?: PhysicsPluginConfig, factory?: PhysicsModuleFactory): PhysicsPlugin
-static prototype: PhysicsPlugin
+static new (wasmUrl: string, config?: Physics2DPluginConfig, factory?: PhysicsModuleFactory): Physics2DPlugin
+static prototype: Physics2DPlugin
```
-## PhysicsPluginConfig — interface @experimental
+## Physics2DPluginConfig — interface @experimental
```
collisionLayerMasks: number[] | undefined
contactDampingRatio: number | undefined
@@ -5331,6 +5314,23 @@ restitutionThreshold: number | undefined
subStepCount: number | undefined
```
+## Physics3DDebugDraw — const @experimental
+```
+ResourceDef<Physics3DDebugDrawConfig>
+```
+
+## Physics3DDebugDrawConfig — interface @experimental
+```
+enabled: boolean
+showColliders: boolean
+showContacts: boolean
+```
+
+## PhysicsModuleFactory — type @experimental
+```
+(config?: Record<string, unknown>) => Promise<PhysicsWasmModule>
+```
+
## PhysicsWasmModule — interface @experimental
```
HEAPF32: Float32Array<ArrayBufferLike>
@@ -5675,7 +5675,7 @@ extraScenes: { name: string; data?: SceneData; path?: string; }[] | undefined
manifest: AddressableManifest | null | undefined
module: ESEngineModule
persistUpdateKey: string | undefined
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
remoteRoot: string | undefined
sceneData: SceneData
@@ -5700,7 +5700,7 @@ depthLayers: number | undefined
firstScene: string
manifest: AddressableManifest | null | undefined
module: ESEngineModule
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
scenes: { name: string; data: SceneData; }[]
uiTheme: "dark" | "light" | undefined
@@ -6573,7 +6573,7 @@ firstScene: string
manifest: AddressableManifest | ManifestModel | null | undefined
module: ESEngineModule | null
persistUpdateKey: string | undefined
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
physicsModule: PhysicsWasmModule | null | undefined
remoteRoot: string | undefined
@@ -9817,14 +9817,14 @@ BtPlugin
(asset: TilesetAsset): number[]
```
-## collider3DWireframe — function @experimental
+## collider2DOutline — function @experimental
```
-(shape: Collider3DShape, segments?: number): Vec3[][]
+(shape: Collider2DShape, center: Vec2, angle: number, ppu: number): Collider2DOutline
```
-## colliderShapeOutline — function @experimental
+## collider3DWireframe — function @experimental
```
-(shape: ColliderShape, center: Vec2, angle: number, ppu: number): ColliderOutline
+(shape: Collider3DShape, segments?: number): Vec3[][]
```
## collisionRefWithMaterial — function @experimental
@@ -10959,7 +10959,7 @@ Logger
## makeLosCheck — function @experimental
```
-(physics: PhysicsAPI): LosCheck
+(physics: Physics2DAPI): LosCheck
```
## makeWidgetInteractable — function @experimental
@@ -11139,7 +11139,7 @@ NavPlugin
## packagedRuntimeInit — function @experimental
```
-(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit">): { physicsEnabled?: boolean; physicsConfig?: PhysicsPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; }
+(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit">): { physicsEnabled?: boolean; physicsConfig?: Physics2DPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; }
```
## paramDefaultValue — function @experimental
@@ -11422,14 +11422,14 @@ PrefabsPlugin
(ray: WorldRay, point: Vec3, normal: Vec3): Vec3 | null
```
-## readCollider3DShapes — function @experimental
+## readCollider2DShapes — function @experimental
```
-(world: World, entity: number): Collider3DInstance[]
+(world: World, entity: number): Collider2DInstance[]
```
-## readColliderShapes — function @experimental
+## readCollider3DShapes — function @experimental
```
-(world: World, entity: number): ColliderInstance[]
+(world: World, entity: number): Collider3DInstance[]
```
## readFieldPath — function @experimental
@@ -11964,12 +11964,12 @@ ServicesPlugin
## shapeCenter — function @experimental
```
-(shape: ColliderShape, worldPos: Vec2, angle: number, ppu: number): Vec2
+(shape: Collider2DShape, worldPos: Vec2, angle: number, ppu: number): Vec2
```
## shapeOffset — function @experimental
```
-(shape: ColliderShape): Vec2
+(shape: Collider2DShape): Vec2
```
## shutdownDrawAPI — function @experimental
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 668fe1ba3..9cc74c8a8 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1975,6 +1975,29 @@ max: Vec3
min: Vec3
```
+## Collider2DInstance — interface @experimental
+```
+enabled: boolean
+isSensor: boolean
+shape: Collider2DShape
+```
+
+## Collider2DOutline — interface @experimental
+```
+circles: { c: Vec2; r: number; }[]
+polylines: Vec2[][]
+```
+
+## Collider2DShape — type @experimental
+```
+| { kind: 'box'; halfExtents: Vec2; offset: Vec2 }
+ | { kind: 'circle'; radius: number; offset: Vec2 }
+ | { kind: 'capsule'; radius: number; halfHeight: number; offset: Vec2 }
+ | { kind: 'segment'; point1: Vec2; point2: Vec2 }
+ | { kind: 'polygon'; vertices: Vec2[] }
+ | { kind: 'chain'; points: Vec2[]; isLoop: boolean }
+```
+
## Collider3DComponent — type @experimental
```
| 'BoxCollider3D' | 'SphereCollider3D' | 'CapsuleCollider3D'
@@ -1996,29 +2019,6 @@ shape: Collider3DShape
| { kind: 'capsule'; radius: number; halfHeight: number }
```
-## ColliderInstance — interface @experimental
-```
-enabled: boolean
-isSensor: boolean
-shape: ColliderShape
-```
-
-## ColliderOutline — interface @experimental
-```
-circles: { c: Vec2; r: number; }[]
-polylines: Vec2[][]
-```
-
-## ColliderShape — type @experimental
-```
-| { kind: 'box'; halfExtents: Vec2; offset: Vec2 }
- | { kind: 'circle'; radius: number; offset: Vec2 }
- | { kind: 'capsule'; radius: number; halfHeight: number; offset: Vec2 }
- | { kind: 'segment'; point1: Vec2; point2: Vec2 }
- | { kind: 'polygon'; vertices: Vec2[] }
- | { kind: 'chain'; points: Vec2[]; isLoop: boolean }
-```
-
## CollisionBrush — interface @experimental
```
collision: ResolvedTileCollision
@@ -4162,7 +4162,7 @@ mouse: boolean | undefined
app: App
module: ESEngineModule | null
physics3dModule: Physics3DWasmModule | undefined
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
physicsModule: PhysicsWasmModule | null | undefined
sceneData: SceneData
@@ -5243,7 +5243,7 @@ colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
entryScene: string
hotUpdate: { remoteRoot?: string; persistUpdateKey?: string; } | undefined
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
renderBackend: "webgl2" | "webgpu" | undefined
scenes: { name: string; path: string; }[] | undefined
@@ -5442,41 +5442,29 @@ static prototype: PerceptionPlugin
ComponentDef<{}>
```
-## Physics — const @beta
-```
-ResourceDef<PhysicsAPI>
-```
-
-## Physics3DDebugDraw — const @experimental
-```
-ResourceDef<Physics3DDebugDrawConfig>
-```
-
-## Physics3DDebugDrawConfig — interface @experimental
+## Physics2D — const @beta
```
-enabled: boolean
-showColliders: boolean
-showContacts: boolean
+ResourceDef<Physics2DAPI>
```
-## PhysicsContactEventData — interface @experimental
+## Physics2DContactEventData — interface @experimental
```
approachSpeed: number | undefined
isSensor: boolean | undefined
other: number
```
-## PhysicsEventType — type @experimental
+## Physics2DEventType — type @experimental
```
-typeof PhysicsEventType[keyof typeof PhysicsEventType]
+typeof Physics2DEventType[keyof typeof Physics2DEventType]
```
-## PhysicsEvents — const @beta
+## Physics2DEvents — const @beta
```
-ResourceDef<PhysicsEventsData>
+ResourceDef<Physics2DEventsData>
```
-## PhysicsEventsData — interface @experimental
+## Physics2DEventsData — interface @experimental
```
collisionEnters: CollisionEnterEvent[]
collisionExits: { entityA: Entity; entityB: Entity; }[]
@@ -5485,21 +5473,16 @@ sensorEnters: SensorEvent[]
sensorExits: SensorEvent[]
```
-## PhysicsModuleFactory — type @experimental
-```
-(config?: Record<string, unknown>) => Promise<PhysicsWasmModule>
-```
-
-## PhysicsPlugin — class @experimental
+## Physics2DPlugin — class @experimental
```
build: (app: App) => void
cleanup: () => void
name: string
-static new (wasmUrl: string, config?: PhysicsPluginConfig, factory?: PhysicsModuleFactory): PhysicsPlugin
-static prototype: PhysicsPlugin
+static new (wasmUrl: string, config?: Physics2DPluginConfig, factory?: PhysicsModuleFactory): Physics2DPlugin
+static prototype: Physics2DPlugin
```
-## PhysicsPluginConfig — interface @experimental
+## Physics2DPluginConfig — interface @experimental
```
collisionLayerMasks: number[] | undefined
contactDampingRatio: number | undefined
@@ -5514,6 +5497,23 @@ restitutionThreshold: number | undefined
subStepCount: number | undefined
```
+## Physics3DDebugDraw — const @experimental
+```
+ResourceDef<Physics3DDebugDrawConfig>
+```
+
+## Physics3DDebugDrawConfig — interface @experimental
+```
+enabled: boolean
+showColliders: boolean
+showContacts: boolean
+```
+
+## PhysicsModuleFactory — type @experimental
+```
+(config?: Record<string, unknown>) => Promise<PhysicsWasmModule>
+```
+
## PhysicsWasmModule — interface @experimental
```
HEAPF32: Float32Array<ArrayBufferLike>
@@ -5858,7 +5858,7 @@ extraScenes: { name: string; data?: SceneData; path?: string; }[] | undefined
manifest: AddressableManifest | null | undefined
module: ESEngineModule
persistUpdateKey: string | undefined
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
remoteRoot: string | undefined
sceneData: SceneData
@@ -5883,7 +5883,7 @@ depthLayers: number | undefined
firstScene: string
manifest: AddressableManifest | null | undefined
module: ESEngineModule
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
scenes: { name: string; data: SceneData; }[]
uiTheme: "dark" | "light" | undefined
@@ -6766,7 +6766,7 @@ firstScene: string
manifest: AddressableManifest | ManifestModel | null | undefined
module: ESEngineModule | null
persistUpdateKey: string | undefined
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
physicsModule: PhysicsWasmModule | null | undefined
remoteRoot: string | undefined
@@ -10025,14 +10025,14 @@ BtPlugin
(asset: TilesetAsset): number[]
```
-## collider3DWireframe — function @experimental
+## collider2DOutline — function @experimental
```
-(shape: Collider3DShape, segments?: number): Vec3[][]
+(shape: Collider2DShape, center: Vec2, angle: number, ppu: number): Collider2DOutline
```
-## colliderShapeOutline — function @experimental
+## collider3DWireframe — function @experimental
```
-(shape: ColliderShape, center: Vec2, angle: number, ppu: number): ColliderOutline
+(shape: Collider3DShape, segments?: number): Vec3[][]
```
## collisionRefWithMaterial — function @experimental
@@ -11202,7 +11202,7 @@ Logger
## makeLosCheck — function @experimental
```
-(physics: PhysicsAPI): LosCheck
+(physics: Physics2DAPI): LosCheck
```
## makeWidgetInteractable — function @experimental
@@ -11382,7 +11382,7 @@ NavPlugin
## packagedRuntimeInit — function @experimental
```
-(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit">): { physicsEnabled?: boolean; physicsConfig?: PhysicsPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; }
+(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit">): { physicsEnabled?: boolean; physicsConfig?: Physics2DPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; }
```
## paramDefaultValue — function @experimental
@@ -11665,14 +11665,14 @@ PrefabsPlugin
(ray: WorldRay, point: Vec3, normal: Vec3): Vec3 | null
```
-## readCollider3DShapes — function @experimental
+## readCollider2DShapes — function @experimental
```
-(world: World, entity: number): Collider3DInstance[]
+(world: World, entity: number): Collider2DInstance[]
```
-## readColliderShapes — function @experimental
+## readCollider3DShapes — function @experimental
```
-(world: World, entity: number): ColliderInstance[]
+(world: World, entity: number): Collider3DInstance[]
```
## readFieldPath — function @experimental
@@ -12207,12 +12207,12 @@ ServicesPlugin
## shapeCenter — function @experimental
```
-(shape: ColliderShape, worldPos: Vec2, angle: number, ppu: number): Vec2
+(shape: Collider2DShape, worldPos: Vec2, angle: number, ppu: number): Vec2
```
## shapeOffset — function @experimental
```
-(shape: ColliderShape): Vec2
+(shape: Collider2DShape): Vec2
```
## shutdownDrawAPI — function @experimental
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 335b7f87d..619cdfe2c 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1970,6 +1970,29 @@ max: Vec3
min: Vec3
```
+## Collider2DInstance — interface @experimental
+```
+enabled: boolean
+isSensor: boolean
+shape: Collider2DShape
+```
+
+## Collider2DOutline — interface @experimental
+```
+circles: { c: Vec2; r: number; }[]
+polylines: Vec2[][]
+```
+
+## Collider2DShape — type @experimental
+```
+| { kind: 'box'; halfExtents: Vec2; offset: Vec2 }
+ | { kind: 'circle'; radius: number; offset: Vec2 }
+ | { kind: 'capsule'; radius: number; halfHeight: number; offset: Vec2 }
+ | { kind: 'segment'; point1: Vec2; point2: Vec2 }
+ | { kind: 'polygon'; vertices: Vec2[] }
+ | { kind: 'chain'; points: Vec2[]; isLoop: boolean }
+```
+
## Collider3DComponent — type @experimental
```
| 'BoxCollider3D' | 'SphereCollider3D' | 'CapsuleCollider3D'
@@ -1991,29 +2014,6 @@ shape: Collider3DShape
| { kind: 'capsule'; radius: number; halfHeight: number }
```
-## ColliderInstance — interface @experimental
-```
-enabled: boolean
-isSensor: boolean
-shape: ColliderShape
-```
-
-## ColliderOutline — interface @experimental
-```
-circles: { c: Vec2; r: number; }[]
-polylines: Vec2[][]
-```
-
-## ColliderShape — type @experimental
-```
-| { kind: 'box'; halfExtents: Vec2; offset: Vec2 }
- | { kind: 'circle'; radius: number; offset: Vec2 }
- | { kind: 'capsule'; radius: number; halfHeight: number; offset: Vec2 }
- | { kind: 'segment'; point1: Vec2; point2: Vec2 }
- | { kind: 'polygon'; vertices: Vec2[] }
- | { kind: 'chain'; points: Vec2[]; isLoop: boolean }
-```
-
## CollisionBrush — interface @experimental
```
collision: ResolvedTileCollision
@@ -4149,7 +4149,7 @@ mouse: boolean | undefined
app: App
module: ESEngineModule | null
physics3dModule: Physics3DWasmModule | undefined
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
physicsModule: PhysicsWasmModule | null | undefined
sceneData: SceneData
@@ -5055,7 +5055,7 @@ colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
entryScene: string
hotUpdate: { remoteRoot?: string; persistUpdateKey?: string; } | undefined
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
renderBackend: "webgl2" | "webgpu" | undefined
scenes: { name: string; path: string; }[] | undefined
@@ -5254,41 +5254,29 @@ static prototype: PerceptionPlugin
ComponentDef<{}>
```
-## Physics — const @beta
-```
-ResourceDef<PhysicsAPI>
-```
-
-## Physics3DDebugDraw — const @experimental
-```
-ResourceDef<Physics3DDebugDrawConfig>
-```
-
-## Physics3DDebugDrawConfig — interface @experimental
+## Physics2D — const @beta
```
-enabled: boolean
-showColliders: boolean
-showContacts: boolean
+ResourceDef<Physics2DAPI>
```
-## PhysicsContactEventData — interface @experimental
+## Physics2DContactEventData — interface @experimental
```
approachSpeed: number | undefined
isSensor: boolean | undefined
other: number
```
-## PhysicsEventType — type @experimental
+## Physics2DEventType — type @experimental
```
-typeof PhysicsEventType[keyof typeof PhysicsEventType]
+typeof Physics2DEventType[keyof typeof Physics2DEventType]
```
-## PhysicsEvents — const @beta
+## Physics2DEvents — const @beta
```
-ResourceDef<PhysicsEventsData>
+ResourceDef<Physics2DEventsData>
```
-## PhysicsEventsData — interface @experimental
+## Physics2DEventsData — interface @experimental
```
collisionEnters: CollisionEnterEvent[]
collisionExits: { entityA: Entity; entityB: Entity; }[]
@@ -5297,21 +5285,16 @@ sensorEnters: SensorEvent[]
sensorExits: SensorEvent[]
```
-## PhysicsModuleFactory — type @experimental
-```
-(config?: Record<string, unknown>) => Promise<PhysicsWasmModule>
-```
-
-## PhysicsPlugin — class @experimental
+## Physics2DPlugin — class @experimental
```
build: (app: App) => void
cleanup: () => void
name: string
-static new (wasmUrl: string, config?: PhysicsPluginConfig, factory?: PhysicsModuleFactory): PhysicsPlugin
-static prototype: PhysicsPlugin
+static new (wasmUrl: string, config?: Physics2DPluginConfig, factory?: PhysicsModuleFactory): Physics2DPlugin
+static prototype: Physics2DPlugin
```
-## PhysicsPluginConfig — interface @experimental
+## Physics2DPluginConfig — interface @experimental
```
collisionLayerMasks: number[] | undefined
contactDampingRatio: number | undefined
@@ -5326,6 +5309,23 @@ restitutionThreshold: number | undefined
subStepCount: number | undefined
```
+## Physics3DDebugDraw — const @experimental
+```
+ResourceDef<Physics3DDebugDrawConfig>
+```
+
+## Physics3DDebugDrawConfig — interface @experimental
+```
+enabled: boolean
+showColliders: boolean
+showContacts: boolean
+```
+
+## PhysicsModuleFactory — type @experimental
+```
+(config?: Record<string, unknown>) => Promise<PhysicsWasmModule>
+```
+
## PhysicsWasmModule — interface @experimental
```
HEAPF32: Float32Array<ArrayBufferLike>
@@ -5670,7 +5670,7 @@ extraScenes: { name: string; data?: SceneData; path?: string; }[] | undefined
manifest: AddressableManifest | null | undefined
module: ESEngineModule
persistUpdateKey: string | undefined
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
remoteRoot: string | undefined
sceneData: SceneData
@@ -5695,7 +5695,7 @@ depthLayers: number | undefined
firstScene: string
manifest: AddressableManifest | null | undefined
module: ESEngineModule
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
scenes: { name: string; data: SceneData; }[]
uiTheme: "dark" | "light" | undefined
@@ -6568,7 +6568,7 @@ firstScene: string
manifest: AddressableManifest | ManifestModel | null | undefined
module: ESEngineModule | null
persistUpdateKey: string | undefined
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
physicsModule: PhysicsWasmModule | null | undefined
remoteRoot: string | undefined
@@ -9812,14 +9812,14 @@ BtPlugin
(asset: TilesetAsset): number[]
```
-## collider3DWireframe — function @experimental
+## collider2DOutline — function @experimental
```
-(shape: Collider3DShape, segments?: number): Vec3[][]
+(shape: Collider2DShape, center: Vec2, angle: number, ppu: number): Collider2DOutline
```
-## colliderShapeOutline — function @experimental
+## collider3DWireframe — function @experimental
```
-(shape: ColliderShape, center: Vec2, angle: number, ppu: number): ColliderOutline
+(shape: Collider3DShape, segments?: number): Vec3[][]
```
## collisionRefWithMaterial — function @experimental
@@ -10959,7 +10959,7 @@ Logger
## makeLosCheck — function @experimental
```
-(physics: PhysicsAPI): LosCheck
+(physics: Physics2DAPI): LosCheck
```
## makeWidgetInteractable — function @experimental
@@ -11144,7 +11144,7 @@ NodePlatformAdapter
## packagedRuntimeInit — function @experimental
```
-(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit">): { physicsEnabled?: boolean; physicsConfig?: PhysicsPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; }
+(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit">): { physicsEnabled?: boolean; physicsConfig?: Physics2DPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; }
```
## paramDefaultValue — function @experimental
@@ -11427,14 +11427,14 @@ PrefabsPlugin
(ray: WorldRay, point: Vec3, normal: Vec3): Vec3 | null
```
-## readCollider3DShapes — function @experimental
+## readCollider2DShapes — function @experimental
```
-(world: World, entity: number): Collider3DInstance[]
+(world: World, entity: number): Collider2DInstance[]
```
-## readColliderShapes — function @experimental
+## readCollider3DShapes — function @experimental
```
-(world: World, entity: number): ColliderInstance[]
+(world: World, entity: number): Collider3DInstance[]
```
## readFieldPath — function @experimental
@@ -11969,12 +11969,12 @@ ServicesPlugin
## shapeCenter — function @experimental
```
-(shape: ColliderShape, worldPos: Vec2, angle: number, ppu: number): Vec2
+(shape: Collider2DShape, worldPos: Vec2, angle: number, ppu: number): Vec2
```
## shapeOffset — function @experimental
```
-(shape: ColliderShape): Vec2
+(shape: Collider2DShape): Vec2
```
## shutdownDrawAPI — function @experimental
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index c7d2a49f3..66857d5bc 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1970,6 +1970,29 @@ max: Vec3
min: Vec3
```
+## Collider2DInstance — interface @experimental
+```
+enabled: boolean
+isSensor: boolean
+shape: Collider2DShape
+```
+
+## Collider2DOutline — interface @experimental
+```
+circles: { c: Vec2; r: number; }[]
+polylines: Vec2[][]
+```
+
+## Collider2DShape — type @experimental
+```
+| { kind: 'box'; halfExtents: Vec2; offset: Vec2 }
+ | { kind: 'circle'; radius: number; offset: Vec2 }
+ | { kind: 'capsule'; radius: number; halfHeight: number; offset: Vec2 }
+ | { kind: 'segment'; point1: Vec2; point2: Vec2 }
+ | { kind: 'polygon'; vertices: Vec2[] }
+ | { kind: 'chain'; points: Vec2[]; isLoop: boolean }
+```
+
## Collider3DComponent — type @experimental
```
| 'BoxCollider3D' | 'SphereCollider3D' | 'CapsuleCollider3D'
@@ -1991,29 +2014,6 @@ shape: Collider3DShape
| { kind: 'capsule'; radius: number; halfHeight: number }
```
-## ColliderInstance — interface @experimental
-```
-enabled: boolean
-isSensor: boolean
-shape: ColliderShape
-```
-
-## ColliderOutline — interface @experimental
-```
-circles: { c: Vec2; r: number; }[]
-polylines: Vec2[][]
-```
-
-## ColliderShape — type @experimental
-```
-| { kind: 'box'; halfExtents: Vec2; offset: Vec2 }
- | { kind: 'circle'; radius: number; offset: Vec2 }
- | { kind: 'capsule'; radius: number; halfHeight: number; offset: Vec2 }
- | { kind: 'segment'; point1: Vec2; point2: Vec2 }
- | { kind: 'polygon'; vertices: Vec2[] }
- | { kind: 'chain'; points: Vec2[]; isLoop: boolean }
-```
-
## CollisionBrush — interface @experimental
```
collision: ResolvedTileCollision
@@ -4149,7 +4149,7 @@ mouse: boolean | undefined
app: App
module: ESEngineModule | null
physics3dModule: Physics3DWasmModule | undefined
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
physicsModule: PhysicsWasmModule | null | undefined
sceneData: SceneData
@@ -4783,7 +4783,7 @@ depthLayers: number | undefined
engineFactory: (opts: unknown) => Promise<ESEngineModule>
engineWasmPath: string
firstScene: string
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
runtimeConfig: RuntimeBuildConfig | undefined
sceneNames: string[]
@@ -5300,7 +5300,7 @@ colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
entryScene: string
hotUpdate: { remoteRoot?: string; persistUpdateKey?: string; } | undefined
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
renderBackend: "webgl2" | "webgpu" | undefined
scenes: { name: string; path: string; }[] | undefined
@@ -5499,41 +5499,29 @@ static prototype: PerceptionPlugin
ComponentDef<{}>
```
-## Physics — const @beta
-```
-ResourceDef<PhysicsAPI>
-```
-
-## Physics3DDebugDraw — const @experimental
-```
-ResourceDef<Physics3DDebugDrawConfig>
-```
-
-## Physics3DDebugDrawConfig — interface @experimental
+## Physics2D — const @beta
```
-enabled: boolean
-showColliders: boolean
-showContacts: boolean
+ResourceDef<Physics2DAPI>
```
-## PhysicsContactEventData — interface @experimental
+## Physics2DContactEventData — interface @experimental
```
approachSpeed: number | undefined
isSensor: boolean | undefined
other: number
```
-## PhysicsEventType — type @experimental
+## Physics2DEventType — type @experimental
```
-typeof PhysicsEventType[keyof typeof PhysicsEventType]
+typeof Physics2DEventType[keyof typeof Physics2DEventType]
```
-## PhysicsEvents — const @beta
+## Physics2DEvents — const @beta
```
-ResourceDef<PhysicsEventsData>
+ResourceDef<Physics2DEventsData>
```
-## PhysicsEventsData — interface @experimental
+## Physics2DEventsData — interface @experimental
```
collisionEnters: CollisionEnterEvent[]
collisionExits: { entityA: Entity; entityB: Entity; }[]
@@ -5542,21 +5530,16 @@ sensorEnters: SensorEvent[]
sensorExits: SensorEvent[]
```
-## PhysicsModuleFactory — type @experimental
-```
-(config?: Record<string, unknown>) => Promise<PhysicsWasmModule>
-```
-
-## PhysicsPlugin — class @experimental
+## Physics2DPlugin — class @experimental
```
build: (app: App) => void
cleanup: () => void
name: string
-static new (wasmUrl: string, config?: PhysicsPluginConfig, factory?: PhysicsModuleFactory): PhysicsPlugin
-static prototype: PhysicsPlugin
+static new (wasmUrl: string, config?: Physics2DPluginConfig, factory?: PhysicsModuleFactory): Physics2DPlugin
+static prototype: Physics2DPlugin
```
-## PhysicsPluginConfig — interface @experimental
+## Physics2DPluginConfig — interface @experimental
```
collisionLayerMasks: number[] | undefined
contactDampingRatio: number | undefined
@@ -5571,6 +5554,23 @@ restitutionThreshold: number | undefined
subStepCount: number | undefined
```
+## Physics3DDebugDraw — const @experimental
+```
+ResourceDef<Physics3DDebugDrawConfig>
+```
+
+## Physics3DDebugDrawConfig — interface @experimental
+```
+enabled: boolean
+showColliders: boolean
+showContacts: boolean
+```
+
+## PhysicsModuleFactory — type @experimental
+```
+(config?: Record<string, unknown>) => Promise<PhysicsWasmModule>
+```
+
## PhysicsWasmModule — interface @experimental
```
HEAPF32: Float32Array<ArrayBufferLike>
@@ -5915,7 +5915,7 @@ extraScenes: { name: string; data?: SceneData; path?: string; }[] | undefined
manifest: AddressableManifest | null | undefined
module: ESEngineModule
persistUpdateKey: string | undefined
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
remoteRoot: string | undefined
sceneData: SceneData
@@ -5940,7 +5940,7 @@ depthLayers: number | undefined
firstScene: string
manifest: AddressableManifest | null | undefined
module: ESEngineModule
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
scenes: { name: string; data: SceneData; }[]
uiTheme: "dark" | "light" | undefined
@@ -6813,7 +6813,7 @@ firstScene: string
manifest: AddressableManifest | ManifestModel | null | undefined
module: ESEngineModule | null
persistUpdateKey: string | undefined
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
physicsModule: PhysicsWasmModule | null | undefined
remoteRoot: string | undefined
@@ -10063,14 +10063,14 @@ BtPlugin
(asset: TilesetAsset): number[]
```
-## collider3DWireframe — function @experimental
+## collider2DOutline — function @experimental
```
-(shape: Collider3DShape, segments?: number): Vec3[][]
+(shape: Collider2DShape, center: Vec2, angle: number, ppu: number): Collider2DOutline
```
-## colliderShapeOutline — function @experimental
+## collider3DWireframe — function @experimental
```
-(shape: ColliderShape, center: Vec2, angle: number, ppu: number): ColliderOutline
+(shape: Collider3DShape, segments?: number): Vec3[][]
```
## collisionRefWithMaterial — function @experimental
@@ -11220,7 +11220,7 @@ Logger
## makeLosCheck — function @experimental
```
-(physics: PhysicsAPI): LosCheck
+(physics: Physics2DAPI): LosCheck
```
## makeWidgetInteractable — function @experimental
@@ -11400,7 +11400,7 @@ NavPlugin
## packagedRuntimeInit — function @experimental
```
-(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit">): { physicsEnabled?: boolean; physicsConfig?: PhysicsPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; }
+(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit">): { physicsEnabled?: boolean; physicsConfig?: Physics2DPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; }
```
## paramDefaultValue — function @experimental
@@ -11683,14 +11683,14 @@ PrefabsPlugin
(ray: WorldRay, point: Vec3, normal: Vec3): Vec3 | null
```
-## readCollider3DShapes — function @experimental
+## readCollider2DShapes — function @experimental
```
-(world: World, entity: number): Collider3DInstance[]
+(world: World, entity: number): Collider2DInstance[]
```
-## readColliderShapes — function @experimental
+## readCollider3DShapes — function @experimental
```
-(world: World, entity: number): ColliderInstance[]
+(world: World, entity: number): Collider3DInstance[]
```
## readFieldPath — function @experimental
@@ -12225,12 +12225,12 @@ ServicesPlugin
## shapeCenter — function @experimental
```
-(shape: ColliderShape, worldPos: Vec2, angle: number, ppu: number): Vec2
+(shape: Collider2DShape, worldPos: Vec2, angle: number, ppu: number): Vec2
```
## shapeOffset — function @experimental
```
-(shape: ColliderShape): Vec2
+(shape: Collider2DShape): Vec2
```
## shutdownDrawAPI — function @experimental
diff --git a/sdk/etc/physics.api.md b/sdk/etc/physics.api.md
index fda6ff673..b592dc6d6 100644
--- a/sdk/etc/physics.api.md
+++ b/sdk/etc/physics.api.md
@@ -109,20 +109,20 @@ radius: number
restitution: number
```
-## ColliderInstance — interface @experimental
+## Collider2DInstance — interface @experimental
```
enabled: boolean
isSensor: boolean
-shape: ColliderShape
+shape: Collider2DShape
```
-## ColliderOutline — interface @experimental
+## Collider2DOutline — interface @experimental
```
circles: { c: Vec2; r: number; }[]
polylines: Vec2[][]
```
-## ColliderShape — type @experimental
+## Collider2DShape — type @experimental
```
| { kind: 'box'; halfExtents: Vec2; offset: Vec2 }
| { kind: 'circle'; radius: number; offset: Vec2 }
@@ -248,12 +248,12 @@ enabled: boolean
normal: Vec2
```
-## Physics — const @beta
+## Physics2D — const @beta
```
-ResourceDef<PhysicsAPI>
+ResourceDef<Physics2DAPI>
```
-## PhysicsAPI — class @experimental
+## Physics2DAPI — class @experimental
```
@internal setPixelsPerUnit: (ppu: number) => void
applyAngularImpulse: (entity: Entity, impulse: number) => void
@@ -323,26 +323,26 @@ setWheelJointMotorSpeed: (entity: Entity, speed: number) => void
shapeCastBox: (center: Vec2, halfExtents: Vec2, angle: number, translation: Vec2, maskBits?: number, ppu?: number) => ShapeCastHit[]
shapeCastCapsule: (center1: Vec2, center2: Vec2, radius: number, translation: Vec2, maskBits?: number, ppu?: number) => ShapeCastHit[]
shapeCastCircle: (center: Vec2, radius: number, translation: Vec2, maskBits?: number, ppu?: number) => ShapeCastHit[]
-static @internal _fromModule: (module: PhysicsWasmModule) => PhysicsAPI
-static new (app: App): PhysicsAPI
-static prototype: PhysicsAPI
+static @internal _fromModule: (module: PhysicsWasmModule) => Physics2DAPI
+static new (app: App): Physics2DAPI
+static prototype: Physics2DAPI
static setDebugDraw: (app: App, enabled: boolean) => void
-static setDebugDrawConfig: (app: App, config: Partial<PhysicsDebugDrawConfig>) => void
+static setDebugDrawConfig: (app: App, config: Partial<Physics2DDebugDrawConfig>) => void
```
-## PhysicsContactEventData — interface @experimental
+## Physics2DContactEventData — interface @experimental
```
approachSpeed: number | undefined
isSensor: boolean | undefined
other: number
```
-## PhysicsDebugDraw — const @experimental
+## Physics2DDebugDraw — const @experimental
```
-ResourceDef<PhysicsDebugDrawConfig>
+ResourceDef<Physics2DDebugDrawConfig>
```
-## PhysicsDebugDrawConfig — interface @experimental
+## Physics2DDebugDrawConfig — interface @experimental
```
enabled: boolean
showColliders: boolean
@@ -350,17 +350,17 @@ showContacts: boolean
showVelocity: boolean
```
-## PhysicsEventType — type @experimental
+## Physics2DEventType — type @experimental
```
-typeof PhysicsEventType[keyof typeof PhysicsEventType]
+typeof Physics2DEventType[keyof typeof Physics2DEventType]
```
-## PhysicsEvents — const @beta
+## Physics2DEvents — const @beta
```
-ResourceDef<PhysicsEventsData>
+ResourceDef<Physics2DEventsData>
```
-## PhysicsEventsData — interface @experimental
+## Physics2DEventsData — interface @experimental
```
collisionEnters: CollisionEnterEvent[]
collisionExits: { entityA: Entity; entityB: Entity; }[]
@@ -369,21 +369,16 @@ sensorEnters: SensorEvent[]
sensorExits: SensorEvent[]
```
-## PhysicsModuleFactory — type @experimental
-```
-(config?: Record<string, unknown>) => Promise<PhysicsWasmModule>
-```
-
-## PhysicsPlugin — class @experimental
+## Physics2DPlugin — class @experimental
```
build: (app: App) => void
cleanup: () => void
name: string
-static new (wasmUrl: string, config?: PhysicsPluginConfig, factory?: PhysicsModuleFactory): PhysicsPlugin
-static prototype: PhysicsPlugin
+static new (wasmUrl: string, config?: Physics2DPluginConfig, factory?: PhysicsModuleFactory): Physics2DPlugin
+static prototype: Physics2DPlugin
```
-## PhysicsPluginConfig — interface @experimental
+## Physics2DPluginConfig — interface @experimental
```
collisionLayerMasks: number[] | undefined
contactDampingRatio: number | undefined
@@ -398,6 +393,11 @@ restitutionThreshold: number | undefined
subStepCount: number | undefined
```
+## PhysicsModuleFactory — type @experimental
+```
+(config?: Record<string, unknown>) => Promise<PhysicsWasmModule>
+```
+
## PhysicsWasmModule — interface @experimental
```
HEAPF32: Float32Array<ArrayBufferLike>
@@ -690,14 +690,14 @@ motorSpeed: number
upperTranslation: number
```
-## colliderShapeOutline — function @experimental
+## collider2DOutline — function @experimental
```
-(shape: ColliderShape, center: Vec2, angle: number, ppu: number): ColliderOutline
+(shape: Collider2DShape, center: Vec2, angle: number, ppu: number): Collider2DOutline
```
-## drawPhysicsDebug — function @experimental
+## drawPhysics2DDebug — function @experimental
```
-(app: App, physicsApiRes: ResourceDef<VelocityProvider>, physicsEventsRes: ResourceDef<PhysicsEventsData>): void
+(app: App, physicsApiRes: ResourceDef<VelocityProvider>, physicsEventsRes: ResourceDef<Physics2DEventsData>): void
```
## loadPhysicsModule — function @experimental
@@ -710,38 +710,38 @@ upperTranslation: number
(p: MoveAndSlideParams, cast: SlideCast): MoveAndSlideResult
```
-## physicsPlugin — function @experimental
+## physics2dPlugin — function @experimental
```
-(wasmUrl: string, config?: PhysicsPluginConfig, factory?: PhysicsModuleFactory): PhysicsPlugin
+(wasmUrl: string, config?: Physics2DPluginConfig, factory?: PhysicsModuleFactory): Physics2DPlugin
```
-## readColliderShapes — function @experimental
+## readCollider2DShapes — function @experimental
```
-(world: World, entity: number): ColliderInstance[]
+(world: World, entity: number): Collider2DInstance[]
```
-## registerCharacterControllerSystem — function @experimental
+## registerCharacterController2DSystem — function @experimental
```
(app: App): void
```
-## registerPhysicsEventBridge — function @experimental
+## registerPhysics2DEventBridge — function @experimental
```
(app: App): void
```
-## setupPhysicsDebugDraw — function @experimental
+## setupPhysics2DDebugDraw — function @experimental
```
-(app: App, physicsApiRes: ResourceDef<VelocityProvider>, physicsEventsRes: ResourceDef<PhysicsEventsData>): void
+(app: App, physicsApiRes: ResourceDef<VelocityProvider>, physicsEventsRes: ResourceDef<Physics2DEventsData>): void
```
## shapeCenter — function @experimental
```
-(shape: ColliderShape, worldPos: Vec2, angle: number, ppu: number): Vec2
+(shape: Collider2DShape, worldPos: Vec2, angle: number, ppu: number): Vec2
```
## shapeOffset — function @experimental
```
-(shape: ColliderShape): Vec2
+(shape: Collider2DShape): Vec2
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 11b83afb4..de7800dbc 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1970,6 +1970,29 @@ max: Vec3
min: Vec3
```
+## Collider2DInstance — interface @experimental
+```
+enabled: boolean
+isSensor: boolean
+shape: Collider2DShape
+```
+
+## Collider2DOutline — interface @experimental
+```
+circles: { c: Vec2; r: number; }[]
+polylines: Vec2[][]
+```
+
+## Collider2DShape — type @experimental
+```
+| { kind: 'box'; halfExtents: Vec2; offset: Vec2 }
+ | { kind: 'circle'; radius: number; offset: Vec2 }
+ | { kind: 'capsule'; radius: number; halfHeight: number; offset: Vec2 }
+ | { kind: 'segment'; point1: Vec2; point2: Vec2 }
+ | { kind: 'polygon'; vertices: Vec2[] }
+ | { kind: 'chain'; points: Vec2[]; isLoop: boolean }
+```
+
## Collider3DComponent — type @experimental
```
| 'BoxCollider3D' | 'SphereCollider3D' | 'CapsuleCollider3D'
@@ -1991,29 +2014,6 @@ shape: Collider3DShape
| { kind: 'capsule'; radius: number; halfHeight: number }
```
-## ColliderInstance — interface @experimental
-```
-enabled: boolean
-isSensor: boolean
-shape: ColliderShape
-```
-
-## ColliderOutline — interface @experimental
-```
-circles: { c: Vec2; r: number; }[]
-polylines: Vec2[][]
-```
-
-## ColliderShape — type @experimental
-```
-| { kind: 'box'; halfExtents: Vec2; offset: Vec2 }
- | { kind: 'circle'; radius: number; offset: Vec2 }
- | { kind: 'capsule'; radius: number; halfHeight: number; offset: Vec2 }
- | { kind: 'segment'; point1: Vec2; point2: Vec2 }
- | { kind: 'polygon'; vertices: Vec2[] }
- | { kind: 'chain'; points: Vec2[]; isLoop: boolean }
-```
-
## CollisionBrush — interface @experimental
```
collision: ResolvedTileCollision
@@ -4156,7 +4156,7 @@ mouse: boolean | undefined
app: App
module: ESEngineModule | null
physics3dModule: Physics3DWasmModule | undefined
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
physicsModule: PhysicsWasmModule | null | undefined
sceneData: SceneData
@@ -5062,7 +5062,7 @@ colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
entryScene: string
hotUpdate: { remoteRoot?: string; persistUpdateKey?: string; } | undefined
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
renderBackend: "webgl2" | "webgpu" | undefined
scenes: { name: string; path: string; }[] | undefined
@@ -5261,41 +5261,29 @@ static prototype: PerceptionPlugin
ComponentDef<{}>
```
-## Physics — const @beta
-```
-ResourceDef<PhysicsAPI>
-```
-
-## Physics3DDebugDraw — const @experimental
-```
-ResourceDef<Physics3DDebugDrawConfig>
-```
-
-## Physics3DDebugDrawConfig — interface @experimental
+## Physics2D — const @beta
```
-enabled: boolean
-showColliders: boolean
-showContacts: boolean
+ResourceDef<Physics2DAPI>
```
-## PhysicsContactEventData — interface @experimental
+## Physics2DContactEventData — interface @experimental
```
approachSpeed: number | undefined
isSensor: boolean | undefined
other: number
```
-## PhysicsEventType — type @experimental
+## Physics2DEventType — type @experimental
```
-typeof PhysicsEventType[keyof typeof PhysicsEventType]
+typeof Physics2DEventType[keyof typeof Physics2DEventType]
```
-## PhysicsEvents — const @beta
+## Physics2DEvents — const @beta
```
-ResourceDef<PhysicsEventsData>
+ResourceDef<Physics2DEventsData>
```
-## PhysicsEventsData — interface @experimental
+## Physics2DEventsData — interface @experimental
```
collisionEnters: CollisionEnterEvent[]
collisionExits: { entityA: Entity; entityB: Entity; }[]
@@ -5304,21 +5292,16 @@ sensorEnters: SensorEvent[]
sensorExits: SensorEvent[]
```
-## PhysicsModuleFactory — type @experimental
-```
-(config?: Record<string, unknown>) => Promise<PhysicsWasmModule>
-```
-
-## PhysicsPlugin — class @experimental
+## Physics2DPlugin — class @experimental
```
build: (app: App) => void
cleanup: () => void
name: string
-static new (wasmUrl: string, config?: PhysicsPluginConfig, factory?: PhysicsModuleFactory): PhysicsPlugin
-static prototype: PhysicsPlugin
+static new (wasmUrl: string, config?: Physics2DPluginConfig, factory?: PhysicsModuleFactory): Physics2DPlugin
+static prototype: Physics2DPlugin
```
-## PhysicsPluginConfig — interface @experimental
+## Physics2DPluginConfig — interface @experimental
```
collisionLayerMasks: number[] | undefined
contactDampingRatio: number | undefined
@@ -5333,6 +5316,23 @@ restitutionThreshold: number | undefined
subStepCount: number | undefined
```
+## Physics3DDebugDraw — const @experimental
+```
+ResourceDef<Physics3DDebugDrawConfig>
+```
+
+## Physics3DDebugDrawConfig — interface @experimental
+```
+enabled: boolean
+showColliders: boolean
+showContacts: boolean
+```
+
+## PhysicsModuleFactory — type @experimental
+```
+(config?: Record<string, unknown>) => Promise<PhysicsWasmModule>
+```
+
## PhysicsWasmModule — interface @experimental
```
HEAPF32: Float32Array<ArrayBufferLike>
@@ -5677,7 +5677,7 @@ extraScenes: { name: string; data?: SceneData; path?: string; }[] | undefined
manifest: AddressableManifest | null | undefined
module: ESEngineModule
persistUpdateKey: string | undefined
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
remoteRoot: string | undefined
sceneData: SceneData
@@ -5702,7 +5702,7 @@ depthLayers: number | undefined
firstScene: string
manifest: AddressableManifest | null | undefined
module: ESEngineModule
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
scenes: { name: string; data: SceneData; }[]
uiTheme: "dark" | "light" | undefined
@@ -6575,7 +6575,7 @@ firstScene: string
manifest: AddressableManifest | ManifestModel | null | undefined
module: ESEngineModule | null
persistUpdateKey: string | undefined
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
physicsModule: PhysicsWasmModule | null | undefined
remoteRoot: string | undefined
@@ -9175,7 +9175,7 @@ depthLayers: number | undefined
engineFactory: (opts: unknown) => Promise<ESEngineModule>
engineWasmPath: string | undefined
firstScene: string
-physicsConfig: PhysicsPluginConfig | undefined
+physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
runtimeConfig: RuntimeBuildConfig | undefined
sceneNames: string[]
@@ -9839,14 +9839,14 @@ BtPlugin
(asset: TilesetAsset): number[]
```
-## collider3DWireframe — function @experimental
+## collider2DOutline — function @experimental
```
-(shape: Collider3DShape, segments?: number): Vec3[][]
+(shape: Collider2DShape, center: Vec2, angle: number, ppu: number): Collider2DOutline
```
-## colliderShapeOutline — function @experimental
+## collider3DWireframe — function @experimental
```
-(shape: ColliderShape, center: Vec2, angle: number, ppu: number): ColliderOutline
+(shape: Collider3DShape, segments?: number): Vec3[][]
```
## collisionRefWithMaterial — function @experimental
@@ -10986,7 +10986,7 @@ Logger
## makeLosCheck — function @experimental
```
-(physics: PhysicsAPI): LosCheck
+(physics: Physics2DAPI): LosCheck
```
## makeWidgetInteractable — function @experimental
@@ -11166,7 +11166,7 @@ NavPlugin
## packagedRuntimeInit — function @experimental
```
-(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit">): { physicsEnabled?: boolean; physicsConfig?: PhysicsPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; }
+(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit">): { physicsEnabled?: boolean; physicsConfig?: Physics2DPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; }
```
## paramDefaultValue — function @experimental
@@ -11449,14 +11449,14 @@ PrefabsPlugin
(ray: WorldRay, point: Vec3, normal: Vec3): Vec3 | null
```
-## readCollider3DShapes — function @experimental
+## readCollider2DShapes — function @experimental
```
-(world: World, entity: number): Collider3DInstance[]
+(world: World, entity: number): Collider2DInstance[]
```
-## readColliderShapes — function @experimental
+## readCollider3DShapes — function @experimental
```
-(world: World, entity: number): ColliderInstance[]
+(world: World, entity: number): Collider3DInstance[]
```
## readFieldPath — function @experimental
@@ -11991,12 +11991,12 @@ ServicesPlugin
## shapeCenter — function @experimental
```
-(shape: ColliderShape, worldPos: Vec2, angle: number, ppu: number): Vec2
+(shape: Collider2DShape, worldPos: Vec2, angle: number, ppu: number): Vec2
```
## shapeOffset — function @experimental
```
-(shape: ColliderShape): Vec2
+(shape: Collider2DShape): Vec2
```
## shutdownDrawAPI — function @experimental
diff --git a/sdk/src/ai/perception/PerceptionPlugin.ts b/sdk/src/ai/perception/PerceptionPlugin.ts
index 9c1666dac..a482e4e4b 100644
--- a/sdk/src/ai/perception/PerceptionPlugin.ts
+++ b/sdk/src/ai/perception/PerceptionPlugin.ts
@@ -7,7 +7,7 @@
* decision system reads a fresh Perception the same frame.
*
* `stepPerception` is extracted to unit-test against a fake world. Line
- * of sight uses a physics raycast when a Physics is present, and is
+ * of sight uses a physics raycast when a Physics2D is present, and is
* skipped (range + FOV only) otherwise — no hard physics dependency.
*/
@@ -17,7 +17,7 @@ import { defineSystem, Schedule, GetWorld } from '../../ecs/system';
import { playModeOnly } from '../../ecs/env';
import { Transform } from '../../ecs/component';
import type { AnyComponentDef, ComponentData } from '../../ecs/component';
-import { Physics, type PhysicsAPI } from '../../physics';
+import { Physics2D, type Physics2DAPI } from '../../physics';
import { Physics3D } from '../../physics3d/Physics3DPlugin';
import type { Physics3DQueries } from '../../physics3d/Physics3DQueries';
import { senseTarget, facingFromRotation } from './sense';
@@ -88,7 +88,7 @@ export function stepPerception(world: PerceptionWorldView, isBlocked?: LosCheck)
* feet, so a ray aimed at the origin passes through the target's own capsule —
* counting that hides everyone approached from below.
*/
-export function makeLosCheck(physics: PhysicsAPI): LosCheck {
+export function makeLosCheck(physics: Physics2DAPI): LosCheck {
return (from, to, observer, target) => {
const dx = to.x - from.x;
const dy = to.y - from.y;
@@ -128,7 +128,7 @@ export class PerceptionPlugin implements Plugin {
// walls of a 3D scene, and the 2D one knows nothing about them.
const q3d = app.hasResource(Physics3D)
? app.getResource<Physics3DQueries | null>(Physics3D) : null;
- const physics = app.hasResource(Physics) ? app.getResource<PhysicsAPI>(Physics) : null;
+ const physics = app.hasResource(Physics2D) ? app.getResource<Physics2DAPI>(Physics2D) : null;
const los = q3d ? makeLosCheck3D(q3d) : physics ? makeLosCheck(physics) : undefined;
stepPerception(world as PerceptionWorldView, los);
},
diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.ts
index 438cd009b..0514707a8 100644
--- a/sdk/src/app/app.ts
+++ b/sdk/src/app/app.ts
@@ -36,7 +36,7 @@ import { setLinearColorSpace } from '../ecs/env';
import { seedEngineComponents } from '../ecs/component';
import { cameraPlugin } from '../camera/CameraPlugin';
import { ScreenScaling, SCREEN_FIT_OFF, type ScreenScalingData } from '../camera/ScreenScaling';
-import { PhysicsRuntime } from '../physics/PhysicsRuntime';
+import { Physics2DRuntime } from '../physics/Physics2DRuntime';
import { SubsystemRegistry } from './subsystems';
import { DOMAIN_SCRIPTS, DOMAIN_UNATTRIBUTED, type ScopeCost, type ScopeRemainder, type SystemCost } from './frameProfile';
import type { SideModuleHost } from '../sideModules/host';
@@ -578,17 +578,17 @@ export class App {
}
async waitForPhysics(): Promise<void> {
- if (!this.hasResource(PhysicsRuntime)) {
- log.warn('app', 'No PhysicsPlugin installed, waitForPhysics() is a no-op');
+ if (!this.hasResource(Physics2DRuntime)) {
+ log.warn('app', 'No Physics2DPlugin installed, waitForPhysics() is a no-op');
return;
}
- const promise = this.getResource(PhysicsRuntime).initPromise;
+ const promise = this.getResource(Physics2DRuntime).initPromise;
if (promise) await promise;
}
get isPhysicsReady(): boolean {
- return this.hasResource(PhysicsRuntime)
- && this.getResource(PhysicsRuntime).module != null;
+ return this.hasResource(Physics2DRuntime)
+ && this.getResource(Physics2DRuntime).module != null;
}
// =========================================================================
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index c010a8eb4..e90261f20 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -644,8 +644,8 @@ export {
export type {
PhysicsWasmModule,
PhysicsModuleFactory,
- PhysicsPluginConfig,
- PhysicsEventsData,
+ Physics2DPluginConfig,
+ Physics2DEventsData,
CollisionEnterEvent,
CollisionHitEvent,
SensorEvent,
diff --git a/sdk/src/core-plugins.ts b/sdk/src/core-plugins.ts
index b7bfb1dc3..2ba57f315 100644
--- a/sdk/src/core-plugins.ts
+++ b/sdk/src/core-plugins.ts
@@ -32,11 +32,11 @@ export { dragPlugin, DragPlugin } from './ui/input/drag';
export { focusPlugin, FocusPlugin } from './ui/input/focus';
export { safeAreaPlugin, SafeAreaPlugin } from './ui/layout/safe-area';
-export { PhysicsPlugin, PhysicsEvents, Physics, loadPhysicsModule } from './physics';
+export { Physics2DPlugin, Physics2DEvents, Physics2D, loadPhysicsModule } from './physics';
// The contact event names, mirrored into the main barrel: an editor palette (or
// game code) must be able to spell `trigger_enter` without importing the side
// module, since the wire is authored whether or not physics is loaded.
-export { PhysicsEventType, type PhysicsContactEventData } from './physics';
+export { Physics2DEventType, type Physics2DContactEventData } from './physics';
export { SpinePlugin, SpineEvents, Spine } from './spine';
// DragonBones beside it, and in the barrel for the same reason: the native entry
// collapses every `esengine*` import onto ONE global, so a game reaching
diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.ts
index 462f29952..2cc3c6400 100644
--- a/sdk/src/core-runtime.ts
+++ b/sdk/src/core-runtime.ts
@@ -174,15 +174,15 @@ export {
} from './physics/CharacterController2D';
export {
- readColliderShapes,
+ readCollider2DShapes,
shapeOffset,
shapeCenter,
- colliderShapeOutline,
+ collider2DOutline,
CAPSULE_ARC_SEGMENTS,
- type ColliderShape,
- type ColliderInstance,
- type ColliderOutline,
-} from './physics/ColliderShape';
+ type Collider2DShape,
+ type Collider2DInstance,
+ type Collider2DOutline,
+} from './physics/ColliderShape2D';
export {
RigidBody3D,
diff --git a/sdk/src/diagnostics/censusProbes.ts b/sdk/src/diagnostics/censusProbes.ts
index fc0c1c1aa..f499b70d0 100644
--- a/sdk/src/diagnostics/censusProbes.ts
+++ b/sdk/src/diagnostics/censusProbes.ts
@@ -180,7 +180,7 @@ export function installBuiltinCensusProbes(): void {
registerCensusProbe({
id: 'physics',
read(ctx) {
- const m = resource<{ module: PhysicsCensusModule | null }>(ctx, 'PhysicsRuntime')?.module;
+ const m = resource<{ module: PhysicsCensusModule | null }>(ctx, 'Physics2DRuntime')?.module;
// Absent until the side module resolves, and absent forever in a game
// with no physics — both are "no counters", never "no bodies".
if (!m?._physics_getBodyCount) return undefined;
diff --git a/sdk/src/physics/CharacterController2D.ts b/sdk/src/physics/CharacterController2D.ts
index 3fb01efd1..a20635d1d 100644
--- a/sdk/src/physics/CharacterController2D.ts
+++ b/sdk/src/physics/CharacterController2D.ts
@@ -6,7 +6,7 @@
* of Box2D v3's native kinematic mover.
*
* The controller reads the entity's own collider, derives a capsule mover from it,
- * and advances one step via `PhysicsAPI.moveCharacter` — Box2D's `b2World_CollideMover`
+ * and advances one step via `Physics2DAPI.moveCharacter` — Box2D's `b2World_CollideMover`
* + `b2SolvePlanes`, which collides the capsule into contact *planes* and solves a
* depenetrating slide. That resolves a character resting on the ground with valid
* normals (a generic shape cast reports the resting contact as a zero-normal
@@ -18,7 +18,7 @@
* (and for its tests); the live system uses the native mover.
*
* Units: `velocity`/positions are world pixels (matching `Transform`); collider
- * dimensions are meters and are scaled to pixels via `PhysicsAPI.getPixelsPerUnit()`.
+ * dimensions are meters and are scaled to pixels via `Physics2DAPI.getPixelsPerUnit()`.
*/
import type { App } from '../app/app';
import type { Entity, Vec2 } from '../types';
@@ -27,7 +27,7 @@ import { Schedule, defineSystem, GetWorld } from '../ecs/system';
import { Query, Mut } from '../ecs/query';
import { Res, Time, type TimeData } from '../ecs/resource';
import { playModeOnly } from '../ecs/env';
-import { Physics, type PhysicsAPI } from './Physics';
+import { Physics2D, type Physics2DAPI } from './Physics2D';
import { readPixelsPerUnit } from './PhysicsSystem';
import { BoxCollider2D, CircleCollider2D, CapsuleCollider2D, activeCollider } from './PhysicsComponents';
import { log } from '../util/logger';
@@ -305,16 +305,16 @@ function warnNonFiniteMove(entity: Entity, ppu: number, dt: number): void {
* depenetrating slide), which — unlike a generic shape cast — resolves a character
* resting on the ground with valid contact normals instead of wedging on it.
*/
-export function registerCharacterControllerSystem(app: App): void {
+export function registerCharacterController2DSystem(app: App): void {
warnedNonFiniteMove = false;
app.addSystemToSchedule(
Schedule.FixedUpdate,
defineSystem(
- [Query(Mut(CharacterController2D)), Res(Time), Res(Physics), GetWorld()],
+ [Query(Mut(CharacterController2D)), Res(Time), Res(Physics2D), GetWorld()],
(
query: Iterable<[Entity, CharacterController2DData]>,
time: TimeData,
- physics: PhysicsAPI,
+ physics: Physics2DAPI,
world: World,
) => {
const dt = time.fixedDelta;
diff --git a/sdk/src/physics/ColliderShape.ts b/sdk/src/physics/ColliderShape2D.ts
similarity index 89%
rename from sdk/src/physics/ColliderShape.ts
rename to sdk/src/physics/ColliderShape2D.ts
index a3a595ccf..c4e7d05e4 100644
--- a/sdk/src/physics/ColliderShape.ts
+++ b/sdk/src/physics/ColliderShape2D.ts
@@ -1,9 +1,9 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
- * @file ColliderShape.ts
+ * @file Collider2DShape.ts
* @brief The single geometry projection over the collider components — the shared
- * seam for BOTH visualizers (the runtime PhysicsDebugDraw and the editor's
+ * seam for BOTH visualizers (the runtime Physics2DDebugDraw and the editor's
* collider gizmo) and for tile-collision overlays. It does NOT touch the
* runtime physics model: colliders stay ordinary C++/TS components dispatched
* by presence in PhysicsSystem; this only READS them into a shape descriptor,
@@ -11,7 +11,7 @@
* emits world-space outlines each backend renders in its own primitives.
*
* Units: shape fields are physics metres (as stored on the components); `ppu`
- * (pixels-per-unit) scales them to world pixels in shapeCenter / colliderShapeOutline.
+ * (pixels-per-unit) scales them to world pixels in shapeCenter / collider2DOutline.
*/
import type { Vec2 } from '../types';
import type { World } from '../ecs/world';
@@ -29,7 +29,7 @@ export const CAPSULE_ARC_SEGMENTS = 16;
/** A collider's geometry, in physics metres. Offset (box/circle/capsule) is metres too;
* segment/polygon/chain carry their points directly and sit at the entity origin. */
-export type ColliderShape =
+export type Collider2DShape =
| { kind: 'box'; halfExtents: Vec2; offset: Vec2 }
| { kind: 'circle'; radius: number; offset: Vec2 }
| { kind: 'capsule'; radius: number; halfHeight: number; offset: Vec2 }
@@ -41,15 +41,15 @@ export type ColliderShape =
* the enabled flag they decide by: a disabled collider is absent from the physics
* world, so the runtime overlay skips it while the editor keeps drawing it (you
* still author its geometry through the gizmo). */
-export interface ColliderInstance {
- shape: ColliderShape;
+export interface Collider2DInstance {
+ shape: Collider2DShape;
isSensor: boolean;
enabled: boolean;
}
/** World-space (pixel) outline: straight runs as polylines + true circles left as
* {center, radius} so a backend can stroke them as arcs (SVG <circle> / circleOutline). */
-export interface ColliderOutline {
+export interface Collider2DOutline {
polylines: Vec2[][];
circles: { c: Vec2; r: number }[];
}
@@ -57,7 +57,7 @@ export interface ColliderOutline {
const ZERO: Vec2 = { x: 0, y: 0 };
/** The collider's local offset in metres (0 for segment/polygon/chain, which have none). */
-export function shapeOffset(shape: ColliderShape): Vec2 {
+export function shapeOffset(shape: Collider2DShape): Vec2 {
return (shape.kind === 'box' || shape.kind === 'circle' || shape.kind === 'capsule')
? shape.offset
: ZERO;
@@ -65,10 +65,10 @@ export function shapeOffset(shape: ColliderShape): Vec2 {
/**
* The shape's world-pixel centre = the entity's world position plus its collider offset
- * (metres × ppu) rotated by the entity angle. This is the offset+rotation transform that
- * used to be re-implemented in PhysicsDebugDraw and ViewportController.
+ * (metres × ppu) rotated by the entity angle. Every drawer of a collider goes through
+ * here, so a gizmo and the solver cannot disagree about where the shape is.
*/
-export function shapeCenter(shape: ColliderShape, worldPos: Vec2, angle: number, ppu: number): Vec2 {
+export function shapeCenter(shape: Collider2DShape, worldPos: Vec2, angle: number, ppu: number): Vec2 {
const off = shapeOffset(shape);
const ox = off.x * ppu;
const oy = off.y * ppu;
@@ -82,7 +82,7 @@ export function shapeCenter(shape: ColliderShape, worldPos: Vec2, angle: number,
* {@link shapeCenter}). Straight-edged shapes return closed/open polylines; a circle
* returns a single {c, r} for the backend to stroke as an arc.
*/
-export function colliderShapeOutline(shape: ColliderShape, center: Vec2, angle: number, ppu: number): ColliderOutline {
+export function collider2DOutline(shape: Collider2DShape, center: Vec2, angle: number, ppu: number): Collider2DOutline {
const cos = Math.cos(angle);
const sin = Math.sin(angle);
// local (px) → world (px), rotated about center.
@@ -136,8 +136,8 @@ export function colliderShapeOutline(shape: ColliderShape, center: Vec2, angle:
* order PhysicsSystem's addShapeForEntity dispatches (box, circle, capsule, segment,
* polygon, chain). Chain has no sensor flag, so it reports isSensor: false.
*/
-export function readColliderShapes(world: World, entity: number): ColliderInstance[] {
- const out: ColliderInstance[] = [];
+export function readCollider2DShapes(world: World, entity: number): Collider2DInstance[] {
+ const out: Collider2DInstance[] = [];
const isEnabled = (c: { enabled?: boolean }): boolean => c.enabled !== false;
if (world.has(entity, BoxCollider2D)) {
const b = world.get(entity, BoxCollider2D) as BoxCollider2DData;
diff --git a/sdk/src/physics/Physics.ts b/sdk/src/physics/Physics2D.ts
similarity index 94%
rename from sdk/src/physics/Physics.ts
rename to sdk/src/physics/Physics2D.ts
index 877219956..62800cb67 100644
--- a/sdk/src/physics/Physics.ts
+++ b/sdk/src/physics/Physics2D.ts
@@ -4,9 +4,9 @@
* @file Physics.ts
* @brief User-facing physics API + Physics resource
*
- * `PhysicsAPI` is the ergonomic wrapper game code uses to drive bodies
+ * `Physics2DAPI` is the ergonomic wrapper game code uses to drive bodies
* (forces, impulses, joints, raycasts). It is published as the
- * `Physics` resource once `PhysicsPlugin` finishes loading the
+ * `Physics` resource once `Physics2DPlugin` finishes loading the
* wasm module; instantiation before that throws.
*/
@@ -14,8 +14,8 @@ import type { App } from '../app/app';
import type { Entity, Vec2 } from '../types';
import { defineResource } from '../ecs/resource';
import type { PhysicsWasmModule } from './PhysicsModuleLoader';
-import { PhysicsRuntime } from './PhysicsRuntime';
-import { PhysicsDebugDraw, type PhysicsDebugDrawConfig } from './PhysicsDebugDraw';
+import { Physics2DRuntime } from './Physics2DRuntime';
+import { Physics2DDebugDraw, type Physics2DDebugDrawConfig } from './Physics2DDebugDraw';
import {
CAST_HIT_STRIDE,
type RaycastHit,
@@ -39,7 +39,7 @@ const DEFAULT_PIXELS_PER_UNIT = 100;
* velocities, `setGravity` — is in **meters** (m/s, m/s²), matching the collider
* component dimensions. Convert with {@link getPixelsPerUnit} when mixing the two.
*/
-export class PhysicsAPI {
+export class Physics2DAPI {
private module_!: PhysicsWasmModule;
// Live pixels-per-unit, pushed each frame by PhysicsSystem from the Canvas, so
// a query that omits `ppu` is scaled correctly instead of silently assuming 100.
@@ -70,18 +70,18 @@ export class PhysicsAPI {
}
constructor(app: App) {
- const module = app.hasResource(PhysicsRuntime)
- ? app.getResource(PhysicsRuntime).module
+ const module = app.hasResource(Physics2DRuntime)
+ ? app.getResource(Physics2DRuntime).module
: null;
if (!module) {
- throw new Error('Physics module not loaded. Ensure PhysicsPlugin init is complete.');
+ throw new Error('Physics module not loaded. Ensure Physics2DPlugin init is complete.');
}
this.init_(module);
}
/** @internal */
- static _fromModule(module: PhysicsWasmModule): PhysicsAPI {
- const instance = Object.create(PhysicsAPI.prototype) as PhysicsAPI;
+ static _fromModule(module: PhysicsWasmModule): Physics2DAPI {
+ const instance = Object.create(Physics2DAPI.prototype) as Physics2DAPI;
instance.init_(module);
return instance;
}
@@ -521,23 +521,23 @@ export class PhysicsAPI {
}
static setDebugDraw(app: App, enabled: boolean): void {
- const config = app.getResource<PhysicsDebugDrawConfig>(PhysicsDebugDraw);
+ const config = app.getResource<Physics2DDebugDrawConfig>(Physics2DDebugDraw);
if (config) {
config.enabled = enabled;
- app.insertResource(PhysicsDebugDraw, config);
+ app.insertResource(Physics2DDebugDraw, config);
}
}
- static setDebugDrawConfig(app: App, config: Partial<PhysicsDebugDrawConfig>): void {
- const current = app.getResource<PhysicsDebugDrawConfig>(PhysicsDebugDraw);
+ static setDebugDrawConfig(app: App, config: Partial<Physics2DDebugDrawConfig>): void {
+ const current = app.getResource<Physics2DDebugDrawConfig>(Physics2DDebugDraw);
if (current) {
- app.insertResource(PhysicsDebugDraw, { ...current, ...config });
+ app.insertResource(Physics2DDebugDraw, { ...current, ...config });
}
}
}
/**
- * Resource published by `PhysicsPlugin` once the wasm module is ready.
+ * Resource published by `Physics2DPlugin` once the wasm module is ready.
* Game code reads it as `Res(Physics)` / `app.getResource(Physics)` to call forces,
* impulses, joint helpers, raycasts, etc.
*/
@@ -551,4 +551,4 @@ export class PhysicsAPI {
*
* @beta
*/
-export const Physics = defineResource<PhysicsAPI>(null!, 'Physics');
+export const Physics2D = defineResource<Physics2DAPI>(null!, 'Physics2D');
diff --git a/sdk/src/physics/PhysicsDebugDraw.ts b/sdk/src/physics/Physics2DDebugDraw.ts
similarity index 87%
rename from sdk/src/physics/PhysicsDebugDraw.ts
rename to sdk/src/physics/Physics2DDebugDraw.ts
index 6b4cf7272..78d91675c 100644
--- a/sdk/src/physics/PhysicsDebugDraw.ts
+++ b/sdk/src/physics/Physics2DDebugDraw.ts
@@ -5,27 +5,27 @@ import type { Color } from '../types';
import type { TransformData, CanvasData } from '../ecs/component';
import type { ResourceDef } from '../ecs/resource';
import type { RigidBody2DData } from './PhysicsComponents';
-import type { PhysicsEventsData } from './PhysicsPlugin';
+import type { Physics2DEventsData } from './Physics2DPlugin';
import { Transform, Canvas } from '../ecs/component';
import { Draw } from '../render/draw';
import { defineResource } from '../ecs/resource';
import { registerDrawCallback } from '../render/customDraw';
import { RigidBody2D, BodyType } from './PhysicsComponents';
-import { readColliderShapes, shapeCenter, colliderShapeOutline } from './ColliderShape';
+import { readCollider2DShapes, shapeCenter, collider2DOutline } from './ColliderShape2D';
-export interface PhysicsDebugDrawConfig {
+export interface Physics2DDebugDrawConfig {
enabled: boolean;
showColliders: boolean;
showVelocity: boolean;
showContacts: boolean;
}
-export const PhysicsDebugDraw = defineResource<PhysicsDebugDrawConfig>({
+export const Physics2DDebugDraw = defineResource<Physics2DDebugDrawConfig>({
enabled: false,
showColliders: true,
showVelocity: false,
showContacts: false,
-}, 'PhysicsDebugDraw');
+}, 'Physics2DDebugDraw');
interface VelocityProvider {
getLinearVelocity(entity: number): { x: number; y: number };
@@ -91,12 +91,12 @@ function drawVelocityArrow(
Draw.line({ x: endX, y: endY }, { x: rightX, y: rightY }, VELOCITY_COLOR, DEBUG_LINE_THICKNESS);
}
-export function drawPhysicsDebug(
+export function drawPhysics2DDebug(
app: App,
physicsApiRes: ResourceDef<VelocityProvider>,
- physicsEventsRes: ResourceDef<PhysicsEventsData>,
+ physicsEventsRes: ResourceDef<Physics2DEventsData>,
): void {
- const config = app.getResource<PhysicsDebugDrawConfig>(PhysicsDebugDraw);
+ const config = app.getResource<Physics2DDebugDrawConfig>(Physics2DDebugDraw);
if (!config || !config.enabled) return;
const ppu = readPixelsPerUnit(app);
@@ -119,12 +119,12 @@ export function drawPhysicsDebug(
if (config.showColliders) {
// One projection for every shape: read the collider(s), take the offset+rotation
// centre, and stroke the world-space outline. Same geometry the per-type branches
- // produced, now shared with the editor gizmo (see ColliderShape).
- for (const { shape, isSensor, enabled } of readColliderShapes(app.world, entity)) {
+ // produced, now shared with the editor gizmo (see Collider2DShape).
+ for (const { shape, isSensor, enabled } of readCollider2DShapes(app.world, entity)) {
if (!enabled) continue; // no shape in the world → nothing to outline
const color = isSensor ? SENSOR_COLOR : bodyTypeColor(rb.bodyType);
const center = shapeCenter(shape, { x: wx, y: wy }, angle, ppu);
- const outline = colliderShapeOutline(shape, center, angle, ppu);
+ const outline = collider2DOutline(shape, center, angle, ppu);
for (const pl of outline.polylines) {
for (let i = 0; i + 1 < pl.length; i++) {
Draw.line(pl[i], pl[i + 1], color, DEBUG_LINE_THICKNESS);
@@ -143,7 +143,7 @@ export function drawPhysicsDebug(
}
if (config.showContacts && app.hasResource(physicsEventsRes)) {
- const events = app.getResource<PhysicsEventsData>(physicsEventsRes);
+ const events = app.getResource<Physics2DEventsData>(physicsEventsRes);
for (const collision of events.collisionEnters) {
Draw.circle(
{ x: collision.contactX, y: collision.contactY },
@@ -156,12 +156,12 @@ export function drawPhysicsDebug(
}
}
-export function setupPhysicsDebugDraw(
+export function setupPhysics2DDebugDraw(
app: App,
physicsApiRes: ResourceDef<VelocityProvider>,
- physicsEventsRes: ResourceDef<PhysicsEventsData>,
+ physicsEventsRes: ResourceDef<Physics2DEventsData>,
): void {
- app.insertResource(PhysicsDebugDraw, {
+ app.insertResource(Physics2DDebugDraw, {
enabled: false,
showColliders: true,
showVelocity: false,
@@ -169,6 +169,6 @@ export function setupPhysicsDebugDraw(
});
registerDrawCallback('physics-debug-draw', () => {
- drawPhysicsDebug(app, physicsApiRes, physicsEventsRes);
+ drawPhysics2DDebug(app, physicsApiRes, physicsEventsRes);
});
}
diff --git a/sdk/src/physics/PhysicsPlugin.ts b/sdk/src/physics/Physics2DPlugin.ts
similarity index 77%
rename from sdk/src/physics/PhysicsPlugin.ts
rename to sdk/src/physics/Physics2DPlugin.ts
index 7a0a109de..83236d683 100644
--- a/sdk/src/physics/PhysicsPlugin.ts
+++ b/sdk/src/physics/Physics2DPlugin.ts
@@ -1,11 +1,11 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
- * @file PhysicsPlugin.ts
- * @brief PhysicsAPI plugin — async wasm load + resource wiring
+ * @file Physics2DPlugin.ts
+ * @brief Physics2DAPI plugin — async wasm load + resource wiring
*
* Thin orchestration layer. Types live in `PhysicsTypes.ts`,
- * the PhysicsAPI API class in `PhysicsAPI.ts`, and the per-frame loop
+ * the Physics2DAPI API class in `Physics2DAPI.ts`, and the per-frame loop
* + entity-tracking state in `PhysicsSystem.ts`. This file just
* loads the wasm module, wires resources, and hands off to the
* system layer.
@@ -17,30 +17,30 @@ import {
type PhysicsWasmModule,
type PhysicsModuleFactory,
} from './PhysicsModuleLoader';
-import { setupPhysicsDebugDraw } from './PhysicsDebugDraw';
+import { setupPhysics2DDebugDraw } from './Physics2DDebugDraw';
import { PhysicsBridge } from './PhysicsBridge';
-import { PhysicsRuntime } from './PhysicsRuntime';
-import { PhysicsAPI, Physics } from './Physics';
-import { registerPhysicsSystem } from './PhysicsSystem';
-import { registerCharacterControllerSystem } from './CharacterController2D';
-import { registerPhysicsEventBridge } from './PhysicsEventBridge';
+import { Physics2DRuntime } from './Physics2DRuntime';
+import { Physics2DAPI, Physics2D } from './Physics2D';
+import { registerPhysics2DSystem } from './PhysicsSystem';
+import { registerCharacterController2DSystem } from './CharacterController2D';
+import { registerPhysics2DEventBridge } from './PhysicsEventBridge';
import {
- PhysicsEvents,
- type PhysicsPluginConfig,
- type ResolvedPhysicsConfig,
+ Physics2DEvents,
+ type Physics2DPluginConfig,
+ type ResolvedPhysics2DConfig,
} from './PhysicsTypes';
import { handleWasmError } from '../wasm/wasmError';
// Re-export the shapes consumers reach for via the plugin file so
-// existing `import from './physics/PhysicsPlugin'` sites keep working.
+// existing `import from './physics/Physics2DPlugin'` sites keep working.
export {
- PhysicsEvents,
- Physics,
- PhysicsAPI,
+ Physics2DEvents,
+ Physics2D,
+ Physics2DAPI,
};
export type {
- PhysicsPluginConfig,
- PhysicsEventsData,
+ Physics2DPluginConfig,
+ Physics2DEventsData,
CollisionEnterEvent,
CollisionHitEvent,
SensorEvent,
@@ -53,7 +53,7 @@ export type {
// Config defaults
// =============================================================================
-function resolveConfig(config: PhysicsPluginConfig): ResolvedPhysicsConfig {
+function resolveConfig(config: Physics2DPluginConfig): ResolvedPhysics2DConfig {
return {
gravity: config.gravity ?? { x: 0, y: -9.81 },
fixedTimestep: config.fixedTimestep ?? 1 / 30,
@@ -110,29 +110,29 @@ function assertModuleContract(module: PhysicsWasmModule): void {
);
}
-export class PhysicsPlugin implements Plugin {
+export class Physics2DPlugin implements Plugin {
name = 'physics';
- private config_: ResolvedPhysicsConfig;
+ private config_: ResolvedPhysics2DConfig;
private wasmUrl_: string;
private factory_?: PhysicsModuleFactory;
private bridge_ = new PhysicsBridge();
private module_: PhysicsWasmModule | null = null;
- constructor(wasmUrl: string, config: PhysicsPluginConfig = {}, factory?: PhysicsModuleFactory) {
+ constructor(wasmUrl: string, config: Physics2DPluginConfig = {}, factory?: PhysicsModuleFactory) {
this.wasmUrl_ = wasmUrl;
this.factory_ = factory;
this.config_ = resolveConfig(config);
}
build(app: App): void {
- app.insertResource(PhysicsEvents, {
+ app.insertResource(Physics2DEvents, {
collisionEnters: [],
collisionExits: [],
collisionHits: [],
sensorEnters: [],
sensorExits: [],
});
- app.insertResource(PhysicsRuntime, { module: null, initPromise: null });
+ app.insertResource(Physics2DRuntime, { module: null, initPromise: null });
// wasm loading → show "initializing", not a stuck "registered".
app.subsystems.transition('physics', 'initializing');
@@ -148,7 +148,7 @@ export class PhysicsPlugin implements Plugin {
// the terminal-abort guard and yields a guarded view in which
// every `_physics_*` call short-circuits after an abort. The
// guarded module has the same type, so every downstream call
- // site (PhysicsSystem closures, the PhysicsAPI API wrapper) gains
+ // site (PhysicsSystem closures, the Physics2DAPI API wrapper) gains
// abort safety without changing a single call.
assertModuleContract(loaded);
@@ -172,15 +172,15 @@ export class PhysicsPlugin implements Plugin {
this.config_.maxLinearSpeed,
);
- registerPhysicsSystem(app, module, this.config_);
+ registerPhysics2DSystem(app, module, this.config_);
- app.getResource(PhysicsRuntime).module = module;
- app.insertResource(Physics, PhysicsAPI._fromModule(module));
- registerCharacterControllerSystem(app);
+ app.getResource(Physics2DRuntime).module = module;
+ app.insertResource(Physics2D, Physics2DAPI._fromModule(module));
+ registerCharacterController2DSystem(app);
// Contacts also reach the entity event channel, so a trigger area
// can be wired by an authored EventBinding row like a button is.
- registerPhysicsEventBridge(app);
- setupPhysicsDebugDraw(app, Physics, PhysicsEvents);
+ registerPhysics2DEventBridge(app);
+ setupPhysics2DDebugDraw(app, Physics2D, Physics2DEvents);
app.setFixedTimestep(this.config_.fixedTimestep);
// Module loaded, world initialized, systems registered.
app.subsystems.transition('physics', 'ready');
@@ -189,9 +189,9 @@ export class PhysicsPlugin implements Plugin {
initPromise.catch((e) => {
app.subsystems.markError('physics', e instanceof Error ? e.message : String(e));
- handleWasmError(e, 'PhysicsPlugin.init');
+ handleWasmError(e, 'Physics2DPlugin.init');
});
- app.getResource(PhysicsRuntime).initPromise = initPromise;
+ app.getResource(Physics2DRuntime).initPromise = initPromise;
}
/**
@@ -206,8 +206,8 @@ export class PhysicsPlugin implements Plugin {
}
}
-export function physicsPlugin(
- wasmUrl: string, config: PhysicsPluginConfig = {}, factory?: PhysicsModuleFactory,
-): PhysicsPlugin {
- return new PhysicsPlugin(wasmUrl, config, factory);
+export function physics2dPlugin(
+ wasmUrl: string, config: Physics2DPluginConfig = {}, factory?: PhysicsModuleFactory,
+): Physics2DPlugin {
+ return new Physics2DPlugin(wasmUrl, config, factory);
}
diff --git a/sdk/src/physics/PhysicsRuntime.ts b/sdk/src/physics/Physics2DRuntime.ts
similarity index 77%
rename from sdk/src/physics/PhysicsRuntime.ts
rename to sdk/src/physics/Physics2DRuntime.ts
index d380ff134..49a57a42f 100644
--- a/sdk/src/physics/PhysicsRuntime.ts
+++ b/sdk/src/physics/Physics2DRuntime.ts
@@ -1,11 +1,11 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
- * @file PhysicsRuntime.ts
+ * @file Physics2DRuntime.ts
* @brief Resource holding the physics wasm module + its load promise
*
* Decoupling this from App as a resource (instead of dynamic
- * properties) lets PhysicsPlugin own the lifetime of the module
+ * properties) lets Physics2DPlugin own the lifetime of the module
* without mutating App, and lets other systems read readiness
* state in the same way they read any other resource.
*/
@@ -13,14 +13,14 @@
import { defineResource } from '../ecs/resource';
import type { PhysicsWasmModule } from './PhysicsModuleLoader';
-export interface PhysicsRuntimeData {
+export interface Physics2DRuntimeData {
/** Loaded physics wasm module, null until the plugin's init promise resolves. */
module: PhysicsWasmModule | null;
/** Promise that resolves once the module is loaded; null before plugin install. */
initPromise: Promise<void> | null;
}
-export const PhysicsRuntime = defineResource<PhysicsRuntimeData>(
+export const Physics2DRuntime = defineResource<Physics2DRuntimeData>(
{ module: null, initPromise: null },
- 'PhysicsRuntime',
+ 'Physics2DRuntime',
);
diff --git a/sdk/src/physics/PhysicsEventBridge.ts b/sdk/src/physics/PhysicsEventBridge.ts
index d3a601428..110c4ab64 100644
--- a/sdk/src/physics/PhysicsEventBridge.ts
+++ b/sdk/src/physics/PhysicsEventBridge.ts
@@ -4,7 +4,7 @@
* @file PhysicsEventBridge.ts
* @brief Contacts and sensor overlaps, republished on the entity event channel.
*
- * `PhysicsEvents` is a per-frame batch resource: excellent for a system that
+ * `Physics2DEvents` is a per-frame batch resource: excellent for a system that
* wants every contact this tick, useless for "when THIS entity is touched". The
* bridge turns each batch entry into an entity-scoped event on the shared queue
* — the same channel a button's `click` travels — which is what lets an authored
@@ -19,7 +19,7 @@ import { Schedule, defineSystem } from '../ecs/system';
import { Res } from '../ecs/resource';
import { playModeOnly } from '../ecs/env';
import { ensureEntityEvents } from '../ecs/entityEvents';
-import { PhysicsEvents, type PhysicsEventsData } from './PhysicsTypes';
+import { Physics2DEvents, type Physics2DEventsData } from './PhysicsTypes';
import type { Entity } from '../types';
/**
@@ -27,7 +27,7 @@ import type { Entity } from '../types';
* producer's — these constants exist so the editor's palette and game code spell
* them the same way (mirrors `UIEventType`).
*/
-export const PhysicsEventType = {
+export const Physics2DEventType = {
CollisionEnter: 'collision_enter',
CollisionExit: 'collision_exit',
CollisionHit: 'collision_hit',
@@ -35,10 +35,10 @@ export const PhysicsEventType = {
TriggerExit: 'trigger_exit',
} as const;
-export type PhysicsEventType = typeof PhysicsEventType[keyof typeof PhysicsEventType];
+export type Physics2DEventType = typeof Physics2DEventType[keyof typeof Physics2DEventType];
/** Payload carried by every bridged event: who else was involved. */
-export interface PhysicsContactEventData {
+export interface Physics2DContactEventData {
/** The other participant — the body touched, or the trigger/visitor. */
other: Entity;
/** True on the sensor's own `trigger_*` event (false on the visitor's). */
@@ -52,41 +52,41 @@ export interface PhysicsContactEventData {
* Update (after the fixed-step physics has filled the resource) and only in play
* mode — the edit realm never steps the world.
*/
-export function registerPhysicsEventBridge(app: App): void {
+export function registerPhysics2DEventBridge(app: App): void {
const events = ensureEntityEvents(app);
const world = app.world;
- const emitPair = (a: Entity, b: Entity, type: string, extra?: Partial<PhysicsContactEventData>): void => {
- if (world.valid(a)) events.emit<PhysicsContactEventData>(a, type, { other: b, ...extra });
- if (world.valid(b)) events.emit<PhysicsContactEventData>(b, type, { other: a, ...extra });
+ const emitPair = (a: Entity, b: Entity, type: string, extra?: Partial<Physics2DContactEventData>): void => {
+ if (world.valid(a)) events.emit<Physics2DContactEventData>(a, type, { other: b, ...extra });
+ if (world.valid(b)) events.emit<Physics2DContactEventData>(b, type, { other: a, ...extra });
};
app.addSystemToSchedule(
Schedule.Update,
- defineSystem([Res(PhysicsEvents)], (physics: PhysicsEventsData) => {
+ defineSystem([Res(Physics2DEvents)], (physics: Physics2DEventsData) => {
for (const c of physics.collisionEnters) {
- emitPair(c.entityA, c.entityB, PhysicsEventType.CollisionEnter);
+ emitPair(c.entityA, c.entityB, Physics2DEventType.CollisionEnter);
}
for (const c of physics.collisionExits) {
- emitPair(c.entityA, c.entityB, PhysicsEventType.CollisionExit);
+ emitPair(c.entityA, c.entityB, Physics2DEventType.CollisionExit);
}
for (const c of physics.collisionHits) {
- emitPair(c.entityA, c.entityB, PhysicsEventType.CollisionHit, { approachSpeed: c.approachSpeed });
+ emitPair(c.entityA, c.entityB, Physics2DEventType.CollisionHit, { approachSpeed: c.approachSpeed });
}
// A sensor pair is asymmetric, so each side is told which it is.
for (const s of physics.sensorEnters) {
if (world.valid(s.sensorEntity)) {
- events.emit<PhysicsContactEventData>(s.sensorEntity, PhysicsEventType.TriggerEnter, { other: s.visitorEntity, isSensor: true });
+ events.emit<Physics2DContactEventData>(s.sensorEntity, Physics2DEventType.TriggerEnter, { other: s.visitorEntity, isSensor: true });
}
if (world.valid(s.visitorEntity)) {
- events.emit<PhysicsContactEventData>(s.visitorEntity, PhysicsEventType.TriggerEnter, { other: s.sensorEntity, isSensor: false });
+ events.emit<Physics2DContactEventData>(s.visitorEntity, Physics2DEventType.TriggerEnter, { other: s.sensorEntity, isSensor: false });
}
}
for (const s of physics.sensorExits) {
if (world.valid(s.sensorEntity)) {
- events.emit<PhysicsContactEventData>(s.sensorEntity, PhysicsEventType.TriggerExit, { other: s.visitorEntity, isSensor: true });
+ events.emit<Physics2DContactEventData>(s.sensorEntity, Physics2DEventType.TriggerExit, { other: s.visitorEntity, isSensor: true });
}
if (world.valid(s.visitorEntity)) {
- events.emit<PhysicsContactEventData>(s.visitorEntity, PhysicsEventType.TriggerExit, { other: s.sensorEntity, isSensor: false });
+ events.emit<Physics2DContactEventData>(s.visitorEntity, Physics2DEventType.TriggerExit, { other: s.sensorEntity, isSensor: false });
}
}
}, { name: 'PhysicsEventBridgeSystem' }),
diff --git a/sdk/src/physics/PhysicsSystem.ts b/sdk/src/physics/PhysicsSystem.ts
index 2ac39eef3..7838f6b1d 100644
--- a/sdk/src/physics/PhysicsSystem.ts
+++ b/sdk/src/physics/PhysicsSystem.ts
@@ -5,8 +5,8 @@
* @brief Per-frame physics driver: entity tracking, shape/joint create,
* step, transform readback, event collection.
*
- * `registerPhysicsSystem` owns all closure state (tracked bodies, joint
- * cache, cached RigidBody2D props). `PhysicsPlugin.build()` calls it once
+ * `registerPhysics2DSystem` owns all closure state (tracked bodies, joint
+ * cache, cached RigidBody2D props). `Physics2DPlugin.build()` calls it once
* the wasm module finishes loading.
*/
@@ -18,7 +18,7 @@ import { Res, Time, type TimeData } from '../ecs/resource';
import { Schedule, defineSystem } from '../ecs/system';
import { playModeOnly } from '../ecs/env';
import type { PhysicsWasmModule } from './PhysicsModuleLoader';
-import { Physics } from './Physics';
+import { Physics2D } from './Physics2D';
import {
RigidBody2D, BoxCollider2D, CircleCollider2D, CapsuleCollider2D,
SegmentCollider2D, PolygonCollider2D, ChainCollider2D, OneWayPlatform2D,
@@ -31,11 +31,11 @@ import {
type MotorJoint2DData,
} from './PhysicsComponents';
import {
- PhysicsEvents,
+ Physics2DEvents,
COLLISION_EVENT_STRIDE,
HIT_EVENT_STRIDE,
quatToAngleZ,
- type ResolvedPhysicsConfig,
+ type ResolvedPhysics2DConfig,
type CollisionEnterEvent,
type CollisionHitEvent,
type SensorEvent,
@@ -366,7 +366,7 @@ const PHYSICS_BODY_BYTES = PHYSICS_BODY_STRIDE * 4;
* to the engine. With `alpha = 1` this reproduces a direct post-step sync.
* @internal exported for testing
*/
-export function applyPhysicsTransforms(
+export function applyPhysics2DTransforms(
app: App,
ppu: number,
parentedBodies: Set<Entity>,
@@ -521,7 +521,7 @@ interface EventAccum {
}
/**
- * Drain this fixed step's events into the per-frame accumulator. PhysicsAPI may step
+ * Drain this fixed step's events into the per-frame accumulator. Physics2DAPI may step
* several times per rendered frame; accumulating (rather than overwriting) keeps
* every collision — the interpolation system publishes + clears once per frame.
*/
@@ -677,10 +677,10 @@ export function jointPartnerGone(world: App['world'], entity: Entity, trackedEnt
* / tracked-joint / parented sets via the enclosing closure so the
* plugin doesn't need to thread them through.
*/
-export function registerPhysicsSystem(
+export function registerPhysics2DSystem(
app: App,
module: PhysicsWasmModule,
- config: ResolvedPhysicsConfig,
+ config: ResolvedPhysics2DConfig,
): void {
const trackedEntities = new Set<Entity>();
const trackedJoints = new Set<Entity>();
@@ -745,7 +745,7 @@ export function registerPhysicsSystem(
const invPpu = 1 / ppu;
// Keep the query API's default scale in sync with the live Canvas,
// so raycast/overlap that omit `ppu` aren't silently scaled to 100.
- if (app.hasResource(Physics)) app.getResource(Physics).setPixelsPerUnit(ppu);
+ if (app.hasResource(Physics2D)) app.getResource(Physics2D).setPixelsPerUnit(ppu);
// Steady-state fast path: skip the full entity reconcile unless
// something structural changed (spawn/despawn/add-remove component →
// structuralVersion) OR a physics component was edited (O(1) gate).
@@ -927,7 +927,7 @@ export function registerPhysicsSystem(
defineSystem(
[Res(Time)],
(time: TimeData) => {
- app.insertResource(PhysicsEvents, {
+ app.insertResource(Physics2DEvents, {
collisionEnters: events.collisionEnters,
collisionExits: events.collisionExits,
collisionHits: events.collisionHits,
@@ -942,7 +942,7 @@ export function registerPhysicsSystem(
events.sensorExits = [];
const ppu = readPixelsPerUnit(app);
- applyPhysicsTransforms(app, ppu, parentedBodies, module, time.fixedAlpha);
+ applyPhysics2DTransforms(app, ppu, parentedBodies, module, time.fixedAlpha);
},
{ name: 'PhysicsInterpolateSystem' }
),
diff --git a/sdk/src/physics/PhysicsTypes.ts b/sdk/src/physics/PhysicsTypes.ts
index 4650dfd5d..0c2fa6428 100644
--- a/sdk/src/physics/PhysicsTypes.ts
+++ b/sdk/src/physics/PhysicsTypes.ts
@@ -4,7 +4,7 @@
* @file PhysicsTypes.ts
* @brief Shared data shapes for the physics plugin
*
- * Plain-data types consumed by `PhysicsPlugin`, `Physics`, and `PhysicsSystem`.
+ * Plain-data types consumed by `Physics2DPlugin`, `Physics`, and `PhysicsSystem`.
* Kept dependency-free so all three files can import without cycles.
*/
@@ -15,7 +15,7 @@ import { defineResource } from '../ecs/resource';
// Plugin configuration
// =============================================================================
-export interface PhysicsPluginConfig {
+export interface Physics2DPluginConfig {
gravity?: Vec2;
fixedTimestep?: number;
subStepCount?: number;
@@ -34,9 +34,9 @@ export interface PhysicsPluginConfig {
}
/** Fully-populated plugin config after defaults are applied. */
-export type ResolvedPhysicsConfig =
- Required<Omit<PhysicsPluginConfig, 'collisionLayerMasks'>>
- & Pick<PhysicsPluginConfig, 'collisionLayerMasks'>;
+export type ResolvedPhysics2DConfig =
+ Required<Omit<Physics2DPluginConfig, 'collisionLayerMasks'>>
+ & Pick<Physics2DPluginConfig, 'collisionLayerMasks'>;
// =============================================================================
// Collision events
@@ -68,7 +68,7 @@ export interface CollisionHitEvent {
approachSpeed: number;
}
-export interface PhysicsEventsData {
+export interface Physics2DEventsData {
collisionEnters: CollisionEnterEvent[];
collisionExits: Array<{ entityA: Entity; entityB: Entity }>;
collisionHits: CollisionHitEvent[];
@@ -83,13 +83,13 @@ export interface PhysicsEventsData {
*
* @beta
*/
-export const PhysicsEvents = defineResource<PhysicsEventsData>({
+export const Physics2DEvents = defineResource<Physics2DEventsData>({
collisionEnters: [],
collisionExits: [],
collisionHits: [],
sensorEnters: [],
sensorExits: []
-}, 'PhysicsEvents');
+}, 'Physics2DEvents');
// =============================================================================
// Query result shapes
diff --git a/sdk/src/physics/index.ts b/sdk/src/physics/index.ts
index 1eb35213f..d9f26d064 100644
--- a/sdk/src/physics/index.ts
+++ b/sdk/src/physics/index.ts
@@ -6,34 +6,34 @@
*
* @example
* ```typescript
- * import { PhysicsPlugin } from 'esengine/physics';
- * app.addPlugin(new PhysicsPlugin('physics.js', { gravity: { x: 0, y: -9.81 } }));
+ * import { Physics2DPlugin } from 'esengine/physics';
+ * app.addPlugin(new Physics2DPlugin('physics.js', { gravity: { x: 0, y: -9.81 } }));
* ```
*/
// Contacts as entity events (the channel widgets emit into), so an authored
// EventBinding row can wire a trigger area with no code.
export {
- PhysicsEventType,
- registerPhysicsEventBridge,
- type PhysicsContactEventData,
+ Physics2DEventType,
+ registerPhysics2DEventBridge,
+ type Physics2DContactEventData,
} from './PhysicsEventBridge';
export {
- PhysicsPlugin,
- physicsPlugin,
- PhysicsEvents,
- PhysicsAPI,
- Physics,
- type PhysicsPluginConfig,
- type PhysicsEventsData,
+ Physics2DPlugin,
+ physics2dPlugin,
+ Physics2DEvents,
+ Physics2DAPI,
+ Physics2D,
+ type Physics2DPluginConfig,
+ type Physics2DEventsData,
type CollisionEnterEvent,
type CollisionHitEvent,
type SensorEvent,
type RaycastHit,
type ShapeCastHit,
type MassData,
-} from './PhysicsPlugin';
+} from './Physics2DPlugin';
export {
loadPhysicsModule,
@@ -74,27 +74,27 @@ export {
} from './PhysicsComponents';
export {
- PhysicsDebugDraw,
- setupPhysicsDebugDraw,
- drawPhysicsDebug,
- type PhysicsDebugDrawConfig,
-} from './PhysicsDebugDraw';
+ Physics2DDebugDraw,
+ setupPhysics2DDebugDraw,
+ drawPhysics2DDebug,
+ type Physics2DDebugDrawConfig,
+} from './Physics2DDebugDraw';
export {
- readColliderShapes,
+ readCollider2DShapes,
shapeOffset,
shapeCenter,
- colliderShapeOutline,
+ collider2DOutline,
CAPSULE_ARC_SEGMENTS,
- type ColliderShape,
- type ColliderInstance,
- type ColliderOutline,
-} from './ColliderShape';
+ type Collider2DShape,
+ type Collider2DInstance,
+ type Collider2DOutline,
+} from './ColliderShape2D';
export {
CharacterController2D,
moveAndSlide,
- registerCharacterControllerSystem,
+ registerCharacterController2DSystem,
type CharacterController2DData,
type MoveAndSlideParams,
type MoveAndSlideResult,
diff --git a/sdk/src/runtime/miniGameRuntime.ts b/sdk/src/runtime/miniGameRuntime.ts
index 43ca4201e..0eeecf33a 100644
--- a/sdk/src/runtime/miniGameRuntime.ts
+++ b/sdk/src/runtime/miniGameRuntime.ts
@@ -27,7 +27,7 @@ import {
registerPackagedSideModules,
} from './packagedRuntime';
import { createMiniGameSideModuleHost, type MiniGameSideModuleFactories } from '../sideModules';
-import type { PhysicsPluginConfig } from '../physics/PhysicsTypes';
+import type { Physics2DPluginConfig } from '../physics/PhysicsTypes';
import type { SceneData } from '../scene/scene';
import { log } from '../util/logger';
@@ -86,7 +86,7 @@ export interface MiniGameRuntimeConfig {
/** The physics world the project declared: gravity, solver, collision matrix.
* The FULL config, not a three-field subset: a collision matrix that reached
* Play and not a shipped build is a game that only collides in rehearsal. */
- physicsConfig?: PhysicsPluginConfig;
+ physicsConfig?: Physics2DPluginConfig;
/** Project-declared UI theme; 'light' re-skins ThemeStyle-tagged widgets at boot. */
uiTheme?: 'dark' | 'light';
/** Project-declared theme token overrides (partial re-skin over the base). */
diff --git a/sdk/src/runtime/packagedRuntime.ts b/sdk/src/runtime/packagedRuntime.ts
index e0be8ba38..b0627f018 100644
--- a/sdk/src/runtime/packagedRuntime.ts
+++ b/sdk/src/runtime/packagedRuntime.ts
@@ -21,7 +21,7 @@ import { FileSystemBackend, type Backend } from '../asset/Backend';
import type { ParsedTextureImportSettings } from '../asset/textureImportSettings';
import { Audio } from '../audio/Audio';
import type { AudioProjectConfig } from '../audio/AudioProjectConfig';
-import type { PhysicsPluginConfig } from '../physics/PhysicsTypes';
+import type { Physics2DPluginConfig } from '../physics/PhysicsTypes';
import { parseThemeOverrides, type ThemeOverrides } from '../ui/theme/tokens';
import { VideoPlayer } from '../video/VideoAPI';
import type { App } from '../app/app';
@@ -68,7 +68,7 @@ export interface PackagedGameConfig {
physicsEnabled?: boolean;
/** The physics world the project declared: gravity, solver, collision matrix.
* Absent ⇒ the engine's own defaults. */
- physicsConfig?: PhysicsPluginConfig;
+ physicsConfig?: Physics2DPluginConfig;
/** Project mixer state: bus volumes, custom buses, effects, duck rules.
* Absent ⇒ the default mix. */
audioConfig?: AudioProjectConfig;
@@ -169,7 +169,7 @@ export function packagedRuntimeInit(
| 'achievements' | 'steamAppId' | 'screenFit'>,
): {
physicsEnabled?: boolean;
- physicsConfig?: PhysicsPluginConfig;
+ physicsConfig?: Physics2DPluginConfig;
audioConfig?: AudioProjectConfig;
uiTheme?: 'light';
uiThemeOverrides?: ThemeOverrides;
diff --git a/sdk/src/runtime/playRealmRuntime.ts b/sdk/src/runtime/playRealmRuntime.ts
index 45369050b..6ea91726b 100644
--- a/sdk/src/runtime/playRealmRuntime.ts
+++ b/sdk/src/runtime/playRealmRuntime.ts
@@ -26,7 +26,7 @@ import { HttpBackend } from '../asset/Backend';
import { Catalog, type CatalogData } from '../asset/Catalog';
import { ManifestModel, type AddressableManifest } from '../asset/AddressableManifest';
import type { SceneData } from '../scene/scene';
-import type { PhysicsPluginConfig } from '../physics/PhysicsPlugin';
+import type { Physics2DPluginConfig } from '../physics/Physics2DPlugin';
import type { AudioProjectConfig } from '../audio/AudioProjectConfig';
import { fetchDecodePixels } from '../asset/imageDecode';
import { applyAssetRefResolvers } from './packagedRuntime';
@@ -78,7 +78,7 @@ export interface PlayRealmRuntimeConfig {
physicsEnabled?: boolean;
/** Project-declared physics world config (gravity, solver tuning, collision-layer
* masks, sleep/continuous) from the editor's Project Settings. */
- physicsConfig?: PhysicsPluginConfig;
+ physicsConfig?: Physics2DPluginConfig;
/** Project-declared UI theme; 'light' re-skins ThemeStyle-tagged widgets at boot. */
uiTheme?: 'dark' | 'light';
/** Project-declared theme token overrides (partial re-skin over the base). */
diff --git a/sdk/src/runtime/playableRuntime.ts b/sdk/src/runtime/playableRuntime.ts
index 2545c8c53..ed16adf81 100644
--- a/sdk/src/runtime/playableRuntime.ts
+++ b/sdk/src/runtime/playableRuntime.ts
@@ -18,7 +18,7 @@ import type { ThemeOverrides } from '../ui';
import type { RuntimeAssetSource } from './runtimeAssets';
import { EmbeddedBackend } from '../asset/Backend';
import { ManifestModel, type AddressableManifest } from '../asset/AddressableManifest';
-import type { PhysicsPluginConfig } from '../physics/PhysicsTypes';
+import type { Physics2DPluginConfig } from '../physics/PhysicsTypes';
import type { SceneData } from '../scene/scene';
import { Audio } from '../audio/Audio';
import { VideoPlayer } from '../video/VideoAPI';
@@ -44,7 +44,7 @@ export interface PlayableRuntimeConfig {
/** The physics world the project declared: gravity, solver, collision matrix.
* The FULL config, not a three-field subset: a collision matrix that reached
* Play and not a shipped build is a game that only collides in rehearsal. */
- physicsConfig?: PhysicsPluginConfig;
+ physicsConfig?: Physics2DPluginConfig;
/** Project-declared UI theme; 'light' re-skins ThemeStyle-tagged widgets at boot. */
uiTheme?: 'dark' | 'light';
/** Project-declared theme token overrides (partial re-skin over the base). */
diff --git a/sdk/src/runtime/runtimeLoader.ts b/sdk/src/runtime/runtimeLoader.ts
index e4db04c5d..f70597f73 100644
--- a/sdk/src/runtime/runtimeLoader.ts
+++ b/sdk/src/runtime/runtimeLoader.ts
@@ -15,7 +15,7 @@ import type { ESEngineModule } from '../wasm';
import type { SpineWasmModule } from '../spine/SpineModuleLoader';
import { SpineManager } from '../spine/SpineManager';
import type { PhysicsWasmModule } from '../physics/PhysicsModuleLoader';
-import { PhysicsPlugin, type PhysicsPluginConfig } from '../physics/PhysicsPlugin';
+import { Physics2DPlugin, type Physics2DPluginConfig } from '../physics/Physics2DPlugin';
import type { Physics3DWasmModule } from '../physics3d/Physics3DModule';
import { Physics3DPlugin } from '../physics3d/Physics3DPlugin';
import { applyAudioProjectConfig, type AudioProjectConfig } from '../audio/AudioProjectConfig';
@@ -191,7 +191,7 @@ export interface LoadRuntimeSceneOptions {
physicsModule?: PhysicsWasmModule | null;
/** Project-declared physics world config (gravity, solver tuning, collision-layer
* masks, sleep/continuous toggles) — threaded from the editor's Project Settings. */
- physicsConfig?: PhysicsPluginConfig;
+ physicsConfig?: Physics2DPluginConfig;
/** Project-declared physics enable (`.uproject` features analog) — installs
* physics even for runtime-spawned bodies the static scene doesn't show.
* OR-combined with a content scan. */
@@ -377,9 +377,9 @@ export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promis
}
if (!physicsModule) {
log.warn('physics', `wanted (declared=${!!physicsEnabled}) but no module loaded — this realm has no side-module host or physics.wasm failed to load`);
- } else if (!app.getPlugin(PhysicsPlugin)) {
+ } else if (!app.getPlugin(Physics2DPlugin)) {
const gravity = physicsConfig?.gravity ?? { ...DEFAULT_GRAVITY };
- const config: PhysicsPluginConfig = {
+ const config: Physics2DPluginConfig = {
gravity,
fixedTimestep: physicsConfig?.fixedTimestep ?? DEFAULT_FIXED_TIMESTEP,
subStepCount: physicsConfig?.subStepCount ?? 4,
@@ -393,7 +393,7 @@ export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promis
if (physicsConfig?.enableSleep !== undefined) config.enableSleep = physicsConfig.enableSleep;
if (physicsConfig?.enableContinuous !== undefined) config.enableContinuous = physicsConfig.enableContinuous;
const mod = physicsModule;
- app.addPlugin(new PhysicsPlugin('', config, () => Promise.resolve(mod)));
+ app.addPlugin(new Physics2DPlugin('', config, () => Promise.resolve(mod)));
log.info('physics', `installed (gravity ${gravity.x}, ${gravity.y})`);
}
}
@@ -548,7 +548,7 @@ export interface RuntimeInitConfig {
physicsModule?: PhysicsWasmModule | null;
/** Project-declared physics world config (gravity, solver tuning, collision-layer
* masks, sleep/continuous toggles) — threaded from the editor's Project Settings. */
- physicsConfig?: PhysicsPluginConfig;
+ physicsConfig?: Physics2DPluginConfig;
/** Project-declared physics enable; see {@link LoadRuntimeSceneOptions.physicsEnabled}. */
physicsEnabled?: boolean;
/** Project-declared mixer state (bus volumes / custom buses / effects / duck
diff --git a/sdk/src/tilemap/tileCollisionOutline.ts b/sdk/src/tilemap/tileCollisionOutline.ts
index 523e33491..b94b69232 100644
--- a/sdk/src/tilemap/tileCollisionOutline.ts
+++ b/sdk/src/tilemap/tileCollisionOutline.ts
@@ -11,7 +11,7 @@
* same {@link mergeCollisionTiles} the native collider path uses, and richer shapes go
* through the same {@link tileColliderShape} + one-way normal reorientation that
* {@link generateChunkTileShapes} spawns from — so the overlay is what you get out of
- * Play. Geometry is world PIXELS (`colliderShapeOutline` at ppu = 1); the caller
+ * Play. Geometry is world PIXELS (`collider2DOutline` at ppu = 1); the caller
* projects it to the screen. No physics units here — the overlay is a picture, not a body.
*/
import type { Vec2 } from '../types';
@@ -20,8 +20,8 @@ import { CHUNK_SIZE } from './chunkCodec';
import { tileIdOf, tileFlagsOf } from './tileBits';
import { mergeCollisionTiles } from './collisionMerge';
import { tileColliderShape, oneWayNormalWorld } from './tiledLoader';
-import { colliderShapeOutline, shapeCenter } from '../physics/ColliderShape';
-import type { ColliderShape } from '../physics/ColliderShape';
+import { collider2DOutline, shapeCenter } from '../physics/ColliderShape2D';
+import type { Collider2DShape } from '../physics/ColliderShape2D';
import type { TilesetModel } from './tilesetResolve';
/**
@@ -40,9 +40,9 @@ export interface TileCollisionPiece {
/** World outline of a pixel-space collider shape at `worldCenter` (no rotation — tiles
* carry flips, not continuous angles, and flips are already baked into the shape). */
-function outlineAt(shape: ColliderShape, worldCenter: Vec2): { polylines: Vec2[][]; circles: { c: Vec2; r: number }[] } {
+function outlineAt(shape: Collider2DShape, worldCenter: Vec2): { polylines: Vec2[][]; circles: { c: Vec2; r: number }[] } {
const center = shapeCenter(shape, worldCenter, 0, 1);
- return colliderShapeOutline(shape, center, 0, 1);
+ return collider2DOutline(shape, center, 0, 1);
}
/**
@@ -80,7 +80,7 @@ export function tileCollisionOutlines(
const y1 = y0 + rect.height - 1;
const cx = originX + ((x0 + x1 + 1) / 2) * tileW;
const cy = originY - ((y0 + y1 + 1) / 2) * tileH;
- const shape: ColliderShape = {
+ const shape: Collider2DShape = {
kind: 'box',
halfExtents: { x: rect.width * tileW * 0.5, y: rect.height * tileH * 0.5 },
offset: { x: 0, y: 0 },
diff --git a/sdk/src/tilemap/tiledLoader.ts b/sdk/src/tilemap/tiledLoader.ts
index 875f20ae6..234bb344c 100644
--- a/sdk/src/tilemap/tiledLoader.ts
+++ b/sdk/src/tilemap/tiledLoader.ts
@@ -38,7 +38,7 @@ function uploadTiledLayerTiles(entity: Entity, layer: TiledLayerData): void {
}
}
import { RigidBody2D, BoxCollider2D, CircleCollider2D, PolygonCollider2D, ChainCollider2D, OneWayPlatform2D, BodyType } from '../physics/PhysicsComponents';
-import type { ColliderShape } from '../physics/ColliderShape';
+import type { Collider2DShape } from '../physics/ColliderShape2D';
import type { ResolvedTileCollision } from './tilesetResolve';
import { mergeCollisionTiles } from './collisionMerge';
import { CHUNK_SIZE } from './chunkCodec';
@@ -981,11 +981,11 @@ export function polygonLocalVerts(
}
/**
- * The pixel-space {@link ColliderShape} for a resolved tile collision, the cell's flip
+ * The pixel-space {@link Collider2DShape} for a resolved tile collision, the cell's flip
* flags applied (origin = cell center, y up). The SINGLE tile→geometry definition shared
* by the runtime spawn ({@link generateChunkTileShapes}, which divides by ppu into a
* collider component) and the editor's tile-collision overlay (which feeds it to
- * `colliderShapeOutline`). A box is flip-symmetric so its geometry ignores the flags; a
+ * `collider2DOutline`). A box is flip-symmetric so its geometry ignores the flags; a
* polygon and a circle's centre go through {@link polygonLocalVerts}, matching the render.
*/
export function tileColliderShape(
@@ -995,7 +995,7 @@ export function tileColliderShape(
flipH: boolean,
flipV: boolean,
flipD: boolean,
-): ColliderShape {
+): Collider2DShape {
const s = rc.shape;
if (s.type === 'polygon') {
return { kind: 'polygon', vertices: polygonLocalVerts(s.points, tileW, tileH, flipH, flipV, flipD) };
diff --git a/sdk/tests/collider-shape.test.ts b/sdk/tests/collider-shape.test.ts
index 0ecbde7c3..1a7bb8085 100644
--- a/sdk/tests/collider-shape.test.ts
+++ b/sdk/tests/collider-shape.test.ts
@@ -2,14 +2,14 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* Golden geometry for the shared collider-shape projection. The outlines must match the
- * pre-refactor PhysicsDebugDraw math exactly (this is the Phase-0 parity proof) so both
+ * pre-refactor Physics2DDebugDraw math exactly (this is the Phase-0 parity proof) so both
* the runtime debug draw and the editor gizmo can render from one source.
*/
import { describe, it, expect } from 'vitest';
import {
- shapeCenter, colliderShapeOutline, CAPSULE_ARC_SEGMENTS,
- type ColliderShape,
-} from '../src/physics/ColliderShape';
+ shapeCenter, collider2DOutline, CAPSULE_ARC_SEGMENTS,
+ type Collider2DShape,
+} from '../src/physics/ColliderShape2D';
const near = (a: { x: number; y: number }, x: number, y: number) => {
expect(a.x).toBeCloseTo(x, 6);
@@ -18,23 +18,23 @@ const near = (a: { x: number; y: number }, x: number, y: number) => {
describe('shapeCenter', () => {
it('adds the collider offset (metres × ppu), unrotated', () => {
- const box: ColliderShape = { kind: 'box', halfExtents: { x: 0.5, y: 0.5 }, offset: { x: 1, y: 0 } };
+ const box: Collider2DShape = { kind: 'box', halfExtents: { x: 0.5, y: 0.5 }, offset: { x: 1, y: 0 } };
near(shapeCenter(box, { x: 10, y: 20 }, 0, 100), 110, 20);
});
it('rotates the offset by the entity angle', () => {
- const box: ColliderShape = { kind: 'box', halfExtents: { x: 0.5, y: 0.5 }, offset: { x: 1, y: 0 } };
+ const box: Collider2DShape = { kind: 'box', halfExtents: { x: 0.5, y: 0.5 }, offset: { x: 1, y: 0 } };
near(shapeCenter(box, { x: 10, y: 20 }, Math.PI / 2, 100), 10, 120); // (100,0) rotated 90° → (0,100)
});
it('is the entity position for offsetless shapes (segment/polygon/chain)', () => {
- const seg: ColliderShape = { kind: 'segment', point1: { x: -0.5, y: 0 }, point2: { x: 0.5, y: 0 } };
+ const seg: Collider2DShape = { kind: 'segment', point1: { x: -0.5, y: 0 }, point2: { x: 0.5, y: 0 } };
near(shapeCenter(seg, { x: 7, y: 9 }, 1.234, 100), 7, 9);
});
});
-describe('colliderShapeOutline', () => {
+describe('collider2DOutline', () => {
it('box → a closed 4-corner loop, ppu-scaled', () => {
- const box: ColliderShape = { kind: 'box', halfExtents: { x: 0.5, y: 0.5 }, offset: { x: 0, y: 0 } };
- const o = colliderShapeOutline(box, { x: 0, y: 0 }, 0, 100);
+ const box: Collider2DShape = { kind: 'box', halfExtents: { x: 0.5, y: 0.5 }, offset: { x: 0, y: 0 } };
+ const o = collider2DOutline(box, { x: 0, y: 0 }, 0, 100);
expect(o.circles).toEqual([]);
expect(o.polylines).toHaveLength(1);
const p = o.polylines[0];
@@ -45,8 +45,8 @@ describe('colliderShapeOutline', () => {
it('box corners match the legacy drawRotatedBox math under rotation', () => {
const hx = 40, hy = 20, angle = 0.7, cx = 12, cy = -3;
- const box: ColliderShape = { kind: 'box', halfExtents: { x: hx / 100, y: hy / 100 }, offset: { x: 0, y: 0 } };
- const p = colliderShapeOutline(box, { x: cx, y: cy }, angle, 100).polylines[0];
+ const box: Collider2DShape = { kind: 'box', halfExtents: { x: hx / 100, y: hy / 100 }, offset: { x: 0, y: 0 } };
+ const p = collider2DOutline(box, { x: cx, y: cy }, angle, 100).polylines[0];
// Reference: the exact transform the old drawRotatedBox used.
const cos = Math.cos(angle), sin = Math.sin(angle);
const corners = [[-hx, -hy], [hx, -hy], [hx, hy], [-hx, hy]] as const;
@@ -54,8 +54,8 @@ describe('colliderShapeOutline', () => {
});
it('circle → a single {c,r}, no polylines', () => {
- const c: ColliderShape = { kind: 'circle', radius: 0.5, offset: { x: 0, y: 0 } };
- const o = colliderShapeOutline(c, { x: 5, y: 5 }, 0, 100);
+ const c: Collider2DShape = { kind: 'circle', radius: 0.5, offset: { x: 0, y: 0 } };
+ const o = collider2DOutline(c, { x: 5, y: 5 }, 0, 100);
expect(o.polylines).toEqual([]);
expect(o.circles).toHaveLength(1);
near(o.circles[0].c, 5, 5);
@@ -63,8 +63,8 @@ describe('colliderShapeOutline', () => {
});
it('capsule → one closed loop with the same segment count the legacy draw emitted', () => {
- const cap: ColliderShape = { kind: 'capsule', radius: 0.25, halfHeight: 0.5, offset: { x: 0, y: 0 } };
- const o = colliderShapeOutline(cap, { x: 0, y: 0 }, 0, 100);
+ const cap: Collider2DShape = { kind: 'capsule', radius: 0.25, halfHeight: 0.5, offset: { x: 0, y: 0 } };
+ const o = collider2DOutline(cap, { x: 0, y: 0 }, 0, 100);
expect(o.circles).toEqual([]);
// legacy: 2 side lines + 2 arcs (16 segs each) = 2 + 32 = 34 segments = 35 points.
const pts = o.polylines[0];
@@ -76,30 +76,30 @@ describe('colliderShapeOutline', () => {
});
it('segment → one open two-point polyline', () => {
- const seg: ColliderShape = { kind: 'segment', point1: { x: -0.5, y: 0 }, point2: { x: 0.5, y: 0 } };
- const o = colliderShapeOutline(seg, { x: 0, y: 0 }, 0, 100);
+ const seg: Collider2DShape = { kind: 'segment', point1: { x: -0.5, y: 0 }, point2: { x: 0.5, y: 0 } };
+ const o = collider2DOutline(seg, { x: 0, y: 0 }, 0, 100);
expect(o.polylines).toHaveLength(1);
expect(o.polylines[0]).toHaveLength(2);
near(o.polylines[0][0], -50, 0); near(o.polylines[0][1], 50, 0);
});
it('polygon → a closed loop of n+1 points', () => {
- const poly: ColliderShape = { kind: 'polygon', vertices: [{ x: 0, y: 0 }, { x: 1, y: 0 }, { x: 0, y: 1 }] };
- const p = colliderShapeOutline(poly, { x: 0, y: 0 }, 0, 100).polylines[0];
+ const poly: Collider2DShape = { kind: 'polygon', vertices: [{ x: 0, y: 0 }, { x: 1, y: 0 }, { x: 0, y: 1 }] };
+ const p = collider2DOutline(poly, { x: 0, y: 0 }, 0, 100).polylines[0];
expect(p).toHaveLength(4);
near(p[0], 0, 0); near(p[1], 100, 0); near(p[2], 0, 100); near(p[3], 0, 0);
});
it('chain → open by default, closed when isLoop', () => {
const pts = [{ x: 0, y: 0 }, { x: 1, y: 0 }, { x: 1, y: 1 }];
- const open = colliderShapeOutline({ kind: 'chain', points: pts, isLoop: false }, { x: 0, y: 0 }, 0, 100);
+ const open = collider2DOutline({ kind: 'chain', points: pts, isLoop: false }, { x: 0, y: 0 }, 0, 100);
expect(open.polylines[0]).toHaveLength(3); // 2 segments
- const loop = colliderShapeOutline({ kind: 'chain', points: pts, isLoop: true }, { x: 0, y: 0 }, 0, 100);
+ const loop = collider2DOutline({ kind: 'chain', points: pts, isLoop: true }, { x: 0, y: 0 }, 0, 100);
expect(loop.polylines[0]).toHaveLength(4); // 3 segments (closed)
});
it('degenerate chain (<2 points) draws nothing', () => {
- const o = colliderShapeOutline({ kind: 'chain', points: [{ x: 0, y: 0 }], isLoop: false }, { x: 0, y: 0 }, 0, 100);
+ const o = collider2DOutline({ kind: 'chain', points: [{ x: 0, y: 0 }], isLoop: false }, { x: 0, y: 0 }, 0, 100);
expect(o.polylines).toEqual([]);
});
});
diff --git a/sdk/tests/colliderEnabled.test.ts b/sdk/tests/colliderEnabled.test.ts
index 21d75e0ea..4473f723b 100644
--- a/sdk/tests/colliderEnabled.test.ts
+++ b/sdk/tests/colliderEnabled.test.ts
@@ -16,7 +16,7 @@ import {
SegmentCollider2D, PolygonCollider2D, ChainCollider2D,
} from '../src/physics/PhysicsComponents';
import { addShapeForEntity, collidersChangedSince } from '../src/physics/PhysicsSystem';
-import { readColliderShapes } from '../src/physics/ColliderShape';
+import { readCollider2DShapes } from '../src/physics/ColliderShape2D';
import type { PhysicsWasmModule } from '../src/physics/PhysicsModuleLoader';
function testWorld(): World {
@@ -103,14 +103,14 @@ describe('the rest of the engine agrees with the shape that is there', () => {
const e = world.spawn();
world.insert(e, BoxCollider2D, { enabled: false } as never);
world.insert(e, CircleCollider2D, {} as never);
- const [box, circle] = readColliderShapes(world, e);
+ const [box, circle] = readCollider2DShapes(world, e);
expect(box.enabled).toBe(false);
expect(circle.enabled).toBe(true);
});
it('marks the collider changed when the flag flips, which is what rebuilds the shapes', () => {
const world = testWorld();
- world.enableChangeTracking(BoxCollider2D); // registerPhysicsSystem does this
+ world.enableChangeTracking(BoxCollider2D); // registerPhysics2DSystem does this
const e = world.spawn();
world.insert(e, BoxCollider2D, {} as never);
const settled = world.getWorldTick();
diff --git a/sdk/tests/perception-los.test.ts b/sdk/tests/perception-los.test.ts
index 616b87266..0b51d3ccb 100644
--- a/sdk/tests/perception-los.test.ts
+++ b/sdk/tests/perception-los.test.ts
@@ -12,7 +12,7 @@
*/
import { describe, it, expect, vi } from 'vitest';
import { makeLosCheck, makeLosCheck3D } from '../src/ai/perception/PerceptionPlugin';
-import type { PhysicsAPI, RaycastHit } from '../src/physics';
+import type { Physics2DAPI, RaycastHit } from '../src/physics';
import type { Physics3DQueries, Cast3DHit } from '../src/physics3d/Physics3DQueries';
import type { Entity, Vec3 } from '../src/types';
@@ -28,8 +28,8 @@ const hit = (entity: Entity, fraction: number): RaycastHit => ({
entity, fraction, point: { x: 0, y: 0 }, normal: { x: 0, y: 1 },
});
-const physicsReturning = (hits: RaycastHit[]): PhysicsAPI =>
- ({ raycast: () => hits }) as unknown as PhysicsAPI;
+const physicsReturning = (hits: RaycastHit[]): Physics2DAPI =>
+ ({ raycast: () => hits }) as unknown as Physics2DAPI;
describe('makeLosCheck', () => {
it('is not blocked by the target it is looking at', () => {
diff --git a/sdk/tests/physics-event-bridge.test.ts b/sdk/tests/physics-event-bridge.test.ts
index 6f2c1e116..6ebcd5465 100644
--- a/sdk/tests/physics-event-bridge.test.ts
+++ b/sdk/tests/physics-event-bridge.test.ts
@@ -8,18 +8,18 @@
*/
import { describe, expect, it, vi } from 'vitest';
import { EntityEventQueue, EntityEvents } from '../src/ecs/entityEvents';
-import { PhysicsEventType, registerPhysicsEventBridge, type PhysicsContactEventData } from '../src/physics/PhysicsEventBridge';
-import { PhysicsEvents, type PhysicsEventsData } from '../src/physics/PhysicsTypes';
+import { Physics2DEventType, registerPhysics2DEventBridge, type Physics2DContactEventData } from '../src/physics/PhysicsEventBridge';
+import { Physics2DEvents, type Physics2DEventsData } from '../src/physics/PhysicsTypes';
import type { Entity } from '../src/types';
-const EMPTY: PhysicsEventsData = {
+const EMPTY: Physics2DEventsData = {
collisionEnters: [], collisionExits: [], collisionHits: [], sensorEnters: [], sensorExits: [],
};
/** A fake App exposing only what the bridge touches, plus a manual tick. */
-function makeApp(batch: Partial<PhysicsEventsData>) {
+function makeApp(batch: Partial<Physics2DEventsData>) {
const queue = new EntityEventQueue();
- const resources = new Map<unknown, unknown>([[PhysicsEvents, { ...EMPTY, ...batch }]]);
+ const resources = new Map<unknown, unknown>([[Physics2DEvents, { ...EMPTY, ...batch }]]);
let system: (() => void) | null = null;
const app = {
world: {
@@ -30,12 +30,12 @@ function makeApp(batch: Partial<PhysicsEventsData>) {
getResource: (def: unknown) => resources.get(def),
insertResource: (def: unknown, v: unknown) => { resources.set(def, v); },
addSystemToSchedule: (_s: unknown, def: { _fn: (...args: unknown[]) => void }) => {
- // The bridge's only system param is Res(PhysicsEvents); feed it directly
+ // The bridge's only system param is Res(Physics2DEvents); feed it directly
// rather than standing up a scheduler.
- system = () => def._fn(resources.get(PhysicsEvents));
+ system = () => def._fn(resources.get(Physics2DEvents));
},
};
- registerPhysicsEventBridge(app as never);
+ registerPhysics2DEventBridge(app as never);
return { queue: resources.get(EntityEvents) as EntityEventQueue, tick: () => system?.(), fallback: queue };
}
@@ -44,7 +44,7 @@ function record(queue: EntityEventQueue, types: string[]) {
const seen: Array<{ type: string; entity: Entity; other: Entity; isSensor?: boolean }> = [];
for (const type of types) {
queue.on(type, (e) => {
- const data = e.data as PhysicsContactEventData;
+ const data = e.data as Physics2DContactEventData;
seen.push({ type: e.type, entity: e.currentTarget, other: data.other, isSensor: data.isSensor });
});
}
@@ -57,7 +57,7 @@ const B = 2 as Entity;
describe('physics → entity events', () => {
it('emits collision_enter on BOTH bodies, each told about the other', () => {
const app = makeApp({ collisionEnters: [{ entityA: A, entityB: B, pointX: 0, pointY: 0, normalX: 0, normalY: 1 } as never] });
- const seen = record(app.queue, [PhysicsEventType.CollisionEnter]);
+ const seen = record(app.queue, [Physics2DEventType.CollisionEnter]);
app.tick();
@@ -69,7 +69,7 @@ describe('physics → entity events', () => {
it('a sensor pair says which side is the trigger', () => {
const app = makeApp({ sensorEnters: [{ sensorEntity: A, visitorEntity: B }] });
- const seen = record(app.queue, [PhysicsEventType.TriggerEnter]);
+ const seen = record(app.queue, [Physics2DEventType.TriggerEnter]);
app.tick();
@@ -84,8 +84,8 @@ describe('physics → entity events', () => {
collisionHits: [{ entityA: A, entityB: B, pointX: 0, pointY: 0, normalX: 0, normalY: 1, approachSpeed: 7.5 }],
});
const speeds: number[] = [];
- app.queue.on(PhysicsEventType.CollisionHit, (e) => {
- speeds.push((e.data as PhysicsContactEventData).approachSpeed!);
+ app.queue.on(Physics2DEventType.CollisionHit, (e) => {
+ speeds.push((e.data as Physics2DContactEventData).approachSpeed!);
});
app.tick();
@@ -96,7 +96,7 @@ describe('physics → entity events', () => {
it('an empty frame emits nothing', () => {
const app = makeApp({});
const spy = vi.fn();
- for (const t of Object.values(PhysicsEventType)) app.queue.on(t, spy);
+ for (const t of Object.values(Physics2DEventType)) app.queue.on(t, spy);
app.tick();
diff --git a/sdk/tests/physics-module-contract.test.ts b/sdk/tests/physics-module-contract.test.ts
index 5d2cedd90..f0c98e13b 100644
--- a/sdk/tests/physics-module-contract.test.ts
+++ b/sdk/tests/physics-module-contract.test.ts
@@ -9,7 +9,7 @@
* of the session — for anyone who put a RigidBody2D in a scene and pressed Play.
*/
import { describe, it, expect, vi } from 'vitest';
-import { PhysicsPlugin } from '../src/physics/PhysicsPlugin';
+import { Physics2DPlugin } from '../src/physics/Physics2DPlugin';
import type { App } from '../src/app/app';
/** Everything the plugin touches before it would reach the module. */
@@ -47,7 +47,7 @@ describe('the physics plugin against a stale wasm', () => {
it('refuses a module missing the frame loop it will call, and names what is missing', async () => {
const stale = moduleWith(EVERY_EXPORT.filter((n) => !n.includes('Interpolated') && n !== '_physics_capturePoses'));
const app = fakeApp();
- new PhysicsPlugin('', {}, async () => stale as never).build(app);
+ new Physics2DPlugin('', {}, async () => stale as never).build(app);
await settle();
expect(app.errors).toHaveLength(1);
@@ -61,7 +61,7 @@ describe('the physics plugin against a stale wasm', () => {
it('lets a module that answers to the whole contract through', async () => {
const good = moduleWith(EVERY_EXPORT);
const app = fakeApp();
- new PhysicsPlugin('', {}, async () => good as never).build(app);
+ new Physics2DPlugin('', {}, async () => good as never).build(app);
await settle();
expect(app.errors.filter((e) => e.includes('out of date'))).toHaveLength(0);
diff --git a/sdk/tests/physics-pixels-per-unit.test.ts b/sdk/tests/physics-pixels-per-unit.test.ts
index 3caec2808..f0fb18364 100644
--- a/sdk/tests/physics-pixels-per-unit.test.ts
+++ b/sdk/tests/physics-pixels-per-unit.test.ts
@@ -1,7 +1,7 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
- * @file A PhysicsAPI answers with a usable pixels-per-unit before anyone pushes one.
+ * @file A Physics2DAPI answers with a usable pixels-per-unit before anyone pushes one.
*
* `_fromModule` builds the instance with `Object.create`, which runs no field
* initializer. The default lived in one, so the published `Physics` resource
@@ -10,26 +10,26 @@
* first move wrote a NaN Transform that every later move started from.
*/
import { describe, it, expect } from 'vitest';
-import { PhysicsAPI } from '../src/physics/Physics';
+import { Physics2DAPI } from '../src/physics/Physics2D';
import type { PhysicsWasmModule } from '../src/physics/PhysicsModuleLoader';
const fakeModule = () => ({}) as unknown as PhysicsWasmModule;
-describe('PhysicsAPI pixels-per-unit', () => {
+describe('Physics2DAPI pixels-per-unit', () => {
it('is finite and positive on a _fromModule instance, before any push', () => {
- const ppu = PhysicsAPI._fromModule(fakeModule()).getPixelsPerUnit();
+ const ppu = Physics2DAPI._fromModule(fakeModule()).getPixelsPerUnit();
expect(Number.isFinite(ppu)).toBe(true);
expect(ppu).toBeGreaterThan(0);
});
it('takes the pushed value', () => {
- const api = PhysicsAPI._fromModule(fakeModule());
+ const api = Physics2DAPI._fromModule(fakeModule());
api.setPixelsPerUnit(1);
expect(api.getPixelsPerUnit()).toBe(1);
});
it('keeps the last good value when pushed a non-finite or non-positive one', () => {
- const api = PhysicsAPI._fromModule(fakeModule());
+ const api = Physics2DAPI._fromModule(fakeModule());
api.setPixelsPerUnit(64);
for (const bad of [NaN, Infinity, 0, -1, undefined as unknown as number]) {
api.setPixelsPerUnit(bad);
diff --git a/sdk/tests/physicsDebugDraw.test.ts b/sdk/tests/physicsDebugDraw.test.ts
index 8506a9a73..29a7857ea 100644
--- a/sdk/tests/physicsDebugDraw.test.ts
+++ b/sdk/tests/physicsDebugDraw.test.ts
@@ -2,11 +2,11 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { describe, it, expect, beforeEach, vi } from 'vitest';
import {
- PhysicsDebugDraw,
- drawPhysicsDebug,
- setupPhysicsDebugDraw,
- type PhysicsDebugDrawConfig,
-} from '../src/physics/PhysicsDebugDraw';
+ Physics2DDebugDraw,
+ drawPhysics2DDebug,
+ setupPhysics2DDebugDraw,
+ type Physics2DDebugDrawConfig,
+} from '../src/physics/Physics2DDebugDraw';
import { BodyType } from '../src/physics/PhysicsComponents';
import { defineResource } from '../src/ecs/resource';
import type { ResourceDef } from '../src/ecs/resource';
@@ -69,10 +69,10 @@ function mockEntity(comps: Record<string, any>): MockEntity {
const MockPhysicsAPI = defineResource<any>({}, 'MockPhysicsAPI');
const MockPhysicsEvents = defineResource<any>({}, 'MockPhysicsEvents');
-describe('PhysicsDebugDraw resource', () => {
+describe('Physics2DDebugDraw resource', () => {
it('should define resource with correct defaults', () => {
- expect(PhysicsDebugDraw._name).toBe('PhysicsDebugDraw');
- expect(PhysicsDebugDraw._default).toEqual({
+ expect(Physics2DDebugDraw._name).toBe('Physics2DDebugDraw');
+ expect(Physics2DDebugDraw._default).toEqual({
enabled: false,
showColliders: true,
showVelocity: false,
@@ -81,7 +81,7 @@ describe('PhysicsDebugDraw resource', () => {
});
});
-describe('drawPhysicsDebug', () => {
+describe('drawPhysics2DDebug', () => {
beforeEach(() => {
vi.clearAllMocks();
clearUserComponents();
@@ -89,27 +89,27 @@ describe('drawPhysicsDebug', () => {
it('should do nothing when config is not present', () => {
const app = createMockApp();
- drawPhysicsDebug(app, MockPhysicsAPI, MockPhysicsEvents);
+ drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);
expect(Draw.line).not.toHaveBeenCalled();
expect(Draw.circleOutline).not.toHaveBeenCalled();
});
it('should do nothing when enabled=false', () => {
const resources = new Map<symbol, any>();
- resources.set(PhysicsDebugDraw._id, {
+ resources.set(Physics2DDebugDraw._id, {
enabled: false, showColliders: true, showVelocity: false, showContacts: false,
});
const app = createMockApp([], resources);
- drawPhysicsDebug(app, MockPhysicsAPI, MockPhysicsEvents);
+ drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);
expect(Draw.line).not.toHaveBeenCalled();
});
it('should draw box collider when enabled', () => {
const resources = new Map<symbol, any>();
- resources.set(PhysicsDebugDraw._id, {
+ resources.set(Physics2DDebugDraw._id, {
enabled: true, showColliders: true, showVelocity: false, showContacts: false,
- } as PhysicsDebugDrawConfig);
+ } as Physics2DDebugDrawConfig);
const entity = mockEntity({
RigidBody2D: { bodyType: BodyType.Static, enabled: true },
@@ -125,16 +125,16 @@ describe('drawPhysicsDebug', () => {
});
const app = createMockApp([entity], resources);
- drawPhysicsDebug(app, MockPhysicsAPI, MockPhysicsEvents);
+ drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);
expect(Draw.line).toHaveBeenCalledTimes(4);
});
it('should draw circle collider when enabled', () => {
const resources = new Map<symbol, any>();
- resources.set(PhysicsDebugDraw._id, {
+ resources.set(Physics2DDebugDraw._id, {
enabled: true, showColliders: true, showVelocity: false, showContacts: false,
- } as PhysicsDebugDrawConfig);
+ } as Physics2DDebugDrawConfig);
const entity = mockEntity({
RigidBody2D: { bodyType: BodyType.Dynamic, enabled: true },
@@ -150,16 +150,16 @@ describe('drawPhysicsDebug', () => {
});
const app = createMockApp([entity], resources);
- drawPhysicsDebug(app, MockPhysicsAPI, MockPhysicsEvents);
+ drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);
expect(Draw.circleOutline).toHaveBeenCalledTimes(1);
});
it('should draw capsule collider when enabled', () => {
const resources = new Map<symbol, any>();
- resources.set(PhysicsDebugDraw._id, {
+ resources.set(Physics2DDebugDraw._id, {
enabled: true, showColliders: true, showVelocity: false, showContacts: false,
- } as PhysicsDebugDrawConfig);
+ } as Physics2DDebugDrawConfig);
const entity = mockEntity({
RigidBody2D: { bodyType: BodyType.Dynamic, enabled: true },
@@ -176,7 +176,7 @@ describe('drawPhysicsDebug', () => {
});
const app = createMockApp([entity], resources);
- drawPhysicsDebug(app, MockPhysicsAPI, MockPhysicsEvents);
+ drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);
// 2 side lines + 16 top arc segments + 16 bottom arc segments = 34
expect(Draw.line).toHaveBeenCalledTimes(34);
@@ -184,9 +184,9 @@ describe('drawPhysicsDebug', () => {
it('should skip disabled rigid bodies', () => {
const resources = new Map<symbol, any>();
- resources.set(PhysicsDebugDraw._id, {
+ resources.set(Physics2DDebugDraw._id, {
enabled: true, showColliders: true, showVelocity: false, showContacts: false,
- } as PhysicsDebugDrawConfig);
+ } as Physics2DDebugDrawConfig);
const entity = mockEntity({
RigidBody2D: { bodyType: BodyType.Dynamic, enabled: false },
@@ -202,16 +202,16 @@ describe('drawPhysicsDebug', () => {
});
const app = createMockApp([entity], resources);
- drawPhysicsDebug(app, MockPhysicsAPI, MockPhysicsEvents);
+ drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);
expect(Draw.line).not.toHaveBeenCalled();
});
it('should use sensor color for sensor colliders', () => {
const resources = new Map<symbol, any>();
- resources.set(PhysicsDebugDraw._id, {
+ resources.set(Physics2DDebugDraw._id, {
enabled: true, showColliders: true, showVelocity: false, showContacts: false,
- } as PhysicsDebugDrawConfig);
+ } as Physics2DDebugDrawConfig);
const entity = mockEntity({
RigidBody2D: { bodyType: BodyType.Static, enabled: true },
@@ -227,7 +227,7 @@ describe('drawPhysicsDebug', () => {
});
const app = createMockApp([entity], resources);
- drawPhysicsDebug(app, MockPhysicsAPI, MockPhysicsEvents);
+ drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);
const calls = (Draw.line as any).mock.calls;
expect(calls.length).toBe(4);
@@ -237,9 +237,9 @@ describe('drawPhysicsDebug', () => {
it('should draw velocity arrows for dynamic bodies', () => {
const resources = new Map<symbol, any>();
- resources.set(PhysicsDebugDraw._id, {
+ resources.set(Physics2DDebugDraw._id, {
enabled: true, showColliders: false, showVelocity: true, showContacts: false,
- } as PhysicsDebugDrawConfig);
+ } as Physics2DDebugDrawConfig);
resources.set(MockPhysicsAPI._id, {
getLinearVelocity: vi.fn().mockReturnValue({ x: 10, y: 5 }),
});
@@ -253,7 +253,7 @@ describe('drawPhysicsDebug', () => {
});
const app = createMockApp([entity], resources);
- drawPhysicsDebug(app, MockPhysicsAPI, MockPhysicsEvents);
+ drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);
// velocity line + 2 arrowhead lines = 3
expect(Draw.line).toHaveBeenCalledTimes(3);
@@ -261,9 +261,9 @@ describe('drawPhysicsDebug', () => {
it('should not draw velocity for static bodies', () => {
const resources = new Map<symbol, any>();
- resources.set(PhysicsDebugDraw._id, {
+ resources.set(Physics2DDebugDraw._id, {
enabled: true, showColliders: false, showVelocity: true, showContacts: false,
- } as PhysicsDebugDrawConfig);
+ } as Physics2DDebugDrawConfig);
resources.set(MockPhysicsAPI._id, {
getLinearVelocity: vi.fn(),
});
@@ -277,16 +277,16 @@ describe('drawPhysicsDebug', () => {
});
const app = createMockApp([entity], resources);
- drawPhysicsDebug(app, MockPhysicsAPI, MockPhysicsEvents);
+ drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);
expect(Draw.line).not.toHaveBeenCalled();
});
it('should draw contact points when showContacts is enabled', () => {
const resources = new Map<symbol, any>();
- resources.set(PhysicsDebugDraw._id, {
+ resources.set(Physics2DDebugDraw._id, {
enabled: true, showColliders: false, showVelocity: false, showContacts: true,
- } as PhysicsDebugDrawConfig);
+ } as Physics2DDebugDrawConfig);
resources.set(MockPhysicsEvents._id, {
collisionEnters: [
{ contactX: 10, contactY: 20 },
@@ -295,28 +295,28 @@ describe('drawPhysicsDebug', () => {
});
const app = createMockApp([], resources);
- drawPhysicsDebug(app, MockPhysicsAPI, MockPhysicsEvents);
+ drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);
expect(Draw.circle).toHaveBeenCalledTimes(2);
});
- it('should not draw contacts when PhysicsEvents resource is missing', () => {
+ it('should not draw contacts when Physics2DEvents resource is missing', () => {
const resources = new Map<symbol, any>();
- resources.set(PhysicsDebugDraw._id, {
+ resources.set(Physics2DDebugDraw._id, {
enabled: true, showColliders: false, showVelocity: false, showContacts: true,
- } as PhysicsDebugDrawConfig);
+ } as Physics2DDebugDrawConfig);
const app = createMockApp([], resources);
- drawPhysicsDebug(app, MockPhysicsAPI, MockPhysicsEvents);
+ drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);
expect(Draw.circle).not.toHaveBeenCalled();
});
it('should use correct body type colors', () => {
const resources = new Map<symbol, any>();
- resources.set(PhysicsDebugDraw._id, {
+ resources.set(Physics2DDebugDraw._id, {
enabled: true, showColliders: true, showVelocity: false, showContacts: false,
- } as PhysicsDebugDrawConfig);
+ } as Physics2DDebugDrawConfig);
const staticEntity = mockEntity({
RigidBody2D: { bodyType: BodyType.Static, enabled: true },
@@ -337,7 +337,7 @@ describe('drawPhysicsDebug', () => {
});
const app = createMockApp([staticEntity, dynamicEntity, kinematicEntity], resources);
- drawPhysicsDebug(app, MockPhysicsAPI, MockPhysicsEvents);
+ drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);
expect(Draw.circleOutline).toHaveBeenCalledTimes(3);
const calls = (Draw.circleOutline as any).mock.calls;
@@ -353,9 +353,9 @@ describe('drawPhysicsDebug', () => {
it('should apply collider offset with rotation', () => {
const resources = new Map<symbol, any>();
- resources.set(PhysicsDebugDraw._id, {
+ resources.set(Physics2DDebugDraw._id, {
enabled: true, showColliders: true, showVelocity: false, showContacts: false,
- } as PhysicsDebugDrawConfig);
+ } as Physics2DDebugDrawConfig);
// 90 degree rotation: quat z=sin(45°), w=cos(45°)
const angle = Math.PI / 2;
@@ -376,7 +376,7 @@ describe('drawPhysicsDebug', () => {
});
const app = createMockApp([entity], resources);
- drawPhysicsDebug(app, MockPhysicsAPI, MockPhysicsEvents);
+ drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);
expect(Draw.circleOutline).toHaveBeenCalledTimes(1);
const call = (Draw.circleOutline as any).mock.calls[0];
@@ -387,7 +387,7 @@ describe('drawPhysicsDebug', () => {
});
});
-describe('setupPhysicsDebugDraw', () => {
+describe('setupPhysics2DDebugDraw', () => {
beforeEach(() => {
clearDrawCallbacks();
});
@@ -396,9 +396,9 @@ describe('setupPhysicsDebugDraw', () => {
const resources = new Map<symbol, any>();
const app = createMockApp([], resources);
- setupPhysicsDebugDraw(app, MockPhysicsAPI, MockPhysicsEvents);
+ setupPhysics2DDebugDraw(app, MockPhysicsAPI, MockPhysicsEvents);
- expect(app.insertResource).toHaveBeenCalledWith(PhysicsDebugDraw, {
+ expect(app.insertResource).toHaveBeenCalledWith(Physics2DDebugDraw, {
enabled: false, showColliders: true, showVelocity: false, showContacts: false,
});
diff --git a/sdk/tests/physicsSyncTransforms.test.ts b/sdk/tests/physicsSyncTransforms.test.ts
index c231d9710..dab660c8b 100644
--- a/sdk/tests/physicsSyncTransforms.test.ts
+++ b/sdk/tests/physicsSyncTransforms.test.ts
@@ -5,7 +5,7 @@ import type { Entity } from '../src/types';
import type { PhysicsWasmModule } from '../src/physics/PhysicsModuleLoader';
import type { TransformData, ParentData } from '../src/ecs/component';
import { Transform, Parent } from '../src/ecs/component';
-import { applyPhysicsTransforms } from '../src/physics/PhysicsSystem';
+import { applyPhysics2DTransforms } from '../src/physics/PhysicsSystem';
import { createMockModule } from './mocks/wasm';
import { World } from '../src/ecs/world';
@@ -18,7 +18,7 @@ function sync(
ppu: number,
parented: Set<Entity>,
): void {
- applyPhysicsTransforms(app, ppu, parented, physMod, 1);
+ applyPhysics2DTransforms(app, ppu, parented, physMod, 1);
}
// =============================================================================
@@ -296,7 +296,7 @@ describe('interpolation hand-off', () => {
]));
const spy = vi.spyOn(mod, '_physics_getInterpolatedTransforms');
- applyPhysicsTransforms(app, PPU, new Set(), mod, 0.5);
+ applyPhysics2DTransforms(app, PPU, new Set(), mod, 0.5);
expect(spy).toHaveBeenCalledWith(0.5);
const t = app.world.get(e1, Transform) as TransformData;
@@ -307,7 +307,7 @@ describe('interpolation hand-off', () => {
it('publishes nothing when the module reports no bodies', () => {
const app = createTestApp();
const mod = createMockPhysicsModule(buildPhysicsBuffer([]));
- expect(() => applyPhysicsTransforms(app, PPU, new Set(), mod, 1)).not.toThrow();
+ expect(() => applyPhysics2DTransforms(app, PPU, new Set(), mod, 1)).not.toThrow();
});
it('passes a shared heap straight through instead of re-marshalling it', () => {
@@ -330,7 +330,7 @@ describe('interpolation hand-off', () => {
engine.HEAPU8 = sharedHeap;
engine._malloc = malloc;
- applyPhysicsTransforms(app, PPU, new Set(), mod, 1);
+ applyPhysics2DTransforms(app, PPU, new Set(), mod, 1);
expect(batchSync).toHaveBeenCalledWith(expect.anything(), buf.ptr, 1, PPU);
expect(malloc).not.toHaveBeenCalled();
diff --git a/sdk/tests/plugin-cleanup.test.ts b/sdk/tests/plugin-cleanup.test.ts
index b9c33abd7..61be633dd 100644
--- a/sdk/tests/plugin-cleanup.test.ts
+++ b/sdk/tests/plugin-cleanup.test.ts
@@ -12,7 +12,7 @@
import { describe, expect, it, vi } from 'vitest';
import { SpineManager } from '../src/spine/SpineManager';
import { SpinePlugin } from '../src/spine/SpinePlugin';
-import { PhysicsPlugin } from '../src/physics/PhysicsPlugin';
+import { Physics2DPlugin } from '../src/physics/Physics2DPlugin';
describe('SpineManager.dispose', () => {
it('shuts down every backend and clears all state, idempotently', () => {
@@ -65,9 +65,9 @@ describe('SpinePlugin.cleanup', () => {
});
});
-describe('PhysicsPlugin.cleanup', () => {
+describe('Physics2DPlugin.cleanup', () => {
it('shuts down the native physics world and nulls the module', () => {
- const plugin = new PhysicsPlugin('fake://physics.wasm');
+ const plugin = new Physics2DPlugin('fake://physics.wasm');
const shutdown = vi.fn();
const p = plugin as any;
p.module_ = { _physics_shutdown: shutdown };
@@ -83,7 +83,7 @@ describe('PhysicsPlugin.cleanup', () => {
});
it('is safe to call before the async module load completed', () => {
- const plugin = new PhysicsPlugin('fake://physics.wasm');
+ const plugin = new Physics2DPlugin('fake://physics.wasm');
expect(() => plugin.cleanup()).not.toThrow();
});
});
diff --git a/sdk/tests/schedule-declared.test.ts b/sdk/tests/schedule-declared.test.ts
index af1c9ed6a..c457edc69 100644
--- a/sdk/tests/schedule-declared.test.ts
+++ b/sdk/tests/schedule-declared.test.ts
@@ -18,7 +18,7 @@ import { App } from '../src/app/app';
import { Schedule, defineSystem, GetWorld } from '../src/ecs/system';
import { simulationBasePlugins } from '../src/app/pluginSets';
import { StatsPlugin } from '../src/stats';
-import { registerCharacterControllerSystem } from '../src/physics/CharacterController2D';
+import { registerCharacterController2DSystem } from '../src/physics/CharacterController2D';
import { setPlatform } from '../src/platform/base';
import { webAdapter } from '../src/platform/web';
@@ -33,7 +33,7 @@ const build = (): App => {
const app = App.new();
for (const plugin of simulationBasePlugins()) app.addPlugin(plugin);
app.addPlugin(new StatsPlugin({ overlay: false }));
- registerCharacterControllerSystem(app);
+ registerCharacterController2DSystem(app);
return app;
};
diff --git a/sdk/tests/subsystems.test.ts b/sdk/tests/subsystems.test.ts
index f24f74fae..3c3ed14e4 100644
--- a/sdk/tests/subsystems.test.ts
+++ b/sdk/tests/subsystems.test.ts
@@ -91,7 +91,7 @@ describe('App auto-registers plugin lifecycle into the subsystem registry', () =
it('leaves an async plugin in the phase it set for itself', () => {
const app = App.new();
- // Mirrors PhysicsPlugin: moves itself off `registered` during build, so
+ // Mirrors Physics2DPlugin: moves itself off `registered` during build, so
// the App must NOT auto-promote it — it reaches ready on its own later.
const phys: Plugin = {
name: 'phys',
diff --git a/templates/2d-platformer/src/systems/coin.ts b/templates/2d-platformer/src/systems/coin.ts
index 1daf24d8f..990f0fc14 100644
--- a/templates/2d-platformer/src/systems/coin.ts
+++ b/templates/2d-platformer/src/systems/coin.ts
@@ -1,6 +1,6 @@
import {
defineSystem, Query, Mut, Res, Time, Transform, Commands,
- PhysicsEvents,
+ Physics2DEvents,
} from 'esengine';
import { Coin, ScoreDisplay } from '../components';
@@ -19,7 +19,7 @@ export const coinBobSystem = defineSystem(
);
export const coinPickupSystem = defineSystem(
- [Res(PhysicsEvents), Query(Coin), Query(Mut(ScoreDisplay)), Commands()],
+ [Res(Physics2DEvents), Query(Coin), Query(Mut(ScoreDisplay)), Commands()],
(events, coins, scores, cmds) => {
for (const ev of events.sensorEnters) {
let isCoin = false;
diff --git a/tools/apiSubsystems.mjs b/tools/apiSubsystems.mjs
index 5eda34be3..08e6155ba 100644
--- a/tools/apiSubsystems.mjs
+++ b/tools/apiSubsystems.mjs
@@ -117,7 +117,7 @@ export const SUBSYSTEMS = [
tier: 'beta',
why: 'the corpus reaches three of thirty-seven physics symbols',
whyZh: '语料只触到 37 个物理符号里的 3 个',
- entry: ['Physics', 'PhysicsEvents', 'CharacterController2D'],
+ entry: ['Physics2D', 'Physics2DEvents', 'CharacterController2D'],
},
{
id: 'camera',
diff --git a/tools/goldenProjects.mjs b/tools/goldenProjects.mjs
index bcbbcfcea..27ae66194 100644
--- a/tools/goldenProjects.mjs
+++ b/tools/goldenProjects.mjs
@@ -75,7 +75,7 @@ export const CAPABILITIES = [
* `null` = the claim is about the PACKAGE, so no source could show it.
*/
export const EVIDENCE = {
- physics: /\b(RigidBody2D|BoxCollider2D|CircleCollider2D|CapsuleCollider2D|physicsPlugin|CharacterController2D)\b/,
+ physics: /\b(RigidBody2D|BoxCollider2D|CircleCollider2D|CapsuleCollider2D|physics2dPlugin|CharacterController2D)\b/,
input: /\b(Input|defineInputMap|isKeyDown|InputState)\b/,
animation: /\b(SpriteAnimator|Animator|spriteAnim|Flipbook|TimelinePlayer|AnimClip)\b/,
ecs: /\b(defineComponent|defineSystem)\b/,