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): the importer brings in the models a project draws with the engine model import, maps MeshRenderer and the built-in shapes onto it, and the editor and the importer share one model import
yhhb9a0249ba8ab
diff --git a/desktop b/desktopindex 7659ca5a2..9f825d2dc 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 7659ca5a2a9ebcb9c5be5d22a94abf397068ef70+Subproject commit 9f825d2dc82efcbacc8be780a84acc86f8fe5f91diff --git a/pipeline/bin/estella.mjs b/pipeline/bin/estella.mjsindex 9d16ef027..2a5396c01 100644--- a/pipeline/bin/estella.mjs+++ b/pipeline/bin/estella.mjs@@ -822,7 +822,7 @@ if (opts.command === 'package-openpaas') {if (opts.command === 'import-cocos') {const { mod, cleanup } = await loadPipeline(path.join(PIPELINE, 'src', 'import', 'cocos', 'index.ts'), 'cocosImport.mjs');try {- const report = mod.importCocosProject({+ const report = await mod.importCocosProject({source: opts.source, out: opts.out, only: opts.only, dryRun: opts.dryRun, ...(opts.into ? { into: opts.into } : {}),});console.log(JSON.stringify(report, null, 2));diff --git a/pipeline/src/assets/importModelFile.ts b/pipeline/src/assets/importModelFile.tsnew file mode 100644index 000000000..9020b8112--- /dev/null+++ b/pipeline/src/assets/importModelFile.ts@@ -0,0 +1,209 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file Importing one model file into a project: the meshes, the images it carries, the materials, the clips and the prefab that+ * assembles them.+ *+ * The editor imports a model dropped into the project, and the Cocos importer imports the models a Cocos project uses; both ask for the+ * same thing, so the writing is here and each caller says only where the source is, where the products go and what to do just before+ * a file is written (the editor journals it for undo).+ */+import { copyFile, mkdir, writeFile } from 'node:fs/promises';+import { existsSync, readFileSync } from 'node:fs';+import path from 'node:path';+import { isInsideRoot, resolveInside } from '../fs/pathSandbox';+import { adoptOrphan } from './assetMeta';+import {+ encodeImportedMesh, assembleModelPrefab, materialProducts, applyLightmapUV, importedImageSettings,+ generateLods, lodName, encodeGeneratedLod, orderHairTriangles,+ type ImportedNode, type SpecularMapReading,+} from './modelImport';+import { modelStem, readModelSource } from './readModelSource';++export interface ModelImportSettings {+ scale: number;+ lightmapUV: boolean;+ specularMap: SpecularMapReading;+ lodLevels: number;+ lodMinTriangles: number;+ characters: boolean;+ springBones: boolean;+}++export interface ImportedModel {+ /** Project-relative paths of everything written, in the order it was produced. */+ products: string[];+ /** What the source says that this engine cannot draw — reported, never dropped. */+ warnings: string[];+ /** The name the prefab and the products are stemmed from. */+ stem: string;+ /** Project-relative path of the prefab that assembles the model; absent when the file held no mesh. */+ prefab?: string;+ /** Each node of the source's hierarchy by its name, with the project-relative `.esmesh` of every primitive it draws. */+ nodeMeshes: Map<string, string[]>;+ /** The clips written, by the animation's own name (the product name without the `<stem>_` prefix). */+ clips: Map<string, string>;+}++export interface ImportModelOptions {+ /** The project root; every product lands inside it. */+ root: string;+ /** Project-relative folder for the products. */+ destDir: string;+ /** The model file. It may lie outside the project (a source being taken over), in which case it is only read. */+ absSource: string;+ /** Where the source's own relative uris resolve from, when it is not beside the source. */+ originDir?: string;+ /** Overrides for what the source's `.meta` says. */+ settings?: Partial<ModelImportSettings>;+ /** Called with the project-relative path just before a file is written. */+ beforeWrite?(rel: string): Promise<void> | void;+}++const DEFAULTS: ModelImportSettings = {+ scale: 1, lightmapUV: false, specularMap: 'color', lodLevels: 0, lodMinTriangles: 256, characters: false, springBones: false,+};++/** What a model's `.meta` asks of the import; the schema's defaults where it is silent or unreadable. One read, because two would be two chances to disagree. */+export function modelSettings(absSource: string): ModelImportSettings {+ try {+ const meta = JSON.parse(readFileSync(`${absSource}.meta`, 'utf8')) as+ { importer?: { scale?: unknown; lightmapUV?: unknown; specularMap?: unknown;+ lodLevels?: unknown; lodMinTriangles?: unknown; characterMaterials?: unknown; springBones?: unknown } };+ const imp = meta.importer;+ const scale = imp?.scale;+ const levels = imp?.lodLevels;+ const minTriangles = imp?.lodMinTriangles;+ return {+ scale: typeof scale === 'number' && scale > 0 ? scale : 1,+ lightmapUV: imp?.lightmapUV === true,+ specularMap: imp?.specularMap === 'orm' ? 'orm' : 'color',+ lodLevels: typeof levels === 'number' ? Math.min(3, Math.max(0, Math.floor(levels))) : 0,+ lodMinTriangles: typeof minTriangles === 'number' && minTriangles >= 0 ? minTriangles : 256,+ characters: imp?.characterMaterials === 'auto',+ springBones: imp?.springBones === 'auto',+ };+ } catch {+ return { ...DEFAULTS };+ }+}++function collectNodeMeshes(nodes: ImportedNode[], meshFiles: string[], out: Map<string, string[]>): void {+ for (const node of nodes) {+ if (node.meshes.length > 0) {+ const files = node.meshes.map((i) => meshFiles[i]).filter((f): f is string => f !== undefined);+ out.set(node.name, [...(out.get(node.name) ?? []), ...files]);+ }+ collectNodeMeshes(node.children, meshFiles, out);+ }+}++/**+ * Import `absSource` into `destDir` of the project at `root`, writing the meshes, the images it carries, the materials, the clips and the+ * prefab that assembles them.+ */+export async function importModelFile(opts: ImportModelOptions): Promise<ImportedModel> {+ const { root, destDir, absSource } = opts;+ const absDir = destDir ? resolveInside(root, destDir, 'model destination') : path.resolve(root);+ await mkdir(absDir, { recursive: true });+ const sourceDir = opts.originDir ?? path.dirname(absSource);+ const stem = modelStem(absSource);+ const projectRef = (abs: string): string => path.relative(path.resolve(root), abs).split(path.sep).join('/');+ const { scale, lightmapUV, specularMap, lodLevels, lodMinTriangles, characters, springBones } = { ...modelSettings(absSource), ...opts.settings };++ const { meshes, textures, nodes, animations, externalFiles, warnings } = await readModelSource(+ new Uint8Array(readFileSync(absSource)), stem,+ {+ filename: absSource,+ externalBuffers: (uri) => {+ const abs = path.join(sourceDir, decodeURIComponent(uri));+ return existsSync(abs) ? new Uint8Array(readFileSync(abs)) : null;+ },+ specularMap,+ },+ );++ // Before anything is written, because it splits vertices: every product below is built from the mesh data this leaves behind.+ if (lightmapUV) warnings.push(...applyLightmapUV(meshes));+ // After it, because a level is a collapse of the mesh as it will be written.+ warnings.push(...await generateLods(meshes, { levels: lodLevels, minTriangles: lodMinTriangles }));+ if (characters) orderHairTriangles(meshes);++ // What each image's sampler asked for, by product name — applied when its `.meta` is first minted and never after: the file's settings are the user's.+ const imageSettings = new Map<string, Record<string, unknown>>(+ [...importedImageSettings(meshes)].map(([file, { settings }]) => [file, { ...settings }]));++ const products: string[] = [];+ const write = async (name: string, bytes: Uint8Array | string): Promise<string> => {+ const rel = destDir ? `${destDir}/${name}` : name;+ await opts.beforeWrite?.(rel);+ await writeFile(path.join(absDir, name), bytes);+ // keeps the uuid a re-import must not change+ await adoptOrphan(path.join(absDir, name), imageSettings.get(name));+ products.push(rel);+ return rel;+ };++ // A file already in the project is left where it lies; one from outside comes WITH the model, at the same relative path. That is what+ // keeps the copied .gltf pointing at its own .bin, so re-importing it still works.+ const externalRefs = new Map<string, string>();+ const external = (uri: string): string => externalRefs.get(uri) ?? uri;+ for (const uri of externalFiles) {+ const abs = path.join(sourceDir, uri);+ if (!existsSync(abs)) continue;+ if (isInsideRoot(root, abs)) {+ // Minted only if it has no `.meta` yet: a data map must not arrive as colour.+ await adoptOrphan(abs, imageSettings.get(uri));+ externalRefs.set(uri, projectRef(abs));+ continue;+ }+ // A uri that reaches outside the model's own folder cannot keep its shape in the project: it lands beside the model, and the+ // source's link to it stays broken — said out loud rather than silently rewritten.+ const keepsShape = isInsideRoot(absDir, path.resolve(absDir, uri));+ if (!keepsShape) warnings.push(`${uri} came from outside the model's folder; the copy is beside it`);+ const name = keepsShape ? uri : path.basename(uri);+ const rel = destDir ? `${destDir}/${name}` : name;+ const absDest = path.join(absDir, name);+ await opts.beforeWrite?.(rel);+ await mkdir(path.dirname(absDest), { recursive: true });+ await copyFile(abs, absDest);+ await adoptOrphan(absDest, imageSettings.get(uri));+ products.push(rel);+ externalRefs.set(uri, rel);+ }++ const meshFiles: string[] = [];+ for (const mesh of meshes) {+ meshFiles.push(await write(`${mesh.name}.esmesh`, encodeImportedMesh(mesh)));+ for (const [i, lod] of (mesh.lods ?? []).entries()) {+ await write(`${lodName(mesh, i + 1)}.esmesh`, encodeGeneratedLod(lod));+ }+ }+ for (const texture of textures) await write(texture.name, texture.bytes);+ const refs = { prefix: destDir ? `${destDir}/` : '', external, characters, springBones };+ for (const material of materialProducts(meshes, stem, refs)) {+ await write(`${material.name}.esmaterial`, `${JSON.stringify(material.data, null, 2)}\n`);+ }+ let firstClip: string | undefined;+ const clips = new Map<string, string>();+ for (const animation of animations) {+ const rel = await write(`${animation.name}.estimeline`, `${JSON.stringify(animation.document, null, 2)}\n`);+ firstClip ??= rel;+ clips.set(animation.name.startsWith(`${stem}_`) ? animation.name.slice(stem.length + 1) : animation.name, rel);+ }+ let prefabRef: string | undefined;+ if (meshes.length > 0) {+ const prefab = assembleModelPrefab(stem, meshes, { refs, nodes, scale, timeline: firstClip });+ prefabRef = await write(`${stem}.esprefab`, `${JSON.stringify(prefab, null, 2)}\n`);+ // Models are authored in metres and a world unit is a design pixel, so a real-world model arrives a few pixels across. Said, not+ // guessed at: the scale is the user's, and this is where they find out they have one.+ const extent = Math.max(...meshes.flatMap((m) => m.data.aabbMax.map((v, i) => v - (m.data.aabbMin[i] ?? 0))));+ if (scale === 1 && extent < 8) {+ warnings.push(`the model is ${extent.toFixed(2)} units across — set Scale in its import settings and reimport if it should be bigger`);+ }+ }++ const nodeMeshes = new Map<string, string[]>();+ collectNodeMeshes(nodes, meshFiles, nodeMeshes);+ return { products, warnings, stem, prefab: prefabRef, nodeMeshes, clips };+}diff --git a/pipeline/src/import/cocos/assets.ts b/pipeline/src/import/cocos/assets.tsindex 826894706..57a82de98 100644--- a/pipeline/src/import/cocos/assets.ts+++ b/pipeline/src/import/cocos/assets.ts@@ -20,7 +20,7 @@ export interface CocosAssetEntry {importer: string;userData: Record<string, unknown>;/** Sub-assets by their full uuid (`<uuid>@<id>`). */- subs: Map<string, { importer: string; userData: Record<string, unknown> }>;+ subs: Map<string, { importer: string; name: string; userData: Record<string, unknown> }>;}export interface CocosAssetIndex {@@ -91,7 +91,7 @@ export function buildCocosAssetIndex(root: string): CocosAssetIndex {for (const sub of Object.values(asObj(meta.subMetas))) {const s = asObj(sub);if (typeof s.uuid !== 'string') continue;- entry.subs.set(s.uuid, { importer: typeof s.importer === 'string' ? s.importer : '', userData: asObj(s.userData) });+ entry.subs.set(s.uuid, { importer: typeof s.importer === 'string' ? s.importer : '', name: typeof s.name === 'string' ? s.name : '', userData: asObj(s.userData) });byUuid.set(s.uuid, entry);}byUuid.set(uuid, entry);diff --git a/pipeline/src/import/cocos/components.ts b/pipeline/src/import/cocos/components.tsindex 9b307a6ba..1e6d45680 100644--- a/pipeline/src/import/cocos/components.ts+++ b/pipeline/src/import/cocos/components.ts@@ -42,6 +42,11 @@ export interface ComponentContext {drawsBakedOutline?(materialUuid: string): boolean;/** A material's main texture and whether it blends additively; null when the project has no such material. */material?(uuid: string): { texture: CocosAssetEntry | null; additive: boolean } | null;+ /**+ * The engine MeshRenderer data of the part of a model a Cocos mesh sub-asset names, once that model was brought in. `exact` is false when+ * the part was picked because the model draws only one.+ */+ modelMesh?(uuid: string): { components: Record<string, unknown>[]; exact: boolean } | null;/** The script class a compressed class id names, when the project has that script. */scriptClass?(classId: string): { name: string } | undefined;/** The project-relative ref of a prefab, queuing it for conversion; null when the project does not have it. */@@ -419,6 +424,57 @@ function directionalLight(c: CocosComponent, ctx: ComponentContext, where: strin};}+/**+ * The shapes Cocos Creator builds in (`db://internal/primitives.fbx`), identified by the bounds of what the editor imported them to: the+ * engine's own builtin meshes, and the size of the Cocos one in world units. The engine's are 100 across, the Cocos ones about 1 (a plane 10),+ * so the node's scale carries the difference and the shape stays the size the scene meant.+ */+const COCOS_PRIMITIVES = '1263d74c-8167-4928-91a6-4e2672411f47';+const PRIMITIVE_MESHES: Record<string, { ref: string; size: number }> = {+ a804a: { ref: 'builtin:cube', size: 1 },+ '17020': { ref: 'builtin:sphere', size: 1 },+ '38fd2': { ref: 'builtin:cylinder', size: 1 },+ '2e76e': { ref: 'builtin:plane', size: 10 },+ fc873: { ref: 'builtin:quad', size: 1 },+};+const ENGINE_PRIMITIVE_SIZE = 100;++/** `cc.MeshRenderer`: the mesh is the model's own part, drawn with the model's own material until the Cocos material is carried across. */+function meshRenderer(c: CocosComponent, ctx: ComponentContext, where: string): { component: ComponentData; scale?: number } | null {+ const meshUuid = uuidOf(c.data._mesh);+ const hasMaterial = Array.isArray(c.data._materials) && c.data._materials.some((m) => uuidOf(m) !== '');+ if (meshUuid.startsWith(COCOS_PRIMITIVES)) {+ const primitive = PRIMITIVE_MESHES[meshUuid.split('@')[1] ?? ''];+ if (!primitive) {+ ctx.report.note('mesh-builtin-shape-unknown', `${where}: ${meshUuid.split('@')[1] ?? ''}`);+ return null;+ }+ ctx.report.component('cc.MeshRenderer', hasMaterial ? 'partial' : 'mapped');+ if (hasMaterial) ctx.report.note('mesh-material-not-carried', where);+ return {+ component: { type: 'MeshRenderer', data: { mesh: primitive.ref, enabled: c.enabled } },+ scale: primitive.size / ENGINE_PRIMITIVE_SIZE,+ };+ }+ const found = meshUuid ? ctx.modelMesh?.(meshUuid) : null;+ if (!found) return null;+ let partial = false;+ if (found.components.length > 1) {+ partial = true;+ ctx.report.note('mesh-several-primitives', where);+ }+ if (!found.exact) {+ partial = true;+ ctx.report.note('mesh-guessed-from-model', where);+ }+ if (hasMaterial) {+ partial = true;+ ctx.report.note('mesh-material-from-model', where);+ }+ ctx.report.component('cc.MeshRenderer', partial ? 'partial' : 'mapped');+ return { component: { type: 'MeshRenderer', data: { ...found.components[0]!, enabled: c.enabled } } };+}+/** `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');@@ -463,6 +519,8 @@ export function convertNode(node: CocosNode, ctx: ComponentContext, where: strinif (!node.active) components.push({ type: 'Disabled', data: {} });const box = uiBox(node);const unmapped: Raw[] = [];+ // a mesh whose unit is not the engine's resizes the node it hangs on+ let unitScale = 1;for (const c of node.components) {let out: ComponentData | null = null;@@ -516,6 +574,12 @@ export function convertNode(node: CocosNode, ctx: ComponentContext, where: strincase 'cc.DirectionalLight':out = directionalLight(c, ctx, where);break;+ case 'cc.MeshRenderer': {+ const mesh = meshRenderer(c, ctx, where);+ out = mesh?.component ?? null;+ if (mesh?.scale !== undefined) unitScale = mesh.scale;+ break;+ }case 'cc.UIOpacity':out = uiOpacity(c, ctx);break;@@ -550,6 +614,11 @@ export function convertNode(node: CocosNode, ctx: ComponentContext, where: strinunmapped.push({ type: c.type, enabled: c.enabled, data: c.data });}+ if (unitScale !== 1) {+ const scale = components[0]!.data.scale as { x: number; y: number; z: number };+ components[0]!.data.scale = { x: scale.x * unitScale, y: scale.y * unitScale, z: scale.z * unitScale };+ }+const cocos: Raw = {};if (unmapped.length) cocos.components = unmapped;if (box) cocos.ui = { width: box.width, height: box.height, anchorX: box.ax, anchorY: box.ay };diff --git a/pipeline/src/import/cocos/convert.ts b/pipeline/src/import/cocos/convert.tsindex 530fe0e6b..deb23502a 100644--- a/pipeline/src/import/cocos/convert.ts+++ b/pipeline/src/import/cocos/convert.ts@@ -78,6 +78,8 @@ export interface ConvertContext extends ComponentContext {loadPrefab(uuid: string): CocosDocument | null;/** The project-relative path the converted prefab of a uuid is written to. */prefabRef(uuid: string): string | null;+ /** The engine prefab of a model a uuid names (the whole model, or its scene), or null when the uuid is not a model that was brought in. */+ modelInstance?(uuid: string): { prefab: string; rootId: string; name: string } | null;/** Where the document being converted lives, for notes. */where: string;}@@ -276,10 +278,35 @@ function diff(pristine: Map<string, Flat>, patched: Map<string, Flat>, ctx: Convreturn out;}+/**+ * What an instance of a model changes about it. The model's own nodes were named by Cocos with ids this import does not know, so only the+ * instance's root can be addressed: its name, whether it is active and where it stands. The rest (a material put on a mesh, a clip set on its+ * animation) is counted, not lost silently.+ */+function modelInstanceOverrides(node: CocosNode, model: { rootId: string; name: string }, ctx: ConvertContext): PrefabOverride[] {+ const inst = node.instance!;+ const roots = inst.overrides.filter((o) => o.target.length === 1);+ const inner = inst.overrides.length - roots.length;+ if (inner > 0) ctx.report.note('model-instance-overrides', `${ctx.where}: ${node.name} (${inner} on the model's own parts)`);+ const addr = roots[0]?.target[0];+ if (addr === undefined) return [];+ const base: CocosNode = {+ id: addr, name: model.name, active: true, pos: { x: 0, y: 0, z: 0 }, rot: { x: 0, y: 0, z: 0, w: 1 }, scale: { x: 1, y: 1, z: 1 },+ layer: 33554432, components: [], children: [],+ };+ const pristine: XNode = { addr, prefix: '', node: base, children: [] };+ const patched = structuredClone(pristine);+ applyOverrides(patched, roots, ctx);+ const quiet: ConvertContext = { ...ctx, report: new ImportReport() };+ return diff(flatten(pristine, quiet), flatten(patched, quiet), ctx).map((o) => ({ ...o, prefabEntityId: model.rootId }));+}+/** The overrides an instance node applies over the prefab it names, or null when that prefab is missing. */function instanceOverrides(node: CocosNode, ctx: ConvertContext): PrefabOverride[] | null {const inst = node.instance;if (!inst) return null;+ const model = ctx.modelInstance?.(inst.asset);+ if (model) return modelInstanceOverrides(node, model, ctx);const pristine = expandAsset(inst.asset, ctx, []);if (!pristine) return null;const patched = structuredClone(pristine);diff --git a/pipeline/src/import/cocos/importProject.ts b/pipeline/src/import/cocos/importProject.tsindex 9b52baa6d..600393333 100644--- a/pipeline/src/import/cocos/importProject.ts+++ b/pipeline/src/import/cocos/importProject.ts@@ -18,6 +18,7 @@ import type { AssetHints, SliceBorder } from './components';import { convertPrefab, convertScene, type ConvertContext } from './convert';import { parseCocosDocument, type CocosDocument } from './document';import { ImportReport, type ImportReportData } from './report';+import { CocosModels } from './models';export interface CocosImportOptions {/** The Cocos project folder (the one holding `assets/` and `settings/`). */@@ -90,7 +91,7 @@ function declareBakedOutline(fnt: string): string {));}-export function importCocosProject(opts: CocosImportOptions): ImportReportData {+export async function importCocosProject(opts: CocosImportOptions): Promise<ImportReportData> {const source = path.resolve(opts.source);const out = path.resolve(opts.out);if (out === source || isInsideRoot(source, out)) {@@ -127,6 +128,7 @@ export function importCocosProject(opts: CocosImportOptions): ImportReportData {return doc;};+ const models = new CocosModels(index, out, into, opts.dryRun === true);const 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>();@@ -158,11 +160,28 @@ export function importCocosProject(opts: CocosImportOptions): ImportReportData {material(materialUuid) {return materialInfo(materialUuid);},+ modelInstance(uuid) {+ const m = models.use(uuid);+ return m && m.use.prefab ? { prefab: m.use.prefab, rootId: m.use.rootId, name: path.basename(m.entry.rel).replace(/\.[^.]+$/, '') } : null;+ },+ modelMesh(uuid) {+ const m = models.use(uuid);+ if (!m) return null;+ const name = models.meshName(m.entry, uuid);+ const hit = name ? m.use.byEntity.get(name) : undefined;+ const renderers = (hit ?? []).filter((c) => c.type === 'MeshRenderer');+ if (renderers.length > 0) return { components: renderers.map((c) => structuredClone(c.data) as Record<string, unknown>), exact: true };+ // a model with one drawn part has no other mesh a node could mean+ const all = [...m.use.byEntity.values()].flat().filter((c) => c.type === 'MeshRenderer');+ return all.length === 1 ? { components: [structuredClone(all[0]!.data) as Record<string, unknown>], exact: false } : null;+ },loadPrefab(uuid) {const e = prefabEntry(uuid);return e ? loadDoc(e) : null;},prefabRef(uuid) {+ const model = models.use(uuid);+ if (model?.use.prefab) return model.use.prefab;const e = prefabEntry(uuid);if (!e) return null;if (!queued.has(e.rel)) {@@ -293,6 +312,7 @@ export function importCocosProject(opts: CocosImportOptions): ImportReportData {const doc = e ? loadDoc(e) : null;if (!e || !doc) continue;ctx.where = r;+ await models.ensureFor(e.file);try {write(outRef(esRel(r, '.esprefab')), convertPrefab(doc, ctx));} catch (err) {@@ -304,6 +324,7 @@ export function importCocosProject(opts: CocosImportOptions): ImportReportData {const doc = e ? loadDoc(e) : null;if (!e || !doc) continue;ctx.where = r;+ await models.ensureFor(e.file);try {write(outRef(esRel(r, '.esscene')), convertScene(doc, ctx));} catch (err) {@@ -311,6 +332,9 @@ export function importCocosProject(opts: CocosImportOptions): ImportReportData {}}+ for (const f of models.failures) report.documents.failed.push(f);+ for (const w of models.warnings) report.note('model-import-warning', `${w.file}: ${w.warning}`);+if (usedScripts.size > 0) {// The scripts stay where they are, unchanged; this file is how the new project's bundle reaches them.const entry = path.join(out, 'src', 'cocos-scripts.ts');diff --git a/pipeline/src/import/cocos/models.ts b/pipeline/src/import/cocos/models.tsnew file mode 100644index 000000000..a45ced2db--- /dev/null+++ b/pipeline/src/import/cocos/models.ts@@ -0,0 +1,126 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file The models a Cocos project draws, taken in with the engine's own model import.+ *+ * A Cocos mesh, material and skeleton live inside an `.fbx` or `.gltf` as sub-assets, and a scene points at them as `<uuid>@<id>`. The engine reads+ * a model by importing it: a prefab that places the pieces, a mesh per primitive, the materials, the images, a clip per animation. This does that+ * import for each model a converted document uses, and answers the two questions the converter has: which prefab is this model, and which mesh+ * component does this Cocos mesh correspond to.+ */+import { existsSync, readdirSync, readFileSync } from 'node:fs';+import path from 'node:path';+import { importModelFile } from '../../assets/importModelFile';+import { modelStem } from '../../assets/readModelSource';+import type { CocosAssetEntry, CocosAssetIndex } from './assets';++type Raw = Record<string, unknown>;+const isObj = (v: unknown): v is Raw => typeof v === 'object' && v !== null && !Array.isArray(v);++export interface ModelUse {+ /** Project-relative path of the model's prefab; empty for a file that only holds animation. */+ prefab: string;+ /** The prefab's root entity id, which an override addresses. */+ rootId: string;+ /** Components by the name of the entity that carries them. */+ byEntity: Map<string, Raw[]>;+ /** Project-relative path of each animation clip, by the animation's own name. */+ clips: Map<string, string>;+}++const MODEL_EXT = /\.(fbx|gltf|glb)$/i;+export const isModelEntry = (entry: CocosAssetEntry | undefined): entry is CocosAssetEntry => !!entry && MODEL_EXT.test(entry.rel);++export class CocosModels {+ private readonly uses = new Map<string, ModelUse | null>();+ private readonly scanned = new Map<string, string[]>();+ readonly failures: Array<{ file: string; error: string }> = [];+ readonly warnings: Array<{ file: string; warning: string }> = [];++ constructor(+ private readonly index: CocosAssetIndex,+ private readonly out: string,+ private readonly into: string,+ private readonly dryRun: boolean,+ ) {}++ /** The model files a document refers to, by looking for their uuids in its text. */+ modelsIn(file: string): CocosAssetEntry[] {+ let uuids = this.scanned.get(file);+ if (!uuids) {+ uuids = [];+ try {+ const text = readFileSync(file, 'utf8');+ for (const m of text.matchAll(/"__uuid__"\s*:\s*"([0-9a-f-]{36})(?:@[0-9a-f]+)?"/g)) uuids.push(m[1]!);+ } catch {+ // an unreadable document is reported where it is parsed+ }+ this.scanned.set(file, [...new Set(uuids)]);+ uuids = this.scanned.get(file)!;+ }+ const found: CocosAssetEntry[] = [];+ for (const u of uuids) {+ const entry = this.index.byUuid.get(u);+ if (isModelEntry(entry) && !found.includes(entry)) found.push(entry);+ }+ return found;+ }++ /** Bring in every model a document uses that has not been brought in. */+ async ensureFor(file: string): Promise<void> {+ for (const entry of this.modelsIn(file)) await this.ensure(entry);+ }++ async ensure(entry: CocosAssetEntry): Promise<void> {+ if (this.uses.has(entry.file)) return;+ this.uses.set(entry.file, null);+ if (this.dryRun) return;+ const destDir = `assets/${this.into}/${path.posix.dirname(entry.rel)}`.replace(/\/\.$/, '');+ const stem = modelStem(entry.file);+ const prefabAbs = path.join(this.out, destDir, `${stem}.esprefab`);+ try {+ // A model already imported is the project's now (its prefab may have been edited): it is read, not written over.+ if (!existsSync(prefabAbs)) {+ const result = await importModelFile({ root: this.out, destDir, absSource: entry.file });+ for (const warning of result.warnings) this.warnings.push({ file: entry.rel, warning });+ }+ this.uses.set(entry.file, readUse(prefabAbs, `${destDir}/${stem}.esprefab`, path.join(this.out, destDir), stem, destDir));+ } catch (err) {+ this.failures.push({ file: entry.rel, error: (err as Error).message });+ }+ }++ /** The model a `<uuid>` or `<uuid>@<id>` names, once it has been brought in. */+ use(uuid: string): { entry: CocosAssetEntry; use: ModelUse } | null {+ const entry = this.index.byUuid.get(uuid.split('@')[0]!);+ if (!isModelEntry(entry)) return null;+ const use = this.uses.get(entry.file);+ return use ? { entry, use } : null;+ }++ /** The name a mesh sub-asset carries, without its `.mesh`. */+ meshName(entry: CocosAssetEntry, uuid: string): string | null {+ const name = entry.subs.get(uuid)?.name;+ return name ? name.replace(/\.mesh$/i, '') : null;+ }+}++function readUse(prefabAbs: string, prefab: string, absDir: string, stem: string, destDir: string): ModelUse {+ // A file with animation and no mesh produces no prefab, only clips.+ const hasPrefab = existsSync(prefabAbs);+ const doc = hasPrefab ? JSON.parse(readFileSync(prefabAbs, 'utf8')) as { rootEntityId?: string; entities?: Raw[] } : {};+ const byEntity = new Map<string, Raw[]>();+ for (const e of (doc as { entities?: Raw[] }).entities ?? []) {+ if (typeof e.name !== 'string' || !Array.isArray(e.components)) continue;+ byEntity.set(e.name, [...(byEntity.get(e.name) ?? []), ...(e.components as Raw[]).filter(isObj)]);+ }+ const clips = new Map<string, string>();+ try {+ for (const file of readdirSync(absDir)) {+ if (file.startsWith(`${stem}_`) && file.endsWith('.estimeline')) clips.set(file.slice(stem.length + 1, -'.estimeline'.length), `${destDir}/${file}`);+ }+ } catch {+ // no clips beside the model+ }+ return { prefab: hasPrefab ? prefab : '', rootId: (doc as { rootEntityId?: string }).rootEntityId ?? 'n1', byEntity, clips };+}diff --git a/pipeline/tests/cocos-import-layer.test.ts b/pipeline/tests/cocos-import-layer.test.tsindex 87a588879..882307152 100644--- a/pipeline/tests/cocos-import-layer.test.ts+++ b/pipeline/tests/cocos-import-layer.test.ts@@ -59,9 +59,9 @@ const scene = [describe('importing for the compatibility layer', () => {let root: string;let scenes: { entities: Array<{ id: number; name: string; components: Array<{ type: string; data: Record<string, any> }> }> };- let report: ReturnType<typeof importCocosProject>;+ let report: Awaited<ReturnType<typeof importCocosProject>>;- beforeAll(() => {+ beforeAll(async () => {root = mkdtempSync(path.join(tmpdir(), 'cocos-layer-'));const put = (rel: string, v: string | object): void => {const f = path.join(root, 'creator', 'assets', rel);@@ -87,7 +87,7 @@ 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'));- report = importCocosProject({ source: path.join(root, 'creator'), out: path.join(root, 'out') });+ 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'));});afterAll(() => rmSync(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }));diff --git a/pipeline/tests/cocos-import-models.test.ts b/pipeline/tests/cocos-import-models.test.tsnew file mode 100644index 000000000..9c28ca39a--- /dev/null+++ b/pipeline/tests/cocos-import-models.test.ts@@ -0,0 +1,148 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file The models a Cocos project draws, taken in with the engine's own model import.+ *+ * The fixture is one glTF triangle standing in for an `.fbx`, a prefab that draws it two ways (a MeshRenderer on a node, and an instance of+ * the model's scene), and a quad from Cocos's built-in shapes. The claims: the model is imported once and its products land beside where it+ * lay in the Cocos project; a MeshRenderer takes the model's own mesh and material; an instance of the model keeps its root's name and place;+ * a built-in shape becomes the engine's, resized so it stays the size the scene meant; and the source is never written to.+ */+import { afterAll, beforeAll, describe, expect, it } from 'vitest';+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, existsSync } from 'node:fs';+import { tmpdir } from 'node:os';+import path from 'node:path';+import { importCocosProject } from '../src/import/cocos';++const MODEL = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa';+const PREFAB = 'bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb';+const PRIMITIVES = '1263d74c-8167-4928-91a6-4e2672411f47';++const vec = (x: number, y: number, z = 0) => ({ __type__: 'cc.Vec3', x, y, z });+const ident = { __type__: 'cc.Quat', x: 0, y: 0, z: 0, w: 1 };++function triangleGltf(): string {+ const buffer = Buffer.alloc(44);+ [0, 0, 0, 1, 0, 0, 0, 1, 0].forEach((v, i) => buffer.writeFloatLE(v, i * 4));+ [0, 1, 2].forEach((v, i) => buffer.writeUInt16LE(v, 36 + i * 2));+ return JSON.stringify({+ asset: { version: '2.0' }, scene: 0, scenes: [{ nodes: [0] }],+ nodes: [{ name: 'tri', mesh: 0 }],+ meshes: [{ name: 'tri', primitives: [{ attributes: { POSITION: 0 }, indices: 1 }] }],+ accessors: [+ { bufferView: 0, componentType: 5126, count: 3, type: 'VEC3', min: [0, 0, 0], max: [1, 1, 0] },+ { bufferView: 1, componentType: 5123, count: 3, type: 'SCALAR' },+ ],+ bufferViews: [{ buffer: 0, byteOffset: 0, byteLength: 36 }, { buffer: 0, byteOffset: 36, byteLength: 6 }],+ buffers: [{ byteLength: 44, uri: `data:application/octet-stream;base64,${buffer.toString('base64')}` }],+ });+}++const node = (name: string, parent: number | null, children: number[], components: number[], prefab: number, pos = vec(0, 0), scale = vec(1, 1, 1)) => ({+ __type__: 'cc.Node', _name: name, _parent: parent === null ? null : { __id__: parent }, _children: children.map((__id__) => ({ __id__ })), _active: true,+ _components: components.map((__id__) => ({ __id__ })), _prefab: { __id__: prefab }, _lpos: pos, _lrot: ident, _lscale: scale, _layer: 1073741824,+});++/** props.prefab: a root with three children: a node drawing the model's mesh, a built-in quad, and an instance of the model's scene. */+const propsPrefab = [+ { __type__: 'cc.Prefab', _name: 'props', data: { __id__: 1 } },+ node('Props', null, [2, 5, 8], [], 4), // 1+ node('Tri', 1, [], [3], 11, vec(5, 0)), // 2+ { __type__: 'cc.MeshRenderer', node: { __id__: 2 }, _enabled: true, __prefab: { __id__: 12 }, _materials: [], _mesh: { __uuid__: `${MODEL}@00a01` } }, // 3+ { __type__: 'cc.PrefabInfo', root: { __id__: 1 }, asset: { __id__: 0 }, fileId: 'propsRoot', instance: null }, // 4+ node('Ground', 1, [], [6], 13, vec(0, 0), vec(2, 2, 2)), // 5+ { __type__: 'cc.MeshRenderer', node: { __id__: 5 }, _enabled: true, __prefab: { __id__: 14 }, _materials: [], _mesh: { __uuid__: `${PRIMITIVES}@fc873` } }, // 6+ { __type__: 'cc.Node', _name: 'unused' }, // 7+ { __type__: 'cc.Node', _objFlags: 0, _parent: { __id__: 1 }, _prefab: { __id__: 9 } }, // 8 (instance of the model's scene)+ { __type__: 'cc.PrefabInfo', root: { __id__: 8 }, asset: { __uuid__: `${MODEL}@00b02` }, fileId: 'modelRoot', instance: { __id__: 10 } }, // 9+ { __type__: 'cc.PrefabInstance', fileId: 'inst', prefabRootNode: { __id__: 1 }, mountedChildren: [], mountedComponents: [], removedComponents: [],+ propertyOverrides: [{ __id__: 15 }, { __id__: 17 }, { __id__: 19 }] }, // 10+ { __type__: 'cc.PrefabInfo', root: { __id__: 1 }, asset: { __id__: 0 }, fileId: 'triInfo', instance: null }, // 11+ { __type__: 'cc.CompPrefabInfo', fileId: 'triMesh' }, // 12+ { __type__: 'cc.PrefabInfo', root: { __id__: 1 }, asset: { __id__: 0 }, fileId: 'groundInfo', instance: null }, // 13+ { __type__: 'cc.CompPrefabInfo', fileId: 'groundMesh' }, // 14+ { __type__: 'CCPropertyOverrideInfo', targetInfo: { __id__: 16 }, propertyPath: ['_name'], value: 'renamed' }, // 15+ { __type__: 'cc.TargetInfo', localID: ['sceneRootId'] }, // 16+ { __type__: 'CCPropertyOverrideInfo', targetInfo: { __id__: 16 }, propertyPath: ['_lpos'], value: vec(3, 4, 5) }, // 17+ { __type__: 'cc.TargetInfo', localID: ['sceneRootId', 'partId'] }, // 18 (a part of the model)+ { __type__: 'CCPropertyOverrideInfo', targetInfo: { __id__: 18 }, propertyPath: ['_lpos'], value: vec(9, 9, 9) }, // 19+];++const meta = (uuid: string, importer: string, extra: object = {}) => ({ ver: '1', importer, uuid, subMetas: {}, userData: {}, ...extra });++let root: string;+let src: string;+let out: string;+let sourceBefore: string;+let report: Awaited<ReturnType<typeof importCocosProject>>;++beforeAll(async () => {+ root = mkdtempSync(path.join(tmpdir(), 'cocos-models-'));+ src = path.join(root, 'creator');+ out = path.join(root, 'estella');+ const put = (rel: string, v: unknown): void => {+ const f = path.join(src, 'assets', rel);+ mkdirSync(path.dirname(f), { recursive: true });+ writeFileSync(f, typeof v === 'string' ? v : JSON.stringify(v));+ };+ put('models/tri/tri.gltf', triangleGltf());+ put('models/tri/tri.gltf.meta', meta(MODEL, 'gltf', {+ subMetas: {+ '00a01': { importer: 'gltf-mesh', uuid: `${MODEL}@00a01`, name: 'tri.mesh', userData: { gltfIndex: 0 } },+ '00b02': { importer: 'gltf-scene', uuid: `${MODEL}@00b02`, name: 'tri.prefab', userData: { gltfIndex: 0 } },+ },+ }));+ put('props/props.prefab', propsPrefab);+ put('props/props.prefab.meta', meta(PREFAB, 'prefab'));+ sourceBefore = readFileSync(path.join(src, 'assets', 'models/tri/tri.gltf'), 'utf8');+ report = await importCocosProject({ source: src, out, only: ['props/'] });+});++afterAll(() => rmSync(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }));++const readJson = (rel: string): any => JSON.parse(readFileSync(path.join(out, rel), 'utf8'));+const entity = (doc: any, name: string): any => doc.entities.find((e: any) => e.name === name);++describe('a model a Cocos project draws', () => {+ it('is imported once, with its products beside where it lay', () => {+ expect(report.documents.failed).toEqual([]);+ for (const f of ['tri.esprefab', 'tri.esmesh']) expect(existsSync(path.join(out, 'assets/cocos/models/tri', f))).toBe(true);+ });++ it('never writes to the model it reads', () => {+ expect(readFileSync(path.join(src, 'assets', 'models/tri/tri.gltf'), 'utf8')).toBe(sourceBefore);+ });++ it('gives a MeshRenderer on a node the model\'s own mesh', () => {+ const tri = entity(readJson('assets/cocos/props/props.esprefab'), 'Tri');+ const mesh = tri.components.find((c: any) => c.type === 'MeshRenderer');+ expect(mesh.data.mesh).toBe('assets/cocos/models/tri/tri.esmesh');+ expect(mesh.data.enabled).toBe(true);+ });++ it('turns an instance of the model\'s scene into a nested prefab that keeps the root\'s name and place', () => {+ const doc = readJson('assets/cocos/props/props.esprefab');+ const inst = doc.entities.find((e: any) => e.nestedPrefab);+ expect(inst.nestedPrefab.prefabPath).toBe('assets/cocos/models/tri/tri.esprefab');+ const modelRoot = readJson('assets/cocos/models/tri/tri.esprefab').rootEntityId;+ const byProperty = (name: string) => inst.nestedPrefab.overrides.find((o: any) => o.type === name || o.propertyName === name);+ expect(inst.nestedPrefab.overrides.every((o: any) => o.prefabEntityId === modelRoot)).toBe(true);+ expect(byProperty('name').value).toBe('renamed');+ expect(byProperty('position').value).toMatchObject({ x: 3, y: 4, z: 5 });+ });++ it('counts what an instance changed on the model\'s own parts instead of losing it silently', () => {+ expect(report.notes['model-instance-overrides']?.count).toBe(1);+ });+});++describe('a Cocos built-in shape', () => {+ it('becomes the engine\'s own, resized so the scene keeps its size', () => {+ const ground = entity(readJson('assets/cocos/props/props.esprefab'), 'Ground');+ const mesh = ground.components.find((c: any) => c.type === 'MeshRenderer');+ expect(mesh.data.mesh).toBe('builtin:quad');+ // the engine's quad is 100 across and Cocos's is 1: a node scaled 2 stands at 2 / 100 of the engine's+ const transform = ground.components.find((c: any) => c.type === 'Transform');+ expect(transform.data.scale.x).toBeCloseTo(0.02, 6);+ });+});diff --git a/pipeline/tests/cocos-import.test.ts b/pipeline/tests/cocos-import.test.tsindex 3d3d9e72c..0470d883a 100644--- a/pipeline/tests/cocos-import.test.ts+++ b/pipeline/tests/cocos-import.test.ts@@ -126,7 +126,7 @@ let registry: Record<string, any>;let root: string;let src: string;let out: string;-let report: ReturnType<typeof importCocosProject>;+let report: Awaited<ReturnType<typeof importCocosProject>>;let before: Record<string, string>;beforeAll(async () => {@@ -159,7 +159,7 @@ beforeAll(async () => {put('main.scene', scene);put('main.scene.meta', meta('55555555-5555-4555-8555-555555555555', 'scene'));before = Object.fromEntries([...files(src)].map((f) => [f, sha(f)]));- report = importCocosProject({ source: src, out });+ report = await importCocosProject({ source: src, out });});afterAll(() => rmSync(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }));@@ -167,9 +167,9 @@ afterAll(() => rmSync(root, { recursive: true, force: true, maxRetries: 10, retrconst readJson = (rel: string): any => JSON.parse(readFileSync(path.join(out, rel), 'utf8'));describe('importing a Cocos project', () => {- it('never writes to the source, and refuses an output inside it', () => {+ it('never writes to the source, and refuses an output inside it', async () => {expect(Object.fromEntries([...files(src)].map((f) => [f, sha(f)]))).toEqual(before);- expect(() => importCocosProject({ source: src, out: path.join(src, 'out') })).toThrow(/never written/);+ await expect(importCocosProject({ source: src, out: path.join(src, 'out') })).rejects.toThrow(/never written/);});it('converts every prefab and scene without failures', () => {@@ -280,15 +280,15 @@ describe('importing again over the same project', () => {const ITEM_REL = 'assets/cocos/ui/item.esprefab';const stateOf = (): { documents: Record<string, string> } => readJson('assets/cocos/.import-state.json');- it('finds nothing to do when neither side changed', () => {- const again = importCocosProject({ source: src, out });+ it('finds nothing to do when neither side changed', async () => {+ const again = await importCocosProject({ source: src, out });expect(again.sync.added).toBe(0);expect(again.sync.updated).toBe(0);expect(again.sync.kept).toEqual([]);expect(again.sync.unchanged).toBeGreaterThan(0);});- it('brings the Cocos side\'s change into a document nobody edited', () => {+ it('brings the Cocos side\'s change into a document nobody edited', async () => {// the file as an earlier import wrote it, different from what the source converts to nowconst file = path.join(out, ITEM_REL);const stale = `${readFileSync(file, 'utf8').trimEnd()}\n\n`;@@ -296,16 +296,16 @@ describe('importing again over the same project', () => {const state = stateOf();state.documents[ITEM_REL] = createHash('sha1').update(stale).digest('hex');writeFileSync(path.join(out, 'assets/cocos/.import-state.json'), JSON.stringify(state));- const again = importCocosProject({ source: src, out });+ const again = await importCocosProject({ source: src, out });expect(again.sync.updated).toBe(1);expect(readFileSync(file, 'utf8')).not.toBe(stale);});- it('keeps a document that was edited here, and says so', () => {+ it('keeps a document that was edited here, and says so', async () => {const file = path.join(out, ITEM_REL);const mine = `${JSON.stringify({ ...readJson(ITEM_REL), edited: true }, null, 2)}\n`;writeFileSync(file, mine);- const again = importCocosProject({ source: src, out });+ const again = await importCocosProject({ source: src, out });expect(again.sync.kept).toEqual([ITEM_REL]);expect(readFileSync(file, 'utf8')).toBe(mine);});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex ae33342e5..3dea80af8 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): the importer brings in the models a project draws with the engine model import, maps MeshRenderer and the built-in shapes onto it, and the editor and the importer share one model import':+ {"internal":"The Cocos Creator compatibility layer and importer have not shipped; the shared model import is a refactor with no change a creator sees."},'feat(particle): an emitter can carry an added velocity per particle and limit particle speed with a dampening, and the Cocos velocity, force and limit modules map onto them':{"note":"Particles can carry an added velocity and be held to a speed limit."},'feat(particle): an emitter can wait startDelay seconds before it emits, with the duration counted from the end of the delay, and the Cocos start delay maps onto it':