@driftengine/core 4.13.2 → 4.13.3

package/dist/render/surfaceDetail.d.ts

@@ -0,0 +1,79 @@
+/**
+ * A material's tiled detail: small normal maps, and occlusion, repeated many times over the base
+ * maps, a region map choosing which one each texel wears. `SurfaceMaterial.detail`, packed into
+ * `uDetail` for `shaders/flat/detail.ts`.
+ *
+ * **What it is for.** A surface's finest grain — leather, a weave, brushed metal, a face's pores —
+ * is a map of a few hundred texels repeated tens of times across it. 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 the base maps carry the shape and a detail map the grain, each garment region
+ * with its own grain at its own repeat, which is how such surfaces are authored.
+ *
+ * **Where the maps are.** The lit stage has 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 (`uModelMap`), and the
+ * region map is a layer of the material's own ORM array, one index a texel in its red. What that
+ * gives up, said where each is refused: a material whose shading model has a map must put its
+ * detail layers in that same array; a layered material whose mask is a map cannot have detail; and
+ * the region map shares the ORM array's size and format, which must keep an index exactly, so an
+ * uncompressed one.
+ *
+ * **Sixteen regions, two vectors each**, behind one vector saying how many and where the region
+ * map is: thirty-three in all, which is why WebGL2 compiles them in only when a material first asks
+ * and refuses them on a part with no room for them.
+ */
+/** Regions a material may name. */
+export declare const MAX_DETAIL_REGIONS = 16;
+/** Floats `uDetail` holds: a header vector, then two vectors a region. */
+export declare const DETAIL_FLOATS: number;
+/** One region's detail. */
+export interface SurfaceDetailRegion {
+    /** The layer of the detail array holding this region's tangent-space normal map. */
+    readonly normalLayer: number;
+    /** The layer holding its occlusion, in red; absent, the region adds none. */
+    readonly occlusionLayer?: number;
+    /** Repeats across the base coordinates, the same both ways or across and down apart. */
+    readonly repeat: number | readonly [number, number];
+    /** Added to the repeated coordinates, so neighbouring regions need not line up. Default none. */
+    readonly offset?: readonly [number, number];
+    /** How far the detail turns the normal: 0 lies flat, 1 as drawn, more steeper. Default 1. */
+    readonly normalStrength?: number;
+    /** How much of its occlusion is laid on, from 0 to 1. Default 1. */
+    readonly occlusionStrength?: number;
+}
+/** A material's tiled detail. */
+export interface SurfaceDetail<Texture> {
+    /**
+     * The array whose layers the regions name, read where a shading model's map is. A material with
+     * a `modelMap` puts its detail layers in that array and names it here too.
+     */
+    readonly maps: Texture;
+    /**
+     * The layer of the material's ORM array holding the region map: in its red, each texel's region
+     * as an index from 0, stored as `index / 255`, read exactly at the base coordinates. Absent, every
+     * texel is region 0, which is a surface with one detail all over: a face's pores.
+     */
+    readonly regionLayer?: number;
+    /** Up to sixteen, by index. A texel naming a region past the last wears the last. */
+    readonly regions: readonly SurfaceDetailRegion[];
+}
+/**
+ * Pack a material's detail into `out`, `DETAIL_FLOATS` long; zeros for none, which the shader reads
+ * as no detail. `hasOrm` says whether the material carries the ORM array a region map is a layer
+ * of; without one every texel is region 0. Allocates nothing.
+ */
+export declare function packSurfaceDetail(detail: SurfaceDetail<unknown> | null, hasOrm: boolean, out: Float32Array): void;
+/** Why a material's detail is drawn without, or null where nothing stands in its way. */
+export type DetailRefusal = 'slot' | 'projection';
+/**
+ * Whether a material's detail can be drawn, given what else wants the slot its maps are read
+ * through: a shading model's own map, or a layered material's mask where it is a map. Either must
+ * be the detail's array itself. And a material placed by the world has no base coordinates for a
+ * region map to be read at, so its detail is refused too.
+ */
+export declare function detailRefusal(detail: SurfaceDetail<unknown>, slotTakenBy: unknown, projected: boolean): DetailRefusal | null;
+/** A material's detail, or null where it names none or no region. */
+export declare function detailOf<Texture>(material: {
+    readonly detail?: SurfaceDetail<Texture> | null;
+} | null): SurfaceDetail<Texture> | null;
+/** The sentence each backend says once when it draws a material without its detail. */
+export declare function detailRefusalWarning(refusal: DetailRefusal): string;

package/dist/render/surfaceDetail.js

@@ -0,0 +1,86 @@
+/**
+ * A material's tiled detail: small normal maps, and occlusion, repeated many times over the base
+ * maps, a region map choosing which one each texel wears. `SurfaceMaterial.detail`, packed into
+ * `uDetail` for `shaders/flat/detail.ts`.
+ *
+ * **What it is for.** A surface's finest grain — leather, a weave, brushed metal, a face's pores —
+ * is a map of a few hundred texels repeated tens of times across it. 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 the base maps carry the shape and a detail map the grain, each garment region
+ * with its own grain at its own repeat, which is how such surfaces are authored.
+ *
+ * **Where the maps are.** The lit stage has 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 (`uModelMap`), and the
+ * region map is a layer of the material's own ORM array, one index a texel in its red. What that
+ * gives up, said where each is refused: a material whose shading model has a map must put its
+ * detail layers in that same array; a layered material whose mask is a map cannot have detail; and
+ * the region map shares the ORM array's size and format, which must keep an index exactly, so an
+ * uncompressed one.
+ *
+ * **Sixteen regions, two vectors each**, behind one vector saying how many and where the region
+ * map is: thirty-three in all, which is why WebGL2 compiles them in only when a material first asks
+ * and refuses them on a part with no room for them.
+ */
+/** Regions a material may name. */
+export const MAX_DETAIL_REGIONS = 16;
+/** Floats `uDetail` holds: a header vector, then two vectors a region. */
+export const DETAIL_FLOATS = 4 + MAX_DETAIL_REGIONS * 8;
+/**
+ * Pack a material's detail into `out`, `DETAIL_FLOATS` long; zeros for none, which the shader reads
+ * as no detail. `hasOrm` says whether the material carries the ORM array a region map is a layer
+ * of; without one every texel is region 0. Allocates nothing.
+ */
+export function packSurfaceDetail(detail, hasOrm, out) {
+    out.fill(0);
+    if (detail === null)
+        return;
+    const count = Math.min(MAX_DETAIL_REGIONS, detail.regions.length);
+    out[0] = count;
+    const regionLayer = detail.regionLayer;
+    out[1] = hasOrm && regionLayer !== undefined ? Math.max(0, Math.floor(regionLayer)) : -1;
+    for (let i = 0; i < count; i++) {
+        const region = detail.regions[i];
+        const at = 4 + i * 8;
+        const repeat = region.repeat;
+        const across = typeof repeat === 'number' ? repeat : repeat[0];
+        const down = typeof repeat === 'number' ? repeat : repeat[1];
+        out[at] = Math.max(0, Math.floor(region.normalLayer));
+        out[at + 1] =
+            region.occlusionLayer === undefined ? -1 : Math.max(0, Math.floor(region.occlusionLayer));
+        out[at + 2] = Math.max(0, region.normalStrength ?? 1);
+        out[at + 3] = Math.min(1, Math.max(0, region.occlusionStrength ?? 1));
+        /* A repeat at or below zero has no grain to show, so it is one rather than a mirror or nothing. */
+        out[at + 4] = across > 0 ? across : 1;
+        out[at + 5] = down > 0 ? down : 1;
+        out[at + 6] = region.offset?.[0] ?? 0;
+        out[at + 7] = region.offset?.[1] ?? 0;
+    }
+}
+/**
+ * Whether a material's detail can be drawn, given what else wants the slot its maps are read
+ * through: a shading model's own map, or a layered material's mask where it is a map. Either must
+ * be the detail's array itself. And a material placed by the world has no base coordinates for a
+ * region map to be read at, so its detail is refused too.
+ */
+export function detailRefusal(detail, slotTakenBy, projected) {
+    if (projected)
+        return 'projection';
+    if (slotTakenBy !== null && slotTakenBy !== undefined && slotTakenBy !== detail.maps) {
+        return 'slot';
+    }
+    return null;
+}
+/** A material's detail, or null where it names none or no region. */
+export function detailOf(material) {
+    const detail = material?.detail ?? null;
+    return detail === null || detail.regions.length === 0 ? null : detail;
+}
+/** The sentence each backend says once when it draws a material without its detail. */
+export function detailRefusalWarning(refusal) {
+    return refusal === 'slot'
+        ? "Renderer: a material's detail is drawn without: its maps are read where a shading model's " +
+            "map goes, and this material binds another array there, its `modelMap` or its layers' " +
+            'mask. Put the detail layers in the `modelMap` array and name that array as `detail.maps`.'
+        : "Renderer: a material's detail is drawn without: it is placed by the world (`projection`), " +
+            'so there are no base coordinates for its regions and repeats to be read at.';
+}

package/dist/render/surfaceTexture.d.ts

@@ -8,6 +8,7 @@
  * array samples exactly as a 2D texture does. A mesh names its layer per vertex (`MeshData.layers`),
  * so a merged block wearing forty facades is one draw.
  */
+import type { SurfaceDetail } from './surfaceDetail.ts';
 import type { SurfaceLayers } from './surfaceLayers.ts';
 import type { SurfaceProjection } from './surfaceProjection.ts';
 import type { SurfaceModel } from './surfaceModel.ts';
@@ -235,6 +236,14 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
      * vertices. See `surfaceLayers.ts` for the rest and what it gives up.
      */
     layers?: SurfaceLayers<Texture> | null;
+    /**
+     * Fine grain tiled over the base maps: up to sixteen regions, each a detail normal map, and an
+     * occlusion, at its own repeat and strength, a region map in the ORM array choosing which one each
+     * texel wears. The detail maps are layers of an array read where `modelMap` goes, so a material
+     * with a shading model's map puts them in that array. **A lit switch**, compiled in the first time
+     * a material asks. See `surfaceDetail.ts` for the rest and what it gives up.
+     */
+    detail?: SurfaceDetail<Texture> | null;
 }
 export interface SurfaceTextureOptions {
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/core",
-  "version": "4.13.2",
+  "version": "4.13.3",
   "description": "The runtime of DriftEngine, a WebGPU game engine with a WebGL2 fallback: renderer, loop, input, cameras, scene graph and physics",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,8 +29,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@driftengine/drft": "4.13.2",
-    "@driftengine/physics": "4.13.2",
+    "@driftengine/drft": "4.13.3",
+    "@driftengine/physics": "4.13.3",
     "gl-matrix": "^3.4.3"
   },
   "author": "Drift Technologies",
@@ -67,8 +67,8 @@
     "prepack": "node ../../scripts/build.mjs @driftengine/core"
   },
   "devDependencies": {
-    "@driftengine/nav": "4.13.2",
-    "@driftengine/network": "4.13.2",
-    "@driftengine/texture": "4.13.2"
+    "@driftengine/nav": "4.13.3",
+    "@driftengine/network": "4.13.3",
+    "@driftengine/texture": "4.13.3"
   }
 }

package/src/index.ts

@@ -677,6 +677,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';
 /*
  * Compressed textures — BC, ETC2 and EAC, ASTC: the source `createSurfaceTexture` takes as blocks,

package/src/render/backend/webgl2/renderer.ts

@@ -117,6 +117,15 @@ import {
   packSurfaceLayers,
 } from '../../surfaceLayers.ts';
 import type { SurfaceLayers } from '../../surfaceLayers.ts';
+import {
+  DETAIL_FLOATS,
+  detailOf,
+  detailRefusal,
+  detailRefusalWarning,
+  packSurfaceDetail,
+  type DetailRefusal,
+  type SurfaceDetail,
+} from '../../surfaceDetail.ts';
 import { LOOK_FLOATS, asksLayerLooks, packLayerLooks } from '../../surfaceLayerLooks.ts';
 import type { SurfaceProjection } from '../../surfaceProjection.ts';
 import { FILM_FRAG, FILM_VERT } from '../../shaders/film.ts';
@@ -1801,6 +1810,13 @@ export class WebGL2Renderer implements RendererApi {
   /** Whether it has room for the layers' looks beside them, and whether the refusal was said. */
   private looksRoom: boolean | null = null;
   private warnedLooksRoom = false;
+  /** `uDetail`, the material's tiled detail packed by `packSurfaceDetail`. */
+  private readonly detailFloats = new Float32Array(DETAIL_FLOATS);
+  /** Whether the lit stage has room for detail on this part, asked once. See `detailOfMaterial`. */
+  private detailRoom: boolean | null = null;
+  private warnedDetailRoom = false;
+  /** The refusals already said, each once. */
+  private readonly warnedDetail = new Set<DetailRefusal>();
   private warnedLayersModelMap = false;
   private warnedLayersTriplanar = false;
   private warnedOverlayRoom = false;
@@ -4462,10 +4478,16 @@ export class WebGL2Renderer implements RendererApi {
     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');
     gl.uniform4fv(u['uLayers'] ?? null, this.layerFloats);
@@ -4771,6 +4793,37 @@ export 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(
+    material: SurfaceMaterial | null,
+    taken: SurfaceTexture | null,
+  ): SurfaceDetail<SurfaceTexture> | null {
+    const detail = detailOf(material) as SurfaceDetail<SurfaceTexture> | null;
+    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;
+  }
+
   private looksFit(layers: SurfaceLayers<SurfaceTexture> | null): boolean {
     if (!asksLayerLooks(layers)) return false;
     this.looksRoom ??= this.switchFits('LAYER_LOOKS', 'LAYERED');
@@ -7121,6 +7174,7 @@ export class WebGL2Renderer implements RendererApi {
       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,
     });
@@ -9287,9 +9341,10 @@ export class WebGL2Renderer implements RendererApi {
     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`. */
@@ -9465,6 +9520,7 @@ export class WebGL2Renderer implements RendererApi {
     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/src/render/backend/webgpu/renderer.ts

@@ -216,6 +216,15 @@ import {
   packSurfaceLayers,
 } from '../../surfaceLayers.ts';
 import type { SurfaceLayers } from '../../surfaceLayers.ts';
+import {
+  DETAIL_FLOATS,
+  detailOf,
+  detailRefusal,
+  detailRefusalWarning,
+  packSurfaceDetail,
+  type DetailRefusal,
+  type SurfaceDetail,
+} from '../../surfaceDetail.ts';
 import { LOOK_FLOATS, asksLayerLooks, packLayerLooks } from '../../surfaceLayerLooks.ts';
 import {
   frameReflectionsRefused,
@@ -3038,6 +3047,10 @@ export class WebGPURenderer implements RendererApi {
    */
   private readonly transmission = new Float32Array([-1, -1, -1, 0]);
   private warnedLayersModelMap = false;
+  /** `uDetail`, the material's tiled detail packed by `packSurfaceDetail`. */
+  private readonly detailFloats = new Float32Array(DETAIL_FLOATS);
+  /** The detail refusals already said, each once. See `detailOfMaterial`. */
+  private readonly warnedDetail = new Set<DetailRefusal>();
   private warnedLayersTriplanar = false;
   /** Its numbers, `uModelParams`, packed by `packModel`. */
   private readonly modelParams = new Float32Array(MODEL_PARAM_FLOATS);
@@ -3516,7 +3529,10 @@ export class WebGPURenderer implements RendererApi {
     const ownModelMap = (material?.modelMap ?? null) as GpuSurfaceTexture | 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;
@@ -3609,6 +3625,10 @@ export class WebGPURenderer implements RendererApi {
       packLayerLooks(layers, this.lookFloats);
       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'));
     });
     /*
@@ -6395,6 +6415,25 @@ export 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(
+    material: SurfaceMaterial<GpuSurfaceTexture> | null,
+    taken: GpuSurfaceTexture | null,
+  ): SurfaceDetail<GpuSurfaceTexture> | null {
+    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;
+  }
+
   private layersOf(
     material: SurfaceMaterial<GpuSurfaceTexture> | null,
   ): SurfaceLayers<GpuSurfaceTexture> | null {
@@ -9110,6 +9149,8 @@ export class WebGPURenderer implements RendererApi {
     /* 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/src/render/shaders/flat/detail.ts

@@ -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: boolean): string {
+  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/src/render/shaders/flat/glassTint.ts

@@ -40,7 +40,8 @@ export type LitSwitch =
   | 'WORLD_UVS'
   | 'MOVING_SUN'
   | 'LAYERED'
-  | 'LAYER_LOOKS';
+  | 'LAYER_LOOKS'
+  | 'SURFACE_DETAIL';
 
 /** Every switch off: what a renderer starts from before its profile and its content say otherwise. */
 export function noLitSwitches(): Record<LitSwitch, boolean> {
@@ -57,6 +58,7 @@ export function noLitSwitches(): Record<LitSwitch, boolean> {
     MOVING_SUN: false,
     LAYERED: false,
     LAYER_LOOKS: false,
+    SURFACE_DETAIL: false,
   };
 }
 

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

@@ -24,6 +24,7 @@ import { overlayGlsl } from './overlay.ts';
 import { reflectionSurfaceGlsl } from './reflectionSurface.ts';
 import { worldUvGlsl } from './worldUv.ts';
 import { movingSunGlsl } from './movingSun.ts';
+import { detailGlsl } from './detail.ts';
 import { layeredGlsl } from './layered.ts';
 import { MAP_READS_GLSL } from './mapReads.ts';
 import { CHANNEL_BEND, LIT_CHANNEL_ATTRIBUTE } from '../vertexChannel.ts';
@@ -539,6 +540,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.
    *
@@ -692,6 +698,8 @@ export function flatFrag(options: FlatShaderOptions): string {
       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

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

@@ -227,6 +227,8 @@ export const MAIN_GLSL = `void main() {
     if (uNormalStrength > 0.0) n = normalMapped(n, surfaceAt, frameAt, frameTangents);
     /* A draw's wrinkles, by region, over whatever the map made: overlay.ts. */
     if (SURFACE_OVERLAY) n = overlayWrinkle(n, unmapped, surfaceAt.xy);
+    /* The material's tiled detail over whatever the maps made, and its occlusion: detail.ts. */
+    if (SURFACE_DETAIL && detailed()) surfaceDetail(n, ormOcclusion, surfaceAt.xy);
 
     /*
      * Microscopic relief: the surface's own texture, as a turn of the normal rather than a change