# 🌐 API

## API

Build your own extensions for Phoenix Lobby 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.phoenixlobby</groupId>
    <artifactId>api</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>
```

## Getting started

Add PhoenixLobby to your **plugin.yml** so your plugin loads after it.

```yaml
depend: [PhoenixLobby]
```

Use `softdepend` instead if your plugin should still work when PhoenixLobby is not installed. In that case check `PhoenixLobbyAPI.isAvailable()` before calling anything.

## The API class

`PhoenixLobbyAPI` answers questions about the lobby without going through placeholders.

```java
if (!PhoenixLobbyAPI.isAvailable()) {
    return;
}

PhoenixLobbyAPI api = PhoenixLobbyAPI.get();
```

| Method                                     | Returns                                                    |
| ------------------------------------------ | ---------------------------------------------------------- |
| `getVersion()`                             | The version of PhoenixLobby that is running                |
| `getNpcTypes()`                            | Every NPC configured on this server                        |
| `getNpcType(String identifier)`            | One NPC by its identifier, as an `Optional`                |
| `isLobbyWorld(String worldName)`           | Whether the plugin treats that world as a lobby            |
| `isInPvpMode(Player player)`               | Whether the player is in [PvP mode](../modules/lobby-pvp.md) |
| `getPlayingParkour(Player player)`         | The parkour the player is running, as an `Optional`        |
| `getParkourHighScore(Player, String)`      | That player's best score on a parkour                      |

```java
PhoenixLobbyAPI.get().getPlayingParkour(player).ifPresent(parkour -> {
    player.sendMessage("You are running " + parkour + ".");
});
```

An `NpcType` gives you `isEnabled()`, `getIdentifier()`, `getDisplayName()` and `getEngineData()`, which in turn reports the [engine](../featues/npcs/npc-engines/) that NPC is drawn with.

> **Warning:**
`PhoenixLobbyAPI.get()` throws if the plugin has not finished loading. Call it from inside your own `onEnable` or later, never from a static initialiser, and guard it with `isAvailable()` when PhoenixLobby is only a soft dependency.

## Everything else

Anything not documented here is internal and can change between versions. For values rather than behaviour, the [placeholders](../plugin-information/placeholders.md) are the stable route and cover far more of the plugin than the API does.

## Events

Four events are fired, and all of them are ordinary Bukkit events, so a normal listener picks them up. They live in `com.phoenixplugins.phoenixlobby.api.events`.

| Event                     | Fired when                                       |
| ------------------------- | ------------------------------------------------ |
| `PlayerDoubleJumpEvent`   | A player uses the [double jump](../modules/double-jump.md) |
| `PlayerParkourStartEvent` | A player starts a [parkour](../modules/parkour/) run |
| `PlayerParkourJumpEvent`  | A player lands on the next parkour block         |
| `PlayerParkourEndEvent`   | A parkour run ends                               |

### What each one carries

| Event                     | Available on the event                                       | Cancellable |
| ------------------------- | ------------------------------------------------------------ | ----------- |
| `PlayerDoubleJumpEvent`   | `getPlayer()`                                                | Yes         |
| `PlayerParkourStartEvent` | `getPlayer()`, `getParkourIdentifier()`                      | Yes         |
| `PlayerParkourJumpEvent`  | `getPlayer()`, `getParkourIdentifier()`, `getScore()`        | No          |
| `PlayerParkourEndEvent`   | `getPlayer()`, `getParkourIdentifier()`, `getScore()`, `getElapsedSeconds()`, `isNewRecord()` | No |

Cancelling `PlayerDoubleJumpEvent` stops the launch, and cancelling `PlayerParkourStartEvent` stops the run before it begins — which is how another plugin blocks either one in its own regions or during its own events.

```java
@EventHandler
public void onDoubleJump(PlayerDoubleJumpEvent event) {
    if (isInMyArena(event.getPlayer())) {
        event.setCancelled(true);
    }
}
```

```java
public class ParkourListener implements Listener {

    @EventHandler
    public void onParkourEnd(PlayerParkourEndEvent event) {
        if (!event.isNewRecord()) {
            return;
        }

        Bukkit.broadcastMessage(event.getPlayer().getName()
                + " set a new record on " + event.getParkourIdentifier()
                + " with " + event.getScore() + " points.");
    }
}
```

> **Info:**
The parkour identifier is the one you gave the parkour in the editor, the same string the [parkour placeholders](../modules/parkour/README.md#placeholders) take.

Setting your listener up, and the rest of what the plugin exposes, is covered above.

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