Engine header (verbatim)
Target API: 5 · Target build:
bbb6l5(verified in production and preprod 2026-11-20) · Status: Analyzed (restored verbatim from the live build’s validator)
The exact text the engine prepends to every pack, rendered from the live build’s validator with its interpolations applied (apiVersion and the six uniform reads via bloxdPackInputs). 216 lines decoded. No paraphrase anywhere. Re-verified on the previous production builds (bny9u, v98qt8) with the shadow additions isolated as the only change.
Reading guide:
- Field-by-field explanations → Structures
- Function-by-function → Functions / Lighting
- Flags (BloxdFlags) → Flags
- The
bloxdTextureId*block is not in this header — it is generated per pack from referenced names (Texture API) #ifdef BLOXD_ALPHAmarks conditional fields (Preprocessor)- Differences from the v4 header (6,021B) → Version History: v5
- How the header is validated (HEADER_VERSION) → Shader Validation
// 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.
// It's below the horizon (y < 0) at night. The moon is always opposite it.
fn bloxdSunDirection() -> vec3f {
return bloxdPackInputs.sunDirection;
}
// The unit vector the light that casts bloxdShadow's shadows travels along,
// in world orientation: from the sun by day, the moon by night, and the
// default sky's sun when there's no sun. Its y is never above 0 (0 when the
// sun is on the horizon).
fn bloxdShadowDirection() -> vec3f {
return bloxdPackInputs.shadowDirection;
}
// 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. Normals don't change.
}
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, // Final RGB colour, emission and fog included.
}
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));
}Related
- API Reference — the annotated version of this header
- Shader Validation — HEADER_VERSION and saved-pack re-validation
- Engine Data — the measurement ledger