@driftengine/core 4.13.2 → 4.13.3

package/CHANGELOG.json

@@ -1,4 +1,15 @@
 [
+  {
+    "version": "4.13.3",
+    "date": "2026-10-12",
+    "entries": [
+      {
+        "kind": "added",
+        "short": "A material can lay fine grain over its maps, a region at a time: up to sixteen detail normals and occlusions at their own repeats, chosen per texel: `SurfaceMaterial.detail`.",
+        "text": "`SurfaceMaterial.detail` lays a surface's finest grain over its base maps: up to sixteen regions, each a tangent-space detail normal map, and an occlusion, at its own repeat, offset and strengths, and a region map choosing which one each texel wears. A surface's grain, leather, a weave, brushed metal, a face's pores, is a map of a few hundred texels repeated tens of times across it, and baked into the base maps it is lost: a 256-texel detail tiled forty times over a 2048-texel map would want some ten thousand texels a side, so a consumer's characters looked smooth beside the surfaces they were authored with. Each texel reads its own region's detail alone, turned through a frame built on the normal the base maps made, and multiplies its occlusion into the surface's; the reads take explicit gradients, the base coordinates' times the region's repeat, since the region is the pixel's own. **Where the maps are, and why**: the lit stage had no texture binding to spare on either backend, so the detail maps are layers of the array read where a shading model's map is, and a material with a `modelMap` puts its detail layers in that array; the region map is a layer of the material's ORM array, one index a texel in its red, read exactly so a region's edge is sharp, which wants an uncompressed array. A material whose model-map slot holds another array, or that is placed by the world, is drawn without its detail, said once. Sixteen regions are thirty-three vectors: WebGL2 compiles them in only when a material first asks (`SURFACE_DETAIL`) and refuses them, said once, on a part with no room; on WebGPU every material's block grows from 1,024 bytes to 1,536. Measured on an RX 9070 XT (`demo/dev/detail.html`): where a material reads region 0 it draws exactly what one region with no region map draws, on WebGPU and on WebGL2 over Vulkan and over OpenGL; its other regions differ from it by 166,558 pixels; and the backends part by at most one level in a channel."
+      }
+    ]
+  },
   {
     "version": "4.13.2",
     "date": "2026-10-11",

package/README.md

@@ -6,7 +6,7 @@ WebGL2 everywhere else, behind one API, and carries the fixed-step loop, the ren
 input, the scene graph, geometry, text and the whole of `@driftengine/physics`, which it re-exports.
 Everything else is a separate package a game adds when it reaches for it.
 
-**Cost: 924.2 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`,
+**Cost: 929.4 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`,
 which fails the build if the figure drifts by more than 3%.
 
 The manual is at **[driftengine.dev/docs](https://driftengine.dev/docs)**, with an example running

package/dist/index.d.ts

@@ -231,6 +231,8 @@ export { SurfaceTexture } from './render/surfaceTexture.ts';
 export type { SurfaceMaterial, SurfaceTextureOptions } from './render/surfaceTexture.ts';
 export type { SurfaceProjection } from './render/surfaceProjection.ts';
 export type { SurfaceLayers } from './render/surfaceLayers.ts';
+export type { SurfaceDetail, SurfaceDetailRegion } from './render/surfaceDetail.ts';
+export { MAX_DETAIL_REGIONS } from './render/surfaceDetail.ts';
 export type { SurfaceLayerLook } from './render/surfaceLayerLooks.ts';
 export { compressedFormatName, isCompressedSource, levelBytes, uploadsCompressed, } from './render/compressedSource.ts';
 export type { BlockFormat, CompressedTextureFormat, CompressedTextureSource, SurfaceSource, } from './render/compressedSource.ts';

package/dist/index.js

@@ -287,6 +287,7 @@ export { MAX_POINT_LIGHTS, SURFACE_TEXTURE_UNIT } from './render/lightBudget.js'
 /* The width a light buffer can usefully be with `clusteredLights` on; `createPointLightBuffer`. */
 export { MAX_CLUSTERED_LIGHTS } from './render/clusteredLights.js';
 export { SurfaceTexture } from './render/surfaceTexture.js';
+export { MAX_DETAIL_REGIONS } from './render/surfaceDetail.js';
 /*
  * Compressed textures — BC, ETC2 and EAC, ASTC: the source `createSurfaceTexture` takes as blocks,
  * the one question to ask before handing one over — whether this device takes its format

package/dist/render/backend/webgl2/renderer.d.ts

@@ -1300,6 +1300,13 @@ export declare class WebGL2Renderer implements RendererApi {
     /** Whether it has room for the layers' looks beside them, and whether the refusal was said. */
     private looksRoom;
     private warnedLooksRoom;
+    /** `uDetail`, the material's tiled detail packed by `packSurfaceDetail`. */
+    private readonly detailFloats;
+    /** Whether the lit stage has room for detail on this part, asked once. See `detailOfMaterial`. */
+    private detailRoom;
+    private warnedDetailRoom;
+    /** The refusals already said, each once. */
+    private readonly warnedDetail;
     private warnedLayersModelMap;
     private warnedLayersTriplanar;
     private warnedOverlayRoom;
@@ -2199,6 +2206,11 @@ export declare class WebGL2Renderer implements RendererApi {
      * as they are, said once — which on a material sharing its arrays reads the wrong textures, so
      * the sentence names the way out.
      */
+    /**
+     * A material's detail, or null where it is refused: its slot holds another array, it is placed by
+     * the world, or the lit stage has no room for its thirty-three vectors. Each said once.
+     */
+    private detailOfMaterial;
     private looksFit;
     /** Says once that a layered material's triplanar projection is laid on the horizontal plane. */
     private warnLayersTriplanar;

package/dist/render/backend/webgl2/renderer.js

@@ -41,6 +41,7 @@ import { resolveTransmission } from '../../transmission.js';
 import { resolveOcclusionFade } from '../../occlusionFade.js';
 import { orthographicDepthSpan } from '../../lightMatrix.js';
 import { LAYER_FLOATS, layerMaskMap, layeredProjection, layersFitBeside, packSurfaceLayers, } from '../../surfaceLayers.js';
+import { DETAIL_FLOATS, detailOf, detailRefusal, detailRefusalWarning, packSurfaceDetail, } from '../../surfaceDetail.js';
 import { LOOK_FLOATS, asksLayerLooks, packLayerLooks } from '../../surfaceLayerLooks.js';
 import { FILM_FRAG, FILM_VERT } from '../../shaders/film.js';
 import { SceneTarget } from '../../sceneTarget.js';
@@ -976,6 +977,13 @@ export class WebGL2Renderer {
     /** Whether it has room for the layers' looks beside them, and whether the refusal was said. */
     looksRoom = null;
     warnedLooksRoom = false;
+    /** `uDetail`, the material's tiled detail packed by `packSurfaceDetail`. */
+    detailFloats = new Float32Array(DETAIL_FLOATS);
+    /** Whether the lit stage has room for detail on this part, asked once. See `detailOfMaterial`. */
+    detailRoom = null;
+    warnedDetailRoom = false;
+    /** The refusals already said, each once. */
+    warnedDetail = new Set();
     warnedLayersModelMap = false;
     warnedLayersTriplanar = false;
     warnedOverlayRoom = false;
@@ -3307,11 +3315,18 @@ export class WebGL2Renderer {
         const modelMap = material?.modelMap ?? null;
         /* A layered material's mask, where it is a map, goes where a model's would: surfaceLayers.ts. */
         const layers = this.layersOf(material);
-        const boundMap = modelMap ?? layerMaskMap(layers);
+        const taken = modelMap ?? layerMaskMap(layers);
+        /* And its detail's array, where nothing else is read there: surfaceDetail.ts. */
+        const detail = this.detailOfMaterial(material, taken);
+        const boundMap = taken ?? detail?.maps ?? null;
         gl.activeTexture(gl.TEXTURE0 + MODEL_MAP_TEXTURE_UNIT);
         gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.emptyTexture2DArray);
         if (boundMap !== null)
             boundMap.bind(gl, MODEL_MAP_TEXTURE_UNIT);
+        packSurfaceDetail(detail, (material?.orm ?? null) !== null, this.detailFloats);
+        if (detail !== null)
+            this.askLit('SURFACE_DETAIL');
+        gl.uniform4fv(u['uDetail'] ?? null, this.detailFloats);
         packSurfaceLayers(layers, this.layerFloats);
         if (layers !== null)
             this.askLit('LAYERED');
@@ -3598,6 +3613,33 @@ export class WebGL2Renderer {
      * as they are, said once — which on a material sharing its arrays reads the wrong textures, so
      * the sentence names the way out.
      */
+    /**
+     * A material's detail, or null where it is refused: its slot holds another array, it is placed by
+     * the world, or the lit stage has no room for its thirty-three vectors. Each said once.
+     */
+    detailOfMaterial(material, taken) {
+        const detail = detailOf(material);
+        if (detail === null)
+            return null;
+        const refusal = detailRefusal(detail, taken, (material?.projection ?? null) !== null);
+        if (refusal !== null) {
+            if (!this.warnedDetail.has(refusal)) {
+                this.warnedDetail.add(refusal);
+                console.warn(detailRefusalWarning(refusal));
+            }
+            return null;
+        }
+        this.detailRoom ??= this.switchFits('SURFACE_DETAIL');
+        if (this.detailRoom)
+            return detail;
+        if (!this.warnedDetailRoom) {
+            this.warnedDetailRoom = true;
+            console.warn("Renderer: a material's detail is refused on this device. It takes thirty-three fragment " +
+                'uniform vectors the lit shader does not have, so the material is drawn without it. A ' +
+                'lower `maxLights` makes the room, or WebGPU has it.');
+        }
+        return null;
+    }
     looksFit(layers) {
         if (!asksLayerLooks(layers))
             return false;
@@ -5595,6 +5637,7 @@ export class WebGL2Renderer {
             movingSun: asIf.MOVING_SUN ?? this.litOn.MOVING_SUN,
             layered: asIf.LAYERED ?? this.litOn.LAYERED,
             layerLooks: asIf.LAYER_LOOKS ?? this.litOn.LAYER_LOOKS,
+            surfaceDetail: asIf.SURFACE_DETAIL ?? this.litOn.SURFACE_DETAIL,
             maxLights: budget.maxLights,
             maxAreaLights: budget.maxAreaLights,
         });
@@ -7454,9 +7497,10 @@ export class WebGL2Renderer {
         this.projection.fill(0);
         /* Nor light through from behind. See `SurfaceMaterial.diffuseTransmission`. */
         resolveTransmission(null, this.transmission);
-        /* Nor layers: one layer until a material asks for more. */
+        /* Nor layers: one layer until a material asks for more. Nor detail. */
         this.layerFloats.fill(0);
         this.lookFloats.fill(0);
+        this.detailFloats.fill(0);
         this.overlayMaps = null;
         this.overlayTexture = null;
         /* Nor an ambient of its own: the frame's, until a draw asks. See `setAmbientSH`. */
@@ -7601,6 +7645,7 @@ export class WebGL2Renderer {
         gl.uniform4fv(u['uWorldUv'] ?? null, this.projection);
         gl.uniform4fv(u['uLayers'] ?? null, this.layerFloats);
         gl.uniform4fv(u['uLayerLooks'] ?? null, this.lookFloats);
+        gl.uniform4fv(u['uDetail'] ?? null, this.detailFloats);
         /* Neither refracting nor glass, which is every draw that does not say otherwise. See
            `bindSeeThrough` for the four numbers in the one vector. */
         gl.uniform4f(u['uSeeThrough'] ?? null, 0, 0, 0, 0);

package/dist/render/backend/webgpu/renderer.d.ts

@@ -1208,6 +1208,10 @@ export declare class WebGPURenderer implements RendererApi {
      */
     private readonly transmission;
     private warnedLayersModelMap;
+    /** `uDetail`, the material's tiled detail packed by `packSurfaceDetail`. */
+    private readonly detailFloats;
+    /** The detail refusals already said, each once. See `detailOfMaterial`. */
+    private readonly warnedDetail;
     private warnedLayersTriplanar;
     /** Its numbers, `uModelParams`, packed by `packModel`. */
     private readonly modelParams;
@@ -2112,6 +2116,11 @@ export declare class WebGPURenderer implements RendererApi {
      * A material's layers where they can be drawn: none asked, or a model's map in the mask's place,
      * said once, leave one layer.
      */
+    /**
+     * A material's detail, or null where it is refused: its slot holds another array, or it is placed
+     * by the world. Each said once. This backend has room for its vectors wherever it runs.
+     */
+    private detailOfMaterial;
     private layersOf;
     /** Says once that a layered material's triplanar projection is laid on the horizontal plane. */
     private warnLayersTriplanar;

package/dist/render/backend/webgpu/renderer.js

@@ -70,6 +70,7 @@ import { resolveTransmission } from '../../transmission.js';
 import { resolveOcclusionFade } from '../../occlusionFade.js';
 import { orthographicDepthSpan } from '../../lightMatrix.js';
 import { LAYER_FLOATS, layerMaskMap, layeredProjection, layersFitBeside, packSurfaceLayers, } from '../../surfaceLayers.js';
+import { DETAIL_FLOATS, detailOf, detailRefusal, detailRefusalWarning, packSurfaceDetail, } from '../../surfaceDetail.js';
 import { LOOK_FLOATS, asksLayerLooks, packLayerLooks } from '../../surfaceLayerLooks.js';
 import { frameReflectionsRefused, resolveFrameReflections, } from '../../frameReflections.js';
 import { REFLECTION_SURFACE_FORMAT, ReflectionSurfacePass } from './reflectionSurfacePass.js';
@@ -2284,6 +2285,10 @@ export class WebGPURenderer {
      */
     transmission = new Float32Array([-1, -1, -1, 0]);
     warnedLayersModelMap = false;
+    /** `uDetail`, the material's tiled detail packed by `packSurfaceDetail`. */
+    detailFloats = new Float32Array(DETAIL_FLOATS);
+    /** The detail refusals already said, each once. See `detailOfMaterial`. */
+    warnedDetail = new Set();
     warnedLayersTriplanar = false;
     /** Its numbers, `uModelParams`, packed by `packModel`. */
     modelParams = new Float32Array(MODEL_PARAM_FLOATS);
@@ -2688,7 +2693,10 @@ export class WebGPURenderer {
         const ownModelMap = (material?.modelMap ?? null);
         /* A layered material's mask, where it is a map, goes where a model's would: surfaceLayers.ts. */
         const layers = this.layersOf(material);
-        const modelMap = ownModelMap ?? layerMaskMap(layers);
+        const taken = ownModelMap ?? layerMaskMap(layers);
+        /* And its detail's array, where nothing else is read there: surfaceDetail.ts. */
+        const detail = this.detailOfMaterial(material, taken);
+        const modelMap = taken ?? detail?.maps ?? null;
         this.materialModel = material?.model ?? null;
         const reflectivity = material?.reflectivity;
         const environmentGain = material?.environmentGain;
@@ -2772,6 +2780,11 @@ export class WebGPURenderer {
             f.set(this.lookFloats, this.materialField('uLayerLooks'));
             if (asksLayerLooks(layers))
                 this.enableLit('LAYER_LOOKS');
+            /* And its tiled detail, the first time a material lays any: detail.ts. */
+            packSurfaceDetail(detail, orm !== null, this.detailFloats);
+            f.set(this.detailFloats, this.materialField('uDetail'));
+            if (detail !== null)
+                this.enableLit('SURFACE_DETAIL');
             f.set(this.modelParams, this.materialField('uModelParams'));
         });
         /*
@@ -5142,6 +5155,23 @@ export class WebGPURenderer {
      * A material's layers where they can be drawn: none asked, or a model's map in the mask's place,
      * said once, leave one layer.
      */
+    /**
+     * A material's detail, or null where it is refused: its slot holds another array, or it is placed
+     * by the world. Each said once. This backend has room for its vectors wherever it runs.
+     */
+    detailOfMaterial(material, taken) {
+        const detail = detailOf(material);
+        if (detail === null)
+            return null;
+        const refusal = detailRefusal(detail, taken, (material?.projection ?? null) !== null);
+        if (refusal === null)
+            return detail;
+        if (!this.warnedDetail.has(refusal)) {
+            this.warnedDetail.add(refusal);
+            console.warn(detailRefusalWarning(refusal));
+        }
+        return null;
+    }
     layersOf(material) {
         const layers = material?.layers ?? null;
         if (layers === null || layers.repeats.length === 0)
@@ -7312,6 +7342,8 @@ export class WebGPURenderer {
         /* Nor layers: one layer until a material asks for more. */
         f.fill(0, at('uLayers'), at('uLayers') + LAYER_FLOATS);
         f.fill(0, at('uLayerLooks'), at('uLayerLooks') + LOOK_FLOATS);
+        /* Nor detail. */
+        f.fill(0, at('uDetail'), at('uDetail') + DETAIL_FLOATS);
         f[at('uCutout')] = 0;
         f[at('uCutout') + 1] = 0;
         this.cutoutResolveStaged = 'hard';

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

@@ -0,0 +1,21 @@
+/**
+ * A material's tiled detail over whatever its maps made: `SurfaceMaterial.detail`, packed into
+ * `uDetail` by `surfaceDetail.ts`.
+ *
+ * **Each texel wears its own region's detail alone.** The region is read exactly from the ORM
+ * array's layer the material names, at the base coordinates, so an index is never blended with its
+ * neighbour's at a region's edge; then that region's normal map is read at its repeat and offset,
+ * turned through a frame built on the normal the base maps made — the construction a layered
+ * material lays its layers over a mesh normal with — and its occlusion multiplied into the
+ * surface's. A strength scales the detail's slopes as a layer's look does.
+ *
+ * **Read with explicit gradients**, the base coordinates' times the region's repeat, because the
+ * region is the pixel's own: a read whose level is implicit is legal only in uniform control flow
+ * (AGENTS.md 2026-08-07), and across a region's edge the repeated coordinates jump, which would
+ * read a level as coarse as the jump. The frame and the gradients are taken first, under the
+ * uniform branch that calls this.
+ *
+ * **A lit switch, `SURFACE_DETAIL`**, off until a material first asks, declared after `LAYERED` and
+ * `LAYER_LOOKS` so each keeps its id. Compiled out, its thirty-three vectors are not declared.
+ */
+export declare function detailGlsl(on: boolean): string;

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

@@ -0,0 +1,74 @@
+/**
+ * A material's tiled detail over whatever its maps made: `SurfaceMaterial.detail`, packed into
+ * `uDetail` by `surfaceDetail.ts`.
+ *
+ * **Each texel wears its own region's detail alone.** The region is read exactly from the ORM
+ * array's layer the material names, at the base coordinates, so an index is never blended with its
+ * neighbour's at a region's edge; then that region's normal map is read at its repeat and offset,
+ * turned through a frame built on the normal the base maps made — the construction a layered
+ * material lays its layers over a mesh normal with — and its occlusion multiplied into the
+ * surface's. A strength scales the detail's slopes as a layer's look does.
+ *
+ * **Read with explicit gradients**, the base coordinates' times the region's repeat, because the
+ * region is the pixel's own: a read whose level is implicit is legal only in uniform control flow
+ * (AGENTS.md 2026-08-07), and across a region's edge the repeated coordinates jump, which would
+ * read a level as coarse as the jump. The frame and the gradients are taken first, under the
+ * uniform branch that calls this.
+ *
+ * **A lit switch, `SURFACE_DETAIL`**, off until a material first asks, declared after `LAYERED` and
+ * `LAYER_LOOKS` so each keeps its id. Compiled out, its thirty-three vectors are not declared.
+ */
+export function detailGlsl(on) {
+    if (!on) {
+        return /* glsl */ `
+const bool SURFACE_DETAIL = false;  // wgsl:override
+bool detailed() { return false; }
+void surfaceDetail(inout vec3 n, inout float occlusion, vec2 uv) {}
+`;
+    }
+    return /* glsl */ `
+/* Whether this program lays a material's detail. Off but where one has asked: detail.ts. */
+const bool SURFACE_DETAIL = true;  // wgsl:override
+/*
+ * Thirty-three vectors, as surfaceDetail.ts packs them: the region count (x) and the ORM array's
+ * layer holding the region map, or -1 for none (y); then two a region, the normal map's layer (x),
+ * the occlusion's or -1 (y), the normal strength (z) and the occlusion strength (w); its repeats
+ * across and down (x y) and its offset (z w).
+ */
+uniform vec4 uDetail[33]; // wgsl:material
+
+bool detailed() { return uDetail[0].x > 0.0; }
+
+/* The region a texel of the base maps is in, read exactly, held to the regions there are. */
+int detailRegion(vec2 uv) {
+  int last = int(uDetail[0].x) - 1;
+  if (uDetail[0].y < 0.0) return 0;
+  ivec2 size = textureSize(uOrmMap, 0).xy;
+  ivec2 texel = clamp(ivec2(floor(fract(uv) * vec2(size))), ivec2(0), size - 1);
+  int region = int(texelFetch(uOrmMap, ivec3(texel, int(uDetail[0].y)), 0).r * 255.0 + 0.5);
+  return clamp(region, 0, last);
+}
+
+void surfaceDetail(inout vec3 n, inout float occlusion, vec2 uv) {
+  /* In uniform control flow, before anything that depends on the pixel's region. */
+  mat3 frame = tangentFrame(n, vWorldPos, uv, vTangent, vHasTangents);
+  vec2 dx = dFdx(uv);
+  vec2 dy = dFdy(uv);
+  int region = detailRegion(uv);
+  vec4 picks = uDetail[1 + region * 2];
+  vec4 place = uDetail[2 + region * 2];
+  vec2 at = uv * place.xy + place.zw;
+  vec2 gx = dx * place.xy;
+  vec2 gy = dy * place.xy;
+  vec3 d = textureGrad(uModelMap, vec3(at, picks.x), gx, gy).xyz * 2.0 - 1.0;
+  /* z rebuilt where none is stored, as the base map's is: normalMap.ts. */
+  d.z = d.z > 0.0 ? d.z : sqrt(max(0.0, 1.0 - dot(d.xy, d.xy)));
+  d = normalize(vec3(d.xy * picks.z, max(d.z, 1e-4)));
+  n = normalize(frame * d);
+  if (picks.y >= 0.0) {
+    float held = textureGrad(uModelMap, vec3(at, picks.y), gx, gy).r;
+    occlusion *= mix(1.0, held, picks.w);
+  }
+}
+`;
+}

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' | 'LAYER_LOOKS';
+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' | 'SURFACE_DETAIL';
 /** 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

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

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

@@ -145,6 +145,11 @@ export interface FlatShaderOptions {
      * \`uLayerLooks\` and all. True when absent; nothing without \`layered\`. See \`layerLooksGlsl\`.
      */
     readonly layerLooks?: boolean;
+    /**
+     * Whether it lays a material's tiled detail over its maps, \`uDetail\` and all
+     * (\`SurfaceMaterial.detail\`). True when absent. See \`detailGlsl\`.
+     */
+    readonly surfaceDetail?: boolean;
     /**
      * How many point lights this build declares room for. `MAX_POINT_LIGHTS` when absent.
      *

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

@@ -24,6 +24,7 @@ import { overlayGlsl } from './overlay.js';
 import { reflectionSurfaceGlsl } from './reflectionSurface.js';
 import { worldUvGlsl } from './worldUv.js';
 import { movingSunGlsl } from './movingSun.js';
+import { detailGlsl } from './detail.js';
 import { layeredGlsl } from './layered.js';
 import { MAP_READS_GLSL } from './mapReads.js';
 import { CHANNEL_BEND, LIT_CHANNEL_ATTRIBUTE } from '../vertexChannel.js';
@@ -514,6 +515,8 @@ export function flatFrag(options) {
         worldUvGlsl(options.worldUvs ?? true),
         /* After the projection, so its switch takes the next id; the normal map below calls it. */
         layeredGlsl(options.layered ?? true, options.layerLooks ?? true),
+        /* After the layers, so its switch takes the next id; main calls it. See detail.ts. */
+        detailGlsl(options.surfaceDetail ?? 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