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): Graphics is a component over the engine Draw (rect, circle and stroked paths kept until clear), UIMeshRenderer folds into its host, and a Node has worldScale and worldRotation
yhh3ac95ed2316a
diff --git a/pipeline/src/import/cocos/components.ts b/pipeline/src/import/cocos/components.tsindex 8a491e2aa..7aaf83315 100644--- a/pipeline/src/import/cocos/components.ts+++ b/pipeline/src/import/cocos/components.ts@@ -630,6 +630,14 @@ function meshRenderer(c: CocosComponent, ctx: ComponentContext, where: string):return { component: { type: 'MeshRenderer', data }, partial };}+/** `cc.Graphics`: the style a scene stores; what is drawn is what scripts draw with it. */+function graphics(c: CocosComponent): ComponentData {+ return {+ type: `${LAYER}Graphics`,+ data: renamed(c, { _lineWidth: 'lineWidth', _lineJoin: 'lineJoin', _lineCap: 'lineCap', _miterLimit: 'miterLimit', _strokeColor: 'strokeColor', _fillColor: 'fillColor' }),+ };+}+/** `cc.UIOpacity`: the alpha of the node and everything under it, which the engine's GroupOpacity is. */function uiOpacity(c: CocosComponent, ctx: ComponentContext): ComponentData {ctx.report.component('cc.UIOpacity', 'mapped');@@ -659,7 +667,7 @@ function script(c: CocosComponent, ctx: ComponentContext): ComponentData | null}/** Components that are folded into another, or carry nothing of their own. */-const FOLDED = new Set(['cc.UITransform', 'cc.LabelOutline', 'cc.LabelShadow', 'cc.Canvas']);+const FOLDED = new Set(['cc.UITransform', 'cc.LabelOutline', 'cc.LabelShadow', 'cc.Canvas', 'cc.UIMeshRenderer']);export interface ConvertedNode {components: ComponentData[];@@ -753,6 +761,9 @@ export function convertNode(node: CocosNode, ctx: ComponentContext, where: strincase 'cc.SkeletalAnimation':out = skeletalAnimation(c, node, ctx, where);break;+ case 'cc.Graphics':+ out = graphics(c);+ break;case 'cc.UIOpacity':out = uiOpacity(c, ctx);break;@@ -773,7 +784,7 @@ export function convertNode(node: CocosNode, ctx: ComponentContext, where: strin}if (FOLDED.has(c.type)) {// A canvas carries nothing of its own here: the design resolution is the scene's, and its camera is a component of its own.- const host = c.type === 'cc.UITransform' || c.type === 'cc.Canvas' ? true : node.components.some((s) => s.type === 'cc.Label');+ const host = c.type === 'cc.UITransform' || c.type === 'cc.Canvas' || c.type === 'cc.UIMeshRenderer' ? true : node.components.some((s) => s.type === 'cc.Label');if (host) {ctx.report.component(c.type, 'mapped');continue;diff --git a/sdk/src/cocos/index.ts b/sdk/src/cocos/index.tsindex 40809cf93..b5f2b555f 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, Camera, RichText, Mask, Toggle, ToggleContainer, ProgressBar, Slider, BlockInputEvents, ScrollView, getVisibleSize, setVisibleSize } from './ui';+export { UITransform, Label, LabelOutline, LabelShadow, Sprite, UIOpacity, Button, EventHandler, Widget, Layout, Camera, RichText, Mask, Toggle, ToggleContainer, ProgressBar, Slider, BlockInputEvents, ScrollView, Graphics, getVisibleSize, setVisibleSize } from './ui';export { Touch, EventTouch } from './input';export { tween, Tween, tweenUtil, easing, updateTweens } from './tween';export { instantiate, loadPrefab, providePrefab } from './prefabs';diff --git a/sdk/src/cocos/node.ts b/sdk/src/cocos/node.tsindex 3dfe1f63c..d60dcda4c 100644--- a/sdk/src/cocos/node.ts+++ b/sdk/src/cocos/node.ts@@ -255,6 +255,8 @@ export class Node {get angle(): number { return this.eulerAngles.z; }set angle(degrees: number) { const e = this.eulerAngles; this.setRotationFromEuler(e.x, e.y, degrees); }+ get worldScale(): Vec3 { const s = this.composedTransform_().worldScale; return new Vec3(s.x, s.y, s.z); }+ get worldRotation(): Quat { const q = this.composedTransform_().worldRotation; return new Quat(q.x, q.y, q.z, q.w); }get worldPosition(): Vec3 { const p = this.composedTransform_().worldPosition; return new Vec3(p.x, p.y, p.z); }set worldPosition(v: Vec3) { this.setWorldPosition(v); }getWorldPosition(out?: Vec3): Vec3 { const p = this.composedTransform_().worldPosition; return (out ?? new Vec3()).set(p.x, p.y, p.z); }diff --git a/sdk/src/cocos/ui/graphics.ts b/sdk/src/cocos/ui/graphics.tsnew file mode 100644index 000000000..fe12069d7--- /dev/null+++ b/sdk/src/cocos/ui/graphics.ts@@ -0,0 +1,247 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file cocos/ui/graphics.ts+ * @brief `Graphics`: the path-drawing component, over the engine's immediate `Draw`.+ *+ * A scene stores only a Graphics' style (line width, colours); its picture is what scripts draw with `moveTo`, `lineTo`, `rect`, `circle`,+ * `stroke` and `fill`, and Cocos keeps that picture until `clear()`. So this keeps the recorded drawing and plays it into the engine's `Draw`+ * every frame, in the node's place. What `Draw` can paint, this paints: lines at a width, filled rectangles and circles. A filled path of any other+ * shape is counted (and said once), not drawn — the engine has no polygon fill, and guessing one would draw the wrong thing.+ */+import { Component } from '../component';+import { Color, Vec2 } from '../math';+import { declareClass } from '../host';+import { Draw } from '../../render/draw';+import { registerScopedDrawCallback, unregisterDrawCallback } from '../../render/customDraw';+import type { CppRegistry } from '../../wasm';+import { log } from '../../util/logger';++interface Subpath {+ points: Vec2[];+ closed: boolean;+ /** Set when the subpath is exactly a rectangle or a circle, which can be filled. */+ shape?: { kind: 'rect'; x: number; y: number; w: number; h: number } | { kind: 'circle'; x: number; y: number; r: number };+}++interface Op {+ kind: 'stroke' | 'fill';+ paths: Subpath[];+ color: Color;+ width: number;+}++const SEGMENTS_PER_CURVE = 16;+let ids = 0;++const toEngine = (c: Color): { r: number; g: number; b: number; a: number } => ({ r: c.r / 255, g: c.g / 255, b: c.b / 255, a: c.a / 255 });++export class Graphics extends Component {+ static readonly LineJoin = Object.freeze({ BEVEL: 0, ROUND: 1, MITER: 2 });+ static readonly LineCap = Object.freeze({ BUTT: 0, ROUND: 1, SQUARE: 2 });++ lineWidth = 1;+ lineJoin = 2;+ lineCap = 0;+ miterLimit = 10;+ strokeColor: Color = new Color(0, 0, 0, 255);+ fillColor: Color = new Color(255, 255, 255, 255);++ private path_: Subpath[] = [];+ private cursor_: Vec2 | null = null;+ private drawn_ = false;+ private ops_: Op[] = [];+ private callback_: string | null = null;+ private warned_ = false;++ // ---- building a path ---------------------------------------------------------------------------------------------++ private current_(): Subpath {+ // A path begun after something was drawn is a new one: the earlier shapes are on the canvas, not in the path.+ if (this.drawn_) { this.path_ = []; this.drawn_ = false; }+ let sub = this.path_[this.path_.length - 1];+ if (!sub || sub.closed || sub.shape) {+ sub = { points: this.cursor_ ? [this.cursor_] : [], closed: false };+ this.path_.push(sub);+ }+ return sub;+ }++ moveTo(x: number, y: number): void {+ if (this.drawn_) { this.path_ = []; this.drawn_ = false; }+ this.cursor_ = new Vec2(x, y);+ this.path_.push({ points: [this.cursor_], closed: false });+ }++ lineTo(x: number, y: number): void {+ const sub = this.current_();+ this.cursor_ = new Vec2(x, y);+ sub.points.push(this.cursor_);+ }++ bezierCurveTo(c1x: number, c1y: number, c2x: number, c2y: number, x: number, y: number): void {+ const sub = this.current_();+ const from = sub.points[sub.points.length - 1] ?? new Vec2(c1x, c1y);+ for (let i = 1; i <= SEGMENTS_PER_CURVE; i++) {+ const t = i / SEGMENTS_PER_CURVE, u = 1 - t;+ sub.points.push(new Vec2(+ u * u * u * from.x + 3 * u * u * t * c1x + 3 * u * t * t * c2x + t * t * t * x,+ u * u * u * from.y + 3 * u * u * t * c1y + 3 * u * t * t * c2y + t * t * t * y));+ }+ this.cursor_ = new Vec2(x, y);+ }++ quadraticCurveTo(cx: number, cy: number, x: number, y: number): void {+ const sub = this.current_();+ const from = sub.points[sub.points.length - 1] ?? new Vec2(cx, cy);+ for (let i = 1; i <= SEGMENTS_PER_CURVE; i++) {+ const t = i / SEGMENTS_PER_CURVE, u = 1 - t;+ sub.points.push(new Vec2(u * u * from.x + 2 * u * t * cx + t * t * x, u * u * from.y + 2 * u * t * cy + t * t * y));+ }+ this.cursor_ = new Vec2(x, y);+ }++ arc(cx: number, cy: number, r: number, startAngle: number, endAngle: number, counterclockwise: boolean): void {+ const sub = this.current_();+ let sweep = endAngle - startAngle;+ if (counterclockwise && sweep > 0) sweep -= Math.PI * 2;+ if (!counterclockwise && sweep < 0) sweep += Math.PI * 2;+ const steps = Math.max(4, Math.ceil((Math.abs(sweep) / (Math.PI * 2)) * 48));+ for (let i = 0; i <= steps; i++) {+ const a = startAngle + (sweep * i) / steps;+ sub.points.push(new Vec2(cx + Math.cos(a) * r, cy + Math.sin(a) * r));+ }+ this.cursor_ = sub.points[sub.points.length - 1]!;+ }++ private shape_(points: Vec2[], shape: Subpath['shape']): void {+ if (this.drawn_) { this.path_ = []; this.drawn_ = false; }+ this.path_.push({ points, closed: true, shape });+ this.cursor_ = points[0] ?? null;+ }++ rect(x: number, y: number, w: number, h: number): void {+ this.shape_([new Vec2(x, y), new Vec2(x + w, y), new Vec2(x + w, y + h), new Vec2(x, y + h)], { kind: 'rect', x, y, w, h });+ }++ /** A rounded rectangle is drawn as its outline of arcs, and filled as the rectangle it rounds: the engine fills no rounded corner here. */+ roundRect(x: number, y: number, w: number, h: number, r: number): void {+ const radius = Math.min(Math.abs(r), Math.abs(w) / 2, Math.abs(h) / 2);+ const pts: Vec2[] = [];+ const corner = (cx: number, cy: number, from: number): void => {+ for (let i = 0; i <= 8; i++) {+ const a = from + (Math.PI / 2) * (i / 8);+ pts.push(new Vec2(cx + Math.cos(a) * radius, cy + Math.sin(a) * radius));+ }+ };+ corner(x + w - radius, y + radius, -Math.PI / 2);+ corner(x + w - radius, y + h - radius, 0);+ corner(x + radius, y + h - radius, Math.PI / 2);+ corner(x + radius, y + radius, Math.PI);+ this.shape_(pts, radius === 0 ? { kind: 'rect', x, y, w, h } : undefined);+ }++ fillRect(x: number, y: number, w: number, h: number): void {+ this.rect(x, y, w, h);+ this.fill();+ }++ circle(cx: number, cy: number, r: number): void {+ const pts: Vec2[] = [];+ for (let i = 0; i < 48; i++) pts.push(new Vec2(cx + Math.cos((i / 48) * Math.PI * 2) * r, cy + Math.sin((i / 48) * Math.PI * 2) * r));+ this.shape_(pts, { kind: 'circle', x: cx, y: cy, r });+ }++ ellipse(cx: number, cy: number, rx: number, ry: number): void {+ const pts: Vec2[] = [];+ for (let i = 0; i < 48; i++) pts.push(new Vec2(cx + Math.cos((i / 48) * Math.PI * 2) * rx, cy + Math.sin((i / 48) * Math.PI * 2) * ry));+ this.shape_(pts, rx === ry ? { kind: 'circle', x: cx, y: cy, r: rx } : undefined);+ }++ close(): void {+ const sub = this.path_[this.path_.length - 1];+ if (sub && !sub.shape) { sub.closed = true; this.cursor_ = sub.points[0] ?? null; }+ }++ // ---- painting it ---------------------------------------------------------------------------------------------------++ private snapshot_(): Subpath[] {+ return this.path_.filter((p) => p.points.length > 0).map((p) => ({ ...p, points: p.points.map((v) => v.clone()) }));+ }++ stroke(): void {+ this.ops_.push({ kind: 'stroke', paths: this.snapshot_(), color: this.strokeColor.clone(), width: this.lineWidth });+ this.drawn_ = true;+ }++ fill(): void {+ this.ops_.push({ kind: 'fill', paths: this.snapshot_(), color: this.fillColor.clone(), width: 0 });+ this.drawn_ = true;+ }++ clear(): void {+ this.ops_ = [];+ this.path_ = [];+ this.cursor_ = null;+ this.drawn_ = false;+ }++ // ---- into the frame --------------------------------------------------------------------------------------------------++ onEnable(): void {+ const registry = this._world.getCppRegistry() as CppRegistry | null;+ if (!registry || this.callback_) return;+ this.callback_ = `cocos-graphics:${++ids}`;+ registerScopedDrawCallback(this.callback_, registry, () => this.paint_());+ }++ onDisable(): void {+ if (this.callback_) unregisterDrawCallback(this.callback_);+ this.callback_ = null;+ }++ private paint_(): void {+ if (this.ops_.length === 0) return;+ const node = this.node;+ const p = node.worldPosition, s = node.worldScale, q = node.worldRotation;+ // the node's turn about Z, which is all a drawing on a flat scene has+ const angle = 2 * Math.atan2(q.z, q.w);+ const cos = Math.cos(angle), sin = Math.sin(angle);+ const place = (v: Vec2): { x: number; y: number } => {+ const x = v.x * s.x, y = v.y * s.y;+ return { x: p.x + x * cos - y * sin, y: p.y + x * sin + y * cos };+ };+ const scale = (Math.abs(s.x) + Math.abs(s.y)) / 2;+ for (const op of this.ops_) {+ const color = toEngine(op.color);+ if (color.a <= 0) continue;+ for (const sub of op.paths) {+ if (op.kind === 'stroke') {+ const pts = sub.points.map(place);+ const thickness = Math.max(op.width * scale, 1);+ for (let i = 1; i < pts.length; i++) Draw.line(pts[i - 1]!, pts[i]!, color, thickness);+ if (sub.closed && pts.length > 2) Draw.line(pts[pts.length - 1]!, pts[0]!, color, thickness);+ } else if (sub.shape?.kind === 'rect' && Math.abs(angle) < 1e-4) {+ const a = place(new Vec2(sub.shape.x, sub.shape.y)), b = place(new Vec2(sub.shape.x + sub.shape.w, sub.shape.y + sub.shape.h));+ Draw.rect({ x: Math.min(a.x, b.x), y: Math.min(a.y, b.y) }, { x: Math.abs(b.x - a.x), y: Math.abs(b.y - a.y) }, color, true);+ } else if (sub.shape?.kind === 'circle') {+ Draw.circle(place(new Vec2(sub.shape.x, sub.shape.y)), sub.shape.r * scale, color, true, 32);+ } else if (!this.warned_) {+ this.warned_ = true;+ log.warn('cocos', `Graphics.fill() of a path that is not a rectangle or a circle is not drawn (${this.node.name})`);+ }+ }+ }+ }+}++export function declareGraphics(): void {+ declareClass(Graphics as never, 'Graphics', [+ { name: 'lineWidth', kind: 'number' },+ { name: 'lineJoin', kind: 'number' },+ { name: 'lineCap', kind: 'number' },+ { name: 'miterLimit', kind: 'number' },+ { name: 'strokeColor', kind: 'color' },+ { name: 'fillColor', kind: 'color' },+ ]);+}diff --git a/sdk/src/cocos/ui/index.ts b/sdk/src/cocos/ui/index.tsindex 0657f6c18..f820f8563 100644--- a/sdk/src/cocos/ui/index.ts+++ b/sdk/src/cocos/ui/index.ts@@ -16,3 +16,4 @@ export { getVisibleSize, setVisibleSize } from './screen';export { Camera } from './camera';export { RichText } from './richText';export { Mask } from './mask';+export { Graphics } from './graphics';diff --git a/sdk/src/cocos/ui/pass.ts b/sdk/src/cocos/ui/pass.tsindex 617b16d71..758180889 100644--- a/sdk/src/cocos/ui/pass.ts+++ b/sdk/src/cocos/ui/pass.ts@@ -16,6 +16,7 @@ import { setCurrentWorld } from '../node';import { alignAllWidgets, declareWidget } from './widget';import { layoutAll, declareLayout } from './layout';import { declareControls } from './controls';+import { declareGraphics } from './graphics';import { declareScrollView } from './scrollView';import { setUiCameraData, setVisibleSize, setWindowPixels } from './screen';@@ -23,6 +24,7 @@ export function declareUiPass(): void {declareWidget();declareLayout();declareControls();+ declareGraphics();declareScrollView();const system = defineSystem([Res(UICameraInfo), Res(ScreenLayout), GetWorld()],diff --git a/sdk/tests/cocos/graphics-wasm.test.ts b/sdk/tests/cocos/graphics-wasm.test.tsnew file mode 100644index 000000000..4922babf9--- /dev/null+++ b/sdk/tests/cocos/graphics-wasm.test.ts@@ -0,0 +1,112 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file Graphics: a script draws a path and keeps it until `clear()`; each frame it is played into the engine's `Draw`, in the node's place.+ */+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';+import type { ESEngineModule } from '../../src/wasm';+import { Transform, ensureBuiltinComponentsRegistered } from '../../src/ecs/component';+import { Color, Graphics, Node, Vec3 } from '../../src/cocos';+import { clearDrawCallbacks, getDrawCallbacks } from '../../src/render/customDraw';+import { HAS_WASM, loadWasmModule } from '../helpers/loadWasm';+import { pointerApp, type PointerApp } from './helpers/pointerApp';++const calls: Array<{ op: string; args: any[] }> = [];+vi.mock('../../src/render/draw', () => ({+ Draw: new Proxy({}, { get: (_t, op: string) => (...args: unknown[]) => { calls.push({ op, args }); } }),+}));++describe.skipIf(!HAS_WASM)('Graphics', () => {+ let module: ESEngineModule;+ let P: PointerApp | undefined;++ beforeAll(async () => { ensureBuiltinComponentsRegistered(); module = await loadWasmModule(); });+ beforeEach(() => { calls.length = 0; });+ afterEach(() => { clearDrawCallbacks(); P?.dispose(); P = undefined; });++ async function graphics(x = 0, y = 0, scale = 1): Promise<{ node: Node; g: Graphics }> {+ P = pointerApp(module);+ const node = new Node('g');+ P.app.world.insert(node._entity, Transform);+ node.setPosition(x, y, 0);+ node.setScale(new Vec3(scale, scale, 1));+ const g = node.addComponent<Graphics>('Graphics')!;+ await P.frame(1);+ return { node, g };+ }++ /** Play the frame's draw callbacks, as the renderer does. */+ const paint = (): void => { calls.length = 0; for (const entry of getDrawCallbacks().values()) entry.fn(); };++ it('fills a rectangle where its node is', async () => {+ const { g } = await graphics(100, 50);+ g.fillColor = new Color(255, 0, 0, 255);+ g.rect(0, 0, 20, 10);+ g.fill();+ paint();+ expect(calls).toHaveLength(1);+ expect(calls[0]!.op).toBe('rect');+ expect(calls[0]!.args[0]).toEqual({ x: 100, y: 50 });+ expect(calls[0]!.args[1]).toEqual({ x: 20, y: 10 });+ expect(calls[0]!.args[2]).toMatchObject({ r: 1, g: 0, b: 0, a: 1 });+ });++ it('keeps what it drew until it is cleared, and draws it again every frame', async () => {+ const { g } = await graphics();+ g.circle(0, 0, 10);+ g.fill();+ paint();+ paint();+ expect(calls.map((c) => c.op)).toEqual(['circle']);+ g.clear();+ paint();+ expect(calls).toEqual([]);+ });++ it('strokes a path as lines of the stroke colour and width, scaled with the node', async () => {+ const { g } = await graphics(0, 0, 2);+ g.lineWidth = 3;+ g.strokeColor = new Color(0, 255, 0, 255);+ g.moveTo(0, 0);+ g.lineTo(10, 0);+ g.lineTo(10, 10);+ g.stroke();+ paint();+ expect(calls.map((c) => c.op)).toEqual(['line', 'line']);+ expect(calls[0]!.args[1]).toEqual({ x: 20, y: 0 });+ expect(calls[0]!.args[3]).toBe(6);+ expect(calls[1]!.args[1]).toEqual({ x: 20, y: 20 });+ });++ it('closes a path back to its start', async () => {+ const { g } = await graphics();+ g.moveTo(0, 0);+ g.lineTo(10, 0);+ g.lineTo(0, 10);+ g.close();+ g.stroke();+ paint();+ expect(calls).toHaveLength(3);+ });++ it('starts a new path after something was drawn, so earlier shapes are not drawn again', async () => {+ const { g } = await graphics();+ g.rect(0, 0, 5, 5);+ g.fill();+ g.rect(20, 0, 5, 5);+ g.fill();+ paint();+ expect(calls.map((c) => c.op)).toEqual(['rect', 'rect']);+ expect(calls[1]!.args[0]).toEqual({ x: 20, y: 0 });+ });++ it('stops drawing when it is disabled', async () => {+ const { g } = await graphics();+ g.rect(0, 0, 5, 5);+ g.fill();+ g.enabled = false;+ await P!.frame(1); // the lifecycle runs with the frame+ paint();+ expect(calls).toEqual([]);+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 856e01f08..81bdaeb2d 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';* the reader recognises anyway.*/export const NOTED = {+ 'feat(cocos): Graphics is a component over the engine Draw (rect, circle and stroked paths kept until clear), UIMeshRenderer folds into its host, and a Node has worldScale and worldRotation':+ {"internal":"The Cocos Creator compatibility layer and importer have not shipped; nothing a creator reaches without opting in."},'feat(animation): an animator state can play at the speed of a float parameter (speedParameter), and the Cocos animation graph is converted to an animator controller':{"note":"An animator state can play at the speed of a parameter."},'feat(cocos): the importer converts Animation clips (.anim) to timelines: position, scale, rotation, sprite and label colour, opacity and active tracks, and plays model-file clips on the node':