> ## Documentation Index
> Fetch the complete documentation index at: https://docs.marioded.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setting up

> Add Reverse to your Java plugin project and discover its active runtime service.

# Setting up

This page shows how to add the Reverse API to a **Java 21 Bukkit plugin project**. We will use the recorder for our first integration; the same discovery pattern applies to player and lobby.

## Choose your API artifact

| Your integration needs to… | Runtime plugin | Maven artifact |
| - | - | - |
| Record a match | `reverse-recorder` | `com.marioded.reverse:api-recorder` |
| Play a saved recording | `reverse-player` | `com.marioded.reverse:api-player` |
| Dispatch a viewer through a lobby | `reverse-lobby` | `com.marioded.reverse:api-lobby` |

Choose the artifact for the role your integration will run on. Your build tool resolves its shared API dependencies automatically.

## Add the dependency

Add the public API from **Maven Central**. Replace `REVERSE_VERSION` below with the published API version compatible with the Reverse release installed on your server.

> [tab] build.gradle.kts
>
> ```kotlin theme={null}
> repositories {
>     mavenCentral()
> }
>
> val reverseVersion = "REVERSE_VERSION"
>
> dependencies {
>     compileOnly("com.marioded.reverse:api-recorder:$reverseVersion")
> }
> ```

> [tab] build.gradle
>
> ```groovy theme={null}
> repositories {
>     mavenCentral()
> }
>
> def reverseVersion = 'REVERSE_VERSION'
>
> dependencies {
>     compileOnly "com.marioded.reverse:api-recorder:$reverseVersion"
> }
> ```

> [tab] pom.xml
>
> Maven uses Central by default. Add the dependency to your existing POM:
>
> ```xml theme={null}
> <dependencies>
>     <dependency>
>         <groupId>com.marioded.reverse</groupId>
>         <artifactId>api-recorder</artifactId>
>         <version>REVERSE_VERSION</version>
>         <scope>provided</scope>
>     </dependency>
> </dependencies>
> ```

Your project also needs its normal Bukkit/Spigot compile dependency. Add any public-signature libraries used by the APIs you call, such as Adventure for the relevant player SPI, as compile-only/provided dependencies too.

> [!NOTE]
>
> **Do not shade the API into your plugin.** Reverse supplies these classes at runtime. A second copy can break service lookup and event class identity.

To target player or lobby, replace `api-recorder` with the appropriate artifact from the table. Use `com.marioded.reverse:api` or `com.marioded.reverse:api-gui` only when your library specifically needs those shared contracts without a role-specific entry point.

## Declare the runtime dependency

Add the actual Bukkit plugin name to your integration's descriptor:

```yaml theme={null}
name: FirstRecording
version: 1.0.0
main: example.FirstRecordingPlugin
depend: [reverse-recorder]
```

Use `reverse-player` or `reverse-lobby` for the corresponding integration. This makes Bukkit load your plugin after the required role. A jar being present does not guarantee its runtime initialized successfully, so we will still check discovery.

If your whole plugin should work without Reverse, use an isolated optional integration and `softdepend`. An optional descriptor alone does not make eager references to absent API classes safe. See [lifecycle handling](https://docs.marioded.com/api/threading-and-failures.md).

## Discover the active runtime

In your plugin's `onEnable`, ask the recorder entry point for its provider:

```java theme={null}
ReverseRecorder recorder = ReverseRecorder.get().orElseThrow(
    () -> new IllegalStateException("Reverse recorder is not available"));
```

`ReverseRecorder.get()` returns an Optional from Bukkit's ServicesManager. If no provider was registered, the Optional is empty. Do not create a replacement implementation yourself.

For the other roles, use the same pattern with `ReversePlayer.get()` or `ReverseLobby.get()`.

## Ready to start

We now have the right compile dependency and runtime load order. Next, we will introduce the service/session objects used by the first recording example.

[Services, recordings, and sessions →](https://docs.marioded.com/api/concepts.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.