Header image

Executive summary: make a text file with some commands in it and read this file in using Import Settings. You can perform almost every Mineways operation by using a command instead of the user interface. You can also temporarily change, add, or clear any blocks you like for an export. You can also associate scripts with Mineways so double-clicking them starts Mineways and runs the script.

Mineways Scripting Language

The "Import Settings" item in the File menu has two uses. One is that you can read in a model previously created with Mineways. Doing so will set up Mineways to be identical to how it was when the file was exported: the world, terrain file, color scheme, and all export settings will be set to what you used when you exported the model. This is handy for continuing to work on a model you exported in a previous session.

However, "Import Settings" can do much more. As of version 4.18 of Mineways, you can make a text file of Mineways scripting commands and read it in to:

None of these functions will affect your original Minecraft world. Mineways considers that data unmodifiable. The changes are performed temporarily on whatever you next export, and not displayed on the map.

Script files have the suffix ".mwscript". When using "Import Settings" note that you can use the file filter of the import dialog to display only these types of files.

Model File Import

Model files have first lines such as:

# Wavefront OBJ file made by Mineways
#VRML V2.0 utf8
# Minecraft world: beta test world
# Extracted from Minecraft world saves/BestWorld

Model export files have all their commands preceded by a "#", scripting language files do not. Script files are simple text files, and are usually stored with the suffix "*.mwscript". See the files that come with the Mineways distribution for examples. A file is considered to be a script if Mineways looks at it and doesn't think it's from a model.

One note on model import: for STL files the file you need to import is labeled *.txt. For example, if you export AwesomeCastle.stl, Mineways also creates an AwesomeCastle.txt file with statistics and settings about your export. OBJ and VRML files have these statistics contained at the top of their exported *.obj and *.wrl files.

Scripting Overview

Most commands consist of a single line, and usually have a colon in them. There are two classes of commands: those that are recognized when an exported model is read in, and those recognized when a script is read. Most, but not all, of the exported model commands are recognized as script commands.

You can take many of the export commands found in model files and use them in a script you're creating. Transferring text from the top of a exported model to a script file is an easy way to get properly-formed commands in place. Simply remove the "#" from in front of each command to use it in a script file. See this section for what the default settings are when exporting for rendering.

Model Export Commands

Here is the full list of model export commands. When found in a model file, each line is preceded by a "#"; in scripting files the "#" is not used. Text in italics is shown as an example. "[deprecated]" means this format is output by older versions of Mineways.

Model Export/Script command syntax Notes
# Wavefront OBJ file made by Mineways
#VRML V2.0 utf8
# Minecraft world: beta test world
# Extracted from Minecraft world saves/BestWorld [deprecated]
Model only. One of these must be the first line encountered in a model (or for STL, text statistics) file that is imported. The italicized text is the world's folder in the .minecraft/saves directory.
Minecraft world: Happy Blocks Land
Minecraft world: C:\Users\erich\AppData\Roaming\.minecraft\saves\Round World
Minecraft world: C:\Users\erich\schematics\teapot.schematic
Minecraft world: [Block Test World] Extracted from Minecraft world saves/BestWorld [deprecated]
The world to load, accessed by the folder name. The .minecraft/saves directory is assumed, but a full path can be given if desired. The full path is always needed for schematics. Use [Block Test World] to load this special test world.
View Overworld
View Nether
View The End
Change to the given map level (will appear all gray if the level does not exist). For model export "View Overworld" is not output, since it's the default.
Terrain file name: C:\Users\erich\Desktop\Mineways\terrainExt_Sphax.png
Terrain file name: terrainExt_DokuLight.png
Sets terrain file to be used. Full path is recommended; if just a file name is given, Mineways looks in the load or last-used directory.
Color scheme: no glass blocks Selects the named color scheme, if available. "Standard" is the default.
Selection location min to max: -199, 0, -466 to -176, 255, -442
Selection location: 60, 0, 60 to 80, 255, 100
Selection location: none
Select the volume to be exported, inclusive. Either form is fine. The volume is defined by a minimum and maximum block location. The commas, spaces, and "to" string do matter here. If "none" is found, deselection occurs (Escape key in Mineways).
Set render type: Wavefront OBJ absolute indices
Set render type: Wavefront OBJ relative indices
Set render type: Binary STL iMaterialise
Set render type: Binary STL VisCAM
Set render type: ASCII STL
Set render type: VRML 2.0
Set 3D print type: Wavefront OBJ absolute indices
Created for Viewing - Wavefront OBJ absolute indices [deprecated]
Created for 3D printing - Wavefront OBJ absolute indices [deprecated]
Set target for commands to export for rendering or 3D printing, and specify the file format to be used. Whatever file type is set, render or 3D print, along with the file format, is the set of export options that will be affected by the export commands that follow. If none is set, export commands will affect "Set render type: Wavefront OBJ absolute indices". If you set export settings and then switch to another file export type or file format, don't expect the options to also be set there.
Not all file types are shown for the 3D print type and deprecated versions, to avoid repetition; these are all the same as shown for rendering.
Units for the model vertex data itself: millimeters Meaningful only for 3D printing export. Valid units: millimeters, centimeters, meters, inches.
Rotate model 0.000000 degrees Number of degrees model is rotated on output. Valid values are 0, 90, 180, 270.
Scale model by making each block 2 mm high
Scale model by fitting to a height of 5 cm
Scale model by using the minimum wall thickness for the Sculpteo multicolor material
Scale model by aiming for a cost of 25.00 for the colored sandstone material
Meaningful only for 3D printing export. There are many variants here; the simplest way to find the text you want is to export manually and examine the top of the file exported. See the export options for more information.
Fill air bubbles: YES; Seal off entrances: no; Fill in isolated tunnels in base of model: no
Connect parts sharing an edge: YES; Connect corner tips: YES; Weld all shared edges: no
Delete floating objects: trees and parts smaller than 16 blocks: YES
Hollow out bottom of model, making the walls 2 mm thick: no; Superhollow: no
Typically used for 3D printing export. See the export options for more information.
Export separate objects: YES
Individual blocks: no
Material per object: YES
G3D full material: YES
Make Z the up direction instead of Y: no
Create composite overlay faces: no
Center model: YES
Export lesser blocks: YES
Fatten lesser blocks: no
Make tree leaves solid: no
Create block faces at the borders: YES
Use biomes: YES
Melt snow blocks: no
Debug: show separate parts as colors: no
Debug: show weld blocks in bright colors: no
Booleans. Boolean values are set as YES/yes/TRUE/true/1; anything else found for a boolean is considered false. See the export options for more information. "Use biomes: YES" also turns on biome display, so that the effect is seen.


Here is an example of a script using the commands above.

Minecraft world: My Cool World
Color scheme: no glass
Terrain file name: C:\Users\erich\Desktop\Mineways\terrainExt_DokuLight.png
Set render type: Wavefront OBJ absolute indices
Use biomes: no
Selection location min to max: -368, 83, 16 to -351, 255, 30

This loads a world, changes its color scheme to "no glass", selects a terrain file, selects rendering to an OBJ file, turn biomes on, and finally selects a volume to export.

Scripting Interface Commands

The commands above are available for scripting, unless listed as "Model only." All script commands are used without a "#" in front of each line. Comments "//" and "/* */" are respected.

If you wish to set any export options, it's wise to first set the export mode and file type by using the "Set render type:" or "Set 3D print type:" command. If you don't, the export settings will be applied to whatever file type was last exported, if any, and a warning will pop up.

Because it's a powerful system that can itself create files, the script file is read twice. Syntax errors are checked for and flagged on the first read; no actions are done. If there are no syntax errors, then the script is read again and executed line by line. Script execution is aborted if some execution error is found and caught. Pro tip: if you want to test a script for syntax errors and not execute it, put "FAIL" (or anything else that's not a command) as a line in the script. It will flag this line, and any other lines causing errors, and will not execute the script until all are fixed.

Even with error checking, it's definitely possible to set combinations that may crash Mineways, as there are complex interactions between systems and especially between blocks and some combinations are simply illegal. If things get wedged, just restart Mineways, which always resets its defaults to a known good state.

Script command syntax Notes
Export for rendering: c:\temp\mysave.obj
Export for 3D printing: myprint.stl
Export schematic: c:\temp\my schematics\myobject.schematic
Export the selected area using the given file type to the specified file.
Jump to Spawn
Jump to Player
Jump to Model
Jump the view to the specific location.
Reset export options: Render
Reset export options: 3D Print
Reset export options: Schematic
Reset all the options for all file formats for the given export mode. Lets you start with a clean slate.
Focus view: -210, 73
Set the view to be centered on this position on the map, X (East-West, East is positive) and Z (North-South, South is positive).
Zoom: 5
Zoom in on the view, higher is more zoomed in. The legal range is 1 to 40, inclusive, and represents the width of each block in pixels.
Show all objects: true
Show biomes: YES
Elevation shading: false
Lighting: no
Cave mode: TRUE
Hide obscured: yes
Set map view mode on or off, using TRUE/true/YES/yes/1 for on. Note that, as usual, showing the biomes doesn't set the checkbox to export them (well, export the biome in the center of the volume exported). The command "Use biomes: YES" does that.
Select minimum height: 55
Select minimum height: -12
Select minimum height: +5
Select minimum height: V
Select minimum height: v
Select minimum height: V43
Select minimum height: v63
Set the minimum height slider for the box volume to be exported. The +/- versions give a relative change, e.g., "-12" means subtract 12 from the current level, whatever it is. V/v is used to set the height level by looking at the selected area, plus a one-block border around it, and selecting the lowest height of the entire set of visible blocks. "V" means "ignore semitransparent blocks", those that can be seen through, such as water and glass. "v" means to pay attention to such blocks. Finally, V/v followed by a number means to use the level found, or the level specified, whichever is larger. For example "V47" means find the minimum level of the selected area (plus one block border). If that level is greater than 47, use it; if less than 47, set the level to 47.

While involved to explain, settings such as "V43" can be useful for exporting the above-ground visible area - 43 is as deep as the oceans normally ever go. Deeper than this and the selected area probably has a deep hole that throws off the level. If you're exporting separate pieces of terrain for viewing, "V" is pretty safe for showing everything above ground (you might miss an area with a large overhang, though, since the overhang will limit the minimum level found). If you know that you don't care about anything lower than, say, 57, then use "V57" to make sure the minimum level set is never lower than 57.

Select maximum height: 119 Set the maximum height slider for the box volume to be exported and that is visible.
Give more export memory: YES On the 32-bit version (and on the Mac) you can run out of memory on export. This option frees up all the allocated map data and reloads it only as needed during export, giving Mineways more memory to use for its other processes. At the end of export the visible world is reloaded for display. This option can cause export to go more slowly.
Close This command has a dramatic effect: it closes the program! This can be useful if you want to run a script and exit when it's done. Combined with a startup script, you can make Mineways run a script and exit by just a double-click. Note that if the script runs with any errors, error processing is done before the script closes, so that you'll be warned. If you don't want to ever halt on errors, use a log file; see the commands that follow.


Here is an example of a script using the commands above.

Set render type: Wavefront OBJ absolute indices
View Nether
Selection location min to max: -38, 83, 16 to -31, 127, 30
Zoom: 9
Export for Rendering: C:\Users\erich\Desktop\nether.obj

For the world that is currently loaded, this sets the render type and file format, switches to the Nether level of the world loaded, selects an area, zooms the map, and performs a rendering export to the file nether.obj

>Script-only Commands

These are the value-added commands, things you simply can't do otherwise in Mineways. Want to turn your stone castle into diamond? Or have all the leaves disappear from your trees? Or add a giant pyramid to your spawn point? The Change blocks command is the genie that can made your dreams come true, if only for a short while.

The idea behind Change blocks is that you can specify extremely temporary changes to your world. These will not show up on the map, and they affect only the next export you perform. After the export the changes are cleared out; you have to load these changes again if you want to apply them again. No actual changes are made to your Minecraft world files.

You can specify a series of commands, which are applied in the order given. Each command works on the results of whatever previous commands did. For example, if you turn all crops into potatoes, then turn potatoes into grass, this has the effect of turning all crops into grass.

One warning: just like a genie fulfilling your wishes, Change blocks commands can set up combinations that can inadvertantly cause terrible things to happen, possibly causing assertions during export or even crashes. This is an expert-level feature, and it's up to you to do the right thing.

Script command syntax Notes
Change blocks: [from block range] [to type[:id]] [at x,y,z [to x,y,z]] Define a range of block types to be affected, what those block types should turn into, and what location or volume of space the command should affect. Not all from/to/at bits are needed, but at least one is. See the examples below for how the various combinations work. These changes do not happen to your world nor show up on the map, they are applied the next time you export and then cleared out.
Clear change block commands Clear out all stored 'Change blocks' commands. While exporting will clear out any Change block commands, you can also clear them out this way without exporting.
Custom printer cost per ccm: 0.03
Custom printer cost per printer ccm: 0.00
Custom printer handling cost: 0.00
Custom printer minimum cost: 0.00
Custom printer currency: $
Custom printer maximum size: 20.0 20.0 19.0
Custom printer minimum wall thickness: 1.5
The custom printer material that is used by the STL exporter can have its attributes set for showing the cost on export. You can set the cost per cubic centimeter (ccm) of material used (assuming a solid model), the cost per ccm of printer volume used (i.e., including the empty space, a bounding box around the model; Shapeways uses this for its Strong & Flexible material, for example), the "handling" cost (added in), the minimum cost a model will cost, the currency symbol (only the first character is used), the volume size of the 3D printer in centimeters (to warn if the print is too large), and the minimum wall thickness in millimeters for printing. Any or all of these can be set; the defaults are shown when not modified. PLA is typically priced at $24 for a 1 kilogram (800 cubic centimeters) spool, and using this conversion. That is, $24/800 ccm then costs $0.03 per cubic centimeter.
Save log file: filename Instead of displaying script errors, warnings, and completion messages to the screen in a pop-up dialog, append this information to the specified log file. Typically call this at the beginning of a script. The log file is closed when the script is processed. This is handy if you have errors and want to look at them later. That said, I added it mostly for testing errors, as the popup dialog is limited to showing the first 20 errors, while the log file has no limit.

Change blocks command examples

The Change blocks command specifies a set of blocks to turn into a particular block ID and data value in a particular volume of space. It has seven variants, depending on whether you specify the from, to, and at values. Here are examples of each variant.

Change blocks: from 8-9

Block IDs 8 and 9 are the two types of water. These are cleared to "air" in the whole selection volume - the land's dried up.

Change blocks: from "wool":5 to "wool":13

Change all lime green wool blocks to a deep green wool.

Change blocks: to "TNT" at 2112,71,548

The specific location, no matter what's in it (even air), is turned into TNT. For the next example below, no "from" means "everything except air". If you can't remember what the default is, just specify it, e.g. this command is the same as Change blocks: from 0-255 to "TNT" at 2112,71,548

Change blocks: to 24:1

Everything solid (not air) in the whole volume is turned into chiseled sandstone. The long form is Change blocks: from 1-255 to 24:1

Change blocks: from "stained glass","glass pane","stained glass pane" to "glass"

Any of the given forms of glass are turned into glass blocks in the entire exported volume (defined by "Selection location:"). Note that the "from" range can be a list of blocks by ID number or name. A range can also be given, e.g. 64,71,193-197 specifics all full doors. You can also give specific data values, e.g. "wood planks":1-5 means all variants of wood planks other than oak, which uses data value 1.

Change blocks: at -5,50,45 to 50,255,90

The at/to volume specified is cleared out, turned to air. The long form is Change blocks: from 1-255 to 0 at -5,50,45 to 50,255,90

Change blocks: from "wheat" to "cactus" at -5,0,-45 to 50,255,90

This example finds any wheat blocks in the given volume and changes them to cactus blocks. The names are those shown in the "Block" column on this page. Or, find these names and IDs in this table.

Change blocks: from 59 to 81 at -5,0,-45 // wheat to cactus

This is the same as say from "wheat" to "cactus", instead using the decimal "Dec" number shown in this table. If you're not sure of the name, use the ID to be safe - you can always add a comment, as shown. Note how the "at" location specifies only a single block in this example, just to show a different example; if that block is wheat, it will be turned into a cactus.

Change blocks: from "wheat":0-6 to "wheat":7 at -5,0,-45 to 50,255,90

Here the data values for wheat are specified. The data value is a number from 0 to 15 and specifies variants of blocks. Wheat's values are 0-7, specifying the growth stage, 7 being fully mature. This example says to make all the wheat fully mature, by taking data values 0-6 and changing them all to 7.

Change blocks: from "wheat":0-6,141-142,207 to "wheat":7 at -5,0,-45 to 50,255,90

Any growing wheat, carrots (ID 141) through potatoes (ID 142), and beetroot seeds (ID 207) are turned into fully grown wheat in the specified area. This is about as elaborate as you can go. All the commands below are shorthand variants, using defaults for missing fields.

Usually if you don't specify a "from" range, it means everything solid (not air). The one exception is if you set "to" and a volume, in which case air is also turned into the specified block type. The "to" value is "air" by default. If the location volume is not given, the whole export selection area is used.

Change blocks: from 198-255 at -319,50,-1077 to -302,50,-1059

All blocks greater or equal in ID to 198 ("end rod") in the given at/to volume are turned into "air", i.e., cleared out. If no "to" ID is given, air is used.


There is no comment syntax for model export files - usually it's better to not mess with these commands at all in the model file. For scripts you can use "//" and anything after is ignored. You can also use "/*" and "*/" to comment out blocks of text.


// My little test script
Set render type: Wavefront OBJ, absolute // the exact text for the file type is needed here
// Set 3D Print Type: STL // you can have multiple comments
/* comment out the following commands for now:
Create block faces at the borders: no // or NO, FALSE, false, 0
Use biomes: YES // or yes, TRUE, true, 1
Make Z the up direction instead of Y: no /* set to "yes" for STL files */
Export for Rendering: c:\temp\mysave.obj // forward slashes in the path specification are also OK

Command Line Options

You can use command-line options with Mineways so that it is customized on startup. For example, you could provide a different initial window size, then run a script that loads your favorite world and takes you to where you were last building.

You can store this command line in a .bat file and double-click that file, or change your options on the shortcut for Mineways itself. See the file mineways.bat in Mineways for an example.


mineways.exe [-w X Y] [-s UserSaveDirectory] [-l mineways_exec.log] [file1.mwscript [file2.mwscript [...]]]

The command-line options are:

Specify the file name and path for a script or model file to load on startup.

-w X Y
Specify the X and Y resolution in pixels of the startup window. Values must be positive integers.

-s UserSaveDirectory
Specify the directory where your Minecraft worlds are located, shown in the "File | Open World" list. This directory is "%appdata%\.minecraft\saves" by default, if not specified. The directory is not a single world's save folder, but rather a directory holding all world folders you want to choose from. If your directory path has spaces in it, you need to use double-quotes around the path, e.g. -s "C:\temp\My Minecraft Saves"

-l mineways_exec.log
For debugging startup problems, you'll normally never use this. Saves startup and commands executed to the file specified.

Here are a few examples:

mineways.exe -w 800 900

Start up Mineways in an 800 x 900 sized window. Note that a larger window does mean a slower world load time.

mineways.exe MyCastle.obj

Import the settings for the previously-exported model MyCastle.obj, its rendering mode, selection volume, etc. Essentially runs Import Settings.

mineways.exe scripting/startup.mwscript

Run the script "startup.mwscript" at startup. This file must be in the same directory as Mineways (probably won't work on Mac); give the path if it's somewhere else.

mineways.exe "C:\Mineways\My House.obj" C:\Mineways\modify.mwscript

If you exported a model just how you like it, you can import it and modify its settings etc. with whatever commands are in your modify.mwscript. When using multiple scripts, it's wise to give the full path to each file, as Mineways can modify the default directory used to load. Note that double quotes are needed when the file or path contains a space character.

mineways.exe -w 1 1 "C:\Mineways\Load Eiffel.mwscript" C:\Mineways\export.mwscript C:\Mineways\close.mwscript

Start with a tiny window and run the specified scripts at startup. The "Load Eiffel" script might load a world and select the Eiffel model in that world. The export script exports it, and the close script closes Mineways. This allows you to essentially run Mineways from the command line with no interactions needed, though the program still needs to pop up a small window. The tiny window actually speeds up processing, since only the map chunks in the exported model are loaded.

mineways.exe -s C:\MyWorlds

Load the world folders contained in C:\MyWorlds so that they appear in the "File | Open World" menu list.

Associating .mwscript files with Mineways

On Windows, run the batch file register-Mineways-run-as-administrator.bat as administrator. Go to the folder where the Mineways code is and right-click on register-Mineways-run-as-administrator.bat and then select "Run as administrator" from the list:


You should see any *.mwscript files with Mineways icons next to them:

script files

Now when you double-click on a file ending with .mwscript, it will run this script on startup.

On the Mac, follow these instructions.

Default Rendering Options

What follows are the default rendering options when Export for Rendering is performed. This list was created by exporting a sample rendering from a world, editing the OBJ file, grabbing the header and removing the "#" character at the beginning of each line, and commenting out the lines that are purely comments. This is provided here as a guide to all the export options available.

// Wavefront OBJ file made by Mineways version 4.18, http://mineways.com
Minecraft world: Voxelia_2016-01-13
Terrain file name: terrainExt.png
Color scheme: Standard
// Sun Jun 05 08:32:21 2016

Selection location min to max: -97, 71, -26 to -76, 255, -5
// Non-empty selection location min to max: -97, 71, -26 to -76, 97, -5

Set render type: Wavefront OBJ absolute indices
Units for the model vertex data itself: meters

// 6249 vertices, 4998 faces (9996 triangles), 2732 blocks, 245 billboards/bits
// block dimensions: X=22 by Y=28 (height) by Z=22 blocks
File type: Export full color texture patterns
Export separate objects: YES
Individual blocks: no
Material per object: YES
G3D full material: no
Make Z the up direction instead of Y: no
Center model: YES
Export lesser blocks: YES
Fatten lesser blocks: no
Make tree leaves solid: no
Create block faces at the borders: YES
Use biomes: no
Rotate model 0.000000 degrees
Scale model by making each block 100 mm high
// Data operation options:
Fill air bubbles: no; Seal off entrances: no; Fill in isolated tunnels in base of model: no
Connect parts sharing an edge: no; Connect corner tips: no; Weld all shared edges: no
Delete floating objects: trees and parts smaller than 16 blocks: no
Hollow out bottom of model, making the walls 10 mm thick: no; Superhollow: no
Melt snow blocks: no
Debug: show separate parts as colors: no
Debug: show weld blocks in bright colors: no

Perl Script Example

Here's a simple Perl script to generate a Mineways script. It shows the power of scripting to make models.

$Cobras = 8;

# Block for each cobra.
@block = ("200","\"tnt\"","\"wood planks\"","\"block of diamond\"","\"wool\":2","20","124","58");

$minlevel = 65;
$maxlevel = 164;
$scale = 30;
$radius = 1;

# Use Block Test World as my canvas - building above about 65 is good
printf "Minecraft world: [Block Test World]\n";
printf "Set render type: Wavefront OBJ absolute indices\n";
printf "selection location: -100,$minlevel,-100 to 100,$maxlevel,100\n";
for ($level = $minlevel; $level <= $maxlevel; $level++) {
    $time = 2 * 3.1415926 * ($level-$minlevel)/($maxlevel-$minlevel);
    for ($cobra=0; $cobra < $Cobras; $cobra++) {
        $objOffset = 3.1415926 * ($cobra/$Cobras);

        # Rotate the object around a center point, depending on the object number itself.
        $x = $scale * cos($objOffset) * cos($time+$objOffset);
        $z = $scale * sin($objOffset) * cos($time+$objOffset);

        # equivalent: printf "Change blocks: from 0-255 to %s at %d,$level,%d to %d,$level,%d\n",
        printf "Change blocks: to %s at %d,$level,%d to %d,$level,%d\n",

Running the script to set up the scene, then exporting (manually) to Sketchfab, you get this:

Scripting test by Eric Haines on Sketchfab