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.

fix(editor): make UINodes positionable — Absolute bake, centered-node drag, Canvas host

esengine602a062f11d7
diff --git a/desktop/src/engine/SceneCommands.ts b/desktop/src/engine/SceneCommands.ts
index c1791a8fd..b0f137f54 100644
--- a/desktop/src/engine/SceneCommands.ts
+++ b/desktop/src/engine/SceneCommands.ts
@@ -252,6 +252,43 @@ export class SceneCommandsImpl {
): void {
// The edit hook (Sequencer record) may observe — or, returning true, suppress.
if (this.editHook && this.editHook(sourceId, compName, key, type, value)) return;
+
+ // Flipping a UINode to Absolute bakes its current layout box into concrete px
+ // insets (below) so it holds its on-screen spot and gains a real, draggable
+ // position — an all-auto absolute node otherwise collapses to the static
+ // top-left corner (frequently under the viewport chrome, so it can't be grabbed).
+ const bakeAbsolute =
+ compName === 'UINode' && key === 'position' &&
+ Number(value) === UIPositionType.Absolute &&
+ Number(this.modelFieldValue(sourceId, 'UINode', 'position')) !== UIPositionType.Absolute;
+ // Capture the seeded insets from the node's box BEFORE the flip — the flip marks
+ // the layout dirty, zeroing the computed size until the next pass, and the pre-flip
+ // box is exactly the on-screen position we want the node to keep.
+ const seed = bakeAbsolute ? this.absoluteInsetSeed_(sourceId) : null;
+ const applySeed = (): void => {
+ if (seed?.insetLeft !== undefined) this.writeField_(sourceId, 'UINode', 'insetLeft', 'dimension', { value: seed.insetLeft, unit: DimensionUnit.Px });
+ if (seed?.insetTop !== undefined) this.writeField_(sourceId, 'UINode', 'insetTop', 'dimension', { value: seed.insetTop, unit: DimensionUnit.Px });
+ };
+ if (bakeAbsolute && !this.gesture) {
+ // One undo step for the flip + the seeded insets.
+ this.beginGesture('Make UI Absolute');
+ this.writeField_(sourceId, compName, key, type, value);
+ applySeed();
+ this.endGesture();
+ return;
+ }
+ this.writeField_(sourceId, compName, key, type, value);
+ if (bakeAbsolute) applySeed(); // coalesced into the caller's gesture
+ }
+
+ /** The unconditional single-field write (model + undo/gesture bookkeeping). */
+ private writeField_(
+ sourceId: EntityId,
+ compName: string,
+ key: string,
+ type: InspectorFieldType,
+ value: InspectorFieldValue,
+ ): void {
const e = this.model.entityBySource(sourceId);
if (!e) return;
const cur = (e.components.find((c) => c.type === compName)?.data as Record<string, unknown>) ?? {};
@@ -276,6 +313,39 @@ export class SceneCommandsImpl {
);
}
+ /**
+ * The concrete px insets that pin a UINode's CURRENT resolved box to its parent's
+ * top-left — captured while the node is still in its old (pre-flip) layout so the
+ * box is live. Only an axis with no explicit offset yet (both sides auto) is
+ * seeded; an axis the user already positioned is left untouched (undefined).
+ * Empty without live boxes. Applied after the flip to keep the node put + draggable.
+ */
+ private absoluteInsetSeed_(sourceId: EntityId): { insetLeft?: number; insetTop?: number } {
+ const rt = this.model.runtimeFor(sourceId);
+ const parentSrc = this.model.entityBySource(sourceId)?.parent;
+ const parentRt = parentSrc != null ? this.model.runtimeFor(parentSrc) : undefined;
+ const node = rt !== undefined ? ViewportController.uiEntityWorldOBB(rt) : null;
+ const parent = parentRt !== undefined ? ViewportController.uiEntityWorldOBB(parentRt) : null;
+ if (!node || !parent) return {};
+ const autoAxis = (nearKey: string, farKey: string): boolean => {
+ const near = this.modelFieldValue(sourceId, 'UINode', nearKey) as { unit: number } | undefined;
+ const far = this.modelFieldValue(sourceId, 'UINode', farKey) as { unit: number } | undefined;
+ return near?.unit === DimensionUnit.Auto && far?.unit === DimensionUnit.Auto;
+ };
+ // An absolute node's margin still offsets it on top of its inset, so the inset
+ // that reproduces the current position is (edge gap − own margin). Only px
+ // margins subtract cleanly; percent/auto margins are rare here and left as 0.
+ const marginPx = (key: string): number => {
+ const m = this.modelFieldValue(sourceId, 'UINode', key) as { value: number; unit: number } | undefined;
+ return m?.unit === DimensionUnit.Px ? m.value : 0;
+ };
+ const out: { insetLeft?: number; insetTop?: number } = {};
+ if (autoAxis('insetLeft', 'insetRight')) out.insetLeft = Math.round((node.cx - node.hw) - (parent.cx - parent.hw) - marginPx('marginLeft'));
+ // Layout space is y-down: the top inset is the gap from the parent's top edge.
+ if (autoAxis('insetTop', 'insetBottom')) out.insetTop = Math.round((parent.cy + parent.hh) - (node.cy + node.hh) - marginPx('marginTop'));
+ return out;
+ }
+
/**
* Move an entity to a world position (keeps local Z). Undoable like any field
* edit. `Transform.position` is parent-local, so a parented entity's world
@@ -301,8 +371,8 @@ export class SceneCommandsImpl {
* shift by the delta, percent insets by delta/parent-size, and a fully
* `auto` axis gets pinned (near edge, px) at its current offset. Opposing
* non-auto insets (a stretch axis) shift together, preserving the span.
- * - Relative (flow) nodes: position is the flow's outcome — the move is
- * dropped here (the move tool excludes them up front and hints).
+ * - Relative (flow) nodes: position is the flow's outcome — the move is dropped
+ * here (the move tool excludes them up front and hints to switch to Absolute).
* Returns true when the entity is a UINode (handled), false to fall through
* to the Transform path.
*/
@@ -321,9 +391,9 @@ export class SceneCommandsImpl {
const dx = x - node.cx;
const dy = y - node.cy;
// Layout space is y-down: moving up (world +y) means a smaller top inset.
- this.shiftInsetAxis_(sourceId, 'insetLeft', 'insetRight', dx, 2 * parent.hw,
+ this.shiftInsetAxis_(sourceId, 'insetLeft', 'insetRight', 'marginLeft', 'marginRight', dx, 2 * parent.hw,
(node.cx - node.hw) - (parent.cx - parent.hw));
- this.shiftInsetAxis_(sourceId, 'insetTop', 'insetBottom', -dy, 2 * parent.hh,
+ this.shiftInsetAxis_(sourceId, 'insetTop', 'insetBottom', 'marginTop', 'marginBottom', -dy, 2 * parent.hh,
(parent.cy + parent.hh) - (node.cy + node.hh));
return true;
}
@@ -337,14 +407,22 @@ export class SceneCommandsImpl {
*/
private shiftInsetAxis_(
sourceId: EntityId, nearKey: string, farKey: string,
+ marginNearKey: string, marginFarKey: string,
delta: number, parentSize: number, currentNearPx: number,
): void {
if (delta === 0) return;
+ const write = (key: string, dim: { value: number; unit: number }): void =>
+ this.setField(sourceId, 'UINode', key, 'dimension', dim);
+ // An `auto` margin re-centers the node on this axis (that's how a Center anchor
+ // holds it) and would fight the inset we pin below — the node wouldn't move. Nail
+ // any auto margin on this axis to 0 first so the inset alone drives the position.
+ for (const mk of [marginNearKey, marginFarKey]) {
+ const m = this.modelFieldValue(sourceId, 'UINode', mk) as { unit: number } | undefined;
+ if (m?.unit === DimensionUnit.Auto) write(mk, { value: 0, unit: DimensionUnit.Px });
+ }
const near = this.modelFieldValue(sourceId, 'UINode', nearKey) as { value: number; unit: number } | undefined;
const far = this.modelFieldValue(sourceId, 'UINode', farKey) as { value: number; unit: number } | undefined;
if (!near || !far) return;
- const write = (key: string, dim: { value: number; unit: number }): void =>
- this.setField(sourceId, 'UINode', key, 'dimension', dim);
let shifted = false;
if (near.unit === DimensionUnit.Px) {
write(nearKey, { ...near, value: near.value + delta });
diff --git a/desktop/src/engine/entitySources.ts b/desktop/src/engine/entitySources.ts
index a3ea3568d..f63999945 100644
--- a/desktop/src/engine/entitySources.ts
+++ b/desktop/src/engine/entitySources.ts
@@ -232,8 +232,16 @@ export async function createFromSource(source: EntitySource, ctx: CreateContext)
} catch {
return null; // build aborted (e.g. a prefab asset failed to load; it surfaced its own error)
}
+ let parent = resolvePlacement(source.placement, ctx);
+ // A UI widget must live under a Canvas (the UI layout root) — a UINode with no
+ // Canvas can't lay out or be positioned. If the scene has none, spin one up first
+ // so the widget is hosted, not orphaned. (Canvas itself has no such placement.)
+ if (source.placement === 'under-canvas' && parent == null) {
+ const canvasSrc = ENTITY_SOURCES.find((s) => s.id === 'canvas');
+ if (canvasSrc) parent = await createFromSource(canvasSrc, { parent: null });
+ }
const id = SceneCommands.create(prefab, {
- parent: resolvePlacement(source.placement, ctx),
+ parent,
position: ctx.position,
linkPrefabRef: source.linkPrefabRef?.(ctx),
});
diff --git a/desktop/src/tools/transformTools.ts b/desktop/src/tools/transformTools.ts
index e9e7240d6..ac677cc2f 100644
--- a/desktop/src/tools/transformTools.ts
+++ b/desktop/src/tools/transformTools.ts
@@ -108,18 +108,41 @@ function isFlowUINode(sourceId: EntityId): boolean {
return pos != null && Number(pos) === 0;
}
+/** A UINode with no Canvas ancestor (the UI layout root) — it has no layout box, so
+ * it can't be positioned at all until it's placed under a Canvas. */
+function isOrphanUINode(sourceId: EntityId): boolean {
+ const e = SceneModel.entityBySource(sourceId);
+ if (!e || !e.components.some((c) => c.type === 'UINode')) return false;
+ for (let p = e.parent; p != null; p = SceneModel.entityBySource(p)?.parent ?? null) {
+ if (SceneModel.entityBySource(p)?.components.some((c) => c.type === 'Canvas')) return false;
+ }
+ return true;
+}
+
let flowHintAt = 0;
+let canvasHintAt = 0;
function captureTargets(ids: readonly EntityId[], kind: Kind = 'move'): Target[] {
let kept = pruneDescendants(ids);
if (kind === 'move') {
+ // A UI element with no Canvas has no layout box — it can't be positioned at all.
+ // Exclude it and point to the fix (the inspector's "Place under a Canvas").
+ if (kept.some(isOrphanUINode)) {
+ kept = kept.filter((id) => !isOrphanUINode(id));
+ if (Date.now() - canvasHintAt > 4000) {
+ canvasHintAt = Date.now();
+ Toasts.push('This UI element has no Canvas, so it can’t be positioned — add one via Details ▸ “Place under a Canvas”.', 'info');
+ }
+ }
+ // A flow (Relative) node's position is owned by the layout — moving it does
+ // nothing until the user explicitly switches it to Absolute (the inspector's
+ // Position field / an anchor preset). Exclude it and hint how, once per burst.
const flow = kept.filter(isFlowUINode);
if (flow.length > 0) {
kept = kept.filter((id) => !isFlowUINode(id));
- // One hint per burst of drags, not per pointer-down.
if (Date.now() - flowHintAt > 4000) {
flowHintAt = Date.now();
- Toasts.push('Flow-layout (Relative) nodes are positioned by layout — drag skipped. Set position to Absolute to move freely.', 'info');
+ Toasts.push('This UI node is Relative (flow-positioned) — set Position to Absolute to move it freely.', 'info');
}
}
}
diff --git a/desktop/tests/ui-absolute-bake.test.ts b/desktop/tests/ui-absolute-bake.test.ts
new file mode 100644
index 000000000..b17e04ab8
--- /dev/null
+++ b/desktop/tests/ui-absolute-bake.test.ts
@@ -0,0 +1,146 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Flipping a UINode's `position` to Absolute (via the shared setField
+ * channel, as the inspector's Position dropdown does) bakes its current
+ * resolved box into concrete px insets — so the node holds its on-screen
+ * spot and gains a real, draggable position instead of collapsing to the
+ * auto/static top-left corner. The live box comes from the viewport's
+ * UINode OBB (mocked here to a known rect). One undo reverts flip + bake.
+ */
+import { describe, it, expect, beforeAll, beforeEach, afterEach, vi } from 'vitest';
+import { App, UINode, UIPositionType, DimensionUnit } 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,
+ },
+}));
+
+// The bake reads each node's live layout box from the viewport OBB; stub it to a
+// rect keyed by runtime id so the test controls the geometry without a layout pass.
+const obb = vi.hoisted(() => ({ boxes: new Map<number, { cx: number; cy: number; hw: number; hh: number; rot: number }>() }));
+vi.mock('@/engine/ViewportController', () => ({
+ ViewportController: {
+ uiEntityWorldOBB: (rt: number) => obb.boxes.get(rt) ?? null,
+ },
+}));
+
+import { EditorSession } from '@/engine/EditorSession';
+
+const emptyScene = (): SceneData => ({ version: '1.0', name: 'test', entities: [] }) as unknown as SceneData;
+const PX = DimensionUnit.Px;
+const AUTO = DimensionUnit.Auto;
+
+describe.skipIf(!HAS_WASM)('setField UINode position → Absolute bakes insets (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());
+ obb.boxes.clear();
+ });
+ afterEach(() => S.dispose());
+
+ // A child UINode under a parent UINode, with the two live boxes registered.
+ const withParentedNode = (): { child: number; parent: number; e: number } => {
+ const parent = S.commands.addEntity()!;
+ S.commands.addComponent(parent, 'UINode');
+ const child = S.commands.addEntity()!;
+ S.commands.addComponent(child, 'UINode');
+ S.commands.setParent(child, parent);
+ // Parent fills [-400,400]×[-300,300]; child sits at (100,50), size 140×40.
+ obb.boxes.set(rt(parent), { cx: 0, cy: 0, hw: 400, hh: 300, rot: 0 });
+ obb.boxes.set(rt(child), { cx: 100, cy: 50, hw: 70, hh: 20, rot: 0 });
+ return { child, parent, e: rt(child) };
+ };
+
+ const setAbsolute = (id: number): void =>
+ S.commands.setField(id, 'UINode', 'position', 'enum', UIPositionType.Absolute);
+
+ it('bakes auto insets to the px offset of the current box (left+top pinned)', () => {
+ const { child, e } = withParentedNode();
+ setAbsolute(child);
+ const n = host.world.get(e, UINode);
+ expect(n.position).toBe(UIPositionType.Absolute);
+ // left = (100-70) - (0-400) = 430 ; top(y-down) = (0+300) - (50+20) = 230
+ expect(n.insetLeft.unit).toBe(PX);
+ expect(n.insetLeft.value).toBe(430);
+ expect(n.insetTop.unit).toBe(PX);
+ expect(n.insetTop.value).toBe(230);
+ // Far edges stay auto — the node is pinned to top-left, free on the far sides.
+ expect(n.insetRight.unit).toBe(AUTO);
+ expect(n.insetBottom.unit).toBe(AUTO);
+ });
+
+ it('is ONE undo step: reverts both the flip and the seeded insets', () => {
+ const { child, e } = withParentedNode();
+ setAbsolute(child);
+ expect(host.world.get(e, UINode).insetLeft.unit).toBe(PX);
+ S.history.undo();
+ const n = host.world.get(e, UINode);
+ expect(n.position).toBe(UIPositionType.Relative);
+ expect(n.insetLeft.unit).toBe(AUTO);
+ expect(n.insetTop.unit).toBe(AUTO);
+ });
+
+ it('never clobbers an axis the user already positioned (a definite inset)', () => {
+ const { child, e } = withParentedNode();
+ S.commands.setField(child, 'UINode', 'insetLeft', 'dimension', { value: 12, unit: PX });
+ setAbsolute(child);
+ const n = host.world.get(e, UINode);
+ expect(n.insetLeft.value).toBe(12); // preserved, not re-baked
+ expect(n.insetTop.unit).toBe(PX); // the still-auto axis is baked
+ expect(n.insetTop.value).toBe(230);
+ });
+
+ it('subtracts the node\'s own px margin so it holds position', () => {
+ const { child, e } = withParentedNode();
+ S.commands.setField(child, 'UINode', 'marginLeft', 'dimension', { value: 30, unit: PX });
+ setAbsolute(child);
+ // 430 edge offset − 30 margin = 400 inset (margin still adds the other 30).
+ expect(host.world.get(e, UINode).insetLeft.value).toBe(400);
+ });
+
+ it('a centered node (auto insets + auto margins) drags: auto margins nail to 0 so the inset moves it', () => {
+ const { child, e } = withParentedNode();
+ S.commands.setField(child, 'UINode', 'position', 'enum', UIPositionType.Absolute);
+ // Reset to the Center-anchor shape: every inset + margin auto (self-centered).
+ for (const k of ['insetLeft', 'insetRight', 'insetTop', 'insetBottom', 'marginLeft', 'marginRight', 'marginTop', 'marginBottom'])
+ S.commands.setField(child, 'UINode', k, 'dimension', { value: 0, unit: AUTO });
+ S.commands.setEntityXY(child, 250, 50); // center 100→250 in x (dx=150), y unchanged
+ const n = host.world.get(e, UINode);
+ // The dragged (x) axis: auto margins nailed to 0, inset pinned to move the node.
+ expect(n.marginLeft.unit).toBe(PX);
+ expect(n.marginLeft.value).toBe(0);
+ expect(n.insetLeft.unit).toBe(PX);
+ expect(n.insetLeft.value).toBe(580); // 430 current offset + 150 delta
+ // The untouched (y) axis keeps its auto margins — only moved axes are nailed.
+ expect(n.marginTop.unit).toBe(AUTO);
+ });
+
+ it('is a graceful no-op flip when no live box is available (unlaid-out node)', () => {
+ const parent = S.commands.addEntity()!;
+ S.commands.addComponent(parent, 'UINode');
+ const child = S.commands.addEntity()!;
+ S.commands.addComponent(child, 'UINode');
+ S.commands.setParent(child, parent);
+ // No OBBs registered → seed can't compute; the flip still applies, insets stay auto.
+ setAbsolute(child);
+ const n = host.world.get(rt(child), UINode);
+ expect(n.position).toBe(UIPositionType.Absolute);
+ expect(n.insetLeft.unit).toBe(AUTO);
+ });
+});
diff --git a/desktop/tests/ui-widget-canvas.test.ts b/desktop/tests/ui-widget-canvas.test.ts
new file mode 100644
index 000000000..15fb5e5df
--- /dev/null
+++ b/desktop/tests/ui-widget-canvas.test.ts
@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file A UI widget ('under-canvas' placement) must be hosted by a Canvas — a
+ * UINode with no Canvas can't lay out or be positioned. createFromSource
+ * spins one up when the scene has none, reuses an existing one, and yields
+ * to an explicit parent.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const rec = vi.hoisted(() => ({ calls: [] as { name: string; parent: number | null }[], hasCanvas: false }));
+vi.mock('@/engine/SceneCommands', () => ({
+ SceneCommands: {
+ findCanvas: () => (rec.hasCanvas ? 1 : null),
+ create: (prefab: { name: string }, opts: { parent: number | null }) => {
+ rec.calls.push({ name: prefab.name, parent: opts.parent });
+ return 100 + rec.calls.length; // a fresh id per create
+ },
+ },
+}));
+
+import { ENTITY_SOURCES, createFromSource } from '@/engine/entitySources';
+const button = () => ENTITY_SOURCES.find((s) => s.label === 'Button')!;
+
+describe('UI widget creation ensures a Canvas host', () => {
+ beforeEach(() => { rec.calls = []; rec.hasCanvas = false; });
+
+ it('a Canvas-less scene spins up a Canvas first, then parents the widget under it', async () => {
+ await createFromSource(button(), { parent: null });
+ expect(rec.calls.map((c) => c.name)).toEqual(['Canvas', 'Button']);
+ expect(rec.calls[0].parent).toBeNull(); // Canvas at root
+ expect(rec.calls[1].parent).toBe(101); // Button under the just-made Canvas (id 100+1)
+ });
+
+ it('an existing Canvas is reused — no second Canvas', async () => {
+ rec.hasCanvas = true;
+ await createFromSource(button(), { parent: null });
+ expect(rec.calls.map((c) => c.name)).toEqual(['Button']);
+ expect(rec.calls[0].parent).toBe(1);
+ });
+
+ it('an explicit drop parent wins — no Canvas auto-created', async () => {
+ await createFromSource(button(), { parent: 42 });
+ expect(rec.calls.map((c) => c.name)).toEqual(['Button']);
+ expect(rec.calls[0].parent).toBe(42);
+ });
+});