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): moving a UINode edits its layout inputs — no more Yoga stomp

yhheab867c80cc3
diff --git a/desktop/src/engine/SceneCommands.ts b/desktop/src/engine/SceneCommands.ts
index 43af14cf7..795077c22 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, ProcessedEntity } from 'esengine';
-import { TilemapAPI } from 'esengine';
+import { TilemapAPI, UIPositionType, DimensionUnit } from 'esengine';
import type { EntityId, InspectorFieldType, InspectorFieldValue } from '@/types';
import { EditorHistory, EditorHistoryImpl } from './EditorHistory';
import { SceneModel, SceneModelImpl } from './SceneModel';
@@ -102,7 +102,8 @@ export function toModelValue(
return { ...(cur[key] as object), ...hexToRgba(String(value)) };
case 'gradient':
case 'curve':
- return value; // a structural { stops/keys: [...] } object — stored as-is
+ case 'dimension':
+ return value; // a structural object ({ stops/keys: [...] }, { value, unit }) — stored as-is
default:
return value;
}
@@ -281,6 +282,7 @@ export class SceneCommandsImpl {
* viewport tools speak world space; the model invariant stays local.
*/
setEntityXY(sourceId: EntityId, x: number, y: number): void {
+ if (this.setUINodeXY_(sourceId, x, y)) return;
const entity = this.model.entityBySource(sourceId);
const pos = this.modelFieldValue(sourceId, 'Transform', 'position') as { z?: number } | undefined;
if (pos === undefined && !entity) return;
@@ -289,6 +291,77 @@ export class SceneCommandsImpl {
this.setField(sourceId, 'Transform', 'position', 'vec3', [local.x, local.y, pos?.z ?? 0]);
}
+ /**
+ * A UINode's on-screen position is LAYOUT-owned: Yoga writes the resolved
+ * placement into `Transform.position` on every relayout, so a Transform write
+ * only holds until the next UI edit, then snaps back. Viewport moves edit the
+ * layout INPUTS instead:
+ * - Absolute nodes: the world delta lands in the inset dimensions — px insets
+ * 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).
+ * Returns true when the entity is a UINode (handled), false to fall through
+ * to the Transform path.
+ */
+ private setUINodeXY_(sourceId: EntityId, x: number, y: number): boolean {
+ const posKind = this.modelFieldValue(sourceId, 'UINode', 'position');
+ if (posKind === undefined) return false;
+ if (Number(posKind) !== UIPositionType.Absolute) return true;
+
+ 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 true; // no live layout boxes → nothing safe to edit
+
+ 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,
+ (node.cx - node.hw) - (parent.cx - parent.hw));
+ this.shiftInsetAxis_(sourceId, 'insetTop', 'insetBottom', -dy, 2 * parent.hh,
+ (parent.cy + parent.hh) - (node.cy + node.hh));
+ return true;
+ }
+
+ /**
+ * Shifts one inset axis by `delta` px toward the `near` edge: every non-auto
+ * side moves in its own unit (px directly, percent scaled by the parent
+ * size); a fully-auto axis pins `near` at its current offset plus the delta.
+ * Offsets measure against the parent's border box — a padded parent's static
+ * offset is absorbed into the pin, not reproduced.
+ */
+ private shiftInsetAxis_(
+ sourceId: EntityId, nearKey: string, farKey: string,
+ delta: number, parentSize: number, currentNearPx: number,
+ ): void {
+ if (delta === 0) return;
+ 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 });
+ shifted = true;
+ } else if (near.unit === DimensionUnit.Percent && parentSize > 0) {
+ write(nearKey, { ...near, value: near.value + (delta / parentSize) * 100 });
+ shifted = true;
+ }
+ if (far.unit === DimensionUnit.Px) {
+ write(farKey, { ...far, value: far.value - delta });
+ shifted = true;
+ } else if (far.unit === DimensionUnit.Percent && parentSize > 0) {
+ write(farKey, { ...far, value: far.value - (delta / parentSize) * 100 });
+ shifted = true;
+ }
+ if (!shifted) write(nearKey, { value: currentNearPx + delta, unit: DimensionUnit.Px });
+ }
+
// — 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/main.tsx b/desktop/src/main.tsx
index af7bb1610..6bae5ac4c 100644
--- a/desktop/src/main.tsx
+++ b/desktop/src/main.tsx
@@ -37,6 +37,8 @@ import { useSelection } from './store/selectionStore';
import { PlayRealm } from './engine/PlayRealm';
import { dockApi } from './layout/dockApi';
import { EditorControlSurface } from './engine/EditorSession';
+import { SceneModel } from './engine/SceneModel';
+import { ViewportController } from './engine/ViewportController';
import { PerfMonitor } from './engine/PerfMonitor';
import { LogStore } from './store/LogStore';
import { initFsWatch } from './project/fsWatch';
@@ -70,6 +72,13 @@ if (new URLSearchParams(location.search).has('automation')) {
togglePerfOverlay: () => PerfMonitor.toggleOverlay(),
captureThumbnail: () => ProjectStore.captureThumbnail(),
surface: EditorControlSurface,
+ /** Live world position of a SOURCE entity (engine-composed, Yoga-fresh for
+ * UI nodes) — lets a drag-automation shot assert a move stuck or was
+ * layout-rejected. */
+ entityWorldXY: (id: number) => {
+ const rt = SceneModel.runtimeFor(id);
+ return rt == null ? null : ViewportController.getEntityWorldXY(rt);
+ },
};
}
diff --git a/desktop/src/material/materialInspectorModel.ts b/desktop/src/material/materialInspectorModel.ts
index 61d2c514a..b6b506ded 100644
--- a/desktop/src/material/materialInspectorModel.ts
+++ b/desktop/src/material/materialInspectorModel.ts
@@ -13,7 +13,7 @@
* std140 layout; this is the editor view of the declarations.
*/
import { BlendMode, CullMode, Material, type MaterialAssetData, type UniformValue } from 'esengine';
-import type { InspectorComponent, InspectorField, InspectorFieldType, EnumOption, GradientValue, CurveValue } from '@/types';
+import type { InspectorComponent, InspectorField, InspectorFieldType, EnumOption, GradientValue, CurveValue, DimensionValue } from '@/types';
import { MaterialDocument } from './MaterialDocument';
import { reflectEsshader, type ShaderParam, type ShaderReflection } from './shaderReflect';
@@ -213,7 +213,7 @@ function fieldValueToAsset(param: ShaderParam, value: number | boolean | string
export function makeMaterialWrite(ctx: MaterialContext) {
// The value union matches FieldRow's edit callback; materials only ever emit
// number / boolean / string / number[] (no gradient/curve), so the cast below is safe.
- return (key: string, _type: InspectorFieldType, value: number | boolean | string | number[] | GradientValue | CurveValue): void => {
+ return (key: string, _type: InspectorFieldType, value: number | boolean | string | number[] | GradientValue | CurveValue | DimensionValue): void => {
if (RENDER_STATE_KEYS.has(key)) {
MaterialDocument.edit(`Set ${key}`, (d) => {
(d as unknown as Record<string, unknown>)[key] = value;
diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsx
index 82c3d375c..df66374b2 100644
--- a/desktop/src/panels/Details.tsx
+++ b/desktop/src/panels/Details.tsx
@@ -63,7 +63,7 @@ import {
import { ContextMenu } from '@/components/Menu';
import { Popover, usePopover } from '@/components/Popover';
import { AddComponentMenu } from '@/components/AddComponentMenu';
-import type { InspectorComponent, InspectorField, InspectorFieldValue, EntityId, NodeKind, EnumOption, AssetType, GradientValue, GradientStop, CurveValue, CurveKey } from '@/types';
+import type { InspectorComponent, InspectorField, InspectorFieldValue, EntityId, NodeKind, EnumOption, AssetType, GradientValue, GradientStop, CurveValue, CurveKey, DimensionValue } from '@/types';
const AXES = ['x', 'y', 'z'];
const fmt = (n: number) => String(Math.round(n * 1000) / 1000);
@@ -1033,7 +1033,7 @@ export function AssetControl({
// A field write override (the live "Game" inspector routes edits to the realm
// instead of the undoable SceneCommands path). When set, gestures are no-ops.
-type FieldWrite = (key: string, type: InspectorField['type'], value: number | boolean | string | number[] | GradientValue | CurveValue) => void;
+type FieldWrite = (key: string, type: InspectorField['type'], value: number | boolean | string | number[] | GradientValue | CurveValue | DimensionValue) => void;
function FieldRow({ entities, comp, field, write }: { entities: EntityId[]; comp: string; field: InspectorField; write?: FieldWrite }) {
const ranged = field.min != null || field.max != null;
@@ -1046,7 +1046,7 @@ function FieldRow({ entities, comp, field, write }: { entities: EntityId[]; comp
};
// An edit fans out to every selected entity (the open gesture coalesces them
// into one undo step); the live "Game" inspector routes to the realm instead.
- const apply = (value: number | boolean | string | number[] | GradientValue | CurveValue) => {
+ const apply = (value: number | boolean | string | number[] | GradientValue | CurveValue | DimensionValue) => {
const v = ranged && typeof value === 'number' ? clamp(value) : value;
if (write) return write(field.key, field.type, v);
for (const e of entities) SceneCommands.setField(e, comp, field.key, field.type, v as never);
diff --git a/desktop/src/tools/transformTools.ts b/desktop/src/tools/transformTools.ts
index 1b953cf0e..b9523c93f 100644
--- a/desktop/src/tools/transformTools.ts
+++ b/desktop/src/tools/transformTools.ts
@@ -32,6 +32,7 @@ import {
scaleAround,
} from './gizmo';
import { Marquee } from './marquee';
+import { Toasts } from '@/store/Toasts';
import type { EditorTool, PointerInput } from './EditorTool';
type Kind = 'move' | 'rotate' | 'scale';
@@ -98,8 +99,31 @@ function pruneDescendants(ids: readonly EntityId[]): EntityId[] {
});
}
-function captureTargets(ids: readonly EntityId[]): Target[] {
- return pruneDescendants(ids).map(readTarget).filter((t): t is Target => t !== null);
+/** Flow-layout (Relative) UINodes: the flex flow owns their position, so a move
+ * gesture has nothing to write (Absolute nodes move via inset edits instead —
+ * see SceneCommands.setEntityXY). Rotation/scale are NOT layout-owned, so this
+ * only gates `move`. */
+function isFlowUINode(sourceId: EntityId): boolean {
+ const pos = SceneQuery.getFieldValue(sourceId, 'UINode', 'position');
+ return pos != null && Number(pos) === 0;
+}
+
+let flowHintAt = 0;
+
+function captureTargets(ids: readonly EntityId[], kind: Kind = 'move'): Target[] {
+ let kept = pruneDescendants(ids);
+ if (kind === 'move') {
+ 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('流式布局(Relative)节点由布局定位,已跳过拖拽 — 将 position 改为 Absolute 可自由拖动', 'info');
+ }
+ }
+ }
+ return kept.map(readTarget).filter((t): t is Target => t !== null);
}
/** Selection centroid = mean of the live world positions of `ids`. */
@@ -301,7 +325,7 @@ function makeTransformTool(mode: ToolMode): EditorTool {
const localAngle = ed.coordSpace === 'local' ? primaryRotationRad(ids) : 0;
const handle = hitTestGizmo(mode as GizmoMode, pc, cur, -localAngle);
if (handle) {
- drag = beginDrag(kind, handle.axis, captureTargets(ids), pivotWorld, pc, p, cur, localAngle);
+ drag = beginDrag(kind, handle.axis, captureTargets(ids, kind), pivotWorld, pc, p, cur, localAngle);
ed.setActiveGizmoAxis(handle.axis); // light up the grabbed handle
ctx.capture(p.pointerId);
return true;
diff --git a/desktop/src/types.ts b/desktop/src/types.ts
index 68bc6cafd..c0c9d0df5 100644
--- a/desktop/src/types.ts
+++ b/desktop/src/types.ts
@@ -40,6 +40,7 @@ export type InspectorFieldType =
| 'flags' // an int bitmask, shown as a multi-select of its bits
| 'gradient' // a color-over-life gradient ({ stops: [...] })
| 'curve' // a scalar over-life curve ({ keys: [...] })
+ | 'dimension' // a CSS-style length ({ value, unit }) — UINode box/inset fields
| 'asset'; // a texture/material/font/... ref (@uuid: string, or 0 for none)
/** A dropdown option for an `enum` field: the label shown, the int stored. */
@@ -68,6 +69,12 @@ export interface CurveValue {
keys: CurveKey[];
}
+/** A CSS-style length ({ value, unit }) — the UINode Dimension wire shape. */
+export interface DimensionValue {
+ value: number;
+ unit: number;
+}
+
export type InspectorFieldValue =
| number
| boolean
@@ -75,7 +82,8 @@ export type InspectorFieldValue =
| [number, number]
| [number, number, number]
| GradientValue
- | CurveValue;
+ | CurveValue
+ | DimensionValue;
export interface InspectorField {
/** key in the component data object */