Skript: Documentation

Please note that this is the old documentation on the last version of Skript I released.
If you use a fork of Skript, please refer to that fork's documentation to find all new & updated information.

Writing a trigger for Skript is not much more than describing what should be done when some conditions are met.
Because many things you would want to do are linked to events, such as placing a block or pulling a lever, every trigger has to define when it should be called. This is called the event of the trigger. Whenever this event occurs, e.g. when a player places a block, the trigger's conditions are checked one by one. If all conditions are met, the effects of the trigger are executed.
The following is a simple example of a trigger with an event, one condition and one effect:

# event:
on place of sand:
# condition:
block below is air
# effect:
send "Watch the sand falling!" to player

In case you didn't already figure out what this trigger does: It informs players who place sand in midair that the sand they just placed will fall down as there's no block below it.

To create a new trigger, start a text editor (e.g. Notepad), write the trigger, and then save it in the Skript/scripts/ directory as ‘name of the trigger.sk’, e.g. ‘plant with hoe.sk’. You can give it any name you want, but it should be meaningful so that you'll later still know what kind of triggers it contains.

After creating or changing a trigger you must either restart your server or use the command /skript reload for the changes to take effect. If you restarted the server you should check the server log for [Skript] errors, while errors will be directly sent to you if you use /skript reload. If you get any errors this means that Skript couldn't understand parts of your trigger, and it will usually tell you what is wrong. If you get a general error like can't understand '...' or '...' is not a(n) ... you should check your spelling.

If you need help you can post on Skript's help forum. As usual, please use the search function before posting and read this documentation, it might answer your questions. Taking a look at what others have accomplished with Skript can also help a lot in case my style of writing does not suit you well.

Advanced Syntax

Skript's syntax is not limited to simple statements, but can also be more complex like set fuel of block to player's tool
To make things like ‘tool of …’ or ‘block below/north of/above …’ possible, so-called expressions are used. You can find a list of all expressions here.

As well as the basic syntax the trigger syntax is also more advanced. The following sections cover these special cases.

Conditionals

A nice feature are conditional statements. Such a statement is a part of a trigger which is only executed/checked if the section's main condition is met, which looks like this:

the first line is the main condition followed by a colon:
followed by one or more indented lines which are only executed if the main condition is met
if a condition is not met within these lines the trigger will continue after the end of the section
the trigger continues as normal after the indented lines

You can also add an ‘else:’ just after the indented lines end and one or more indented lines afterwards which will be executed if the main condition isn't met.
The following example demonstrates the usage of conditionals:

on login:
chance of 50%:
give a cake to the player
send "You got a gift for logging in =)" to the player
else:
send "You were not fortunate enough to get a gift this time. Try again next time!" to the player

This script gives each player a 50% chance of receiving a cake upon logging in, notifying them of their gift or that they didn't receive a gift if they were not lucky.

Loops

Loops help to reduce repetitive tasks within triggers. There are currently a few loopable values, including items, blocks and players.

Loops are pretty straightforward. You say what to loop and then use that within the loop:

loop values to loop:
do something with the loop-value

Please note that conditions behave differently in loops. If a condition is not met, only the current execution of the loop is terminated and the loop will continue with the next item. If you want conditions to exit the loop, use a conditional:

condition:
exit loop

You can also stop the whole trigger with ‘exit’ or ‘exit trigger’.

As examples are always nice here's one. It defines a command /find which finds a block of a certain type near the player:

command /find <material>:
description: Find a block of the given material
trigger:
loop blocks in radius 10:
loop-block is argument
message "Found a %argument% block at %location of loop-block%"
stop trigger
send "There's no %argument% block around!" to player

~ njol.ch created by Peter Güttinger
~ icons by Yusuke Kamiyamane ~
Last modified: Týr's Day, the 1st of October 2013