Skip to content

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

feat(cocos): a sprite, a label and a graphics are UIRenderers, which accept the rebuild requests scripts send

yhh2cbbf8de3cf9
diff --git a/desktop b/desktop
index e0b35125d..bb747d95b 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit e0b35125dc714b379a9071e4cea08d3b8f42b527
+Subproject commit bb747d95bfbb0183eb484804e50ea730495391ae
diff --git a/sdk/src/cocos/index.ts b/sdk/src/cocos/index.ts
index 561c5edbc..980359972 100644
--- a/sdk/src/cocos/index.ts
+++ b/sdk/src/cocos/index.ts
@@ -30,6 +30,7 @@ export { registerBuiltinComponent, type BuiltinAdapter } from './builtins';
export { unsupported } from './unsupported';
export { ccenum, js, NodePool, profiler } from './misc';
export { MeshRenderer, ModelRenderer, UIMeshRenderer } from './meshRenderer';
+export { UIRenderer } from './ui/renderer';
export { geometry } from './geometry';
export { UITransform, Label, LabelOutline, LabelShadow, Sprite, UIOpacity, Button, EventHandler, Widget, Layout, Camera, RichText, Mask, Toggle, ToggleContainer, ProgressBar, Slider, BlockInputEvents, ScrollView, Graphics, Line, EditBox, PageView, PageViewIndicator, ScrollBar, SafeArea, WebView, getVisibleSize, setVisibleSize } from './ui';
export { Touch, EventTouch } from './input';
diff --git a/sdk/src/cocos/ui/graphics.ts b/sdk/src/cocos/ui/graphics.ts
index 69a7418a7..dd9933278 100644
--- a/sdk/src/cocos/ui/graphics.ts
+++ b/sdk/src/cocos/ui/graphics.ts
@@ -10,6 +10,7 @@
* sorted and batched like any mesh and moves with the node. Nothing is redrawn per frame; the geometry is rebuilt on the frame after a change.
*/
import { Component } from '../component';
+import { UIRenderer } from './renderer';
import { Color, Vec2 } from '../math';
import { declareClass } from '../host';
import { Schedule, defineSystem, addSystemToSchedule } from '../../ecs/system';
@@ -43,7 +44,7 @@ const toColor = (c: Color): PathColor => [c.r / 255, c.g / 255, c.b / 255, c.a /
/** The engine's geometry API, handed over by the frame (a component has no app to ask). */
let meshApi: MeshRendererAPI | null = null;
-export class Graphics extends Component {
+export class Graphics extends UIRenderer {
static readonly LineJoin = Object.freeze({ BEVEL: 0, ROUND: 1, MITER: 2 });
static readonly LineCap = Object.freeze({ BUTT: 0, ROUND: 1, SQUARE: 2 });
diff --git a/sdk/src/cocos/ui/label.ts b/sdk/src/cocos/ui/label.ts
index edad52e12..8150db723 100644
--- a/sdk/src/cocos/ui/label.ts
+++ b/sdk/src/cocos/ui/label.ts
@@ -13,6 +13,7 @@ import type { World } from '../../ecs/world';
import type { Entity } from '../../types';
import { Color } from '../math';
import { Component } from '../component';
+import { UIRenderer } from './renderer';
import { registerBuiltinComponent } from '../builtins';
import { toCocosColor, toEngineColor, viewAdapter } from './view';
@@ -37,7 +38,7 @@ function toCocosOverflow(engine: number): number {
}
/** The `Text` data of an entity: the thing every property below reads and writes. */
-export class TextView extends Component {
+export class TextView extends UIRenderer {
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/renderer.ts b/sdk/src/cocos/ui/renderer.ts
new file mode 100644
index 000000000..c25708197
--- /dev/null
+++ b/sdk/src/cocos/ui/renderer.ts
@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file cocos/ui/renderer.ts
+ * @brief `UIRenderer`: what every component that draws a 2D UI element is, in Cocos.
+ *
+ * Cocos builds each element's vertices on the CPU and asks to have them rebuilt when something changed; a script that changes how a
+ * label or a sprite is built says so with `markForUpdateRenderData` or `setVertsDirty`. The engine draws from the component's data
+ * as it stands, every frame, so there is nothing to rebuild, and these are accepted and do nothing. They are here so the scripts
+ * that ask are not stopped by the question.
+ */
+import { Component } from '../component';
+
+export class UIRenderer extends Component {
+ /** Ask for the element's vertices to be rebuilt. The engine draws from current data, so there is nothing to rebuild. */
+ markForUpdateRenderData(_enable = true): void { /* drawn from the component's data every frame */ }
+ setVertsDirty(): void { /* see markForUpdateRenderData */ }
+ updateRenderer(): void { /* see markForUpdateRenderData */ }
+ /** Whether the element is waiting for a rebuild: never, here. */
+ get renderEntity(): undefined { return undefined; }
+}
diff --git a/sdk/src/cocos/ui/sprite.ts b/sdk/src/cocos/ui/sprite.ts
index 7c8870c81..3fed1e6c4 100644
--- a/sdk/src/cocos/ui/sprite.ts
+++ b/sdk/src/cocos/ui/sprite.ts
@@ -14,6 +14,7 @@ import type { World } from '../../ecs/world';
import type { Entity } from '../../types';
import { Color } from '../math';
import { Component } from '../component';
+import { UIRenderer } from './renderer';
import { registerBuiltinComponent } from '../builtins';
import { toCocosColor, toEngineColor, viewAdapter } from './view';
@@ -33,7 +34,7 @@ function toCocosType(mode: SpriteDrawMode | undefined): number {
return SpriteType.SIMPLE;
}
-export class Sprite extends Component {
+export class Sprite extends UIRenderer {
static readonly Type = SpriteType;
static readonly SizeMode = SizeMode;
diff --git a/sdk/tests/cocos/misc.test.ts b/sdk/tests/cocos/misc.test.ts
index b9b0c2e52..422584ac5 100644
--- a/sdk/tests/cocos/misc.test.ts
+++ b/sdk/tests/cocos/misc.test.ts
@@ -3,6 +3,7 @@
import { describe, expect, it } from 'vitest';
import { NodePool, ccenum, js, profiler } from '../../src/cocos/misc';
import type { Node } from '../../src/cocos/node';
+import { Graphics, Label, Sprite, UIRenderer } from '../../src/cocos';
/** The parts of a node a pool touches. */
function fakeNode(handler?: { unuse(): void; reuse(args: unknown[]): void }) {
@@ -80,3 +81,14 @@ describe('profiler', () => {
expect(profiler.isShowingStats()).toBe(false);
});
});
+
+describe('UIRenderer', () => {
+ it('is the base of what draws a 2D element, and takes the rebuild requests that scripts send', () => {
+ for (const type of [Sprite, Label, Graphics]) {
+ expect(type.prototype).toBeInstanceOf(UIRenderer);
+ expect(typeof type.prototype.markForUpdateRenderData).toBe('function');
+ }
+ const probe = Object.create(Sprite.prototype) as Sprite;
+ expect(() => { probe.markForUpdateRenderData(); probe.markForUpdateRenderData(false); probe.setVertsDirty(); }).not.toThrow();
+ });
+});