Scripting
WorldPainter has a scripting engine which you can use to:
- Perform operations on the command line on computers without a graphical user interface, such as servers.
- Perform advanced operations that aren't currently possible with the GUI.
- Automate sequences of commonly executed operations
The currently available operations in the scripting engine are:
- Creating new worlds from height maps
- Exporting worlds to Minecraft maps
- Applying height maps or masks as layers or terrain types
- Setting layers or the terrain according to filters
- Etc...
The scripts are written in JavaScript, although it is possible to install support for other scripting languages.
Running Scripts
There are two ways to run scripts: inside WorldPainter using Tools -> Run script... or from the command line using the wpscript command.
Inside WorldPainter
To run scripts from inside WorldPainter, open the Run Script screen by selecting Run script... from the Tools menu. You can select a previously executed script from the drop down list, or you can load a new script by pressing the ... button. You can pass parameters to the script by entering them in the "Parameters" text area (one parameter per line). These will be available to the script in the arguments (from index 0) and argv (from index 1) arrays. Press Run to run the script. If it writes to the console the output will be displayed in the "Output" text area.
Scripts executed from inside WorldPainter have access to the currently loaded world and currently selected dimension, so that they can manipulate them.
The Command Line
WorldPainter scripts can be run from your operating system's command line, using the wpscript command. The "command line" is a way to interact with the operating system of your computer by typing textual commands with your keyboard and receiving the results as text on the screen, using a terminal window. On Windows the quickest way to open a terminal window is to press the Windows key, type cmd and press Enter.
Regardless of the operating system you run scripts with the wpscript command, which should automatically be available on the command line after installing WorldPainter:
wpscript <scriptfile> [<scriptarg> ...]
Where <scriptfile> is the filename of the script, including extension, which can optionally be followed by one or more script arguments. The arguments will be available to the script in the arguments array (starting from index 0) or the argv array (starting from index 1).
Script files
Script files are text files with a name of your choice, but the extension should reflect the scripting language. These pages assume JavaScript, which most Java runtimes should support, for which the extension of your script files should be: .js.
You can create them with any text editor, such as Notepad on Windows, or a dedicated IDE or programmers' editor which might provide JavaScript syntax highlighting and code completion.
API
The WorldPainter functionality is made available to the script in the form of a context object named wp. For details about the available operations on the WorldPainter scripting context, see the API page.
Examples
Here are a few example scripts to show what you can do, and how you would do it:
Creating a world from a height map and applying layers
A complete example of creating a new world from a height map, and using other height maps to add forests and rivers.
