Blockbench & the .bbmodel format

What a .bbmodel file actually is, which format to start a project in, the element rules the game stopped enforcing in 1.21.6 and 1.21.11, and the gotchas that cost the most time — measured against the game's own models where a number is claimed.

What a .bbmodel is, and is not

.bbmodel is Blockbench's project format: a single JSON file holding the geometry, the UV map, the embedded textures, the animations, and the editor state for one project. It is a save file, not a game asset. Minecraft cannot load a .bbmodel; nothing in assets/ or data/ ever has that extension. What ships in a resource pack is the export — a Java block/item model JSON — and what ships to a server plugin is the .bbmodel itself, which the plugin converts.

That distinction is the source of the most common beginner failure: the model is finished, the file is in the pack, and the game renders nothing, because the file in the pack is the project rather than the export.

Two consequences worth knowing before you start:

• Everything is in the one file. Textures are embedded, so a .bbmodel is self-contained and can be handed to someone else as a single attachment. This is why server plugins accept it directly.
• The file you author is not the file you ship. A pack ships the exported JSON plus a separate PNG; a plugin ships the project. Keep the project in source control and treat the export as a build artefact.

Choosing a project format

Blockbench's format choice at project creation is not cosmetic — it decides which features the editor exposes and which restrictions it enforces. Choosing wrong and discovering it after a day of modelling is unpleasant, because format conversion is lossy in the direction that matters (a Generic model dropped into Java Block/Item loses whatever exceeds the Java limits).

From an empty project to a model in the game

The rest of this page is about the file. This section is the part that stops people on day one: an empty Blockbench window has no obvious way to make anything, and the tool most people reach for first does not exist.

1. Pick the format before you build

The project format decides what the model can ever be — which export it produces, and whether it can animate. A Java Block/Item project can never hold keyframes, because vanilla Java has no animated block-model format. If you want motion, choose an entity or Generic Model format up front; converting later is not a button. See Choosing a project format.

2. Know which mode you are in

Blockbench has four working modes, switched from the tabs at the top: Edit, Paint, Animate and Display. Adding geometry is an Edit mode action, so if a project seems to offer no way to add anything, check which mode you are in before anything else.

3. Add geometry

There is no line tool and nothing that draws shapes in 3D. Blockbench builds models from elements, and the creation actions are the whole list: Add Cube, Add Mesh, Add Group and Add Texture Mesh. Which of them a project offers depends on its format. Start with Add Cube, then shape it with the Element panel’s Position, Size, Pivot Point and Rotation sliders, or drag it in the viewport.

4. Give it a texture

The Textures panel has Create Texture for a new blank sheet and Import Texture for an existing image. Paint in Paint mode, and read UV mapping before you start: box UV and per-face UV lay the sheet out differently, and switching later repaints nothing for you.

5. Set how it looks in a hand or a frame

Display mode positions the model for each slot it can appear in — first and third person, head, ground, item frame, GUI — against a reference model. Skip this and a correct model can still look wrong the moment someone holds it.

6. Get it into a pack

A Java Block/Item project exports a .json block model. That file goes under assets/<namespace>/models/ in a resource pack with its textures under assets/<namespace>/textures/, and on current versions an item reaches it through an item model definition — see Resource packs. The .bbmodel itself stays behind as your working file; the game never loads it. A server-side model plugin is the exception, and it is covered in Handing a .bbmodel to a server plugin.

The element rules, and which ones still apply

Every modelling guide in the ecosystem teaches the same element rule: a cube may be rotated about one axis, by an angle from -45, -22.5, 0, 22.5, 45, and nothing else. That rule dates from 14w07a, when custom block models were first given rotation at all. It is no longer the game's rule.

This is not a paper change. In 26.3 Snapshot 10 the game's own models already use angles the old rule forbids: of 303 element rotations across 95 vanilla models, 10 fall outside the legacy set — seven at -67.5°, two at -90°, and one at 0.0001°. They are all sign templates.

Two rotation forms

The multi-axis change did not extend the old object; it added a second shape. Both are accepted, and vanilla currently uses both — 301 elements in the angle/axis form and 2 in the per-axis form.

assets/<namespace>/models/block/example.json — the classic form

"rotation": { "angle": -22.5, "axis": "y", "origin": [8, 0, 8] }

assets/<namespace>/models/block/example.json — the 1.21.11+ per-axis form

"rotation": { "x": 180, "y": -67.5, "z": -180, "origin": [8, 0, 8] }

Note what the second form does not contain: there is no axis field. An element either names one axis and one angle, or gives per-axis angles under x, y and z. Mixing the two in the same object is not a documented shape and should not be relied on.

Coordinate range

Element from and to coordinates are clamped to -16 through 32 — one block of overhang in each direction around the 16×16×16 block volume. Vanilla stays inside it: across all 1,204 elements in the game's models, zero coordinates fall outside that range. A cube pushed beyond it does not error loudly; it is clamped, and the model silently renders wrong.

What the game reads, measured

An exporter writes what it knows; the vanilla loader reads what it recognises and ignores the rest. Reading the shipped models is the cheapest way to see where those two sets differ. All counts below are from 26.3 Snapshot 10 (resource pack format 97), across 4,192 model files, of which 347 define their own elements.

At the top level of a model file, the distribution shows how little of a pack is actually geometry: textures appears in 4,147 files and parent in 3,887, but elements in only 347. Most vanilla models are a parent reference plus a texture map. A pack that redefines geometry where it only needed to retexture is doing more work than the game asked for, and inherits none of the parent's later fixes.

Exporter leftovers

Two keys in vanilla's models are not vanilla model fields at all:

• groups — the Blockbench outliner hierarchy, present in four block models (custom_fence_side_north, _east, _south, _west), each carrying a group object complete with Blockbench's "color": 0 field.
• texture_size — present in exactly one model, heavy_core.json, set to [16, 16], which is the default.

Both are inert. They are visible proof that Mojang exports from Blockbench too, and they are a useful calibration: the vanilla loader ignores unknown keys rather than failing, which is why a stray groups array in your own export costs bytes but not correctness.

UV mapping: box vs per-face

Blockbench offers two UV modes, and the choice constrains everything downstream.

Two rules keep a Minecraft-style model looking right:

• Preserve the pixel ratio. One texture pixel corresponds to one unit of model scale. A face whose UV rectangle does not match its geometry squashes or stretches the texture. Blockbench's Auto UV does this correctly for per-face mapping.
• Avoid mixels. A “mixel” is an element of mixed resolution — a cube smaller than one pixel, or an over-inflated one — so that the model shows two effective pixel sizes at once. The vanilla art style does not use them (with the narrow exception of slightly inflated elements on some models).

Bones, parenting and pivot points

Blockbench's vocabulary is worth using precisely, because plugin documentation assumes it:

Parenting is placing one bone inside another so the child follows the parent. Build the hierarchy outward, from bones near the centre of the body to bones away from it: torso → arm → hand. A consistent naming convention pays for itself the moment a config file has to reference a bone by name.

Pivot points are the single most common cause of animation that looks wrong for reasons the author cannot name. A pivot belongs at the joint — the point of attachment between two bones — not at the centre of the geometry and certainly not left wherever it landed. Set it with the Pivot tool, or centre it to the selection from the Element panel, and set it on the group, not on a cube inside the group.

.bbmodel format versions & breaking changes

Every .bbmodel carries a format_version. Anything that reads these files should branch on it, because the format has broken compatibility more than once. Additions are not listed by Blockbench; only the changes that alter how existing data is interpreted.

Animation

Animation is a per-format capability, not a universal one. Model animations are available in Bedrock Model, Bedrock Legacy, Modded Entity, OptiFine Entity (via expressions), Generic Model and GeckoLib — and not in Java Block/Item, because vanilla Java has no animated block-model format. Animating a resource-pack model means either the item-definition system, display entities, or a server-side plugin; it does not mean keyframes in the model file.

Where animation is available, the mechanics are consistent:

• Keyframes are drawn as diamonds for linear interpolation and circles for smooth. Step keyframes hold. Bezier keyframes exist, but consumers vary in whether they interpolate them.
• Channels are per-bone and per-property (rotation, position, scale). Only bones can be animated; elements cannot.
• The playhead snaps to valid frame times by default; hold Ctrl to scrub smoothly.

Handing a .bbmodel to a server plugin

Server-side model plugins take the opposite route from a resource pack: you give them the .bbmodel project, and they generate the resource pack for you by splitting the model into per-bone item models. The Codex documents this in detail on the ModelEngine page; the parts that are really modelling decisions belong here.

• Bone count is entity count. Each bone that contains geometry becomes a rendered entity in the world. A model with sixty bones costs sixty entities per spawn. Bones with no geometry are virtual and cost nothing, so the balance to strike is between cubes (free) and bones (expensive but animatable).
• Bone names are an interface. Prefixes and reserved names change behaviour — head tracking, seats, hitboxes, nametag anchors. A rename is an API change, so settle the naming before anyone writes config against it.
• Orientation and ground level are conventions. Model facing north, feet on the grid: the grid line is ground level, and a model built floating will spawn floating.
• The hitbox is modelled, not configured. A dedicated hitbox bone supplies both the collision box and the eye height, taken from that bone's pivot Y. A pivot at or below zero produces a mob that takes damage for no visible reason — it is suffocating.

Gotchas

Licensing

Blockbench is free and open source, for any purpose including commercial. Its documentation is explicit that what you make with it is your artwork and yours to redistribute — the tool claims nothing. That is a statement about Blockbench, not about the assets you feed it: a model traced from someone else's work, or built on a purchased asset, carries whatever licence that source came with.

Sources

• Blockbench Wiki — The .bbmodel format — format intent, format_version, and the 4.9 / 4.10 / 5.0 breaking changes.
• Blockbench Wiki — Formats — the per-format capability matrix this page's format table is drawn from.
• Blockbench Wiki — Overview & Tips — terminology, pivot points, parenting, vertex snap, Z-fighting, sliders and expressions.
• Blockbench Wiki — Minecraft Style Guide — element count, UV ratio, mixels, shading conventions.
• Blockbench Wiki — FAQ — licensing, Mojang's internal use, backups, the console.
• Blockbench Wiki — 3D Export — OBJ / glTF / FBX / DAE trade-offs for non-Minecraft targets.
• Minecraft Wiki — Model — the version history behind the 14w07a, 1.21.6, 1.21.11, 26.1 and 26.3 rotation and element changes.
• ModelEngine — Creating a Model — bones vs cubes, hitbox and eye height, ground level and facing.
• ModelEngine — Animating a Model — 20 fps snapping and keyframe interpolation support.
• misode/mcmeta — assets-json — the shipped models every measured count on this page was taken from, via tools/model_shape_audit.py.