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(assets): a model's material comes in as a material
esenginefa0c91c86193
diff --git a/desktop/electron/importModel.ts b/desktop/electron/importModel.tsindex 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: strifor (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.esprefabnew file mode 100644index 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.metanew file mode 100644index 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.esscenenew file mode 100644index 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.gltfnew file mode 100644index 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.jsonnew file mode 100644index 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.pngnew file mode 100644index 000000000..6c77d6fbfBinary files /dev/null and b/desktop/public/scenes/model-material_0.png differdiff --git a/desktop/public/scenes/model-material_0.png.meta b/desktop/public/scenes/model-material_0.png.metanew file mode 100644index 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.esmeshnew file mode 100644index 000000000..f1248f700Binary files /dev/null and b/desktop/public/scenes/model-material_0_0.esmesh differdiff --git a/desktop/public/scenes/model-material_0_0.esmesh.meta b/desktop/public/scenes/model-material_0_0.esmesh.metanew file mode 100644index 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.esmeshnew file mode 100644index 000000000..f1248f700Binary files /dev/null and b/desktop/public/scenes/model-material_1_0.esmesh differdiff --git a/desktop/public/scenes/model-material_1_0.esmesh.meta b/desktop/public/scenes/model-material_1_0.esmesh.metanew file mode 100644index 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.esmeshnew file mode 100644index 000000000..f1248f700Binary files /dev/null and b/desktop/public/scenes/model-material_2_0.esmesh differdiff --git a/desktop/public/scenes/model-material_2_0.esmesh.meta b/desktop/public/scenes/model-material_2_0.esmesh.metanew file mode 100644index 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.esmaterialnew file mode 100644index 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.metanew file mode 100644index 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.esmaterialnew file mode 100644index 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.metanew file mode 100644index 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.esmaterialnew file mode 100644index 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.metanew file mode 100644index 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.esprefabindex 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.esmaterialnew file mode 100644index 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.metanew file mode 100644index 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.mjsindex 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.tsindex 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.tsindex 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.mdxindex 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.mdxindex 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.esprefabindex 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.gltfindex 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.esmaterialnew file mode 100644index 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.metanew file mode 100644index 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.mjsindex 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.tsindex 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, ImportedImif (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.tsindex 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.cppindex 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.mjsindex 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.