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 filelite/terrainShaderPack.tssurvives 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).
| Stage | Anchor in the engine shader | What is grafted |
|---|---|---|
| vertex | the let worldPos = … through vertexOutputs.vNormalW = … block | build BloxdVertexIn, call the vertex hook, write worldPos back (also rewriting let worldPos to var worldPos) |
| surface | baseColor = vec4f(baseColor.rgb * fragmentInputs.vColor, baseColor.a); | build BloxdSurfaceIn, call the surface hook, write baseColor / alpha back |
| lit color | just before the fog mix | captures the pre-fog color (v3 used the bloxdSpLitColour temporary — v5 promotes this role into the public bloxdLitColour() header function) |
| light | the return color; at the fragment shader’s end | build 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.alphawrite-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 thebaseColor/alphawrite-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) → theBloxdFlagsstruct (delivered viabloxdSpFlags)- the
litColourcapture went from engine-internal to public API (bloxdLitColour()— v4’sbloxdSpLitColourpromoted) BloxdLightIngaineddiffuse/emissive, andbloxdShading()rebuilds the material response (Lighting)- delivery of
localPosition(bloxdSpItemLocalPosition), enchant inputs (bloxdSpEnchant) andoverlayColour(Model rendering) fogVisibility→fogAlpha(inverted)- the Model program joined the variant matrix (3 programs × 2 modes = 6 variants)
What feeds BloxdLightIn (per field)
| Field | Engine-side source |
|---|---|
litColour | the fragment color captured just before the fog mix — “before emission and fog” in header terms |
directional | the vertex-interpolated sum of per-directional-light Lambert (2-light setup in Rendering pipeline) |
diffuse / emissive | the material’s directional RGB response / RGB glow |
ambient | material.ambient × sceneAmbient — per material, per frame |
blockLight / skyLight | the decoded light-level varyings (Lighting internals) |
ambientLightColour / skyLightColour | the corresponding uniforms |
heldLight | built from the light-level varying and held-light uniforms (cone falloff in Lighting internals) |
fogColour | black only in entirely fog-less scenes (mode 0) |
fogAlpha | the clamped fog factor (Fog internals) |
position / normal / localPosition / flags / textureId / textureRotation / uv / mipLevel | varyings and flat-interpolated values (same as BloxdSurfaceIn — post-vertex-hook values) |