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 converted project links its source images instead of copying them, so conversion does not store a multi-gigabyte art folder twice

yhh853aee42ab97
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5479ee376..81c5d6f67 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.
+- **A converted Cocos project links its images.** The source images, fonts and spine files are hard-linked into the converted project (copied only across drives), so a multi-gigabyte art folder is neither copied nor stored twice, and a re-import skips what is already linked. The project reads those files and never writes into them.
- **A Cocos conversion shows its progress.** The importer reports the stage it is in and how far through it is, and the editor runs the conversion on a thread of its own with a progress bar over the window, instead of freezing until it ends.
- **Bursts on a schedule.** `ParticleEmitter.bursts` is a list of `{ time, count }`: each releases its particles once the emitter has been emitting for `time` seconds, and a looping emitter repeats the list every `duration`. It runs beside `burstCount`, which still repeats one burst on an interval.
- **A 3D collider can sit off its entity.** `BoxCollider3D`, `SphereCollider3D` and `CapsuleCollider3D` take an optional `center`, the shape's place from the entity origin in world units. The body stays at the entity, so a dynamic body turns about its origin and the shape swings round it.
diff --git a/pipeline/src/import/cocos/importProject.ts b/pipeline/src/import/cocos/importProject.ts
index 626708f0a..643c062e7 100644
--- a/pipeline/src/import/cocos/importProject.ts
+++ b/pipeline/src/import/cocos/importProject.ts
@@ -9,7 +9,7 @@
* other. Only what the converted documents reference is copied.
*/
import { createHash } from 'node:crypto';
-import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, linkSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs';
import path from 'node:path';
import { isInsideRoot } from '../../fs/pathSandbox';
import { buildScriptIndex } from './scripts';
@@ -83,7 +83,7 @@ function copyFontPages(fnt: string, dest: string, uuidFor: (pageFile: string) =>
const page = path.join(path.dirname(fnt), m[1]!);
if (!existsSync(page)) continue;
const to = path.join(path.dirname(dest), m[1]!);
- copyFileSync(page, to);
+ placeFile(page, to);
const uuid = uuidFor(page);
if (uuid) {
const meta = {
@@ -105,6 +105,30 @@ function declareBakedOutline(fnt: string): string {
));
}
+/**
+ * A source file, in the project. Left alone when it is already there as it was, otherwise a hard link to it (instant, and a multi-gigabyte art
+ * folder is not stored twice), and where the two folders are on different drives a copy that keeps the source's modification time, so the next
+ * import can tell it is unchanged. Nothing here ever writes into the file: the project reads it, and writes its settings beside it.
+ */
+function placeFile(from: string, to: string): void {
+ const source = statSync(from);
+ const there = (() => { try { return statSync(to); } catch { return null; } })();
+ if (there && there.ino !== 0 && there.ino === source.ino && there.dev === source.dev) return;
+ // linked beside the destination and moved over it, so a file system that cannot link leaves what was there untouched
+ const staged = `${to}.linking`;
+ try {
+ rmSync(staged, { force: true });
+ linkSync(from, staged);
+ renameSync(staged, to);
+ return;
+ } catch {
+ rmSync(staged, { force: true }); // another drive, or a file system without links
+ }
+ if (there && there.size === source.size && Math.abs(there.mtimeMs - source.mtimeMs) < 2) return;
+ copyFileSync(from, to);
+ utimesSync(to, source.atime, source.mtime);
+}
+
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. */
@@ -271,7 +295,7 @@ export async function importCocosProject(opts: CocosImportOptions): Promise<Impo
if (!existsSync(from)) continue;
const to = path.join(out, toRef(name));
mkdirSync(path.dirname(to), { recursive: true });
- copyFileSync(from, to);
+ placeFile(from, to);
mintSidecar(to);
}
}
@@ -620,7 +644,7 @@ export async function importCocosProject(opts: CocosImportOptions): Promise<Impo
}
mkdirSync(path.dirname(dest), { recursive: true });
if (entry.file.endsWith('.fnt') && hints?.bakedOutline) writeOut(dest, declareBakedOutline(readFileSync(entry.file, 'utf8')));
- else copyFileSync(entry.file, dest);
+ else placeFile(entry.file, dest);
if (entry.file.endsWith('.fnt')) {
copyFontPages(entry.file, dest, (page) => byRel.get(norm(path.relative(assetsDir, page)))?.uuid);
// The asset database ships a font's page image only for a `bitmapfont`, since nothing else names it.
diff --git a/pipeline/tests/cocos-import-layer.test.ts b/pipeline/tests/cocos-import-layer.test.ts
index 3fcbbed43..9c52e0c49 100644
--- a/pipeline/tests/cocos-import-layer.test.ts
+++ b/pipeline/tests/cocos-import-layer.test.ts
@@ -7,7 +7,7 @@
* The scene is built by hand in Cocos's file shape (a flat array of objects pointing at each other by index), because the shape
* is the thing under test: a script component is named by its script's compressed uuid, and a node is named by an array index.
*/
-import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import path from 'node:path';
import { afterAll, beforeAll, describe, expect, it } from 'vitest';
@@ -182,6 +182,14 @@ describe('importing for the compatibility layer', () => {
expect(main).not.toMatch(/import '\.\/components';/);
});
+ it('puts a source image in the project as a link to it, not a second copy, and never writes into it', () => {
+ const from = statSync(path.join(root, 'creator', 'assets', 'resources', 'ui', 'icon.png'));
+ const to = statSync(path.join(root, 'out', 'assets', 'cocos', 'resources', 'ui', 'icon.png'));
+ expect(to.size).toBe(from.size);
+ expect(to.ino === from.ino && to.dev === from.dev).toBe(true);
+ expect(readFileSync(path.join(root, 'creator', 'assets', 'resources', 'ui', 'icon.png'), 'utf8')).toBe('not a png');
+ });
+
it('counts the components it maps', () => {
for (const type of ['cc.Widget', 'cc.Layout', 'cc.Button', 'cc.UITransform']) expect(report.components[type]!.unmapped).toBe(0);
});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 3e3430714..f5171da17 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 converted project links its source images instead of copying them, so conversion does not store a multi-gigabyte art folder twice':
+ {"note":"A converted Cocos project links its images."},
'feat(cocos): the importer reports its progress by stage, so a long conversion can show a bar':
{"note":"A Cocos conversion shows its progress."},
'feat(particle): an emitter can release bursts on a schedule (bursts), and the Cocos burst list, repeat count and burst times map onto it':