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(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.meta
new file mode 100644
index 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.meta
new file mode 100644
index 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.esscene
new file mode 100644
index 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.json
new file mode 100644
index 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.esprefab
index 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.meta
new file mode 100644
index 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.meta
new file mode 100644
index 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.meta
new file mode 100644
index 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.meta
new file mode 100644
index 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.esprefab
index 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.meta
new file mode 100644
index 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.meta
new file mode 100644
index 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.meta
new file mode 100644
index 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.esprefab
index 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.meta
new file mode 100644
index 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.meta
new file mode 100644
index 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.meta
new file mode 100644
index 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.meta
new file mode 100644
index 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.meta
new file mode 100644
index 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.meta
new file mode 100644
index 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.ts
index 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.json
index 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.esprefab
index 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.ts
index 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, ImportedIm
if (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, ImportedIm
return {
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.md
index 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: boolean
enabled: boolean
geometry: Mesh2DGeometry
layer: number
@@ -4231,6 +4232,7 @@ lit: boolean
material: number
mesh: number
normalMap: number
+opaque: boolean
parallax: Vec2
texture: number
```
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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: boolean
enabled: boolean
geometry: Mesh2DGeometry
layer: number
@@ -4244,6 +4245,7 @@ lit: boolean
material: number
mesh: number
normalMap: number
+opaque: boolean
parallax: Vec2
texture: number
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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: boolean
enabled: boolean
geometry: Mesh2DGeometry
layer: number
@@ -4226,6 +4227,7 @@ lit: boolean
material: number
mesh: number
normalMap: number
+opaque: boolean
parallax: Vec2
texture: number
```
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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: boolean
enabled: boolean
geometry: Mesh2DGeometry
layer: number
@@ -4226,6 +4227,7 @@ lit: boolean
material: number
mesh: number
normalMap: number
+opaque: boolean
parallax: Vec2
texture: number
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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: boolean
enabled: boolean
geometry: Mesh2DGeometry
layer: number
@@ -4233,6 +4234,7 @@ lit: boolean
material: number
mesh: number
normalMap: number
+opaque: boolean
parallax: Vec2
texture: number
```
diff --git a/sdk/src/ecs/bridge/ptrAccessors.generated.ts b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
index 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.ts
index 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.ts
index 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.ts
index 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.snap
index 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.cpp
index 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.cpp
index 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.hpp
index 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.cpp
index 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.mjs
index 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.