buscript

Buscript adds the capability for a server to run Javascript from text files. Beyond what is normally offered by Javascript, buscript adds some global functions to enable scripts to be written easily and hopefully by anyone!

The latest development builds can always be found at http://ci.onarandombox.com/job/Buscript/

Commands

Currently there's just one command

/run <script> [player]

Permission: buscript.run

<script> is the name of the file that contains the script you wish to run. Buscript will look in plugins/Buscript/scripts for this file name. Since it indicates a file name, it needs to have the file extension as well. If your script file is myscript.txt, then you need to type /run myscript.txt.

[player] is optional. This field is used to indicate a target for your script. In general, this should probably be someone that is online if you are going to use it.

The run command will always reload the file so there is no need to do anything special should you modify the script.

Should the command not locate a script, it will attempt to create the file for you (though it will be blank and do nothing.)

Scripts

Scripts are text files that contain Javascript code. This may sound scary to people unfamiliar with coding but luckily buscript provides several easy to use methods for creating basic scripts.

Your script files must be located in the scripts directory that the Buscript plugin creates for you automatically. The file extension used can be anything (even nothing) as long as the file contains valid Javascript.

Script Features

• Easy to use global functions including command running, message broadcasting, permission management and more.
• Any string used in these global functions has access to "%target%" which represents the current target of the script. Example: broadcast("Hello, %target%")
• The ability to run another script at a later time with 100% reliability, even if the server crashes!
• Buscript defines the global variable target so more advanced things can be done with the script's target.
• The global variable server is also available which gives direct access to the Bukkit server variable just as if you were working from within a plugin!
  
  

Detailed Script Features

Global Functions and Variables

Example Scripts

/run broadcast-sample.txt dumptruckman

broadcast-sample.txt:

  broadcast("Hey everyone, §c%target% §fis a cool guy!")
  command("op %target%")

This is a simple script that tells everyone on the server what a cool guy the target (dumptruckman in this case) is and then ops them.

It even colors the name, imagine that.

/run perm-sample.txt dumptruckman

perm-sample.txt:

  message("%target%", "You have just been given flight in the creative world for 30 minutes!")
  addPerm("creative", "%target%", "flight.permission")
  runLater("remove-perm.txt", "30m", "%target%")

remove-perm.txt:

  message("%target%", "Your flight power has been removed, hope you weren't up there!")
  removePerm("creative", "%target%", "flight.permission")

Please note these two scripts require Vault and a Vault compatible permission manager which allows them to work even when the player is not online.

It is possible to instead use the command() function to run your own permission commands without using Vault.

Also note "flight.permission" is not a real permission. Your actual flight enabling permission may vary (or not even exist!)

For Developers

Source code: https://github.com/dumptruckman/Buscript
Javadoc: http://ci.onarandombox.com/view/Other%20Great%20Plugins/job/Buscript/javadoc/
Maven repository: http://repo.onarandombox.com/content/groups/public/
Maven pom information:

  <groupId>com.dumptruckman.minecraft</groupId>
  <artifactId>buscript</artifactId>
  <version>1.0-SNAPSHOT</version>

You can easily use this as a library instead of a plugin by adding it as a library to your plugin. I would recommend shading it in with maven, possibly relocating the code to a new namespace.
After that, simple create a

new Buscript(yourPlugin)

and from there you will find all the methods you need to run your own scripts and even add your own global methods!

If you wish to extend the functionality of Buscript as a plugin, the main plugin class BuscriptPlugin has a convenient getAPI() method to return the Buscript object it has on hand.

The javadocs are available for download via the maven repository.