Download the current API

These compiled SIR+ API artifacts are generated directly from the standalone SIRApi project.

dependencies {
    compileOnly(files("libs/SIR-Plus-Api-0.3.2.jar"))
}

What the API is for

SIRApi exists so you can extend SIR+ without forking the base plugin. The API gives you access to:

• the SIR+ plugin instance and managers
• addon lifecycle hooks
• command-provider integration
• user data wrappers
• helper utilities for listeners, files, placeholders, and chat toggles

The normal addon workflow is:

1. compile against the API jar with compileOnly
2. implement a class that extends SIRAddon
3. ship addon.yml
4. optionally ship commands.yml
5. drop the jar into plugins/SIR-Plus/addons

Add the API to your project

Use the build-tool selector in the download box above to switch between Gradle Kotlin, Gradle Groovy, Maven, and a manual IDE-style setup. The snippet updates automatically for the selected API version.

Suggested project layout

my-addon/
  src/main/java/...
  src/main/resources/
    addon.yml
    commands.yml
    config.yml

Only addon.yml is mandatory. The rest depends on what your addon does.

addon.yml reference

Typical addon descriptor:

main: com.example.sirplus.ExampleAddon
name: example-addon
title: Example Addon
description:
  - Adds custom behavior on top of SIR+.
depend: []
soft-depend:
  - PlaceholderAPI

Field meaning

Remember that depend and soft-depend here refer to addons, not Bukkit plugins. Bukkit plugin dependencies are better represented with PluginDependant.

Minimal addon class

package com.example.sirplus;

import com.bitaspire.sir.SIRApi;
import com.bitaspire.sir.addon.SIRAddon;

public final class ExampleAddon extends SIRAddon {

    @Override
    public boolean register() {
        saveResource("config.yml", false);
        SIRApi.instance().getPlugin().getLogger().info(getName() + " loaded successfully.");
        return true;
    }

    @Override
    public boolean unregister() {
        SIRApi.instance().getPlugin().getLogger().info(getName() + " unloaded.");
        return true;
    }
}

This is enough for SIR+ to:

• instantiate the addon
• create its data folder
• extract resources you save with saveResource(...)
• register the addon in the addon manager

Addon commands with CommandProvider

If your addon should contribute commands, implement CommandProvider and ship a commands.yml descriptor in the jar root.

Minimal provider example:

import com.bitaspire.sir.addon.SIRAddon;
import com.bitaspire.sir.command.CommandProvider;
import com.bitaspire.sir.command.SIRCommand;

import java.util.Collections;
import java.util.Set;

public final class ExampleAddon extends SIRAddon implements CommandProvider {
    @Override
    public Set<SIRCommand> getCommands() {
        return Collections.singleton(new ExampleCommand());
    }
}

commands.yml reference

main: com.example.sirplus.ExampleAddon
name: ExampleAddon
title: Example Addon
description:
  - Example addon command provider.

commands:
  example:
    permission: sir.example
    aliases: [ex]
    description: "Example command"
    usage: "/example <arg>"
    permission-message: "You do not have permission"
    sub-commands:
      reload: sir.example.reload
    depends:
      enabled: false
      parent: "other"

What SIR+ reads from commands.yml

This is the same command model used by the built-in providers, so addon commands can feel native to the platform.

Useful API types

The public API jar includes much more than SIRAddon. These are the types you will reach for most often.

Package map

The current API jar exposes classes under:

• com.bitaspire.sir.*
• com.bitaspire.sir.channel.*
• com.bitaspire.sir.addon.*
• com.bitaspire.sir.command.*
• com.bitaspire.sir.module.*
• com.bitaspire.sir.user.*

That means addon code can interact with addon management, command management, module metadata, and user data without reflecting into the main plugin jar.

ChatChannel changes in 0.3.2

API 0.3.2 formalizes the new channel model used by the modern channels module and by SIR+:

• the canonical interface is now com.bitaspire.sir.channel.ChatChannel
• channel behavior is grouped into Access, Audience, Style, Logging, and Click
• channel routing is no longer exposed as one giant flat interface
• the old com.bitaspire.sir.ChatChannel still exists only as a deprecated compatibility bridge for pre-0.3.2 addons

If you are writing a new addon, import the new package directly.

import com.bitaspire.sir.channel.ChatChannel;
import com.bitaspire.sir.channel.Access;
import com.bitaspire.sir.channel.Audience;
import com.bitaspire.sir.channel.Style;
import com.bitaspire.sir.channel.Logging;

Typical migration examples:

• old channel.getLocalAccess() -> new channel.getAccess()
• old channel.getRadius() -> new channel.getAudience().getRadius()
• old channel.getChatFormat() -> new channel.getStyle().getFormat()
• old channel.getLogFormat() -> new channel.getLogging().getFormat()
• old channel.getClickAction() -> new channel.getStyle().getClick()

This is the main API change you need to account for when upgrading addon code from the previous public builds.

Common extension patterns

Plugin-aware loading

Implement PluginDependant when your addon expects a plugin such as PlaceholderAPI or Vault.

That lets SIR+ defer or validate loading around external plugin availability.

Per-user toggles

Implement ChatToggleable when your addon owns a user toggle and you want to store that state through SIR's settings flow.

Placeholder expansions

Extend PAPIExpansion if your addon also ships placeholders.

Custom formatting

Implement UserFormatter<T> when your addon should expose formatter behavior that other addon-aware code can resolve through the addon manager.

Event listeners

Extend com.bitaspire.sir.Listener when you want the convenience registration helpers instead of raw Bukkit boilerplate.

Build and deploy

1. Compile the addon jar against the selected API jar, currently SIR-Plus-Api-0.3.2.jar.
2. Make sure addon.yml is at the jar root.
3. If the addon exposes commands, include commands.yml too.
4. Copy the jar into plugins/SIR-Plus/addons/.
5. Start the server.
6. Use /sir addons to verify that the addon is visible.
7. Enable or disable it with /sir addons [name] [enable/disable/toggle] as needed.

If the jar loads but its commands do not appear, the usual culprit is a missing or malformed commands.yml.

Troubleshooting

Check these first when an addon does not behave as expected:

1. addon.yml exists at the jar root
2. the main class extends SIRAddon
3. addon hard dependencies in depend are present
4. plugin dependencies declared through PluginDependant are installed
5. the addon is enabled in addons/states.yml
6. if commands are missing, commands.yml exists and the addon implements CommandProvider

For the runtime side of loading and state persistence, continue with Addon Runtime.