A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(physics): a 3D collider can be seen while it is authored
esengine7f7b733f4ba7
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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` resourceanswers `sphereCast`, `overlapSphere` and `overlapBox` alongside `raycast`, allin world units and all narrowable by layer. A ray is infinitely thin and slipsdiff --git a/desktop/scripts/editor-checks/collider3d-gizmo.mjs b/desktop/scripts/editor-checks/collider3d-gizmo.mjsnew file mode 100644index 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.tsindex 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.tsxindex 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'sbody ↔ anchor on the connected body), plus the prismatic/wheel slide axisand the motor joint's target-velocity arrow. rAF-positioned, physics flag. */}diff --git a/desktop/src/theme/app.css b/desktop/src/theme/app.cssindex 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 — solidoutlines, dashed sensors, one-way arrows — all in ONE viewport-spanning SVG whosepath data the rAF writes each frame. Shares the collider colour: tile and entitydiff --git a/docs/astro/src/content/docs/gameplay/physics-3d.mdx b/docs/astro/src/content/docs/gameplay/physics-3d.mdxindex 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>+## CharactersA `CharacterController3D` replaces a `RigidBody3D` rather than accompanying one: adiff --git a/docs/astro/src/content/docs/zh-cn/gameplay/physics-3d.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/physics-3d.mdxindex 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.mdindex 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 = 0BuiltinComponentDef<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 | undefined16```+## COLLIDER3D_RING_SEGMENTS — const @experimental+```+24+```+## COLLISION_BRUSHES — const @experimental```CollisionBrush[]@@ -1625,6 +1644,21 @@ width: numberBuiltinComponentDef<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 = 2Nothing = 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 | ImageSegmentBuiltinComponentDef<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: numberOmit<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 @@ ParticlePluginPerceptionPlugin```+## 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.mdindex 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 = 0BuiltinComponentDef<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 | undefined16```+## COLLIDER3D_RING_SEGMENTS — const @experimental+```+24+```+## COLLISION_BRUSHES — const @experimental```CollisionBrush[]@@ -1625,6 +1644,21 @@ width: numberBuiltinComponentDef<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 = 2Nothing = 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 | ImageSegmentBuiltinComponentDef<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: numberOmit<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 @@ ParticlePluginPerceptionPlugin```+## 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.mdindex 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 = 0BuiltinComponentDef<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 | undefined16```+## COLLIDER3D_RING_SEGMENTS — const @experimental+```+24+```+## COLLISION_BRUSHES — const @experimental```CollisionBrush[]@@ -1620,6 +1639,21 @@ width: numberBuiltinComponentDef<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 = 2Nothing = 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 | ImageSegmentBuiltinComponentDef<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: numberOmit<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 @@ ParticlePluginPerceptionPlugin```+## 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.mdindex 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 = 0BuiltinComponentDef<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 | undefined16```+## COLLIDER3D_RING_SEGMENTS — const @experimental+```+24+```+## COLLISION_BRUSHES — const @experimental```CollisionBrush[]@@ -1620,6 +1639,21 @@ width: numberBuiltinComponentDef<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 = 2Nothing = 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 | ImageSegmentBuiltinComponentDef<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: numberOmit<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 @@ ParticlePluginPerceptionPlugin```+## 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.mdindex 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 = 0BuiltinComponentDef<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 | undefined16```+## COLLIDER3D_RING_SEGMENTS — const @experimental+```+24+```+## COLLISION_BRUSHES — const @experimental```CollisionBrush[]@@ -1620,6 +1639,21 @@ width: numberBuiltinComponentDef<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 = 2Nothing = 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 | ImageSegmentBuiltinComponentDef<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: numberOmit<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 @@ ParticlePluginPerceptionPlugin```+## 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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 });+ });+ });+});