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