Basic guide to writing a ReSpouted plugin

Hello there! Want to get started writing a plugin for Spout? Well this is probably the best place, currently, to get started other than reading existing source code of decade, or older, old plugins.

I'm JustDoom and I am in charge of the server side of the ReSpouted project. I am now writing some basic guides on how to use their API!

I may update this further as I figure out how to create more stuff with the Spout API, stay tuned!

Getting Started
Custom Items
Custom Blocks

Getting Started

Getting started is easy. You can head over to GitHub and use this template I made as a base. There are some basic instructions in the README file for setting it up, I will not go over those here. Just make sure to use Java 8 for the plugin.

Great! Now you have a project set up to get started developing with.

Custom Items

Custom items is a very easy place to get started. You will want to create a branch new class named after whatever item you want to add, ExampleItem in this case for me, that then extends the SpoutAPI GenericCustomBlock class.

This was prompt you, depending on your IDE, to create a constructor with a super method that either has 2 or 3 inputs. We want the one with 3 as that lets us specify a custom texture to use. The first input is the instance of your plugin, if you used the template from before that would be Main.get(). The second is the item ID, which will be exampleitem. And the last is the URL to a PNG file for the texture. In this example I will just be using one from my own Spout plugin.

The class should now look like

public class ExampleItem extends GenericCustomItem {
    public ExampleItem() {
        super(Main.get(), "exampleitem", "https://i.ibb.co/sCFvQBD/q6wBozz.png");
    }
}

We are almost ready to see the item in game! But first we must do one more thing.

Back in the Main class we need to initialise the item class. We only want to do this once in a central place. So create a variable to hold the ExampleItem instance and initialise it in the Bukkit onEnable method.

public class Main extends JavaPlugin {

    private static Main INSTANCE;

    public Main() {
        INSTANCE = this;
    }

    public ExampleItem EXAMPLE_ITEM;

    @Override
    public void onEnable() {
        EXAMPLE_ITEM = new ExampleItem();
    }

    public static Main get() {
        return INSTANCE;
    }
}

Your Main class should now look something like this. If you build the plugin and add it to the server you will now have an item in the game!

Awesome! But it is still missing some things, like a proper name and functionality. Going back to the ExampleItem constructor we can call setName() with a proper name we want our item to have. I will set mine to Example Item. We can also set whether the item is stackable or not with setStackable(false), which will make it not stack. Fixing this feature was the first update to the Spout plugin in over a decade!

At the time of writing, getting the item from the custom creative tab makes it stackable, but as soon as it is thrown or properly interacted with it will become unstackable.

We can also add some basic functionality to the item by adding the override public boolean onItemInteract(SpoutPlayer player, SpoutBlock block, BlockFace face) to the class. This will let us run code when the item is interacted with, such as right clicking in the air or on a block.

@Override  
public boolean onItemInteract(SpoutPlayer player, SpoutBlock block, BlockFace face) {

    if (!player.isSpoutCraftEnabled()) return false; // Only interact if Spout player (Spout can allow vanilla clients to join)

    player.getInventory().addItem(new SpoutItemStack(Main.get().EXAMPLE_ITEM)); // Give player a Spout item

    return true; // Return true for success
}

With this we can obtain more of the item just by interacting with it! But ONLY if we are a Spout player. Some Spout plugins allow Vanilla clients to join, they will see normal items without the texture but should still be able to interact with most things.

In the method we give the player a new SpoutItemStack, this is how you give custom Spout items instead of a Vanilla item.

That is how to create your own custom item with a texture using the ReSpouted Plugin! Try to incorporate it into some Bukkit code for further features.

Custom Blocks

Custom blocks are another big part of Spout, and a bit more complex than items. To create one, you must make a new class for it such as ExampleBlock that extends GenericCustomBlock. The first two are the same as the item class, plugin instance and block ID. But the third is now isOpaque, for me I will set this to true.

Note: Builds 5 and 6 of Re:Spouted Plugin do not work with custom blocks due to a change in the last Spout Plugin commit. Spoutcraft Plugin builds 4 and below should also work.

public class ExampleBlock extends GenericCustomBlock {
    public ExampleBlock() {
        super(Main.get(), "exampleblock", true);
    }
}

I will also set the block name with setName().

Do not forget to add this to the main class as well!

public class Main extends JavaPlugin {
    private static Main INSTANCE;

    public Main() {
        INSTANCE = this;
    }

    public ExampleItem EXAMPLE_ITEM;
    public ExampleBlock EXAMPLE_BLOCK;

    @Override
    public void onEnable() {
        EXAMPLE_ITEM = new ExampleItem();
        EXAMPLE_BLOCK = new ExampleBlock();
    }

    public static Main get() {
        return INSTANCE;
    }
}

With that we should get a custom block that looks just like Stone. We need to do one more thing to give it a texture. We want to add new GenericCubeBlockDesign(Main.get(), "https://i.ibb.co/sCFvQBD/q6wBozz.png", 16) as the fourth argument of our super call. This sets the design of the block to the linked texture with a size of 16x16 pixels.

The class should now look like this

public class ExampleBlock extends GenericCustomBlock {
    public ExampleBlock() {
        super(Main.get(), "exampleblock", true, new GenericCubeBlockDesign(Main.get(), "https://i.ibb.co/sCFvQBD/q6wBozz.png", 16));
        setName("Example Block");
    }
}

Upload the plugin to the server and you should have a new item in the creative menu that lets you place your new block!

Success

Conclusion

With all that out of the way, go and have fun creating your own (Re)Spout(ed) plugins! Explore what used to be and what led up to our current server software. I love this kind of stuff, it is really cool seeing how it all came together. Many plugins we use now used to support Spout back when it was in use. The Spigot server software also got its start on the Spout forums!

Basic guide to writing a ReSpouted plugin

Contents

Getting Started

Custom Items

Custom Blocks

Conclusion