# 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:

```java
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:

```yaml
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:

```yaml
# 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:

<pre class="language-java"><code class="lang-java">// Example Player Data Class
public class PlayerWelcomeData {
    private int loginCount;
    private long lastLogin;
    private boolean hasSeenWelcome;
    
    // Getters and setters
}
<strong>
</strong>// 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!");
        }
    });
</code></pre>

### 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:

```java
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
    }
}
```