Skip to Content
GuidesPerformance

Performance

Target API: 5 · Target build: bbb6l5 (2026-11-20, production and preprod) · Status: Verified (measurement-based practice)

Pack hooks run on every fragment (all pixels of terrain / liquid / model), so style choices move frame rate significantly.

First facts

  • The light hook is the final stage: it runs for every drawn pixel of terrain, liquid and model — most of the screen
  • Packs run on WebGPU: evaluate cost assuming a range of GPUs including mobile
  • The loader’s size cap (256 KB of .wgsl) is also a practical compile-time ceiling

Cost ladder (cheap → expensive)

OperationCostNote
mix / clamp / arithmetic◎ minimal
input reads (l.skyLight…)◎uniform/vertex-attribute sourced
smoothstep / pow○pow varies by exponent
sin / cos○animation staple
dot / normalize○
bloxdTexel() (texture sample)△cheaper at higher mips
dpdx / dpdy / fwidth△surface/light hooks only
branching (if)△WGSL may evaluate both sides; uniform-ish conditions (flag checks) are cheap
hash noise (many sin/fract)△gate micro-bump effects by distance

Practice

  1. Gate effects to the faces that need them — flags selection beats “+20% everywhere”
  2. Drop detail with distance — early-out when distance(surface.position, bloxdEyePosition()) exceeds a threshold
  3. Use mips — bloxdTexel(id, uv, mipLevel + 1.0) is a ¼-resolution average (worked examples)
  4. Prefer surface hooks for color tweaks — the light hook is the all-pixels final stage
  5. Add detail incrementally and compare FPS (testing)
  6. #ifdef guards don’t save runtime — variants are compile units; runtime savings come from flags and distance

Measuring

  • Compare FPS with/without the pack via browser devtools (performance panel / WebGPU stats)
  • Measure terrain-heavy scenes (shadow-rich forest) and water (liquid hooks) separately
  • Check mobile hardware — it can be tens of times slower