Note: This page is targeted at plugin developers who want to extend Skript's capabilities. If you're a server admin check out the documentation instead.

First Steps

New Plugin

If you want to create a new add-on for Skript, simply create a new plugin as explained in the Bukkit wiki, and add depend: [Skript] to your plugin.yml. This will make sure that the add-on is only loaded if Skript is actually installed on the server, or generate an error otherwise, and it will also load after Skript.
For most add-ons you won't have to write any usual plugin code, only register new expressions, effects, classes, etc. to Skript using the methods explained below.

Existing Plugin

If you already have a plugin and want to hook into Skript, you have to add soft-depend: [Skript] to your plugin.yml, and add a check for whether Skript is installed on the server in your plugin's onEnable:

if (Bukkit.getPluginManager().getPlugin("Skript") != null) {
	// put all code related to Skript here
}

If you omit the check you'll get errors if Skript is not installed.

Creating new Syntax Elements

For each element you'll have to make a separate class and extend the correct base class: ch.njol.skript.lang.Effect for effects, ch.njol.skript.lang.Condition for conditions, and ch.njol.skript.lang.util.SimpleExpression or any class out of ch.njol.skript.expressions.base for expressions (The differences of these expression classes will be explained later on).

Now implement all required methods of the class you're extending. I hope that the Javadocs are clear enough to understand what to do, but if you don't understand something you can always ask questions.

Expressions

Like previously mentioned you have several classes you can extend to create new expressions:

• If you want to create a simple ‘property’ expression, e.g. location of <entity> you should extend SimplePropertyExpression<F, T> where <T> is the property type and <F> is the type to get the property from. This class replaces the T[] get(Event) method with a T convert(F) method which should get the property from the value (e.g. return f.getLocation();), and also provides a register method which automatically creates two patterns, e.g. location of %entity% and %entity%'[s] location.
• For other property expressions that are not so basic you can extend PropertyExpression, but remember to call setExpr in init!
• For most other cases you should extend SimpleExpression, e.g. to create a simple expression like damage, but also to create expressions like random number between %number% and %number%.

Expressions also have several optional methods which you don't have to override, e.g. acceptChange, change, setTime, iterator, and isLoopOf.

Registering a new element

To make Skript aware of your new element use one of the static registerXyz methods in ch.njol.skript.Skript. Please note that Skript registers each element in its own class in a static {…} block which only works because of a small hack. You can either use the same method via a SkriptAddon instance received by Skript.registerAddon or simply register all your elements in onEnable().

Classes

If you want to use a custom class in your syntax elements you'll have to register that as well. Take a look at ch.njol.skript.classes.data.BukkitClasses for examples.

Patterns

When registering expressions, conditions and effects you have to provide a pattern to match your syntax element. Such a pattern will be matched 1:1 to the user's input except for the following constructs:

• [square brackets] make part of the pattern optional
• (ordinary|brackets) with groups separated by pipes (|) match any of the groups.
  A group can be prefixed with <int>¦, e.g. (1¦first|2¦second) to set the ParseResult's mark to the given integer (can be negative)
• <angle brackets> can be used to include a regex in the pattern. Please note that this is much less efficient than using the above brackets.
• %percent signs% are used to denote an expression in the pattern. The text between the percent signs has to be the codename of the desired return type, e.g. itemtype. All %expression%s defined in the pattern will be in the array given to your expression's init method, where the default value of a type will be used if an expression was omitted, e.g. if it is enclosed in square brackets.
  %-codename% causes the expression to be null instead of the class' default value if it's omitted. This is required if the type does not have a default value.
  %codename1/codename2/etc.% allows to define a list of accepted types for the expression.
  %codename@-1% and %codename@1% will automatically call .setTime(-1/1) on the expression and print an error if it returns false.
  %~codename% forces the expression to be an expression and not a literal, while %*codename% only parses literals and no expressions.
• A backslash (\) escapes the next character, even if it doesn't have a special meaning.

Please note that patterns are not checked for errors but may generate runtime errors while parsing if they are found to be invalid.

Maven Repository

If you're using Maven for your plugin, you can add Skript as dependency by adding the following to your pom.xml:

<dependencies>
	<dependency>
		<groupId>ch.njol</groupId>
		<artifactId>skript</artifactId>
		<version>2.0.1</version><!-- Use whatever version you want to depend on -->
		<scope>provided</scope>
	</dependency>
</dependencies>

<repositories>
	<repository>
		<id>njol-repo</id>
		<url>http://maven.njol.ch/repo/</url>
	</repository>
</repositories>

A Last Word

Please also take a look at all predefined syntax elements in ch.njol.skript.expressions/effects/conditions/events before asking too many questions .