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.

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 -->
  <name>Hawkfalcon Repository</name>

<!--add this to your dependencies section -->

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:

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.

Last updated