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
feat(editor): the target screen the game is RUN at, not just authored against
esengined0e2c248c64d
diff --git a/desktop/src/components/OverlayMenu.tsx b/desktop/src/components/OverlayMenu.tsxnew file mode 100644index 000000000..63f2e83d9--- /dev/null+++ b/desktop/src/components/OverlayMenu.tsx@@ -0,0 +1,72 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file OverlayMenu.tsx — the glass dropdown the viewport overlay bars are made of.+ *+ * Lives here rather than inside a panel because the Viewport and the Game panel+ * both carry overlay controls, and two copies of a menu row is how the two bars+ * start looking almost the same.+ */+import { useRef, type ReactNode } from 'react';+import { Check, ChevronDown, type LucideIcon } from 'lucide-react';+import { Popover, usePopover } from '@/components/Popover';++export function OvDropdown({+ icon: Icon,+ label,+ title,+ children,+}: {+ icon: LucideIcon;+ label: ReactNode;+ title?: string;+ children: ReactNode;+}) {+ const pop = usePopover();+ const btnRef = useRef<HTMLButtonElement>(null);+ return (+ <>+ <button+ ref={btnRef}+ type="button"+ className={`ovbtn${pop.isOpen ? ' open' : ''}`}+ title={title}+ aria-haspopup="menu"+ aria-expanded={pop.isOpen}+ onClick={() => (pop.isOpen ? pop.close() : pop.open(btnRef.current))}+ >+ <Icon className="ic" size={13} strokeWidth={1.9} />+ {label}+ <ChevronDown className="cv" size={9} strokeWidth={2.5} />+ </button>+ {/* Item clicks bubble to the menu to dismiss; each runs its own handler. */}+ {pop.isOpen && pop.anchor && (+ <Popover anchor={pop.anchor} width="auto" className="popover--glass" onClose={pop.close}>+ <div role="menu" onClick={pop.close}>+ {children}+ </div>+ </Popover>+ )}+ </>+ );+}++/** Multi-toggle menu row (checkbox box) — for the Show Flags menu. */+export function DdCheck({ on, label, onClick }: { on: boolean; label: string; onClick: () => void }) {+ return (+ <div className={`ovmenu-item${on ? ' on' : ''}`} role="menuitemcheckbox" aria-checked={on} onClick={onClick}>+ <span className="chk">{on && <Check size={8} strokeWidth={3.5} />}</span>+ <span className="l">{label}</span>+ </div>+ );+}++/** Single-select menu row (tick mark, shown when active) — for the Snap menu. */+export function DdRadio({ on, label, onClick }: { on: boolean; label: string; onClick: () => void }) {+ return (+ <div className={`ovmenu-item${on ? ' on' : ''}`} role="menuitemradio" aria-checked={on} onClick={onClick}>+ <span className="tk"><Check size={11} strokeWidth={3} /></span>+ <span className="l">{label}</span>+ </div>+ );+}diff --git a/desktop/src/mode/TargetScreen.tsx b/desktop/src/mode/TargetScreen.tsxnew file mode 100644index 000000000..1ecc9f0fc--- /dev/null+++ b/desktop/src/mode/TargetScreen.tsx@@ -0,0 +1,111 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file TargetScreen.tsx — "which screen am I looking at", for every view that+ * shows the game.+ *+ * The device selection used to be a UI-mode authoring preview and nothing else:+ * the edit viewport drew a letterboxed design frame with it, while the running+ * game — in the viewport or in the Game panel — ignored it and simply filled+ * whatever the panel had been dragged to. So a project could be authored for a+ * phone and only ever be RUN at whatever aspect the dock happened to be, which+ * is the one thing the setting exists to prevent.+ *+ * One selection now drives both. Editing previews it; play is constrained to it.+ */+import { Smartphone } from 'lucide-react';+import { t } from '@/i18n';+import { OvDropdown, DdCheck, DdRadio } from '@/components/OverlayMenu';+import { useEditorMode } from '@/store/editorModeStore';+import { RESOLUTION_PRESETS, RESOLUTION_PRESET_BY_ID, deviceDims } from '@/mode/resolutionPresets';++/**+ * The dropdown: device presets, orientation, and (authoring only) the safe-area+ * overlay. `design` — the no-simulation sentinel — leaves play filling its host,+ * which is what someone authoring for desktop wants.+ *+ * `designAspect` is the authored resolution the orientation snaps to when a real+ * device is picked; pass it where a scene Canvas is in play, omit it elsewhere.+ */+export function TargetScreenDropdown({+ designAspect,+ showSafeAreaToggle = false,+}: {+ designAspect?: { w: number; h: number };+ showSafeAreaToggle?: boolean;+}) {+ const device = useEditorMode((s) => s.device);+ const orientation = useEditorMode((s) => s.orientation);+ const showSafeArea = useEditorMode((s) => s.showSafeArea);++ return (+ <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={() => {+ const ms = useEditorMode.getState();+ ms.setDevice(p.id);+ // Picking a real device snaps the orientation to the design's own+ // (a landscape design previews on a landscape phone); the explicit+ // orientation radios below still override.+ if (p.w > 0 && designAspect) {+ const want = designAspect.w >= designAspect.h ? 'landscape' : 'portrait';+ if (ms.orientation !== want) ms.toggleOrientation();+ }+ }}+ />+ ))}+ <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()}+ />+ {showSafeAreaToggle && (+ <>+ <div className="ovmenu-lbl">{t('vp.overlay')}</div>+ <DdCheck on={showSafeArea} label={t('vp.safeArea')} onClick={() => useEditorMode.getState().toggleSafeArea()} />+ </>+ )}+ </OvDropdown>+ );+}++/**+ * How a play host should be sized for the current selection.+ *+ * The letterbox is done in CSS, on the ELEMENT hosting the realm, rather than+ * inside the engine: the realm then sees a canvas of the device's shape and its+ * own ScreenScaling adapts to it exactly as it would on the real hardware. Doing+ * it in the engine instead would mean two things fitting the same content and+ * disagreeing about the result.+ *+ * `null` (the `design` sentinel) means "fill the host" — no constraint.+ */+export function playHostAspectStyle(+ device: string,+ orientation: 'portrait' | 'landscape',+): React.CSSProperties | null {+ const d = deviceDims(device as never, orientation);+ if (!d) return null;+ return { aspectRatio: `${d.w} / ${d.h}`, maxWidth: '100%', maxHeight: '100%', width: 'auto', height: '100%' };+}++/** Label for the status readout: the simulated screen's pixel size, or null. */+export function targetScreenLabel(device: string, orientation: 'portrait' | 'landscape'): string | null {+ const d = deviceDims(device as never, orientation);+ return d ? `${d.w} × ${d.h}` : null;+}diff --git a/desktop/src/panels/GamePanel.tsx b/desktop/src/panels/GamePanel.tsxindex 7e04486ca..1cc1e35b5 100644--- a/desktop/src/panels/GamePanel.tsx+++ b/desktop/src/panels/GamePanel.tsx@@ -4,11 +4,16 @@ import { useEffect, useRef, useSyncExternalStore } from 'react';import { t } from '@/i18n';import { PlayRealm, PlayRealms } from '@/engine/PlayRealm';import { useEditorStore } from '@/store/editorStore';+import { useEditorMode } from '@/store/editorModeStore';+import { TargetScreenDropdown, playHostAspectStyle, targetScreenLabel } from '@/mode/TargetScreen';// The "Game" dock panel: hosts the isolated play-realm iframe (the realm owns the// element + re-parents it here, so the realm survives panel remounts). The host// div has NO React children — the realm appends the iframe into it manually — so a// status overlay is a separate absolutely-positioned sibling.+//+// The overlay bar carries the target-screen control, so a game can be run at a+// device's shape instead of at whatever aspect the dock was last dragged to.function overlayFor(snap: { playing: boolean; ready: boolean; error: string | null }): string | null {return snap.error@@ -24,6 +29,8 @@ export function GamePanel() {const hostRef = useRef<HTMLDivElement>(null);const snap = useSyncExternalStore(PlayRealm.subscribe, PlayRealm.getSnapshot);const playTarget = useEditorStore((s) => s.playTarget);+ const device = useEditorMode((s) => s.device);+ const orientation = useEditorMode((s) => s.orientation);// Only host the realm iframe in 'window' mode — in 'viewport' mode the Viewport// owns it (one iframe, one mount). Guards against a stale Game tab stealing it.@@ -36,9 +43,18 @@ export function GamePanel() {}, [playTarget]);const overlay = overlayFor(snap);+ const aspect = playHostAspectStyle(device, orientation);+ const sizeLabel = targetScreenLabel(device, orientation);+return (<div className="game-panel">- <div className="game-panel__host" ref={hostRef} />+ <div className="game-panel__bar">+ <TargetScreenDropdown />+ {sizeLabel && <span className="game-panel__size">{sizeLabel}</span>}+ </div>+ <div className="game-panel__stage">+ <div className="game-panel__host" style={aspect ?? undefined} ref={hostRef} />+ </div>{overlay && <div className={`game-panel__overlay${snap.error ? ' error' : ''}`}>{overlay}</div>}</div>);diff --git a/desktop/src/panels/Viewport.tsx b/desktop/src/panels/Viewport.tsxindex 452128e85..a2d4d69c3 100644--- a/desktop/src/panels/Viewport.tsx+++ b/desktop/src/panels/Viewport.tsx@@ -1,10 +1,10 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport { memo, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';-import type { PointerEvent as ReactPointerEvent, DragEvent as ReactDragEvent, ReactNode } from 'react';+import type { PointerEvent as ReactPointerEvent, DragEvent as ReactDragEvent } from 'react';import {MousePointer2, Move, RotateCw, Scale3d, Grid3x3, Frame,- Camera, Check, ChevronDown, Loader2, TriangleAlert, Lightbulb, Sparkles, Globe, Crosshair, Smartphone, Monitor, Magnet, Axis3d, Hexagon, MapPin, type LucideIcon,+ Camera, Loader2, TriangleAlert, Lightbulb, Sparkles, Globe, Crosshair, Monitor, Magnet, Axis3d, Hexagon, MapPin, type LucideIcon,AlignStartVertical, AlignCenterVertical, AlignEndVertical,AlignStartHorizontal, AlignCenterHorizontal, AlignEndHorizontal,AlignHorizontalDistributeCenter, AlignVerticalDistributeCenter,@@ -16,7 +16,7 @@ import { useTilemapPaint, type PaintTool } from '@/store/tilemapPaintStore';import { exitTilePaint, isTilePaintMode, selectedTilemapCellSize } from '@/tools/tileMode';import { activeMode, activeModeOverlays } from '@/mode/activeMode';import { useEditorMode } from '@/store/editorModeStore';-import { RESOLUTION_PRESETS, RESOLUTION_PRESET_BY_ID, DESIGN_RESOLUTION_PRESETS, deviceDims } from '@/mode/resolutionPresets';+import { RESOLUTION_PRESET_BY_ID, DESIGN_RESOLUTION_PRESETS, deviceDims } from '@/mode/resolutionPresets';import { buildStampGhost } from '@/tools/tileStampGhost';import { alignSelection, distributeSelection } from '@/tools/alignTools';import { TilemapAPI, tileIdOf, isNonOrthogonal, isCollisionPaletteRef, buildCollisionPaletteModel, UINode, DimensionUnit, computeEffectiveOrthoSize, type TileCollisionPiece, type TilesetModel } from 'esengine';@@ -40,7 +40,8 @@ import { PerfMonitor } from '@/engine/PerfMonitor';import { PerfOverlay } from '@/components/PerfOverlay';import { PluginOverlays } from '@/plugins/PluginOverlays';import { Perf } from '@/components/Perf';-import { Popover, usePopover } from '@/components/Popover';+import { OvDropdown, DdRadio } from '@/components/OverlayMenu';+import { TargetScreenDropdown, playHostAspectStyle } from '@/mode/TargetScreen';import { usePanelWindow, eventWindow } from '@/components/PanelWindow';import type { ToolMode, EntityId } from '@/types';import { resolveActiveTool, type EditorTool, type ToolContext, type PointerInput } from '@/tools';@@ -520,65 +521,6 @@ function OvTool({// A viewport overlay dropdown (the "show flags" / "snap" menus): an .ovbtn// trigger with an icon, a label, and a chevron, over a glass <Popover> holding// the check/radio rows. Closes on item-click, outside press, scroll, or Escape.-function OvDropdown({- icon: Icon,- label,- title,- children,-}: {- icon: LucideIcon;- label: ReactNode;- title?: string;- children: ReactNode;-}) {- const pop = usePopover();- const btnRef = useRef<HTMLButtonElement>(null);- return (- <>- <button- ref={btnRef}- type="button"- className={`ovbtn${pop.isOpen ? ' open' : ''}`}- title={title}- aria-haspopup="menu"- aria-expanded={pop.isOpen}- onClick={() => (pop.isOpen ? pop.close() : pop.open(btnRef.current))}- >- <Icon className="ic" size={13} strokeWidth={1.9} />- {label}- <ChevronDown className="cv" size={9} strokeWidth={2.5} />- </button>- {/* Item clicks bubble to the menu to dismiss; each runs its own handler. */}- {pop.isOpen && pop.anchor && (- <Popover anchor={pop.anchor} width="auto" className="popover--glass" onClose={pop.close}>- <div role="menu" onClick={pop.close}>- {children}- </div>- </Popover>- )}- </>- );-}--// Multi-toggle menu row (checkbox box) — for the Show Flags menu.-function DdCheck({ on, label, onClick }: { on: boolean; label: string; onClick: () => void }) {- return (- <div className={`ovmenu-item${on ? ' on' : ''}`} role="menuitemcheckbox" aria-checked={on} onClick={onClick}>- <span className="chk">{on && <Check size={8} strokeWidth={3.5} />}</span>- <span className="l">{label}</span>- </div>- );-}--// Single-select menu row (tick mark, shown when active) — for the Snap menu.-function DdRadio({ on, label, onClick }: { on: boolean; label: string; onClick: () => void }) {- return (- <div className={`ovmenu-item${on ? ' on' : ''}`} role="menuitemradio" aria-checked={on} onClick={onClick}>- <span className="tk"><Check size={11} strokeWidth={3} /></span>- <span className="l">{label}</span>- </div>- );-}// Only this node re-renders per mouse move; the HUD follows the slow stats cadence.function HudCursor() {@@ -770,9 +712,12 @@ export function Viewport() {// 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.+ // The per-frame overlay draw reads these through getState(); subscribing keeps+ // the component re-rendering when they change, and the play host below sizes+ // itself from the same values.const device = useEditorMode((s) => s.device);const orientation = useEditorMode((s) => s.orientation);- const showSafeArea = useEditorMode((s) => s.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);@@ -2081,46 +2026,10 @@ export function Viewport() {))}<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={() => {- const ms = useEditorMode.getState();- ms.setDevice(p.id);- // Picking a real device snaps the orientation to the design's own- // (a landscape design previews on a landscape phone); the explicit- // orientation radios below still override.- if (p.w > 0) {- const dw = sceneCanvas ? sceneCanvas.x : projectDesign.width;- const dh = sceneCanvas ? sceneCanvas.y : projectDesign.height;- const want = dw >= dh ? 'landscape' : 'portrait';- if (ms.orientation !== want) ms.toggleOrientation();- }- }}- />- ))}- <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>+ <TargetScreenDropdown+ designAspect={sceneCanvas ? { w: sceneCanvas.x, h: sceneCanvas.y } : { w: projectDesign.width, h: projectDesign.height }}+ showSafeAreaToggle+ /><span className="ov-divider" /><OvDropdownicon={Magnet}@@ -2498,7 +2407,15 @@ export function Viewport() {button obscuring the running game. */}{playTarget === 'viewport' && (<div className={`viewport__play${playInViewport ? '' : ' viewport__play--parked'}`}>- <div className="viewport__play-host" ref={playHostRef} />+ {/* Same target screen the edit overlay previews: playing in the viewport+ letterboxes to the picked device instead of filling the dock. */}+ <div className="viewport__play-stage">+ <div+ className="viewport__play-host"+ style={playHostAspectStyle(device, orientation) ?? undefined}+ ref={playHostRef}+ />+ </div>{playInViewport && (!realm.ready || realm.error) && (<div className={`viewport__play-status${realm.error ? ' error' : ''}`}>{realm.error ? t('vp.playFailed', { error: realm.error }) : t('vp.startingGame')}diff --git a/desktop/src/theme/viewport.css b/desktop/src/theme/viewport.cssindex d4b7cbd27..ff1e5ce8d 100644--- a/desktop/src/theme/viewport.css+++ b/desktop/src/theme/viewport.css@@ -267,7 +267,7 @@warm re-Play) but is invisible, non-interactive, and behind the editor stage.visibility (not display:none) keeps the iframe's GL context alive. */.viewport__play--parked { visibility: hidden; pointer-events: none; z-index: -1; }-.viewport__play-host { position: absolute; inset: 0; }+.viewport__play-host { width: 100%; height: 100%; }.viewport__play-host iframe { width: 100%; height: 100%; border: 0; display: block; }.viewport__play-status {position: absolute;@@ -338,7 +338,25 @@/* Game view (isolated play realm iframe) — REARCH_EDITOR_REALM Phase R. */.game-panel { position: relative; width: 100%; height: 100%; background: var(--srf-1); overflow: hidden; }-.game-panel__host { position: absolute; inset: 0; }+/* Bar over the stage rather than above it: the game keeps the full panel, and the+ controls read as viewport chrome — the same glass buttons the viewport uses. */+.game-panel__bar {+ position: absolute;+ top: 6px;+ left: 6px;+ z-index: 3;+ display: flex;+ align-items: center;+ gap: 6px;+}+.game-panel__size { color: var(--text-mute); font-size: var(--fs-xs); font-variant-numeric: tabular-nums; }+/* The stage centres a host that may be narrower than the panel: a device+ selection letterboxes by SHAPING the host, so the realm's canvas is the+ device's shape and its ScreenScaling adapts exactly as on real hardware. */+.game-panel__stage { position: absolute; inset: 0; display: flex; align-items: center; justify-content: center; }+.game-panel__host { width: 100%; height: 100%; }+/* Play-in-viewport gets the same letterbox: one target screen, both views. */+.viewport__play-stage { position: absolute; inset: 0; display: flex; align-items: center; justify-content: center; }.game-panel__overlay {position: absolute;inset: 0;diff --git a/desktop/tests/target-screen.test.ts b/desktop/tests/target-screen.test.tsnew file mode 100644index 000000000..e2ef000ed--- /dev/null+++ b/desktop/tests/target-screen.test.ts@@ -0,0 +1,51 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file One target screen, obeyed by both the edit viewport and the running game.+ *+ * The device selection used to shape only the authoring overlay: a game played in+ * the viewport or the Game panel filled whatever the dock had been dragged to, so+ * a project authored for a phone was never actually RUN at a phone's shape. These+ * pin the sizing rule the play hosts apply.+ */+import { describe, it, expect } from 'vitest';+import { playHostAspectStyle, targetScreenLabel } from '@/mode/TargetScreen';+import { deviceDims } from '@/mode/resolutionPresets';++describe('play host sizing', () => {+ it('leaves the host unconstrained for the `design` sentinel', () => {+ // No simulated device means "fill the panel" — the behaviour someone+ // authoring for desktop expects, and what every view did before.+ expect(playHostAspectStyle('design', 'landscape')).toBeNull();+ expect(playHostAspectStyle('design', 'portrait')).toBeNull();+ expect(targetScreenLabel('design', 'landscape')).toBeNull();+ });++ it('constrains the host to the device aspect, orientation applied', () => {+ const portrait = playHostAspectStyle('iphone', 'portrait');+ const landscape = playHostAspectStyle('iphone', 'landscape');++ expect(portrait?.aspectRatio).toBe('1170 / 2532');+ expect(landscape?.aspectRatio).toBe('2532 / 1170');+ // Fits INSIDE the panel either way rather than overflowing it.+ expect(portrait?.maxWidth).toBe('100%');+ expect(portrait?.maxHeight).toBe('100%');+ });++ it('reports the simulated pixel size the aspect came from', () => {+ expect(targetScreenLabel('iphone', 'portrait')).toBe('1170 × 2532');+ expect(targetScreenLabel('ipad', 'landscape')).toBe('2360 × 1640');+ expect(targetScreenLabel('720p', 'portrait')).toBe('720 × 1280');+ });++ it('agrees with the dims the authoring overlay draws from', () => {+ // The frame the edit viewport draws and the box the game runs in must come+ // from one source, or the preview stops predicting the run.+ for (const device of ['iphone', 'ipad', '1080p', '720p'] as const) {+ for (const orientation of ['portrait', 'landscape'] as const) {+ const d = deviceDims(device, orientation)!;+ expect(playHostAspectStyle(device, orientation)?.aspectRatio).toBe(`${d.w} / ${d.h}`);+ }+ }+ });+});