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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.xshyo.us/free-plugins/therewards/addons.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.