= Scripting =

!WorldPainter has a scripting engine which you can use to:
 1. Perform operations on the command line on computers without a graphical user interface, such as servers.
 1. Perform advanced operations that aren't currently possible with the GUI.
 1. 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 [wiki:Scripting/API API] page.

= Examples =

Here are a few example scripts to show what you can do, and how you would do it:

[wiki:Scripting/Example1 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.