Scripts
The scripts themselves are loaded from script files in the scripts subdirectory of the plugin's data directory (the directory will be created automatically the first time the plugin is loaded). The character encoding used for loading the scripts is always UTF-8. This allows you to include special characters easily and robustly. No escaping needed, just use the characters you want directly and save the script with UTF-8 encoding.
The extension of the filename indiciates the script language of the script. The only currently supported script language is JavaScript (or technically ECMAScript) and the corresponding extenions is .js. The name of the file without the extension becomes the name of the script, by which it will be referred to by the commands described below. The name of the script is case sensitive.
Commands
The following commands exist for working with scripts:
/listscripts
Lists all loaded scripts.
/reloadscripts
Reloads all loaded scripts from disk. Note: this only reloads already loaded scripts! To load newly added scripts, for now you have to use the /reload command.
Context variables
To interact with the Minecraft world, the script has access to the following variables. Note that the availability of these variables depends on the context from which the script is being invoked:
| Expression | Description | Type | ||||
world | The current world (if defined). | World | ||||
world.get(worldname) | A specifically named world. worldname can be a string literal, or a variable. | World | ||||
player | The current player (if defined). | Player | ||||
player.get(playername) | A specifically named player. playername can be a string literal, or a variable. | Player | ||||
player.all | All players. | Player | ||||
block.get(blockname) | A named block with a specific name in the current world (if defined). blockname can be a string literal, or a variable. | Block | ||||
time | The time in the current world (if defined). | Time | ||||
item.get(itemdescription) | An item such as can be stored in an inventory, held by a player, etc.. itemdescription can be an item ID or an item name. The names are those as defined in the Materials class of the Bukkit API. | Item | ||||
args | An array containing the arguments to the script, if applicable. | String[] | ||||
command.get(commandname) | A particular CraftBukkit or plugin command which can be executed. | Command |
Actions:
| Expression | Description | Type | ||||
command.execute(command) | Execute a command as though it had been typed on the console. Any messages sent by the command will be collected in a String array and returned. | String[] | ||||
command.execute(command, args) | Execute a command with arguments as though it had been typed on the console. Any messages sent by the command will be collected in a String array and returned. | String[] |
To be expanded...
World
Properties:
| Expression | Description | Type | ||||
name | The name of the world. | String | ||||
block(blockname) | The named block with the specified blockname in this world. | Block | ||||
block(x, y, z) | The block at the specified coordinates in this world. | Block | ||||
box(block1, block2) | A box shaped volume of blocks, with the corners being defined by block1 and block2, which must be Blocks. | Volume | ||||
column(block1, block2) | A box shaped volume of blocks, with the corners being defined by block1 and block2, but vertically extended to the top and bottom of the map. | Volume | ||||
time | The current time in the world. | Time |
Volume
Properties:
| Expression | Description | Type | ||||
blocksOfType(typeId) | All blocks in the volume of the specified typeId, which must be an integer literal or integer typed variable. | Block | ||||
blocksOfType(typeName) | All blocks in the volume of the specified typeName, which must be a String literal or String typed variable. The names are those as defined in the Materials class of the Bukkit API. | Block |
Block
Actions (note that most of these only apply to certain block types. If you try to invoke them on an inappropriate block type, nothing will happen):
| Expression | Description | |||
interact() | Interact with the block (as if the player had right-clicked on it). | |||
push() | A synonym for interact(). | |||
switchOff() | Switch the lever off, if it is currently on. | |||
switchOn() | Switch the lever on, if it is currently off. | |||
close() | Close the door, trap door or fence gate, if it is currently open. | |||
open() | Open the door, trap door or fence gate, if it is currently closed. |
Properties:
| Expression | Description | Type | ||||
empty | Whether the block is empty (air). | Boolean | ||||
isOn | Whether the block is either providing or receiving redstone power. | Boolean | ||||
isOff | Whether the block is not either providing or receiving redstone power. | Boolean | ||||
inventory | The inventory of the block, if applicable (such as for chests) | Inventory |
Player
Actions:
| Expression | Description | |||
sendMessage(message) | Send the player a chat message. message can be a string literal or a variable. You can send coloured messages by including a colour code. | |||
kick(message) | Kick the player with the specified message. message can be a string literal or a variable. | |||
ban(message) | Kick and ban the player with the specified message. message can be a string literal or a variable. | |||
pardon() | Pardon the player. |
Properties:
| Expression | Description | Type | ||||
name | The name of the player. | String | ||||
isOnline | Whether the player is online. | Boolean | ||||
inventory | The inventory of the player (only if the player is online, for now). | Inventory | ||||
isOp | Whether the player is an operator. | Boolean | ||||
hasPermission(permission) | Whether the player has the specified permission. permission should be a string constant or string typed variable. Any permissions system which supports the Bukkit permissions API (also known as SuperPerms) is supported. | Boolean |
Time
Properties:
| Expression | Description | Type | ||||
now | The time of day in ticks (there are 20 ticks per second, the full day-night cycle lasts 20 minutes or 24,000 ticks and tick zero is the start of the day). | String | ||||
isDawn | Whether it is currently dawn. | Boolean | ||||
isDay | Whether it is currently day. | Boolean | ||||
isDusk | Whether it is currently dusk. | Boolean | ||||
isNight | Whether it is currently night. | Boolean |
Inventory
Actions:
These actions take items as parameters. There are three ways to specify the item: with an integer, being the item ID; with a string, being the item name; or by using the item.get(itemdescription) context variable described above, allowing you to specify data value, damage and amount. See below for details.
| Expression | Description | |||
set([item, item, item...]) | Replace the contents of the inventory with the specified array of items. See below for ways to specify items. | |||
clear(slot) | Clear the specified slot, where slot is an integer specifying the slot index. | |||
clear() | Clear the entire inventory. | |||
add(item) | Adds the specified item to the inventory, being as efficient as possible and using existing stacks as far as possible. | |||
remove(item) | Remove the specified items (taking the amount into account) from the inventory. See below for the way to specify the amount. | |||
removeAll(item) | Remove all items of the specified item. |
Properties:
| Expression | Description | Type | ||||
size | The number of slots in the inventory. | Integer | ||||
contains(item) | Whether the inventory contains any items of the specified type. See below for ways to specify items. | Boolean |
Item
The properties below can be chained. For instance, to specify a stack of 32 red wool, you could write item.get('WOOL').data(14).amount(32).
Properties:
| Expression | Description | Type | ||||
data(data) | Set the data value to the specified value | Item | ||||
amount(amount) | Set the amount to the specified value | Item | ||||
damage(damage) | Set the damage to the specified value | Item |
Command
Actions:
| Expression | Description | Type | ||||
execute() | Execute the command as though it had been typed on the console. Any messages sent by the command will be collected in a String array and returned. | String[] | ||||
execute(args) | Execute the command with arguments as though it had been typed on the console. Any messages sent by the command will be collected in a String array and returned. | String[] |
To be expanded...
Comments