A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(cocos): a 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.tsindex 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.tsindex 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<Impoconst 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 meanconst 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.tsindex 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 }, // 4node('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.mjsindex 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':