Skip to content
Converts Minecraft models to and from various formats
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
src/blockmodel fixing test data paths Jan 14, 2019
.travis.yml adding travis Jan 14, 2019 cleaning up tests Oct 1, 2015 fixing broken dist Oct 1, 2015 Update Jan 14, 2019
setup.cfg fixing up distribution Oct 1, 2015


Build Status

A Python library that converts Minecraft models to and from various 3D formats.

blockmodel is the core model creation library used by to create models on its servers.

blockmodel supports python 2.7 and 3.6


The easiest way to use blockmodel is to install it with pip pip install blockmodel

Or you can clone this repo and run the usual python install


First create an instance of blockmodel.BlockModel with one of its classmethods



BlockModel.from_json(as_json, max_size=None)

The json has to be a multi-dimensional array of blocks [x][y][z] where each block is an array of block ids and data[id, data]. For example:


This will create a 9x9 block of dirt with grass on top and a partly exposed block of diamond ore in the middle. (Note this method takes json encoded string not a python array.)

BlockModel.from_png(as_png, max_size=None)

The png reader will create a model one block high in which the block id is taken from the red value of each pixel.

BlockModel.from_sparse_json(as_json, max_size=None)

This is an alternative way to define a block model using json. Instead of using a multi-dimensional array you use an array of individual block locations in the form [x, y, z, id, data]. For example

[[7, 4, 2, 2, 0],
[8, 4, 2, 2, 0],
[9, 4, 2, 2, 0],
[9, 4, 3, 2, 0],
[9, 4, 4, 2, 0],
[8, 4, 4, 2, 0],
[7, 4, 4, 2, 0],
[7, 4, 3, 2, 0]]

This makes a 9x9 ring of grass

BlockModel.from_schematic_file(schematic_file_path, max_size=None)

This uses Minecraft's schematic file format as produced by WorldEdit

Once you have created a model you can save it in one of five formats

  • obj
  • x3d
  • collada
  • schematic
  • csv


block_model = BlockModel.from_schematic_file(schematic)
obj = block_model.obj

Or you can use the helper methods to save models directly to file

  • save_as_stl(file_path)
  • save_as_obj(file_path)
  • save_as_x3d(file_path)
  • save_as_collada(file_path)
  • save_as_schematic(file_path)

These functions will create obj, x3d and collada files inside a folder with the correct texture

For example:

earth_json ="""[
block_model = BlockModel.from_json(earth_json)

This will save out a collada model to file from json.

You can’t perform that action at this time.