The `command()` function is used to expose javascript functions for
use by non-operators (regular players). Only operators should be
allowed use raw javascript using the `/js ` command because it is too
powerful for use by regular players and can be easily abused. However,
the `/jsp ` command lets you (the operator / server administrator /
plugin author) safely expose javascript functions for use by players.
#### Parameters
* commandName : The name to give your command - the command will be invoked like this by players `/jsp commandName`
* commandFunction: The javascript function which will be invoked when the command is invoked by a player.
* options (Array - optional) : An array of command options/parameters
which the player can supply (It's useful to supply an array so that
Tab-Completion works for the `/jsp ` commands.
* intercepts (boolean - optional) : Indicates whether this command
can intercept Tab-Completion of the `/jsp ` command - advanced
usage - see alias/alias.js for example.
#### Example
See chat/colors.js or alias/alias.js or homes/homes.js for examples of how to use the `command()` function.
### ready() function
The `ready()` function provides a way for plugins to do additional
setup once all of the other plugins/modules have loaded. For example,
event listener registration can only be done after the
events/events.js module has loaded. A plugin author could load the
file explicilty like this...
load(__folder + "../events/events.js");
// event listener registration goes here
... or better still, just do event regristration using the `ready()`
handler knowing that by the time the `ready()` callback is invoked,
all of the scriptcraft modules have been loaded...
ready(function(){
// event listener registration goes here
// code that depends on other plugins/modules also goes here
});
The execution of the function object passed to the `ready()` function
is *deferred* until all of the plugins/modules have loaded. That way
you are guaranteed that when the function is invoked, all of the
plugins/modules have been loaded and evaluated and are ready to use.
Core Module - Special Variables
===============================
There are a couple of special javascript variables available in ScriptCraft...
* __folder - The current working directory - this variable is only to be used within the main body of a .js file.
* __plugin - The ScriptCraft JavaPlugin object.
* server - The Minecraft Server object.
* self - the current player. (Note - this value should not be used in multi-threaded scripts - it's not thread-safe)
## Miscellaneous Core Functions
### setTimeout() function
This function mimics the setTimeout() function used in browser-based javascript.
However, the function will only accept a function reference, not a string of javascript code.
Where setTimeout() in the browser returns a numeric value which can be subsequently passed to
clearTimeout(), This implementation returns a [BukkitTask][btdoc] object which can be subsequently passed to ScriptCraft's own clearTimeout() implementation.
If Node.js supports setTimeout() then it's probably good for ScriptCraft to support it too.
This function mimics the setInterval() function used in browser-based javascript.
However, the function will only accept a function reference, not a string of javascript code.
Where setInterval() in the browser returns a numeric value which can be subsequently passed to
clearInterval(), This implementation returns a [BukkitTask][btdoc] object which can be subsequently passed to ScriptCraft's own clearInterval() implementation.
If Node.js supports setInterval() then it's probably good for ScriptCraft to support it too.
The times() method makes building multiple copies of buildings easy. It's possible to create rows or grids of buildings without resorting to `for` or `while` loops.
Parameters
----------
* numTimes (optional - default 2) : The number of times you want to repeat the preceding statements.
Example
-------
Say you want to do the same thing over and over. You have a couple of options...
* You can use a for loop...
d = new Drone(); for (var i =0;i <4;i++){d.cottage().right(8);}
While this will fit on the in-game prompt, it's awkward. You need to
declare a new Drone object first, then write a for loop to create the
4 cottages. It's also error prone, even the `for` loop is too much
syntax for what should really be simple.
* You can use a while loop...
d = new Drone(); var i=4; while (i--){ d.cottage().right(8); }
... which is slightly shorter but still too much syntax. Each of the
above statements is fine for creating a 1-dimensional array of
structures. But what if you want to create a 2-dimensional or
3-dimensional array of structures? Enter the `times()` method.
The `times()` method lets you repeat commands in a chain any number of
times. So to create 4 cottages in a row you would use the following
statement...
cottage().right(8).times(4);
...which will build a cottage, then move right 8 blocks, then do it
again 4 times over so that at the end you will have 4 cottages in a
row. What's more the `times()` method can be called more than once in
a chain. So if you wanted to create a *grid* of 20 houses ( 4 x 5 ),
Creates the text out of blocks. Useful for large-scale in-game signs.
Parameters
----------
* message - The message to create - (use `\n` for newlines)
* foregroundBlock (default: black wool) - The block to use for the foreground
* backgroundBlock (default: none) - The block to use for the background
Example
-------
To create a 2-line high message using glowstone...
blocktype("Hello\nWorld",blocks.glowstone);
![blocktype example][imgbt1]
[imgbt1]: img/blocktype1.png
Blocks Module
=============
You hate having to lookup [Data Values][dv] when you use ScriptCraft's Drone() functions. So do I.
So I created this blocks object which is a helper object for use in construction.
Examples
--------
box( blocks.oak ); // creates a single oak wood block
box( blocks.sand, 3, 2, 1 ); // creates a block of sand 3 wide x 2 high x 1 long
box( blocks.wool.green, 2 ); // creates a block of green wool 2 blocks wide
Color aliased properties that were a direct descendant of the blocks object are no longer used to avoid confusion with carpet and stained clay blocks. In addition, there's a convenience array `blocks.rainbow` which is an array of the 7 colors of the rainbow (or closest approximations).
Drone.sphere() method
=====================
Creates a sphere.
Parameters
----------
* block - The block the sphere will be made of.
* radius - The radius of the sphere.
Example
-------
To create a sphere of Iron with a radius of 10 blocks...
sphere( blocks.iron, 10);
Spheres are time-consuming to make. You *can* make large spheres (250 radius) but expect the
server to be very busy for a couple of minutes while doing so.
Drone.sphere0() method
======================
Creates an empty sphere.
Parameters
----------
* block - The block the sphere will be made of.
* radius - The radius of the sphere.
Example
-------
To create a sphere of Iron with a radius of 10 blocks...
sphere0( blocks.iron, 10);
Spheres are time-consuming to make. You *can* make large spheres (250 radius) but expect the
server to be very busy for a couple of minutes while doing so.
Drone.hemisphere() method
=========================
Creates a hemisphere. Hemispheres can be either north or south.
Parameters
----------
* block - the block the hemisphere will be made of.
* radius - the radius of the hemisphere
* northSouth - whether the hemisphere is 'north' or 'south'
Example
-------
To create a wood 'north' hemisphere with a radius of 7 blocks...
hemisphere(blocks.oak, 7, 'north');
Drone.hemisphere0() method
=========================
Creates a hollow hemisphere. Hemispheres can be either north or south.
Parameters
----------
* block - the block the hemisphere will be made of.
* radius - the radius of the hemisphere
* northSouth - whether the hemisphere is 'north' or 'south'
Example
-------
To create a glass 'north' hemisphere with a radius of 20 blocks...
hemisphere0(blocks.glass, 20, 'north');
Drone.rainbow() method
======================
Creates a Rainbow.
Parameters
----------
* radius (optional - default:18) - The radius of the rainbow
Example
-------
var d = new Drone();
d.rainbow(30);
Drone.spiral_stairs() method
============================
Constructs a spiral staircase with slabs at each corner.
Parameters
----------
* stairBlock - The block to use for stairs, should be one of the following...
- 'oak'
- 'spruce'
- 'birch'
- 'jungle'
- 'cobblestone'
- 'brick'
- 'stone'
- 'nether'
- 'sandstone'
- 'quartz'
* flights - The number of flights of stairs to build.
Example
-------
To construct a spiral staircase 5 floors high made of oak...
spiral_stairs('oak', 5);
Classroom Module
================
The `classroom` object contains a couple of utility functions for use
in a classroom setting. The goal of these functions is to make it
easier for tutors to facilitate ScriptCraft for use by students in a
classroom environment. Although granting ScriptCraft access to
students on a shared server is potentially risky (Students can
potentially abuse it), it is slighlty less risky than granting
operator privileges to each student. (Enterprising students will
quickly realise how to grant themselves and others operator privileges
once they have access to ScriptCraft).
The goal of this module is not so much to enforce restrictions
(security or otherwise) but to make it easier for tutors to setup a shared server
so students can learn Javascript.
classroom.allowScripting() function
===================================
Allow or disallow anyone who connects to the server (or is already
connected) to use ScriptCraft. This function is preferable to granting 'ops' privileges
to every student in a Minecraft classroom environment.
Parameters
----------
* canScript : true or false
Example
-------
To allow all players (and any players who connect to the server) to
use the `js` and `jsp` commands...
/js classroom.allowScripting(true)
To disallow scripting (and prevent players who join the server from using the commands)...
/js classroom.allowScripting(false)
Only ops users can run the classroom.allowScripting() function - this is so that students
don't try to bar themselves and each other from scripting.
events Module
=============
The Events module provides a thin wrapper around Bukkit's
Event-handling API. Bukkit's Events API makes use of Java Annotations
which are not available in Javascript, so this module provides a
simple way to listen to minecraft events in javascript.
events.on() static method
=========================
This method is used to register event listeners.
Parameters
----------
* eventName - A string or java class. If a string is supplied it must
be part of the Bukkit event class name. See [Bukkit API][buk] for
details of the many bukkit event types. When a string is supplied
there is no need to provide the full class name - you should omit
the 'org.bukkit.event' prefix. e.g. if the string
"block.BlockBreakEvent" is supplied then it's converted to the
org.bukkit.event.block.BlockBreakEvent class .
If a java class is provided (say in the case where you've defined
your own custom event) then provide the full class name (without
enclosing quotes).
* callback - A function which will be called whenever the event
fires. The callback should take 2 parameters, listener (the Bukkit
registered listener for this callback) and event (the event fired).
* priority (optional - default: "HIGHEST") - The priority the
listener/callback takes over other listeners to the same
event. Possible values are "HIGH", "HIGHEST", "LOW", "LOWEST",
"NORMAL", "MONITOR". For an explanation of what the different
priorities mean refer to bukkit's [Event API Reference][buk2].
Returns
-------
An org.bukkit.plugin.RegisteredListener object which can be used to
unregister the listener. This same object is passed to the callback
function each time the event is fired.
Example:
------
The following code will print a message on screen every time a block is broken in the game
