> For the complete documentation index, see [llms.txt](https://docs.xshyo.us/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xshyo.us/free-plugins/therewards/addons.md).

# 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.