API v5 migration guide
Version: 5 · Status: Historical (migration guide of the era; the target build is noted in the text) Target build:
ab90qa.main.6188124c.js— live on production and preprod simultaneously (measured 2026-11-03), so everything here applies to production as-is. This is the biggest API revision since v3. What is visible: the engine header grew from 6,021 to 8,954 decoded bytes (151 → 208 lines) — almost every struct gained fields, four new functions document the engine’s own lighting recipe, and theblockFlagsbitmask is gone, replaced by a properBloxdFlagsstruct of booleans. The#ifdef BLOXD_LIGHTINGcompile-time gate is gone too: lighting state moved into the per-frame uniform as alit: u32member and is queried at runtime withbloxdLit(). The default pack template now ships all nine hooks instead of six. And thebloxdSp*engine-internal namespace grew from 27 to 46 symbols.
Re-verified, in order, on every production build since: xkg8x (2026-11-04 — the header byte-identical, every loader / variant / hook / reserved-name measurement unchanged, the registry moved 896 → 906 usable names; §80); 2lcqcl preprod (different main bundle, identical on every shader-pack surface); bny9u (2026-11-05 — header, default pack template, loader limits, uniform layout, hooks, variants, macros, reserved names and validation messages all unchanged; registry 906 → 911; game definitions 111 → 115); v98qt8 (2026-11-08 — same frozen API surface, registry 911 → 906, game definitions 115 → 116, plus the texture-constant folding regression); and bbb6l5 (2026-11-20 — the first v5-era surface change: the uniform grew to 80 bytes with shadowDirection, the real sun/moon shadow functions bloxdShadow() / bloxdAirShadow() joined the API, pack.json gained keepCircleShadows, the folding regression was fixed, and the registry grew to 1,650 layers / 1,017 usable names; §80 addendum). The apiVersion stays 5 through all of it — v5 packs written for the launch build still load unchanged.
The v5 change set in one screen:
| Area | v4 | v5 |
|---|---|---|
pack.json apiVersion | 4 (strict) | 5 (strict) — v4 packs are rejected at load |
| Block identity | blockFlags: u32 + 6 bloxdBlockFlag* bit constants | flags: BloxdFlags — 14 named bool fields (§71) |
| New flag kinds | — | slab stairs flat placed held dropped thrown lifeform — models and entities are now distinguishable from terrain (§71) |
| Model position | — | localPosition: vec3f on every input struct (§72) |
| Enchant & overlay | engine-only | enchantTier / enchantColour / enchantSpeed / overlayColour inputs + outputs (§72–§73) |
| Lighting gate | #ifdef BLOXD_LIGHTING (compile-time, 8 variants) | removed — uniform gains lit: u32 @ offset 4; test bloxdLit() at runtime; 6 variants (§74) |
| Lighting helpers | engine-private litColour | public: bloxdShading(), bloxdWorldLight(), bloxdLitColour() (§74) |
bloxdFragmentBlockPosition() | documented in the header | out of the documented header — but still injected and still accepted by the validator (§75) |
| Default pack | 6 hooks (vertex+surface) | 9 hooks — light hooks included (§76) |
bloxdChunkSize | not in header | new const bloxdChunkSize: i32 = 32 (§78) |
bloxdSp* namespace | 27 symbols | 46 symbols (+20, −1) (§79) |
| Texture registry | 905 usable names | 896 usable names — +1, −10 (§80) |
Loader limits, zip rules, pack.json shape, hooks names, strict contract | — | frozen, byte-identical limits (§70) |
Conversion from v4 is mostly mechanical (§77): the one silent trap is different this time — a pack that still reads blockFlags or guards light hooks with #ifdef BLOXD_LIGHTING fails validation with a specific message (the analyzer now explains both), so nothing silently misbehaves; but a pack that only reads the old bit constants by name will refuse to load until ported. As always, verify with an in-game compile before distributing.
69. Fate of v4 packs (conclusion first)
Every v4 pack — including every pack distributed as v4 — now fails on production exactly at load. The loader compares manifest.apiVersion !== 5 with strict JavaScript !== — the version constant 5 and the header template live in the same module in this build (module 29836), so the check and the header text it validates against move together. The JSON must carry the number 5; a string "5" fails and is reported with its JSON spelling, exactly as in v4.
The two load-time messages are unchanged from v4, verbatim from the live i18n dictionary:
This pack is for shader pack API version {{packVersion}}. Bloxd supports version {{version}}.— the key is present but doesn’t equal 5.
A stored (previously working) v4 pack doesn’t throw anything at the player: the stored-pack outcome resolves to {kind: "none", reason: "otherApiVersion"}, the pack is silently inactive, and the shader-pack settings tab explains itself with the status line:
This shader pack is for API version {{packVersion}}, so it won't run. Load a version {{version}} pack to replace it.
The manifest rules are otherwise re-measured and unchanged: pack.json must be a JSON object at the zip root; apiVersion must be present and === 5; name is required, a string, non-empty after trimming; author is optional but must be a string if present; everything else in the manifest is ignored.
70. pack.json, the loader, and the uniform (what stays unchanged)
The whole pack model carries over from v4 byte-for-byte. The loader limits, re-measured on the live loader chunk (c53):
| Limit | Value | Message when exceeded |
|---|---|---|
.wgsl files per pack | 256 | The pack has more than 256 .wgsl files. |
Total .wgsl source | 256 KB | The pack's .wgsl files are over 256 KB in total. |
pack.json size | 64 KB | pack.json is over 64 KB. |
| Zip size | 32 MB | The zip is over 32 MB. |
| Zip entries | 1,024 | The zip has more than 1024 entries. |
| Zip shape | — | split zips, Zip64, encrypted entries, unsupported compression methods each rejected with a dedicated message; every file must be valid UTF-8; exactly one pack.json; no duplicate paths |
The per-frame uniform is still @group(3) @binding(0) var<uniform> bloxdPackInputs: BloxdPackInputs, still 64 bytes — but it gained a member. The layout table, from the live uniform-layout module:
| Offset | Field | Type | Note |
|---|---|---|---|
| 0 | seconds | f32 | backs bloxdSeconds() |
| 4 | lit | u32 | new in v5 — 1 when block/sky lighting is on; backs bloxdLit() |
| 16 | renderOffset | vec3i | backs bloxdRenderOffset() |
| 32 | sunDirection | vec3f | backs bloxdSunDirection() |
| 48 | eyePosition | vec3f | backs bloxdEyePosition() |
lit slots into the padding that v4 already had between seconds and renderOffset (offsets 4–15 were alignment slack in v4; renderOffset stays at 16 because a vec3i needs 16-byte alignment), so the struct’s total size and every other member’s offset are unchanged. The engine writes it as a single setUint32(4, lit ? 1 : 0) — it is a flag, not a light level: the v4 JS-side names terrainLightLevels / terrainHeldLight are gone from the bundle entirely.
The pack bind-group layout is otherwise unchanged: group 3 is still 0 uniform · 1 scene-depth texture (liquid variants) · 2 the bloxdSpTextureLayers storage buffer. minBindingSize is still 64.
71. The flags rewrite: blockFlags → BloxdFlags (the headline)
v4 identified a face with a blockFlags: u32 and six bloxdBlockFlag* constants (opaque 1, emissive 2, vegetation 4, dirt 8, sand 16, rock 32). v5 replaces the whole mechanism with a struct of named booleans, quoted verbatim from the live header:
// What kind of block, item or lifeform a face is. Any number of flags may be
// set, possibly even none. For example, sandstone is sand and rock.
struct BloxdFlags {
opaque: bool, // Opaque blocks, i.e. full cubes with no gaps or holes.
emissive: bool, // Blocks that emit light, e.g. lava and glowing ores.
vegetation: bool, // Leaves, grass blocks and leafy plants, e.g. tall grass.
dirt: bool, // Soil, grass blocks included. Rocky Dirt is rock too.
sand: bool, // Sand, Red Sand and every sandstone, which is rock too.
rock: bool, // Stone variants, and more, e.g. gravel, ores and magma.
// Drawn as block models, so never part of terrain or flagged as opaque.
slab: bool, // Half blocks.
stairs: bool, // Stairs and corner stairs.
flat: bool, // Planes, e.g. tall grass, flowers, crops and cobwebs.
placed: bool, // Blocks placed as part of chunks. Not items or vehicles.
held: bool, // Items in a hand, in first or third person.
dropped: bool, // Dropped items, on the ground, on a belt or in a pipe.
thrown: bool, // Items in flight, e.g. snowballs, arrows and rockets.
lifeform: bool, // Players, mobs and NPCs. Includes armour and cosmetics.
}The six v4 bit tests map one-to-one onto fields — the migration is a rename, not a rethink:
| v4 | v5 |
|---|---|
(surface.blockFlags & bloxdBlockFlagOpaque) != 0u | surface.flags.opaque |
(surface.blockFlags & bloxdBlockFlagEmissive) != 0u | surface.flags.emissive |
(surface.blockFlags & bloxdBlockFlagVegetation) != 0u | surface.flags.vegetation |
(surface.blockFlags & bloxdBlockFlagDirt) != 0u | surface.flags.dirt |
(surface.blockFlags & bloxdBlockFlagSand) != 0u | surface.flags.sand |
(surface.blockFlags & bloxdBlockFlagRock) != 0u | surface.flags.rock |
The eight new fields are the real story. v4 had no way to tell a slab from a full block, a held item from terrain, or a player from a pumpkin — every non-terrain face was just “not opaque” with a texture id. v5 answers “what am I looking at” directly:
slab/stairs/flat— the three block-model shapes.flatcovers the cross-plane plants (tall grass, flowers, crops, cobwebs). These are drawn as block models, so the header notes they are never part of terrain and neveropaque.placed— chunk geometry as placed in the world; explicitly not items or vehicles.held— items in a hand, first or third person. This is the field first-person-shader authors wanted since v1: you can finally detect the held item and treat it differently from the world.dropped/thrown— items on the ground / on belts / in pipes, versus items in flight (snowballs, arrows, rockets).lifeform— players, mobs and NPCs, including armour and cosmetics.
Combined with localPosition (§72) and the enchant/overlay inputs, the model pipeline can now be shaded with full knowledge of what it is rendering. A minimal “held item glow” recipe, impossible in v4:
fn bloxdModelSurface(surface: BloxdSurfaceIn) -> BloxdSurface {
var out = bloxdDefaultSurface(surface);
// Brighten whatever the local player is holding, nothing else.
if (surface.flags.held) {
out.colour *= 1.15;
}
return out;
}Note what did not change: the fields live in the same place in all three input structs (BloxdVertexIn, BloxdSurfaceIn, BloxdLightIn — field name flags, type BloxdFlags), the semantics of the six surviving booleans are the v4 semantics with the same edge cases the header now spells out (“Rocky Dirt is rock too”, “every sandstone is rock too”), and multiple flags still combine freely (“sandstone is sand and rock”, “possibly even none”).
72. New inputs: localPosition, the enchant quartet, and overlayColour
BloxdVertexIn, BloxdSurfaceIn and BloxdLightIn all grow the same new members. From the header, verbatim:
localPosition: vec3f, // A model's local coordinates. 0 for terrain/liquid.localPosition— the model-space position of the vertex/fragment, before the model instance is placed in the world.vec3f(0.0)for terrain and liquid faces (they have no model). For a player’s arm, a held sword, a windmill blade, this is the coordinate that rotates with the model — a per-model animation or a curvature effect keyed to “where on the sword am I” now takes one field instead of world-space guesswork. In the light struct the header notes it is “the same as in BloxdVertexIn, after the vertex hook” — i.e. if your vertex hook moves the vertex, the light hook’slocalPositionfollows.
And on BloxdSurfaceIn / BloxdLightIn only (the vertex struct doesn’t need them):
// Enchanted items and armour only, all 0 for anything else.
enchantTier: u32, // 1-5 for Tier 1-5.
enchantColour: vec4f, // RGB enchant colour, and its animated alpha.
enchantSpeed: f32, // How fast the pattern moves, faster at higher tiers.
// Players and mobs only, 0 for anything else: RGB overlay colour, e.g. the
// red flash when hurt, and its alpha. bloxdLitColour mixes it into colour.
overlayColour: vec4f,enchantTier— the item’s enchant tier as an integer 1–5, for the classic “glint intensity by tier” effect without parsing the colour.enchantColour— the live enchant RGB plus its animated alpha in.a: the engine animates the glint sweep, so reading.aper-fragment gives you the moving pattern for free. All zeros on unenchanted faces.enchantSpeed— how fast the enchant pattern moves; the header’s own note is “faster at higher tiers”, soenchantTierandenchantSpeedare consistent by construction.overlayColour— the damage/hurt flash and similar entity overlays (RGB + alpha), 0 for anything that isn’t a player or mob. The engine mixes this before lighting; see §73 for the output side.
The old quartet (textureId, textureRotation, uv, mipLevel) carries over untouched, with one comment rewording: v4 said uv was “texture coordinates in blocks”; v5 says “The texture spans 0-1. fract(uv) is drawn.” — the same field, described from the texture’s point of view: one texture tile spans 0.0–1.0 of uv, and integer steps of uv tile it across a repeated wall. No port action needed unless you hand-rolled assumptions about multi-block spans.
73. New outputs: BloxdSurface gains enchantColour and overlayColour
The surface output struct grows two fields, verbatim:
struct BloxdSurface {
colour: vec3f, // RGB colour output.
#ifdef BLOXD_ALPHA
alpha: f32, // Opacity output.
#endif
emission: vec3f, // Emissive RGB, added after lighting, before fog.
enchantColour: vec4f, // Enchant output, mixed in by bloxdLitColour.
overlayColour: vec4f, // Overlay output, mixed in by bloxdLitColour.
}Your surface hook now owns the enchant glint and the hurt-flash, in the same way it already owned emission:
bloxdDefaultSurfacepassessurface.enchantColourandsurface.overlayColourthrough unchanged, so the default look is identical to v4’s engine-side behaviour.- Zeroing
out.enchantColourin your hook removes the enchant glint from your custom lighting — a “no-glint realism” pack is now two lines. - Amplifying
out.overlayColour.amakes the hurt flash punchier without touching the base colour; the mix happens inbloxdLitColour(§74), after shading, exactly where the engine put it. - The emission ordering note carries over verbatim: emission is added after lighting, before fog — and the two new fields are mixed in by
bloxdLitColour, which is before emission and fog. The full output chain, in order:colour→ overlay mix → shading → enchant mix → world light →+ emission→ fog.
74. The lighting recipe goes public: bloxdLit() and the three helpers
v4 gated lighting code at compile time: 8 variants (strict|allow × lit|unlit × terrain|liquid), with #ifdef BLOXD_LIGHTING deciding whether light hooks ran the lit or unlit path. v5 drops the whole lighting axis from compilation:
- The variant matrix is 6, not 8:
strict|allow×terrain|liquid|model, namedallow.terrain…strict.liquidetc. (the labels the engine itself builds for the loader screen). BLOXD_STRICTis still strict-only;BLOXD_ALPHAis still all-liquid plus every allow variant (off for strict terrain and strict model);BLOXD_SCENE_DEPTHis still liquid-only.BLOXD_LIGHTINGno longer exists.- Lighting state moved to the uniform (
lit: u32, §70) and is queried in code with the new header function:
// Whether block and sky lighting is on. When it's off, BloxdLightIn's
// blockLight and heldLight are 0, and its skyLight and light colours are 1.
fn bloxdLit() -> bool {
return bloxdPackInputs.lit != 0u;
}If your v4 pack wrapped its light hooks in #ifdef BLOXD_LIGHTING ... #else ... #endif, the v5 port is an early return: if (!bloxdLit()) { return bloxdDefaultLight(surface, light); }. The analyzer even tells you this — using BLOXD_LIGHTING now produces the validation message “BLOXD_LIGHTING was removed in apiVersion 5; test bloxdLit() in code instead.” (measured verbatim from the live validator).
Three more functions join the header, and they are the ones v4 authors kept re-deriving by hand — the engine’s own lighting, documented as callable WGSL:
// How the face's material and angle light it: directional light on its
// diffuse colour, plus its emissive and ambient terms, clamped to 0-1.
fn bloxdShading(light: BloxdLightIn) -> vec3f {
let diffuse = light.directional * light.diffuse;
return saturate(diffuse + light.emissive + light.ambient);
}
// The world's light at this fragment: the brightest of block, sky and held
// light, none below ambientLightColour.
fn bloxdWorldLight(light: BloxdLightIn) -> vec3f {
let ambientLight = light.ambientLightColour;
let blockLight = ambientLight + light.blockLight * (1.0 - ambientLight);
let skyLight = mix(ambientLight, light.skyLightColour, light.skyLight);
let heldLight = ambientLight + light.heldLight * (1.0 - ambientLight);
return max(max(blockLight, skyLight), heldLight);
}
// The surface's colour lit as the engine does, before emission and fog:
// mixed with overlayColour, then bloxdShading, then mixed with
// enchantColour, then bloxdWorldLight.
fn bloxdLitColour(surface: BloxdSurface, light: BloxdLightIn) -> vec3f {
let overlay = surface.overlayColour;
let overlaid = mix(surface.colour, overlay.rgb, overlay.a);
let shaded = bloxdShading(light) * overlaid;
let enchant = surface.enchantColour;
let enchanted = mix(shaded, enchant.rgb, enchant.a);
return max(enchanted * bloxdWorldLight(light), vec3f(0.0));
}And bloxdDefaultLight itself now uses them — the default is literally “apply the engine recipe and then fog the emission-extended result”:
fn bloxdDefaultLight(surface: BloxdSurface, light: BloxdLightIn) -> BloxdLight {
let lit = bloxdLitColour(surface, light);
return BloxdLight(bloxdApplyFog(lit + surface.emission, light));
}To feed bloxdShading, BloxdLightIn also gains two inputs (verbatim comments):
directional: f32, // Summed Lambert from directional lights; 0 if none.
diffuse: vec3f, // The material's RGB response to directional light.
emissive: vec3f, // The material's RGB glow, added to directional light.diffuse and emissive are new in v5 (v4 had directional and ambient only): they let you rebuild bloxdShading with modifications — e.g. keep the engine’s world light but replace the Lambert term with your own wrap-around shading — without losing the material response the engine already knows. The doc comments on the light levels were also reworded from “0 without BLOXD_LIGHTING” to “0 when !bloxdLit()”, which is the same fact in the v5 vocabulary.
A “custom shading, engine world-light” light hook — the recipe v4 authors approximated by scaling litColour, now exact:
fn bloxdTerrainLight(surface: BloxdSurface, light: BloxdLightIn) -> BloxdLight {
// Half-Lambert wrap: soft, never fully dark on the back face.
let nDotL = light.directional; // already the summed Lambert term
let wrapped = nDotL * 0.5 + 0.5;
let shaded = saturate(wrapped * light.diffuse + light.emissive + light.ambient);
let colour = max(shaded * bloxdWorldLight(light), vec3f(0.0));
return BloxdLight(bloxdApplyFog(colour + surface.emission, light));
}75. Removals: bloxdFragmentBlockPosition(), bloxdBlockFlag*, bloxdSpLitColour
Three things are gone, and the validator says so by name:
bloxdFragmentBlockPosition(position, normal) -> vec3i— dropped from the documented header, but not actually dead: the validator’s signature table kept its entry (so calls still pass validation in every hook, vertex included), and the code generator still injects a definition into the terrain/liquid module and both model programs (vec3i(floor(position - normal * 0.5)) + bloxdRenderOffset()for terrain/liquid; a 1/64-offset, cell-snapping variant for models). v4 packs calling it keep working. Treat it as deprecated: it is undocumented now, so preferbloxdWorldPosition()for continuous positions andflagsfor “which block am I on”, and expect it may vanish in a future version.- The six
bloxdBlockFlag*constants — replaced byBloxdFlags(§71). Any surviving reference fails validation with the analyzer’s reserved-name diagnostic. bloxdSpLitColour— the engine-internal symbol whose job became the publicbloxdLitColour()(§74). It leaves thebloxdSp*namespace, which otherwise only grows (§79).
The v4-era functions that survive unchanged: bloxdEyePosition(), bloxdRenderOffset(), bloxdSunDirection(), bloxdSeconds(), bloxdWorldPosition(), bloxdApplyFog(), bloxdDefaultVertex(), bloxdDefaultSurface(), bloxdDefaultLight(), plus the whole texture API (bloxdTexel, bloxdTextureSize, bloxdTextureId* — §79 re-measures the registry) and BloxdOpaqueBehind / bloxdSceneDepth with their liquid-variant semantics.
76. The default pack ships all nine hooks
The template a new pack starts from now includes the light hooks — v4’s template had six (vertex+surface per program) and left light hooks to be copied from the docs. v5’s, verbatim and complete (1,633 bytes as shipped):
// Every hook here returns its engine default. Modify the return values to start
// building a shader pack. If you delete a hook, the default is used instead.
// All blocks but water and block models use terrain hooks.
#ifndef BLOXD_STRICT
// Strict games keep terrain where it is. Without the #ifndef, this hook would
// turn the whole shader pack off there.
fn bloxdTerrainVertex(vertex: BloxdVertexIn) -> BloxdVertex {
return bloxdDefaultVertex(vertex);
}
#endif
fn bloxdTerrainSurface(surface: BloxdSurfaceIn) -> BloxdSurface {
return bloxdDefaultSurface(surface);
}
fn bloxdTerrainLight(surface: BloxdSurface, light: BloxdLightIn) -> BloxdLight {
return bloxdDefaultLight(surface, light);
}
// Water uses liquid hooks. To share code with another hook, define a function
// and call it from both places.
#ifndef BLOXD_STRICT
fn bloxdLiquidVertex(vertex: BloxdVertexIn) -> BloxdVertex {
return bloxdDefaultVertex(vertex);
}
#endif
fn bloxdLiquidSurface(surface: BloxdSurfaceIn) -> BloxdSurface {
return bloxdDefaultSurface(surface);
}
fn bloxdLiquidLight(surface: BloxdSurface, light: BloxdLightIn) -> BloxdLight {
return bloxdDefaultLight(surface, light);
}
// Models: block models such as slabs and plants, items, players and mobs.
#ifndef BLOXD_STRICT
fn bloxdModelVertex(vertex: BloxdVertexIn) -> BloxdVertex {
return bloxdDefaultVertex(vertex);
}
#endif
fn bloxdModelSurface(surface: BloxdSurfaceIn) -> BloxdSurface {
return bloxdDefaultSurface(surface);
}
fn bloxdModelLight(surface: BloxdSurface, light: BloxdLightIn) -> BloxdLight {
return bloxdDefaultLight(surface, light);
}The comments are new wording and worth reading as documentation of the deletion model: “Modify the return values to start building a shader pack. If you delete a hook, the default is used instead.” The liquid note changed too — v4 said “If deleted, water uses your terrain hooks instead”, v5 says “To share code with another hook, define a function and call it from both places” — and the strict note now explains the #ifndef in one sentence: “Strict games keep terrain where it is. Without the #ifndef, this hook would turn the whole shader pack off there.”
The strict-games contract itself (v4 §60) is unchanged: an unguarded vertex hook reports <hook> moves terrain, which strict games prevent., a reachable discard reports discard makes terrain see-through, which strict games prevent., and either disables all hooks in strict games. The 12 allow titles were re-measured on the live bundle — still 12, unchanged.
77. v4 → v5 migration checklist
pack.json:"apiVersion": 5— the number, not a string.- Port flags (mechanical, §71): every
blockFlags & bloxdBlockFlagX != 0u→flags.x; delete the constants — the validator rejects them by name. - Port the lighting gate (the one with a validator message):
#ifdef BLOXD_LIGHTING→if (bloxdLit()) { ... } else { return bloxdDefaultLight(surface, light); };BLOXD_LIGHTINGnow triggers “BLOXD_LIGHTING was removed in apiVersion 5; test bloxdLit() in code instead.” - Migrate off
bloxdFragmentBlockPosition(§75) — it still compiles, but it is undocumented now; usebloxdWorldPosition()/flags. - Decide on the new inputs/outputs (optional):
flags.slab/stairs/flat/placed/held/dropped/thrown/lifeform(§71),localPosition(§72), the enchant quartet +overlayColour(§72–§73). Pass-through viabloxdDefaultSurfacekeeps the v4 look exactly. - Adopt the engine recipe helpers (optional but recommended): replace hand-rolled light colour with
bloxdLitColour(surface, light)— or mix and match withbloxdShading/bloxdWorldLight(§74) — then addsurface.emissionandbloxdApplyFogasbloxdDefaultLightdoes. - Strict audit (unchanged from v4):
#ifndef BLOXD_STRICTaround vertex hooks and any reachablediscard. - In-game compile check: the loader validates all 6 variants at once (strict × terrain/liquid/model — the lighting axis no longer compiles separately, §74). Then eyeball one allow game and one strict game.
- Bump your own version metadata and re-distribute: stored v4 copies on players’ machines are silently inactive (§69) and only the settings tab says why.
77.1 A complete v4 → v5 port, before and after
A compact v4 pack — “greenery tint + held-light boost” — as it would fail today, and ported:
// ---- v4 (fails validation on ab90qa) ----
fn bloxdTerrainSurface(surface: BloxdSurfaceIn) -> BloxdSurface {
var out = bloxdDefaultSurface(surface);
if ((surface.blockFlags & bloxdBlockFlagVegetation) != 0u) {
out.colour *= vec3f(1.0, 1.08, 0.9);
}
if ((surface.blockFlags & bloxdBlockFlagEmissive) != 0u) {
out.emission += vec3f(0.05);
}
return out;
}
#ifdef BLOXD_LIGHTING
fn bloxdTerrainLight(surface: BloxdSurface, light: BloxdLightIn) -> BloxdLight {
var out = bloxdDefaultLight(surface, light);
out.colour += light.heldLight * 0.15; // glow near a held light source
return out;
}
#endif// ---- v5 (ported; identical on-screen behaviour) ----
fn bloxdTerrainSurface(surface: BloxdSurfaceIn) -> BloxdSurface {
var out = bloxdDefaultSurface(surface);
if (surface.flags.vegetation) {
out.colour *= vec3f(1.0, 1.08, 0.9);
}
if (surface.flags.emissive) {
out.emission += vec3f(0.05);
}
return out;
}
fn bloxdTerrainLight(surface: BloxdSurface, light: BloxdLightIn) -> BloxdLight {
if (!bloxdLit()) { return bloxdDefaultLight(surface, light); }
var out = bloxdDefaultLight(surface, light);
out.colour += light.heldLight * 0.15;
return out;
}And the v5-only bonus the same pack can now add — model awareness in two lines:
fn bloxdModelSurface(surface: BloxdSurfaceIn) -> BloxdSurface {
var out = bloxdDefaultSurface(surface);
if (surface.flags.lifeform && !surface.flags.held) {
out.colour *= 1.05; // subtle world-entity lift, hands excluded
}
return out;
}78. Other v5 changes and notes
bloxdChunkSizejoins the header —const bloxdChunkSize: i32 = 32;(“Blocks along each side of a chunk”). Previously an engine-side magic number; now a named constant you can branch on.bloxdPi/bloxdTauunchanged.- The header’s frame-function section got a shared comment — “These functions return the same value for the entire frame” (v4: “return 1 value per frame, the same for every call site”) — pure wording.
- Y-derivatives are auto-negated in pack code. The analyzer rewrites every call to
dpdy,dpdyCoarseordpdyFineinto(-dpdy(...))— the screen-space y axis points down, so the negation makes “derivative with respect to up” match intuition. You writedpdy(h)expecting “how does h change going up”; the emitted code negates it for you.dpdxand thefwidthfamily are untouched. (Measured in the validator’s token-rewrite pass; the dpdy family is specifically listed as the negation set.) - Texture-name diagnostics got a spelling engine. A name that starts with
bloxdTextureIdbut doesn’t resolve now gets a Levenshtein-powered suggestion: “X' isn't part of the shader pack API. Texture names start with exactly bloxdTextureId: did you mean bloxdTextureIdY?” — plus dedicated messages for frame spellings (“names a frame of the animated texture Z: use bloxdTextureIdZ, which bloxdTexel animates.”) and turned spellings (“names a turned copy of Z: use bloxdTextureIdZ, which bloxdTexel turns as each face shows it.”). The general reservation rule is restated in the diagnostics: “Packs can’t declare names starting with bloxd, other than the hook functions bloxd<Terrain|Liquid|Model><Vertex|Surface|Light>”, and “Packs can’t use X: the engine binds every texture and sampler. Surface and light hooks can read atlas textures with bloxdTexel.” - Only referenced texture constants are emitted. The header’s
bloxdTextureId*block is generated per pack from the names you actually reference — a pack that uses three constants gets threeconstlines prepended, not the full ~900. HEADER_VERSIONmoved to9.<hash>.<hash>— same two-suffix structure as v4 (fnv1a32 of the header material, fnv1a32 of the sorted name-id registry), with the leading integer bumped from 8 to 9. The stored-pack recheck logic (§55 of the v4 guide) is unchanged: a header/registry change flips stored packs to “needs re-check”.- i18n surface: the shader-pack key family is unchanged in shape (the
load*,status*, and variant-label keys of the v4 guide §62 all re-measured present;loadNoWgsl/loadNotZipstill exact). - Bundle layout for re-researchers: header c55 (unchanged), loader/persistence c51–c53, validator + registry builder c55, WebGPU codegen c56, fog c9, default pack template c116 (moved from c124), the BLOXD_ALPHA sites c51/c52/c53/c55/c9. Chunk format note: every chunk is now an ES module (
export const modules = {...}) — c53 even carries modules for both c52 and c53 — which matters if you text-search the bundle (a module id like1371lives in main’s sparse module array, not in any chunk).
79. Engine internals v5: the texture pipeline and the 46-symbol bloxdSp* namespace
The three-variant texture codegen of v4 §63 carries over with the same shape. Restored from the live generator (c56):
Variant 1 — no texture pack active (the whole generated block; bloxdTextureSize and bloxdTexel are stubs):
fn bloxdTextureSize(bloxdSpMipLevel: f32) -> vec2u {
return vec2u(1u);
}
fn bloxdTexel(bloxdSpTextureId: u32, bloxdSpUv: vec2f, bloxdSpMipLevel: f32) -> vec4f {
return vec4f(1.0);
}Variant 2 — the atlas path (default in games): bloxdTextureSize returns textureDimensions(textureAtlas0, u32(clamp(round(bloxdSpMipLevel), 0.0, f32(textureNumLevels(textureAtlas0) - 1u)))), and bloxdTexel applies the face’s quarter-turn rotation before loading — the v4 rotation subtlety (v4 guide §57.4), now spelled as an explicit if-chain on the generated bloxdSpTurned:
// Each quarter turn clockwise the face shows its texture at reads the unturned texture at (v, 1 - u)
var bloxdSpTurned = bloxdSpUv;
if (bloxdSpTextureRotation == 1u) {
bloxdSpTurned = vec2f(bloxdSpUv.y, 1.0 - bloxdSpUv.x);
} else if (bloxdSpTextureRotation == 2u) {
bloxdSpTurned = 1.0 - bloxdSpUv;
} else if (bloxdSpTextureRotation == 3u) {
bloxdSpTurned = vec2f(1.0 - bloxdSpUv.y, bloxdSpUv.x);
}(The bloxdSpTextureRotation name in that excerpt is the engine’s own storage for the input quartet’s rotation member — v4 §63.2’s delivery path, unchanged in role.) Variant 3 — custom texture-pack textures — samples a per-texture cell of a layered atlas via textureLoad(<atlas>, min(bloxdSpCellAt * bloxdSpSize + bloxdSpAt, <dims> - 1u), bloxdSpLevel), with a bloxdSpOwnTexel path for the pack’s own texel.
The bloxdSp* namespace — everything the generator can inject and you therefore cannot redeclare — grew from 27 to 46 symbols: 20 new, 1 retired (bloxdSpLitColour, whose job is now the public bloxdLitColour), 26 carried over:
bloxdSpAcross · bloxdSpAt · bloxdSpBehind · bloxdSpCell · bloxdSpCellAt · bloxdSpCellIndex · bloxdSpColour · bloxdSpDdx · bloxdSpDdy · bloxdSpDown · bloxdSpEnchant · bloxdSpEye · bloxdSpFlags · bloxdSpFrame · bloxdSpIndex · bloxdSpInside · bloxdSpItemLocalPosition · bloxdSpLayer · bloxdSpLevel · bloxdSpLight · bloxdSpLightIn · bloxdSpLod · bloxdSpMipLevel · bloxdSpNormal · bloxdSpOut · bloxdSpOwnTexel · bloxdSpPixel · bloxdSpPosition · bloxdSpPositionW · bloxdSpQuarterTurns · bloxdSpScale · bloxdSpSceneDepth · bloxdSpSize · bloxdSpSurface · bloxdSpSurfaceIn · bloxdSpTexelUV · bloxdSpTexture · bloxdSpTextureId · bloxdSpTextureLayers · bloxdSpTextureRotation · bloxdSpTurned · bloxdSpUv · bloxdSpVertex · bloxdSpVertexIn · bloxdSpWord · bloxdSpZ
The new names trace directly to the v5 features: bloxdSpFlags (the flags struct path), bloxdSpEnchant / bloxdSpItemLocalPosition (the new inputs), bloxdSpAcross / bloxdSpAt / bloxdSpCell / bloxdSpCellAt / bloxdSpCellIndex / bloxdSpSize / bloxdSpLevel / bloxdSpOwnTexel (the cell-sampling texture-pack path), bloxdSpQuarterTurns (the rotation chain above), bloxdSpNormal / bloxdSpPosition / bloxdSpColour / bloxdSpOut / bloxdSpWord / bloxdSpIndex / bloxdSpDown / bloxdSpInside (generated locals in the expanded hooks). The pack-level reservation rule is unchanged and broader than the list: anything matching /^bloxd/i, case-insensitive.
80. The texture registry: 896 usable names (the drift, measured)
Re-measured on ab90qa (2026-11-03) by the same methodology as the v4 catalogue (§68 of the v4 guide): run the engine’s own registry-builder module (module 29833 in this build) on the shipped block-registry texture data and record its output.
| Measurement | cnty9 (v4) | ab90qa (v5) |
|---|---|---|
| Atlas entries | 1,219 | 1,210 |
| Turned families (rotated spellings) | 57 (228) | 57 (228) — unchanged |
| Animated families (frame spellings) | 42 (188) | 42 (188) — unchanged |
| Usable named constants | 905 | 896 |
| Id churn among surviving names | — | 334 of 905 got a different id |
The drift, in full (this is the complete list — 11 names):
- Added (1):
scorpion_eggs. - Removed (10): the eight double-chest textures
chest_double_front,chest_double_front_hi,chest_double_front_lo,chest_double_back,chest_double_back_hi,chest_double_back_lo,chest_double_top_1_hi,chest_double_top_1_lo— andchest_double_top_2_hi,chest_double_top_2_lo(the double chest is gone from the game data; the single-chestchest_*family survives intact) — plusmob_spawner_hostile_block_sideandmob_spawner_neutral_block_side(the spawner keepsmob_spawner_block_top; the variant side textures are gone).
The doctrine of the v4 catalogue (§68 of the v4 guide) carries over word for word: names are the API, ids are a snapshot. 334 of the 905 surviving names changed id between the two builds — write bloxdTextureIdStone, never 351. The v4 catalogue’s alphabetical list (§68.2 of the v4 guide) remains valid for v5 modulo the 11-name drift above; the folding rules and both family tables are unchanged, so its §68.3–§68.4 (turned and animated families) are still exact. The current-form catalogue is the Texture catalog.
Addendum (2026-11-04, xkg8x): the registry moved again one day after the v5 launch — every removal below is reversed. Atlas entries 1,210 → 1,220, usable names 896 → 906 (the eight double-chest textures and both spawner side variants are back; nothing removed), 376 of the 896 survivors changed id, families unchanged (57 / 42). Preprod 2lcqcl measured identical on every shader-pack surface. The current-form catalogue is re-measured on xkg8x: Texture catalog.
Addendum (2026-11-05, bny9u): the registry moved yet again — two new blocks shipped. Atlas entries 1,220 → 1,232, usable names 906 → 911 (+5: trading_terminal_front / _side / _top, stone_generator_side / _top; nothing removed), 864 of the 906 survivors changed id (95%), rotation families unchanged (57), animation families 42 → 43 (trading_terminal_front, 8 frames at 250 ms). Production and preprod serve the same build. The current-form catalogue is re-measured on bny9u: Texture catalog.
Addendum (2026-11-08, v98qt8): the registry moved again, and this time the build also ships a folding regression. Atlas entries 1,232 → 1,227, usable names 911 → 906 (+1 hay_block_top; −6 artisan_table_side/_top, crafting_table_side, furnace_front/_side/_top — the Furnace, Workbench and Artisan Bench became block models (the Workbench kept crafting_table_top — its top face is still terrain-textured)), 716 of the 905 survivors changed id (79%), both family sets unchanged (57 / 43). Production and preprod serve the same build. The regression: the engine’s animated-texture table is keyed by spelling where the folding code expects slot indices, so the 43 animation-family base names (lava …) currently fail validation while the 196 frame spellings resolve as individual constants — full byte-level analysis in Engine Internals: Texture Registry. The current-form catalogue is re-measured on v98qt8: Texture catalog.
Addendum (2026-11-20, bbb6l5): the registry took its largest step ever, and this is the first v5-era API surface change. Atlas entries 1,227 → 1,650 (+423, −0), usable names 906 → 1,017 (+111 — the Atomic Age content pack: reactor machinery, uranium and materials, batteries, bombs and specials), rotation families 57 → 64, animation families 43 → 71 plus the 204 new frameA~frameB~interval transition spellings (pre-blended cross-fade slots), 863 of the 906 survivors changed id (95%), and the v98qt8 folding regression is fixed (the animation table is slot-keyed again — lava and friends validate). Alongside it, the pack-visible API grew without an apiVersion bump: the uniform gained shadowDirection: vec3f @ 64 (64 → 80 bytes, minBindingSize 80), the header gained bloxdShadowDirection(), the injected functions bloxdShadow() / bloxdAirShadow(t) opened the real sun/moon shadow system to packs, and pack.json gained the optional keepCircleShadows boolean. The fingerprint moved 13d4e18f → 32451195 (match-verified against the shipped pre-built atlas). The current-form catalogue is re-measured on bbb6l5: Texture catalog.
81. Confirmed constants, limits, and layouts (v5)
The v5 row of the guide’s measurement ledger — everything measured on ab90qa (2026-11-03, prod = preprod, byte-identical):
| Item | Value |
|---|---|
apiVersion | 5 (strict ===, number) |
| Engine header | 8,954 B / 208 lines decoded (9,125 B as shipped, 6 interpolations); first line // The Bloxd shader pack API, apiVersion 5. Read-only, prepended to all packs. — full text in §82 |
| Hooks | 9 (terrain/liquid/model × vertex/surface/light); names unchanged; default template ships all 9 (§76) |
| Variants | 6 (strict × program); names strict|allow.terrain|liquid|model — the lighting axis is gone (§74) |
| Macros | BLOXD_STRICT (strict) · BLOXD_ALPHA (all liquid + non-strict terrain/model) · BLOXD_SCENE_DEPTH (all liquid) · BLOXD_LIGHTING |
| Pack uniform | @group(3) @binding(0), 80 B on bbb6l5 (64 B at launch): seconds@0, lit@4 (u32, new in v5), renderOffset@16, sunDirection@32, eyePosition@48, shadowDirection@64 (new on bbb6l5) |
| Pack bindings | group 3: 0 uniform · 1 scene depth (liquid) · 2 bloxdSpTextureLayers storage; minBindingSize 80 on bbb6l5 (64 at launch) |
| Flags | BloxdFlags struct, 14 bools (§71); v4 bit values retired |
| Loader limits | 256 .wgsl / 256 KB source / 64 KB pack.json / 32 MB zip / 1,024 zip entries; UTF-8; one manifest; unique paths — all unchanged |
| Texture registry | 1,210 entries → 896 usable names; drift +1/−10 vs cnty9 (§80); catalogue: v4 guide §68 + §80’s drift list (current form: Texture catalog); re-measured on xkg8x (2026-11-04): 1,220 / 906, all 10 removals reversed, 376 id changes; on bny9u (2026-11-05): 1,232 / 911, +5 (Trading Terminal ×3, Stone Generator ×2), 864 id changes; on v98qt8 (2026-11-08): 1,227 / 906, +1 hay_block_top, −6 model-converted block textures, 716 id changes, folding regression (§80 addendum); on bbb6l5 (2026-11-20): 1,650 / 1,017, +423/−0 (Atomic Age content + transition slots), 863 id changes, folding regression fixed (§80 addendum) |
| Light curve | 0–15 levels → 0–1 on the ease-out curve (6 → 0.45, 12 → 0.92) — in-header, unchanged |
| Lift curve | 1 - (1 - x / (3 - 2x))^3 — unchanged |
| Directional cone | 0.12 / 0.65 / 0.62 / 0.95 — unchanged |
| Fog colour | vec3f(183/255, 191/255, 195/255) — unchanged |
| Reserved names | /^bloxd/i (case-insensitive) + 46 bloxdSp* engine symbols at launch (§79) — 88 on bbb6l5 |
| HEADER_VERSION | 9.<fnv1a32(header)>.<fnv1a32(texture registry)> at launch — 9.<hash> on bbb6l5, the registry fingerprint folded in at the page level |
| Strict titles | everything except the 12 allow titles listed in Game policy (re-verified on bbb6l5, unchanged; game definitions 116 → 119) |
82. The complete v5 engine header, verbatim
The §67 artefact, re-measured for v5: the exact text the engine prepends to every pack, restored from the live production build with its live interpolations applied (apiVersion and the five uniform reads through bloxdPackInputs). 208 lines at launch. Nothing is paraphrased. On bbb6l5 the header grew to 216 lines with the shadow additions — the current text lives in Engine Internals: Engine Header.:
// The Bloxd shader pack API, apiVersion 5. Read-only, prepended to all packs.
const bloxdPi: f32 = 3.1415926535898;
const bloxdTau: f32 = 6.2831853071796;
// Blocks along each side of a chunk.
const bloxdChunkSize: i32 = 32;
// These functions return the same value for the entire frame.
// The camera's render position.
fn bloxdEyePosition() -> vec3f {
return bloxdPackInputs.eyePosition;
}
// Integer distance, in blocks: render position + this offset = world position.
// Changes as the player travels, so render positions stay close to 0,0,0.
// See bloxdWorldPosition for one way to use it.
fn bloxdRenderOffset() -> vec3i {
return bloxdPackInputs.renderOffset;
}
// The unit vector towards the sun, in world orientation; 0 when there's no sun.
fn bloxdSunDirection() -> vec3f {
return bloxdPackInputs.sunDirection;
}
// Seconds since the page loaded. As an f32, it has sub-millisecond precision
// for the first 4.5 hours. Get a recurring timer using bloxdSeconds() % period.
fn bloxdSeconds() -> f32 {
return bloxdPackInputs.seconds;
}
// Whether block and sky lighting is on. When it's off, BloxdLightIn's
// blockLight and heldLight are 0, and its skyLight and light colours are 1.
fn bloxdLit() -> bool {
return bloxdPackInputs.lit != 0u;
}
// What kind of block, item or lifeform a face is. Any number of flags may be
// set, possibly even none. For example, sandstone is sand and rock.
struct BloxdFlags {
opaque: bool, // Opaque blocks, i.e. full cubes with no gaps or holes.
emissive: bool, // Blocks that emit light, e.g. lava and glowing ores.
vegetation: bool, // Leaves, grass blocks and leafy plants, e.g. tall grass.
dirt: bool, // Soil, grass blocks included. Rocky Dirt is rock too.
sand: bool, // Sand, Red Sand and every sandstone, which is rock too.
rock: bool, // Stone variants, and more, e.g. gravel, ores and magma.
// Drawn as block models, so never part of terrain or flagged as opaque.
slab: bool, // Half blocks.
stairs: bool, // Stairs and corner stairs.
flat: bool, // Planes, e.g. tall grass, flowers, crops and cobwebs.
placed: bool, // Blocks placed as part of chunks. Not items or vehicles.
held: bool, // Items in a hand, in first or third person.
dropped: bool, // Dropped items, on the ground, on a belt or in a pipe.
thrown: bool, // Items in flight, e.g. snowballs, arrows and rockets.
lifeform: bool, // Players, mobs and NPCs. Includes armour and cosmetics.
}
// Convert a render position to a world position, with possible f32 inaccuracy.
fn bloxdWorldPosition(position: vec3f) -> vec3f {
return position + vec3f(bloxdRenderOffset());
}
struct BloxdVertexIn {
position: vec3f, // Render position.
normal: vec3f, // Unit vector pointing away from the face.
localPosition: vec3f, // A model's local coordinates. 0 for terrain/liquid.
flags: BloxdFlags, // What kind of block, item or lifeform.
}
struct BloxdVertex {
position: vec3f, // The render position output.
}
struct BloxdSurfaceIn {
colour: vec3f, // RGB colour = texture * tint * ambient occlusion.
alpha: f32, // Opacity.
// Enchanted items and armour only, all 0 for anything else.
enchantTier: u32, // 1-5 for Tier 1-5.
enchantColour: vec4f, // RGB enchant colour, and its animated alpha.
enchantSpeed: f32, // How fast the pattern moves, faster at higher tiers.
// Players and mobs only, 0 for anything else: RGB overlay colour, e.g. the
// red flash when hurt, and its alpha. bloxdLitColour mixes it into colour.
overlayColour: vec4f,
// These mean the same as in BloxdVertexIn, after the vertex hook.
position: vec3f, // Render position.
normal: vec3f, // Unit vector pointing away from the face.
localPosition: vec3f, // A model's local coordinates. 0 for terrain/liquid.
flags: BloxdFlags, // What kind of block, item or lifeform.
// These are all 0 if the face has no texture. Most models use textureId 0.
textureId: u32, // This face's texture. Compare with bloxdTextureId*.
textureRotation: u32, // Quarter turns clockwise, which bloxdTexel applies.
uv: vec2f, // The texture spans 0-1. fract(uv) is drawn.
mipLevel: f32, // Texture mipmap level. 0 = full size, 1 = half, etc.
}
struct BloxdSurface {
colour: vec3f, // RGB colour output.
#ifdef BLOXD_ALPHA
alpha: f32, // Opacity output.
#endif
emission: vec3f, // Emissive RGB, added after lighting, before fog.
enchantColour: vec4f, // Enchant output, mixed in by bloxdLitColour.
overlayColour: vec4f, // Overlay output, mixed in by bloxdLitColour.
}
// blockLight, skyLight and heldLight are 0-1, from the 0-15 light levels on an
// ease-out curve, e.g. 6->0.45, 12->0.92. They all exclude ambientLightColour.
// bloxdLitColour lights a surface from these as the engine does.
struct BloxdLightIn {
litColour: vec3f, // Lit and enchanted RGB colour, before emission and fog.
directional: f32, // Summed Lambert from directional lights; 0 if none.
diffuse: vec3f, // The material's RGB response to directional light.
emissive: vec3f, // The material's RGB glow, added to directional light.
ambient: vec3f, // RGB ambient colour, added to directional light.
blockLight: vec3f, // RGB block light; 0 when !bloxdLit().
skyLight: f32, // Sky light; 1 when !bloxdLit().
ambientLightColour: vec3f, // Minimum RGB light; 1 when !bloxdLit().
skyLightColour: vec3f, // RGB colour of skyLight; 1 when !bloxdLit().
heldLight: vec3f, // RGB held light; 0 when !bloxdLit() or no light held.
fogColour: vec3f, // The game's RGB fog colour; 0 when the game has no fog.
fogAlpha: f32, // 0 = no fog, 1 = only fogColour.
// These are the same as in BloxdSurfaceIn.
position: vec3f, // Render position.
normal: vec3f, // Unit vector pointing away from the face.
localPosition: vec3f, // A model's local coordinates. 0 for terrain/liquid.
flags: BloxdFlags, // What kind of block, item or lifeform.
textureId: u32, // This face's texture. Compare with bloxdTextureId*.
textureRotation: u32, // Quarter turns clockwise, which bloxdTexel applies.
uv: vec2f, // The texture spans 0-1. fract(uv) is drawn.
mipLevel: f32, // Texture mipmap level. 0 = full size, 1 = half, etc.
}
struct BloxdLight {
colour: vec3f, // RGB colour output.
}
struct BloxdOpaqueBehind {
hit: bool, // False where nothing opaque is behind (sky).
position: vec3f, // The render position; 0 when !hit.
distance: f32, // From the camera; 0 when !hit.
}
fn bloxdDefaultVertex(vertex: BloxdVertexIn) -> BloxdVertex {
return BloxdVertex(vertex.position);
}
fn bloxdDefaultSurface(surface: BloxdSurfaceIn) -> BloxdSurface {
return BloxdSurface(
surface.colour,
#ifdef BLOXD_ALPHA
surface.alpha,
#endif
vec3f(0.0),
surface.enchantColour,
surface.overlayColour,
);
}
// Apply this fragment's fog to colour, as the engine does.
fn bloxdApplyFog(colour: vec3f, light: BloxdLightIn) -> vec3f {
return mix(colour, light.fogColour, light.fogAlpha);
}
// How the face's material and angle light it: directional light on its
// diffuse colour, plus its emissive and ambient terms, clamped to 0-1.
fn bloxdShading(light: BloxdLightIn) -> vec3f {
let diffuse = light.directional * light.diffuse;
return saturate(diffuse + light.emissive + light.ambient);
}
// The world's light at this fragment: the brightest of block, sky and held
// light, none below ambientLightColour.
fn bloxdWorldLight(light: BloxdLightIn) -> vec3f {
let ambientLight = light.ambientLightColour;
let blockLight = ambientLight + light.blockLight * (1.0 - ambientLight);
let skyLight = mix(ambientLight, light.skyLightColour, light.skyLight);
let heldLight = ambientLight + light.heldLight * (1.0 - ambientLight);
return max(max(blockLight, skyLight), heldLight);
}
// The surface's colour lit as the engine does, before emission and fog:
// mixed with overlayColour, then bloxdShading, then mixed with
// enchantColour, then bloxdWorldLight.
fn bloxdLitColour(surface: BloxdSurface, light: BloxdLightIn) -> vec3f {
let overlay = surface.overlayColour;
let overlaid = mix(surface.colour, overlay.rgb, overlay.a);
let shaded = bloxdShading(light) * overlaid;
let enchant = surface.enchantColour;
let enchanted = mix(shaded, enchant.rgb, enchant.a);
return max(enchanted * bloxdWorldLight(light), vec3f(0.0));
}
fn bloxdDefaultLight(surface: BloxdSurface, light: BloxdLightIn) -> BloxdLight {
let lit = bloxdLitColour(surface, light);
return BloxdLight(bloxdApplyFog(lit + surface.emission, light));
}Every hook signature, struct, constant and comment above is load-bearing: it is what the live validator parses, what the code generator prepends, and what your pack compiles against. Diff it against the v4 header (§67 of the v4 guide) to see v5 in one screen: bloxdChunkSize and bloxdLit() near the top, the BloxdFlags struct replacing the bit constants, localPosition and the enchant/overlay fields in the input structs, the two new outputs, and the three lighting helpers before bloxdDefaultLight.