Shader validation
Target API: 5 · Target build:
bbb6l5(2026-11-20, production and preprod) · Status: Analyzed (restored from the live validator)
The static validation (analyzer, stage 1 of the load check). User-facing fixes: Validation errors.
The stages
- Loader limits (zip / pack.json shape) → Pack format
- Static validation (analyzer) — this page; syntax, types, reserved names, hook contracts across all 6 variants
- Real browser compilation → WGSL compilation
- Runtime re-validation on game join — actually compiles every existing terrain material (stricter than the settings-screen check); failing it drops the pack for that game
The special-function signature table
The validator keeps a cross-hook call restriction table:
const Jq = new Map([
["bloxdFragmentBlockPosition", { params: "position: vec3f, normal: vec3f", returns: "vec3i", symbol: null, vertex: true }],
["bloxdOpaqueBehind", { params: "", returns: "BloxdOpaqueBehind", symbol: "BLOXD_SCENE_DEPTH" }],
["bloxdTexel", { params: "textureId: u32, uv: vec2f, mipLevel: f32", returns: "vec4f", symbol: null }],
["bloxdTextureSize", { params: "mipLevel: f32", returns: "vec2u", symbol: null }],
]);Restored logic:
- calling a non-
vertex: truespecial function from a vertex hook → “X reaches Y, which only surface and light hooks can use.” - a function with a
symbol(bloxdOpaqueBehind→BLOXD_SCENE_DEPTH) reached from a variant that doesn’t define that macro → “X reaches Y, which needs BLOXD_SCENE_DEPTH, and Z doesn’t define it; in code other programs’ hooks share, guard the call with #ifdef BLOXD_SCENE_DEPTH.”
Note: bloxdFragmentBlockPosition is gone from the header generation, but its entry remains in this live table — and the table is what the identifier check consults, so calls still pass validation. The code generator also still injects the definition (terrain/liquid and both model programs), so the function remains callable in practice. Treated as deprecated: undocumented, and may be dropped in any future version.
Reserved-name diagnostics
- the
/^bloxd/igeneral rule: “Packs can’t declare names starting with bloxd, other than the hook functions bloxd<Terrain|Liquid|Model><Vertex|Surface|Light>” - direct texture/sampler declarations: “Packs can’t use X: the engine binds every texture and sampler. Surface and light hooks can read atlas textures with bloxdTexel.”
Texture-name resolution & diagnostics
bloxdTextureId* resolution has a dedicated path (the messages):
- folding: split on non-alphanumerics, CamelCase, prefix with
bloxdTextureId; reverse matching is case/underscore-insensitive - spelling suggestions (new in v5): unmatched names get Levenshtein proposals at threshold
max(2, floor(len/4)) + 1 - dedicated messages for frame spellings and turned-copy spellings
- post-fold ambiguous names are unusable
v5’s new diagnostics
- “BLOXD_LIGHTING was removed in apiVersion 5; test bloxdLit() in code instead.” — names the removed macro
- packs reading
blockFlagsor referencingbloxdBlockFlag*fail the reserved-name diagnostic — no pack misbehaves silently
The Y-derivative rewrite
The analyzer’s token-rewrite pass rewrites every dpdy / dpdyCoarse / dpdyFine call to (-dpdy(...)) (the dpdy family is explicitly enumerated as the inversion set). dpdx and fwidth are untouched (Restrictions).
Header & texture-constant generation
- the header is prepended read-only (Engine header)
- the
bloxdTextureId*block is generated per pack from referenced names
HEADER_VERSION
HEADER_VERSION is 9.<fnv1a32(header)>.<fnv1a32(texture registry)> (leading integer 8 → 9 from v4). The two fnv1a32 suffixes fingerprint the header material and the sorted name-id registry. Saved-pack re-validation uses this fingerprint to decide “needs re-check” (Compatibility).
Validation stubs
Code that passes static validation gets stub code synthesized before the real browser-WGSL check: var<private> bloxdValidationP: vec4f plus bloxdValidateVertex / bloxdValidateFragment — the type-stub table (bool → p.x > 0.0, vec3f → p.xyz, …) builds input structs and invokes the hooks. Details: WGSL compilation.