# Environment design techniques catalog

A categorized catalog of the concrete graphics techniques used to build
high-quality, detailed, and lightweight 3D Environments in Al-Amr. Each entry
says what the technique is and where/why it is used, in one or two lines. For
deep, code-referenced walkthroughs see
[Park zones 3D techniques](./park-zones-3d-techniques.md).

## Where this lives

- `environments/hub/src/world/` — the worked examples for most techniques
  below, under `materials`, `systems`, `post` and `zones`.
- `environments/hub/src/world/lighting-rig.ts` and
  `environments/hub/src/world/palette.ts` — the lighting and colour decisions
  these techniques are tuned against.
- `packages/r3f/src/EnvironmentCanvas.tsx` and
  `packages/r3f/src/renderer-factory.ts` — the WebGPU-first canvas and the real
  WebGL2 fallback every technique here has to survive.
- `quality/rendering-profile.json` — the budgets a technique may not exceed.

## 1. Textures and materials

- **Normal maps** — tree trunks and rocks use normal maps so the surface reads
  as rough bark or stone without extra geometry; light bends over fake relief.
- **Procedural canvas textures** — bark and rock textures are generated at
  runtime on a 2D canvas from pure trigonometric height fields; no image files
  are shipped.
- **Height-field to normal map (Sobel)** — the normal map is derived from the
  procedural height field with Sobel central differences, once per source
  lifetime.
- **Roughness modulation** — ground roughness is modulated by the same
  micro-noise as the color, so sunny crests look dry and wet banks look glossy.
- **Gradient color ramps** — meadows, foliage, and water bodies blend 2–3
  authored colors (deep/meadow/sunlit) with noise instead of using albedo
  textures.
- **Detail (micro) texture** — a high-frequency sine product adds blade-level
  grain that only appears in close view; distant pixels stay cheap.
- **Emissive materials** — sun disc, water glints, and waterfall spray use
  emissive output so selective bloom can pick exactly them up.
- **Layered material terms** — the shared flora surface stacks optional terms
  (mottle, patch, rim light, sunlit tips, moss) on one gradient base graph.

## 2. Lighting

- **Directional sun light** — one shadow-casting `directionalLight` per zone,
  aligned with a shared world sun direction so zones stay consistent.
- **Hemisphere fill light** — sky/ground bounce faked with one
  `hemisphereLight`; cheap ambient with no extra shadow cost.
- **Shadow mapping** — orthographic shadow frustum authored per zone; map size
  is the quality lever (2048 enhanced, 1024 otherwise).
- **Shadow toggling over shadow shrinking** — at the lowest tier, foliage
  `castShadow` is removed entirely instead of lowering resolution further.
- **Emissive-as-light trick** — HDR emissive accents (glints, sparks, spray)
  glow through bloom, giving a lit feel without real light sources.

## 3. Shader effects

- **FBM noise** — fractal Brownian motion over `mx_noise_float` builds the sky
  clouds; octave count is set at graph build time per quality tier.
- **Amplitude-normalized FBM** — the noise sum is divided by the amplitude sum
  so cloud coverage thresholds read identically at every tier.
- **Directional sine waves** — water surfaces layer 3 directional sine waves;
  analytic cosine slopes give the normal field with no finite differences.
- **Fresnel** — water lifts sky color at grazing view angles (power-5 fresnel),
  the classic cheap reflectivity cue.
- **HDR sun glint (specular sparkle)** — `pow(sunAmount, 340)` plus a twinkle
  term creates the hard sun sparkle on water, fed to bloom via emissive.
- **Caustics** — interfering directional sine sets, sharpened with a power and
  masked by depth, fake moving caustic light on submerged beds.
- **Whitewater from multiplied sine bands** — waterfall foam multiplies two
  sine bands (deliberately no expensive noise), so it costs the same at every
  tier.
- **Screen-door dithering** — foliage near the camera fades by stochastic
  discard instead of transparency; sorting and blending stay untouched.
- **Direction-based sky gradient** — zenith-to-horizon blend with sun-side
  horizon warming (`pow(saturate(cosSun), 3)`).
- **Slope-based tinting** — the local normal's Y decides where ground turns to
  rock; steep slopes get grey-cream stone, meadows never do.

## 4. Geometry and mesh techniques

- **GPU instancing** — all vegetation, petals, debris, and mist are
  `InstancedMesh`: one draw call per batch regardless of instance count.
- **Per-instance attributes** — tint, scale, stretch, and animation phase vary
  per instance through instanced attributes and `instanceColor`.
- **Vertex welding (`mergeVertices`)** — canopy polyhedra are welded, then
  shared vertices are displaced by a seeded hash and normals recomputed:
  watertight organic silhouettes with no cracks.
- **Billboards** — waterfall impact mist uses camera-facing quads (sprites)
  that rise, spread, and fade; volume faked with a handful of planes.
- **Polar displaced disc terrain** — the ground mesh is a polar grid displaced
  by a pure height function; ring/radial segment counts scale per tier.
- **Ribbon meshes for flowing water** — the river is flat ribbons following a
  winding centerline; a vertical curtain mesh forms the waterfall.
- **Distance stride culling (in-shader LOD)** — far instances are culled inside
  the shader by index modulo (half at mid range, quarter at far); the draw call
  stays, the vertex cost drops.
- **Inflated bounding volumes** — instanced bounds are inflated by the max wind
  displacement so frustum culling stays correct while vertices move on GPU.

## 5. Animation techniques

- **Vertex-shader wind** — trees and grass sway by GPU vertex displacement,
  weighted between species anchors (base/top Y), with per-instance phase from a
  salted hash.
- **UV/texture scrolling** — river flow scrolls sine bands over flow-metre UVs,
  so separate water stretches move at one world speed.
- **Quadratic waterfall acceleration** — the curtain's coordinates are warped
  with `v + v*v*0.9` so falling water visibly accelerates.
- **Shared time uniforms** — one time uniform per material drives all motion;
  a global motion scale slows everything on low tiers and freezes it for
  reduced-motion users.
- **Vertex displacement waves** — the pond's physical wave (≈0.04 m) is done in
  `positionNode`, inside the authored freeboard margin.

## 6. Sky and atmosphere

- **In-scene sky dome** — a `BackSide` sphere whose color is computed from the
  view direction; geometry instead of a screen-space sky effect.
- **Far-plane pinning** — `clip.z = clip.w` in the vertex shader pins the dome
  to the far plane, independent of camera distance.
- **Camera-following dome** — the dome copies the camera position each frame
  and renders first with depth write off, always behind world meshes.
- **Projected cloud layer** — FBM clouds are sampled on a virtual plane above
  the head and drift with time.
- **HDR sun disc and halo** — the sun is an HDR disc with a tight golden halo
  routed through emissive so bloom blooms exactly it.
- **Fog matched to the horizon** — linear scene fog uses exactly the dome's
  horizon-halo color, so terrain edges dissolve into the sky seamlessly.

## 7. Water techniques

- **Depth-graded body color** — water color lerps from warm shallow tint to
  deep body color by depth, instead of real refraction.
- **Underwater caustic light** — animated caustic patterns play on the riverbed
  and plunge-pool floor (see caustics above).
- **Impact foam ring** — an expanding foam ring radiates from the authored
  waterfall impact point on the plunge pool.
- **Floating foam patches and debris** — instanced leaves/foam ride the river
  surface on a flow loop, positioned by the river's own math.
- **Edge fade (soft banks)** — water opacity fades at banks and curtain edges
  to hide the mesh intersection line.
- **No real-time reflections** — no reflector/planar-reflection pass; fresnel +
  sky color + glints fake reflectivity and keep draw calls flat.

## 8. Vegetation techniques

- **Species variety from instanced batches** — multiple tree species (broadleaf,
  poplar, willow) share one instancing stack with per-species sway anchors.
- **Anchored scatter** — petal nests anchor to seeded trees, so ground petals
  read as blossom fall rather than random confetti.
- **Color veins via cell hashing** — a coarse 16 m cell hash assigns palette
  indices so neighboring plants share hues and form colored drifts.
- **Trunk + canopy pairing** — trunks and canopies share an instancing stride
  id so one plant sways and thins out together.
- **Canopy silhouette over leaf detail** — welded, displaced polyhedra give
  organic crowns; no per-leaf geometry at all.

## 9. Post-processing

- **MRT (multi-render-target)** — the scene renders once into `output` +
  `emissive` attachments; bloom reads only the emissive one.
- **Selective bloom** — bloom applies only to emissive pixels (sun, glints,
  spray) instead of thresholding the whole frame.
- **ACES filmic tone mapping** — the classic filmic curve maps HDR to display
  range; applied exactly once per render path.
- **FXAA** — cheap fullscreen anti-aliasing at the end of the chain, on
  tone-mapped (display-referred) pixels.
- **Exposure as the art lever** — `toneMappingExposure` is a live uniform;
  mood changes are uniform writes, never pipeline rebuilds.
- **Direct-render fallback** — the lowest tier skips the whole pipeline
  (no MRT/bloom/FXAA) with a plain render and per-material tone mapping.

## 10. Deterministic scatter and placement

- **Seeded PRNG (xorshift32)** — all placement is deterministic from one seed;
  the scene is identical on every visit and testable without a GPU.
- **Independent substreams** — each batch (trees, grass, petals, debris) XORs
  its own substream key so changing one count never reshuffles another batch.
- **Acceptance-ring scatter** — groves plus singles are distributed with a
  distance grid for natural clumping without overlaps.
- **Layout exclusions** — spawn clearing, portal clearing, view corridor, and
  water bodies stay empty so the first view is always composed and walkable.