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.

fix(editor): the authored screen is drawn where it is, not hidden when it is not a rect

esengine1c8dadaac895
diff --git a/desktop/scripts/editor-checks/design-frame.mjs b/desktop/scripts/editor-checks/design-frame.mjs
new file mode 100644
index 000000000..78a6ec0b2
--- /dev/null
+++ b/desktop/scripts/editor-checks/design-frame.mjs
@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file design-frame — the authored screen is drawn on the plane it is on.
+ *
+ * The design frame, the device frame, the scrim outside them and the safe area are
+ * all rects on the 2D plane. Projected corner by corner they are quads, and only a
+ * head-on eye sees them as rects. This drives a real editor and measures the shape.
+ *
+ * The measurement is the frame against itself. Toggling gizmos paints the frame, so
+ * the span between its two side strokes on a row is its width there. Head-on that
+ * width is the same near the top and near the bottom; from a turned eye a trapezoid's
+ * two ends differ. Both claims are made, so a frame drawn as an axis-aligned box fails
+ * the second while still passing the first.
+ */
+import { cp } from 'node:fs/promises';
+import path from 'node:path';
+import { makeProject, checker, DESKTOP } from '../lib/editorDriver.mjs';
+
+const EXAMPLE = path.resolve(DESKTOP, '..', 'examples', 'sprite-rendering');
+
+const SCENE = JSON.stringify({
+ version: '1.0', name: 'Main',
+ // No scene Camera: its own framing gizmo is a projected quad too, and it would be
+ // the widest thing the gizmo toggle paints on most rows.
+ entities: [
+ {
+ id: 1, name: 'Canvas', parent: null, children: [], visible: true,
+ components: [
+ { type: 'Transform', data: { position: { x: 0, y: 0, z: 0 } } },
+ { type: 'Canvas', data: { designResolution: { x: 800, y: 600 } } },
+ ],
+ },
+ ],
+}, null, 1);
+
+export const name = 'design-frame';
+export const describes = 'the authored screen is drawn as the shape it is, from any eye';
+
+/**
+ * How far apart the frame's two side strokes are, per row.
+ *
+ * The tolerance is high on purpose: the scrim outside the frame is a 32% wash over
+ * an already-black viewport and moves a channel by three, while the frame's own
+ * stroke is a bright accent over it. Only the strokes clear this bar.
+ */
+function frameWidths(a, b, tol = 40) {
+ const w = Math.min(a.w, b.w);
+ const h = Math.min(a.h, b.h);
+ const rows = [];
+ for (let y = 0; y < h; y++) {
+ let first = -1;
+ let last = -1;
+ for (let x = 0; x < w; x++) {
+ const p = a.px(x, y);
+ const q = b.px(x, y);
+ if (Math.abs(p[0] - q[0]) > tol || Math.abs(p[1] - q[1]) > tol || Math.abs(p[2] - q[2]) > tol) {
+ if (first < 0) first = x;
+ last = x;
+ }
+ }
+ rows.push({ y, width: first < 0 ? 0 : last - first });
+ }
+ return rows;
+}
+
+/**
+ * The frame's width a fraction of the way down it, over the rows where both side
+ * strokes are present. The band excludes the ends, where the top and bottom strokes
+ * and the resolution label run the full width and say nothing about the sides.
+ */
+function widthAt(rows, fraction) {
+ const spanning = rows.filter((r) => r.width > 100);
+ if (spanning.length < 40) return null;
+ const lo = Math.round(spanning.length * 0.15);
+ const band = spanning.slice(lo, spanning.length - lo);
+ return band[Math.round((band.length - 1) * fraction)].width;
+}
+
+export async function run(ed) {
+ const root = await makeProject({ 'assets/scenes/main.esscene': SCENE });
+ await cp(path.join(EXAMPLE, 'project.esproject'), path.join(root, 'project.esproject'));
+ await cp(path.join(EXAMPLE, 'src'), path.join(root, 'src'), { recursive: true });
+ const check = checker();
+ await ed.open(root, 'assets/scenes/main.esscene');
+ await ed.call('run_editor_command', { id: 'mode.ui' }, 30000);
+ await ed.call('select', { id: null }, 30000);
+ await ed.sleep(1000);
+
+ /** The frame's width near its top and near its bottom, for the current eye. */
+ const measure = async (label) => {
+ await ed.call('run_editor_command', { id: 'view.toggleGizmos' }, 30000);
+ await ed.sleep(700);
+ const off = await ed.screenshot(`${label}-off`);
+ await ed.call('run_editor_command', { id: 'view.toggleGizmos' }, 30000);
+ await ed.sleep(700);
+ const on = await ed.screenshot(`${label}-on`);
+ const rows = frameWidths(off, on);
+ return { near: widthAt(rows, 0.15), far: widthAt(rows, 0.85) };
+ };
+
+ const flat = await measure('design-frame-flat');
+ if (!check(flat.near != null && flat.far != null,
+ 'the head-on shot has no frame to measure — it is not being drawn at all')) {
+ return check.failures;
+ }
+ // Head-on the frame is a rect, and stays one: this is what says the measurement
+ // reads the frame rather than some other thing the gizmo toggle repaints.
+ check(
+ Math.abs(flat.near - flat.far) <= Math.max(flat.near, flat.far) * 0.02,
+ `head-on the frame measures ${flat.near}px near its top and ${flat.far}px near its bottom — `
+ + 'a rect seen square-on has one width, so this is measuring something else',
+ );
+
+ await ed.call('run_editor_command', { id: 'view.toggleViewPerspective' }, 30000);
+ await ed.sleep(1200);
+ const turned = await measure('design-frame-turned');
+ if (!check(turned.near != null && turned.far != null,
+ 'the turned shot has no frame to measure')) {
+ return check.failures;
+ }
+ const spread = Math.abs(turned.near - turned.far) / Math.max(turned.near, turned.far);
+ check(
+ spread > 0.08,
+ `from a turned eye the frame measures ${turned.near}px near its top and ${turned.far}px near `
+ + `its bottom (${(spread * 100).toFixed(1)}% apart) — a rect on a plane seen at an angle is a `
+ + 'trapezoid, and this is still being drawn as a box',
+ );
+
+ return check.failures;
+}
diff --git a/desktop/src/panels/Viewport.tsx b/desktop/src/panels/Viewport.tsx
index f92077b71..c1849af25 100644
--- a/desktop/src/panels/Viewport.tsx
+++ b/desktop/src/panels/Viewport.tsx
@@ -243,21 +243,27 @@ function syncColliderPoints(g: SVGGElement, points: ColliderPointHandle[]): void
}
}
-// A world-space rect on the 2D plane → a CSS-px screen rect, from two opposite
-// corners. Exact head-on, which is where the 2D frames it draws mean anything;
-// turned, it is the AABB of a quad. Null if off-camera / no view.
-function worldRectToScreen(
- cx: number,
- cy: number,
- halfW: number,
- halfH: number,
-): { x: number; y: number; w: number; h: number } | null {
- const a = ViewportController.worldToClient(cx - halfW, cy + halfH);
- const b = ViewportController.worldToClient(cx + halfW, cy - halfH);
- if (!a || !b) return null;
- return { x: Math.min(a.x, b.x), y: Math.min(a.y, b.y), w: Math.abs(b.x - a.x), h: Math.abs(b.y - a.y) };
+/** A world rect on the 2D plane, as the four screen points it projects to (CSS px,
+ * clockwise from the top-left corner). Null when any corner is off-camera. */
+type Quad = [{ x: number; y: number }, { x: number; y: number }, { x: number; y: number }, { x: number; y: number }];
+
+function worldRectToQuad(cx: number, cy: number, halfW: number, halfH: number): Quad | null {
+ const pts = ([[-1, 1], [1, 1], [1, -1], [-1, -1]] as const).map(
+ ([sx, sy]) => ViewportController.worldToClient(cx + sx * halfW, cy + sy * halfH));
+ return pts.some((p) => !p) ? null : (pts as Quad);
}
+/** A quad as an SVG `points` list. */
+const quadPoints = (q: Quad): string => q.map((p) => `${p.x.toFixed(1)},${p.y.toFixed(1)}`).join(' ');
+
+/** Shape an SVG polygon to a quad. */
+function setPoints(el: Element | null, q: Quad): void {
+ el?.setAttribute('points', quadPoints(q));
+}
+
+/** A quad as one closed SVG subpath. */
+const quadPath = (q: Quad): string => `M${q.map((p) => `${p.x.toFixed(1)} ${p.y.toFixed(1)}`).join('L')}Z`;
+
/**
* Shape one outline polygon to the entity's projected hull, or hide it. `sid` null
* (engine not ready) hides it too — a stale outline on a scene that is not there
@@ -1353,94 +1359,98 @@ export function Viewport() {
// Show the design/device overlay in UI mode (design frame always) OR in any mode
// once a real device is picked — reading the project design resolution when the
// scene has no Canvas, so a gameplay scene previews on devices without a UI layer.
- // Not from a turned eye: it is all screen rects on the 2D plane, and only a
- // head-on view projects that plane to a rect — perspective head-on still does,
- // so what this asks about is the eye and not the projection.
const ms0 = useEditorMode.getState();
- const ci = ready && showG && !ViewportController.isOrbited()
- && (activeModeOverlays().designFrame || ms0.device !== 'design')
+ const ci = ready && showG && (activeModeOverlays().designFrame || ms0.device !== 'design')
? ViewportController.screenInfo()
: null;
- // The design frame lives in the UI world scale: 1 unit = 1 design px (the invariant
- // CameraPlugin's uiLayoutRect / buildCameraInfo use). pixelsPerUnit is physics-only
- // and must NOT scale it, or the frame renders 100× off from where UI lays out.
- const des = ci
- ? worldRectToScreen(ci.cx, ci.cy, ci.designResolution.x / 2, ci.designResolution.y / 2)
+ const ms = useEditorMode.getState();
+ // The oriented device size (null for 'design'), from the SAME source App.tsx
+ // feeds to uiLayoutRect — so this frame and the UI layout cannot drift apart.
+ const dd = ci ? deviceDims(ms.device, ms.orientation, ProjectStore.getSnapshot()?.screenPresets) : null;
+ // Every frame here is a rect on the 2D plane, kept in WORLD half-extents and
+ // projected corner by corner — a quad from any eye, a rect only head-on. Its
+ // scale is 1 unit = 1 design px (uiLayoutRect's invariant), never pixelsPerUnit.
+ const desHalf = ci
+ ? { w: ci.designResolution.x / 2, h: ci.designResolution.y / 2 }
: null;
- if (ci && des) {
+ const devHalf = ci && desHalf && dd
+ ? (() => {
+ const deviceAspect = dd.w / dd.h;
+ const h = computeEffectiveOrthoSize(
+ desHalf.h, ci.designResolution.x / ci.designResolution.y,
+ deviceAspect, ci.scaleMode, ci.matchWidthOrHeight,
+ );
+ return { w: h * deviceAspect, h };
+ })()
+ : desHalf;
+ const des = ci && desHalf ? worldRectToQuad(ci.cx, ci.cy, desHalf.w, desHalf.h) : null;
+ const dev = ci && devHalf ? worldRectToQuad(ci.cx, ci.cy, devHalf.w, devHalf.h) : des;
+ if (ci && desHalf && devHalf && des && dev) {
dsvg.style.opacity = '1';
- const ms = useEditorMode.getState();
const preset = screenPresetById(ms.device, ProjectStore.getSnapshot()?.screenPresets);
- // Device visible frame: the design resolution fit into the simulated device's
- // aspect per the Canvas scaleMode. `dd` is the oriented device size (null for the
- // 'design' sentinel) — the SAME source App.tsx feeds to uiLayoutRect, so this
- // frame and the actual UI layout share one aspect and can't drift.
- const dd = deviceDims(ms.device, ms.orientation, ProjectStore.getSnapshot()?.screenPresets);
- let dev = des;
- if (dd) {
- const deviceAspect = dd.w / dd.h;
- const designAspect = ci.designResolution.x / ci.designResolution.y;
- const halfH = computeEffectiveOrthoSize(
- ci.designResolution.y / 2, designAspect, deviceAspect, ci.scaleMode, ci.matchWidthOrHeight,
- );
- dev = worldRectToScreen(ci.cx, ci.cy, halfH * deviceAspect, halfH) ?? des;
- }
- setRectAttrs(dsvg.querySelector('.df-design'), des);
- setRectAttrs(dsvg.querySelector('.df-device'), dev);
+ setPoints(dsvg.querySelector('.df-design'), des);
+ setPoints(dsvg.querySelector('.df-device'), dev);
// Everything-outside-the-screen shading, drawn as one even-odd path (an outer
- // rect with the design rect punched out). Two cases share the geometry:
+ // region with the design frame punched out). Two cases share the geometry:
// • a simulated device that CONTAINS the design → the device's letterbox bars,
// tinted the canvas background (how the game bars would look on that screen);
// • the 'design' device (no simulation) → the design frame IS the screen, so
// dim the rest of the free scene view with a neutral scrim. Without this the
// authored resolution is only a thin outline and reads as "still landscape".
- // A device that CROPS the design (dev smaller) shows no bars.
+ // A device that CROPS the design (dev smaller) shows no bars — measured in
+ // world units, where the comparison is what it says rather than a projection.
const lb = dsvg.querySelector('.df-letterbox') as SVGPathElement | null;
if (lb) {
- const punch = (o: { x: number; y: number; w: number; h: number }): string =>
- `M${o.x},${o.y}h${o.w}v${o.h}h${-o.w}Z M${des.x},${des.y}h${des.w}v${des.h}h${-des.w}Z`;
const hasDevice = dd != null;
- const deviceContains =
- dev.w >= des.w - 0.5 && dev.h >= des.h - 0.5 && (dev.w > des.w + 0.5 || dev.h > des.h + 0.5);
+ const grew = (a: number, b: number): boolean => a >= b - 0.5;
+ const deviceContains = grew(devHalf.w, desHalf.w) && grew(devHalf.h, desHalf.h)
+ && (devHalf.w > desHalf.w + 0.5 || devHalf.h > desHalf.h + 0.5);
if (hasDevice && deviceContains) {
- lb.setAttribute('d', punch(dev));
+ lb.setAttribute('d', quadPath(dev) + quadPath(des));
const bg = ci.backgroundColor;
lb.style.fill = `rgba(${Math.round(bg.r * 255)},${Math.round(bg.g * 255)},${Math.round(bg.b * 255)},0.55)`;
lb.style.opacity = '1';
} else if (!hasDevice) {
- lb.setAttribute('d', punch({ x: 0, y: 0, w: dsvg.clientWidth, h: dsvg.clientHeight }));
+ const w = dsvg.clientWidth;
+ const h = dsvg.clientHeight;
+ lb.setAttribute('d', `M0,0h${w}v${h}h${-w}Z${quadPath(des)}`);
lb.style.fill = 'rgba(0,0,0,0.32)';
lb.style.opacity = '1';
} else {
lb.style.opacity = '0';
}
}
- // Safe-area inset within the device frame (device px → screen px by the frame ratio).
- const safe = dsvg.querySelector('.df-safe') as SVGRectElement | null;
+ // Safe-area inset within the device frame. The insets are device px; one
+ // world unit per device px converts them, so the inset rect is a world rect
+ // like every other frame here rather than a screen-space shrink.
+ const safe = dsvg.querySelector('.df-safe') as SVGPolygonElement | null;
if (safe) {
- if (ms.showSafeArea && preset.safe && dd) {
- const sx = dev.w / dd.w;
- const sy = dev.h / dd.h;
- setRectAttrs(safe, {
- x: dev.x + preset.safe.left * sx,
- y: dev.y + preset.safe.top * sy,
- w: dev.w - (preset.safe.left + preset.safe.right) * sx,
- h: dev.h - (preset.safe.top + preset.safe.bottom) * sy,
- });
- safe.style.opacity = '1';
- } else {
- safe.style.opacity = '0';
- }
+ const q = ms.showSafeArea && preset.safe && dd
+ ? (() => {
+ const sx = (devHalf.w * 2) / dd.w;
+ const sy = (devHalf.h * 2) / dd.h;
+ const left = ci.cx - devHalf.w + preset.safe.left * sx;
+ const right = ci.cx + devHalf.w - preset.safe.right * sx;
+ // Layout space is y-down: the `top` inset comes off the high edge.
+ const top = ci.cy + devHalf.h - preset.safe.top * sy;
+ const bottom = ci.cy - devHalf.h + preset.safe.bottom * sy;
+ return worldRectToQuad((left + right) / 2, (top + bottom) / 2,
+ (right - left) / 2, (top - bottom) / 2);
+ })()
+ : null;
+ if (q) { setPoints(safe, q); safe.style.opacity = '1'; } else { safe.style.opacity = '0'; }
}
- // The authored resolution, pinned to the frame's top-left corner but clamped
- // into the viewport — when the frame corner pans off-screen the label sticks
- // to the nearest edge instead of getting clipped away.
+ // The authored resolution, pinned to the frame's near corner but clamped into
+ // the viewport — when that corner pans off-screen the label sticks to the
+ // nearest edge instead of getting clipped away.
const dlabel = designLabelRef.current;
if (dlabel) {
dlabel.textContent = `${ci.designResolution.x} × ${ci.designResolution.y}`;
+ const anchorX = Math.min(...des.map((p) => p.x));
+ const anchorY = Math.min(...des.map((p) => p.y));
// Top clamp (48) clears the docked scene toolbar (38px) at the viewport top.
- const lx = Math.min(Math.max(des.x + 4, 4), Math.max(dsvg.clientWidth - dlabel.offsetWidth - 4, 4));
- const ly = Math.min(Math.max(des.y + 4, 48), Math.max(dsvg.clientHeight - dlabel.offsetHeight - 4, 48));
+ const lx = Math.min(Math.max(anchorX + 4, 4), Math.max(dsvg.clientWidth - dlabel.offsetWidth - 4, 4));
+ const ly = Math.min(Math.max(anchorY + 4, 48), Math.max(dsvg.clientHeight - dlabel.offsetHeight - 4, 48));
dlabel.style.transform = `translate(${lx}px, ${ly}px)`;
dlabel.style.opacity = '1';
}
@@ -2239,8 +2249,9 @@ export function Viewport() {
const comps = src != null ? SceneModel.entityBySource(src)?.components : undefined;
if (src != null && comps && !comps.some((c) => c.type === 'Canvas')) {
const rt = SceneModel.runtimeFor(src);
- const obb = rt != null ? ViewportController.uiEntityWorldOBB(rt) : null;
- if (obb) r = worldRectToScreen(obb.cx, obb.cy, obb.hw, obb.hh);
+ // The same rect the container's selection outline uses, which for a UINode
+ // goes through the UI camera the layout box is actually in.
+ if (rt != null) r = ViewportController.getEntityScreenRect(rt);
}
}
if (r) {
@@ -2929,9 +2940,9 @@ export function Viewport() {
<svg ref={designSvgRef} className="viewport__design-svg" style={{ opacity: 0 }} aria-hidden="true">
<path className="df-letterbox" fillRule="evenodd" />
- <rect className="df-device" />
- <rect className="df-safe" />
- <rect className="df-design" />
+ <polygon className="df-device" />
+ <polygon className="df-safe" />
+ <polygon className="df-design" />
</svg>
<div ref={designLabelRef} className="viewport__design-label" style={{ opacity: 0 }} aria-hidden="true" />