Scripting API

Running Javascript files in worldpainter

(WORK IN PROGRESS, INFORMATION MIGHT BE WRONG OR INCOMPLETE)
Worldpainter allows to execute JS files during runtime from Toolbar > Tools > Run Script. The JS script is loaded in when the user selects it, and searched for parameter definitions at the file start. The parsed parameters are then offered as input fields to the user. The user selects the values he likes and runs the script. The selected values are provided to the scripts runtime environment as a dictionary calles "params". if you defined a parameter like this:

//script.param.maxSurface.type=integer
//script.param.maxSurface.description=maximum surface area of ponds
//script.param.maxSurface.optional=false
//script.param.maxSurface.default=500
//script.param.maxSurface.displayName=Max Surface value

you can access parameters during runtime like this:

var maxSurface = params["maxSurface"]; //type number
print("max surface input:" + maxSurface);

other available parameter types are:

• string
• integer
• percentage
• float
• file
• boolean

You can provide a script name and description with

//script.name=My script name (by IR0NSIGHT) v1.0.1
//script.description=This is my hello world script\nand it supports multi line descriptions!

your script is executed using js.eval (i think, at least) and the interpreter (Nashorn) supports ecma 5.1 syntax.
This java class: ScriptRunner reads, parses, compiles and executes the script. Please note, that the executing js environment is Nashorn (which is a JS interpreter for Java by Oracle) and not node.js.
This means common functions like console.log are not provided, as these are NodeJS specifics, not ECMA5.1.
Nashorn provides some alternatives: print("hello world") instead of console.log("hello world") for example.

Pre Provided functionality:

Worldpainter supplies some functionality already in form of the Scripting Context
it provides pre-implemented operations such as loading worlds, creating filters, applying terrain and exporting worlds (and more) Scriping Context Examples

Worldpainter (WP) provides some objects to the executing environment:

• argv
• params (string array)
• world
• dimension
• DataSize
• scriptDir
  you can access them directly in your script:

print(params)

Java object in JS

Nashorn allows to interact with the worldpainter java application. Java objects can be instantiated and used in the JS file and Java methods can be called:

var annotationsLayer = org.pepsoft.worldpainter.layers.Annotations.INSTANCE;
print("layer type:"+ typeof(annotationsLayer)); //prints Java class name
dimension.setLayerValueAt(annotationsLayer, 10, 20, 10); //set purple(=annotation 10) at x=10,y=20

dimension is the Instance of the Worldpainter Java class org.pepsoft.worldpainter.Dimension
Its provided by default to the JS environment by the Worldpainter Script Runner. We call its method "public void setLayerValueAt(Layer layer, int x, int y, int value)" Note how we get a Java Instance of the Layer by finding an instance in the java application somewhere and using that: org.pepsoft.worldpainter.layers.Annotations.INSTANCE Instead, we could also create our own instance. We can access all java things like that. read this Baeldung Nashorn Docu for a more in depth look at the Nashorn environment.

Runtime persistence

The executing environment is persistent across the Worldpainter runtime lifetime. This means, that we can save variables to the global scope of our JS environment in one script, and access them in another script:

//script A
var myVar = "hello world";

//script B, executed after script A:
print(myVar) // prints "hello world";

if we want to prevent this behaviour, we can scope our script into a function:

function main(){
   var myVar = "hello world";
};
main();