@driftengine/core 4.11.1 → 4.13.0

package/dist/render/shaders/flat/layerLooks.js

@@ -0,0 +1,108 @@
+/**
+ * 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) {
+    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 layerNamedSpecular(int i) { return -1.0; }
+float layerRepeatDown(int i, float across) { return across; }
+vec2 layerOcclusionStrengths() { return vec2(0.0); }
+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
+ * on the colour, from 0 up (6), and on the ambient light (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 specular the layer names, or -1 where it names none and the surface's own stands. */
+float layerNamedSpecular(int i) {
+  if (LAYER_LOOKS) return layerLook(48 + i);
+  return -1.0;
+}
+
+/* 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;
+}
+
+/* The mesh occlusion's strength on the colour (x), from 0 up, and on the ambient light (y). */
+vec2 layerOcclusionStrengths() {
+  if (LAYER_LOOKS) return uLayerLooks[1].zw;
+  return vec2(0.0);
+}
+
+vec2 layerOcclusionRange() {
+  if (LAYER_LOOKS) return uLayerLooks[14].zw;
+  return vec2(0.0, 1.0);
+}
+`;
+}

package/dist/render/shaders/flat/layered.d.ts

@@ -2,7 +2,8 @@
  * 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,7 +22,8 @@
  * 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 declare function layeredGlsl(on: boolean): string;
+export declare function layeredGlsl(on: boolean, looks?: boolean): string;

package/dist/render/shaders/flat/layered.js

@@ -1,8 +1,10 @@
+import { layerLooksGlsl } from './layerLooks.js';
 /**
  * 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 +23,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) {
+export function layeredGlsl(on, looks = false) {
     if (!on) {
         return /* glsl */ `
 const bool LAYERED = false;  // wgsl:override
@@ -38,6 +41,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 +56,16 @@ 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's colour and of its ambient
+ * light, 1 where none: layeredBegin.
+ */
+float lColorOcclusion;
+float lAmbientOcclusion;
 
 bool layered() {
   return uLayers[1].y > 0.5;
@@ -71,14 +82,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 +104,25 @@ 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 each strength. The
+   * colour's may pass 1, darkening faster than the occlusion does, and is held at black.
+   */
+  lColorOcclusion = 1.0;
+  lAmbientOcclusion = 1.0;
+  vec2 strength = layerOcclusionStrengths();
+  if (strength.x > 0.0 || strength.y > 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 bare = 1.0 - mix(range.x, range.y, texture(uOrmMap, vec3(vUv.xy, at)).r);
+    lColorOcclusion = max(0.0, 1.0 - strength.x * bare);
+    lAmbientOcclusion = 1.0 - strength.y * bare;
+  }
   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 +162,60 @@ 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, at the colour's strength.
+ */
 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;
   }
+  sum.rgb *= lColorOcclusion;
   return sum;
 }
 
+/* What the ambient light keeps: the occlusion at the mesh's coordinates, at the ambient's strength. */
+float layeredAmbient() {
+  return lAmbientOcclusion;
+}
+
+/*
+ * The specular by the shares: each layer's named one at its share, and the surface's own over the
+ * layers naming none, once at most. Under a summed blend the shares add past 1 where the weights
+ * do, and a surface whose layers leave the specular to it reflects its own, not its own times that
+ * sum; under a blend laid over, the shares never pass 1 and this is the sum it always was. What it
+ * gives up: named speculars still add as their colours do, so a summed blend that names them
+ * reflects their sum. 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 named = 0.0;
+    float unnamed = 0.0;
+    for (int i = 0; i < 5; i++) {
+      if (float(i) >= uLayers[1].y) break;
+      float specular = layerNamedSpecular(i);
+      if (specular < 0.0) unnamed += layerShare(i);
+      else named += specular * layerShare(i);
+    }
+    return named + own * min(unnamed, 1.0);
+  }
+  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 +232,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 +245,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. */