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): a converted project declares its script components for the editor and starts from the scripts, and the Cocos scripts bundle past the gaps Cocos tolerates (missing cc names, reassigned const, package files outside exports, preview-only imports)
yhhd0c2c011700e
diff --git a/pipeline/src/bundle/cocosCompat.ts b/pipeline/src/bundle/cocosCompat.tsindex c71a2be6a..cf97e27a4 100644--- a/pipeline/src/bundle/cocosCompat.ts+++ b/pipeline/src/bundle/cocosCompat.ts@@ -14,9 +14,17 @@* arguments. A Cocos project's own tsconfig usually extends a file the editor generates and the checkout lacks, so it cannot* be relied on to say it.*+ * A package's file by its path (`long/umd/index.js`) even where the package's `exports` map does not list it: Cocos resolves+ * files the way node did before `exports`, and the generated protobuf code of a project asks for exactly that.+ *+ * A third, smaller one: Cocos compiles scripts that esbuild refuses. A `const` that is assigned to later is a TypeScript error Cocos+ * builds through (its output is `var`, where the assignment simply works), and esbuild stops the whole bundle on it. Such a+ * declaration is read as `let`, which is what the script meant.+ ** Only files that import `cc` are touched: a script that does not is not a Cocos script, and keeps whatever its own tsconfig says.* The project's files are read, never written.*/+import { existsSync, statSync } from 'node:fs';import { readFile } from 'node:fs/promises';import path from 'node:path';import type { Plugin } from 'esbuild';@@ -30,6 +38,51 @@ const IMPORTS_CC = /(?:from|import)\s*\(?\s*['"]cc(?:\/env)?['"]/;const TS = /\.tsx?$/;const RESOLVING = Symbol('cocos-compat:resolving');+const PACKAGE_FILE = /^(?:@[^/]+\/[^/]+|[^@./][^/]*)\/.+/;++/** `<dir>/node_modules/<specifier>` for the nearest dir upward that has it, as a file. */+function packageFileFrom(dir: string, specifier: string): string | undefined {+ for (let d = dir; ; d = path.dirname(d)) {+ const candidate = path.join(d, 'node_modules', specifier);+ if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;+ if (path.dirname(d) === d) return undefined;+ }+}++const CONST_DECL = /\bconst\s+([A-Za-z_$][\w$]*)\s*(?::[^=;\n]+)?=/g;+const escapeRe = (name: string): string => name.replace(/[$]/g, '\\$&');++const NAMED_CC_IMPORT = /^[ \t]*import\s*\{([^}]*)\}\s*from\s*(['"])(cc(?:\/env)?)\2\s*;?/gm;++/**+ * `import { A, B as C } from 'cc'` as a read of the layer's namespace. The layer provides part of the Creator API, and Cocos hands a+ * script the rest as `undefined` where a bundler would stop at the first name that is not exported. A name the layer lacks is+ * `undefined` here too, and the script finds out only if it gets as far as using it.+ */+export function readNamedImportsThroughNamespace(source: string): string {+ let n = 0;+ return source.replace(NAMED_CC_IMPORT, (_all, list: string, quote: string, from: string) => {+ const bindings = list.split(',').map((x) => x.trim()).filter((x) => x && !/^type\s/.test(x))+ .map((x) => { const [name, alias] = x.split(/\s+as\s+/); return alias ? `${name!.trim()}: ${alias.trim()}` : name!.trim(); });+ if (bindings.length === 0) return '';+ const ns = `__cc${n++}`;+ return `import * as ${ns} from ${quote}${from}${quote}; const { ${bindings.join(', ')} } = ${ns};`;+ });+}++/** The source with every `const` that the script assigns to again read as `let`; the source itself when there is none. */+export function letTheReassignedConsts(source: string): string {+ if (!source.includes('const ')) return source;+ let out = source;+ for (const m of source.matchAll(CONST_DECL)) {+ const name = escapeRe(m[1]!);+ // an assignment statement: the name at the start of a statement, then `=` that is not `==` or `=>`, or a compound operator+ const assigned = new RegExp(`(?:^|[;{}\\n])\\s*${name}\\s*(?:[-+*/%&|^]|\\*\\*|<<|>>>?|&&|\\|\\||\\?\\?)?=(?![=>])`, 'm');+ if (!assigned.test(source.slice((m.index ?? 0) + m[0].length))) continue;+ out = out.replace(new RegExp(`\\bconst(\\s+${name}\\b)`), 'let$1');+ }+ return out;+}export function cocosCompatPlugin(): Plugin {return {@@ -46,6 +99,20 @@ export function cocosCompatPlugin(): Plugin {return { path: layer.path, external: layer.external, sideEffects: layer.sideEffects };});+ // `preview-template/` is the page the Creator editor's preview serves, Node code included; a build never ships it, so what a script+ // reaches for there is nothing.+ build.onResolve({ filter: /(^|\/)preview-template\// }, (args) => ({ path: args.path, namespace: 'cocos-preview-only' }));+ build.onLoad({ filter: /.*/, namespace: 'cocos-preview-only' }, () => ({ contents: 'export {};', loader: 'js' }));++ // Only a path the bundler could not resolve itself falls back to the plain file lookup.+ build.onResolve({ filter: PACKAGE_FILE }, async (args) => {+ if (args.pluginData === RESOLVING || args.kind === 'entry-point') return undefined;+ const tried = await build.resolve(args.path, { kind: args.kind, importer: args.importer, resolveDir: args.resolveDir, pluginData: RESOLVING });+ if (tried.errors.length === 0) return tried;+ const file = packageFileFrom(args.resolveDir, args.path);+ return file ? { path: file } : undefined;+ });+build.onLoad({ filter: TS }, async (args) => {if (args.path.includes(`${path.sep}node_modules${path.sep}`)) return undefined;let source: string;@@ -54,7 +121,11 @@ export function cocosCompatPlugin(): Plugin {} catch {return undefined;}- if (!IMPORTS_CC.test(source)) return undefined;+ if (!IMPORTS_CC.test(source)) {+ const fixed = letTheReassignedConsts(source);+ return fixed === source ? undefined : { contents: fixed, loader: args.path.endsWith('x') ? 'tsx' : 'ts', resolveDir: path.dirname(args.path) };+ }+ source = readNamedImportsThroughNamespace(letTheReassignedConsts(source));const esbuild = await loadEsbuild();const out = await esbuild.transform(source, {loader: args.path.endsWith('x') ? 'tsx' : 'ts',diff --git a/pipeline/src/import/cocos/importProject.ts b/pipeline/src/import/cocos/importProject.tsindex ca49ec581..626708f0a 100644--- a/pipeline/src/import/cocos/importProject.ts+++ b/pipeline/src/import/cocos/importProject.ts@@ -105,6 +105,50 @@ function declareBakedOutline(fnt: string): string {));}+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. */+function defaultLike(sample: unknown): unknown {+ if (typeof sample === 'number') return 0;+ if (typeof sample === 'string') return '';+ if (typeof sample === 'boolean') return false;+ if (Array.isArray(sample)) return [];+ return null;+}++/**+ * Make the converted project run and open in the editor as converted. `src/components.ts` is the entry the editor reads component schemas+ * from without running the project: it gets the compatibility layer's own components, and one declaration for each script class the+ * scenes use, with the fields they carry. `src/main.ts` starts the project, so it loads the scripts themselves (which declare the real+ * classes) and not those declarations. Both files are rewritten only while they are still what the starter project or this import wrote:+ * once the creator has edited one, it is theirs.+ */+function wireProjectEntries(out: string, scriptFields: Map<string, Map<string, unknown>>): void {+ const read = (file: string): string | null => { try { return readFileSync(file, 'utf8'); } catch { return null; } };+ const components = path.join(out, 'src', 'components.ts');+ const current = read(components);+ if (current === null || current.includes(GENERATED) || /^(\s*\/\/[^\n]*\n)*\s*export \{\};?\s*$/.test(current)) {+ const lines = [+ `// ${GENERATED}. The editor reads component schemas from this file without running the project.`,+ "// The Cocos compatibility layer's own components, and the script classes the converted scenes use, with the fields they carry.",+ "// Running the project loads the scripts themselves (src/cocos-scripts.ts); these declarations are for the editor only.",+ "import { defineComponent } from 'esengine';",+ "import 'esengine/cocos';", '',+ ];+ for (const [name, fields] of [...scriptFields].sort((a, b) => a[0].localeCompare(b[0]))) {+ const body = ['enabled: true', ...[...fields].filter(([k]) => k !== 'enabled').sort((a, b) => a[0].localeCompare(b[0]))+ .map(([k, v]) => `${JSON.stringify(k)}: ${JSON.stringify(defaultLike(v))}`)];+ lines.push(`defineComponent(${JSON.stringify(name)}, { ${body.join(', ')} });`);+ }+ writeOut(components, `${lines.join('\n')}\n`);+ }+ const main = path.join(out, 'src', 'main.ts');+ const text = read(main);+ if (text !== null && !text.includes('cocos-scripts') && /^import '\.\/components';\s*$/m.test(text)) {+ writeOut(main, text.replace(/^import '\.\/components';\s*$/m, "// The converted Cocos scripts (the editor reads src/components.ts instead).\nimport './cocos-scripts';"));+ }+}+export async function importCocosProject(opts: CocosImportOptions): Promise<ImportReportData> {const source = path.resolve(opts.source);const out = path.resolve(opts.out);@@ -150,11 +194,28 @@ export async function importCocosProject(opts: CocosImportOptions): Promise<Impoconst scripts = buildScriptIndex(index);/** The scripts a converted document refers to, which the project has to bundle for those components to exist. */const usedScripts = new Set<string>();+ /** The component each script class became, and the fields its instances carry: what the editor needs to show them without running the script. */+ const scriptFields = new Map<string, Map<string, unknown>>();+ const collectScriptFields = (doc: unknown): void => {+ 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 (typeof o.type === 'string' && o.type.startsWith('Cocos.') && typeof o.data === 'object' && o.data !== null && scriptNames.has(o.type)) {+ const fields = scriptFields.get(o.type) ?? new Map<string, unknown>();+ for (const [k, x] of Object.entries(o.data as Record<string, unknown>)) if (!fields.has(k) || fields.get(k) == null) fields.set(k, x);+ scriptFields.set(o.type, fields);+ }+ Object.values(o).forEach(walk);+ };+ walk(doc);+ };+ const scriptNames = new Set<string>();const ctx: ConvertContext = {assets: index,scriptClass: (classId) => {const found = scripts.get(classId);- if (found) usedScripts.add(found.rel);+ if (found) { usedScripts.add(found.rel); scriptNames.add(`Cocos.${found.name}`); }return found;},prefabAssetRef: (uuid) => ctx.prefabRef(uuid),@@ -500,7 +561,9 @@ export async function importCocosProject(opts: CocosImportOptions): Promise<Impoprogress('prefabs', i, pending.length, r);await models.ensureFor(e.file);try {- write(outRef(esRel(r, '.esprefab')), convertPrefab(doc, ctx));+ const converted = convertPrefab(doc, ctx);+ collectScriptFields(converted);+ write(outRef(esRel(r, '.esprefab')), converted);} catch (err) {report.documents.failed.push({ file: r, error: (err as Error).message });}@@ -513,7 +576,9 @@ export async function importCocosProject(opts: CocosImportOptions): Promise<Impoprogress('scenes', si, scenes.length, r);await models.ensureFor(e.file);try {- write(outRef(esRel(r, '.esscene')), convertScene(doc, ctx));+ const converted = convertScene(doc, ctx);+ collectScriptFields(converted);+ write(outRef(esRel(r, '.esscene')), converted);} catch (err) {report.documents.failed.push({ file: r, error: (err as Error).message });}@@ -539,6 +604,7 @@ export async function importCocosProject(opts: CocosImportOptions): Promise<Impo].join('\n');if (!opts.dryRun) writeOut(entry, text);report.note('cocos-scripts-entry', `${path.relative(out, entry).split(path.sep).join('/')}: ${usedScripts.size} script(s)`);+ if (!opts.dryRun) wireProjectEntries(out, scriptFields);}report.textures = textures.size;diff --git a/pipeline/tests/cocos-compat-bundle.test.ts b/pipeline/tests/cocos-compat-bundle.test.tsindex 59db65995..cbd7cfcc5 100644--- a/pipeline/tests/cocos-compat-bundle.test.ts+++ b/pipeline/tests/cocos-compat-bundle.test.ts@@ -88,3 +88,28 @@ export default [${names.join(', ')}, EDITOR, DEBUG];expect(result.errors).toEqual([]);});});++describe('a const the script assigns to again', () => {+ it('is read as let, and only that one', async () => {+ const { letTheReassignedConsts } = await import('../src/bundle/cocosCompat');+ const fixed = letTheReassignedConsts('const a = null;\nconst b = 1;\nif (x) {\n a = 2;\n}\nconst c: number = 3;\n c += 1;\nuse(b == 1, a);');+ expect(fixed).toContain('let a = null');+ expect(fixed).toContain('const b = 1');+ expect(fixed).toContain('let c: number = 3');+ });+ it('leaves a source with no reassignment as it is', async () => {+ const { letTheReassignedConsts } = await import('../src/bundle/cocosCompat');+ const src = 'const a = 1;\nconst f = () => a === 2 ? a : 3;\nconst o = { a: 1 };\no.a = 2;\n';+ expect(letTheReassignedConsts(src)).toBe(src);+ });+});++describe('named imports from cc', () => {+ it('are read from the layer namespace, so a name the layer lacks is undefined instead of a build error', async () => {+ const { readNamedImportsThroughNamespace } = await import('../src/bundle/cocosCompat');+ const out = readNamedImportsThroughNamespace("import { _decorator, Node as N, type Vec3, gfx } from 'cc';\nimport { EDITOR } from 'cc/env';\nconst x = 1;");+ expect(out).toContain("import * as __cc0 from 'cc'; const { _decorator, Node: N, gfx } = __cc0;");+ expect(out).toContain("import * as __cc1 from 'cc/env'; const { EDITOR } = __cc1;");+ expect(out).toContain('const x = 1;');+ });+});diff --git a/pipeline/tests/cocos-import-layer.test.ts b/pipeline/tests/cocos-import-layer.test.tsindex 882307152..3fcbbed43 100644--- a/pipeline/tests/cocos-import-layer.test.ts+++ b/pipeline/tests/cocos-import-layer.test.ts@@ -87,6 +87,9 @@ describe('importing for the compatibility layer', () => {put('hero/skin.json.meta', meta('f5f5f5f5-f5f5-4f5f-8f5f-f5f5f5f5f5f5', 'json'));put('art/plain.json', '{}');put('art/plain.json.meta', meta(PLAIN, 'json'));+ // the starter project's entry, which the import points at the converted scripts+ mkdirSync(path.join(root, 'out', 'src'), { recursive: true });+ writeFileSync(path.join(root, 'out', 'src', 'main.ts'), "// Game entry.\nimport './components';\n");report = await importCocosProject({ source: path.join(root, 'creator'), out: path.join(root, 'out') });scenes = JSON.parse(readFileSync(path.join(root, 'out', 'assets', 'cocos', 'main.esscene'), 'utf8'));});@@ -169,6 +172,16 @@ describe('importing for the compatibility layer', () => {expect(report.components['cc.Mask']).toEqual({ mapped: 1, partial: 0, unmapped: 0 });});+ it('declares the script classes the scenes use for the editor, and starts the project from the scripts themselves', () => {+ const components = readFileSync(path.join(root, 'out', 'src', 'components.ts'), 'utf8');+ expect(components).toContain("import 'esengine/cocos';");+ expect(components).toMatch(/defineComponent\("Cocos\.Hud", \{ enabled: true,/);+ expect(components).toContain('"speed": 0');+ const main = readFileSync(path.join(root, 'out', 'src', 'main.ts'), 'utf8');+ expect(main).toContain("import './cocos-scripts';");+ expect(main).not.toMatch(/import '\.\/components';/);+ });+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);});