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(render): a mesh can hide another one
esengine23c35ae87c5c
diff --git a/desktop/public/scenes/lit-triangles.esmesh.meta b/desktop/public/scenes/lit-triangles.esmesh.metanew file mode 100644index 000000000..cc5ff755b--- /dev/null+++ b/desktop/public/scenes/lit-triangles.esmesh.meta@@ -0,0 +1,6 @@+{+ "uuid": "a3c5cebd-e841-47a7-8d8d-aff1bdf508ff",+ "version": "2.0",+ "type": "mesh",+ "importer": {}+}diff --git a/desktop/public/scenes/lit-triangles.esprefab.meta b/desktop/public/scenes/lit-triangles.esprefab.metanew file mode 100644index 000000000..9aca49be7--- /dev/null+++ b/desktop/public/scenes/lit-triangles.esprefab.meta@@ -0,0 +1,8 @@+{+ "uuid": "7ea2c787-d89a-45b8-b507-ac6eb20901be",+ "version": "2.0",+ "type": "prefab",+ "importer": {+ "autoMigrate": true+ }+}diff --git a/desktop/public/scenes/mesh-depth.esscene b/desktop/public/scenes/mesh-depth.esscenenew file mode 100644index 000000000..fc4e6b68a--- /dev/null+++ b/desktop/public/scenes/mesh-depth.esscene@@ -0,0 +1,108 @@+{+ "version": 1,+ "name": "MeshDepth",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 300+ }+ }+ },+ {+ "type": "Camera",+ "data": {+ "projectionType": 1,+ "orthoSize": 300,+ "isActive": true,+ "priority": 0+ }+ }+ ]+ },+ {+ "id": 1,+ "name": "Flat",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "Mesh2D",+ "data": {+ "color": {+ "r": 1,+ "g": 0,+ "b": 0,+ "a": 1+ },+ "layer": 0,+ "enabled": true,+ "opaque": true,+ "mesh": "/scenes/textured-quad.esmesh"+ }+ }+ ]+ },+ {+ "id": 2,+ "name": "Turned",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ },+ "rotation": {+ "w": 0.8660254,+ "x": 0,+ "y": 0.5,+ "z": 0+ }+ }+ },+ {+ "type": "Mesh2D",+ "data": {+ "color": {+ "r": 0,+ "g": 1,+ "b": 0,+ "a": 1+ },+ "layer": 0,+ "enabled": true,+ "opaque": true,+ "mesh": "/scenes/textured-quad.esmesh"+ }+ }+ ]+ }+ ]+}diff --git a/desktop/public/scenes/mesh-depth.textures.json b/desktop/public/scenes/mesh-depth.textures.jsonnew file mode 100644index 000000000..0967ef424--- /dev/null+++ b/desktop/public/scenes/mesh-depth.textures.json@@ -0,0 +1 @@+{}diff --git a/desktop/public/scenes/node-tree.esprefab b/desktop/public/scenes/node-tree.esprefabindex 4803c5169..4d59b6cb7 100644--- a/desktop/public/scenes/node-tree.esprefab+++ b/desktop/public/scenes/node-tree.esprefab@@ -52,6 +52,8 @@"b": 0,"a": 1},+ "opaque": true,+ "cullBackfaces": true,"enabled": true}}@@ -89,6 +91,8 @@"b": 0,"a": 1},+ "opaque": true,+ "cullBackfaces": true,"enabled": true}}diff --git a/desktop/public/scenes/node-tree.esprefab.meta b/desktop/public/scenes/node-tree.esprefab.metanew file mode 100644index 000000000..a76f5b2e1--- /dev/null+++ b/desktop/public/scenes/node-tree.esprefab.meta@@ -0,0 +1,8 @@+{+ "uuid": "d006902d-8443-4734-9e8d-6536e808b000",+ "version": "2.0",+ "type": "prefab",+ "importer": {+ "autoMigrate": true+ }+}diff --git a/desktop/public/scenes/node-tree_0_0.esmesh.meta b/desktop/public/scenes/node-tree_0_0.esmesh.metanew file mode 100644index 000000000..6dd5b9cd6--- /dev/null+++ b/desktop/public/scenes/node-tree_0_0.esmesh.meta@@ -0,0 +1,6 @@+{+ "uuid": "d8f46c40-e937-42e0-99ca-fefe5202988d",+ "version": "2.0",+ "type": "mesh",+ "importer": {}+}diff --git a/desktop/public/scenes/node-tree_1_0.esmesh.meta b/desktop/public/scenes/node-tree_1_0.esmesh.metanew file mode 100644index 000000000..ebac2d73a--- /dev/null+++ b/desktop/public/scenes/node-tree_1_0.esmesh.meta@@ -0,0 +1,6 @@+{+ "uuid": "0699f6e8-a06d-4aaf-a8e1-72fdc441b3b6",+ "version": "2.0",+ "type": "mesh",+ "importer": {}+}diff --git a/desktop/public/scenes/normalmap-quad.esmesh.meta b/desktop/public/scenes/normalmap-quad.esmesh.metanew file mode 100644index 000000000..8fce2da80--- /dev/null+++ b/desktop/public/scenes/normalmap-quad.esmesh.meta@@ -0,0 +1,6 @@+{+ "uuid": "3ee71346-7da9-4c4a-9563-1b4163424d8e",+ "version": "2.0",+ "type": "mesh",+ "importer": {}+}diff --git a/desktop/public/scenes/normalmap-quad.esprefab b/desktop/public/scenes/normalmap-quad.esprefabindex 85aa57edd..ca6d31dd3 100644--- a/desktop/public/scenes/normalmap-quad.esprefab+++ b/desktop/public/scenes/normalmap-quad.esprefab@@ -25,6 +25,8 @@"b": 1,"a": 1},+ "opaque": true,+ "cullBackfaces": true,"enabled": true}}diff --git a/desktop/public/scenes/normalmap-quad.esprefab.meta b/desktop/public/scenes/normalmap-quad.esprefab.metanew file mode 100644index 000000000..04f3212d6--- /dev/null+++ b/desktop/public/scenes/normalmap-quad.esprefab.meta@@ -0,0 +1,8 @@+{+ "uuid": "4d3cbde2-6eb5-4db2-9c87-9dfb8415ad3e",+ "version": "2.0",+ "type": "prefab",+ "importer": {+ "autoMigrate": true+ }+}diff --git a/desktop/public/scenes/normalmap-quad_0.png.meta b/desktop/public/scenes/normalmap-quad_0.png.metanew file mode 100644index 000000000..de9542b7f--- /dev/null+++ b/desktop/public/scenes/normalmap-quad_0.png.meta@@ -0,0 +1,20 @@+{+ "uuid": "910df10c-73cb-4c57-bcb9-8f803f045049",+ "version": "2.0",+ "type": "texture",+ "importer": {+ "maxSize": 2048,+ "compress": true,+ "compressFormat": "uastc",+ "filterMode": "linear",+ "wrapMode": "repeat",+ "premultiplyAlpha": false,+ "sRGB": true,+ "sliceBorder": {+ "left": 0,+ "right": 0,+ "top": 0,+ "bottom": 0+ }+ }+}diff --git a/desktop/public/scenes/textured-quad.esmesh.meta b/desktop/public/scenes/textured-quad.esmesh.metanew file mode 100644index 000000000..ec0327414--- /dev/null+++ b/desktop/public/scenes/textured-quad.esmesh.meta@@ -0,0 +1,6 @@+{+ "uuid": "118146bf-a566-4253-968c-92ec53910c8f",+ "version": "2.0",+ "type": "mesh",+ "importer": {}+}diff --git a/desktop/public/scenes/textured-quad.esprefab b/desktop/public/scenes/textured-quad.esprefabindex 797b7c0e7..a225b6d64 100644--- a/desktop/public/scenes/textured-quad.esprefab+++ b/desktop/public/scenes/textured-quad.esprefab@@ -25,6 +25,8 @@"b": 1,"a": 1},+ "opaque": true,+ "cullBackfaces": true,"enabled": true}}diff --git a/desktop/public/scenes/textured-quad.esprefab.meta b/desktop/public/scenes/textured-quad.esprefab.metanew file mode 100644index 000000000..ba95372eb--- /dev/null+++ b/desktop/public/scenes/textured-quad.esprefab.meta@@ -0,0 +1,8 @@+{+ "uuid": "b15f3c09-7ba7-438e-8e39-04b80a6a75ae",+ "version": "2.0",+ "type": "prefab",+ "importer": {+ "autoMigrate": true+ }+}diff --git a/desktop/public/scenes/textured-quad_0.png.meta b/desktop/public/scenes/textured-quad_0.png.metanew file mode 100644index 000000000..867881ee2--- /dev/null+++ b/desktop/public/scenes/textured-quad_0.png.meta@@ -0,0 +1,20 @@+{+ "uuid": "e91392b2-3d13-4d0d-b1dc-8859b8435f1e",+ "version": "2.0",+ "type": "texture",+ "importer": {+ "maxSize": 2048,+ "compress": true,+ "compressFormat": "uastc",+ "filterMode": "linear",+ "wrapMode": "repeat",+ "premultiplyAlpha": false,+ "sRGB": true,+ "sliceBorder": {+ "left": 0,+ "right": 0,+ "top": 0,+ "bottom": 0+ }+ }+}diff --git a/desktop/public/scenes/two-triangles.esmesh.meta b/desktop/public/scenes/two-triangles.esmesh.metanew file mode 100644index 000000000..8b2236169--- /dev/null+++ b/desktop/public/scenes/two-triangles.esmesh.meta@@ -0,0 +1,6 @@+{+ "uuid": "2f6e1fd0-5baa-40a2-9e9e-ba20d8971475",+ "version": "2.0",+ "type": "mesh",+ "importer": {}+}diff --git a/desktop/public/scenes/two-triangles.esprefab.meta b/desktop/public/scenes/two-triangles.esprefab.metanew file mode 100644index 000000000..f14b8841f--- /dev/null+++ b/desktop/public/scenes/two-triangles.esprefab.meta@@ -0,0 +1,8 @@+{+ "uuid": "909c02a6-3aac-437e-9a93-c5f8134b831d",+ "version": "2.0",+ "type": "prefab",+ "importer": {+ "autoMigrate": true+ }+}diff --git a/desktop/public/scenes/white-triangles.esmesh.meta b/desktop/public/scenes/white-triangles.esmesh.metanew file mode 100644index 000000000..7f6618f69--- /dev/null+++ b/desktop/public/scenes/white-triangles.esmesh.meta@@ -0,0 +1,6 @@+{+ "uuid": "6784c46c-35b6-44ee-96a3-689c8762c153",+ "version": "2.0",+ "type": "mesh",+ "importer": {}+}diff --git a/desktop/public/scenes/white-triangles.esprefab.meta b/desktop/public/scenes/white-triangles.esprefab.metanew file mode 100644index 000000000..0e0da887e--- /dev/null+++ b/desktop/public/scenes/white-triangles.esprefab.meta@@ -0,0 +1,8 @@+{+ "uuid": "aa5071cf-e1cd-4e17-85c8-5cf231b8958b",+ "version": "2.0",+ "type": "prefab",+ "importer": {+ "autoMigrate": true+ }+}diff --git a/desktop/tests/gltf-import.test.ts b/desktop/tests/gltf-import.test.tsindex 948e2597d..e90954def 100644--- a/desktop/tests/gltf-import.test.ts+++ b/desktop/tests/gltf-import.test.ts@@ -163,10 +163,22 @@ describe('glTF material import', () => {expect(line).toContain('normal-map scale 0.4');expect(line).toContain('emissive');expect(line).toContain('alpha cutoff 0.4');- expect(line).toContain('backfaces are not culled');expect(line).toContain('KHR_materials_clearcoat');});+ it('is opaque and single-sided unless the source says otherwise', () => {+ // Both are the glTF's own defaults, so a model arrives occluding itself the+ // way it was authored rather than as a stack of blended planes.+ const plain = importGltfMeshes(gltf(withInlineImage()), 'model').meshes[0]!;+ expect(plain.material).toMatchObject({ opaque: true, cullBackfaces: true });++ const doc = withInlineImage();+ (doc.materials as Record<string, unknown>[])[0]!.alphaMode = 'BLEND';+ (doc.materials as Record<string, unknown>[])[0]!.doubleSided = true;+ const blended = importGltfMeshes(gltf(doc), 'model').meshes[0]!;+ expect(blended.material).toMatchObject({ opaque: false, cullBackfaces: false });+ });+it('carries a normal map, extracting its image like any other', () => {const doc = withInlineImage();doc.images = [@@ -316,6 +328,8 @@ describe('glTF prefab assembly', () => {mesh: 'assets/models/model.esmesh',texture: 'assets/models/model_0.png',color: { r: 0.25, g: 0.5, b: 0.75, a: 1 },+ opaque: true,+ cullBackfaces: true,enabled: true,},});@@ -333,7 +347,7 @@ describe('glTF prefab assembly', () => {// The second primitive names no material: no texture, no tint, engine defaults.expect(prefab.entities[2]!.components[1]!.data).toEqual({mesh: 'model_0_1.esmesh', enabled: true,- });+ }); // no material named: engine defaults, blended and two-sided});it('places each node where the source puts it, parents included', () => {diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.jsonindex 843b039bb..d5628635b 100644--- a/docs/astro/src/data/components.generated.json+++ b/docs/astro/src/data/components.generated.json@@ -1305,6 +1305,18 @@"doc": "Sorting layer — controls draw order across renderables.","range": "step 1"},+ {+ "key": "opaque",+ "type": "boolean",+ "default": "false",+ "doc": "Opaque: no blending; writes and tests depth, so meshes occlude each other."+ },+ {+ "key": "cullBackfaces",+ "type": "boolean",+ "default": "false",+ "doc": "Cull back faces: triangles facing away from the camera are skipped."+ },{"key": "lit","type": "boolean",diff --git a/examples/model-import/assets/models/robot.esprefab b/examples/model-import/assets/models/robot.esprefabindex a25176cd8..d120386ba 100644--- a/examples/model-import/assets/models/robot.esprefab+++ b/examples/model-import/assets/models/robot.esprefab@@ -47,6 +47,8 @@"b": 1,"a": 1},+ "opaque": true,+ "cullBackfaces": true,"enabled": true}}@@ -84,6 +86,8 @@"b": 0.86,"a": 1},+ "opaque": true,+ "cullBackfaces": true,"enabled": true}}diff --git a/pipeline/src/assets/gltfImport.ts b/pipeline/src/assets/gltfImport.tsindex 3bd9256eb..d770db0f1 100644--- a/pipeline/src/assets/gltfImport.ts+++ b/pipeline/src/assets/gltfImport.ts@@ -49,6 +49,10 @@ export interface ImportedMaterial {baseColorTexture?: ImportedImageRef;/** Tangent-space normal map; the engine derives its tangent frame per pixel. */normalTexture?: ImportedImageRef;+ /** Not BLEND: drawn without blending, and taking part in depth. */+ opaque: boolean;+ /** `doubleSided: false` (the glTF default): back faces are not drawn. */+ cullBackfaces: boolean;}/** An image the glTF carries inline (GLB chunk or data uri), to be written beside the meshes. */@@ -401,15 +405,14 @@ function readMaterial(ctx: MaterialContext, textureCache: Map<number, ImportedImif (pbr.metallicRoughnessTexture || (pbr.metallicFactor ?? 1) !== 0 || (pbr.roughnessFactor ?? 1) !== 1) {unused.push('metallic-roughness');}- // The engine has no strength on a normal map; a scaled one would be imported- // at full strength, which is a different surface than the author saw.+ // 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}`);- if (src.doubleSided === false) unused.push('single-sided (backfaces are not culled)');for (const name of Object.keys(src.extensions ?? {})) unused.push(name);if (unused.length > 0) ctx.warnings.push(`${label}: ${unused.join(', ')} not imported`);@@ -420,6 +423,10 @@ function readMaterial(ctx: MaterialContext, textureCache: Map<number, ImportedImreturn {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.+ opaque: (src.alphaMode ?? 'OPAQUE') !== 'BLEND',+ cullBackfaces: src.doubleSided !== true,...(texture ? { baseColorTexture: texture } : {}),...(normal ? { normalTexture: normal } : {}),};@@ -743,6 +750,8 @@ function meshComponent(mesh: ImportedMesh, refs: ProductRefs): ComponentData {...(texture ? { texture } : {}),...(normalMap ? { normalMap } : {}),...(color ? { color: { r: color[0], g: color[1], b: color[2], a: color[3] } } : {}),+ ...(mesh.material?.opaque ? { opaque: true } : {}),+ ...(mesh.material?.cullBackfaces ? { cullBackfaces: true } : {}),enabled: true,} };}diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 85e868443..638adfeec 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -5,7 +5,7 @@ Symbols: 113 public · 55 beta · 1411 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```-"96f79850bd2b098b"+"bcac84b6e9bb2019"```## ANCHOR_AXES — const @experimental@@ -4224,6 +4224,7 @@ static prototype: Mesh2DAPI## Mesh2DData — interface @experimental```color: Color+cullBackfaces: booleanenabled: booleangeometry: Mesh2DGeometrylayer: number@@ -4231,6 +4232,7 @@ lit: booleanmaterial: numbermesh: numbernormalMap: number+opaque: booleanparallax: Vec2texture: number```diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 65330443c..65dcd89e2 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -5,7 +5,7 @@ Symbols: 113 public · 60 beta · 1430 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```-"96f79850bd2b098b"+"bcac84b6e9bb2019"```## ANCHOR_AXES — const @experimental@@ -4237,6 +4237,7 @@ static prototype: Mesh2DAPI## Mesh2DData — interface @experimental```color: Color+cullBackfaces: booleanenabled: booleangeometry: Mesh2DGeometrylayer: number@@ -4244,6 +4245,7 @@ lit: booleanmaterial: numbermesh: numbernormalMap: number+opaque: booleanparallax: Vec2texture: number```diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex f327f3488..05c136441 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -4219,6 +4219,7 @@ static prototype: Mesh2DAPI## Mesh2DData — interface @experimental```color: Color+cullBackfaces: booleanenabled: booleangeometry: Mesh2DGeometrylayer: number@@ -4226,6 +4227,7 @@ lit: booleanmaterial: numbermesh: numbernormalMap: number+opaque: booleanparallax: Vec2texture: number```diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 87e6635dd..09ba7d487 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -4219,6 +4219,7 @@ static prototype: Mesh2DAPI## Mesh2DData — interface @experimental```color: Color+cullBackfaces: booleanenabled: booleangeometry: Mesh2DGeometrylayer: number@@ -4226,6 +4227,7 @@ lit: booleanmaterial: numbermesh: numbernormalMap: number+opaque: booleanparallax: Vec2texture: number```diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex df5d67754..7a4866583 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -4226,6 +4226,7 @@ static prototype: Mesh2DAPI## Mesh2DData — interface @experimental```color: Color+cullBackfaces: booleanenabled: booleangeometry: Mesh2DGeometrylayer: number@@ -4233,6 +4234,7 @@ lit: booleanmaterial: numbermesh: numbernormalMap: number+opaque: booleanparallax: Vec2texture: number```diff --git a/sdk/src/ecs/bridge/ptrAccessors.generated.ts b/sdk/src/ecs/bridge/ptrAccessors.generated.tsindex 4adefd1c3..a614e94ea 100644--- a/sdk/src/ecs/bridge/ptrAccessors.generated.ts+++ b/sdk/src/ecs/bridge/ptrAccessors.generated.ts@@ -554,6 +554,8 @@ export interface Mesh2DPtrData {normalMap: number;color: Color;layer: number;+ opaque: boolean;+ cullBackfaces: boolean;lit: boolean;parallax: Vec2;material: number;@@ -569,7 +571,9 @@ export function fillMesh2D(out.normalMap = u32[(ptr + 4) >> 2];const color_ = out.color; color_.r = f32[(ptr + 8) >> 2]; color_.g = f32[((ptr + 8) >> 2) + 1]; color_.b = f32[((ptr + 8) >> 2) + 2]; color_.a = f32[((ptr + 8) >> 2) + 3];out.layer = u32[(ptr + 24) >> 2] | 0;- out.lit = u8[ptr + 28] !== 0;+ out.opaque = u8[ptr + 28] !== 0;+ out.cullBackfaces = u8[ptr + 29] !== 0;+ out.lit = u8[ptr + 30] !== 0;const parallax_ = out.parallax; parallax_.x = f32[(ptr + 32) >> 2]; parallax_.y = f32[((ptr + 32) >> 2) + 1];out.material = u32[(ptr + 40) >> 2];out.enabled = u8[ptr + 44] !== 0;@@ -584,7 +588,9 @@ export function writeMesh2D(u32[(ptr + 4) >> 2] = data.normalMap;f32[(ptr + 8) >> 2] = data.color.r; f32[((ptr + 8) >> 2) + 1] = data.color.g; f32[((ptr + 8) >> 2) + 2] = data.color.b; f32[((ptr + 8) >> 2) + 3] = data.color.a;u32[(ptr + 24) >> 2] = data.layer | 0;- u8[ptr + 28] = data.lit ? 1 : 0;+ u8[ptr + 28] = data.opaque ? 1 : 0;+ u8[ptr + 29] = data.cullBackfaces ? 1 : 0;+ u8[ptr + 30] = data.lit ? 1 : 0;f32[(ptr + 32) >> 2] = data.parallax.x; f32[((ptr + 32) >> 2) + 1] = data.parallax.y;u32[(ptr + 40) >> 2] = data.material;u8[ptr + 44] = data.enabled ? 1 : 0;@@ -597,6 +603,8 @@ export function createMesh2DData(): Mesh2DPtrData {normalMap: 0,color: { r: 0, g: 0, b: 0, a: 0 },layer: 0,+ opaque: false,+ cullBackfaces: false,lit: false,parallax: { x: 0, y: 0 },material: 0,diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.tsindex 036d3a075..5ba1f39eb 100644--- a/sdk/src/ecs/component.generated.ts+++ b/sdk/src/ecs/component.generated.ts@@ -15,7 +15,7 @@ import type { Dimension, Padding } from '../wasm/wasm.generated';* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to* run on mismatch, because mismatched offsets read the wrong heap bytes.*/-export const ABI_LAYOUT_HASH = '96f79850bd2b098b';+export const ABI_LAYOUT_HASH = 'bcac84b6e9bb2019';/*** One asset-valued field of a component: which field, and what kind of@@ -332,6 +332,8 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {normalMap: 0,color: { r: 1, g: 1, b: 1, a: 1 },layer: 0,+ opaque: false,+ cullBackfaces: false,lit: false,parallax: { x: 1, y: 1 },material: 0,@@ -347,6 +349,8 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {normalMap: { tooltip: "Normal map (tangent space). Needs a mesh with normals." },color: { tooltip: "Tint multiplied into the vertex colors (white = unchanged)." },layer: { step: 1, tooltip: "Sorting layer — controls draw order across renderables.", enumSource: "sortingLayers" },+ opaque: { tooltip: "Opaque: no blending; writes and tests depth, so meshes occlude each other." },+ cullBackfaces: { tooltip: "Cull back faces: triangles facing away from the camera are skipped." },lit: { tooltip: "Receive 2D lights: Light2D entities light this mesh (flat normal). A custom material overrides this." },parallax: { tooltip: "Parallax scroll factor (1 = with world, <1 = slower, 0 = locked to camera).", advanced: true },material: { advanced: true },@@ -1004,6 +1008,8 @@ export interface Mesh2DData {normalMap: number;color: Color;layer: number;+ opaque: boolean;+ cullBackfaces: boolean;lit: boolean;parallax: Vec2;material: number;diff --git a/sdk/src/wasm/ptrLayouts.generated.ts b/sdk/src/wasm/ptrLayouts.generated.tsindex 70af23b0c..9bc4f4ad2 100644--- a/sdk/src/wasm/ptrLayouts.generated.ts+++ b/sdk/src/wasm/ptrLayouts.generated.ts@@ -169,7 +169,9 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {{ name: 'normalMap', type: 'u32', offset: 4 },{ name: 'color', type: 'color', offset: 8 },{ name: 'layer', type: 'i32', offset: 24 },- { name: 'lit', type: 'bool', offset: 28 },+ { name: 'opaque', type: 'bool', offset: 28 },+ { name: 'cullBackfaces', type: 'bool', offset: 29 },+ { name: 'lit', type: 'bool', offset: 30 },{ name: 'parallax', type: 'vec2', offset: 32 },{ name: 'material', type: 'u32', offset: 40 },{ name: 'enabled', type: 'bool', offset: 44 },diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.tsindex c77a958ee..5526fc71c 100644--- a/sdk/src/wasm/wasm.generated.ts+++ b/sdk/src/wasm/wasm.generated.ts@@ -347,6 +347,8 @@ export interface Mesh2D {normalMap: number;color: Vec4;layer: number;+ opaque: boolean;+ cullBackfaces: boolean;lit: boolean;parallax: Vec2;material: number;diff --git a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snapindex 13c4fb9b3..e98d942fd 100644--- a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap+++ b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap@@ -219,6 +219,9 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho"color": {"tooltip": "Tint multiplied into the vertex colors (white = unchanged).",},+ "cullBackfaces": {+ "tooltip": "Cull back faces: triangles facing away from the camera are skipped.",+ },"layer": {"enumSource": "sortingLayers","step": 1,@@ -233,6 +236,9 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho"normalMap": {"tooltip": "Normal map (tangent space). Needs a mesh with normals.",},+ "opaque": {+ "tooltip": "Opaque: no blending; writes and tests depth, so meshes occlude each other.",+ },"parallax": {"advanced": true,"tooltip": "Parallax scroll factor (1 = with world, <1 = slower, 0 = locked to camera).",diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cppindex 0a8ea826c..66274f507 100644--- a/src/esengine/bindings/EditorAPI.generated.cpp+++ b/src/esengine/bindings/EditorAPI.generated.cpp@@ -2,10 +2,10 @@* @file EditorAPI.generated.cpp* @brief Auto-generated editor API with string-dispatched component access* @details Generated by EHT - DO NOT EDIT- * @schema_hash 54ca135d78453810+ * @schema_hash faf3163ec9f73265*/-#define ES_EDITOR_API_SCHEMA_HASH "54ca135d78453810"+#define ES_EDITOR_API_SCHEMA_HASH "faf3163ec9f73265"#include <emscripten/bind.h>#include <string>@@ -252,6 +252,8 @@ std::string editor_getComponentSchema(const std::string& name) {{"key":"color.b","type":"color","group":"Mesh2D"},{"key":"color.a","type":"color","group":"Mesh2D"},{"key":"layer","type":"int","group":"Mesh2D"},+ {"key":"opaque","type":"bool","group":"Mesh2D"},+ {"key":"cullBackfaces","type":"bool","group":"Mesh2D"},{"key":"lit","type":"bool","group":"Mesh2D"},{"key":"parallax.x","type":"float","group":"Mesh2D"},{"key":"parallax.y","type":"float","group":"Mesh2D"},@@ -2022,7 +2024,9 @@ bool editor_setBool(Registry& reg, u32 e, const std::string& comp, const std::st} else if (comp == "Mesh2D") {if (!reg.has<esengine::ecs::Mesh2D>(entity)) return false;auto& c = reg.get<esengine::ecs::Mesh2D>(entity);- if (field == "lit") { c.lit = value; }+ if (field == "opaque") { c.opaque = value; }+ else if (field == "cullBackfaces") { c.cullBackfaces = value; }+ else if (field == "lit") { c.lit = value; }else if (field == "enabled") { c.enabled = value; }else { return false; }return true;@@ -2187,7 +2191,9 @@ bool editor_getBool(Registry& reg, u32 e, const std::string& comp, const std::st} else if (comp == "Mesh2D") {if (!reg.has<esengine::ecs::Mesh2D>(entity)) return false;const auto& c = reg.get<esengine::ecs::Mesh2D>(entity);- if (field == "lit") { return c.lit; }+ if (field == "opaque") { return c.opaque; }+ else if (field == "cullBackfaces") { return c.cullBackfaces; }+ else if (field == "lit") { return c.lit; }else if (field == "enabled") { return c.enabled; }} else if (comp == "ParticleEmitter") {if (!reg.has<esengine::ecs::ParticleEmitter>(entity)) return false;diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cppindex 5b9a4610f..ac1f78151 100644--- a/src/esengine/bindings/WebBindings.generated.cpp+++ b/src/esengine/bindings/WebBindings.generated.cpp@@ -443,6 +443,8 @@ struct Mesh2DJS {u32 normalMap;glm::vec4 color;i32 layer;+ bool opaque;+ bool cullBackfaces;bool lit;glm::vec2 parallax;u32 material;@@ -455,6 +457,8 @@ void mesh2dApplyJS(esengine::ecs::Mesh2D& c, const Mesh2DJS& js) {c.normalMap = resource::TextureHandle(js.normalMap);c.color = js.color;c.layer = js.layer;+ c.opaque = js.opaque;+ c.cullBackfaces = js.cullBackfaces;c.lit = js.lit;c.parallax = js.parallax;c.material = js.material;@@ -474,6 +478,8 @@ Mesh2DJS mesh2dToJS(const esengine::ecs::Mesh2D& c) {js.normalMap = c.normalMap.id();js.color = c.color;js.layer = c.layer;+ js.opaque = c.opaque;+ js.cullBackfaces = c.cullBackfaces;js.lit = c.lit;js.parallax = c.parallax;js.material = c.material;@@ -1222,6 +1228,8 @@ EMSCRIPTEN_BINDINGS(esengine_components) {.field("normalMap", &Mesh2DJS::normalMap).field("color", &Mesh2DJS::color).field("layer", &Mesh2DJS::layer)+ .field("opaque", &Mesh2DJS::opaque)+ .field("cullBackfaces", &Mesh2DJS::cullBackfaces).field("lit", &Mesh2DJS::lit).field("parallax", &Mesh2DJS::parallax).field("material", &Mesh2DJS::material)@@ -2313,7 +2321,9 @@ static_assert(offsetof(esengine::ecs::Mesh2D, texture) == 0, "ABI offset drift:static_assert(offsetof(esengine::ecs::Mesh2D, normalMap) == 4, "ABI offset drift: esengine::ecs::Mesh2D.normalMap (EHT expected 4)");static_assert(offsetof(esengine::ecs::Mesh2D, color) == 8, "ABI offset drift: esengine::ecs::Mesh2D.color (EHT expected 8)");static_assert(offsetof(esengine::ecs::Mesh2D, layer) == 24, "ABI offset drift: esengine::ecs::Mesh2D.layer (EHT expected 24)");-static_assert(offsetof(esengine::ecs::Mesh2D, lit) == 28, "ABI offset drift: esengine::ecs::Mesh2D.lit (EHT expected 28)");+static_assert(offsetof(esengine::ecs::Mesh2D, opaque) == 28, "ABI offset drift: esengine::ecs::Mesh2D.opaque (EHT expected 28)");+static_assert(offsetof(esengine::ecs::Mesh2D, cullBackfaces) == 29, "ABI offset drift: esengine::ecs::Mesh2D.cullBackfaces (EHT expected 29)");+static_assert(offsetof(esengine::ecs::Mesh2D, lit) == 30, "ABI offset drift: esengine::ecs::Mesh2D.lit (EHT expected 30)");static_assert(offsetof(esengine::ecs::Mesh2D, parallax) == 32, "ABI offset drift: esengine::ecs::Mesh2D.parallax (EHT expected 32)");static_assert(offsetof(esengine::ecs::Mesh2D, material) == 40, "ABI offset drift: esengine::ecs::Mesh2D.material (EHT expected 40)");static_assert(offsetof(esengine::ecs::Mesh2D, enabled) == 44, "ABI offset drift: esengine::ecs::Mesh2D.enabled (EHT expected 44)");@@ -2522,7 +2532,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif// ABI Hash -- runtime handshake against the SDK bundle// =============================================================================-static const char* kEsAbiLayoutHash = "96f79850bd2b098b";+static const char* kEsAbiLayoutHash = "bcac84b6e9bb2019";std::string esengineGetAbiLayoutHash() {return std::string(kEsAbiLayoutHash);diff --git a/src/esengine/ecs/components/Mesh2D.hpp b/src/esengine/ecs/components/Mesh2D.hppindex e3743896b..cf2879e0c 100644--- a/src/esengine/ecs/components/Mesh2D.hpp+++ b/src/esengine/ecs/components/Mesh2D.hpp@@ -62,6 +62,17 @@ struct Mesh2D {ES_PROPERTY(step=1, enum_source=sortingLayers, tooltip="Sorting layer — controls draw order across renderables.")i32 layer{0};+ /** @brief Drawn as an opaque surface: no blending, and it takes part in depth —+ * which is what lets one mesh hide another wherever it is nearer, rather+ * than whichever was submitted last. A glTF's OPAQUE alpha mode. */+ ES_PROPERTY(tooltip="Opaque: no blending; writes and tests depth, so meshes occlude each other.")+ bool opaque{false};++ /** @brief Skip triangles facing away from the camera — a closed model's inside.+ * A glTF says this with `doubleSided: false`, which is its default. */+ ES_PROPERTY(tooltip="Cull back faces: triangles facing away from the camera are skipped.")+ bool cullBackfaces{false};+/** @brief Lit by the scene's 2D lights (Light2D). A custom material overrides this. */ES_PROPERTY(tooltip="Receive 2D lights: Light2D entities light this mesh (flat normal). A custom material overrides this.")bool lit{false};diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cppindex e384373e8..5680a9613 100644--- a/src/esengine/renderer/plugins/MeshPlugin.cpp+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp@@ -130,6 +130,17 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {.type = RenderType::Mesh,};+ // An opaque surface says so itself rather than waiting for a depth layer:+ // no blending, depth written AND tested — the only way one mesh hides+ // another. Opaque sorts ahead of blended within a layer, so 2D stays on top.+ if (mesh.opaque) {+ key.stage = RenderStage::Opaque;+ key.blend = BlendMode::None;+ key.depthTest = true;+ key.depthWrite = true;+ }+ if (mesh.cullBackfaces) key.cull = static_cast<u8>(CullMode::Back);+// Material resolve mirrors SpritePlugin: an unregistered handle falls back to// the default batch shader; a material owns shading fully, so it takes// precedence over the lit toggle.diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex dea46f44d..cf8ff5f46 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -149,6 +149,11 @@ export const SCENES = [// centres at x = ±120 project to 0.40 / 0.60, with 0.30 empty. The hit test at// the new place proves screen→world followed the turn.{ id: "view-orbit", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_ORBIT: "60,0", ESTELLA_VERIFY_PICK: "{\"x\":0.40,\"y\":0.556,\"entity\":1}", ESTELLA_VERIFY_SCENE: "/scenes/mesh2d.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh2d.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.40,\"y\":0.556,\"rgb\":[255,0,0],\"tol\":40},{\"x\":0.60,\"y\":0.556,\"rgb\":[0,255,0],\"tol\":40},{\"x\":0.30,\"y\":0.556,\"rgb\":[0,0,0],\"tol\":30}]" } },+ // Two quads crossing: one flat, one turned 60° about Y, so each is nearer on+ // one side. Painter's order cannot draw that — with `opaque` the halves resolve+ // by depth (left green, right red), and without it the later draw takes both.+ { id: "mesh-opaque", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-depth.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh-depth.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.42,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":40},{\"x\":0.58,\"y\":0.5,\"rgb\":[255,0,0],\"tol\":40}]" } },+ { id: "mesh-opaque-off", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SET_FIELD: "{\"entity\":2,\"component\":\"Mesh2D\",\"key\":\"opaque\",\"value\":false}", ESTELLA_VERIFY_SCENE: "/scenes/mesh-depth.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh-depth.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.42,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":40},{\"x\":0.58,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":40}]" } },// A normal map over FLAT normals: the quad faces the viewer, so without the map// 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.