> For the complete documentation index, see [llms.txt](https://docs.marioded.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.marioded.com/api-introduction/getting-started.md).

# Setting up

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

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.

{% tabs %}
{% tab title="build.gradle.kts" %}

```kotlin
repositories {
    mavenCentral()
}

val reverseVersion = "REVERSE_VERSION"

dependencies {
    compileOnly("com.marioded.reverse:api-recorder:$reverseVersion")
}
```

{% endtab %}

{% tab title="build.gradle" %}

```groovy
repositories {
    mavenCentral()
}

def reverseVersion = 'REVERSE_VERSION'

dependencies {
    compileOnly "com.marioded.reverse:api-recorder:$reverseVersion"
}
```

{% endtab %}

{% tab title="pom.xml" %}
Maven uses Central by default. Add the dependency to your existing POM:

```xml
<dependencies>
    <dependency>
        <groupId>com.marioded.reverse</groupId>
        <artifactId>api-recorder</artifactId>
        <version>REVERSE_VERSION</version>
        <scope>provided</scope>
    </dependency>
</dependencies>
```

{% endtab %}
{% endtabs %}

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.

{% hint style="info" %}
**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.
{% endhint %}

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:

{% code title="plugin.yml — our first recording integration" %}

```yaml
name: FirstRecording
version: 1.0.0
main: example.FirstRecordingPlugin
depend: [reverse-recorder]
```

{% endcode %}

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](/api-how-to-guides/threading-and-failures.md).

## Discover the active runtime

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

```java
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.

{% content-ref url="/pages/13RGQWyfsvKyik0eYVoz" %}
[Services, recordings, and sessions](/api-introduction/concepts.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.marioded.com/api-introduction/getting-started.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.