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): device preview reads project design resolution, no Canvas needed

yhh40c1ed49dbfa
diff --git a/desktop/src/engine/ViewportController.ts b/desktop/src/engine/ViewportController.ts
index 56a79501b..a77a92cc0 100644
--- a/desktop/src/engine/ViewportController.ts
+++ b/desktop/src/engine/ViewportController.ts
@@ -8,6 +8,7 @@ import {
} from 'esengine';
import type { EntityId } from '@/types';
import { EngineHost } from './EngineHost';
+import { projectDesignSeed } from './entitySources';
import { SceneModel } from './SceneModel';
import {
type OBB,
@@ -86,6 +87,18 @@ function clientToScreen(clientX: number, clientY: number): { sx: number; sy: num
};
}
+/** The "screen" the design/device preview draws against — a Canvas' presentation
+ * fields, or the project design resolution when no Canvas is in the scene. */
+export interface EditorScreenInfo {
+ cx: number;
+ cy: number;
+ designResolution: { x: number; y: number };
+ pixelsPerUnit: number;
+ scaleMode: number;
+ matchWidthOrHeight: number;
+ backgroundColor: { r: number; g: number; b: number; a: number };
+}
+
// Picking and screen<->world conversions for the viewport, all routed through
// the engine's own camera matrices (no projection assumptions).
export const ViewportController = {
@@ -376,9 +389,9 @@ export const ViewportController = {
*/
frameCanvas(): void {
const view = editorView();
- const ci = this.canvasInfo();
+ const ci = this.screenInfo(); // Canvas if present, else the project design rect at origin
const panel = EngineHost.canvas;
- if (!view || !ci) return;
+ if (!view) return;
const desHalfW = ci.designResolution.x / 2;
const desHalfH = ci.designResolution.y / 2;
if (desHalfW <= 0 || desHalfH <= 0) return;
@@ -528,14 +541,7 @@ export const ViewportController = {
* Reads the first entity carrying a Canvas (the same singleton-per-scene assumption
* as the runtime's registry_getCanvasEntity), centered on its Transform.
*/
- canvasInfo(): {
- cx: number; cy: number;
- designResolution: { x: number; y: number };
- pixelsPerUnit: number;
- scaleMode: number;
- matchWidthOrHeight: number;
- backgroundColor: { r: number; g: number; b: number; a: number };
- } | null {
+ canvasInfo(): EditorScreenInfo | null {
const world = EngineHost.world;
if (!world) return null;
for (const e of world.getAllEntities()) {
@@ -561,6 +567,31 @@ export const ViewportController = {
return null;
},
+ /**
+ * The effective "screen" for the design/device preview: the scene's Canvas when
+ * present (UI-authored), else the PROJECT design resolution centered at origin.
+ * This is what decouples the device preview from the UI layer — a pure gameplay
+ * scene (no Canvas) still previews on any device against the project reference
+ * resolution, and the device dropdown works in any editor mode. Never null.
+ *
+ * Without a Canvas the fit uses FixedHeight (the engine's Canvas default) so the
+ * device frame has a defined shape; once a project camera-fit is set it drives this.
+ */
+ screenInfo(): EditorScreenInfo {
+ const canvas = this.canvasInfo();
+ if (canvas) return canvas;
+ const d = projectDesignSeed();
+ return {
+ cx: 0, cy: 0,
+ designResolution: { x: d.width, y: d.height },
+ pixelsPerUnit: 100,
+ scaleMode: 1, // CanvasScaleMode.FixedHeight — the engine's Canvas default
+ matchWidthOrHeight: 0.5,
+ // No Canvas ⇒ no authored letterbox tint; the overlay falls back to a neutral scrim.
+ backgroundColor: { r: 0, g: 0, b: 0, a: 0 },
+ };
+ },
+
/**
* 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.
diff --git a/desktop/src/engine/entitySources.ts b/desktop/src/engine/entitySources.ts
index 5a90b3aae..e61d84a58 100644
--- a/desktop/src/engine/entitySources.ts
+++ b/desktop/src/engine/entitySources.ts
@@ -138,6 +138,13 @@ export function setCanvasDesignSeed(fn: () => { width: number; height: number })
canvasDesignSeed = fn;
}
+/** The project's reference (design) resolution, from the same provider that seeds new
+ * Canvases. Read by the editor's design/device preview so it works without a UI Canvas —
+ * exposed here (rather than importing ProjectStore) to keep the engine modules acyclic. */
+export function projectDesignSeed(): { width: number; height: number } {
+ return canvasDesignSeed?.() ?? { width: 1920, height: 1080 };
+}
+
const UI_WIDGET_ICON: Record<string, LucideIcon> = {
Button: SquareMousePointer,
Toggle: ToggleLeft,
diff --git a/desktop/src/panels/Viewport.tsx b/desktop/src/panels/Viewport.tsx
index e87c3bf47..5014bd97e 100644
--- a/desktop/src/panels/Viewport.tsx
+++ b/desktop/src/panels/Viewport.tsx
@@ -595,11 +595,16 @@ export function Viewport() {
// Derived from the pin + selection, so subscribe to the pin here.
useEditorMode((s) => s.pinned);
const mode = activeMode();
- // Device-preview controls for the UI-mode design-resolution overlay (the rAF reads
- // these via getState(); the subscriptions keep the device dropdown label current).
+ // Device-preview controls for the design-resolution overlay (the rAF reads these via
+ // getState(); the subscriptions keep the device dropdown label current). Available in
+ // any editor mode — a device preview is a screen concern, not a UI-layer one.
const device = useEditorMode((s) => s.device);
const orientation = useEditorMode((s) => s.orientation);
const showSafeArea = useEditorMode((s) => s.showSafeArea);
+ // Project design resolution — the reference the preview falls back to when the scene
+ // has no Canvas (so gameplay-only scenes preview on devices too). Reactive for the label.
+ const projectState = useSyncExternalStore(ProjectStore.subscribe, ProjectStore.getSnapshot);
+ const projectDesign = projectState?.designResolution ?? { width: 1920, height: 1080 };
// The scene's Canvas + its authored design resolution — the value the Design control
// edits (the single source of truth). Re-read on any model change so the label tracks.
const dataRev = useSyncExternalStore(SceneStore.subscribe, SceneStore.getRevision);
@@ -803,7 +808,13 @@ export function Viewport() {
// all projected from world each frame so they lock to pan/zoom.
const dsvg = designSvgRef.current;
if (dsvg) {
- const ci = ready && showG && activeModeOverlays().designFrame ? ViewportController.canvasInfo() : null;
+ // 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.
+ const ms0 = useEditorMode.getState();
+ 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.
@@ -1543,55 +1554,55 @@ export function Viewport() {
<Crosshair size={13} strokeWidth={1.9} />
<span className="val">{pivotMode === 'pivot' ? t('vp.pivot.pivot') : t('vp.pivot.center')}</span>
</button>
- {mode.overlays?.designFrame && (
- <>
- <span className="ov-divider" />
- {sceneCanvas && (
- <OvDropdown
- icon={Monitor}
- label={<span className="val">{sceneCanvas.x}×{sceneCanvas.y}</span>}
- title={t('vp.designResTitle')}
- >
- <div className="ovmenu-lbl">{t('vp.designRes')}</div>
- {DESIGN_RESOLUTION_PRESETS.map((p) => (
- <DdRadio
- key={p.label}
- on={sceneCanvas.x === p.x && sceneCanvas.y === p.y}
- label={p.label}
- onClick={() => {
- SceneCommands.setField(sceneCanvas.id, 'Canvas', 'designResolution', 'vec2', [p.x, p.y]);
- ViewportController.frameCanvas();
- }}
- />
- ))}
- <div className="ovmenu-lbl">{t('vp.designResExact')}</div>
- </OvDropdown>
- )}
- <OvDropdown
- icon={Smartphone}
- label={<span className="val">{RESOLUTION_PRESET_BY_ID[device].label}</span>}
- title={t('vp.deviceTitle')}
- >
- <div className="ovmenu-lbl">{t('vp.device')}</div>
- {RESOLUTION_PRESETS.map((p) => (
- <DdRadio key={p.id} on={device === p.id} label={p.label} onClick={() => useEditorMode.getState().setDevice(p.id)} />
- ))}
- <div className="ovmenu-lbl">{t('vp.orientation')}</div>
- <DdRadio
- on={orientation === 'landscape'}
- label={t('vp.landscape')}
- onClick={() => orientation !== 'landscape' && useEditorMode.getState().toggleOrientation()}
- />
- <DdRadio
- on={orientation === 'portrait'}
- label={t('vp.portrait')}
- onClick={() => orientation !== 'portrait' && useEditorMode.getState().toggleOrientation()}
- />
- <div className="ovmenu-lbl">{t('vp.overlay')}</div>
- <DdCheck on={showSafeArea} label={t('vp.safeArea')} onClick={() => useEditorMode.getState().toggleSafeArea()} />
- </OvDropdown>
- </>
- )}
+ {/* Screen controls — available in EVERY editor mode. Design resolution edits
+ the scene Canvas when present, else the project reference resolution; the
+ device dropdown simulates a real screen regardless of any UI layer. */}
+ <span className="ov-divider" />
+ <OvDropdown
+ icon={Monitor}
+ label={<span className="val">{sceneCanvas ? `${sceneCanvas.x}×${sceneCanvas.y}` : `${projectDesign.width}×${projectDesign.height}`}</span>}
+ title={t('vp.designResTitle')}
+ >
+ <div className="ovmenu-lbl">{t('vp.designRes')}</div>
+ {DESIGN_RESOLUTION_PRESETS.map((p) => (
+ <DdRadio
+ key={p.label}
+ on={sceneCanvas ? (sceneCanvas.x === p.x && sceneCanvas.y === p.y) : (projectDesign.width === p.x && projectDesign.height === p.y)}
+ label={p.label}
+ onClick={() => {
+ // With a Canvas, edit its authored resolution; without one, edit the
+ // project reference resolution (the source screenInfo/seeding read).
+ if (sceneCanvas) SceneCommands.setField(sceneCanvas.id, 'Canvas', 'designResolution', 'vec2', [p.x, p.y]);
+ else void ProjectStore.setDisplay({ width: p.x, height: p.y });
+ ViewportController.frameCanvas();
+ }}
+ />
+ ))}
+ <div className="ovmenu-lbl">{t('vp.designResExact')}</div>
+ </OvDropdown>
+ <OvDropdown
+ icon={Smartphone}
+ label={<span className="val">{RESOLUTION_PRESET_BY_ID[device].label}</span>}
+ title={t('vp.deviceTitle')}
+ >
+ <div className="ovmenu-lbl">{t('vp.device')}</div>
+ {RESOLUTION_PRESETS.map((p) => (
+ <DdRadio key={p.id} on={device === p.id} label={p.label} onClick={() => useEditorMode.getState().setDevice(p.id)} />
+ ))}
+ <div className="ovmenu-lbl">{t('vp.orientation')}</div>
+ <DdRadio
+ on={orientation === 'landscape'}
+ label={t('vp.landscape')}
+ onClick={() => orientation !== 'landscape' && useEditorMode.getState().toggleOrientation()}
+ />
+ <DdRadio
+ on={orientation === 'portrait'}
+ label={t('vp.portrait')}
+ onClick={() => orientation !== 'portrait' && useEditorMode.getState().toggleOrientation()}
+ />
+ <div className="ovmenu-lbl">{t('vp.overlay')}</div>
+ <DdCheck on={showSafeArea} label={t('vp.safeArea')} onClick={() => useEditorMode.getState().toggleSafeArea()} />
+ </OvDropdown>
</div>
</div>