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(mesh): the second UV set survives the import boundary

esengine4474cae0bd80
diff --git a/desktop b/desktop
index 2a7fb028e..80b80cacd 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 2a7fb028e36aa6190fae51896bc3c702c79a64f6
+Subproject commit 80b80cacd6fad15ce249c3661104f1ddbfbac1b1
diff --git a/pipeline/src/assets/gltfImport.ts b/pipeline/src/assets/gltfImport.ts
index 229183569..0ad735a24 100644
--- a/pipeline/src/assets/gltfImport.ts
+++ b/pipeline/src/assets/gltfImport.ts
@@ -436,7 +436,11 @@ function readSampler(ctx: MaterialContext, index: number | undefined,
/** Resolves a glTF texture index to the file a MeshRenderer will sample, extracting inline images. */
function readTexture(ctx: MaterialContext, cache: Map<number, ImportedImageRef | null>,
ref: GltfTextureRef, label: string): ImportedImageRef | null {
- if (ref.texCoord) ctx.warnings.push(`${label}: TEXCOORD_${ref.texCoord} is not imported (one UV set)`);
+ // The mesh carries a second set; a MATERIAL still samples the first, so a
+ // texture asking for another one is the loss to report — not the UVs.
+ if (ref.texCoord) {
+ ctx.warnings.push(`${label}: samples TEXCOORD_${ref.texCoord}; materials read the first set, so it will sample UV0`);
+ }
for (const name of Object.keys(ref.extensions ?? {})) {
ctx.warnings.push(`${label}: ${name} not imported (uvs are used as authored)`);
}
@@ -881,8 +885,14 @@ export async function importGltfMeshes(
const positions = attribute('POSITION', posIndex)!;
const vertexCount = positions.length / 3;
const uvIndex = prim.attributes.TEXCOORD_0;
+ const uv1Index = prim.attributes.TEXCOORD_1;
const colorIndex = prim.attributes.COLOR_0;
const uvs = attribute('TEXCOORD_0', uvIndex);
+ // Tolerant where TEXCOORD_0 is not: a Draco blob that omits a set it
+ // declared must not fail an import that has no need of it.
+ let uvs1: Float32Array | null = null;
+ try { uvs1 = attribute('TEXCOORD_1', uv1Index); }
+ catch { warnings.push(`${label}: TEXCOORD_1 is declared and missing from the Draco blob`); }
const normalIndex = prim.attributes.NORMAL;
const normals = attribute('NORMAL', normalIndex);
const colorsRaw = attribute('COLOR_0', colorIndex);
@@ -925,6 +935,9 @@ export async function importGltfMeshes(
{ semantic: MeshChannel.Color, components: 4, type: MeshChannelType.UNorm8 },
...(normals ? [{ semantic: MeshChannel.Normal, components: 3,
type: MeshChannelType.Float32 }] : []),
+ // Ahead of the skinning pair, which the two lines below find by position.
+ ...(uvs1 ? [{ semantic: MeshChannel.TexCoord1, components: 2,
+ type: MeshChannelType.Float32 }] : []),
...(skinned ? [
{ semantic: MeshChannel.Joints, components: 4, type: MeshChannelType.UInt16 },
{ semantic: MeshChannel.Weights, components: 4, type: MeshChannelType.Float32 },
@@ -932,6 +945,7 @@ export async function importGltfMeshes(
]);
const jointsChannel = skinned ? channels[channels.length - 2]! : null;
const weightsChannel = skinned ? channels[channels.length - 1]! : null;
+ const uv1Channel = channels.find(c => c.semantic === MeshChannel.TexCoord1) ?? null;
const vertices = new Uint8Array(vertexCount * vertexStride);
const dv = new DataView(vertices.buffer);
@@ -953,6 +967,12 @@ export async function importGltfMeshes(
// bottom-up, and the two conventions each look right alone.
dv.setFloat32(at + channels[1]!.offset + 4,
uvs ? 1 - (uvs[i * 2 + 1] ?? 0) : 0, true);
+ if (uv1Channel && uvs1) {
+ // Flipped exactly as UV0 is: two sets that disagreed about
+ // which way is up would be worse than one.
+ dv.setFloat32(at + uv1Channel.offset, uvs1[i * 2] ?? 0, true);
+ dv.setFloat32(at + uv1Channel.offset + 4, 1 - (uvs1[i * 2 + 1] ?? 0), true);
+ }
for (let c = 0; c < 4; c++) {
const v = colorsRaw
? (c < colorComps ? colorsRaw[i * colorComps + c] ?? 1 : 1)
diff --git a/pipeline/tests/gltf-import.test.ts b/pipeline/tests/gltf-import.test.ts
index 4de0815c5..e148c64a6 100644
--- a/pipeline/tests/gltf-import.test.ts
+++ b/pipeline/tests/gltf-import.test.ts
@@ -74,6 +74,58 @@ function withInlineImage(): Record<string, unknown> {
};
}
+/**
+ * A glTF whose triangle carries TWO UV sets, the second offset from the first.
+ * Identical sets would pass a reader that kept only one, so the fixture makes the
+ * difference visible.
+ */
+function gltfWithSecondUv(): Uint8Array {
+ const positions = new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]);
+ const uv0 = new Float32Array([0, 0, 1, 0, 0, 1]);
+ const uv1 = new Float32Array([0.5, 0.25, 0.75, 0.25, 0.5, 0.5]);
+ const indices = new Uint16Array([0, 1, 2]);
+ const bytes = Buffer.concat([
+ Buffer.from(positions.buffer), Buffer.from(uv0.buffer),
+ Buffer.from(uv1.buffer), Buffer.from(indices.buffer),
+ ]);
+ const doc = {
+ asset: { version: '2.0' },
+ buffers: [{ byteLength: 90, uri: `data:application/octet-stream;base64,${bytes.toString('base64')}` }],
+ bufferViews: [
+ { buffer: 0, byteOffset: 0, byteLength: 36 },
+ { buffer: 0, byteOffset: 36, byteLength: 24 },
+ { buffer: 0, byteOffset: 60, byteLength: 24 },
+ { buffer: 0, byteOffset: 84, byteLength: 6 },
+ ],
+ accessors: [
+ { bufferView: 0, componentType: 5126, count: 3, type: 'VEC3' },
+ { bufferView: 1, componentType: 5126, count: 3, type: 'VEC2' },
+ { bufferView: 2, componentType: 5126, count: 3, type: 'VEC2' },
+ { bufferView: 3, componentType: 5123, count: 3, type: 'SCALAR' },
+ ],
+ meshes: [{ name: 'Tri', primitives: [{
+ attributes: { POSITION: 0, TEXCOORD_0: 1, TEXCOORD_1: 2 }, indices: 3, mode: 4,
+ }] }],
+ nodes: [{ mesh: 0 }],
+ scenes: [{ nodes: [0] }],
+ scene: 0,
+ };
+ return new TextEncoder().encode(JSON.stringify(doc));
+}
+
+/** One channel's values, vertex by vertex. */
+function uvsOf(mesh: ImportedMesh, semantic: number): number[] {
+ const channel = mesh.data.channels.find(c => c.semantic === semantic);
+ if (!channel) return [];
+ const view = new DataView(mesh.data.vertices.buffer, mesh.data.vertices.byteOffset);
+ const out: number[] = [];
+ for (let i = 0; i < mesh.vertexCount; i++) {
+ const at = i * mesh.data.vertexStride + channel.offset;
+ out.push(view.getFloat32(at, true), view.getFloat32(at + 4, true));
+ }
+ return out;
+}
+
function texCoords(mesh: ImportedMesh): number[] {
const channel = mesh.data.channels.find(c => c.semantic === MeshChannel.TexCoord0)!;
const view = new DataView(mesh.data.vertices.buffer, mesh.data.vertices.byteOffset);
@@ -872,3 +924,26 @@ describe('Draco-compressed geometry', () => {
expect(meshes).toHaveLength(1);
});
});
+
+describe('a second UV set', () => {
+ it('reaches the mesh, distinct from the first', async () => {
+ const result = await importGltfMeshes(gltfWithSecondUv(), 'twoUv');
+ const mesh = result.meshes[0]!;
+ const uv0 = uvsOf(mesh, MeshChannel.TexCoord0);
+ const uv1 = uvsOf(mesh, MeshChannel.TexCoord1);
+ expect(uv1).toHaveLength(6);
+ expect(uv1).not.toEqual(uv0);
+ // Both sets are V-flipped at this boundary, as UV0 always has been: two sets
+ // disagreeing about which way is up would be worse than one.
+ expect(uv1).toEqual([0.5, 0.75, 0.75, 0.75, 0.5, 0.5]);
+ });
+
+ it('is absent from a mesh whose source has one set', async () => {
+ const result = await importGltfMeshes(gltf({}), 'oneUv');
+ const mesh = result.meshes[0]!;
+ // Not "zeroes in a channel nobody wrote": a file states what it has, so a
+ // mesh without a second set stays a mesh without one.
+ expect(mesh.data.channels.some(c => c.semantic === MeshChannel.TexCoord1)).toBe(false);
+ expect(uvsOf(mesh, MeshChannel.TexCoord1)).toEqual([]);
+ });
+});
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 7bceb473d..3e013864b 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -4902,7 +4902,7 @@ static prototype: MemoryTransport
## MeshChannel — const @experimental
```
-{ readonly Position: 0; readonly Color: 1; readonly TexCoord0: 2; readonly Normal: 3; readonly Tangent: 4; readonly Joints: 5; readonly Weights: 6; }
+{ readonly Position: 0; readonly Color: 1; readonly TexCoord0: 2; readonly Normal: 3; readonly Tangent: 4; readonly Joints: 5; readonly Weights: 6; readonly TexCoord1: 7; }
```
## MeshChannelDesc — interface @experimental
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 9fb772cb5..2e961e4a7 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -4915,7 +4915,7 @@ static prototype: MemoryTransport
## MeshChannel — const @experimental
```
-{ readonly Position: 0; readonly Color: 1; readonly TexCoord0: 2; readonly Normal: 3; readonly Tangent: 4; readonly Joints: 5; readonly Weights: 6; }
+{ readonly Position: 0; readonly Color: 1; readonly TexCoord0: 2; readonly Normal: 3; readonly Tangent: 4; readonly Joints: 5; readonly Weights: 6; readonly TexCoord1: 7; }
```
## MeshChannelDesc — interface @experimental
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index ffcf0c44a..7a88674a5 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -4897,7 +4897,7 @@ static prototype: MemoryTransport
## MeshChannel — const @experimental
```
-{ readonly Position: 0; readonly Color: 1; readonly TexCoord0: 2; readonly Normal: 3; readonly Tangent: 4; readonly Joints: 5; readonly Weights: 6; }
+{ readonly Position: 0; readonly Color: 1; readonly TexCoord0: 2; readonly Normal: 3; readonly Tangent: 4; readonly Joints: 5; readonly Weights: 6; readonly TexCoord1: 7; }
```
## MeshChannelDesc — interface @experimental
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 739d48ebd..15dbfa43f 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -4897,7 +4897,7 @@ static prototype: MemoryTransport
## MeshChannel — const @experimental
```
-{ readonly Position: 0; readonly Color: 1; readonly TexCoord0: 2; readonly Normal: 3; readonly Tangent: 4; readonly Joints: 5; readonly Weights: 6; }
+{ readonly Position: 0; readonly Color: 1; readonly TexCoord0: 2; readonly Normal: 3; readonly Tangent: 4; readonly Joints: 5; readonly Weights: 6; readonly TexCoord1: 7; }
```
## MeshChannelDesc — interface @experimental
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 51cd6e75c..5642f4165 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -4904,7 +4904,7 @@ static prototype: MemoryTransport
## MeshChannel — const @experimental
```
-{ readonly Position: 0; readonly Color: 1; readonly TexCoord0: 2; readonly Normal: 3; readonly Tangent: 4; readonly Joints: 5; readonly Weights: 6; }
+{ readonly Position: 0; readonly Color: 1; readonly TexCoord0: 2; readonly Normal: 3; readonly Tangent: 4; readonly Joints: 5; readonly Weights: 6; readonly TexCoord1: 7; }
```
## MeshChannelDesc — interface @experimental
diff --git a/sdk/src/asset/meshFormat.ts b/sdk/src/asset/meshFormat.ts
index 7af96ef5e..9a235ff07 100644
--- a/sdk/src/asset/meshFormat.ts
+++ b/sdk/src/asset/meshFormat.ts
@@ -43,6 +43,11 @@ export const MeshChannel = {
Joints: 5,
/** How much each of those four joints moves it. */
Weights: 6,
+ /** A second UV set: what an unwrap produces for a lightmap, a detail pass or an
+ * AO atlas. Carried because the boundary is lossy in one direction — a source
+ * that had one cannot be re-derived — and read by nothing yet, which is why
+ * `meshShaderReads` in GfxEnums.hpp keeps it out of the vertex LAYOUT. */
+ TexCoord1: 7,
} as const;
/** How a channel's components are stored. Append only — serialized. */
diff --git a/src/esengine/renderer/rhi/GfxEnums.hpp b/src/esengine/renderer/rhi/GfxEnums.hpp
index 88a0d4043..317aa47c8 100644
--- a/src/esengine/renderer/rhi/GfxEnums.hpp
+++ b/src/esengine/renderer/rhi/GfxEnums.hpp
@@ -127,8 +127,22 @@ enum class MeshChannel : u8 {
Tangent = 4,
Joints = 5,
Weights = 6,
+ /// A second UV set. Location 7 is the last one before the per-object record
+ /// at MESH_INSTANCE_FIRST_LOCATION, which is why that constant is fixed.
+ TexCoord1 = 7,
};
+/**
+ * @brief Whether the mesh shaders READ a channel, as opposed to the file carrying it.
+ * @details A channel kept for its information stays in the vertex buffer and out
+ * of the LAYOUT: an attribute nothing reads spends a slot and a fetch
+ * per vertex. Binding it anyway was tried on both backends and neither
+ * refused, so this is a cost, not a correctness fix.
+ */
+constexpr bool meshShaderReads(MeshChannel c) {
+ return c != MeshChannel::TexCoord1;
+}
+
/**
* @brief How a channel's components are stored, as the file spells it.
* @details The asset layer's vocabulary rather than the device's: these are the
diff --git a/src/esengine/resource/ResourceManager.cpp b/src/esengine/resource/ResourceManager.cpp
index 98dbb8033..498d46e6b 100644
--- a/src/esengine/resource/ResourceManager.cpp
+++ b/src/esengine/resource/ResourceManager.cpp
@@ -495,13 +495,19 @@ bool ResourceManager::realizeMesh(Mesh& mesh, ConstSpan<u8> vertexBytes, ConstSp
// engine's and is appended here, so no caller has to know how a transform
// reaches the shader — the reason a mesh is drawn without touching its bytes.
VertexLayoutDesc layout;
- if (channels.size() + MESH_INSTANCE_ATTRIBUTES > MAX_VERTEX_ATTRIBUTES) {
- ES_LOG_ERROR("realizeMesh: {} channels exceeds the layout budget", channels.size());
- return false;
- }
- for (usize i = 0; i < channels.size(); ++i) {
- layout.attributes[i] = channels[i];
- layout.attributes[i].bufferSlot = 0;
+ // A channel no shader reads stays out of the layout (meshShaderReads): it
+ // would spend an attribute slot and a fetch per vertex. The stride is
+ // unchanged, so the bytes remain for whoever starts reading them.
+ u32 bound = 0;
+ for (const GfxVertexAttribute& c : channels) {
+ if (!meshShaderReads(static_cast<MeshChannel>(c.location))) continue;
+ if (bound + MESH_INSTANCE_ATTRIBUTES >= MAX_VERTEX_ATTRIBUTES) {
+ ES_LOG_ERROR("realizeMesh: {} bound channels exceeds the layout budget", bound + 1);
+ return false;
+ }
+ layout.attributes[bound] = c;
+ layout.attributes[bound].bufferSlot = 0;
+ ++bound;
}
bool hasNormals = false;
bool skinned = false;
@@ -515,7 +521,7 @@ bool ResourceManager::realizeMesh(Mesh& mesh, ConstSpan<u8> vertexBytes, ConstSp
layout.strides[1] = skinned ? MESH_INSTANCE_STRIDE_SKINNED
: hasNormals ? MESH_INSTANCE_STRIDE_LIT : MESH_INSTANCE_STRIDE;
layout.instanceStep[1] = true;
- u32 next = static_cast<u32>(channels.size());
+ u32 next = bound;
// Only where the shader will read them: a layout may not declare an attribute
// its shader does not consume, which WebGPU rejects. A skinned record thus
// carries neither model nor normal matrix — its bones are world-space.