@driftengine/core 4.8.5 → 4.8.7

package/src/render/instances.ts

@@ -10,10 +10,11 @@
  * plant. This one carries a full transform, because a vehicle pitches and rolls on its suspension
  * and a yaw cannot say so.
  *
- * **What it gives up** is a matrix per instance where a scatter spends five floats: 76 bytes
+ * **What it gives up** is a matrix per instance where a scatter spends five floats: 80 bytes
  * against 44, and no wind. **What would make it wrong** is a caller wanting per-instance
- * anything else — an opacity, a morph weight — which wants another attribute, and the sixteen
- * WebGL2 guarantees are already spent.
+ * anything beyond an opacity and a texture cell — a morph weight, say — which wants another
+ * attribute, and the sixteen WebGL2 guarantees are already spent. The opacity rides the float the
+ * stride was padded with and the cell the matrix's bottom row, which is why neither costs a byte.
  */
 export interface MeshInstances {
   /**
@@ -30,6 +31,40 @@ export interface MeshInstances {
    * — the alternative is a second batch per colour, which is the thing this exists to avoid.
    */
   readonly tints: Float32Array;
+  /**
+   * One float each, the instance's opacity from 0 to 1, which a blended draw
+   * (`drawTranslucentInstanced`) multiplies into the batch's own. **Absent, or an instance past its
+   * end, is 1** — wholly opaque, which is what every instance was before 4.8.6.
+   *
+   * What lets one draw carry particles fading at different rates: without it a consumer drew a
+   * batch per opacity level, each a draw and a material of its own. It is the instance's twin of
+   * the per-vertex alpha lane (`MeshData.channel`), multiplied in where that lane is.
+   */
+  readonly alphas?: Float32Array;
+  /**
+   * Four floats each, the instance's region of its lightmap page: `[scaleU, scaleV, biasU, biasV]`,
+   * read by a draw whose material is a `lightmapModel` — instances of one mesh in one material sit
+   * in different regions of one page, each applied before the material's own region. **They ride
+   * the tint and the opacity**, which a lightmapped instance gives up (see `lightmap.ts`): where
+   * these are given, those are not read. **A lightmapped batch needs them**, since a bake is
+   * different light at each instance; one drawn without them reads its tints as its regions, and
+   * either mismatch is said once on the console.
+   */
+  readonly lightmapRegions?: Float32Array;
+  /**
+   * Four floats each, the instance's cell of its texture: `[scaleU, scaleV, offsetU, offsetV]`,
+   * applied to the mesh's coordinates before the material's own scale and offset, in every pass
+   * that reads them — so one draw carries particles in different cells of a flipbook, or props
+   * wearing different tiles of one atlas. **Absent, or past `count`, is the whole texture**,
+   * `[1, 1, 0, 0]`, which is what every instance read before 4.8.7.
+   *
+   * **It rides the matrix's bottom row**, which an instance's placement — a turn, a scale and a
+   * move — leaves at `[0, 0, 0, 1]`, and which every stage drawing an instance rebuilds as that.
+   * So a placement must be affine, as every placement of a solid object is; a projective one is
+   * drawn as its affine part. A culled batch (`cullInstances`) carries the cells only into a
+   * target that has the array.
+   */
+  readonly uvRegions?: Float32Array;
   /** How many instances the arrays hold. Fixed at creation; the buffers are sized from it. */
   readonly capacity: number;
   /** How many are live. The rest of the buffer is neither uploaded nor drawn. */
@@ -47,20 +82,22 @@ export function createMeshInstances(capacity: number): MeshInstances {
   return {
     models: new Float32Array(capacity * 16),
     tints: new Float32Array(capacity * 3),
+    alphas: new Float32Array(capacity).fill(1),
     capacity,
     count: 0,
   };
 }
 
 /**
- * Floats one instance occupies in the interleaved vertex buffer: sixteen of matrix, three of
- * tint, and one of padding.
+ * Floats one instance occupies in the interleaved vertex buffer: sixteen of matrix, the bottom row
+ * of which carries the texture cell, three of tint, and the opacity.
  *
- * **Padded to twenty so the stride is 80 bytes rather than 76.** A vertex buffer's stride must be
- * a multiple of four on both backends, which 76 already is — the padding is for the *attribute*
- * offsets: the tint sits at byte 64 and a three-float attribute ending at 76 leaves the next
- * instance's first column starting there, which is legal but puts every second instance on an
- * offset no driver aligns well. One wasted float an instance is 4 bytes against 76.
+ * **Twenty so the stride is 80 bytes rather than 76.** A vertex buffer's stride must be a multiple
+ * of four on both backends, which 76 already is — the twentieth float was padding for the
+ * *attribute* offsets: the tint sits at byte 64 and a three-float attribute ending at 76 leaves the
+ * next instance's first column starting there, which is legal but puts every second instance on an
+ * offset no driver aligns well. Since 4.8.6 it carries the instance's opacity, read with the tint
+ * as one four-float attribute, so the opacity cost no attribute and no byte.
  */
 export const INSTANCE_FLOATS = 20;
 
@@ -68,7 +105,7 @@ export const INSTANCE_FLOATS = 20;
 export const INSTANCE_STRIDE = INSTANCE_FLOATS * 4;
 
 /**
- * Interleave `count` instances into `out`, matrix then tint, at `INSTANCE_FLOATS` apart.
+ * Interleave `count` instances into `out`, matrix, tint and opacity, at `INSTANCE_FLOATS` apart.
  *
  * **Interleaved rather than two buffers** so a batch's upload is one `writeBuffer` and an
  * instance's colour sits beside the matrix that places it. Shared by both backends, because
@@ -78,16 +115,28 @@ export const INSTANCE_STRIDE = INSTANCE_FLOATS * 4;
  * Writes nothing beyond `count`, and allocates nothing: `out` is the caller's staging array.
  */
 export function packInstances(instances: MeshInstances, out: Float32Array): void {
-  const { models, tints } = instances;
+  const { models, tints, alphas, lightmapRegions, uvRegions } = instances;
   const count = Math.min(instances.count, instances.capacity);
   for (let i = 0; i < count; i += 1) {
     const at = i * INSTANCE_FLOATS;
     const m = i * 16;
     for (let c = 0; c < 16; c += 1) out[at + c] = models[m + c] as number;
+    /* The texture cell in the bottom row an affine placement leaves free. See `uvRegions`. */
+    const cell = i * 4;
+    out[at + 3] = uvRegions?.[cell] ?? 1;
+    out[at + 7] = uvRegions?.[cell + 1] ?? 1;
+    out[at + 11] = uvRegions?.[cell + 2] ?? 0;
+    out[at + 15] = uvRegions?.[cell + 3] ?? 0;
+    if (lightmapRegions !== undefined) {
+      /* The region in the tint's and the opacity's place. See `lightmapRegions`. */
+      for (let c = 0; c < 4; c += 1) out[at + 16 + c] = lightmapRegions[i * 4 + c] as number;
+      continue;
+    }
     const t = i * 3;
     out[at + 16] = tints[t] as number;
     out[at + 17] = tints[t + 1] as number;
     out[at + 18] = tints[t + 2] as number;
+    out[at + 19] = alphas?.[i] ?? 1;
   }
 }
 

package/src/render/lightBudget.ts

@@ -1,4 +1,5 @@
 /** Fixed point-light budget shared by CPU selection and the flat shader. */
+import { MAX_AREA_LIGHTS, packAreaSizesAndDoors } from './areaLights.ts';
 import type { AreaLightBuffer } from './areaLights.ts';
 import type { ResolvedAreaShadows } from './areaShadowSet.ts';
 import {
@@ -6,6 +7,8 @@ import {
   POINT_LIGHT_COS_OUTER,
   lampSourceRadius,
   lampWeight,
+  lightChannelsOf,
+  lightFalloffExponentOf,
 } from './clusteredLights.ts';
 
 /**
@@ -256,12 +259,22 @@ export const CLOTH_REST_TEXTURE_UNIT = CLOTH_PARTICLES_TEXTURE_UNIT + 1;
 export const MODEL_MAP_TEXTURE_UNIT = CLOTH_REST_TEXTURE_UNIT + 1;
 
 /**
- * The two units skin's screen-space blur reads on WebGL2 — its target and the frame's depth — past
+ * The units skin's screen-space blur reads on WebGL2 — its target and the frame's depth — past
  * every unit a lit program binds, so spreading skin in the middle of a frame unbinds nothing the
  * draws after it sample. WebGL2 guarantees thirty-two.
  */
 export const SKIN_BLUR_TEXTURE_UNIT = MODEL_MAP_TEXTURE_UNIT + 1;
 export const SKIN_BLUR_DEPTH_UNIT = SKIN_BLUR_TEXTURE_UNIT + 1;
+/** And the skin's colour, which the blur's second axis multiplies the spread light by. */
+export const SKIN_BLUR_ALBEDO_UNIT = SKIN_BLUR_DEPTH_UNIT + 1;
+
+/**
+ * A sprite particle's image and the frame's depth copy its soft edge reads, on WebGL2: past every
+ * unit a lit program binds, for the skin blur's reason — a particle is drawn in the middle of a
+ * frame, and the draws after it must find their textures where they left them.
+ */
+export const PARTICLE_SPRITE_UNIT = SKIN_BLUR_ALBEDO_UNIT + 1;
+export const PARTICLE_DEPTH_UNIT = PARTICLE_SPRITE_UNIT + 1;
 
 /**
  * A cookie's tile, in texels a side.
@@ -380,11 +393,30 @@ export interface PointLightSet {
    * drawn for one spot works in another with a different angle.
    */
   readonly lightCookies?: Float32Array;
+  /**
+   * One per light: the lighting channels it lights, as a bitmask in a float — 1, 2, 3 … 255.
+   * **Absent, or a short array, is channel 1 for every light**, which is every surface's default
+   * too, so a scene that never names a channel lights everything with everything as it did.
+   *
+   * A light shades a surface only where its mask and the surface's `SurfaceMaterial.lightChannels`
+   * share a bit. What it is for: a rig of lights that belongs to some draws and not others — a
+   * character's own key and rim lights, which the floor around the character must not take.
+   */
+  readonly lightChannels?: Float32Array;
+  /**
+   * One per light: its own falloff exponent, `(1 - (d/R)^2)^n` with no distance term, or 0 for the
+   * frame's falloff. **Absent, or a short array, is 0 for every light**, so a scene that names none
+   * falls off as it did. See `PointLightSource.falloffExponent`.
+   */
+  readonly lightFalloffExponents?: Float32Array;
 }
 
 /** Weights are optional per consumer; a short array means every light is fully present. */
 const FULLY_PRESENT: Float32Array = new Float32Array(MAX_POINT_LIGHTS).fill(1);
 
+/** The fixed arm's rectangles as `uAreaLightSize` holds them; refilled per bind, allocated once. */
+const AREA_SIZES_AND_DOORS = new Float32Array(MAX_AREA_LIGHTS * 4);
+
 /** No size at all, which is the behaviour every scene had before a light could have one. */
 const POINT_SOURCES: Float32Array = new Float32Array(MAX_POINT_LIGHTS);
 /**
@@ -483,9 +515,11 @@ export function bindPointLights(
    * every lamp switched off.
    */
   gl.uniform3fv(uniforms['uLightDir[0]'] ?? null, r.directions);
-  gl.uniform2fv(uniforms['uLightCone[0]'] ?? null, r.coneCos);
+  /* The cone and, in z, the light's own falloff exponent. See `conesAndFalloffs`. */
+  gl.uniform4fv(uniforms['uLightCone[0]'] ?? null, r.conesAndFalloffs);
   gl.uniform1fv(uniforms['uLightIesProfile[0]'] ?? null, r.iesProfiles);
-  gl.uniform3fv(uniforms['uLightIesAxis[0]'] ?? null, r.iesAxes);
+  /* The azimuth and, in w, the channels. See `axesAndChannels`. */
+  gl.uniform4fv(uniforms['uLightIesAxis[0]'] ?? null, r.axesAndChannels);
   gl.uniform1fv(uniforms['uLightCookie[0]'] ?? null, r.cookies);
 }
 
@@ -513,7 +547,9 @@ export function bindAreaLights(
   gl.uniform3fv(uniforms['uAreaLightColor[0]'] ?? null, lights.colors);
   gl.uniform3fv(uniforms['uAreaLightRight[0]'] ?? null, lights.right);
   gl.uniform3fv(uniforms['uAreaLightUp[0]'] ?? null, lights.up);
-  gl.uniform2fv(uniforms['uAreaLightSize[0]'] ?? null, lights.sizes);
+  /* The half extents and, in zw, the barn doors. See `packAreaSizesAndDoors`. */
+  packAreaSizesAndDoors(lights, AREA_SIZES_AND_DOORS);
+  gl.uniform4fv(uniforms['uAreaLightSize[0]'] ?? null, AREA_SIZES_AND_DOORS);
   gl.uniform1fv(uniforms['uAreaLightTwoSided[0]'] ?? null, lights.twoSided);
 }
 
@@ -561,6 +597,18 @@ export interface ResolvedPointLights {
   iesProfiles: Float32Array;
   iesAxes: Float32Array;
   cookies: Float32Array;
+  /**
+   * Owned, four a light: the photometric azimuth in xyz and the light's channels in w, which is how
+   * `uLightIesAxis` carries them — the channels in a lane the axis left, rather than in a uniform
+   * array of their own, which would cost a row a light of a budget that has none to give.
+   */
+  readonly axesAndChannels: Float32Array;
+  /**
+   * Owned, four a light: the cone's two cosines, then the light's own falloff exponent, as
+   * `uLightCone` carries them — a `vec2` array costs a whole row a light on WebGL2 anyway, so the
+   * exponent rides the half it left rather than a row of its own.
+   */
+  readonly conesAndFalloffs: Float32Array;
   /**
    * Owned, `MAX_POINT_LIGHTS` long: the emitter sizes and weights as the froxel record carries
    * them, at half precision. `sourceRadii` and `weights` point here once a light set resolves, so
@@ -585,6 +633,8 @@ const glLights: ResolvedPointLights = {
   iesProfiles: NO_PROFILES,
   iesAxes: NO_IES_AXES,
   cookies: NO_COOKIES,
+  axesAndChannels: new Float32Array(MAX_POINT_LIGHTS * 4),
+  conesAndFalloffs: new Float32Array(MAX_POINT_LIGHTS * 4),
   heldSourceRadii: new Float32Array(MAX_POINT_LIGHTS),
   heldWeights: new Float32Array(MAX_POINT_LIGHTS),
 };
@@ -619,6 +669,8 @@ export function resolvePointLights(
     out.iesProfiles = NO_PROFILES;
     out.iesAxes = NO_IES_AXES;
     out.cookies = NO_COOKIES;
+    packAxesAndChannels(NO_IES_AXES, undefined, out.axesAndChannels);
+    packConesAndFalloffs(OPEN_CONES, undefined, out.conesAndFalloffs);
     return out;
   }
   /*
@@ -711,5 +763,37 @@ export function resolvePointLights(
   out.iesProfiles = iesProfiles;
   out.iesAxes = iesAxes;
   out.cookies = cookies;
+  packAxesAndChannels(iesAxes, lights.lightChannels, out.axesAndChannels);
+  packConesAndFalloffs(coneCos, lights.lightFalloffExponents, out.conesAndFalloffs);
   return out;
 }
+
+/** The cone and the falloff exponent, four a light, as `uLightCone` holds them. */
+function packConesAndFalloffs(
+  cones: Float32Array,
+  exponents: Float32Array | undefined,
+  out: Float32Array,
+): void {
+  const named = (exponents?.length ?? 0) >= MAX_POINT_LIGHTS ? exponents : undefined;
+  for (let light = 0; light < MAX_POINT_LIGHTS; light++) {
+    out[light * 4] = cones[light * 2] ?? POINT_LIGHT_COS_INNER;
+    out[light * 4 + 1] = cones[light * 2 + 1] ?? POINT_LIGHT_COS_OUTER;
+    out[light * 4 + 2] = lightFalloffExponentOf(named?.[light]);
+    out[light * 4 + 3] = 0;
+  }
+}
+
+/** The azimuth and the channels, four a light, as `uLightIesAxis` holds them. */
+function packAxesAndChannels(
+  axes: Float32Array,
+  channels: Float32Array | undefined,
+  out: Float32Array,
+): void {
+  const named = (channels?.length ?? 0) >= MAX_POINT_LIGHTS ? channels : undefined;
+  for (let light = 0; light < MAX_POINT_LIGHTS; light++) {
+    out[light * 4] = axes[light * 3] ?? 0;
+    out[light * 4 + 1] = axes[light * 3 + 1] ?? 0;
+    out[light * 4 + 2] = axes[light * 3 + 2] ?? 0;
+    out[light * 4 + 3] = lightChannelsOf(named?.[light]);
+  }
+}

package/src/render/lightmap.ts

@@ -0,0 +1,243 @@
+/**
+ * A baked lightmap: what a consumer hands over, how both backends lay it out, and what a surface
+ * reads from it — the backend-neutral half of `createLightmap` and `lightmapModel`, by the
+ * 2026-08-13 rule.
+ *
+ * **What it is for.** A stage built in another engine carries its static light baked: the bounce
+ * off its walls, the soft occlusion in its corners, most of the colour a reference render shows.
+ * The dynamic lights alone leave everything they do not reach flat. A consumer decodes the bake
+ * into pages — one irradiance image and one direction image each — and every lightmapped surface
+ * reads its own region of its page, at its second texture coordinates scaled and offset into it.
+ *
+ * **What a surface adds**, for its shading normal `n` (the normal map's, where it has one):
+ *
+ *     d     = direction * 2 - 1
+ *     light = irradiance(uv) * max(0, dot(d.xyz, n) + d.w)
+ *     diffuse += albedo * (1 - metal) * light
+ *
+ * Unreal's high-quality lightmap read, `GetLightMapColorHQ`, once its own vectors have decoded the
+ * page — the first-order spherical harmonic its direction carries, in this engine's axes. **Added
+ * to what the dynamic lights give**, and to the ambient: a consumer whose bake already holds the
+ * sky's light zeroes the ambient for those draws itself, with `setAmbientSH` and nine zeros.
+ *
+ * **A shading model, because everything it would otherwise take is spent.** The page binds where a
+ * model's map does and the region is the model's numbers (`lightmapModel`), so a lightmapped
+ * material is a pipeline constant of its own and nothing else pays for it; the surface is otherwise
+ * the standard model, unchanged. The second coordinates ride the grain and relief attributes
+ * (`MeshData.lightmapUvs`, stored below zero by `withLightmapUvs`), and an instance's region rides
+ * its tint and opacity (`MeshInstances.lightmapRegions`). **What it gives up**: a lightmapped
+ * surface has no procedural grain or relief, no other shading model, and an instanced batch with
+ * regions no tint. **What it does not do**: the GPU-driven pipeline and splats read no page.
+ */
+import type { MeshData } from '@driftengine/drft';
+import { packRgb9e5 } from './rgb9e5.ts';
+
+/** One page as a consumer decoded it. */
+export interface LightmapPage {
+  readonly width: number;
+  readonly height: number;
+  /**
+   * Linear irradiance, row-major from the top, in the same units every other light here is in — a
+   * bake from another engine scaled by that engine's exposure, as its lights are. Either three
+   * floats a texel, or one word a texel already packed as rgb9e5 (`rgb9e5.ts`), which is how such a
+   * bake usually arrives and which uploads with no conversion at all.
+   */
+  readonly irradiance: Float32Array | Uint32Array;
+  /**
+   * The direction the light arrives from, four bytes a texel: a first-order spherical harmonic in
+   * this engine's world axes, each value stored as `v * 0.5 + 0.5` — xyz the axis, w the constant.
+   */
+  readonly direction: Uint8Array;
+}
+
+/** Layers a page is uploaded as: the irradiance, then the direction. */
+export const LIGHTMAP_LAYERS = 2;
+
+/**
+ * Where a surface's region of its page is: `lightmapUv = uv2 * scale + bias`, as
+ * `[scaleU, scaleV, biasU, biasV]`. The whole page is the identity.
+ */
+export type LightmapRegion = readonly [number, number, number, number];
+
+/** The whole page. */
+export const WHOLE_PAGE: LightmapRegion = [1, 1, 0, 0];
+
+/**
+ * A page as both backends upload it: two layers of four bytes a texel, row-major from the top. The
+ * first is the irradiance's rgb9e5 word, byte by byte from its lowest; the second is the direction.
+ *
+ * **Eight bytes a texel, and the shader filters it.** Half floats were sixteen: a stage of 49 pages
+ * and 21.8 million texels held 348 MB, where this holds 174. The price is that the irradiance cannot
+ * be filtered as it is stored — a bilinear blend of two words with different exponents is not the
+ * blend of the colours they hold — so the lit stage fetches a texel's four neighbours, decodes each
+ * and blends the colours (`modelBaked` in `shaders/flat/models.ts`): four fetches a layer where one
+ * filtered sample was, on lightmapped surfaces alone. **What would make it wrong** is every device
+ * a page reaches sampling `rgb9e5ufloat`, which WebGL2 does as `RGB9_E5` too; it would then be a
+ * texture of its own, filtered by the device, and a binding the lit stage has no room for.
+ */
+export interface LightmapTexels {
+  readonly kind: 'lightmap-texels';
+  readonly width: number;
+  readonly height: number;
+  /** Each layer's bytes, in layer order: the irradiance, then the direction. */
+  readonly layers: readonly Uint8Array[];
+}
+
+/** Whether a surface texture's source is a page's texels rather than an image or blocks. */
+export function isLightmapTexels(source: unknown): source is LightmapTexels {
+  return (
+    typeof source === 'object' &&
+    source !== null &&
+    (source as { kind?: unknown }).kind === 'lightmap-texels'
+  );
+}
+
+/**
+ * A page as both backends upload it (see `LightmapTexels`). Refuses a page whose arrays are not its
+ * size, naming the one that is short. Packed irradiance is read where it lies, with no copy; float
+ * irradiance is packed once, here.
+ */
+export function lightmapTexels(page: LightmapPage): LightmapTexels {
+  const { width, height } = page;
+  if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1) {
+    throw new Error(`createLightmap: a ${width} by ${height} page has nothing in it`);
+  }
+  const texels = width * height;
+  const irradiance = page.irradiance;
+  const packed = irradiance instanceof Uint32Array;
+  const wanted = packed ? texels : texels * 3;
+  if (irradiance.length !== wanted) {
+    throw new Error(
+      `createLightmap: ${irradiance.length} irradiance ${packed ? 'words' : 'floats'} for a ` +
+        `${width} by ${height} page, which wants ${wanted}: ` +
+        (packed ? 'one rgb9e5 word a texel' : 'three a texel'),
+    );
+  }
+  if (page.direction.length !== texels * 4) {
+    throw new Error(
+      `createLightmap: ${page.direction.length} direction bytes for a ${width} by ${height} ` +
+        `page, which wants ${texels * 4}: four a texel`,
+    );
+  }
+  let words: Uint32Array;
+  if (packed) {
+    words = irradiance;
+  } else {
+    words = new Uint32Array(texels);
+    for (let t = 0; t < texels; t++) {
+      words[t] = packRgb9e5(
+        irradiance[t * 3] as number,
+        irradiance[t * 3 + 1] as number,
+        irradiance[t * 3 + 2] as number,
+      );
+    }
+  }
+  return {
+    kind: 'lightmap-texels',
+    width,
+    height,
+    layers: [littleEndianBytes(words), page.direction],
+  };
+}
+
+/** Whether this platform lays a word out lowest byte first, which the shader's decode assumes. */
+const LITTLE_ENDIAN = new Uint8Array(new Uint32Array([1]).buffer)[0] === 1;
+
+/**
+ * A page's words as bytes, lowest first: a view of the same memory on every little-endian platform,
+ * which is every one a browser runs on, and a reordered copy anywhere else.
+ */
+function littleEndianBytes(words: Uint32Array): Uint8Array {
+  const bytes = new Uint8Array(words.buffer, words.byteOffset, words.length * 4);
+  if (LITTLE_ENDIAN) return bytes;
+  const swapped = new Uint8Array(bytes.length);
+  for (let i = 0; i < bytes.length; i += 4) {
+    swapped[i] = bytes[i + 3] as number;
+    swapped[i + 1] = bytes[i + 2] as number;
+    swapped[i + 2] = bytes[i + 1] as number;
+    swapped[i + 3] = bytes[i] as number;
+  }
+  return swapped;
+}
+
+/**
+ * A mesh with its second coordinates moved onto the grain and relief streams they ride, or the
+ * mesh itself where it has none. Called by both backends' `createMesh`, before anything records
+ * which streams the mesh has.
+ *
+ * **Stored as `-1 - uv`, below zero, and that is what keeps the lanes safe to share.** Grain takes
+ * effect only above zero and relief is read through `max(relief, 0)`, so the same mesh drawn by a
+ * material that is not lightmapped is a mesh with no grain and no relief — rather than one mottled
+ * and bumped by its own coordinates, which is what storing them as they are drew. **What it gives
+ * up** is coordinates at or below −1, which read as nothing; a page's coordinates are from 0 to 1.
+ */
+export function withLightmapUvs(data: MeshData): MeshData {
+  const uvs = data.lightmapUvs;
+  if (uvs === undefined) return data;
+  const vertices = uvs.length / 2;
+  const grain = new Float32Array(vertices);
+  const relief = new Float32Array(vertices);
+  for (let v = 0; v < vertices; v++) {
+    grain[v] = -1 - (uvs[v * 2] as number);
+    relief[v] = -1 - (uvs[v * 2 + 1] as number);
+  }
+  return { ...data, grain, relief, lightmapUvs: undefined };
+}
+
+/** A material's region, checked: four finite numbers, the whole page where none was named. */
+export function lightmapRegionOf(region: LightmapRegion | undefined): LightmapRegion {
+  if (region === undefined) return WHOLE_PAGE;
+  let finite = region.length === 4;
+  for (let i = 0; i < region.length; i++) finite &&= Number.isFinite(region[i]);
+  if (!finite) {
+    throw new Error(
+      'lightmapModel: a region is four numbers, [scaleU, scaleV, biasU, biasV], ' +
+        `and was given ${String(region)}`,
+    );
+  }
+  return region;
+}
+
+let warnedUnpaged = false;
+
+/**
+ * Says once that a lightmapped material was set with no page. The lit stage adds nothing for one,
+ * which is the defined state; this is what keeps it from also being a silent one.
+ */
+export function warnUnpagedLightmap(
+  model: { readonly kind: string } | null | undefined,
+  map: unknown,
+): void {
+  if (warnedUnpaged || model?.kind !== 'lightmap' || (map !== null && map !== undefined)) return;
+  warnedUnpaged = true;
+  console.warn(
+    'setMaterial: a lightmapModel material with no modelMap reads no page and adds no light. ' +
+      'Pass the page createLightmap returned as its modelMap.',
+  );
+}
+
+let warnedRegions = false;
+
+/**
+ * Says once that an instanced batch and its material disagree about lightmap regions: a batch with
+ * regions drawn by a material that is not lightmapped, or a lightmapped one drawn without them. The
+ * regions ride the lane a tint and an opacity do (`MeshInstances.lightmapRegions`), so either draw
+ * reads one as the other: drawn, and wrong, which is why it is said rather than left.
+ */
+export function warnRegionsWithoutPage(
+  model: { readonly kind: string } | null | undefined,
+  regions: Float32Array | undefined,
+): void {
+  if (warnedRegions) return;
+  const lightmapped = model?.kind === 'lightmap';
+  if (lightmapped === (regions !== undefined)) return;
+  warnedRegions = true;
+  console.warn(
+    lightmapped
+      ? 'drawInstanced: a lightmapModel material drawing a batch with no lightmapRegions reads ' +
+          'its tints as regions. Give each instance its region of the page.'
+      : 'drawInstanced: a batch with lightmapRegions drawn by a material that is not a ' +
+          'lightmapModel reads its regions as its tints and opacities. Draw it with its page, or ' +
+          'without regions.',
+  );
+}

package/src/render/mesh.ts

@@ -400,7 +400,8 @@ export class Mesh {
       gl.vertexAttribDivisor(location, 1);
     }
     gl.enableVertexAttribArray(15);
-    gl.vertexAttribPointer(15, 3, gl.FLOAT, false, stride, 64);
+    /* The tint and, in w, the opacity: one attribute for both. See `INSTANCE_FLOATS`. */
+    gl.vertexAttribPointer(15, 4, gl.FLOAT, false, stride, 64);
     gl.vertexAttribDivisor(15, 1);
     gl.bindVertexArray(null);
     return vao;