Importing custom models
Import external 3D models and place them in your map. An imported model becomes a custom block or a prop, and once you build the resource pack it looks the same in game.
| Format | Extension | Kind |
|---|---|---|
| Blockbench · NP model | .bbmodel · .npmodel | Cube models (boxes, like Minecraft models) |
| OBJ · glTF · FBX | .obj · .gltf · .glb · .fbx | Polygon (triangle) models |
Minecraft models are made only of boxes (cubes). So a polygon model must be converted to a cube model or to blocks on import before it can appear in game.
How to open
Section titled “How to open”| Method | Action |
|---|---|
| Content Browser Import button | Choose a file and the Import model dialog appears. Right-click an empty area › Import… does the same. |
| Double-click a model file in Content Browser Project files | Imports it through the dialog. |
| Drag a model file from the Content Browser into the viewport | For OBJ, FBX and glTF, the dialog opens first. After importing, drag the prop from the Content Browser again. .bbmodel and .npmodel are imported right away and placed at that spot. |
Since 0.9.9: OBJ, FBX and glTF always go through the dialog, even when dragged in or double-clicked in Project files. Previously they were imported directly as “Original shape” and left out of the resource pack.
Quick start
Section titled “Quick start”- Press Import in the Content Browser and choose an
.objfile. - Leave Display (default) under Convert in the dialog.
- Set Units and Up axis to match the program the model was made in. To set the size, enter a block count in Fit size.
- Press Import. The model is registered as a prop.
- Click that prop in the Content Browser to switch to the Prop tool (8). Click an empty spot to place it. After placing, the tool switches to Selection, so you can move it right away with W · E · R.
- Build the resource pack with Build › Build resource pack and it looks the same in game.
Import modes
Section titled “Import modes”Choose under Convert in the dialog. If there are polygon files, the default is Display; if there are only cube models, the default is Keep original shape.
| Mode | Result | In game | Use for |
|---|---|---|---|
| Display | Converts to a cube model (one palette texture) by merging same-color cells into boxes, and registers it as a prop. | Exported as a resource pack model and shown via ItemDisplay. | Sculptures · decorations |
| Convert to blocks | Splits the model into cells and builds it from the closest-colored vanilla blocks. Saved as a prefab (tag Model conversion) and placement mode starts right away. | Just blocks. | Things to stand on · large terrain features |
| Keep original shape | Registers the model as is. Cube models within one block become custom blocks; the rest become props. | Only cube models appear. Polygon faces cannot become game models. | .bbmodel · .npmodel |
Since 0.9.7: Display and Convert to blocks were added. Previously OBJ, FBX and glTF were dropped from the game entirely.
Dialog fields
Section titled “Dialog fields”| Field | Value | Shown for | Meaning |
|---|---|---|---|
| Convert | Display · Convert to blocks · Keep original shape | All | Table above |
| Display precision | 4–128 cells (default 32) | Display | Number of cells to divide the longest side into. Higher is smoother but uses more boxes. |
| Block size | 2–256 blocks (default 24) | Convert to blocks | Number of blocks along the longest side |
| Blocks to use | All solid-color blocks · Concrete · wool · Terracotta · Building blocks (stone · wood · ore) | Convert to blocks | Block set to match colors against |
| Fill inside | On · Off | Convert to blocks | Fills the inside of closed models. When off, only the outer shell is built. |
| Units | 1 unit = 1 block (meter) · 1 unit = 1 pixel (1/16 block) · Centimeters (0.01) · Inches (0.0254) · Millimeters (0.001) | All | Size of one unit of model coordinates |
| Up axis | Y up (glTF·Godot·Minecraft) · Z up (Blender originals·3ds Max, etc.) | All | The model’s up direction |
| Fit size | 0–256 blocks (0 = off) | Display · Original shape | Fits the longest side to this number of blocks. |
| Shrink textures over 512px | On (default) | Display · Original shape | Shrinks large textures to a power-of-two size. |
- Convert to blocks picks blocks by the average color of the jar textures when a Minecraft jar is available.
- A prefab converted to blocks becomes one actor when placed (Prefabs).
Placing and moving props
Section titled “Placing and moving props”Place Display and Original shape props with the Prop tool (8).
| Input | Action |
|---|---|
| Click a prop in the Content Browser | Selects it as the prop to place and switches to the Prop tool. |
| Click an empty spot (Prop tool) | Places the prop. After placing, the tool switches to Selection and that prop is selected. |
| Shift+click | Places and stays in the Prop tool (keep placing). |
| Drag a prop into the viewport | Places it at that spot. |
| Click a prop | Selects that prop (works in the Selection tool too). |
| Drag a handle | Move, rotate or scale along the red X, green Y or blue Z axis. Releasing is one undo step |
| White square in the center | Move = along the floor plane (XZ); Size = uniform |
| W · E · R | Move · rotate · size handles |
| Ctrl+D | Duplicate the selected prop |
| Del | Delete the selected prop |
| End | Drop the selected prop to the floor |
| Esc | Cancel the handle drag (back to the start) → deselect the prop |
Since 0.9.8: Prefabs, block-converted models, display models and Prop tool clicks all switch to the Selection tool after one placement. To keep placing, use Shift+click.
This is the Prop group of the Tools panel for the Prop tool.
| Field | Default | Meaning |
|---|---|---|
| Move · Rotate · Size | Handle mode (W · E · R) | |
| Snap | 0.5 block · 15° · 0.125 | Move, rotate and size steps when grid snap is on |
| Position · Rotation° · Size (X · Y · Z) | Numeric input for the selected prop | |
| Duplicate · Delete · Reset rotation · scale | For the selected prop |
- Viewport right bar World / Local: in Local, the handle axes follow the prop’s rotation.
- Turn on surface snap (magnet) on the viewport right bar to make dropped props stick to surfaces and stand along the normal.
Changing the import mode
Section titled “Changing the import mode”Re-import an already imported model in a different mode while keeping the same id. Placed copies use the same id, so they change too.
- Right-click the model in the Content Browser and choose Change import mode…. Import mode… on the top bar of the Asset Editor does the same.
- Choose a mode in the dialog and press Reimport.
- If you choose Convert to blocks, a new prefab is made from the source and placement mode starts.
Since 0.9.9: Change import mode… was added. Use it to switch OBJ, FBX and glTF imported as “Original shape” to Display.
Asset Editor
Section titled “Asset Editor”Double-click a custom block or prop in the Content Browser (or right-click › Open in Asset Editor) to open it. You can also open it with Window › Asset Editor (selected custom). It starts as a floating window; dock it with the button at the right of its bar.
| Top bar | Action |
|---|---|
| Save | Saves the registry and painted layers. Unsaved UVs are saved to a new version file. |
| Reimport | Reads the source file again (after editing in Blockbench etc.). |
| Import mode… | “Changing the import mode” above |
| Include in resource pack | When off, this asset produces no resource pack files (it stays in the registry and map). |
| Preview in viewport | Selects this asset as the block or prop to place. |
| Tab | Contents |
|---|---|
| Preview | Real-size 3D view. Toggle block grid, model bounding box, collision box and lighting |
| UV | UV editor (.bbmodel · .npmodel only) |
| Paint | Texture painting |
| Version | List of the source and saved versions. Revert to this version (does not delete files) |
| Details field | Meaning |
|---|---|
| id | Lowercase letters, digits and _. If you change it, copies already placed keep the old id. |
| Type | Custom block (1-block note block state) · Prop (item display) |
| Folder · Tags | Content Browser folder and search tags. The light=N tag is the emission strength. |
| Collision | Full cell (full) · None (none) · Box (box) + min · max. Used by the server plugin. |
| Transform (placement defaults) | Initial move, rotation and size when placing |
| Resource pack item | Include or not · item kind (prop · block · weapon · armor · effect) · item model id · display slot |
UV editing scope
Section titled “UV editing scope”- The UV editor (Ctrl+U) opens only
.bbmodeland.npmodelmodels. - OBJ, FBX and glTF cannot be UV-edited. Paint their colors in the Paint tab.
- How they go into the game is set with Import mode….
What goes into the resource pack
Section titled “What goes into the resource pack”Build the complete resource pack with Build › Build resource pack (or Window › Resource pack › Build resource pack).
| Asset | In the resource pack |
|---|---|
| Display props · cube model props | Item models. The server shows them with ItemDisplay. |
| Custom blocks | Block models assigned to note block states |
| “Original shape” polygon props | Automatically converted to Display (cube models) when building the resource pack, with a warning. |
| Assets with Include in resource pack off | Not included. |
| Prefabs converted to blocks | Vanilla blocks, so no resource pack is needed. |
Since 0.9.9: “Original shape” OBJ, FBX and glTF are also automatically converted to Display and included in the resource pack.
For detailed pack structure, see Resource pack and HUD.
Options
Section titled “Options”| Setting | Where | Meaning |
|---|---|---|
| Convert · precision · block size · blocks to use · fill inside · units · up axis · fit size · texture shrinking | Import model dialog | The “Dialog fields” table above |
| Snap · Position · Rotation° · Size | Tools panel › Prop | Prop tool |
| Grid snap · World / Local · surface snap | Viewport right bar | Prop move step and axes |
| Include in resource pack · Collision · Resource pack item | Asset Editor | Per-asset settings |
Shortcuts
Section titled “Shortcuts”| Key | Action |
|---|---|
| 8 | Prop tool |
| W · E · R | Prop move · rotate · size handles |
| Shift+click | Keep placing |
| Ctrl+D | Duplicate prop |
| Del | Delete prop |
| End | Drop to floor |
| Esc | Cancel handle drag → deselect |
| Ctrl+U | UV editor |
| Double-click · Enter (Content Browser) | Open the Asset Editor |
Tips / cautions
Section titled “Tips / cautions”- If an imported model is missing from the resource pack, check whether it is “Original shape” and switch it to Display with Change import mode….
- Setting Display precision too high increases the box count and the load in game. Start at 32 and raise it only when needed.
- For things people must stand on (bridges, floors), use Convert to blocks instead of props. Props have no collision by default.
- FBX is read by the loader built into the editor; OBJ, glTF and bbmodel are read by the editor core.
- After editing a model file, apply the changes with Reimport in the Asset Editor (or Content Browser right-click › Reimport).