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(viewport): draw physics collider shapes in the editor

esenginefb0db32bcad6
diff --git a/desktop/src/engine/ViewportController.ts b/desktop/src/engine/ViewportController.ts
index 3448bcc01..34705bb9e 100644
--- a/desktop/src/engine/ViewportController.ts
+++ b/desktop/src/engine/ViewportController.ts
@@ -1,7 +1,7 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import {
- Camera, CameraView, EditorView, Light2D, Sprite, Transform,
+ Camera, CameraView, EditorView, Light2D, Sprite, Transform, Canvas, BoxCollider, CircleCollider,
UINode, UICameraInfo, screenToUiWorld, uiWorldToScreen, uiHitTestWorld, type UICameraData,
} from 'esengine';
import type { EntityId } from '@/types';
@@ -382,4 +382,70 @@ export const ViewportController = {
const color = `#${hex(l.color.r)}${hex(l.color.g)}${hex(l.color.b)}`;
return { cx: center.x, cy: center.y, kind: l.type, color, radiusPx, sdx, sdy, coneHalf };
},
+
+ /** Ids of entities carrying a box/circle collider — the collider-gizmo set. */
+ colliderIds(): EntityId[] {
+ const world = EngineHost.world;
+ if (!world) return [];
+ const out: EntityId[] = [];
+ for (const e of world.getAllEntities()) {
+ if (world.has(e, Transform) && (world.has(e, BoxCollider) || world.has(e, CircleCollider))) out.push(e);
+ }
+ return out;
+ },
+
+ // Collider sizes are physics meters; the world is pixels. Mirror the runtime's
+ // live read (the Canvas entity's pixelsPerUnit, else 100) so the gizmo matches.
+ colliderPixelsPerUnit(): number {
+ const world = EngineHost.world;
+ if (world) {
+ for (const e of world.getAllEntities()) {
+ if (world.has(e, Canvas)) {
+ const ppu = (world.get(e, Canvas) as { pixelsPerUnit?: number }).pixelsPerUnit;
+ if (ppu) return ppu;
+ }
+ }
+ }
+ return 100;
+ },
+
+ /**
+ * 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.
+ */
+ getColliderGizmo(
+ id: EntityId,
+ ): { kind: 'box'; pts: Array<{ x: number; y: number }> } | { kind: 'circle'; cx: number; cy: number; r: number } | null {
+ const world = EngineHost.world;
+ if (!world || !world.valid(id) || !world.has(id, Transform)) return null;
+ const t = world.get(id, Transform);
+ const ppu = this.colliderPixelsPerUnit();
+ const rot = quatAngleZ(t.worldRotation as { w: number; x: number; y: number; z: number });
+ const cos = Math.cos(rot);
+ const sin = Math.sin(rot);
+ const placeOffset = (off: { x: number; y: number }) => ({
+ x: t.worldPosition.x + (off.x * ppu) * cos - (off.y * ppu) * sin,
+ y: t.worldPosition.y + (off.x * ppu) * sin + (off.y * ppu) * cos,
+ });
+
+ 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 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;
+ return { kind: 'box', pts: screen.map((p) => ({ x: p!.x, y: p!.y })) };
+ }
+
+ const cc = world.get(id, CircleCollider) as { radius: number; offset: { x: number; y: number } };
+ const c = placeOffset(cc.offset);
+ const center = this.worldToClient(c.x, c.y);
+ const edge = this.worldToClient(c.x + cc.radius * ppu, c.y);
+ if (!center || !edge) return null;
+ return { kind: 'circle', cx: center.x, cy: center.y, r: Math.hypot(edge.x - center.x, edge.y - center.y) };
+ },
};
diff --git a/desktop/src/panels/Viewport.tsx b/desktop/src/panels/Viewport.tsx
index 046a106d7..bcb97d8c6 100644
--- a/desktop/src/panels/Viewport.tsx
+++ b/desktop/src/panels/Viewport.tsx
@@ -244,6 +244,13 @@ export function Viewport() {
() => (engine.status === 'ready' ? ViewportController.light2DIds() : []),
[structRev, engine.status],
);
+ // Physics colliders aren't drawn by the renderer — outline each (box polygon /
+ // circle) as a gizmo so you can see/tune collider shapes without entering Play.
+ const colliderRefs = useRef(new Map<number, SVGSVGElement | null>());
+ const colliderIds = useMemo(
+ () => (engine.status === 'ready' ? ViewportController.colliderIds() : []),
+ [structRev, engine.status],
+ );
// Mount the live engine canvas into the stage; it survives panel re-docking.
useEffect(() => {
@@ -426,6 +433,28 @@ export function Viewport() {
}
}
+ // Collider gizmos — box polygon / circle outline at the collider's shape.
+ for (const [cid, svg] of colliderRefs.current) {
+ if (!svg) continue;
+ const cg = camsOn ? ViewportController.getColliderGizmo(cid) : null;
+ const poly = svg.querySelector('.cl-box') as SVGPolygonElement | null;
+ const circ = svg.querySelector('.cl-circle') as SVGCircleElement | null;
+ if (cg && cg.kind === 'box' && poly) {
+ poly.setAttribute('points', cg.pts.map((p) => `${p.x},${p.y}`).join(' '));
+ poly.style.opacity = '1';
+ if (circ) circ.style.opacity = '0';
+ } else if (cg && cg.kind === 'circle' && circ) {
+ circ.setAttribute('cx', String(cg.cx));
+ circ.setAttribute('cy', String(cg.cy));
+ circ.setAttribute('r', String(cg.r));
+ circ.style.opacity = '1';
+ if (poly) poly.style.opacity = '0';
+ } else {
+ if (poly) poly.style.opacity = '0';
+ if (circ) circ.style.opacity = '0';
+ }
+ }
+
// Light2D gizmos — icon at the light, dashed reach circle (Point/Spot), direction
// line (Directional/Spot), all tinted by the light color. Edit mode + gizmos on.
for (const [lid, wrap] of lightRefs.current) {
@@ -696,6 +725,23 @@ export function Viewport() {
</div>
))}
+ {/* Collider gizmos: a full-viewport SVG per collider (box polygon / circle),
+ positioned in absolute canvas-relative CSS px by the rAF. */}
+ {colliderIds.map((id) => (
+ <svg
+ key={id}
+ ref={(el) => {
+ if (el) colliderRefs.current.set(id, el);
+ else colliderRefs.current.delete(id);
+ }}
+ className="viewport__collider-gizmo"
+ aria-hidden="true"
+ >
+ <polygon className="cl-box" points="" />
+ <circle className="cl-circle" cx="0" cy="0" r="0" />
+ </svg>
+ ))}
+
{/* Play In Viewport: the realm iframe fills the stage; a thin badge marks PIE. */}
{playInViewport && (
<div className="viewport__play">
diff --git a/desktop/src/theme/app.css b/desktop/src/theme/app.css
index 128990669..b7fe5f037 100644
--- a/desktop/src/theme/app.css
+++ b/desktop/src/theme/app.css
@@ -729,6 +729,25 @@
stroke-linecap: round;
}
+/* Physics collider outline (box polygon / circle). The SVG spans the viewport;
+ the rAF writes absolute canvas-relative px into the shape. */
+.viewport__collider-gizmo {
+ position: absolute;
+ inset: 0;
+ width: 100%;
+ height: 100%;
+ z-index: 2;
+ pointer-events: none;
+ overflow: visible;
+}
+.viewport__collider-gizmo .cl-box,
+.viewport__collider-gizmo .cl-circle {
+ fill: rgba(0, 220, 130, 0.06);
+ stroke: #00dc82;
+ stroke-width: 1.5;
+ opacity: 0;
+}
+
.viewport__overlay {
position: absolute;
display: flex;