@driftengine/core 4.11.1 → 4.12.0

package/src/render/shaders/flat/layerLooks.ts

@@ -0,0 +1,116 @@
+/**
+ * Which layer of the shared arrays each of a layered material's layers reads, and how each looks:
+ * `uLayerLooks`, packed by `surfaceLayerLooks.ts`, read by `layered.ts`.
+ *
+ * **Every helper is the identity where the switch is off**, written as a branch on `LAYER_LOOKS`
+ * itself because the generated WGSL carries one string for both values of an override: layer `i`
+ * reads layer `i`, the maps beyond the layers start at the layer count, a tint is white, a range is
+ * 0 to 1, a normal is as stored, a specular is the surface's own, a repeat down is the repeat
+ * across, and nothing is occluded — exactly what `layered.ts` did before this existed, which is what
+ * a layered material that asks for none of it has to keep drawing.
+ *
+ * **A lit switch, `LAYER_LOOKS`**, off until a material first asks and declared after `LAYERED`, so
+ * every switch before it keeps its id. It is only ever compiled beside `LAYERED`, whose `uLayers`
+ * it reads.
+ */
+export function layerLooksGlsl(on: boolean): string {
+  if (!on) {
+    return /* glsl */ `
+const bool LAYER_LOOKS = false;  // wgsl:override
+float layerArray(int i) { return float(i); }
+float layerExtras() { return uLayers[1].y; }
+vec3 layerTint(int i) { return vec3(1.0); }
+vec2 layerRanges(int i, vec2 roughMetal) { return roughMetal; }
+vec3 layerStrengthen(int i, vec3 texel) { return texel; }
+float layerSpecular(int i, float own) { return own; }
+float layerRepeatDown(int i, float across) { return across; }
+float layerOcclusionStrength() { return 0.0; }
+bool layerOcclusionAmbient() { return false; }
+vec2 layerOcclusionRange() { return vec2(0.0, 1.0); }
+`;
+  }
+  return /* glsl */ `
+/* Whether layers are picked from shared arrays and given looks of their own: layerLooks.ts. */
+const bool LAYER_LOOKS = true;  // wgsl:override
+/*
+ * Fifteen vectors, as surfaceLayerLooks.ts packs them: the array layer each of the five reads, base
+ * first (floats 0 to 4); where the maps beyond the layers start (5), the mesh occlusion's strength
+ * (6) and whether it darkens the ambient light rather than the colour (7); then two vectors a
+ * layer, base first: its tint (x y z) and normal strength (w), then its roughness range (x to y)
+ * and metalness range (z to w); then each layer's specular, -1 for the surface's own (48 to 52), its
+ * repeat down (53 to 57), and the occlusion's range (58 to 59).
+ */
+uniform vec4 uLayerLooks[15]; // wgsl:material
+
+/* Float k of the fifteen vectors. */
+float layerLook(int k) {
+  return uLayerLooks[k / 4][k % 4];
+}
+
+/* The layer of the albedo, normal and ORM arrays a material's layer i reads. */
+float layerArray(int i) {
+  if (LAYER_LOOKS) return layerLook(i);
+  return float(i);
+}
+
+/* Where the maps beyond the layers start in each array. */
+float layerExtras() {
+  if (LAYER_LOOKS) return uLayerLooks[1].y;
+  return uLayers[1].y;
+}
+
+vec3 layerTint(int i) {
+  if (LAYER_LOOKS) return uLayerLooks[2 + i * 2].xyz;
+  return vec3(1.0);
+}
+
+/* The ORM's roughness and metalness, each spread over the layer's own range. */
+vec2 layerRanges(int i, vec2 roughMetal) {
+  if (LAYER_LOOKS) {
+    vec4 range = uLayerLooks[3 + i * 2];
+    return vec2(mix(range.x, range.y, roughMetal.x), mix(range.z, range.w, roughMetal.y));
+  }
+  return roughMetal;
+}
+
+/*
+ * A tangent-space texel bent further or less by the layer's strength: its x and y scaled, its z
+ * kept, so 0 lies flat and a strength above 1 steepens every slope the map holds. z is held above
+ * zero so a texel lying exactly flat on its surface cannot normalise to nothing at strength 0.
+ */
+vec3 layerStrengthen(int i, vec3 texel) {
+  if (LAYER_LOOKS) return normalize(vec3(texel.xy * uLayerLooks[2 + i * 2].w, max(texel.z, 1e-4)));
+  return texel;
+}
+
+/* The layer's specular, or the surface's own where it names none. */
+float layerSpecular(int i, float own) {
+  if (LAYER_LOOKS) {
+    float named = layerLook(48 + i);
+    return named < 0.0 ? own : named;
+  }
+  return own;
+}
+
+/* The layer's repeat down, which is its repeat across unless it gave two. */
+float layerRepeatDown(int i, float across) {
+  if (LAYER_LOOKS) return layerLook(53 + i);
+  return across;
+}
+
+float layerOcclusionStrength() {
+  if (LAYER_LOOKS) return uLayerLooks[1].z;
+  return 0.0;
+}
+
+bool layerOcclusionAmbient() {
+  if (LAYER_LOOKS) return uLayerLooks[1].w > 0.5;
+  return false;
+}
+
+vec2 layerOcclusionRange() {
+  if (LAYER_LOOKS) return uLayerLooks[14].zw;
+  return vec2(0.0, 1.0);
+}
+`;
+}

package/src/render/shaders/flat/layered.ts

@@ -1,8 +1,11 @@
+import { layerLooksGlsl } from './layerLooks.ts';
+
 /**
  * A material blended from layers by a mask: `SurfaceMaterial.layers`, packed into `uLayers` by
  * `surfaceLayers.ts`.
  *
- * **Layer `i` is layer `i` of the material's arrays**, each read at its own repeat of where the
+ * **Layer `i` is layer `i` of the material's arrays** — or the layer `layerLooks.ts` picks, with the
+ * tint, ranges and normal strength it gives each — each read at its own repeat of where the
  * layers are laid: the mesh's coordinates, or the world's horizontal plane where the material has a
  * projection (`worldUv.ts`). The mask's channels weigh layers 1 to 4 — red, green, blue, alpha — and
  * come from a map read where a shading model's would be, from the ORM array's layer past the layers,
@@ -21,10 +24,11 @@
  * in uniform control flow (AGENTS.md 2026-08-07), so the loop is bounded by the layer count, a
  * uniform, and never skips on a share, which is the pixel's own.
  *
- * **A lit switch, `LAYERED`**, off until a material first asks, declared last so every switch before
- * it keeps its id. Compiled out, its four vectors are not declared and its calls are constants.
+ * **A lit switch, `LAYERED`**, off until a material first asks, declared after every switch before
+ * it so each keeps its id. Compiled out, its four vectors are not declared and its calls are
+ * constants. `looks` compiles `LAYER_LOOKS` in beside it, and means nothing without it.
  */
-export function layeredGlsl(on: boolean): string {
+export function layeredGlsl(on: boolean, looks = false): string {
   if (!on) {
     return /* glsl */ `
 const bool LAYERED = false;  // wgsl:override
@@ -38,6 +42,8 @@ bool layeredMeshNormal() { return false; }
 vec3 layeredMeshTexel() { return vec3(0.0, 0.0, 1.0); }
 bool layeredGlows() { return false; }
 vec3 layeredEmissive() { return vec3(0.0); }
+float layeredAmbient() { return 1.0; }
+float layeredSpecular(float own) { return own; }
 `;
   }
   return /* glsl */ `
@@ -51,10 +57,12 @@ const bool LAYERED = true;  // wgsl:override
  * layer or -1 (y), its bias (z) and its sharpness (w).
  */
 uniform vec4 uLayers[4]; // wgsl:material
-
+${layerLooksGlsl(looks)}
 /* Each layer's share of this point, the base's and layers 1 to 4's: worked out once, in layeredBegin. */
 float lShareBase;
 vec4 lShare;
+/* What an occlusion read at the mesh's coordinates leaves of this point, 1 where none: layeredBegin. */
+float lMeshOcclusion;
 
 bool layered() {
   return uLayers[1].y > 0.5;
@@ -71,14 +79,15 @@ vec2 layerPlace() {
 }
 
 vec3 layerAt(int i) {
-  return vec3(layerPlace() * layerRepeat(i), float(i));
+  float across = layerRepeat(i);
+  return vec3(layerPlace() * vec2(across, layerRepeatDown(i, across)), layerArray(i));
 }
 
 /* The weights as the material keeps them: the mask's channels, at the mesh's own coordinates. */
 vec4 layerWeights() {
   float source = uLayers[1].w;
   if (source > 1.5) return vec4(vColor, 0.0);
-  if (source > 0.5) return texture(uOrmMap, vec3(vUv.xy, uLayers[1].y));
+  if (source > 0.5) return texture(uOrmMap, vec3(vUv.xy, layerExtras()));
   return texture(uModelMap, vec3(vUv.xy, 0.0));
 }
 
@@ -92,10 +101,22 @@ vec4 layerPick(float layer) {
  * Under a branch on uniforms, as its reads are.
  */
 void layeredBegin() {
+  /*
+   * The occlusion at the mesh's coordinates, once: the ORM array's layer past the layers and past
+   * any mask and added mask it carries, spread over its range and taken at its strength.
+   */
+  lMeshOcclusion = 1.0;
+  float strength = layerOcclusionStrength();
+  if (strength > 0.0) {
+    float at = layerExtras() + (abs(uLayers[1].w - 1.0) < 0.5 ? 1.0 : 0.0) + (uLayers[2].z > 0.5 ? 1.0 : 0.0);
+    vec2 range = layerOcclusionRange();
+    float occlusion = mix(range.x, range.y, texture(uOrmMap, vec3(vUv.xy, at)).r);
+    lMeshOcclusion = mix(1.0, occlusion, strength);
+  }
   vec4 m = layerWeights();
   if (uLayers[2].z > 0.5) {
     /* The ORM array's layer past the layers, and past the mask where the array carries that too. */
-    float at = uLayers[1].y + (abs(uLayers[1].w - 1.0) < 0.5 ? 1.0 : 0.0);
+    float at = layerExtras() + (abs(uLayers[1].w - 1.0) < 0.5 ? 1.0 : 0.0);
     float added = texture(uOrmMap, vec3(layerPlace() * uLayers[2].w, at)).r * uLayers[3].x;
     m = mix(m, clamp(m + added, 0.0, 1.0), layerPick(uLayers[2].z));
   }
@@ -135,23 +156,52 @@ vec3 layeredColor(vec3 color) {
   return uLayers[1].w > 1.5 ? vec3(1.0) : color;
 }
 
-/* Colour by the shares, and the base layer's coverage, which a cutout reads. */
+/*
+ * Colour by the shares, each layer's tinted, and the base layer's coverage, which a cutout reads;
+ * then darkened by the occlusion at the mesh's coordinates, where it is the colour that takes it.
+ */
 vec4 layeredAlbedo() {
   vec4 sum = vec4(0.0);
   for (int i = 0; i < 5; i++) {
     if (float(i) >= uLayers[1].y) break;
     vec4 t = texture(uAlbedo, layerAt(i));
-    sum.rgb += t.rgb * layerShare(i);
+    sum.rgb += t.rgb * layerTint(i) * layerShare(i);
     if (i == 0) sum.a = t.a;
   }
+  if (!layerOcclusionAmbient()) sum.rgb *= lMeshOcclusion;
   return sum;
 }
 
+/* What the ambient light keeps: the occlusion at the mesh's coordinates, where it takes it. */
+float layeredAmbient() {
+  return layerOcclusionAmbient() ? lMeshOcclusion : 1.0;
+}
+
+/*
+ * The specular by the shares, each layer's own or the surface's where it names none. The surface's
+ * own, untouched, where no material has asked for looks: shares summing to one in floating point
+ * are not quite one, and a layered material that names nothing must draw exactly as before.
+ */
+float layeredSpecular(float own) {
+  if (LAYER_LOOKS) {
+    float sum = 0.0;
+    for (int i = 0; i < 5; i++) {
+      if (float(i) >= uLayers[1].y) break;
+      sum += layerSpecular(i, own) * layerShare(i);
+    }
+    return sum;
+  }
+  return own;
+}
+
+/* Occlusion, roughness and metalness by the shares, each layer's spread over its own ranges. */
 vec3 layeredOrm() {
   vec3 sum = vec3(0.0);
   for (int i = 0; i < 5; i++) {
     if (float(i) >= uLayers[1].y) break;
-    sum += texture(uOrmMap, layerAt(i)).rgb * layerShare(i);
+    vec3 t = texture(uOrmMap, layerAt(i)).rgb;
+    t.yz = layerRanges(i, t.yz);
+    sum += t * layerShare(i);
   }
   return sum;
 }
@@ -168,7 +218,7 @@ vec3 layeredTexel() {
   vec3 sum = vec3(0.0);
   for (int i = 0; i < 5; i++) {
     if (float(i) >= uLayers[1].y) break;
-    sum += layerNormalTexel(layerAt(i)) * layerShare(i);
+    sum += layerStrengthen(i, layerNormalTexel(layerAt(i))) * layerShare(i);
   }
   float len = length(sum);
   return len > 1e-5 ? sum / len : vec3(0.0, 0.0, 1.0);
@@ -181,7 +231,7 @@ bool layeredMeshNormal() {
 
 /* That normal's texel: the normal array's layer past the layers, at the mesh's coordinates. */
 vec3 layeredMeshTexel() {
-  return layerNormalTexel(vec3(vUv.xy, uLayers[1].y));
+  return layerNormalTexel(vec3(vUv.xy, layerExtras()));
 }
 
 /* Whether the emissive map belongs to one layer rather than to the whole surface. */

package/src/render/shaders/flat/main.ts

@@ -18,6 +18,9 @@ export const MAIN_GLSL = `void main() {
   projectSurface(surfaceAt, frameAt, frameTangents);
   /* A layered material's mask, read once for every layer's share below: layered.ts. */
   if (LAYERED && layered()) layeredBegin();
+  /* And the specular every highlight below reads: its layers' own, where a material gives them. */
+  surfaceSpecular = vSpecular;
+  if (LAYERED && layered()) surfaceSpecular = layeredSpecular(vSpecular);
   if (dot(vec4(vWorldPos, 1.0), uClipPlane) < 0.0) discard;
   /*
    * The layer's surface effects, zeros where the albedo array carries no table — see
@@ -511,6 +514,8 @@ export const MAIN_GLSL = `void main() {
 #endif
     /* A draw's own ambient, where one is set, in place of the frame's: \`setAmbientSH\`. */
     if (uAmbientSH[6].w > 0.5) ambient = ambientHarmonics(n);
+    /* Less of it where a layered material's mesh occlusion darkens the ambient light: layered.ts. */
+    if (LAYERED && layered()) ambient *= layeredAmbient();
     /*
      * A metal keeps its ambient and loses its direct diffuse.
      *
@@ -564,7 +569,7 @@ export const MAIN_GLSL = `void main() {
      * mix(x, y, 0) is exactly x, so at metal 0 this is vec3(vSpecular) and the line below is the
      * one it replaces with the scalar broadened to three components.
      */
-    vec3 specColor = mix(vec3(vSpecular), albedo, metal);
+    vec3 specColor = mix(vec3(surfaceSpecular), albedo, metal);
     /*
      * **A metal's highlight goes white at a grazing angle, and that is most of what reads as
      * polished.**
@@ -1657,7 +1662,7 @@ export const MAIN_GLSL = `void main() {
        * any lamp in the scene. The condition is the old one exactly when metal is 0, so nothing
        * that binds no map takes a different branch than it took before.
        */
-      if (vSpecular > 0.0 || metal > 0.0) {
+      if (surfaceSpecular > 0.0 || metal > 0.0) {
         vec3 toEyeLamp = normalize(uCameraPos - vWorldPos);
         vec3 lampHalfway = normalize(toLight / max(dist, 1e-4) + toEyeLamp);
         /* The same grazing whitening the sun's highlight takes, and zero at metal 0 for the look. */

package/src/render/shaders/flat/models.ts

@@ -221,7 +221,7 @@ void modelSurface(vec3 n, vec3 albedo, float roughness, float metal, vec3 at) {
   if (MODEL_SKIN) {
     if (SKIN_DIFFUSE) mAlbedo = vec3(1.0);
   }
-  mSpecColor = mix(vec3(vSpecular), albedo, metal);
+  mSpecColor = mix(vec3(surfaceSpecular), albedo, metal);
   mRoughness = roughness;
   mMetal = metal;
   mMap = vec4(0.5, 0.5, 1.0, 1.0);

package/src/render/shaders/flat/preamble.ts

@@ -52,6 +52,12 @@ in vec3 vColor;
 in vec3 vWorldPos;
 in float vEmissive;
 in float vSpecular;
+/*
+ * The specular this fragment shades with: its vertices' own, or a layered material's layers'
+ * blend of theirs, set once at the top of main. Every read of the specular reads this rather than
+ * the varying, so a layer's specular reaches the highlight, the reflection and the area lights alike.
+ */
+float surfaceSpecular;
 in vec4 vLightPos;
 in vec3 vUv;
 in vec3 vEmissiveColor;