# 🌐 API

> **Danger:**
The API is only available for the premium version of the plugin.

Build your own extensions for Phoenix Duels with our public API.

## Maven Repository

```xml
<repositories>
    <repository>
        <id>phoenixplugins</id>
        <url>https://repo.phoenixplugins.com/</url>
    </repository>
</repositories>
```

## Dependency

```xml
<dependency>
    <groupId>com.phoenixplugins.phoenixduels</groupId>
    <artifactId>api</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>
```

## Advanced Access (Internal Classes)

Our public API covers the recommended integration points for addons.
If you need deeper access to internal classes and systems, we recommend using a direct `systemPath` dependency to your local Phoenix Duels plugin JAR.

```xml
<dependency>
    <groupId>com.phoenixplugins.phoenixduels</groupId>
    <artifactId>internal</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/libs/PhoenixDuels-1.0.0-SNAPSHOT.jar</systemPath>
</dependency>
```

Place the plugin JAR in your project's `libs` folder before building.

By using internal access through `systemPath`, you can work with plugin registries that are not part of the public API, such as:

* `MenuRegistry`: register custom menus and menu configurations.
* `CommandsRegistry`: register custom commands.
* `RuleRegistry`: register custom gamemode rules.
* `LoadoutRegistry`: register custom loadout types.
* `EditorRegistry`: register custom editor sections.

> **Warning:**
Internal classes can change between versions without API compatibility guarantees.
When possible, prefer public API integrations first.

## Custom Addons

Custom Addons are extensions that allow you to extend, modify, or enhance Phoenix Duels behavior with your own Java code.

### Before You Start

1. Add the API [dependency](#dependency).
2. Create your addon project (Maven or Gradle).
3. Make sure your final artifact is a shaded or standalone JAR when needed.

### addon.yml

Create an `addon.yml` file in your project resources folder.

```yaml
name: AddonName
main: your.path.AddonExample
author: [YourName]
version: 1.0.0
description: Small description (optional)
website: https://your-website.com (optional)
```

Required fields:

* `name`: Display name of your addon.
* `main`: Fully qualified path to your addon main class.
* `author`: One or more addon authors.
* `version`: Addon version.

### Main Class Example

The `main` value in `addon.yml` must point to your class that extends `Addon`.

```java
package your.path;

import com.phoenixplugins.phoenixduels.api.sdk.plugin.addons.Addon;

public class AddonExample extends Addon {

    @Override
    public void init() {
        // Register rules, menus, modules, or listeners.
    }

    @Override
    public void load() {
        // Runtime registrations and startup logic.
    }

    @Override
    public void unload() {
        // Cleanup logic.
    }

    @Override
    public void reload() {
        // Optional runtime reload logic.
    }

    @Override
    public String getRequiredPluginVersion() {
        return "1.0.0";
    }
}
```

### Build and Install

1. Build your addon JAR with your normal project build command.
2. Move the compiled JAR into `plugins/PhoenixDuels/addons`.
3. Restart the server.
4. Check console logs to confirm the addon was loaded successfully.

### Next Step

Continue with [🧪 Examples](examples.md) for practical event and profile integrations.

Source: https://www.phoenixplugins.com/docs/phoenix-duels/api