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
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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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]);+ });+});