Pageable staff mod

This page is a tutorial that allows developers to learn how to create a configurable and pageable staff mod using StaffModLib.

Introduction

In this page, you'll learn how to create a configurable and pageable staff mod using StaffModLib. This kind of staff mod is very useful when you want your players to have more than 9 items in their inventory. It introduces a page system which allows them to switch between the pages of items very easily.

We'll build this tutorial on the previous one so if you have not already read it, we recommend you to do so.

Configurable staff mod

Set a staff mod pageable

First of all, we'll declare our staff mod as pageable. To do so, we'll inherit from the PageableBukkitStaffMod class instead of the SimpleBukkitStaffMod class previously used. So, let's do that into the SimpleStaffMod class that has been previously created.

public class SimpleStaffMod extends PageableBukkitStaffMod implements Configurable {

    // For lisibility reasons, we do not display all the previously
    // mentionned code but suppose that it is here.

    @Override
    public NavigationItem<ItemStack> getNext() {
        return null; // Will be replaced later.
    }

    @Override
    public NavigationItem<ItemStack> getPrevious() {
        return null; // Will be replaced later.
    }
    
    // ...
}

Creating page items

These items are used to switch between next and previous pages of items of the staff mod. To add them into our staff mod, we first need to create a NavItem class which inherits of the BukkitNavigationItem class and which will contains their data. This class will also implements the Configurable interface to allow to configure the item from a configuration file.

This class has a constructor with two required parameters :

Name	Type	Description
plugin	Plugin	A plugin instance used to register listeners.
staffMod	PageableStaffMod<Player, ItemStack>	An instance of your staff mod which will be used to switch to another pages.

We'll also add another parameter which corresponds to the type of action the item will do. It will be used to get the right item in the config file. There are two possible actions : OPEN_PREVIOUS_PAGE and OPEN_NEXT_PAGE.

So here is the code of the NavItem class :

public class NavItem extends BukkitNavigationItem implements Configurable {

    private final NavigationType type;
    private ItemStack item;

    public NavItem(Plugin plugin, PageableStaffMod<Player, ItemStack> staffMod, NavigationType type) {
        super(plugin, staffMod);
        this.type = type;
    }

    @Override
    public NavigationType getNavigationType() {
        return this.type;
    }

    @Override
    public ItemStack getItem() {
        return this.item.clone();
    }

    @Override
    public void configure(ConfigurationSection parent) {

        // If page type is PREVIOUS, then the key is 'previous-page'.
        // Else, the key is 'next-page'.
        String key = this.type == NavigationType.OPEN_PREVIOUS_PAGE ? "previous-page" : "next-page";

        ConfigurationSection section = parent.getConfigurationSection(key);

        this.item = section.getItemStack("item").clone();
    }
}

You can notice that the body of the configure(ConfigurationSection parent) method is different in comparison with the one of basic items. Indeed, we'll configure the item according to its page type and as it is a page item, its slot is automatically added by the plugin.

An item which allows to go to the previous page is set in the first slot of the inventory whereas the one which allows to go to the next page is set in the last.

Register page items

Now, go back to the SimpleStaffMod class and implements the body of the getNext() and the getPrevious() methods.

@Override
public NavigationItem<ItemStack> getPrevious() {
    return new NavItem(this.plugin, this, NavigationType.OPEN_PREVIOUS_PAGE);
}

@Override
public NavigationItem<ItemStack> getNext() {
    return new NavItem(this.plugin, this, NavigationType.OPEN_NEXT_PAGE);
}

These items are automatically registered at runtime by the library so don't have to register them manually.

Configure the staff mod

The configuration of the staff mod is different from the one that has been previously created. Indeed, you have to configure all the registered items and not only the held ones.

@Override
public void configure(ConfigurationSection parent) {
    this.getPagination().getElements().stream()
        .filter(item -> item instanceof Configurable)
        .map(item -> (Configurable) item)
        .forEach(configurable -> configurable.configure(parent));
}

Do not configure the slot of the items in the configure() method because they will be overrided by the library at runtime when navigating between pages.

Registering items

To simulate a staff mod with a lot of items, we'll create another type of item using the TestItem class.

ppublic class TestItem extends BukkitStaffModItem implements Configurable {

    private ItemStack item;

    @Override
    public ItemStack getItem() {
        return this.item.clone();
    }

    @Override
    public void configure(ConfigurationSection parent) {

        ConfigurationSection section = parent.getConfigurationSection("test-item");

        this.item = section.getItemStack("item");
    }
}

Now, let's register our items (excluding page items).

private void registerItems(Player player) {

    // Declaring items.
    BukkitStaffModItem freezeItem = new FreezeItem(player, this.plugin);
    
    // WARNING : Do not set slot here. They will be added automatically
    // by the pagination system.
    
    // Registering items.
    this.registerItem(freezeItem);
    
    // Adding test items for the example.
    for(int i = 0; i < 30; i++) this.registerItem(new TestItem());
    
    // Configuring the staff mod.
    this.configure(this.getConfigurationSection());
}

Configuration file

In this part, we'll go back into the configuration file that has been previously created and we'll configure all of our items. Let's do so by opening this file and adding replacing the staffmod section by the following one :

staffmod:
  # The name of the section in which the item is stored.
  # It can be anything you want.
  freeze:
    # The configuration of the ItemStack.
    # Refer to the Spigot doc for more information.
    item:
      ==: org.bukkit.inventory.ItemStack
      type: BLAZE_ROD
      amount: 1
      meta:
        ==: ItemMeta
        meta-type: UNSPECIFIC
        display-name: "§eFreeze"
        lore:
          - "§eClick to §afreeze §eor §cunfreeze §ea player."
  # This section is about the test item.
  test-item:
    item:
      ==: org.bukkit.inventory.ItemStack
      type: STICK
      amount: 1
      meta:
        ==: ItemMeta
        meta-type: UNSPECIFIC
        display-name: "§eTest item"
        lore:
          - "§eA test item !"
  # This section is about the item which allows a player
  # to go to the previous page of the staff mod.
  previous-page:
    item:
      ==: org.bukkit.inventory.ItemStack
      type: ARROW
      amount: 1
      meta:
        ==: ItemMeta
        meta-type: UNSPECIFIC
        display-name: "§bPrevious Page"
        lore:
          - "§eClick to go on the §6previous page §eof the menu."
  # This section is about the item which allows a player
  # to go to the previous page of the staff mod.
  next-page:
    item:
      ==: org.bukkit.inventory.ItemStack
      type: ARROW
      amount: 1
      meta:
        ==: ItemMeta
        meta-type: UNSPECIFIC
        display-name: "§bNext page"
        lore:
          - "§eClick to go on the §6next page §eof the menu."

Do not add the slot of the items here because they will be automatically set by the library at runtime when navigating between pages. However, the order of the item in this section is important and will be conserved.

Now your pageable and configurable staff mod is ready to be used !