> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://aetherskywarswiki.netlify.app/api/mcp` to find what you need.

# Developer API

AetherSkyWars ships a separate API module addons can compile against.

<img src="/api-shape.svg" alt="An addon compiles against the API module, which ships inside the plugin jar" />

This page is for plugin developers. If you are running a server, you do not need it.

## Adding the dependency

The API is published to GitHub Packages as `cc.arrowtan.aetherskywars:aetherskywars-api`.

```xml
<dependency>
    <groupId>cc.arrowtan.aetherskywars</groupId>
    <artifactId>aetherskywars-api</artifactId>
    <version><!-- the version you are building against --></version>
    <scope>provided</scope>
</dependency>
```

Use `provided`. The API classes ship inside the AetherSkyWars jar already, so bundling them
into yours causes two copies on the classpath.

Then soft-depend on it in your `plugin.yml`:

```yaml
softdepend: [AetherSkyWars]
```

Use `depend` instead if your plugin is useless without it.

:::note
GitHub Packages needs authentication even for public packages. Add a server entry with a
token to your Maven `settings.xml`.
:::

## Getting the API

Everything goes through one entry point.

```java
import cc.arrowtan.aetherskywars.api.AetherSkyWarsAPI;

AetherSkyWarsAPI api = AetherSkyWarsAPI.getInstance();
```

:::info
The instance is set while AetherSkyWars enables. Calling `getInstance()` from your own
`onEnable` can return `null` if your plugin loads first. Fetch it lazily, when you actually
need it, or on the first server tick.
:::

## Managers

The API is split into managers, one per area.

| Manager | What it covers |
| --- | --- |
| `getMapManagerAPI()` | Arenas: look them up, list them by mode, find the next available one. |
| `getPlayerManagerAPI()` | Players: state, current match, how many are playing. |
| `getDatabaseManagerAPI()` | Stored stats and match history. |
| `getLeaderboardManagerAPI()` | The eight leaderboards and their entries. |
| `getAchievementsManagerAPI()` | Achievement definitions and progress. |
| `getKitManagerAPI()` | Kits. |
| `getShopManagerAPI()` | Shop entries. |
| `getPartiesManagerAPI()` | Parties. |
| `getLobbyManagerAPI()` | The server lobby. |
| `getWorldManagerAPI()` | Arena worlds: create, copy, reset, delete. |
| `getLanguageManagerAPI()` | Languages and the message prefix. |
| `getHologramManagerAPI()` | The hologram backend in use. |
| `getCurrencyAdapterAPI()` | Coins, or Vault, whichever is active. |

```java [How many players are in Solo matches]
import cc.arrowtan.aetherskywars.api.managers.MapManagerAPI;

int solo = api.getPlayerManagerAPI()
              .getPlayingPlayers(MapManagerAPI.MapGamemodes.SOLO);
```

```java [Read a player's stats]
import cc.arrowtan.aetherskywars.api.player.ASWPlayer;

ASWPlayer asw = api.getPlayerManagerAPI().getPlayer(bukkitPlayer);
if (asw != null && asw.isInMatch()) {
    asw.getMatch().removePlayer(asw);
}
```

## Events

Bukkit events are fired for state changes, so you can react without polling.

| Event | Fired when |
| --- | --- |
| `ASWRoomStateChangeEvent` | An arena moves between states, for example `WAITING` to `PLAYING`. |

```java
import cc.arrowtan.aetherskywars.api.events.ASWRoomStateChangeEvent;

@EventHandler
public void onStateChange(ASWRoomStateChangeEvent event) {
    // event.getRoom() is the arena that changed
}
```

See [Arenas and modes](/features/arenas-and-modes) for what each state means.

## Useful types

| Type | What it is |
| --- | --- |
| `ASWMap` | An arena. State, mode, players, cages, chests, settings, events. |
| `ASWPlayer` | A player in the plugin's terms. Wraps the Bukkit player and adds match state. |
| `ASWTeam` | A team inside a Teams arena. |
| `ASWKit` | A kit definition. |
| `ASWChest` | A tagged chest, with its tier and type. |
| `ASWMapEvent` | A timed game event on an arena. |
| `ASWLeaderboard` | One leaderboard and its ordered entries. |

## Utilities worth knowing

| Class | Use |
| --- | --- |
| `Text` | `Text.color(String)` runs a string through the same colour engine the plugin uses, so your addon's messages support the same hex, gradient, and rainbow syntax. See [Colors](/configuration/colors). |
| `ItemStackSpringer` | Serialises an `ItemStack` to and from the config format used across the plugin's YAML files. See [Items and slots](/configuration/items-and-slots). |
| `ParticleUtils` | Resolves particle names, including the pre-1.20.5 ones, and spawns particles that need a data object. |

## Version notes

The API targets Java 21 and Minecraft 1.21.11, the same as the plugin. Methods that take or
return Bukkit types follow current Bukkit API, so registry lookups replace the old static
constants for enchantments and potions.

Questions about the API, or want something exposed that is not? Ask on
[Discord](https://discord.arrowtan.cc).

## Related pages

* [Placeholders](/reference/placeholders), if you only need to read values
* [Commands](/reference/commands)