@driftengine/core 4.13.1 → 4.13.3

package/CHANGELOG.json

@@ -1,4 +1,46 @@
 [
+  {
+    "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",
+    "entries": [
+      {
+        "kind": "added",
+        "short": "A mesh stored as weighted points in its joints' own spaces is posed on the device, so the main thread hands over the joints and nothing else: `createPointSkin` and `posePointSkin`.",
+        "text": "`createPointSkin(mesh, data)` and `posePointSkin(skin, matrices)` pose a dynamic mesh on the device from a format some models are stored in: each vertex up to four points, each in the space of the joint it follows, with a weight each, and a normal in the space of its first joint (`PointSkinData`). Posed, a vertex is the weighted sum of each point moved by its joint, which ordinary skinning cannot express, since it moves one bind-pose position by a blend of joints; such a rig was posed on the main thread and its positions uploaded every frame, measured by a consumer at 38% of the main thread's drawing time. WebGPU poses in a compute pass and WebGL2 by transform feedback, writing the mesh's own positions and normals, so every pass draws it as any dynamic mesh, its shadow and its motion included, and a skinned vertex stage that has no attribute left for four more points is untouched. The joints are each joint's transform into the mesh's model space, sixteen floats a joint with no inverse bind. The mesh's bounds become a box around each joint's reach, scaled by the joint's largest axis and by the most a vertex's weights sum to, so it is culled as it moves without the posed vertices coming back to the CPU. Measured on an RX 9070 XT (`demo/dev/pointSkin.html`): the device's pose draws the picture the same pose computed on the CPU draws, to the pixel on WebGPU and within 6 pixels on WebGL2, and differs from the rest pose by 70,792; under reconstruction the two part by 743 pixels a level deep, the rounding of single against double precision, where a motion fault parts them by 43,629."
+      },
+      {
+        "kind": "added",
+        "short": "A mesh's colours can be rewritten in place: a mesh made `{ dynamicColors: true }` takes `updateMeshColors`, so ground shaded again every frame is no longer made again.",
+        "text": "`updateMeshColors(mesh, colors)` rewrites a mesh's colours, three linear floats a vertex, on a mesh created with `{ dynamicColors: true }`, which keeps them as floats in a buffer of their own. Nothing else moves: not the positions, not the bounds, and no motion vector. `updateMesh` rewrites positions and normals only, so a surface whose colour changes while it stays where it is, such as ground darkened with its distance from a moving camera, was made again as a new mesh nearly every frame: a consumer measured 295 of 301 frames measured, a fifth of the drawing's main-thread time. The option is independent of `dynamic`, and costs twelve bytes a vertex where sixteen-bit colours cost six or eight and one colour every vertex shares costs nothing. On WebGPU the colours are the mesh's last vertex buffer, so every other buffer stays where it was, and every pipeline that draws such a mesh, the shadow pass's included, reads them there. Measured on an RX 9070 XT (`demo/dev/meshColors.html`): colours rewritten in place draw the picture a mesh made with the same colours draws, to the pixel on both backends, drawn alone and instanced."
+      },
+      {
+        "kind": "added",
+        "short": "A skinned cloth can be drawn back toward its skinned shape, so styled hair keeps the shape it was made in at rest and swings out of it as the body moves: `pull`, a stiffness.",
+        "text": "`SkinnedClothParameters.pull` draws every free particle of a garment back toward where its skinning puts it, as a stiffness: metres a second squared for every metre away. Applied first among the limits, after the constraints, each substep keeping `1 / (1 + pull · h²)` of a particle's offset, which is a compliant constraint's step, so the shape it holds against gravity is one length at every step: a particle at rest under gravity sits `9.81 / pull` metres below its skinned place. The limits could not do this, since a max distance is a sphere a particle may fall anywhere inside, so styled hair pinned at its roots fell to its edge and hung over the face. **A stiffness rather than a share of the offset kept a second as `damping` is, which is what was asked for**: a share scaled by the step holds a sag proportional to it, measured on hair authored to keep 0.7 of its offset a 1/60 step at 6.36, 3.49 and 1.83 mm at 1/60, 1/120 and 1/240, where the stiffness holds 6.36 mm at all three. A share `k` kept a step `s` is `(1 / k - 1) / s²` and keeps exactly `k` at that step. The same on the device and on the CPU: with a pull, the device's solve parts from the CPU's by 0.001 mm, no more than the CPU parts from itself nudged a tenth of a micrometre a frame (`demo/dev/skinnedCloth.html?parity=1&pull=400`)."
+      },
+      {
+        "kind": "added",
+        "short": "An Android app can be held the way its game is played: `\"android\": { \"orientation\": \"sensorLandscape\" }` in drift.package.json, written into the activity.",
+        "text": "`drift.package.json`'s `android.orientation` is written into the activity's `android:screenOrientation`, so an app starts the right way round before any of the game's code runs, which a `lockOrientation` taken at run time cannot do. It takes every value Android documents (`landscape`, `sensorLandscape`, `portrait`, `sensorPortrait`, `userLandscape`, `fullSensor` and the rest) and refuses one it does not when the manifest is read, naming the field, since Android ignores an attribute value it does not know and the build would quietly be the phone's choice again. `unspecified`, the default, leaves the copied manifest exactly as it was. Until now the template's `unspecified` was the only answer, so a game held sideways built from a copy of the packager's templates, copied again from each release. `drift-package doctor` prints it beside the permissions and the cleartext policy."
+      },
+      {
+        "kind": "fixed",
+        "short": "A skinned draw that follows cloth binds the groups it made before, where WebGPU made them again nearly every frame: 24 a frame for two characters, and none now.",
+        "text": "A skinned draw's bind group was kept one a palette slot and material and made again whenever a resource in it differed from the last draw's. A garment's particles take turns between two textures, a step each, so a draw following cloth found the other texture every frame; and several meshes following one cloth bind one particle texture each with a binding of its own, so they replaced each other's group draw by draw. A consumer counted 24 groups made a frame for two characters, and none with cloth off. Each key now keeps a shelf of up to sixteen groups, each found again by the four resources it was built with, so a steady garment's draws make none; the cast shadows' groups, which missed the same way, keep a shelf a palette slot. And the views a draw of one binding binds with a set of particles are kept for every binding rather than for the last, which made two objects a draw as several meshes took turns. Measured on an RX 9070 XT (`demo/dev/skinnedCloth.html`): the garment, the garment under reconstruction and three garments stepped as one draw the picture a build that makes every group again draws, to the pixel, where binding last step's particles moves 18,321 pixels."
+      }
+    ]
+  },
   {
     "version": "4.13.1",
     "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: 920.9 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

@@ -155,8 +155,9 @@ export { BLOOM_LEVELS } from './render/bloomChain.ts';
 export type { BloomResponse } from './render/bloomChain.ts';
 export { probeDevice } from './render/backend/probe.ts';
 export type { ProbeVerdict } from './render/backend/probe.ts';
-export type { BoltHandle, CausticsHandle, ClothBindingHandle, ClothParticlesHandle, FlockHandle, IncrementalMeshHandle, LineHandle, MeshHandle, MeshOptions, PrepareOptions, RenderBackend, RendererApi, ParticleHandle, PlumeHandle, ScatterHandle, InstancedHandle, SdfTextHandle, SurfaceTextureHandle, TextHandle, WaterHandle, WindStreakHandle, } from './render/backend/api.ts';
+export type { BoltHandle, CausticsHandle, ClothBindingHandle, PointSkinHandle, ClothParticlesHandle, FlockHandle, IncrementalMeshHandle, LineHandle, MeshHandle, MeshOptions, PrepareOptions, RenderBackend, RendererApi, ParticleHandle, PlumeHandle, ScatterHandle, InstancedHandle, SdfTextHandle, SurfaceTextureHandle, TextHandle, WaterHandle, WindStreakHandle, } from './render/backend/api.ts';
 export type { ClothBindingData } from './render/clothBindingData.ts';
+export type { PointSkinData } from './render/pointSkin.ts';
 export { anisotropicModel, eyeModel, hairModel, lightmapModel, skinModel, } from './render/surfaceModel.ts';
 export type { AnisotropicModel, EyeModel, HairModel, LightmapModel, SkinModel, SurfaceModel, SurfaceModelKind, } from './render/surfaceModel.ts';
 export { DEFAULT_FRAME_REFLECTIONS } from './render/frameReflections.ts';
@@ -230,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/api.d.ts

@@ -12,6 +12,7 @@ import type { CompressedTextureSource, SurfaceSource } from '../compressedSource
 import type { LightmapPage } from '../lightmap.ts';
 import type { DeviceParticles } from '../particlePool.ts';
 import type { ClothBindingData } from '../clothBindingData.ts';
+import type { PointSkinData } from '../pointSkin.ts';
 import type { TextStyle } from '../textLayout.ts';
 import type { SdfFont } from '../sdfFont.ts';
 import type { SdfTextStyle } from '../sdfTextLayout.ts';
@@ -49,6 +50,12 @@ export interface MeshHandle {
  */
 export interface ClothBindingHandle {
 }
+/**
+ * A dynamic mesh's point skin on the device, from `createPointSkin`: its vertices as weighted points
+ * in its joints' spaces. Opaque likewise.
+ */
+export interface PointSkinHandle {
+}
 /** One character's cloth particles on the device, from `createClothParticles`. Opaque likewise. */
 export interface ClothParticlesHandle {
 }
@@ -190,15 +197,24 @@ export interface MeshOptions {
     /**
      * Whether this mesh's positions will be rewritten with `updateMesh`.
      *
-     * Costs a `DYNAMIC_DRAW` hint on WebGL2 and a CPU-side copy of the interleaved vertex data on
-     * WebGPU, which interleaves every attribute into one buffer and so cannot patch a position
-     * without the rest of the vertex in hand. Both are paid only where a consumer asks.
+     * Costs a `DYNAMIC_DRAW` hint on WebGL2, and on WebGPU two buffers of its own for the positions
+     * and the normals beside the rest of the vertex, bound with it on every draw, and floats for the
+     * normals where they might have been sixteen bits. Paid only where a consumer asks.
      */
     readonly dynamic?: boolean;
+    /**
+     * Whether this mesh's colours will be rewritten with `updateMeshColors`.
+     *
+     * Costs the colours as floats in a buffer of their own, twelve bytes a vertex where they might
+     * have been sixteen bits or, for one colour every vertex shares, nothing at all. Independent of
+     * `dynamic`: a surface shaded again as a camera moves rewrites its colours every frame and its
+     * positions never, and should pay for neither the positions' buffers nor their motion.
+     */
+    readonly dynamicColors?: boolean;
 }
 export type RendererApi = Omit<{
     [K in keyof Renderer]: Renderer[K];
-}, 'gpuTimer' | 'createMesh' | 'createMeshIncremental' | 'updateMesh' | 'drawMesh' | 'disposeMesh' | 'drawTranslucentMesh' | 'drawLightVolume' | 'drawFilm' | 'createScatter' | 'drawScatter' | 'uploadScatter' | 'disposeScatter' | 'createInstanced' | 'uploadInstanced' | 'drawInstanced' | 'drawTranslucentInstanced' | 'disposeInstanced' | 'createWater' | 'drawWater' | 'disposeWater' | 'createPlumes' | 'drawPlumes' | 'disposePlumes' | 'setPlumeScale' | 'createCaustics' | 'drawCaustics' | 'disposeCaustics' | 'createParticles' | 'drawParticles' | 'drawDeviceParticles' | 'disposeParticles' | 'createWindStreaks' | 'drawWindStreaks' | 'disposeWindStreaks' | 'createFlock' | 'drawFlock' | 'disposeFlock' | 'createBolts' | 'drawBolts' | 'disposeBolts' | 'createLines' | 'drawLines' | 'disposeLines' | 'createText' | 'setText' | 'setPlate' | 'drawText' | 'textWidth' | 'disposeText' | 'createSdfText' | 'setSdfText' | 'drawSdfText' | 'disposeSdfText' | 'createSurfaceTexture' | 'createSurfaceTextureArray' | 'createLightmap' | 'createSceneCapture' | 'captureScene' | 'updateSurfaceTexture' | 'disposeSurfaceTexture' | 'setSurfaceTexture' | 'setMaterial' | 'prepareMesh' | 'prepareInstanced' | 'setSurfaceOverlay' | 'createClothBinding' | 'createClothParticles' | 'updateClothParticles' | 'setCloth' | 'disposeClothBinding' | 'disposeClothParticles'> & {
+}, 'gpuTimer' | 'createMesh' | 'createMeshIncremental' | 'updateMesh' | 'updateMeshColors' | 'drawMesh' | 'disposeMesh' | 'drawTranslucentMesh' | 'drawLightVolume' | 'drawFilm' | 'createScatter' | 'drawScatter' | 'uploadScatter' | 'disposeScatter' | 'createInstanced' | 'uploadInstanced' | 'drawInstanced' | 'drawTranslucentInstanced' | 'disposeInstanced' | 'createWater' | 'drawWater' | 'disposeWater' | 'createPlumes' | 'drawPlumes' | 'disposePlumes' | 'setPlumeScale' | 'createCaustics' | 'drawCaustics' | 'disposeCaustics' | 'createParticles' | 'drawParticles' | 'drawDeviceParticles' | 'disposeParticles' | 'createWindStreaks' | 'drawWindStreaks' | 'disposeWindStreaks' | 'createFlock' | 'drawFlock' | 'disposeFlock' | 'createBolts' | 'drawBolts' | 'disposeBolts' | 'createLines' | 'drawLines' | 'disposeLines' | 'createText' | 'setText' | 'setPlate' | 'drawText' | 'textWidth' | 'disposeText' | 'createSdfText' | 'setSdfText' | 'drawSdfText' | 'disposeSdfText' | 'createSurfaceTexture' | 'createSurfaceTextureArray' | 'createLightmap' | 'createSceneCapture' | 'captureScene' | 'updateSurfaceTexture' | 'disposeSurfaceTexture' | 'setSurfaceTexture' | 'setMaterial' | 'prepareMesh' | 'prepareInstanced' | 'setSurfaceOverlay' | 'createClothBinding' | 'createClothParticles' | 'updateClothParticles' | 'setCloth' | 'disposeClothBinding' | 'disposeClothParticles' | 'createPointSkin' | 'posePointSkin' | 'disposePointSkin'> & {
     /**
      * A mesh's cloth binding: which simulation triangle each of its vertices follows, where on it and
      * by how much (`ClothBindingData`). The mesh must be skinned — a binding blends each vertex
@@ -222,6 +238,29 @@ export type RendererApi = Omit<{
     setCloth(binding: ClothBindingHandle | null, particles?: ClothParticlesHandle | null): void;
     disposeClothBinding(binding: ClothBindingHandle): void;
     disposeClothParticles(particles: ClothParticlesHandle): void;
+    /**
+     * A dynamic mesh posed on the device from weighted points in its joints' own spaces
+     * (`PointSkinData`): each vertex the weighted sum of up to four points, each moved by its joint,
+     * and a normal turned by its first joint. Posed into the mesh's own positions and normals, so
+     * every pass draws it as any dynamic mesh, motion vectors included. See `pointSkin.ts`.
+     *
+     * **For a rig whose vertices are stored that way**, which ordinary skinning cannot pose: it moves
+     * one bind-pose position by a blend of joints. Such a rig was posed on the main thread and
+     * uploaded every frame, reported at 38% of the main thread's drawing time.
+     *
+     * The mesh must be `{ dynamic: true }` and have the skin's vertex count; any other is refused in
+     * words, as is a joint past 511.
+     */
+    createPointSkin(mesh: MeshHandle, data: PointSkinData): PointSkinHandle;
+    /**
+     * Pose a skin: `matrices` holds each joint's transform into the mesh's model space, sixteen floats
+     * a joint, column-major, at least as many joints as the skin names. **Once a frame, before the
+     * mesh's draws**: a second pose in a frame reaches every draw of it on WebGPU, as a second
+     * `updateMesh` does. The mesh's bounds become a box around every joint's reach, so it is culled
+     * as it moves without the posed vertices ever coming back to the CPU.
+     */
+    posePointSkin(skin: PointSkinHandle, matrices: Float32Array): void;
+    disposePointSkin(skin: PointSkinHandle): void;
     /**
      * What the following draws lay over their surfaces beyond their materials — a rim of light, a
      * dissolve with a glowing edge, wrinkle normals by region — or null for none, which every pass
@@ -581,16 +620,32 @@ export type RendererApi = Omit<{
      * quads with a matrix each, which caps the resolution at the number of draw calls a consumer
      * can afford. A consumer found it by trying to hang a banner.
      *
-     * **Only positions and normals.** Colour, emissive and the rest describe what a surface *is*
-     * and do not change because it bent; rewriting them every frame would be uploading unchanged
-     * bytes. The vertex *count* is fixed: the index buffer, the pipeline and every other attribute
-     * are sized against it, and an update of a different size is refused naming both.
+     * **Only positions and normals.** Emissive and the rest describe what a surface *is* and do not
+     * change because it bent; rewriting them every frame would be uploading unchanged bytes. Colour
+     * is the exception a consumer found, a surface shaded again every frame without moving, and it
+     * has `updateMeshColors` of its own rather than a place here, so a rewrite of either sends only
+     * what changed. The vertex *count* is fixed: the index buffer, the pipeline and every other
+     * attribute are sized against it, and an update of a different size is refused naming both.
      *
      * The mesh must have been created with `{ dynamic: true }`. That is not ceremony — it decides
      * the buffer hint on one backend and what has to be kept on the other, and a mesh that never
      * deforms should pay for neither.
      */
     updateMesh(mesh: MeshHandle, positions: Float32Array, normals?: Float32Array): void;
+    /**
+     * Rewrite a mesh's colours, three floats a vertex, linear as `MeshData.colors` is.
+     *
+     * **For a surface whose colour changes while it stays where it is**: ground shaded with its
+     * distance from a moving camera, a heat map, a tile lit by a game's own rules. Without it such a
+     * surface is made again as a new mesh every frame, which is a buffer allocated and let go each
+     * frame on both backends and every pipeline it draws with looked up again.
+     *
+     * The mesh must have been created with `{ dynamicColors: true }`, which gives the colours a buffer
+     * of their own; any other is refused in words. Nothing else moves: not the positions, not the
+     * bounds, and no motion vector, since a colour does not move. A different vertex count is refused
+     * naming both.
+     */
+    updateMeshColors(mesh: MeshHandle, colors: Float32Array): void;
     /** Draw a handle this renderer made. Passing one from the other backend is a caller error. */
     drawMesh(mesh: MeshHandle, model: ReadonlyMat4, depthLayer?: number, tint?: Vec3 | null, 
     /**

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

@@ -0,0 +1,23 @@
+import type { Mesh } from '../../mesh.ts';
+import { type PointSkinData, type PointSkinReach } from '../../pointSkin.ts';
+/** The program and feedback object every skin on a context poses with, made at the first skin. */
+export interface PointSkinPose {
+    readonly program: WebGLProgram;
+    readonly feedback: WebGLTransformFeedback;
+}
+export declare function createPointSkinPose(gl: WebGL2RenderingContext): PointSkinPose;
+export declare class GlPointSkin {
+    readonly mesh: Mesh;
+    readonly reach: PointSkinReach;
+    private readonly count;
+    private readonly vao;
+    private readonly buffers;
+    private readonly joints;
+    private readonly width;
+    constructor(gl: WebGL2RenderingContext, mesh: Mesh, data: PointSkinData);
+    /** One buffer, read as each `[location, size, stride, offset]` says. */
+    private attach;
+    /** Pose every vertex into the mesh's buffers now, and undo every binding it made. */
+    pose(gl: WebGL2RenderingContext, pose: PointSkinPose, matrices: Float32Array): void;
+    dispose(gl: WebGL2RenderingContext): void;
+}

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

@@ -0,0 +1,159 @@
+/**
+ * A point skin on WebGL2: posed by transform feedback, a vertex stage run once a vertex with the
+ * rasteriser off, its two outputs captured into the dynamic mesh's own position and normal buffers.
+ * What a point skin is, and why it poses into a mesh, is `pointSkin.ts`; the same arithmetic in the
+ * same order is `backend/webgpu/shaders/pointSkin.wgsl.ts`.
+ *
+ * **Every binding it makes it undoes**, because it runs between a frame's draws: the program, the
+ * vertex array, the joint texture on its own unit, the feedback buffers and the discard. A buffer
+ * left bound for feedback while a draw reads it as vertices is an error WebGL2 raises at the draw.
+ */
+import { POINT_SKIN_TEXTURE_UNIT } from '../../lightBudget.js';
+import { reachOf } from '../../pointSkin.js';
+import { compileProgram } from '../../shader.js';
+const POSE_VERT = /* glsl */ `#version 300 es
+precision highp float;
+precision highp int;
+layout(location = 0) in vec4 aNamed;
+layout(location = 1) in vec4 aWeights;
+layout(location = 2) in vec3 aPoint0;
+layout(location = 3) in vec3 aPoint1;
+layout(location = 4) in vec3 aPoint2;
+layout(location = 5) in vec3 aPoint3;
+layout(location = 6) in vec3 aNormal;
+uniform highp sampler2D uJoints;
+out vec3 vPosition;
+out vec3 vNormal;
+
+mat4 jointAt(float joint) {
+  int at = int(joint) * 4;
+  return mat4(
+    texelFetch(uJoints, ivec2(at, 0), 0),
+    texelFetch(uJoints, ivec2(at + 1, 0), 0),
+    texelFetch(uJoints, ivec2(at + 2, 0), 0),
+    texelFetch(uJoints, ivec2(at + 3, 0), 0)
+  );
+}
+
+void main() {
+  vec3 p = vec3(0.0);
+  if (aWeights.x != 0.0) p += aWeights.x * (jointAt(aNamed.x) * vec4(aPoint0, 1.0)).xyz;
+  if (aWeights.y != 0.0) p += aWeights.y * (jointAt(aNamed.y) * vec4(aPoint1, 1.0)).xyz;
+  if (aWeights.z != 0.0) p += aWeights.z * (jointAt(aNamed.z) * vec4(aPoint2, 1.0)).xyz;
+  if (aWeights.w != 0.0) p += aWeights.w * (jointAt(aNamed.w) * vec4(aPoint3, 1.0)).xyz;
+  vec3 raw = mat3(jointAt(aNamed.x)) * aNormal;
+  float l = length(raw);
+  vNormal = l > 0.0 ? raw / l : raw;
+  vPosition = p;
+  gl_Position = vec4(0.0, 0.0, 0.0, 1.0);
+}
+`;
+const POSE_FRAG = /* glsl */ `#version 300 es
+precision mediump float;
+out vec4 colour;
+void main() {
+  colour = vec4(0.0);
+}
+`;
+export function createPointSkinPose(gl) {
+    const program = compileProgram(gl, POSE_VERT, POSE_FRAG, 'pointSkin.pose', [
+        'vPosition',
+        'vNormal',
+    ]);
+    gl.useProgram(program);
+    gl.uniform1i(gl.getUniformLocation(program, 'uJoints'), POINT_SKIN_TEXTURE_UNIT);
+    gl.useProgram(null);
+    const feedback = gl.createTransformFeedback();
+    if (feedback === null)
+        throw new Error('createTransformFeedback failed');
+    return { program, feedback };
+}
+export class GlPointSkin {
+    mesh;
+    reach;
+    count;
+    vao;
+    buffers = [];
+    joints;
+    width;
+    constructor(gl, mesh, data) {
+        this.mesh = mesh;
+        this.reach = reachOf(data);
+        this.count = data.weights.length / 4;
+        const vao = gl.createVertexArray();
+        if (vao === null)
+            throw new Error('createVertexArray failed');
+        this.vao = vao;
+        gl.bindVertexArray(vao);
+        this.attach(gl, data.joints, [[0, 4, 16, 0]]);
+        this.attach(gl, data.weights, [[1, 4, 16, 0]]);
+        this.attach(gl, data.points, [
+            [2, 3, 48, 0],
+            [3, 3, 48, 12],
+            [4, 3, 48, 24],
+            [5, 3, 48, 36],
+        ]);
+        this.attach(gl, data.normals, [[6, 3, 12, 0]]);
+        gl.bindVertexArray(null);
+        gl.bindBuffer(gl.ARRAY_BUFFER, null);
+        /* One row, four texels a joint, as the skin palette is. */
+        this.width = Math.max(1, this.reach.joints * 4);
+        const joints = gl.createTexture();
+        if (joints === null)
+            throw new Error('createTexture failed');
+        this.joints = joints;
+        gl.activeTexture(gl.TEXTURE0 + POINT_SKIN_TEXTURE_UNIT);
+        gl.bindTexture(gl.TEXTURE_2D, joints);
+        gl.texStorage2D(gl.TEXTURE_2D, 1, gl.RGBA32F, this.width, 1);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+    }
+    /** One buffer, read as each `[location, size, stride, offset]` says. */
+    attach(gl, values, reads) {
+        const buffer = gl.createBuffer();
+        if (buffer === null)
+            throw new Error('createBuffer failed');
+        this.buffers.push(buffer);
+        gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+        gl.bufferData(gl.ARRAY_BUFFER, values, gl.STATIC_DRAW);
+        for (const [location, size, stride, offset] of reads) {
+            gl.enableVertexAttribArray(location);
+            gl.vertexAttribPointer(location, size, gl.FLOAT, false, stride, offset);
+        }
+    }
+    /** Pose every vertex into the mesh's buffers now, and undo every binding it made. */
+    pose(gl, pose, matrices) {
+        const streams = this.mesh.streams;
+        if (streams === null)
+            return;
+        gl.useProgram(pose.program);
+        gl.bindVertexArray(this.vao);
+        gl.activeTexture(gl.TEXTURE0 + POINT_SKIN_TEXTURE_UNIT);
+        gl.bindTexture(gl.TEXTURE_2D, this.joints);
+        if (this.reach.joints > 0) {
+            gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, this.width, 1, gl.RGBA, gl.FLOAT, matrices, 0);
+        }
+        gl.enable(gl.RASTERIZER_DISCARD);
+        gl.bindTransformFeedback(gl.TRANSFORM_FEEDBACK, pose.feedback);
+        gl.bindBufferBase(gl.TRANSFORM_FEEDBACK_BUFFER, 0, streams.positions);
+        gl.bindBufferBase(gl.TRANSFORM_FEEDBACK_BUFFER, 1, streams.normals);
+        gl.beginTransformFeedback(gl.POINTS);
+        gl.drawArrays(gl.POINTS, 0, this.count);
+        gl.endTransformFeedback();
+        gl.bindBufferBase(gl.TRANSFORM_FEEDBACK_BUFFER, 0, null);
+        gl.bindBufferBase(gl.TRANSFORM_FEEDBACK_BUFFER, 1, null);
+        gl.bindTransformFeedback(gl.TRANSFORM_FEEDBACK, null);
+        gl.bindBuffer(gl.TRANSFORM_FEEDBACK_BUFFER, null);
+        gl.disable(gl.RASTERIZER_DISCARD);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+        gl.bindVertexArray(null);
+        gl.useProgram(null);
+    }
+    dispose(gl) {
+        for (const buffer of this.buffers)
+            gl.deleteBuffer(buffer);
+        gl.deleteTexture(this.joints);
+        gl.deleteVertexArray(this.vao);
+    }
+}

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

@@ -85,6 +85,8 @@ import type { FlockParams } from '../../flockRenderer.ts';
 import { InstancedBatch } from './instanced.ts';
 import type { BoneAnimationClip, BoneAnimationHandle } from '../../boneAnimation.ts';
 import type { InstancedOptions, MeshInstances } from '../../instances.ts';
+import { type PointSkinData } from '../../pointSkin.ts';
+import { GlPointSkin } from './pointSkinFeedback.ts';
 /** Reused each frame: which shader light slot each bound cubemap serves. */
 export type { ShadowCasterSink, ShadowCasters } from '../../shadowCasters.ts';
 /** Lighting and atmosphere for a frame. The game decides what goes in it. */
@@ -1298,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;
@@ -1869,6 +1878,25 @@ export declare class WebGL2Renderer implements RendererApi {
      * buffer is the same buffer. Rebinding here would cost a state change for nothing.
      */
     updateMesh(mesh: Mesh, positions: Float32Array, normals?: Float32Array): void;
+    /** The program and feedback object every point skin poses with, made at the first one. */
+    private pointSkinPose;
+    /**
+     * A dynamic mesh posed on the device from weighted points in its joints' spaces, by transform
+     * feedback. Refused in words on a mesh that is not dynamic, whose buffers are not hinted for a
+     * rewrite every frame.
+     */
+    createPointSkin(mesh: Mesh, data: PointSkinData): GlPointSkin;
+    /**
+     * Pose a skin now: `matrices` holds each joint's transform into the mesh's model space, sixteen
+     * floats, column-major. A command in the stream, so the draws after it read this pose.
+     */
+    posePointSkin(skin: GlPointSkin, matrices: Float32Array): void;
+    disposePointSkin(skin: GlPointSkin): void;
+    /**
+     * Rewrite a mesh's colours, on a mesh made `dynamicColors`. The VAO is left alone for the reason
+     * `updateMesh` gives: the buffer is the same buffer.
+     */
+    updateMeshColors(mesh: Mesh, colors: Float32Array): void;
     /**
      * Compile the skinned flat program, once, on the first rigged mesh.
      *
@@ -2178,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';
@@ -134,6 +135,8 @@ import { CUTOUT_RESOLVE_CODE, resolveCutout } from '../../cutoutDither.js';
 import { materialHasMaps, noteMapsWithoutUvs } from '../../mapsWithoutUvs.js';
 import { VIEW_MODEL_DEPTH_SHARE, viewModelDepthRange } from '../../viewModel.js';
 import { noLitSwitches } from '../../shaders/flat/glassTint.js';
+import { poseBounds, validatePointSkin, validatePose, } from '../../pointSkin.js';
+import { GlPointSkin, createPointSkinPose } from './pointSkinFeedback.js';
 /**
  * How many frames `firstFrameSettled` will ask before it stops asking.
  *
@@ -974,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;
@@ -2584,7 +2594,7 @@ export class WebGL2Renderer {
          */
         const drawn = withLightmapUvs(data);
         this.warmVariants(drawn);
-        return new Mesh(this.gl, drawn, options.dynamic === true);
+        return new Mesh(this.gl, drawn, options.dynamic === true, false, options.dynamicColors === true);
     }
     /**
      * Geometry in, handle out — but the geometry lands over as many frames as the caller gives it.
@@ -2598,7 +2608,7 @@ export class WebGL2Renderer {
     createMeshIncremental(data, options = {}) {
         const drawn = withLightmapUvs(data);
         this.warmVariants(drawn);
-        const { mesh, upload } = createMeshIncremental(this.gl, drawn, options.dynamic === true);
+        const { mesh, upload } = createMeshIncremental(this.gl, drawn, options.dynamic === true, options.dynamicColors === true);
         return {
             mesh,
             upload: {
@@ -2641,6 +2651,43 @@ export class WebGL2Renderer {
     updateMesh(mesh, positions, normals) {
         mesh.update(this.gl, positions, normals);
     }
+    /** The program and feedback object every point skin poses with, made at the first one. */
+    pointSkinPose = null;
+    /**
+     * A dynamic mesh posed on the device from weighted points in its joints' spaces, by transform
+     * feedback. Refused in words on a mesh that is not dynamic, whose buffers are not hinted for a
+     * rewrite every frame.
+     */
+    createPointSkin(mesh, data) {
+        if (mesh.streams === null) {
+            throw new Error('a point skin poses a mesh created with { dynamic: true }, whose positions and normals ' +
+                'are rewritten every frame. Say so at `createMesh`.');
+        }
+        validatePointSkin(data, mesh.vertexCount);
+        this.pointSkinPose ??= createPointSkinPose(this.gl);
+        return new GlPointSkin(this.gl, mesh, data);
+    }
+    /**
+     * Pose a skin now: `matrices` holds each joint's transform into the mesh's model space, sixteen
+     * floats, column-major. A command in the stream, so the draws after it read this pose.
+     */
+    posePointSkin(skin, matrices) {
+        validatePose(matrices, skin.reach);
+        if (this.contextLost || this.pointSkinPose === null)
+            return;
+        poseBounds(matrices, skin.reach, skin.mesh.bounds);
+        skin.pose(this.gl, this.pointSkinPose, matrices);
+    }
+    disposePointSkin(skin) {
+        skin.dispose(this.gl);
+    }
+    /**
+     * Rewrite a mesh's colours, on a mesh made `dynamicColors`. The VAO is left alone for the reason
+     * `updateMesh` gives: the buffer is the same buffer.
+     */
+    updateMeshColors(mesh, colors) {
+        mesh.updateColors(this.gl, colors);
+    }
     /**
      * Compile the skinned flat program, once, on the first rigged mesh.
      *
@@ -3268,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');
@@ -3559,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;
@@ -5556,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,
         });
@@ -7415,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`. */
@@ -7562,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);