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 document the creator edited moves from the layer Cocos.Widget to the engine RectAnchors on re-import

yhhaa495000ce80
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1d91ddcae..244669500 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,7 @@ published separately; it ships inside the editor.
- **Scroll areas can be pulled past an end and spring back.** A scroll area whose movement is Elastic now does what the setting always said: a drag past an end is stiffer the further out it goes, letting go returns the content, and a flick that reaches an end bounces off it. It is opt-in per area (`ScrollMovement.Elastic`; Clamped, the default, behaves as before), and the gesture model (`ScrollMotion`, with `ScrollContainer.dragTo` and `getOverscroll`) is exported for scrolling anything else the same way.
- **More easing curves.** Sine, quart, quint, expo and circ (each in, out and in-out), bounce in and in-out, and smoothstep and smootherstep join the quad, cubic, back, elastic and out-bounce curves. They are new `EasingType` members after the existing ones, so a saved tween keeps its curve, and they ease the same in a C++ tween and a script value tween.
- **World content has a rectangle: `ContentRect`.** A size and the pivot the entity's transform sits on, which the `Sprite` and `Text` on the entity follow and which a `UIMask` on it clips to — no `UINode` needed, so a clipping region or a scroll viewport can stand in the world. `contentRectContains` tests a world point against it.
+- **Edited Cocos documents move to RectAnchors.** A converted document the creator edited is left as it is on re-import, except that its `Cocos.Widget` components become the engine `RectAnchors` (same fields, no `target`), so a project converted before the change keeps its alignment.
- **RectAnchors: world content that follows its parent.** A new engine component pins content placed by its `Transform` and sized by a `ContentRect` to the edges or centre of its parent rectangle (stretch, pin to an edge, centre with an offset, margins in units or as a fraction), or, with no parent rectangle, to the screen, which is centred on the world origin. An engine system aligns parents before the children that depend on them, in the editor edit mode as well as in play, on ONCE / ON_RESIZE / ALWAYS. The Cocos `Widget` is now a view on it, and a converted project carries `RectAnchors` instead of a compatibility-layer component, so a scene is laid out where the editor shows it. The visible area of the Cocos layer is centred on the origin, as the engine screen is.
- **A converted Cocos project fits the screen as the game does.** The Cocos design fit (fit width, fit height) becomes the project camera scale mode (fixed width, fixed height), so a UI laid out in design units comes out the same size on every screen instead of being drawn at the window pixel size. `cc.profiler` (`showStats`, `hideStats`) is accepted by the compatibility layer.
- **A Cocos node layer is its renderers layer.** The sprites, texts, shapes, spine, particles and meshes of a converted node are put in the layer the node had in Cocos (its bit index), which is what a camera culling mask selects among. A UI camera that draws only layer 25 used to draw none of the sprites left in layer 0, so the converted game launch scene was black.
diff --git a/pipeline/src/import/cocos/importProject.ts b/pipeline/src/import/cocos/importProject.ts
index e89a08a50..7e2bd6831 100644
--- a/pipeline/src/import/cocos/importProject.ts
+++ b/pipeline/src/import/cocos/importProject.ts
@@ -205,6 +205,34 @@ function globalDefiningScripts(assets: CocosAssetIndex): string[] {
return found.sort();
}
+/**
+ * A document the creator edited is left as it is, but it was written when a Cocos widget was a component of the compatibility layer
+ * (`Cocos.Widget`), and is now the engine's `RectAnchors`: the same fields, under the engine's name. Only that name changes, in place;
+ * everything the creator did to the document stays. Answers whether the document held one.
+ */
+function migrateWidgets(file: string): boolean {
+ let text: string;
+ try { text = readFileSync(file, 'utf8'); } catch { return false; }
+ if (!text.includes('"Cocos.Widget"')) return false;
+ let changed = false;
+ const walk = (v: unknown): void => {
+ if (Array.isArray(v)) { v.forEach(walk); return; }
+ if (typeof v !== 'object' || v === null) return;
+ const o = v as Record<string, unknown>;
+ if (o.type === 'Cocos.Widget') {
+ o.type = 'RectAnchors';
+ if (typeof o.data === 'object' && o.data !== null) delete (o.data as Record<string, unknown>).target;
+ changed = true;
+ }
+ Object.values(o).forEach(walk);
+ };
+ let doc: unknown;
+ try { doc = JSON.parse(text); } catch { return false; }
+ walk(doc);
+ if (changed) writeOut(file, JSON.stringify(doc, null, 2) + '\n');
+ return changed;
+}
+
const GENERATED = 'Generated by import-cocos';
/** A default for a field, of the kind its sample is: what the editor shows before anything is typed. */
@@ -614,6 +642,7 @@ export async function importCocosProject(opts: CocosImportOptions): Promise<Impo
else if (written[relPath] === now) report.sync.updated++;
else {
report.sync.kept.push(relPath);
+ if (!opts.dryRun && migrateWidgets(file)) report.note('widget-migrated', relPath);
return;
}
written[relPath] = next;
diff --git a/pipeline/tests/cocos-widget-migration.test.ts b/pipeline/tests/cocos-widget-migration.test.ts
new file mode 100644
index 000000000..7e3336057
--- /dev/null
+++ b/pipeline/tests/cocos-widget-migration.test.ts
@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file A document the creator edited keeps what they did, and still moves to the engine's `RectAnchors` from the compatibility layer's
+ * `Cocos.Widget`: only the component's name changes.
+ */
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { importCocosProject } from '../src/import/cocos';
+
+const meta = (uuid: string, importer: string): object => ({ ver: '1', importer, uuid, subMetas: {}, userData: {} });
+
+describe('a kept document that holds a Cocos.Widget', () => {
+ let root: string;
+ let file: string;
+ let second: Awaited<ReturnType<typeof importCocosProject>>;
+
+ beforeAll(async () => {
+ root = mkdtempSync(path.join(tmpdir(), 'cocos-migrate-'));
+ const dir = path.join(root, 'creator', 'assets');
+ mkdirSync(dir, { recursive: true });
+ const zero = { __type__: 'cc.Vec3', x: 0, y: 0, z: 0 };
+ writeFileSync(path.join(dir, 'main.scene'), JSON.stringify([
+ { __type__: 'cc.SceneAsset', _name: 'main', scene: { __id__: 1 } },
+ { __type__: 'cc.Scene', _name: 'main', _children: [{ __id__: 2 }] },
+ { __type__: 'cc.Node', _name: 'N', _parent: { __id__: 1 }, _children: [], _active: true, _components: [], _prefab: null, _lpos: zero, _lrot: { __type__: 'cc.Quat', x: 0, y: 0, z: 0, w: 1 }, _lscale: { __type__: 'cc.Vec3', x: 1, y: 1, z: 1 }, _layer: 1 },
+ ]));
+ writeFileSync(path.join(dir, 'main.scene.meta'), JSON.stringify(meta('dddddddd-dddd-4ddd-8ddd-dddddddddddd', 'scene')));
+ const source = path.join(root, 'creator'), out = path.join(root, 'out');
+ await importCocosProject({ source, out });
+ // the creator edits it, and it was written back when widgets were the layer's
+ file = path.join(out, 'assets', 'cocos', 'main.esscene');
+ const doc = JSON.parse(readFileSync(file, 'utf8')) as { entities: Array<{ name: string; components: unknown[] }> };
+ doc.entities.find((e) => e.name === 'N')!.components.push({ type: 'Cocos.Widget', data: { enabled: true, alignFlags: 45, left: 5, target: 3 } }, { type: 'Name', data: { value: 'edited by hand' } });
+ writeFileSync(file, `${JSON.stringify(doc, null, 2)}\n`);
+ second = await importCocosProject({ source, out });
+ });
+ afterAll(() => rmSync(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }));
+
+ it('is kept, and says it was migrated', () => {
+ expect(second.sync.kept).toContain('assets/cocos/main.esscene');
+ expect(second.notes['widget-migrated']?.count).toBe(1);
+ });
+
+ it('holds a RectAnchors with the same fields (and no target), and nothing else changed', () => {
+ const doc = JSON.parse(readFileSync(file, 'utf8')) as { entities: Array<{ name: string; components: Array<{ type: string; data: Record<string, unknown> }> }> };
+ const components = doc.entities.find((e) => e.name === 'N')!.components;
+ const anchors = components.find((c) => c.type === 'RectAnchors')!;
+ expect(anchors.data).toEqual({ enabled: true, alignFlags: 45, left: 5 });
+ expect(components.some((c) => c.type === 'Cocos.Widget')).toBe(false);
+ expect(components.find((c) => c.type === 'Name')!.data.value).toBe('edited by hand');
+ });
+});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 5ee853a31..c2110149c 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): a document the creator edited moves from the layer Cocos.Widget to the engine RectAnchors on re-import':
+ {"note":"Edited Cocos documents move to RectAnchors."},
'feat(ui): RectAnchors pins world content to its parent rectangle or the screen in the engine, and the Cocos Widget is a view on it':
{"note":"RectAnchors: world content that follows its parent."},
'feat(cocos): a converted project keeps the Cocos fit width of its design, and cc.profiler exists in the compatibility layer':