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(editor): a 3D joint shows what it holds and how it is free

esengine912a3e65e6a7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 63dd7ef72..4c4760659 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -32,6 +32,11 @@ published separately; it ships inside the editor.
chain — what a door needs against its own frame, and what a ragdoll needs
against itself.
+- **A 3D joint shows what it holds.** The viewport draws the link from a joint's
+ anchor to the body it names, and — for a hinge or a slider — the axis it is
+ free about. A joint has no shape to see: which body and which axis live only in
+ the numbers, and the axis is the half no position on screen can imply.
+
- **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
diff --git a/desktop/scripts/editor-checks/joint3d-gizmo.mjs b/desktop/scripts/editor-checks/joint3d-gizmo.mjs
new file mode 100644
index 000000000..22bde9b27
--- /dev/null
+++ b/desktop/scripts/editor-checks/joint3d-gizmo.mjs
@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file joint3d-gizmo — a 3D joint shows what it holds, and about what axis.
+ *
+ * A joint has no shape to see. Which body it holds and which axis it is free
+ * about are only in the numbers, and the axis is the half that no position on
+ * screen can imply — which is why this measures the picture's HEIGHT: the link
+ * is horizontal by construction, so everything tall in it is the axis marker.
+ */
+import { makeProject, checker } from '../lib/editorDriver.mjs';
+
+/** The bob is 150 to the right of the anchor; the hinge axis is upright. */
+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: 'Anchor', parent: null, children: [], visible: true,
+ components: [
+ { type: 'Transform', data: { position: { x: -75, y: 0, z: 0 } } },
+ { type: 'RigidBody3D', data: { bodyType: 0 } },
+ { type: 'BoxCollider3D', data: { halfExtents: { x: 10, y: 10, z: 10 } } },
+ ],
+ },
+ {
+ id: 2, name: 'Bob', parent: null, children: [], visible: true,
+ components: [
+ { type: 'Transform', data: { position: { x: 75, y: 0, z: 0 } } },
+ { type: 'RigidBody3D', data: { bodyType: 2 } },
+ { type: 'BoxCollider3D', data: { halfExtents: { x: 10, y: 10, z: 10 } } },
+ {
+ type: 'HingeJoint3D',
+ data: { connectedEntity: 1, anchor: { x: 0, y: 0, z: 0 }, axis: { x: 0, y: 1, z: 0 } },
+ },
+ ],
+ },
+ ],
+}, null, 1);
+
+export const name = 'joint3d-gizmo';
+export const describes = 'a 3D joint is drawn in the viewport, link and free axis both';
+
+/** Pixels near the joint gizmo colour (--gizmo-joint #c58cff): violet, so red and
+ * blue both well above green — nothing else in the viewport is. */
+function jointBox(png) {
+ let minX = Infinity, minY = Infinity, maxX = -1, maxY = -1, count = 0;
+ 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[2] < 120 || p[0] < 80 || p[2] - p[1] < 40 || p[0] - p[1] < 20) 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: 'Joint3DGizmo', 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 shot = await ed.screenshot('joint3d-on');
+
+ const box = jointBox(shot);
+ if (!check(box != null, 'no joint gizmo anywhere in the viewport')) return check.failures;
+ if (!check(box.count > 60, `only ${box.count} joint pixels — nothing that could be a link`)) {
+ return check.failures;
+ }
+
+ // The link spans 150 world units horizontally; the axis marker spans 120
+ // vertically. A gizmo that drew the link alone would be a flat line.
+ const ratio = box.h / box.w;
+ check(
+ ratio > 0.45 && ratio < 1.1,
+ `the gizmo is ${box.w}×${box.h} (${ratio.toFixed(2)}) — with the 120-unit axis marker `
+ + 'over a 150-unit link it should be roughly 0.8 tall; a flat one means the axis is missing',
+ );
+
+ // And it is the JOINT that is drawn, not the bodies: pointing it at nothing
+ // takes the whole gizmo away.
+ await ed.call('set_field', {
+ entity: 2, component: 'HingeJoint3D', key: 'connectedEntity', type: 'entity', value: -1,
+ }, 30000);
+ await ed.sleep(900);
+ const gone = jointBox(await ed.screenshot('joint3d-off'));
+ check(
+ (gone?.count ?? 0) < box.count * 0.25,
+ `a joint connected to nothing still drew ${gone?.count ?? 0} of ${box.count} pixels — the `
+ + 'gizmo is not reading the joint it claims to draw',
+ );
+
+ return check.failures;
+}
diff --git a/desktop/src/engine/ViewportController.ts b/desktop/src/engine/ViewportController.ts
index 60632d184..d79e0bcce 100644
--- a/desktop/src/engine/ViewportController.ts
+++ b/desktop/src/engine/ViewportController.ts
@@ -13,6 +13,7 @@ import {
readColliderShapes, colliderShapeOutline, shapeCenter,
BoxCollider3D, SphereCollider3D, CapsuleCollider3D, MeshCollider3D, CharacterController3D,
readCollider3DShapes, collider3DWireframe, placeCollider3DWireframe,
+ readJoint3D, rotateVec3ByQuat,
layerOrderOf,
editorViewHalfHeight, editorViewHalfExtent, setEditorViewHalfHeight, EDITOR_UI_ANCHOR,
entityWorldBox, uiNodeWorldBox, meshWorldBox, editorViewIsOrbited,
@@ -37,6 +38,9 @@ import {
type PickCandidate,
} from './viewportMath';
+// Half-length of a 3D joint's axis marker, in world units — long enough to read
+// against a body, short enough not to look like the link itself.
+const JOINT3D_AXIS_WORLD_HALF = 60;
// World half-size of the pick/outline box for entities without renderable bounds
// (cameras, lights, empties) — so they're click-selectable like any sprite.
const ICON_WORLD_HALF = 24;
@@ -1169,6 +1173,65 @@ export const ViewportController = {
return { outline, outlineSensor, outlineInactive };
},
+ /** Ids of entities declaring a 3D joint — the 3D joint-gizmo set. */
+ joint3DIds(): EntityId[] {
+ const world = EngineHost.world;
+ if (!world) return [];
+ const out: EntityId[] = [];
+ for (const e of world.getAllEntities()) {
+ if (!world.has(e, Transform)) continue;
+ if (readJoint3D(world as unknown as Parameters<typeof readJoint3D>[0], e)) out.push(e);
+ }
+ return out;
+ },
+
+ /**
+ * Screen-space gizmo for a 3D joint: the link from its anchor to the body it
+ * names, the anchor itself, and — for a hinge or slider — the axis it is free
+ * about, which is the half no position can show. Null when the joint names
+ * nothing that exists, since a link to the origin would read as a joint.
+ */
+ getJoint3DGizmo(id: EntityId): { ax: number; ay: number; bx: number; by: number; axis: string; on: boolean } | null {
+ const world = EngineHost.world;
+ if (!world || !world.valid(id) || !world.has(id, Transform)) return null;
+ const joint = readJoint3D(world as unknown as Parameters<typeof readJoint3D>[0], id);
+ if (!joint) return null;
+ const other = joint.connectedEntity as EntityId;
+ if (!world.valid(other) || !world.has(other, Transform)) return null;
+
+ const place = (entity: EntityId, local: { x: number; y: number; z: number } | null) => {
+ const t = world.get(entity, Transform);
+ const p = t.worldPosition as { x: number; y: number; z: number };
+ if (!local) return p;
+ const r = rotateVec3ByQuat(t.worldRotation as { x: number; y: number; z: number; w: number }, local);
+ return { x: p.x + r.x, y: p.y + r.y, z: p.z + r.z };
+ };
+
+ const near = place(id, joint.anchor);
+ const far = place(other, joint.connectedAnchor);
+ const a = this.worldToClient(near.x, near.y, near.z);
+ const b = this.worldToClient(far.x, far.y, far.z);
+ if (!a || !b) return null;
+
+ let axis = '';
+ if (joint.axis) {
+ const t = world.get(id, Transform);
+ const dir = rotateVec3ByQuat(t.worldRotation as { x: number; y: number; z: number; w: number }, joint.axis);
+ const len = Math.hypot(dir.x, dir.y, dir.z);
+ if (len > 1e-6) {
+ const s = JOINT3D_AXIS_WORLD_HALF / len;
+ const ends = [1, -1].map((sign) =>
+ this.worldToClient(near.x + dir.x * s * sign, near.y + dir.y * s * sign,
+ near.z + dir.z * s * sign));
+ if (ends[0] && ends[1]) {
+ axis = `M${ends[0].x.toFixed(1)},${ends[0].y.toFixed(1)}`
+ + `L${ends[1].x.toFixed(1)},${ends[1].y.toFixed(1)}`;
+ }
+ }
+ }
+ return { ax: a.x, ay: a.y, bx: b.x, by: b.y, axis, on: joint.enabled };
+ },
+
/**
* 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 ae7c34930..6d6208da7 100644
--- a/desktop/src/panels/Viewport.tsx
+++ b/desktop/src/panels/Viewport.tsx
@@ -1019,6 +1019,13 @@ export function Viewport() {
() => (engine.status === 'ready' && showColliders ? ViewportController.collider3DIds() : []),
[structRev, worldRev, engine.status, showColliders],
);
+ // 3D joints: which body is held to which, and about what axis — the half of a
+ // joint no position can show. On the physics switch, like the 2D joint gizmos.
+ const joint3DRefs = useRef(new Map<number, SVGSVGElement | null>());
+ const joint3DIds = useMemo(
+ () => (engine.status === 'ready' && showColliders ? ViewportController.joint3DIds() : []),
+ [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
@@ -1757,6 +1764,27 @@ export function Viewport() {
}
}
+ // 3D joints: anchor → connected body, plus the hinge/slider axis.
+ for (const [jid, svg] of joint3DRefs.current) {
+ if (!svg) continue;
+ const jg = camsOn ? ViewportController.getJoint3DGizmo(jid) : null;
+ svg.style.opacity = jg ? (jg.on ? '1' : '0.4') : '0';
+ if (!jg) continue;
+ const link = svg.querySelector('.j3-link') as SVGLineElement | null;
+ if (link) {
+ link.setAttribute('x1', String(jg.ax));
+ link.setAttribute('y1', String(jg.ay));
+ link.setAttribute('x2', String(jg.bx));
+ link.setAttribute('y2', String(jg.by));
+ }
+ const anchor = svg.querySelector('.j3-anchor') as SVGCircleElement | null;
+ if (anchor) {
+ anchor.setAttribute('cx', String(jg.ax));
+ anchor.setAttribute('cy', String(jg.ay));
+ }
+ (svg.querySelector('.j3-axis') as SVGPathElement | null)?.setAttribute('d', jg.axis);
+ }
+
// 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 /
@@ -2646,6 +2674,25 @@ export function Viewport() {
</svg>
))}
+ {/* 3D joint gizmos: the link to the body it holds, the anchor it holds at,
+ and the axis a hinge or slider is free along. */}
+ {joint3DIds.map((id) => (
+ <svg
+ key={id}
+ ref={(el) => {
+ if (el) joint3DRefs.current.set(id, el);
+ else joint3DRefs.current.delete(id);
+ }}
+ className="viewport__joint3d-gizmo"
+ data-src={SceneModel.sourceFor(id)}
+ aria-hidden="true"
+ >
+ <line className="j3-link" x1="0" y1="0" x2="0" y2="0" />
+ <path className="j3-axis" d="" />
+ <circle className="j3-anchor" cx="0" cy="0" r="4" />
+ </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 19a901303..0ccba6d5d 100644
--- a/desktop/src/theme/app.css
+++ b/desktop/src/theme/app.css
@@ -722,6 +722,36 @@ body.thumb-capture .viewport > :not(.viewport__stage):not(.viewport__play) {
stroke-width: 1.5;
stroke-dasharray: 5 4;
}
+/* 3D joints share the joint colour: the concept is the same, and a scene is in
+ one world or the other, so the two sets never crowd each other. */
+.viewport__joint3d-gizmo {
+ position: absolute;
+ inset: 0;
+ width: 100%;
+ height: 100%;
+ z-index: 2;
+ pointer-events: none;
+ overflow: visible;
+ transition: opacity var(--t-fast);
+}
+.viewport__joint3d-gizmo .j3-link {
+ stroke: var(--gizmo-joint);
+ stroke-width: 1.5;
+ stroke-dasharray: 5 4;
+}
+/* The free axis, solid against the dashed link — a hinge turns about it, a
+ slider travels along it, and nothing else in the picture says which. */
+.viewport__joint3d-gizmo .j3-axis {
+ fill: none;
+ stroke: var(--gizmo-joint);
+ stroke-width: 2;
+ stroke-linecap: round;
+}
+.viewport__joint3d-gizmo .j3-anchor {
+ fill: var(--gizmo-joint);
+ stroke: var(--srf-2);
+ stroke-width: 1.25;
+}
.viewport__joint-gizmo .jt-a,
.viewport__joint-gizmo .jt-b {
fill: var(--gizmo-joint);
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 86c75ff1f..19ec9d873 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 113,
"beta": 72,
- "experimental": 1555,
+ "experimental": 1558,
"deprecated": 3
},
- "total": 1740,
+ "total": 1743,
"subsystems": [
{
"id": "ecs",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index ef5bef6fd..25a12fd45 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 · 65 beta · 1440 experimental · 3 deprecated
+Symbols: 113 public · 65 beta · 1443 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -3813,6 +3813,16 @@ world: World
(typeof InterpType)[keyof typeof InterpType]
```
+## Joint3DShape — interface @experimental
+```
+anchor: Vec3 | null
+axis: Vec3 | null
+connectedAnchor: Vec3 | null
+connectedEntity: number
+enabled: boolean
+type: string
+```
+
## JsonResult — interface @experimental
```
data: T
@@ -10992,6 +11002,11 @@ PrefabsPlugin
(data: Record<string, unknown>, path: string): unknown
```
+## readJoint3D — function @experimental
+```
+(world: World, entity: number): Joint3DShape | null
+```
+
## readPtrField — function @experimental
```
(f32: Float32Array, u32: Uint32Array, u8: Uint8Array, ptr: number, field: PtrFieldDesc): unknown
@@ -11242,6 +11257,11 @@ ReplicationPlugin
(s: TileStamp): TileStamp
```
+## rotateVec3ByQuat — function @experimental
+```
+(q: Quat, v: Vec3): Vec3
+```
+
## runHeadless — function @beta
```
(app: App, options?: { fps?: number; }): () => void
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 8d65bf6e9..106d8d62f 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 · 70 beta · 1459 experimental · 3 deprecated
+Symbols: 113 public · 70 beta · 1462 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -3821,6 +3821,16 @@ world: World
(typeof InterpType)[keyof typeof InterpType]
```
+## Joint3DShape — interface @experimental
+```
+anchor: Vec3 | null
+axis: Vec3 | null
+connectedAnchor: Vec3 | null
+connectedEntity: number
+enabled: boolean
+type: string
+```
+
## JsonResult — interface @experimental
```
data: T
@@ -11235,6 +11245,11 @@ PrefabsPlugin
(data: Record<string, unknown>, path: string): unknown
```
+## readJoint3D — function @experimental
+```
+(world: World, entity: number): Joint3DShape | null
+```
+
## readPtrField — function @experimental
```
(f32: Float32Array, u32: Uint32Array, u8: Uint8Array, ptr: number, field: PtrFieldDesc): unknown
@@ -11485,6 +11500,11 @@ ReplicationPlugin
(s: TileStamp): TileStamp
```
+## rotateVec3ByQuat — function @experimental
+```
+(q: Quat, v: Vec3): Vec3
+```
+
## runHeadless — function @beta
```
(app: App, options?: { fps?: number; }): () => void
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 3ffe9c439..f19ebc139 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 · 67 beta · 1439 experimental · 3 deprecated
+Symbols: 113 public · 67 beta · 1442 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -3808,6 +3808,16 @@ world: World
(typeof InterpType)[keyof typeof InterpType]
```
+## Joint3DShape — interface @experimental
+```
+anchor: Vec3 | null
+axis: Vec3 | null
+connectedAnchor: Vec3 | null
+connectedEntity: number
+enabled: boolean
+type: string
+```
+
## JsonResult — interface @experimental
```
data: T
@@ -10997,6 +11007,11 @@ PrefabsPlugin
(data: Record<string, unknown>, path: string): unknown
```
+## readJoint3D — function @experimental
+```
+(world: World, entity: number): Joint3DShape | null
+```
+
## readPtrField — function @experimental
```
(f32: Float32Array, u32: Uint32Array, u8: Uint8Array, ptr: number, field: PtrFieldDesc): unknown
@@ -11247,6 +11262,11 @@ ReplicationPlugin
(s: TileStamp): TileStamp
```
+## rotateVec3ByQuat — function @experimental
+```
+(q: Quat, v: Vec3): Vec3
+```
+
## runHeadless — function @beta
```
(app: App, options?: { fps?: number; }): () => void
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 16f002452..7d7ef1068 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 · 65 beta · 1460 experimental · 3 deprecated
+Symbols: 113 public · 65 beta · 1463 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -3808,6 +3808,16 @@ world: World
(typeof InterpType)[keyof typeof InterpType]
```
+## Joint3DShape — interface @experimental
+```
+anchor: Vec3 | null
+axis: Vec3 | null
+connectedAnchor: Vec3 | null
+connectedEntity: number
+enabled: boolean
+type: string
+```
+
## JsonResult — interface @experimental
```
data: T
@@ -11247,6 +11257,11 @@ PrefabsPlugin
(data: Record<string, unknown>, path: string): unknown
```
+## readJoint3D — function @experimental
+```
+(world: World, entity: number): Joint3DShape | null
+```
+
## readPtrField — function @experimental
```
(f32: Float32Array, u32: Uint32Array, u8: Uint8Array, ptr: number, field: PtrFieldDesc): unknown
@@ -11497,6 +11512,11 @@ ReplicationPlugin
(s: TileStamp): TileStamp
```
+## rotateVec3ByQuat — function @experimental
+```
+(q: Quat, v: Vec3): Vec3
+```
+
## runHeadless — function @beta
```
(app: App, options?: { fps?: number; }): () => void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 8ab60d979..627d0589a 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 · 65 beta · 1450 experimental · 3 deprecated
+Symbols: 113 public · 65 beta · 1453 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -3815,6 +3815,16 @@ world: World
(typeof InterpType)[keyof typeof InterpType]
```
+## Joint3DShape — interface @experimental
+```
+anchor: Vec3 | null
+axis: Vec3 | null
+connectedAnchor: Vec3 | null
+connectedEntity: number
+enabled: boolean
+type: string
+```
+
## JsonResult — interface @experimental
```
data: T
@@ -11019,6 +11029,11 @@ PrefabsPlugin
(data: Record<string, unknown>, path: string): unknown
```
+## readJoint3D — function @experimental
+```
+(world: World, entity: number): Joint3DShape | null
+```
+
## readPtrField — function @experimental
```
(f32: Float32Array, u32: Uint32Array, u8: Uint8Array, ptr: number, field: PtrFieldDesc): unknown
@@ -11269,6 +11284,11 @@ ReplicationPlugin
(s: TileStamp): TileStamp
```
+## rotateVec3ByQuat — function @experimental
+```
+(q: Quat, v: Vec3): Vec3
+```
+
## runHeadless — function @beta
```
(app: App, options?: { fps?: number; }): () => void
diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.ts
index f946d1316..24ab97233 100644
--- a/sdk/src/core-runtime.ts
+++ b/sdk/src/core-runtime.ts
@@ -213,10 +213,16 @@ export {
type FixedJoint3DData,
} from './physics3d/Physics3DJoints';
+export {
+ readJoint3D,
+ type Joint3DShape,
+} from './physics3d/Physics3DJoints';
+
export {
readCollider3DShapes,
collider3DWireframe,
placeCollider3DWireframe,
+ rotateVec3ByQuat,
COLLIDER3D_RING_SEGMENTS,
type Collider3DShape,
type Collider3DInstance,
diff --git a/sdk/src/physics3d/ColliderShape3D.ts b/sdk/src/physics3d/ColliderShape3D.ts
index 5d2c5bdf1..9e474fe07 100644
--- a/sdk/src/physics3d/ColliderShape3D.ts
+++ b/sdk/src/physics3d/ColliderShape3D.ts
@@ -58,7 +58,8 @@ export interface Collider3DInstance {
const ZERO: Vec3 = { x: 0, y: 0, z: 0 };
-/** @internal Shared with the joint wiring, which turns anchors and axes the same way. */
+/** Turn a vector by a rotation — what places an anchor, an axis or a wireframe
+ * vertex in the world, and the one piece of 3D maths every visualizer needs. */
export function rotateVec3ByQuat(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);
diff --git a/sdk/src/physics3d/Physics3DJoints.ts b/sdk/src/physics3d/Physics3DJoints.ts
index eb9168402..d0634a451 100644
--- a/sdk/src/physics3d/Physics3DJoints.ts
+++ b/sdk/src/physics3d/Physics3DJoints.ts
@@ -16,6 +16,7 @@
import { defineComponent, Transform } from '../ecs/component';
import type { TransformData } from '../ecs/component.generated';
import type { App } from '../app/app';
+import type { World } from '../ecs/world';
import type { Entity, Vec3 } from '../types';
import type { Physics3DWasmModule } from './Physics3DModule';
import { rotateVec3ByQuat } from './ColliderShape3D';
@@ -197,6 +198,41 @@ function jointOn(app: App, entity: Entity): { def: Joint3DDef; data: AnyJoint }
return null;
}
+/** One joint as a visualizer needs it: which rule, what it connects, and the
+ * local geometry that positions it. Anchors and axes are in the declaring
+ * entity's own space, in world units. */
+export interface Joint3DShape {
+ type: string;
+ connectedEntity: number;
+ /** Null for a fixed joint, which has no anchor — the pose is the joint. */
+ anchor: Vec3 | null;
+ /** The far anchor, on the connected entity. Distance joints only. */
+ connectedAnchor: Vec3 | null;
+ /** The axis a hinge turns about or a slider travels along. */
+ axis: Vec3 | null;
+ enabled: boolean;
+}
+
+/**
+ * The joint an entity declares, in the shape a gizmo draws — the SAME first-wins
+ * choice the world makes, so an editor never draws a joint the solver ignored.
+ */
+export function readJoint3D(world: World, entity: number): Joint3DShape | null {
+ for (const def of JOINT3D_TYPES) {
+ if (!world.has(entity, def)) continue;
+ const d = world.get(entity, def) as unknown as Record<string, unknown>;
+ return {
+ type: def._name,
+ connectedEntity: d.connectedEntity as number,
+ anchor: (d.anchor as Vec3 | undefined) ?? null,
+ connectedAnchor: (d.connectedAnchor as Vec3 | undefined) ?? null,
+ axis: (d.axis as Vec3 | undefined) ?? null,
+ enabled: d.enabled !== false,
+ };
+ }
+ return null;
+}
+
/** A local (world-unit) point on `entity`, in metres, where the solver wants it. */
function anchorInMetres(app: App, entity: Entity, local: Vec3, ppu: number): Vec3 {
const t = app.world.get(entity, Transform) as TransformData | undefined;