ScriptCraft lets you write Minecraft Mods using Javascript - a programming language that's relatively easy to learn and use. ScriptCraft is a Minecraft Server plugin which means it must be used with a Minecraft server. Once you've downloaded and installed the Minecraft Server, then installed the ScriptCraft Plugin you can write your own Minecraft mods using Javascript.
I created ScriptCraft to make it easier for younger programmers to create their own Minecraft Mods. Mods are written using the JavaScript programming language. Once the ScriptCraft mod is installed, you can add your own new Mods by adding JavaScript (.js) files in a directory.
- If you're new to programming and want to start modding Minecraft, then Start Here.
- If you've already used Scratch, have attended a few CoderDojo sessions, or have already dabbled with JavaScript, then Start Here.
- Watch some demos of what you can do with ScriptCraft.
This is a simple mod in a file called greet.js in the scriptcraft/plugins directory:
function greet( player ) {
echo( player, 'Hello ' + player.name );
}
exports.greet = greet;At the in-game prompt, type:
/js greet(self)Anything you can do using the Spigot or CanaryMod APIs in Java, you can do using ScriptCraft in JavaScript.
ScriptCraft is a plugin for Minecraft Servers which lets operators, administrators and plug-in authors customize the game using JavaScript. ScriptCraft makes it easier to create your own mods. Mods can be written in Javscript and can use the full SpigotMC API or CanaryMod API. ScriptCraft works with all of the following Minecraft Server software:
I recommend using SpigotMC because both CanaryMod and CraftBukkit are
no longer being actively developed. The ScriptCraft mod also lets you
enter javascript commands at the in-game prompt. To bring up the
in-game prompt press the / key then type js followed by any
javascript statement. For example: /js 1 + 1 will print 2.
ScriptCraft also includes many objects and functions to make building
and modding easier using JavaScript. The JavaScript Drone object
bundled with ScriptCraft provides an easy way to build at-scale in
Minecraft. See the attached temple.js file for an example
of how you can use the sample Drone plugin to create new buildings in
Minecraft.
ScriptCraft is a Minecraft Server Mod which only works with Minecraft
for Personal computers (Windows, Mac and Linux). It does not work with
X-BOX, Playstation or WiiU versions of the game. You will need to have
Java version 7 or later installed. Check the version by typing java -version at a command prompt.
Before installing ScriptCraft you must first install
- Java and JavaScript engine
- SpigotMC which is a special version of Minecraft Server that makes it easy to customize the game.
Unfortunately, the most used Java distribution (Oracle JDK or OpenJDK) does NOT include any more the JavaScript engine (called Nashorn), starting from release 15 (and deprecated since release 11). The most suited replacement is GraalVM, still from Oracle. You can dowload the package from the GraalVM web site and install it according to your Operating System. Note that this may require some manual setup (e.g. under Windows, adding the binaries path to the PATH environmental variable). Note that if you already have a working Java installation (e.g. OpenJDK) the two may clash, so you may end up with Java from OpenJDK and JavaScript from GraalVM. This is untested.
Follow these steps to download and install SpigotMC.
- Download Spigot's BuildTools.jar
- Save the BuildTools.jar file to a new directory called spigotmc.
- Open a terminal (Mac and Linux) or command prompt (windows) window and type
java -jar BuildTools.jar. This will kick off a long series of commands to "build" SpigotMC. - When the build is done, there will be a new file beginning with
spigotand ending in.jarin the spigotmc directory. Run this file by typingjava -jar spigot-1.10.2.jar(it might not be that exact name - you can list files in the directory by typingdir(Windows) orls(Mac and Linux). - The server will start up then shut down very shortly afterwards. You'll need to edit a file called
eula.txt- changeeula=falsetoeula=trueand save the file. - Run the
java -jar spigot-1.10.2.jarcommand again - this time the server will start up. Shut it down by typingstopat the server prompt.
Follow these steps to download and install ScriptCraft.
- Download the scriptcraft.jar plugin and save it to the
pluginsdirectory and restart the server by typingjava -jar spigot-1.10.2.jar. REMARK: the compiled scriptcraft.jar may fail with the newer Java/JavaScript version, in particular with GraalVM, due to subtle incompatibitities, see e.g. the migration guide from Nashorn to GraalJS. In this case (errors when loading the plugin during the server start-up) you may need to use a newer scriptcraft.jar (you can try the 'scriptcraft.jar' file you can find in the 'target' directory in this repository), or compile it yourself, see next paragraph. - At the server prompt type
js 1 + 1and hit enter. The result2should be displayed.
Congratulations - you've just installed your Custom Minecraft Server and are ready to begin writing your first mod!
Download the latest sources from the current repository (the one hosting this readme). You can dowload them as Zip file or, if you know how to use git, you can clone the repository.
These sources contain some patches that have been tested with GraalVM with Java release 21.2.0 under Windows10 and SpigotMC server. They are not guaranteed to work in other environments but may help fixing compatibility issues also in those cases.
The sources are built using Ant. You must first install Ant. Be sure to follow the installation instructions as it needs some manual configuration.
Now you should be able to build ScriptCraft out of the box issuing the 'ant' command from a shell in the base directory where you cloned / unzipped your sources. Ant will create a folder called 'target' in which you will find the file scriptcraft.jar at the end of the build process.
Once installed, a new scriptcraft/plugins directory is automatically
created. All files in the scriptcraft/plugins directory will be
automatically loaded when the server starts. Only players who are
ops can use this plugin. You can grant a player op privileges by
typing 'op ' (replacing with your own Minecraft
user name) at the server console prompt or by adding the player's
username to the ops.txt file in your server directory.
Launch the server, then launch the Minecraft client and create a new
server connection. The IP address will be localhost . Once you've
connected to your server and have entered the game, look at a
ground-level block and type:
/js up().box( blocks.wool.black, 4, 9, 1 )
… This will create a black monolith structure 4 blocks wide by 9 blocks high by 1 block long. Take a look at the src/main/javascript/drone/drone.js file to see what ScriptCraft's drone can do.
If you're interested in customizing minecraft beyond just creating new buildings, take a look at the homes mod for an example of how to create a more fully-featured JavaScript plugin for Minecraft.
Listed below is a simple mod that will make blocks 'Howl' when they're broken.
// copy and paste this code to a new file named 'scriptcraft/plugins/howling-blocks.js'
var sounds = require('sounds');
function howl(event){
sounds.entityWolfHowl( event.block );
}
events.blockBreak( howl );If you're using CanaryMod instead of SpigotMC you can download the equivalent code.
A JavaScript mod for minecraft is just a JavaScript source file (.js) located in the scriptcraft/plugins directory. All .js files in this directory will be automatically loaded when the server starts.
To get started writing your own mod, take a look at some of the examples.
Because the SpigotMC API is open, all of the SpigotMC API is accessible via javascript once the ScriptCraft plugin is loaded. There are a couple of useful Java objects exposed via javascript in the ScriptCraft plugin:
-
__plugin– the ScriptCraft Plugin itself. This is a useful starting point for accessing other SpigotMC objects. The__pluginobject is of type org.bukkit.plugin.Plugin and all of its properties and methods are accessible. For example:js __plugin.namereturns the plugin's name (JavaScript is more concise than the equivalent Java code:__plugin.getName()). -
server– The top-level org.bukkit.Server object. See the SpigotMC API docs for reference. -
self– The player/command-block or server console operator who invoked the/jscommand. Again, this is a good jumping off point for diving into the SpigotMC API.
If you would like to contribute source code and/or documentation changes please read contributing.md
ScriptCraft works with Bukkit Plugin and uses the Bukkit Configuration API. On first loading, ScriptCraft will create a config.yml file in the plugins/scriptcraft/ directory. This file looks like this:
extract-js:
plugins: true
modules: true
lib: true
This file allows scriptcraft admins to turn on or off re-unzipping of the modules,
plugins and lib folders when deploying a new version of
ScriptCraft. It's strongly recommended that the lib directory always
be set to true to get the latest core ScriptCraft code . The modules
and plugins directories are optional and not part of ScriptCraft core.
- To get started using ScriptCraft to Learn JavaScript, read The Young Person's Guide to Programming in Minecraft.
- The ScriptCraft API documentation.
- To delve deeper into creating your own minecraft mod for use by others, read Creating a complete Minecraft Mod in JavaScript.
- Take a look at some examples.
- Buy the Official ScriptCraft Book A Beginner's Guide to Writing Minecraft Plugins in Javascript.
You can find more information about ScriptCraft on my blog.
CoderDojo Athenry have some excellent tutorials for younger programmers who have used Scratch and are interested in Modding Minecraft using JavaScript. In particular, they have an excellent Scratch - to - JavaScript tutorial which explains Scratch programs and how to do the same thing in JavaScript.
I highly recommend the series of tutorials provided by CoderDojo Athenry.
Developer Chris Cacciatore has created some interesting tools using ScriptCraft:
To launch a container with SpigotMC and ScriptCraft you can just do
docker run -p 25565:25565 -it tclavier/scriptcraft
You can find all files used to build this container in github project: docker-scriptcraft