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(editor): a 3D joint shows what it holds and how it is free
esengine912a3e65e6a7
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 needsagainst 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 awireframe of every 3D collider — box, sphere, capsule, character, and the boundsof a mesh collider — turned the way its entity is. A 3D shape is nothing thediff --git a/desktop/scripts/editor-checks/joint3d-gizmo.mjs b/desktop/scripts/editor-checks/joint3d-gizmo.mjsnew file mode 100644index 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.tsindex 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.tsxindex 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'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 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.jsonindex 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.mdindex 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; }): () => voiddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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; }): () => voiddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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; }): () => voiddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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; }): () => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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; }): () => voiddiff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.tsindex 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.tsindex 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 × tconst tx = 2 * (q.y * v.z - q.z * v.y);diff --git a/sdk/src/physics3d/Physics3DJoints.ts b/sdk/src/physics3d/Physics3DJoints.tsindex 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;