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
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.mjsnew file mode 100644index 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.tsxindex 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" />