Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(physics): a 3D collider can be seen while it is authored

esengine7f7b733f4ba7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4a8e1b8e7..bbd8c043b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,17 @@ published separately; it ships inside the editor.
### Added
+- **3D colliders are visible while you author them.** The viewport draws a
+ wireframe of every 3D collider — box, sphere, capsule, character, and the bounds
+ of a mesh collider — turned the way its entity is. A 3D shape is nothing the
+ renderer draws, so until now the only way to learn whether a box was the right
+ size was to press Play and watch what happened.
+
+ A shape the running world would NOT build is drawn dimmed and dashed: the solver
+ gives an entity one body shape, and a disabled collider, one shadowed by a
+ higher-priority shape, or one on an entity with no rigid body would otherwise
+ promise a collision that never happens.
+
- **Spatial queries with a shape, not just a line.** The `Physics3D` resource
answers `sphereCast`, `overlapSphere` and `overlapBox` alongside `raycast`, all
in world units and all narrowable by layer. A ray is infinitely thin and slips
diff --git a/desktop/scripts/editor-checks/collider3d-gizmo.mjs b/desktop/scripts/editor-checks/collider3d-gizmo.mjs
new file mode 100644
index 000000000..127e96a71
--- /dev/null
+++ b/desktop/scripts/editor-checks/collider3d-gizmo.mjs
@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file collider3d-gizmo — a 3D collider can be seen, and it is seen in 3D.
+ *
+ * The geometry is unit-tested. What no unit test reaches is the rest of the
+ * chain: the editor world carrying the 3D components, the per-frame projection,
+ * and the overlay's paths. The gizmo is DOM over the canvas, so only the
+ * composited window can see it at all.
+ *
+ * The scene is a box turned 90° about X, with three different half-extents. That
+ * makes the picture answer more than "something was drawn": a correct projection
+ * turns the 200-deep half into the tall one (400×200 on screen, a 2:1 box),
+ * while the flattening this codebase has produced three times before — reading
+ * the quaternion as one Z angle — would draw 40 wide and 200 tall instead.
+ */
+import { makeProject, checker } from '../lib/editorDriver.mjs';
+
+/** sin/cos of 45° — a quarter turn about X, so the box's depth becomes its height. */
+const S = Math.SQRT1_2;
+
+const SCENE = JSON.stringify({
+ version: '1.0', name: 'Main',
+ entities: [
+ {
+ id: 0, name: 'Camera', parent: null, children: [], visible: true,
+ components: [
+ { type: 'Transform', data: { position: { x: 0, y: 0, z: 10 } } },
+ { type: 'Camera', data: { projectionType: 1, orthoSize: 300, isActive: true, priority: 0 } },
+ ],
+ },
+ {
+ id: 1, name: 'Block', parent: null, children: [], visible: true,
+ components: [
+ {
+ type: 'Transform',
+ data: { position: { x: 0, y: 0, z: 0 }, rotation: { x: S, y: 0, z: 0, w: S } },
+ },
+ { type: 'RigidBody3D', data: { bodyType: 0 } },
+ { type: 'BoxCollider3D', data: { halfExtents: { x: 50, y: 10, z: 100 } } },
+ ],
+ },
+ ],
+}, null, 1);
+
+export const name = 'collider3d-gizmo';
+export const describes = 'a 3D collider is drawn in the viewport, turned the way the entity is';
+
+/** The gizmo colour (--gizmo-collider #00dc82) over the viewport's dark ground:
+ * strongly green, and green far above both other channels. */
+function greenBox(png, minGreen) {
+ let minX = Infinity, minY = Infinity, maxX = -1, maxY = -1, count = 0;
+ // The viewport only — panels, the toolbar and the status bar have greens of
+ // their own, and a stray one would stretch the box across the window.
+ const x0 = Math.round(png.w * 0.04), x1 = Math.round(png.w * 0.62);
+ const y0 = Math.round(png.h * 0.12), y1 = Math.round(png.h * 0.88);
+ for (let y = y0; y < y1; y++) {
+ for (let x = x0; x < x1; x++) {
+ const p = png.px(x, y);
+ if (p[1] < minGreen || p[1] - p[0] < 60 || p[1] - p[2] < 25) continue;
+ count++;
+ if (x < minX) minX = x;
+ if (x > maxX) maxX = x;
+ if (y < minY) minY = y;
+ if (y > maxY) maxY = y;
+ }
+ }
+ return maxX < 0 ? null : { minX, minY, maxX, maxY, w: maxX - minX + 1, h: maxY - minY + 1, count };
+}
+
+export async function run(ed) {
+ const root = await makeProject({
+ 'project.esproject': JSON.stringify({ name: 'Collider3D', version: '1.0' }, null, 2),
+ 'assets/scenes/main.esscene': SCENE,
+ });
+ const check = checker();
+
+ await ed.open(root, 'assets/scenes/main.esscene');
+ await ed.sleep(1200);
+ const drawn = await ed.screenshot('collider3d-on');
+
+ const box = greenBox(drawn, 110);
+ if (!check(box != null, 'no collider wireframe anywhere in the viewport')) return check.failures;
+ // Low enough that a wrongly-projected box still gets measured below: "it drew
+ // something" is not the claim, "it drew this shape" is.
+ if (!check(box.count > 40,
+ `only ${box.count} wireframe pixels — nothing that could be a box outline`)) {
+ return check.failures;
+ }
+
+ // 100 wide × 200 tall in world units once the quarter turn about X is applied.
+ const ratio = box.h / box.w;
+ check(
+ Math.abs(ratio - 2) < 0.3,
+ `the wireframe came out ${box.w}×${box.h} (${ratio.toFixed(2)}:1) rather than 2:1 — the `
+ + 'entity rotation is not reaching the shape in three axes',
+ );
+
+ // The same shape with no body behind it is drawn as authored-but-absent: still
+ // visible to edit, unmistakably not what the world will collide with. Without
+ // this, `active` could be computed and thrown away.
+ await ed.call('set_field', {
+ entity: 1, component: 'RigidBody3D', key: 'enabled', type: 'bool', value: false,
+ }, 30000);
+ await ed.sleep(900);
+ const off = await ed.screenshot('collider3d-inactive');
+ const dim = greenBox(off, 110);
+ const dimCount = dim?.count ?? 0;
+ check(
+ dimCount < box.count * 0.5,
+ `disabling the rigid body left ${dimCount} of ${box.count} solid wireframe pixels — a shape `
+ + 'the world does not build is being drawn as if it does',
+ );
+ // ...and it did not simply vanish: the geometry is still there to author.
+ const faint = greenBox(off, 55);
+ check(
+ (faint?.count ?? 0) > 60,
+ `the wireframe disappeared entirely (${faint?.count ?? 0} faint pixels) — a disabled body `
+ + 'should dim its shape, not hide it',
+ );
+
+ return check.failures;
+}
diff --git a/desktop/src/engine/ViewportController.ts b/desktop/src/engine/ViewportController.ts
index 101f71295..60632d184 100644
--- a/desktop/src/engine/ViewportController.ts
+++ b/desktop/src/engine/ViewportController.ts
@@ -11,6 +11,8 @@ import {
TilemapLayer, TilemapAPI, decodeTilemapChunks, CHUNK_SIZE, tileCollisionOutlines,
tileCellCenter, tileCellOutline, isNonOrthogonal,
readColliderShapes, colliderShapeOutline, shapeCenter,
+ BoxCollider3D, SphereCollider3D, CapsuleCollider3D, MeshCollider3D, CharacterController3D,
+ readCollider3DShapes, collider3DWireframe, placeCollider3DWireframe,
layerOrderOf,
editorViewHalfHeight, editorViewHalfExtent, setEditorViewHalfHeight, EDITOR_UI_ANCHOR,
entityWorldBox, uiNodeWorldBox, meshWorldBox, editorViewIsOrbited,
@@ -1109,6 +1111,64 @@ export const ViewportController = {
return { outline: solid, outlineSensor: sensor, oneWay, sizeHandle, radiusHandle, points };
},
+ /** Ids of entities carrying any 3D collider — the 3D collider-gizmo set. Separate
+ * from {@link colliderIds} because the two worlds are separate: a scene uses one
+ * or the other, and their shapes project differently (three axes, not a plane). */
+ collider3DIds(): EntityId[] {
+ const world = EngineHost.world;
+ if (!world) return [];
+ const out: EntityId[] = [];
+ for (const e of world.getAllEntities()) {
+ if (!world.has(e, Transform)) continue;
+ if (world.has(e, BoxCollider3D) || world.has(e, SphereCollider3D)
+ || world.has(e, CapsuleCollider3D) || world.has(e, MeshCollider3D)
+ || world.has(e, CharacterController3D)) {
+ out.push(e);
+ }
+ }
+ return out;
+ },
+
+ /**
+ * Screen-space wireframe of every 3D collider on `id` (SVG path data, CSS px), split
+ * into solid / sensor / inactive — drawn like the others, a shape the world does not
+ * build would promise collisions that never happen. Points project through their own
+ * z, since one entity plane would flatten a shape that spans depth.
+ */
+ getCollider3DGizmo(id: EntityId): { outline: string; outlineSensor: string; outlineInactive: string } | null {
+ const world = EngineHost.world;
+ if (!world || !world.valid(id) || !world.has(id, Transform)) return null;
+ const t = world.get(id, Transform);
+ const instances = readCollider3DShapes(
+ world as unknown as Parameters<typeof readCollider3DShapes>[0], id);
+ if (instances.length === 0) return null;
+
+ const pos = t.worldPosition as { x: number; y: number; z: number };
+ const rot = t.worldRotation as { x: number; y: number; z: number; w: number };
+ let outline = '';
+ let outlineSensor = '';
+ let outlineInactive = '';
+
+ for (const inst of instances) {
+ const lines = placeCollider3DWireframe(collider3DWireframe(inst.shape), pos, rot);
+ let d = '';
+ for (const line of lines) {
+ let pen = false;
+ for (const p of line) {
+ const s = this.worldToClient(p.x, p.y, p.z);
+ if (!s) { pen = false; continue; }
+ d += `${pen ? 'L' : 'M'}${s.x.toFixed(1)},${s.y.toFixed(1)}`;
+ pen = true;
+ }
+ d += ' ';
+ }
+ if (!inst.active) outlineInactive += d;
+ else if (inst.isSensor) outlineSensor += d;
+ else outline += d;
+ }
+ return { outline, outlineSensor, outlineInactive };
+ },
+
/**
* World-space collision outlines for a selected TilemapLayer's placed tiles — the
* SAME merged boxes + flip-aware rich shapes (slopes / circles / one-way / sensors)
diff --git a/desktop/src/panels/Viewport.tsx b/desktop/src/panels/Viewport.tsx
index 344145fb7..ae7c34930 100644
--- a/desktop/src/panels/Viewport.tsx
+++ b/desktop/src/panels/Viewport.tsx
@@ -1011,6 +1011,14 @@ export function Viewport() {
() => (engine.status === 'ready' && showColliders ? ViewportController.colliderIds() : []),
[structRev, worldRev, engine.status, showColliders],
);
+ // The 3D world's shapes, on the same switch: they are even less visible than the
+ // 2D ones (a box around a model is nothing the renderer draws), and they project
+ // as wireframes through three axes rather than outlines on a plane.
+ const collider3DRefs = useRef(new Map<number, SVGSVGElement | null>());
+ const collider3DIds = useMemo(
+ () => (engine.status === 'ready' && showColliders ? ViewportController.collider3DIds() : []),
+ [structRev, worldRev, engine.status, showColliders],
+ );
// Tile-collision overlay: the selected TilemapLayer's per-tile collision, drawn into
// ONE SVG (not one per tile). Its world-space outlines are (re)built into a ref by the
// effect below whenever the layer / its content changes; the rAF projects them each
@@ -1737,6 +1745,18 @@ export function Viewport() {
}
}
+ // 3D collider wireframes — solid / sensor / inactive, the three the projection
+ // splits every shape on the entity into.
+ for (const [cid, svg] of collider3DRefs.current) {
+ if (!svg) continue;
+ const cg = camsOn ? ViewportController.getCollider3DGizmo(cid) : null;
+ for (const [sel, d] of [['.c3-outline', cg?.outline],
+ ['.c3-outline-sensor', cg?.outlineSensor],
+ ['.c3-outline-inactive', cg?.outlineInactive]] as const) {
+ (svg.querySelector(sel) as SVGPathElement | null)?.setAttribute('d', d ?? '');
+ }
+ }
+
// Tile-collision overlay — the selected layer's per-tile collision, all in one SVG.
// Pieces are prebuilt in world space (the effect above); here we only project them
// to screen paths, culled to the visible world rect. Empty (flag off / no layer /
@@ -2603,6 +2623,29 @@ export function Viewport() {
</svg>
))}
+ {/* 3D collider wireframes: one SVG per entity, three paths — the shape the
+ solver builds, the one it builds as a trigger, and the authored-but-absent
+ one (disabled / shadowed / bodyless). */}
+ {collider3DIds.map((id) => (
+ <svg
+ key={id}
+ ref={(el) => {
+ if (el) collider3DRefs.current.set(id, el);
+ else collider3DRefs.current.delete(id);
+ }}
+ className={
+ 'viewport__collider3d-gizmo'
+ + (selectedIds.has(SceneModel.sourceFor(id) ?? -1) ? ' is-live' : '')
+ }
+ data-src={SceneModel.sourceFor(id)}
+ aria-hidden="true"
+ >
+ <path className="c3-outline-inactive" d="" />
+ <path className="c3-outline-sensor" d="" />
+ <path className="c3-outline" d="" />
+ </svg>
+ ))}
+
{/* Joint gizmos: one link line per scene-authored joint (anchor on the joint's
body ↔ anchor on the connected body), plus the prismatic/wheel slide axis
and the motor joint's target-velocity arrow. rAF-positioned, physics flag. */}
diff --git a/desktop/src/theme/app.css b/desktop/src/theme/app.css
index 5cf9f4259..19a901303 100644
--- a/desktop/src/theme/app.css
+++ b/desktop/src/theme/app.css
@@ -592,6 +592,47 @@ body.thumb-capture .viewport > :not(.viewport__stage):not(.viewport__play) {
opacity: 0;
}
+/* 3D collider wireframes — the same colour language as the 2D ones (collision is
+ collision), drawn as unfilled edges: a filled projection of twelve box edges
+ reads as a solid blob and hides the model it belongs to. */
+.viewport__collider3d-gizmo {
+ position: absolute;
+ inset: 0;
+ width: 100%;
+ height: 100%;
+ z-index: 2;
+ pointer-events: none;
+ overflow: visible;
+}
+.viewport__collider3d-gizmo path {
+ fill: none;
+ stroke-linejoin: round;
+}
+.viewport__collider3d-gizmo .c3-outline {
+ stroke: var(--gizmo-collider);
+ stroke-width: 1.25;
+ opacity: 0.75;
+}
+/* The selected entity's shape reads over everything else in a crowded scene. */
+.viewport__collider3d-gizmo.is-live .c3-outline {
+ stroke-width: 1.75;
+ opacity: 1;
+}
+.viewport__collider3d-gizmo .c3-outline-sensor {
+ stroke: var(--gizmo-collider);
+ stroke-width: 1.25;
+ stroke-dasharray: 4 3;
+ opacity: 0.7;
+}
+/* Authored but not in the running world (disabled / shadowed by another shape /
+ no rigid body): dimmed, so it never reads as something that will collide. */
+.viewport__collider3d-gizmo .c3-outline-inactive {
+ stroke: var(--gizmo-collider);
+ stroke-width: 1.25;
+ stroke-dasharray: 3 3;
+ opacity: 0.5;
+}
+
/* Tile-collision overlay: the selected TilemapLayer's per-tile collision — solid
outlines, dashed sensors, one-way arrows — all in ONE viewport-spanning SVG whose
path data the rAF writes each frame. Shares the collider colour: tile and entity
diff --git a/docs/astro/src/content/docs/gameplay/physics-3d.mdx b/docs/astro/src/content/docs/gameplay/physics-3d.mdx
index 049b5c52e..2909f23e6 100644
--- a/docs/astro/src/content/docs/gameplay/physics-3d.mdx
+++ b/docs/astro/src/content/docs/gameplay/physics-3d.mdx
@@ -68,6 +68,25 @@ cmds.spawn()
stops nothing.
</Aside>
+## Seeing a shape
+
+The viewport draws every 3D collider as a wireframe, turned the way its entity is —
+nothing else on screen says how big the box around a model is. It is on the same
+switch as the 2D collider gizmos.
+
+An entity gets ONE body shape, chosen in the order `BoxCollider3D`,
+`SphereCollider3D`, `MeshCollider3D`, `CapsuleCollider3D`. Whatever loses — a
+disabled collider, one shadowed by that order, or any collider on an entity with no
+enabled `RigidBody3D` — is drawn dimmed and dashed: still there to author, visibly
+not what the world will collide with. A `CharacterController3D` capsule is drawn
+beside it, since a character is swept rather than solved.
+
+<Aside>
+ A mesh collider draws the BOUNDS of its triangles rather than every edge — the
+ triangles are the mesh you are already looking at, and a few thousand projected
+ edges would bury it.
+</Aside>
+
## Characters
A `CharacterController3D` replaces a `RigidBody3D` rather than accompanying one: a
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 306b59741..d2e8c5830 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
@@ -62,6 +62,22 @@ cmds.spawn()
导入的几何拦不住任何东西时,先怀疑这个。
</Aside>
+## 看见形状
+
+视口把每个 3D 碰撞体画成线框,并跟着实体一起转——屏幕上没有任何别的东西
+能说出「模型外面那个盒子有多大」。它和 2D 碰撞体 gizmo 共用同一个开关。
+
+一个实体只会拿到**一个**刚体形状,按 `BoxCollider3D`、`SphereCollider3D`、
+`MeshCollider3D`、`CapsuleCollider3D` 的顺序挑。落选的那些——被禁用的、
+被这个顺序盖住的、以及所有挂在没有启用 `RigidBody3D` 的实体上的——画成暗淡虚线:
+仍然摆得动,但一眼就看得出世界不会拿它去碰撞。`CharacterController3D` 的胶囊
+画在它旁边,因为角色是被扫掠的而不是被求解的。
+
+<Aside>
+ 网格碰撞体画的是它三角形的**包围盒**而不是每一条边——那些三角形就是你已经在看的
+ 这个网格,几千条投影出来的边只会把它埋掉。
+</Aside>
+
## 角色
`CharacterController3D` **取代** `RigidBody3D` 而不是与它并存:被求解器推的刚体
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 2df504f65..5abacd0f5 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 58 beta · 1418 experimental · 3 deprecated
+Symbols: 113 public · 60 beta · 1435 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -1248,6 +1248,20 @@ Static = 0
BuiltinComponentDef<BoxColliderData>
```
+## BoxCollider3D — const @experimental
+```
+BuiltinComponentDef<BoxCollider3DData>
+```
+
+## BoxCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+halfExtents: Vec3
+isSensor: boolean
+restitution: number
+```
+
## BoxColliderData — interface @experimental
```
categoryBits: number
@@ -1425,6 +1439,11 @@ sprite: number | undefined
16
```
+## COLLIDER3D_RING_SEGMENTS — const @experimental
+```
+24
+```
+
## COLLISION_BRUSHES — const @experimental
```
CollisionBrush[]
@@ -1625,6 +1644,21 @@ width: number
BuiltinComponentDef<CapsuleColliderData>
```
+## CapsuleCollider3D — const @experimental
+```
+BuiltinComponentDef<CapsuleCollider3DData>
+```
+
+## CapsuleCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+halfHeight: number
+isSensor: boolean
+radius: number
+restitution: number
+```
+
## CapsuleColliderData — interface @experimental
```
categoryBits: number
@@ -1822,6 +1856,27 @@ ComponentDef<ChainColliderData>
ComponentDef<CharacterControllerData>
```
+## CharacterController3D — const @beta
+```
+BuiltinComponentDef<CharacterController3DData>
+```
+
+## CharacterController3DData — interface @experimental
+```
+enabled: boolean
+floorNormal: Vec3
+halfHeight: number
+isOnFloor: boolean
+layer: number
+mass: number
+maxSlope: number
+radius: number
+realVelocity: Vec3
+snapDown: number
+stepHeight: number
+velocity: Vec3
+```
+
## CharacterControllerData — interface @experimental
```
floorMaxAngle: number
@@ -1875,6 +1930,27 @@ Depth = 2
Nothing = 0
```
+## Collider3DComponent — type @experimental
+```
+| 'BoxCollider3D' | 'SphereCollider3D' | 'CapsuleCollider3D'
+ | 'MeshCollider3D' | 'CharacterController3D'
+```
+
+## Collider3DInstance — interface @experimental
+```
+active: boolean
+component: Collider3DComponent
+isSensor: boolean
+shape: Collider3DShape
+```
+
+## Collider3DShape — type @experimental
+```
+| { kind: 'box'; halfExtents: Vec3; center: Vec3 }
+ | { kind: 'sphere'; radius: number }
+ | { kind: 'capsule'; radius: number; halfHeight: number }
+```
+
## ColliderInstance — interface @experimental
```
enabled: boolean
@@ -4299,6 +4375,20 @@ type: number
{ readonly Float32: 0; readonly UNorm8: 1; readonly UInt16: 2; }
```
+## MeshCollider3D — const @beta
+```
+BuiltinComponentDef<MeshCollider3DData>
+```
+
+## MeshCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+layer: number
+mesh: number
+restitution: number
+```
+
## MeshData — interface @experimental
```
aabbMax: [number, number, number]
@@ -6042,6 +6132,22 @@ TextSegment | ImageSegment
BuiltinComponentDef<RigidBodyData>
```
+## RigidBody3D — const @experimental
+```
+BuiltinComponentDef<RigidBody3DData>
+```
+
+## RigidBody3DData — interface @experimental
+```
+angularDamping: number
+bodyType: number
+enabled: boolean
+fixedRotation: boolean
+gravityScale: number
+layer: number
+linearDamping: number
+```
+
## RigidBodyData — interface @experimental
```
angularDamping: number
@@ -6740,6 +6846,20 @@ rolloff: number
Omit<PrefabOverride, 'prefabEntityId'> & { prefabEntityId?: string }
```
+## SphereCollider3D — const @experimental
+```
+BuiltinComponentDef<SphereCollider3DData>
+```
+
+## SphereCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+isSensor: boolean
+radius: number
+restitution: number
+```
+
## Spine — const @beta
```
ResourceDef<SpineManager>
@@ -9262,6 +9382,11 @@ BtPlugin
(asset: TilesetAsset): number[]
```
+## collider3DWireframe — function @experimental
+```
+(shape: Collider3DShape, segments?: number): Vec3[][]
+```
+
## colliderShapeOutline — function @experimental
```
(shape: ColliderShape, center: Vec2, angle: number, ppu: number): ColliderOutline
@@ -10602,6 +10727,11 @@ ParticlePlugin
PerceptionPlugin
```
+## placeCollider3DWireframe — function @experimental
+```
+(lines: Vec3[][], position: Vec3, rotation: Quat): Vec3[][]
+```
+
## platformCanOpenData — function @experimental
```
(): boolean
@@ -10762,6 +10892,11 @@ PrefabsPlugin
(radius: number, options?: RadiusInterestOptions): InterestPolicy
```
+## readCollider3DShapes — function @experimental
+```
+(world: World, entity: number): Collider3DInstance[]
+```
+
## readColliderShapes — function @experimental
```
(world: World, entity: number): ColliderInstance[]
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index ed9284726..e232d0bc4 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 63 beta · 1437 experimental · 3 deprecated
+Symbols: 113 public · 65 beta · 1454 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -1248,6 +1248,20 @@ Static = 0
BuiltinComponentDef<BoxColliderData>
```
+## BoxCollider3D — const @experimental
+```
+BuiltinComponentDef<BoxCollider3DData>
+```
+
+## BoxCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+halfExtents: Vec3
+isSensor: boolean
+restitution: number
+```
+
## BoxColliderData — interface @experimental
```
categoryBits: number
@@ -1425,6 +1439,11 @@ sprite: number | undefined
16
```
+## COLLIDER3D_RING_SEGMENTS — const @experimental
+```
+24
+```
+
## COLLISION_BRUSHES — const @experimental
```
CollisionBrush[]
@@ -1625,6 +1644,21 @@ width: number
BuiltinComponentDef<CapsuleColliderData>
```
+## CapsuleCollider3D — const @experimental
+```
+BuiltinComponentDef<CapsuleCollider3DData>
+```
+
+## CapsuleCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+halfHeight: number
+isSensor: boolean
+radius: number
+restitution: number
+```
+
## CapsuleColliderData — interface @experimental
```
categoryBits: number
@@ -1822,6 +1856,27 @@ ComponentDef<ChainColliderData>
ComponentDef<CharacterControllerData>
```
+## CharacterController3D — const @beta
+```
+BuiltinComponentDef<CharacterController3DData>
+```
+
+## CharacterController3DData — interface @experimental
+```
+enabled: boolean
+floorNormal: Vec3
+halfHeight: number
+isOnFloor: boolean
+layer: number
+mass: number
+maxSlope: number
+radius: number
+realVelocity: Vec3
+snapDown: number
+stepHeight: number
+velocity: Vec3
+```
+
## CharacterControllerData — interface @experimental
```
floorMaxAngle: number
@@ -1875,6 +1930,27 @@ Depth = 2
Nothing = 0
```
+## Collider3DComponent — type @experimental
+```
+| 'BoxCollider3D' | 'SphereCollider3D' | 'CapsuleCollider3D'
+ | 'MeshCollider3D' | 'CharacterController3D'
+```
+
+## Collider3DInstance — interface @experimental
+```
+active: boolean
+component: Collider3DComponent
+isSensor: boolean
+shape: Collider3DShape
+```
+
+## Collider3DShape — type @experimental
+```
+| { kind: 'box'; halfExtents: Vec3; center: Vec3 }
+ | { kind: 'sphere'; radius: number }
+ | { kind: 'capsule'; radius: number; halfHeight: number }
+```
+
## ColliderInstance — interface @experimental
```
enabled: boolean
@@ -4312,6 +4388,20 @@ type: number
{ readonly Float32: 0; readonly UNorm8: 1; readonly UInt16: 2; }
```
+## MeshCollider3D — const @beta
+```
+BuiltinComponentDef<MeshCollider3DData>
+```
+
+## MeshCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+layer: number
+mesh: number
+restitution: number
+```
+
## MeshData — interface @experimental
```
aabbMax: [number, number, number]
@@ -6235,6 +6325,22 @@ TextSegment | ImageSegment
BuiltinComponentDef<RigidBodyData>
```
+## RigidBody3D — const @experimental
+```
+BuiltinComponentDef<RigidBody3DData>
+```
+
+## RigidBody3DData — interface @experimental
+```
+angularDamping: number
+bodyType: number
+enabled: boolean
+fixedRotation: boolean
+gravityScale: number
+layer: number
+linearDamping: number
+```
+
## RigidBodyData — interface @experimental
```
angularDamping: number
@@ -6933,6 +7039,20 @@ rolloff: number
Omit<PrefabOverride, 'prefabEntityId'> & { prefabEntityId?: string }
```
+## SphereCollider3D — const @experimental
+```
+BuiltinComponentDef<SphereCollider3DData>
+```
+
+## SphereCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+isSensor: boolean
+radius: number
+restitution: number
+```
+
## Spine — const @beta
```
ResourceDef<SpineManager>
@@ -9470,6 +9590,11 @@ BtPlugin
(asset: TilesetAsset): number[]
```
+## collider3DWireframe — function @experimental
+```
+(shape: Collider3DShape, segments?: number): Vec3[][]
+```
+
## colliderShapeOutline — function @experimental
```
(shape: ColliderShape, center: Vec2, angle: number, ppu: number): ColliderOutline
@@ -10845,6 +10970,11 @@ ParticlePlugin
PerceptionPlugin
```
+## placeCollider3DWireframe — function @experimental
+```
+(lines: Vec3[][], position: Vec3, rotation: Quat): Vec3[][]
+```
+
## platformCanOpenData — function @experimental
```
(): boolean
@@ -11005,6 +11135,11 @@ PrefabsPlugin
(radius: number, options?: RadiusInterestOptions): InterestPolicy
```
+## readCollider3DShapes — function @experimental
+```
+(world: World, entity: number): Collider3DInstance[]
+```
+
## readColliderShapes — function @experimental
```
(world: World, entity: number): ColliderInstance[]
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 49ae4501b..cc23d06da 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 60 beta · 1417 experimental · 3 deprecated
+Symbols: 113 public · 62 beta · 1434 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -1243,6 +1243,20 @@ Static = 0
BuiltinComponentDef<BoxColliderData>
```
+## BoxCollider3D — const @experimental
+```
+BuiltinComponentDef<BoxCollider3DData>
+```
+
+## BoxCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+halfExtents: Vec3
+isSensor: boolean
+restitution: number
+```
+
## BoxColliderData — interface @experimental
```
categoryBits: number
@@ -1420,6 +1434,11 @@ sprite: number | undefined
16
```
+## COLLIDER3D_RING_SEGMENTS — const @experimental
+```
+24
+```
+
## COLLISION_BRUSHES — const @experimental
```
CollisionBrush[]
@@ -1620,6 +1639,21 @@ width: number
BuiltinComponentDef<CapsuleColliderData>
```
+## CapsuleCollider3D — const @experimental
+```
+BuiltinComponentDef<CapsuleCollider3DData>
+```
+
+## CapsuleCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+halfHeight: number
+isSensor: boolean
+radius: number
+restitution: number
+```
+
## CapsuleColliderData — interface @experimental
```
categoryBits: number
@@ -1817,6 +1851,27 @@ ComponentDef<ChainColliderData>
ComponentDef<CharacterControllerData>
```
+## CharacterController3D — const @beta
+```
+BuiltinComponentDef<CharacterController3DData>
+```
+
+## CharacterController3DData — interface @experimental
+```
+enabled: boolean
+floorNormal: Vec3
+halfHeight: number
+isOnFloor: boolean
+layer: number
+mass: number
+maxSlope: number
+radius: number
+realVelocity: Vec3
+snapDown: number
+stepHeight: number
+velocity: Vec3
+```
+
## CharacterControllerData — interface @experimental
```
floorMaxAngle: number
@@ -1870,6 +1925,27 @@ Depth = 2
Nothing = 0
```
+## Collider3DComponent — type @experimental
+```
+| 'BoxCollider3D' | 'SphereCollider3D' | 'CapsuleCollider3D'
+ | 'MeshCollider3D' | 'CharacterController3D'
+```
+
+## Collider3DInstance — interface @experimental
+```
+active: boolean
+component: Collider3DComponent
+isSensor: boolean
+shape: Collider3DShape
+```
+
+## Collider3DShape — type @experimental
+```
+| { kind: 'box'; halfExtents: Vec3; center: Vec3 }
+ | { kind: 'sphere'; radius: number }
+ | { kind: 'capsule'; radius: number; halfHeight: number }
+```
+
## ColliderInstance — interface @experimental
```
enabled: boolean
@@ -4294,6 +4370,20 @@ type: number
{ readonly Float32: 0; readonly UNorm8: 1; readonly UInt16: 2; }
```
+## MeshCollider3D — const @beta
+```
+BuiltinComponentDef<MeshCollider3DData>
+```
+
+## MeshCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+layer: number
+mesh: number
+restitution: number
+```
+
## MeshData — interface @experimental
```
aabbMax: [number, number, number]
@@ -6037,6 +6127,22 @@ TextSegment | ImageSegment
BuiltinComponentDef<RigidBodyData>
```
+## RigidBody3D — const @experimental
+```
+BuiltinComponentDef<RigidBody3DData>
+```
+
+## RigidBody3DData — interface @experimental
+```
+angularDamping: number
+bodyType: number
+enabled: boolean
+fixedRotation: boolean
+gravityScale: number
+layer: number
+linearDamping: number
+```
+
## RigidBodyData — interface @experimental
```
angularDamping: number
@@ -6735,6 +6841,20 @@ rolloff: number
Omit<PrefabOverride, 'prefabEntityId'> & { prefabEntityId?: string }
```
+## SphereCollider3D — const @experimental
+```
+BuiltinComponentDef<SphereCollider3DData>
+```
+
+## SphereCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+isSensor: boolean
+radius: number
+restitution: number
+```
+
## Spine — const @beta
```
ResourceDef<SpineManager>
@@ -9257,6 +9377,11 @@ BtPlugin
(asset: TilesetAsset): number[]
```
+## collider3DWireframe — function @experimental
+```
+(shape: Collider3DShape, segments?: number): Vec3[][]
+```
+
## colliderShapeOutline — function @experimental
```
(shape: ColliderShape, center: Vec2, angle: number, ppu: number): ColliderOutline
@@ -10607,6 +10732,11 @@ ParticlePlugin
PerceptionPlugin
```
+## placeCollider3DWireframe — function @experimental
+```
+(lines: Vec3[][], position: Vec3, rotation: Quat): Vec3[][]
+```
+
## platformCanOpenData — function @experimental
```
(): boolean
@@ -10767,6 +10897,11 @@ PrefabsPlugin
(radius: number, options?: RadiusInterestOptions): InterestPolicy
```
+## readCollider3DShapes — function @experimental
+```
+(world: World, entity: number): Collider3DInstance[]
+```
+
## readColliderShapes — function @experimental
```
(world: World, entity: number): ColliderInstance[]
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 7039808e4..4fabc6a57 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 58 beta · 1438 experimental · 3 deprecated
+Symbols: 113 public · 60 beta · 1455 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -1243,6 +1243,20 @@ Static = 0
BuiltinComponentDef<BoxColliderData>
```
+## BoxCollider3D — const @experimental
+```
+BuiltinComponentDef<BoxCollider3DData>
+```
+
+## BoxCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+halfExtents: Vec3
+isSensor: boolean
+restitution: number
+```
+
## BoxColliderData — interface @experimental
```
categoryBits: number
@@ -1420,6 +1434,11 @@ sprite: number | undefined
16
```
+## COLLIDER3D_RING_SEGMENTS — const @experimental
+```
+24
+```
+
## COLLISION_BRUSHES — const @experimental
```
CollisionBrush[]
@@ -1620,6 +1639,21 @@ width: number
BuiltinComponentDef<CapsuleColliderData>
```
+## CapsuleCollider3D — const @experimental
+```
+BuiltinComponentDef<CapsuleCollider3DData>
+```
+
+## CapsuleCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+halfHeight: number
+isSensor: boolean
+radius: number
+restitution: number
+```
+
## CapsuleColliderData — interface @experimental
```
categoryBits: number
@@ -1817,6 +1851,27 @@ ComponentDef<ChainColliderData>
ComponentDef<CharacterControllerData>
```
+## CharacterController3D — const @beta
+```
+BuiltinComponentDef<CharacterController3DData>
+```
+
+## CharacterController3DData — interface @experimental
+```
+enabled: boolean
+floorNormal: Vec3
+halfHeight: number
+isOnFloor: boolean
+layer: number
+mass: number
+maxSlope: number
+radius: number
+realVelocity: Vec3
+snapDown: number
+stepHeight: number
+velocity: Vec3
+```
+
## CharacterControllerData — interface @experimental
```
floorMaxAngle: number
@@ -1870,6 +1925,27 @@ Depth = 2
Nothing = 0
```
+## Collider3DComponent — type @experimental
+```
+| 'BoxCollider3D' | 'SphereCollider3D' | 'CapsuleCollider3D'
+ | 'MeshCollider3D' | 'CharacterController3D'
+```
+
+## Collider3DInstance — interface @experimental
+```
+active: boolean
+component: Collider3DComponent
+isSensor: boolean
+shape: Collider3DShape
+```
+
+## Collider3DShape — type @experimental
+```
+| { kind: 'box'; halfExtents: Vec3; center: Vec3 }
+ | { kind: 'sphere'; radius: number }
+ | { kind: 'capsule'; radius: number; halfHeight: number }
+```
+
## ColliderInstance — interface @experimental
```
enabled: boolean
@@ -4294,6 +4370,20 @@ type: number
{ readonly Float32: 0; readonly UNorm8: 1; readonly UInt16: 2; }
```
+## MeshCollider3D — const @beta
+```
+BuiltinComponentDef<MeshCollider3DData>
+```
+
+## MeshCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+layer: number
+mesh: number
+restitution: number
+```
+
## MeshData — interface @experimental
```
aabbMax: [number, number, number]
@@ -6282,6 +6372,22 @@ TextSegment | ImageSegment
BuiltinComponentDef<RigidBodyData>
```
+## RigidBody3D — const @experimental
+```
+BuiltinComponentDef<RigidBody3DData>
+```
+
+## RigidBody3DData — interface @experimental
+```
+angularDamping: number
+bodyType: number
+enabled: boolean
+fixedRotation: boolean
+gravityScale: number
+layer: number
+linearDamping: number
+```
+
## RigidBodyData — interface @experimental
```
angularDamping: number
@@ -6980,6 +7086,20 @@ rolloff: number
Omit<PrefabOverride, 'prefabEntityId'> & { prefabEntityId?: string }
```
+## SphereCollider3D — const @experimental
+```
+BuiltinComponentDef<SphereCollider3DData>
+```
+
+## SphereCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+isSensor: boolean
+radius: number
+restitution: number
+```
+
## Spine — const @beta
```
ResourceDef<SpineManager>
@@ -9502,6 +9622,11 @@ BtPlugin
(asset: TilesetAsset): number[]
```
+## collider3DWireframe — function @experimental
+```
+(shape: Collider3DShape, segments?: number): Vec3[][]
+```
+
## colliderShapeOutline — function @experimental
```
(shape: ColliderShape, center: Vec2, angle: number, ppu: number): ColliderOutline
@@ -10857,6 +10982,11 @@ ParticlePlugin
PerceptionPlugin
```
+## placeCollider3DWireframe — function @experimental
+```
+(lines: Vec3[][], position: Vec3, rotation: Quat): Vec3[][]
+```
+
## platformCanOpenData — function @experimental
```
(): boolean
@@ -11017,6 +11147,11 @@ PrefabsPlugin
(radius: number, options?: RadiusInterestOptions): InterestPolicy
```
+## readCollider3DShapes — function @experimental
+```
+(world: World, entity: number): Collider3DInstance[]
+```
+
## readColliderShapes — function @experimental
```
(world: World, entity: number): ColliderInstance[]
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index d01776a04..63b0d9b81 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 58 beta · 1428 experimental · 3 deprecated
+Symbols: 113 public · 60 beta · 1445 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -1243,6 +1243,20 @@ Static = 0
BuiltinComponentDef<BoxColliderData>
```
+## BoxCollider3D — const @experimental
+```
+BuiltinComponentDef<BoxCollider3DData>
+```
+
+## BoxCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+halfExtents: Vec3
+isSensor: boolean
+restitution: number
+```
+
## BoxColliderData — interface @experimental
```
categoryBits: number
@@ -1420,6 +1434,11 @@ sprite: number | undefined
16
```
+## COLLIDER3D_RING_SEGMENTS — const @experimental
+```
+24
+```
+
## COLLISION_BRUSHES — const @experimental
```
CollisionBrush[]
@@ -1620,6 +1639,21 @@ width: number
BuiltinComponentDef<CapsuleColliderData>
```
+## CapsuleCollider3D — const @experimental
+```
+BuiltinComponentDef<CapsuleCollider3DData>
+```
+
+## CapsuleCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+halfHeight: number
+isSensor: boolean
+radius: number
+restitution: number
+```
+
## CapsuleColliderData — interface @experimental
```
categoryBits: number
@@ -1817,6 +1851,27 @@ ComponentDef<ChainColliderData>
ComponentDef<CharacterControllerData>
```
+## CharacterController3D — const @beta
+```
+BuiltinComponentDef<CharacterController3DData>
+```
+
+## CharacterController3DData — interface @experimental
+```
+enabled: boolean
+floorNormal: Vec3
+halfHeight: number
+isOnFloor: boolean
+layer: number
+mass: number
+maxSlope: number
+radius: number
+realVelocity: Vec3
+snapDown: number
+stepHeight: number
+velocity: Vec3
+```
+
## CharacterControllerData — interface @experimental
```
floorMaxAngle: number
@@ -1870,6 +1925,27 @@ Depth = 2
Nothing = 0
```
+## Collider3DComponent — type @experimental
+```
+| 'BoxCollider3D' | 'SphereCollider3D' | 'CapsuleCollider3D'
+ | 'MeshCollider3D' | 'CharacterController3D'
+```
+
+## Collider3DInstance — interface @experimental
+```
+active: boolean
+component: Collider3DComponent
+isSensor: boolean
+shape: Collider3DShape
+```
+
+## Collider3DShape — type @experimental
+```
+| { kind: 'box'; halfExtents: Vec3; center: Vec3 }
+ | { kind: 'sphere'; radius: number }
+ | { kind: 'capsule'; radius: number; halfHeight: number }
+```
+
## ColliderInstance — interface @experimental
```
enabled: boolean
@@ -4301,6 +4377,20 @@ type: number
{ readonly Float32: 0; readonly UNorm8: 1; readonly UInt16: 2; }
```
+## MeshCollider3D — const @beta
+```
+BuiltinComponentDef<MeshCollider3DData>
+```
+
+## MeshCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+layer: number
+mesh: number
+restitution: number
+```
+
## MeshData — interface @experimental
```
aabbMax: [number, number, number]
@@ -6044,6 +6134,22 @@ TextSegment | ImageSegment
BuiltinComponentDef<RigidBodyData>
```
+## RigidBody3D — const @experimental
+```
+BuiltinComponentDef<RigidBody3DData>
+```
+
+## RigidBody3DData — interface @experimental
+```
+angularDamping: number
+bodyType: number
+enabled: boolean
+fixedRotation: boolean
+gravityScale: number
+layer: number
+linearDamping: number
+```
+
## RigidBodyData — interface @experimental
```
angularDamping: number
@@ -6742,6 +6848,20 @@ rolloff: number
Omit<PrefabOverride, 'prefabEntityId'> & { prefabEntityId?: string }
```
+## SphereCollider3D — const @experimental
+```
+BuiltinComponentDef<SphereCollider3DData>
+```
+
+## SphereCollider3DData — interface @experimental
+```
+enabled: boolean
+friction: number
+isSensor: boolean
+radius: number
+restitution: number
+```
+
## Spine — const @beta
```
ResourceDef<SpineManager>
@@ -9284,6 +9404,11 @@ BtPlugin
(asset: TilesetAsset): number[]
```
+## collider3DWireframe — function @experimental
+```
+(shape: Collider3DShape, segments?: number): Vec3[][]
+```
+
## colliderShapeOutline — function @experimental
```
(shape: ColliderShape, center: Vec2, angle: number, ppu: number): ColliderOutline
@@ -10629,6 +10754,11 @@ ParticlePlugin
PerceptionPlugin
```
+## placeCollider3DWireframe — function @experimental
+```
+(lines: Vec3[][], position: Vec3, rotation: Quat): Vec3[][]
+```
+
## platformCanOpenData — function @experimental
```
(): boolean
@@ -10789,6 +10919,11 @@ PrefabsPlugin
(radius: number, options?: RadiusInterestOptions): InterestPolicy
```
+## readCollider3DShapes — function @experimental
+```
+(world: World, entity: number): Collider3DInstance[]
+```
+
## readColliderShapes — function @experimental
```
(world: World, entity: number): ColliderInstance[]
diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.ts
index 2056dba22..2791f44e4 100644
--- a/sdk/src/core-runtime.ts
+++ b/sdk/src/core-runtime.ts
@@ -185,6 +185,31 @@ export {
type ColliderOutline,
} from './physics/ColliderShape';
+export {
+ RigidBody3D,
+ BoxCollider3D,
+ SphereCollider3D,
+ CapsuleCollider3D,
+ MeshCollider3D,
+ CharacterController3D,
+ type RigidBody3DData,
+ type BoxCollider3DData,
+ type SphereCollider3DData,
+ type CapsuleCollider3DData,
+ type MeshCollider3DData,
+ type CharacterController3DData,
+} from './physics3d/Physics3DComponents';
+
+export {
+ readCollider3DShapes,
+ collider3DWireframe,
+ placeCollider3DWireframe,
+ COLLIDER3D_RING_SEGMENTS,
+ type Collider3DShape,
+ type Collider3DInstance,
+ type Collider3DComponent,
+} from './physics3d/ColliderShape3D';
+
// =============================================================================
// Resources
// =============================================================================
diff --git a/sdk/src/physics3d/ColliderShape3D.ts b/sdk/src/physics3d/ColliderShape3D.ts
new file mode 100644
index 000000000..c49b8694f
--- /dev/null
+++ b/sdk/src/physics3d/ColliderShape3D.ts
@@ -0,0 +1,271 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file ColliderShape3D.ts
+ * @brief The single geometry projection over the 3D collider components — the
+ * shared seam for every visualizer of the 3D world.
+ * @details A 3D collider is invisible in a way a 2D one never was: the shape is
+ * not the sprite, the entity may be rotated on three axes, and nothing
+ * on screen says how big the box around a model is. This reads the
+ * components into shape descriptors and emits wireframes from them, so
+ * the editor gizmo and any runtime overlay draw the same geometry.
+ *
+ * What it reports is what the SOLVER builds, not what the scene carries:
+ * the running world gives an entity ONE body shape, chosen in the order
+ * {@link readCollider3DShapes} walks, and none at all without an enabled
+ * RigidBody3D. A gizmo that drew every authored collider would promise
+ * collisions that do not happen.
+ *
+ * Units: 3D collider fields are world units already (the system divides by
+ * pixels-per-unit on its way into the solver), so nothing here scales.
+ */
+import type { Vec3, Quat } from '../types';
+import type { World } from '../ecs/world';
+import {
+ RigidBody3D, BoxCollider3D, SphereCollider3D, CapsuleCollider3D,
+ MeshCollider3D, CharacterController3D,
+} from './Physics3DComponents';
+import type {
+ RigidBody3DData, BoxCollider3DData, SphereCollider3DData, CapsuleCollider3DData,
+ MeshCollider3DData, CharacterController3DData,
+} from './Physics3DComponents';
+import { getMeshCollision } from '../asset/meshCollision';
+
+/** Points per full circle in a sphere/capsule wireframe. */
+export const COLLIDER3D_RING_SEGMENTS = 24;
+
+/** A 3D collider's geometry in entity-local space, in world units. */
+export type Collider3DShape =
+ | { kind: 'box'; halfExtents: Vec3; center: Vec3 }
+ | { kind: 'sphere'; radius: number }
+ | { kind: 'capsule'; radius: number; halfHeight: number };
+
+/** Which component authored a shape — the Inspector target behind a gizmo. */
+export type Collider3DComponent =
+ | 'BoxCollider3D' | 'SphereCollider3D' | 'CapsuleCollider3D'
+ | 'MeshCollider3D' | 'CharacterController3D';
+
+export interface Collider3DInstance {
+ component: Collider3DComponent;
+ shape: Collider3DShape;
+ isSensor: boolean;
+ /** Whether the running world builds this shape. False for a disabled collider,
+ * one shadowed by a higher-priority shape on the same entity, one whose mesh
+ * never loaded, or any collider on an entity with no enabled RigidBody3D —
+ * all authorable, none of them in the solver. */
+ active: boolean;
+}
+
+const ZERO: Vec3 = { x: 0, y: 0, z: 0 };
+
+function rotateByQuat(q: Quat, v: Vec3): Vec3 {
+ // t = 2 * (q.xyz × v); v' = v + q.w * t + q.xyz × t
+ const tx = 2 * (q.y * v.z - q.z * v.y);
+ const ty = 2 * (q.z * v.x - q.x * v.z);
+ const tz = 2 * (q.x * v.y - q.y * v.x);
+ return {
+ x: v.x + q.w * tx + q.y * tz - q.z * ty,
+ y: v.y + q.w * ty + q.z * tx - q.x * tz,
+ z: v.z + q.w * tz + q.x * ty - q.y * tx,
+ };
+}
+
+/** Local AABB of a loaded mesh's collision triangles, or null when nothing loaded them. */
+function meshBounds(handle: number): { center: Vec3; halfExtents: Vec3 } | null {
+ const data = handle !== 0 ? getMeshCollision(handle) : null;
+ if (!data || data.positions.length < 3) return null;
+ const p = data.positions;
+ let minX = p[0]!, minY = p[1]!, minZ = p[2]!;
+ let maxX = minX, maxY = minY, maxZ = minZ;
+ for (let i = 3; i + 2 < p.length; i += 3) {
+ const x = p[i]!, y = p[i + 1]!, z = p[i + 2]!;
+ if (x < minX) minX = x; else if (x > maxX) maxX = x;
+ if (y < minY) minY = y; else if (y > maxY) maxY = y;
+ if (z < minZ) minZ = z; else if (z > maxZ) maxZ = z;
+ }
+ return {
+ center: { x: (minX + maxX) / 2, y: (minY + maxY) / 2, z: (minZ + maxZ) / 2 },
+ halfExtents: { x: (maxX - minX) / 2, y: (maxY - minY) / 2, z: (maxZ - minZ) / 2 },
+ };
+}
+
+/**
+ * Every 3D collider on `entity`, each marked with whether it is the one the solver
+ * ends up building. The order mirrors `createBody` in Physics3DSystem — box, sphere,
+ * mesh, capsule — and must keep mirroring it: a visualizer drawing a different shape
+ * than the world collides with is worse than none.
+ */
+export function readCollider3DShapes(world: World, entity: number): Collider3DInstance[] {
+ const out: Collider3DInstance[] = [];
+ const on = (c: { enabled?: boolean }): boolean => c.enabled !== false;
+ const body = world.has(entity, RigidBody3D)
+ ? world.get(entity, RigidBody3D) as RigidBody3DData : null;
+ const bodyLive = body !== null && on(body);
+ let taken = false;
+
+ const box = world.has(entity, BoxCollider3D)
+ ? world.get(entity, BoxCollider3D) as BoxCollider3DData : null;
+ if (box) {
+ const chosen = !taken && on(box);
+ if (chosen) taken = true;
+ out.push({
+ component: 'BoxCollider3D',
+ shape: { kind: 'box', halfExtents: box.halfExtents, center: ZERO },
+ isSensor: box.isSensor === true,
+ active: chosen && bodyLive,
+ });
+ }
+
+ const sphere = world.has(entity, SphereCollider3D)
+ ? world.get(entity, SphereCollider3D) as SphereCollider3DData : null;
+ if (sphere) {
+ const chosen = !taken && on(sphere);
+ if (chosen) taken = true;
+ out.push({
+ component: 'SphereCollider3D',
+ shape: { kind: 'sphere', radius: sphere.radius },
+ isSensor: sphere.isSensor === true,
+ active: chosen && bodyLive,
+ });
+ }
+
+ const mesh = world.has(entity, MeshCollider3D)
+ ? world.get(entity, MeshCollider3D) as MeshCollider3DData : null;
+ if (mesh) {
+ // A mesh collider claims the entity's one body slot as soon as it names a
+ // mesh; whether that mesh loaded decides only if a body appears at all.
+ const chosen = !taken && on(mesh) && mesh.mesh !== 0;
+ if (chosen) taken = true;
+ const bounds = meshBounds(mesh.mesh);
+ if (bounds) {
+ out.push({
+ component: 'MeshCollider3D',
+ shape: { kind: 'box', halfExtents: bounds.halfExtents, center: bounds.center },
+ isSensor: false,
+ active: chosen && bodyLive,
+ });
+ }
+ }
+
+ const capsule = world.has(entity, CapsuleCollider3D)
+ ? world.get(entity, CapsuleCollider3D) as CapsuleCollider3DData : null;
+ if (capsule) {
+ const chosen = !taken && on(capsule);
+ if (chosen) taken = true;
+ out.push({
+ component: 'CapsuleCollider3D',
+ shape: { kind: 'capsule', radius: capsule.radius, halfHeight: capsule.halfHeight },
+ isSensor: capsule.isSensor === true,
+ active: chosen && bodyLive,
+ });
+ }
+
+ // A character is swept rather than solved, on its own path: it stands beside
+ // whatever body the entity has instead of competing for the slot.
+ const character = world.has(entity, CharacterController3D)
+ ? world.get(entity, CharacterController3D) as CharacterController3DData : null;
+ if (character) {
+ out.push({
+ component: 'CharacterController3D',
+ shape: { kind: 'capsule', radius: character.radius, halfHeight: character.halfHeight },
+ isSensor: false,
+ active: on(character),
+ });
+ }
+
+ return out;
+}
+
+function ring(radius: number, axis: 'xy' | 'xz' | 'yz', offset: Vec3, segments: number): Vec3[] {
+ const pts: Vec3[] = [];
+ for (let i = 0; i <= segments; i++) {
+ const a = (i / segments) * Math.PI * 2;
+ const c = Math.cos(a) * radius;
+ const s = Math.sin(a) * radius;
+ pts.push(axis === 'xy' ? { x: offset.x + c, y: offset.y + s, z: offset.z }
+ : axis === 'xz' ? { x: offset.x + c, y: offset.y, z: offset.z + s }
+ : { x: offset.x, y: offset.y + c, z: offset.z + s });
+ }
+ return pts;
+}
+
+/** Half-circle cap from angle 0 to π, in the plane the axis names, around `offset`. */
+function arc(radius: number, axis: 'xy' | 'zy', offset: Vec3, sign: 1 | -1, segments: number): Vec3[] {
+ const pts: Vec3[] = [];
+ for (let i = 0; i <= segments; i++) {
+ const a = (i / segments) * Math.PI;
+ const c = Math.cos(a) * radius;
+ const s = Math.sin(a) * radius * sign;
+ pts.push(axis === 'xy'
+ ? { x: offset.x + c, y: offset.y + s, z: offset.z }
+ : { x: offset.x, y: offset.y + s, z: offset.z + c });
+ }
+ return pts;
+}
+
+/**
+ * The shape's wireframe as entity-local polylines (world units, unrotated).
+ * A box gives its 12 edges; a sphere three great circles; a capsule two rings,
+ * four caps and the four lines between them.
+ */
+export function collider3DWireframe(shape: Collider3DShape, segments = COLLIDER3D_RING_SEGMENTS): Vec3[][] {
+ if (shape.kind === 'box') {
+ const { center: c, halfExtents: h } = shape;
+ const corner = (sx: number, sy: number, sz: number): Vec3 =>
+ ({ x: c.x + sx * h.x, y: c.y + sy * h.y, z: c.z + sz * h.z });
+ const face = (sy: number): Vec3[] => [
+ corner(-1, sy, -1), corner(1, sy, -1), corner(1, sy, 1), corner(-1, sy, 1), corner(-1, sy, -1),
+ ];
+ const posts: Vec3[][] = [];
+ for (const [sx, sz] of [[-1, -1], [1, -1], [1, 1], [-1, 1]] as const) {
+ posts.push([corner(sx, -1, sz), corner(sx, 1, sz)]);
+ }
+ return [face(-1), face(1), ...posts];
+ }
+
+ if (shape.kind === 'sphere') {
+ const r = shape.radius;
+ return [
+ ring(r, 'xy', ZERO, segments),
+ ring(r, 'xz', ZERO, segments),
+ ring(r, 'yz', ZERO, segments),
+ ];
+ }
+
+ // Capsule: Y-up, the axis Jolt's CapsuleShape uses, so a wireframe rotated by
+ // the entity lands on the shape the solver built.
+ const { radius: r, halfHeight: hh } = shape;
+ const top: Vec3 = { x: 0, y: hh, z: 0 };
+ const bottom: Vec3 = { x: 0, y: -hh, z: 0 };
+ const half = Math.max(2, Math.round(segments / 2));
+ const posts: Vec3[][] = [];
+ for (const [sx, sz] of [[1, 0], [-1, 0], [0, 1], [0, -1]] as const) {
+ posts.push([
+ { x: sx * r, y: -hh, z: sz * r },
+ { x: sx * r, y: hh, z: sz * r },
+ ]);
+ }
+ return [
+ ring(r, 'xz', top, segments),
+ ring(r, 'xz', bottom, segments),
+ arc(r, 'xy', top, 1, half),
+ arc(r, 'zy', top, 1, half),
+ arc(r, 'xy', bottom, -1, half),
+ arc(r, 'zy', bottom, -1, half),
+ ...posts,
+ ];
+}
+
+/**
+ * Local polylines placed in the world by an entity's position and rotation.
+ *
+ * Scale is deliberately left out: the solver builds the shape from the collider's
+ * own numbers, so a scaled entity still collides at its authored size and a gizmo
+ * that grew with the scale would be drawing a body that does not exist.
+ */
+export function placeCollider3DWireframe(lines: Vec3[][], position: Vec3, rotation: Quat): Vec3[][] {
+ return lines.map((line) => line.map((p) => {
+ const r = rotateByQuat(rotation, p);
+ return { x: position.x + r.x, y: position.y + r.y, z: position.z + r.z };
+ }));
+}
diff --git a/sdk/tests/physics3d-wireframe.test.ts b/sdk/tests/physics3d-wireframe.test.ts
new file mode 100644
index 000000000..48b0d644c
--- /dev/null
+++ b/sdk/tests/physics3d-wireframe.test.ts
@@ -0,0 +1,325 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file A 3D collider can be seen — and what is seen is what collides.
+ *
+ * The wireframe exists so an author can tell whether a shape is the size and
+ * place they meant. That only helps if it draws the shape the SOLVER built, so
+ * the shape-selection half of these checks runs the real stepPhysics3D over the
+ * same world and asserts the two agree: whichever `add*` the system called is
+ * the instance the reader marked active. Restating the priority order here
+ * instead would pass happily while the two drifted apart.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { Transform } from '../src/ecs/component';
+import type { TransformData } from '../src/ecs/component.generated';
+import {
+ RigidBody3D, BoxCollider3D, SphereCollider3D, CapsuleCollider3D, CharacterController3D,
+ MeshCollider3D,
+} from '../src/physics3d/Physics3DComponents';
+import {
+ readCollider3DShapes, collider3DWireframe, placeCollider3DWireframe,
+ type Collider3DShape,
+} from '../src/physics3d/ColliderShape3D';
+import { registerMeshCollision, releaseMeshCollision } from '../src/asset/meshCollision';
+import { stepPhysics3D, DEFAULT_PHYSICS3D_CONFIG } from '../src/physics3d/Physics3DSystem';
+import type { Physics3DWasmModule } from '../src/physics3d/Physics3DModule';
+import type { World } from '../src/ecs/world';
+import type { App } from '../src/app/app';
+import type { Entity, Vec3 } from '../src/types';
+
+/** Records which shape the system asked the module to build. */
+function fakeModule(): Physics3DWasmModule & { calls: string[] } {
+ const calls: string[] = [];
+ const heap = new Float32Array(1024);
+ const record = (name: string) => (...args: number[]): number => {
+ calls.push(name);
+ return args.length > 0 ? calls.length : calls.length;
+ };
+ return {
+ calls,
+ HEAPF32: heap,
+ HEAPU32: new Uint32Array(heap.buffer),
+ _physics3d_init: record('init'),
+ _physics3d_isReady: () => 1,
+ _physics3d_step: record('step'),
+ _physics3d_addBox: record('addBox'),
+ _physics3d_addSphere: record('addSphere'),
+ _physics3d_addCapsule: record('addCapsule'),
+ _physics3d_addMeshBody: record('addMeshBody'),
+ _physics3d_removeBody: record('removeBody'),
+ _physics3d_addCharacter: record('addCharacter'),
+ _physics3d_moveCharacter: record('moveCharacter'),
+ _physics3d_removeCharacter: record('removeCharacter'),
+ _physics3d_characterStates: () => 0,
+ _physics3d_characterStatesBytes: () => 0,
+ _physics3d_transforms: () => 0,
+ _physics3d_transformsBytes: () => 0,
+ _physics3d_contacts: () => 0,
+ _physics3d_contactsBytes: () => 0,
+ _malloc: () => 4,
+ _free: () => undefined,
+ } as unknown as Physics3DWasmModule & { calls: string[] };
+}
+
+function fakeWorld() {
+ const store = new Map<Entity, Map<unknown, Record<string, unknown>>>();
+ let next = 1;
+ return {
+ spawn(): Entity {
+ const e = next++ as Entity;
+ store.set(e, new Map());
+ return e;
+ },
+ insert<T>(e: Entity, def: unknown, data?: Partial<T>): T {
+ const defaults = (def as { _default?: object })._default ?? {};
+ const value = structuredClone({ ...defaults, ...(data ?? {}) });
+ store.get(e)!.set(def, value as Record<string, unknown>);
+ return value as T;
+ },
+ get(e: Entity, def: unknown): unknown { return store.get(e)?.get(def); },
+ has(e: Entity, def: unknown): boolean { return store.get(e)?.has(def) ?? false; },
+ valid(e: Entity): boolean { return store.has(e); },
+ queryEntities(defs: unknown[]): Entity[] {
+ return [...store.entries()]
+ .filter(([, comps]) => defs.every((d) => comps.has(d)))
+ .map(([e]) => e);
+ },
+ };
+}
+
+/** The module call each collider component turns into, so the two halves can be compared. */
+const CALL_FOR: Record<string, string> = {
+ BoxCollider3D: 'addBox',
+ SphereCollider3D: 'addSphere',
+ CapsuleCollider3D: 'addCapsule',
+ MeshCollider3D: 'addMeshBody',
+};
+
+function bounds(lines: Vec3[][]): { min: Vec3; max: Vec3 } {
+ const min = { x: Infinity, y: Infinity, z: Infinity };
+ const max = { x: -Infinity, y: -Infinity, z: -Infinity };
+ for (const line of lines) {
+ for (const p of line) {
+ min.x = Math.min(min.x, p.x); max.x = Math.max(max.x, p.x);
+ min.y = Math.min(min.y, p.y); max.y = Math.max(max.y, p.y);
+ min.z = Math.min(min.z, p.z); max.z = Math.max(max.z, p.z);
+ }
+ }
+ return { min, max };
+}
+
+const size = (lines: Vec3[][]): Vec3 => {
+ const b = bounds(lines);
+ return { x: b.max.x - b.min.x, y: b.max.y - b.min.y, z: b.max.z - b.min.z };
+};
+
+describe('what a 3D collider looks like', () => {
+ let world: ReturnType<typeof fakeWorld>;
+ let app: App;
+ let module: ReturnType<typeof fakeModule>;
+
+ beforeEach(() => {
+ world = fakeWorld();
+ app = { world } as unknown as App;
+ module = fakeModule();
+ });
+
+ const spawn = (withBody = true): Entity => {
+ const e = world.spawn();
+ world.insert<TransformData>(e, Transform, {
+ position: { x: 0, y: 0, z: 0 },
+ rotation: { x: 0, y: 0, z: 0, w: 1 },
+ scale: { x: 1, y: 1, z: 1 },
+ worldPosition: { x: 0, y: 0, z: 0 },
+ worldRotation: { x: 0, y: 0, z: 0, w: 1 },
+ worldScale: { x: 1, y: 1, z: 1 },
+ });
+ if (withBody) world.insert(e, RigidBody3D);
+ return e;
+ };
+
+ const read = (e: Entity) => readCollider3DShapes(world as unknown as World, e);
+
+ /** Which component the solver actually built a body from, per the real system. */
+ const built = (): string | null => {
+ module.calls.length = 0;
+ stepPhysics3D(app, module, new Map(), DEFAULT_PHYSICS3D_CONFIG);
+ const call = module.calls.find((c) => Object.values(CALL_FOR).includes(c));
+ return call ?? null;
+ };
+
+ describe('the shape it reports is the shape the world builds', () => {
+ it('marks the box active when box and sphere are both authored', () => {
+ const e = spawn();
+ world.insert(e, SphereCollider3D);
+ world.insert(e, BoxCollider3D);
+
+ const active = read(e).filter((i) => i.active);
+ expect(active).toHaveLength(1);
+ expect(CALL_FOR[active[0]!.component]).toBe(built());
+ });
+
+ it('follows the world past a disabled collider to the next one', () => {
+ const e = spawn();
+ world.insert(e, BoxCollider3D, { enabled: false });
+ world.insert(e, SphereCollider3D);
+
+ const active = read(e).filter((i) => i.active);
+ expect(active).toHaveLength(1);
+ expect(active[0]!.component).toBe('SphereCollider3D');
+ expect(built()).toBe('addSphere');
+ });
+
+ it('lets a mesh collider shadow a capsule, as the world does', () => {
+ registerMeshCollision(4242, {
+ positions: new Float32Array([0, 0, 0, 100, 0, 0, 0, 0, 100, 100, 0, 100]),
+ indices: new Uint32Array([0, 2, 1, 2, 3, 1]),
+ });
+ const e = spawn();
+ world.insert(e, MeshCollider3D, { mesh: 4242 });
+ world.insert(e, CapsuleCollider3D);
+
+ const active = read(e).filter((i) => i.active);
+ expect(active.map((i) => i.component)).toEqual(['MeshCollider3D']);
+ expect(built()).toBe('addMeshBody');
+ releaseMeshCollision(4242);
+ });
+
+ it('reports no active shape without a rigid body, and the world builds none', () => {
+ const e = spawn(false);
+ world.insert(e, BoxCollider3D);
+
+ expect(read(e)).toHaveLength(1); // still authorable, still drawn
+ expect(read(e)[0]!.active).toBe(false);
+ expect(built()).toBeNull();
+ });
+
+ it('reports no active shape for a disabled body', () => {
+ const e = spawn();
+ world.insert(e, RigidBody3D, { enabled: false });
+ world.insert(e, BoxCollider3D);
+
+ expect(read(e)[0]!.active).toBe(false);
+ expect(built()).toBeNull();
+ });
+
+ it('draws a character beside the body shape rather than instead of it', () => {
+ const e = spawn();
+ world.insert(e, BoxCollider3D);
+ world.insert(e, CharacterController3D);
+
+ const active = read(e).filter((i) => i.active).map((i) => i.component);
+ expect(active).toEqual(['BoxCollider3D', 'CharacterController3D']);
+ });
+
+ it('carries the sensor flag through, so an overlay can tell them apart', () => {
+ const e = spawn();
+ world.insert(e, SphereCollider3D, { isSensor: true });
+ expect(read(e)[0]!.isSensor).toBe(true);
+ });
+ });
+
+ describe('the wireframe', () => {
+ it('spans exactly the box it describes', () => {
+ const shape: Collider3DShape = {
+ kind: 'box',
+ halfExtents: { x: 10, y: 20, z: 30 },
+ center: { x: 0, y: 0, z: 0 },
+ };
+ expect(size(collider3DWireframe(shape))).toEqual({ x: 20, y: 40, z: 60 });
+ });
+
+ it('gives the box its twelve edges', () => {
+ const shape: Collider3DShape = {
+ kind: 'box', halfExtents: { x: 1, y: 1, z: 1 }, center: { x: 0, y: 0, z: 0 },
+ };
+ const lines = collider3DWireframe(shape);
+ const segments = lines.reduce((n, l) => n + l.length - 1, 0);
+ expect(segments).toBe(12);
+ const corners = new Set(lines.flat().map((p) => `${p.x},${p.y},${p.z}`));
+ expect(corners.size).toBe(8);
+ });
+
+ it('keeps every sphere point on the sphere', () => {
+ const lines = collider3DWireframe({ kind: 'sphere', radius: 7 });
+ for (const p of lines.flat()) {
+ expect(Math.hypot(p.x, p.y, p.z)).toBeCloseTo(7, 5);
+ }
+ expect(size(lines)).toEqual({ x: 14, y: 14, z: 14 });
+ });
+
+ it('is as tall AND as wide as the capsule', () => {
+ // Height alone cannot tell radius from halfHeight: 30 + 50 and 50 + 30
+ // stand the same. The width is what separates them.
+ const lines = collider3DWireframe({ kind: 'capsule', radius: 30, halfHeight: 50 });
+ const s = size(lines);
+ expect(s.y).toBeCloseTo(2 * (30 + 50), 3);
+ expect(s.x).toBeCloseTo(60, 3);
+ expect(s.z).toBeCloseTo(60, 3);
+ });
+
+ it('bulges only at the caps of the capsule', () => {
+ const lines = collider3DWireframe({ kind: 'capsule', radius: 10, halfHeight: 40 });
+ for (const p of lines.flat()) {
+ const lateral = Math.hypot(p.x, p.z);
+ if (Math.abs(p.y) <= 40) expect(lateral).toBeLessThanOrEqual(10.001);
+ else {
+ const overshoot = Math.abs(p.y) - 40;
+ expect(lateral ** 2 + overshoot ** 2).toBeLessThanOrEqual(10 ** 2 + 1e-3);
+ }
+ }
+ });
+
+ it('takes the mesh collider from the triangles that will be collided against', () => {
+ registerMeshCollision(99, {
+ positions: new Float32Array([-4, 0, -2, 6, 8, -2, 6, 0, 10]),
+ indices: new Uint32Array([0, 1, 2]),
+ });
+ const e = spawn();
+ world.insert(e, MeshCollider3D, { mesh: 99 });
+
+ const shape = read(e)[0]!.shape;
+ expect(shape.kind).toBe('box');
+ if (shape.kind !== 'box') throw new Error('unreachable');
+ expect(shape.center).toEqual({ x: 1, y: 4, z: 4 });
+ expect(shape.halfExtents).toEqual({ x: 5, y: 4, z: 6 });
+ releaseMeshCollision(99);
+ });
+
+ it('draws nothing for a mesh whose triangles never loaded', () => {
+ const e = spawn();
+ world.insert(e, MeshCollider3D, { mesh: 12345 });
+ expect(read(e)).toHaveLength(0);
+ });
+ });
+
+ describe('placing it in the world', () => {
+ it('turns the box with the entity', () => {
+ const shape: Collider3DShape = {
+ kind: 'box', halfExtents: { x: 10, y: 20, z: 30 }, center: { x: 0, y: 0, z: 0 },
+ };
+ const half = Math.PI / 4; // 90° about Y
+ const turned = placeCollider3DWireframe(
+ collider3DWireframe(shape),
+ { x: 0, y: 0, z: 0 },
+ { x: 0, y: Math.sin(half), z: 0, w: Math.cos(half) },
+ );
+ const s = size(turned);
+ expect(s.x).toBeCloseTo(60, 3); // the 30-deep half is now the wide one
+ expect(s.y).toBeCloseTo(40, 3);
+ expect(s.z).toBeCloseTo(20, 3);
+ });
+
+ it('lands the shape on the entity', () => {
+ const placed = placeCollider3DWireframe(
+ collider3DWireframe({ kind: 'sphere', radius: 5 }),
+ { x: 100, y: -50, z: 20 },
+ { x: 0, y: 0, z: 0, w: 1 },
+ );
+ const b = bounds(placed);
+ expect(b.min).toEqual({ x: 95, y: -55, z: 15 });
+ expect(b.max).toEqual({ x: 105, y: -45, z: 25 });
+ });
+ });
+});