# 🌐 API

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

Build your own extensions for Phoenix Crates with our public API. [Events](events.md) and [Examples](examples.md) have their own pages.

## Maven Repository

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

## Dependency

```xml
<dependency>
	<groupId>com.phoenixplugins.phoenixcrates</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 Crates plugin JAR.

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

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

## JavaDocs

* [Open Phoenix Crates JavaDocs](https://www.phoenixplugins.com/javadocs/phoenix-crates)

## Custom Addons

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

### Before You Start

1. Add the [Maven Repository](#maven-repository) and the [Dependency](#dependency) above.
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's 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.phoenixcrates.api.sdk.plugin.addons.Addon;

public class AddonExample extends Addon {

	@Override
	public void onLoad() {
		// Called when the addon is loaded.
	}

	@Override
	public void onEnable() {
		// Register listeners, commands, tasks, etc.
	}

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

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

### Build and Install

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

## Custom Animations

Create your own opening phase animations and register them at runtime through the API.

### 1. Create Your Phase Class

Extend `OpeningPhaseAnimation` and implement the lifecycle methods:

```java
public class YourPhaseAnimation extends OpeningPhaseAnimation<EmptyOpeningPhaseData> {

    public YourPhaseAnimation(OpeningCrateAnimation animation, OpeningPhaseType type,
            EmptyOpeningPhaseData data) {
        super(animation, type, data);
    }

    @Override
    public void load() {
    }

    @Override
    public void tick() {
    }

    @Override
    public void unload() {
    }

}
```

### 2. Register on Enable

Register your phase during addon startup and unregister it on shutdown:

```java
public void onEnable() {
        registerPhase(
                new OpeningPhaseType(PhaseType.FIRST, "YOUR_PHASE_IDENTIFIER",
                "Your Display Name",
                XMaterial.STONE, ServerVersion.v1_16_R1,
                            new XMaterial[] {}, EmptyOpeningPhaseData.class,
                            (animation, type, data) -> new YourPhaseAnimation(animation,
                                    type, (EmptyOpeningPhaseData) data),
                            () -> new EmptyOpeningPhaseData()));
}

public void onDisable() {
        for (final OpeningPhaseType type : this.registeredPhases) {
            OpeningPhaseType.unregisterPhase(type);
        }
}

private void registerPhase(OpeningPhaseType phase) {
        // Registering first phase animations
        OpeningPhaseType.registerPhase(phase);

        // Caching to unload later on
        this.registeredPhases.add(phase);
}
```

### Good Practices

* Use unique identifiers for each custom phase.
* Keep heavy logic out of `tick()` when possible.
* Always unregister phases in `onDisable()`.
* Test phases on the same Minecraft version as production.

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