Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(cocos): a material put on a part of a model instance reaches that part: the part is told by the id of its renderer, read from the editor library

yhh115da5b08eb5
diff --git a/pipeline/src/import/cocos/components.ts b/pipeline/src/import/cocos/components.ts
index 8451ede11..aeaa6abb9 100644
--- a/pipeline/src/import/cocos/components.ts
+++ b/pipeline/src/import/cocos/components.ts
@@ -70,7 +70,7 @@ export interface ComponentContext {
*/
modelMesh?(uuid: string): { components: Record<string, unknown>[]; exact: boolean } | 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; paths: Map<string, string> } | null;
+ modelInstance?(uuid: string): { prefab: string; rootId: string; name: string; paths: Map<string, string>; parts: Map<string, string> } | null;
/**
* The `.esanimator` a Cocos animation graph is converted to for a node whose bones stand at @p paths, or null when the graph is not one of the
* project's. A graph that plays clips of a model is written once for each skeleton it is put on.
@@ -654,6 +654,19 @@ function applyMaterial(data: Raw, c: CocosComponent, ctx: ComponentContext, wher
return { found: true, exact };
}
+/**
+ * What a Cocos material makes of a MeshRenderer's data, as the fields it sets: the same as a renderer that holds the material, for an override that
+ * puts one on a part of a model. Null when the project does not have the material.
+ */
+export function meshMaterialFields(uuid: string, ctx: ComponentContext, where: string): Raw | null {
+ const data: Raw = {};
+ const applied = applyMaterial(data, { type: 'cc.MeshRenderer', id: '', enabled: true, data: { _materials: [{ __uuid__: uuid }] } } as CocosComponent, ctx, where);
+ if (!applied.found) return null;
+ // the model's own material is dropped when this one has no converted counterpart: it would own the shading and hide the image
+ if (!('material' in data)) data.material = '';
+ return data;
+}
+
/** `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; partial: boolean } | null {
const meshUuid = uuidOf(c.data._mesh);
diff --git a/pipeline/src/import/cocos/convert.ts b/pipeline/src/import/cocos/convert.ts
index e4ecdcd16..96bf77fd7 100644
--- a/pipeline/src/import/cocos/convert.ts
+++ b/pipeline/src/import/cocos/convert.ts
@@ -13,7 +13,7 @@
* Addresses follow the engine's own: an entity inside a nested prefab is
* `slot/localId`, a prefab's own entities are bare ids.
*/
-import { convertNode, sameData, type ComponentContext, type ComponentData } from './components';
+import { convertNode, meshMaterialFields, sameData, type ComponentContext, type ComponentData } from './components';
import { foldEditBoxes } from './editBoxFold';
import { NODE_REF, type CocosDocument, type CocosNode, type CocosOverride } from './document';
import { ImportReport } from './report';
@@ -316,16 +316,31 @@ function diff(pristine: Map<string, Flat>, patched: Map<string, Flat>, ctx: Conv
* 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; paths: Map<string, string> }, ctx: ConvertContext): PrefabOverride[] {
+function modelInstanceOverrides(node: CocosNode, model: { rootId: string; name: string; paths: Map<string, string>; parts: Map<string, string> }, ctx: ConvertContext): PrefabOverride[] {
const inst = node.instance!;
// A property of the instance's root: its name, whether it is on, where it stands. The overrides on a component of the model are told apart
// by what they set: a skeletal animation's clip is carried, anything else is counted.
const animation = animationOverrides(inst.overrides);
const shape = (o: CocosOverride): boolean => ['_name', '_active', '_lpos', '_lrot', '_lscale', '_euler'].includes(o.path[0] ?? '');
const roots = inst.overrides.filter((o) => o.target.length === 1 && shape(o));
- const inner = inst.overrides.length - roots.length - animation.used;
- if (inner > 0) ctx.report.note('model-instance-overrides', `${ctx.where}: ${node.name} (${inner} on the model's own parts)`);
+ // The material a part of the model is given: the part is told by the id of its renderer, and the material is put on it as it would be on a
+ // renderer that holds it.
const out: PrefabOverride[] = [];
+ let materials = 0;
+ for (const o of inst.overrides) {
+ if (o.path[0] !== '_materials' || o.path[1] !== '0' || o.target.length !== 1) continue;
+ const part = model.parts.get(o.target[0]!);
+ const uuid = (o.value as { __uuid__?: unknown } | null)?.__uuid__;
+ if (part === undefined || typeof uuid !== 'string') continue;
+ const fields = meshMaterialFields(uuid, ctx, `${ctx.where}: ${node.name}`);
+ if (!fields) continue;
+ materials++;
+ for (const [propertyName, value] of Object.entries(fields)) {
+ out.push({ prefabEntityId: part, type: 'property', componentType: 'MeshRenderer', propertyName, value });
+ }
+ }
+ const inner = inst.overrides.length - roots.length - animation.used - materials;
+ if (inner > 0) ctx.report.note('model-instance-overrides', `${ctx.where}: ${node.name} (${inner} on the model's own parts)`);
if (animation.clip) {
const timeline = ctx.clipOn?.(animation.clip, model.paths, `${ctx.where}: ${node.name}`);
if (timeline) {
diff --git a/pipeline/src/import/cocos/importProject.ts b/pipeline/src/import/cocos/importProject.ts
index 804e43881..782576f18 100644
--- a/pipeline/src/import/cocos/importProject.ts
+++ b/pipeline/src/import/cocos/importProject.ts
@@ -32,7 +32,7 @@ import { convertPass, isOutlinePass, type PassConversion } from './effectConvert
* importer that made less (or differently), and is brought up to date when it is opened. Raise it when the converted output changes in a
* way an existing project needs to pick up: a new generated file, a field a document or a manifest now carries.
*/
-export const COCOS_IMPORT_REVISION = 21;
+export const COCOS_IMPORT_REVISION = 22;
/** Whether the project at @p projectRoot was written by an importer of this revision. A project that was not converted has nothing to bring up. */
export function cocosImportIsCurrent(projectRoot: string): boolean {
@@ -491,7 +491,13 @@ export async function importCocosProject(opts: CocosImportOptions): Promise<Impo
},
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(/\.[^.]+$/, ''), paths: m.use.paths } : null;
+ if (!m || !m.use.prefab) return null;
+ const parts = new Map<string, string>();
+ for (const [fileId, name] of models.partsOf(m.entry)) {
+ const id = m.use.renderers.get(name);
+ if (id !== undefined) parts.set(fileId, id);
+ }
+ return { prefab: m.use.prefab, rootId: m.use.rootId, name: path.basename(m.entry.rel).replace(/\.[^.]+$/, ''), paths: m.use.paths, parts };
},
modelSkin(meshUuid) {
const m = models.use(meshUuid);
diff --git a/pipeline/src/import/cocos/models.ts b/pipeline/src/import/cocos/models.ts
index ffbb2754f..a960c2675 100644
--- a/pipeline/src/import/cocos/models.ts
+++ b/pipeline/src/import/cocos/models.ts
@@ -31,6 +31,8 @@ export interface ModelUse {
paths: Map<string, string>;
/** The names of the joints a skinned part is bound to, in the order its vertices index them, keyed by the part's name. */
skin: Map<string, string[]>;
+ /** The prefab entity id of the mesh renderer of each part of the model, by the part's name: a part is a node, and its renderer is on the node or on the child the import made for its geometry. */
+ renderers: Map<string, string>;
}
const MODEL_EXT = /\.(fbx|gltf|glb)$/i;
@@ -101,6 +103,29 @@ export class CocosModels {
}
}
+ /**
+ * The mesh renderers of a model by the id Cocos gave each component: what a property override on a model's part addresses. Read from the
+ * editor's library of imported assets, which is there when the project has been opened; without it the parts cannot be told apart.
+ */
+ partsOf(entry: CocosAssetEntry): Map<string, string> {
+ const found = new Map<string, string>();
+ const scene = [...entry.subs.entries()].find(([, sub]) => sub.importer === 'gltf-scene')?.[0];
+ if (!scene) return found;
+ const file = path.join(this.index.root, '..', 'library', scene.slice(0, 2), `${scene}.json`);
+ try {
+ const objs = JSON.parse(readFileSync(file, 'utf8')) as Raw[];
+ for (const o of objs) {
+ if (!isObj(o) || o.__type__ !== 'cc.MeshRenderer') continue;
+ const info = isObj(o.__prefab) && typeof o.__prefab.__id__ === 'number' ? objs[o.__prefab.__id__] : null;
+ const node = isObj(o.node) && typeof o.node.__id__ === 'number' ? objs[o.node.__id__] : null;
+ if (isObj(info) && typeof info.fileId === 'string' && isObj(node) && typeof node._name === 'string') found.set(info.fileId, node._name);
+ }
+ } catch {
+ // no library: the parts stay unaddressed, and the overrides on them are counted
+ }
+ return found;
+ }
+
/** 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]!);
@@ -164,7 +189,15 @@ function readUse(prefabAbs: string, prefab: string, absDir: string, stem: string
skin.set(String(e.name), c.data.joints.map((id) => String(byId.get(String(id))?.name ?? '')));
}
}
- return { prefab: hasPrefab ? prefab : '', rootId: (doc as { rootEntityId?: string }).rootEntityId ?? 'n1', byEntity, clips, paths, skin };
+ const renderers = new Map<string, string>();
+ for (const e of entities) {
+ const holds = (Array.isArray(e.components) ? (e.components as Raw[]) : []).some((c) => c.type === 'MeshRenderer');
+ if (!holds || typeof e.name !== 'string') continue;
+ const parent = typeof e.parent === 'string' ? byId.get(e.parent) : undefined;
+ const part = e.name === 'GeometryTransform' && typeof parent?.name === 'string' ? parent.name : e.name;
+ if (!renderers.has(part)) renderers.set(part, String(e.prefabEntityId));
+ }
+ return { prefab: hasPrefab ? prefab : '', rootId: (doc as { rootEntityId?: string }).rootEntityId ?? 'n1', byEntity, clips, paths, skin, renderers };
}
/** Give a generated asset the `.meta` an export needs to ship it, unless it has one. */
diff --git a/pipeline/tests/cocos-model-parts.test.ts b/pipeline/tests/cocos-model-parts.test.ts
new file mode 100644
index 000000000..8cb936138
--- /dev/null
+++ b/pipeline/tests/cocos-model-parts.test.ts
@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file The mesh renderers of a model told apart by the id Cocos gave each component, so a material put on one part of a model instance reaches that part.
+ */
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { afterAll, describe, expect, it } from 'vitest';
+import { CocosModels } from '../src/import/cocos/models';
+import type { CocosAssetEntry, CocosAssetIndex } from '../src/import/cocos/assets';
+
+describe('the parts of a model', () => {
+ const roots: string[] = [];
+ afterAll(() => { for (const r of roots) rmSync(r, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); });
+
+ function models(withLibrary: boolean): { models: CocosModels; entry: CocosAssetEntry } {
+ const project = mkdtempSync(path.join(tmpdir(), 'cocos-parts-'));
+ roots.push(project);
+ const uuid = '0b66da8a-0278-47c3-968e-5e4325ae5482';
+ const scene = `${uuid}@8a0c4`;
+ if (withLibrary) {
+ mkdirSync(path.join(project, 'library', '0b'), { recursive: true });
+ writeFileSync(path.join(project, 'library', '0b', `${scene}.json`), JSON.stringify([
+ { __type__: 'cc.Prefab' },
+ { __type__: 'cc.Node', _name: 'room' },
+ { __type__: 'cc.Node', _name: 'wall' },
+ { __type__: 'cc.MeshRenderer', node: { __id__: 2 }, __prefab: { __id__: 4 } },
+ { __type__: 'cc.CompPrefabInfo', fileId: 'wallRenderer' },
+ ]));
+ }
+ const entry: CocosAssetEntry = {
+ uuid, file: path.join(project, 'assets', 'room.FBX'), rel: 'room.FBX', importer: 'fbx', userData: {},
+ subs: new Map([[scene, { importer: 'gltf-scene', name: 'room.prefab', userData: {} }]]),
+ };
+ const index: CocosAssetIndex = { root: path.join(project, 'assets'), byUuid: new Map([[uuid, entry]]), bundles: [] };
+ return { models: new CocosModels(index, path.join(project, 'out'), 'cocos', true), entry };
+ }
+
+ it('are named by the id of their renderer, from the editor library', () => {
+ const { models: m, entry } = models(true);
+ expect([...m.partsOf(entry)]).toEqual([['wallRenderer', 'wall']]);
+ });
+
+ it('stay unaddressed when the project has no library', () => {
+ const { models: m, entry } = models(false);
+ expect(m.partsOf(entry).size).toBe(0);
+ });
+});