Skip to Content
API ReferenceShader hooks

Shader hooks

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

Packs can define 9 hooks — 3 render targets (programs) × 3 pipeline stages, all optional (undefined means engine default).

9-hook comparison

HookProgramStageArgumentsReturnsRun condition
bloxdTerrainVertexTerrainvertexBloxdVertexInBloxdVertexallow variants only (defining it in strict is itself an error)
bloxdTerrainSurfaceTerrainsurfaceBloxdSurfaceInBloxdSurfacealways
bloxdTerrainLightTerrainlightBloxdSurface, BloxdLightInBloxdLightalways
bloxdLiquidVertexLiquidvertexBloxdVertexInBloxdVertexallow only
bloxdLiquidSurfaceLiquidsurfaceBloxdSurfaceInBloxdSurfacealways
bloxdLiquidLightLiquidlightBloxdSurface, BloxdLightInBloxdLightalways
bloxdModelVertexModelvertexBloxdVertexInBloxdVertexallow only
bloxdModelSurfaceModelsurfaceBloxdSurfaceInBloxdSurfacealways
bloxdModelLightModellightBloxdSurface, BloxdLightInBloxdLightalways

What each program draws

ProgramDrawsWater when no Liquid hook exists
Terrainevery block except water and block models—
Liquidwaterno Terrain hook runs on water either (water keeps its default look)
Modelblock models (slabs, stairs, plants, crops, cobwebs), held/dropped/thrown items, players, mobs, NPCs, armour, cosmetics—

Stage roles

  • Vertex — move vertex positions (grass sway, waves). Vertex animation disables the whole pack in strict games, so #ifndef BLOXD_STRICT is mandatory
  • Surface — the material output: colour / alpha (conditional) / emission / enchantColour / overlayColour
  • Light — the final color; takes the surface output plus BloxdLightIn. Its return value is the on-screen color

Signatures

fn bloxdTerrainVertex(vertex: BloxdVertexIn) -> BloxdVertex { return bloxdDefaultVertex(vertex); } fn bloxdTerrainSurface(surface: BloxdSurfaceIn) -> BloxdSurface { return bloxdDefaultSurface(surface); } fn bloxdTerrainLight(surface: BloxdSurface, light: BloxdLightIn) -> BloxdLight { return bloxdDefaultLight(surface, light); } // bloxdLiquid* / bloxdModel* take the same argument and return types

Special-function call restrictions

The engine’s validator restricts which hooks may reach certain functions (violations fail with dedicated “reaches” diagnostics):

FunctionCallable fromGuard
bloxdTexelsurface / light hooks only—
bloxdTextureSizesurface / light hooks only—
bloxdOpaqueBehindsurface / light hooks (meaningful in liquid variants)#ifdef BLOXD_SCENE_DEPTH

bloxdFragmentBlockPosition is no longer in the documented header, but the engine still injects and accepts it — see Functions: bloxdFragmentBlockPosition. It was the one special function callable from vertex hooks; for new code prefer flags for “which block is this”.

Fallbacks and sharing

  • Undefined hook → that stage behaves as the engine default (bloxdDefaultVertex / bloxdDefaultSurface / bloxdDefaultLight)
  • Share processing across hooks with a module-scope function called from both:
fn sharedSurface(s: BloxdSurfaceIn) -> BloxdSurface { var out = bloxdDefaultSurface(s); out.colour *= vec3f(1.02); return out; } fn bloxdTerrainSurface(surface: BloxdSurfaceIn) -> BloxdSurface { return sharedSurface(surface); } fn bloxdModelSurface(surface: BloxdSurfaceIn) -> BloxdSurface { return sharedSurface(surface); }