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 MeshRenderer wears the Cocos material it was given (image, tint, blending, culling, lighting), and a mesh is found by its place in the model when its name is not readable

yhh5f3cf14653dc
diff --git a/pipeline/src/import/cocos/components.ts b/pipeline/src/import/cocos/components.ts
index 1d666b7fe..81cac6c63 100644
--- a/pipeline/src/import/cocos/components.ts
+++ b/pipeline/src/import/cocos/components.ts
@@ -31,6 +31,23 @@ export interface AssetHints {
bakedOutline?: boolean;
}
+/** What a Cocos material says that a MeshRenderer, a Sprite or a particle can carry: the image and tint, and how it blends and culls. */
+export interface MaterialInfo {
+ texture: CocosAssetEntry | null;
+ /** The tint (`mainColor` or `albedo`), 0..1, when the material sets one. */
+ color?: { r: number; g: number; b: number; a: number };
+ normal?: CocosAssetEntry | null;
+ additive: boolean;
+ /** Blends with what is behind it. */
+ transparent: boolean;
+ /** The effect does not light the surface. */
+ unlit: boolean;
+ /** Faces turned away are not drawn. */
+ cullBack: boolean;
+ /** The effect is one of the engine's built-ins rather than the project's own shader, which is approximated. */
+ builtinEffect: boolean;
+}
+
export interface ComponentContext {
assets: CocosAssetIndex;
report: ImportReport;
@@ -41,8 +58,8 @@ export interface ComponentContext {
* outline's colour supplied at draw time. Such a font has to say so, in the channel flags BMFont gives that layout.
*/
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;
+ /** What a Cocos material draws and how; null when the project has no such material. */
+ material?(uuid: string): MaterialInfo | 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.
@@ -510,6 +527,35 @@ const PRIMITIVE_MESHES: Record<string, { ref: string; size: number }> = {
};
const ENGINE_PRIMITIVE_SIZE = 100;
+/**
+ * Put a Cocos material on a MeshRenderer's data: its image and tint, whether it blends, whether it lights, which faces it draws. The material the
+ * model brought is dropped then, since a material owns shading fully and would hide these. Only the first of several materials is carried.
+ *
+ * @returns `found`: the project had the material; `exact`: it was one of the built-in effects, so nothing of its look was approximated.
+ */
+function applyMaterial(data: Raw, c: CocosComponent, ctx: ComponentContext, where: string): { found: boolean; exact: boolean } {
+ const uuids = (Array.isArray(c.data._materials) ? c.data._materials : []).map(uuidOf).filter(Boolean);
+ const info = uuids[0] ? ctx.material?.(uuids[0]) ?? null : null;
+ if (!info) {
+ if (uuids.length > 0) ctx.report.note('mesh-material-missing', where);
+ return { found: false, exact: false };
+ }
+ delete data.material;
+ if (info.texture) data.texture = ctx.assetRef(info.texture);
+ if (info.normal) data.normalMap = ctx.assetRef(info.normal);
+ if (info.color) data.color = info.color;
+ data.lit = !info.unlit;
+ data.opaque = !info.transparent;
+ data.cullBackfaces = info.cullBack;
+ let exact = info.builtinEffect;
+ if (!info.builtinEffect) ctx.report.note('mesh-custom-effect', where);
+ if (uuids.length > 1) {
+ exact = false;
+ ctx.report.note('mesh-several-materials', where);
+ }
+ return { found: true, exact };
+}
+
/** `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);
@@ -520,15 +566,16 @@ function meshRenderer(c: CocosComponent, ctx: ComponentContext, where: string):
ctx.report.note('mesh-builtin-shape-unknown', `${where}: ${meshUuid.split('@')[1] ?? ''}`);
return null;
}
- 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,
- partial: hasMaterial,
- };
+ const data: Raw = { mesh: primitive.ref, enabled: c.enabled };
+ const applied = applyMaterial(data, c, ctx, where);
+ return { component: { type: 'MeshRenderer', data }, scale: primitive.size / ENGINE_PRIMITIVE_SIZE, partial: hasMaterial && !applied.exact };
}
const found = meshUuid ? ctx.modelMesh?.(meshUuid) : null;
- if (!found) return null;
+ if (!found) {
+ ctx.report.note(meshUuid ? 'mesh-model-part-not-found' : 'mesh-none', `${where}: ${meshUuid}`);
+ return null;
+ }
+ const materials = (Array.isArray(c.data._materials) ? c.data._materials : []).map(uuidOf).filter(Boolean);
let partial = false;
if (found.components.length > 1) {
partial = true;
@@ -538,11 +585,16 @@ function meshRenderer(c: CocosComponent, ctx: ComponentContext, where: string):
partial = true;
ctx.report.note('mesh-guessed-from-model', where);
}
- if (hasMaterial) {
- partial = true;
- ctx.report.note('mesh-material-from-model', where);
+ const data: Raw = { ...found.components[0]!, enabled: c.enabled };
+ if (materials.length > 0) {
+ const applied = applyMaterial(data, c, ctx, where);
+ if (!applied.exact) partial = true;
+ if (!applied.found) {
+ partial = true;
+ ctx.report.note('mesh-material-from-model', where);
+ }
}
- return { component: { type: 'MeshRenderer', data: { ...found.components[0]!, enabled: c.enabled } }, partial };
+ return { component: { type: 'MeshRenderer', data }, partial };
}
/** `cc.UIOpacity`: the alpha of the node and everything under it, which the engine's GroupOpacity is. */
diff --git a/pipeline/src/import/cocos/importProject.ts b/pipeline/src/import/cocos/importProject.ts
index f8fb92db7..801f94d29 100644
--- a/pipeline/src/import/cocos/importProject.ts
+++ b/pipeline/src/import/cocos/importProject.ts
@@ -19,6 +19,7 @@ import { convertPrefab, convertScene, type ConvertContext } from './convert';
import { parseCocosDocument, type CocosDocument } from './document';
import { ImportReport, type ImportReportData } from './report';
import { CocosModels, clipOf, clipPlayOf, retargetClip } from './models';
+import type { MaterialInfo } from './components';
export interface CocosImportOptions {
/** The Cocos project folder (the one holding `assets/` and `settings/`). */
@@ -195,9 +196,17 @@ export async function importCocosProject(opts: CocosImportOptions): Promise<Impo
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 mesh's name can be in any language and any state of repair, but its place in the file is a number: the engine names the parts of a
+ // model with several meshes `<stem>_<mesh>_<primitive>`
+ const gltfIndex = m.entry.subs.get(uuid)?.userData.gltfIndex;
+ if (typeof gltfIndex === 'number') {
+ const wanted = new RegExp(`_${gltfIndex}_\\d+\\.esmesh$`);
+ const byIndex = [...m.use.byEntity.values()].flat().filter((c) => c.type === 'MeshRenderer' && typeof (c.data as { mesh?: unknown }).mesh === 'string' && wanted.test((c.data as { mesh: string }).mesh));
+ if (byIndex.length > 0) return { components: byIndex.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;
+ return all.length === 1 ? { components: [structuredClone(all[0]!.data) as Record<string, unknown>], exact: true } : null;
},
loadPrefab(uuid) {
const e = prefabEntry(uuid);
@@ -216,22 +225,51 @@ export async function importCocosProject(opts: CocosImportOptions): Promise<Impo
},
};
- // What a particle material draws and how: its main texture (a sub-asset of an image) and whether the destination factor is One.
- const materials = new Map<string, { texture: CocosAssetEntry | null; additive: boolean } | null>();
- const materialInfo = (materialUuid: string): { texture: CocosAssetEntry | null; additive: boolean } | null => {
+ // What a material draws and how: its main texture (a sub-asset of an image), its tint, and the state it sets.
+ const BUILTIN_EFFECTS = new Set(['a3cd009f-0ab0-420d-9278-b9fdab939bbc', '1baf0fc9-befa-459c-8bdd-af1a450a0319']); // builtin-standard, builtin-unlit
+ const BUILTIN_UNLIT = '1baf0fc9-befa-459c-8bdd-af1a450a0319';
+ const materials = new Map<string, MaterialInfo | null>();
+ const colorOf = (v: unknown): { r: number; g: number; b: number; a: number } | undefined => {
+ if (typeof v !== 'object' || v === null) return undefined;
+ const o = v as Record<string, unknown>;
+ const n = (x: unknown, d: number): number => (typeof x === 'number' && Number.isFinite(x) ? x : d);
+ // a Color is 0..255 by r g b a; a Vec4 is 0..1 by x y z w
+ if ('r' in o) return { r: n(o.r, 255) / 255, g: n(o.g, 255) / 255, b: n(o.b, 255) / 255, a: n(o.a, 255) / 255 };
+ if ('x' in o) return { r: n(o.x, 1), g: n(o.y, 1), b: n(o.z, 1), a: n(o.w, 1) };
+ return undefined;
+ };
+ const materialInfo = (materialUuid: string): MaterialInfo | null => {
if (materials.has(materialUuid)) return materials.get(materialUuid) ?? null;
- let info: { texture: CocosAssetEntry | null; additive: boolean } | null = null;
+ let info: MaterialInfo | null = null;
try {
const mat = index.byUuid.get(materialUuid);
if (mat) {
const json = JSON.parse(readFileSync(mat.file, 'utf8')) as {
- _props?: Array<{ mainTexture?: { __uuid__?: string } }>;
- _states?: Array<{ blendState?: { targets?: Array<{ blend?: boolean; blendDst?: number }> } }>;
+ _effectAsset?: { __uuid__?: string };
+ _props?: Array<Record<string, unknown>>;
+ _states?: Array<{ blendState?: { targets?: Array<{ blend?: boolean; blendSrc?: number; blendDst?: number }> }; rasterizerState?: { cullMode?: number } }>;
+ };
+ const props = Object.assign({}, ...(json._props ?? [])) as Record<string, unknown>;
+ const uuidIn = (v: unknown): string | undefined => (typeof v === 'object' && v !== null ? ((v as { __uuid__?: string }).__uuid__ ?? undefined) : undefined);
+ const entryOf = (v: unknown): CocosAssetEntry | null => {
+ const u = uuidIn(v);
+ return u ? index.byUuid.get(u.split('@')[0]!) ?? null : null;
};
- const texUuid = json._props?.find((p) => p.mainTexture?.__uuid__)?.mainTexture?.__uuid__;
- const base = typeof texUuid === 'string' ? texUuid.split('@')[0]! : undefined;
const target = json._states?.[0]?.blendState?.targets?.[0];
- info = { texture: base ? index.byUuid.get(base) ?? null : null, additive: target?.blend === true && target.blendDst === 1 };
+ const effectUuid = json._effectAsset?.__uuid__ ?? '';
+ const effectEntry = index.byUuid.get(effectUuid);
+ const effectName = (effectEntry ? path.basename(effectEntry.rel) : '').toLowerCase();
+ const color = colorOf(props.mainColor) ?? colorOf(props.albedo);
+ info = {
+ texture: entryOf(props.mainTexture) ?? entryOf(props.albedoMap),
+ ...(color ? { color } : {}),
+ normal: entryOf(props.normalMap),
+ additive: target?.blend === true && target.blendDst === 1,
+ transparent: target?.blend === true,
+ unlit: effectUuid === BUILTIN_UNLIT || effectName.includes('unlit'),
+ cullBack: (json._states?.[0]?.rasterizerState?.cullMode ?? 2) === 2,
+ builtinEffect: BUILTIN_EFFECTS.has(effectUuid),
+ };
}
} catch {
info = null;
diff --git a/pipeline/tests/cocos-import-models.test.ts b/pipeline/tests/cocos-import-models.test.ts
index 3e534857f..3c2a0f2be 100644
--- a/pipeline/tests/cocos-import-models.test.ts
+++ b/pipeline/tests/cocos-import-models.test.ts
@@ -17,6 +17,9 @@ 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 GROUND_IMG = 'cccccccc-cccc-4ccc-8ccc-cccccccccccc';
+const GROUND_MAT = 'dddddddd-dddd-4ddd-8ddd-dddddddddddd';
+const STANDARD = 'a3cd009f-0ab0-420d-9278-b9fdab939bbc';
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 };
@@ -51,7 +54,7 @@ const propsPrefab = [
{ __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.MeshRenderer', node: { __id__: 5 }, _enabled: true, __prefab: { __id__: 14 }, _materials: [{ __uuid__: GROUND_MAT }], _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
@@ -92,6 +95,14 @@ beforeAll(async () => {
'00b02': { importer: 'gltf-scene', uuid: `${MODEL}@00b02`, name: 'tri.prefab', userData: { gltfIndex: 0 } },
},
}));
+ put('tex/ground.png', 'not really a png');
+ put('tex/ground.png.meta', meta(GROUND_IMG, 'image', { subMetas: { '6c48a': { importer: 'texture', uuid: `${GROUND_IMG}@6c48a`, name: 'texture', userData: {} } } }));
+ put('mat/ground.mtl', {
+ __type__: 'cc.Material', _effectAsset: { __uuid__: STANDARD }, _techIdx: 0,
+ _props: [{ mainTexture: { __uuid__: `${GROUND_IMG}@6c48a` }, mainColor: { __type__: 'cc.Color', r: 255, g: 128, b: 0, a: 255 } }],
+ _states: [{ rasterizerState: { cullMode: 0 }, blendState: { targets: [{ blend: true, blendSrc: 2, blendDst: 4 }] } }],
+ });
+ put('mat/ground.mtl.meta', meta(GROUND_MAT, 'material'));
put('props/props.prefab', propsPrefab);
put('props/props.prefab.meta', meta(PREFAB, 'prefab'));
sourceBefore = readFileSync(path.join(src, 'assets', 'models/tri/tri.gltf'), 'utf8');
@@ -145,6 +156,18 @@ describe('a Cocos built-in shape', () => {
const transform = ground.components.find((c: any) => c.type === 'Transform');
expect(transform.data.scale.x).toBeCloseTo(0.02, 6);
});
+
+ it('wears the Cocos material it was given: its image, tint, blending and culling', () => {
+ const ground = entity(readJson('assets/cocos/props/props.esprefab'), 'Ground');
+ const mesh = ground.components.find((c: any) => c.type === 'MeshRenderer').data;
+ expect(mesh.texture).toBe('assets/cocos/tex/ground.png');
+ expect(mesh.color.r).toBeCloseTo(1, 5);
+ expect(mesh.color.g).toBeCloseTo(128 / 255, 5);
+ expect(mesh.lit).toBe(true); // the built-in standard effect lights the surface
+ expect(mesh.opaque).toBe(false); // it blends
+ expect(mesh.cullBackfaces).toBe(false); // cull mode none
+ expect(report.components['cc.MeshRenderer']?.mapped).toBeGreaterThanOrEqual(1);
+ });
});
describe('a clip played on another skeleton', () => {
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 5b58ce784..b0efbccd8 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'feat(cocos): a MeshRenderer wears the Cocos material it was given (image, tint, blending, culling, lighting), and a mesh is found by its place in the model when its name is not readable':
+ {"internal":"The Cocos Creator compatibility layer and importer have not shipped; nothing a creator reaches without opting in."},
'feat(cocos): the importer binds SkinnedMeshRenderer to the model skin and plays SkeletalAnimation clips on the skeleton they are put on, cut to the span and wrap mode Cocos names':
{"internal":"The Cocos Creator compatibility layer and importer have not shipped; nothing a creator reaches without opting in."},
'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':