@solidrt/3d 0.0.53 → 0.0.55

package/AGENTS.md

@@ -131,9 +131,12 @@ blendMode and pointer events like any element.
   the upload), so swapping `<Mesh geometry>` reactively never accumulates
   old generations. `disposeGeometry` is the immediate explicit free.
 - Materials dedupe hard: one program + one pipeline per material CLASS
-  (unlit color, unlit map, each opaque or transparent), `depth: true` +
-  `cull: "back"`; an instance is
-  just per-entry uniforms (`uColor`) and bindings (`uMap`).
+  (a `shaderMaterialClass` per option combination for unlit, lit and
+  sprite alike: map x transparent x cull x alphaTest, lit's extras on
+  top), `depth: true` + `cull: "back"` unless the material says otherwise
+  (`cull: "none"` for double-sided geometry; lit flips the normal on back
+  faces); an instance is just per-entry uniforms (`uColor`) and bindings
+  (`uMap`).
 - The pure pieces (`math.ts`, `order.ts`, `geometry.ts`,
   `profile.ts`, `sweep.ts`, `gltf.ts`, `model-file.ts`) are Solid-free and
   GPU-free BY DESIGN so they can be checked headless (and, for the two
@@ -149,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 |
@@ -168,6 +171,31 @@ elsewhere. Called once, untracked, inside the scene context. Scene
 layout, so render and display size separate - render at 2x and display
 smaller for supersampling.
 
+Filling the window: `width`/`height` are DEVICE pixels, the leaf's layout
+is LOGICAL. A `designSize` view fits the leaf to the window but never
+changes the target, so on a HiDPI display a 720-pixel scene is stretched
+across ~1100 device pixels and looks soft, and nothing warns (the
+examples' `SIZE = 720` is a verification convenience, not a sizing
+model). Render at the window's device size and lay the leaf out at its
+logical size:
+
+```tsx
+let target = createMemo(() => {
+  let { width, height } = windowSize()
+  let scale = displayScale()
+  return { w: Math.round(width * scale), h: Math.round(height * scale) }
+})
+<Scene width={target().w} height={target().h}
+       output={t => <texture src={t} width={windowSize().width}
+                             height={windowSize().height}
+                             {...useScene().scene.handlersFor(windowSize)} />}>
+```
+
+`windowSize` and `displayScale` come from `@solidrt/core`. The leaf's
+layout differs from the target, so it takes `handlersFor` (below), not
+`handlers`; `useScene()` works inside `output` because it runs in the
+scene context.
+
 Camera control: `createOrbitCamera(scene, { target?, azimuth?, elevation?,
 distance?, min/maxDistance?, min/maxElevation?, orbitSpeed?, rotateSpeed?,
 zoomSpeed?, zoomAnchor?, rotateAnchor?, panSpeed?, viewport?, clampTarget? })`
@@ -321,8 +349,10 @@ uint16/uint32 indices by vertex count automatically.
 
 Materials:
 
-- `unlit({ color?, map? })` - straight `[r, g, b, a?]` 0..1, premultiplied
-  internally.
+- `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
@@ -416,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
@@ -472,17 +533,27 @@ the directional list, Lambert diffuse, Blinn-Phong highlight when
 `specular` (0..1 strength) is set with `shininess` (default 30), the
 same `color`/`map`/`transparent` as unlit, `vertexColors: true` to
 multiply by the colored layout's aColor (so the geometry must carry it),
-and `triplanar: n` to sample `map` by world position at `n` repeats per
-world unit, blended across the three axis planes by the normal. Triplanar
+`triplanar: n` to sample `map` by world position at `n` repeats per
+world unit, blended across the three axis planes by the normal, and
+`alphaTest: t` for a cutout (a fragment whose final alpha is below `t`
+is discarded; Three's alphaTest, glTF MASK): opaque, depth-written, no
+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
-combination (map x vertexColors x triplanar x transparent), cached for
-the app's lifetime, one pipeline per vertex layout - a thousand lit
-meshes share one program. The view vector comes from the shared uCamPos;
-`uTriplanar` is declared only by the triplanar classes so the other
-classes do not warn about an inactive uniform.
+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
+shared uCamPos; `uTriplanar` and `uAlphaTest` are declared only by the
+classes that use them (the cutoff is a per-entry value, so every
+alphaTest material shares one class) so the other classes do not warn
+about an inactive uniform.
 
 ## Models
 
@@ -494,7 +565,8 @@ next to it, or single-file .glb) and become a Group of meshes, Three's
   bun and on flux): `ModelData` = `parts` (one per mesh node, its NAME
   kept, vertices in the standard layout with the node's WORLD transform
   baked in), `materials` (base color factor, `map` = index into `images`,
-  `doubleSided`, `transparent` = alphaMode BLEND), `images` (the encoded
+  `doubleSided`, `transparent` = alphaMode BLEND, `alphaMode` as written
+  and `alphaCutoff`, spec default 0.5), `images` (the encoded
   PNG/JPEG bytes, undecoded) and `bounds`. A .gltf's external files come
   through `resolve(uri)` (uri as written, still percent-encoded;
   `gltfExternalUris(bytes)` lists them so an async caller can read them
@@ -507,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)`,
@@ -526,10 +598,10 @@ next to it, or single-file .glb) and become a Group of meshes, Three's
   "binary" }` then `createModel(parseGltf(bytes))`, see
   `examples/model.tsx`); bake anything big.
 
-Not in the subset, reported or dropped: `doubleSided` is reported and NOT
-applied (the standard materials cull back faces); vertex colors, tangents
-and further UV sets are dropped; samplers are ignored (every texture
-repeats); alphaMode MASK draws opaque; emissive/additive parts of a model
+Applied: `doubleSided` (the default material draws it with `cull:
+"none"`) and alphaMode MASK (`alphaTest: alphaCutoff`). Not in the
+subset, dropped: vertex colors, tangents and further UV sets; samplers
+are ignored (every texture repeats); emissive/additive parts of a model
 draw as their base color (a model's "glow" cards come out as dark wedges).
 The follow-ups are filed in okf/backlog/3d-model-loader.md.
 
@@ -568,7 +640,13 @@ The follow-ups are filed in okf/backlog/3d-model-loader.md.
   are opaque to the library, so any inferred box would be a guess. Supply
   `bounds` for anything pickable or transparent.
 - Transparency is an EXPLICIT material flag, Three's rule: `unlit({ color:
-  [r, g, b, 0.5] })` still draws opaque; `unlit({ ..., transparent: true })`
+  [r, g, b, 0.5] })` still draws opaque, and opaque means it: the standard
+  classes write alpha 1 when not `transparent` (the scene target is
+  composited premultiplied, so a leaked texel or color alpha would punch
+  a see-through hole in an opaque draw - the source of "white cutouts"
+  on an alpha-mapped model drawn without alphaTest). A `shaderMaterial`
+  writes its own fragColor: give an opaque look alpha 1 too.
+  `unlit({ ..., transparent: true })`
   (or `shaderMaterial({ transparent: true })`) builds the pipeline with
   `blend: "alpha"` and `depthWrite: false` (depth test stays on, so it hides
   behind opaques without occluding other translucents). The one inference:
@@ -675,7 +753,14 @@ The follow-ups are filed in okf/backlog/3d-model-loader.md.
   `shadow.normalBias` (world units along the receiver normal, the one to
   reach for first, ~0.02); the depth pass culls FRONT faces (Three's
   shadowSide default), so closed casters need little bias but a
-  single-sided plane casts nothing. Opting out of receiving is on the
+  back-culling plane casts only from its back. The shadow side follows
+  the material's `cull` (Three's shadowSide rule, Godot's shadow pass):
+  a `cull: "none"` foliage card or pane casts from both faces, and a
+  UV-mapped `alphaTest` material casts its cutout (leaves, not
+  rectangles), through the `Material.shadow` variant the standard
+  classes carry (a `shaderMaterial` gets the cull side from its `cull`
+  and supplies its own cutout variant as the `shadow` instance option).
+  Opting out of receiving is on the
   MATERIAL here (`receiveShadow: false`), not the object (Three's
   `mesh.receiveShadow`) - Godot's split, and URP's - and instanced
   meshes never cast (the depth override cannot know their records) - the
@@ -752,12 +837,13 @@ The follow-ups are filed in okf/backlog/3d-model-loader.md.
   vertex source - a comment counts - selects the "colored" layout, and
   the material then rejects standard geometry at add(). Do not mention
   aColor you do not read.
-- Picking is the VOLUME tier: a hit means the ray crossed the mesh's
-  transformed bounding box, not its surface. Never present `point` as a
-  surface point (it is the box-entry point), and never add a
-  triangle-accurate path in JS - per-triangle rays at mesh scale are
-  interpreter-hostile; that tier is core work (BVH descent per the
-  differentiators ladder).
+- Picking is triangle-accurate for ordinary meshes (`point` is a surface
+  point, hits carry `face`/`uv`/`normal`) but box-only for instanced
+  meshes: there `point` is the entry point of the population `bounds`
+  box, and `face`/`uv`/`normal` are absent. Never present an instanced
+  hit as a surface hit. Both tiers run in the spatial core (Rust); never
+  add a per-triangle path in JS - rays at mesh scale are
+  interpreter-hostile, and the core already does it.
 - `scene.handlers` vs `handlersFor`: localX/localY arrive in the leaf's
   LAYOUT frame (every ancestor transform and design-size fit is already
   undone by the element hit test). `handlers` therefore assumes leaf
@@ -766,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.53",
+  "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.53"
+    "@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/gltf.ts

@@ -30,11 +30,16 @@ export type ModelMaterial = {
   color: [number, number, number, number]
   /** Index into ModelData.images (the base color texture), or null. */
   map: number | null
-  /** glTF doubleSided. Reported, not applied: the standard materials cull
-   * back faces. */
+  /** glTF doubleSided; createModel's default material draws it with
+   * `cull: "none"`. */
   doubleSided: boolean
-  /** alphaMode BLEND. MASK draws opaque (no alpha test). */
+  /** alphaMode BLEND; createModel's default material blends it. */
   transparent: boolean
+  /** glTF alphaMode as written (default OPAQUE). MASK is a cutout:
+   * createModel's default material draws it with `alphaTest: alphaCutoff`. */
+  alphaMode: "OPAQUE" | "MASK" | "BLEND"
+  /** glTF alphaCutoff (default 0.5); meaningful for MASK only. */
+  alphaCutoff: number
 }
 
 /** One drawable: a mesh node's primitive, vertices in WORLD space. */
@@ -67,10 +72,21 @@ const CHUNK_JSON = 0x4e4f534a
 const CHUNK_BIN = 0x004e4942
 const MODE_TRIANGLES = 4
 
+// The spec's alphaCutoff when a MASK material leaves it out.
+const GLTF_ALPHA_CUTOFF = 0.5
+
 const COMPONENT_BYTES: Record<number, number> = { 5120: 1, 5121: 1, 5122: 2, 5123: 2, 5125: 4, 5126: 4 }
 const TYPE_ELEMENTS: Record<string, number> = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT2: 4, MAT3: 9, MAT4: 16 }
 
-const DEFAULT_MATERIAL: ModelMaterial = { name: "default", color: [1, 1, 1, 1], map: null, doubleSided: false, transparent: false }
+const DEFAULT_MATERIAL: ModelMaterial = {
+  name: "default",
+  color: [1, 1, 1, 1],
+  map: null,
+  doubleSided: false,
+  transparent: false,
+  alphaMode: "OPAQUE",
+  alphaCutoff: GLTF_ALPHA_CUTOFF,
+}
 
 /** True when the bytes are a .glb container (the "glTF" magic). */
 export function isGlb(bytes: Uint8Array): boolean {
@@ -171,6 +187,8 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
       map,
       doubleSided: m.doubleSided === true,
       transparent: m.alphaMode === "BLEND",
+      alphaMode: m.alphaMode === "MASK" || m.alphaMode === "BLEND" ? m.alphaMode : "OPAQUE",
+      alphaCutoff: typeof m.alphaCutoff === "number" ? m.alphaCutoff : GLTF_ALPHA_CUTOFF,
     }
   })
   // Primitives without a material draw the spec's default; it is appended