Scripting

incomplete

If you join a multiplayer world (not host), your global scripts are not accessible.
If you share a world, only the global scripts used in that world are included in the share.

### Common Parameter Definitions

All commands and parameters are case insensitive, with only a small number of exceptions. The exceptions are documented with the command documentation.

### Open Script option

If you highlight a command in your script that specifies another script, e.g. the Script command or the SetEventScript command, pressing the Start button will open the target script in a new editor window.

### Text Substitution

[text]
Any text parameter supports text substitution. Text substitution is when certain key words surrounded by [square brackets] are substituted with a value.

[gamertag] - the players gamertag is substituted.
[clan] - the players clan name is substituted.
[history:key] - the value of the player history identified by key is substituted.
[syshistory:key] - the value of the system history identified by key is substituted.
[clanhistory:key] - the value of the players clan history identified by key is substituted.

e.g. If the players gamertag is 'Baldy' and the players clan is 'Dragons' and the player has a value of 5 for their 'rank' history, then the following text:

[Hello [gamertag] of Clan [clan]. Your Rank is [history:rank]. Good luck!]
will be substituted as:
[Hello Baldy of Clan Dragons. Your Rank is 5. Good luck!]

### Coordinates

[x,y,z]
This parameter defines that a three dimensional coordinate is expected. This parameter has three components, separated by commas. Each component must be either a positive or negative whole number. Usually it is the coordinate (location) of a block in the world, but it can also be used to define relative coordinates, which are coordinates relative to another coordinate.

x: The x coordinate is for the west/east axis.
y: The y coordinate is for the up/down axis.
z: The z coordinate is for the north/south axis.

Relative coordinates are supported.
[rel:x, y, z]

Example:
[rel:-10, 5, 20] - The final coordinate will be this coordinate + the coordinate of the script block that the script was executed from, otherwise if the script was run manually from the menu then it will be an absolute coordinate (+ [0,0,0].

If the script block is located at [30, 10, 40], then the final coordinate of [rel:-10, 5, 20] will be [20, 15, 60]

Player relative coordinates are supported.

[prel:x, y, z] - Relative to the players position.
[vrel:f, y, r] - Relative to the players viewpoint. f = forward, r = right.
[hvrel:f, y, r] - Relative to the players horizontal viewpoint (Up/down view direction is ignored). f = forward, r = right.

Example:
[vrel: 10, 2, 3] - 10 Blocks forward of the player + 2 blocks up + 3 blocks to the right.
[vrel: -5, -2, -3] - 5 Blocks behind the player + 2 blocks down + 3 blocks to the left.

Cursor relative coordinates are supported.
[crel:x, y, z] - Relative to the block the player is looking at (with highlight frame).

Target and Killer relative coordinates are supported.
[trel:x, y, z] - Relative to the targets position.
[tvrel:f, y, r] - Relative to the targets viewpoint.
[krel:x, y, z] - Relative to the killers position.
[kvrel:f, y, r] - Relative to the killers viewpoint.

* Note: Killer relative coords are only valid when the script is executed via the PlayerDeath event.

### 2D Coordinates (Surface coordinates)

[x,z]
This parameter defines that a two dimensional coordinate is expected. This parameter has two components, separated by commas. Each component must be either a positive or negative whole number. Usually it is the coordinate (location) of a block on the world surface. With these coordinates, the y component not required and usually the surface height at x,z is used instead.

x: The x coordinate is for the west/east axis.
z: The z coordinate is for the north/south axis.

Relative coordinates are supported.

### Other Parameters:

[block]
This parameter defines that the name of a block is expected.

[item]
This parameter defines that the name of an item is expected. In most cases, block names are also valid.

[compare]
This parameter specifies that a comparison operator is expected. Valid comparison operators are:
[=] - Equal To
[!=] - Not Equal To
[<>] - Not Equal To
[>] - Greater Than
[>=] - Greater Than or Equal To
[<] - Less Than
[<=] - Less Than or Equal To
[mod] - Modulus

[qty|count]
This parameter specifies that a numerical quantity is expected.

[count|history]
This parameter specifies that a numerical quantity is expected. History values can also be used.
e.g.
[5] specifies the fixed number 5.
[history:key] - the value of the player history identified by key is used.
[syshistory:key] - the value of the system history identified by key is used.
[clanhistory:key] - the value of the players clan history identified by key is used.

### Fixed Value Parameter Definitions:

Fixed value parameters are not substituted with a user defined value, their value is always the same, and they specify a certain action or target for the script command.

[player]
This parameter specifies that the command is targeted at the player who activated the script.

[clan]
This parameter specifies that the command is targeted at all clan members of the player who activated the script.

[admin]
This parameter specifies that the command is targeted at all admins.

[delete]
This parameter specifies that the data the command is targeting is to be deleted.

[true|false]
[on|off|toggle]

[n|s|e|w]
This parameter specifies a direction. n = north, s = south, e = east, w = west.

### Multi-line support:

Clicking Left Stick toggles multi-line selection on and off. Multiple selected lines are highlighted in yellow. The clipboard supports multiple lines so if you have multiple lines selected and you press Copy, all the lines are copied to the clipboard, and when you press Paste, all the lines from the clipboard will be pasted.

Also if you delete a line while multiple lines are selected, all selected lines will be deleted.

## List of Commands

### Blueprint

Customize an items crafting blueprint.

`Blueprint [item:qty] [craft|furnace:time] [slot:item:qty:dur]..[slot:item:qty:dur] [skill=x] [level=x]`

`[item:qty]` - The product item and qty of the craft. Qty is optional. If omitted, a qty of 1 is used.

`[slot:item:qty:dur]` - The craft grid slot, item id, qty and durability of a material used in the craft. Slot must be a number from 1 to 9. 1=bottom left, 2=bottom center, 3=bottom right, 4=middle left,6=middle right,7=top left, 9=top right. Slot can only be 1-3 for furnace items. Slot is optional. If Slot is omitted it will default to the previous slot + 1, starting with 1. Qty is optional, if omitted a qty of 1 is used. Durability is optional, if omitted, 0 is used.

`[craft|furnace:time]` - Whether the item is crafted in the workbench or furnace. Time = smelt time in furnace. This parameter is optional and can be omitted. Time is also optional and can be omitted. If time is omitted, the items current smelt time is used. If the item currently does not have a smelt time, then a smelt time of 4.5 seconds is used.

`[skill=x]` - This skill type used for crafting. This parameter is option and can be omitted.
`[level=x]` - The required skill level to craft the item. This parameter is option and can be omitted.

Blueprint customizations via this command are not saved. Blueprints will be reset to default on a world reload.
Note: Only items currently craftable can be customized. i.e. You cannot add a blueprint for an item which does not already have a blueprint.

**Examples:**

`Blueprint [Revolver]`

Disables the crafting of a Revolver.

`Blueprint [Revolver] [SteelIngot] [Stick]`

Allows workbench crafting of a Revolver by placing a steel ingot bottom left, and a stick bottom center. Crafting skill level 1 is required.

`Blueprint [Revolver] [SteelIngot] [Stick] [skill=smithing] [level=15]`

Allows workbench crafting of a Revolver by placing a steel ingot bottom left, and a stick bottom center. A Smithing level of 15 is required to craft the item.

`Blueprint [Blue:2] [4:Wood:3] [BlueBox:5] [9:Feather]`

Allows workbench crafting of 2 Blue blocks by placing 3 Wood blocks middle left, 5 BlueBox blocks middle center, and a Feather top right.

`Blueprint [ColorGreen] [furnace] [Basalt] [Leaves]`

Allows furnace smelting of 1 Green block from Basalt and Leaves. Smelt time defaults to 4.5 seconds.

`var [time] = [2.5]
Blueprint [ColorGreen] [furnace:time] [Basalt] [Leaves]`

Allows furnace smelting of 1 Green block from Basalt and Leaves. Smelt time is 2.5 seconds.

### CaveIn

Starts a cave in (earthquake). Only one Cave In can exist in a world at the same time. If a CaveIn command is executed and there is already another cave in in progress, the command is ignored.

`CaveIn [x,y,z] [seed]`

`[x,y,z]` - The coordinate in the world of the center of the cave in.

`[seed]` - The seed for the random number generator. This value can be any number. This parameter may be ommitted, and a value of zero (0) will be used.

**Examples:**

`CaveIn [200,100,300]`

Starts a cave in at location 200,100,300, using zero (0) as the random seed.

`CaveIn [300,120,200] [2001]`

Starts a Cave In at location 300,120,200, using 2001 as the random seed.

### CCTV

Views the game world from a block position.

`CCTV [admin] [x,y,z]`

`[admin]` - Indicates this command should only be executed if the player has the admin permission. False if omitted.

`[x,y,z]` - The coordinate in the world of the block to view from.

`[millisecs]` - The length of time the player will view from the CCTV. The player may exit manually before this time has passed by pressing the A button. If this parameter is omitted or has a value of zero, the player will view indefinitely, until they exit manually. This parameter cannot be omitted if you want to specify [swivelspeed].

`[swivelspeed]` - How fast the camera swivels when using the right stick. This value is a percentage (valid values between 0 and 100). 1% = slowest, 100% = fastest, 0% = swivel disabled. If this parameter is omitted, 0 is used (swivel is disabled). swivelspeed is ignore if the [track] option is used instead of a direction. This parameter cannot be omitted if you want to specify [fov].

`[fov]` - Field of View (zoom). This value is a percentage (valid values between 1 and 100). 1% = fully zoomed in, 100% = fully zoomed out. A value of 50% is used if this parameter is omitted.

**Examples:**

`CCTV [10,20,30]`

Player views the world from location 10,20,30, initially facing north. The player will stay in CCTV mode indefinitely, until they press the A button. Swivel is disabled. FOV is 50%.

`CCTV [admin] [10,20,30]`

Same as above except the command only works for admin players.

`CCTV [admin] [10,20,30] [track]`

Same as above except the CCTV will stay focused on the player (as they move around) who activated the script.

`CCTV [10,20,30] [e]`

Player views the world from location 10,20,30, initially facing east. The player will stay in CCTV mode indefinitely, until they press the A button. Swivel is disabled. FOV is 50%.

`CCTV [10,20,30] [e] [5000]`

Same as above except the player will automatically exit from the CCTV view after 5 seconds, if they have not already manually exited. Swivel is disabled. FOV is 50%.

`CCTV [10,20,30] [e] [5000] [10]`

Same as above except the Swivel speed will be 10% (quite slow).

`CCTV [10,20,30] [20,20,30] [5000] [10]`

Same as above except the CCTV will look at the block position [20,20,30] instead of facing east.

`CCTV [10,20,30] [e] [5000] [10] [15]`

Same as above except the fov will be 15% (quite zoomed in).

`CCTV [admin] [10,20,30] [n] [0] [100] [90]`

Admin Player views the world from location 10,20,30, initially facing west. The player will stay in CCTV mode indefinitely, until they press the A button. Swivel is full speed. FOV is 90%.

While CCTV is active for a player, their HUD is turned off (like ghosting players). If swivel is not disabled, the player can zoom out/in using the left/right shoulder buttons.

### Clan

Assigns the player to a clan or removes them from a clan.

`Clan [name|remove]`

`[name]` - The name of the clan to assign the player to.
`[remove]` - Remove the player from whichever clan they are assigned to.

**Examples:**

`Clan [Team1]`

Assigns the player to the clan called Team1.

`Clan [remove]`

Removes the player from whichever clan they have previously been assigned to.

### Commit

Forces a graphics refresh.

`Commit`

There are no parameters for this command.

The Commit command is needed if you intend to create some kind of animation. If a script contains several commands that change blocks in the world, the graphics are only refreshed once the script has finished, this is because graphics refreshes are slow and if the game refreshed the graphics after every block is changed, the script could take a very long time to complete. It is also sometimes undesirable to have the graphics refresh after every block change, as you may wish for a wall of blocks etc to appear or disappear in a single moment.

**Examples:**

One example where animation is required is for a script that raises or lowers a castle gate. For each level the gate raises/lowers, you want the graphics to refresh to create the animation of the gate raising/lowering. In this case you would insert a Commit command (and often a short Wait command) between each set of commands that raise/lower one level of the gate.

### Context

Set the context for some command parameters.

Currently only the `[player]` context type can be set. This command allows scripts to change the target of all [player] based commands. i.e. the value of [player] can be changed for commands that use the [player] parameter.

`Context [player]` - Same as `Context [player] [default]`.

`Context [player] [default]` - Set the `[player]` context to default - which is the player who activated the script.

`Context [player] [target]` - Set the `[player]` context to the result of an `Intersect` command.

`Context [player] [killer]` - Set the `[player]` context to the player who killed the `[default]` player. Only usable on PlayerDeath event scripts.

Context is automatically set back to default at the end of an If/Endif block, so there is no need to manually set it back.

**Examples:**

`If`

````
Intersect [ray] [vrel:0,0,0] [vrel:8,0,0]

`````Then`````
Health [+10] // This increases the health of the default context - the player who activated the script.
Context [player] [target] // Set context to the player or mob returned by the intersect command.
Health [-20] // This damages the player or mob returned by the intersect command.

`````Endif // Context is automatically set back to [default] here.`

`If`

````
Intersect [sphere] [prel:0,1,0] [15] [players]

`````Then`````
History [kills] [player] // Increment the [kills] history for the default context - the player who activated the script.
Context [player] [target] // Set context to the player returned by the intersect command.
History [killed] [player] // Increment the [killed] history for the player returned by the intersect command.

`````Endif // Context is automatically set back to [default] here.`