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(text): the engine's rich-text parser reads Cocos's tags (size, color names, br; underline/outline/click kept as plain text); Cocos Camera and RichText are views on the engine's Camera and Text; a touch has a screen point (getLocation) and a canvas point (getUILocation)
yhhd4692cfaa8e4
diff --git a/docs/astro/src/content/docs/ui/text.mdx b/docs/astro/src/content/docs/ui/text.mdxindex 92a6bb5c3..f87ffebce 100644--- a/docs/astro/src/content/docs/ui/text.mdx+++ b/docs/astro/src/content/docs/ui/text.mdx@@ -160,8 +160,10 @@ known tag renders literally (so a stray `<` cannot eat your text).|---|---|| `<b>…</b>` | Bold run. || `<i>…</i>` | Italic run. |-| `<color=#RRGGBB>…</color>` | Colored run; `#RRGGBBAA` adds alpha. |-| `<font size=32>…</font>` | Run at another font size (`size="32"` also parses); the shared baseline is kept. |+| `<color=#RRGGBB>…</color>` | Colored run; `#RRGGBBAA` adds alpha. A name works too: `<color=red>` (black, white, red, green, blue, yellow, cyan, magenta, orange, gray, purple, pink, brown). |+| `<font size=32>…</font>` | Run at another font size (`size="32"` also parses); the shared baseline is kept. `<size=32>…</size>` is the same. |+| `<br/>` | A line break. |+| `<u>`, `<s>`, `<outline …>`, `<on click=…>` | Accepted so text written for other engines does not show raw tags; the text is kept and the style (or click) is not applied. || `<img src="…" width=24 height=24 />` | Inline image — an icon flowed in with the text (see [below](#inline-images)). |```typescriptdiff --git a/docs/astro/src/content/docs/zh-cn/ui/text.mdx b/docs/astro/src/content/docs/zh-cn/ui/text.mdxindex f9fd5eb4d..1eea0f09a 100644--- a/docs/astro/src/content/docs/zh-cn/ui/text.mdx+++ b/docs/astro/src/content/docs/zh-cn/ui/text.mdx@@ -140,8 +140,10 @@ const pulseBanner = defineSystem([Query(Mut(Transform), Text), Res(Time)], (q, t|---|---|| `<b>…</b>` | 加粗片段。 || `<i>…</i>` | 斜体片段。 |-| `<color=#RRGGBB>…</color>` | 着色片段;`#RRGGBBAA` 带 alpha。 |-| `<font size=32>…</font>` | 另一字号的片段(`size="32"` 也能解析);共享基线。 |+| `<color=#RRGGBB>…</color>` | 着色片段;`#RRGGBBAA` 带 alpha。也可以写颜色名:`<color=red>`(black、white、red、green、blue、yellow、cyan、magenta、orange、gray、purple、pink、brown)。 |+| `<font size=32>…</font>` | 另一字号的片段(`size="32"` 也能解析);共享基线。`<size=32>…</size>` 等价。 |+| `<br/>` | 换行。 |+| `<u>`、`<s>`、`<outline …>`、`<on click=…>` | 接受这些标记,使为其他引擎写的文本不会显示出原始标签;文字保留,样式(或点击)不生效。 || `<img src="…" width=24 height=24 />` | 内联图片——随文本一起排布的图标(见[下文](#内联图片))。 |```typescriptdiff --git a/pipeline/src/import/cocos/components.ts b/pipeline/src/import/cocos/components.tsindex fad1d2cd6..1f399eb1f 100644--- a/pipeline/src/import/cocos/components.ts+++ b/pipeline/src/import/cocos/components.ts@@ -227,7 +227,8 @@ function label(c: CocosComponent, siblings: CocosComponent[], box: UiBox | null,function richText(c: CocosComponent, box: UiBox | null, ctx: ComponentContext): ComponentData {const d = c.data;- ctx.report.component('cc.RichText', 'partial');+ // The markup is the engine's rich-text parser's to read (it knows Cocos's tags), so the string goes across as written.+ ctx.report.component('cc.RichText', 'mapped');const maxWidth = num(d._maxWidth, 0);return {type: 'Text',@@ -257,6 +258,7 @@ function camera(c: CocosComponent, ctx: ComponentContext): ComponentData {farPlane: num(d._far, 1000),priority: num(d._priority, 0),cullingMask: num(d._visibility, 0xffffffff) >>> 0,+ ...(isObj(d._rect) ? { viewport: { x: num(d._rect.x, 0), y: num(d._rect.y, 0), z: num(d._rect.width, 1), w: num(d._rect.height, 1) } } : {}),isActive: c.enabled,},};diff --git a/sdk/src/cocos/index.ts b/sdk/src/cocos/index.tsindex 727a44c2f..986959531 100644--- a/sdk/src/cocos/index.ts+++ b/sdk/src/cocos/index.ts@@ -26,7 +26,7 @@ export {AnimationClip, SceneAsset, EffectAsset, Mesh,} from './assets';export { registerBuiltinComponent, type BuiltinAdapter } from './builtins';-export { UITransform, Label, LabelOutline, LabelShadow, Sprite, UIOpacity, Button, EventHandler, Widget, Layout, Toggle, ToggleContainer, ProgressBar, Slider, BlockInputEvents, ScrollView, getVisibleSize, setVisibleSize } from './ui';+export { UITransform, Label, LabelOutline, LabelShadow, Sprite, UIOpacity, Button, EventHandler, Widget, Layout, Camera, RichText, Toggle, ToggleContainer, ProgressBar, Slider, BlockInputEvents, ScrollView, getVisibleSize, setVisibleSize } from './ui';export { Touch, EventTouch, pumpTouches } from './input';export { tween, Tween, tweenUtil, easing, updateTweens } from './tween';export { instantiate, loadPrefab, providePrefab } from './prefabs';diff --git a/sdk/src/cocos/input.ts b/sdk/src/cocos/input.tsindex c2346359e..4488912f9 100644--- a/sdk/src/cocos/input.ts+++ b/sdk/src/cocos/input.ts@@ -29,32 +29,42 @@ import { UITransform } from './ui/uiTransform';import { log } from '../util/logger';import { EventKeyboard, EventMouse, input as globalInput, keyCodeOf, Input as InputApi } from './inputApi';-/** One finger (or the mouse button) as a script sees it. */+interface Point { x: number; y: number; sx: number; sy: number }++/**+ * One finger (or the mouse button) as a script sees it, at two kinds of place as in Cocos: the SCREEN point+ * (`getLocation`: pixels of the drawing surface, origin bottom-left — what a camera's `screenToWorld` takes), and the CANVAS point+ * (`getUILocation`: the space the UI is laid out in, which in an imported scene is the world's).+ */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_,- ) {}+ private cur_: Point;+ private readonly start_: Point;+ private prev_: Point;++ constructor(public readonly id: number, x: number, y: number, sx: number = x, sy: number = y) {+ this.cur_ = { x, y, sx, sy };+ this.start_ = { ...this.cur_ };+ this.prev_ = { ...this.cur_ };+ }/** @internal */- _move(x: number, y: number): void { this.prevX_ = this.x_; this.prevY_ = this.y_; this.x_ = x; this.y_ = y; }+ _move(x: number, y: number, sx: number = x, sy: number = y): void { this.prev_ = this.cur_; this.cur_ = { x, y, sx, sy }; }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_); }++ getLocation(out: Vec2 = new Vec2()): Vec2 { return out.set(this.cur_.sx, this.cur_.sy); }+ getLocationX(): number { return this.cur_.sx; }+ getLocationY(): number { return this.cur_.sy; }+ getStartLocation(out: Vec2 = new Vec2()): Vec2 { return out.set(this.start_.sx, this.start_.sy); }+ getPreviousLocation(out: Vec2 = new Vec2()): Vec2 { return out.set(this.prev_.sx, this.prev_.sy); }+ getDelta(out: Vec2 = new Vec2()): Vec2 { return out.set(this.cur_.sx - this.prev_.sx, this.cur_.sy - this.prev_.sy); }++ getUILocation(out: Vec2 = new Vec2()): Vec2 { return out.set(this.cur_.x, this.cur_.y); }+ getUILocationX(): number { return this.cur_.x; }+ getUILocationY(): number { return this.cur_.y; }+ getUIStartLocation(out: Vec2 = new Vec2()): Vec2 { return out.set(this.start_.x, this.start_.y); }+ getUIPreviousLocation(out: Vec2 = new Vec2()): Vec2 { return out.set(this.prev_.x, this.prev_.y); }+ getUIDelta(out: Vec2 = new Vec2()): Vec2 { return out.set(this.cur_.x - this.prev_.x, this.cur_.y - this.prev_.y); }}/** The event a touch listener receives. */@@ -85,6 +95,9 @@ export class EventTouch {getLocationX(): number { return this.touch.getLocationX(); }getLocationY(): number { return this.touch.getLocationY(); }getUILocation(out?: Vec2): Vec2 { return this.touch.getUILocation(out); }+ getUIStartLocation(out?: Vec2): Vec2 { return this.touch.getUIStartLocation(out); }+ getUIPreviousLocation(out?: Vec2): Vec2 { return this.touch.getUIPreviousLocation(out); }+ getUIDelta(out?: Vec2): Vec2 { return this.touch.getUIDelta(out); }getUILocationX(): number { return this.touch.getUILocationX(); }getUILocationY(): number { return this.touch.getUILocationY(); }getStartLocation(out?: Vec2): Vec2 { return this.touch.getStartLocation(out); }@@ -199,11 +212,12 @@ export function pumpTouches(world: World, input: InputState, camera: UICameraDatconst 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 };+ const sx = p.x * dpr, sy = surfaceH - p.y * dpr;+ const at = camera.valid ? screenToUiWorld(camera, sx, sy) : { x: 0, y: 0 };let gesture = book.get(p.id);if (p.pressed && !gesture) {- const touch = new Touch(p.id, at.x, at.y);+ const touch = new Touch(p.id, at.x, at.y, sx, sy);const hit = hitNode(world, new Vec2(at.x, at.y));gesture = { touch, target: hit, chainFrom: hit };book.set(p.id, gesture);@@ -214,12 +228,12 @@ export function pumpTouches(world: World, input: InputState, camera: UICameraDatif (!gesture) continue;if (p.down && (at.x !== gesture.touch.getLocationX() || at.y !== gesture.touch.getLocationY())) {- gesture.touch._move(at.x, at.y);+ gesture.touch._move(at.x, at.y, sx, sy);globalInput.emit(Node.EventType.TOUCH_MOVE, new EventTouch(Node.EventType.TOUCH_MOVE, gesture.touch, live));if (gesture.chainFrom) dispatch(withCancel(new EventTouch(Node.EventType.TOUCH_MOVE, gesture.touch, live), gesture, live), gesture.target, gesture.chainFrom);}if (p.released) {- gesture.touch._move(at.x, at.y);+ gesture.touch._move(at.x, at.y, sx, sy);const type = p.cancelled ? Node.EventType.TOUCH_CANCEL : Node.EventType.TOUCH_END;globalInput.emit(type, new EventTouch(type, gesture.touch, live));if (gesture.chainFrom) dispatch(withCancel(new EventTouch(type, gesture.touch, live), gesture, live), gesture.target, gesture.chainFrom);@@ -244,12 +258,13 @@ export function pumpKeysAndMouse(input: InputState, camera: UICameraData): voidfor (const code of input.keysReleased) globalInput.emit(InputApi.EventType.KEY_UP, new EventKeyboard(keyCodeOf(code), InputApi.EventType.KEY_UP));const dpr = platformDevicePixelRatio();- const at = camera.valid ? screenToUiWorld(camera, input.mouseX * dpr, camera.screenH - input.mouseY * dpr) : { x: 0, y: 0 };+ const sx = input.mouseX * dpr, sy = camera.screenH - input.mouseY * dpr;+ const at = camera.valid ? screenToUiWorld(camera, sx, sy) : { x: 0, y: 0 };const lastMouse = lastMouseOf.get(input);const previous = lastMouse ?? at;const moved = lastMouse !== undefined && (at.x !== lastMouse.x || at.y !== lastMouse.y);const prev = new Vec2(previous.x, previous.y);- const event = (type: string): EventMouse => new EventMouse(type, at.x, at.y, prev);+ const event = (type: string): EventMouse => new EventMouse(type, at.x, at.y, prev, sx, sy);for (const b of input.mouseButtonsPressed) globalInput.emit(InputApi.EventType.MOUSE_DOWN, event(InputApi.EventType.MOUSE_DOWN)._button(b));if (moved) globalInput.emit(InputApi.EventType.MOUSE_MOVE, event(InputApi.EventType.MOUSE_MOVE));for (const b of input.mouseButtonsReleased) globalInput.emit(InputApi.EventType.MOUSE_UP, event(InputApi.EventType.MOUSE_UP)._button(b));diff --git a/sdk/src/cocos/inputApi.ts b/sdk/src/cocos/inputApi.tsindex 4c05e331d..7f8a70d1a 100644--- a/sdk/src/cocos/inputApi.ts+++ b/sdk/src/cocos/inputApi.ts@@ -77,23 +77,26 @@ export class EventMouse {stopped = false;private readonly location_: Vec2;private prev_: Vec2;+ private readonly screen_: Vec2;private scrollX_ = 0;private scrollY_ = 0;private button_ = 0;- constructor(public readonly type: string, x = 0, y = 0, prev?: Vec2) {+ /** @p x / @p y are the canvas (UI) point, @p sx / @p sy the screen point (pixels of the surface, origin bottom-left). */+ constructor(public readonly type: string, x = 0, y = 0, prev?: Vec2, sx: number = x, sy: number = y) {this.location_ = new Vec2(x, y);this.prev_ = prev ?? new Vec2(x, y);+ this.screen_ = new Vec2(sx, sy);}/** @internal */ _button(b: number): this { this.button_ = b; return this; }/** @internal */ _scroll(x: number, y: number): this { this.scrollX_ = x; this.scrollY_ = y; return this; }getButton(): number { return this.button_; }- getLocation(out: Vec2 = new Vec2()): Vec2 { return out.set(this.location_.x, this.location_.y); }- getLocationX(): number { return this.location_.x; }- getLocationY(): number { return this.location_.y; }- getUILocation(out: Vec2 = new Vec2()): Vec2 { return this.getLocation(out); }+ getLocation(out: Vec2 = new Vec2()): Vec2 { return out.set(this.screen_.x, this.screen_.y); }+ getLocationX(): number { return this.screen_.x; }+ getLocationY(): number { return this.screen_.y; }+ getUILocation(out: Vec2 = new Vec2()): Vec2 { return out.set(this.location_.x, this.location_.y); }getUILocationX(): number { return this.location_.x; }getUILocationY(): number { return this.location_.y; }getPreviousLocation(out: Vec2 = new Vec2()): Vec2 { return out.set(this.prev_.x, this.prev_.y); }diff --git a/sdk/src/cocos/ui/button.ts b/sdk/src/cocos/ui/button.tsindex edb67ad67..d92f4a1f0 100644--- a/sdk/src/cocos/ui/button.ts+++ b/sdk/src/cocos/ui/button.ts@@ -111,7 +111,7 @@ export class Button extends Component {if (!this.pressed_) return;this.pressed_ = false;this.applyTransition_();- const inside = this.node.getComponent(UITransform)?.isHit(event.getLocation()) ?? true;+ const inside = this.node.getComponent(UITransform)?.isHit(event.getUILocation()) ?? true;if (this.interactable && this.enabledInHierarchy && inside) {EventHandler.emitEvents(this.clickEvents, event);this.node.emit(EventType.CLICK, this);diff --git a/sdk/src/cocos/ui/camera.ts b/sdk/src/cocos/ui/camera.tsnew file mode 100644index 000000000..b0b2565e1--- /dev/null+++ b/sdk/src/cocos/ui/camera.ts@@ -0,0 +1,111 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file cocos/ui/camera.ts+ * @brief `Camera`: a view on the engine's `Camera`, with Cocos's names and the conversions scripts use it for.+ *+ * Every setting is the engine camera's, renamed (`orthoHeight` is its `orthoSize`, `visibility` its `cullingMask`, `rect` its+ * `viewport`) and `projection` translated, since the two number the kinds the other way round. The conversions go through the+ * UI camera — the one that draws the scene's UI and world content — so `screenToWorld(touch.getLocation())` lands where the+ * finger is, which is what a script that has a camera in hand wants.+ *+ * Not carried: `clearColor` and `clearFlags` are held so a script can read back what it set, but the engine's clear belongs to its+ * renderer settings, not to the camera.+ */+import { Camera as EngineCamera, type CameraData } from '../../ecs/component';+import type { World } from '../../ecs/world';+import type { Entity } from '../../types';+import { isProjectable, projectWorldPoint } from '../../ui/util/math';+import { screenToUiWorld } from '../../ui/util/ui-pick';+import { Color, Rect, Vec3 } from '../math';+import { Component } from '../component';+import { registerBuiltinComponent } from '../builtins';+import type { Node } from '../node';+import { viewAdapter } from './view';+import { UITransform } from './uiTransform';+import { uiCameraData } from './screen';++const ProjectionType = Object.freeze({ ORTHO: 0, PERSPECTIVE: 1 });+const FOVAxis = Object.freeze({ VERTICAL: 0, HORIZONTAL: 1 });+const ClearFlag = Object.freeze({ DONT_CLEAR: 0, DEPTH_ONLY: 6, SOLID_COLOR: 7, SKYBOX: 14 });++/** The engine's camera types: 0 perspective, 1 orthographic. */+const ENGINE_ORTHO = 1;++export class Camera extends Component {+ static readonly ProjectionType = ProjectionType;+ static readonly FOVAxis = FOVAxis;+ static readonly ClearFlag = ClearFlag;++ private data_(): CameraData { return this._world.get(this._entity, EngineCamera); }+ private patch_(patch: Partial<CameraData>): void { this._world.set(this._entity, EngineCamera, { ...this.data_(), ...patch }); }++ private clearColor_ = new Color(0, 0, 0, 255);+ private clearFlags_: number = ClearFlag.SOLID_COLOR;++ get projection(): number { return this.data_().projectionType === ENGINE_ORTHO ? ProjectionType.ORTHO : ProjectionType.PERSPECTIVE; }+ set projection(v: number) { this.patch_({ projectionType: v === ProjectionType.ORTHO ? ENGINE_ORTHO : 0 }); }++ /** Half the visible height in world units, as in Cocos. */+ get orthoHeight(): number { return this.data_().orthoSize; }+ set orthoHeight(v: number) { this.patch_({ orthoSize: v }); }++ get fov(): number { return this.data_().fov; }+ set fov(v: number) { this.patch_({ fov: v }); }+ get fovAxis(): number { return FOVAxis.VERTICAL; }++ get near(): number { return this.data_().nearPlane; }+ set near(v: number) { this.patch_({ nearPlane: v }); }+ get far(): number { return this.data_().farPlane; }+ set far(v: number) { this.patch_({ farPlane: v }); }++ get priority(): number { return this.data_().priority; }+ set priority(v: number) { this.patch_({ priority: v }); }++ /** The layers this camera draws, as a bitmask. */+ get visibility(): number { return this.data_().cullingMask >>> 0; }+ set visibility(v: number) { this.patch_({ cullingMask: v >>> 0 }); }++ /** The part of the window it draws into, 0..1. */+ get rect(): Rect { const v = this.data_().viewport; return new Rect(v.x, v.y, v.z, v.w); }+ set rect(r: Rect) { this.patch_({ viewport: { x: r.x, y: r.y, z: r.width, w: r.height } }); }++ get clearFlags(): number { return this.clearFlags_; }+ set clearFlags(v: number) { this.clearFlags_ = v; }+ get clearColor(): Color { return this.clearColor_.clone(); }+ set clearColor(v: Color) { this.clearColor_ = v.clone(); }++ get enabled(): boolean { return this.data_().isActive; }+ set enabled(v: boolean) { this.patch_({ isActive: v }); }++ /**+ * The world point under a screen point (pixels of the drawing surface, origin bottom-left — what `EventTouch.getLocation`+ * gives). @p screenPos.z is the depth along the view ray; for a flat scene it does not change x and y.+ */+ screenToWorld(screenPos: Vec3, out: Vec3 = new Vec3()): Vec3 {+ const cam = uiCameraData();+ if (!cam?.valid) return out.set(0, 0, 0);+ const w = screenToUiWorld(cam, screenPos.x, screenPos.y);+ return out.set(w.x, w.y, 0);+ }++ /** The screen point (surface pixels, origin bottom-left) a world point lands on. */+ worldToScreen(worldPos: Vec3, out: Vec3 = new Vec3()): Vec3 {+ const cam = uiCameraData();+ if (!cam?.valid) return out.set(0, 0, 0);+ const p = projectWorldPoint(worldPos.x, worldPos.y, worldPos.z, cam.viewProjection, cam.vpX, cam.vpY, cam.vpW, cam.vpH);+ return isProjectable(p) ? out.set(p.x, p.y, 0) : out.set(0, 0, 0);+ }++ /** A world point as a point in @p uiNode's space (relative to its anchor): where to put something there that is at @p worldPos. */+ convertToUINode(worldPos: Vec3, uiNode: Node, out: Vec3 = new Vec3()): Vec3 {+ const t = uiNode.getComponent(UITransform);+ if (!t) return out.set(worldPos.x, worldPos.y, worldPos.z);+ return t.convertToNodeSpaceAR(worldPos, out);+ }+}++const hasCamera = (world: World, entity: Entity): boolean => world.has(entity, EngineCamera);+const addCamera = (world: World, entity: Entity): void => { world.insert(entity, EngineCamera, {}); };++registerBuiltinComponent(Camera, ['cc.Camera', 'Camera'], viewAdapter(Camera, hasCamera, addCamera));diff --git a/sdk/src/cocos/ui/index.ts b/sdk/src/cocos/ui/index.tsindex ac5dfec85..35ed4acf6 100644--- a/sdk/src/cocos/ui/index.ts+++ b/sdk/src/cocos/ui/index.ts@@ -13,3 +13,5 @@ export { ScrollView } from './scrollView';export { Widget, alignWidget } from './widget';export { Layout } from './layout';export { getVisibleSize, setVisibleSize } from './screen';+export { Camera } from './camera';+export { RichText } from './richText';diff --git a/sdk/src/cocos/ui/label.ts b/sdk/src/cocos/ui/label.tsindex 85dc07c11..252bd355d 100644--- a/sdk/src/cocos/ui/label.ts+++ b/sdk/src/cocos/ui/label.ts@@ -35,7 +35,7 @@ function toCocosOverflow(engine: number): number {}/** The `Text` data of an entity: the thing every property below reads and writes. */-class TextView extends Component {+export 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 }); }}diff --git a/sdk/src/cocos/ui/pass.ts b/sdk/src/cocos/ui/pass.tsindex 6a7c068b9..bfdfaf067 100644--- a/sdk/src/cocos/ui/pass.ts+++ b/sdk/src/cocos/ui/pass.ts@@ -16,7 +16,7 @@ import { alignAllWidgets, declareWidget } from './widget';import { layoutAll, declareLayout } from './layout';import { declareControls } from './controls';import { declareScrollView } from './scrollView';-import { setVisibleSize, setWindowPixels } from './screen';+import { setUiCameraData, setVisibleSize, setWindowPixels } from './screen';export function declareUiPass(): void {declareWidget();@@ -27,6 +27,7 @@ export function declareUiPass(): void {[Res(UICameraInfo), GetWorld()],(camera, world) => {// What the UI camera shows is the visible area scripts and widgets measure against; the surface is the window.+ setUiCameraData(camera ?? null);if (camera?.valid) {setVisibleSize(camera.worldRight - camera.worldLeft, camera.worldTop - camera.worldBottom);setWindowPixels(camera.screenW, camera.screenH);diff --git a/sdk/src/cocos/ui/richText.ts b/sdk/src/cocos/ui/richText.tsnew file mode 100644index 000000000..4b4a76031--- /dev/null+++ b/sdk/src/cocos/ui/richText.ts@@ -0,0 +1,56 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file cocos/ui/richText.ts+ * @brief `RichText`: a view on the engine's `Text` with markup on.+ *+ * Nothing here parses markup. A `RichText` is a `Text` whose `richText` flag is set, and the string a script writes —+ * `<color=#ff0000>hit</color> <b>crit</b><br/>` — is handed to the engine's own rich-text parser, which reads the tags Cocos's+ * rich text uses. Tags the renderer cannot draw (underline, outline, click) keep their text and lose their style.+ */+import { Text, type TextData } from '../../ui/core/text';+import type { World } from '../../ecs/world';+import type { Entity } from '../../types';+import { Color } from '../math';+import { registerBuiltinComponent } from '../builtins';+import { TextView } from './label';+import { toCocosColor, toEngineColor, viewAdapter } from './view';++export class RichText extends TextView {+ /** Kept so a script can read back what it set; the engine draws text, not touch handlers. */+ handleTouchEvent = true;++ get string(): string { return this.text_().content; }+ set string(v: string) { this.patch_({ content: v === undefined || v === null ? '' : String(v) }); }++ get fontSize(): number { return this.text_().fontSize; }+ set fontSize(v: number) {+ const t = this.text_();+ const px = t.lineHeight * t.fontSize;+ this.patch_({ fontSize: v, lineHeight: v > 0 ? px / v : t.lineHeight });+ }++ 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 fontColor(): Color { return toCocosColor(this.text_().color); }+ set fontColor(v: Color) { this.patch_({ color: toEngineColor(v) }); }++ get horizontalAlign(): number { return this.text_().align; }+ set horizontalAlign(v: number) { this.patch_({ align: v as TextData['align'] }); }++ /** The width at which lines wrap; 0 means they do not. */+ get maxWidth(): number { const t = this.text_(); return t.wordWrap ? t.boxWidth : 0; }+ set maxWidth(v: number) { this.patch_(v > 0 ? { wordWrap: true, boxWidth: v } : { wordWrap: false }); }++ get enabled(): boolean { return this.text_().enabled; }+ set enabled(v: boolean) { this.patch_({ enabled: v }); }+}++const isRich = (world: World, entity: Entity): boolean => world.has(entity, Text) && world.get(entity, Text).richText;+const addRich = (world: World, entity: Entity): void => {+ if (world.has(entity, Text)) world.set(entity, Text, { ...world.get(entity, Text), richText: true });+ else world.insert(entity, Text, { richText: true });+};++registerBuiltinComponent(RichText, ['cc.RichText', 'RichText'], viewAdapter(RichText, isRich, addRich));diff --git a/sdk/src/cocos/ui/screen.ts b/sdk/src/cocos/ui/screen.tsindex 7a45944f8..0b8b6eee1 100644--- a/sdk/src/cocos/ui/screen.ts+++ b/sdk/src/cocos/ui/screen.ts@@ -10,6 +10,9 @@* (see pass.ts); until it does, it is the size of a typical design resolution so a scene still lays out.*/+import type { UICameraData } from '../../ui/core/ui-camera-info';++let uiCamera: UICameraData | null = null;let width = 960;let height = 640;let generation = 0;@@ -47,3 +50,7 @@ export function onScreenChange(listener: (kind: 'visible' | 'window') => void):listeners.push(listener);return () => { const i = listeners.indexOf(listener); if (i >= 0) listeners.splice(i, 1); };}++/** The UI camera's data as of the last frame (the live object the frame loop keeps current), for the conversions a camera offers. */+export function setUiCameraData(data: UICameraData | null): void { uiCamera = data; }+export function uiCameraData(): UICameraData | null { return uiCamera; }diff --git a/sdk/src/ui/text/rich-text-parser.ts b/sdk/src/ui/text/rich-text-parser.tsindex ad19d6a72..738e7a28f 100644--- a/sdk/src/ui/text/rich-text-parser.ts+++ b/sdk/src/ui/text/rich-text-parser.ts@@ -38,6 +38,18 @@ interface StyleFrame {const TAG_COLOR_RE = /^color=(#[0-9a-fA-F]{6,8})$/;const TAG_FONT_SIZE_RE = /^font\s+size=(?:"(\d+)"|(\d+))$/;+/** `<size=24>`: the same as `<font size=24>`, in the spelling Cocos Creator's rich text uses. */+const TAG_SIZE_RE = /^size=(?:"(\d+)"|'(\d+)'|(\d+))$/;+/** `<color=red>`: a colour by name, as well as by hex. */+const TAG_COLOR_NAME_RE = /^color=(?:"([a-zA-Z]+)"|'([a-zA-Z]+)'|([a-zA-Z]+))$/;+/** Tags that mark text this renderer cannot style (underline, strike, outline) or react to (`<on click>`): the tag is consumed and its text kept. */+const TAG_INERT_OPEN_RE = /^(?:u|s|outline(?:\s[^>]*)?|on(?:\s[^>]*)?)$/;+const TAG_INERT_CLOSE = new Set(['/u', '/s', '/outline', '/on']);++const NAMED_COLORS: Readonly<Record<string, string>> = {+ black: '#000000', white: '#ffffff', red: '#ff0000', green: '#00ff00', blue: '#0000ff', yellow: '#ffff00', cyan: '#00ffff',+ magenta: '#ff00ff', orange: '#ffa500', gray: '#808080', grey: '#808080', purple: '#800080', pink: '#ffc0cb', brown: '#a52a2a',+};function parseHexColor(hex: string): Color | null {if (hex.length !== 7 && hex.length !== 9) return null;@@ -119,7 +131,18 @@ export function parseRichText(input: string): RichTextRun[] {emitTextRun(runs, buffer, current);buffer = '';stack.push({ ...current, italic: true });- } else if (tagContent === '/b' || tagContent === '/i' || tagContent === '/color' || tagContent === '/font') {+ } else if (tagContent === '/b' || tagContent === '/i' || tagContent === '/color' || tagContent === '/font' || tagContent === '/size') {+ emitTextRun(runs, buffer, current);+ buffer = '';+ if (stack.length > 1) stack.pop();+ } else if (tagContent === 'br' || tagContent === 'br/' || tagContent === 'br /') {+ buffer += '\n';+ } else if (TAG_INERT_OPEN_RE.test(tagContent)) {+ // keep the text; the style (or the click) is not something this renderer has+ emitTextRun(runs, buffer, current);+ buffer = '';+ stack.push({ ...current });+ } else if (TAG_INERT_CLOSE.has(tagContent)) {emitTextRun(runs, buffer, current);buffer = '';if (stack.length > 1) stack.pop();@@ -136,9 +159,13 @@ export function parseRichText(input: string): RichTextRun[] {}} else {const colorMatch = tagContent.match(TAG_COLOR_RE);- const parsed = colorMatch ? parseHexColor(colorMatch[1]) : null;+ const nameMatch = colorMatch ? null : tagContent.match(TAG_COLOR_NAME_RE);+ const named = nameMatch ? NAMED_COLORS[(nameMatch[1] ?? nameMatch[2] ?? nameMatch[3]).toLowerCase()] : undefined;+ const parsed = colorMatch ? parseHexColor(colorMatch[1]) : named ? parseHexColor(named) : null;const fontSizeMatch = tagContent.match(TAG_FONT_SIZE_RE);- const parsedSize = fontSizeMatch ? parseInt(fontSizeMatch[1] ?? fontSizeMatch[2], 10) : NaN;+ const sizeMatch = fontSizeMatch ? null : tagContent.match(TAG_SIZE_RE);+ const parsedSize = fontSizeMatch ? parseInt(fontSizeMatch[1] ?? fontSizeMatch[2], 10)+ : sizeMatch ? parseInt(sizeMatch[1] ?? sizeMatch[2] ?? sizeMatch[3], 10) : NaN;if (parsed) {emitTextRun(runs, buffer, current);diff --git a/sdk/tests/RichTextParser.test.ts b/sdk/tests/RichTextParser.test.tsindex 58c8b8dde..a55ba5f2e 100644--- a/sdk/tests/RichTextParser.test.ts+++ b/sdk/tests/RichTextParser.test.ts@@ -134,3 +134,41 @@ describe('parseRichText – <font> tag', () => {expect(fullText).toContain('text');});});++describe('parseRichText – the tags Cocos Creator\'s rich text writes', () => {+ const text = (runs: RichTextRun[]): string[] => runs.filter((r) => r.type === 'text').map((r) => (r as { text: string }).text);++ it('reads <size=N> as a font size, and </size> ends it', () => {+ const runs = parseRichText('a<size=30>b</size>c');+ expect(text(runs)).toEqual(['a', 'b', 'c']);+ expect(runs.map((r) => (r as { fontSize: number | null }).fontSize)).toEqual([null, 30, null]);+ });++ it('reads a colour by name as well as by hex', () => {+ const runs = parseRichText('<color=red>x</color><color=#00ff00>y</color><color=Blue>z</color>');+ const colors = runs.map((r) => (r as { color: { r: number; g: number; b: number } | null }).color);+ expect(colors[0]).toMatchObject({ r: 1, g: 0, b: 0 });+ expect(colors[1]).toMatchObject({ r: 0, g: 1, b: 0 });+ expect(colors[2]).toMatchObject({ r: 0, g: 0, b: 1 });+ });++ it('does not take an unknown colour name for markup: it stays as text', () => {+ expect(text(parseRichText('<color=nonesuch>x</color>')).join('')).toContain('<color=nonesuch>');+ });++ it('turns <br/> into a line break', () => {+ expect(text(parseRichText('a<br/>b')).join('')).toBe('a\nb');+ expect(text(parseRichText('a<br>b')).join('')).toBe('a\nb');+ });++ it('keeps the text of tags it cannot style (underline, strike, outline, click) and drops the tag', () => {+ expect(text(parseRichText('<u>under</u> <s>gone</s> <outline color=black width=2>edge</outline> <on click="go">tap</on>')).join(''))+ .toBe('under gone edge tap');+ });++ it('still styles text inside a tag it cannot style', () => {+ const runs = parseRichText('<u><b>both</b></u>');+ expect(text(runs)).toEqual(['both']);+ expect((runs[0] as { bold: boolean }).bold).toBe(true);+ });+});diff --git a/sdk/tests/cocos/camera-richtext-wasm.test.ts b/sdk/tests/cocos/camera-richtext-wasm.test.tsnew file mode 100644index 000000000..c2934caf6--- /dev/null+++ b/sdk/tests/cocos/camera-richtext-wasm.test.ts@@ -0,0 +1,208 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file `Camera` and `RichText`, and the two kinds of place a touch has, against the real engine.+ *+ * A camera's settings are the engine camera's under Cocos's names; its conversions go through the UI camera, so a touch's SCREEN+ * point (`getLocation`) converts to the world point under the finger and back. A `RichText` is a `Text` with markup on, and the+ * markup is the engine's parser's to read.+ */+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';+import type { ESEngineModule } from '../../src/wasm';+import { App, flushPendingRegistrations } from '../../src/app/app';+import { Camera as EngineCamera, Transform, ensureBuiltinComponentsRegistered } from '../../src/ecs/component';+import { AppContext, setDefaultContext } from '../../src/ecs/context';+import { InputState } from '../../src/input/input';+import { Text } from '../../src/ui/core/text';+import { parseRichText } from '../../src/ui/text/rich-text-parser';+import { resetClassRegistry } from '../../src/cocos/registry';+import { declareBuiltinScripts } from '../../src/cocos/builtinScripts';+import { Camera, Color, EventTouch, Node, RichText, UITransform, Vec3, pumpTouches, setCurrentWorld } from '../../src/cocos';+import { setUiCameraData } from '../../src/cocos/ui/screen';+import { HAS_WASM, loadWasmModule } from '../helpers/loadWasm';++// An orthographic view 800 x 600 pixels showing world x in -400..400, y in -300..300: the screen point (400, 300) is the world origin.+const toWorld = (glX: number, glY: number) => ({ x: glX - 400, y: glY - 300 });+vi.mock('../../src/ui/util/ui-pick', () => ({ screenToUiWorld: (_cam: unknown, glX: number, glY: number) => toWorld(glX, glY) }));+vi.mock('../../src/ui/util/math', async (orig) => {+ const real = await orig<typeof import('../../src/ui/util/math')>();+ return { ...real, projectWorldPoint: (wx: number, wy: number) => ({ x: wx + 400, y: wy + 300, clipW: 1 }) };+});++describe.skipIf(!HAS_WASM)('Camera, RichText and touch locations', () => {+ let module: ESEngineModule;+ let registry: InstanceType<ESEngineModule['Registry']> | undefined;+ let app: App | undefined;++ beforeAll(async () => { ensureBuiltinComponentsRegistered(); module = await loadWasmModule(); });+ afterEach(() => {+ setUiCameraData(null);+ setCurrentWorld(null);+ app?.world.disconnectCpp();+ registry?.delete();+ app = undefined;+ registry = undefined;+ });++ function boot(): void {+ setDefaultContext(new AppContext());+ ensureBuiltinComponentsRegistered();+ resetClassRegistry();+ declareBuiltinScripts();+ registry = new module.Registry();+ app = App.new();+ app.connectCpp(registry as never, module);+ flushPendingRegistrations(app);+ setCurrentWorld(app.world);+ setUiCameraData({ valid: true, screenH: 600, viewProjection: new Float32Array(16), vpX: 0, vpY: 0, vpW: 800, vpH: 600 } as never);+ }+ const node = (name: string): Node => { const n = new Node(name); app!.world.insert(n._entity, Transform); return n; };++ describe('Camera', () => {+ it('is the engine camera under Cocos\'s names', () => {+ boot();+ const n = node('cam');+ const cam = n.addComponent(Camera)!;+ expect(app!.world.has(n._entity, EngineCamera)).toBe(true);+ cam.orthoHeight = 320;+ cam.fov = 50;+ cam.near = 2;+ cam.far = 500;+ cam.priority = 3;+ cam.visibility = 0b1010;+ const d = app!.world.get(n._entity, EngineCamera);+ expect([d.orthoSize, d.fov, d.nearPlane, d.farPlane, d.priority, d.cullingMask]).toEqual([320, 50, 2, 500, 3, 10]);+ expect([cam.orthoHeight, cam.visibility]).toEqual([320, 10]);+ });++ it('numbers the projection kinds the way Cocos does, the other way round from the engine', () => {+ boot();+ const n = node('cam');+ const cam = n.addComponent(Camera)!;+ cam.projection = Camera.ProjectionType.ORTHO;+ expect(app!.world.get(n._entity, EngineCamera).projectionType).toBe(1);+ expect(cam.projection).toBe(Camera.ProjectionType.ORTHO);+ cam.projection = Camera.ProjectionType.PERSPECTIVE;+ expect(app!.world.get(n._entity, EngineCamera).projectionType).toBe(0);+ expect(cam.projection).toBe(Camera.ProjectionType.PERSPECTIVE);+ });++ it('maps the viewport to rect and the active flag to enabled', () => {+ boot();+ const n = node('cam');+ const cam = n.addComponent(Camera)!;+ cam.rect = { x: 0.25, y: 0, width: 0.5, height: 1 } as never;+ const v = app!.world.get(n._entity, EngineCamera).viewport;+ expect([v.x, v.y, v.z, v.w]).toEqual([0.25, 0, 0.5, 1]);+ cam.enabled = false;+ expect(app!.world.get(n._entity, EngineCamera).isActive).toBe(false);+ });++ it('converts a screen point to the world under it, and back', () => {+ boot();+ const cam = node('cam').addComponent(Camera)!;+ const world = cam.screenToWorld(new Vec3(500, 350, 0));+ expect([world.x, world.y]).toEqual([100, 50]);+ const screen = cam.worldToScreen(new Vec3(100, 50, 0));+ expect([screen.x, screen.y]).toEqual([500, 350]);+ });++ it('keeps a clear colour a script set, without applying it', () => {+ boot();+ const cam = node('cam').addComponent(Camera)!;+ cam.clearColor = new Color(10, 20, 30, 255);+ expect([cam.clearColor.r, cam.clearColor.g, cam.clearColor.b]).toEqual([10, 20, 30]);+ });++ it('converts a world point into a node\'s own space', () => {+ boot();+ const cam = node('cam').addComponent(Camera)!;+ const panel = node('panel');+ panel.addComponent(UITransform)!.setContentSize(100, 100);+ panel.setPosition(200, 100, 0);+ const local = cam.convertToUINode(new Vec3(230, 90, 0), panel);+ expect([local.x, local.y]).toEqual([30, -10]);+ });+ });++ describe('touch locations', () => {+ it('gives the screen point from getLocation and the canvas point from getUILocation', () => {+ boot();+ const input = new InputState();+ const seen: Array<{ screen: number[]; ui: number[] }> = [];+ const n = node('target');+ n.addComponent(UITransform)!.setContentSize(2000, 2000);+ n.on(Node.EventType.TOUCH_START, (e: EventTouch) => {+ seen.push({ screen: [e.getLocationX(), e.getLocationY()], ui: [e.getUILocationX(), e.getUILocationY()] });+ });+ // a pointer at CSS (500, 250) with the surface 600 high: GL y = 600 - 250 = 350+ const p = { id: 1, x: 500, y: 250 };+ input.touches.set(1, p);+ input.touchesStarted.set(1, p);+ pumpTouches(app!.world, input, { valid: true, screenH: 600 } as never);+ expect(seen).toEqual([{ screen: [500, 350], ui: [100, 50] }]);+ });++ it('hands a camera the touch\'s screen point and gets the canvas point back', () => {+ boot();+ const cam = node('cam').addComponent(Camera)!;+ const input = new InputState();+ let converted: Vec3 | null = null;+ const n = node('target');+ n.addComponent(UITransform)!.setContentSize(2000, 2000);+ n.on(Node.EventType.TOUCH_START, (e: EventTouch) => {+ const l = e.getLocation();+ converted = cam.screenToWorld(new Vec3(l.x, l.y, 0));+ expect(converted.x).toBe(e.getUILocationX());+ expect(converted.y).toBe(e.getUILocationY());+ });+ const p = { id: 1, x: 120, y: 80 };+ input.touches.set(1, p);+ input.touchesStarted.set(1, p);+ pumpTouches(app!.world, input, { valid: true, screenH: 600 } as never);+ expect(converted).not.toBeNull();+ });+ });++ describe('RichText', () => {+ it('is a Text with markup on, found as a RichText and writes its string through', () => {+ boot();+ const n = node('rich');+ const rt = n.addComponent(RichText)!;+ expect(app!.world.get(n._entity, Text).richText).toBe(true);+ rt.string = '<color=red>hit</color><br/><size=40>big</size>';+ expect(app!.world.get(n._entity, Text).content).toBe('<color=red>hit</color><br/><size=40>big</size>');+ expect(n.getComponent(RichText)).toBe(rt);+ });++ it('hands the engine\'s parser the markup it writes, and the parser reads it', () => {+ const runs = parseRichText('<color=red>hit</color><br/><size=40>big</size>');+ const text = runs.map((r) => (r.type === 'text' ? r.text : '')).join('');+ expect(text).toBe('hit\nbig');+ });++ it('keeps line height in pixels across a size change, and wraps at maxWidth when it is set', () => {+ boot();+ const n = node('rich');+ const rt = n.addComponent(RichText)!;+ rt.fontSize = 20;+ rt.lineHeight = 30;+ rt.fontSize = 40;+ expect(rt.lineHeight).toBeCloseTo(30, 5);+ expect(rt.maxWidth).toBe(0);+ rt.maxWidth = 300;+ const t = app!.world.get(n._entity, Text);+ expect([t.wordWrap, t.boxWidth]).toEqual([true, 300]);+ expect(rt.maxWidth).toBe(300);+ rt.maxWidth = 0;+ expect(app!.world.get(n._entity, Text).wordWrap).toBe(false);+ });++ it('reads a plain Text that is not rich as no RichText', () => {+ boot();+ const n = node('plain');+ app!.world.insert(n._entity, Text, {});+ expect(n.getComponent(RichText)).toBeNull();+ });+ });+});