3D engine that AI agents drive
Move the impostor and dither GLSL out of the core shaders into addon-registered slots
Nguyen Xuan An18f65b84cefc
diff --git a/changes/324.md b/changes/324.mdindex cfc88d60..48fbd109 100644--- a/changes/324.md+++ b/changes/324.md@@ -1 +1 @@-- Add baked impostor levels and dithered cross-fades to the vegetation addon (issue #324). `selectLevels(instances, eye, { impostors: { from: 3 }, fade: 0.06 })` draws far trees as one camera-facing card from a 64-view hemi-octahedral colour and normal atlas baked on the CPU (0.6 to 0.7 s for five species in Node), lit by the scene and casting a shadow from the light's side, and cross-fades neighbouring levels with the new `alphaMode: 'dither'`, chosen from the distance alone. A 5,223-tree forest drops from 2.68M to 0.52M triangles with cards from level 3 and 0.36M from level 2 (measured in Node). Both are opt-in, so existing scenes draw as before.+- Add baked impostor levels and dithered cross-fades to the vegetation addon (issue #324). `selectLevels(instances, eye, { impostors: { from: 3 }, fade: 0.06 })` draws far trees as one camera-facing card from a 64-view hemi-octahedral colour and normal atlas baked on the CPU (0.6 to 0.7 s for five species in Node), lit by the scene and casting a shadow from the light's side, and cross-fades neighbouring levels with a dither coverage, chosen from the distance alone. A 5,223-tree forest drops from 2.68M to 0.52M triangles with cards from level 3 and 0.36M from level 2 (measured in Node). Both are opt-in, so existing scenes draw as before.diff --git a/changes/324.size.md b/changes/324.size.mdindex 5b55af04..4ad4cd0f 100644--- a/changes/324.size.md+++ b/changes/324.size.md@@ -1,8 +1,8 @@-- entry:core: the impostor GLSL slots in the vertex shaders, the `dither` alpha branch in `surfaceAlpha` and four renderer hooks cost about 400 bytes gzip; the card GLSL itself registers from the vegetation addon and is not in the core.-- entry:vegetation: the new CPU atlas baker, the card shader code and the cross-fade selection are about 3.9 KB gzip of new addon code.-- scene:lit-box: the same core growth as entry:core.+- entry:core: the five GLSL slots in the vertex and fragment shaders, the shared registry tables and one `opacityBias` term in the alpha state cost about 230 bytes gzip; the card GLSL and the dither code register from the vegetation addon and are not in the core.+- entry:vegetation: the new CPU atlas baker, the card shader code and the cross-fade selection are about 4 KB gzip of new addon code.+- scene:lit-box: the same core growth as entry:core (191 bytes).- scene:gltf-box: the same core growth as entry:core.- scene:gltf-box+lazy: the same core growth as entry:core.- scene:agent-scene: the same core growth as entry:core.- scene:agent-scene+lazy: the same core growth as entry:core.-- archive: the vegetation impostor baker, card shader and cross-fade selection (three new source files) and their docs add about 12 KB to the package.+- archive: the vegetation impostor baker, card shader and cross-fade selection (new source files) and their docs add about 12 KB to the package.diff --git a/docs/culling-lod.md b/docs/culling-lod.mdindex 3a1576f9..b4a40400 100644--- a/docs/culling-lod.md+++ b/docs/culling-lod.md@@ -34,7 +34,7 @@ An instance uses the coarsest level whose `error` (the farthest its vertices lie## Cross-fades and impostor levels-`lods` switch a mesh by its pixel error and do not fade. The vegetation addon chooses its own levels by distance (`selectLevels`) and can fade between them: `selectLevels(instances, eye, { fade: 0.06 })` draws both levels near a threshold with complementary screen-door coverage (`alphaMode: 'dither'`, `opacity` and `ditherIncoming` on the material), and `impostors` adds a last level that draws one baked card per tree (material tag `impostor`). Culling treats the card as a rigid part: its bounding sphere holds the quad, and the sway is a few centimetres. Both choices depend on the distance only, so they keep the determinism below; see [Vegetation](/vegetation.md#impostors-and-cross-fade).+`lods` switch a mesh by its pixel error and do not fade. The vegetation addon chooses its own levels by distance (`selectLevels`) and can fade between them: `selectLevels(instances, eye, { fade: 0.06 })` draws both levels near a threshold with complementary screen-door coverage (a mask material whose `opacityBias` carries the coverage; the code registers when the vegetation addon is imported), and `impostors` adds a last level that draws one baked card per tree (material tag `impostor`). Culling treats the card as a rigid part: its bounding sphere holds the quad, and the sway is a few centimetres. Both choices depend on the distance only, so they keep the determinism below; see [Vegetation](/vegetation.md#impostors-and-cross-fade).## Determinismdiff --git a/docs/vegetation.md b/docs/vegetation.mdindex cdb92198..cefed7aa 100644--- a/docs/vegetation.md+++ b/docs/vegetation.md@@ -133,7 +133,7 @@ An impostor is baked per tree variant on first use, or by `prepareImpostors(variThe card is a quad with the `impostor` material tag. The vertex shader (`src/impostor-shader.js`) turns it to the eye, picks the atlas cell nearest the view direction in the tree's own frame (so yaw is respected) and sways its top by `frame.wind`; the standard fragment shader then lights it with the sun, the sky and the shadow map like any other surface, using the baked normals. In the shadow pass the "eye" is the light, so the card casts the tree's shadow as the sun sees it, cutout by the baked leaf mask. The card counts 2 triangles.-`fade` (a fraction of the switch distance, default 0.06 when `impostors` is on) cross-fades two neighbouring levels over a band of that fraction either side of each threshold: both draw, with `alphaMode: 'dither'`, whose coverage in eighths of the way is complementary (a pixel the outgoing level drops is drawn by the incoming one, from the same interleaved-gradient pattern of the screen position). The level and the step come from the distance alone, so a camera position always draws the same picture and a seek repeats. Selection with `fade` or `impostors` keeps no hysteresis, since the band does its job; `changed` is true when any instance moved to another level or step. Shadows draw every level of a fade at full coverage.+`fade` (a fraction of the switch distance, default 0.06 when `impostors` is on) cross-fades two neighbouring levels over a band of that fraction either side of each threshold: both draw, with a mask material whose `opacityBias` carries the dither coverage (the dither code and the card shader register on import of the addon, so scenes without it do not carry them), and whose coverage in eighths of the way is complementary (a pixel the outgoing level drops is drawn by the incoming one, from the same interleaved-gradient pattern of the screen position). The level and the step come from the distance alone, so a camera position always draws the same picture and a seek repeats. Selection with `fade` or `impostors` keeps no hysteresis, since the band does its job; `changed` is true when any instance moved to another level or step. Shadows draw every level of a fade at full coverage.Measured (Node, 2026-11-03), 5,223 trees (broadleaf, birch, conifer, bush, 3 variants each) on a 1,550 m square with the eye at its middle at 2 m, so every distance from 0 to 1,100 m occurs:diff --git a/src/impostor-shader.js b/src/impostor-shader.jsindex ad9fa5cc..9e6a8248 100644--- a/src/impostor-shader.js+++ b/src/impostor-shader.js@@ -4,7 +4,7 @@// extra attribute. The same function runs in the colour and shadow vertex shaders: in the shadow pass the "eye" is// the light, so the card shows the tree as the sun sees it.-import { materialTags, registerAddonGlsl } from './shader-registry.js';+import { materialTags, addonGlsl } from './shader-registry.js';/** Frames per side of the hemi-octahedral atlas (the atlas holds this many squared views). */export const IMPOSTOR_FRAMES = 8;@@ -57,22 +57,23 @@ const ALPHA_COVERAGE = ` if (materialOpacity > 1.0) {}`;-registerAddonGlsl({- alphaCoverage: ALPHA_COVERAGE,- declarations: impostorShader,- colorHook: ` vec3 impostorNormal = vec3(0.0, 1.0, 0.0);- bool isImpostor = instanceSurface.w == ${IMPOSTOR_TAG}.0;- if (isImpostor) {+Object.assign(addonGlsl, {+ alpha: ALPHA_COVERAGE,+ defs: impostorShader,+ color: ` if (instanceSurface.w == ${IMPOSTOR_TAG}.0) {vec2 atlasUv;- world.xyz = impostorCard(position, uv, instanceMatrix, viewProjection, time, wind, atlasUv, impostorNormal);+ vec3 cardNormal;+ world.xyz = impostorCard(position, uv, instanceMatrix, viewProjection, time, wind, atlasUv, cardNormal);uv = atlasUv;+ worldPosition = world.xyz;+ worldNormal = cardNormal;}`,- normalHook: ` if (isImpostor) worldNormal = impostorNormal;-`,- depthHook: ` if (instanceSurface.w == ${IMPOSTOR_TAG}.0) {+ depth: ` if (instanceSurface.w == ${IMPOSTOR_TAG}.0) {vec3 lightFacing;- world.xyz = impostorCard(position, uv, instanceMatrix, lightProjection, time, wind, shadowUv, lightFacing);+ vec2 atlasUv;+ world.xyz = impostorCard(position, uv, instanceMatrix, lightProjection, time, wind, atlasUv, lightFacing);+ uv = atlasUv;}`,});diff --git a/src/shader-registry.js b/src/shader-registry.jsindex a2deaae3..9bfa01dd 100644--- a/src/shader-registry.js+++ b/src/shader-registry.js@@ -54,10 +54,6 @@ export function requireFeatureCode(feature) {/** Value of `material.tag` in the instance data; the vegetation addon adds `impostor`. */export const materialTags = { armor: 1, floor: 2, water: 3, foliage: 4, terrain: 5, grass: 7, fire: 8, smoke: 9, unlit: 10, liquid: 11, foam: 12 };-// GLSL the vegetation addon splices into the shaders: `declarations`, `colorHook` and `normalHook` in the colour vertex-// shader, `depthHook` in the shadow vertex shader and `alphaCoverage` in the fragment shader's surfaceAlpha.-export const addonGlsl = { declarations: '', colorHook: '', normalHook: '', depthHook: '', alphaCoverage: '' };+// GLSL the vegetation addon splices into the shaders: `defs` and `color` in the colour vertex shader, `defs` and `depth` in the shadow vertex shader and `alpha` in the fragment shader's surfaceAlpha.+export const addonGlsl = { defs: '', color: '', depth: '', alpha: '' };-export function registerAddonGlsl(slots) {- Object.assign(addonGlsl, slots);-}diff --git a/src/shaders.js b/src/shaders.jsindex f4b67e5b..4725c46c 100644--- a/src/shaders.js+++ b/src/shaders.js@@ -119,14 +119,14 @@ flat out mat3 boxNormalMatrix;${skinningShader()}${morphingShader}${windShader(features)}-${addonGlsl.declarations}+${addonGlsl.defs}void main() {// A crowd batch reads its joints and weights from the UV and colour attributes, which then carry no texture or tint.vec2 uv = USES_CROWD ? vec2(-1.0) : uvSets.xy;mat4 deformation = USES_CROWD ? crowdTransform() : (USES_SKIN ? skinTransform() : mat4(1.0));vec4 world = instanceMatrix * deformation * vec4(USES_MORPH ? morphedPosition(position) : position, 1.0);world.xyz += USES_CROWD ? vec3(0.0) : assemblyOffset * assemblyAmount + assemblyDetailOffset * smoothstep(0.3, 1.0, assemblyAmount);-${addonGlsl.colorHook} if (USES_WIND) world.xyz += windOffset(position, world.xyz, uv, instanceSurface.w, time, wind);+ if (USES_WIND) world.xyz += windOffset(position, world.xyz, uv, instanceSurface.w, time, wind);if (USES_WAVES && instanceSurface.w == 3.0) {world.y += sin(world.x * 1.4 + time * 0.8) * 0.025 + sin(world.z * 1.8 - time) * 0.02;}@@ -137,7 +137,7 @@ ${addonGlsl.colorHook} if (USES_WIND) world.xyz += windOffset(position, world.xvec3 localNormal = USES_MORPH ? morphedNormal(normal) : normal;vec3 deformedNormal = (USES_SKIN || USES_CROWD) ? transpose(inverse(mat3(deformation))) * localNormal : localNormal;worldNormal = normalize(instanceNormal * deformedNormal);-${addonGlsl.normalHook} // Metres along the object's own axes, so a pattern follows a moving node and is not stretched by its scale.+${addonGlsl.color} // Metres along the object's own axes, so a pattern follows a moving node and is not stretched by its scale.boxPosition = (USES_MORPH ? morphedPosition(position) : position) * vec3(length(instanceMatrix[0].xyz), length(instanceMatrix[1].xyz), length(instanceMatrix[2].xyz));boxNormal = deformedNormal;boxNormalMatrix = instanceNormal;@@ -174,15 +174,14 @@ out vec2 textureUV;${skinningShader()}${morphingShader}${windShader(features)}-${addonGlsl.declarations}+${addonGlsl.defs}void main() {vec2 uv = USES_CROWD ? vec2(-1.0) : uvSets.xy;vec4 world = instanceMatrix * (USES_CROWD ? crowdTransform() : skinTransform()) * vec4(morphedPosition(position), 1.0);world.xyz += USES_CROWD ? vec3(0.0) : assemblyOffset * assemblyAmount + assemblyDetailOffset * smoothstep(0.3, 1.0, assemblyAmount);// Same displacement as the colour pass, so shadows follow the swaying leaves.world.xyz += windOffset(position, world.xyz, uv, instanceSurface.w, time, wind);- vec2 shadowUv = uv;-${addonGlsl.depthHook} textureUV = shadowUv;+${addonGlsl.depth} textureUV = uv;gl_Position = lightProjection * world;}`;}@@ -499,7 +498,7 @@ ${featureCode("worldMossFunction")}// Opaque draws 1, mask resolves to a cutoutfloat surfaceAlpha(float textureAlpha) {if (!USES_ALPHA_MODE) return 1.0;float alpha = materialOpacity * textureAlpha;-${addonGlsl.alphaCoverage} if (alphaMode > 1.5) return alpha;+${addonGlsl.alpha} if (alphaMode > 1.5) return alpha;if (alphaToCoverage > 0.5) {float softness = max(fwidth(alpha), 0.0001);alpha = clamp((alpha - alphaCutoff) / softness + 0.5, 0.0, 1.0);