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): 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/desktop
index 7659ca5a2..9f825d2dc 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 7659ca5a2a9ebcb9c5be5d22a94abf397068ef70
+Subproject commit 9f825d2dc82efcbacc8be780a84acc86f8fe5f91
diff --git a/pipeline/bin/estella.mjs b/pipeline/bin/estella.mjs
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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: strin
if (!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: strin
case '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: strin
unmapped.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.ts
index 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: Conv
return 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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, retr
const 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 now
const 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.mjs
index 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':