Skip to Content
API ReferenceInput & output structures

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. }
FieldTypeDescription
positionvec3frender-space position (world space via bloxdWorldPosition())
normalvec3funit vector pointing away from the face
localPositionvec3fmodel-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
flagsBloxdFlagsface 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. }
FieldTypeDescription
colourvec3fRGB = texture × tint × AO, baked by the mesher
alphaf32opacity
enchantTieru32enchant tier 1–5; 0 for anything not enchanted
enchantColourvec4fenchant RGB plus an animated alpha (.a) — reading .a per fragment gives a moving pattern for free; all zero on unenchanted faces
enchantSpeedf32enchant pattern speed («faster at higher tiers»)
overlayColourvec4fentity 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)
textureIdu32this face’s texture; compare with bloxdTextureId*; 0 when the face has no texture — most models use textureId 0 (model-owned textures, player skins)
textureRotationu32quarter turns clockwise (0–3), applied by bloxdTexel
uvvec2fthe texture spans 0–1; fract(uv) is drawn (integer steps tile)
mipLevelf32mipmap 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. }
FieldTypeConditionDescription
colourvec3falwaysRGB output
alphaf32#ifdef BLOXD_ALPHA (all liquid + non-strict terrain/model)opacity output
emissionvec3falwaysemissive RGB — added after lighting, before fog
enchantColourvec4falwaysenchant output, mixed in by bloxdLitColour
overlayColourvec4falwaysoverlay 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

FieldExists whenNote
BloxdSurface.alpha#ifdef BLOXD_ALPHAall liquid variants + non-strict terrain/model
bloxdOpaqueBehind() call#ifdef BLOXD_SCENE_DEPTHall 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 hooks var out = s; also works
  • A bare var x: BloxdSurface; is a validation error
  • Hook parameters are read-only — copy before mutating