Skip to main content

​
Overview

Skript provides a comprehensive addon API that allows developers to extend Skript’s functionality by creating custom syntax elements, registering new types, and integrating with external plugins.

​
Registering an Addon

To create a Skript addon, you first need to register your plugin with Skript. This provides access to the addon API and syntax registration methods. 
import org.skriptlang.skript.Skript;
import org.skriptlang.skript.addon.SkriptAddon;
import org.bukkit.plugin.java.JavaPlugin;

public class MyAddon extends JavaPlugin {
    
    private SkriptAddon addon;
    
    @Override
    public void onEnable() {
        // Register the addon with Skript
        addon = Skript.instance().registerAddon(getClass(), getName());
        
        // Your registration code here
    }
}

​
Legacy API (Deprecated)

The legacy API is still supported but marked for removal: 
import ch.njol.skript.Skript;
import ch.njol.skript.SkriptAddon;

@Deprecated
public void onEnable() {
    SkriptAddon addon = Skript.registerAddon(this);
}
Source: /src/main/java/ch/njol/skript/SkriptAddon.java:36-38

​
Loading Classes

The SkriptAddon class provides utilities to load syntax element classes from your addon’s jar file. 
public SkriptAddon loadClasses(String basePackage, String... subPackages) 
        throws IOException {
    Utils.getClasses(plugin, basePackage, subPackages);
    return this;
}
Source: /src/main/java/ch/njol/skript/SkriptAddon.java:75-78

​
Example Usage

@Override
public void onEnable() {
    addon = Skript.instance().registerAddon(getClass(), getName());
    
    try {
        addon.loadClasses("com.example.myaddon", 
            "expressions", 
            "conditions", 
            "effects", 
            "events"
        );
    } catch (IOException e) {
        // Handle error
        getLogger().severe("Failed to load addon classes: " + e.getMessage());
    }
}
This automatically loads all classes in the specified subpackages, triggering their static initializer blocks where syntax registration typically occurs.

​
Language Files

Addons can provide their own language files for localization: 
public SkriptAddon setLanguageFileDirectory(String directory) {
    localizer().setSourceDirectories(directory, 
        plugin.getDataFolder().getAbsolutePath() + directory);
    return this;
}
Source: /src/main/java/ch/njol/skript/SkriptAddon.java:87-90

​
Example

addon.setLanguageFileDirectory("lang");
This tells Skript to look for language files in:
  • your-addon.jar/lang/ (bundled with the plugin)
  • plugins/YourAddon/lang/ (user-customizable)

​
Addon Registry System

The modern addon API provides a registry system for storing and retrieving addon-specific data: 
@Override
public <R extends Registry<?>> void storeRegistry(Class<R> registryClass, R registry) {
    addon.storeRegistry(registryClass, registry);
}

@Override
public <R extends Registry<?>> R registry(Class<R> registryClass) {
    return addon.registry(registryClass);
}
Source: /src/main/java/ch/njol/skript/SkriptAddon.java:133-150

​
Accessing the Syntax Registry

Every addon has access to a SyntaxRegistry for registering syntax elements: 
@Override
public SyntaxRegistry syntaxRegistry() {
    return addon.syntaxRegistry();
}
Source: /src/main/java/ch/njol/skript/SkriptAddon.java:158-160

​
Version Information

The addon API automatically parses version information from your plugin.yml: 
SkriptAddon(JavaPlugin plugin) {
    this.plugin = plugin;
    this.name = plugin.getName();
    Version version;
    try {
        version = new Version(plugin.getDescription().getVersion());
    } catch (IllegalArgumentException e) {
        // Falls back to parsing numeric components
        final Matcher m = Pattern.compile("(\\d+)(?:\\.(\\d+)(?:\\.(\\d+))?)?").
            matcher(plugin.getDescription().getVersion());
        if (!m.find())
            throw new IllegalArgumentException("Version contains no numbers");
        version = new Version(Utils.parseInt(m.group(1)), 
            m.group(2) == null ? 0 : Utils.parseInt(m.group(2)), 
            m.group(3) == null ? 0 : Utils.parseInt(m.group(3)));
    }
    this.version = version;
}
Source: /src/main/java/ch/njol/skript/SkriptAddon.java:36-55

​
Best Practices

Add Skript as a dependency to ensure proper load order:
depend: [Skript]
Or use soft-depend if your plugin can work without Skript:
softdepend: [Skript]
Always register your addon in onEnable() or onLoad(). Registration after Skript has finished loading will throw a SkriptAPIException.
The modern API (org.skriptlang.skript.*) is preferred over the deprecated legacy API (ch.njol.skript.*).

​
Complete Example

package com.example.myaddon;

import org.bukkit.plugin.java.JavaPlugin;
import org.skriptlang.skript.Skript;
import org.skriptlang.skript.addon.SkriptAddon;

import java.io.IOException;

public class MySkriptAddon extends JavaPlugin {
    
    private SkriptAddon addon;
    
    @Override
    public void onEnable() {
        // Check if Skript is present
        if (getServer().getPluginManager().getPlugin("Skript") == null) {
            getLogger().severe("Skript not found! Disabling plugin.");
            setEnabled(false);
            return;
        }
        
        // Register with Skript
        addon = Skript.instance().registerAddon(getClass(), getName());
        
        // Set up language files
        addon.setLanguageFileDirectory("lang");
        
        // Load syntax elements
        try {
            addon.loadClasses("com.example.myaddon",
                "expressions",
                "conditions",
                "effects",
                "events"
            );
        } catch (IOException e) {
            getLogger().severe("Failed to load syntax classes: " + e.getMessage());
            setEnabled(false);
            return;
        }
        
        getLogger().info("MySkriptAddon " + addon.name() + " has been enabled!");
    }
    
    @Override
    public void onDisable() {
        getLogger().info("MySkriptAddon has been disabled.");
    }
}

​
Next Steps

Syntax Registration

Learn how to register custom conditions, effects, and expressions

Custom Events

Create custom Skript events for your addon

Build docs developers (and LLMs) love

Get started for freeTalk to us