Addons

Creating and Using Addons in TheRewards

This guide explains how to create custom addons for TheRewards system using the provided Addon abstract class.

Basic Structure of an Addon

An addon extends the abstract Addon class and implements its required methods. Here's a simple example:

package com.example.myserver.addons;

import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerJoinEvent;
import xshyo.us.theAPI.commands.CommandArg;
import xshyo.us.therewards.api.Addon;
import xshyo.us.therewards.api.AddonManager;
import xshyo.us.therewards.enums.DebugLevel;
import xshyo.us.therewards.utilities.Debug;

public class WelcomeAddon extends Addon {

    public WelcomeAddon() {
        super("WelcomeAddon");
    }

    @Override
    protected void onLoad(AddonManager manager) {
        // Register configuration
        registerAddonConfig("config");
        
        // Register commands
        registerAddonCommand(new WelcomeCommands());
        
        // Register event listeners
        registerListener(new WelcomeListener());
        
        // Schedule a task
        scheduleTask(() -> {
            Debug.log("WelcomeAddon periodic task running!", DebugLevel.NORMAL);
        }, 20L, 12000L); // Run after 1 second, then every 10 minutes
        
        Debug.log("WelcomeAddon has been loaded successfully!", DebugLevel.NORMAL);
    }

    @Override
    protected void onUnload() {
        Debug.log("WelcomeAddon is being unloaded...", DebugLevel.NORMAL);
        // Clean up resources, if necessary
    }

    @Override
    protected void onConfigReload() {
        Debug.log("Reloading configuration for WelcomeAddon", DebugLevel.NORMAL);
        // Handle configuration reload
    }
    
    // Inner class for event handling
    private class WelcomeListener implements Listener {
        @EventHandler
        public void onPlayerJoin(PlayerJoinEvent event) {
            String welcomeMessage = getConfig("config").getString("welcome-message");
            event.getPlayer().sendMessage(welcomeMessage);
        }
    }
    
    // Inner class for commands
    private class WelcomeCommands extends CommandArg {
        public WelcomeCommands() {
            super("welcome");
        }
        
        @Override
        public boolean execute(CommandSender sender, String[] args) {
            if (args.length == 0) {
                sender.sendMessage("Welcome to the server!");
                return true;
            }
            
            if (args[0].equalsIgnoreCase("reload")) {
                onConfigReload();
                sender.sendMessage("Welcome addon configuration reloaded!");
                return true;
            }
            
            return false;
        }
    }
}

Setting Up addon.yml

Every addon requires an addon.yml file at the root of the JAR that defines metadata:

yamlCopyname: VoucherAddon
version: 1.0.0
main: xshyo.us.voucherAddon.VoucherAddon

This file specifies:

• name: The addon's identifier

• version: The current version

• main: The fully qualified class name of your main addon class

Configuration File

Create a config.yml file at the root of your JAR:

# WelcomeAddon Configuration
file-version: 1.0

# Welcome message shown to players when they join
welcome-message: "§aWelcome to our server! Enjoy your stay!"

# Other settings
enable-join-messages: true

Working with Player Data

The addon system provides methods to store and retrieve player-specific data:

// Example Player Data Class
public class PlayerWelcomeData {
    private int loginCount;
    private long lastLogin;
    private boolean hasSeenWelcome;
    
    // Getters and setters
}

// Storing player data
PlayerWelcomeData data = new PlayerWelcomeData();
data.setLoginCount(5);
data.setLastLogin(System.currentTimeMillis());
data.setHasSeenWelcome(true);
savePlayerData(player.getUniqueId(), data);

// Loading player data
loadPlayerData(player.getUniqueId(), PlayerWelcomeData.class)
    .thenAccept(playerData -> {
        if (playerData != null) {
            int logins = playerData.getLoginCount();
            player.sendMessage("This is your " + logins + " login!");
        }
    });

Installation

1. Place your addon JAR file in the /plugins/TheRewards/addons/ directory.

2. Restart the server or use the reload command provided by TheRewards.

3. Verify that your addon loaded correctly by checking the console logs.

Best Practices

1. Clean Resource Management: Always clean up resources in the onUnload() method.

2. Configuration First: Use configuration files for customizable elements rather than hardcoding values.

3. Error Handling: Implement proper error handling to prevent addon failures from affecting the main plugin.

4. Performance Awareness: Be mindful of performance, especially for scheduled tasks and event listeners.

5. Unique Names: Ensure your addon has a unique name to avoid conflicts with other addons.

Advanced Usage: Commands with Subcommands

For more complex command structures:

private class AdvancedCommands extends CommandArg {
    public AdvancedCommands() {
        super("myaddon");
    }
    
    @Override
    public boolean execute(CommandSender sender, String[] args) {
        if (args.length < 1) {
            sender.sendMessage("Usage: /therewards myaddon <subcommand>");
            return true;
        }
        
        switch (args[0].toLowerCase()) {
            case "help":
                showHelp(sender);
                return true;
            case "stats":
                if (args.length < 2) {
                    sender.sendMessage("Usage: /therewards myaddon stats <player>");
                    return true;
                }
                showStats(sender, args[1]);
                return true;
            // Add more subcommands
        }
        
        return false;
    }
    
    // Helper methods for subcommands
    private void showHelp(CommandSender sender) {
        // Show help information
    }
    
    private void showStats(CommandSender sender, String playerName) {
        // Show player stats
    }
}