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): physics gizmos - one-way arrows, joint links, offset-true drags

yhh15494a15bca2
diff --git a/desktop/src/engine/ViewportController.ts b/desktop/src/engine/ViewportController.ts
index 4aed10b6f..0a0e53d9d 100644
--- a/desktop/src/engine/ViewportController.ts
+++ b/desktop/src/engine/ViewportController.ts
@@ -2,7 +2,8 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import {
Camera, CameraView, EditorView, Light2D, Sprite, Transform, Canvas, BoxCollider, CircleCollider,
- ParticleEmitter,
+ ParticleEmitter, OneWayPlatform,
+ RevoluteJoint, DistanceJoint, PrismaticJoint, WeldJoint, WheelJoint, MotorJoint,
UINode, UICameraInfo, screenToUiWorld, uiWorldToScreen, uiPickAllWorld, type UICameraData,
} from 'esengine';
import type { EntityId } from '@/types';
@@ -27,6 +28,25 @@ const ICON_WORLD_HALF = 24;
// foreground gizmo (camera/light) wins a tie against a big sprite beneath it.
const ICON_PICK_LAYER = 1e6;
+// The scene-authored joint components, each drawn as an anchor-to-anchor link gizmo.
+// (The mouse/drag joint is imperative runtime API only — no component, nothing to draw.)
+const JOINT_GIZMO_DEFS = {
+ RevoluteJoint, DistanceJoint, PrismaticJoint, WeldJoint, WheelJoint, MotorJoint,
+} as const;
+export type JointGizmoType = keyof typeof JOINT_GIZMO_DEFS;
+
+// The joint fields the gizmo reads. Anchors are world PIXELS in each body's local
+// frame (PhysicsSystem converts to meters with ×invPpu); MotorJoint has no anchors
+// (it drives the relative body transform), so both default to the body origin.
+interface JointGizmoData {
+ connectedEntity: number;
+ anchorA?: { x: number; y: number };
+ anchorB?: { x: number; y: number };
+ axis?: { x: number; y: number };
+ linearVelocity?: { x: number; y: number };
+ enabled?: boolean;
+}
+
// Structural shape of the engine's CameraView resource (screen<->world).
interface CameraViewLike {
screenToWorld(x: number, y: number): { x: number; y: number } | null;
@@ -533,15 +553,41 @@ export const ViewportController = {
return null;
},
+ /**
+ * Offset-aware world center of the entity's box/circle collider (world px) — the
+ * point radius/size drags measure from, matching where the gizmo shape is drawn.
+ * Falls back to the entity origin when there's no collider.
+ */
+ colliderWorldCenter(id: EntityId): { x: number; y: number } | null {
+ const world = EngineHost.world;
+ if (!world || !world.valid(id) || !world.has(id, Transform)) return null;
+ const t = world.get(id, Transform);
+ const off = world.has(id, BoxCollider)
+ ? (world.get(id, BoxCollider) as { offset: { x: number; y: number } }).offset
+ : world.has(id, CircleCollider)
+ ? (world.get(id, CircleCollider) as { offset: { x: number; y: number } }).offset
+ : null;
+ if (!off || (off.x === 0 && off.y === 0)) return { x: t.worldPosition.x, y: t.worldPosition.y };
+ const ppu = this.colliderPixelsPerUnit();
+ const rot = quatAngleZ(t.worldRotation as { w: number; x: number; y: number; z: number });
+ return {
+ x: t.worldPosition.x + (off.x * ppu) * Math.cos(rot) - (off.y * ppu) * Math.sin(rot),
+ y: t.worldPosition.y + (off.x * ppu) * Math.sin(rot) + (off.y * ppu) * Math.cos(rot),
+ };
+ },
+
/**
* Screen-space collider outline for the gizmo: a 4-corner polygon (box) or a
* center + radius (circle), in CSS px. The collider lives at the entity's world
- * transform + its (meter) offset, scaled to pixels by pixelsPerUnit.
+ * transform + its (meter) offset, scaled to pixels by pixelsPerUnit. `cx/cy` is
+ * the shape's screen center for both kinds. `oneWay` is the OneWayPlatform solid-
+ * side normal as a screen unit vector (world-space — contact normals don't rotate
+ * with the entity), or null when the entity has none / it's disabled.
*/
getColliderGizmo(
id: EntityId,
ppuHint?: number,
- ): { kind: 'box'; pts: Array<{ x: number; y: number }>; handle: { x: number; y: number } | null; sizeHandle: { x: number; y: number } | null } | { kind: 'circle'; cx: number; cy: number; r: number; handle: { x: number; y: number } | null; sizeHandle: { x: number; y: number } | null } | null {
+ ): { kind: 'box'; cx: number; cy: number; r: number; pts: Array<{ x: number; y: number }>; handle: { x: number; y: number } | null; sizeHandle: { x: number; y: number } | null; oneWay: { dx: number; dy: number } | null } | { kind: 'circle'; cx: number; cy: number; r: number; pts: Array<{ x: number; y: number }>; handle: { x: number; y: number } | null; sizeHandle: { x: number; y: number } | null; oneWay: { dx: number; dy: number } | null } | null {
const world = EngineHost.world;
if (!world || !world.valid(id) || !world.has(id, Transform)) return null;
const t = world.get(id, Transform);
@@ -555,19 +601,28 @@ export const ViewportController = {
x: t.worldPosition.x + (off.x * ppu) * cos - (off.y * ppu) * sin,
y: t.worldPosition.y + (off.x * ppu) * sin + (off.y * ppu) * cos,
});
+ // One-way platforms cancel contacts approaching from behind `normal` — show the
+ // solid side. The normal is world-space (screen y flips), independent of rotation.
+ let oneWay: { dx: number; dy: number } | null = null;
+ if (world.has(id, OneWayPlatform)) {
+ const ow = world.get(id, OneWayPlatform) as { normal: { x: number; y: number }; enabled: boolean };
+ const len = Math.hypot(ow.normal.x, ow.normal.y);
+ if (ow.enabled !== false && len > 1e-4) oneWay = { dx: ow.normal.x / len, dy: -ow.normal.y / len };
+ }
if (world.has(id, BoxCollider)) {
const b = world.get(id, BoxCollider) as { halfExtents: { x: number; y: number }; offset: { x: number; y: number } };
const c = placeOffset(b.offset);
const hw = b.halfExtents.x * ppu;
const hh = b.halfExtents.y * ppu;
+ const centerS = this.worldToClient(c.x, c.y);
const screen = obbCorners({ cx: c.x, cy: c.y, hw: Math.abs(hw), hh: Math.abs(hh), rot }).map(([wx, wy]) =>
this.worldToClient(wx, wy),
);
- if (screen.some((p) => !p)) return null;
+ if (!centerS || screen.some((p) => !p)) return null;
const bs = screen.map((p) => ({ x: p!.x, y: p!.y }));
// Size handle at the +hw,+hh corner (obbCorners index 2) — drag = halfExtents.
- return { kind: 'box', pts: bs, handle: null, sizeHandle: bs[2] };
+ return { kind: 'box', cx: centerS.x, cy: centerS.y, r: 0, pts: bs, handle: null, sizeHandle: bs[2], oneWay };
}
const cc = world.get(id, CircleCollider) as { radius: number; offset: { x: number; y: number } };
@@ -577,7 +632,75 @@ export const ViewportController = {
if (!center || !edge) return null;
// Radius handle at the top of the circle (drag = radius, in physics meters).
const handle = this.worldToClient(c.x, c.y + cc.radius * ppu);
- return { kind: 'circle', cx: center.x, cy: center.y, r: Math.hypot(edge.x - center.x, edge.y - center.y), handle: handle ?? null, sizeHandle: null };
+ return { kind: 'circle', cx: center.x, cy: center.y, r: Math.hypot(edge.x - center.x, edge.y - center.y), pts: [], handle: handle ?? null, sizeHandle: null, oneWay };
+ },
+
+ /** (entity, joint-type) pairs for every scene-authored joint — the joint-gizmo set. */
+ jointGizmoKeys(): Array<{ id: EntityId; type: JointGizmoType }> {
+ const world = EngineHost.world;
+ if (!world) return [];
+ const out: Array<{ id: EntityId; type: JointGizmoType }> = [];
+ for (const e of world.getAllEntities()) {
+ if (!world.has(e, Transform)) continue;
+ for (const type of Object.keys(JOINT_GIZMO_DEFS) as JointGizmoType[]) {
+ if (world.has(e, JOINT_GIZMO_DEFS[type])) out.push({ id: e, type });
+ }
+ }
+ return out;
+ },
+
+ /**
+ * Screen-space link geometry for a scene-authored joint: the anchor on the joint's
+ * own body (`b`), the anchor on the connected body (`a`, null while connectedEntity
+ * is unset — the joint is inert until it links), plus the type-specific directions:
+ * `axis` = prismatic/wheel slide axis (local to the CONNECTED body, Box2D
+ * localFrameA — see PhysicsJoints.cpp), `vel` = motor target linear velocity.
+ * Anchors are world px in each body's local frame (PhysicsSystem ×invPpu → meters);
+ * MotorJoint has none, so both ends sit at the body origins.
+ */
+ getJointGizmo(
+ id: EntityId,
+ type: JointGizmoType,
+ ): { b: { x: number; y: number }; a: { x: number; y: number } | null; axis: { dx: number; dy: number } | null; vel: { dx: number; dy: number } | null; on: boolean } | null {
+ const world = EngineHost.world;
+ const def = JOINT_GIZMO_DEFS[type];
+ if (!world || !def || !world.valid(id) || !world.has(id, def) || !world.has(id, Transform)) return null;
+ const j = world.get(id, def) as JointGizmoData;
+ const anchorOn = (eid: EntityId, anchor: { x: number; y: number }) => {
+ const tt = world.get(eid, Transform);
+ const r = quatAngleZ(tt.worldRotation as { w: number; x: number; y: number; z: number });
+ const cos = Math.cos(r);
+ const sin = Math.sin(r);
+ return this.worldToClient(
+ tt.worldPosition.x + anchor.x * cos - anchor.y * sin,
+ tt.worldPosition.y + anchor.x * sin + anchor.y * cos,
+ );
+ };
+ const b = anchorOn(id, j.anchorB ?? { x: 0, y: 0 });
+ if (!b) return null;
+
+ const cid = j.connectedEntity as EntityId;
+ let a: { x: number; y: number } | null = null;
+ let axis: { dx: number; dy: number } | null = null;
+ if (typeof cid === 'number' && cid >= 0 && world.valid(cid) && world.has(cid, Transform)) {
+ a = anchorOn(cid, j.anchorA ?? { x: 0, y: 0 });
+ if (j.axis) {
+ const len = Math.hypot(j.axis.x, j.axis.y);
+ if (len > 1e-4) {
+ const tc = world.get(cid, Transform);
+ const r = quatAngleZ(tc.worldRotation as { w: number; x: number; y: number; z: number });
+ const wx = (j.axis.x * Math.cos(r) - j.axis.y * Math.sin(r)) / len;
+ const wy = (j.axis.x * Math.sin(r) + j.axis.y * Math.cos(r)) / len;
+ axis = { dx: wx, dy: -wy }; // world → screen y-flip
+ }
+ }
+ }
+ let vel: { dx: number; dy: number } | null = null;
+ if (j.linearVelocity) {
+ const len = Math.hypot(j.linearVelocity.x, j.linearVelocity.y);
+ if (len > 1e-4) vel = { dx: j.linearVelocity.x / len, dy: -j.linearVelocity.y / len };
+ }
+ return { b, a, axis, vel, on: j.enabled !== false };
},
/** Ids of entities carrying a ParticleEmitter — the emitter-gizmo set. */
@@ -603,12 +726,13 @@ export const ViewportController = {
*/
getParticleEmitterGizmo(
id: EntityId,
- ): { cx: number; cy: number; kind: 'point' | 'circle' | 'poly'; r: number; pts: Array<{ x: number; y: number }>; on: boolean; handle: { x: number; y: number } | null; sizeHandle: { x: number; y: number } | null; angleHandle: { x: number; y: number } | null } | null {
+ ): { cx: number; cy: number; kind: 'point' | 'circle' | 'poly'; r: number; pts: Array<{ x: number; y: number }>; spread: Array<{ x: number; y: number }> | null; on: boolean; handle: { x: number; y: number } | null; sizeHandle: { x: number; y: number } | null; angleHandle: { x: number; y: number } | null } | null {
const world = EngineHost.world;
if (!world || !world.valid(id) || !world.has(id, ParticleEmitter) || !world.has(id, Transform)) return null;
const t = world.get(id, Transform);
const p = world.get(id, ParticleEmitter) as {
- shape: number; shapeRadius: number; shapeSize: { x: number; y: number }; shapeAngle: number; enabled: boolean;
+ shape: number; shapeRadius: number; shapeSize: { x: number; y: number }; shapeAngle: number;
+ angleSpreadMin: number; angleSpreadMax: number; enabled: boolean;
};
const center = this.worldToClient(t.worldPosition.x, t.worldPosition.y);
if (!center) return null;
@@ -623,13 +747,31 @@ export const ViewportController = {
y: t.worldPosition.y + lx * sin + ly * cos,
});
+ // Point/Rect aim by angleSpread (0° = local +X, CCW — randomDirection); Circle
+ // aims radially and Cone by shapeAngle, so only the former two get the wedge.
+ // The full-circle default (0..360) draws nothing — no aim to show.
+ const spreadWedge = (reach: number): Array<{ x: number; y: number }> | null => {
+ const span = p.angleSpreadMax - p.angleSpreadMin;
+ if (span <= 0 || span >= 360) return null;
+ const STEPS = Math.max(2, Math.ceil(span / 15));
+ const pts: Array<{ x: number; y: number }> = [{ x: center.x, y: center.y }];
+ for (let i = 0; i <= STEPS; i++) {
+ const a = (p.angleSpreadMin + span * (i / STEPS)) * (Math.PI / 180);
+ const w = toWorld(Math.cos(a) * reach, Math.sin(a) * reach);
+ const s = this.worldToClient(w.x, w.y);
+ if (!s) return null;
+ pts.push({ x: s.x, y: s.y });
+ }
+ return pts;
+ };
+
switch (p.shape) {
case 1: { // Circle — spawn disk of shapeRadius
const edge = this.worldToClient(t.worldPosition.x + p.shapeRadius, t.worldPosition.y);
const r = edge ? Math.hypot(edge.x - center.x, edge.y - center.y) : 0;
// Radius handle at the top of the ring (drag to resize shapeRadius).
const handle = this.worldToClient(t.worldPosition.x, t.worldPosition.y + p.shapeRadius);
- return { cx: center.x, cy: center.y, kind: 'circle', r, pts: [], on, handle: handle ?? null, sizeHandle: null, angleHandle: null };
+ return { cx: center.x, cy: center.y, kind: 'circle', r, pts: [], spread: null, on, handle: handle ?? null, sizeHandle: null, angleHandle: null };
}
case 2: { // Rectangle — oriented spawn box of shapeSize
const corners = obbCorners({
@@ -638,8 +780,9 @@ export const ViewportController = {
}).map(([wx, wy]) => this.worldToClient(wx, wy));
if (corners.some((s) => !s)) return null;
const cs = corners.map((s) => ({ x: s!.x, y: s!.y }));
+ const reach = Math.max(48, Math.hypot(p.shapeSize.x, p.shapeSize.y) * 0.5 + 16);
// Size handle at the +halfW,+halfH corner (obbCorners index 2) — drag = shapeSize.
- return { cx: center.x, cy: center.y, kind: 'poly', r: 0, pts: cs, on, handle: null, sizeHandle: cs[2], angleHandle: null };
+ return { cx: center.x, cy: center.y, kind: 'poly', r: 0, pts: cs, spread: spreadWedge(reach), on, handle: null, sizeHandle: cs[2], angleHandle: null };
}
case 3: { // Cone — aim wedge: local up (0,1) swept ±shapeAngle/2, out to shapeRadius
const half = Math.max(0, p.shapeAngle) * 0.5 * (Math.PI / 180);
@@ -659,10 +802,10 @@ export const ViewportController = {
const handleS = this.worldToClient(tip.x, tip.y);
const edge = toWorld(Math.sin(half) * rad, Math.cos(half) * rad);
const angleS = this.worldToClient(edge.x, edge.y);
- return { cx: center.x, cy: center.y, kind: 'poly', r: 0, pts, on, handle: handleS ?? null, sizeHandle: null, angleHandle: angleS ?? null };
+ return { cx: center.x, cy: center.y, kind: 'poly', r: 0, pts, spread: null, on, handle: handleS ?? null, sizeHandle: null, angleHandle: angleS ?? null };
}
- default: // Point (0) — a marker at the emitter (the clickable icon)
- return { cx: center.x, cy: center.y, kind: 'point', r: 0, pts: [], on, handle: null, sizeHandle: null, angleHandle: null };
+ default: // Point (0) — a marker at the emitter (the clickable icon) + its aim wedge
+ return { cx: center.x, cy: center.y, kind: 'point', r: 0, pts: [], spread: spreadWedge(48), on, handle: null, sizeHandle: null, angleHandle: null };
}
},
};
diff --git a/desktop/src/i18n/messages/commands.ts b/desktop/src/i18n/messages/commands.ts
index 3ac0c557e..c87f66b36 100644
--- a/desktop/src/i18n/messages/commands.ts
+++ b/desktop/src/i18n/messages/commands.ts
@@ -48,7 +48,7 @@ export const commandMessages = defineMessages({
'cmd.view.toggleGrid': { en: 'Show Grid', zh: '显示网格' },
'cmd.view.toggleGizmos': { en: 'Show Gizmos', zh: '显示 Gizmo' },
'cmd.view.togglePreviewFx': { en: 'Preview FX', zh: '预览特效' },
- 'cmd.view.toggleColliders': { en: 'Show Colliders', zh: '显示碰撞体' },
+ 'cmd.view.toggleColliders': { en: 'Show Physics Gizmos', zh: '显示物理 Gizmo' },
'cmd.view.toggleCoordSpace': { en: 'Local Axes', zh: '局部坐标轴' },
'cmd.view.togglePivotMode': { en: 'Pivot (vs Center)', zh: '轴心(而非中心)' },
'cmd.view.toggleSnapping': { en: 'Snapping', zh: '吸附' },
diff --git a/desktop/src/i18n/messages/viewport.ts b/desktop/src/i18n/messages/viewport.ts
index 9b83aa597..1a9013a0f 100644
--- a/desktop/src/i18n/messages/viewport.ts
+++ b/desktop/src/i18n/messages/viewport.ts
@@ -66,7 +66,7 @@ export const viewportMessages = defineMessages({
'vp.showFlags': { en: 'Show Flags', zh: '显示标记' },
'vp.flag.grid': { en: 'Grid', zh: '网格' },
'vp.flag.gizmos': { en: 'Gizmos', zh: 'Gizmo' },
- 'vp.flag.colliders': { en: 'Colliders', zh: '碰撞体' },
+ 'vp.flag.colliders': { en: 'Physics', zh: '物理' },
'vp.flag.previewFx': { en: 'Preview FX', zh: '预览特效' },
'vp.flag.perf': { en: 'Perf', zh: '性能' },
diff --git a/desktop/src/panels/Viewport.tsx b/desktop/src/panels/Viewport.tsx
index 2952fc8bd..b8068eb97 100644
--- a/desktop/src/panels/Viewport.tsx
+++ b/desktop/src/panels/Viewport.tsx
@@ -20,7 +20,7 @@ import { commands } from '@/commands';
import { MOD_LABEL } from '@/commands/keybinding';
import { EngineHost } from '@/engine/EngineHost';
import { PlayRealm } from '@/engine/PlayRealm';
-import { ViewportController } from '@/engine/ViewportController';
+import { ViewportController, type JointGizmoType } from '@/engine/ViewportController';
import { ProjectStore } from '@/project/ProjectStore';
import { createFromSource, sourceById, SOURCE_DND_MIME } from '@/engine/entitySources';
import { resizeUINodeAxis, type ResizeSide, type AxisResizeWrites } from '@/engine/uiResize';
@@ -54,13 +54,15 @@ const toInput = (e: ReactPointerEvent): PointerInput => ({
// emitter shapeRadius, light radius, and circle-collider radius all drive their field
// this way. `ppu` maps world distance to the field's units: 1 for world-space radii
// (emitter/light), the collider's pixelsPerUnit for physics-meter radii. Measures from
-// the entity's world origin (exact when the shape has no local offset).
+// the entity's world origin unless the shape has its own center (collider offset) —
+// callers pass `centerOverride` so the drag measures from where the shape is drawn.
function startRadiusHandleDrag(
rt: number, component: string, field: string, ppu: number, e: ReactPointerEvent,
+ centerOverride?: { x: number; y: number } | null,
): void {
if (e.button !== 0) return;
const src = SceneModel.sourceFor(rt);
- const center = ViewportController.getEntityWorldXY(rt);
+ const center = centerOverride ?? ViewportController.getEntityWorldXY(rt);
if (src == null || !center) return;
e.stopPropagation();
SceneCommands.beginGesture(`${component} radius`);
@@ -83,12 +85,14 @@ function startRadiusHandleDrag(
// cursor is un-rotated into the entity's local frame so the corner's |local| gives the
// half-extents. `fullSize` writes the full size (emitter shapeSize = 2× half); else the
// half-extents (collider halfExtents). `ppu` maps world px → the field's units.
+// `centerOverride` = the shape's own center when it's offset from the entity origin.
function startSizeHandleDrag(
rt: number, component: string, field: string, ppu: number, fullSize: boolean, e: ReactPointerEvent,
+ centerOverride?: { x: number; y: number } | null,
): void {
if (e.button !== 0) return;
const src = SceneModel.sourceFor(rt);
- const center = ViewportController.getEntityWorldXY(rt);
+ const center = centerOverride ?? ViewportController.getEntityWorldXY(rt);
if (src == null || !center) return;
e.stopPropagation();
const rot = ViewportController.getEntityWorldAngleRad(rt);
@@ -619,6 +623,13 @@ export function Viewport() {
() => (engine.status === 'ready' && showColliders ? ViewportController.colliderIds() : []),
[structRev, engine.status, showColliders],
);
+ // Scene-authored joints are equally invisible — draw each as an anchor link (plus
+ // axis/velocity direction). Keyed by entity + joint type; same physics show flag.
+ const jointRefs = useRef(new Map<string, SVGSVGElement | null>());
+ const jointKeys = useMemo(
+ () => (engine.status === 'ready' && showColliders ? ViewportController.jointGizmoKeys() : []),
+ [structRev, engine.status, showColliders],
+ );
// Particle emitters don't simulate in edit mode — outline each emitter's spawn
// shape (point / circle / rect / cone) + a clickable icon, positioned by the rAF.
const particleRefs = useRef(new Map<number, HTMLDivElement | null>());
@@ -1023,6 +1034,120 @@ export function Viewport() {
csz.style.display = 'none';
}
}
+ // One-way platform: an arrow out of the collider center along the solid-side
+ // normal (screen-fixed length, like the light direction line, so it reads at
+ // any zoom) — the side a body can land on; it passes through from the other.
+ const owLine = svg.querySelector('.cl-oneway') as SVGLineElement | null;
+ const owHead = svg.querySelector('.cl-oneway-head') as SVGPolygonElement | null;
+ if (cg && cg.oneWay) {
+ const L = 30;
+ const { dx, dy } = cg.oneWay;
+ const bx = cg.cx + dx * L;
+ const by = cg.cy + dy * L;
+ if (owLine) {
+ owLine.setAttribute('x1', String(cg.cx));
+ owLine.setAttribute('y1', String(cg.cy));
+ owLine.setAttribute('x2', String(bx));
+ owLine.setAttribute('y2', String(by));
+ owLine.style.opacity = '1';
+ }
+ if (owHead) {
+ const px = -dy;
+ const py = dx;
+ owHead.setAttribute('points', [
+ `${bx + dx * 9},${by + dy * 9}`,
+ `${bx + px * 4.5},${by + py * 4.5}`,
+ `${bx - px * 4.5},${by - py * 4.5}`,
+ ].join(' '));
+ owHead.style.opacity = '1';
+ }
+ } else {
+ if (owLine) owLine.style.opacity = '0';
+ if (owHead) owHead.style.opacity = '0';
+ }
+ }
+
+ // Joint gizmos — the anchor-to-anchor link (own body ↔ connected body), the
+ // prismatic/wheel slide axis, and the motor joint's target-velocity arrow.
+ // Unlinked joints (no connectedEntity yet) show just their own anchor dot.
+ for (const [key, svg] of jointRefs.current) {
+ if (!svg) continue;
+ const sep = key.indexOf(':');
+ const jg = camsOn
+ ? ViewportController.getJointGizmo(Number(key.slice(0, sep)), key.slice(sep + 1) as JointGizmoType)
+ : null;
+ const line = svg.querySelector('.jt-line') as SVGLineElement | null;
+ const dotA = svg.querySelector('.jt-a') as SVGCircleElement | null;
+ const dotB = svg.querySelector('.jt-b') as SVGCircleElement | null;
+ const axis = svg.querySelector('.jt-axis') as SVGLineElement | null;
+ const vel = svg.querySelector('.jt-vel') as SVGLineElement | null;
+ const velHead = svg.querySelector('.jt-vel-head') as SVGPolygonElement | null;
+ if (!jg) {
+ svg.style.opacity = '0';
+ continue;
+ }
+ svg.style.opacity = jg.on ? '1' : '0.35';
+ if (dotB) {
+ dotB.setAttribute('cx', String(jg.b.x));
+ dotB.setAttribute('cy', String(jg.b.y));
+ }
+ if (line) {
+ if (jg.a) {
+ line.setAttribute('x1', String(jg.b.x));
+ line.setAttribute('y1', String(jg.b.y));
+ line.setAttribute('x2', String(jg.a.x));
+ line.setAttribute('y2', String(jg.a.y));
+ line.style.opacity = '1';
+ } else {
+ line.style.opacity = '0';
+ }
+ }
+ if (dotA) {
+ if (jg.a) {
+ dotA.setAttribute('cx', String(jg.a.x));
+ dotA.setAttribute('cy', String(jg.a.y));
+ dotA.style.opacity = '1';
+ } else {
+ dotA.style.opacity = '0';
+ }
+ }
+ if (axis) {
+ if (jg.a && jg.axis) {
+ axis.setAttribute('x1', String(jg.a.x - jg.axis.dx * 26));
+ axis.setAttribute('y1', String(jg.a.y - jg.axis.dy * 26));
+ axis.setAttribute('x2', String(jg.a.x + jg.axis.dx * 26));
+ axis.setAttribute('y2', String(jg.a.y + jg.axis.dy * 26));
+ axis.style.opacity = '1';
+ } else {
+ axis.style.opacity = '0';
+ }
+ }
+ // Motor target velocity: arrow out of the driven body's anchor.
+ if (jg.vel) {
+ const L = 30;
+ const tx = jg.b.x + jg.vel.dx * L;
+ const ty = jg.b.y + jg.vel.dy * L;
+ if (vel) {
+ vel.setAttribute('x1', String(jg.b.x));
+ vel.setAttribute('y1', String(jg.b.y));
+ vel.setAttribute('x2', String(tx));
+ vel.setAttribute('y2', String(ty));
+ vel.style.opacity = '1';
+ }
+ if (velHead) {
+ const px = -jg.vel.dy;
+ const py = jg.vel.dx;
+ velHead.setAttribute('points', [
+ `${tx + jg.vel.dx * 9},${ty + jg.vel.dy * 9}`,
+ `${tx + px * 4.5},${ty + py * 4.5}`,
+ `${tx - px * 4.5},${ty - py * 4.5}`,
+ ].join(' '));
+ velHead.style.opacity = '1';
+ }
+ } else {
+ if (vel) vel.style.opacity = '0';
+ if (velHead) velHead.style.opacity = '0';
+ }
}
// Light2D gizmos — icon at the light, dashed reach circle (Point/Spot), direction
@@ -1095,6 +1220,17 @@ export function Viewport() {
const svg = particleShapeRefs.current.get(pid);
const poly = svg ? (svg.querySelector('.pe-poly') as SVGPolygonElement | null) : null;
const circ = svg ? (svg.querySelector('.pe-circle') as SVGCircleElement | null) : null;
+ // Aim wedge (Point/Rect): the angleSpread arc particles will fly into. The
+ // full-circle default draws nothing, so it only appears once aimed.
+ const spread = svg ? (svg.querySelector('.pe-spread') as SVGPolygonElement | null) : null;
+ if (spread) {
+ if (pg && pg.spread) {
+ spread.setAttribute('points', pg.spread.map((p) => `${p.x},${p.y}`).join(' '));
+ spread.style.opacity = pg.on ? '0.7' : '0.3';
+ } else {
+ spread.style.opacity = '0';
+ }
+ }
if (pg) {
wrap.style.opacity = pg.on ? '1' : '0.4';
wrap.style.visibility = 'visible';
@@ -1515,17 +1651,20 @@ export function Viewport() {
else colliderRefs.current.delete(id);
}}
className="viewport__collider-gizmo"
+ data-src={SceneModel.sourceFor(id)}
aria-hidden="true"
>
<polygon className="cl-box" points="" />
<circle className="cl-circle" cx="0" cy="0" r="0" />
+ <line className="cl-oneway" x1="0" y1="0" x2="0" y2="0" />
+ <polygon className="cl-oneway-head" points="" />
<circle
className="cl-handle"
cx="0"
cy="0"
r="5"
style={{ display: 'none' }}
- onPointerDown={(e) => startRadiusHandleDrag(id, 'CircleCollider', 'radius', ViewportController.colliderPixelsPerUnit(), e)}
+ onPointerDown={(e) => startRadiusHandleDrag(id, 'CircleCollider', 'radius', ViewportController.colliderPixelsPerUnit(), e, ViewportController.colliderWorldCenter(id))}
/>
<circle
className="cl-size-handle"
@@ -1533,11 +1672,35 @@ export function Viewport() {
cy="0"
r="5"
style={{ display: 'none' }}
- onPointerDown={(e) => startSizeHandleDrag(id, 'BoxCollider', 'halfExtents', ViewportController.colliderPixelsPerUnit(), false, e)}
+ onPointerDown={(e) => startSizeHandleDrag(id, 'BoxCollider', 'halfExtents', ViewportController.colliderPixelsPerUnit(), false, e, ViewportController.colliderWorldCenter(id))}
/>
</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. */}
+ {jointKeys.map(({ id, type }) => (
+ <svg
+ key={`${id}:${type}`}
+ ref={(el) => {
+ if (el) jointRefs.current.set(`${id}:${type}`, el);
+ else jointRefs.current.delete(`${id}:${type}`);
+ }}
+ className="viewport__joint-gizmo"
+ data-src={SceneModel.sourceFor(id)}
+ data-joint={type}
+ aria-hidden="true"
+ >
+ <line className="jt-line" x1="0" y1="0" x2="0" y2="0" />
+ <line className="jt-axis" x1="0" y1="0" x2="0" y2="0" />
+ <line className="jt-vel" x1="0" y1="0" x2="0" y2="0" />
+ <polygon className="jt-vel-head" points="" />
+ <circle className="jt-b" cx="0" cy="0" r="3" />
+ <circle className="jt-a" cx="0" cy="0" r="3" />
+ </svg>
+ ))}
+
{/* Particle-emitter gizmos: a clickable icon (select-to-identify, like a light)
+ a spawn-shape overlay SVG (cone wedge / circle / box), positioned by the rAF. */}
{particleIds.map((id) => {
@@ -1579,6 +1742,7 @@ export function Viewport() {
>
<polygon className="pe-poly" points="" />
<circle className="pe-circle" cx="0" cy="0" r="0" />
+ <polygon className="pe-spread" points="" />
<circle
className="pe-handle"
cx="0"
diff --git a/desktop/src/theme/app.css b/desktop/src/theme/app.css
index 21bd35f82..90867caeb 100644
--- a/desktop/src/theme/app.css
+++ b/desktop/src/theme/app.css
@@ -414,6 +414,56 @@ body.thumb-capture .viewport__play-stop {
.viewport__collider-gizmo .cl-size-handle {
cursor: nwse-resize;
}
+/* One-way platform solid-side arrow (world-space normal out of the collider center). */
+.viewport__collider-gizmo .cl-oneway {
+ stroke: var(--gizmo-collider);
+ stroke-width: 2;
+ stroke-linecap: round;
+ opacity: 0;
+}
+.viewport__collider-gizmo .cl-oneway-head {
+ fill: var(--gizmo-collider);
+ opacity: 0;
+}
+
+/* Joint link gizmo: anchor dots + link line (own body ↔ connected body), the
+ prismatic/wheel slide axis, and the motor target-velocity arrow. The SVG spans
+ the viewport; the rAF writes absolute canvas-relative px. */
+.viewport__joint-gizmo {
+ position: absolute;
+ inset: 0;
+ width: 100%;
+ height: 100%;
+ z-index: 2;
+ pointer-events: none;
+ overflow: visible;
+ transition: opacity var(--t-fast);
+}
+.viewport__joint-gizmo .jt-line {
+ stroke: var(--gizmo-joint);
+ stroke-width: 1.5;
+ stroke-dasharray: 5 4;
+}
+.viewport__joint-gizmo .jt-a,
+.viewport__joint-gizmo .jt-b {
+ fill: var(--gizmo-joint);
+ stroke: var(--srf-2);
+ stroke-width: 1.25;
+}
+.viewport__joint-gizmo .jt-axis {
+ stroke: var(--gizmo-joint);
+ stroke-width: 1.25;
+ stroke-dasharray: 2 3;
+ stroke-linecap: round;
+}
+.viewport__joint-gizmo .jt-vel {
+ stroke: var(--gizmo-joint);
+ stroke-width: 2;
+ stroke-linecap: round;
+}
+.viewport__joint-gizmo .jt-vel-head {
+ fill: var(--gizmo-joint);
+}
/* Particle-emitter gizmo: a clickable icon at the emitter + its spawn-shape overlay.
The icon wrapper is translate()'d to the emitter; the shape SVG spans the viewport
@@ -464,6 +514,15 @@ body.thumb-capture .viewport__play-stop {
stroke-width: 1.5;
opacity: 0;
}
+/* angleSpread aim wedge (Point/Rect) — where particles will fly, dashed so it reads
+ as direction, not spawn geometry. */
+.viewport__particle-shape .pe-spread {
+ fill: color-mix(in srgb, var(--gizmo-particle) 4%, transparent);
+ stroke: var(--gizmo-particle);
+ stroke-width: 1.25;
+ stroke-dasharray: 4 3;
+ opacity: 0;
+}
/* Draggable handles — radius (Circle/Cone), size corner (Rect), angle edge (Cone). */
.viewport__particle-shape .pe-handle,
.viewport__particle-shape .pe-size-handle,
diff --git a/desktop/src/theme/tokens.css b/desktop/src/theme/tokens.css
index 4a191c18e..cc181e981 100644
--- a/desktop/src/theme/tokens.css
+++ b/desktop/src/theme/tokens.css
@@ -94,6 +94,7 @@
--gizmo-collider: #00dc82;
--gizmo-particle: #ffb454;
--gizmo-tile: #58b6e6;
+ --gizmo-joint: #c58cff;
/* — Category identity: component header bars / icons read by domain. — */
--cat-transform: #4a8fd6;
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index dccdb4ada..e82d3a664 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: 1125 stable · 17 beta · 1 deprecated
+Symbols: 1131 stable · 17 beta · 1 deprecated
## ABI_LAYOUT_HASH — const
```
@@ -1776,6 +1776,11 @@ value: number
ComponentDef<{}>
```
+## DistanceJoint — const
+```
+ComponentDef<DistanceJointData>
+```
+
## DragPlugin — class
```
build: (app: App) => void
@@ -3489,6 +3494,11 @@ meta: boolean
shift: boolean
```
+## MotorJoint — const
+```
+ComponentDef<MotorJointData>
+```
+
## MouseButton — const
```
(button: number) => Binding
@@ -3672,6 +3682,11 @@ params: NodeParamSpec[]
(filter: FilterExpr): FilterExpr
```
+## OneWayPlatform — const
+```
+ComponentDef<OneWayPlatformData>
+```
+
## Or — function
```
(...filters: FilterExpr[]): FilterExpr
@@ -4454,6 +4469,11 @@ static new (sceneUrl: string, baseUrl?: string): PreviewPlugin
static prototype: PreviewPlugin
```
+## PrismaticJoint — const
+```
+ComponentDef<PrismaticJointData>
+```
+
## ProbedRegistrations — interface
```
fingerprint: string
@@ -6873,6 +6893,16 @@ sideModules: SideModuleHost | undefined
ySortLayers: number | undefined
```
+## WeldJoint — const
+```
+ComponentDef<WeldJointData>
+```
+
+## WheelJoint — const
+```
+ComponentDef<WheelJointData>
+```
+
## With — function
```
(component: AnyComponentDef): FilterExpr
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 9c1e8d849..9251a905a 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: 1124 stable · 19 beta · 1 deprecated
+Symbols: 1130 stable · 19 beta · 1 deprecated
## ANCHOR_AXES — const
```
@@ -1771,6 +1771,11 @@ value: number
ComponentDef<{}>
```
+## DistanceJoint — const
+```
+ComponentDef<DistanceJointData>
+```
+
## DragPlugin — class
```
build: (app: App) => void
@@ -3484,6 +3489,11 @@ meta: boolean
shift: boolean
```
+## MotorJoint — const
+```
+ComponentDef<MotorJointData>
+```
+
## MouseButton — const
```
(button: number) => Binding
@@ -3667,6 +3677,11 @@ params: NodeParamSpec[]
(filter: FilterExpr): FilterExpr
```
+## OneWayPlatform — const
+```
+ComponentDef<OneWayPlatformData>
+```
+
## Or — function
```
(...filters: FilterExpr[]): FilterExpr
@@ -4449,6 +4464,11 @@ static new (sceneUrl: string, baseUrl?: string): PreviewPlugin
static prototype: PreviewPlugin
```
+## PrismaticJoint — const
+```
+ComponentDef<PrismaticJointData>
+```
+
## ProbedRegistrations — interface
```
fingerprint: string
@@ -6868,6 +6888,16 @@ sideModules: SideModuleHost | undefined
ySortLayers: number | undefined
```
+## WeldJoint — const
+```
+ComponentDef<WeldJointData>
+```
+
+## WheelJoint — const
+```
+ComponentDef<WheelJointData>
+```
+
## With — function
```
(component: AnyComponentDef): FilterExpr
diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.ts
index 629ef64db..1af0b1fe0 100644
--- a/sdk/src/core-runtime.ts
+++ b/sdk/src/core-runtime.ts
@@ -143,7 +143,13 @@ export {
SegmentCollider,
PolygonCollider,
ChainCollider,
+ OneWayPlatform,
RevoluteJoint,
+ DistanceJoint,
+ PrismaticJoint,
+ WeldJoint,
+ WheelJoint,
+ MotorJoint,
BodyType,
} from './physics/PhysicsComponents';