推荐配套插件
为了获得最佳的重放 NPC 体验,建议安装 GlobalReplay 并与 PacketEvents 配合使用。PacketEvents 支持客户端假人重放 NPC 的 UUID/名称/皮肤还原。如果没有 PacketEvents,GlobalReplay 仍可运行,但重放 NPC 将使用盔甲架作为备用标记。
GlobalReplay

简介
GlobalReplay 是一款基于 Paper API 的 Minecraft 服务器插件,它在后台静默记录真实玩家的活动,并允许管理员在隔离的平行世界中重放历史时刻。
- 插件名称:
GlobalReplay
- 作者:
bentianjia
- 命令前缀:
/replay
- Java 版本:Java 21
- 目标服务端:Paper
1.20-1.21.11
- 所需时间格式:
yyyy-MM-dd_HH:mm
示例时间相关命令:
/replay enter overworld 2024-01-15_23:00
/replay goto 2024-01-15_23:47
功能特性
持续后台录制
GlobalReplay 会自动记录所有真实玩家,无需管理员手动启动录制会话。
- 玩家位置与朝向(采用动态采样):
- 空闲状态玩家:每 10 秒记录一帧
- 移动中玩家:每秒记录一帧
- 战斗中的玩家:每个游戏刻(tick)记录一帧
- 方块变化,包括破坏、放置和爆炸
- 玩家交互行为,包括左键攻击挥动、右键交互、进食、拾取/丢弃物品、快捷栏切换、背包点击以及容器打开/关闭操作
- 容器与背包的变化,在变化发生时以物品快照形式存储
- 玩家死亡与重生事件
- 维度转移事件,包含来源维度、目标维度以及转移前后的位置信息
- 玩家加入与退出服务器事件
- 服务器启动与停止时间戳,用于在回放中作为离线断点
自动消息语言
面向玩家的消息会尽可能使用其 Minecraft 客户端的语言。
支持的语言:
其他客户端语言将回退至英语。控制台消息统一使用英语。
LZ4 存储与自动清理
回放数据按世界或维度拆分,随后以每小时一个 .replay.lz4 分片的形式存储:
plugins/GlobalReplay/recordings/
主世界/
2024-01-15_22.replay.lz4
2024-01-15_23.replay.lz4
下界/
末地/
<自定义世界名称>/
- 回放数据首先写入内存缓冲区。
- 缓冲的数据每间隔可配置的时间,会以 LZ4 算法进行批量压缩并刷入磁盘。
- 在服务器关闭期间,剩余的缓冲数据会被强制刷盘。
- 旧的回放文件由可配置的自动清理策略进行管理。
- 每个
.replay.lz4 分片覆盖一小时(60 分钟)的回放数据。
- 当打开回放时,可能会在
plugins/GlobalReplay/temp/ 目录下写入解压缩后的缓存文件。
- 原始的
.replay.lz4 录制文件会保留;仅在退出回放后五分钟未再使用时,才会删除临时的解压缩缓存。
智能假人与 NPC 排除
GlobalReplay 旨在仅记录真实玩家。它在启动时扫描已加载的插件,并自动启用支持的排除模块。
被排除的实体和账户包括:
- 通过
NPC 元数据检测到的 Citizens2 NPC
- 通过 Shopkeepers API 标记检测到的 Shopkeepers 实体
- 通过 MythicMobs 实体标签检测到的 MythicMobs 实体
- 通过特殊实体名前缀检测到的 Carpet 假人
- 通过插件元数据检测到的 NPCLib 实体
- 拥有
globalreplay.exempt 权限的账户
- 标记为
globalreplay_npc=true 的回放 NPC
- 来自
recording.excluded-entity-names 的手动排除项
- 来自
recording.excluded-entity-uuids 的手动排除项
新生成的实体会通过 EntitySpawnEvent 进行检查,因此运行时生成的 NPC 和假实体也会被跳过。
隔离的平行世界
管理员可以进入回放会话,而不会影响实时服务器世界。
- 每位管理员都会获得一个单独的临时平行世界实例。
- 多名管理员可以同时回放相同的录制文件,且各自拥有独立的时间线。
- 解压缩和回放加载是异步进行的。
- 玩家传送和游戏状态更改会在主服务器线程上执行。
- 管理员进入平行世界时,其坐标和旋转角度与在原世界中一致,而不是被传送到世界出生点。
- 管理员的原始位置、游戏模式和物品栏会在进入时保存,并在退出时恢复。
- 进入回放世界后,播放将自动开始。
只读回放保护
平行世界在设计上是只读的。
BlockBreakEvent 会被取消。
BlockPlaceEvent 会被取消。
InventoryClickEvent 会被取消。
InventoryDragEvent 会被取消。
EntityDamageEvent 会被取消。
- 其他改变世界的行为均被阻止。
- 容器可以被打开以供检查,但其内容无法被修改。
基于 NPC 的播放
GlobalReplay 将已记录的玩家还原为回放 NPC。
- 安装 PacketEvents 后,可用于创建跨版本的假人实体。
- 保留玩家 UUID。
- 按 UUID 请求 Mojang 皮肤纹理并注入回放 NPC。
- 恢复显示名称,包括 LuckPerms 前缀、颜色及格式。
- 回放 NPC 在运行时使用独立的客户端实体 UUID,同时保持记录玩家的真实可见名称,因此实时玩家与其回放 NPC 可同时存在。
- 回放 NPC 根据记录的坐标和旋转角度逐帧移动。
- 回放 NPC 模拟记录的移动、相机旋转、左键点击、右键点击、进食、拾取/丢弃物品、手持物品变化、背包点击以及容器开合操作。
- 回放 NPC 带有
globalreplay_npc=true 标签,以便录制器忽略它们。
- 可使用旁观者模式进入 NPC 身体,以该玩家的第一人称视角进行观看。
离线断点
如果在回放时间线期间服务器处于离线状态,GlobalReplay 会显示灰色断点,并向管理员发送如下通知:
[GlobalReplay] Server was offline for X minutes
安装
- 安装 Java 21。
- 运行兼容
1.20-1.21.11 的 Paper 服务器。
- 将 PacketEvents 安装到服务器
plugins 文件夹中,以实现带有皮肤的完整假人回放 NPC。若未安装 PacketEvents,GlobalReplay 仍可启动并使用盔甲架作为备用标记。
- 将 GlobalReplay 插件 jar 文件安装到服务器
plugins 文件夹中。
- 确保服务器能够下载插件库,因为 GlobalReplay 通过
plugin.yml 声明了 org.lz4:lz4-java。
- 首次启动服务器以生成
plugins/GlobalReplay/config.yml。
- 检查配置,然后重启服务器或运行
/replay reload。
命令
所有命令的时间参数必须使用 yyyy-MM-dd_HH:mm 格式。
| 命令 |
描述 |
/replay enter <dimension> <time> [player|uuid|me] |
在当前坐标进入隔离的平行世界,并从指定时间开始回放。如果提供了目标,当回放 NPC 出现时立即传送到该记录玩家附近。使用 me/self/@s 或 UUID 以避免名称冲突。示例:/replay enter overworld 2024-01-15_23:00 me。 |
/replay pause |
暂停或恢复当前回放会话。 |
/replay speed <0.5/1/2/4> |
更改播放速度。 |
/replay goto <time> |
跳转到当前回放中的特定完整时间戳。示例:/replay goto 2024-01-15_23:47。 |
/replay focus <player|uuid|me> |
通过传送到回放 NPC 附近来跟随记录的玩家。命令目标是回放 NPC,因此即使实时玩家在线,/replay focus bentianjia 也会传送到回放 NPC;如有需要,请使用 me/self/@s 或 UUID。 |
/replay exit |
离开平行世界,销毁临时实例,并将管理员恢复到之前的状态。 |
/replay list [dimension] |
列出可用的回放文件,可按维度筛选。 |
/replay reload |
重新加载 config.yml,扫描假人排除项,并保持正在进行的录制和当前回放会话继续运行。 |
需要执行耗时操作的命令会先发送即时进度反馈,然后在异步任务完成后发送最终结果。
回放进入进度消息:
[GlobalReplay] Decompressing replay files, please wait...
[GlobalReplay] Decompression complete, loading parallel world...
[GlobalReplay] Entered parallel world <time>, <X> players loaded
配置重载结果:
[GlobalReplay] Configuration reloaded
权限
| 权限 |
描述 |
globalreplay.enter |
允许进入回放世界并使用回放会话控制。 |
globalreplay.enter.others |
在强制执行基于玩家范围的访问时,允许查看其他玩家的回放数据。 |
globalreplay.admin |
授予所有 GlobalReplay 管理权限。 |
globalreplay.exempt |
防止该账号被录制。适用于假人或自动化账号。 |
GlobalReplay 兼容 LuckPerms 权限检查。
配置
默认 config.yml 结构:
storage:
flush-interval-seconds: 30
compression: lz4
auto-delete:
enabled: true
keep-full-quality-hours: 24
keep-low-quality-days: 7
delete-after-days: 30
recording:
excluded-entity-names:
- "shopkeeper"
excluded-entity-uuids: []
prefix: "&8[&bGlobalReplay&8]&r "
配置参考:
| 键 |
描述 |
storage.flush-interval-seconds |
缓冲录制数据压缩并刷盘到磁盘的频率。 |
storage.compression |
回放文件的压缩算法。目前仅支持 lz4。 |
auto-delete.enabled |
启用或禁用自动录制清理。 |
auto-delete.keep-full-quality-hours |
在最近几小时内保持全质量录制。 |
auto-delete.keep-low-quality-days |
在接下来几天内保留低质量录制。 |
auto-delete.delete-after-days |
删除超过此天数的录制。 |
recording.excluded-entity-names |
手动排除的实体名称。匹配的实体不会被录制。 |
recording.excluded-entity-uuids |
手动排除的实体 UUID。匹配的实体不会被录制。 |
prefix |
聊天消息前缀。支持与 Minecraft 颜色代码一起使用的 &。 |
运行 /replay reload 会重新加载所有配置值,扫描假人排除模块,不会中断正在进行的录制,也不会影响已经进入回放世界内的管理员。
作者
GlobalReplay 由 bentianjia 开发。
许可证
GlobalReplay 采用 MIT 许可证授权。只要保留标识 bentianjia 为作者的版权声明,您即可使用、修改和分发本软件。
Recommended Companion Plugin
For the best replay NPC experience, it is recommended to install GlobalReplay together with PacketEvents. PacketEvents enables client-side fake-player replay NPCs with UUID/name/skin restoration. Without PacketEvents, GlobalReplay still runs, but replay NPCs use ArmorStand fallback markers.
GlobalReplay

Introduction
GlobalReplay is a Paper API Minecraft server plugin that silently records real player activity in the background and lets administrators replay historical moments inside isolated parallel worlds.
- Plugin name:
GlobalReplay
- Author:
bentianjia
- Command prefix:
/replay
- Java version: Java 21
- Target server: Paper
1.20-1.21.11
- Required time format:
yyyy-MM-dd_HH:mm
Example time-based commands:
/replay enter overworld 2024-01-15_23:00
/replay goto 2024-01-15_23:47
Features
Continuous Background Recording
GlobalReplay continuously records all real players without requiring administrators to start a manual session.
- Player position and rotation with dynamic sampling:
- Idle players: one frame every 10 seconds
- Moving players: one frame every second
- Players in combat: one frame every tick
- Block changes, including breaking, placing, and explosions
- Player interaction actions, including left-click swings, right-click interactions, food consumption, item pickup/drop, hotbar switching, inventory clicks, and container open/close actions
- Container and inventory changes, stored as item snapshots when changes happen
- Player death and respawn events
- Dimension transfer events, including source dimension, target dimension, and before/after locations
- Player join and quit events
- Server start and stop timestamps, used as offline breakpoints during replay
Automatic Message Language
Player-facing messages follow the player's Minecraft client language when possible.
Supported languages:
- Arabic
- Chinese
- English
- French
- Russian
- Spanish
Other client languages fall back to English. Console messages use English.
LZ4 Storage and Automatic Cleanup
Replay data is split by world or dimension, then stored as hourly .replay.lz4 shards:
plugins/GlobalReplay/recordings/
overworld/
2024-01-15_22.replay.lz4
2024-01-15_23.replay.lz4
nether/
the_end/
<custom-world-name>/
- Replay data is written to an in-memory buffer first.
- Buffered data is batch-compressed with LZ4 and flushed to disk every configurable interval.
- Remaining buffered data is force-flushed during server shutdown.
- Old recordings are managed by a configurable automatic cleanup policy.
- Each
.replay.lz4 shard covers one hour, or 60 minutes, of replay data.
- When a replay is opened, decompressed cache files may be written under
plugins/GlobalReplay/temp/.
- The original
.replay.lz4 recording file is kept; only the temporary decompressed cache is deleted after it has been unused for 5 minutes after replay exit.
Smart Fake Player and NPC Exclusion
GlobalReplay is designed to record real players only. It scans loaded plugins on startup and enables supported exclusion modules automatically.
Excluded entities and accounts include:
- Citizens2 NPCs detected by
NPC metadata
- Shopkeepers entities detected through Shopkeepers API markers
- MythicMobs entities detected by MythicMobs entity tags
- Carpet fake players detected by special entity name prefixes
- NPCLib entities detected by plugin metadata
- Accounts with the
globalreplay.exempt permission
- Replay NPCs marked with
globalreplay_npc=true
- Manual exclusions from
recording.excluded-entity-names
- Manual exclusions from
recording.excluded-entity-uuids
Newly spawned entities are checked through EntitySpawnEvent so runtime-generated NPCs and fake entities are skipped as well.
Isolated Parallel Worlds
Administrators can enter replay sessions without affecting the live server world.
- Each administrator receives a separate temporary parallel world instance.
- Multiple administrators can replay the same recording at the same time with independent timelines.
- Decompression and replay loading run asynchronously.
- Player teleportation and game-state changes are performed back on the main server thread.
- The administrator enters the parallel world at the same coordinates and rotation they had in the original world instead of being sent to world spawn.
- The administrator's original location, game mode, and inventory are saved on entry and restored on exit.
- Playback starts automatically after entering the replay world.
Read-Only Replay Protection
Parallel worlds are read-only by design.
BlockBreakEvent is cancelled.
BlockPlaceEvent is cancelled.
InventoryClickEvent is cancelled.
InventoryDragEvent is cancelled.
EntityDamageEvent is cancelled.
- Other world-changing actions are blocked.
- Containers may be opened for inspection, but their contents cannot be modified.
NPC-Based Playback
GlobalReplay restores recorded players as replay NPCs.
- PacketEvents is used to create cross-version fake player entities when installed.
- Player UUIDs are preserved.
- Mojang skin textures are requested by UUID and injected into replay NPCs.
- Display names are restored, including LuckPerms prefixes, colors, and formatting.
- Replay NPCs keep the recorded player's real visible name while using a separate client-side entity UUID, so a live player and their replay NPC can exist at the same time.
- Replay NPCs move frame by frame using recorded coordinates and rotation.
- Replay NPCs mimic recorded movement, camera rotation, left-clicks, right-clicks, eating, item pickup/drop, held-item changes, inventory clicks, and container open/close actions.
- Replay NPCs are tagged with
globalreplay_npc=true so the recorder ignores them.
- Spectator mode can be used to enter an NPC body and watch from that player's first-person perspective.
Offline Breakpoints
When the server was offline during a replay timeline, GlobalReplay shows a gray breakpoint and notifies the administrator with a message such as:
[GlobalReplay] Server was offline for X minutes
Installation
- Install Java 21.
- Run a Paper server compatible with
1.20-1.21.11.
- Install PacketEvents into the server
plugins folder for full fake-player replay NPCs with skins. Without PacketEvents, GlobalReplay still starts and uses ArmorStand fallback markers.
- Install the GlobalReplay plugin jar into the server
plugins folder.
- Make sure the server can download plugin libraries, because GlobalReplay declares
org.lz4:lz4-java through plugin.yml.
- Start the server once to generate
plugins/GlobalReplay/config.yml.
- Review the configuration, then restart the server or run
/replay reload.
Commands
All command time arguments must use yyyy-MM-dd_HH:mm.
| Command |
Description |
/replay enter <dimension> <time> [player|uuid|me] |
Enter an isolated parallel world at your current coordinates and start replaying from the specified time. If a target is provided, teleport near that recorded player as soon as their replay NPC appears. Use me/self/@s or a UUID to avoid name conflicts. Example: /replay enter overworld 2024-01-15_23:00 me. |
/replay pause |
Pause or resume the current replay session. |
/replay speed <0.5/1/2/4> |
Change playback speed. |
/replay goto <time> |
Jump to a specific full timestamp in the current replay. Example: /replay goto 2024-01-15_23:47. |
/replay focus <player|uuid|me> |
Follow a recorded player by teleporting near their replay NPC. Names target replay NPCs, so /replay focus bentianjia teleports to the replay NPC even if the live player is online; use me/self/@s or a UUID when needed. |
/replay exit |
Leave the parallel world, destroy the temporary instance, and restore the administrator's previous state. |
/replay list [dimension] |
List available replay files, optionally filtered by dimension. |
/replay reload |
Reload config.yml, rescan fake-player exclusions, and keep active recording and current replay sessions running. |
Commands that require expensive work send immediate progress feedback first, then send the final result after the asynchronous task completes.
Replay entry progress messages:
[GlobalReplay] Decompressing replay files, please wait...
[GlobalReplay] Decompression complete, loading parallel world...
[GlobalReplay] Entered parallel world <time>, <X> players loaded
Configuration reload result:
[GlobalReplay] Configuration reloaded
Permissions
| Permission |
Description |
globalreplay.enter |
Allows entering replay worlds and using replay session controls. |
globalreplay.enter.others |
Allows viewing replay data for other players when player-scoped access is enforced. |
globalreplay.admin |
Grants all GlobalReplay administrative permissions. |
globalreplay.exempt |
Prevents the account from being recorded. Intended for fake-player or automation accounts. |
GlobalReplay is compatible with LuckPerms permission checks.
Configuration
Default config.yml structure:
storage:
flush-interval-seconds: 30
compression: lz4
auto-delete:
enabled: true
keep-full-quality-hours: 24
keep-low-quality-days: 7
delete-after-days: 30
recording:
excluded-entity-names:
- "shopkeeper"
excluded-entity-uuids: []
prefix: "&8[&bGlobalReplay&8]&r "
Configuration reference:
| Key |
Description |
storage.flush-interval-seconds |
How often buffered recording data is compressed and flushed to disk. |
storage.compression |
Compression algorithm for replay files. Currently only lz4 is supported. |
auto-delete.enabled |
Enables or disables automatic recording cleanup. |
auto-delete.keep-full-quality-hours |
Keeps recent recordings at full quality for this many hours. |
auto-delete.keep-low-quality-days |
Keeps lower-quality retained recordings for this many days. |
auto-delete.delete-after-days |
Deletes recordings older than this many days. |
recording.excluded-entity-names |
Manually excluded entity names. Matching entities are not recorded. |
recording.excluded-entity-uuids |
Manually excluded entity UUIDs. Matching entities are not recorded. |
prefix |
Chat message prefix. Supports Minecraft color codes with &. |
Running /replay reload reloads all configuration values, rescans fake-player exclusion modules, does not interrupt active recording, and does not affect administrators already inside replay worlds.
Author
GlobalReplay is authored by bentianjia.
License
GlobalReplay is licensed under the MIT License. You may use, modify, and distribute it as long as the copyright notice identifying bentianjia as the author is retained.
评论 0
登录后参与评分
还没有评论,来抢沙发吧