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.

fix(physics3d): a contact point is given in the units of Transform, as a ray hit is, so the debug draw crosses land where the bodies met

yhh3061dab97485
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2ab8b801a..330ab0999 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -90,6 +90,7 @@ published separately; it ships inside the editor.
### Fixed
+- **A 3D contact point is in the units of `Transform`.** The point a `Physics3DEvents.contactEnters` entry carries was in the physics world's own units, so with the default 100 pixels to the unit it sat a hundredth of the way from the origin, and the contact crosses of the physics debug draw landed there instead of where the bodies met. It is now scaled as a ray hit is.
- **`RectAnchors`, `AnchorFlag` and `AnchorMode` can be imported from `esengine`.** They were exported from the UI module only, so the import the manual shows did not resolve.
- **Lit materials draw on WebGPU again.** A lit material on the engine's own vertex stage, and a 2D lit shader, built a WebGPU program with a preprocessor line left in it, so the material drew nothing (and a desktop build of a 3D scene came up black). `#if` and `#elif` conditions with `defined`, `!`, `&&`, `||` and parentheses now resolve in a WGSL twin as they do in GLSL.
- **A scanned preview reaches the game's own server.** The page a phone opens from the preview QR code allowed connections only to itself, so a game that logged in to a server on the LAN worked in Play and in a single-file build but not on the phone. The preview now connects as Play does; a shipping web export still connects only to the servers listed in Project Settings → Allowed server origins.
diff --git a/docs/astro/src/content/docs/gameplay/physics-3d.mdx b/docs/astro/src/content/docs/gameplay/physics-3d.mdx
index 459ade277..868e2805b 100644
--- a/docs/astro/src/content/docs/gameplay/physics-3d.mdx
+++ b/docs/astro/src/content/docs/gameplay/physics-3d.mdx
@@ -456,7 +456,7 @@ for (const { sensorEntity, visitorEntity } of events.sensorEnters) {
| Channel | What it carries |
|---|---|
-| `contactEnters` | Both entities, the contact normal and the point. |
+| `contactEnters` | Both entities, the contact normal and the point, in the same units as `Transform`. |
| `contactExits` | Only the pair — see below. |
| `sensorEnters` / `sensorExits` | The **sensor first**, then the visitor. |
diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/physics-3d.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/physics-3d.mdx
index 917d01d83..9aaaa9577 100644
--- a/docs/astro/src/content/docs/zh-cn/gameplay/physics-3d.mdx
+++ b/docs/astro/src/content/docs/zh-cn/gameplay/physics-3d.mdx
@@ -412,7 +412,7 @@ for (const { sensorEntity, visitorEntity } of events.sensorEnters) {
| 通道 | 带着什么 |
|---|---|
-| `contactEnters` | 两个实体、接触法线和接触点。 |
+| `contactEnters` | 两个实体、接触法线和接触点,接触点与 `Transform` 同单位。 |
| `contactExits` | 只有这一对——原因见下。 |
| `sensorEnters` / `sensorExits` | **传感器在前**,然后是访客。 |
diff --git a/sdk/etc/physics3d.api.md b/sdk/etc/physics3d.api.md
index a42753f35..86da8dc6d 100644
--- a/sdk/etc/physics3d.api.md
+++ b/sdk/etc/physics3d.api.md
@@ -484,7 +484,7 @@ twistMinAngle: number
## drainPhysics3DEvents — function @experimental
```
-(module: Physics3DWasmModule, events: Physics3DEventsData): void
+(module: Physics3DWasmModule, events: Physics3DEventsData, pixelsPerUnit?: number): void
```
## drawPhysics3DDebug — function @experimental
diff --git a/sdk/src/physics3d/Physics3DModule.ts b/sdk/src/physics3d/Physics3DModule.ts
index a1d9e827b..ae92a6944 100644
--- a/sdk/src/physics3d/Physics3DModule.ts
+++ b/sdk/src/physics3d/Physics3DModule.ts
@@ -231,9 +231,13 @@ export const Physics3DEvents = defineResource<Physics3DEventsData>({
sensorExits: [],
}, 'Physics3DEvents');
-/** Refill `events` from the module's four buffers. */
+/**
+ * Refill `events` from the module's four buffers. A contact point is made in the world's own
+ * units, so `pixelsPerUnit` brings it into the space `Transform` and the queries speak.
+ */
export function drainPhysics3DEvents(module: Physics3DWasmModule,
- events: Physics3DEventsData): void {
+ events: Physics3DEventsData,
+ pixelsPerUnit = 1): void {
const f32 = module.HEAPF32;
const read = <T>(ptr: number, bytes: number, stride: number,
make: (base: number) => T): T[] => {
@@ -248,7 +252,7 @@ export function drainPhysics3DEvents(module: Physics3DWasmModule,
(o) => ({
entityA: f32[o] as Entity, entityB: f32[o + 1] as Entity,
normalX: f32[o + 2]!, normalY: f32[o + 3]!, normalZ: f32[o + 4]!,
- pointX: f32[o + 5]!, pointY: f32[o + 6]!, pointZ: f32[o + 7]!,
+ pointX: f32[o + 5]! * pixelsPerUnit, pointY: f32[o + 6]! * pixelsPerUnit, pointZ: f32[o + 7]! * pixelsPerUnit,
}));
events.contactExits = read(
module._physics3d_contactExits(), module._physics3d_contactExitsBytes(), 2,
diff --git a/sdk/src/physics3d/Physics3DSystem.ts b/sdk/src/physics3d/Physics3DSystem.ts
index 71d8e170b..b1b9dd85f 100644
--- a/sdk/src/physics3d/Physics3DSystem.ts
+++ b/sdk/src/physics3d/Physics3DSystem.ts
@@ -359,7 +359,7 @@ export function stepPhysics3D(app: App, module: Physics3DWasmModule,
module._physics3d_step(config.fixedTimestep, config.collisionSteps);
// Drained immediately after the step that produced them: the module's buffers
// hold one step's worth and the next step clears them.
- if (events) drainPhysics3DEvents(module, events);
+ if (events) drainPhysics3DEvents(module, events, ppu);
// Only bodies the solver moved are in the buffer, so this is the frame's
// moving population rather than every body in the world.
diff --git a/sdk/tests/physics3d-ecs.test.ts b/sdk/tests/physics3d-ecs.test.ts
index 5253bbe84..19263eebf 100644
--- a/sdk/tests/physics3d-ecs.test.ts
+++ b/sdk/tests/physics3d-ecs.test.ts
@@ -325,7 +325,7 @@ describe('the 3D world and the ECS', () => {
const events = {
contactEnters: [], contactExits: [], sensorEnters: [], sensorExits: [],
};
- // (entityA, entityB, normal, point) — two bodies met head-on at 1m up.
+ // (entityA, entityB, normal, point) — two bodies met head-on at 1m up, which is 100 in Transform units.
module.publishContacts([7, 9, 0, 1, 0, 0, 1, 0]);
stepPhysics3D(app, module, bodies, DEFAULT_PHYSICS3D_CONFIG, new Map(), events);
@@ -334,7 +334,7 @@ describe('the 3D world and the ECS', () => {
expect(hit!.entityA).toBe(7);
expect(hit!.entityB).toBe(9);
expect(hit!.normalY).toBeCloseTo(1, 6);
- expect(hit!.pointY).toBeCloseTo(1, 6);
+ expect(hit!.pointY).toBeCloseTo(DEFAULT_PHYSICS3D_CONFIG.pixelsPerUnit, 6);
});
it('collides against a loaded mesh\u2019s own triangles', () => {