Submission Method: MCEdit

MCEdit is a program developed primarily by codewarrior0 (with many other contributors) to enable Minecraft players to freely edit their Minecraft world outside of the game.

To quote the MCEdit Wikipage:

MCEdit is a versatile map editor, designed for moving blocks, creating land, adding others' creation, or just about anything possible within Minecraft. With it, you can…

- open a level of nearly any type and fly around in glorious 3D!
- select millions of blocks and clone them anywhere else in the level
- fill a boxy selection with the block of your choice, or replace one kind of block with another
- export blocks to a "schematic" file for later use
- import a schematic or an entire level into any world using the crane
- move the player or his spawn point
- create and and remove chunks from the world
- fill blackened areas with light
- find bugs!

Quick Info

Why do we like it?

We find MCEdit to be the perfect environment for exploring AI generative techniques within a Minecraft world (without having to worry about hooking an agent up into the actual game itself). Using the "Filter" plugin system included in MCEdit, you can easily write python scripts that can access and manipulate a Minecraft map file with little-to-no overhead.

How to get it?

Follow the directions below in "Getting Started"

How to submit with this method?

  1. Login to the submission website
  2. Go to the submission page
  3. In the file section, add a ZIP file, which contains a python filter file, complete with a filter "perform function", and optionally, any other required files necessary for your code (data files, etc). This will be unzipped into the filters folder and run from within MCEdit by the submission server. The perform function should contain the code that builds the settlement for the map and within the coordinates specified as parameters in the perform function. The coordinates give the corner of a bounding box, the settlement should be built within that bounding box.
  4. If you have other requirements, please document them and include them with your submission.

Other important information

MCEdit has its own API page which explains a lot of its inner methods and functionality. Check it out for detailed function and class explanations.

Getting Started

The first thing you need to do is clone this repo to get the latest version of the MCAI Framework. This is an adapted version of the MCEdit-Unified repository found here, with some extra functionality we added in.

To clone, use the recursive option of the clone command:

git clone --recursive

After cloning to your computer, there are a few packages you will need to install. We recommend setting up an Anaconda environment specifically for mcedit to run within. To learn how to install Anaconda, look here: How To Get Anaconda. When creating a new environment for anaconda, make sure to use the python=2.7 parameter. MCEdit and some of the required libraries only run in python 2.7.
Here is an example of creating a new anaconda environment:

conda create -n py27 python=2.7 anaconda

To run your anaconda environment, run:

source activate [name of environment]

To deactivate your environment, run:

source deactivate

You will also need PyOpenGL, numpy, pygame, pyyaml, pillow, and ftputil to run mcedit. Install them inside your conda by running:

pip install PyOpenGL numpy pygame pyyaml pillow ftputil==3.4

From the official mcedit wiki page:

Ubuntu Linux users can install the following packages via apt-get to grab all the dependencies easily and install them into the system python. This also downloads all libraries required to build these modules using pip install

apt-get install python-opengl python-pygame python-yaml python-numpy

If everything was installed correctly, you should now be able to run MCEdit with `python`.

IMPORTANT NOTE: mcedit MUST be run with python2.7! It will not work with python 3!

Windows only section

You will also need to install the pypiwin32 package with

pip install pypiwin32

## Mac only section
If you are getting a _ValueError: unknown locale: UTF-8 in Python_, edit your bash profile and add these two lines:

export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

Then remember to reload your profile.

Using MCEdit


After opening MCEdit, you will be taken to the main menu screen.


New World will auto generate a new world for you. You can set different settings like "creative" v "survival" mode, how many chunks are first loaded, and other things.

Quick Load or one of the resulting load buttons below will allow you to load up a saved world. Just remember not to have it open in Minecraft at the same time, or MCEdit will crash.

Moving Around

Once you enter a world, you'll see it much as you would if you were playing it in Minecraft. You can move around the space using _wasd_ and _ijkl_ to look around. You can also hold the right mouse button to look around. Left shift will make you go down, space will make you go up.

The Toolbar

Select Tool:

This allows you to select subregions of the world, by clicking and dragging across the screen. You can also use the three nudge buttons in the bottom center of the screen to change the selection box size and position. Left click holding and using wasd changes it a little, right click holding changes it a lot. On the left side, you can modify the way your select tool works
- Nudge: works like the center nudge tool, except it moves over the selected blocks
- Deselect: clears the current selection
- Select Chunks: completely selects all chunks that your selection touches, from bottom to top
- Delete Blocks removes all blocks in your selection, as does Delete Entities and Delete Tile Ticks, respectively.
- Analyze: will show you a report of your selection box makeup.
- Cut, Copy, and Paste: work a lot like you'd expect them
- Export: saves this selection box to a schematics file, which allows you to share it between worlds

Brush Tool:

Allows you to rapidly place blocks in the world. Using the fill function allows you to *really* rapidly place blocks in the world.


Clones the selected chunk. You can place it by using paste.


These are covered more in detail in the "Filters In Detail" section. These custom-made scripts allow us to run code on top of the Minecraft world to do a variety of things, like rapidly build forests, carve out oceans, or procedurally build cities. To use one, simply select one of the filters, then fill in the given parameters however you wish.

Filters: How To

What is a filter?

Filters are commands that MCEdit can run to manipulate the Minecraft World. Players, designers, and programmers can use them to add functionality to MCEdit (as well as programmatically change their respective world in the Minecraft game). They can be used to do almost anything in the world, from flooding an entire area with water, to constructing volcanoes and enormous trees, to searching for all the stone blocks in a section of earth and changing them into gold ore.

All filters are located in the MCEdit root directory's "stock-filters" folder. If you want to create your own filter, you must put it in this folder for MCEdit to see it.

If you need some examples…

One of the biggest MCEdit filter programmers by far is Adrian Brightmoore who was created hundreds of filters and shared them for public use. If you are interested in learning more, visit his website, or search his youtube channel.

A few other filter programmers of note are SethBling and TexelElf who have some good examples of filters on their websites.

Build your own

Building your own filter is as easy as making a python script, with some additional stuff. A filter file is just a python file placed within the stock-filters folder contained within the root directory of this repo. It has two main requirements, which are described in the following two sections:

User Input

Filters can take user input (which can be any kind of object) if they contain an input dictionary. It should look somewhat like this example:

inputs = (
        ("Name_Of_Filter", "label"),
        ("Material1", alphaMaterials.StoneBricks),
        ("Density", (10, 1, 100)),
        ("Chance", 10),

In this example, the first entry in the inputs dictionary is just a label, which will be displayed in MCEdit at the top of the filter UI. The 'Material1' entry will allow the user to specify a type of material, with the default being alphaMaterials.StoneBricks. The third entry allows the user to specify an integer value with a default of 10, a minimum of 1, and a maximum of 100. The fourth and final entry is simply an integer input with no restrictions.

The Perform Function

All filters must have a perform function, which is called anytime the filter is called in MCEdit. You can pretty much do anything you want in this function including but not limited to: calling other functions, File I/O, training, testing, building/destroying, evolving, overthrowing governments, etc. The perform function takes three parameters and looks like this:

def perform(level, box, options):
  print('Perform things!')

The level parameter is the entirety of the loaded Minecraft world. This object will allow you to query any loaded block in the world. Within MCEdit, filters are run on defined user-selected boxes in the world (in other words, a subspace of the entire level). The box parameter holds this object, which allows you to query any block within this space. The options parameter is a dictionary of user input variables, identical to the inputs variable described above.

And that's it!
Believe it or not, that is all that an MCEdit filter needs to run in MCEdit. After creation, remember to put the file in your MCEdit "stock-filters" folder, and then try it out in game. To refresh your filters in MCEdit, click on any other command on the bottom command bar, then click back on filters. To use a filter, simply reload the filters section by clicking away from it, then clicking back on "filters". Next, select your filter from the list. After filling in selected parameters, and selecting a sizable part of the world, you can run your filter on that part of the world!

Don't forget to look at the MCEdit API page for more ideas on how to manipulate the world.

Utility Functions Module

In our modified framework version of MCEdit, we added a utilityFunctions module to make it easier to query information from the Minecraft world. On this page, we will describe functions from this module in detail.

Manipulation and Query Block Functions

The methods are primarily concerned with the manipulation and query of Minecraft blocks, i.e. changing empty space into solid blocks or finding out what type of block is at a specified coordinate

Set Block

def setBlock(level, (block, data), x, y, z):

Sets the block at the given x y z coordinate to the input block type and subtype ID. For example: setBlock(level, (4, 0), 0, 0, 0) will set the block located at the coordinate (0,0,0) to cobblestone.

Set Block If Empty

def setBlockIfEmpty(level, (block, data), x, y, z):

Sets the block given at the given x y z coordinate to the input block type and subtype ID's if the block at x y z is empty

Set Block To Ground

def setBlockToGround(level, (block, data), x, y, z, ymin):

At the given x y z coordinate, this function proceeds to iterate down the y dimension and set each block to the input block type ID and subtype ID if the block is empty until it reaches the given ymin value. For example: setBlockToGround(level, (4, 0), 0, 75, 0, 50) will set blocks located at (0, 75, 0) to (0, 50, 0) to cobblestone until it reaches y = 50 or a non-empty block.

Drill Down

def drillDown(level, x, z, miny, maxy):

Given a box and an x z coordinate, this function proceeds to drill down a y-column from maxy to miny and return a list containing every block in the column. For example: drillDown(level, 10, 5, 15, 25) will return a list of blocks from (10, 25, 0) until (10, 15, 0)

Mapping Functions

These functions are for squashing the 3D matrix representation of Minecraft into a 2D, top-down array. They include heightmap functions, tree and foliage map functions, and more

Tree Map

def treeMap(level, box):

Returns a 2d matrix mapping the locations of any trees. Essentially squashes the 3d representation of a Minecraft box into a 2d map without a y dimension. Anywhere a wood block is detected, the respective x z coordinate in the matrix will reflect that.

3D Math Functions

These functions concern mathematical helper functions, like calculating 3D box dimensions and raycasting between 2 points

Get Box Size

def getBoxSize(box):

Calculates the size of the box in each dimension, returning a tuple with this data.

Ray Trace

def raytrace((x1, y1, z1), (x2, y2, z2)):

Calculates the ray-trace line between two given coordinates (x1, y1, z1) and (x2, y2, z2) using the Bresenham 3D algorithm. Returns a list of points which intersected with the straight line between these two points.
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License