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): self-contained viewport chrome + global toolbar goes global-only

yhhd24b08dff74e
diff --git a/desktop/src/commands/editorCommands.ts b/desktop/src/commands/editorCommands.ts
index 4d3b62c7d..7b4d75ed2 100644
--- a/desktop/src/commands/editorCommands.ts
+++ b/desktop/src/commands/editorCommands.ts
@@ -348,6 +348,27 @@ commands.register({
isChecked: () => editor().snapping,
run: () => editor().toggleSnapping(),
});
+commands.register({
+ id: 'view.toggleMinimap',
+ label: t('cmd.view.toggleMinimap'),
+ category: t('cat.view'),
+ isChecked: () => editor().showMinimap,
+ run: () => editor().toggleMinimap(),
+});
+commands.register({
+ id: 'view.toggleStats',
+ label: t('cmd.view.toggleStats'),
+ category: t('cat.view'),
+ isChecked: () => editor().showStats,
+ run: () => editor().toggleStats(),
+});
+commands.register({
+ id: 'view.toggleCoords',
+ label: t('cmd.view.toggleCoords'),
+ category: t('cat.view'),
+ isChecked: () => editor().showCoords,
+ run: () => editor().toggleCoords(),
+});
// — Editor —
commands.register({
diff --git a/desktop/src/engine/ViewportController.ts b/desktop/src/engine/ViewportController.ts
index be97752a1..f2b12f4cb 100644
--- a/desktop/src/engine/ViewportController.ts
+++ b/desktop/src/engine/ViewportController.ts
@@ -6,7 +6,7 @@ import {
ParticleEmitter, OneWayPlatform,
RevoluteJoint, DistanceJoint, PrismaticJoint, WeldJoint, WheelJoint, MotorJoint,
UINode, UICameraInfo, screenToUiWorld, uiWorldToScreen, uiPickAllWorld, type UICameraData,
- TilemapLayer, TilemapAPI, decodeTilemapChunks, tileCollisionOutlines,
+ TilemapLayer, TilemapAPI, decodeTilemapChunks, CHUNK_SIZE, tileCollisionOutlines,
tileCellCenter, tileCellOutline, isNonOrthogonal,
readColliderShapes, colliderShapeOutline, shapeCenter,
type TilesetModel, type TileCollisionPiece, type TileGridParams,
@@ -129,6 +129,15 @@ export interface ColliderGizmo {
points: ColliderPointHandle[];
}
+/** World AABB union of the scene's content — the extent the minimap fits into. */
+export interface MinimapBounds { minX: number; minY: number; maxX: number; maxY: number; }
+/** One schematic box in the minimap: an entity's world AABB + a coarse kind for colour. */
+export interface MinimapBox { x0: number; y0: number; x1: number; y1: number; kind: 'sprite' | 'tile' | 'icon'; }
+
+// Above this many boxes the minimap stops collecting (bounds still cover everything
+// collected) — a schematic overview needs the layout, not thousands of rects/rebuild.
+const MINIMAP_BOX_CAP = 800;
+
// Picking and screen<->world conversions for the viewport, all routed through
// the engine's own camera matrices (no projection assumptions).
export const ViewportController = {
@@ -432,6 +441,87 @@ export const ViewportController = {
view.orthoSize = clamp(halfH, 8, 40000);
},
+ /** World center + half-extents of the editor camera's visible rect — the minimap's
+ * camera indicator. Half-height = orthoSize; half-width = orthoSize × panel aspect. */
+ editorViewRect(): { cx: number; cy: number; halfW: number; halfH: number } | null {
+ const view = editorView();
+ const canvas = EngineHost.canvas;
+ if (!view) return null;
+ const aspect = canvas && canvas.height > 0 ? canvas.width / canvas.height : 1;
+ return { cx: view.x, cy: view.y, halfW: view.orthoSize * aspect, halfH: view.orthoSize };
+ },
+
+ /** Recenter the editor view on a world point (minimap click / drag navigation). Leaves
+ * zoom untouched — the minimap moves the camera, it doesn't reframe. */
+ centerViewOn(wx: number, wy: number): void {
+ const view = editorView();
+ if (!view) return;
+ view.x = wx;
+ view.y = wy;
+ },
+
+ /** World AABB of a painted tilemap layer from its chunk-grid bounds (cheap — chunk
+ * granularity, no per-tile scan). Tiles extend +x / −y from the layer origin, matching
+ * tileCollisionOutlines. Null for an empty / unsized layer. */
+ tilemapWorldAABB(rt: EntityId): { x0: number; y0: number; x1: number; y1: number } | null {
+ const world = EngineHost.world;
+ if (!world || !world.has(rt, TilemapLayer) || !world.has(rt, Transform)) return null;
+ const layer = world.get(rt, TilemapLayer) as { cellSize: { x: number; y: number } };
+ const tw = layer.cellSize.x, th = layer.cellSize.y;
+ if (!(tw > 0) || !(th > 0)) return null;
+ const chunks = decodeTilemapChunks(TilemapAPI.exportChunks(rt) || '');
+ if (chunks.length === 0) return null;
+ let cMinX = Infinity, cMinY = Infinity, cMaxX = -Infinity, cMaxY = -Infinity;
+ for (const c of chunks) {
+ cMinX = Math.min(cMinX, c.x); cMinY = Math.min(cMinY, c.y);
+ cMaxX = Math.max(cMaxX, c.x); cMaxY = Math.max(cMaxY, c.y);
+ }
+ const t = world.get(rt, Transform);
+ const ox = t.worldPosition.x, oy = t.worldPosition.y;
+ return {
+ x0: ox + cMinX * CHUNK_SIZE * tw,
+ x1: ox + (cMaxX + 1) * CHUNK_SIZE * tw,
+ y0: oy - (cMaxY + 1) * CHUNK_SIZE * th, // bottom (larger cellY = lower world y)
+ y1: oy - cMinY * CHUNK_SIZE * th, // top
+ };
+ },
+
+ /** Schematic overview of the scene for the viewport minimap: every entity's world AABB
+ * (a coarse kind for colour) and their union bounds. Sprites use their rendered box,
+ * tilemaps their painted extent, everything else an icon box — the same bounds Frame
+ * reads. Cheap enough to recompute on structural / data change; the minimap projects
+ * these into its panel and the rAF overlays the live camera rect. UI nodes are
+ * screen-space, so they're excluded. */
+ minimapBoxes(): { bounds: MinimapBounds | null; boxes: MinimapBox[] } {
+ const world = EngineHost.world;
+ const boxes: MinimapBox[] = [];
+ let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+ const add = (x0: number, y0: number, x1: number, y1: number, kind: MinimapBox['kind']) => {
+ if (boxes.length < MINIMAP_BOX_CAP) boxes.push({ x0, y0, x1, y1, kind });
+ minX = Math.min(minX, x0); minY = Math.min(minY, y0);
+ maxX = Math.max(maxX, x1); maxY = Math.max(maxY, y1);
+ };
+ if (world) {
+ for (const e of world.getAllEntities()) {
+ if (!world.valid(e) || !world.has(e, Transform) || world.has(e, UINode)) continue;
+ if (world.has(e, TilemapLayer)) {
+ const tb = this.tilemapWorldAABB(e);
+ if (tb) { add(tb.x0, tb.y0, tb.x1, tb.y1, 'tile'); continue; }
+ }
+ const b = this.entityBounds(e);
+ if (!b) continue;
+ let x0 = Infinity, y0 = Infinity, x1 = -Infinity, y1 = -Infinity;
+ for (const [wx, wy] of obbCorners(b)) {
+ x0 = Math.min(x0, wx); y0 = Math.min(y0, wy);
+ x1 = Math.max(x1, wx); y1 = Math.max(y1, wy);
+ }
+ add(x0, y0, x1, y1, world.has(e, Sprite) ? 'sprite' : 'icon');
+ }
+ }
+ const bounds = Number.isFinite(minX) ? { minX, minY, maxX, maxY } : null;
+ return { bounds, boxes };
+ },
+
/** Ids of the scene's camera entities — the camera-gizmo set (structural). */
cameraIds(): EntityId[] {
const world = EngineHost.world;
diff --git a/desktop/src/i18n/messages/commands.ts b/desktop/src/i18n/messages/commands.ts
index 75caf3ec2..93fcfda10 100644
--- a/desktop/src/i18n/messages/commands.ts
+++ b/desktop/src/i18n/messages/commands.ts
@@ -54,6 +54,9 @@ export const commandMessages = defineMessages({
'cmd.view.toggleCoordSpace': { en: 'Local Axes', zh: '局部坐标轴' },
'cmd.view.togglePivotMode': { en: 'Pivot (vs Center)', zh: '轴心(而非中心)' },
'cmd.view.toggleSnapping': { en: 'Snapping', zh: '吸附' },
+ 'cmd.view.toggleMinimap': { en: 'Minimap', zh: '小地图' },
+ 'cmd.view.toggleStats': { en: 'Stats HUD', zh: '统计信息' },
+ 'cmd.view.toggleCoords': { en: 'Coordinates HUD', zh: '坐标信息' },
// — Editor / play / build —
'cmd.settings.open': { en: 'Settings…', zh: '设置…' },
diff --git a/desktop/src/i18n/messages/viewport.ts b/desktop/src/i18n/messages/viewport.ts
index b7218a55e..f7c27a1fd 100644
--- a/desktop/src/i18n/messages/viewport.ts
+++ b/desktop/src/i18n/messages/viewport.ts
@@ -75,6 +75,7 @@ export const viewportMessages = defineMessages({
// — View controls —
'vp.frameSelected': { en: 'Frame Selected', zh: '聚焦所选' },
+ 'vp.minimap': { en: 'Minimap · click or drag to navigate', zh: '小地图 · 点击或拖动以导航' },
'vp.coordSpaceTitle': {
en: "Gizmo axes: World / Local (the active object's own axes)",
zh: 'Gizmo 坐标轴:世界 / 局部(活动对象自身的坐标轴)',
diff --git a/desktop/src/layout/MenuBar.tsx b/desktop/src/layout/MenuBar.tsx
index 8d38fe16d..aa6d4605e 100644
--- a/desktop/src/layout/MenuBar.tsx
+++ b/desktop/src/layout/MenuBar.tsx
@@ -12,6 +12,7 @@ import { LAYOUT_KEY } from '@/layout/DockLayout';
import { useEditorStore } from '@/store/editorStore';
import { ProjectStore } from '@/project/ProjectStore';
import { EditorHistory } from '@/engine/EditorHistory';
+import { PerfMonitor } from '@/engine/PerfMonitor';
import { Toasts } from '@/store/Toasts';
import { MenuItems, handleMenuListKey, type MenuItem } from '@/components/Menu';
import { commands, formatKeybinding } from '@/commands';
@@ -134,6 +135,11 @@ export function MenuBar() {
cmdItem('view.toggleTileCollision'),
cmdItem('view.togglePreviewFx'),
{ sep: true },
+ cmdItem('view.toggleMinimap'),
+ cmdItem('view.toggleStats'),
+ cmdItem('view.toggleCoords'),
+ { label: t('vp.flag.perf'), checked: PerfMonitor.getSnapshot().visible, onClick: () => PerfMonitor.toggleOverlay() },
+ { sep: true },
cmdItem('view.toggleCoordSpace'),
cmdItem('view.togglePivotMode'),
cmdItem('view.toggleSnapping'),
diff --git a/desktop/src/layout/Toolbar.tsx b/desktop/src/layout/Toolbar.tsx
index dbf2ee968..1b95d87e6 100644
--- a/desktop/src/layout/Toolbar.tsx
+++ b/desktop/src/layout/Toolbar.tsx
@@ -5,17 +5,9 @@ import {
Save,
Undo2,
Redo2,
- MousePointer2,
- Move,
- RotateCw,
- Scale3d,
- Magnet,
- Grid3x3,
- Sparkles,
Play,
Pause,
Square as Stop,
- Eye,
Hammer,
Monitor,
AppWindow,
@@ -27,15 +19,13 @@ import { IconButton } from '@/components/IconButton';
import { ContextMenu } from '@/components/Menu';
import { EditorHistory } from '@/engine/EditorHistory';
import { commands, formatKeybinding } from '@/commands';
-import type { ToolMode } from '@/types';
import { t } from '@/i18n';
-const TOOLS: { mode: ToolMode; icon: LucideIcon; label: string }[] = [
- { mode: 'select', icon: MousePointer2, label: t('layout.tool.select') },
- { mode: 'move', icon: Move, label: t('layout.tool.move') },
- { mode: 'rotate', icon: RotateCw, label: t('layout.tool.rotate') },
- { mode: 'scale', icon: Scale3d, label: t('layout.tool.scale') },
-];
+// The global toolbar is GLOBAL-only: Save · Undo/Redo · Play · Build. Everything
+// scoped to the scene view (the transform tools, snap/grid/fx toggles, gizmos)
+// lives in the viewport's own chrome — the floating tool palette and the docked
+// scene toolbar — so it travels with the viewport when it pops out to its own OS
+// window, and no control is duplicated in two bars that can drift out of sync.
/** Shortcut-hint suffix for a command's tooltip, derived from its keybinding. */
function hint(id: string): string {
@@ -64,15 +54,14 @@ function TBtn({
}
export function Toolbar() {
- // Reactive display state (tool / toggles / play); actions dispatch through the
+ // Reactive display state (play target/players); actions dispatch through the
// command registry so menu, toolbar, and keyboard share one implementation.
const playTarget = useEditorStore((s) => s.playTarget);
const setPlayTarget = useEditorStore((s) => s.setPlayTarget);
const playPlayers = useEditorStore((s) => s.playPlayers);
const setPlayPlayers = useEditorStore((s) => s.setPlayPlayers);
const [modeMenu, setModeMenu] = useState<{ x: number; y: number } | null>(null);
- const { tool, snapping, showGrid, showGizmos, previewFx, isPlaying, isPaused, togglePause, stop } =
- useEditorStore();
+ const { isPlaying, isPaused, togglePause, stop } = useEditorStore();
// Re-render on history changes to refresh undo/redo enabled state + labels.
useSyncExternalStore(EditorHistory.subscribe, EditorHistory.getVersion);
@@ -106,28 +95,6 @@ export function Toolbar() {
/>
</div>
- <span className="tdiv" />
-
- <div className="tgroup" role="radiogroup" aria-label={t('layout.transformTool')}>
- {TOOLS.map((tb) => (
- <TBtn
- key={tb.mode}
- icon={tb.icon}
- label={`${tb.label}${hint(`tool.${tb.mode}`)}`}
- active={tool === tb.mode}
- onClick={() => commands.run(`tool.${tb.mode}`)}
- />
- ))}
- </div>
-
- <span className="tdiv" />
-
- <div className="tgroup">
- <TBtn icon={Magnet} label={t('cmd.view.toggleSnapping')} active={snapping} onClick={() => commands.run('view.toggleSnapping')} />
- <TBtn icon={Grid3x3} label={t('cmd.view.toggleGrid')} active={showGrid} onClick={() => commands.run('view.toggleGrid')} />
- <TBtn icon={Sparkles} label={t('cmd.view.togglePreviewFx')} active={previewFx} onClick={() => commands.run('view.togglePreviewFx')} />
- </div>
-
<span className="tspacer" />
{/* Play controls sit dead-center — the focal action. */}
@@ -183,7 +150,6 @@ export function Toolbar() {
<span className="tspacer" />
<div className="tgroup">
- <TBtn icon={Eye} label={t('cmd.view.toggleGizmos')} active={showGizmos} onClick={() => commands.run('view.toggleGizmos')} />
<button type="button" className="tbtn" title={t('layout.buildScriptsTooltip')} onClick={() => commands.run('build.scripts')}>
<Hammer size={15} strokeWidth={1.85} />
<span className="lbl">{t('layout.build')}</span>
diff --git a/desktop/src/panels/Viewport.tsx b/desktop/src/panels/Viewport.tsx
index 673368a8d..f01c6aad6 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 Team
-import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
+import { memo, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
import type { PointerEvent as ReactPointerEvent, DragEvent as ReactDragEvent, ReactNode } from 'react';
import {
- MousePointer2, Move, RotateCw, Scale3d, Grid3x3, Eye, Frame,
- Camera, Check, ChevronDown, Loader2, TriangleAlert, Lightbulb, Sparkles, Globe, Crosshair, Smartphone, Monitor, type LucideIcon,
+ MousePointer2, Move, RotateCw, Scale3d, Grid3x3, Frame,
+ Camera, Check, ChevronDown, Loader2, TriangleAlert, Lightbulb, Sparkles, Globe, Crosshair, Smartphone, Monitor, Magnet, Axis3d, Hexagon, type LucideIcon,
} from 'lucide-react';
import { t } from '@/i18n';
import { useEditorStore } from '@/store/editorStore';
@@ -20,7 +20,7 @@ import { commands } from '@/commands';
import { MOD_LABEL } from '@/commands/keybinding';
import { EngineHost } from '@/engine/EngineHost';
import { PlayRealm } from '@/engine/PlayRealm';
-import { ViewportController, type JointGizmoType, type ColliderPointHandle } from '@/engine/ViewportController';
+import { ViewportController, type JointGizmoType, type ColliderPointHandle, type MinimapBounds, type MinimapBox } from '@/engine/ViewportController';
import { ProjectStore } from '@/project/ProjectStore';
import { createFromSource, sourceById, SOURCE_DND_MIME } from '@/engine/entitySources';
import { resizeUINodeAxis, type ResizeSide, type AxisResizeWrites } from '@/engine/uiResize';
@@ -487,17 +487,20 @@ function OvTool({
kbd,
active,
onClick,
+ toggle,
}: {
icon: LucideIcon;
label: string;
kbd?: string;
active?: boolean;
onClick: () => void;
+ /** A display-flag toggle (soft accent "on") rather than a tool selection (strong fill). */
+ toggle?: boolean;
}) {
return (
<button
type="button"
- className={`ovbtn ov-tool${active ? ' active' : ''}`}
+ className={`ovbtn ov-tool${toggle ? ' ov-toggle' : ''}${active ? ' active' : ''}`}
title={label}
aria-label={label}
aria-pressed={active}
@@ -593,8 +596,12 @@ function HudCursor() {
// The corner HUD (perf + coordinates). Owns the StatsStore subscription so the
// slow stats updates re-render ONLY this leaf — not the whole, gizmo-heavy
// Viewport.
-function ViewportHud({ ready, selCount, zoomPct, tool, paintHint }: {
+function ViewportHud({ ready, showStats, showCoords, selCount, zoomPct, tool, paintHint }: {
ready: boolean;
+ /** Corner FPS/frame/entity HUD — opt-in (off by default). */
+ showStats: boolean;
+ /** Bottom-left cursor/selection/hint readout — opt-in (off by default). */
+ showCoords: boolean;
selCount: number;
zoomPct: number;
tool: ToolMode;
@@ -604,7 +611,7 @@ function ViewportHud({ ready, selCount, zoomPct, tool, paintHint }: {
const stats = useSyncExternalStore(StatsStore.subscribe, StatsStore.getSnapshot);
return (
<>
- {ready && (
+ {ready && showStats && (
<div className="vp-perf" aria-hidden="true">
<div className="pr h">
<span className="k">FPS</span>
@@ -621,17 +628,101 @@ function ViewportHud({ ready, selCount, zoomPct, tool, paintHint }: {
</div>
</div>
)}
- <div className="vp-coord">
- <div className="ro">
- <HudCursor />
- {t('vp.hud.sel')} <strong>{selCount}</strong> · {zoomPct}%
+ {showCoords && (
+ <div className="vp-coord">
+ <div className="ro">
+ <HudCursor />
+ {t('vp.hud.sel')} <strong>{selCount}</strong> · {zoomPct}%
+ </div>
+ <div className="hint">{paintHint ?? TOOL_HINT[tool]}</div>
</div>
- <div className="hint">{paintHint ?? TOOL_HINT[tool]}</div>
- </div>
+ )}
</>
);
}
+// Bottom-right scene minimap: a schematic overview (one rect per entity) the whole
+// scene fits into, with the editor camera's world rect overlaid each frame. Click /
+// drag recenters the camera — fast navigation of large levels. React.memo'd so it only
+// rebuilds its rects when the (memoized) box set changes, not on every Viewport render.
+const MINIMAP_W = 200;
+const MINIMAP_H = 128;
+const MINIMAP_PAD = 8;
+
+const ViewportMinimap = memo(function ViewportMinimap({ data }: { data: { bounds: MinimapBounds | null; boxes: MinimapBox[] } }) {
+ const win = usePanelWindow();
+ const camRef = useRef<SVGRectElement>(null);
+ // Fit the world bounds into the panel (preserve aspect, letterbox). Recomputed only
+ // when the bounds change; the projection below closes over it.
+ const fit = useMemo(() => {
+ const b = data.bounds;
+ if (!b) return null;
+ const worldW = Math.max(b.maxX - b.minX, 1e-3);
+ const worldH = Math.max(b.maxY - b.minY, 1e-3);
+ const scale = Math.min((MINIMAP_W - 2 * MINIMAP_PAD) / worldW, (MINIMAP_H - 2 * MINIMAP_PAD) / worldH);
+ return { b, scale, offX: (MINIMAP_W - worldW * scale) / 2, offY: (MINIMAP_H - worldH * scale) / 2 };
+ }, [data.bounds]);
+
+ // Overlay the editor camera's world rect on the minimap every frame (it tracks
+ // pan/zoom). Its own tiny rAF keeps this off the gizmo-heavy main viewport tick.
+ useEffect(() => {
+ if (!fit) return;
+ let raf = 0;
+ const tick = () => {
+ raf = requestAnimationFrame(tick);
+ const rect = camRef.current;
+ if (!rect) return;
+ const v = ViewportController.editorViewRect();
+ if (!v) { rect.style.opacity = '0'; return; }
+ rect.setAttribute('x', String(fit.offX + (v.cx - v.halfW - fit.b.minX) * fit.scale));
+ rect.setAttribute('y', String(fit.offY + (fit.b.maxY - (v.cy + v.halfH)) * fit.scale));
+ rect.setAttribute('width', String(Math.max(2, v.halfW * 2 * fit.scale)));
+ rect.setAttribute('height', String(Math.max(2, v.halfH * 2 * fit.scale)));
+ rect.style.opacity = '1';
+ };
+ raf = requestAnimationFrame(tick);
+ return () => cancelAnimationFrame(raf);
+ }, [fit, win]);
+
+ // Minimap px → world, then recenter the camera there (click + drag, zoom untouched).
+ const navTo = (e: ReactPointerEvent) => {
+ if (!fit) return;
+ const r = (e.currentTarget as SVGSVGElement).getBoundingClientRect();
+ ViewportController.centerViewOn(
+ fit.b.minX + (e.clientX - r.left - fit.offX) / fit.scale,
+ fit.b.maxY - (e.clientY - r.top - fit.offY) / fit.scale,
+ );
+ };
+
+ if (!fit || data.boxes.length === 0) return null;
+ return (
+ <div className="viewport__minimap" title={t('vp.minimap')}>
+ <svg
+ width={MINIMAP_W}
+ height={MINIMAP_H}
+ onPointerDown={(e) => {
+ if (e.button !== 0) return;
+ (e.currentTarget as SVGSVGElement).setPointerCapture(e.pointerId);
+ navTo(e);
+ }}
+ onPointerMove={(e) => { if (e.buttons & 1) navTo(e); }}
+ >
+ {data.boxes.map((bx, i) => (
+ <rect
+ key={i}
+ className={`mm-box mm-${bx.kind}`}
+ x={fit.offX + (bx.x0 - fit.b.minX) * fit.scale}
+ y={fit.offY + (fit.b.maxY - bx.y1) * fit.scale}
+ width={Math.max(1, (bx.x1 - bx.x0) * fit.scale)}
+ height={Math.max(1, (bx.y1 - bx.y0) * fit.scale)}
+ />
+ ))}
+ <rect ref={camRef} className="mm-cam" />
+ </svg>
+ </div>
+ );
+});
+
export function Viewport() {
// The window this viewport currently lives in — main, or its own OS window once
// popped out. Drives resize re-binding and any window-scoped listeners below.
@@ -644,6 +735,9 @@ export function Viewport() {
const showColliders = useEditorStore((s) => s.showColliders);
const showTileCollision = useEditorStore((s) => s.showTileCollision);
const previewFx = useEditorStore((s) => s.previewFx);
+ const showStats = useEditorStore((s) => s.showStats);
+ const showCoords = useEditorStore((s) => s.showCoords);
+ const showMinimap = useEditorStore((s) => s.showMinimap);
const activeGizmoAxis = useEditorStore((s) => s.activeGizmoAxis);
const coordSpace = useEditorStore((s) => s.coordSpace);
const pivotMode = useEditorStore((s) => s.pivotMode);
@@ -817,6 +911,12 @@ export function Viewport() {
() => (engine.status === 'ready' ? ViewportController.particleEmitterIds() : []),
[structRev, engine.status],
);
+ // Minimap overview boxes + scene bounds — recomputed on structural / data change (the
+ // camera rect updates live inside the minimap). dataRev catches entity moves on commit.
+ const minimap = useMemo(
+ () => (engine.status === 'ready' ? ViewportController.minimapBoxes() : { bounds: null, boxes: [] }),
+ [structRev, dataRev, engine.status],
+ );
// Mount the live engine canvas into the stage; it survives panel re-docking.
useEffect(() => {
@@ -1052,7 +1152,7 @@ export function Viewport() {
const dlabel = designLabelRef.current;
if (dlabel) {
dlabel.textContent = `${ci.designResolution.x} × ${ci.designResolution.y}`;
- // Top clamp clears the .ov-tl floating toolbar (top:10 + ~34px tall).
+ // 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));
dlabel.style.transform = `translate(${lx}px, ${ly}px)`;
@@ -1812,19 +1912,11 @@ export function Viewport() {
return (
<div className={`viewport${isPlaying ? ' viewport--play' : ''}`}>
- {/* Top-left: view menus (UE5 layout) — Show Flags dropdown + Frame. */}
- <div className="ov ov-tl">
- <div className="ov-cluster">
- <OvDropdown icon={Eye} label={t('vp.show')} title={t('vp.showFlags')}>
- <div className="ovmenu-lbl">{t('vp.showFlags')}</div>
- <DdCheck on={showGrid} label={t('vp.flag.grid')} onClick={() => commands.run('view.toggleGrid')} />
- <DdCheck on={showGizmos} label={t('vp.flag.gizmos')} onClick={() => commands.run('view.toggleGizmos')} />
- <DdCheck on={showColliders} label={t('vp.flag.colliders')} onClick={() => commands.run('view.toggleColliders')} />
- <DdCheck on={showTileCollision} label={t('vp.flag.tileCollision')} onClick={() => commands.run('view.toggleTileCollision')} />
- <DdCheck on={previewFx} label={t('vp.flag.previewFx')} onClick={() => commands.run('view.togglePreviewFx')} />
- <DdCheck on={perfVisible} label={t('vp.flag.perf')} onClick={() => PerfMonitor.toggleOverlay()} />
- </OvDropdown>
- <span className="ov-divider" />
+ {/* Docked scene toolbar under the panel tabs — view menus + display controls
+ on the left, quick display toggles pinned right. Tool selection lives in the
+ floating palette over the canvas (.ov-left). */}
+ <div className="viewport__toolbar">
+ <div className="viewport__tb-group">
<OvTool icon={Frame} label={`${t('vp.frameSelected')} (F)`} kbd="F" onClick={() => commands.run('view.frameSelected')} />
<span className="ov-divider" />
<button
@@ -1911,30 +2003,12 @@ export function Viewport() {
<div className="ovmenu-lbl">{t('vp.overlay')}</div>
<DdCheck on={showSafeArea} label={t('vp.safeArea')} onClick={() => useEditorMode.getState().toggleSafeArea()} />
</OvDropdown>
- </div>
- </div>
-
- {/* Top-right: transform tools (UE5 moved gizmo tools here) + Snap. */}
- <div className="ov ov-tr">
- <div className="ov-cluster">
- {TOOLS.map((t) => (
- <OvTool
- key={t.mode}
- icon={t.icon}
- label={`${t.label} (${t.key})`}
- kbd={t.key}
- active={tool === t.mode}
- onClick={() => commands.run(`tool.${t.mode}`)}
- />
- ))}
<span className="ov-divider" />
<OvDropdown
- icon={Grid3x3}
+ icon={Magnet}
label={<span className="val">{snapping ? snapStep : t('vp.snapOff')}</span>}
title={t('vp.gridSnap')}
>
- <div className="ovmenu-lbl">{t('vp.gridDisplay')}</div>
- <DdCheck on={showGrid} label={t('vp.flag.grid')} onClick={() => commands.run('view.toggleGrid')} />
<div className="ovmenu-lbl">{t('vp.gridSnapSection')}</div>
<DdRadio on={!snapping} label={t('vp.snapOff')} onClick={() => useEditorStore.setState({ snapping: false })} />
<div className="ovmenu-lbl">{t('vp.snapMove')}</div>
@@ -1966,6 +2040,32 @@ export function Viewport() {
))}
</OvDropdown>
</div>
+
+ <div className="viewport__tb-group viewport__tb-group--right">
+ <span className="vp-mode-chip">2D</span>
+ <div className="ov-seg">
+ <OvTool toggle icon={Grid3x3} label={t('vp.flag.grid')} active={showGrid} onClick={() => commands.run('view.toggleGrid')} />
+ <OvTool toggle icon={Axis3d} label={t('vp.flag.gizmos')} active={showGizmos} onClick={() => commands.run('view.toggleGizmos')} />
+ <OvTool toggle icon={Hexagon} label={t('vp.flag.colliders')} active={showColliders} onClick={() => commands.run('view.toggleColliders')} />
+ <OvTool toggle icon={Sparkles} label={t('vp.flag.previewFx')} active={previewFx} onClick={() => commands.run('view.togglePreviewFx')} />
+ </div>
+ </div>
+ </div>
+
+ {/* Floating tool palette over the canvas — selection + transform (Q/W/E/R). */}
+ <div className="ov ov-left">
+ <div className="ov-cluster ov-cluster--v">
+ {TOOLS.map((tl) => (
+ <OvTool
+ key={tl.mode}
+ icon={tl.icon}
+ label={`${tl.label} (${tl.key})`}
+ kbd={tl.key}
+ active={tool === tl.mode}
+ onClick={() => commands.run(`tool.${tl.mode}`)}
+ />
+ ))}
+ </div>
</div>
{/* The engine canvas mounts here; pointer events drive pick + transform + pan. */}
@@ -2317,11 +2417,14 @@ export function Viewport() {
<ViewportHud
ready={engine.status === 'ready'}
+ showStats={showStats}
+ showCoords={showCoords}
selCount={selCount}
zoomPct={zoomPct}
tool={tool}
paintHint={inTilePaint && paintTool ? TILE_HINT[paintTool] : null}
/>
+ {engine.status === 'ready' && showMinimap && <ViewportMinimap data={minimap} />}
{perfVisible && <Perf id="viewport.perfhud"><PerfOverlay /></Perf>}
{mode.id !== 'scene' && (
diff --git a/desktop/src/store/editorStore.ts b/desktop/src/store/editorStore.ts
index a570d1924..f6f9f0aa5 100644
--- a/desktop/src/store/editorStore.ts
+++ b/desktop/src/store/editorStore.ts
@@ -46,6 +46,12 @@ interface EditorState {
showTileCollision: boolean;
/** Simulate particle emitters live in edit mode (authoring preview). */
previewFx: boolean;
+ /** Corner performance HUD (FPS / frame time / entity count). Off by default — opt-in. */
+ showStats: boolean;
+ /** Bottom-left cursor / selection / zoom / tool-hint readout. Off by default. */
+ showCoords: boolean;
+ /** Bottom-right scene minimap overview. On by default; toggle to reclaim the corner. */
+ showMinimap: boolean;
snapping: boolean;
// Grid-snap increment (world units) applied to Move while `snapping` is on. The
// viewport snap dropdown picks from a fixed set (16 / 32 / 64); "off" flips
@@ -71,6 +77,9 @@ interface EditorState {
toggleColliders: () => void;
toggleTileCollision: () => void;
togglePreviewFx: () => void;
+ toggleStats: () => void;
+ toggleCoords: () => void;
+ toggleMinimap: () => void;
toggleSnapping: () => void;
setSnapStep: (step: number) => void;
setSnapAngle: (deg: number) => void;
@@ -138,6 +147,9 @@ export const useEditorStore = create<EditorState>((set) => ({
showColliders: true,
showTileCollision: true,
previewFx: true,
+ showStats: false,
+ showCoords: false,
+ showMinimap: true,
snapping: false,
snapStep: 32,
snapAngle: 15,
@@ -153,6 +165,9 @@ export const useEditorStore = create<EditorState>((set) => ({
toggleColliders: () => set((s) => ({ showColliders: !s.showColliders })),
toggleTileCollision: () => set((s) => ({ showTileCollision: !s.showTileCollision })),
togglePreviewFx: () => set((s) => ({ previewFx: !s.previewFx })),
+ toggleStats: () => set((s) => ({ showStats: !s.showStats })),
+ toggleCoords: () => set((s) => ({ showCoords: !s.showCoords })),
+ toggleMinimap: () => set((s) => ({ showMinimap: !s.showMinimap })),
toggleSnapping: () => set((s) => ({ snapping: !s.snapping })),
setSnapStep: (snapStep) => set({ snapStep, snapping: true }),
setSnapAngle: (snapAngle) => set({ snapAngle }),
diff --git a/desktop/src/theme/app.css b/desktop/src/theme/app.css
index 629b010f8..158955a36 100644
--- a/desktop/src/theme/app.css
+++ b/desktop/src/theme/app.css
@@ -697,7 +697,7 @@ body.thumb-capture .viewport > :not(.viewport__stage):not(.viewport__play) {
never collides with the play flag. */
.viewport__tileflag {
position: absolute;
- top: 10px;
+ top: 46px; /* clear the docked scene toolbar (38px) */
left: 50%;
transform: translateX(-50%);
z-index: 3;
diff --git a/desktop/src/theme/viewport.css b/desktop/src/theme/viewport.css
index c14503cf8..d788ee3d1 100644
--- a/desktop/src/theme/viewport.css
+++ b/desktop/src/theme/viewport.css
@@ -18,8 +18,6 @@
border-radius: var(--r-lg);
box-shadow: var(--shadow-2);
}
-.ov-tl { top: 10px; left: 10px; }
-.ov-tr { top: 10px; right: 10px; }
.ovbtn {
height: 26px;
padding: 0 8px;
@@ -41,6 +39,11 @@
.ovbtn.open .cv { transform: rotate(180deg); }
.ov-tool { width: 30px; height: 30px; padding: 0; justify-content: center; position: relative; }
.ov-tool.active { color: var(--on-accent); background: var(--acc); }
+/* Display-flag toggles read softer than a selected tool: an accent glyph on a faint
+ accent wash when on, a muted glyph when off — "what's shown" vs. the palette's
+ strong "which tool is active" fill. */
+.ov-toggle.active { color: var(--acc); background: color-mix(in srgb, var(--acc) 15%, transparent); }
+.ov-toggle.active:hover { color: var(--acc); background: color-mix(in srgb, var(--acc) 24%, transparent); }
.ov-tool kbd {
position: absolute;
bottom: -2px;
@@ -57,6 +60,59 @@
.ov-tool:hover kbd { opacity: 1; }
.ov-divider { width: 1px; height: 16px; background: var(--border-line); margin: 0 3px; }
+/* Docked scene toolbar: a full-width strip pinned to the top of the viewport,
+ directly below the panel tabs. Opaque on the raised surface (the same token as
+ the tab strip) so it reads as one header block over the canvas — view menus +
+ display controls on the left, quick display toggles pinned right. Tool selection
+ lives in the floating .ov-left palette over the canvas, not here. */
+.viewport__toolbar {
+ position: absolute;
+ top: 0;
+ left: 0;
+ right: 0;
+ z-index: 8;
+ height: 38px;
+ display: flex;
+ align-items: center;
+ gap: 4px;
+ padding: 0 8px;
+ background: var(--srf-3);
+ border-bottom: 1px solid var(--border-line);
+ box-shadow: 0 2px 8px rgba(0, 0, 0, 0.28);
+}
+.viewport__tb-group { display: flex; align-items: center; gap: 1px; min-width: 0; }
+/* The left group yields first when the dock narrows; the right toggles stay put. */
+.viewport__toolbar > .viewport__tb-group:first-child { flex: 0 1 auto; overflow: hidden; }
+.viewport__tb-group--right { margin-left: auto; flex: none; gap: 6px; }
+/* Segmented "well" grouping the display-flag toggles as one cohesive control,
+ set apart from the 2D status chip beside it. */
+.ov-seg {
+ display: flex;
+ align-items: center;
+ gap: 1px;
+ padding: 2px;
+ background: color-mix(in srgb, var(--text) 6%, transparent);
+ border-radius: var(--r-md);
+}
+.ov-seg .ov-tool { width: 28px; height: 26px; }
+/* Static mode indicator — the engine is 2D-only, so this reads, it doesn't toggle. */
+.vp-mode-chip {
+ font-family: var(--mono);
+ font-size: var(--fs-2xs);
+ font-weight: 700;
+ letter-spacing: 0.03em;
+ color: var(--on-accent);
+ background: var(--acc);
+ padding: 3px 6px;
+ border-radius: var(--r-sm);
+ user-select: none;
+}
+
+/* Floating tool palette (vertical) over the canvas' top-left corner — the Q/W/E/R
+ selection + transform tools, always visible without crowding the top bar. */
+.ov-left { top: 48px; left: 10px; }
+.ov-cluster--v { flex-direction: column; gap: 1px; }
+
/* overlay dropdown (view-menu / snap): the shared <Popover> shell in a glass
variant (backdrop blur over the live viewport), holding UE-style check/radio
rows. Popover owns the float + dismiss; these classes are just the contents. */
@@ -128,10 +184,10 @@
/* Design-resolution readout pinned to the frame's top-left corner (rAF-positioned). */
.viewport__design-label { position: absolute; top: 0; left: 0; z-index: 6; pointer-events: none; padding: 1px 5px; font-size: var(--fs-2xs); font-variant-numeric: tabular-nums; color: var(--on-accent); background: var(--acc); border-radius: var(--r-sm); white-space: nowrap; }
-/* perf widget (bottom-right) */
+/* perf widget (top-right, below the docked toolbar — the bottom-right is the minimap) */
.vp-perf {
position: absolute;
- bottom: 10px;
+ top: 48px;
right: 10px;
z-index: 4;
min-width: 128px;
@@ -152,6 +208,32 @@
.vp-perf .pr.h .v { color: var(--text); font-size: var(--fs-md); }
.vp-perf .ps { height: 1px; background: var(--border-line); margin: 5px -9px; }
+/* Bottom-right scene minimap: a schematic overview the whole scene fits into. Boxes
+ are entity world AABBs (coloured by kind); the accent rect tracks the editor camera.
+ Click / drag inside recenters the camera. */
+.viewport__minimap {
+ position: absolute;
+ bottom: 10px;
+ right: 10px;
+ z-index: 4;
+ padding: 4px;
+ background: rgba(var(--glass-rgb), 0.72);
+ -webkit-backdrop-filter: blur(14px);
+ backdrop-filter: blur(14px);
+ border: 1px solid var(--border-line);
+ border-radius: var(--r-md);
+ box-shadow: var(--shadow-2);
+ line-height: 0;
+}
+.viewport__minimap svg { display: block; cursor: crosshair; border-radius: var(--r-sm); background: rgba(0, 0, 0, 0.25); }
+/* Wireframe outlines (matching the reference's schematic look) — reads clean even when
+ a big background sprite spans the level; tilemaps get a faint filled region. */
+.viewport__minimap .mm-box { fill: none; stroke-width: 1; }
+.viewport__minimap .mm-sprite { stroke: var(--text-dim); opacity: 0.85; }
+.viewport__minimap .mm-tile { fill: color-mix(in srgb, var(--acc) 16%, transparent); stroke: color-mix(in srgb, var(--acc) 45%, transparent); opacity: 0.9; }
+.viewport__minimap .mm-icon { stroke: var(--text-mute); opacity: 0.45; }
+.viewport__minimap .mm-cam { fill: color-mix(in srgb, var(--acc) 10%, transparent); stroke: var(--acc); stroke-width: 1.5; }
+
/* coord readout (bottom-left) */
.vp-coord {
position: absolute;
@@ -220,7 +302,10 @@
.viewport--play .viewport__light-gizmo,
.viewport--play .viewport__collider-gizmo,
.viewport--play .viewport__tilecol-gizmo,
-.viewport--play .viewport__particle-gizmo {
+.viewport--play .viewport__particle-gizmo,
+.viewport--play .viewport__toolbar,
+.viewport--play .viewport__minimap,
+.viewport--play .ov-left {
display: none;
}