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): UI authoring — anchor grid, widget palette, resize gizmo

esengine793c24a6698e
diff --git a/desktop/src/engine/SceneCommands.ts b/desktop/src/engine/SceneCommands.ts
index 4265c34e9..c1791a8fd 100644
--- a/desktop/src/engine/SceneCommands.ts
+++ b/desktop/src/engine/SceneCommands.ts
@@ -1,7 +1,7 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { SceneData, PrefabData } from 'esengine';
-import { TilemapAPI, TilemapLiveSync, UIPositionType, DimensionUnit } from 'esengine';
+import { TilemapAPI, TilemapLiveSync, UIPositionType, DimensionUnit, anchorPresetFields, type AnchorPreset } from 'esengine';
import type { EntityId, InspectorFieldType, InspectorFieldValue } from '@/types';
import { EditorHistory, EditorHistoryImpl } from './EditorHistory';
import { SceneModel, SceneModelImpl } from './SceneModel';
@@ -363,6 +363,30 @@ export class SceneCommandsImpl {
if (!shifted) write(nearKey, { value: currentNearPx + delta, unit: DimensionUnit.Px });
}
+ /**
+ * Apply an anchor preset (Start / Center / End / Stretch per axis) to each
+ * UINode as one undo step. A preset is a VIEW over the box fields, not stored
+ * state, so this simply writes `position` Absolute + the insets/margins (+ size
+ * for a Stretch axis) that express it — {@link detectAnchor} reads them back.
+ */
+ setUINodeAnchor(sourceIds: EntityId[], preset: AnchorPreset): void {
+ const f = anchorPresetFields(preset);
+ const dims: Array<[string, { value: number; unit: number }]> = [
+ ['insetLeft', f.insetLeft], ['insetRight', f.insetRight],
+ ['insetTop', f.insetTop], ['insetBottom', f.insetBottom],
+ ['marginLeft', f.marginLeft], ['marginRight', f.marginRight],
+ ['marginTop', f.marginTop], ['marginBottom', f.marginBottom],
+ ];
+ if (f.width) dims.push(['width', f.width]);
+ if (f.height) dims.push(['height', f.height]);
+ this.beginGesture('Anchor');
+ for (const id of sourceIds) {
+ this.setField(id, 'UINode', 'position', 'enum', f.position);
+ for (const [key, dim] of dims) this.setField(id, 'UINode', key, 'dimension', dim);
+ }
+ this.endGesture();
+ }
+
// — Undoable entity lifecycle (model ops; the Reconciler re-spawns/-despawns) —
/** Spawn a new empty entity (with a Transform). Returns its source id. */
diff --git a/desktop/src/engine/entitySources.ts b/desktop/src/engine/entitySources.ts
index 8a1cf56da..a3ea3568d 100644
--- a/desktop/src/engine/entitySources.ts
+++ b/desktop/src/engine/entitySources.ts
@@ -193,6 +193,16 @@ export function userComponentSources(): EntitySource[] {
}));
}
+/** DnD payload type carrying an {@link EntitySource} id — a widget dragged from
+ * the UI palette onto the viewport. Kept beside the registry so the palette and
+ * the viewport drop handler agree on one string. */
+export const SOURCE_DND_MIME = 'application/x-estella-source';
+
+/** The source with this id, or null. */
+export function sourceById(id: string): EntitySource | null {
+ return ENTITY_SOURCES.find((s) => s.id === id) ?? null;
+}
+
/** Case-insensitive filter over label + category + keywords, for the Create popover. */
export function matchSources(sources: EntitySource[], query: string): EntitySource[] {
const q = query.trim().toLowerCase();
diff --git a/desktop/src/engine/uiResize.ts b/desktop/src/engine/uiResize.ts
new file mode 100644
index 000000000..10d661777
--- /dev/null
+++ b/desktop/src/engine/uiResize.ts
@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file uiResize — the pure geometry→box-field math behind the viewport UI resize
+ * gizmo. Dragging one edge of a UINode is resolved in WORLD units, then
+ * written back to the node's own fields in its own units, so a resize keeps
+ * the CSS box model consistent across every anchor:
+ *
+ * - Definite size (px/%): the dragged edge changes the size; the opposite
+ * edge stays put. A pinned inset on the dragged side tracks the moved edge.
+ * - Stretched (auto size + both insets pinned): the dragged edge moves its
+ * own inset, growing/shrinking the span.
+ * - Content-auto (no fixed extent): nothing to resize on that axis.
+ *
+ * Kept unit-testable (pure numbers, no World/DOM) — the gizmo supplies the
+ * world geometry (edge delta, ppu, parent extent), this returns field writes.
+ */
+import { DimensionUnit, type Dimension } from 'esengine';
+
+/** Which edge of the axis is being dragged (low = left/bottom, high = right/top). */
+export type ResizeSide = 'low' | 'high';
+
+export interface AxisResizeInput {
+ /** Current size on this axis (width or height). */
+ size: Dimension;
+ /** Low-edge inset (insetLeft / insetBottom). */
+ nearInset: Dimension;
+ /** High-edge inset (insetRight / insetTop). */
+ farInset: Dimension;
+ side: ResizeSide;
+ /** How far the dragged edge moved along the axis's + direction, in world units. */
+ edgeDeltaWorld: number;
+ /** Design px per world unit (Canvas pixelsPerUnit). */
+ ppu: number;
+ /** Parent's extent on this axis, in world units (for percent conversion). */
+ parentExtentWorld: number;
+}
+
+export interface AxisResizeWrites {
+ size?: Dimension;
+ nearInset?: Dimension;
+ farInset?: Dimension;
+}
+
+const isAuto = (d: Dimension) => d.unit === DimensionUnit.Auto;
+
+/** A world-unit delta expressed in `unit`: px = design px (world × ppu); percent =
+ * fraction of the parent extent. */
+function worldToUnit(worldDelta: number, unit: number, ppu: number, parentExtent: number): number {
+ if (unit === DimensionUnit.Percent) return parentExtent > 0 ? (worldDelta / parentExtent) * 100 : 0;
+ return worldDelta * ppu;
+}
+
+const shift = (d: Dimension, worldDelta: number, ppu: number, parent: number): Dimension => ({
+ value: d.value + worldToUnit(worldDelta, d.unit, ppu, parent),
+ unit: d.unit,
+});
+
+/** The field writes that resize one axis by moving one edge. Empty when the axis is
+ * content-auto (no fixed extent to change). */
+export function resizeUINodeAxis(inp: AxisResizeInput): AxisResizeWrites {
+ const { size, nearInset, farInset, side, edgeDeltaWorld, ppu, parentExtentWorld } = inp;
+ const w: AxisResizeWrites = {};
+
+ if (!isAuto(size)) {
+ // The dragged edge grows/shrinks the size; the opposite edge is the fixed anchor.
+ const sizeDelta = side === 'high' ? edgeDeltaWorld : -edgeDeltaWorld;
+ const value = Math.max(0, size.value + worldToUnit(sizeDelta, size.unit, ppu, parentExtentWorld));
+ w.size = { value, unit: size.unit };
+ // A pinned inset on the dragged side must follow the moved edge, else the box
+ // shifts instead of resizing.
+ if (side === 'high' && !isAuto(farInset)) w.farInset = shift(farInset, -edgeDeltaWorld, ppu, parentExtentWorld);
+ if (side === 'low' && !isAuto(nearInset)) w.nearInset = shift(nearInset, edgeDeltaWorld, ppu, parentExtentWorld);
+ return w;
+ }
+
+ if (!isAuto(nearInset) && !isAuto(farInset)) {
+ // Stretched: the dragged edge moves its own inset (the high edge sits at
+ // parentExtent − farInset, so moving it +Δ means farInset −Δ).
+ if (side === 'high') w.farInset = shift(farInset, -edgeDeltaWorld, ppu, parentExtentWorld);
+ else w.nearInset = shift(nearInset, edgeDeltaWorld, ppu, parentExtentWorld);
+ }
+ return w;
+}
diff --git a/desktop/src/layout/DockLayout.tsx b/desktop/src/layout/DockLayout.tsx
index 1a19c3e40..a3570c81b 100644
--- a/desktop/src/layout/DockLayout.tsx
+++ b/desktop/src/layout/DockLayout.tsx
@@ -20,6 +20,7 @@ import { GamePanel, GameClientPanel } from '@/panels/GamePanel';
import { Sequencer } from '@/panels/Sequencer';
import { TilesetEditor } from '@/panels/TilesetEditor';
import { TilemapPainter } from '@/panels/TilemapPainter';
+import { UIWidgetsPanel } from '@/panels/UIWidgetsPanel';
import { MaterialGraphEditor } from '@/panels/MaterialGraphEditor';
import { StateMachineEditor } from '@/panels/StateMachineEditor';
import { BtTreeEditor } from '@/panels/BtTreeEditor';
@@ -44,6 +45,7 @@ const components: Record<string, FC<IDockviewPanelProps>> = {
sequencer: () => panel('sequencer', <Sequencer />),
tileset: () => panel('tileset', <TilesetEditor />),
tilemap: () => panel('tilemap', <TilemapPainter />),
+ uiWidgets: () => panel('uiWidgets', <UIWidgetsPanel />),
materialgraph: () => panel('materialgraph', <MaterialGraphEditor />),
statemachine: () => panel('statemachine', <StateMachineEditor />),
behaviortree: () => panel('behaviortree', <BtTreeEditor />),
diff --git a/desktop/src/mode/editorModes.ts b/desktop/src/mode/editorModes.ts
index 55a64be37..3c3aa6db2 100644
--- a/desktop/src/mode/editorModes.ts
+++ b/desktop/src/mode/editorModes.ts
@@ -58,6 +58,7 @@ const uiMode: EditorModeDef = {
label: 'UI',
icon: LayoutPanelTop,
toolset: 'transform',
+ panels: [{ id: 'ui-widgets', component: 'uiWidgets', title: 'UI Widgets', side: 'left', width: 240 }],
overlays: { designFrame: true, safeArea: true, letterbox: true },
suggestFor: (s) => s.hasComponent('Canvas') || s.hasComponent('UINode'),
};
diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsx
index 2a8420b3f..94eabfd8f 100644
--- a/desktop/src/panels/Details.tsx
+++ b/desktop/src/panels/Details.tsx
@@ -44,7 +44,7 @@ import { InspectorClipboard } from '@/engine/inspectorClipboard';
import { SceneCommands, toModelValue } from '@/engine/SceneCommands';
import { ENTITY_SOURCES, createFromSource } from '@/engine/entitySources';
import { PlayInspect } from '@/engine/PlayInspect';
-import { DimensionUnit } from 'esengine';
+import { DimensionUnit, AnchorAxis, ANCHOR_AXES, detectAnchor } from 'esengine';
import type { SceneData, InputMapAsset, ActionType, Binding } from 'esengine';
import { modelAddableComponentEntries, subscribeSchemas, getSchemaRevision, prettyLabel, hexToRgba, dynamicEnumOptions } from '@/engine/schema';
import * as imap from '@/project/inputMapDoc';
@@ -1101,6 +1101,66 @@ function textBoxAction(comp: InspectorComponent, sourceId: EntityId): { label: s
};
}
+// Where a preset's mark sits inside its cell (percent of the cell box), per axis
+// mode. Start/Center/End are a 30%-wide dot at the near/mid/far third; Stretch is
+// a bar filling the axis — a glanceable picture of the anchor.
+const ANCHOR_MARK: Record<number, { start: number; size: number }> = {
+ [AnchorAxis.Start]: { start: 14, size: 30 },
+ [AnchorAxis.Center]: { start: 35, size: 30 },
+ [AnchorAxis.End]: { start: 56, size: 30 },
+ [AnchorAxis.Stretch]: { start: 12, size: 76 },
+};
+const ANCHOR_H = { [AnchorAxis.Start]: 'Left', [AnchorAxis.Center]: 'Center', [AnchorAxis.End]: 'Right', [AnchorAxis.Stretch]: 'Stretch H' };
+const ANCHOR_V = { [AnchorAxis.Start]: 'Top', [AnchorAxis.Center]: 'Middle', [AnchorAxis.End]: 'Bottom', [AnchorAxis.Stretch]: 'Stretch V' };
+const anchorTitle = (h: AnchorAxis, v: AnchorAxis) =>
+ h === AnchorAxis.Stretch && v === AnchorAxis.Stretch ? 'Stretch' : `${ANCHOR_V[v]} · ${ANCHOR_H[h]}`;
+
+/** UMG/Unity-style anchor preset picker for a UINode: a 4×4 grid (Left/Center/
+ * Right/Stretch × Top/Middle/Bottom/Stretch) that writes position + inset/margin
+ * box fields, and highlights the cell the current box already matches. Making the
+ * node Absolute is implicit in every preset — clicking one anchors the node. */
+function AnchorPresetGrid({ entities, comp }: { entities: EntityId[]; comp: InspectorComponent }) {
+ const dim = (key: string) => {
+ const v = comp.fields.find((f) => f.key === key)?.value as { value: number; unit: number } | undefined;
+ return v ?? { value: 0, unit: DimensionUnit.Auto };
+ };
+ const node = {
+ position: Number(comp.fields.find((f) => f.key === 'position')?.value ?? 0),
+ insetLeft: dim('insetLeft'), insetRight: dim('insetRight'),
+ insetTop: dim('insetTop'), insetBottom: dim('insetBottom'),
+ marginLeft: dim('marginLeft'), marginRight: dim('marginRight'),
+ marginTop: dim('marginTop'), marginBottom: dim('marginBottom'),
+ width: dim('width'), height: dim('height'),
+ } as Parameters<typeof detectAnchor>[0];
+ const active = detectAnchor(node);
+ return (
+ <div className="anchor-grid" role="group" aria-label="Anchor preset">
+ {ANCHOR_AXES.map((v) =>
+ ANCHOR_AXES.map((h) => {
+ const on = active != null && active.h === h && active.v === v;
+ const hm = ANCHOR_MARK[h];
+ const vm = ANCHOR_MARK[v];
+ return (
+ <button
+ key={`${v}-${h}`}
+ type="button"
+ className={`anchor-cell${on ? ' active' : ''}`}
+ title={anchorTitle(h, v)}
+ aria-pressed={on}
+ onClick={() => SceneCommands.setUINodeAnchor(entities, { h, v })}
+ >
+ <span
+ className="anchor-mark"
+ style={{ left: `${hm.start}%`, width: `${hm.size}%`, top: `${vm.start}%`, height: `${vm.size}%` }}
+ />
+ </button>
+ );
+ }),
+ )}
+ </div>
+ );
+}
+
function ComponentSection({
entities,
comp,
@@ -1109,6 +1169,7 @@ function ComponentSection({
onMore,
write,
action,
+ extra,
}: {
entities: EntityId[];
comp: InspectorComponent;
@@ -1117,6 +1178,7 @@ function ComponentSection({
onMore?: (e: React.MouseEvent, name: string) => void;
write?: FieldWrite;
action?: { label: string; title: string; run: () => void };
+ extra?: React.ReactNode;
}) {
const Icon = componentIcon(comp.name);
const overridden = comp.fields.some(isModified);
@@ -1194,6 +1256,7 @@ function ComponentSection({
{action.label}
</button>
)}
+ {extra}
<div className="comp-fields">
{ungrouped.map(row)}
{[...groups].map(([cat, fields]) => (
@@ -1988,6 +2051,7 @@ function EditorDetails() {
collapsed={collapsed.has(comp.name)}
onToggle={() => toggle(comp.name)}
onMore={(e, name) => setCompMenu({ x: e.clientX, y: e.clientY, comp: name })}
+ extra={comp.name === 'UINode' ? <AnchorPresetGrid entities={ids} comp={comp} /> : undefined}
/>
))}
{query && visible.length === 0 && (
diff --git a/desktop/src/panels/UIWidgetsPanel.tsx b/desktop/src/panels/UIWidgetsPanel.tsx
new file mode 100644
index 000000000..44eeffabc
--- /dev/null
+++ b/desktop/src/panels/UIWidgetsPanel.tsx
@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file UIWidgetsPanel — the UI-mode widget palette. Drag an item onto the
+ * viewport to place it, or click to add it under the Canvas.
+ *
+ * Data-driven from the SAME `ENTITY_SOURCES` registry the Create popover uses —
+ * there is no parallel widget list, so a new UI source (builtin or user) appears
+ * here for free with its registry label + icon.
+ */
+import { ENTITY_SOURCES, createFromSource, SOURCE_DND_MIME, type EntitySource } from '@/engine/entitySources';
+import { useSelection } from '@/store/selectionStore';
+
+const UI_SOURCES = ENTITY_SOURCES.filter((s) => s.category === 'UI');
+
+export function UIWidgetsPanel() {
+ const add = (s: EntitySource) => {
+ void createFromSource(s, { parent: null }).then((id) => {
+ if (id != null) useSelection.getState().select(id);
+ });
+ };
+ return (
+ <div className="ui-palette">
+ <div className="ui-palette-hint">Drag onto the canvas, or click to add under the Canvas.</div>
+ <div className="ui-palette-grid">
+ {UI_SOURCES.map((s) => {
+ const Icon = s.icon;
+ return (
+ <button
+ key={s.id}
+ type="button"
+ className="ui-palette-item"
+ draggable
+ title={s.label}
+ onDragStart={(e) => {
+ e.dataTransfer.setData(SOURCE_DND_MIME, s.id);
+ e.dataTransfer.setData('text/plain', s.label);
+ e.dataTransfer.effectAllowed = 'copy';
+ }}
+ onClick={() => add(s)}
+ >
+ <Icon size={18} strokeWidth={1.8} />
+ <span className="ui-palette-label">{s.label}</span>
+ </button>
+ );
+ })}
+ </div>
+ </div>
+ );
+}
diff --git a/desktop/src/panels/Viewport.tsx b/desktop/src/panels/Viewport.tsx
index 138046340..5da09d74b 100644
--- a/desktop/src/panels/Viewport.tsx
+++ b/desktop/src/panels/Viewport.tsx
@@ -21,6 +21,8 @@ import { EngineHost } from '@/engine/EngineHost';
import { PlayRealm } from '@/engine/PlayRealm';
import { ViewportController } 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';
import { IMAGE_RE } from '@/project/assetMeta';
import { createTilemapFromTileset } from '@/tilemap/createTilemap';
import { SceneModel } from '@/engine/SceneModel';
@@ -31,7 +33,7 @@ import { PerfMonitor } from '@/engine/PerfMonitor';
import { PerfOverlay } from '@/components/PerfOverlay';
import { Perf } from '@/components/Perf';
import { Popover, usePopover } from '@/components/Popover';
-import type { ToolMode } from '@/types';
+import type { ToolMode, EntityId } from '@/types';
import { resolveActiveTool, type EditorTool, type ToolContext, type PointerInput } from '@/tools';
import { cursorTile } from '@/tools/tileTools';
import { GIZMO, type GizmoAxis } from '@/tools/gizmo';
@@ -133,7 +135,10 @@ function setRectAttrs(el: Element | null, r: { x: number; y: number; w: number;
}
// A UINode length field ({ value, unit }) from the model, or null.
-function uiDim(src: number, key: 'width' | 'height'): { value: number; unit: number } | null {
+function uiDim(
+ src: number,
+ key: 'width' | 'height' | 'insetLeft' | 'insetRight' | 'insetTop' | 'insetBottom',
+): { value: number; unit: number } | null {
const d = SceneModel.entityBySource(src)?.components.find((c) => c.type === 'UINode')?.data as
| Record<string, unknown>
| undefined;
@@ -141,31 +146,71 @@ function uiDim(src: number, key: 'width' | 'height'): { value: number; unit: num
return v && typeof v === 'object' && 'value' in v && 'unit' in v ? (v as { value: number; unit: number }) : null;
}
-// Drag a UI box edge/corner handle → its px width/height (UINode dimension). Screen
-// space: the box's on-screen size over its px value gives screen-px-per-UI-px, so the
-// drag tracks the cursor 1:1. Only px-unit sides resize (percent/auto have no fixed px);
-// writes go through the SAME setField + begin/endGesture channel the Inspector uses.
-function startUiResizeDrag(rt: number, edge: 'e' | 's' | 'se', e: ReactPointerEvent): void {
+// The eight resize handles, each as which edge it moves per axis (low = left/bottom,
+// high = right/top in the y-up world).
+type UiEdge = 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw';
+const UI_EDGE_SIDES: Record<UiEdge, { x?: ResizeSide; y?: ResizeSide }> = {
+ e: { x: 'high' }, w: { x: 'low' }, n: { y: 'high' }, s: { y: 'low' },
+ ne: { x: 'high', y: 'high' }, nw: { x: 'low', y: 'high' },
+ se: { x: 'high', y: 'low' }, sw: { x: 'low', y: 'low' },
+};
+
+// Round a Dimension for a clean inspector value (px → integer, percent → 2dp).
+function roundDim(d: { value: number; unit: number }): { value: number; unit: number } {
+ return d.unit === DimensionUnit.Px
+ ? { value: Math.round(d.value), unit: d.unit }
+ : { value: Math.round(d.value * 100) / 100, unit: d.unit };
+}
+function applyAxisResize(src: EntityId, axis: 'x' | 'y', w: AxisResizeWrites): void {
+ const keys = axis === 'x'
+ ? { size: 'width', near: 'insetLeft', far: 'insetRight' }
+ : { size: 'height', near: 'insetBottom', far: 'insetTop' };
+ if (w.size) SceneCommands.setField(src, 'UINode', keys.size, 'dimension', roundDim(w.size));
+ if (w.nearInset) SceneCommands.setField(src, 'UINode', keys.near, 'dimension', roundDim(w.nearInset));
+ if (w.farInset) SceneCommands.setField(src, 'UINode', keys.far, 'dimension', roundDim(w.farInset));
+}
+
+// Drag a UI box edge/corner handle → resize the UINode, unit-aware and anchor-aware
+// (see uiResize.ts). Works in world units (the UI-world is design-px-baked, so 1 unit
+// = 1 design px, matching setUINodeXY_); the parent box drives percent + stretch.
+// Writes go through the SAME setField + begin/endGesture channel the Inspector uses.
+function startUiResizeDrag(rt: number, edge: UiEdge, e: ReactPointerEvent): void {
if (e.button !== 0) return;
const src = SceneModel.sourceFor(rt);
- const rect0 = ViewportController.getEntityScreenRect(rt);
- if (src == null || !rect0) return;
+ const obb = ViewportController.uiEntityWorldOBB(rt);
+ if (src == null || !obb) return;
+ const parentSrc = SceneModel.entityBySource(src)?.parent;
+ const parentRt = parentSrc != null ? SceneModel.runtimeFor(parentSrc) : undefined;
+ const pobb = parentRt != null ? ViewportController.uiEntityWorldOBB(parentRt) : null;
+ if (!pobb) return; // no parent box → no anchor-correct / percent frame to resize in
e.stopPropagation();
- const w0 = uiDim(src, 'width');
- const h0 = uiDim(src, 'height');
- const sx = w0 && w0.unit === DimensionUnit.Px && w0.value > 0 ? rect0.w / w0.value : null;
- const sy = h0 && h0.unit === DimensionUnit.Px && h0.value > 0 ? rect0.h / h0.value : null;
- const startX = e.clientX;
- const startY = e.clientY;
+
+ const sides = UI_EDGE_SIDES[edge];
+ const left = obb.cx - obb.hw, right = obb.cx + obb.hw;
+ const bottom = obb.cy - obb.hh, top = obb.cy + obb.hh;
+ // Start field values (resize recomputes from these + the total edge delta, so the
+ // repeated writes during a drag never accumulate rounding).
+ const fx = { size: uiDim(src, 'width'), nearInset: uiDim(src, 'insetLeft'), farInset: uiDim(src, 'insetRight') };
+ const fy = { size: uiDim(src, 'height'), nearInset: uiDim(src, 'insetBottom'), farInset: uiDim(src, 'insetTop') };
+ const parentW = 2 * pobb.hw, parentH = 2 * pobb.hh;
+
SceneCommands.beginGesture('Resize UI');
const onMove = (ev: PointerEvent) => {
- if ((edge === 'e' || edge === 'se') && sx && w0) {
- const nw = Math.max(0, Math.round(w0.value + (ev.clientX - startX) / sx));
- SceneCommands.setField(src, 'UINode', 'width', 'dimension', { value: nw, unit: DimensionUnit.Px });
+ const wp = ViewportController.canvasToWorld(ev.clientX, ev.clientY);
+ if (!wp) return;
+ if (sides.x && fx.size && fx.nearInset && fx.farInset) {
+ const edgeDeltaWorld = wp.x - (sides.x === 'high' ? right : left);
+ applyAxisResize(src, 'x', resizeUINodeAxis({
+ size: fx.size, nearInset: fx.nearInset, farInset: fx.farInset,
+ side: sides.x, edgeDeltaWorld, ppu: 1, parentExtentWorld: parentW,
+ }));
}
- if ((edge === 's' || edge === 'se') && sy && h0) {
- const nh = Math.max(0, Math.round(h0.value + (ev.clientY - startY) / sy));
- SceneCommands.setField(src, 'UINode', 'height', 'dimension', { value: nh, unit: DimensionUnit.Px });
+ if (sides.y && fy.size && fy.nearInset && fy.farInset) {
+ const edgeDeltaWorld = wp.y - (sides.y === 'high' ? top : bottom);
+ applyAxisResize(src, 'y', resizeUINodeAxis({
+ size: fy.size, nearInset: fy.nearInset, farInset: fy.farInset,
+ side: sides.y, edgeDeltaWorld, ppu: 1, parentExtentWorld: parentH,
+ }));
}
};
const onUp = () => {
@@ -1189,7 +1234,8 @@ export function Viewport() {
// spawns a Sprite entity sized to the texture; a `.estileset` spawns a paintable
// TilemapLayer.
const isAssetDrag = (e: ReactDragEvent) =>
- e.dataTransfer.types.includes('application/x-estella-asset');
+ e.dataTransfer.types.includes('application/x-estella-asset') ||
+ e.dataTransfer.types.includes(SOURCE_DND_MIME);
const onDragOver = (e: ReactDragEvent) => {
if (!isAssetDrag(e)) return;
@@ -1198,6 +1244,19 @@ export function Viewport() {
};
const onDrop = (e: ReactDragEvent) => {
+ // A widget dragged from the UI palette: create it (under the Canvas via its
+ // placement rule) at the drop point and select it.
+ const sourceId = e.dataTransfer.getData(SOURCE_DND_MIME);
+ if (sourceId) {
+ const source = sourceById(sourceId);
+ if (!source) return;
+ e.preventDefault();
+ const drop = ViewportController.canvasToWorld(e.clientX, e.clientY);
+ void createFromSource(source, { parent: null, position: drop ?? undefined }).then((id) => {
+ if (id != null) useSelection.getState().select(id);
+ });
+ return;
+ }
const path = e.dataTransfer.getData('application/x-estella-asset');
if (!path) return;
const wp = ViewportController.canvasToWorld(e.clientX, e.clientY);
@@ -1582,30 +1641,17 @@ export function Viewport() {
<div ref={designLabelRef} className="viewport__design-label" style={{ opacity: 0 }} aria-hidden="true" />
<div ref={uiGizmoRef} className="viewport__ui-gizmo" style={{ opacity: 0 }}>
- <span
- className="uig-h uig-e"
- onPointerDown={(e) => {
- const p = useSelection.getState().selectedId;
- const rt = p != null ? SceneModel.runtimeFor(p) : undefined;
- if (rt != null) startUiResizeDrag(rt, 'e', e);
- }}
- />
- <span
- className="uig-h uig-s"
- onPointerDown={(e) => {
- const p = useSelection.getState().selectedId;
- const rt = p != null ? SceneModel.runtimeFor(p) : undefined;
- if (rt != null) startUiResizeDrag(rt, 's', e);
- }}
- />
- <span
- className="uig-h uig-se"
- onPointerDown={(e) => {
- const p = useSelection.getState().selectedId;
- const rt = p != null ? SceneModel.runtimeFor(p) : undefined;
- if (rt != null) startUiResizeDrag(rt, 'se', e);
- }}
- />
+ {(['n', 's', 'e', 'w', 'ne', 'nw', 'se', 'sw'] as const).map((edge) => (
+ <span
+ key={edge}
+ className={`uig-h uig-${edge}`}
+ onPointerDown={(e) => {
+ const p = useSelection.getState().selectedId;
+ const rt = p != null ? SceneModel.runtimeFor(p) : undefined;
+ if (rt != null) startUiResizeDrag(rt, edge, e);
+ }}
+ />
+ ))}
</div>
<div ref={gizmoRef} className="viewport__gizmo" aria-hidden="true">
<GizmoOverlay tool={tool} active={activeGizmoAxis} />
diff --git a/desktop/src/theme/inspector.css b/desktop/src/theme/inspector.css
index 8eb69300b..d4acdcde6 100644
--- a/desktop/src/theme/inspector.css
+++ b/desktop/src/theme/inspector.css
@@ -76,6 +76,16 @@
.comp-action { margin: 6px 8px 0; padding: 4px 8px; width: calc(100% - 16px); font-size: var(--fs-2xs); color: var(--text); background: var(--srf-3); border: 1px solid var(--border); border-radius: var(--r-sm); cursor: pointer; transition: background var(--t-fast), border-color var(--t-fast); }
.comp-action:hover { background: var(--srf-4); border-color: var(--acc); }
+/* Anchor preset picker (UINode): a 4×4 grid of parent boxes, each showing where
+ the anchored element would sit; the cell matching the live box is highlighted. */
+.anchor-grid { display: grid; grid-template-columns: repeat(4, 1fr); gap: 3px; margin: 6px 8px 2px; width: max-content; }
+.anchor-cell { position: relative; width: 26px; height: 26px; padding: 0; background: var(--srf-3); border: 1px solid var(--border); border-radius: var(--r-xs); cursor: pointer; transition: background var(--t-fast), border-color var(--t-fast); }
+.anchor-cell:hover { border-color: var(--acc); background: var(--srf-4); }
+.anchor-cell.active { border-color: var(--acc); background: var(--acc-soft); }
+.anchor-mark { position: absolute; background: var(--text-dim); border-radius: 1px; pointer-events: none; }
+.anchor-cell:hover .anchor-mark { background: var(--text); }
+.anchor-cell.active .anchor-mark { background: var(--acc-hi); }
+
/* property rows (label col + value col, reset on right) */
.prop { display: grid; grid-template-columns: 38% 1fr 18px; align-items: center; gap: 4px; min-height: var(--h-prop); padding: 1px 0; position: relative; }
.prop-label { font-size: var(--fs-sm); color: var(--text-dim); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; padding-left: 2px; }
diff --git a/desktop/src/theme/ui-palette.css b/desktop/src/theme/ui-palette.css
new file mode 100644
index 000000000..e54d3046a
--- /dev/null
+++ b/desktop/src/theme/ui-palette.css
@@ -0,0 +1,12 @@
+/* SPDX-License-Identifier: Apache-2.0 */
+/* SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team */
+
+/* UI-mode widget palette (UIWidgetsPanel): drag-source tiles for the UI-category
+ entity sources. */
+.ui-palette { padding: 8px; display: flex; flex-direction: column; gap: 8px; height: 100%; overflow-y: auto; }
+.ui-palette-hint { font-size: var(--fs-2xs); color: var(--text-dim); line-height: 1.4; padding: 0 2px; }
+.ui-palette-grid { display: grid; grid-template-columns: repeat(2, 1fr); gap: 6px; }
+.ui-palette-item { display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 6px; padding: 12px 6px; color: var(--text); background: var(--srf-3); border: 1px solid var(--border); border-radius: var(--r-sm); cursor: grab; transition: background var(--t-fast), border-color var(--t-fast); }
+.ui-palette-item:hover { background: var(--srf-4); border-color: var(--acc); }
+.ui-palette-item:active { cursor: grabbing; }
+.ui-palette-label { font-size: var(--fs-2xs); text-align: center; line-height: 1.2; }
diff --git a/desktop/src/theme/viewport.css b/desktop/src/theme/viewport.css
index 33aabf8dc..6dca52a3a 100644
--- a/desktop/src/theme/viewport.css
+++ b/desktop/src/theme/viewport.css
@@ -110,8 +110,13 @@
.viewport__ui-gizmo { position: absolute; top: 0; left: 0; pointer-events: none; z-index: 6; }
.viewport__ui-gizmo .uig-h { position: absolute; pointer-events: auto; background: var(--acc); border: 1px solid var(--on-accent); box-sizing: border-box; border-radius: 1px; }
.uig-e { right: -4px; top: 50%; width: 8px; height: 14px; transform: translateY(-50%); cursor: ew-resize; }
+.uig-w { left: -4px; top: 50%; width: 8px; height: 14px; transform: translateY(-50%); cursor: ew-resize; }
.uig-s { bottom: -4px; left: 50%; width: 14px; height: 8px; transform: translateX(-50%); cursor: ns-resize; }
+.uig-n { top: -4px; left: 50%; width: 14px; height: 8px; transform: translateX(-50%); cursor: ns-resize; }
.uig-se { right: -4px; bottom: -4px; width: 10px; height: 10px; cursor: nwse-resize; }
+.uig-nw { left: -4px; top: -4px; width: 10px; height: 10px; cursor: nwse-resize; }
+.uig-ne { right: -4px; top: -4px; width: 10px; height: 10px; cursor: nesw-resize; }
+.uig-sw { left: -4px; bottom: -4px; width: 10px; height: 10px; cursor: nesw-resize; }
/* Design-resolution overlay (UI mode): the authored design frame (solid accent), the
simulated device's visible frame (dashed), the letterbox bars (Canvas background
diff --git a/desktop/tests/anchor-preset.test.ts b/desktop/tests/anchor-preset.test.ts
new file mode 100644
index 000000000..e5e36b341
--- /dev/null
+++ b/desktop/tests/anchor-preset.test.ts
@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file SceneCommands.setUINodeAnchor writes the box fields a preset resolves to
+ * (through the shared setField channel), as ONE undo step, and the written
+ * UINode reads back as that preset via the SDK's detectAnchor — the same
+ * derivation the inspector grid uses to highlight the active cell.
+ */
+import { describe, it, expect, beforeAll, beforeEach, afterEach, vi } from 'vitest';
+import { App, UINode, AnchorAxis, UIPositionType, DimensionUnit, detectAnchor } from 'esengine';
+import type { ESEngineModule, SceneData } from 'esengine';
+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';
+
+const host = vi.hoisted(() => ({ world: null as unknown as App['world'] }));
+vi.mock('@/engine/EngineHost', () => ({
+ EngineHost: {
+ mutableWorld: () => host.world,
+ get world() { return host.world; },
+ getResource: () => undefined,
+ },
+}));
+
+import { EditorSession } from '@/engine/EditorSession';
+
+const emptyScene = (): SceneData => ({ version: '1.0', name: 'test', entities: [] }) as unknown as SceneData;
+
+describe.skipIf(!HAS_WASM)('SceneCommands.setUINodeAnchor (headless World)', () => {
+ let module: ESEngineModule;
+ let S: EditorSession;
+ const rt = (sourceId: number): number => S.model.runtimeFor(sourceId)!;
+
+ beforeAll(async () => { module = await loadWasmModule(); });
+ beforeEach(() => {
+ const app = App.new();
+ const registry = new module.Registry();
+ app.connectCpp(registry as never, module);
+ host.world = app.world;
+ S = EditorSession.create();
+ S.model.adopt(emptyScene(), new Map());
+ });
+ afterEach(() => S.dispose());
+
+ const withUINode = (): { id: number; e: number } => {
+ const id = S.commands.addEntity()!;
+ S.commands.addComponent(id, 'UINode');
+ return { id, e: rt(id) };
+ };
+ const AUTO = DimensionUnit.Auto;
+ const PX = DimensionUnit.Px;
+
+ it('Center/Center makes the node Absolute with auto insets + auto margins', () => {
+ const { id, e } = withUINode();
+ S.commands.setUINodeAnchor([id], { h: AnchorAxis.Center, v: AnchorAxis.Center });
+ const n = host.world.get(e, UINode);
+ expect(n.position).toBe(UIPositionType.Absolute);
+ for (const d of [n.insetLeft, n.insetRight, n.insetTop, n.insetBottom,
+ n.marginLeft, n.marginRight, n.marginTop, n.marginBottom]) {
+ expect(d.unit).toBe(AUTO);
+ }
+ });
+
+ it('Start/Start pins the near edges (px) and frees the far edges (auto)', () => {
+ const { id, e } = withUINode();
+ S.commands.setUINodeAnchor([id], { h: AnchorAxis.Start, v: AnchorAxis.Start });
+ const n = host.world.get(e, UINode);
+ expect(n.insetLeft.unit).toBe(PX);
+ expect(n.insetTop.unit).toBe(PX);
+ expect(n.insetRight.unit).toBe(AUTO);
+ expect(n.insetBottom.unit).toBe(AUTO);
+ });
+
+ it('Stretch/Stretch drives the size via auto', () => {
+ const { id, e } = withUINode();
+ S.commands.setUINodeAnchor([id], { h: AnchorAxis.Stretch, v: AnchorAxis.Stretch });
+ const n = host.world.get(e, UINode);
+ expect(n.insetLeft.unit).toBe(PX);
+ expect(n.insetRight.unit).toBe(PX);
+ expect(n.width.unit).toBe(AUTO);
+ expect(n.height.unit).toBe(AUTO);
+ });
+
+ it('the write is ONE undo step (reverts position back to Relative)', () => {
+ const { id, e } = withUINode();
+ expect(host.world.get(e, UINode).position).toBe(UIPositionType.Relative);
+ S.commands.setUINodeAnchor([id], { h: AnchorAxis.End, v: AnchorAxis.Center });
+ expect(host.world.get(e, UINode).position).toBe(UIPositionType.Absolute);
+ S.history.undo();
+ expect(host.world.get(e, UINode).position).toBe(UIPositionType.Relative);
+ });
+
+ it('the written box reads back as the preset via detectAnchor (grid highlight)', () => {
+ const { id, e } = withUINode();
+ for (const h of [AnchorAxis.Start, AnchorAxis.Center, AnchorAxis.End, AnchorAxis.Stretch]) {
+ for (const v of [AnchorAxis.Start, AnchorAxis.Center, AnchorAxis.End, AnchorAxis.Stretch]) {
+ S.commands.setUINodeAnchor([id], { h, v });
+ expect(detectAnchor(host.world.get(e, UINode))).toEqual({ h, v });
+ }
+ }
+ });
+
+ it('applies to a multi-selection in one undo step', () => {
+ const a = withUINode();
+ const b = withUINode();
+ S.commands.setUINodeAnchor([a.id, b.id], { h: AnchorAxis.Center, v: AnchorAxis.Start });
+ expect(host.world.get(a.e, UINode).position).toBe(UIPositionType.Absolute);
+ expect(host.world.get(b.e, UINode).position).toBe(UIPositionType.Absolute);
+ S.history.undo();
+ expect(host.world.get(a.e, UINode).position).toBe(UIPositionType.Relative);
+ expect(host.world.get(b.e, UINode).position).toBe(UIPositionType.Relative);
+ });
+});
diff --git a/desktop/tests/create-catalog.test.ts b/desktop/tests/create-catalog.test.ts
index a8fb0ec04..9c045ecd1 100644
--- a/desktop/tests/create-catalog.test.ts
+++ b/desktop/tests/create-catalog.test.ts
@@ -1,7 +1,7 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { describe, it, expect } from 'vitest';
-import { ENTITY_SOURCES, matchSources, CREATE_CATEGORY_ORDER } from '@/engine/entitySources';
+import { ENTITY_SOURCES, matchSources, CREATE_CATEGORY_ORDER, sourceById, SOURCE_DND_MIME } from '@/engine/entitySources';
describe('Create catalog (searchable source registry)', () => {
it('covers builtins + anchor components, every category in the declared order', () => {
@@ -34,4 +34,19 @@ describe('Create catalog (searchable source registry)', () => {
expect(matchSources(ENTITY_SOURCES, ' ')).toEqual(ENTITY_SOURCES);
expect(matchSources(ENTITY_SOURCES, 'zzzzz')).toEqual([]);
});
+
+ // The UI-mode widget palette (UIWidgetsPanel) and the viewport drop handler both
+ // read this registry — the palette lists the UI category, the drop resolves the id.
+ it('UI category backs the widget palette (Canvas + the builtin widgets)', () => {
+ const ui = ENTITY_SOURCES.filter((s) => s.category === 'UI').map((s) => s.label);
+ expect(ui).toEqual(expect.arrayContaining(['Canvas', 'Button', 'Toggle', 'Slider']));
+ });
+
+ it('sourceById round-trips a dragged palette id back to its source', () => {
+ for (const s of ENTITY_SOURCES.filter((x) => x.category === 'UI')) {
+ expect(sourceById(s.id)).toBe(s);
+ }
+ expect(sourceById('nope::missing')).toBeNull();
+ expect(SOURCE_DND_MIME).toMatch(/^application\//);
+ });
});
diff --git a/desktop/tests/editor-mode.test.ts b/desktop/tests/editor-mode.test.ts
index 7c58118d7..45bb94b3d 100644
--- a/desktop/tests/editor-mode.test.ts
+++ b/desktop/tests/editor-mode.test.ts
@@ -52,6 +52,12 @@ describe('editor-mode registry + derivation', () => {
expect(EDITOR_MODES[EDITOR_MODES.length - 1].id).toBe('scene');
});
+ it('UI mode reveals the widget palette panel on entry', () => {
+ expect(EDITOR_MODE_BY_ID.ui.panels).toEqual([
+ expect.objectContaining({ component: 'uiWidgets', side: 'left' }),
+ ]);
+ });
+
it('suggests the mode implied by the selection', () => {
withComponents('TilemapLayer');
expect(suggestedMode().id).toBe('tilemap');
diff --git a/desktop/tests/ui-resize.test.ts b/desktop/tests/ui-resize.test.ts
new file mode 100644
index 000000000..186ee4991
--- /dev/null
+++ b/desktop/tests/ui-resize.test.ts
@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file The pure resize-gizmo math (uiResize.resizeUINodeAxis): moving one edge
+ * of a UINode maps to size / inset field writes that keep the CSS box model
+ * consistent across every anchor and unit.
+ */
+import { describe, it, expect } from 'vitest';
+import { DimensionUnit } from 'esengine';
+import { resizeUINodeAxis, type AxisResizeInput } from '@/engine/uiResize';
+
+const px = (v: number) => ({ value: v, unit: DimensionUnit.Px });
+const pct = (v: number) => ({ value: v, unit: DimensionUnit.Percent });
+const auto = () => ({ value: 0, unit: DimensionUnit.Auto });
+
+// ppu 1, parent extent 1000 world → percent delta = worldΔ / 10.
+const base = (over: Partial<AxisResizeInput>): AxisResizeInput => ({
+ size: px(100), nearInset: auto(), farInset: auto(),
+ side: 'high', edgeDeltaWorld: 0, ppu: 1, parentExtentWorld: 1000,
+ ...over,
+});
+
+describe('resizeUINodeAxis', () => {
+ it('grows a px box from the far edge (near edge fixed)', () => {
+ const w = resizeUINodeAxis(base({ size: px(100), nearInset: px(0), side: 'high', edgeDeltaWorld: 50 }));
+ expect(w.size).toEqual(px(150));
+ expect(w.nearInset).toBeUndefined();
+ expect(w.farInset).toBeUndefined();
+ });
+
+ it('shrinks a px box from the near edge and tracks the pinned near inset (far edge fixed)', () => {
+ const w = resizeUINodeAxis(base({ size: px(100), nearInset: px(20), side: 'low', edgeDeltaWorld: 30 }));
+ expect(w.size).toEqual(px(70)); // 100 - 30
+ expect(w.nearInset).toEqual(px(50)); // 20 + 30 → left edge in by 30, right stays
+ });
+
+ it('end-anchored: dragging the far edge grows the size and follows the pinned far inset', () => {
+ const w = resizeUINodeAxis(base({ size: px(100), nearInset: auto(), farInset: px(10), side: 'high', edgeDeltaWorld: 40 }));
+ expect(w.size).toEqual(px(140));
+ expect(w.farInset).toEqual(px(-30)); // 10 - 40 → right edge out by 40, left stays
+ });
+
+ it('end-anchored: dragging the near edge only changes size (near inset is auto)', () => {
+ const w = resizeUINodeAxis(base({ size: px(100), nearInset: auto(), farInset: px(10), side: 'low', edgeDeltaWorld: 25 }));
+ expect(w.size).toEqual(px(75));
+ expect(w.nearInset).toBeUndefined();
+ expect(w.farInset).toBeUndefined();
+ });
+
+ it('is unit-aware: a percent-sized box resizes in percent of the parent', () => {
+ const w = resizeUINodeAxis(base({ size: pct(40), nearInset: px(0), side: 'high', edgeDeltaWorld: 50 }));
+ expect(w.size).toEqual(pct(45)); // +50 world / 1000 * 100 = +5%
+ });
+
+ it('centered box (both insets/margins auto): resize changes only the size', () => {
+ const hi = resizeUINodeAxis(base({ size: px(100), nearInset: auto(), farInset: auto(), side: 'high', edgeDeltaWorld: 40 }));
+ expect(hi.size).toEqual(px(140));
+ expect(hi.nearInset).toBeUndefined();
+ expect(hi.farInset).toBeUndefined();
+ const lo = resizeUINodeAxis(base({ size: px(100), side: 'low', edgeDeltaWorld: 40 }));
+ expect(lo.size).toEqual(px(60));
+ });
+
+ it('stretched (auto size, both insets pinned): the dragged edge moves its own inset', () => {
+ const hi = resizeUINodeAxis(base({ size: auto(), nearInset: px(0), farInset: px(0), side: 'high', edgeDeltaWorld: 20 }));
+ expect(hi.farInset).toEqual(px(-20));
+ expect(hi.size).toBeUndefined();
+ const lo = resizeUINodeAxis(base({ size: auto(), nearInset: px(0), farInset: px(0), side: 'low', edgeDeltaWorld: 20 }));
+ expect(lo.nearInset).toEqual(px(20));
+ expect(lo.size).toBeUndefined();
+ });
+
+ it('content-auto (auto size, no pinned insets): nothing to resize', () => {
+ const w = resizeUINodeAxis(base({ size: auto(), nearInset: auto(), farInset: auto(), side: 'high', edgeDeltaWorld: 50 }));
+ expect(w).toEqual({});
+ });
+
+ it('never produces a negative size', () => {
+ const w = resizeUINodeAxis(base({ size: px(20), nearInset: px(0), side: 'low', edgeDeltaWorld: 999 }));
+ expect(w.size).toEqual(px(0));
+ });
+});