在在线模式和离线模式之间切换服务器,而不会导致任何人丢失物品。
Minecraft 通过 UUID 保存玩家数据,而玩家的 UUID 取决于服务器的模式。切换 online-mode 后,所有人都会获得一个新的 UUID。他们的旧物品栏数据仍然存在于磁盘中,但服务器不再读取该位置,因此他们会以空状态出生。
UserOverUUID 会在服务器加载数据之前,于玩家加入时将数据迁移至新的 UUID。这样玩家出生时会保留其物品栏、末影箱、经验值、位置、统计数据和进度,无需重新登录。
功能特性
- 自动执行。 在服务器读取玩家数据之前,于加入时进行迁移。
- 双向支持。 支持从在线到离线、从离线到在线,以及之后的再次切换。
- 安全默认设置。 采用复制而非移动操作,绝不会自行覆盖现有数据,并对所触及的每个文件进行备份。
- 每位玩家仅运行一次。 账本会记录已完成的迁移,因此下次登录时不会重复操作。
- 代理感知。 兼容 BungeeCord 和 Velocity 后方环境。
- 无需联网。 在线 UUID 可从
usercache.json 以及玩家数据中保存的名称中获取。Mojang API 仅作为可选的最终备选方案。
- 插件数据。 可添加任何以 UUID 命名的插件文件或文件夹,例如 Essentials 的用户数据。
- 1.19 至 26.x。 支持 Minecraft 26.1 引入的
players/ 文件夹布局。
快速上手
- 将 jar 包放入
plugins/ 目录并重启服务器。
- 更改
server.properties(或你的代理设置)中的 online-mode 并重启。
- 完成。每位玩家在第一次加入时即可找回其数据。
在安装插件前已完成切换? 在此期间加入过的玩家现在拥有基于新 UUID 的全新空白档案,插件不会自行覆盖这些数据。请使用 /uom status <player> 进行检查,并通过 /uom migrate <player> --force 找回旧数据。全新档案会先被备份。
命令
所有命令均需权限 useroveruuid.admin(默认为 op)。/uom 和 /uuidmigrate 为别名。
| 命令 |
功能说明 |
/uom status <player> |
显示两个 UUID、它们的来源以及是否有待迁移的数据 |
/uom dryrun <player> |
列出迁移将复制的所有文件,但不进行任何实际更改 |
/uom migrate <player> |
立即执行迁移。如果玩家在线,则先将其踢出 |
/uom reload |
重新加载 config.yml |
dryrun 和 migrate 支持以下选项:
--force 替换新 UUID 下已存在的数据(先进行备份)
--to-online 或 --to-offline 手动选择方向,例如用于切换前的准备
判定逻辑
| 玩家以以下身份加入 |
数据从何处复制 |
| 离线 UUID |
其在线 UUID,依次在 usercache.json、已保存的玩家数据中查找,最后尝试 Mojang API(若启用) |
| 在线 UUID |
其离线 UUID。还会检查名称的其他拼写方式(如 steve 与 Steve) |
| Bedrock (Floodgate) UUID |
无操作,Bedrock 玩家将被跳过 |
如果玩家在新 UUID 下已有数据,则予以保留,控制台会提示你如何替换它。唯一的例外是再次切换回原模式时:如果现有文件是上次迁移留下的陈旧副本,且另一侧的数据更新,则会进行替换(并备份),从而实现“在线→离线→在线”全程无损。
配置
config.yml
# 首次以其他 UUID 加入时自动迁移玩家数据。
autoMigrate: true
# COPY 会保留旧 UUID 下的文件(最安全)。MOVE 会在迁移后删除它们。
operation: COPY
# 是否替换玩家在新 UUID 下已有的数据?保持 false,改为对单个玩家使用
# /uom migrate <player> --force。
overwriteTarget: false
# 自动迁移后踢出玩家。通常不需要。
kickAfterMigrate: false
kickMessage: "&aYour player data was migrated. Please rejoin."
worlds:
autoDetect: true
additionalWorldFolders: []
lookup:
useUsercache: true
scanPlayerData: true
useMojangApi: false
mojangApiTimeoutMs: 3000
cacheTtlMinutes: 1440
paths:
includeVanillaPlayerdata: true
includeStats: true
includeAdvancements: true
# 占位符:{uuid}, {uuid_nodash}, {name}。相对于服务器根目录。
customPaths:
- "plugins/Essentials/userdata/{uuid}.yml"
备份
每次迁移都会在 plugins/UserOverUUID/backups/<date>_<player>_<uuid>/ 写入备份。其中包含迁移的文件、被替换的任何文件,以及一个 manifest.txt 清单,记录各项数据的去向。若要撤销迁移,请在玩家离线时将文件复制回去。
注意事项
- 对于插件数据,仅文件名或文件夹路径发生变化。那些将 UUID 存储在文件内部或数据库中的插件(如 LuckPerms、MySQL 经济系统)需要各自专用的迁移工具。
- 在离线模式下,任何人都可以任意名称加入,因此以 "Steve" 身份加入的人将获得 Steve 的迁移数据。如果这对你的服务器很重要,请使用认证插件。
- 兼容 Paper、Purpur、Spigot 和 Bukkit。不支持 Folia。
从 1.0.0 升级
版本 1.0.0 曾名为 UuidMigrate。请删除 UuidMigrate-1.0.0.jar 并添加新的 jar 包。你的配置文件和备份会从 plugins/UuidMigrate 自动迁移过来,同时 /uuidmigrate 命令和 uuidmigrate.admin 权限将继续有效。
支持
发现 bug,或希望支持其他插件的数据迁移?提交 Issue 或在 Discord 上提问。
Switch your server between online mode and offline mode without anyone losing their stuff.
Minecraft saves player data by UUID, and a player's UUID depends on the server's mode. Switch online-mode and everyone gets a new UUID. Their old inventory is still on disk, but the server doesn't look there, so they spawn with nothing.
UserOverUUID moves the data to the new UUID when the player joins, before the server loads it. They spawn with their inventory, ender chest, XP, position, stats and advancements, no rejoin needed.
Features
- Automatic. Migrates on join, before the server reads the player's data.
- Both directions. Online to offline, offline to online, and back again later.
- Safe defaults. Copies instead of moving, never replaces existing data on its own, and backs up every file it touches.
- Runs once per player. A ledger remembers finished migrations, so nothing repeats on the next login.
- Proxy aware. Works behind BungeeCord and Velocity.
- No internet needed. Online UUIDs are found in
usercache.json and in the names saved inside player data. The Mojang API is an optional last resort.
- Plugin data. Add any plugin file or folder that is named after a UUID, such as Essentials userdata.
- 1.19 to 26.x. Supports the
players/ folder layout that Minecraft 26.1 introduced.
Getting started
- Put the jar in
plugins/ and restart.
- Change
online-mode in server.properties (or your proxy's setting) and restart.
- Done. Each player gets their data back the first time they join.
Switched before installing the plugin? Anyone who joined in between now has a fresh, empty profile under their new UUID, and the plugin won't overwrite that on its own. Check with /uom status <player> and bring the old data back with /uom migrate <player> --force. The fresh profile is backed up first.
Commands
Every command needs useroveruuid.admin (op by default). /uom and /uuidmigrate are aliases.
| Command |
What it does |
/uom status <player> |
Shows both UUIDs, where they were found, and whether there is anything to migrate |
/uom dryrun <player> |
Lists every file a migration would copy, without changing anything |
/uom migrate <player> |
Migrates now. Kicks the player first if they are online |
/uom reload |
Reloads config.yml |
dryrun and migrate take these options:
--force replaces data that already exists under the new UUID (backed up first)
--to-online or --to-offline picks the direction yourself, for example to prepare before switching
How it decides
| Player joins with |
Data is copied from |
| An offline UUID |
Their online UUID, looked up in usercache.json, then in saved player data, then the Mojang API (if enabled) |
| An online UUID |
Their offline UUID. Other spellings of the name (steve vs Steve) are checked too |
| A Bedrock (Floodgate) UUID |
Nothing, Bedrock players are skipped |
If the player already has data under the new UUID, it is kept and the console tells you how to replace it. The one exception is switching back: when the existing file is the stale copy left behind by the last migration and the other side is newer, it gets replaced (and backed up), so going online, offline and online again loses nothing.
Configuration
config.yml
# Migrate a player's data automatically the first time they join with their other UUID.
autoMigrate: true
# COPY keeps the files under the old UUID (safest). MOVE deletes them after migrating.
operation: COPY
# Replace data a player already has under their new UUID? Leave false and use
# /uom migrate <player> --force for single players instead.
overwriteTarget: false
# Kick the player after an automatic migration. Normally not needed.
kickAfterMigrate: false
kickMessage: "&aYour player data was migrated. Please rejoin."
worlds:
autoDetect: true
additionalWorldFolders: []
lookup:
useUsercache: true
scanPlayerData: true
useMojangApi: false
mojangApiTimeoutMs: 3000
cacheTtlMinutes: 1440
paths:
includeVanillaPlayerdata: true
includeStats: true
includeAdvancements: true
# Placeholders: {uuid}, {uuid_nodash}, {name}. Relative to the server folder.
customPaths:
- "plugins/Essentials/userdata/{uuid}.yml"
Backups
Every migration writes a backup to plugins/UserOverUUID/backups/<date>_<player>_<uuid>/. It holds the migrated files, any files they replaced, and a manifest.txt listing what went where. To undo a migration, copy the files back while the player is offline.
Good to know
- For plugin data, only the file name or folder changes. Plugins that store UUIDs inside their files or in a database (LuckPerms, MySQL economies) need their own migration tools.
- In offline mode anyone can join under any name, so whoever joins as "Steve" gets Steve's migrated data. Use an authentication plugin if that matters on your server.
- Runs on Paper, Purpur, Spigot and Bukkit. Folia is not supported.
Upgrading from 1.0.0
Version 1.0.0 was called UuidMigrate. Delete UuidMigrate-1.0.0.jar and add the new jar. Your config and backups are copied over from plugins/UuidMigrate automatically, and /uuidmigrate and uuidmigrate.admin keep working.
Support
Found a bug, or want support for another plugin's data? Open an issue or ask on Discord.
评论 0
登录后参与评分
还没有评论,来抢沙发吧