BetterReplay

BetterReplay is a server-side replay plugin for Paper with Folia-friendly scheduling through FoliaLib. It records player and nearby entity activity on the server, stores that timeline, and replays it in-game for viewers without requiring a client replay mod.

What this project is

• Server plugin written in Java 21
• Targets modern Paper APIs
• Uses PacketEvents for packet interception and replay entity updates
• Uses FoliaLib for scheduler and teleport compatibility
• Supports file and MySQL storage backends
• Uses a short-lived replay-list cache for saved replay commands and API listing calls
• New saves use finalized binary .br archives with Zstd-compressed payloads; legacy JSON replays and older LZ4 .br archives remain readable during the migration window, but pre-v2 alpha .br inventory archives are intentionally unsupported

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
• Fits moderation, event review, and server-side tooling workflows

Typical client-side replay mod approach:

• Records from a specific client perspective
• Usually requires modded client setup
• Often focuses on free-camera or cinematic editing
• Playback is usually local to the recording client

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

Features

• Server-side recording and in-game playback with no client replay mod required
• Finalized binary .br replay archives stored in either file or MySQL backends
• Crash/restart-safe append-log recording with startup recovery of orphaned temporary saves
• Replay protection, retention cleanup, chunk-aware filtered export, and hidden admin diagnostics
• Optional chunk-aware recording and playback for block baselines around recorded players
• Playback controls with pause stepping, variable speed, and live speed feedback
• Viewer safety controls, viewer state restoration, and optional live-player vanish during playback
• Velocity replay handoff for launching playback on a dedicated backend server and returning viewers afterward
• ViaVersion proxy client-version details for correct replay player skin metadata on backend servers
• API-first integration support for other plugins
• Optional Floodgate soft dependency support

Velocity replay handoff

BetterReplay can move viewers to another Velocity backend for playback with /replay play <name> server:<backend> or a configured Velocity.Default-Replay-Server, then return them to their original server when the replay ends.

This lets a network keep replay viewing isolated on dedicated replay servers while production servers continue recording. Shared MySQL storage is recommended so the origin and replay backend can access the same saved replay list and payloads. Failed or unacknowledged handoffs report a chat error to the viewer.

Velocity plugin download: https://github.com/JustinDevB/BetterReplayVelocity/releases/tag/1.1.1

ViaVersion proxy details

When a ViaVersion proxy sends vv:proxy_details, BetterReplay uses its reported client protocol version for replay player skin metadata instead of the backend's local protocol detection. This handles networks where backend ViaVersion sees the proxy connection protocol rather than the player's actual client version. The proxy must run ViaVersion 5.7.2 or newer with send-player-details: true; absent or invalid payloads fall back to PacketEvents detection.