@driftengine/core 4.11.0 → 4.12.0

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

@@ -7,4 +7,4 @@
  *
  * Depth zero and after the models, whose `modelLight` it calls; see `flatFrag`.
  */
-export declare const AREA_LIGHT_GLSL = "\n/**\n * The rectangle's signed form factor at this fragment: its corners **wound so a surface on the\n * emitting side sees them counter-clockwise**, which is what makes it positive there. The natural\n * order \u2014 minus, plus, plus, minus \u2014 winds the other way, and every one-sided light then clamped to\n * zero and the frame was black. The sign is the sidedness: a one-sided rectangle takes the positive\n * part and a two-sided one the magnitude.\n */\nfloat areaSignedForm(vec3 n, vec3 centre, vec3 right, vec3 up, vec2 halfSize) {\n  vec3 c0 = centre - right * halfSize.x + up * halfSize.y;\n  vec3 c1 = centre + right * halfSize.x + up * halfSize.y;\n  vec3 c2 = centre + right * halfSize.x - up * halfSize.y;\n  vec3 c3 = centre - right * halfSize.x - up * halfSize.y;\n  return quadFormFactor(n, vWorldPos, c0, c1, c2, c3);\n}\n\n/**\n * How far along one of a rectangle's axes a fragment still sees it past the barn door on that axis's\n * positive edge: `p` the fragment's place along the axis, `height` its height above the\n * rectangle's plane, `halfSize` the rectangle's half extent, and the door's tip `tipOut` beyond\n * the edge and `tipUp` above the plane. Points of the rectangle past the answer are hidden.\n *\n * Above the tip, the tip's shadow on the plane as seen from the fragment is the limit. Below it, a\n * fragment beside the door and outside its line is hidden from all of it, and one inside the door's\n * reach is hidden from none of it.\n */\nfloat barnDoorLimit(float p, float height, float halfSize, float tipOut, float tipUp) {\n  float tipAt = halfSize + tipOut;\n  if (height > tipUp) return (height * tipAt - tipUp * p) / (height - tipUp);\n  if (p > halfSize && height * tipOut < tipUp * (p - halfSize)) return -1e9;\n  return 1e9;\n}\n\n/**\n * The part of a rectangle a fragment sees past its barn doors, written into `centre` and\n * `halfSize` as the smaller rectangle that is left, or false where the doors hide all of it.\n * `doors` is the cosine of their angle from the normal and their length; a length of 0 is no doors.\n * Each axis is clipped by its own two doors, which is what makes this four projections and a min.\n */\nbool areaBarnDoors(inout vec3 centre, vec3 right, vec3 up, inout vec2 halfSize, vec2 doors) {\n  if (doors.y <= 0.0) return true;\n  vec3 toFragment = vWorldPos - centre;\n  float height = dot(toFragment, cross(right, up));\n  /* Behind the emitting side: nothing to clip, and the form factor already answers it. */\n  if (height <= 0.0) return true;\n  float tipOut = doors.y * sqrt(max(1.0 - doors.x * doors.x, 0.0));\n  float tipUp = doors.y * doors.x;\n  vec2 p = vec2(dot(toFragment, right), dot(toFragment, up));\n  vec2 hi = vec2(\n    min(halfSize.x, barnDoorLimit(p.x, height, halfSize.x, tipOut, tipUp)),\n    min(halfSize.y, barnDoorLimit(p.y, height, halfSize.y, tipOut, tipUp))\n  );\n  vec2 lo = vec2(\n    max(-halfSize.x, -barnDoorLimit(-p.x, height, halfSize.x, tipOut, tipUp)),\n    max(-halfSize.y, -barnDoorLimit(-p.y, height, halfSize.y, tipOut, tipUp))\n  );\n  if (hi.x <= lo.x || hi.y <= lo.y) return false;\n  centre += right * (0.5 * (lo.x + hi.x)) + up * (0.5 * (lo.y + hi.y));\n  halfSize = 0.5 * (hi - lo);\n  return true;\n}\n\n/**\n * What one rectangle of colour `color` and form factor `form` adds to the lamps' two sums, open\n * and shadowed by `occl` and `glass`.\n *\n * **A model answers a rectangle as it answers a lamp at its centre**, carried at the rectangle's\n * own energy: the diffuse by the exact form factor over the centre's cosine, the specular by the\n * form factor. An approximation, stated: a model's lobe is not integrated over the rectangle as the\n * standard lobe is, so a glossy model under a large softbox shows a lobe from its centre rather than\n * its shape.\n *\n * **The standard lobe is integrated over the rectangle**, rather than sampled at one point on it.\n * What stood here once handed the closest point on the rectangle to `sphereLobe` and scaled it by\n * `form`, the *diffuse* form factor. Measured against a brute-force integral by\n * `scripts/areaSpecular.mjs`, that lost the reflection rather than blurring it: on polished metal\n * facing a softbox it returned 0.000233 where the integral is 0.9207, and head-on on a rough surface\n * it was 3.7 times too bright. Worst 287% either way; this is 40.1% where the light is what the\n * surface reflects and 79.0% for one overhead. `quadCoverage` says what fraction of the specular\n * lobe the rectangle covers and the environment BRDF says how much the surface returns, the split\n * the probe path uses. **`dfg.x + dfg.y` and not `envSpecularEnergy`**, deliberately: the\n * compensation returns the multiply-scattered share, and every direct lobe in this shader is\n * single-scattering, so adding it here returns energy the light never had. Measured at 211%\n * against 40.1%.\n */\nvoid areaLightAdd(\n  vec3 centre,\n  vec3 right,\n  vec3 up,\n  vec2 halfSize,\n  vec3 color,\n  float form,\n  float occl,\n  vec3 glass,\n  vec3 n,\n  vec3 albedo,\n  float metal,\n  vec3 specColor,\n  float roughness,\n  bool modelled,\n  inout vec3 lampOpen,\n  inout vec3 lampShadowed\n) {\n  if (modelled) {\n    vec3 areaL = normalize(centre - vWorldPos);\n    modelLight(areaL, 0.0, 0.0);\n    vec3 areaModel = (mDiffuse * (form / max(dot(n, areaL), 1e-3)) + mSpecular * form) * color;\n    lampOpen += areaModel;\n    lampShadowed += areaModel * occl * glass;\n    return;\n  }\n  /* Held back with the point lamps', and shadowed by the same term it always was. */\n  vec3 areaDiffuse = albedo * color * form * (1.0 - metal);\n  lampOpen += areaDiffuse;\n  lampShadowed += areaDiffuse * occl * glass;\n\n  if (vSpecular > 0.0 || metal > 0.0) {\n    vec3 c0 = centre - right * halfSize.x + up * halfSize.y;\n    vec3 c1 = centre + right * halfSize.x + up * halfSize.y;\n    vec3 c2 = centre + right * halfSize.x - up * halfSize.y;\n    vec3 c3 = centre - right * halfSize.x - up * halfSize.y;\n    vec3 toEyeArea = normalize(uCameraPos - vWorldPos);\n    float coverage = quadCoverage(n, vWorldPos, toEyeArea, roughness, c0, c1, c2, c3);\n    if (coverage > 0.0) {\n      vec2 areaDfg = envBrdfApprox(max(dot(n, toEyeArea), 0.0), roughness);\n      vec3 areaSpec = specColor * areaDfg.x + vec3(areaDfg.y);\n      vec3 areaHighlight = areaSpec * color * coverage;\n      lampOpen += areaHighlight;\n      lampShadowed += areaHighlight * occl * glass;\n    }\n  }\n}\n";
+export declare const AREA_LIGHT_GLSL = "\n/**\n * The rectangle's signed form factor at this fragment: its corners **wound so a surface on the\n * emitting side sees them counter-clockwise**, which is what makes it positive there. The natural\n * order \u2014 minus, plus, plus, minus \u2014 winds the other way, and every one-sided light then clamped to\n * zero and the frame was black. The sign is the sidedness: a one-sided rectangle takes the positive\n * part and a two-sided one the magnitude.\n */\nfloat areaSignedForm(vec3 n, vec3 centre, vec3 right, vec3 up, vec2 halfSize) {\n  vec3 c0 = centre - right * halfSize.x + up * halfSize.y;\n  vec3 c1 = centre + right * halfSize.x + up * halfSize.y;\n  vec3 c2 = centre + right * halfSize.x - up * halfSize.y;\n  vec3 c3 = centre - right * halfSize.x - up * halfSize.y;\n  return quadFormFactor(n, vWorldPos, c0, c1, c2, c3);\n}\n\n/**\n * How far along one of a rectangle's axes a fragment still sees it past the barn door on that axis's\n * positive edge: `p` the fragment's place along the axis, `height` its height above the\n * rectangle's plane, `halfSize` the rectangle's half extent, and the door's tip `tipOut` beyond\n * the edge and `tipUp` above the plane. Points of the rectangle past the answer are hidden.\n *\n * Above the tip, the tip's shadow on the plane as seen from the fragment is the limit. Below it, a\n * fragment beside the door and outside its line is hidden from all of it, and one inside the door's\n * reach is hidden from none of it.\n */\nfloat barnDoorLimit(float p, float height, float halfSize, float tipOut, float tipUp) {\n  float tipAt = halfSize + tipOut;\n  if (height > tipUp) return (height * tipAt - tipUp * p) / (height - tipUp);\n  if (p > halfSize && height * tipOut < tipUp * (p - halfSize)) return -1e9;\n  return 1e9;\n}\n\n/**\n * The part of a rectangle a fragment sees past its barn doors, written into `centre` and\n * `halfSize` as the smaller rectangle that is left, or false where the doors hide all of it.\n * `doors` is the cosine of their angle from the normal and their length; a length of 0 is no doors.\n * Each axis is clipped by its own two doors, which is what makes this four projections and a min.\n */\nbool areaBarnDoors(inout vec3 centre, vec3 right, vec3 up, inout vec2 halfSize, vec2 doors) {\n  if (doors.y <= 0.0) return true;\n  vec3 toFragment = vWorldPos - centre;\n  float height = dot(toFragment, cross(right, up));\n  /* Behind the emitting side: nothing to clip, and the form factor already answers it. */\n  if (height <= 0.0) return true;\n  float tipOut = doors.y * sqrt(max(1.0 - doors.x * doors.x, 0.0));\n  float tipUp = doors.y * doors.x;\n  vec2 p = vec2(dot(toFragment, right), dot(toFragment, up));\n  vec2 hi = vec2(\n    min(halfSize.x, barnDoorLimit(p.x, height, halfSize.x, tipOut, tipUp)),\n    min(halfSize.y, barnDoorLimit(p.y, height, halfSize.y, tipOut, tipUp))\n  );\n  vec2 lo = vec2(\n    max(-halfSize.x, -barnDoorLimit(-p.x, height, halfSize.x, tipOut, tipUp)),\n    max(-halfSize.y, -barnDoorLimit(-p.y, height, halfSize.y, tipOut, tipUp))\n  );\n  if (hi.x <= lo.x || hi.y <= lo.y) return false;\n  centre += right * (0.5 * (lo.x + hi.x)) + up * (0.5 * (lo.y + hi.y));\n  halfSize = 0.5 * (hi - lo);\n  return true;\n}\n\n/**\n * What one rectangle of colour `color` and form factor `form` adds to the lamps' two sums, open\n * and shadowed by `occl` and `glass`.\n *\n * **A model answers a rectangle as it answers a lamp at its centre**, carried at the rectangle's\n * own energy: the diffuse by the exact form factor over the centre's cosine, the specular by the\n * form factor. An approximation, stated: a model's lobe is not integrated over the rectangle as the\n * standard lobe is, so a glossy model under a large softbox shows a lobe from its centre rather than\n * its shape.\n *\n * **The standard lobe is integrated over the rectangle**, rather than sampled at one point on it.\n * What stood here once handed the closest point on the rectangle to `sphereLobe` and scaled it by\n * `form`, the *diffuse* form factor. Measured against a brute-force integral by\n * `scripts/areaSpecular.mjs`, that lost the reflection rather than blurring it: on polished metal\n * facing a softbox it returned 0.000233 where the integral is 0.9207, and head-on on a rough surface\n * it was 3.7 times too bright. Worst 287% either way; this is 40.1% where the light is what the\n * surface reflects and 79.0% for one overhead. `quadCoverage` says what fraction of the specular\n * lobe the rectangle covers and the environment BRDF says how much the surface returns, the split\n * the probe path uses. **`dfg.x + dfg.y` and not `envSpecularEnergy`**, deliberately: the\n * compensation returns the multiply-scattered share, and every direct lobe in this shader is\n * single-scattering, so adding it here returns energy the light never had. Measured at 211%\n * against 40.1%.\n */\nvoid areaLightAdd(\n  vec3 centre,\n  vec3 right,\n  vec3 up,\n  vec2 halfSize,\n  vec3 color,\n  float form,\n  float occl,\n  vec3 glass,\n  vec3 n,\n  vec3 albedo,\n  float metal,\n  vec3 specColor,\n  float roughness,\n  bool modelled,\n  inout vec3 lampOpen,\n  inout vec3 lampShadowed\n) {\n  if (modelled) {\n    vec3 areaL = normalize(centre - vWorldPos);\n    modelLight(areaL, 0.0, 0.0);\n    vec3 areaModel = (mDiffuse * (form / max(dot(n, areaL), 1e-3)) + mSpecular * form) * color;\n    lampOpen += areaModel;\n    lampShadowed += areaModel * occl * glass;\n    return;\n  }\n  /* Held back with the point lamps', and shadowed by the same term it always was. */\n  vec3 areaDiffuse = albedo * color * form * (1.0 - metal);\n  lampOpen += areaDiffuse;\n  lampShadowed += areaDiffuse * occl * glass;\n\n  if (surfaceSpecular > 0.0 || metal > 0.0) {\n    vec3 c0 = centre - right * halfSize.x + up * halfSize.y;\n    vec3 c1 = centre + right * halfSize.x + up * halfSize.y;\n    vec3 c2 = centre + right * halfSize.x - up * halfSize.y;\n    vec3 c3 = centre - right * halfSize.x - up * halfSize.y;\n    vec3 toEyeArea = normalize(uCameraPos - vWorldPos);\n    float coverage = quadCoverage(n, vWorldPos, toEyeArea, roughness, c0, c1, c2, c3);\n    if (coverage > 0.0) {\n      vec2 areaDfg = envBrdfApprox(max(dot(n, toEyeArea), 0.0), roughness);\n      vec3 areaSpec = specColor * areaDfg.x + vec3(areaDfg.y);\n      vec3 areaHighlight = areaSpec * color * coverage;\n      lampOpen += areaHighlight;\n      lampShadowed += areaHighlight * occl * glass;\n    }\n  }\n}\n";

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

@@ -123,7 +123,7 @@ void areaLightAdd(
   lampOpen += areaDiffuse;
   lampShadowed += areaDiffuse * occl * glass;
 
-  if (vSpecular > 0.0 || metal > 0.0) {
+  if (surfaceSpecular > 0.0 || metal > 0.0) {
     vec3 c0 = centre - right * halfSize.x + up * halfSize.y;
     vec3 c1 = centre + right * halfSize.x + up * halfSize.y;
     vec3 c2 = centre + right * halfSize.x - up * halfSize.y;

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

@@ -8,7 +8,7 @@ export declare function glassTintGlsl(glassShadows: boolean): string;
  * The lit stage's switches, by the name of the constant each is: the decision both backends make
  * about which optional code a lit program carries. See `litSwitchesGlsl`.
  */
-export type LitSwitch = 'GLASS_SHADOWS' | 'CLUSTERED_LIGHTS' | 'LIGHT_FIXTURES' | 'SURFACE_EFFECTS' | 'DRIFT_LIGHT' | 'PHYSICAL_SPECULAR' | 'SURFACE_OVERLAY' | 'REFLECTION_MAPS' | 'WORLD_UVS' | 'MOVING_SUN' | 'LAYERED';
+export type LitSwitch = 'GLASS_SHADOWS' | 'CLUSTERED_LIGHTS' | 'LIGHT_FIXTURES' | 'SURFACE_EFFECTS' | 'DRIFT_LIGHT' | 'PHYSICAL_SPECULAR' | 'SURFACE_OVERLAY' | 'REFLECTION_MAPS' | 'WORLD_UVS' | 'MOVING_SUN' | 'LAYERED' | 'LAYER_LOOKS';
 /** Every switch off: what a renderer starts from before its profile and its content say otherwise. */
 export declare function noLitSwitches(): Record<LitSwitch, boolean>;
 /** Which of the lit stage's optional features a build reads. See `litSwitchesGlsl`. */

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

@@ -37,6 +37,7 @@ export function noLitSwitches() {
         WORLD_UVS: false,
         MOVING_SUN: false,
         LAYERED: false,
+        LAYER_LOOKS: false,
     };
 }
 /**

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

@@ -140,6 +140,11 @@ export interface FlatShaderOptions {
      * True when absent. See \`layeredGlsl\`.
      */
     readonly layered?: boolean;
+    /**
+     * Whether a layered material's layers are picked from shared arrays and given looks of their own,
+     * \`uLayerLooks\` and all. True when absent; nothing without \`layered\`. See \`layerLooksGlsl\`.
+     */
+    readonly layerLooks?: boolean;
     /**
      * How many point lights this build declares room for. `MAX_POINT_LIGHTS` when absent.
      *

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

@@ -18,6 +18,7 @@ import { modelsGlsl } from './models.js';
 import { AREA_LIGHT_GLSL } from './areaLight.js';
 import { NORMAL_MAP_GLSL } from './normalMap.js';
 import { DRIFT_LIGHT_GLSL } from './driftLight.js';
+import { LIGHTMAP_OPACITY_STEPS } from '../../instances.js';
 import { SURFACE_EFFECTS_GLSL } from './surfaceEffects.js';
 import { overlayGlsl } from './overlay.js';
 import { reflectionSurfaceGlsl } from './reflectionSurface.js';
@@ -341,10 +342,16 @@ void main() {
   vAlpha = aInstanceTint.w;
   vThickness = 1.0;
   if (LIGHTMAP_REGIONS) {
+    /*
+     * The opacity's transparency rides the U offset as whole steps of 2, the offset itself under 1
+     * (\`MeshInstances.lightmapRegions\`): taken off, and none where the instance is opaque.
+     */
+    float steps = floor(aInstanceTint.z * 0.5);
+    float offsetU = aInstanceTint.z - 2.0 * steps;
     /* Out of the lane's \`-1 - uv\`, through the region, and back into it. See lightmap.ts. */
-    vGrain = -1.0 - ((-1.0 - aGrain) * aInstanceTint.x + aInstanceTint.z);
+    vGrain = -1.0 - ((-1.0 - aGrain) * aInstanceTint.x + offsetU);
     vRelief = -1.0 - ((-1.0 - aRelief) * aInstanceTint.y + aInstanceTint.w);
-    vAlpha = 1.0;
+    vAlpha = 1.0 - steps / ${LIGHTMAP_OPACITY_STEPS.toFixed(1)};
   }
 #else
   vSkyDirect = aChannel.y;
@@ -506,7 +513,7 @@ export function flatFrag(options) {
         /* After the reflection maps, so its switch takes the next id; main calls it. worldUv.ts. */
         worldUvGlsl(options.worldUvs ?? true),
         /* After the projection, so its switch takes the next id; the normal map below calls it. */
-        layeredGlsl(options.layered ?? true),
+        layeredGlsl(options.layered ?? true, options.layerLooks ?? true),
         /* Where each map is read, after both of the ways it can be read otherwise. See mapReads.ts. */
         MAP_READS_GLSL,
         /* After the frame and the projection it calls, unconditional for the same reason as the

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

@@ -0,0 +1,16 @@
+/**
+ * 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 declare function layerLooksGlsl(on: boolean): string;

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

@@ -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) {
+    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/dist/render/shaders/flat/layered.d.ts

@@ -2,18 +2,28 @@
  * 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 the mesh's coordinates times its
- * own repeat; the mask is layer 0 of the map a shading model would read, at the mesh's coordinates.
- * Each channel lays a layer over everything before it — red layer 1, green 2, blue 3, alpha 4 — so a
- * layer's share is its channel times one less each later channel, and the base keeps what none of
- * them took. Colour, roughness and occlusion are blended by those shares, and the normal map's
- * tangent-space texels too, before the frame turns them into the world.
+ * **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,
+ * or from the vertex colour; an added mask placed as the layers are raises one layer's weight, and
+ * one layer may be weighed by how much the surface faces up instead of by its channel.
+ *
+ * **Two ways to combine them.** Laid over, each layer covers everything before it, so a layer's
+ * share is its weight times one less each later weight, and the base keeps what none took. Summed,
+ * the base is mixed toward each layer times its weight by the weights' sum held to 1, so each
+ * layer's share is its weight times that and the base keeps the rest. The shares are worked out once
+ * a pixel, in `layeredBegin`; colour, roughness and occlusion are blended by them, and the normal
+ * map's tangent-space texels too, before the frame turns them into the world — around a normal read
+ * at the mesh's own coordinates, where the material lays one under the layers.
  *
  * **Every layer present is read, whatever its share.** A read whose level is implicit is legal only
  * 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 two 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,106 +1,238 @@
+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 the mesh's coordinates times its
- * own repeat; the mask is layer 0 of the map a shading model would read, at the mesh's coordinates.
- * Each channel lays a layer over everything before it — red layer 1, green 2, blue 3, alpha 4 — so a
- * layer's share is its channel times one less each later channel, and the base keeps what none of
- * them took. Colour, roughness and occlusion are blended by those shares, and the normal map's
- * tangent-space texels too, before the frame turns them into the world.
+ * **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,
+ * or from the vertex colour; an added mask placed as the layers are raises one layer's weight, and
+ * one layer may be weighed by how much the surface faces up instead of by its channel.
+ *
+ * **Two ways to combine them.** Laid over, each layer covers everything before it, so a layer's
+ * share is its weight times one less each later weight, and the base keeps what none took. Summed,
+ * the base is mixed toward each layer times its weight by the weights' sum held to 1, so each
+ * layer's share is its weight times that and the base keeps the rest. The shares are worked out once
+ * a pixel, in `layeredBegin`; colour, roughness and occlusion are blended by them, and the normal
+ * map's tangent-space texels too, before the frame turns them into the world — around a normal read
+ * at the mesh's own coordinates, where the material lays one under the layers.
  *
  * **Every layer present is read, whatever its share.** A read whose level is implicit is legal only
  * 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 two 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
 bool layered() { return false; }
 void layeredBegin() {}
+vec3 layeredColor(vec3 color) { return color; }
 vec4 layeredAlbedo() { return vec4(1.0); }
 vec3 layeredOrm() { return vec3(1.0); }
 vec3 layeredTexel() { return vec3(0.0, 0.0, 1.0); }
+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 */ `
 /* Whether this program blends a material's layers. Off but where one has asked: layered.ts. */
 const bool LAYERED = true;  // wgsl:override
-/* The five repeats, base first (x y z w, then x), the count (y) and the glowing layer, or -1 (z). */
-uniform vec4 uLayers[2]; // wgsl:material
-
-/* The mask's channels that lay a layer, zero past the count: read once, in layeredBegin. */
-vec4 lMask;
+/*
+ * Four vectors, as surfaceLayers.ts packs them: the five repeats, base first (x y z w, then x); the
+ * count (y), the glowing layer or -1 (z) and where the mask is, 0 a map, 1 the ORM array, 2 the
+ * vertex colour (w); the blend, 0 over and 1 summed (x), whether a mesh normal is laid under the
+ * layers (y), the added mask's layer or -1 (z) and its repeat (w); its intensity (x), the facing
+ * 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;
 }
 
-/* The mask, at the mesh's coordinates, where a model's map is. Under a branch on uniforms. */
-void layeredBegin() {
-  vec4 m = texture(uModelMap, vec3(vUv.xy, 0.0));
-  float n = uLayers[1].y;
-  lMask = vec4(n > 1.5 ? m.r : 0.0, n > 2.5 ? m.g : 0.0, n > 3.5 ? m.b : 0.0, n > 4.5 ? m.a : 0.0);
+float layerRepeat(int i) {
+  return i < 4 ? uLayers[0][i] : uLayers[1].x;
 }
 
-/* Layer i's share of this point: its channel, less every later layer's. */
-float layerShare(int i) {
-  float keep = 1.0;
-  for (int j = 3; j >= 0; j--) {
-    if (j + 1 == i) return lMask[j] * keep;
-    keep *= 1.0 - lMask[j];
+/* Where the layers are laid: the world's horizontal plane under a projection, the mesh's otherwise. */
+vec2 layerPlace() {
+  if (WORLD_UVS && projected()) return planarAt();
+  return vUv.xy;
+}
+
+vec3 layerAt(int 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, layerExtras()));
+  return texture(uModelMap, vec3(vUv.xy, 0.0));
+}
+
+/* Which of layers 1 to 4 a packed layer number names, as a vector of one 1: none for -1. */
+vec4 layerPick(float layer) {
+  return vec4(equal(vec4(layer), vec4(1.0, 2.0, 3.0, 4.0)));
+}
+
+/*
+ * The weights, changed where the material asks and zero past the count, and every share from them.
+ * 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 = 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));
   }
-  return keep;
+  if (uLayers[3].y > 0.5) {
+    float up = normalize(vNormal).y * 0.5 + 0.5;
+    float facing = clamp(uLayers[3].z + uLayers[3].w * up, 0.0, 1.0);
+    m = mix(m, vec4(facing), layerPick(uLayers[3].y));
+  }
+  float n = uLayers[1].y;
+  m *= vec4(n > 1.5 ? 1.0 : 0.0, n > 2.5 ? 1.0 : 0.0, n > 3.5 ? 1.0 : 0.0, n > 4.5 ? 1.0 : 0.0);
+  if (uLayers[2].x > 0.5) {
+    float taken = min(m.x + m.y + m.z + m.w, 1.0);
+    lShare = m * taken;
+    lShareBase = 1.0 - taken;
+    return;
+  }
+  /* Each over everything before it: a layer keeps its weight of what every later one leaves. */
+  float keep = 1.0;
+  lShare.w = m.w * keep;
+  keep *= 1.0 - m.w;
+  lShare.z = m.z * keep;
+  keep *= 1.0 - m.z;
+  lShare.y = m.y * keep;
+  keep *= 1.0 - m.y;
+  lShare.x = m.x * keep;
+  keep *= 1.0 - m.x;
+  lShareBase = keep;
 }
 
-float layerRepeat(int i) {
-  return i < 4 ? uLayers[0][i] : uLayers[1].x;
+float layerShare(int i) {
+  if (i == 0) return lShareBase;
+  return lShare[i - 1];
 }
 
-vec3 layerAt(int i) {
-  return vec3(vUv.xy * layerRepeat(i), float(i));
+/* The vertex colour's part in the albedo: none where it is the mask instead. */
+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;
 }
 
-/* The tangent-space texels blended, each with its z rebuilt where a two-channel map stored none. */
+/* A tangent-space texel off the normal array, its z rebuilt where a two-channel map stored none. */
+vec3 layerNormalTexel(vec3 at) {
+  vec3 t = texture(uNormalMap, at).xyz * 2.0 - 1.0;
+  t.z = t.z > 0.0 ? t.z : sqrt(max(0.0, 1.0 - dot(t.xy, t.xy)));
+  return t;
+}
+
+/* The tangent-space texels blended by the shares. */
 vec3 layeredTexel() {
   vec3 sum = vec3(0.0);
   for (int i = 0; i < 5; i++) {
     if (float(i) >= uLayers[1].y) break;
-    vec3 t = texture(uNormalMap, layerAt(i)).xyz * 2.0 - 1.0;
-    t.z = t.z > 0.0 ? t.z : sqrt(max(0.0, 1.0 - dot(t.xy, t.xy)));
-    sum += t * 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);
 }
 
+/* Whether a normal read at the mesh's own coordinates lies under the layers. */
+bool layeredMeshNormal() {
+  return uLayers[2].y > 0.5;
+}
+
+/* That normal's texel: the normal array's layer past the layers, at the mesh's coordinates. */
+vec3 layeredMeshTexel() {
+  return layerNormalTexel(vec3(vUv.xy, layerExtras()));
+}
+
 /* Whether the emissive map belongs to one layer rather than to the whole surface. */
 bool layeredGlows() {
   return uLayers[1].z > -0.5;