BetterReplay

BetterReplay is a server-side replay plugin for Paper and Folia-style scheduling. It records player and nearby entity activity on the server, saves the timeline, and replays it for viewers in-game.

What this project is

• Server plugin written in Java
• Targets modern Paper APIs
• Uses PacketEvents and FoliaLib for packet handling and scheduling
• Supports two storage backends:
  • local JSON files
  • MySQL

How this differs from client-side replay mods

BetterReplay is not a client recording mod.

Server-side approach (this project):

• Runs entirely on the server
• No replay mod required on player clients
• Captures server-observed gameplay state and events
• Plays back by spawning and updating replay entities for a viewer
• Good for moderation, event review, and server-side tooling

Typical client-side replay mod approach:

• Records from a specific client perspective
• Usually requires modded client setup
• Often includes advanced free-camera/cinematic editing features
• Playback is usually local to the client recording

In short: BetterReplay focuses on server-managed replay workflows and API-driven integration.

Features

• Start and stop recordings
• Save recordings to file or MySQL
• List and delete stored replays
• Replay sessions for viewers
• API-first integration support for other plugins
• Optional Floodgate soft dependency support

Base command:

• /replay

Subcommands:

• start
• stop
• play
• list
• delete

Permissions:

• replay.start
• replay.stop
• replay.play
• replay.list
• replay.delete
• replay.*

Storage-Type options

Valid values for General.Storage-Type are:

• file
  • Stores replay data as JSON files under the plugin data folder.
• mysql
  • Stores replay data in a MySQL table (replays) using the configured General.MySQL.* values.

These values should be lowercase as shown above.

File storage example

General:
  Check-Update: true
  Storage-Type: file

MySQL storage example

General:
  Check-Update: true
  Storage-Type: mysql
  MySQL:
    host: 127.0.0.1
    port: 3306
    database: betterreplay
    user: replay_user
    password: change-me

Additional key used by command pagination:

list-page-size: 10

Notes:

• If Storage-Type is invalid, plugin falls back to file storage.
• MySQL replay names are stored in a VARCHAR(64) primary key column.

API

BetterReplay provides a public API for other plugins to start/stop recordings, manage replays, and listen for lifecycle events.

Quick example:

ReplayManager manager = ReplayAPI.get();
manager.startRecording("demo-session", List.of(player), 120);
manager.stopRecording("demo-session", true);
manager.startReplay("demo-session", viewerPlayer);