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 material can say its surface goes ON another one
esengine0f3dba109af1
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex e05e43fb1..77443bd6d 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -97,6 +97,18 @@ published separately; it ships inside the editor.Per-instance, not per-object-record, because the record was out of room at thetime. The entry below is the change that moved it.+- **A surface can say it goes ON another one.** Two coplanar surfaces — a decal+ on a wall, a marking on a road, a patch on a floor — had no way to settle which+ one the depth test keeps. Whichever drew first won, which is not a thing an+ author can say. A material now carries `depthBias`, in units of the depth+ buffer's own resolution, and both backends apply it to the constant and the+ slope-scaled term (a constant alone stops separating them at a grazing angle).++ It is the piece a decal cannot be built without, and it has none of a decal's+ other machinery: no new pass, no depth read, no G-buffer. Two pixel scenes hold+ it — the same wall and the same patch, differing in that one number, showing+ the patch in one and the wall in the other.+- **A scatter brush.** Drag across the ground and copies of the selected objectland across it, turned and sized a little differently each — the first of theauthoring tools ruling 03 is about, since everything the renderer needed fordiff --git a/desktop b/desktopindex dab33b347..5eebbe685 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit dab33b34773ebdb882e456493ae897d307f5e938+Subproject commit 5eebbe6853f2edabc23742978df8899249fdd21ddiff --git a/fixtures/scenes/mat-decal-flat.esscene b/fixtures/scenes/mat-decal-flat.esscenenew file mode 100644index 000000000..e44756dfd--- /dev/null+++ b/fixtures/scenes/mat-decal-flat.esscene@@ -0,0 +1,120 @@+{+ "version": 4,+ "name": "Main",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 400+ }+ }+ },+ {+ "type": "Camera",+ "data": {+ "projectionType": 1,+ "orthoSize": 200,+ "nearPlane": 1,+ "farPlane": 2000,+ "isActive": true,+ "priority": 0+ }+ }+ ]+ },+ {+ "id": 1,+ "name": "Wall",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ },+ "scale": {+ "x": 3.0,+ "y": 3.0,+ "z": 0.2+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:cube",+ "opaque": true,+ "lit": false,+ "cullBackfaces": true,+ "material": "/scenes/mat-decal/wall.esmaterial",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "layer": 0,+ "enabled": true+ }+ }+ ]+ },+ {+ "id": 2,+ "name": "Decal",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ },+ "scale": {+ "x": 1.2,+ "y": 1.2,+ "z": 0.2+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:cube",+ "opaque": true,+ "lit": false,+ "cullBackfaces": true,+ "material": "/scenes/mat-decal/decal-flat.esmaterial",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "layer": 0,+ "enabled": true+ }+ }+ ]+ }+ ]+}diff --git a/fixtures/scenes/mat-decal.esscene b/fixtures/scenes/mat-decal.esscenenew file mode 100644index 000000000..30bea3c76--- /dev/null+++ b/fixtures/scenes/mat-decal.esscene@@ -0,0 +1,120 @@+{+ "version": 4,+ "name": "Main",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 400+ }+ }+ },+ {+ "type": "Camera",+ "data": {+ "projectionType": 1,+ "orthoSize": 200,+ "nearPlane": 1,+ "farPlane": 2000,+ "isActive": true,+ "priority": 0+ }+ }+ ]+ },+ {+ "id": 1,+ "name": "Wall",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ },+ "scale": {+ "x": 3.0,+ "y": 3.0,+ "z": 0.2+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:cube",+ "opaque": true,+ "lit": false,+ "cullBackfaces": true,+ "material": "/scenes/mat-decal/wall.esmaterial",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "layer": 0,+ "enabled": true+ }+ }+ ]+ },+ {+ "id": 2,+ "name": "Decal",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ },+ "scale": {+ "x": 1.2,+ "y": 1.2,+ "z": 0.2+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:cube",+ "opaque": true,+ "lit": false,+ "cullBackfaces": true,+ "material": "/scenes/mat-decal/decal.esmaterial",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "layer": 0,+ "enabled": true+ }+ }+ ]+ }+ ]+}diff --git a/fixtures/scenes/mat-decal/decal-flat.esmaterial b/fixtures/scenes/mat-decal/decal-flat.esmaterialnew file mode 100644index 000000000..90126861c--- /dev/null+++ b/fixtures/scenes/mat-decal/decal-flat.esmaterial@@ -0,0 +1,12 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "tint.esshader",+ "blendMode": 0,+ "depthTest": true,+ "depthWrite": true,++ "properties": {+ "u_tint": { "r": 1, "g": 0, "b": 0, "a": 1 }+ }+}diff --git a/fixtures/scenes/mat-decal/decal.esmaterial b/fixtures/scenes/mat-decal/decal.esmaterialnew file mode 100644index 000000000..c7f214a3b--- /dev/null+++ b/fixtures/scenes/mat-decal/decal.esmaterial@@ -0,0 +1,12 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "tint.esshader",+ "blendMode": 0,+ "depthTest": true,+ "depthWrite": true,+ "depthBias": -8,+ "properties": {+ "u_tint": { "r": 1, "g": 0, "b": 0, "a": 1 }+ }+}diff --git a/fixtures/scenes/mat-decal/tint.esshader b/fixtures/scenes/mat-decal/tint.esshadernew file mode 100644index 000000000..b114d38e8--- /dev/null+++ b/fixtures/scenes/mat-decal/tint.esshader@@ -0,0 +1,27 @@+#pragma shader "MeshTintTest"+#pragma version 300 es+#pragma domain Unlit+#pragma param u_tint color default(1,1,1,1)++// Fragment only: the engine owns the vertex stage, which is what lets the same+// material be compiled for a second vertex source (a GPU-resident mesh).+#pragma fragment+precision mediump float;++in vec4 v_color;+in vec2 v_texCoord;++out vec4 fragColor;++void main() {+ fragColor = v_color * u_tint;+}+#pragma end++#pragma fragment wgsl+// No VSOut here: the engine's canonical vertex owns that interface and injects+// it into a fragment-only twin.+@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {+ return v.v_color * mc.u_tint;+}+#pragma enddiff --git a/fixtures/scenes/mat-decal/wall.esmaterial b/fixtures/scenes/mat-decal/wall.esmaterialnew file mode 100644index 000000000..5bc4c7f05--- /dev/null+++ b/fixtures/scenes/mat-decal/wall.esmaterial@@ -0,0 +1,11 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "tint.esshader",+ "blendMode": 0,+ "depthTest": true,+ "depthWrite": true,+ "properties": {+ "u_tint": { "r": 0, "g": 1, "b": 0, "a": 1 }+ }+}diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex ca9ba97d2..f4e37ff03 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -5098,13 +5098,14 @@ static prototype: MaskReach## Material — const @experimental```-{ createShader(vertexSrc: string, fragmentSrc: string): ShaderHandle; releaseShader(shader: ShaderHandle): void; create(options: MaterialOptions): MaterialHandle; compileShader(esshaderSource: string, features?: string[]): ShaderHandle; getSwitch(material: MaterialHandle, name: string): boolean; setSwitch(material: MaterialHandle, name: string, on: boolean): void; get(material: MaterialHandle): MaterialData | undefined; setUniform(material: MaterialHandle, name: string, value: UniformValue): void; getUniform(material: MaterialHandle, name: string): UniformValue | undefined; setBlendMode(material: MaterialHandle, mode: BlendMode): void; getBlendMode(material: MaterialHandle): BlendMode; setDepthTest(material: MaterialHandle, enabled: boolean): void; setDepthWrite(material: MaterialHandle, enabled: boolean): void; setCull(material: MaterialHandle, cull: CullMode): void; getShader(material: MaterialHandle): ShaderHandle; release(material: MaterialHandle): void; isValid(material: MaterialHandle): boolean; renderPreview(material: MaterialHandle, w: number, h: number): Promise<ImageData | null>; releaseAll(): void; createFromAsset(data: MaterialAssetData, shaderHandle: ShaderHandle, parentHandle?: MaterialHandle): MaterialHandle; createInstance(source: MaterialHandle): MaterialHandle; toAssetData(material: MaterialHandle, shaderPath: string, parentPath?: string): MaterialAssetData | null; getUniforms(material: MaterialHandle): Map<string, UniformValue>; tex(textureId: number, slot?: number): TextureRef; }+{ createShader(vertexSrc: string, fragmentSrc: string): ShaderHandle; releaseShader(shader: ShaderHandle): void; create(options: MaterialOptions): MaterialHandle; compileShader(esshaderSource: string, features?: string[]): ShaderHandle; getSwitch(material: MaterialHandle, name: string): boolean; setSwitch(material: MaterialHandle, name: string, on: boolean): void; get(material: MaterialHandle): MaterialData | undefined; setUniform(material: MaterialHandle, name: string, value: UniformValue): void; getUniform(material: MaterialHandle, name: string): UniformValue | undefined; setBlendMode(material: MaterialHandle, mode: BlendMode): void; getBlendMode(material: MaterialHandle): BlendMode; setDepthTest(material: MaterialHandle, enabled: boolean): void; setDepthWrite(material: MaterialHandle, enabled: boolean): void; setDepthBias(material: MaterialHandle, units: number): void; setCull(material: MaterialHandle, cull: CullMode): void; getShader(material: MaterialHandle): ShaderHandle; release(material: MaterialHandle): void; isValid(material: MaterialHandle): boolean; renderPreview(material: MaterialHandle, w: number, h: number): Promise<ImageData | null>; releaseAll(): void; createFromAsset(data: MaterialAssetData, shaderHandle: ShaderHandle, parentHandle?: MaterialHandle): MaterialHandle; createInstance(source: MaterialHandle): MaterialHandle; toAssetData(material: MaterialHandle, shaderPath: string, parentPath?: string): MaterialAssetData | null; getUniforms(material: MaterialHandle): Map<string, UniformValue>; tex(textureId: number, slot?: number): TextureRef; }```## MaterialAssetData — interface @experimental```blendMode: number | undefinedcull: number | undefined+depthBias: number | undefineddepthTest: boolean | undefineddepthWrite: boolean | undefinedinstanceOf: string | undefined@@ -5121,6 +5122,7 @@ blendMode: BlendModecachedBuffer_: Float32Array<ArrayBufferLike> | nullcachedIdx_: numbercull: CullMode+depthBias: numberdepthTest: booleandepthWrite: booleandirty_: boolean@@ -5158,6 +5160,7 @@ number```blendMode: BlendMode | undefinedcull: CullMode | undefined+depthBias: number | undefineddepthTest: boolean | undefineddepthWrite: boolean | undefinedshader: numberdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex de04a34fa..5bc54fb24 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -5106,13 +5106,14 @@ static prototype: MaskReach## Material — const @experimental```-{ createShader(vertexSrc: string, fragmentSrc: string): ShaderHandle; releaseShader(shader: ShaderHandle): void; create(options: MaterialOptions): MaterialHandle; compileShader(esshaderSource: string, features?: string[]): ShaderHandle; getSwitch(material: MaterialHandle, name: string): boolean; setSwitch(material: MaterialHandle, name: string, on: boolean): void; get(material: MaterialHandle): MaterialData | undefined; setUniform(material: MaterialHandle, name: string, value: UniformValue): void; getUniform(material: MaterialHandle, name: string): UniformValue | undefined; setBlendMode(material: MaterialHandle, mode: BlendMode): void; getBlendMode(material: MaterialHandle): BlendMode; setDepthTest(material: MaterialHandle, enabled: boolean): void; setDepthWrite(material: MaterialHandle, enabled: boolean): void; setCull(material: MaterialHandle, cull: CullMode): void; getShader(material: MaterialHandle): ShaderHandle; release(material: MaterialHandle): void; isValid(material: MaterialHandle): boolean; renderPreview(material: MaterialHandle, w: number, h: number): Promise<ImageData | null>; releaseAll(): void; createFromAsset(data: MaterialAssetData, shaderHandle: ShaderHandle, parentHandle?: MaterialHandle): MaterialHandle; createInstance(source: MaterialHandle): MaterialHandle; toAssetData(material: MaterialHandle, shaderPath: string, parentPath?: string): MaterialAssetData | null; getUniforms(material: MaterialHandle): Map<string, UniformValue>; tex(textureId: number, slot?: number): TextureRef; }+{ createShader(vertexSrc: string, fragmentSrc: string): ShaderHandle; releaseShader(shader: ShaderHandle): void; create(options: MaterialOptions): MaterialHandle; compileShader(esshaderSource: string, features?: string[]): ShaderHandle; getSwitch(material: MaterialHandle, name: string): boolean; setSwitch(material: MaterialHandle, name: string, on: boolean): void; get(material: MaterialHandle): MaterialData | undefined; setUniform(material: MaterialHandle, name: string, value: UniformValue): void; getUniform(material: MaterialHandle, name: string): UniformValue | undefined; setBlendMode(material: MaterialHandle, mode: BlendMode): void; getBlendMode(material: MaterialHandle): BlendMode; setDepthTest(material: MaterialHandle, enabled: boolean): void; setDepthWrite(material: MaterialHandle, enabled: boolean): void; setDepthBias(material: MaterialHandle, units: number): void; setCull(material: MaterialHandle, cull: CullMode): void; getShader(material: MaterialHandle): ShaderHandle; release(material: MaterialHandle): void; isValid(material: MaterialHandle): boolean; renderPreview(material: MaterialHandle, w: number, h: number): Promise<ImageData | null>; releaseAll(): void; createFromAsset(data: MaterialAssetData, shaderHandle: ShaderHandle, parentHandle?: MaterialHandle): MaterialHandle; createInstance(source: MaterialHandle): MaterialHandle; toAssetData(material: MaterialHandle, shaderPath: string, parentPath?: string): MaterialAssetData | null; getUniforms(material: MaterialHandle): Map<string, UniformValue>; tex(textureId: number, slot?: number): TextureRef; }```## MaterialAssetData — interface @experimental```blendMode: number | undefinedcull: number | undefined+depthBias: number | undefineddepthTest: boolean | undefineddepthWrite: boolean | undefinedinstanceOf: string | undefined@@ -5129,6 +5130,7 @@ blendMode: BlendModecachedBuffer_: Float32Array<ArrayBufferLike> | nullcachedIdx_: numbercull: CullMode+depthBias: numberdepthTest: booleandepthWrite: booleandirty_: boolean@@ -5166,6 +5168,7 @@ number```blendMode: BlendMode | undefinedcull: CullMode | undefined+depthBias: number | undefineddepthTest: boolean | undefineddepthWrite: boolean | undefinedshader: numberdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 9d87b6a97..4cd2b900b 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -5093,13 +5093,14 @@ static prototype: MaskReach## Material — const @experimental```-{ createShader(vertexSrc: string, fragmentSrc: string): ShaderHandle; releaseShader(shader: ShaderHandle): void; create(options: MaterialOptions): MaterialHandle; compileShader(esshaderSource: string, features?: string[]): ShaderHandle; getSwitch(material: MaterialHandle, name: string): boolean; setSwitch(material: MaterialHandle, name: string, on: boolean): void; get(material: MaterialHandle): MaterialData | undefined; setUniform(material: MaterialHandle, name: string, value: UniformValue): void; getUniform(material: MaterialHandle, name: string): UniformValue | undefined; setBlendMode(material: MaterialHandle, mode: BlendMode): void; getBlendMode(material: MaterialHandle): BlendMode; setDepthTest(material: MaterialHandle, enabled: boolean): void; setDepthWrite(material: MaterialHandle, enabled: boolean): void; setCull(material: MaterialHandle, cull: CullMode): void; getShader(material: MaterialHandle): ShaderHandle; release(material: MaterialHandle): void; isValid(material: MaterialHandle): boolean; renderPreview(material: MaterialHandle, w: number, h: number): Promise<ImageData | null>; releaseAll(): void; createFromAsset(data: MaterialAssetData, shaderHandle: ShaderHandle, parentHandle?: MaterialHandle): MaterialHandle; createInstance(source: MaterialHandle): MaterialHandle; toAssetData(material: MaterialHandle, shaderPath: string, parentPath?: string): MaterialAssetData | null; getUniforms(material: MaterialHandle): Map<string, UniformValue>; tex(textureId: number, slot?: number): TextureRef; }+{ createShader(vertexSrc: string, fragmentSrc: string): ShaderHandle; releaseShader(shader: ShaderHandle): void; create(options: MaterialOptions): MaterialHandle; compileShader(esshaderSource: string, features?: string[]): ShaderHandle; getSwitch(material: MaterialHandle, name: string): boolean; setSwitch(material: MaterialHandle, name: string, on: boolean): void; get(material: MaterialHandle): MaterialData | undefined; setUniform(material: MaterialHandle, name: string, value: UniformValue): void; getUniform(material: MaterialHandle, name: string): UniformValue | undefined; setBlendMode(material: MaterialHandle, mode: BlendMode): void; getBlendMode(material: MaterialHandle): BlendMode; setDepthTest(material: MaterialHandle, enabled: boolean): void; setDepthWrite(material: MaterialHandle, enabled: boolean): void; setDepthBias(material: MaterialHandle, units: number): void; setCull(material: MaterialHandle, cull: CullMode): void; getShader(material: MaterialHandle): ShaderHandle; release(material: MaterialHandle): void; isValid(material: MaterialHandle): boolean; renderPreview(material: MaterialHandle, w: number, h: number): Promise<ImageData | null>; releaseAll(): void; createFromAsset(data: MaterialAssetData, shaderHandle: ShaderHandle, parentHandle?: MaterialHandle): MaterialHandle; createInstance(source: MaterialHandle): MaterialHandle; toAssetData(material: MaterialHandle, shaderPath: string, parentPath?: string): MaterialAssetData | null; getUniforms(material: MaterialHandle): Map<string, UniformValue>; tex(textureId: number, slot?: number): TextureRef; }```## MaterialAssetData — interface @experimental```blendMode: number | undefinedcull: number | undefined+depthBias: number | undefineddepthTest: boolean | undefineddepthWrite: boolean | undefinedinstanceOf: string | undefined@@ -5116,6 +5117,7 @@ blendMode: BlendModecachedBuffer_: Float32Array<ArrayBufferLike> | nullcachedIdx_: numbercull: CullMode+depthBias: numberdepthTest: booleandepthWrite: booleandirty_: boolean@@ -5153,6 +5155,7 @@ number```blendMode: BlendMode | undefinedcull: CullMode | undefined+depthBias: number | undefineddepthTest: boolean | undefineddepthWrite: boolean | undefinedshader: numberdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 0c5c3fc40..4c595815c 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -5093,13 +5093,14 @@ static prototype: MaskReach## Material — const @experimental```-{ createShader(vertexSrc: string, fragmentSrc: string): ShaderHandle; releaseShader(shader: ShaderHandle): void; create(options: MaterialOptions): MaterialHandle; compileShader(esshaderSource: string, features?: string[]): ShaderHandle; getSwitch(material: MaterialHandle, name: string): boolean; setSwitch(material: MaterialHandle, name: string, on: boolean): void; get(material: MaterialHandle): MaterialData | undefined; setUniform(material: MaterialHandle, name: string, value: UniformValue): void; getUniform(material: MaterialHandle, name: string): UniformValue | undefined; setBlendMode(material: MaterialHandle, mode: BlendMode): void; getBlendMode(material: MaterialHandle): BlendMode; setDepthTest(material: MaterialHandle, enabled: boolean): void; setDepthWrite(material: MaterialHandle, enabled: boolean): void; setCull(material: MaterialHandle, cull: CullMode): void; getShader(material: MaterialHandle): ShaderHandle; release(material: MaterialHandle): void; isValid(material: MaterialHandle): boolean; renderPreview(material: MaterialHandle, w: number, h: number): Promise<ImageData | null>; releaseAll(): void; createFromAsset(data: MaterialAssetData, shaderHandle: ShaderHandle, parentHandle?: MaterialHandle): MaterialHandle; createInstance(source: MaterialHandle): MaterialHandle; toAssetData(material: MaterialHandle, shaderPath: string, parentPath?: string): MaterialAssetData | null; getUniforms(material: MaterialHandle): Map<string, UniformValue>; tex(textureId: number, slot?: number): TextureRef; }+{ createShader(vertexSrc: string, fragmentSrc: string): ShaderHandle; releaseShader(shader: ShaderHandle): void; create(options: MaterialOptions): MaterialHandle; compileShader(esshaderSource: string, features?: string[]): ShaderHandle; getSwitch(material: MaterialHandle, name: string): boolean; setSwitch(material: MaterialHandle, name: string, on: boolean): void; get(material: MaterialHandle): MaterialData | undefined; setUniform(material: MaterialHandle, name: string, value: UniformValue): void; getUniform(material: MaterialHandle, name: string): UniformValue | undefined; setBlendMode(material: MaterialHandle, mode: BlendMode): void; getBlendMode(material: MaterialHandle): BlendMode; setDepthTest(material: MaterialHandle, enabled: boolean): void; setDepthWrite(material: MaterialHandle, enabled: boolean): void; setDepthBias(material: MaterialHandle, units: number): void; setCull(material: MaterialHandle, cull: CullMode): void; getShader(material: MaterialHandle): ShaderHandle; release(material: MaterialHandle): void; isValid(material: MaterialHandle): boolean; renderPreview(material: MaterialHandle, w: number, h: number): Promise<ImageData | null>; releaseAll(): void; createFromAsset(data: MaterialAssetData, shaderHandle: ShaderHandle, parentHandle?: MaterialHandle): MaterialHandle; createInstance(source: MaterialHandle): MaterialHandle; toAssetData(material: MaterialHandle, shaderPath: string, parentPath?: string): MaterialAssetData | null; getUniforms(material: MaterialHandle): Map<string, UniformValue>; tex(textureId: number, slot?: number): TextureRef; }```## MaterialAssetData — interface @experimental```blendMode: number | undefinedcull: number | undefined+depthBias: number | undefineddepthTest: boolean | undefineddepthWrite: boolean | undefinedinstanceOf: string | undefined@@ -5116,6 +5117,7 @@ blendMode: BlendModecachedBuffer_: Float32Array<ArrayBufferLike> | nullcachedIdx_: numbercull: CullMode+depthBias: numberdepthTest: booleandepthWrite: booleandirty_: boolean@@ -5153,6 +5155,7 @@ number```blendMode: BlendMode | undefinedcull: CullMode | undefined+depthBias: number | undefineddepthTest: boolean | undefineddepthWrite: boolean | undefinedshader: numberdiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 783274f7a..c6d7fb0be 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -323,7 +323,7 @@ initRendererWebGPU: (canvasSelector: string, width: number, height: number, readinitRendererWithContext: (contextHandle: number) => booleanmarkDeviceRestored: (() => number) | undefinedmaterial_compileEsshader: (source: string, featuresCsv: string) => number-material_define: (materialId: number, shaderHandle: number, blendMode: number, flags: number) => void+material_define: (materialId: number, shaderHandle: number, blendMode: number, flags: number, depthBias: number) => voidmaterial_setTexture: (materialId: number, name: string, textureHandle: number) => voidmaterial_setUniform: (materialId: number, name: string, arity: number, v0: number, v1: number, v2: number, v3: number) => voidmaterial_undefine: (materialId: number) => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex ec49e6400..52d6304e1 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -5100,13 +5100,14 @@ static prototype: MaskReach## Material — const @experimental```-{ createShader(vertexSrc: string, fragmentSrc: string): ShaderHandle; releaseShader(shader: ShaderHandle): void; create(options: MaterialOptions): MaterialHandle; compileShader(esshaderSource: string, features?: string[]): ShaderHandle; getSwitch(material: MaterialHandle, name: string): boolean; setSwitch(material: MaterialHandle, name: string, on: boolean): void; get(material: MaterialHandle): MaterialData | undefined; setUniform(material: MaterialHandle, name: string, value: UniformValue): void; getUniform(material: MaterialHandle, name: string): UniformValue | undefined; setBlendMode(material: MaterialHandle, mode: BlendMode): void; getBlendMode(material: MaterialHandle): BlendMode; setDepthTest(material: MaterialHandle, enabled: boolean): void; setDepthWrite(material: MaterialHandle, enabled: boolean): void; setCull(material: MaterialHandle, cull: CullMode): void; getShader(material: MaterialHandle): ShaderHandle; release(material: MaterialHandle): void; isValid(material: MaterialHandle): boolean; renderPreview(material: MaterialHandle, w: number, h: number): Promise<ImageData | null>; releaseAll(): void; createFromAsset(data: MaterialAssetData, shaderHandle: ShaderHandle, parentHandle?: MaterialHandle): MaterialHandle; createInstance(source: MaterialHandle): MaterialHandle; toAssetData(material: MaterialHandle, shaderPath: string, parentPath?: string): MaterialAssetData | null; getUniforms(material: MaterialHandle): Map<string, UniformValue>; tex(textureId: number, slot?: number): TextureRef; }+{ createShader(vertexSrc: string, fragmentSrc: string): ShaderHandle; releaseShader(shader: ShaderHandle): void; create(options: MaterialOptions): MaterialHandle; compileShader(esshaderSource: string, features?: string[]): ShaderHandle; getSwitch(material: MaterialHandle, name: string): boolean; setSwitch(material: MaterialHandle, name: string, on: boolean): void; get(material: MaterialHandle): MaterialData | undefined; setUniform(material: MaterialHandle, name: string, value: UniformValue): void; getUniform(material: MaterialHandle, name: string): UniformValue | undefined; setBlendMode(material: MaterialHandle, mode: BlendMode): void; getBlendMode(material: MaterialHandle): BlendMode; setDepthTest(material: MaterialHandle, enabled: boolean): void; setDepthWrite(material: MaterialHandle, enabled: boolean): void; setDepthBias(material: MaterialHandle, units: number): void; setCull(material: MaterialHandle, cull: CullMode): void; getShader(material: MaterialHandle): ShaderHandle; release(material: MaterialHandle): void; isValid(material: MaterialHandle): boolean; renderPreview(material: MaterialHandle, w: number, h: number): Promise<ImageData | null>; releaseAll(): void; createFromAsset(data: MaterialAssetData, shaderHandle: ShaderHandle, parentHandle?: MaterialHandle): MaterialHandle; createInstance(source: MaterialHandle): MaterialHandle; toAssetData(material: MaterialHandle, shaderPath: string, parentPath?: string): MaterialAssetData | null; getUniforms(material: MaterialHandle): Map<string, UniformValue>; tex(textureId: number, slot?: number): TextureRef; }```## MaterialAssetData — interface @experimental```blendMode: number | undefinedcull: number | undefined+depthBias: number | undefineddepthTest: boolean | undefineddepthWrite: boolean | undefinedinstanceOf: string | undefined@@ -5123,6 +5124,7 @@ blendMode: BlendModecachedBuffer_: Float32Array<ArrayBufferLike> | nullcachedIdx_: numbercull: CullMode+depthBias: numberdepthTest: booleandepthWrite: booleandirty_: boolean@@ -5160,6 +5162,7 @@ number```blendMode: BlendMode | undefinedcull: CullMode | undefined+depthBias: number | undefineddepthTest: boolean | undefineddepthWrite: boolean | undefinedshader: numberdiff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.tsindex bae30a432..e195d157e 100644--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts@@ -67,7 +67,7 @@ export interface NativeEngineApi {gl_checkErrors?(context: string): number;gl_enableErrorCheck?(enabled: boolean): void;material_compileEsshader?(source: string, featuresCsv: string): number;- material_define?(materialId: number, shaderHandle: number, blendMode: number, flags: number): void;+ material_define?(materialId: number, shaderHandle: number, blendMode: number, flags: number, depthBias: number): void;material_setTexture?(materialId: number, name: string, textureHandle: number): void;material_setUniform?(materialId: number, name: string, arity: number, v0: number, v1: number, v2: number, v3: number): void;material_undefine?(materialId: number): void;diff --git a/sdk/src/render/material.ts b/sdk/src/render/material.tsindex 0def48f1b..45dc0b836 100644--- a/sdk/src/render/material.ts+++ b/sdk/src/render/material.ts@@ -84,6 +84,9 @@ export interface MaterialOptions {depthTest?: boolean;depthWrite?: boolean;cull?: CullMode;+ /** Depth-buffer units toward the eye — the only way to say which of two+ * COPLANAR surfaces wins (a decal on a wall). 0 leaves it where it is. */+ depthBias?: number;/** Enabled static switches (#pragma switch) for the record; the shader permutation is* chosen at compile time (see Material.compileShader). Stored for inspection/serialization. */switches?: Record<string, boolean>;@@ -103,6 +106,7 @@ export interface MaterialAssetData {depthTest?: boolean;depthWrite?: boolean;cull?: number;+ depthBias?: number;/*** Parent material asset ref — present on a material instance (UE MaterialInstanceConstant).* The shader and any non-overridden render state are inherited from the parent; `shader`@@ -121,13 +125,16 @@ export interface MaterialData {depthTest: boolean;depthWrite: boolean;cull: CullMode;+ /** Depth-buffer units toward the eye — the only way to say which of two+ * COPLANAR surfaces wins (a decal on a wall). 0 leaves it where it is. */+ depthBias: number;/** Enabled static switches (the shader permutation was chosen for these at compile time). */switches: Record<string, boolean>;/*** Instance parenting (UE MaterialInstanceConstant): when set, this material inherits the* parent's shader + render state + params, and only its own diffs are stored — `uniforms`* holds just the overridden params, and `overrides` names the overridden render-state- * fields ('blendMode' | 'depthTest' | 'depthWrite' | 'cull'). Undefined on a base material.+ * fields. Undefined on a base material.*/parent?: MaterialHandle;overrides: Set<string>;@@ -261,6 +268,7 @@ interface ResolvedMaterial {depthTest: boolean;depthWrite: boolean;cull: CullMode;+ depthBias: number;uniforms: Map<string, UniformValue>;}@@ -274,7 +282,8 @@ function resolveMaterial(handle: MaterialHandle): ResolvedMaterial | null {if (!parent) {return {shader: data.shader, blendMode: data.blendMode, depthTest: data.depthTest,- depthWrite: data.depthWrite, cull: data.cull, uniforms: new Map(data.uniforms),+ depthWrite: data.depthWrite, cull: data.cull, depthBias: data.depthBias,+ uniforms: new Map(data.uniforms),};}const uniforms = parent.uniforms; // fresh map from the recursive call@@ -285,6 +294,7 @@ function resolveMaterial(handle: MaterialHandle): ResolvedMaterial | null {depthTest: data.overrides.has('depthTest') ? data.depthTest : parent.depthTest,depthWrite: data.overrides.has('depthWrite') ? data.depthWrite : parent.depthWrite,cull: data.overrides.has('cull') ? data.cull : parent.cull,+ depthBias: data.overrides.has('depthBias') ? data.depthBias : parent.depthBias,uniforms,};}@@ -295,7 +305,8 @@ function flushMaterial(handle: MaterialHandle): void {const resolved = resolveMaterial(handle);if (resolved && module) {module.material_define(handle, resolved.shader, resolved.blendMode,- materialFlags(resolved.depthTest, resolved.depthWrite, resolved.cull));+ materialFlags(resolved.depthTest, resolved.depthWrite, resolved.cull),+ resolved.depthBias);for (const [name, value] of resolved.uniforms) pushUniform(handle, name, value);}const kids = childrenOf.get(handle);@@ -362,6 +373,7 @@ export const Material = {depthTest: options.depthTest ?? false,depthWrite: options.depthWrite ?? true,cull: options.cull ?? CullMode.None,+ depthBias: options.depthBias ?? 0,switches: options.switches ? { ...options.switches } : {},overrides: new Set(),dirty_: true,@@ -493,6 +505,20 @@ export const Material = {}},+ /**+ * How far toward the eye this surface is pushed, in depth-buffer units —+ * what makes a decal win against the wall it is laid on. Negative is toward+ * the eye; 0 leaves the surface where its geometry puts it.+ */+ setDepthBias(material: MaterialHandle, units: number): void {+ const data = materials.get(material);+ if (data) {+ data.depthBias = Math.round(units);+ if (data.parent !== undefined) data.overrides.add('depthBias');+ flushMaterial(material);+ }+ },+/** Sets the triangle culling mode. */setCull(material: MaterialHandle, cull: CullMode): void {const data = materials.get(material);@@ -571,6 +597,7 @@ export const Material = {if (data.depthTest !== undefined) this.setDepthTest(handle, data.depthTest);if (data.depthWrite !== undefined) this.setDepthWrite(handle, data.depthWrite);if (data.cull !== undefined) this.setCull(handle, data.cull as CullMode);+ if (data.depthBias !== undefined) this.setDepthBias(handle, data.depthBias);return handle;}@@ -581,6 +608,7 @@ export const Material = {depthTest: data.depthTest ?? false,depthWrite: data.depthWrite ?? true,cull: (data.cull as CullMode) ?? CullMode.None,+ depthBias: data.depthBias ?? 0,switches: data.switches,});},@@ -609,6 +637,7 @@ export const Material = {depthTest: sourceData.depthTest,depthWrite: sourceData.depthWrite,cull: sourceData.cull,+ depthBias: sourceData.depthBias,switches: {}, // instance inherits the parent's shader permutation (switch override = follow-up)parent: source,overrides: new Set(),@@ -649,6 +678,7 @@ export const Material = {if (data.overrides.has('depthTest')) asset.depthTest = data.depthTest;if (data.overrides.has('depthWrite')) asset.depthWrite = data.depthWrite;if (data.overrides.has('cull')) asset.cull = data.cull;+ if (data.overrides.has('depthBias')) asset.depthBias = data.depthBias;return asset;}@@ -660,6 +690,7 @@ export const Material = {depthTest: data.depthTest,depthWrite: data.depthWrite,cull: data.cull,+ depthBias: data.depthBias,properties,};if (Object.keys(data.switches).length > 0) asset.switches = { ...data.switches };diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex c811059cd..3727a5299 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -409,7 +409,7 @@ export interface ESEngineModule {// which is what makes them work on a device too; declared here because embind// registers them by hand for the web.material_compileEsshader(source: string, featuresCsv: string): number;- material_define(materialId: number, shaderHandle: number, blendMode: number, flags: number): void;+ material_define(materialId: number, shaderHandle: number, blendMode: number, flags: number, depthBias: number): void;material_setUniform(materialId: number, name: string, arity: number,v0: number, v1: number, v2: number, v3: number): void;material_setTexture(materialId: number, name: string, textureHandle: number): void;diff --git a/sdk/tests/material.test.ts b/sdk/tests/material.test.tsindex 94462a521..d106f6809 100644--- a/sdk/tests/material.test.ts+++ b/sdk/tests/material.test.ts@@ -162,7 +162,7 @@ describe('Material API', () => {cull: CullMode.Back,});expect(mock.material_define).toHaveBeenCalledWith(- h, 42, BlendMode.Additive, flags(true, true, CullMode.Back),+ h, 42, BlendMode.Additive, flags(true, true, CullMode.Back), 0,);});@@ -299,7 +299,7 @@ describe('Material API', () => {mock.material_define.mockClear();Material.setBlendMode(h, BlendMode.Additive);expect(mock.material_define).toHaveBeenCalledWith(- h, 1, BlendMode.Additive, flags(false, true, CullMode.None),+ h, 1, BlendMode.Additive, flags(false, true, CullMode.None), 0,);});@@ -315,7 +315,7 @@ describe('Material API', () => {Material.setDepthTest(h, true);expect(Material.get(h)!.depthTest).toBe(true);expect(mock.material_define).toHaveBeenCalledWith(- h, 1, BlendMode.Normal, flags(true, true, CullMode.None),+ h, 1, BlendMode.Normal, flags(true, true, CullMode.None), 0,);});@@ -325,7 +325,47 @@ describe('Material API', () => {Material.setDepthWrite(h, false);expect(Material.get(h)!.depthWrite).toBe(false);expect(mock.material_define).toHaveBeenCalledWith(- h, 1, BlendMode.Normal, flags(false, false, CullMode.None),+ h, 1, BlendMode.Normal, flags(false, false, CullMode.None), 0,+ );+ });++ it('carries a depth bias through to the engine, as its own value', () => {+ const h = Material.create({ shader: 1 as ShaderHandle });+ mock.material_define.mockClear();+ Material.setDepthBias(h, -8);+ // Its own argument and not a bit in `flags`: a value packed into a+ // word of switches is how the two sides come to disagree about it.+ expect(mock.material_define).toHaveBeenCalledWith(+ h, 1, BlendMode.Normal, flags(false, true, CullMode.None), -8,+ );+ expect(Material.get(h)?.depthBias).toBe(-8);+ });++ it('rounds a bias to whole depth-buffer units', () => {+ const h = Material.create({ shader: 1 as ShaderHandle, depthBias: -2.6 });+ expect(Material.get(h)?.depthBias).toBe(-2.6);+ Material.setDepthBias(h, -2.6);+ expect(Material.get(h)?.depthBias).toBe(-3);+ });++ it('lets an instance override its parent bias, and inherit it otherwise', () => {+ const base = Material.create({ shader: 1 as ShaderHandle, depthBias: -4 });+ const inherits = Material.createInstance(base);+ const overrides = Material.createInstance(base);+ mock.material_define.mockClear();+ Material.setDepthBias(overrides, -16);++ expect(mock.material_define).toHaveBeenCalledWith(+ overrides, 1, BlendMode.Normal, flags(false, true, CullMode.None), -16,+ );+ mock.material_define.mockClear();+ Material.setDepthBias(base, -9);+ // The non-overriding child follows its parent; the overriding one does not.+ expect(mock.material_define).toHaveBeenCalledWith(+ inherits, 1, BlendMode.Normal, flags(false, true, CullMode.None), -9,+ );+ expect(mock.material_define).toHaveBeenCalledWith(+ overrides, 1, BlendMode.Normal, flags(false, true, CullMode.None), -16,);});@@ -335,7 +375,7 @@ describe('Material API', () => {Material.setCull(h, CullMode.Front);expect(Material.get(h)!.cull).toBe(CullMode.Front);expect(mock.material_define).toHaveBeenCalledWith(- h, 1, BlendMode.Normal, flags(false, true, CullMode.Front),+ h, 1, BlendMode.Normal, flags(false, true, CullMode.Front), 0,);});});@@ -447,7 +487,7 @@ describe('Material API', () => {mock.material_define.mockClear();const inst = Material.createInstance(src);expect(mock.material_define).toHaveBeenCalledWith(- inst, 5, BlendMode.Multiply, flags(false, true, CullMode.None),+ inst, 5, BlendMode.Multiply, flags(false, true, CullMode.None), 0,);});@@ -572,6 +612,7 @@ describe('Material API', () => {depthTest: true,depthWrite: true,cull: CullMode.None,+ depthBias: 0,properties: { u_time: 0.5 },});});diff --git a/src/esengine/bindings/MaterialBindings.cpp b/src/esengine/bindings/MaterialBindings.cppindex 77b231e33..024ebaea6 100644--- a/src/esengine/bindings/MaterialBindings.cpp+++ b/src/esengine/bindings/MaterialBindings.cpp@@ -16,6 +16,7 @@#include "../resource/ResourceManager.hpp"#include "../resource/ShaderParser.hpp"+#include <algorithm>#include <cstdlib>#include <sstream>@@ -107,7 +108,8 @@ u32 material_compileEsshader(const std::string& source, const std::string& featureturn handle.id();}-void material_define(u32 materialId, u32 shaderHandle, u32 blendMode, u32 flags) {+void material_define(u32 materialId, u32 shaderHandle, u32 blendMode, u32 flags,+ i32 depthBias) {auto* rc = g_renderContext;if (!rc) return;// The handle is the identity; the program id is a cache of what it currently@@ -121,6 +123,9 @@ void material_define(u32 materialId, u32 shaderHandle, u32 blendMode, u32 flags)rec.depthTest = (flags & 0x1u) != 0;rec.depthWrite = (flags & 0x2u) != 0;rec.cull = static_cast<CullMode>((flags >> 2) & 0x3u);+ // Its own parameter and not another flag bit: this is a VALUE, and packing+ // one into a word of booleans is how two sides come to disagree about it.+ rec.depthBias = static_cast<i16>(std::clamp(depthBias, -32768, 32767));rc->materials().define(materialId, rec);}diff --git a/src/esengine/bindings/MaterialBindings.hpp b/src/esengine/bindings/MaterialBindings.hppindex 8fd186020..48b4510f5 100644--- a/src/esengine/bindings/MaterialBindings.hpp+++ b/src/esengine/bindings/MaterialBindings.hpp@@ -32,12 +32,13 @@ namespace esengine {u32 material_compileEsshader(const std::string& source, const std::string& featuresCsv);/**- * Publish a material's resolved render state. @p shaderHandle is the SDK shader- * resource handle, translated here to the program id the render path binds;- * @p flags packs depthTest (bit 0), depthWrite (bit 1) and CullMode (bits 2-3).- * Param values arrive separately, via material_setUniform / material_setTexture.+ * Publish a material's resolved render state. @p shaderHandle is translated here+ * to the program id the render path binds; @p flags packs depthTest (bit 0),+ * depthWrite (bit 1) and CullMode (bits 2-3), while @p depthBias is its own+ * parameter because it is a value, not a switch.*/-void material_define(u32 materialId, u32 shaderHandle, u32 blendMode, u32 flags);+void material_define(u32 materialId, u32 shaderHandle, u32 blendMode, u32 flags,+ i32 depthBias);/** Pack a named param's float components into the material's std140 block, by* reflected offset. A no-op when the shader declares no matching `#pragma param`. */diff --git a/src/esengine/renderer/draw/BatchBuilder.cpp b/src/esengine/renderer/draw/BatchBuilder.cppindex 0b73d8b3a..3f9f8d382 100644--- a/src/esengine/renderer/draw/BatchBuilder.cpp+++ b/src/esengine/renderer/draw/BatchBuilder.cpp@@ -118,6 +118,7 @@ void pushBatchDraw(DrawList& drawList, const ClipState& clips,cmd.depth_test = depthTest;cmd.depth_write = depthWrite;cmd.cull = key.cull;+ cmd.depth_bias = key.depthBias;// The Batch stream always samples a texture (white fallback at minimum); other// streams bind one only when the draw actually has one (the shape stream is// textureless, so execute() must not touch sampler units for it).diff --git a/src/esengine/renderer/draw/BatchBuilder.hpp b/src/esengine/renderer/draw/BatchBuilder.hppindex ae22bcf13..c2ff85412 100644--- a/src/esengine/renderer/draw/BatchBuilder.hpp+++ b/src/esengine/renderer/draw/BatchBuilder.hpp@@ -115,6 +115,7 @@ struct BatchDrawKey {bool depthTest = false;bool depthWrite = true;u8 cull = 0; ///< CullMode: 0 = none, 1 = back, 2 = front.+ i16 depthBias = 0; ///< Depth-buffer units toward the eye. @see PipelineDesc.// The transient stream this draw's geometry lives in. Only the Batch stream carries// a per-vertex texIndex, so only it participates in the multi-texture merge.LayoutId layoutId = LayoutId::Batch;diff --git a/src/esengine/renderer/draw/DrawCommand.hpp b/src/esengine/renderer/draw/DrawCommand.hppindex 9704aac6d..1e6facd14 100644--- a/src/esengine/renderer/draw/DrawCommand.hpp+++ b/src/esengine/renderer/draw/DrawCommand.hpp@@ -107,6 +107,7 @@ struct DrawCommand {bool depth_test = false;bool depth_write = true;u8 cull = 0; ///< CullMode: 0 = none, 1 = back, 2 = front.+ i16 depth_bias = 0; ///< Depth-buffer units toward the eye. @see PipelineDesc.BatchBreak break_reason = BatchBreak::RunStart; ///< Why this draw call started.u8 texture_count = 0;@@ -371,6 +372,8 @@ struct DrawCommand {if (shader_id != next.shader_id) return BatchBreak::Shader;if (material_id != next.material_id) return BatchBreak::Material;if (cull != next.cull) return BatchBreak::Cull;+ if (depth_bias != next.depth_bias) return BatchBreak::Cull;+ if (depth_bias != next.depth_bias) return BatchBreak::Cull;if (state_flags != next.state_flags) return BatchBreak::State;if (state_flags & CMD_STATE_SCISSOR) {if (scissor != next.scissor) return BatchBreak::Scissor;diff --git a/src/esengine/renderer/draw/DrawList.cpp b/src/esengine/renderer/draw/DrawList.cppindex 9f9ba96b4..b2fd308c5 100644--- a/src/esengine/renderer/draw/DrawList.cpp+++ b/src/esengine/renderer/draw/DrawList.cpp@@ -232,6 +232,7 @@ void DrawList::execute(GfxDevice& device, TransientBufferPool& buffers,desc.stencil = stencil;desc.cullEnabled = cmd.cull != 0;desc.cullFront = cmd.cull == 2;+ desc.depthBias = cmd.depth_bias;if (lastHandle == PipelineHandle::Invalid || !(desc == lastDesc)) {lastHandle = device.createPipeline(desc);diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cppindex aa1443a0e..7d7a3277e 100644--- a/src/esengine/renderer/plugins/MeshPlugin.cpp+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp@@ -622,6 +622,7 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {key.depthTest = m->depthTest;key.depthWrite = m->depthWrite;key.cull = static_cast<u8>(m->cull);+ key.depthBias = m->depthBias;}} else if (mesh.lit && ctx.frame) {if (litProgram == 0) litProgram = ctx.frame->batchProgram({"LIT"});diff --git a/src/esengine/renderer/plugins/SpritePlugin.cpp b/src/esengine/renderer/plugins/SpritePlugin.cppindex 1212a3b14..01459d399 100644--- a/src/esengine/renderer/plugins/SpritePlugin.cpp+++ b/src/esengine/renderer/plugins/SpritePlugin.cpp@@ -112,6 +112,7 @@ void SpritePlugin::collect(RenderCollectContext& collect_ctx) {key.depthTest = m->depthTest;key.depthWrite = m->depthWrite;key.cull = static_cast<u8>(m->cull);+ key.depthBias = m->depthBias;}} else if (sprite.lit && ctx.frame) {// A material owns shading fully, so it takes precedence over the toggle.diff --git a/src/esengine/renderer/plugins/TrailPlugin.cpp b/src/esengine/renderer/plugins/TrailPlugin.cppindex 269108e67..17e0f72b8 100644--- a/src/esengine/renderer/plugins/TrailPlugin.cpp+++ b/src/esengine/renderer/plugins/TrailPlugin.cpp@@ -100,6 +100,7 @@ void TrailPlugin::collect(RenderCollectContext& collect_ctx) {key.depthTest = m->depthTest;key.depthWrite = m->depthWrite;key.cull = static_cast<u8>(m->cull);+ key.depthBias = m->depthBias;}}diff --git a/src/esengine/renderer/plugins/UIElementPlugin.cpp b/src/esengine/renderer/plugins/UIElementPlugin.cppindex ba090987a..0490a9b94 100644--- a/src/esengine/renderer/plugins/UIElementPlugin.cpp+++ b/src/esengine/renderer/plugins/UIElementPlugin.cpp@@ -250,6 +250,7 @@ void UIElementPlugin::collect(RenderCollectContext& collect_ctx) {key.depthTest = m->depthTest;key.depthWrite = m->depthWrite;key.cull = static_cast<u8>(m->cull);+ key.depthBias = m->depthBias;}}diff --git a/src/esengine/renderer/rhi/GLDevice.cpp b/src/esengine/renderer/rhi/GLDevice.cppindex 7ddae4ea8..f1b48da6d 100644--- a/src/esengine/renderer/rhi/GLDevice.cpp+++ b/src/esengine/renderer/rhi/GLDevice.cpp@@ -982,6 +982,7 @@ void GLDevice::setPipeline(PipelineHandle handle) {setDepthWrite(desc.depthWrite);setCulling(desc.cullEnabled);if (desc.cullEnabled) setCullFace(desc.cullFront);+ setDepthBias(desc.depthBias);applyStencilMode(desc.stencil);current_pipeline_ = handle;@@ -989,6 +990,24 @@ void GLDevice::setPipeline(PipelineHandle handle) {current_layout_ = desc.vertexLayout;}+/**+ * @brief Push this surface toward the eye by @p bias units of depth resolution.+ *+ * @details Both terms take it: the constant separates coplanar surfaces head-on,+ * the slope-scaled one keeps them separated at a grazing angle, where a+ * constant offset spans less depth than one pixel of the surface does.+ */+void GLDevice::setDepthBias(i16 bias) {+ if (bias == current_depth_bias_) return;+ if (bias == 0) {+ glDisable(GL_POLYGON_OFFSET_FILL);+ } else {+ glEnable(GL_POLYGON_OFFSET_FILL);+ glPolygonOffset(static_cast<f32>(bias), static_cast<f32>(bias));+ }+ current_depth_bias_ = bias;+}+void GLDevice::setStencilReference(i32 ref) {switch (current_stencil_mode_) {case GfxStencilMode::Write:diff --git a/src/esengine/renderer/rhi/GLDevice.hpp b/src/esengine/renderer/rhi/GLDevice.hppindex 13d7aa39f..872beb1de 100644--- a/src/esengine/renderer/rhi/GLDevice.hpp+++ b/src/esengine/renderer/rhi/GLDevice.hpp@@ -159,6 +159,7 @@ private:void setColorMask(bool r, bool g, bool b, bool a);void setCulling(bool enabled);void setCullFace(bool front);+ void setDepthBias(i16 bias);// Pipeline cache: a handle is (index + 1) into pipelines_; PipelineHandle::Invalid is 0.// WebGL2 has no native pipeline object, so a pipeline is applied as a bundle of GL@@ -205,6 +206,7 @@ private:static constexpr u32 kTextureSlots = 16;u32 active_texture_unit_ = 0;u32 bound_texture_[kTextureSlots] = {};+ i16 current_depth_bias_ = 0;int scissor_test_ = -1; // tri-state: -1 unknown, 0 disabled, 1 enabledstruct LayoutRecord {diff --git a/src/esengine/renderer/rhi/PipelineState.hpp b/src/esengine/renderer/rhi/PipelineState.hppindex cfaaff4d6..6ac469b32 100644--- a/src/esengine/renderer/rhi/PipelineState.hpp+++ b/src/esengine/renderer/rhi/PipelineState.hpp@@ -51,6 +51,10 @@ struct PipelineDesc {GfxStencilMode stencil = GfxStencilMode::Off;bool cullEnabled = false;bool cullFront = false;+ /// How far toward the eye this surface is pushed, in units of the depth+ /// buffer's resolution — the only way to say which of two COPLANAR surfaces+ /// wins. Drives both the constant and the slope-scaled term.+ i16 depthBias = 0;bool operator==(const PipelineDesc&) const = default;};diff --git a/src/esengine/renderer/store/MaterialStore.hpp b/src/esengine/renderer/store/MaterialStore.hppindex 981644d1d..a56b2a00d 100644--- a/src/esengine/renderer/store/MaterialStore.hpp+++ b/src/esengine/renderer/store/MaterialStore.hpp@@ -118,6 +118,9 @@ struct MaterialRecord {bool depthTest = false;bool depthWrite = true;CullMode cull = CullMode::None;+ /// Depth-buffer units toward the eye — what a surface laid ON another one+ /// says so it wins. @see PipelineDesc::depthBias.+ i16 depthBias = 0;/// Packed std140 MaterialConstants payload (sized to the shader's blockSize), the GPU/// UBO it uploads to (lazy), and whether the bytes changed since the last upload.diff --git a/src/esengine/renderer/webgpu/WebGPUMappings.hpp b/src/esengine/renderer/webgpu/WebGPUMappings.hppindex c185b26c4..6cc547c21 100644--- a/src/esengine/renderer/webgpu/WebGPUMappings.hpp+++ b/src/esengine/renderer/webgpu/WebGPUMappings.hpp@@ -318,6 +318,11 @@ inline WGPUDepthStencilState toWGPUDepthStencil(const PipelineDesc& desc, WGPUTeds.stencilBack = toWGPUStencilFace(desc.stencil);ds.stencilReadMask = 0xFFu;ds.stencilWriteMask = toWGPUStencilWriteMask(desc.stencil);+ // Both terms, for the reason GLDevice::setDepthBias gives: head-on the+ // constant separates coplanar surfaces, at a grazing angle only the+ // slope-scaled one does.+ ds.depthBias = desc.depthBias;+ ds.depthBiasSlopeScale = static_cast<float>(desc.depthBias);return ds;}diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 422dd406b..9b8727b4c 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -28,6 +28,9 @@ export const NOTES_FLOOR = 'v0.65.0';* the reader recognises anyway.*/export const NOTED = {+ 'feat(render): a material can say its surface goes ON another one':+ { note: 'A surface can say it goes ON another one.' },+'feat(editor): a scatter brush, and one stroke that undoes in one step':{ note: 'A scatter brush.' },diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex 87df1d6ea..904ea2d83 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -543,6 +543,12 @@ export const SCENES = [// A material drawing GPU-resident geometry. Its shader writes only a fragment,// so the ENGINE owns the vertex stage and compiles a second variant for this// source; wrong placement or an ignored tint moves the probes.++ // Two COPLANAR surfaces, separated by nothing but the bias the decal's+ // material carries: the centre is the decal, the ring is the wall. The twin+ // below is identical but for that one number, and shows wall throughout.+ { id: "mat-decal", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-decal.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[255,0,0],\"tol\":40},{\"x\":0.25,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":40}]" } },+ { id: "mat-decal-flat", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-decal-flat.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":40},{\"x\":0.25,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":40}]" } },{ id: "mesh-material", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_MESH_ASSET: "/scenes/white-triangles.esmesh", ESTELLA_VERIFY_MESH_MATERIAL: "/scenes/mesh-material/tintonly.esmaterial", ESTELLA_VERIFY_SCENE: "/scenes/mesh-material.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh-material.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.30,\"y\":0.556,\"rgb\":[0,0,255],\"tol\":40},{\"x\":0.70,\"y\":0.556,\"rgb\":[0,0,255],\"tol\":40},{\"x\":0.5,\"y\":0.12,\"rgb\":[0,0,0],\"tol\":30}]" } },// What a normal is FOR: two coplanar triangles, one white colour, normals// facing the viewer and +X, under a head-on directional light. Only a shader