Skip to Content

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

  1. Loader limits (zip / pack.json shape) → Pack format
  2. Static validation (analyzer) — this page; syntax, types, reserved names, hook contracts across all 6 variants
  3. Real browser compilation → WGSL compilation
  4. 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: true special 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/i general 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 blockFlags or referencing bloxdBlockFlag* 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.