Input & output structures
Target API: 5 · Target build:
bbb6l5(2026-11-20, production and preprod) · Status: Analyzed (restored verbatim from the live header)
Seven structs are readable/writable by packs. Every field is listed below (#ifdef fields are conditional). The full header is in Engine Internals.
BloxdVertexIn (vertex hook input)
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.
}| Field | Type | Description |
|---|---|---|
position | vec3f | render-space position (world space via bloxdWorldPosition()) |
normal | vec3f | unit vector pointing away from the face |
localPosition | vec3f | model-local coordinates; vec3f(0.0) for terrain and liquid; for a player’s arm, a held sword or windmill blades this rotates with the model |
flags | BloxdFlags | face kind (Flags) |
BloxdVertex (vertex hook output)
struct BloxdVertex {
position: vec3f, // The render position output. Normals don't change.
}BloxdSurfaceIn (surface hook input)
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.
}| Field | Type | Description |
|---|---|---|
colour | vec3f | RGB = texture × tint × AO, baked by the mesher |
alpha | f32 | opacity |
enchantTier | u32 | enchant tier 1–5; 0 for anything not enchanted |
enchantColour | vec4f | enchant RGB plus an animated alpha (.a) — reading .a per fragment gives a moving pattern for free; all zero on unenchanted faces |
enchantSpeed | f32 | enchant pattern speed («faster at higher tiers») |
overlayColour | vec4f | entity overlay (hurt flash etc.) RGB + alpha; 0 outside players/mobs; mixed in by bloxdLitColour before lighting |
position / normal / localPosition / flags | — | same meanings as BloxdVertexIn, after the vertex hook (they follow moved vertices) |
textureId | u32 | this face’s texture; compare with bloxdTextureId*; 0 when the face has no texture — most models use textureId 0 (model-owned textures, player skins) |
textureRotation | u32 | quarter turns clockwise (0–3), applied by bloxdTexel |
uv | vec2f | the texture spans 0–1; fract(uv) is drawn (integer steps tile) |
mipLevel | f32 | mipmap level: 0 = full size, 1 = half… |
BloxdSurface (surface hook output)
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.
}| Field | Type | Condition | Description |
|---|---|---|---|
colour | vec3f | always | RGB output |
alpha | f32 | #ifdef BLOXD_ALPHA (all liquid + non-strict terrain/model) | opacity output |
emission | vec3f | always | emissive RGB — added after lighting, before fog |
enchantColour | vec4f | always | enchant output, mixed in by bloxdLitColour |
overlayColour | vec4f | always | overlay output, mixed in by bloxdLitColour |
bloxdDefaultSurface passes enchantColour / overlayColour through unchanged, so the default look matches v4’s engine-internal behavior. Zero out.enchantColour to remove the glint under custom lighting; amplify out.overlayColour.a to emphasize the hurt flash.
BloxdLightIn (light hook input)
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.
}Field-by-field meaning and role in lighting math: see Lighting.
Versus older API versions: fogVisibility (v2–v4) is now fogAlpha with inverted semantics (0 = no fog); engineColour is now litColour; light-level wording is «0 when !bloxdLit()». The full per-version field changes: Version History.
BloxdLight (light hook output)
struct BloxdLight {
colour: vec3f, // Final RGB colour, emission and fog included.
}BloxdOpaqueBehind (special-function return)
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.
}Return value of bloxdOpaqueBehind(). Use in liquid variants behind an #ifdef BLOXD_SCENE_DEPTH guard (the field was found: bool in v2). The shadow-era additions (bloxdShadow / bloxdAirShadow return plain f32) are documented in Functions.
Conditional fields ↔ macros
| Field | Exists when | Note |
|---|---|---|
BloxdSurface.alpha | #ifdef BLOXD_ALPHA | all liquid variants + non-strict terrain/model |
bloxdOpaqueBehind() call | #ifdef BLOXD_SCENE_DEPTH | all liquid variants |
BLOXD_STRICT controls hook existence (vertex hooks), not struct shape. See Preprocessor.
Writing conventions (recap)
- Never construct output structs directly — start from
bloxdDefault*; in light hooksvar out = s;also works - A bare
var x: BloxdSurface;is a validation error - Hook parameters are read-only — copy before mutating
Related
- Lighting · Flags · Texture API