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.

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.ts
index 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.ts
index 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);
+ });
+});