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
fix(fbx): a vertex colour layer that would import an invisible mesh is dropped
yhh06cc972178bd
diff --git a/pipeline/src/assets/fbxImport.ts b/pipeline/src/assets/fbxImport.tsindex 8f50aa60e..c818cc1c3 100644--- a/pipeline/src/assets/fbxImport.ts+++ b/pipeline/src/assets/fbxImport.ts@@ -394,17 +394,56 @@ function buildNodes(scene: FbxScene, meshIndexOf: Map<string, number[]>): Import/* -- Geometry ----------------------------------------------------------- */+/**+ * Share of vertices that may be fully transparent before a vertex-colour layer+ * is read as broken rather than authored. Deliberately near 1: a mesh really can+ * fade most of itself out, but one that is transparent at 19 vertices in 20 is+ * not being shaded — it is being erased.+ */+const INVISIBLE_COLOR_SHARE = 0.95;++/**+ * The vertex colours to actually use: `colors`, or null when the layer would+ * make the mesh invisible (see the call site). Warns, naming the share, so the+ * substitution is never silent.+ *+ * Exported for the test: the decision is a threshold on real numbers, and the+ * FBX fixtures write no colour layer to drive it end to end.+ */+export function dropInvisibleColors(colors: Float32Array, vertexCount: number,+ name: string, warnings: string[]): Float32Array | null {+ if (vertexCount === 0) return colors;+ let transparent = 0;+ for (let i = 0; i < vertexCount; i++) if ((colors[i * 4 + 3] ?? 0) === 0) transparent++;+ const share = transparent / vertexCount;+ if (share < INVISIBLE_COLOR_SHARE) return colors;+ warnings.push(`${name}: ${(share * 100).toFixed(1)}% of its vertex colours are fully`+ + ' transparent, which would import an invisible mesh — the layer is ignored and the'+ + ' mesh uses white, as one with no colour layer does');+ return null;+}+/** One material run of one FBX mesh as the `.esmesh` payload it becomes. */function buildMesh(part: FbxMeshPart, name: string, payload: Uint8Array,material: ImportedMaterial | undefined, warnings: string[]): ImportedMesh {const positions = floats(payload, part.positions);const normals = part.normals ? floats(payload, part.normals) : null;const uvs = part.uvs ? floats(payload, part.uvs) : null;- const colors = part.colors ? floats(payload, part.colors) : null;const joints = part.joints ? ushorts(payload, part.joints) : null;const weights = part.weights ? floats(payload, part.weights) : null;const indices = uints(payload, part.indices);const vertexCount = part.vertexCount;+ // MeshRenderer multiplies its tint INTO the vertex colours, so a layer that+ // is transparent nearly everywhere is a mesh that imports, occludes, and+ // draws nothing — with no error anywhere to say why. Nobody authors that;+ // it is what a colour layer whose indices did not match the mesh decays to+ // (ufbx clamps the bad index and hands back zeroes, warning only "Clamped+ // index"). Measured on a real project: 3 of 80 building models arrived 96-99%+ // alpha-zero and imported invisible. Drop the layer to white and SAY so —+ // white is what a mesh with no colour layer already gets, so the fallback is+ // the ordinary path rather than a special case.+ const colors = part.colors ? dropInvisibleColors(floats(payload, part.colors),+ part.vertexCount, name, warnings) : null;// A pose the renderer cannot hold is not a pose — see the same read in the// glTF importer. Static, and it says why, rather than joints indexing a// matrix that was never uploaded.diff --git a/pipeline/tests/fbx-import.test.ts b/pipeline/tests/fbx-import.test.tsindex f799c9424..ff8c836bd 100644--- a/pipeline/tests/fbx-import.test.ts+++ b/pipeline/tests/fbx-import.test.ts@@ -9,7 +9,7 @@* `scripts/lib/fbxFixtures.mjs` rather than hidden in a binary.*/import { describe, it, expect } from 'vitest';-import { importFbxMeshes } from '../src/assets/fbxImport';+import { importFbxMeshes, dropInvisibleColors } from '../src/assets/fbxImport';import { assembleModelPrefab, materialProducts,type ImportedMesh, type ImportedNode } from '../src/assets/modelImport';import { MeshChannel } from 'esengine';@@ -228,3 +228,49 @@ describe('fbx reporting', () => {.rejects.toThrow();});});++/**+ * A colour layer whose indices did not match the mesh decays to zeroes (ufbx+ * clamps the bad index and says only "Clamped index"), and MeshRenderer+ * multiplies its tint INTO those — so the model imports, occludes, and draws+ * nothing. Real project, real numbers: 3 of 80 building models arrived 96-99%+ * alpha-zero and were invisible with no error anywhere.+ */+describe('fbx vertex colours that would import an invisible mesh', () => {+ /** `count` vertices, of which the first `opaque` have alpha 1. */+ const layer = (count: number, opaque: number): Float32Array => {+ const c = new Float32Array(count * 4);+ for (let i = 0; i < opaque; i++) c.set([1, 1, 1, 1], i * 4);+ return c;+ };++ it('keeps a layer that actually colours the mesh', () => {+ const warnings: string[] = [];+ const colors = layer(100, 100);+ expect(dropInvisibleColors(colors, 100, 'm', warnings)).toBe(colors);+ expect(warnings).toEqual([]);+ });++ it('keeps a layer that fades most — but not nearly all — of the mesh', () => {+ const warnings: string[] = [];+ const colors = layer(100, 10); // 90% transparent: a fade, not an erasure+ expect(dropInvisibleColors(colors, 100, 'm', warnings)).toBe(colors);+ expect(warnings).toEqual([]);+ });++ it('drops a layer that is transparent nearly everywhere, and says so', () => {+ const warnings: string[] = [];+ // The measured shape: 48 of 4238 vertices opaque (98.9% transparent).+ expect(dropInvisibleColors(layer(4238, 48), 4238, 'building_acakemy_1_1', warnings)).toBeNull();+ expect(warnings).toHaveLength(1);+ expect(warnings[0]).toContain('building_acakemy_1_1');+ expect(warnings[0]).toContain('98.9%');+ expect(warnings[0]).toContain('invisible');+ });++ it('drops a layer that is wholly transparent', () => {+ const warnings: string[] = [];+ expect(dropInvisibleColors(layer(64, 0), 64, 'm', warnings)).toBeNull();+ expect(warnings).toHaveLength(1);+ });+});