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(cocos): Widget and Layout — edge/centre/stretch alignment against the parent or the visible area, and row, column and grid layouts with Cocos's arithmetic, run in an end-of-frame pass

yhhd5e5c43bb348
diff --git a/sdk/src/cocos/builtinScripts.ts b/sdk/src/cocos/builtinScripts.ts
index c35825153..79cb537e9 100644
--- a/sdk/src/cocos/builtinScripts.ts
+++ b/sdk/src/cocos/builtinScripts.ts
@@ -11,6 +11,7 @@
import { getDefaultContext } from '../ecs/context';
import { declareButton } from './ui/button';
import { declareInputSystem } from './input';
+import { declareUiPass } from './ui/pass';
import { resetClassRegistry } from './registry';
const declared = new WeakSet<object>();
@@ -22,6 +23,7 @@ export function declareBuiltinScripts(): void {
declared.add(context);
declareButton();
declareInputSystem();
+ declareUiPass();
}
/** Test seam: forget the registry and declare again into the (possibly new) current context. */
diff --git a/sdk/src/cocos/index.ts b/sdk/src/cocos/index.ts
index 144897585..72c64552c 100644
--- a/sdk/src/cocos/index.ts
+++ b/sdk/src/cocos/index.ts
@@ -25,7 +25,7 @@ export {
AnimationClip, SceneAsset, EffectAsset, Mesh,
} from './assets';
export { registerBuiltinComponent, type BuiltinAdapter } from './builtins';
-export { UITransform, Label, LabelOutline, LabelShadow, Sprite, UIOpacity, Button, EventHandler } from './ui';
+export { UITransform, Label, LabelOutline, LabelShadow, Sprite, UIOpacity, Button, EventHandler, Widget, Layout, getVisibleSize, setVisibleSize } from './ui';
export { Touch, EventTouch, pumpTouches } from './input';
export { declareBuiltinScripts, redeclareBuiltinScripts } from './builtinScripts';
export { classInfoNamed, classInfoOf, allClassInfos, COMPONENT_PREFIX, resetClassRegistry } from './registry';
diff --git a/sdk/src/cocos/ui/index.ts b/sdk/src/cocos/ui/index.ts
index eb4b74e15..c4b79b07a 100644
--- a/sdk/src/cocos/ui/index.ts
+++ b/sdk/src/cocos/ui/index.ts
@@ -8,3 +8,6 @@ export { UITransform, uiTransformDef, ensureUITransform } from './uiTransform';
export { Label, LabelOutline, LabelShadow } from './label';
export { Sprite, UIOpacity } from './sprite';
export { Button, EventHandler, declareButton } from './button';
+export { Widget, alignWidget } from './widget';
+export { Layout } from './layout';
+export { getVisibleSize, setVisibleSize } from './screen';
diff --git a/sdk/src/cocos/ui/layout.ts b/sdk/src/cocos/ui/layout.ts
new file mode 100644
index 000000000..8faf555bc
--- /dev/null
+++ b/sdk/src/cocos/ui/layout.ts
@@ -0,0 +1,327 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file cocos/ui/layout.ts
+ * @brief `Layout`: a container that arranges its children in a row, a column or a grid.
+ *
+ * The arithmetic is Cocos's, ported rather than re-derived, so a list lands where it landed there: positions come from the layout's
+ * anchor and padding, each child contributes its size (times its scale only if `affectedByScale`), and a row or column breaks when
+ * the next child would cross the far edge, or at a fixed count. `resizeMode` lets the container grow to fit (CONTAINER) or the
+ * children stretch to fill it (CHILDREN).
+ *
+ * Cocos relayouts when something it listens to changes. Here the pass compares what the layout depends on — its settings and the
+ * active children with their sizes — against what it saw last, and relayouts on a difference, which is the same trigger without a
+ * listener on every child. `updateLayout()` forces it now.
+ */
+import { Component } from '../component';
+import { Node } from '../node';
+import { Size, Vec3 } from '../math';
+import { declareClass } from '../host';
+import { instancesOfClass } from '../registry';
+import type { World } from '../../ecs/world';
+import type { Entity } from '../../types';
+import { UITransform } from './uiTransform';
+import { depthOf } from './widget';
+
+const Type = Object.freeze({ NONE: 0, HORIZONTAL: 1, VERTICAL: 2, GRID: 3 });
+const ResizeMode = Object.freeze({ NONE: 0, CONTAINER: 1, CHILDREN: 2 });
+const AxisDirection = Object.freeze({ HORIZONTAL: 0, VERTICAL: 1 });
+const VerticalDirection = Object.freeze({ BOTTOM_TO_TOP: 0, TOP_TO_BOTTOM: 1 });
+const HorizontalDirection = Object.freeze({ LEFT_TO_RIGHT: 0, RIGHT_TO_LEFT: 1 });
+const Constraint = Object.freeze({ NONE: 0, FIXED_ROW: 1, FIXED_COL: 2 });
+
+const SETTINGS = [
+ 'type', 'resizeMode', 'paddingLeft', 'paddingRight', 'paddingTop', 'paddingBottom', 'spacingX', 'spacingY',
+ 'verticalDirection', 'horizontalDirection', 'affectedByScale', 'cellWidth', 'cellHeight', 'startAxis', 'constraint', 'constraintNum', 'isAlign',
+] as const;
+
+export class Layout extends Component {
+ static readonly Type = Type;
+ static readonly ResizeMode = ResizeMode;
+ static readonly AxisDirection = AxisDirection;
+ static readonly VerticalDirection = VerticalDirection;
+ static readonly HorizontalDirection = HorizontalDirection;
+ static readonly Constraint = Constraint;
+
+ type: number = Type.NONE;
+ resizeMode: number = ResizeMode.NONE;
+ paddingLeft = 0;
+ paddingRight = 0;
+ paddingTop = 0;
+ paddingBottom = 0;
+ spacingX = 0;
+ spacingY = 0;
+ verticalDirection: number = VerticalDirection.TOP_TO_BOTTOM;
+ horizontalDirection: number = HorizontalDirection.LEFT_TO_RIGHT;
+ affectedByScale = false;
+ cellWidth = 40;
+ cellHeight = 40;
+ startAxis: number = AxisDirection.HORIZONTAL;
+ constraint: number = Constraint.NONE;
+ constraintNum = 2;
+ isAlign = false;
+
+ /** @internal */
+ _seen = '';
+
+ get cellSize(): Size { return new Size(this.cellWidth, this.cellHeight); }
+ set cellSize(v: Size) { this.cellWidth = v.width; this.cellHeight = v.height; }
+ get alignHorizontal(): boolean { return this.isAlign; }
+ set alignHorizontal(v: boolean) { this.isAlign = v; }
+ get alignVertical(): boolean { return this.isAlign; }
+ set alignVertical(v: boolean) { this.isAlign = v; }
+ get padding(): number { return this.paddingLeft; }
+ set padding(v: number) { this.paddingLeft = this.paddingRight = this.paddingTop = this.paddingBottom = v; }
+
+ /** Arrange the children now, rather than at the end of the frame. */
+ updateLayout(force = false): void {
+ if (force) this._seen = '';
+ layoutNode(this);
+ this._seen = this.signature_();
+ }
+
+ /** @internal What the layout depends on: its settings, and the useful children with their sizes. */
+ signature_(): string {
+ let s = '';
+ for (const k of SETTINGS) s += `${this[k]},`;
+ const own = this.node.getComponent(UITransform);
+ if (own) s += `${own.width},${own.height},${own.anchorX},${own.anchorY}`;
+ const scaled = this.affectedByScale;
+ for (const t of usefulChildren(this)) {
+ const sc = scaled ? t.node.getScale() : null;
+ s += `|${t.node._entity},${t.width},${t.height}${sc ? `,${sc.x},${sc.y}` : ''}`;
+ }
+ return s;
+ }
+}
+
+/** Active children that have a rectangle, in sibling order. */
+function usefulChildren(layout: Layout): UITransform[] {
+ const out: UITransform[] = [];
+ for (const child of layout.node.children) {
+ if (!child.active) continue;
+ const t = child.getComponent(UITransform);
+ if (t) out.push(t);
+ }
+ return out;
+}
+
+const used = (layout: Layout, scale: number): number => (layout.affectedByScale ? Math.abs(scale) : 1);
+const paddingH = (l: Layout): number => l.paddingLeft + l.paddingRight;
+const paddingV = (l: Layout): number => l.paddingTop + l.paddingBottom;
+
+/** How many children a row (or column) holds under a fixed constraint, 0 when it is free. */
+function fixedBreakingNum(l: Layout, count: number): number {
+ if (l.type !== Type.GRID || l.constraint === Constraint.NONE || l.constraintNum <= 0) return 0;
+ let num = l.constraint === Constraint.FIXED_ROW ? Math.ceil(count / l.constraintNum) : l.constraintNum;
+ if (l.startAxis === AxisDirection.VERTICAL) num = l.constraint === Constraint.FIXED_COL ? Math.ceil(count / l.constraintNum) : l.constraintNum;
+ return num;
+}
+
+type Position = (child: Node, t: UITransform, offset: number) => number;
+
+function layoutHorizontally(l: Layout, children: UITransform[], self: UITransform, baseWidth: number, rowBreak: boolean, positionY: Position, apply: boolean): number {
+ const limit = fixedBreakingNum(l, children.length);
+ let sign = 1;
+ let padX = l.paddingLeft;
+ if (l.horizontalDirection === HorizontalDirection.RIGHT_TO_LEFT) { sign = -1; padX = l.paddingRight; }
+
+ const startPos = (l.horizontalDirection - self.anchorX) * baseWidth + sign * padX;
+ let nextX = startPos - sign * l.spacingX;
+ let totalHeight = 0, rowMaxHeight = 0, tempMaxHeight = 0, maxHeight = 0;
+ let isBreak = false;
+ let newChildWidth = l.cellWidth;
+ if (l.type !== Type.GRID && l.resizeMode === ResizeMode.CHILDREN) {
+ newChildWidth = (baseWidth - paddingH(l) - (children.length - 1) * l.spacingX) / children.length;
+ }
+
+ for (let i = 0; i < children.length; i++) {
+ const t = children[i]!;
+ const child = t.node;
+ const scale = child.getScale();
+ const sx = used(l, scale.x), sy = used(l, scale.y);
+ if (l.resizeMode === ResizeMode.CHILDREN) {
+ t.width = newChildWidth / sx;
+ if (l.type === Type.GRID) t.height = l.cellHeight / sy;
+ }
+ const anchorX = Math.abs(l.horizontalDirection - t.anchorX);
+ const w = t.width * sx;
+ const h = t.height * sy;
+
+ if (h > tempMaxHeight) {
+ maxHeight = Math.max(tempMaxHeight, maxHeight);
+ rowMaxHeight = tempMaxHeight || h;
+ tempMaxHeight = h;
+ }
+ nextX += sign * (anchorX * w + l.spacingX);
+ const rightBoundary = sign * (1 - anchorX) * w;
+
+ if (rowBreak) {
+ if (limit > 0) {
+ isBreak = i / limit > 0 && i % limit === 0;
+ if (isBreak) rowMaxHeight = tempMaxHeight > h ? tempMaxHeight : rowMaxHeight;
+ } else if (w > baseWidth - paddingH(l)) {
+ if (nextX > startPos + sign * (anchorX * w)) isBreak = true;
+ } else {
+ const boundary = (1 - l.horizontalDirection - self.anchorX) * baseWidth;
+ const breakBoundary = nextX + rightBoundary + sign * (sign > 0 ? l.paddingRight : l.paddingLeft);
+ isBreak = Math.abs(breakBoundary) > Math.abs(boundary);
+ }
+ if (isBreak) {
+ nextX = startPos + sign * (anchorX * w);
+ if (h !== tempMaxHeight) rowMaxHeight = tempMaxHeight;
+ totalHeight += rowMaxHeight + l.spacingY;
+ rowMaxHeight = tempMaxHeight = h;
+ }
+ }
+ const y = positionY(child, t, totalHeight);
+ if (apply) child.setPosition(nextX, y);
+ nextX += rightBoundary;
+ }
+ rowMaxHeight = Math.max(rowMaxHeight, tempMaxHeight);
+ return Math.max(maxHeight, totalHeight + rowMaxHeight) + paddingV(l);
+}
+
+function layoutVertically(l: Layout, children: UITransform[], self: UITransform, baseHeight: number, columnBreak: boolean, positionX: Position, apply: boolean): number {
+ const limit = fixedBreakingNum(l, children.length);
+ let sign = 1;
+ let padY = l.paddingBottom;
+ if (l.verticalDirection === VerticalDirection.TOP_TO_BOTTOM) { sign = -1; padY = l.paddingTop; }
+
+ const startPos = (l.verticalDirection - self.anchorY) * baseHeight + sign * padY;
+ let nextY = startPos - sign * l.spacingY;
+ let tempMaxWidth = 0, maxWidth = 0, colMaxWidth = 0, totalWidth = 0;
+ let isBreak = false;
+ let newChildHeight = l.cellHeight;
+ if (l.type !== Type.GRID && l.resizeMode === ResizeMode.CHILDREN) {
+ newChildHeight = (baseHeight - paddingV(l) - (children.length - 1) * l.spacingY) / children.length;
+ }
+
+ for (let i = 0; i < children.length; i++) {
+ const t = children[i]!;
+ const child = t.node;
+ const scale = child.getScale();
+ const sx = used(l, scale.x), sy = used(l, scale.y);
+ if (l.resizeMode === ResizeMode.CHILDREN) {
+ t.height = newChildHeight / sy;
+ if (l.type === Type.GRID) t.width = l.cellWidth / sx;
+ }
+ const anchorY = Math.abs(l.verticalDirection - t.anchorY);
+ const w = t.width * sx;
+ const h = t.height * sy;
+
+ if (w > tempMaxWidth) {
+ maxWidth = Math.max(tempMaxWidth, maxWidth);
+ colMaxWidth = tempMaxWidth || w;
+ tempMaxWidth = w;
+ }
+ nextY += sign * (anchorY * h + l.spacingY);
+ const topBoundary = sign * (1 - anchorY) * h;
+
+ if (columnBreak) {
+ if (limit > 0) {
+ isBreak = i / limit > 0 && i % limit === 0;
+ if (isBreak) colMaxWidth = tempMaxWidth > h ? tempMaxWidth : colMaxWidth;
+ } else if (h > baseHeight - paddingV(l)) {
+ if (nextY > startPos + sign * (anchorY * h)) isBreak = true;
+ } else {
+ const boundary = (1 - l.verticalDirection - self.anchorY) * baseHeight;
+ const breakBoundary = nextY + topBoundary + sign * (sign > 0 ? l.paddingTop : l.paddingBottom);
+ isBreak = Math.abs(breakBoundary) > Math.abs(boundary);
+ }
+ if (isBreak) {
+ nextY = startPos + sign * (anchorY * h);
+ if (w !== tempMaxWidth) colMaxWidth = tempMaxWidth;
+ totalWidth += colMaxWidth + l.spacingX;
+ colMaxWidth = tempMaxWidth = w;
+ }
+ }
+ const x = positionX(child, t, totalWidth);
+ if (apply) child.setPosition(new Vec3(x, nextY, child.getPosition().z));
+ nextY += topBoundary;
+ }
+ colMaxWidth = Math.max(colMaxWidth, tempMaxWidth);
+ return Math.max(maxWidth, totalWidth + colMaxWidth) + paddingH(l);
+}
+
+/** Arrange one layout's children. */
+export function layoutNode(l: Layout): void {
+ const self = l.node.getComponent(UITransform);
+ if (!self) return;
+ const children = usefulChildren(l);
+
+ if (l.type === Type.HORIZONTAL) {
+ let baseWidth = self.width;
+ if (l.resizeMode === ResizeMode.CONTAINER) {
+ baseWidth = children.reduce((s, t) => s + t.width * used(l, t.node.getScale().x), 0) + (children.length - 1) * l.spacingX + paddingH(l);
+ }
+ layoutHorizontally(l, children, self, baseWidth, false, (c) => (l.isAlign ? 0 : c.getPosition().y), true);
+ self.width = baseWidth;
+ } else if (l.type === Type.VERTICAL) {
+ let baseHeight = self.height;
+ if (l.resizeMode === ResizeMode.CONTAINER) {
+ baseHeight = children.reduce((s, t) => s + t.height * used(l, t.node.getScale().y), 0) + (children.length - 1) * l.spacingY + paddingV(l);
+ }
+ layoutVertically(l, children, self, baseHeight, false, (c) => (l.isAlign ? 0 : c.getPosition().x), true);
+ self.height = baseHeight;
+ } else if (l.type === Type.GRID) {
+ const anchor = { x: self.anchorX, y: self.anchorY };
+ const size = { width: self.width, height: self.height };
+ if (l.startAxis === AxisDirection.HORIZONTAL) {
+ let sign = 1;
+ let bottom = -anchor.y * size.height;
+ let padY = l.paddingBottom;
+ if (l.verticalDirection === VerticalDirection.TOP_TO_BOTTOM) { sign = -1; bottom = (1 - anchor.y) * size.height; padY = l.paddingTop; }
+ const fn: Position = (c, t, off) => bottom + sign * (off + (1 - t.anchorY) * t.height * used(l, c.getScale().y) + padY);
+ let newHeight = 0;
+ if (l.resizeMode === ResizeMode.CONTAINER) {
+ newHeight = layoutHorizontally(l, children, self, size.width, true, fn, false);
+ bottom = -anchor.y * newHeight;
+ if (l.verticalDirection === VerticalDirection.TOP_TO_BOTTOM) bottom = (1 - anchor.y) * newHeight;
+ }
+ layoutHorizontally(l, children, self, size.width, true, fn, true);
+ if (l.resizeMode === ResizeMode.CONTAINER) self.setContentSize(size.width, newHeight);
+ } else {
+ let sign = 1;
+ let left = -anchor.x * size.width;
+ let padX = l.paddingLeft;
+ if (l.horizontalDirection === HorizontalDirection.RIGHT_TO_LEFT) { sign = -1; left = (1 - anchor.x) * size.width; padX = l.paddingRight; }
+ const fn: Position = (c, t, off) => left + sign * (off + (1 - t.anchorX) * t.width * used(l, c.getScale().x) + padX);
+ let newWidth = 0;
+ if (l.resizeMode === ResizeMode.CONTAINER) {
+ newWidth = layoutVertically(l, children, self, size.height, true, fn, false);
+ left = -anchor.x * newWidth;
+ if (l.horizontalDirection === HorizontalDirection.RIGHT_TO_LEFT) left = (1 - anchor.x) * newWidth;
+ }
+ layoutVertically(l, children, self, size.height, true, fn, true);
+ if (l.resizeMode === ResizeMode.CONTAINER) self.setContentSize(newWidth, size.height);
+ }
+ }
+}
+
+/** Arrange every layout whose inputs changed, innermost first (an outer container may be sized by an inner one). */
+export function layoutAll(world: World): void {
+ const due: Array<{ layout: Layout; depth: number }> = [];
+ for (const [entity, inst] of instancesOfClass(world, Layout) as Array<[Entity, Layout]>) {
+ if (!inst.enabled || !world.isEntityActive(entity) || inst.type === Type.NONE) continue;
+ const sig = inst.signature_();
+ if (sig === inst._seen) continue;
+ due.push({ layout: inst, depth: depthOf(inst.node) });
+ }
+ due.sort((a, b) => b.depth - a.depth);
+ for (const { layout } of due) {
+ layoutNode(layout);
+ // Laying out can resize the container or the children, which changes what the layout depends on; record the result so it settles.
+ layout._seen = layout.signature_();
+ }
+}
+
+export function declareLayout(): void {
+ declareClass(Layout as never, 'Layout', [
+ ...['type', 'resizeMode', 'paddingLeft', 'paddingRight', 'paddingTop', 'paddingBottom', 'spacingX', 'spacingY',
+ 'verticalDirection', 'horizontalDirection', 'cellWidth', 'cellHeight', 'startAxis', 'constraint', 'constraintNum']
+ .map((name) => ({ name, kind: 'number' as const })),
+ { name: 'affectedByScale', kind: 'boolean' as const },
+ { name: 'isAlign', kind: 'boolean' as const },
+ ]);
+}
diff --git a/sdk/src/cocos/ui/pass.ts b/sdk/src/cocos/ui/pass.ts
new file mode 100644
index 000000000..7430c3d45
--- /dev/null
+++ b/sdk/src/cocos/ui/pass.ts
@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file cocos/ui/pass.ts
+ * @brief The end-of-frame pass that aligns widgets and arranges layouts.
+ *
+ * Cocos does both after the frame's scripts have run, so a script that moves or resizes something this frame is answered by the
+ * alignment in the same frame. Widgets go first (a stretched container changes what its layout sees), then layouts innermost-first,
+ * then widgets once more for the ones that follow a size the layouts just set (those set to align every frame).
+ */
+import { Schedule, defineSystem, addSystemToSchedule, GetWorld } from '../../ecs/system';
+import { setCurrentWorld } from '../node';
+import { alignAllWidgets, declareWidget } from './widget';
+import { layoutAll, declareLayout } from './layout';
+
+export function declareUiPass(): void {
+ declareWidget();
+ declareLayout();
+ const system = defineSystem(
+ [GetWorld()],
+ (world) => {
+ const previous = setCurrentWorld(world);
+ try {
+ alignAllWidgets(world);
+ layoutAll(world);
+ alignAllWidgets(world);
+ } finally {
+ setCurrentWorld(previous);
+ }
+ },
+ { name: 'Cocos:UiPass', touches: { opaque: true } },
+ );
+ addSystemToSchedule(Schedule.Last, system);
+}
diff --git a/sdk/src/cocos/ui/screen.ts b/sdk/src/cocos/ui/screen.ts
new file mode 100644
index 000000000..a3e420f3b
--- /dev/null
+++ b/sdk/src/cocos/ui/screen.ts
@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file cocos/ui/screen.ts
+ * @brief The rectangle a root UI node aligns to: Cocos's "visible rect".
+ *
+ * A widget on a node whose parent has no rectangle of its own (the canvas, or anything straight under the scene) aligns to the
+ * visible area of the screen. In an imported scene the engine's world and Cocos's are one space, with the visible area running from
+ * the origin to its size, so the rectangle is just a width and a height. The host sets it from the real viewport; until it does, it
+ * is the size of a typical design resolution so a scene still lays out.
+ */
+
+let width = 960;
+let height = 640;
+let generation = 0;
+
+/** The visible area's size, in the canvas units scripts see. */
+export function getVisibleSize(): { width: number; height: number } { return { width, height }; }
+
+/** Tell the layer the visible area changed; widgets set to follow the window re-align. */
+export function setVisibleSize(w: number, h: number): void {
+ if (w === width && h === height) return;
+ width = w;
+ height = h;
+ generation++;
+}
+
+/** Bumps whenever the visible size changes. */
+export function visibleSizeGeneration(): number { return generation; }
diff --git a/sdk/src/cocos/ui/widget.ts b/sdk/src/cocos/ui/widget.ts
new file mode 100644
index 000000000..e2ffd3c55
--- /dev/null
+++ b/sdk/src/cocos/ui/widget.ts
@@ -0,0 +1,227 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file cocos/ui/widget.ts
+ * @brief `Widget`: a node pinned to the edges (or centre) of its parent's rectangle.
+ *
+ * The arithmetic is Cocos's own, so a panel lands where it landed there: each axis is either stretched (both edges set — the size
+ * follows the parent), pinned to one edge, or centred with an offset, with margins in pixels or as a fraction of the parent. A node
+ * whose parent has no rectangle aligns to the visible area (see screen.ts).
+ *
+ * When it runs follows `alignMode`: ONCE the first time, ON_WINDOW_RESIZE on enable and whenever the visible size changes, ALWAYS
+ * every frame. Changing any of the widget's own settings re-aligns it whatever the mode, which is what the setters do in Cocos.
+ *
+ * Only the parent as target is supported; a widget that names another node as its target aligns to the parent and says so once.
+ */
+import { Component } from '../component';
+import { Node } from '../node';
+import { Vec3 } from '../math';
+import { declareClass } from '../host';
+import { instancesOfClass } from '../registry';
+import { log } from '../../util/logger';
+import type { World } from '../../ecs/world';
+import type { Entity } from '../../types';
+import { UITransform } from './uiTransform';
+import { getVisibleSize, visibleSizeGeneration } from './screen';
+
+const AlignFlags = Object.freeze({ TOP: 1, MID: 2, BOT: 4, LEFT: 8, CENTER: 16, RIGHT: 32, HORIZONTAL: 8 | 16 | 32, VERTICAL: 1 | 2 | 4 });
+const AlignMode = Object.freeze({ ONCE: 0, ON_WINDOW_RESIZE: 1, ALWAYS: 2 });
+
+const SETTINGS = [
+ 'alignFlags', 'left', 'right', 'top', 'bottom', 'horizontalCenter', 'verticalCenter',
+ 'isAbsLeft', 'isAbsRight', 'isAbsTop', 'isAbsBottom', 'isAbsHorizontalCenter', 'isAbsVerticalCenter', 'alignMode',
+] as const;
+
+export class Widget extends Component {
+ static readonly AlignMode = AlignMode;
+ static readonly AlignFlags = AlignFlags;
+
+ alignFlags = 0;
+ left = 0;
+ right = 0;
+ top = 0;
+ bottom = 0;
+ horizontalCenter = 0;
+ verticalCenter = 0;
+ isAbsLeft = true;
+ isAbsRight = true;
+ isAbsTop = true;
+ isAbsBottom = true;
+ isAbsHorizontalCenter = true;
+ isAbsVerticalCenter = true;
+ alignMode: number = AlignMode.ON_WINDOW_RESIZE;
+ target: Node | null = null;
+
+ /** @internal What the last alignment saw: the settings, and the visible size it was done at. */
+ _seen = '';
+ _seenGeneration = -1;
+ _hadAlignOnce = false;
+ _warnedTarget = false;
+
+ private flag_(bit: number): boolean { return (this.alignFlags & bit) > 0; }
+ private setFlag_(bit: number, on: boolean, clears = 0): void {
+ this.alignFlags = on ? (this.alignFlags | bit) & ~clears : this.alignFlags & ~bit;
+ }
+ get isAlignLeft(): boolean { return this.flag_(AlignFlags.LEFT); }
+ set isAlignLeft(v: boolean) { this.setFlag_(AlignFlags.LEFT, v, AlignFlags.CENTER); }
+ get isAlignRight(): boolean { return this.flag_(AlignFlags.RIGHT); }
+ set isAlignRight(v: boolean) { this.setFlag_(AlignFlags.RIGHT, v, AlignFlags.CENTER); }
+ get isAlignTop(): boolean { return this.flag_(AlignFlags.TOP); }
+ set isAlignTop(v: boolean) { this.setFlag_(AlignFlags.TOP, v, AlignFlags.MID); }
+ get isAlignBottom(): boolean { return this.flag_(AlignFlags.BOT); }
+ set isAlignBottom(v: boolean) { this.setFlag_(AlignFlags.BOT, v, AlignFlags.MID); }
+ get isAlignHorizontalCenter(): boolean { return this.flag_(AlignFlags.CENTER); }
+ set isAlignHorizontalCenter(v: boolean) { this.setFlag_(AlignFlags.CENTER, v, AlignFlags.LEFT | AlignFlags.RIGHT); }
+ get isAlignVerticalCenter(): boolean { return this.flag_(AlignFlags.MID); }
+ set isAlignVerticalCenter(v: boolean) { this.setFlag_(AlignFlags.MID, v, AlignFlags.TOP | AlignFlags.BOT); }
+ get isStretchWidth(): boolean { return (this.alignFlags & (AlignFlags.LEFT | AlignFlags.RIGHT)) === (AlignFlags.LEFT | AlignFlags.RIGHT); }
+ get isStretchHeight(): boolean { return (this.alignFlags & (AlignFlags.TOP | AlignFlags.BOT)) === (AlignFlags.TOP | AlignFlags.BOT); }
+
+ get isAbsoluteLeft(): boolean { return this.isAbsLeft; }
+ set isAbsoluteLeft(v: boolean) { this.isAbsLeft = v; }
+ get isAbsoluteRight(): boolean { return this.isAbsRight; }
+ set isAbsoluteRight(v: boolean) { this.isAbsRight = v; }
+ get isAbsoluteTop(): boolean { return this.isAbsTop; }
+ set isAbsoluteTop(v: boolean) { this.isAbsTop = v; }
+ get isAbsoluteBottom(): boolean { return this.isAbsBottom; }
+ set isAbsoluteBottom(v: boolean) { this.isAbsBottom = v; }
+ get isAbsoluteHorizontalCenter(): boolean { return this.isAbsHorizontalCenter; }
+ set isAbsoluteHorizontalCenter(v: boolean) { this.isAbsHorizontalCenter = v; }
+ get isAbsoluteVerticalCenter(): boolean { return this.isAbsVerticalCenter; }
+ set isAbsoluteVerticalCenter(v: boolean) { this.isAbsVerticalCenter = v; }
+
+ /** Align now, rather than at the end of the frame. */
+ updateAlignment(): void {
+ this._hadAlignOnce = false;
+ alignWidget(this);
+ }
+
+ /** Ask for alignment at the end of the frame, whatever the mode. */
+ setDirty(): void { this._seen = ''; this._hadAlignOnce = false; }
+
+ private signature_(): string {
+ let s = '';
+ for (const k of SETTINGS) s += `${this[k]},`;
+ return s;
+ }
+
+ /** @internal Whether the pass should align this widget now. */
+ _due(generation: number): boolean {
+ if (this.alignFlags === 0) return false;
+ if (this.alignMode === AlignMode.ALWAYS) return true;
+ const sig = this.signature_();
+ if (sig !== this._seen) { this._seen = sig; this._seenGeneration = generation; this._hadAlignOnce = false; return true; }
+ if (this.alignMode === AlignMode.ONCE) return false;
+ if (generation !== this._seenGeneration) { this._seenGeneration = generation; return true; }
+ return false;
+ }
+}
+
+interface Anchor { x: number; y: number }
+
+/** Align one widget to its parent, as Cocos's `align` does (rotation ignored). */
+export function alignWidget(widget: Widget): void {
+ if (widget._hadAlignOnce) return;
+ if (widget.alignMode === AlignMode.ONCE) widget._hadAlignOnce = true;
+ const node = widget.node;
+ const own = node.getComponent(UITransform);
+ if (!own) return;
+ if (widget.target && widget.target !== node.parent && !widget._warnedTarget) {
+ widget._warnedTarget = true;
+ log.warn('cocos', `${node.name}: Widget.target other than the parent is not supported; aligning to the parent`);
+ }
+
+ const parent = node.parent;
+ const parentTransform = parent?.getComponent(UITransform) ?? null;
+ const isRoot = !parentTransform;
+ const visible = getVisibleSize();
+ const targetW = parentTransform ? parentTransform.width : visible.width;
+ const targetH = parentTransform ? parentTransform.height : visible.height;
+ const targetAnchor: Anchor = parentTransform ? { x: parentTransform.anchorX, y: parentTransform.anchorY } : { x: 0, y: 0 };
+
+ const pos = node.getPosition();
+ const scale = node.getScale();
+ let x = pos.x;
+ let y = pos.y;
+
+ if (widget.alignFlags & AlignFlags.HORIZONTAL) {
+ let left = isRoot ? 0 : -targetAnchor.x * targetW;
+ let right = isRoot ? visible.width : left + targetW;
+ left += widget.isAbsLeft ? widget.left : widget.left * targetW;
+ right -= widget.isAbsRight ? widget.right : widget.right * targetW;
+ let anchorX = own.anchorX;
+ let scaleX = scale.x;
+ if (scaleX < 0) { anchorX = 1 - anchorX; scaleX = -scaleX; }
+ if (widget.isStretchWidth) {
+ const width = right - left;
+ if (scaleX !== 0) own.width = width / scaleX;
+ x = left + anchorX * width;
+ } else {
+ const width = own.width * scaleX;
+ if (widget.isAlignHorizontalCenter) {
+ const offset = widget.isAbsHorizontalCenter ? widget.horizontalCenter : widget.horizontalCenter * targetW;
+ const center = (0.5 - targetAnchor.x) * targetW;
+ x = center + (anchorX - 0.5) * width + offset;
+ } else if (widget.isAlignLeft) {
+ x = left + anchorX * width;
+ } else {
+ x = right + (anchorX - 1) * width;
+ }
+ }
+ }
+
+ if (widget.alignFlags & AlignFlags.VERTICAL) {
+ let bottom = isRoot ? 0 : -targetAnchor.y * targetH;
+ let top = isRoot ? visible.height : bottom + targetH;
+ bottom += widget.isAbsBottom ? widget.bottom : widget.bottom * targetH;
+ top -= widget.isAbsTop ? widget.top : widget.top * targetH;
+ let anchorY = own.anchorY;
+ let scaleY = scale.y;
+ if (scaleY < 0) { anchorY = 1 - anchorY; scaleY = -scaleY; }
+ if (widget.isStretchHeight) {
+ const height = top - bottom;
+ if (scaleY !== 0) own.height = height / scaleY;
+ y = bottom + anchorY * height;
+ } else {
+ const height = own.height * scaleY;
+ if (widget.isAlignVerticalCenter) {
+ const offset = widget.isAbsVerticalCenter ? widget.verticalCenter : widget.verticalCenter * targetH;
+ const middle = (0.5 - targetAnchor.y) * targetH;
+ y = middle + (anchorY - 0.5) * height + offset;
+ } else if (widget.isAlignBottom) {
+ y = bottom + anchorY * height;
+ } else {
+ y = top + (anchorY - 1) * height;
+ }
+ }
+ }
+ node.setPosition(new Vec3(x, y, pos.z));
+}
+
+/** How deep a node is: parents align before the children that depend on their size. */
+export function depthOf(node: Node): number {
+ let d = 0;
+ for (let p = node.parent; p; p = p.parent) d++;
+ return d;
+}
+
+/** Align every widget that is due, parents first. */
+export function alignAllWidgets(world: World): void {
+ const generation = visibleSizeGeneration();
+ const due: Array<{ widget: Widget; depth: number }> = [];
+ for (const [entity, inst] of instancesOfClass(world, Widget) as Array<[Entity, Widget]>) {
+ if (!inst.enabled || !world.isEntityActive(entity)) continue;
+ if (inst._due(generation)) due.push({ widget: inst, depth: depthOf(inst.node) });
+ }
+ due.sort((a, b) => a.depth - b.depth);
+ for (const { widget } of due) alignWidget(widget);
+}
+
+/** Declare the widget's component, so a scene that holds one finds it. */
+export function declareWidget(): void {
+ declareClass(Widget as never, 'Widget', [
+ ...['alignFlags', 'left', 'right', 'top', 'bottom', 'horizontalCenter', 'verticalCenter', 'alignMode'].map((name) => ({ name, kind: 'number' as const })),
+ ...['isAbsLeft', 'isAbsRight', 'isAbsTop', 'isAbsBottom', 'isAbsHorizontalCenter', 'isAbsVerticalCenter'].map((name) => ({ name, kind: 'boolean' as const })),
+ { name: 'target', kind: 'node' as const },
+ ]);
+}
diff --git a/sdk/tests/cocos/widget-layout-wasm.test.ts b/sdk/tests/cocos/widget-layout-wasm.test.ts
new file mode 100644
index 000000000..345669f8d
--- /dev/null
+++ b/sdk/tests/cocos/widget-layout-wasm.test.ts
@@ -0,0 +1,207 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file `Widget` and `Layout` against the real engine.
+ *
+ * The numbers are the ones Cocos produces for the same settings: a stretched panel takes its parent's size minus its margins, a
+ * pinned one keeps its size and sits at the edge by its anchor, a centred one is offset from the middle; a row starts at the
+ * container's left edge plus padding and advances by each child's width plus spacing.
+ */
+import { afterEach, beforeAll, describe, expect, it } from 'vitest';
+import type { ESEngineModule } from '../../src/wasm';
+import { App, flushPendingRegistrations } from '../../src/app/app';
+import { Transform, ensureBuiltinComponentsRegistered } from '../../src/ecs/component';
+import { AppContext, setDefaultContext } from '../../src/ecs/context';
+import { resetClassRegistry } from '../../src/cocos/registry';
+import { Layout, Node, UITransform, Widget, setCurrentWorld, setVisibleSize } from '../../src/cocos';
+import { declareUiPass } from '../../src/cocos/ui/pass';
+import { HAS_WASM, loadWasmModule } from '../helpers/loadWasm';
+
+describe.skipIf(!HAS_WASM)('widgets and layouts on the engine', () => {
+ let module: ESEngineModule;
+ let registry: InstanceType<ESEngineModule['Registry']> | undefined;
+ let app: App | undefined;
+
+ beforeAll(async () => { ensureBuiltinComponentsRegistered(); module = await loadWasmModule(); });
+
+ function connect(): void {
+ setDefaultContext(new AppContext());
+ ensureBuiltinComponentsRegistered();
+ resetClassRegistry();
+ declareUiPass();
+ registry = new module.Registry();
+ app = App.new();
+ app.connectCpp(registry as never, module);
+ flushPendingRegistrations(app);
+ setCurrentWorld(app.world);
+ setVisibleSize(960, 640);
+ }
+ afterEach(() => {
+ setCurrentWorld(null);
+ app?.world.disconnectCpp();
+ registry?.delete();
+ app = undefined;
+ registry = undefined;
+ });
+
+ function box(name: string, w: number, h: number, parent?: Node, ax = 0.5, ay = 0.5): Node {
+ const n = new Node(name);
+ app!.world.insert(n._entity, Transform);
+ const t = n.addComponent(UITransform)!;
+ t.setContentSize(w, h);
+ t.setAnchorPoint(ax, ay);
+ parent?.addChild(n);
+ return n;
+ }
+ const frame = async (n = 2): Promise<void> => { for (let i = 0; i < n; i++) await app!.tick(1 / 60); };
+ const widget = (n: Node, set: (w: Widget) => void): Widget => { const w = n.addComponent(Widget)!; set(w); return w; };
+ const size = (n: Node): number[] => { const t = n.getComponent(UITransform)!; return [t.width, t.height]; };
+
+ it('stretches a panel to its parent minus the margins', async () => {
+ connect();
+ const parent = box('parent', 400, 300);
+ const panel = box('panel', 10, 10, parent);
+ widget(panel, (w) => { w.isAlignLeft = w.isAlignRight = w.isAlignTop = w.isAlignBottom = true; w.left = 20; w.right = 40; w.top = 10; w.bottom = 30; });
+ await frame();
+ expect(size(panel)).toEqual([340, 260]);
+ // the parent's space is anchor-relative: its left edge is -200, so the panel spans -180..160 and is centred at -10
+ expect(panel.position.x).toBeCloseTo(-10, 5);
+ expect(panel.position.y).toBeCloseTo(((-150 + 30) + (150 - 10)) / 2, 5);
+ });
+
+ it('pins a node to one edge by its anchor and keeps its size', async () => {
+ connect();
+ const parent = box('parent', 400, 300);
+ const node = box('n', 50, 20, parent, 0, 1); // anchored top-left
+ widget(node, (w) => { w.isAlignRight = true; w.right = 10; w.isAlignTop = true; w.top = 5; });
+ await frame();
+ expect([node.position.x, node.position.y]).toEqual([200 - 10 - 50, 150 - 5]);
+ expect(size(node)).toEqual([50, 20]);
+ });
+
+ it('centres with an offset, in pixels or as a fraction of the parent', async () => {
+ connect();
+ const parent = box('parent', 400, 300);
+ const a = box('a', 50, 50, parent);
+ widget(a, (w) => { w.isAlignHorizontalCenter = true; w.horizontalCenter = 30; w.isAlignVerticalCenter = true; w.verticalCenter = -10; });
+ const b = box('b', 50, 50, parent);
+ widget(b, (w) => { w.isAlignHorizontalCenter = true; w.isAbsHorizontalCenter = false; w.horizontalCenter = 0.25; });
+ await frame();
+ expect([a.position.x, a.position.y]).toEqual([30, -10]);
+ expect(b.position.x).toBe(100);
+ });
+
+ it('aligns a node under no rectangle to the visible area, and follows it when it changes', async () => {
+ connect();
+ const canvas = box('canvas', 1, 1);
+ widget(canvas, (w) => { w.isAlignLeft = w.isAlignRight = w.isAlignTop = w.isAlignBottom = true; });
+ await frame();
+ expect(size(canvas)).toEqual([960, 640]);
+ expect([canvas.position.x, canvas.position.y]).toEqual([480, 320]);
+ setVisibleSize(1280, 720);
+ await frame();
+ expect(size(canvas)).toEqual([1280, 720]);
+ expect(canvas.position.x).toBe(640);
+ });
+
+ it('aligns once and leaves the node to the script after, in ONCE mode; every frame, in ALWAYS mode', async () => {
+ connect();
+ const parent = box('parent', 400, 300);
+ const once = box('once', 50, 50, parent);
+ widget(once, (w) => { w.alignMode = Widget.AlignMode.ONCE; w.isAlignLeft = true; });
+ const always = box('always', 50, 50, parent);
+ widget(always, (w) => { w.alignMode = Widget.AlignMode.ALWAYS; w.isAlignLeft = true; });
+ await frame();
+ once.setPosition(0, 0, 0);
+ always.setPosition(0, 0, 0);
+ await frame();
+ expect(once.position.x).toBe(0);
+ expect(always.position.x).toBe(-175);
+ });
+
+ it('aligns again when a setting changes, whatever the mode', async () => {
+ connect();
+ const parent = box('parent', 400, 300);
+ const node = box('n', 50, 50, parent);
+ const w = widget(node, (x) => { x.alignMode = Widget.AlignMode.ONCE; x.isAlignLeft = true; });
+ await frame();
+ expect(node.position.x).toBe(-175);
+ w.left = 100;
+ await frame();
+ expect(node.position.x).toBe(-75);
+ });
+
+ it('lays children out in a row from the left edge, with padding and spacing', async () => {
+ connect();
+ const row = box('row', 300, 50);
+ const layout = row.addComponent(Layout)!;
+ layout.type = Layout.Type.HORIZONTAL;
+ layout.paddingLeft = 10;
+ layout.spacingX = 5;
+ const kids = [box('a', 40, 20, row), box('b', 60, 20, row), box('c', 20, 20, row)];
+ await frame();
+ // the left edge is -150, plus 10 of padding; the centres follow at +20, +30 after a 5 gap, +10 after another
+ expect(kids.map((k) => k.position.x)).toEqual([-120, -65, -20]);
+ expect(size(row)).toEqual([300, 50]);
+ });
+
+ it('grows the container to fit in CONTAINER mode, and fills it from the top', async () => {
+ connect();
+ const col = box('col', 100, 10);
+ const layout = col.addComponent(Layout)!;
+ layout.type = Layout.Type.VERTICAL;
+ layout.resizeMode = Layout.ResizeMode.CONTAINER;
+ layout.paddingTop = 4;
+ layout.paddingBottom = 6;
+ layout.spacingY = 10;
+ const a = box('a', 30, 40, col), b = box('b', 30, 20, col);
+ await frame();
+ const height = 4 + 6 + 40 + 20 + 10;
+ expect(size(col)[1]).toBe(height);
+ expect(a.position.y).toBe(height / 2 - 4 - 20);
+ expect(b.position.y).toBe(height / 2 - 4 - 40 - 10 - 10);
+ });
+
+ it('stretches the children to share the container in CHILDREN mode', async () => {
+ connect();
+ const row = box('row', 220, 50);
+ const layout = row.addComponent(Layout)!;
+ layout.type = Layout.Type.HORIZONTAL;
+ layout.resizeMode = Layout.ResizeMode.CHILDREN;
+ layout.spacingX = 10;
+ const kids = [box('a', 5, 20, row), box('b', 5, 20, row)];
+ await frame();
+ expect(kids.map((k) => size(k)[0])).toEqual([105, 105]);
+ });
+
+ it('wraps a grid at the container edge, and relayouts when a child is added', async () => {
+ connect();
+ const grid = box('grid', 100, 100);
+ const layout = grid.addComponent(Layout)!;
+ layout.type = Layout.Type.GRID;
+ layout.cellWidth = layout.cellHeight = 40;
+ box('a', 40, 40, grid); box('b', 40, 40, grid); box('c', 40, 40, grid);
+ await frame();
+ const [a, b, c] = grid.children;
+ expect(a!.position.y).toBe(b!.position.y); // two fit on the first row
+ expect(c!.position.y).toBeLessThan(a!.position.y); // the third wrapped below
+ expect(c!.position.x).toBe(a!.position.x);
+ const d = box('d', 40, 40, grid);
+ await frame();
+ expect(d.position.x).toBe(b!.position.x);
+ expect(d.position.y).toBe(c!.position.y);
+ });
+
+ it('lets a widget-stretched container relayout its children in the same frame', async () => {
+ connect();
+ const parent = box('parent', 400, 100);
+ const row = box('row', 10, 100, parent);
+ widget(row, (w) => { w.isAlignLeft = w.isAlignRight = true; });
+ const layout = row.addComponent(Layout)!;
+ layout.type = Layout.Type.HORIZONTAL;
+ layout.resizeMode = Layout.ResizeMode.CHILDREN;
+ const kids = [box('a', 5, 20, row), box('b', 5, 20, row)];
+ await frame(1);
+ expect(kids.map((k) => size(k)[0])).toEqual([200, 200]);
+ });
+});