Custom item actions

This page describes how to develop custom item actions.

CraftVentory comes with a set of predefined item actions. However, to meet your needs, you may want to create new item actions. This page explains step by step how this can be achieved.

Create the action

The first step consists in creating the action itself. This is done by creating a new class that implements the interface ClickAction. In the following example, we are implementing an action which executes a command when a player clicks on an item.

public class CommandAction implements ClickAction {

    public static final String ACTION_NAME = "EXECUTE_COMMAND";

    private final String command;

    public CommandAction(String command) {

        if(command == null || command.isEmpty()) {
            throw new IllegalArgumentException("command cannot null or empty");
        }

        this.command = command;
    }

    @Override
    public void execute(FastInventoryClickEvent event) {
        Player player = event.getPlayer();
        player.performCommand(this.command);
    }

    @Override
    public String getName() {
        return ACTION_NAME;
    }
}

When implementing the ClickAction interface, two methods must be defined:

• execute(FastInventoryClickEvent event): Method executed when a player clicks on an item which has our action.

• getName(): Returns the name of the action. This name must identify uniquely the action and it is encouraged to use a globally visible constant to store it.

Create the action loader

Like inventories and items, actions can be configured in configuration files. Thus, it is necessary to tell the library how to load each action.

This is done by creating a class that implements the ClickActionLoader<T> interface. Here, we only want to load our action from YAML files so the generic parameter will be a ConfigurationSection.

public class CommandActionLoader implements ClickActionLoader<ConfigurationSection> {

    private static final String COMMAND_KEY = "command";

    @Override
    public ClickAction load(ConfigurationSection section) throws InventoryConfigException {

        if(!section.isString(COMMAND_KEY)) {
            throw new InventoryConfigException(String.format("Property '%s' not found or not a string at '%s'", COMMAND_KEY, section.getCurrentPath()));
        }

        String command = section.getString(COMMAND_KEY);

        if(command.startsWith("/")) {
            command = command.substring(1);
        }

        return new CommandAction(command);
    }

    @Override
    public String getName() {
        return CommandAction.ACTION_NAME;
    }
}

When implementing the ClickActionLoader<T> interface, two methods must be defined:

• load(ConfigurationSection section): Method executed to load the action. When an error occurs, this method should throw an InventoryConfigException.

• getName(): Returns the name of the action. This name must be the same as the one defined in the class that implements the ClickAction interface.

Register the action loader

The last step consists in registering our action loader in a factory to tell the library to use it. If you are using the default ClickActionLoaderFactory provided by the library, this can be done with the following code:

ClickActionLoaderFactory<ConfigurationSection> factory = FastInventoryLibrary.createDefaultClickActionLoaderFactory();
factory.addLoader(new CommandActionLoader());