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): UI component adapters, touch events on nodes, and Button — Label/Sprite/UIOpacity/UITransform as views on the engine's components, the topmost listener claiming a touch and bubbling it up, clicks that end inside

yhhfd25b4537e27
diff --git a/sdk/src/cocos/builtinScripts.ts b/sdk/src/cocos/builtinScripts.ts
new file mode 100644
index 000000000..c35825153
--- /dev/null
+++ b/sdk/src/cocos/builtinScripts.ts
@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file cocos/builtinScripts.ts
+ * @brief The parts of the layer that are scripts and systems rather than views: `Button`, and the touch system.
+ *
+ * A script class and a system are declared into the engine's current context, and a context is what a running app owns — so these
+ * are declared once for the one a game runs in, which importing the layer does. A test that replaces the context has to declare them
+ * again, and does so here; asking twice for the same context is harmless.
+ */
+import { getDefaultContext } from '../ecs/context';
+import { declareButton } from './ui/button';
+import { declareInputSystem } from './input';
+import { resetClassRegistry } from './registry';
+
+const declared = new WeakSet<object>();
+
+/** Declare the layer's own classes and systems into the current context, once per context. */
+export function declareBuiltinScripts(): void {
+ const context = getDefaultContext();
+ if (declared.has(context)) return;
+ declared.add(context);
+ declareButton();
+ declareInputSystem();
+}
+
+/** Test seam: forget the registry and declare again into the (possibly new) current context. */
+export function redeclareBuiltinScripts(): void {
+ resetClassRegistry();
+ declareBuiltinScripts();
+}
diff --git a/sdk/src/cocos/component.ts b/sdk/src/cocos/component.ts
index 6effe0320..bb9212954 100644
--- a/sdk/src/cocos/component.ts
+++ b/sdk/src/cocos/component.ts
@@ -32,8 +32,13 @@ interface Timer {
export class Component {
/** The node this component is on. Set before `onLoad`. */
node!: Node;
- /** Whether the component takes part: a disabled one gets no `update`, and `onDisable` has run. */
- enabled = true;
+ private enabled_ = true;
+ /**
+ * Whether the component takes part: a disabled one gets no `update`, and `onDisable` has run. An accessor, so the built-in views
+ * (`Label`, `Sprite`) can answer it from the engine component they stand for.
+ */
+ get enabled(): boolean { return this.enabled_; }
+ set enabled(value: boolean) { this.enabled_ = value; }
/** @internal */ _world!: World;
/** @internal */ _entity!: Entity;
diff --git a/sdk/src/cocos/index.ts b/sdk/src/cocos/index.ts
index 3412d1309..144897585 100644
--- a/sdk/src/cocos/index.ts
+++ b/sdk/src/cocos/index.ts
@@ -12,6 +12,9 @@
export { Vec2, Vec3, Quat, Color, Size, Rect, v2, v3, color, size, rect, math, toRadian, toDegree, clamp, clamp01, lerp } from './math';
export { Component } from './component';
export { Node, setCurrentWorld, getCurrentWorld } from './node';
+import { Node as NodeClass } from './node';
+/** The event names, under the name scripts import them by. */
+export const NodeEventType = NodeClass.EventType;
export {
_decorator, ccclass, property, requireComponent, executionOrder, menu, help, icon, inspector, playOnFocus, executeInEditMode,
disallowMultiple, type, integer, float, string, boolean, CCInteger, CCFloat, CCString, CCBoolean, Enum,
@@ -22,4 +25,11 @@ 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 { Touch, EventTouch, pumpTouches } from './input';
+export { declareBuiltinScripts, redeclareBuiltinScripts } from './builtinScripts';
export { classInfoNamed, classInfoOf, allClassInfos, COMPONENT_PREFIX, resetClassRegistry } from './registry';
+
+import { declareBuiltinScripts as declare } from './builtinScripts';
+// Declared once, into the context a game runs in, when the layer is imported.
+declare();
diff --git a/sdk/src/cocos/input.ts b/sdk/src/cocos/input.ts
new file mode 100644
index 000000000..ed30782b9
--- /dev/null
+++ b/sdk/src/cocos/input.ts
@@ -0,0 +1,202 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file cocos/input.ts
+ * @brief Touch events on nodes: `Node.on(TOUCH_START, ...)`, `EventTouch`, and the system that raises them.
+ *
+ * The engine already turns the mouse and fingers into one list of pointers each frame (`uiPointersOf`) and knows the camera that
+ * maps a screen point to the world. What Cocos adds is who gets told: a touch is claimed at its start by the TOPMOST node that
+ * listens for touches and whose rectangle holds the point, the rest of the gesture (move, end, cancel) goes to that same node
+ * wherever the finger has gone, and the event then bubbles up through the node's ancestors, each of which hears it without being
+ * hit-tested, until one stops it.
+ *
+ * A touch's location is a world point. In an imported scene the engine's world and Cocos's are the same space (the canvas sits where
+ * it sat, the camera is where it was), so a script's `getUILocation()` and `convertToNodeSpaceAR` mean what they meant.
+ */
+import { Schedule, defineSystem, addSystemToSchedule, GetWorld } from '../ecs/system';
+import { Res } from '../ecs/resource';
+import { Input, type InputState } from '../input/input';
+import { uiPointersOf } from '../ui/input/pointerBook';
+import { UICameraInfo, type UICameraData } from '../ui/core/ui-camera-info';
+import { screenToUiWorld } from '../ui/util/ui-pick';
+import { platformDevicePixelRatio } from '../platform';
+import type { World } from '../ecs/world';
+import type { Entity } from '../types';
+import { Children, Parent } from '../ecs/component';
+import { Vec2 } from './math';
+import { Node, touchListeningEntities } from './node';
+import { UITransform } from './ui/uiTransform';
+import { log } from '../util/logger';
+
+/** One finger (or the mouse button) as a script sees it. */
+export class Touch {
+ constructor(
+ public readonly id: number,
+ private x_: number,
+ private y_: number,
+ private readonly startX_: number = x_,
+ private readonly startY_: number = y_,
+ private prevX_: number = x_,
+ private prevY_: number = y_,
+ ) {}
+
+ /** @internal */
+ _move(x: number, y: number): void { this.prevX_ = this.x_; this.prevY_ = this.y_; this.x_ = x; this.y_ = y; }
+
+ getID(): number { return this.id; }
+ getLocation(out: Vec2 = new Vec2()): Vec2 { return out.set(this.x_, this.y_); }
+ getLocationX(): number { return this.x_; }
+ getLocationY(): number { return this.y_; }
+ /** The canvas-space point: in an imported scene the same space as the world, see the file comment. */
+ getUILocation(out: Vec2 = new Vec2()): Vec2 { return out.set(this.x_, this.y_); }
+ getUILocationX(): number { return this.x_; }
+ getUILocationY(): number { return this.y_; }
+ getStartLocation(out: Vec2 = new Vec2()): Vec2 { return out.set(this.startX_, this.startY_); }
+ getPreviousLocation(out: Vec2 = new Vec2()): Vec2 { return out.set(this.prevX_, this.prevY_); }
+ getDelta(out: Vec2 = new Vec2()): Vec2 { return out.set(this.x_ - this.prevX_, this.y_ - this.prevY_); }
+}
+
+/** The event a touch listener receives. */
+export class EventTouch {
+ /** Always bubbles, as in Cocos. */
+ readonly bubbles = true;
+ target: Node | null = null;
+ currentTarget: Node | null = null;
+ private stopped_ = false;
+
+ constructor(public readonly type: string, public readonly touch: Touch, private readonly all_: Touch[]) {}
+
+ get propagationStopped(): boolean { return this.stopped_; }
+ stopPropagation(): void { this.stopped_ = true; }
+ stopPropagationImmediate(): void { this.stopped_ = true; }
+ getTouches(): Touch[] { return this.all_; }
+
+ getID(): number { return this.touch.id; }
+ getLocation(out?: Vec2): Vec2 { return this.touch.getLocation(out); }
+ getLocationX(): number { return this.touch.getLocationX(); }
+ getLocationY(): number { return this.touch.getLocationY(); }
+ getUILocation(out?: Vec2): Vec2 { return this.touch.getUILocation(out); }
+ getUILocationX(): number { return this.touch.getUILocationX(); }
+ getUILocationY(): number { return this.touch.getUILocationY(); }
+ getStartLocation(out?: Vec2): Vec2 { return this.touch.getStartLocation(out); }
+ getPreviousLocation(out?: Vec2): Vec2 { return this.touch.getPreviousLocation(out); }
+ getDelta(out?: Vec2): Vec2 { return this.touch.getDelta(out); }
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Which node is on top.
+// ---------------------------------------------------------------------------------------------------------------------
+
+/** Where a node stands in draw order, as the sibling indices from the root: a later sibling, or a descendant, is above. */
+function orderKey(world: World, entity: Entity): number[] {
+ const path: number[] = [];
+ let current: Entity = entity;
+ for (;;) {
+ const parent: Entity | undefined = world.tryGet(current, Parent)?.entity;
+ if (!parent) { path.push(Number(current)); break; }
+ path.push(world.tryGet(parent, Children)?.entities.indexOf(current) ?? 0);
+ current = parent;
+ }
+ return path.reverse();
+}
+
+/** Higher draw order first. */
+function compareTopmost(a: number[], b: number[]): number {
+ const n = Math.min(a.length, b.length);
+ for (let i = 0; i < n; i++) if (a[i] !== b[i]) return b[i]! - a[i]!;
+ return b.length - a.length; // a descendant is above its ancestor
+}
+
+const TOUCH_TYPES = [Node.EventType.TOUCH_START, Node.EventType.TOUCH_MOVE, Node.EventType.TOUCH_END, Node.EventType.TOUCH_CANCEL];
+
+function listensForTouch(node: Node): boolean {
+ for (const t of TOUCH_TYPES) if (node.hasEventListener(t)) return true;
+ return false;
+}
+
+/** The topmost active node that listens for touches and holds @p point, or null. */
+function hitNode(world: World, point: Vec2): Node | null {
+ const hits: Array<{ node: Node; key: number[] }> = [];
+ for (const entity of touchListeningEntities(world)) {
+ if (!world.valid(entity)) continue;
+ const node = Node.for(world, entity);
+ if (!listensForTouch(node) || !node.activeInHierarchy) continue;
+ const transform = node.getComponent(UITransform);
+ if (!transform || !transform.isHit(point)) continue;
+ hits.push({ node, key: orderKey(world, entity) });
+ }
+ if (hits.length === 0) return null;
+ hits.sort((a, b) => compareTopmost(a.key, b.key));
+ return hits[0]!.node;
+}
+
+/** Hand an event to a node and its ancestors, nearest first, until one stops it. */
+function dispatch(event: EventTouch, from: Node): void {
+ event.target = from;
+ for (let node: Node | null = from; node && !event.propagationStopped; node = node.parent) {
+ event.currentTarget = node;
+ if (!node.hasEventListener(event.type)) continue;
+ try {
+ node.emit(event.type, event);
+ } catch (err) {
+ log.error('cocos', `${node.name} ${event.type} listener threw`, err);
+ }
+ }
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// The per-frame system.
+// ---------------------------------------------------------------------------------------------------------------------
+
+interface Gesture { touch: Touch; target: Node | null }
+const gestures = new WeakMap<World, Map<number, Gesture>>();
+
+function gesturesOf(world: World): Map<number, Gesture> {
+ let g = gestures.get(world);
+ if (!g) gestures.set(world, (g = new Map()));
+ return g;
+}
+
+/** Turn this frame's pointers into TOUCH_START / MOVE / END events. Exported so a test (or a host with its own loop) can drive it. */
+export function pumpTouches(world: World, input: InputState, camera: UICameraData): void {
+ const book = gesturesOf(world);
+ const dpr = platformDevicePixelRatio();
+ const surfaceH = camera.screenH;
+ const pointers = uiPointersOf(input);
+ const live = [...book.values()].map((g) => g.touch);
+
+ for (const p of pointers) {
+ const at = camera.valid ? screenToUiWorld(camera, p.x * dpr, surfaceH - p.y * dpr) : { x: 0, y: 0 };
+ let gesture = book.get(p.id);
+
+ if (p.pressed && !gesture) {
+ const touch = new Touch(p.id, at.x, at.y);
+ gesture = { touch, target: hitNode(world, new Vec2(at.x, at.y)) };
+ book.set(p.id, gesture);
+ live.push(touch);
+ if (gesture.target) dispatch(new EventTouch(Node.EventType.TOUCH_START, touch, live), gesture.target);
+ }
+ if (!gesture) continue;
+
+ if (p.down && (at.x !== gesture.touch.getLocationX() || at.y !== gesture.touch.getLocationY())) {
+ gesture.touch._move(at.x, at.y);
+ if (gesture.target) dispatch(new EventTouch(Node.EventType.TOUCH_MOVE, gesture.touch, live), gesture.target);
+ }
+ if (p.released) {
+ gesture.touch._move(at.x, at.y);
+ const type = p.cancelled ? Node.EventType.TOUCH_CANCEL : Node.EventType.TOUCH_END;
+ if (gesture.target) dispatch(new EventTouch(type, gesture.touch, live), gesture.target);
+ book.delete(p.id);
+ }
+ }
+}
+
+/** Register the touch system with the engine's frame loop. Idempotent per context is the caller's business: see `declareBuiltinScripts`. */
+export function declareInputSystem(): void {
+ const system = defineSystem(
+ [Res(Input), Res(UICameraInfo), GetWorld()],
+ (input, camera, world) => { pumpTouches(world, input, camera); },
+ { name: 'Cocos:Input', touches: { opaque: true } },
+ );
+ addSystemToSchedule(Schedule.PreUpdate, system);
+}
diff --git a/sdk/src/cocos/node.ts b/sdk/src/cocos/node.ts
index 0145ef0d4..02d5e66db 100644
--- a/sdk/src/cocos/node.ts
+++ b/sdk/src/cocos/node.ts
@@ -32,6 +32,12 @@ export function getCurrentWorld(): World | null { return currentWorld; }
const cache = new WeakMap<World, Map<Entity, Node>>();
+/** The entities that have registered a touch listener: the only ones a touch has to be tested against. */
+const touchListeners = new WeakMap<World, Set<Entity>>();
+export function touchListeningEntities(world: World): Iterable<Entity> {
+ return touchListeners.get(world) ?? [];
+}
+
type Listener = { callback: (...args: any[]) => void; target?: unknown; once: boolean };
export class Node {
@@ -323,6 +329,11 @@ export class Node {
dispatchEvent(event: { type: string }): void { this.emit(event.type, event); }
private addListener_(type: string, listener: Listener): void {
+ if (type.startsWith('touch-')) {
+ let set = touchListeners.get(this._world);
+ if (!set) touchListeners.set(this._world, (set = new Set()));
+ set.add(this._entity);
+ }
if (!this.listeners_) this.listeners_ = new Map();
const list = this.listeners_.get(type);
if (list) list.push(listener); else this.listeners_.set(type, [listener]);
diff --git a/sdk/src/cocos/ui/button.ts b/sdk/src/cocos/ui/button.ts
new file mode 100644
index 000000000..0619ebb37
--- /dev/null
+++ b/sdk/src/cocos/ui/button.ts
@@ -0,0 +1,167 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file cocos/ui/button.ts
+ * @brief `Button` and `EventHandler`.
+ *
+ * Unlike `Label` or `Sprite`, a button is behaviour: it listens for the touches on its node and, when one ends inside, says "click"
+ * — to the handlers authored in the editor (`clickEvents`) and to whoever did `node.on(Button.EventType.CLICK, ...)`. So it is a
+ * real script class, declared through the same path as a game's (host.ts), with its settings as stored data.
+ *
+ * The one thing an editor-authored handler holds that the engine's data model cannot carry is a node reference inside a list of
+ * records. The records are therefore stored as two parallel lists — the targets, which are entity references the scene loader
+ * remaps, and the rest of each handler — and joined here when the button loads.
+ */
+import { Component } from '../component';
+import { Color } from '../math';
+import { Node } from '../node';
+import { declareClass } from '../host';
+import { classInfoNamed } from '../registry';
+import { Sprite } from './sprite';
+import { UITransform } from './uiTransform';
+import type { EventTouch } from '../input';
+
+/** An editor-authored callback: call `handler` on the `component` of `target`, with the event and `customEventData`. */
+export class EventHandler {
+ target: Node | null = null;
+ /** The class name of the component on `target`. */
+ component = '';
+ handler = '';
+ customEventData = '';
+
+ emit(args: unknown[] = []): void {
+ const target = this.target;
+ if (!target || !target.isValid || !this.handler) return;
+ const comp = this.component ? target.getComponent(this.component) : null;
+ const fn = (comp as unknown as Record<string, unknown> | null)?.[this.handler];
+ if (typeof fn === 'function') fn.apply(comp, [...args, this.customEventData]);
+ }
+
+ static emitEvents(handlers: EventHandler[], ...args: unknown[]): void {
+ for (const h of handlers) h.emit(args);
+ }
+}
+
+const Transition = Object.freeze({ NONE: 0, COLOR: 1, SPRITE: 2, SCALE: 3 });
+const EventType = Object.freeze({ CLICK: 'click' });
+
+export class Button extends Component {
+ static readonly Transition = Transition;
+ static readonly EventType = EventType;
+
+ interactable = true;
+ transition: number = Transition.NONE;
+ zoomScale = 1.2;
+ duration = 0.1;
+ normalColor = new Color(255, 255, 255, 255);
+ hoverColor = new Color(211, 211, 211, 255);
+ pressedColor = new Color(255, 255, 255, 255);
+ disabledColor = new Color(124, 124, 124, 255);
+ /** The node the transition acts on; this node when none is set. */
+ target: Node | null = null;
+ clickTargets: Array<Node | null> = [];
+ clickHandlers: Array<{ component: string; handler: string; customEventData: string }> = [];
+ clickEvents: EventHandler[] = [];
+
+ private pressed_ = false;
+ private restScale_: { x: number; y: number; z: number } | null = null;
+
+ onLoad(): void {
+ if (this.clickEvents.length === 0) {
+ this.clickEvents = this.clickHandlers.map((h, i) => {
+ const e = new EventHandler();
+ e.target = this.clickTargets[i] ?? null;
+ e.component = h.component;
+ e.handler = h.handler;
+ e.customEventData = h.customEventData;
+ return e;
+ });
+ }
+ }
+
+ onEnable(): void {
+ this.node.on(Node.EventType.TOUCH_START, this.onTouchStart, this);
+ this.node.on(Node.EventType.TOUCH_END, this.onTouchEnd, this);
+ this.node.on(Node.EventType.TOUCH_CANCEL, this.onTouchCancel, this);
+ this.applyTransition_();
+ }
+
+ onDisable(): void {
+ this.node.off(Node.EventType.TOUCH_START, this.onTouchStart, this);
+ this.node.off(Node.EventType.TOUCH_END, this.onTouchEnd, this);
+ this.node.off(Node.EventType.TOUCH_CANCEL, this.onTouchCancel, this);
+ this.pressed_ = false;
+ this.restore_();
+ }
+
+ private onTouchStart(event: EventTouch): void {
+ if (!this.interactable || !this.enabledInHierarchy) return;
+ this.pressed_ = true;
+ this.applyTransition_();
+ event.stopPropagation();
+ }
+
+ private onTouchEnd(event: EventTouch): void {
+ if (!this.pressed_) return;
+ this.pressed_ = false;
+ this.applyTransition_();
+ const inside = this.node.getComponent(UITransform)?.isHit(event.getLocation()) ?? true;
+ if (this.interactable && this.enabledInHierarchy && inside) {
+ EventHandler.emitEvents(this.clickEvents, event);
+ this.node.emit(EventType.CLICK, this);
+ }
+ event.stopPropagation();
+ }
+
+ private onTouchCancel(): void {
+ this.pressed_ = false;
+ this.applyTransition_();
+ }
+
+ /** The node the transition acts on. */
+ private transitionTarget_(): Node { return this.target ?? this.node; }
+
+ private restore_(): void {
+ if (this.restScale_) {
+ const s = this.restScale_;
+ this.transitionTarget_().setScale(s.x, s.y, s.z);
+ this.restScale_ = null;
+ }
+ }
+
+ /** Instant: the press is shown or not. Cocos eases these over `duration`; a transition that lasts a tenth of a second is not what a script reads. */
+ private applyTransition_(): void {
+ const node = this.transitionTarget_();
+ if (this.transition === Transition.SCALE) {
+ if (this.pressed_) {
+ if (!this.restScale_) { const s = node.scale; this.restScale_ = { x: s.x, y: s.y, z: s.z }; }
+ const r = this.restScale_;
+ node.setScale(r.x * this.zoomScale, r.y * this.zoomScale, r.z);
+ } else {
+ this.restore_();
+ }
+ } else if (this.transition === Transition.COLOR) {
+ const sprite = node.getComponent(Sprite);
+ if (sprite) sprite.color = !this.interactable ? this.disabledColor : this.pressed_ ? this.pressedColor : this.normalColor;
+ }
+ }
+}
+
+/** Declare the button's component, so a scene that holds one finds it. */
+export function declareButton(): void {
+ declareClass(Button as never, 'Button', [
+ { name: 'interactable', kind: 'boolean' },
+ { name: 'transition', kind: 'number' },
+ { name: 'zoomScale', kind: 'number' },
+ { name: 'duration', kind: 'number' },
+ { name: 'normalColor', kind: 'color' },
+ { name: 'hoverColor', kind: 'color' },
+ { name: 'pressedColor', kind: 'color' },
+ { name: 'disabledColor', kind: 'color' },
+ { name: 'target', kind: 'node' },
+ { name: 'clickTargets', kind: 'node', array: true },
+ { name: 'clickHandlers', kind: 'json' },
+ ]);
+}
+
+export const isButtonDeclared = (): boolean => classInfoNamed('Button') !== undefined;
diff --git a/sdk/src/cocos/ui/index.ts b/sdk/src/cocos/ui/index.ts
new file mode 100644
index 000000000..eb4b74e15
--- /dev/null
+++ b/sdk/src/cocos/ui/index.ts
@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file cocos/ui/index.ts
+ * @brief Cocos's built-in UI components, as views on the engine's. Importing this registers their adapters.
+ */
+export { UITransform, uiTransformDef, ensureUITransform } from './uiTransform';
+export { Label, LabelOutline, LabelShadow } from './label';
+export { Sprite, UIOpacity } from './sprite';
+export { Button, EventHandler, declareButton } from './button';
diff --git a/sdk/src/cocos/ui/label.ts b/sdk/src/cocos/ui/label.ts
new file mode 100644
index 000000000..85dc07c11
--- /dev/null
+++ b/sdk/src/cocos/ui/label.ts
@@ -0,0 +1,120 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file cocos/ui/label.ts
+ * @brief `Label`, `LabelOutline` and `LabelShadow`: views on the engine's `Text`.
+ *
+ * Every field a script sets maps to a `Text` field, converted at the boundary: colours between Cocos's 0..255 and the engine's
+ * 0..1, line height between pixels and a ratio of the font size, and the three enums, whose numbers agree for alignment and differ
+ * for overflow (Cocos's `SHRINK` is 2, the engine's is 3). Nothing is held here: a `Label` is the `Text` on its node.
+ */
+import { Text, TextOverflow, type TextData } from '../../ui/core/text';
+import type { World } from '../../ecs/world';
+import type { Entity } from '../../types';
+import { Color } from '../math';
+import { Component } from '../component';
+import { registerBuiltinComponent } from '../builtins';
+import { toCocosColor, toEngineColor, viewAdapter } from './view';
+
+/** Cocos's `Label.Overflow`: NONE, CLAMP, SHRINK, RESIZE_HEIGHT. */
+const Overflow = Object.freeze({ NONE: 0, CLAMP: 1, SHRINK: 2, RESIZE_HEIGHT: 3 });
+const HorizontalAlign = Object.freeze({ LEFT: 0, CENTER: 1, RIGHT: 2 });
+const VerticalAlign = Object.freeze({ TOP: 0, CENTER: 1, BOTTOM: 2 });
+const CacheMode = Object.freeze({ NONE: 0, BITMAP: 1, CHAR: 2 });
+
+function toEngineOverflow(cocos: number): number {
+ if (cocos === Overflow.CLAMP) return TextOverflow.Clip;
+ if (cocos === Overflow.SHRINK) return TextOverflow.Shrink;
+ return TextOverflow.Visible; // NONE, and RESIZE_HEIGHT, which the engine has no equivalent of
+}
+
+function toCocosOverflow(engine: number): number {
+ if (engine === TextOverflow.Clip || engine === TextOverflow.Ellipsis) return Overflow.CLAMP;
+ if (engine === TextOverflow.Shrink) return Overflow.SHRINK;
+ return Overflow.NONE;
+}
+
+/** The `Text` data of an entity: the thing every property below reads and writes. */
+class TextView extends Component {
+ protected text_(): TextData { return this._world.get(this._entity, Text); }
+ protected patch_(patch: Partial<TextData>): void { this._world.set(this._entity, Text, { ...this.text_(), ...patch }); }
+}
+
+export class Label extends TextView {
+ static readonly Overflow = Overflow;
+ static readonly HorizontalAlign = HorizontalAlign;
+ static readonly VerticalAlign = VerticalAlign;
+ static readonly CacheMode = CacheMode;
+
+ /** The text shown. A script writes `label.string = ...` more than anything else it does. */
+ get string(): string { return this.text_().content; }
+ set string(v: string) { this.patch_({ content: v === undefined || v === null ? '' : String(v) }); }
+
+ get color(): Color { return toCocosColor(this.text_().color); }
+ set color(v: Color) { this.patch_({ color: toEngineColor(v) }); }
+
+ get fontSize(): number { return this.text_().fontSize; }
+ set fontSize(v: number) {
+ // Cocos keeps lineHeight in pixels, the engine as a ratio of the size: keep the pixel value across a size change.
+ const t = this.text_();
+ const px = t.lineHeight * t.fontSize;
+ this.patch_({ fontSize: v, lineHeight: v > 0 ? px / v : t.lineHeight });
+ }
+ get actualFontSize(): number { return this.text_().fontSize; }
+
+ get lineHeight(): number { const t = this.text_(); return t.lineHeight * t.fontSize; }
+ set lineHeight(px: number) { const t = this.text_(); this.patch_({ lineHeight: t.fontSize > 0 ? px / t.fontSize : t.lineHeight }); }
+
+ get horizontalAlign(): number { return this.text_().align; }
+ set horizontalAlign(v: number) { this.patch_({ align: v as TextData['align'] }); }
+ get verticalAlign(): number { return this.text_().verticalAlign; }
+ set verticalAlign(v: number) { this.patch_({ verticalAlign: v as TextData['verticalAlign'] }); }
+
+ get overflow(): number { return toCocosOverflow(this.text_().overflow); }
+ set overflow(v: number) { this.patch_({ overflow: toEngineOverflow(v) as TextData['overflow'] }); }
+
+ get enableWrapText(): boolean { return this.text_().wordWrap; }
+ set enableWrapText(v: boolean) { this.patch_({ wordWrap: v }); }
+
+ get isBold(): boolean { return this.text_().bold; }
+ set isBold(v: boolean) { this.patch_({ bold: v }); }
+ get isItalic(): boolean { return this.text_().italic; }
+ set isItalic(v: boolean) { this.patch_({ italic: v }); }
+
+ get fontFamily(): string { return this.text_().fontFamily; }
+ set fontFamily(v: string) { this.patch_({ fontFamily: v }); }
+ /** Whether a font file is not in use. Reading only: which font is drawn is `Text.font`. */
+ get useSystemFont(): boolean { return !this.text_().font; }
+ set useSystemFont(_v: boolean) {}
+
+ /** The measured size of the text is the engine's layout to know; a no-op here, as a script calls it to force a refresh. */
+ updateRenderData(_force = false): void {}
+
+ get enabled(): boolean { return this.text_().enabled; }
+ set enabled(v: boolean) { this.patch_({ enabled: v }); }
+}
+
+export class LabelOutline extends TextView {
+ get color(): Color { return toCocosColor(this.text_().strokeColor); }
+ set color(v: Color) { this.patch_({ strokeColor: toEngineColor(v) }); }
+ get width(): number { return this.text_().strokeWidth; }
+ set width(v: number) { this.patch_({ strokeWidth: v }); }
+}
+
+export class LabelShadow extends TextView {
+ get color(): Color { return toCocosColor(this.text_().shadowColor); }
+ set color(v: Color) { this.patch_({ shadowColor: toEngineColor(v) }); }
+ get offset(): { x: number; y: number } { const t = this.text_(); return { x: t.shadowOffsetX, y: -t.shadowOffsetY }; }
+ set offset(v: { x: number; y: number }) { this.patch_({ shadowOffsetX: v.x, shadowOffsetY: -v.y }); }
+ get blur(): number { return this.text_().shadowBlur; }
+ set blur(v: number) { this.patch_({ shadowBlur: v }); }
+}
+
+const hasText = (world: World, entity: Entity): boolean => world.has(entity, Text);
+const addText = (world: World, entity: Entity): void => { world.insert(entity, Text, {}); };
+
+registerBuiltinComponent(Label, ['cc.Label', 'Label'], viewAdapter(Label, hasText, addText));
+// Outline and shadow are properties of the same Text: present when it has any, and adding one does not give it a visible effect until
+// the script sets a width or an offset.
+registerBuiltinComponent(LabelOutline, ['cc.LabelOutline', 'LabelOutline'], viewAdapter(LabelOutline, hasText, addText));
+registerBuiltinComponent(LabelShadow, ['cc.LabelShadow', 'LabelShadow'], viewAdapter(LabelShadow, hasText, addText));
diff --git a/sdk/src/cocos/ui/sprite.ts b/sdk/src/cocos/ui/sprite.ts
new file mode 100644
index 000000000..b3077e0b0
--- /dev/null
+++ b/sdk/src/cocos/ui/sprite.ts
@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file cocos/ui/sprite.ts
+ * @brief `Sprite` and `UIOpacity`: views on the engine's `Sprite`.
+ *
+ * Colour, the draw type and the enable flag map directly. The frame (`spriteFrame`) is a texture, which the engine addresses by a
+ * handle that an asset load produces; assigning one is the asset layer's job, so here the frame is the path the `Sprite` was made
+ * with and assigning a path is carried to the engine's `texture` only where the project's assets have already loaded it.
+ */
+import { Sprite as EngineSprite } from '../../ecs/component';
+import { SpriteDrawMode } from '../../wasm/wasm.generated';
+import type { World } from '../../ecs/world';
+import type { Entity } from '../../types';
+import { Color } from '../math';
+import { Component } from '../component';
+import { registerBuiltinComponent } from '../builtins';
+import { toCocosColor, toEngineColor, viewAdapter } from './view';
+
+/** Cocos's `Sprite.Type`: SIMPLE, SLICED, TILED, FILLED. */
+const SpriteType = Object.freeze({ SIMPLE: 0, SLICED: 1, TILED: 2, FILLED: 3 });
+const SizeMode = Object.freeze({ CUSTOM: 0, TRIMMED: 1, RAW: 2 });
+
+function toEngineDrawMode(type: number): SpriteDrawMode {
+ if (type === SpriteType.SLICED) return SpriteDrawMode.NineSlice;
+ if (type === SpriteType.TILED) return SpriteDrawMode.Tiled;
+ return SpriteDrawMode.Simple; // SIMPLE, and FILLED, which the engine draws whole
+}
+
+function toCocosType(mode: SpriteDrawMode | undefined): number {
+ if (mode === SpriteDrawMode.NineSlice) return SpriteType.SLICED;
+ if (mode === SpriteDrawMode.Tiled) return SpriteType.TILED;
+ return SpriteType.SIMPLE;
+}
+
+export class Sprite extends Component {
+ static readonly Type = SpriteType;
+ static readonly SizeMode = SizeMode;
+
+ private data_() { return this._world.get(this._entity, EngineSprite); }
+ private patch_(patch: Partial<ReturnType<Sprite['data_']>>): void { this._world.set(this._entity, EngineSprite, { ...this.data_(), ...patch }); }
+
+ get color(): Color { return toCocosColor(this.data_().color); }
+ set color(v: Color) { this.patch_({ color: toEngineColor(v) }); }
+
+ get type(): number { return toCocosType(this.data_().drawMode); }
+ set type(v: number) { this.patch_({ drawMode: toEngineDrawMode(v) }); }
+
+ /** The frame is set by the asset layer; the engine draws whatever texture the sprite holds. */
+ sizeMode = SizeMode.CUSTOM;
+ /** Not carried: the engine has no grayscale draw for a sprite. */
+ grayscale = false;
+ fillType = 0;
+ fillRange = 0;
+
+ get enabled(): boolean { return this.data_().enabled; }
+ set enabled(v: boolean) { this.patch_({ enabled: v }); }
+}
+
+/**
+ * `UIOpacity`: the alpha of a node and everything under it. The engine has no subtree alpha for world content, so this fades the
+ * node's own renderer — a `Sprite`'s colour alpha — and not its children. A script that fades a panel by its `UIOpacity` will see the
+ * panel's own art fade and its children stay; that is a difference from Cocos, and one the engine would have to grow a feature to close.
+ */
+export class UIOpacity extends Component {
+ private opacity_ = 255;
+ /** The sprite's own alpha before any fade, taken the first time one is applied so repeated writes do not compound. */
+ private baseAlpha_: number | null = null;
+
+ get opacity(): number { return this.opacity_; }
+ set opacity(v: number) {
+ this.opacity_ = Math.min(255, Math.max(0, v));
+ if (!this._world.has(this._entity, EngineSprite)) return;
+ const s = this._world.get(this._entity, EngineSprite);
+ if (this.baseAlpha_ === null) this.baseAlpha_ = s.color.a;
+ this._world.set(this._entity, EngineSprite, { ...s, color: { ...s.color, a: this.baseAlpha_ * (this.opacity_ / 255) } });
+ }
+}
+
+const hasSprite = (world: World, entity: Entity): boolean => world.has(entity, EngineSprite);
+const addSprite = (world: World, entity: Entity): void => { world.insert(entity, EngineSprite, {}); };
+
+registerBuiltinComponent(Sprite, ['cc.Sprite', 'Sprite'], viewAdapter(Sprite, hasSprite, addSprite));
+registerBuiltinComponent(UIOpacity, ['cc.UIOpacity', 'UIOpacity'], viewAdapter(UIOpacity, () => true, () => {}));
diff --git a/sdk/src/cocos/ui/uiTransform.ts b/sdk/src/cocos/ui/uiTransform.ts
new file mode 100644
index 000000000..71c9fcd42
--- /dev/null
+++ b/sdk/src/cocos/ui/uiTransform.ts
@@ -0,0 +1,158 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file cocos/ui/uiTransform.ts
+ * @brief `UITransform`: a node's content size and anchor point.
+ *
+ * In Cocos the rectangle belongs to the node and the renderers draw into it. The engine has the opposite arrangement — a `Sprite`
+ * has its own size and pivot, a `Text` its own box — and nothing for a node that draws nothing but still has an extent (a button's
+ * hit area, a layout container, a scroll view's viewport). So the extent is kept in a small data component of the compatibility layer,
+ * `Cocos.UITransform`, which is the one place a script's `contentSize` lives, and a write to it is carried through to the `Sprite` and
+ * `Text` on the same node so they draw into the rectangle the script set.
+ *
+ * Importing a scene writes this component for every node that had a `UITransform`, so it starts out as authored; a node that never
+ * had one gets it when a script first asks, filled in from the renderer it has.
+ */
+import { defineComponent } from '../../ecs/component';
+import { Sprite, Transform } from '../../ecs/component';
+import { Text } from '../../ui/core/text';
+import type { World } from '../../ecs/world';
+import type { Entity } from '../../types';
+import { Rect, Size, Vec2, Vec3 } from '../math';
+import { Component } from '../component';
+import { registerBuiltinComponent } from '../builtins';
+import { viewAdapter } from './view';
+
+export interface UITransformData {
+ width: number;
+ height: number;
+ anchorX: number;
+ anchorY: number;
+}
+
+/** The data component, defined per context so a fresh `AppContext` still finds it. */
+export function uiTransformDef() {
+ return defineComponent<UITransformData>('Cocos.UITransform', { width: 100, height: 100, anchorX: 0.5, anchorY: 0.5 });
+}
+
+/** The rectangle a node's renderers say it has, for a node that was never given one. */
+function derive(world: World, entity: Entity): UITransformData {
+ const sprite = world.has(entity, Sprite) ? world.get(entity, Sprite) : null;
+ if (sprite) return { width: sprite.size.x, height: sprite.size.y, anchorX: sprite.pivot.x, anchorY: sprite.pivot.y };
+ const text = world.has(entity, Text) ? world.get(entity, Text) : null;
+ if (text && (text.boxWidth > 0 || text.boxHeight > 0)) {
+ return { width: text.boxWidth, height: text.boxHeight, anchorX: text.boxPivot.x, anchorY: text.boxPivot.y };
+ }
+ return { width: 100, height: 100, anchorX: 0.5, anchorY: 0.5 };
+}
+
+/** The rectangle data of a node, made if it has none. */
+export function ensureUITransform(world: World, entity: Entity): UITransformData {
+ const def = uiTransformDef();
+ if (!world.has(entity, def)) world.insert(entity, def, derive(world, entity));
+ return world.get(entity, def);
+}
+
+/** Carry a rectangle to the renderers on the same node, which draw it. */
+function propagate(world: World, entity: Entity, rect: UITransformData): void {
+ if (world.has(entity, Sprite)) {
+ const s = world.get(entity, Sprite);
+ world.set(entity, Sprite, { ...s, size: { x: rect.width, y: rect.height }, pivot: { x: rect.anchorX, y: rect.anchorY } });
+ }
+ if (world.has(entity, Text)) {
+ const t = world.get(entity, Text);
+ world.set(entity, Text, { ...t, boxWidth: rect.width, boxHeight: rect.height, boxPivot: { x: rect.anchorX, y: rect.anchorY } });
+ }
+}
+
+export class UITransform extends Component {
+ private read_(): UITransformData { return ensureUITransform(this._world, this._entity); }
+ private write_(patch: Partial<UITransformData>): void {
+ const next = { ...this.read_(), ...patch };
+ this._world.set(this._entity, uiTransformDef(), next);
+ propagate(this._world, this._entity, next);
+ }
+
+ get contentSize(): Size { const r = this.read_(); return new Size(r.width, r.height); }
+ set contentSize(v: Size) { this.write_({ width: v.width, height: v.height }); }
+ setContentSize(w: number | Size, h?: number): void {
+ if (typeof w === 'object') this.contentSize = w; else this.write_({ width: w, height: h ?? this.read_().height });
+ }
+
+ get width(): number { return this.read_().width; }
+ set width(v: number) { this.write_({ width: v }); }
+ get height(): number { return this.read_().height; }
+ set height(v: number) { this.write_({ height: v }); }
+
+ get anchorPoint(): Vec2 { const r = this.read_(); return new Vec2(r.anchorX, r.anchorY); }
+ set anchorPoint(v: Vec2) { this.write_({ anchorX: v.x, anchorY: v.y }); }
+ setAnchorPoint(x: number | Vec2, y?: number): void {
+ if (typeof x === 'object') this.anchorPoint = x; else this.write_({ anchorX: x, anchorY: y ?? this.read_().anchorY });
+ }
+ get anchorX(): number { return this.read_().anchorX; }
+ set anchorX(v: number) { this.write_({ anchorX: v }); }
+ get anchorY(): number { return this.read_().anchorY; }
+ set anchorY(v: number) { this.write_({ anchorY: v }); }
+
+ /** The rectangle in the node's own space: its left/bottom corner is minus the anchor times the size. */
+ private local_(): Rect {
+ const r = this.read_();
+ return new Rect(-r.anchorX * r.width, -r.anchorY * r.height, r.width, r.height);
+ }
+
+ /** A point in the node's space (relative to its anchor) as a point in world space, scale and rotation applied. */
+ convertToWorldSpaceAR(point: Vec3, out?: Vec3): Vec3 {
+ const world = this._world;
+ world.ensureTransformsComposed();
+ const t = world.get(this._entity, Transform);
+ const { x: qx, y: qy, z: qz, w: qw } = t.worldRotation;
+ const sx = point.x * t.worldScale.x, sy = point.y * t.worldScale.y, sz = point.z * t.worldScale.z;
+ const tx = 2 * (qy * sz - qz * sy), ty = 2 * (qz * sx - qx * sz), tz = 2 * (qx * sy - qy * sx);
+ const result = out ?? new Vec3();
+ result.x = t.worldPosition.x + sx + qw * tx + (qy * tz - qz * ty);
+ result.y = t.worldPosition.y + sy + qw * ty + (qz * tx - qx * tz);
+ result.z = t.worldPosition.z + sz + qw * tz + (qx * ty - qy * tx);
+ return result;
+ }
+
+ /** The reverse: a world point as a point relative to this node's anchor. */
+ convertToNodeSpaceAR(point: Vec3, out?: Vec3): Vec3 {
+ const world = this._world;
+ world.ensureTransformsComposed();
+ const t = world.get(this._entity, Transform);
+ const dx = point.x - t.worldPosition.x, dy = point.y - t.worldPosition.y, dz = point.z - t.worldPosition.z;
+ const { x: qx, y: qy, z: qz, w: qw } = t.worldRotation;
+ const ix = -qx, iy = -qy, iz = -qz;
+ const tx = 2 * (iy * dz - iz * dy), ty = 2 * (iz * dx - ix * dz), tz = 2 * (ix * dy - iy * dx);
+ const rx = dx + qw * tx + (iy * tz - iz * ty);
+ const ry = dy + qw * ty + (iz * tx - ix * tz);
+ const rz = dz + qw * tz + (ix * ty - iy * tx);
+ const result = out ?? new Vec3();
+ result.x = rx / (t.worldScale.x || 1);
+ result.y = ry / (t.worldScale.y || 1);
+ result.z = rz / (t.worldScale.z || 1);
+ return result;
+ }
+
+ /** Whether a world-space point is inside the rectangle. */
+ isHit(worldPoint: Vec2): boolean {
+ const local = this.convertToNodeSpaceAR(new Vec3(worldPoint.x, worldPoint.y, 0));
+ return this.local_().contains(new Vec2(local.x, local.y));
+ }
+
+ /** The axis-aligned box of the rectangle in world space. */
+ getBoundingBoxToWorld(): Rect {
+ const r = this.local_();
+ const corners = [new Vec3(r.x, r.y, 0), new Vec3(r.x + r.width, r.y, 0), new Vec3(r.x + r.width, r.y + r.height, 0), new Vec3(r.x, r.y + r.height, 0)]
+ .map((c) => this.convertToWorldSpaceAR(c));
+ const xs = corners.map((c) => c.x), ys = corners.map((c) => c.y);
+ const x = Math.min(...xs), y = Math.min(...ys);
+ return new Rect(x, y, Math.max(...xs) - x, Math.max(...ys) - y);
+ }
+}
+
+registerBuiltinComponent(UITransform, ['cc.UITransform', 'UITransform'], viewAdapter(
+ UITransform,
+ (world, entity) => world.has(entity, uiTransformDef()) || world.has(entity, Sprite) || world.has(entity, Text),
+ (world, entity) => { ensureUITransform(world, entity); },
+));
diff --git a/sdk/src/cocos/ui/view.ts b/sdk/src/cocos/ui/view.ts
new file mode 100644
index 000000000..a5354af0a
--- /dev/null
+++ b/sdk/src/cocos/ui/view.ts
@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file cocos/ui/view.ts
+ * @brief The shared shape of a Cocos built-in component that is a view on engine data.
+ *
+ * `Label`, `Sprite`, `UITransform` and the rest have no storage of their own: each reads and writes a component the engine
+ * already has (`Text`, `Sprite`), or a small compat data component where the engine has no counterpart. What they share is how a
+ * view is found and made — one instance per (world, entity, class), created on demand, never driven by the host's lifecycle
+ * system, because there is nothing for it to run — and that is here.
+ */
+import type { World } from '../../ecs/world';
+import type { Entity } from '../../types';
+import { Component } from '../component';
+import type { BuiltinAdapter } from '../builtins';
+import { instancesOn, nodeOf, storeInstance } from '../registry';
+import { Color } from '../math';
+
+/** A view on engine data. `enabled` is read from and written to the underlying component where it has one. */
+export abstract class ViewComponent extends Component {
+ /** The enable flag of whatever stands behind this view: the engine's `enabled` field, or the view's own. */
+ protected abstract readEnabled(): boolean;
+ protected abstract writeEnabled(value: boolean): void;
+}
+
+/**
+ * The adapter for a view class: @p present says whether the entity has what stands behind it, @p create gives it that.
+ * The view instance is made once and kept, so `node.getComponent(Label) === node.getComponent(Label)`.
+ */
+export function viewAdapter<T extends Component>(
+ ctor: new () => T,
+ present: (world: World, entity: Entity) => boolean,
+ create: (world: World, entity: Entity) => void,
+): BuiltinAdapter {
+ const view = (world: World, entity: Entity): T => {
+ let inst = instancesOn(world, entity)?.get(ctor) as T | undefined;
+ if (!inst) {
+ inst = new ctor();
+ inst._world = world;
+ inst._entity = entity;
+ inst.node = nodeOf(world, entity);
+ inst._loaded = true;
+ storeInstance(world, entity, ctor, inst);
+ }
+ return inst;
+ };
+ return {
+ get: (world, entity) => (present(world, entity) ? view(world, entity) : null),
+ add: (world, entity) => {
+ if (!present(world, entity)) create(world, entity);
+ return view(world, entity);
+ },
+ };
+}
+
+/** An engine colour (channels 0..1) as Cocos's (0..255). */
+export function toCocosColor(c: { r: number; g: number; b: number; a: number }): Color {
+ return new Color(Math.round(c.r * 255), Math.round(c.g * 255), Math.round(c.b * 255), Math.round(c.a * 255));
+}
+
+/** Cocos's colour (0..255) as the engine's (0..1). */
+export function toEngineColor(c: Color): { r: number; g: number; b: number; a: number } {
+ return { r: c.r / 255, g: c.g / 255, b: c.b / 255, a: c.a / 255 };
+}
diff --git a/sdk/tests/cocos/touch-wasm.test.ts b/sdk/tests/cocos/touch-wasm.test.ts
new file mode 100644
index 000000000..2971a47a2
--- /dev/null
+++ b/sdk/tests/cocos/touch-wasm.test.ts
@@ -0,0 +1,275 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Touches on nodes, and `Button`, against the real engine.
+ *
+ * What a Cocos script cannot be told is wrong, and what is pinned: a touch is claimed at its start by the TOPMOST node that listens and
+ * holds the point; the rest of the gesture goes to that node wherever the finger goes; the event bubbles up the ancestors, nearest
+ * first, until one stops it; and a button clicks when a touch ends INSIDE it, and not otherwise.
+ *
+ * The camera is faked as the identity (a screen pixel is a world unit, y flipped), so the geometry in the tests is the geometry on screen.
+ */
+import { afterEach, beforeAll, describe, expect, it, vi } 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 { InputState } from '../../src/input/input';
+import { resetClassRegistry } from '../../src/cocos/registry';
+import {
+ Button, Component, EventHandler, EventTouch, Node, NodeEventType, UITransform, Vec2, _decorator, pumpTouches, setCurrentWorld,
+} from '../../src/cocos';
+import { declareButton } from '../../src/cocos/ui/button';
+import { HAS_WASM, loadWasmModule } from '../helpers/loadWasm';
+
+// A screen pixel is a world unit: the GL y is the surface height minus the screen y.
+vi.mock('../../src/ui/util/ui-pick', () => ({ screenToUiWorld: (_cam: unknown, glX: number, glY: number) => ({ x: glX, y: glY }) }));
+
+const SURFACE_H = 800;
+const camera = { valid: true, screenH: SURFACE_H } as never;
+
+describe.skipIf(!HAS_WASM)('touches and buttons on the engine', () => {
+ let module: ESEngineModule;
+ let registry: InstanceType<ESEngineModule['Registry']> | undefined;
+ let app: App | undefined;
+ let input: InputState;
+
+ beforeAll(async () => { ensureBuiltinComponentsRegistered(); module = await loadWasmModule(); });
+
+ function connect(): void {
+ setDefaultContext(new AppContext());
+ ensureBuiltinComponentsRegistered();
+ resetClassRegistry();
+ declareButton();
+ registry = new module.Registry();
+ app = App.new();
+ app.connectCpp(registry as never, module);
+ flushPendingRegistrations(app);
+ setCurrentWorld(app.world);
+ input = new InputState();
+ }
+ afterEach(() => {
+ setCurrentWorld(null);
+ app?.world.disconnectCpp();
+ registry?.delete();
+ app = undefined;
+ registry = undefined;
+ });
+
+ const W = () => app!.world;
+
+ /** A node of @p w by @p h whose centre is at (x, y). */
+ function box(name: string, x: number, y: number, w = 100, h = 100, parent?: Node): Node {
+ const n = new Node(name);
+ W().insert(n._entity, Transform);
+ n.addComponent(UITransform)!.setContentSize(w, h);
+ n.setPosition(x, y, 0);
+ parent?.addChild(n);
+ return n;
+ }
+
+ // ---- driving the pointers by hand ----------------------------------------------------------------------------------
+ const screenOf = (wx: number, wy: number): { x: number; y: number } => ({ x: wx, y: SURFACE_H - wy });
+ function pump(): void { pumpTouches(W(), input, camera); input.touchesStarted.clear(); input.touchesEnded.clear(); }
+ function press(id: number, wx: number, wy: number): void {
+ const p = { id, ...screenOf(wx, wy) };
+ input.touches.set(id, p);
+ input.touchesStarted.set(id, p);
+ pump();
+ }
+ function move(id: number, wx: number, wy: number): void { input.touches.set(id, { id, ...screenOf(wx, wy) }); pump(); }
+ function release(id: number, wx: number, wy: number): void {
+ const p = { id, ...screenOf(wx, wy) };
+ input.touches.delete(id);
+ input.touchesEnded.set(id, p);
+ pump();
+ }
+
+ function record(node: Node, log: string[], tag = node.name): void {
+ for (const type of [NodeEventType.TOUCH_START, NodeEventType.TOUCH_MOVE, NodeEventType.TOUCH_END]) {
+ node.on(type, (e: EventTouch) => log.push(`${tag}:${type.replace('touch-', '')}@${Math.round(e.getUILocationX())},${Math.round(e.getUILocationY())}`));
+ }
+ }
+
+ it('tells a node about a touch that starts, moves and ends on it, with where each happened', () => {
+ connect();
+ const a = box('a', 200, 200);
+ const log: string[] = [];
+ record(a, log);
+ press(1, 210, 190);
+ move(1, 230, 190);
+ release(1, 230, 190);
+ expect(log).toEqual(['a:start@210,190', 'a:move@230,190', 'a:end@230,190']);
+ });
+
+ it('says nothing to a node the touch missed', () => {
+ connect();
+ const a = box('a', 200, 200);
+ const log: string[] = [];
+ record(a, log);
+ press(1, 400, 400);
+ release(1, 400, 400);
+ expect(log).toEqual([]);
+ });
+
+ it('hands the touch to the topmost of two overlapping nodes: the later sibling', () => {
+ connect();
+ const root = box('root', 0, 0, 1000, 1000);
+ const under = box('under', 200, 200, 100, 100, root);
+ const over = box('over', 220, 200, 100, 100, root);
+ const log: string[] = [];
+ record(under, log);
+ record(over, log);
+ press(1, 210, 200); // inside both
+ release(1, 210, 200);
+ expect(log.every((l) => l.startsWith('over:'))).toBe(true);
+ expect(log).toHaveLength(2);
+ });
+
+ it('keeps sending the gesture to the node that claimed it, wherever the finger goes', () => {
+ connect();
+ const a = box('a', 200, 200);
+ const b = box('b', 600, 200);
+ const log: string[] = [];
+ record(a, log);
+ record(b, log);
+ press(1, 200, 200);
+ move(1, 600, 200); // over b, but a has the touch
+ release(1, 600, 200);
+ expect(log.map((l) => l.split('@')[0])).toEqual(['a:start', 'a:move', 'a:end']);
+ });
+
+ it('bubbles to the ancestors nearest first, and stops where a listener says so', () => {
+ connect();
+ const parent = box('parent', 300, 300, 400, 400);
+ const child = box('child', 0, 0, 100, 100, parent);
+ const grand = box('grand', 300, 300, 400, 400);
+ const order: string[] = [];
+ child.on(NodeEventType.TOUCH_START, () => order.push('child'));
+ parent.on(NodeEventType.TOUCH_START, () => order.push('parent'));
+ press(1, 300, 300);
+ release(1, 300, 300);
+ expect(order).toEqual(['child', 'parent']);
+
+ order.length = 0;
+ child.targetOff(undefined);
+ child.on(NodeEventType.TOUCH_START, (e: EventTouch) => { order.push('child2'); e.stopPropagation(); });
+ press(2, 300, 300);
+ release(2, 300, 300);
+ expect(order).toContain('child2');
+ expect(order).not.toContain('parent');
+ void grand;
+ });
+
+ it('does not tell a switched-off node, or one under a switched-off parent', () => {
+ connect();
+ const parent = box('parent', 200, 200, 300, 300);
+ const child = box('child', 0, 0, 100, 100, parent);
+ const log: string[] = [];
+ record(child, log);
+ parent.active = false;
+ press(1, 200, 200);
+ release(1, 200, 200);
+ expect(log).toEqual([]);
+ });
+
+ it('gives the event its target and current target, and reads back a delta', () => {
+ connect();
+ const parent = box('parent', 200, 200, 300, 300);
+ const child = box('child', 0, 0, 100, 100, parent);
+ const seen: Array<{ target: string; current: string; dx?: number }> = [];
+ child.on(NodeEventType.TOUCH_START, () => {});
+ parent.on(NodeEventType.TOUCH_START, (e: EventTouch) => seen.push({ target: e.target!.name, current: e.currentTarget!.name }));
+ child.on(NodeEventType.TOUCH_MOVE, (e: EventTouch) => seen.push({ target: 'm', current: 'm', dx: e.getDelta().x }));
+ press(1, 200, 200);
+ move(1, 215, 200);
+ expect(seen[0]).toEqual({ target: 'child', current: 'parent' });
+ expect(seen[1]!.dx).toBe(15);
+ });
+
+ // ---- Button ----------------------------------------------------------------------------------------------------
+
+ /** Defined per test: the registry is reset when the engine connects, which would forget a class decorated at load. */
+ function defineTarget() {
+ @_decorator.ccclass('Target')
+ class Target extends Component {
+ calls: unknown[][] = [];
+ onClicked(_event: unknown, data: string): void { this.calls.push([data]); }
+ }
+ return Target;
+ }
+
+ async function button(x = 200, y = 200): Promise<{ node: Node; button: Button }> {
+ const node = box('btn', x, y);
+ const b = node.addComponent<Button>('Button')!;
+ await app!.tick(1 / 60); // onEnable registers the listeners
+ return { node, button: b };
+ }
+
+ it('clicks when a touch ends inside it: the node event, and the authored handlers with their custom data', async () => {
+ connect();
+ const holder = box('holder', 0, 0);
+ const Target = defineTarget();
+ const t = holder.addComponent(Target)!;
+ const { node, button: b } = await button();
+ const handler = new EventHandler();
+ handler.target = holder; handler.component = 'Target'; handler.handler = 'onClicked'; handler.customEventData = 'buy';
+ b.clickEvents = [handler];
+ let clicked = 0;
+ node.on(Button.EventType.CLICK, () => clicked++);
+ press(1, 205, 205);
+ release(1, 195, 195);
+ expect(clicked).toBe(1);
+ expect(t.calls).toEqual([['buy']]);
+ });
+
+ it('does not click when the touch ends outside, or when the button is not interactable', async () => {
+ connect();
+ const { node, button: b } = await button();
+ let clicked = 0;
+ node.on(Button.EventType.CLICK, () => clicked++);
+ press(1, 200, 200);
+ release(1, 500, 500); // dragged off and let go
+ expect(clicked).toBe(0);
+ b.interactable = false;
+ press(2, 200, 200);
+ release(2, 200, 200);
+ expect(clicked).toBe(0);
+ });
+
+ it('swallows the touch, so a node behind it does not also hear it', async () => {
+ connect();
+ const behind = box('behind', 200, 200, 300, 300);
+ const log: string[] = [];
+ record(behind, log);
+ await button();
+ press(1, 200, 200);
+ release(1, 200, 200);
+ expect(log).toEqual([]);
+ });
+
+ it('zooms its node while pressed, with the SCALE transition, and puts it back', async () => {
+ connect();
+ const { node, button: b } = await button();
+ b.transition = Button.Transition.SCALE;
+ b.zoomScale = 1.5;
+ node.setScale(2, 2, 1);
+ press(1, 200, 200);
+ expect(node.scale.x).toBeCloseTo(3, 5);
+ release(1, 200, 200);
+ expect(node.scale.x).toBeCloseTo(2, 5);
+ });
+
+ it('stops listening when disabled', async () => {
+ connect();
+ const { node, button: b } = await button();
+ let clicked = 0;
+ node.on(Button.EventType.CLICK, () => clicked++);
+ b.enabled = false;
+ await app!.tick(1 / 60); // the host sees the change and calls onDisable
+ press(1, 200, 200);
+ release(1, 200, 200);
+ expect(clicked).toBe(0);
+ void Vec2;
+ });
+});
diff --git a/sdk/tests/cocos/ui-adapters-wasm.test.ts b/sdk/tests/cocos/ui-adapters-wasm.test.ts
new file mode 100644
index 000000000..89763723a
--- /dev/null
+++ b/sdk/tests/cocos/ui-adapters-wasm.test.ts
@@ -0,0 +1,245 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Cocos's built-in UI components as views on the engine's, against the real engine (Sprite is a C++ component).
+ *
+ * What a script relies on and cannot be told is wrong: that `label.string = ...` is the Text that is drawn, that a colour set in
+ * Cocos's 0..255 comes back as the same 0..255, that line height keeps its pixel value when the font size changes (the engine stores
+ * a ratio), that the overflow numbers translate (SHRINK is 2 in Cocos and 3 in the engine), and that a size set on UITransform
+ * reaches the Sprite and Text that draw into it.
+ */
+import { afterEach, beforeAll, describe, expect, it } from 'vitest';
+import type { ESEngineModule } from '../../src/wasm';
+import { World } from '../../src/ecs/world';
+import { Sprite as EngineSprite, Transform, ensureBuiltinComponentsRegistered } from '../../src/ecs/component';
+import { AppContext, setDefaultContext } from '../../src/ecs/context';
+import { Text } from '../../src/ui/core/text';
+import { TextOverflow } from '../../src/ui/core/text';
+import { Color, Label, LabelOutline, LabelShadow, Node, Size, Sprite, UIOpacity, UITransform, Vec2, Vec3, setCurrentWorld } from '../../src/cocos';
+import { HAS_WASM, loadWasmModule } from '../helpers/loadWasm';
+
+describe.skipIf(!HAS_WASM)('built-in UI components on the engine', () => {
+ let module: ESEngineModule;
+ let registry: InstanceType<ESEngineModule['Registry']> | undefined;
+ let world: World | undefined;
+ const W = (): World => world!;
+
+ beforeAll(async () => { ensureBuiltinComponentsRegistered(); module = await loadWasmModule(); });
+
+ function connect(): void {
+ setDefaultContext(new AppContext());
+ ensureBuiltinComponentsRegistered();
+ registry = new module.Registry();
+ world = new World();
+ world.connectCpp(registry, module);
+ setCurrentWorld(world);
+ }
+ afterEach(() => {
+ setCurrentWorld(null);
+ world?.disconnectCpp();
+ registry?.delete();
+ registry = undefined;
+ world = undefined;
+ });
+
+ const node = (name: string): Node => { const n = new Node(name); W().insert(n._entity, Transform); return n; };
+
+ describe('Label', () => {
+ it('is the Text on its node: added if there is none, the same view each time', () => {
+ connect();
+ const n = node('l');
+ expect(n.getComponent(Label)).toBeNull();
+ const label = n.addComponent(Label)!;
+ expect(label).toBeInstanceOf(Label);
+ expect(W().has(n._entity, Text)).toBe(true);
+ expect(n.getComponent(Label)).toBe(label);
+ expect(n.getComponent('cc.Label')).toBe(label);
+ });
+
+ it('writes the string, size and flags through to the Text that is drawn', () => {
+ connect();
+ const n = node('l');
+ const label = n.addComponent(Label)!;
+ label.string = '胜利';
+ label.fontSize = 36;
+ label.isBold = true;
+ label.enableWrapText = false;
+ const t = W().get(n._entity, Text);
+ expect(t.content).toBe('胜利');
+ expect(t.fontSize).toBe(36);
+ expect(t.bold).toBe(true);
+ expect(t.wordWrap).toBe(false);
+ expect(label.string).toBe('胜利');
+ });
+
+ it('turns a null or undefined string into empty text, as Cocos does', () => {
+ connect();
+ const label = node('l').addComponent(Label)!;
+ label.string = 'x';
+ label.string = undefined as never;
+ expect(label.string).toBe('');
+ });
+
+ it('converts a colour between Cocos 0..255 and the engine 0..1, and reads back what was set', () => {
+ connect();
+ const n = node('l');
+ const label = n.addComponent(Label)!;
+ label.color = new Color(255, 128, 0, 64);
+ const t = W().get(n._entity, Text);
+ expect(t.color.r).toBeCloseTo(1, 5);
+ expect(t.color.g).toBeCloseTo(128 / 255, 5);
+ expect(t.color.b).toBe(0);
+ expect(t.color.a).toBeCloseTo(64 / 255, 5);
+ const back = label.color;
+ expect([back.r, back.g, back.b, back.a]).toEqual([255, 128, 0, 64]);
+ });
+
+ it('keeps a line height in pixels when the font size changes, though the engine stores a ratio', () => {
+ connect();
+ const label = node('l').addComponent(Label)!;
+ label.fontSize = 20;
+ label.lineHeight = 30;
+ expect(label.lineHeight).toBeCloseTo(30, 5);
+ label.fontSize = 40;
+ expect(label.lineHeight).toBeCloseTo(30, 5); // still 30px, not 60
+ });
+
+ it('translates the overflow numbers and the alignments', () => {
+ connect();
+ const n = node('l');
+ const label = n.addComponent(Label)!;
+ label.overflow = Label.Overflow.SHRINK;
+ expect(W().get(n._entity, Text).overflow).toBe(TextOverflow.Shrink);
+ expect(label.overflow).toBe(Label.Overflow.SHRINK);
+ label.overflow = Label.Overflow.CLAMP;
+ expect(W().get(n._entity, Text).overflow).toBe(TextOverflow.Clip);
+ label.overflow = Label.Overflow.RESIZE_HEIGHT; // no engine counterpart: draws whole
+ expect(W().get(n._entity, Text).overflow).toBe(TextOverflow.Visible);
+ label.horizontalAlign = Label.HorizontalAlign.RIGHT;
+ label.verticalAlign = Label.VerticalAlign.BOTTOM;
+ const t = W().get(n._entity, Text);
+ expect([t.align, t.verticalAlign]).toEqual([2, 2]);
+ });
+
+ it('has its outline and shadow as properties of the same Text', () => {
+ connect();
+ const n = node('l');
+ n.addComponent(Label);
+ const outline = n.addComponent(LabelOutline)!;
+ outline.color = new Color(0, 0, 255, 255);
+ outline.width = 3;
+ const shadow = n.addComponent(LabelShadow)!;
+ shadow.offset = { x: 2, y: -4 };
+ shadow.blur = 5;
+ const t = W().get(n._entity, Text);
+ expect(t.strokeWidth).toBe(3);
+ expect(t.strokeColor.b).toBe(1);
+ // Cocos's y is up; the engine's shadow y is down
+ expect(t.shadowOffsetX).toBe(2);
+ expect(t.shadowOffsetY).toBe(4);
+ expect(t.shadowBlur).toBe(5);
+ expect(shadow.offset).toEqual({ x: 2, y: -4 });
+ });
+ });
+
+ describe('Sprite and UIOpacity', () => {
+ it('is the engine Sprite on its node, with Cocos colour and type numbers', () => {
+ connect();
+ const n = node('s');
+ const sprite = n.addComponent(Sprite)!;
+ expect(W().has(n._entity, EngineSprite)).toBe(true);
+ sprite.color = new Color(10, 20, 30, 255);
+ expect(W().get(n._entity, EngineSprite).color.g).toBeCloseTo(20 / 255, 5);
+ sprite.type = Sprite.Type.SLICED;
+ expect(sprite.type).toBe(Sprite.Type.SLICED);
+ sprite.type = Sprite.Type.TILED;
+ expect(sprite.type).toBe(Sprite.Type.TILED);
+ sprite.enabled = false;
+ expect(W().get(n._entity, EngineSprite).enabled).toBe(false);
+ });
+
+ it('fades the node\'s own sprite by UIOpacity, and does not compound repeated writes', () => {
+ connect();
+ const n = node('s');
+ n.addComponent(Sprite);
+ const opacity = n.addComponent(UIOpacity)!;
+ opacity.opacity = 128;
+ const a1 = W().get(n._entity, EngineSprite).color.a;
+ expect(a1).toBeCloseTo(128 / 255, 3);
+ opacity.opacity = 128;
+ opacity.opacity = 128;
+ expect(W().get(n._entity, EngineSprite).color.a).toBeCloseTo(a1, 5);
+ opacity.opacity = 255;
+ expect(W().get(n._entity, EngineSprite).color.a).toBeCloseTo(1, 5);
+ });
+ });
+
+ describe('UITransform', () => {
+ it('starts from the renderer the node has, and is there for a node that draws nothing', () => {
+ connect();
+ const withSprite = node('a');
+ withSprite.addComponent(Sprite);
+ W().set(withSprite._entity, EngineSprite, { ...W().get(withSprite._entity, EngineSprite), size: { x: 80, y: 40 }, pivot: { x: 0, y: 1 } });
+ const t = withSprite.getComponent(UITransform)!;
+ expect(t.contentSize.width).toBe(80);
+ expect(t.contentSize.height).toBe(40);
+ expect(t.anchorPoint.equals(new Vec2(0, 1))).toBe(true);
+
+ const bare = node('b');
+ const bt = bare.addComponent(UITransform)!;
+ bt.setContentSize(300, 200);
+ expect(bare.getComponent(UITransform)).toBe(bt);
+ expect(bt.width).toBe(300);
+ expect(bt.height).toBe(200);
+ });
+
+ it('carries a size and anchor to the Sprite and Text that draw into it', () => {
+ connect();
+ const n = node('both');
+ n.addComponent(Sprite);
+ n.addComponent(Label);
+ const t = n.addComponent(UITransform)!;
+ t.contentSize = new Size(120, 60);
+ t.anchorPoint = new Vec2(0.5, 1);
+ const s = W().get(n._entity, EngineSprite);
+ expect([s.size.x, s.size.y, s.pivot.x, s.pivot.y]).toEqual([120, 60, 0.5, 1]);
+ const x = W().get(n._entity, Text);
+ expect([x.boxWidth, x.boxHeight, x.boxPivot.x, x.boxPivot.y]).toEqual([120, 60, 0.5, 1]);
+ });
+
+ it('tests a world point against its rectangle, anchor and position applied', () => {
+ connect();
+ const n = node('hit');
+ const t = n.addComponent(UITransform)!;
+ t.setContentSize(100, 50);
+ t.setAnchorPoint(0.5, 0.5);
+ n.setPosition(200, 100, 0);
+ expect(t.isHit(new Vec2(200, 100))).toBe(true);
+ expect(t.isHit(new Vec2(249, 124))).toBe(true);
+ expect(t.isHit(new Vec2(251, 100))).toBe(false);
+ expect(t.isHit(new Vec2(200, 126))).toBe(false);
+ // an anchor at the bottom-left moves the rectangle up and to the right of the node
+ t.setAnchorPoint(0, 0);
+ expect(t.isHit(new Vec2(250, 120))).toBe(true);
+ expect(t.isHit(new Vec2(199, 100))).toBe(false);
+ });
+
+ it('converts between node space and world space under a scaled, moved parent', () => {
+ connect();
+ const parent = node('p'), child = node('c');
+ parent.addChild(child);
+ parent.setPosition(100, 0, 0);
+ parent.setScale(2, 2, 1);
+ child.setPosition(10, 5, 0);
+ const t = child.addComponent(UITransform)!;
+ const world = t.convertToWorldSpaceAR(new Vec3(0, 0, 0));
+ expect(world.x).toBeCloseTo(120, 3); // 100 + 10 * 2
+ expect(world.y).toBeCloseTo(10, 3);
+ const back = t.convertToNodeSpaceAR(world);
+ expect(back.x).toBeCloseTo(0, 3);
+ expect(back.y).toBeCloseTo(0, 3);
+ const box = t.getBoundingBoxToWorld();
+ expect(box.width).toBeCloseTo(200, 3); // the 100px default width, scaled by the parent
+ });
+ });
+});