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)
| Operation | Cost | Note |
|---|---|---|
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
- Gate effects to the faces that need them —
flagsselection beats “+20% everywhere” - Drop detail with distance — early-out when
distance(surface.position, bloxdEyePosition())exceeds a threshold - Use mips —
bloxdTexel(id, uv, mipLevel + 1.0)is a ¼-resolution average (worked examples) - Prefer surface hooks for color tweaks — the light hook is the all-pixels final stage
- Add detail incrementally and compare FPS (testing)
#ifdefguards 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