@solidrt/3d 0.0.54 → 0.0.55

package/AGENTS.md

@@ -152,7 +152,7 @@ blendMode and pointer events like any element.
 
 | Component | Props |
 | --- | --- |
-| `Scene` | `width`, `height` (target pixels), `clearColor?`, `background?` (fragment GLSL), `samples?` (1/2/4/8 MSAA), `label?`, `ref?(scene)`, `output?(texture)`, `events?` (mesh pointer events, default on) |
+| `Scene` | `width`, `height` (target pixels), `clearColor?`, `background?` (fragment GLSL), `fog?` (`{ color, near, far }`, linear by camera distance), `samples?` (1/2/4/8 MSAA), `label?`, `ref?(scene)`, `output?(texture)`, `events?` (mesh pointer events, default on) |
 | `Group` | `position?`, `rotation?` (Euler radians, XYZ order), `quaternion?` (either, not both), `scale?` (number = uniform), `visible?`, pointer events (below), `ref?(node)` |
 | `Mesh` | `geometry`, `material`, transforms as Group, `params?` (per-mesh uniforms, merge semantics - no unset), pointer events (below), `ref?(mesh)` |
 | `Sprite` | as Mesh minus `geometry`: a camera-facing unit quad, `scale` is its world size, rotation is ignored; pair with a `sprite()` material |
@@ -349,9 +349,10 @@ uint16/uint32 indices by vertex count automatically.
 
 Materials:
 
-- `unlit({ color?, map?, transparent?, cull?, alphaTest? })` - straight
-  `[r, g, b, a?]` 0..1, premultiplied internally; `cull` and `alphaTest`
-  as on lit (a mapped cutout casts its cutout).
+- `unlit({ color?, map?, transparent?, cull?, alphaTest?, fog? })` -
+  straight `[r, g, b, a?]` 0..1, premultiplied internally; `cull` and
+  `alphaTest` as on lit (a mapped cutout casts its cutout); `fog: false`
+  opts out of the scene's fog (all three standard materials take it).
 - `sprite({ color?, map?, transparent?, billboard? })` - unlit on a quad
   that turns to face the camera IN THE VERTEX STAGE (off the shared
   uCamRight/uCamUp, or uCamPos for `billboard: "fixed-y"`, which yaws
@@ -445,6 +446,37 @@ a background is static art - anything animated is a mesh's own
 shaderMaterial (or, until blend factors land, a separate shader texture
 underneath, which translucent grounds also still need).
 
+Fog: `scene.setFog(fog | null)`, the `fog` option on createScene and
+the reactive `Scene` prop, in Three's two shapes: linear `{ color, near,
+far }` (`Fog`; fades from near to far, fully fogged past far) or exp2
+`{ color, density }` (`FogExp2`, Unity's default; `1 - exp(-(d *
+density)^2)`, no start band, never quite opaque - 0.01 is ~63% at 100
+units). Either form takes `height` + `heightFalloff` (Godot's fog
+height, Unreal's height falloff): full fog at and below `height` (world
+y, default 0), thinning by `exp(-(y - height) * heightFalloff)` above -
+a valley fills, the hilltops and the sky stay clear; per fragment
+height, not integrated along the ray, the cheap tier every engine ships
+first. A fragment fades toward `color` by its RADIAL distance from
+`uCamPos` (not view depth). It is ONE shared-params write (`uFogColor`,
+`uFogNear`, `uFogInv` = 1/(far-near), `uFogDensity`, `uFogHeight`,
+`uFogHeightFalloff`; the form not in use is 0, "no fog" is every rate
+0, which the scene seeds at creation so there is no enable flag and no
+branch - the shader takes the larger of the two distance factors times
+the height term), fanned out to every view, so fogging costs nothing
+per frame however many meshes. Every standard material (unlit,
+lit, sprite) composes it after its alphaTest discard, mixed at the alpha
+it writes (premultiplied stays premultiplied); `fog: false` on the
+material drops the code from the program (Three's `material.fog`) - a
+sky sphere, a far backdrop. A shaderMaterial opts in by composing `FOG`
+from `/glsl` (declares the set; `fog(rgb, alpha, worldPos, camPos)`, or
+`fogAdditive(rgb, worldPos, camPos)` for a `blend: "add"` look, which
+fades toward black instead of the fog color).
+The BACKGROUND is not fogged: it is entry zero with no depth or
+distance, so match the fog color to `clearColor` or the background's
+horizon, and put `far` at or inside the camera's far plane to hide the
+clip. `examples/fog.tsx` cycles the forms over a valley;
+`examples/cascades.tsx` fogs its field to the sky.
+
 Lighting GLSL (`@solidrt/3d/glsl`): exported string constants composed
 into shaderMaterial sources with plain template literals - `LIT_VERTEX`
 (the standard vertex stage: clip position plus vWorldPos/vNormal/vUv
@@ -509,7 +541,12 @@ sorting, usually with `cull: "none"` for cards. Triplanar
 is an OPTION, not the default: generators emit 0..1 UVs per face, so a
 map on a plane is a decal (UV) while a map on generated scenery wants one
 density across parts of any size (triplanar); the map must be created
-with `wrap: "repeat"`. Internally one `shaderMaterialClass` per option
+with `wrap: "repeat"`. Any `map` on a surface seen at distance also wants
+`mipmap: true` at creation, or it aliases as it recedes, and a tiled
+surface seen at a grazing angle (a floor, a road) wants `anisotropy: 4`
+or more beside it, or trilinear smears the far half into the mip its long
+axis picked (`createModel` uploads its images with both; the device clamps
+the level, `limits.maxAnisotropy` reports it). Internally one `shaderMaterialClass` per option
 combination (map x vertexColors x triplanar x transparent x cull x
 alphaTest), cached for the app's lifetime, one pipeline per vertex layout
 - a thousand lit meshes share one program. The view vector comes from the
@@ -542,7 +579,7 @@ next to it, or single-file .glb) and become a Group of meshes, Three's
   Blender exports Draco by DEFAULT, so that is the first error a real
   file hits.
 - `createModel(data, { material?, label? })` - uploads the images (repeat
-  wrap, mipmapped), makes one material per glTF material (default `lit({
+  wrap, mipmapped, 4x anisotropic), makes one material per glTF material (default `lit({
   color, map, transparent })`; pass `material(m, map)` for anything else,
   it is called once per material and shared), one mesh per part, all
   children of the returned `Model` (a Group): `add(scene.root, model)`,
@@ -815,6 +852,13 @@ The follow-ups are filed in okf/backlog/3d-model-loader.md.
   leaf under a design size. Only a leaf whose layout size deliberately
   differs from the target (supersampling) needs `handlersFor`, fed the
   layout size the app itself set.
+- Scene-wide effects reach a custom material ONLY by composition: a
+  `shaderMaterial` that does not compose `FOG` is unfogged, one that does
+  not compose the `SHADOW_*` trio is unshadowed, and since every
+  instanced mesh has a custom material, an instanced forest stays crisp
+  in a fogged scene until its fragment calls `fog()`. The engine cannot
+  inject it (what you declare is what runs); check both when a custom
+  look sits beside standard ones and reads wrong at distance.
 - Hover (enter/leave) reacts to pointer MOTION only: a mesh animating
   under a still pointer fires nothing until the next move - the same
   limit the element hit test has (hit-test-per-frame is an open platform

package/examples/README.md

@@ -58,6 +58,13 @@ depends on `@solidrt/3d` (or in-repo from the package directory).
   the plain box widened to cover the field: one map's texels spread over
   it, blocky everywhere) and the `cascades`/`fly` debug commands set the
   count and the shadow distance and park the flight.
+- `fog.tsx` - scene fog over a valley of pines between two ridges: a
+  click cycles LINEAR (`{ near, far }`, a clear band then a fade to the
+  far plane), EXP2 (`{ density }`, thickening from the first metre) and
+  HEIGHT (`heightFalloff`: the valley floor fills, the hilltops and sky
+  stay clear), then off; two suns show the material opt-out (`unlit({
+  fog: false })` stays bright, its twin fogs). The `fog` debug command
+  sets the mode and its knobs and `pan` parks the camera.
 - `model.tsx` - a model from a file: `model.glb` (a small rover with
   nested node transforms, a mirrored node, a textured material, a
   transparent dome and a mesh without normals) parsed with `parseGltf`

package/examples/cascades.tsx

@@ -14,8 +14,11 @@
 // The `cascades` debug command sets the count and the shadow distance
 // (`{ count, distance }`; the range the cascades split, the camera's far
 // by default - pulling it in sharpens every cascade) and `fly` parks the
-// flight (`{ t: seconds }`), so a capture repeats.
-import { createSignal, onFrame, pct, render } from "@solidrt/core"
+// flight (`{ t: seconds }`), so a capture repeats. The field is fogged
+// toward the sky color from FOG_NEAR to FOG_FAR, inside the camera's far
+// plane, so the far pillars sink into the horizon instead of clipping
+// (`examples/fog.tsx` is the fog tour).
+import { createSignal, flush, onFrame, pct, render } from "@solidrt/core"
 import { registerDebug } from "srt:dev"
 import { box, DirectionalLight, HemisphereLight, lit, Mesh, PerspectiveCamera, plane, Scene, sphere } from "@solidrt/3d"
 import type { Geometry, Vec3 } from "@solidrt/3d"
@@ -27,6 +30,12 @@ const FAR = 200
 const RADIUS = 50
 const HEIGHT = 5
 const PERIOD = 90
+// The sky, shared by the clear and the fog so the horizon has no band.
+const SKY: [number, number, number] = [0.6, 0.72, 0.88]
+// The fog band: clear up to FOG_NEAR, fully sky at FOG_FAR (the far edge
+// of the field is about 150 units out at the flight's radius).
+const FOG_NEAR = 30
+const FOG_FAR = 150
 
 let [cascades, setCascades] = createSignal(3)
 let [distance, setDistance] = createSignal<number | null>(null)
@@ -37,6 +46,7 @@ let parked: number | null = null
 registerDebug("cascades", (args?: Record<string, unknown>) => {
   if (typeof args?.count === "number") setCascades(args.count)
   if (typeof args?.distance === "number" || args?.distance === null) setDistance(args.distance)
+  flush()
   return { cascades: cascades(), distance: distance() }
 })
 registerDebug("fly", (args?: Record<string, unknown>) => {
@@ -46,6 +56,7 @@ registerDebug("fly", (args?: Record<string, unknown>) => {
   } else if (args?.t === null) {
     parked = null
   }
+  flush()
   return { t: time(), parked: parked !== null }
 })
 
@@ -87,7 +98,14 @@ function App() {
   return (
     <window>
       <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]} onPointerDown={() => setCascades(c => (c % 4) + 1)}>
-        <Scene width={SIZE} height={SIZE} clearColor={[0.6, 0.72, 0.88, 1]} samples={4} label="cascades">
+        <Scene
+          width={SIZE}
+          height={SIZE}
+          clearColor={[SKY[0], SKY[1], SKY[2], 1]}
+          fog={{ color: SKY, near: FOG_NEAR, far: FOG_FAR }}
+          samples={4}
+          label="cascades"
+        >
           <PerspectiveCamera fov={50} near={0.5} far={FAR} position={eye()} lookAt={ahead()} />
           <HemisphereLight sky={[0.5, 0.58, 0.7]} ground={[0.25, 0.22, 0.18]} />
           <DirectionalLight

package/examples/fog.tsx

@@ -0,0 +1,174 @@
+// Scene fog, all three forms over one valley: a camera on a hillside
+// panning slowly across a floor of pines between two ridges, the far
+// ridge near the camera's far plane. LINEAR fog (`{ near, far }`,
+// Three's Fog) is a clear band then a fade, and hides the clip when
+// `far` sits at the camera's; EXP2 (`{ density }`, Three's FogExp2 /
+// Unity's default) thickens from the first metre with no band and
+// never quite closes; HEIGHT (`heightFalloff` on either) fills the
+// valley floor and thins on the way up, so the hilltops and the sky
+// stay clear while the pines below drown - per fragment height, the
+// cheap tier. Fog is one shared-params write per change, whatever the
+// mesh count, and every standard material takes it; the two suns show
+// the opt-out: the left one is `unlit({ fog: false })` and stays
+// bright in every mode, the right one fogs like everything else.
+//
+// A click cycles linear -> exp2 -> height -> off. The `fog` debug
+// command sets the mode and its knobs (`{ mode: "linear" | "exp2" |
+// "height" | "off", near, far, density, height, falloff }`) and returns
+// the state; `pan` parks the camera (`{ t: seconds }`), so a capture
+// repeats.
+import { createSignal, flush, onFrame, pct, render } from "@solidrt/core"
+import { registerDebug } from "srt:dev"
+import { cone, cylinder, DirectionalLight, HemisphereLight, lit, Mesh, PerspectiveCamera, plane, Scene, sphere, unlit } from "@solidrt/3d"
+import type { FogOptions, Vec3 } from "@solidrt/3d"
+
+const SIZE = 720
+const FAR = 400
+// The sky, shared by the clear and the fog so the horizon has no band.
+const SKY: [number, number, number] = [0.72, 0.78, 0.86]
+// The camera: on the near hillside, panning slowly across the valley.
+const EYE: Vec3 = [-40, 42, 140]
+const PAN_PERIOD = 60
+// How far the look-at point swings left and right of the valley axis.
+const PAN_SWING = 70
+// The linear band, the exp2 thickness and the height layer.
+const NEAR = 40
+const LINEAR_FAR = FAR
+const DENSITY = 0.006
+const HEIGHT = 10
+const HEIGHT_FALLOFF = 0.12
+
+type Mode = "linear" | "exp2" | "height" | "off"
+const MODES: Mode[] = ["linear", "exp2", "height", "off"]
+
+let [mode, setMode] = createSignal<Mode>("linear")
+let [near, setNear] = createSignal(NEAR)
+let [far, setFar] = createSignal(LINEAR_FAR)
+let [density, setDensity] = createSignal(DENSITY)
+let [height, setHeight] = createSignal(HEIGHT)
+let [falloff, setFalloff] = createSignal(HEIGHT_FALLOFF)
+let [time, setTime] = createSignal(0)
+let parked: number | null = null
+
+let num = (v: unknown, set: (n: number) => void) => {
+  if (typeof v === "number") set(v)
+}
+
+registerDebug("fog", (args?: Record<string, unknown>) => {
+  if (typeof args?.mode === "string" && MODES.includes(args.mode as Mode)) setMode(args.mode as Mode)
+  num(args?.near, setNear)
+  num(args?.far, setFar)
+  num(args?.density, setDensity)
+  num(args?.height, setHeight)
+  num(args?.falloff, setFalloff)
+  flush()
+  return { mode: mode(), near: near(), far: far(), density: density(), height: height(), falloff: falloff() }
+})
+registerDebug("pan", (args?: Record<string, unknown>) => {
+  if (typeof args?.t === "number") {
+    parked = args.t
+    setTime(args.t)
+  } else if (args?.t === null) {
+    parked = null
+  }
+  flush()
+  return { t: time(), parked: parked !== null }
+})
+
+function fog(): FogOptions | undefined {
+  switch (mode()) {
+    case "linear":
+      return { color: SKY, near: near(), far: far() }
+    case "exp2":
+      return { color: SKY, density: density() }
+    case "height":
+      return { color: SKY, density: density(), height: height(), heightFalloff: falloff() }
+    case "off":
+      return undefined
+  }
+}
+
+// The two ridges: flattened spheres sunk into the ground, and the height
+// they give the ground at (x, z) so the pines stand on them.
+type Hill = { position: Vec3; scale: Vec3 }
+let hills: Hill[] = [
+  { position: [-90, -8, 120], scale: [110, 44, 90] },
+  { position: [60, -6, -140], scale: [150, 40, 90] },
+  { position: [-140, -10, -60], scale: [90, 36, 120] },
+  { position: [150, -4, 40], scale: [80, 26, 70] },
+]
+function groundHeight(x: number, z: number): number {
+  let y = 0
+  for (let h of hills) {
+    let dx = (x - h.position[0]) / h.scale[0]
+    let dz = (z - h.position[2]) / h.scale[2]
+    let r = 1 - dx * dx - dz * dz
+    if (r > 0) y = Math.max(y, h.position[1] + h.scale[1] * Math.sqrt(r))
+  }
+  return y
+}
+
+// The pines, on a jittered grid over the valley and up the ridges.
+type Pine = { position: Vec3; size: number }
+let pines: Pine[] = []
+let step = 18
+for (let i = -12; i <= 12; i++) {
+  for (let j = -12; j <= 12; j++) {
+    let x = i * step + ((i * 7 + j * 13) % 9) - 4
+    let z = j * step + ((i * 11 + j * 5) % 9) - 4
+    let y = groundHeight(x, z)
+    // No pines on the near hillside under the camera, none above the tree line.
+    if (y > 30 || (x < -20 && z > 90)) continue
+    let size = 5 + ((i * 3 + j * 5 + 20) % 5)
+    pines.push({ position: [x, y, z], size })
+  }
+}
+
+function App() {
+  onFrame(tick => {
+    if (parked === null) setTime(tick / 1000)
+  })
+  let lookAt = () => {
+    let a = Math.sin((time() / PAN_PERIOD) * 2 * Math.PI)
+    return [a * PAN_SWING, 6, -60] as Vec3
+  }
+
+  let ground = lit({ color: [0.36, 0.48, 0.3] })
+  let rock = lit({ color: [0.5, 0.47, 0.42] })
+  let needles = lit({ color: [0.16, 0.36, 0.22] })
+  let trunk = lit({ color: [0.35, 0.25, 0.16] })
+  let sunLit = unlit({ color: [1, 0.92, 0.6], fog: false })
+  let sunFogged = unlit({ color: [1, 0.92, 0.6] })
+
+  let floor = plane({ width: 800, height: 800 })
+  let hill = sphere({ radius: 1, widthSegments: 48, heightSegments: 24 })
+  let crown = cone({ radius: 0.5, height: 1, radialSegments: 10 })
+  let stem = cylinder({ radiusTop: 0.08, radiusBottom: 0.1, height: 1, radialSegments: 6 })
+  let sun = sphere({ radius: 14, widthSegments: 24, heightSegments: 12 })
+
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]} onPointerDown={() => setMode(m => MODES[(MODES.indexOf(m) + 1) % MODES.length] ?? "linear")}>
+        <Scene width={SIZE} height={SIZE} clearColor={[SKY[0], SKY[1], SKY[2], 1]} fog={fog()} samples={4} label="fog">
+          <PerspectiveCamera fov={55} near={0.5} far={FAR} position={EYE} lookAt={lookAt()} />
+          <HemisphereLight sky={[0.55, 0.62, 0.75]} ground={[0.28, 0.24, 0.2]} />
+          <DirectionalLight color={[0.9, 0.85, 0.75]} rotation={[-0.9, 0.6, 0]} />
+          <Mesh geometry={floor} material={ground} rotation={[-Math.PI / 2, 0, 0]} />
+          {hills.map(h => (
+            <Mesh geometry={hill} material={rock} position={h.position} scale={h.scale} />
+          ))}
+          {pines.map(p => (
+            <>
+              <Mesh geometry={stem} material={trunk} position={[p.position[0], p.position[1] + p.size * 0.15, p.position[2]]} scale={[p.size, p.size * 0.3, p.size]} />
+              <Mesh geometry={crown} material={needles} position={[p.position[0], p.position[1] + p.size * 0.3 + p.size * 0.5, p.position[2]]} scale={[p.size * 0.9, p.size, p.size * 0.9]} />
+            </>
+          ))}
+          <Mesh geometry={sun} material={sunLit} position={[-30, 100, -220]} />
+          <Mesh geometry={sun} material={sunFogged} position={[30, 100, -220]} />
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/3d",
-  "version": "0.0.54",
+  "version": "0.0.55",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -18,7 +18,7 @@
     "AGENTS.md"
   ],
   "peerDependencies": {
-    "@solidjs/signals": "2.0.0-rc.3",
-    "@solidrt/core": "0.0.54"
+    "@solidjs/signals": "2.0.0-rc.4",
+    "@solidrt/core": "0.0.55"
   }
 }

package/src/components.tsx

@@ -31,7 +31,7 @@ import {
   setVisible,
 } from "./scene.ts"
 import type { ShaderParams } from "@solidrt/core/gpu"
-import type { DirectionalLight as DirectionalLightNode, HemisphereLight as HemisphereLightNode, InstancedMesh as InstancedMeshNode, Mesh as MeshNode, Scene as SceneHandle, SceneNode, ScenePointerEvent, ShadowOptions } from "./scene.ts"
+import type { DirectionalLight as DirectionalLightNode, FogOptions, HemisphereLight as HemisphereLightNode, InstancedMesh as InstancedMeshNode, Mesh as MeshNode, Scene as SceneHandle, SceneNode, ScenePointerEvent, ShadowOptions } from "./scene.ts"
 import type { Geometry } from "./geometry.ts"
 import type { Material } from "./material.ts"
 import type { Quat, Vec3 } from "./math.ts"
@@ -107,6 +107,12 @@ export type SceneProps = {
    * source replaces the background; undefined removes it. Three's
    * `scene.background = color` is `clearColor` here. */
   background?: string
+  /** Scene-wide fog (scene.setFog): linear `{ color, near, far }` or exp2
+   * `{ color, density }`, optionally thinning above `height` by
+   * `heightFalloff`; every standard material fades toward `color` by
+   * distance from the camera. Reactive; undefined removes it. Match
+   * `color` to clearColor or the background, which is not fogged. */
+  fog?: FogOptions
   label?: string
   /** Multisample count (1, 2, 4 or 8; default 1): anti-aliased mesh edges.
    * Fixed at creation. */
@@ -149,6 +155,10 @@ export let Scene: ParentComponent<SceneProps> = props => {
     () => props.background,
     b => scene.setBackground(b ?? null),
   )
+  createEffect(
+    () => props.fog,
+    f => scene.setFog(f ?? null),
+  )
   untrack(() => props.ref)?.(scene)
   let output = untrack(() => props.output)
   let events = untrack(() => props.events) !== false

package/src/glsl.ts

@@ -127,6 +127,53 @@ export const FRESNEL = glsl`
   }
 `
 
+/**
+ * The scene's fog (`scene.setFog`): the uniform set it writes - `uFogColor`,
+ * the linear band `uFogNear` / `uFogInv` (1 / (far - near)), the exp2
+ * `uFogDensity`, and the height attenuation `uFogHeight` /
+ * `uFogHeightFalloff`; the form not in use is 0, a fogless scene writes
+ * every rate 0, so the factor is 0 with no branch and no enable flag -
+ * plus `vec3 fog(vec3 rgb, float alpha, vec3 worldPos, vec3 camPos)`: the
+ * factor by the RADIAL distance from the camera (the larger of the two
+ * forms), thinned by `exp(-(y - height) * falloff)` above the fog height,
+ * mixing toward the fog color at the fragment's written alpha
+ * (premultiplied output stays premultiplied). Compose it last, after the
+ * alphaTest discard, with the alpha you are about to write:
+ *
+ *   fragColor = vec4(fog(rgb, a, vWorldPos, uCamPos), a);
+ *
+ * The standard materials compose exactly this; `fog: false` on one drops
+ * it (a sky sphere, a far backdrop). The background is not fogged.
+ *
+ * An ADDITIVE blend (`blend: "add"`) must not fade toward the fog color
+ * - a distant glow would brighten into a sky-colored halo - so it uses
+ * `vec3 fogAdditive(vec3 rgb, vec3 worldPos, vec3 camPos)`, the same
+ * factor fading toward black.
+ *
+ * Only what composes one of these is fogged: a shaderMaterial that does
+ * not - and so every instanced mesh, whose material is always custom -
+ * stays crisp in a fogged scene. The engine cannot inject it for you.
+ */
+export const FOG = glsl`
+  uniform vec3 uFogColor;
+  uniform float uFogNear;
+  uniform float uFogInv;
+  uniform float uFogDensity;
+  uniform float uFogHeight;
+  uniform float uFogHeightFalloff;
+  vec3 fog(vec3 rgb, float alpha, vec3 worldPos, vec3 camPos) {
+    float d = distance(worldPos, camPos);
+    float linear = clamp((d - uFogNear) * uFogInv, 0.0, 1.0);
+    float dd = d * uFogDensity;
+    float exp2 = 1.0 - exp(-dd * dd);
+    float h = exp(-max(worldPos.y - uFogHeight, 0.0) * uFogHeightFalloff);
+    return mix(rgb, uFogColor * alpha, max(linear, exp2) * h);
+  }
+  vec3 fogAdditive(vec3 rgb, vec3 worldPos, vec3 camPos) {
+    return fog(rgb, 0.0, worldPos, camPos);
+  }
+`
+
 /**
  * The scene's shadow set as a receiving program declares it: ONE
  * `uShadowAtlas` (every casting light's depth map is a tile of it, so N

package/src/index.ts

@@ -6,7 +6,7 @@
 // PerspectiveCamera) on top. See AGENTS.md for the model and the traps.
 
 export { add, createDirectionalLight, createGroup, createHemisphereLight, createInstancedMesh, createMesh, createScene, createSprite, setLight, disposeInstances, getRotation, lookAt, remove, setCastShadow, setGeometry, setInstanceCount, setInstances, setMaterial, setMeshParams, setRenderOrder, setTransform, setTransition, setVisible, worldPosition, MAX_SHADOWS } from "./scene.ts"
-export type { CameraUpdate, DirectionalLight as DirectionalLightNode, DirectionalLightOptions, HemisphereLight as HemisphereLightNode, HemisphereLightOptions, Hit, Light, InstancedMesh as InstancedMeshNode, InstancedMeshOptions, Mesh as MeshNode, MeshInstances, OrthoExtent, Scene as SceneHandle, SceneHandlers, SceneNode, SceneOptions, ScenePointerEvent, ShadowCamera, ShadowOptions, TransformUpdate, TransitionEndEvent, View, ViewOptions } from "./scene.ts"
+export type { CameraUpdate, DirectionalLight as DirectionalLightNode, DirectionalLightOptions, FogOptions, HemisphereLight as HemisphereLightNode, HemisphereLightOptions, Hit, Light, InstancedMesh as InstancedMeshNode, InstancedMeshOptions, Mesh as MeshNode, MeshInstances, OrthoExtent, Scene as SceneHandle, SceneHandlers, SceneNode, SceneOptions, ScenePointerEvent, ShadowCamera, ShadowOptions, TransformUpdate, TransitionEndEvent, View, ViewOptions } from "./scene.ts"
 export type { NodeTransition, NodeTransitionSpec } from "flux:spatial"
 export { disposeGeometry } from "./geometry-gpu.ts"
 export { box, circle, cone, cylinder, fillAttribute, fillColors, geometryBounds, layoutAttributes, layoutKey, layoutSlot, layoutStride, mergeGeometries, packGeometry, plane, ring, sphere, torus, torusKnot, transformGeometry, validateGeometry, withAttribute, withColors, STANDARD_FLOATS, VERTEX_LAYOUTS } from "./geometry.ts"

package/src/material.ts

@@ -42,7 +42,7 @@ import type {
 } from "@solidrt/core/gpu"
 import { layoutAttributes, layoutKey, layoutSlot } from "./geometry.ts"
 import type { VertexLayout } from "./geometry.ts"
-import { BLINN_SPECULAR, HEMISPHERE, LAMBERT, LIT_VERTEX, LIT_VERTEX_COLORED, MAX_LIGHTS, SHADOW, SHADOW_LOOKUP, SHADOW_SLOTS } from "./glsl.ts"
+import { BLINN_SPECULAR, FOG, HEMISPHERE, LAMBERT, LIT_VERTEX, LIT_VERTEX_COLORED, MAX_LIGHTS, SHADOW, SHADOW_LOOKUP, SHADOW_SLOTS } from "./glsl.ts"
 
 export type Material = {
   /** The pipeline this material draws with for geometry of `layout`
@@ -91,34 +91,46 @@ export type Material = {
 // what keeps camera motion O(1) instead of O(meshes), and the extra
 // per-vertex mat4 multiply is free on the GPU. aNormal from the shared
 // layout is deliberately not declared - inactive attributes are skipped
-// and only the stride accounts for them.
+// and only the stride accounts for them. vWorldPos is the fog distance
+// input; a fragment that does not read it (fog: false) leaves the out
+// unmatched, which links fine.
 const UNLIT_VERTEX = glsl`
   in vec3 aPos;
   in vec2 aUV;
   out vec2 vUv;
+  out vec3 vWorldPos;
   uniform mat4 uModel;
   uniform mat4 uViewProj;
 
   void main() {
-    gl_Position = uViewProj * uModel * vec4(aPos, 1.0);
+    vec4 world = uModel * vec4(aPos, 1.0);
+    vWorldPos = world.xyz;
+    gl_Position = uViewProj * world;
     vUv = aUV;
   }
 `
 
 // The unlit fragment (sprites share it): the color, times the map when
-// there is one, with the alphaTest discard when asked for. An opaque
+// there is one, with the alphaTest discard when asked for, then the
+// scene's fog (FOG from ./glsl, mixed at the alpha about to be written)
+// unless the material opted out. An opaque
 // class writes alpha 1: the scene target is composited premultiplied, so
 // a leaked texel alpha would punch a hole through an opaque draw.
-function unlitFragment(map: boolean, alphaTest: boolean, transparent: boolean): string {
+function unlitFragment(map: boolean, alphaTest: boolean, transparent: boolean, fog: boolean): string {
+  let alpha = transparent ? "base.a" : "1.0"
   return glsl`
     ${map ? "in vec2 vUv;" : ""}
+    ${fog ? "in vec3 vWorldPos;" : ""}
     ${map ? "uniform sampler2D uMap;" : ""}
     uniform vec4 uColor;
     ${alphaTest ? "uniform float uAlphaTest;" : ""}
+    ${fog ? "uniform vec3 uCamPos;" : ""}
+    ${fog ? FOG : ""}
     void main() {
       vec4 base = ${map ? "texture(uMap, vUv) * uColor" : "uColor"};
       ${alphaTest ? "if (base.a < uAlphaTest) discard;" : ""}
-      fragColor = ${transparent ? "base" : "vec4(base.rgb, 1.0)"};
+      ${fog ? `base.rgb = fog(base.rgb, ${alpha}, vWorldPos, uCamPos);` : ""}
+      fragColor = vec4(base.rgb, ${alpha});
     }
   `
 }
@@ -148,6 +160,12 @@ export type UnlitOptions = {
    * fences want it with `cull: "none"`; a mapped cutout casts its cutout
    * (Material.shadow). */
   alphaTest?: number
+  /** Take the scene's fog (default true, Three's `material.fog`): the
+   * fragment fades toward the fog color with its distance from the
+   * camera once `scene.setFog` is set. `false` drops the fog code from
+   * the program - a sky sphere or a far backdrop that must keep its
+   * color, an emissive marker. */
+  fog?: boolean
 }
 
 /**
@@ -163,12 +181,13 @@ export function unlit(opts: UnlitOptions = {}): Material {
   let transparent = opts.transparent === true
   let cull = opts.cull ?? "back"
   let alphaTest = opts.alphaTest !== undefined
-  let key = [map, transparent, cull, alphaTest].join("|")
+  let fog = opts.fog !== false
+  let key = [map, transparent, cull, alphaTest, fog].join("|")
   let cls = unlitClasses.get(key)
   if (cls === undefined) {
     cls = shaderMaterialClass({
       vertex: UNLIT_VERTEX,
-      fragment: unlitFragment(map, alphaTest, transparent),
+      fragment: unlitFragment(map, alphaTest, transparent, fog),
       transparent,
       cull,
       label: "scene-unlit-" + key,
@@ -217,7 +236,8 @@ export type LitOptions = UnlitOptions & {
 // composes by hand, per flag: map x vertexColors x triplanar x shadow x
 // transparent x cull (a class that shows back faces lights them with the
 // normal flipped, else a double-sided leaf's back is black) x alphaTest
-// (the cutoff itself is a per-entry uniform, one class for every value).
+// (the cutoff itself is a per-entry uniform, one class for every value)
+// x fog (the scene's fog composed last, or left out of the program).
 // An opaque class writes alpha 1 (see unlitFragment). Lights arrive
 // through the scene's shared params (light nodes); the base color, map
 // and highlight are per entry. The
@@ -237,6 +257,7 @@ type LitClass = {
   shadow: boolean
   cull: CullMode
   alphaTest: boolean
+  fog: boolean
 }
 
 function litClassKey(c: LitClass): string {
@@ -244,8 +265,9 @@ function litClassKey(c: LitClass): string {
 }
 
 function litFragment(c: LitClass): string {
-  let { map, vertexColors, triplanar, shadow, alphaTest } = c
+  let { map, vertexColors, triplanar, shadow, alphaTest, fog } = c
   let backFaces = c.cull !== "back"
+  let alpha = c.transparent ? "base.a" : "1.0"
   return glsl`
     in vec3 vWorldPos;
     in vec3 vNormal;
@@ -273,6 +295,7 @@ function litFragment(c: LitClass): string {
     ${HEMISPHERE}
     ${LAMBERT}
     ${BLINN_SPECULAR}
+    ${fog ? FOG : ""}
 
     void main() {
       vec3 n = normalize(vNormal);
@@ -302,7 +325,9 @@ function litFragment(c: LitClass): string {
         light += uLightColor[i] * lambert(n, l) * s;
         spec += uLightColor[i] * blinnSpecular(n, v, l, uShininess) * s;
       }
-      fragColor = vec4(base.rgb * light + spec * uSpecular * base.a, ${c.transparent ? "base.a" : "1.0"});
+      vec3 rgb = base.rgb * light + spec * uSpecular * base.a;
+      ${fog ? `rgb = fog(rgb, ${alpha}, vWorldPos, uCamPos);` : ""}
+      fragColor = vec4(rgb, ${alpha});
     }
   `
 }
@@ -335,6 +360,7 @@ export function lit(opts: LitOptions = {}): Material {
     shadow: opts.receiveShadow !== false,
     cull,
     alphaTest,
+    fog: opts.fog !== false,
   }
   let key = litClassKey(flags)
   let cls = litClasses.get(key)
@@ -477,6 +503,7 @@ const SPRITE_VERTEX_SRC = glsl`
   in vec3 aPos;
   in vec2 aUV;
   out vec2 vUv;
+  out vec3 vWorldPos;
   uniform mat4 uModel;
   uniform mat4 uViewProj;
   uniform vec3 uCamRight;
@@ -486,6 +513,7 @@ const SPRITE_VERTEX_SRC = glsl`
     vec3 center = uModel[3].xyz;
     vec2 size = vec2(length(uModel[0].xyz), length(uModel[1].xyz));
     vec3 world = center + uCamRight * (aPos.x * size.x) + uCamUp * (aPos.y * size.y);
+    vWorldPos = world;
     gl_Position = uViewProj * vec4(world, 1.0);
     vUv = aUV;
   }
@@ -495,6 +523,7 @@ const SPRITE_FIXED_Y_VERTEX_SRC = glsl`
   in vec3 aPos;
   in vec2 aUV;
   out vec2 vUv;
+  out vec3 vWorldPos;
   uniform mat4 uModel;
   uniform mat4 uViewProj;
   uniform vec3 uCamPos;
@@ -507,6 +536,7 @@ const SPRITE_FIXED_Y_VERTEX_SRC = glsl`
     float len = length(toCam);
     vec3 right = len > 1e-6 ? vec3(toCam.z, 0.0, -toCam.x) / len : vec3(1.0, 0.0, 0.0);
     vec3 world = center + right * (aPos.x * size.x) + vec3(0.0, aPos.y * size.y, 0.0);
+    vWorldPos = world;
     gl_Position = uViewProj * vec4(world, 1.0);
     vUv = aUV;
   }
@@ -531,12 +561,13 @@ export function sprite(opts: SpriteOptions = {}): Material {
   let map = opts.map !== undefined
   let transparent = opts.transparent !== false
   let fixedY = opts.billboard === "fixed-y"
-  let key = [map, transparent, fixedY].join("|")
+  let fog = opts.fog !== false
+  let key = [map, transparent, fixedY, fog].join("|")
   let cls = spriteClasses.get(key)
   if (cls === undefined) {
     cls = shaderMaterialClass({
       vertex: fixedY ? SPRITE_FIXED_Y_VERTEX_SRC : SPRITE_VERTEX_SRC,
-      fragment: unlitFragment(map, false, transparent),
+      fragment: unlitFragment(map, false, transparent, fog),
       transparent,
       cull: "none",
       label: "scene-sprite-" + key,

package/src/model.ts

@@ -20,6 +20,12 @@ import type { Material } from "./material.ts"
 import { add, createGroup, createMesh, remove } from "./scene.ts"
 import type { Mesh, SceneNode } from "./scene.ts"
 
+/** Anisotropic filtering level for a model's textures: the engines' usual
+ * default (Godot ships 2x, Unity's quality presets 2-8x) - enough to keep a
+ * tiled surface legible at a grazing angle, cheap on every GPU. Clamped to
+ * the device by the runtime. */
+const MODEL_ANISOTROPY = 4
+
 export type ModelOptions = {
   /** The material for each glTF material (default: `lit` with its color,
    * map and transparency). `map` is the uploaded base color texture, or
@@ -44,8 +50,9 @@ export type Model = SceneNode & {
 
 /**
  * Build the scene object for parsed model data: upload its images (repeat
- * wrap, mipmapped), make a material per glTF material, a mesh per part,
- * all under one Group. Synchronous - the data is already in memory.
+ * wrap, mipmapped, MODEL_ANISOTROPY), make a material per glTF material, a
+ * mesh per part, all under one Group. Synchronous - the data is already in
+ * memory.
  */
 export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
   let label = opts.label
@@ -54,6 +61,7 @@ export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
     return createTexture(image.data, image.width, image.height, {
       wrap: "repeat",
       mipmap: true,
+      anisotropy: MODEL_ANISOTROPY,
       autoFree: false,
       label: label ? label + "-image" + i : undefined,
     })

package/src/scene.ts

@@ -373,8 +373,50 @@ export type CameraUpdate = {
   ortho?: OrthoExtent | null
 }
 
+/**
+ * Scene fog, by RADIAL distance from the camera, in one of two forms:
+ * linear (Three's `Fog`, Unity's linear mode) fades toward `color` from
+ * `near` to `far` world units and is fully fogged past `far`; exp2
+ * (Three's `FogExp2`, Unity's default) thickens as
+ * `1 - exp(-(distance * density)^2)`, no start band, never quite opaque
+ * - `density` 0.01 is about 63% fog at 100 units, 98% at 200. Either
+ * form takes the height attenuation (Godot's fog height, Unreal's
+ * height falloff): the fog is full at and below `height` (world y) and
+ * thins above it by `exp(-(y - height) * heightFalloff)` - a valley
+ * fills while the hilltops and the sky stay clear; `heightFalloff` 0.1
+ * halves the fog every ~7 units of climb. Match
+ * `color` to the clearColor or background - the background is not
+ * fogged, so a mismatch shows as a band at the horizon - and, for the
+ * linear form, set `far` at or inside the camera's far plane to hide
+ * the clip.
+ */
+export type FogOptions = (
+  | {
+      /** Distance where the fade starts, world units; negative puts the
+       * camera itself part-way into the fog (Three allows the same). */
+      near: number
+      /** Distance where the fade completes, world units; must exceed near. */
+      far: number
+    }
+  | {
+      /** Exp2 thickness per world unit, > 0 (0.005 haze .. 0.05 pea soup). */
+      density: number
+    }
+) & {
+  /** Straight [r, g, b], 0..1. */
+  color: [number, number, number]
+  /** World y at and below which the fog is full; default 0. Only acts
+   * with a `heightFalloff`. */
+  height?: number
+  /** How fast the fog thins above `height`, per world unit (e-fold rate,
+   * >= 0); default 0, no height attenuation. */
+  heightFalloff?: number
+}
+
 export type SceneOptions = {
   clearColor?: [number, number, number, number]
+  /** Scene-wide fog; see setFog. */
+  fog?: FogOptions
   /** Fragment GLSL drawn behind the meshes, inside the scene's own pass -
    * see setBackground. */
   background?: string
@@ -458,6 +500,19 @@ export type Scene = {
    * declare a name simply skips it. Frame-rate-safe like setTransform.
    */
   setParams(params: ShaderParams): void
+  /**
+   * Set, replace, or remove (null) the scene's fog, linear
+   * (`{ color, near, far }`) or exp2 (`{ color, density }`), either with
+   * the optional `height`/`heightFalloff`. One shared-params write
+   * (`uFogColor`, `uFogNear`, `uFogInv`, `uFogDensity`, `uFogHeight`,
+   * `uFogHeightFalloff` - the set FOG in `@solidrt/3d/glsl` declares;
+   * the form not in use is written 0), fanned out to every view like
+   * setParams, so however many meshes fog it costs nothing per frame.
+   * Every standard material (unlit, lit, sprite) composes it unless
+   * created with `fog: false`; a shaderMaterial opts in by composing FOG.
+   * The background is not fogged: match colors (see FogOptions).
+   */
+  setFog(fog: FogOptions | null): void
   /**
    * Set, replace, or remove (null) the scene's background: fragment GLSL
    * drawn as the FIRST entry of the scene's own pass - one target, no
@@ -2119,6 +2174,32 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       setTargetParams(texture, params)
       for (let v of views) setTargetParams(v.texture, params)
     },
+    setFog(fog) {
+      if (fog === null) {
+        scene.setParams({ uFogInv: 0, uFogDensity: 0, uFogHeightFalloff: 0 })
+        return
+      }
+      let color = [fog.color[0], fog.color[1], fog.color[2]]
+      let height = fog.height ?? 0
+      let falloff = fog.heightFalloff ?? 0
+      if (!Number.isFinite(height) || !Number.isFinite(falloff) || falloff < 0) {
+        throw new Error(`setFog: height must be finite and heightFalloff finite and >= 0, got ${height} / ${falloff}`)
+      }
+      let params: ShaderParams = { uFogColor: color, uFogHeight: height, uFogHeightFalloff: falloff }
+      if ("density" in fog) {
+        let { density } = fog
+        if (!Number.isFinite(density) || density <= 0) {
+          throw new Error(`setFog: density must be finite and > 0, got ${density}`)
+        }
+        scene.setParams({ ...params, uFogInv: 0, uFogDensity: density })
+        return
+      }
+      let { near, far } = fog
+      if (!(Number.isFinite(near) && Number.isFinite(far)) || far <= near) {
+        throw new Error(`setFog: near/far must be finite with near < far, got ${near}..${far}`)
+      }
+      scene.setParams({ ...params, uFogNear: near, uFogInv: 1 / (far - near), uFogDensity: 0 })
+    },
     setBackground(source) {
       if (disposed) return
       if (background !== null) {
@@ -2273,6 +2354,12 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       }
     },
   }
+  // The fog set starts at "none" (uFogInv and uFogDensity 0 are factor 0,
+  // uFogHeightFalloff 0 is no attenuation) so every material that declares
+  // it has coverage from the first frame; a target tolerates the names
+  // when nothing declares them.
+  scene.setParams({ uFogColor: [0, 0, 0], uFogNear: 0, uFogInv: 0, uFogDensity: 0, uFogHeight: 0, uFogHeightFalloff: 0 })
+  if (opts?.fog !== undefined) scene.setFog(opts.fog)
   if (opts?.background !== undefined) scene.setBackground(opts.background)
   if (opts?.autoFree !== false && getOwner()) onCleanup(() => scene.dispose())
   return scene