Overview

STB offers an API to make it easy for other plugins to define their own custom items and blocks, and benefit from STB's framework of automated event routing, energy system, GUI methods and block persistence.

• API Javadocs

As of v0.0.4 the API has settled down somewhat and later versions of STB should (hopefully!) not introduce any API breakage without good warning via deprecation.

The basic steps to creating an STB-based plugin are:

1. Add SensibleToolbox as a build dependency to your plugin

2. Add a dependency on SensibleToolbox (soft or hard, depends on how you're using STB) in your plugin's plugin.yml file

3. Define your custom item/block class(es) in your plugin

4. Attempt to hook SensibleToolbox in your plugin's onEnable() method

5. If you successfully hook SensibleToolbox, register your custom item/block class(es) with a simple API call

The above steps will now be explained in more detail...

Add STB as a Build Dependency

If you build your plugin with Maven (recommended!), just add these lines to your pom.xml:

<!--add this to your repositories section -->
<repository>
  <id>hawkfalcon-repo</id>
  <name>Hawkfalcon Repository</name>
  <url>http://ci.hawkfalcon.com/plugin/repository/everything</url>
</repository>

<!--add this to your dependencies section -->
<dependency>
  <groupId>me.desht</groupId>
  <artifactId>sensibletoolbox</artifactId>
  <version>0.0.4</version>
  <scope>provided</scope>
</dependency>

I recommend using an explicit <version> number there. The current release version at time of writing is 0.0.4.

If you don't use Maven, you'll need to download the desired version of SensibleToolbox.jar and manually add it as a build dependency in your IDE.

Add a plugin.yml dependency

Easy enough; just add this line to your plugin.yml:

depend: [ ProtocolLib, SensibleToolbox ]

or if your plugin already depends on other plugins, add it to the list:

depend: [ ProtocolLib, SensibleToolbox ]

Defining a Custom Item/Block Class

This is most complex part. Defining a new STB item or block basically consists of creating a class which extends one of the existing base classes provided by SensibleToolbox, overriding several mandatory methods, and optionally overriding many more methods. The useful base classes to extend are:

• BaseSTBItem - extend this class if your new item is just an item, and not placeable in the world as a block. Example: https://github.com/desht/sensibletoolbox/blob/master/src/main/java/me/desht/sensibletoolbox/items/TapeMeasure.java

• BaseSTBBlock - extend this class if your new item is a generic block (but read on for more specific types of block). Example: https://github.com/desht/sensibletoolbox/blob/master/src/main/java/me/desht/sensibletoolbox/blocks/RedstoneClock.java

• BaseSTBMachine - extend this class if your new item is a generic machine, with input/output slots, an energy cell slot and can be charged with SCU. Example: https://github.com/desht/sensibletoolbox/blob/master/src/main/java/me/desht/sensibletoolbox/blocks/machines/FiftyKBatteryBox.java

• AbstractProcessingMachine - extend this class if your machine will have a progress bar to indicate its progress. Note that this can also be used to indicate any kind of numeric quantity, e.g. see https://github.com/desht/sensibletoolbox/blob/master/src/main/java/me/desht/sensibletoolbox/blocks/machines/BigStorageUnit.java (the processing indicator here shows the number of items in the BSU)

• AbstractIOMachine - extend this class if your machine does simple input->output item processing, with possible custom recipes. Example: https://github.com/desht/sensibletoolbox/blob/master/src/main/java/me/desht/sensibletoolbox/blocks/machines/Masher.java

The Javadocs contain a full reference of the methods which must be or may be overridden in your new subclass.

Hooking SensibleToolbox and Registering your Item(s)

You'll want to use code similar to the following in your onEnable():

public void onEnable() {
  // ... do other stuff

  Plugin stb = pm.getPlugin("SensibleToolbox");
  if (stb != null && stb.isEnabled()) {
    SensibleToolbox.getItemRegistry().registerItem(this, new YourCustomItemClass());
  }

  // ...
}

An Example Plugin

The STBTest plugin has been created to use as a testbed for hooking into Sensible Toolbox, but also to serve as example code on how the Sensible Toolbox API can be used:

• https://github.com/desht/stbtest/

So far, only one new item has been added, the Lightning Gun: https://github.com/desht/stbtest/blob/master/src/main/java/me/desht/stbtest/LightningGun.java - the code is heavily commented and worth browsing to get an idea of how a simple STB item would be created. It includes concepts such as freezing/thawing item data, storing and using SCU, and using custom STB ingredients in its crafting recipe.