Skip to Content
GuidesModels and textures

Models and textures

Target API: 5 · Target build: bbb6l5 (verified in production and preprod 2026-11-20) · Status: Analyzed (restored from header & validator)

What the new v5 Model hooks draw and read.

What the Model program draws

  • Block models: half blocks (slab), stairs (stairs), crossed-plane plants — tall grass, flowers, crops, cobwebs (flat)
  • Items: held (held), dropped (dropped), thrown (thrown — snowballs, arrows, rockets)
  • Entities: players, mobs, NPCs (lifeform) — including armour and cosmetics

Terrain (full blocks) and Liquid (water) never enter this program.

What reads differently

Model faces carry three things terrain faces never have:

InformationFieldValue on terrain
model-local coordinateslocalPosition: vec3fvec3f(0.0) (no model)
enchant stateenchantTier / enchantColour / enchantSpeedall 0
entity overlayoverlayColour0

And textures mean something different: terrain faces carry atlas textureIds, but most models use textureId: 0 (“no texture”) — player skins and mob textures are not in the atlas namespace. surface.colour already contains skin × tint, so work from it (model-owned textures).

flags’s held / dropped / thrown / lifeform / placed are meaningful only on model faces (Flags).

localPosition

The model-instance-local position before world placement; vec3f(0.0) for terrain/liquid.

  • For a player’s arm, a held sword or windmill blades it rotates with the model
  • Keyed per-part animation and bending effects become a one-field write — “how far up the blade am I” is directly localPosition.y
  • In light structs it is the post-vertex-hook value (header: “the same as in BloxdVertexIn, after the vertex hook”)

Selection patterns

fn bloxdModelSurface(surface: BloxdSurfaceIn) -> BloxdSurface { var out = bloxdDefaultSurface(surface); if (surface.flags.lifeform && !surface.flags.held) { out.colour *= 1.05; // lift world entities, exclude the hand } if (surface.flags.held) { out.colour *= 1.15; // brighten the local player's held items } return out; }

Full examples: model shader recipes and enchant effects.

Terrain / Liquid / Model cheat sheet

Want to affectHooksSelection fields
full-block lookbloxdTerrain*material flags (opaque / rock…)
waterbloxdLiquid*always Liquid (no Liquid hooks = water untouched)
plants, slabs, stairsbloxdModel*flags.flat / slab / stairs
held itemsbloxdModel*flags.held
dropped itemsbloxdModel*flags.dropped
thrown itemsbloxdModel*flags.thrown
players & mobsbloxdModel*flags.lifeform

Lighting

bloxdModelLight takes the same BloxdSurface / BloxdLightIn and works with bloxdDefaultLight / bloxdLitColour(). The enchant glint (enchantColour) and hurt flash (overlayColour) mix inside bloxdLitColour, so defaults preserve both looks automatically; to control them see enchant effects.

Internals

How models render and how flags/enchant inputs flow: Engine Internals: Model Rendering; generated symbols like bloxdSpItemLocalPosition and bloxdSpEnchant are listed in restrictions.