Minecraft <=> Sauerbraten converter


I've (finally) updated the scripts to handle Minecraft's anvil save format and Sauerbraten's new formats (the scripts still produce v29 ogz files, but they can read up to v33, and Sauerbraten's map loader is backwards compatible).

I've also realised that using Sauerbraten to edit Minecraft maps isn't as great an idea as I originally hoped. Sauerbraten is optimised for a different kind of geometry and can get sluggish. Moreover existing tools (such as WorldEdit, which I used to make my adventure map) are quite good.



Minecraft is a game played on vast randomly generated cubical earth-like worlds.

Sauerbraten is a compact open-source first-person-shooter styled after games such as Quake. Its maps are also based on cubical geometry. Moreover it sports a convenient and powerful in-game level editor.

The goal of this package is to convert some part of a Minecraft map to a Sauerbraten map, and vice-versa. The main purpose is to allow Sauerbraten's powerful editor to be used to edit Minecraft maps, though other applications are surely possible.

The package is written in Perl, which made it relatively quick to write and hopefully fairly platform independent (I only have a windows machine, so if you run this on Unix/Linux or Mac OS, please let me know how it goes). Of course it might have run a bit faster if it were written in C++. Anyone who wants to port it is welcome to ;).

There is another project with a very similar goal here, but it apparently doesn't run on windows.

A generic Minecraft map The Sauerbraten in-game editor The same Minecraft map converted to Sauerbraten

Download and setup instructions

  1. Install Minecraft if you don't already have it (it costs 26.95 USD (I think)).
  2. Install Sauerbraten if you don't already have it (it's FREE :D).
  3. Install Perl if you don't already have it (also FREE :D).
  4. Download this zip file.
  5. Unzip the zip file into your "Sauerbraten home folder". This should create folders sauerbraten/packages/minecraft and sauerbraten/packages/models/minecraft. Note: your Sauerbraten home folder may simply be the folder where you installed Sauerbraten (the one containing sauerbraten.bat), or it may be elsewhere. The latter case can be confusing since Sauerbraten will still read maps from the installation directory, but it will save maps elsewhere while appearing to save to the same filename. If you find that you can convert from Minecraft, and load, edit and save the Sauerbraten map, but see no changes when converting back to Minecraft, this may be the problem.
  6. Edit the settings file.
    1. Open the file sauerbraten/packages/minecraft/settings.pl in a text editor.
    2. Change the line $mc_folder='...'; to indicate the directory containing your Minecraft save games. If you want to edit multiplayer maps, this should be the directory containing minecraft_server.jar or minecraft_server.exe. If you want to edit single player maps, these instructions will give the directory you need.
    3. (OPTIONAL) Change $sauer_folder='...'; if you want the Sauerbraten maps to be stored somewhere else.
    4. (OPTIONAL) Change $mc_ogz_scale=3; if desired. This indicates that the sidelength of one Minecraft block will be 23=8 Sauerbraten units. This seems about right visually. Note that decreasing this may lose some detail on some blocks, such as a 7/8 full block of water. Also increasing it will reduce the maximum possible size of converted region.
      Unfortunately Minecraft and Sauerbraten avatars have different aspect ratios (1:2 and 3:4 respectively). With $mc_ogz_scale=3; it will be impossible to fit through a 1 block wide tunnel. Increasing to $mc_ogz_scale=4; will allow the player to fit through a tunnel 1 block high and 1 block wide.
    5. (OPTIONAL) Uncomment the lines under replaceblocks to remove ores and tall grass. This can cut down the size of the .ogz file. Other replacements can be made using the same format, expressing the block IDs in hex.
  7. On Unix/Linux or Mac OS, you will likely need to set the permissions of all .pl files to make them executable, and ensure that the first line of each indicates the location of Perl on your machine.

Instructions for running

The package includes two Perl scripts - mcr_to_ogz.pl and ogz_to_mcr.pl. The former reads a specified area on a Minecraft map and creates a Sauerbraten map representing it. The latter replaces a specified area of a Minecraft map with the contents of a Sauerbraten map. After following the instructions in the previous section, open a command prompt or terminal and navigate to the directory sauerbraten/packages/minecraft. The following subsections describe the use of each script, as well as a very brief introduction to editing in Sauerbraten.

Minecraft to Sauerbraten

The command
mcr_to_ogz.pl mcname sauername c0x c0z size
will create a Sauerbraten map sauername.ogz representing part of the Mincraft map mcname (add "/DIM-1" or "/DIM1" to mcname to convert the Nether or End). The part converted will consist of all blocks with coordinates
16 c0x ≤ x < 16 c0x + 2size      0 ≤ y < 128      16 c0z ≤ z < 16 c0z + 2size

The size parameter must be between 7 and 10 inclusive (actually if you changed $mc_ogz_scale, the maximum allowable value of size is 13 - $mc_ogz_scale). For example,

mcr_to_ogz.pl world mymap 0 0 7
will read a 128x128x128 cube from the Minecraft map named "world", with x and z ranging from 0 to 127, and put the result in mymap.ogz.

Warning: Sauerbraten can freeze up when trying to load very large (and detailed) maps. I recommend sticking to size 7 or 8.

So many blocks!

Editing in Sauerbraten

The Sauerbraten documentation has an excellent
introduction and reference for editing. The following is intended to be a brief introduction in the context of this package. Suppose mymap.ogz has been created as in the previous subsection.
  1. Run Sauerbraten by running sauerbraten.bat on Windows or sauerbraten_unix on Unix/Linux/Mac OS(?).
  2. Type /coop minecraft/mymap and press enter. The map we've created will be loaded.
  3. Press E to toggle edit mode.
  4. Click and drag to select a rectangular prism-shaped region. Hold G and scroll to adjust the size of the selection cursor. If you want to also select entites (such as torches and ladders) inside the selection, type /entselect [insel].
  5. Press C and V to copy and paste a region of cubes or a selection of entities.
  6. The selected region additionally has one of its faces selected (outlined in white). Select a different face by tapping R while pointing at it.
  7. Hold R and scroll to rotate the selection around the selected face.
  8. Hold Y and scroll to change the texture of the currently selected face.
  9. Scroll up to remove blocks, or down to extrude them.
  10. To convert a block to water, select it, type /water, and then remove the block.
  11. Same deal for lava and glass.
  12. Type /savemap to save changes made to the map (or /savemap minecraft/anothermap to give it a new name).
The selected region is indicated by blue lines. The nearest face of the region is bounded by white lines since it's the selected face. The size of the cursor can be seen in the centre of the image R+scroll to rotate Copy and paste using C and V
Y+scroll to change a texture Scroll down to extrude Fear my giant bedrock tower!

Sauerbraten to Minecraft

The command

ogz_to_mcr.pl sauername mcname c0x c0z
will overwrite part of the Mincraft map mcname with the contents of sauername.ogz. The part overwritten will have lower coordinates (16 c0x, 0, 16 c0z) and will be 128 blocks high. The length and width will depend on the size of sauername.ogz; namely, it will be 2$mapscale - $mc_ogz_scale where $mapscale is the scale of the map (type /echo $mapscale in Sauerbraten to see this) and $mc_ogz_scale is specified in sauerbraten/packages/minecraft/settings.pl (the default is 3). Continuing with the above example,
ogz_to_mcr.pl mymap world 0 0
will transfer any changes made in Sauerbraten back to the Minecraft map.

An unusual sand formation *fear*

Tile entities

Minecraft stores additional data, such as the contents of chests and furnaces, in tile entities. In addition to writing sauername.ogz, the script mcr_to_ogz.pl records tile entites in the file sauername_tileents.txt. This file can be edited to change the contents of chests, and the result will be transferred back to Minecraft when ogz_to_mcr.pl is run.

The format of sauername_tileents.txt is as follows (see sample_tileents.txt for an example). The first line of each tile entity has the form

index id
where index is referenced by the Sauerbraten map (see below) and id describes the type of tile entity (eg Chest, MobSpawner...). For a Sign tile entity, the remaining lines are the lines of text on the sign. For a MobSpawner, the next line indicates the mob spawned (eg Zombie, Enderman...). Any numerical attributes of the tile entity are indicated by a line of the form
where fmt indicates the format of the property (eg i16 for TAG_Short, i32 for TAG_Int, f32 for TAG_Float) and property is the name of the property (eg BurnTime for a furnace). If the tile entity has a list of items (eg for a Furnace, Chest or Cauldron), these items are indicated by lines of the form
slot: id damage count
where slot indicates which slot the item takes (eg 0 to 26 for a Chest), id and damage are the item ID and damage value of the item, and count is the number of items in the stack. Additionally any enchantments are indicated at the end of the line in the form (id,lvl) (see here for enchantment ids and permissable levels). Finally a blank line indicates the end of the tile entity.

The tile entity data is represented in the Sauerbraten map by a rotating purple slab mapmodel. The parameters of the mapmodel are

mapmodel 0 109 0 index 0
where index is the index of the tile entity in sauername_tileents.txt. The index is most easily changed by pressing period (.) while the entity is selected. Multiple blocks can refer to the same tile entity data; for example, copying a chest along with its tile entity mapmodel will produce a chest with identical contents.


The two conversion operations don't quite reverse each other in either order. Some information is lost in both directions. The intention was to facilitate large-scale editing of geometry. Smale-scale details are more easily entered in Minecraft in creative mode.

Minecraft to Sauerbraten

All data in the Minecraft map is represented by geometry and textures in Sauerbraten. Therefore blocks which look identical in Minecraft will become identical in the Sauerbraten map. For instance:

More recent versions of Sauerbraten seem to do some optimisations, replacing textures that can't be seen. Therefore a block which is completely surrounded (such as ore) will get replaced by the surrounding material.

The lighting information is all lost - the Sauerbraten map produced has no lighting. I might consider in a later version placing lights on each light source (torch etc) to emulate the Minecraft light (an idea due to IkeKrull). Unfortunately lava doesn't intrinsically provide light in Sauerbraten and I don't really want to put a light in every lava block. Minecraft entities (such as passive and aggressive mobs) are also lost.

For the most part, water and lava look nicer in Sauerbraten than in Minecraft. However Sauerbraten doesn't allow sloping water surfaces. A stream of water in Minecraft which decreases in height is represented as a series of blocks with decreasing height. It looks OK, sort of.

This project was also an excuse for me to learn how to make models for Sauerbraten in Blender. If it looks like they were produced by an amateur, it's because they were. Most of them turned out OK, but I admit the fire model looks like a wobbling layered jelly desert.

Underwater in Sauerbraten The Sauerbraten representation of a trickling stream Served on a plate of netherrack - Yum!

Sauerbraten to Minecraft

A Sauerbraten map can contain features that wouldn't be seen in a Minecraft map (such as sloping faces, small scale details and blocks with mismatching textures on different faces). This is exacerbated when Sauerbraten replaces hidden textures. The "closest" minecraft block is chosen, but this may not be sensible in many cases.

The conversion of mapmodels is a bit more forgiving; as long as a valid mapmodel is used, the nearest fit will be found for its position and rotation. This can still make it tricky to get the rotation right for mapmodels which are symmetric.

Finally the converter fills out BlockLight and SkyLight with dummy values. Minecraft seems to recompute these fairly quickly, but any remaining dark patches can be removed by causing a block update.

This was a plain extended piston, but when it contracts we can see that it has become sticky If Minecraft leaves a patch unlit, place and remove a block to make it update the lighting


While writing this package I made frequent reference to the following:


Creative Commons License
The Perl scripts and md3 files are licensed under a Creative Commons Attribution 3.0 Unported License


The textures belong to Mojang. I trust they will contact me if they have issue with the textures being included in the download. In any case, presumably anyone with a use for the package will already legally have a copy of the texture.

Free Web Hosting