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(assets): a model's material comes in as a material

esenginefa0c91c86193
diff --git a/desktop/electron/importModel.ts b/desktop/electron/importModel.ts
index 7e7d683a6..31bc9edd6 100644
--- a/desktop/electron/importModel.ts
+++ b/desktop/electron/importModel.ts
@@ -16,7 +16,7 @@ import { resolveInRoot } from './projectFs';
import { capture } from './fileJournal';
import { adoptOrphan } from '../../pipeline/src/assets/assetMeta';
import {
- importGltfMeshes, encodeImportedMesh, assembleGltfPrefab,
+ importGltfMeshes, encodeImportedMesh, assembleGltfPrefab, materialProducts,
} from '../../pipeline/src/assets/gltfImport';
export interface ModelImportResult {
@@ -61,7 +61,8 @@ export async function importModel(root: string, destDir: string, absSource: stri
// `.meta` is first minted and never after: the file's settings are the user's.
const imageSettings = new Map<string, Record<string, unknown>>();
for (const mesh of meshes) {
- for (const image of [mesh.material?.baseColorTexture, mesh.material?.normalTexture]) {
+ for (const image of [mesh.material?.baseColorTexture, mesh.material?.normalTexture,
+ mesh.material?.emissiveTexture, mesh.material?.occlusionTexture]) {
if (image?.settings) imageSettings.set(image.file, { ...image.settings });
}
}
@@ -109,11 +110,12 @@ export async function importModel(root: string, destDir: string, absSource: stri
for (const mesh of meshes) await write(`${mesh.name}.esmesh`, encodeImportedMesh(mesh));
for (const texture of textures) await write(texture.name, texture.bytes);
+ const refs = { prefix: destDir ? `${destDir}/` : '', external };
+ for (const material of materialProducts(meshes, stem, refs)) {
+ await write(`${material.name}.esmaterial`, `${JSON.stringify(material.data, null, 2)}\n`);
+ }
if (meshes.length > 0) {
- const prefab = assembleGltfPrefab(stem, meshes, {
- refs: { prefix: destDir ? `${destDir}/` : '', external },
- nodes,
- });
+ const prefab = assembleGltfPrefab(stem, meshes, { refs, nodes });
await write(`${stem}.esprefab`, `${JSON.stringify(prefab, null, 2)}\n`);
}
return { products, warnings };
diff --git a/desktop/public/scenes/model-material.esprefab b/desktop/public/scenes/model-material.esprefab
new file mode 100644
index 000000000..d18aec3d2
--- /dev/null
+++ b/desktop/public/scenes/model-material.esprefab
@@ -0,0 +1,126 @@
+{
+ "version": "2",
+ "name": "model-material",
+ "rootEntityId": "root",
+ "entities": [
+ {
+ "prefabEntityId": "root",
+ "name": "model-material",
+ "parent": null,
+ "children": [
+ "n0",
+ "n1",
+ "n2"
+ ],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ }
+ ]
+ },
+ {
+ "prefabEntityId": "n0",
+ "name": "Glow",
+ "parent": "root",
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -220,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Mesh2D",
+ "data": {
+ "mesh": "scenes/model-material_0_0.esmesh",
+ "lit": true,
+ "material": "scenes/model-material_m0.esmaterial",
+ "color": {
+ "r": 0,
+ "g": 0,
+ "b": 0,
+ "a": 1
+ },
+ "opaque": true,
+ "cullBackfaces": true,
+ "enabled": true
+ }
+ }
+ ]
+ },
+ {
+ "prefabEntityId": "n1",
+ "name": "Shaded",
+ "parent": "root",
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "Mesh2D",
+ "data": {
+ "mesh": "scenes/model-material_1_0.esmesh",
+ "lit": true,
+ "material": "scenes/model-material_m1.esmaterial",
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "opaque": true,
+ "cullBackfaces": true,
+ "enabled": true
+ }
+ }
+ ]
+ },
+ {
+ "prefabEntityId": "n2",
+ "name": "Cutout",
+ "parent": "root",
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 220,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Mesh2D",
+ "data": {
+ "mesh": "scenes/model-material_2_0.esmesh",
+ "lit": true,
+ "material": "scenes/model-material_m2.esmaterial",
+ "color": {
+ "r": 1,
+ "g": 0,
+ "b": 0,
+ "a": 0.3
+ },
+ "opaque": true,
+ "cullBackfaces": true,
+ "enabled": true
+ }
+ }
+ ]
+ }
+ ]
+}
diff --git a/desktop/public/scenes/model-material.esprefab.meta b/desktop/public/scenes/model-material.esprefab.meta
new file mode 100644
index 000000000..c8da261f9
--- /dev/null
+++ b/desktop/public/scenes/model-material.esprefab.meta
@@ -0,0 +1,8 @@
+{
+ "uuid": "bdcabc0e-e74a-4868-8a6f-906f34f97c9a",
+ "version": "2.0",
+ "type": "prefab",
+ "importer": {
+ "autoMigrate": true
+ }
+}
diff --git a/desktop/public/scenes/model-material.esscene b/desktop/public/scenes/model-material.esscene
new file mode 100644
index 000000000..601f619a3
--- /dev/null
+++ b/desktop/public/scenes/model-material.esscene
@@ -0,0 +1,67 @@
+{
+ "version": 1,
+ "name": "ModelMaterial",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 10
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 300,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ]
+ },
+ {
+ "id": 1,
+ "name": "Ambient",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Light2D",
+ "data": {
+ "type": 2,
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "intensity": 1,
+ "enabled": true
+ }
+ }
+ ]
+ }
+ ]
+}
diff --git a/desktop/public/scenes/model-material.gltf b/desktop/public/scenes/model-material.gltf
new file mode 100644
index 000000000..686b9bd9a
--- /dev/null
+++ b/desktop/public/scenes/model-material.gltf
@@ -0,0 +1,229 @@
+{
+ "asset": {
+ "version": "2.0",
+ "generator": "estella test fixture"
+ },
+ "buffers": [
+ {
+ "byteLength": 140,
+ "uri": "data:application/octet-stream;base64,AADIwgAAyEIAAAAAAADIQgAAyEIAAAAAAADIwgAAyMIAAAAAAADIQgAAyMIAAAAAAAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/AACAPwAAgD8AAAIAAQABAAIAAwA="
+ }
+ ],
+ "bufferViews": [
+ {
+ "buffer": 0,
+ "byteOffset": 0,
+ "byteLength": 48
+ },
+ {
+ "buffer": 0,
+ "byteOffset": 48,
+ "byteLength": 48
+ },
+ {
+ "buffer": 0,
+ "byteOffset": 96,
+ "byteLength": 32
+ },
+ {
+ "buffer": 0,
+ "byteOffset": 128,
+ "byteLength": 12
+ }
+ ],
+ "accessors": [
+ {
+ "bufferView": 0,
+ "componentType": 5126,
+ "count": 4,
+ "type": "VEC3",
+ "min": [
+ -100,
+ -100,
+ 0
+ ],
+ "max": [
+ 100,
+ 100,
+ 0
+ ]
+ },
+ {
+ "bufferView": 1,
+ "componentType": 5126,
+ "count": 4,
+ "type": "VEC3"
+ },
+ {
+ "bufferView": 2,
+ "componentType": 5126,
+ "count": 4,
+ "type": "VEC2"
+ },
+ {
+ "bufferView": 3,
+ "componentType": 5123,
+ "count": 6,
+ "type": "SCALAR"
+ }
+ ],
+ "images": [
+ {
+ "mimeType": "image/png",
+ "uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAIAAAABCAIAAAB7QOjdAAAAD0lEQVR4nGP4//8/AwMDAA74Av7Ji4P1AAAAAElFTkSuQmCC"
+ }
+ ],
+ "samplers": [
+ {
+ "magFilter": 9728,
+ "minFilter": 9728
+ }
+ ],
+ "textures": [
+ {
+ "sampler": 0,
+ "source": 0
+ }
+ ],
+ "materials": [
+ {
+ "name": "Glow",
+ "pbrMetallicRoughness": {
+ "baseColorFactor": [
+ 0,
+ 0,
+ 0,
+ 1
+ ],
+ "metallicFactor": 0,
+ "roughnessFactor": 1
+ },
+ "emissiveFactor": [
+ 0,
+ 1,
+ 0
+ ],
+ "emissiveTexture": {
+ "index": 0
+ }
+ },
+ {
+ "name": "Shaded",
+ "pbrMetallicRoughness": {
+ "baseColorFactor": [
+ 1,
+ 1,
+ 1,
+ 1
+ ],
+ "metallicFactor": 0,
+ "roughnessFactor": 1
+ },
+ "occlusionTexture": {
+ "index": 0,
+ "strength": 1
+ }
+ },
+ {
+ "name": "Cutout",
+ "pbrMetallicRoughness": {
+ "baseColorFactor": [
+ 1,
+ 0,
+ 0,
+ 0.3
+ ],
+ "metallicFactor": 0,
+ "roughnessFactor": 1
+ },
+ "alphaMode": "MASK",
+ "alphaCutoff": 0.5
+ }
+ ],
+ "meshes": [
+ {
+ "name": "GlowQuad",
+ "primitives": [
+ {
+ "attributes": {
+ "POSITION": 0,
+ "NORMAL": 1,
+ "TEXCOORD_0": 2
+ },
+ "indices": 3,
+ "material": 0,
+ "mode": 4
+ }
+ ]
+ },
+ {
+ "name": "ShadedQuad",
+ "primitives": [
+ {
+ "attributes": {
+ "POSITION": 0,
+ "NORMAL": 1,
+ "TEXCOORD_0": 2
+ },
+ "indices": 3,
+ "material": 1,
+ "mode": 4
+ }
+ ]
+ },
+ {
+ "name": "CutoutQuad",
+ "primitives": [
+ {
+ "attributes": {
+ "POSITION": 0,
+ "NORMAL": 1,
+ "TEXCOORD_0": 2
+ },
+ "indices": 3,
+ "material": 2,
+ "mode": 4
+ }
+ ]
+ }
+ ],
+ "nodes": [
+ {
+ "name": "Glow",
+ "mesh": 0,
+ "translation": [
+ -220,
+ 0,
+ 0
+ ]
+ },
+ {
+ "name": "Shaded",
+ "mesh": 1,
+ "translation": [
+ 0,
+ 0,
+ 0
+ ]
+ },
+ {
+ "name": "Cutout",
+ "mesh": 2,
+ "translation": [
+ 220,
+ 0,
+ 0
+ ]
+ }
+ ],
+ "scenes": [
+ {
+ "nodes": [
+ 0,
+ 1,
+ 2
+ ]
+ }
+ ],
+ "scene": 0
+}
diff --git a/desktop/public/scenes/model-material.textures.json b/desktop/public/scenes/model-material.textures.json
new file mode 100644
index 000000000..0967ef424
--- /dev/null
+++ b/desktop/public/scenes/model-material.textures.json
@@ -0,0 +1 @@
+{}
diff --git a/desktop/public/scenes/model-material_0.png b/desktop/public/scenes/model-material_0.png
new file mode 100644
index 000000000..6c77d6fbf
Binary files /dev/null and b/desktop/public/scenes/model-material_0.png differ
diff --git a/desktop/public/scenes/model-material_0.png.meta b/desktop/public/scenes/model-material_0.png.meta
new file mode 100644
index 000000000..107acc233
--- /dev/null
+++ b/desktop/public/scenes/model-material_0.png.meta
@@ -0,0 +1,20 @@
+{
+ "uuid": "70c1fbce-23d0-417d-a861-83b4f9323cfb",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "compress": true,
+ "compressFormat": "uastc",
+ "filterMode": "nearest",
+ "wrapMode": "repeat",
+ "premultiplyAlpha": false,
+ "sRGB": true,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/desktop/public/scenes/model-material_0_0.esmesh b/desktop/public/scenes/model-material_0_0.esmesh
new file mode 100644
index 000000000..f1248f700
Binary files /dev/null and b/desktop/public/scenes/model-material_0_0.esmesh differ
diff --git a/desktop/public/scenes/model-material_0_0.esmesh.meta b/desktop/public/scenes/model-material_0_0.esmesh.meta
new file mode 100644
index 000000000..824637cf2
--- /dev/null
+++ b/desktop/public/scenes/model-material_0_0.esmesh.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "8d5193e3-f785-4792-8017-ffc8e9175d32",
+ "version": "2.0",
+ "type": "mesh",
+ "importer": {}
+}
diff --git a/desktop/public/scenes/model-material_1_0.esmesh b/desktop/public/scenes/model-material_1_0.esmesh
new file mode 100644
index 000000000..f1248f700
Binary files /dev/null and b/desktop/public/scenes/model-material_1_0.esmesh differ
diff --git a/desktop/public/scenes/model-material_1_0.esmesh.meta b/desktop/public/scenes/model-material_1_0.esmesh.meta
new file mode 100644
index 000000000..ba0fa9d33
--- /dev/null
+++ b/desktop/public/scenes/model-material_1_0.esmesh.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "8bdfabde-f176-4781-84f0-78e488a95db4",
+ "version": "2.0",
+ "type": "mesh",
+ "importer": {}
+}
diff --git a/desktop/public/scenes/model-material_2_0.esmesh b/desktop/public/scenes/model-material_2_0.esmesh
new file mode 100644
index 000000000..f1248f700
Binary files /dev/null and b/desktop/public/scenes/model-material_2_0.esmesh differ
diff --git a/desktop/public/scenes/model-material_2_0.esmesh.meta b/desktop/public/scenes/model-material_2_0.esmesh.meta
new file mode 100644
index 000000000..bfb17b2d3
--- /dev/null
+++ b/desktop/public/scenes/model-material_2_0.esmesh.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "16055a55-6179-4cca-ab49-03a4692918cb",
+ "version": "2.0",
+ "type": "mesh",
+ "importer": {}
+}
diff --git a/desktop/public/scenes/model-material_m0.esmaterial b/desktop/public/scenes/model-material_m0.esmaterial
new file mode 100644
index 000000000..7db117af0
--- /dev/null
+++ b/desktop/public/scenes/model-material_m0.esmaterial
@@ -0,0 +1,18 @@
+{
+ "version": "1.0",
+ "type": "material",
+ "shader": "builtin:model",
+ "blendMode": 9,
+ "depthTest": true,
+ "depthWrite": true,
+ "cull": 1,
+ "properties": {
+ "u_emissiveMap": "model-material_0.png",
+ "u_emissive": {
+ "r": 0,
+ "g": 1,
+ "b": 0,
+ "a": 1
+ }
+ }
+}
diff --git a/desktop/public/scenes/model-material_m0.esmaterial.meta b/desktop/public/scenes/model-material_m0.esmaterial.meta
new file mode 100644
index 000000000..c3ae74740
--- /dev/null
+++ b/desktop/public/scenes/model-material_m0.esmaterial.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "06d78bcc-f4ed-496e-b69d-5a5583aec7aa",
+ "version": "2.0",
+ "type": "material",
+ "importer": {}
+}
diff --git a/desktop/public/scenes/model-material_m1.esmaterial b/desktop/public/scenes/model-material_m1.esmaterial
new file mode 100644
index 000000000..ff1c5bb2c
--- /dev/null
+++ b/desktop/public/scenes/model-material_m1.esmaterial
@@ -0,0 +1,13 @@
+{
+ "version": "1.0",
+ "type": "material",
+ "shader": "builtin:model",
+ "blendMode": 9,
+ "depthTest": true,
+ "depthWrite": true,
+ "cull": 1,
+ "properties": {
+ "u_occlusionMap": "model-material_0.png",
+ "u_occlusionStrength": 1
+ }
+}
diff --git a/desktop/public/scenes/model-material_m1.esmaterial.meta b/desktop/public/scenes/model-material_m1.esmaterial.meta
new file mode 100644
index 000000000..1e3022860
--- /dev/null
+++ b/desktop/public/scenes/model-material_m1.esmaterial.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "ba633b43-4f8b-4524-8fac-42f89b319349",
+ "version": "2.0",
+ "type": "material",
+ "importer": {}
+}
diff --git a/desktop/public/scenes/model-material_m2.esmaterial b/desktop/public/scenes/model-material_m2.esmaterial
new file mode 100644
index 000000000..2aa6da3a8
--- /dev/null
+++ b/desktop/public/scenes/model-material_m2.esmaterial
@@ -0,0 +1,12 @@
+{
+ "version": "1.0",
+ "type": "material",
+ "shader": "builtin:model",
+ "blendMode": 9,
+ "depthTest": true,
+ "depthWrite": true,
+ "cull": 1,
+ "properties": {
+ "u_alphaCutoff": 0.5
+ }
+}
diff --git a/desktop/public/scenes/model-material_m2.esmaterial.meta b/desktop/public/scenes/model-material_m2.esmaterial.meta
new file mode 100644
index 000000000..049a43fe6
--- /dev/null
+++ b/desktop/public/scenes/model-material_m2.esmaterial.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "5abe3d53-41c8-47c3-a168-17bfaf79fec4",
+ "version": "2.0",
+ "type": "material",
+ "importer": {}
+}
diff --git a/desktop/public/scenes/normalmap-quad.esprefab b/desktop/public/scenes/normalmap-quad.esprefab
index 13500a611..ef12d75c6 100644
--- a/desktop/public/scenes/normalmap-quad.esprefab
+++ b/desktop/public/scenes/normalmap-quad.esprefab
@@ -19,7 +19,7 @@
"data": {
"mesh": "scenes/normalmap-quad.esmesh",
"lit": true,
- "normalMap": "scenes/normalmap-quad_0.png",
+ "material": "scenes/normalmap-quad_m0.esmaterial",
"color": {
"r": 1,
"g": 1,
diff --git a/desktop/public/scenes/normalmap-quad_m0.esmaterial b/desktop/public/scenes/normalmap-quad_m0.esmaterial
new file mode 100644
index 000000000..e1640478a
--- /dev/null
+++ b/desktop/public/scenes/normalmap-quad_m0.esmaterial
@@ -0,0 +1,12 @@
+{
+ "version": "1.0",
+ "type": "material",
+ "shader": "builtin:model",
+ "blendMode": 9,
+ "depthTest": true,
+ "depthWrite": true,
+ "cull": 1,
+ "properties": {
+ "u_normalMap": "normalmap-quad_0.png"
+ }
+}
diff --git a/desktop/public/scenes/normalmap-quad_m0.esmaterial.meta b/desktop/public/scenes/normalmap-quad_m0.esmaterial.meta
new file mode 100644
index 000000000..671057e71
--- /dev/null
+++ b/desktop/public/scenes/normalmap-quad_m0.esmaterial.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "6d919cd6-5600-48ee-9353-02e130046f97",
+ "version": "2.0",
+ "type": "material",
+ "importer": {}
+}
diff --git a/desktop/scripts/make-mesh-fixture.mjs b/desktop/scripts/make-mesh-fixture.mjs
index 62f1ea1c3..86c5f6657 100644
--- a/desktop/scripts/make-mesh-fixture.mjs
+++ b/desktop/scripts/make-mesh-fixture.mjs
@@ -27,8 +27,11 @@ const cli = path.join(HERE, '..', '..', 'pipeline', 'bin', 'estella.mjs');
//
// public/ stands in for the project root, so the prefab's refs read `scenes/…`
// — the spelling a component carries, resolved from the served root.
+// model-material: the three channels only a material can carry — emission,
+// occlusion, an alpha cutoff — one quad each.
for (const name of ['two-triangles.gltf', 'lit-triangles.gltf', 'white-triangles.gltf',
- 'textured-quad.gltf', 'node-tree.gltf', 'normalmap-quad.gltf']) {
+ 'textured-quad.gltf', 'node-tree.gltf', 'normalmap-quad.gltf',
+ 'model-material.gltf']) {
const run = spawnSync(process.execPath,
[cli, 'import-gltf', path.join(scenes, name), '--project', path.join(HERE, '..', 'public')], {
stdio: 'inherit',
diff --git a/desktop/tests/gltf-import.test.ts b/desktop/tests/gltf-import.test.ts
index 3fb97db9f..698c5bdd8 100644
--- a/desktop/tests/gltf-import.test.ts
+++ b/desktop/tests/gltf-import.test.ts
@@ -9,9 +9,10 @@
*/
import { describe, it, expect } from 'vitest';
import {
- importGltfMeshes, assembleGltfPrefab, type ImportedMesh, type PrefabAssembly,
+ importGltfMeshes, assembleGltfPrefab, materialProducts,
+ type ImportedMesh, type PrefabAssembly, type ProductRefs,
} from '../../pipeline/src/assets/gltfImport';
-import { MeshChannel } from 'esengine';
+import { BlendMode, CullMode, MeshChannel } from 'esengine';
import { plainTriangle, meshoptTriangle, dracoTriangle } from '../scripts/lib/gltfFixtures.mjs';
const PNG_1PX = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==';
@@ -162,9 +163,11 @@ describe('glTF material import', () => {
const line = warnings.join('\n');
expect(line).toContain('metallic-roughness');
expect(line).toContain('normal-map scale 0.4');
- expect(line).toContain('emissive');
- expect(line).toContain('alpha cutoff 0.4');
expect(line).toContain('KHR_materials_clearcoat');
+ // Shading a metal needs a view direction, which 2D lights have not got; the
+ // channels that DO reach a shader are products, not warnings.
+ expect(line).not.toContain('emissive');
+ expect(line).not.toContain('alpha cutoff');
});
it('is opaque and single-sided unless the source says otherwise', async () => {
@@ -312,6 +315,101 @@ describe('glTF material import', () => {
});
});
+describe('glTF material products', () => {
+ const shaded = (extra: Record<string, unknown>): Record<string, unknown> => {
+ const doc = withInlineImage();
+ doc.materials = [{ name: 'Shaded', ...extra }];
+ return doc;
+ };
+ const productsOf = async (doc: Record<string, unknown>, refs: ProductRefs = {}) => {
+ const { meshes } = await importGltfMeshes(gltf(doc), 'model');
+ return { meshes, products: materialProducts(meshes, 'model', refs) };
+ };
+
+ it('writes nothing for a material a Mesh2D already carries whole', async () => {
+ // baseColor is the component's own texture x colour, so a material here
+ // would be a second file saying what the first one says.
+ const { products } = await productsOf(withInlineImage());
+ expect(products).toEqual([]);
+ });
+
+ it('carries the channels a component has no room for', async () => {
+ const { products } = await productsOf(shaded({
+ emissiveFactor: [1, 0.5, 0], emissiveTexture: { index: 0 },
+ occlusionTexture: { index: 0, strength: 0.25 },
+ alphaMode: 'MASK', alphaCutoff: 0.4,
+ }), { prefix: 'assets/models/' });
+ expect(products).toHaveLength(1);
+ expect(products[0]!.name).toBe('model_m0');
+ expect(products[0]!.data.shader).toBe('builtin:model');
+ expect(products[0]!.data.properties).toEqual({
+ u_emissive: { r: 1, g: 0.5, b: 0, a: 1 },
+ u_emissiveMap: 'model_0.png',
+ u_occlusionMap: 'model_0.png',
+ u_occlusionStrength: 0.25,
+ u_alphaCutoff: 0.4,
+ });
+ });
+
+ it('takes the normal map WITH it, off the component', async () => {
+ // A material shader samples its own units; a map left on the component
+ // would be one nothing reads.
+ const { meshes, products } = await productsOf(
+ shaded({ normalTexture: { index: 0 }, emissiveFactor: [1, 1, 1] }),
+ { prefix: 'assets/models/' });
+ expect(products[0]!.data.properties.u_normalMap).toBe('model_0.png');
+ const prefab = assembleGltfPrefab('model', meshes, { refs: { prefix: 'assets/models/' } });
+ const mesh2d = prefab.entities[1]!.components[1]!.data;
+ expect(mesh2d.material).toBe('assets/models/model_m0.esmaterial');
+ expect(mesh2d.normalMap).toBeUndefined();
+ });
+
+ it('says the render state the draw would otherwise have said itself', async () => {
+ // A material REPLACES the draw's blend/depth/cull, so a model told to
+ // occlude itself must keep saying so through the material.
+ const opaque = await productsOf(shaded({ emissiveFactor: [1, 1, 1] }));
+ expect(opaque.products[0]!.data).toMatchObject({
+ blendMode: BlendMode.None, depthTest: true, depthWrite: true, cull: CullMode.Back,
+ });
+ const blended = await productsOf(shaded({
+ emissiveFactor: [1, 1, 1], alphaMode: 'BLEND', doubleSided: true,
+ }));
+ expect(blended.products[0]!.data).toMatchObject({
+ blendMode: BlendMode.Normal, depthTest: false, depthWrite: false, cull: CullMode.None,
+ });
+ });
+
+ it('writes one product for a material several primitives share', async () => {
+ const doc = shaded({ emissiveFactor: [0, 0, 1] });
+ const { meshes } = await importGltfMeshes(gltf(doc, [
+ { attributes: { POSITION: 0, TEXCOORD_0: 1 }, indices: 2, material: 0, mode: 4 },
+ { attributes: { POSITION: 0, TEXCOORD_0: 1 }, indices: 2, material: 0, mode: 4 },
+ ]), 'model');
+ const refs = { prefix: 'assets/models/' };
+ expect(materialProducts(meshes, 'model', refs)).toHaveLength(1);
+ const prefab = assembleGltfPrefab('model', meshes, { refs });
+ const refsUsed = prefab.entities.flatMap(e => e.components
+ .filter(c => c.type === 'Mesh2D').map(c => c.data.material));
+ expect(refsUsed).toEqual(['assets/models/model_m0.esmaterial',
+ 'assets/models/model_m0.esmaterial']);
+ });
+
+ it('spells an image already in the project as a logical path', async () => {
+ // A material resolves a relative ref against its own directory, and this one
+ // is not beside it.
+ const doc = shaded({ emissiveTexture: { index: 0 } });
+ doc.images = [{ uri: 'shared/glow.png' }];
+ const inAssets = await productsOf(doc, {
+ prefix: 'assets/models/', external: (uri) => `assets/${uri}`,
+ });
+ expect(inAssets.products[0]!.data.properties.u_emissiveMap).toBe('assets/shared/glow.png');
+ const elsewhere = await productsOf(doc, {
+ prefix: 'models/', external: (uri) => `art/${uri}`,
+ });
+ expect(elsewhere.products[0]!.data.properties.u_emissiveMap).toBe('/art/shared/glow.png');
+ });
+});
+
describe('glTF prefab assembly', () => {
const assemble = async (bytes: Uint8Array, options: Partial<PrefabAssembly> = {}) => {
const { meshes, nodes } = await importGltfMeshes(bytes, 'model');
diff --git a/desktop/tests/import-model.test.ts b/desktop/tests/import-model.test.ts
index 152b44d52..b029d72fa 100644
--- a/desktop/tests/import-model.test.ts
+++ b/desktop/tests/import-model.test.ts
@@ -83,6 +83,29 @@ describe('importing a model', () => {
expect(prefab.entities[0]!.components[1]!.data.mesh).toBe('assets/models/robot.esmesh');
});
+ it('writes a material for the shading the component cannot carry', async () => {
+ const doc = JSON.parse(gltf('glow.png')) as
+ { materials: Record<string, unknown>[] };
+ doc.materials[0]!.emissiveTexture = { index: 0 };
+ doc.materials[0]!.emissiveFactor = [1, 0.5, 0];
+ writeFileSync(path.join(outside, 'glow.png'), 'PNG');
+ const src = path.join(outside, 'robot.gltf');
+ writeFileSync(src, JSON.stringify(doc));
+ const res = await importAssets(root, 'assets/models', [src]);
+
+ expect(res.imported).toContain('assets/models/robot_m0.esmaterial');
+ expect(meta(path.join(root, 'assets/models/robot_m0.esmaterial')).type).toBe('material');
+ const material = JSON.parse(
+ readFileSync(path.join(root, 'assets/models/robot_m0.esmaterial'), 'utf8'),
+ ) as { shader: string; properties: Record<string, unknown> };
+ expect(material.shader).toBe('builtin:model');
+ // Beside the material, so its bare name is what a relative resolve wants.
+ expect(material.properties.u_emissiveMap).toBe('glow.png');
+ const prefab = prefabOf(path.join(root, 'assets/models/robot.esprefab'));
+ expect(prefab.entities[0]!.components[1]!.data.material)
+ .toBe('assets/models/robot_m0.esmaterial');
+ });
+
it('produces beside an in-project source, not in the browser’s folder', async () => {
const abs = path.join(root, 'assets/sub/tree.gltf');
mkdirSync(path.dirname(abs), { recursive: true });
diff --git a/docs/astro/src/content/docs/graphics/materials.mdx b/docs/astro/src/content/docs/graphics/materials.mdx
index 79d573e78..31b276da4 100644
--- a/docs/astro/src/content/docs/graphics/materials.mdx
+++ b/docs/astro/src/content/docs/graphics/materials.mdx
@@ -32,6 +32,7 @@ creates a material from a built-in template — the same list ships in code as
| **Dissolve** | `sprite-dissolve` | Noise burn-away with a glowing edge (`u_progress` 0→1). |
| **Pixelate** | `sprite-pixelate` | Quantizes UVs to a `u_pixels` grid. |
| **UV Scroll** | `sprite-uv-scroll` | Scrolls the texture by `u_scrollSpeed` × time. |
+| **Model** | `model` | What a glTF material says beyond base color: `u_normalMap`, `u_emissive`(`Map`), `u_occlusionMap` + `u_occlusionStrength`, `u_alphaCutoff`. Written by model import. |
A new material **references** its template by id — it stores `shader: "builtin:sprite-unlit"`
and writes **no shader file** to disk. The engine compiles the built-in from in-code source
@@ -135,6 +136,7 @@ The engine injects these into every compiled `.esshader` — never declare them
| `u_viewport` | always | `vec4` canvas: `.xy` size in pixels, `.zw` = 1/size (screen UV = `gl_FragCoord.xy * u_viewport.zw`). |
| MaterialConstants block | when the shader has params | Your `#pragma param` values. |
| `applyLighting2D(albedo, N, worldPos)` | Lit2D | Applies every scene light (+shadows); returns the lit color. |
+| `applyLighting2DAO(albedo, N, worldPos, ao)` | Lit2D | The same, with the ambient term scaled by `ao` (1 = unoccluded). |
| `sampleNormal(map, uv)` | Lit2D | Unpacks a tangent-space normal map (RGB → [-1,1], normalized). |
| `shadowFactor2D(worldPos, target, softness)` | Lit2D | Occlusion factor toward a point (used by `applyLighting2D`). |
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx b/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx
index f1f789cd5..c045aa1ef 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx
@@ -28,6 +28,7 @@ std140 uniform 块,于是 CPU 能按名字设置、并安全地送到 GPU。一
| **Dissolve** | `sprite-dissolve` | 噪声烧蚀 + 发光边缘(`u_progress` 0→1)。 |
| **Pixelate** | `sprite-pixelate` | UV 量化到 `u_pixels` 网格。 |
| **UV Scroll** | `sprite-uv-scroll` | 按 `u_scrollSpeed` × 时间滚动纹理。 |
+| **Model** | `model` | glTF 材质在 base color 之外说的东西:`u_normalMap`、`u_emissive`(`Map`)、`u_occlusionMap` + `u_occlusionStrength`、`u_alphaCutoff`。模型导入会写出它。 |
新建材质是**按 id 引用**其模板的——它存的是 `shader: "builtin:sprite-unlit"`,并**不会**在磁盘上
写出 shader 文件。引擎从内置源码编译该模板(运行时加载器、cook 步骤、编辑器三处以同样方式解析
@@ -119,6 +120,7 @@ std140 uniform 块,于是 CPU 能按名字设置、并安全地送到 GPU。一
| `u_viewport` | 总是 | `vec4` 画布:`.xy` 像素尺寸,`.zw` = 1/尺寸(屏幕 UV = `gl_FragCoord.xy * u_viewport.zw`)。 |
| MaterialConstants 块 | 着色器有参数时 | 你的 `#pragma param` 值。 |
| `applyLighting2D(albedo, N, worldPos)` | Lit2D | 应用场景所有灯光(含阴影),返回受光颜色。 |
+| `applyLighting2DAO(albedo, N, worldPos, ao)` | Lit2D | 同上,但环境光项乘以 `ao`(1 = 无遮蔽)。 |
| `sampleNormal(map, uv)` | Lit2D | 解包切线空间法线贴图(RGB → [-1,1],归一化)。 |
| `shadowFactor2D(worldPos, target, softness)` | Lit2D | 朝向目标点的遮挡系数(`applyLighting2D` 内部使用)。 |
diff --git a/examples/model-import/assets/models/robot.esprefab b/examples/model-import/assets/models/robot.esprefab
index d120386ba..501f9f300 100644
--- a/examples/model-import/assets/models/robot.esprefab
+++ b/examples/model-import/assets/models/robot.esprefab
@@ -40,6 +40,7 @@
"type": "Mesh2D",
"data": {
"mesh": "assets/models/robot_0_0.esmesh",
+ "lit": true,
"texture": "assets/models/robot_0.png",
"color": {
"r": 1,
@@ -80,6 +81,8 @@
"type": "Mesh2D",
"data": {
"mesh": "assets/models/robot_1_0.esmesh",
+ "lit": true,
+ "material": "assets/models/robot_m1.esmaterial",
"color": {
"r": 0.32,
"g": 0.54,
diff --git a/examples/model-import/assets/models/robot.gltf b/examples/model-import/assets/models/robot.gltf
index 3b23ae577..a39441cfd 100644
--- a/examples/model-import/assets/models/robot.gltf
+++ b/examples/model-import/assets/models/robot.gltf
@@ -168,7 +168,12 @@
],
"metallicFactor": 0,
"roughnessFactor": 1
- }
+ },
+ "emissiveFactor": [
+ 0.9,
+ 0.25,
+ 0.1
+ ]
}
],
"meshes": [
diff --git a/examples/model-import/assets/models/robot_m1.esmaterial b/examples/model-import/assets/models/robot_m1.esmaterial
new file mode 100644
index 000000000..27f557105
--- /dev/null
+++ b/examples/model-import/assets/models/robot_m1.esmaterial
@@ -0,0 +1,17 @@
+{
+ "version": "1.0",
+ "type": "material",
+ "shader": "builtin:model",
+ "blendMode": 9,
+ "depthTest": true,
+ "depthWrite": true,
+ "cull": 1,
+ "properties": {
+ "u_emissive": {
+ "r": 0.9,
+ "g": 0.25,
+ "b": 0.1,
+ "a": 1
+ }
+ }
+}
diff --git a/examples/model-import/assets/models/robot_m1.esmaterial.meta b/examples/model-import/assets/models/robot_m1.esmaterial.meta
new file mode 100644
index 000000000..088928a14
--- /dev/null
+++ b/examples/model-import/assets/models/robot_m1.esmaterial.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "8334ea1e-6d68-4f88-8f42-fa6ec0483565",
+ "version": "2.0",
+ "type": "material",
+ "importer": {}
+}
diff --git a/pipeline/bin/estella.mjs b/pipeline/bin/estella.mjs
index 2cc7ce09b..bf19f5173 100644
--- a/pipeline/bin/estella.mjs
+++ b/pipeline/bin/estella.mjs
@@ -201,7 +201,8 @@ if (opts.command === 'import-gltf') {
// Settings the source asked for, by product name; only ever the FIRST mint.
const settings = new Map();
for (const mesh of meshes) {
- for (const image of [mesh.material?.baseColorTexture, mesh.material?.normalTexture]) {
+ for (const image of [mesh.material?.baseColorTexture, mesh.material?.normalTexture,
+ mesh.material?.emissiveTexture, mesh.material?.occlusionTexture]) {
if (image?.settings) settings.set(image.file, image.settings);
}
}
@@ -219,6 +220,12 @@ if (opts.command === 'import-gltf') {
await adopt(outFile);
report(outFile, `${texture.bytes.length} bytes`);
}
+ for (const material of importer.materialProducts(meshes, stem, refs)) {
+ const outFile = path.join(dir, `${material.name}.esmaterial`);
+ writeFileSync(outFile, `${JSON.stringify(material.data, null, 2)}\n`);
+ await adopt(outFile);
+ report(outFile, Object.keys(material.data.properties).join(', '));
+ }
if (meshes.length > 0) {
const outFile = path.join(dir, `${stem}.esprefab`);
const prefab = importer.assembleGltfPrefab(stem, meshes, { refs, nodes, scale: opts.scale });
diff --git a/pipeline/src/assets/gltfImport.ts b/pipeline/src/assets/gltfImport.ts
index eb98f90e8..e64c75266 100644
--- a/pipeline/src/assets/gltfImport.ts
+++ b/pipeline/src/assets/gltfImport.ts
@@ -12,7 +12,8 @@
/// <reference path="./draco3dgltf.d.ts" />
import {
MeshChannel, MeshChannelType, packChannels, encodeMesh, PREFAB_FORMAT_VERSION,
- type MeshData, type PrefabData, type PrefabEntityData,
+ MATERIAL_FORMAT_VERSION, BlendMode, CullMode,
+ type MeshData, type MaterialAssetData, type PrefabData, type PrefabEntityData,
type PrefabComponentData as ComponentData,
} from 'esengine';
import { MeshoptDecoder } from 'meshoptimizer/decoder';
@@ -40,23 +41,44 @@ export interface ImportedImageRef {
}
/**
- * A glTF material in the terms a Mesh2D carries: the engine's mesh path is
- * `texture(uv) * vertexColor * tint`, which is what glTF calls baseColor. The
- * PBR channels around it have no consumer here and are reported, not dropped.
+ * A glTF material, split by what can carry it: baseColor is `texture(uv) *
+ * vertexColor * tint`, which a Mesh2D's own fields say, and the shading around
+ * it becomes an `.esmaterial` (@ref materialProducts). What neither can express
+ * is reported, not dropped.
*/
export interface ImportedMaterial {
+ /** The source's own material index — what its product is named after. */
+ index: number;
name: string;
/** baseColorFactor — the tint multiplied into the vertex colors. */
baseColor: [number, number, number, number];
baseColorTexture?: ImportedImageRef;
/** Tangent-space normal map; the engine derives its tangent frame per pixel. */
normalTexture?: ImportedImageRef;
+ /** emissiveFactor — light the surface makes, unaffected by the scene's lights. */
+ emissive?: [number, number, number];
+ emissiveTexture?: ImportedImageRef;
+ /** Ambient occlusion in the map's red channel, scaled by @ref occlusionStrength. */
+ occlusionTexture?: ImportedImageRef;
+ occlusionStrength?: number;
+ /** alphaMode MASK: a fragment below this alpha is discarded (glTF default 0.5). */
+ alphaCutoff?: number;
/** Not BLEND: drawn without blending, and taking part in depth. */
opaque: boolean;
/** `doubleSided: false` (the glTF default): back faces are not drawn. */
cullBackfaces: boolean;
}
+/** A material product: the shading a Mesh2D's own fields cannot say. */
+export interface ImportedMaterialAsset {
+ /** `<stem>_m<material index>` — stable across re-imports, so overrides keep matching. */
+ name: string;
+ /** The `.esmaterial` document. */
+ data: MaterialAssetData;
+ /** Every image it references, so the caller can carry the sampler settings over. */
+ images: ImportedImageRef[];
+}
+
/** An image the glTF carries inline (GLB chunk or data uri), to be written beside the meshes. */
export interface ImportedTexture {
/** `<stem>_<image index>.<ext>` — named for the source, since an inline image has no name. */
@@ -107,6 +129,8 @@ const TYPE_COMPONENTS: Record<string, number> = {
interface GltfTextureRef {
index: number; texCoord?: number;
+ /** How much of an occlusionTexture's shadowing applies (occlusionTextureInfo only). */
+ strength?: number;
/** KHR_texture_transform and friends: a uv rewrite this importer does not do. */
extensions?: Record<string, unknown>;
}
@@ -552,10 +576,10 @@ function readTexture(ctx: MaterialContext, cache: Map<number, ImportedImageRef |
}
/**
- * One glTF material as the baseColor a Mesh2D can carry. Everything a PBR
- * material says beyond that — metal, roughness, emission, a normal map, an alpha
- * cutoff — has no consumer in this engine yet, so it is reported rather than
- * quietly lost.
+ * One glTF material, read into the two things that can hold it (@ref
+ * materialProducts). Metal and roughness stay reported-not-imported: shading
+ * them needs a view direction and this engine's lights are 2D, so a metallic
+ * factor in a product would be a knob nothing reads.
*/
function readMaterial(ctx: MaterialContext, textureCache: Map<number, ImportedImageRef | null>,
index: number): ImportedMaterial {
@@ -568,14 +592,9 @@ function readMaterial(ctx: MaterialContext, textureCache: Map<number, ImportedIm
if (pbr.metallicRoughnessTexture || (pbr.metallicFactor ?? 1) !== 0 || (pbr.roughnessFactor ?? 1) !== 1) {
unused.push('metallic-roughness');
}
- // Alpha coverage beyond opaque/blended has no equivalent: the engine draws a
- // masked material as opaque, which is the closer of the two.
if (src.normalTexture?.scale !== undefined && src.normalTexture.scale !== 1) {
unused.push(`normal-map scale ${src.normalTexture.scale}`);
}
- if (src.occlusionTexture) unused.push('occlusion');
- if (src.emissiveTexture || (src.emissiveFactor ?? [0, 0, 0]).some(v => v !== 0)) unused.push('emissive');
- if (src.alphaMode === 'MASK') unused.push(`alpha cutoff ${src.alphaCutoff ?? 0.5}`);
for (const name of Object.keys(src.extensions ?? {})) unused.push(name);
if (unused.length > 0) ctx.warnings.push(`${label}: ${unused.join(', ')} not imported`);
@@ -583,15 +602,31 @@ function readMaterial(ctx: MaterialContext, textureCache: Map<number, ImportedIm
? readTexture(ctx, textureCache, pbr.baseColorTexture, label) : null;
const normal = src.normalTexture
? readTexture(ctx, textureCache, src.normalTexture, label) : null;
+ const emissiveMap = src.emissiveTexture
+ ? readTexture(ctx, textureCache, src.emissiveTexture, label) : null;
+ const occlusionMap = src.occlusionTexture
+ ? readTexture(ctx, textureCache, src.occlusionTexture, label) : null;
+ const emissive = src.emissiveFactor ?? (emissiveMap ? [1, 1, 1] : [0, 0, 0]);
return {
+ index,
name: src.name ?? `material_${index}`,
baseColor: [factor[0] ?? 1, factor[1] ?? 1, factor[2] ?? 1, factor[3] ?? 1],
// A glTF is OPAQUE and single-sided unless it says otherwise, so a model
- // arrives occluding itself the way it was authored to.
+ // arrives occluding itself the way it was authored to. MASK is opaque
+ // too — what it adds is the cutoff below.
opaque: (src.alphaMode ?? 'OPAQUE') !== 'BLEND',
cullBackfaces: src.doubleSided !== true,
...(texture ? { baseColorTexture: texture } : {}),
...(normal ? { normalTexture: normal } : {}),
+ ...(emissive.some(v => v !== 0)
+ ? { emissive: [emissive[0] ?? 0, emissive[1] ?? 0, emissive[2] ?? 0] as [number, number, number] }
+ : {}),
+ ...(emissiveMap ? { emissiveTexture: emissiveMap } : {}),
+ ...(occlusionMap ? {
+ occlusionTexture: occlusionMap,
+ occlusionStrength: src.occlusionTexture?.strength ?? 1,
+ } : {}),
+ ...(src.alphaMode === 'MASK' ? { alphaCutoff: src.alphaCutoff ?? 0.5 } : {}),
};
}
@@ -932,17 +967,112 @@ export interface PrefabAssembly {
scale?: number;
}
-function meshComponent(mesh: ImportedMesh, refs: ProductRefs): ComponentData {
+/** How a component spells a reference to an image: a project-relative path. */
+function imageRef(image: ImportedImageRef, refs: ProductRefs): string {
+ return image.external
+ ? refs.external?.(image.file) ?? image.file
+ : (refs.prefix ?? '') + image.file;
+}
+
+/**
+ * How a MATERIAL spells the same reference. It resolves a relative ref against
+ * its own directory, and every product lands beside it, so a product is its bare
+ * name; a file already in the project takes a logical path instead — the one
+ * other spelling that resolver passes through (as `rewriteMaterialRefs` writes).
+ */
+function materialImageRef(image: ImportedImageRef, refs: ProductRefs): string {
+ const dir = refs.prefix ?? '';
+ const ref = imageRef(image, refs);
+ if (ref.startsWith(dir)) {
+ const beside = ref.slice(dir.length);
+ if (beside.length > 0 && !beside.includes('/')) return beside;
+ }
+ return ref.startsWith('assets/') || ref.startsWith('/') ? ref : `/${ref}`;
+}
+
+/**
+ * Whether this material says anything a Mesh2D's own fields cannot. Shading —
+ * normal map, emission, occlusion, an alpha cutoff — is per-material constants
+ * and samplers, and the component has neither: its per-object attributes end at
+ * location 15, the ceiling both backends guarantee.
+ */
+function needsMaterial(material: ImportedMaterial | undefined): material is ImportedMaterial {
+ return !!material && !!(material.normalTexture || material.emissive || material.emissiveTexture
+ || material.occlusionTexture || material.alphaCutoff);
+}
+
+/** `<stem>_m<source material index>` — the product a material becomes. */
+function materialName(stem: string, material: ImportedMaterial): string {
+ return `${stem}_m${material.index}`;
+}
+
+/**
+ * The `.esmaterial` documents an import writes, one per source material that
+ * needs one. The render state is written out because a material REPLACES the
+ * draw's own — a model told to occlude itself would start blending the moment
+ * it gained a material.
+ */
+export function materialProducts(meshes: ImportedMesh[], stem: string,
+ refs: ProductRefs = {}): ImportedMaterialAsset[] {
+ const out: ImportedMaterialAsset[] = [];
+ const seen = new Set<number>();
+ for (const mesh of meshes) {
+ const material = mesh.material;
+ if (!needsMaterial(material) || seen.has(material.index)) continue;
+ seen.add(material.index);
+
+ const images: ImportedImageRef[] = [];
+ const properties: Record<string, unknown> = {};
+ const bind = (name: string, image?: ImportedImageRef): void => {
+ if (!image) return;
+ images.push(image);
+ properties[name] = materialImageRef(image, refs);
+ };
+ bind('u_normalMap', material.normalTexture);
+ bind('u_emissiveMap', material.emissiveTexture);
+ bind('u_occlusionMap', material.occlusionTexture);
+ if (material.emissive) {
+ const [r, g, b] = material.emissive;
+ properties.u_emissive = { r, g, b, a: 1 };
+ }
+ if (material.occlusionStrength !== undefined) {
+ properties.u_occlusionStrength = material.occlusionStrength;
+ }
+ if (material.alphaCutoff !== undefined) properties.u_alphaCutoff = material.alphaCutoff;
+
+ out.push({
+ name: materialName(stem, material),
+ data: {
+ version: MATERIAL_FORMAT_VERSION,
+ type: 'material',
+ shader: 'builtin:model',
+ blendMode: material.opaque ? BlendMode.None : BlendMode.Normal,
+ depthTest: material.opaque,
+ depthWrite: material.opaque,
+ cull: material.cullBackfaces ? CullMode.Back : CullMode.None,
+ properties,
+ },
+ images,
+ });
+ }
+ return out;
+}
+
+function meshComponent(mesh: ImportedMesh, stem: string, refs: ProductRefs): ComponentData {
const prefix = refs.prefix ?? '';
- const ref = (image?: ImportedImageRef): string | null => image
- ? (image.external ? refs.external?.(image.file) ?? image.file : prefix + image.file)
- : null;
- const texture = ref(mesh.material?.baseColorTexture);
- // A normal map needs normals to perturb; without them the engine draws the
- // unlit variant and the map would be a reference to nothing.
+ const texture = mesh.material?.baseColorTexture
+ ? imageRef(mesh.material.baseColorTexture, refs) : null;
const hasNormals = mesh.data.channels.some(c => c.semantic === MeshChannel.Normal);
- const normalMap = hasNormals ? ref(mesh.material?.normalTexture) : null;
const color = mesh.material?.baseColor;
+ // Shading moves WHOLE to the material when there is one: a material shader
+ // reads its own samplers, so a normal map left on the component would be a
+ // map nothing samples.
+ const material = needsMaterial(mesh.material)
+ ? `${prefix}${materialName(stem, mesh.material)}.esmaterial` : null;
+ // A normal map needs normals to perturb; without them the engine draws the
+ // unlit variant and the map would be a reference to nothing.
+ const normalMap = !material && hasNormals && mesh.material?.normalTexture
+ ? imageRef(mesh.material.normalTexture, refs) : null;
return { type: 'Mesh2D', data: {
mesh: `${prefix}${mesh.name}.esmesh`,
// Geometry that carries normals was authored to be shaded, so the product
@@ -951,6 +1081,7 @@ function meshComponent(mesh: ImportedMesh, refs: ProductRefs): ComponentData {
...(hasNormals ? { lit: true } : {}),
...(texture ? { texture } : {}),
...(normalMap ? { normalMap } : {}),
+ ...(material ? { material } : {}),
...(color ? { color: { r: color[0], g: color[1], b: color[2], a: color[3] } } : {}),
...(mesh.material?.opaque ? { opaque: true } : {}),
...(mesh.material?.cullBackfaces ? { cullBackfaces: true } : {}),
@@ -994,7 +1125,7 @@ export function assembleGltfPrefab(name: string, meshes: ImportedMesh[],
const drawn = node.meshes.map(i => meshes[i]).filter((m): m is ImportedMesh => !!m);
// One primitive rides the node itself; several cannot, since a Mesh2D
// draws one mesh — they become its children, at its own origin.
- const own = drawn.length === 1 && drawn[0] ? [meshComponent(drawn[0], refs)] : [];
+ const own = drawn.length === 1 && drawn[0] ? [meshComponent(drawn[0], name, refs)] : [];
const self = entity(id, node.name, parent,
[transformComponent(node, rootScale), ...own]);
entities.push(self);
@@ -1003,7 +1134,7 @@ export function assembleGltfPrefab(name: string, meshes: ImportedMesh[],
const childId = `${id}_p${i}`;
self.children.push(childId);
entities.push(entity(childId, mesh.name, id,
- [transformComponent(), meshComponent(mesh, refs)]));
+ [transformComponent(), meshComponent(mesh, name, refs)]));
});
}
for (const child of node.children) self.children.push(emitNode(child, id));
@@ -1026,7 +1157,7 @@ export function assembleGltfPrefab(name: string, meshes: ImportedMesh[],
const id = `m${i}`;
root.children.push(id);
entities.push(entity(id, mesh.name, 'root',
- [transformComponent(), meshComponent(mesh, refs)]));
+ [transformComponent(), meshComponent(mesh, name, refs)]));
});
}
return {
diff --git a/sdk/src/render/builtinShaders.ts b/sdk/src/render/builtinShaders.ts
index f999ece09..b3538ea6d 100644
--- a/sdk/src/render/builtinShaders.ts
+++ b/sdk/src/render/builtinShaders.ts
@@ -324,6 +324,73 @@ void main() {
#pragma end
`;
+// The shading a glTF material says beyond its base colour. Those channels are
+// per-material constants and per-material samplers, which is what a material has
+// and a component does not — a Mesh2D's per-object attributes are full.
+const MODEL = `#pragma shader "Model"
+#pragma version 300 es
+#pragma domain Lit2D
+#pragma param u_tint color default(1,1,1,1)
+#pragma param u_normalMap texture default(flatnormal)
+#pragma param u_emissive color default(0,0,0,1)
+#pragma param u_emissiveMap texture default(white)
+#pragma param u_occlusionMap texture default(white)
+#pragma param u_occlusionStrength float default(1) range(0,1) ui(slider)
+#pragma param u_alphaCutoff float default(0) range(0,1) ui(slider)
+
+#pragma fragment
+precision mediump float;
+
+in vec4 v_color;
+in vec2 v_texCoord;
+in highp vec2 v_worldPos;
+#ifdef MESH_NORMALS
+in highp vec3 v_worldNormal;
+in highp vec3 v_worldXYZ;
+#endif
+
+uniform sampler2D u_textures[8];
+
+out vec4 fragColor;
+
+// Base colour rides the draw itself (slot 0 x vertex colour) — glTF's baseColor
+// is what a Mesh2D already carries. Emission is added AFTER lighting (it is light
+// this surface makes) and occlusion scales only the ambient term.
+void main() {
+ vec4 base = texture(u_textures[0], v_texCoord) * v_color * u_tint;
+ if (base.a < u_alphaCutoff) discard;
+#ifdef MESH_NORMALS
+ highp vec3 N = perturbNormal(normalize(v_worldNormal), v_worldXYZ, v_texCoord,
+ sampleNormal(u_normalMap, v_texCoord));
+#else
+ vec3 N = sampleNormal(u_normalMap, v_texCoord);
+#endif
+ float ao = mix(1.0, texture(u_occlusionMap, v_texCoord).r, u_occlusionStrength);
+ vec3 lit = applyLighting2DAO(base.rgb, N, v_worldPos, ao);
+ fragColor = vec4(lit + u_emissive.rgb * texture(u_emissiveMap, v_texCoord).rgb, base.a);
+}
+#pragma end
+
+#pragma fragment wgsl
+@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
+ let base = textureSampleLevel(t0, s0, v.v_texCoord, 0.0) * v.v_color * mc.u_tint;
+ if (base.a < mc.u_alphaCutoff) { discard; }
+#ifdef MESH_NORMALS
+ let N = perturbNormal(normalize(v.v_worldNormal), v.v_worldXYZ, v.v_texCoord,
+ sampleNormal(u_normalMap, u_normalMap_s, v.v_texCoord));
+#else
+ let N = sampleNormal(u_normalMap, u_normalMap_s, v.v_texCoord);
+#endif
+ let occl = textureSampleLevel(u_occlusionMap, u_occlusionMap_s, v.v_texCoord, 0.0).r;
+ let ao = mix(1.0, occl, mc.u_occlusionStrength);
+ let lit = applyLighting2DAO(base.rgb, N, v.v_worldPos, ao);
+ let emit = mc.u_emissive.rgb
+ * textureSampleLevel(u_emissiveMap, u_emissiveMap_s, v.v_texCoord, 0.0).rgb;
+ return vec4f(lit + emit, base.a);
+}
+#pragma end
+`;
+
export const BUILTIN_SHADER_TEMPLATES: readonly BuiltinShaderTemplate[] = [
template('sprite-unlit', 'Unlit', 'Texture × vertex color × tint, no lighting.', SPRITE_UNLIT),
template('sprite-lit', 'Lit', 'Lit by the scene\'s 2D lights; optional normal map.', SPRITE_LIT),
@@ -336,6 +403,9 @@ export const BUILTIN_SHADER_TEMPLATES: readonly BuiltinShaderTemplate[] = [
template('sprite-pixelate', 'Pixelate', 'Quantizes UVs to a coarse pixel grid.', SPRITE_PIXELATE),
template('sprite-uv-scroll', 'UV Scroll',
'Scrolls the texture over time (conveyors, water, clouds).', SPRITE_UV_SCROLL),
+ template('model', 'Model',
+ 'What an imported model\'s material says: normal map, emission, occlusion, alpha cutoff.',
+ MODEL),
];
export function builtinShaderTemplate(id: string): BuiltinShaderTemplate | undefined {
diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cpp
index 18fe2e897..9950fc40e 100644
--- a/src/esengine/resource/ShaderParser.cpp
+++ b/src/esengine/resource/ShaderParser.cpp
@@ -755,8 +755,8 @@ fn shadowFactor2D(worldPos : vec2f, aim : vec2f, softness : f32) -> f32 {
}
return 1.0 - blocked / 5.0;
}
-fn applyLighting2D(albedo : vec3f, N : vec3f, worldPos : vec2f) -> vec3f {
- var lit = lc.u_ambient.rgb;
+fn applyLighting2DAO(albedo : vec3f, N : vec3f, worldPos : vec2f, ao : f32) -> vec3f {
+ var lit = lc.u_ambient.rgb * ao;
for (var i = 0; i < 16; i++) {
let pd = lc.u_lights[i].posDir;
let col = lc.u_lights[i].color;
@@ -795,6 +795,9 @@ fn applyLighting2D(albedo : vec3f, N : vec3f, worldPos : vec2f) -> vec3f {
}
return albedo * lit;
}
+fn applyLighting2D(albedo : vec3f, N : vec3f, worldPos : vec2f) -> vec3f {
+ return applyLighting2DAO(albedo, N, worldPos, 1.0);
+}
)";
std::string trimWs(const std::string& s) {
@@ -1131,8 +1134,11 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
" }\n"
" return 1.0 - blocked / float(K);\n"
"}\n"
- "highp vec3 applyLighting2D(highp vec3 albedo, highp vec3 N, highp vec2 worldPos) {\n"
- " highp vec3 lit = u_ambient.rgb;\n"
+ // Ambient occlusion darkens the light that arrives from everywhere, which is
+ // the ambient term; a lit surface's own lights are unobstructed by it.
+ "highp vec3 applyLighting2DAO(highp vec3 albedo, highp vec3 N, highp vec2 worldPos,\n"
+ " highp float ao) {\n"
+ " highp vec3 lit = u_ambient.rgb * ao;\n"
" for (int i = 0; i < 16; ++i) {\n"
" highp vec4 pd = u_lights[i].posDir;\n"
" highp vec4 col = u_lights[i].color;\n"
@@ -1172,6 +1178,9 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
" lit += col.rgb * (col.a * ndotl * atten);\n"
" }\n"
" return albedo * lit;\n"
+ "}\n"
+ "highp vec3 applyLighting2D(highp vec3 albedo, highp vec3 N, highp vec2 worldPos) {\n"
+ " return applyLighting2DAO(albedo, N, worldPos, 1.0);\n"
"}\n";
assembled << kLit2DHeader;
headerLines += countNewlines(kLit2DHeader);
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 8c7d5bbc3..900fa7987 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -179,6 +179,10 @@ export const SCENES = [
// both halves take the same light. Its texels point -X and +X, so the lit half
// and the unlit one are the tangent frame, derived per pixel from derivatives.
{ id: "mesh-normalmap", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_PREFAB: "/scenes/normalmap-quad.esprefab", ESTELLA_VERIFY_SCENE: "/scenes/mesh-normalmap.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh-normalmap.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.375,\"y\":0.5,\"rgb\":[180,180,180],\"tol\":45},{\"x\":0.625,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":30}]" } },
+ // The channels only a material can carry, one quad each, through the products a
+ // real import wrote. Ambient light only: the black quad's lit half can only be
+ // emission, the white quad's right half is occluded away, the cutout discards.
+ { id: "model-material", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_PREFAB: "/scenes/model-material.esprefab", ESTELLA_VERIFY_SCENE: "/scenes/model-material.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/model-material.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.05,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":40},{\"x\":0.2167,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":30},{\"x\":0.4167,\"y\":0.5,\"rgb\":[255,255,255],\"tol\":40},{\"x\":0.5833,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":30},{\"x\":0.8667,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":30}]" } },
// Takes the GPU away for real and captures AFTER the cycle: the four points
// sample the atlas, so they fail unless the content came back. A vertex-colour
// scene passed with the re-upload deleted. No webgpu — no GL extension there.