Creating your first recording

Let’s record a match from our own plugin. We will use the recorder runtime and build a small FirstRecordingPlugin that starts capture, stops it, and logs the save result. Complete Setting up first. All start/stop calls in this tutorial run on the Bukkit main thread.

Get the recorder

Start by discovering the active runtime in onEnable:

private ReverseRecorder recorder;
private RecordSession activeSession;

@Override
public void onEnable() {
    recorder = ReverseRecorder.get().orElseThrow(
        () -> new IllegalStateException("Reverse recorder is not available"));
}

recorder is the service entry point. activeSession will hold the recording started by this example. This simple version intentionally manages one active match at a time.

Start the match recording

Add a method your game’s match-start handler can call:

public UUID startMatch(World world, UUID ownerId) {
    if (activeSession != null) {
        throw new IllegalStateException("This integration already has an active recording");
    }
    activeSession = recorder.getRecorderService().startRecording(
        world, List.of(ownerId), new ReplayText("Arena final", "First integration"));
    return activeSession.getUniqueId();
}

Let’s break down the call:

world is the live Bukkit world to record.
List.of(ownerId) gives that player catalog access to the finished replay.
ReplayText sets the name and description shown to users.
The returned session ID identifies this recording, not the Bukkit world.

When start succeeds, Reverse has prepared the initial scene and registered the session. If setup fails, the call throws instead of returning a half-started recording.

Stop capture and wait for saving

At match end, stop the same session:

UUID sessionId = activeSession.getUniqueId();
CompletionStage<StopResult> saving = recorder.getRecorderService().stopSession(sessionId);
activeSession = null;

Capture has now stopped, but the save may still be running. Clearing our reference allows another match to start while that I/O finishes. It does not cancel persistence. Use the stage to decide when the replay is ready:

saving.whenComplete((result, failure) -> {
    if (failure != null) {
        getLogger().log(Level.SEVERE, "Could not save recording " + sessionId, failure);
    } else if (result.replayId() == null) {
        getLogger().warning("Recording was already stopped: " + sessionId);
    } else if (result.degraded()) {
        getLogger().log(Level.WARNING, "Terrain unavailable for replay " + result.replayId(),
            result.terrainFailure());
    } else {
        getLogger().info("Replay ready: " + result.replayId());
    }
});

There are four outcomes here: save failure, an already stopped session, saved events with failed terrain, or a usable saved replay. We only log a normal “ready” result in the last case.

The completion callback has no main-thread guarantee. Logging is fine here; schedule Bukkit player messages and world operations back to the main thread. See Threading and failure handling.

Connect it to your game

Declare the recorder dependency:

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

Call startMatch(world, ownerId) from your main-thread match-start handler and stopMatch() from the match-end or cancellation handler. These are integration methods, not automatically registered commands. The example’s onDisable also requests stop for any recording it still owns. After a successful save, keep the replay UUID with your match. On a player server connected to the same replay and terrain storage, an authorized owner/admin can use /reverseplayer play <replay-id> to check the result. The recorder runtime alone does not provide playback.

What we have built

We can now discover Reverse, start a recording, stop the exact session we created, and distinguish all persistence outcomes. Next, let’s limit capture to an arena and choose the recorded players. Improve your recording →

Get Started

Everyday Use

Configure & Customize

Keep Things Running

API - Start Here

API - How-to Guides

API - Advanced Integrations

Reference

Creating your first recording

Creating your first recording

Get the recorder

Start the match recording

Stop capture and wait for saving

Connect it to your game

What we have built

​Creating your first recording

​Get the recorder

​Start the match recording

​Stop capture and wait for saving

​Connect it to your game

​What we have built

Creating your first recording

Get the recorder

Start the match recording

Stop capture and wait for saving

Connect it to your game

What we have built