A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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);+ });+});