Skip to Content
Engine Internals & ResearchHook invocation internals

Hook invocation internals

Target API: 5 · Target build: bbb6l5 (2026-11-20, production and preprod) · Status: Analyzed (restored from the production bundle — the Lite renderer; the integrated source file lite/terrainShaderPack.ts survives in error strings)

How the engine calls hooks at runtime. This changes nothing about the code you write, but removes the guesswork about what hooks receive.

The splice architecture

The renderer does not “call” hooks from JavaScript. Once a pack passes validation, the engine grafts your hook invocations into its terrain WGSL by replacing fixed anchor lines in the shader text. Each anchor must match exactly once — zero or multiple matches abort with at the shader pack ${hook} hook: ${no|more than one} anchor (lite/terrainShaderPack.ts).

StageAnchor in the engine shaderWhat is grafted
vertexthe let worldPos = … through vertexOutputs.vNormalW = … blockbuild BloxdVertexIn, call the vertex hook, write worldPos back (also rewriting let worldPos to var worldPos)
surfacebaseColor = vec4f(baseColor.rgb * fragmentInputs.vColor, baseColor.a);build BloxdSurfaceIn, call the surface hook, write baseColor / alpha back
lit colorjust before the fog mixcaptures the pre-fog color (v3 used the bloxdSpLitColour temporary — v5 promotes this role into the public bloxdLitColour() header function)
lightthe return color; at the fragment shader’s endbuild BloxdLightIn, call the light hook, write color back — after the fog mix

What the splice forces

  • strict terrain ignores surface-hook alpha changes. The alpha = bloxdSpSurface.alpha write-back is grafted only for the liquid program or non-strict variants — the implementation behind the macro table (Preprocessor)
  • A strict variant that declares a vertex hook never runs it. The engine reports at build time: Shader pack code ${variant} is strict and has a vertex hook, which strict mode never runs. Hence the template’s #ifndef BLOXD_STRICT
  • bloxdSp* identifiers are engine temporaries — invisible to your code but present in diagnostics and reverse-engineering output (Reserved identifiers — 46 in v5)
  • The default-surface shortcut. If a variant’s surface hook is literally bloxdDefaultSurface, the engine omits the baseColor / alpha write-back graft entirely — the default already produces those values, so the assignments are dead code. Unmodified hook chains cost nothing

What changed in v5

The splice architecture existed in the v2 renderer and stayed stable across v2 → v3 (v3 only changed vBlockId → vBlockFlags and added the liquid variant). v5’s changes:

  • vBlockFlags (bits) → the BloxdFlags struct (delivered via bloxdSpFlags)
  • the litColour capture went from engine-internal to public API (bloxdLitColour() — v4’s bloxdSpLitColour promoted)
  • BloxdLightIn gained diffuse / emissive, and bloxdShading() rebuilds the material response (Lighting)
  • delivery of localPosition (bloxdSpItemLocalPosition), enchant inputs (bloxdSpEnchant) and overlayColour (Model rendering)
  • fogVisibility → fogAlpha (inverted)
  • the Model program joined the variant matrix (3 programs × 2 modes = 6 variants)

What feeds BloxdLightIn (per field)

FieldEngine-side source
litColourthe fragment color captured just before the fog mix — “before emission and fog” in header terms
directionalthe vertex-interpolated sum of per-directional-light Lambert (2-light setup in Rendering pipeline)
diffuse / emissivethe material’s directional RGB response / RGB glow
ambientmaterial.ambient × sceneAmbient — per material, per frame
blockLight / skyLightthe decoded light-level varyings (Lighting internals)
ambientLightColour / skyLightColourthe corresponding uniforms
heldLightbuilt from the light-level varying and held-light uniforms (cone falloff in Lighting internals)
fogColourblack only in entirely fog-less scenes (mode 0)
fogAlphathe clamped fog factor (Fog internals)
position / normal / localPosition / flags / textureId / textureRotation / uv / mipLevelvaryings and flat-interpolated values (same as BloxdSurfaceIn — post-vertex-hook values)