CraftScripts¶
Scripts allow you to program small tasks without having to learn Java, figure out how to compile WorldEdit, or bother with reinventing the wheel. CraftScripts are written in JavaScript.
Requirements¶
Before you start using CraftScripts, you’ll have to install the Rhino JavaScript engine. A direct link to the download is here. Rename the downloaded file to js.jar
. Move js.jar
to the plugins/
or plugins/WorldEdit
folder (on Bukkit) or the mods
folder (other platforms).
Using CraftScripts¶
Once you have the JS engine installed, drop your CraftScript .js
files in the craftscripts
folder (in the WorldEdit config folder - either plugins/WorldEdit
or config/WorldEdit
depending on platform).
To run a CraftScript
/cs <filename> <args>
/.s <args>
The /cs
command will run the CraftScript with the given filename (.js
can be left out). Each CraftScript may have its own arguments. The /.s
command will re-run your last used CraftScript.
Writing CraftScripts¶
Scripting in WorldEdit allows you to write world manipulation code without having to learn Java or compile your code. Scripts, called CraftScripts in WorldEdit, and are written in JavaScript and go into your craftscripts/ directory. The advantages of writing scripts with WorldEdit are:
Hook right into WorldEdit’s undo/redo system
Use WorldEdit’s block place prioritization
Accept WorldEdit’s powerful block type syntax (
//set sign[facing=north]
)Get the region selected by the user
Note
It is recommended you have a basic understanding of JavaScript or Java to begin writing CraftScripts.
Tip
While we’ll be going over using CraftScripts with the WorldEdit API, there are no real restrictions on what you can do. Advanced users may even hook into the API of the underlying platform (Bukkit, Forge, etc).
Introduction¶
Scripts have the following three variables in their global namespace:
context
is an instance of CraftScriptContext.player
is the player who invoked the script, an instance of Player.argv
is a Java array strings, which are the arguments used upon invoking the scripts
Working with blocks¶
All block editing in WorldEdit is done through an EditSession. This object handles history and block placement order all automatically. To get an edit session for your own script, use:
var sess = context.remember();
Every time you call that method, you will get a new EditSession
, so be sure to keep one around. To set blocks, you will either need to provide a BlockState
which is a combination of a block type and one or more states, or a BaseBlock
, which is a BlockState
that may additionally have NBT data.
Note that because BlockTypes
is in the com.sk89q.worldedit.world.block
namespace, it had to be imported first. The first argument for setBlock()
is a BlockVector3
indicating the position in the world.
To get blocks, use getBlock()
on EditSession
. You’ll get back a BaseBlock
too.
Processing arguments¶
Arguments are passed in under the argv
variable. If you need to check whether the right number of arguments was provided by the user, you can use CraftScriptContext#checkArgs()
.
The CraftScriptContext
can to some basic argument parsing with CraftScriptContext#getBlock()
. You can also hook directly into WorldEdit’s parsers via WorldEdit.getInstance().getPatternFactory()
and .getMaskFactory()
.
What happens if the user inputs an invalid block? An exception will be raised and if you don’t catch it, the user will be informed about their error and your script will be halted.
Working with Java packages¶
To import a java package, you can use the following syntax:
importPackage(Packages.package.name.here);
You can import any package available in the Java classpath - not restricted to WorldEdit.
Example Scripts¶
You can find some example scripts in the GitHub repository for WorldEdit. Note that they may not all be updated for current WorldEdit API. You can find more about the WorldEdit API in the API section.