Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(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.mdx
index 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)). |
```typescript
diff --git a/docs/astro/src/content/docs/zh-cn/ui/text.mdx b/docs/astro/src/content/docs/zh-cn/ui/text.mdx
index 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 />` | 内联图片——随文本一起排布的图标(见[下文](#内联图片))。 |
```typescript
diff --git a/pipeline/src/import/cocos/components.ts b/pipeline/src/import/cocos/components.ts
index 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.ts
index 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.ts
index 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: UICameraDat
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 };
+ 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: UICameraDat
if (!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): void
for (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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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();
+ });
+ });
+});