[Craig]

This topic will document each script command. I will also put this documentation in game for quick access while you are editing scripts.
This documentation is up to date for version 2.44 as at 12 Aug 2016.

General Script Help:

Full Command List:

Blueprint: Customize an items crafting blueprint.
CaveIn: Starts a cave in (earthquake).
CCTV: Views the game world from a block position.
Clan: Adds or removes the player from a clan.
Commit: Forces a graphics refresh.
Context: Set the context for some command parameters.
CopyBlock: Copies a block from one location to another.
CopyRegion: Copies all the blocks from one region to another.
Equip: Forces the player to equip an item if they have it in their inventory.
Exit: Exit the script immediately.
Explosion: Creates an explosion.
Fog: Creates a fog weather effect.
Hail: Creates a hail weather effect.
Health: Manipulate a players current Health points.
History: Manipulates historical records.
HUDBar: Add/remove custom HUD status bars, driven by history values.
HUDCounter: Add/remove custom HUD counters, driven by history values.
HUDShape: Add/remove custom shapes to the HUD.
HUDText: Add/remove custom text element to the HUD.
Inventory: Manipulates block and entity inventories.
Input: Prompt the player to enter a number.
Item: Customize an items properties.
Kick: Kicks a player from the multiplayer session.
Loop: Restarts the script from the top.
Marker: Manipulates map markers.
Menu: Prompt gamer with a multiple choice menu.
MessageBox: Prompt gamer with a multiple choice message box.
MobHealth: Manipulate mob current Health points.
MobSpawn: Spawns a mob.
MobState: Set the state of all mobs in a region.
MoveBlock: Moves a block from one location to another.
MoveRegion: Moves all blocks from one region to another.
Notify: Creates a notification message.
OpenBlock: Opens the standard interface screen for container blocks.
Particle: Emit an individual particle.
ParticleEmitter: Creates a particle emitter that emits particles at a specified frequency over a specified length of time.
Paste: Pastes a component.
Permission: Manipulates player permissions.
Pickup: Manipulates item pickups.
ReplaceRegion: Replaces all occurrences of a block in a region with another block.
Rain: Creates a rain weather effect.
Script: Executes another script.
SetBlock: Sets the block id at a location.
SetBlockScript: Assigns a script to blocks that can execute scripts.
SetEventScript: Assigns a script to be executed on certain game events.
SetNameplate: Sets player or mob nameplate settings.
SetPower: Sets the power state at a location.
SetReach: Set's the distance that players can reach (target) blocks.
SetRegion: Sets all the block ids in a region.
SetSphere: Creates a sphere of blocks.
SetSwitch: Manipulates switches and buttons.
SetText: Sets the text of blocks that have text properties.
SetTexture: Sets the texture for a block that has multiple texture capability. Also used to set decals for blocks that support decals.
Skill: Sets a players skill level.
SkillAddXP: Add XP to a players skill level.
SkyColor: Customize sky color.
Sound: Plays a sound.
Teleport: Teleports entities.
TintColor: Applies a multiplicative tint color to the texture pack.
Unequip: Forces the player to unequip items.
Var: Declare variables and assign values.
Wait: Pauses the script execution for a time.
Waypoint: Manipulates player waypoints.
Zone: Manipulates zones.

Conditionals:

If: Starts a conditional If, Then, Elseif, Else, Endif block
CanEquip: Queries if the player can use an item.
HasAction: Queries if the player has performed an action.
HasHistory: Queries historical records.
HasInventory: Queries block or entity inventories.
HasMarker: Queries map markers.
HasPermission: Queries player permissions.
HasPlayer: Queries player properties.
HasSkill: Queries player skill levels.
HasStatBonus: Queries player item stat bonuses.
Intersect: Tests for an intersection with players, mobs or both.
IsAvatar: Queries what skin the player is currently wearing.
IsBlock: Queries the block id at a location.
IsBlockDeliveringPower: Queries if a block is delivering power (to adjacent blocks).
IsBlockEdited: Queries if the block at a location has been edited.
IsBlockLightSource: Queries if the block at a location is a light source (emits light).
IsBlockOpen: Queries if the block at a location is being accessed by a player.
IsBlockOre: Queries if the block at a location is an ore block.
IsBlockPassable: Queries if a player can pass through the block at a location.
IsBlockReceivingPower: Queries if a block is receiving power from an adjacent power emitting block. This command has replaced the old IsPowered command.
IsBlockResistance: Queries a blocks resistance (hardness) at a location.
IsBlockSolid: Queries if the block at a location is a solid block (players cannot see through it or see through parts of it).
IsBlockTexture: Queries the block texture id at a location.
IsClan: Queries if the player is a member of a clan.
IsClock: Queries the current game hour (24 hour clock).
IsCombat: Queries if combat is enabled.
IsDayTime: Queries whether or not it is currently day time.
IsDistance: Queries the distance between the player and a location.
IsEquipped: Queries if the player has the item equipped.
IsFiniteResources: Queries if Finite Resources is enabled.
IsGamerCount: Queries the number of gamers in the session.
IsInZone: Queries if the player is in a zone.
IsLight: Queries the quantity of light at a location.
IsLit: Queries if a location is touched by light, either from itself or an adjacent location.
IsMobCount: Queries the number of mobs in an area.
IsNameplate: Queries the players nameplate setting.
IsNightTime: Queries whether or not it is currently night time.
IsPowered: Queries if a block is powered.
IsSkills: Queries is the skill system is enabled.
IsRandom: Returns a random number.
IsTime: Queries the current game or player time.
IsVar: Queries the value of a variable.
Then: Marks which commands are executed if the queries are true.
Elseif: Allows multiple query branches.
Else: Marks which commands are executed if the queries are false.
Endif: Ends an If, Then, Else, Elseif block.

[Craig]

Global Scripts:
Global scripts are scripts that are accessible to all of your worlds.
To make a script global, simply prefix it's name with 'Global\'
If you host a multiplayer world, your global scripts are accessible.
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.

If you see multiple parameters defined, separated by a vertical bar (|), this means only one of the parameters should be used, it is your choice which. e.g. [on|off|toggle] means you can use either [on], [off] or [toggle], but only one. [true|false] means you can use either [true] or [false], but not both. Note: Some commands do support multiple choices, such as the Notify command. e.g. notify [text] [clan|admin] will notify both clan members and admins.


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.

[actor]
This parameter specifies that the command is targeted at the player or NPC 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.

[Craig]

.

[Craig]

Pickup: Manipulates item pickups.

Pickup [clear]
Pickup [x,y,z] [item] [qty]

[clear] - Clear all pickups in the world.

[x,y,z] - The coordinate in the world where the pickup is to spawn.

[item] - The name of the item to spawn.

[qty] - The quantity of the item in the pickup. This parameter may be ommitted, and a value of one (1) will be used.

Examples:

Pickup [100,200,150] [WoodSword]
Spawns a pickup at location 100,200,150 for 1 WoodSword.

Pickup [300,150,250] [Grass] [50]
Spawns a pickup at location 300,150,250 for 50 Grass blocks.

Pickup [clear]
Clears all pickup's in the world.

[Craig]

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.

[Craig]

CCTV: Views the game world from a block position.

CCTV [admin] [x,y,z]
CCTV [admin] [x,y,z] [x,y,z|n|s|e|w|track]
CCTV [admin] [x,y,z] [x,y,z|n|s|e|w|track]
CCTV [admin] [x,y,z] [x,y,z|n|s|e|w|track] [millisecs]
CCTV [admin] [x,y,z] [x,y,z|n|s|e|w|track] [millisecs] [swivelspeed]
CCTV [admin] [x,y,z] [x,y,z|n|s|e|w|track] [millisecs] [swivelspeed] [fov]

[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.

[x,y,z|n|s|e|w|track] - Either the target block position to look at or the initial direction the player will be facing. n = north, s = south, e = east, w = west. Hybrid directions such as nw or sse are not valid. North is used if this parameter is omitted. There is also the option to specify [track] instead of a direction. If this option is used, the CCTV will track the player who activated the script. swivelspeed is ignored if tracking is used.

[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.

[Craig]

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.

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.

[Craig]

CopyBlock: Copies a block from a source location to a destination location. All data and settings attached to the source block are copied to the destination block.

CopyBlock [x,y,z] [x,y,z]

[x,y,z] - The 1st coordinate is the source location.
[x,y,z] - The 2nd coordinate is the destination location.

Examples:

CopyBlock [10,20,30] [110,120,130]
Copies the block and all it's associated data at location 10,20.30 to location 110,120,130.

[Craig]

CopyRegion: Copies all the blocks from one source region to another destination region. All data and settings attached to the source blocks are copied to the destination blocks.

CopyRegion [x,y,z] [x,y,z] [x,y,z]

[x,y,z] - The 1st coordinate is the minimum bound of the source region.
[x,y,z] - The 2nd coordinate is the maximum bound of the source region.
[x,y,z] - The 3rd coordinate is the minimum bound of the destination region.

Examples:

CopyRegion [100,200,300] [150,250,350] [10,20,30]
Copies all the blocks and all their associated data from 100,200,300 / 150,250,350 to the location starting at 10,20,30. The final block at 150,250,350 will be copied to 60,70,80.

[Craig]

Fog: Creates a fog weather effect.

Fog [x,z] [radius] [duration] [intensity]
Fog [x,z] [radius] [duration] [intensity] [r,g,b]
Fog [x,z] [radius] [duration] [intensity] [r,g,b] [visibility]
Fog [x,z] [delete]

[x,z] - The surface coordinate for the center of the fog effect.

[radius] - The radius of the fog effect in blocks.

[duration] - The duration of the fog effect in seconds.

[intensity] - The strength or thickness of the fog. Valid values are 1 - 100, with 1 being the weakest and 100 the strongest.

[r,g,b] - The color of the fog in rgb format. r = red, g = green, b = blue. rgb are the 3 primary light colors and any color can be created with these 3 components. Possible values for each component are 0 - 255. This parameter may be omitted. If it is omitted, a random grayish color is used.

[visibility] - The distance in blocks from the players eye to the full strength of the fog. This parameter may be omitted. If it is omitted, a value of 40 is used.

[delete] - Deletes the Fog effect at [x,z]

Examples:

Fog [100,200] [100] [20] [50]
Creates a fog effect at surface coordinate 100,200, with a radius of 100 blocks. The effect lasts for 20 seconds and is half strength. A random grayish color is used. Visibility is 40 blocks.

Fog [300,800] [70] [120] [75] [200,200,200]
Creates a fog effect at surface coordinate 300,800, with a radius of 70 blocks. The effect lasts for 2 minutes and is 3/4 strength. The color of the fog is a whitish gray. Visibility is 40 blocks.

Fog [800,100] [20] [300] [100] [20,20,20] [3]
Creates a fog effect at surface coordinate 800,100, with a radius of 20 blocks. The effect lasts for 5 minutes and is full strength. The color of the fog is dark almost black. Visibility is 3 blocks, making it impossible for the player to see more than 3 blocks ahead of them.

Fog [300,800] [delete]
Deletes the current Fog effect at [300,800]