在线UUID修复

在线UUID修复

此模组在登录时拦截UUID分配,并从Mojang API获取真实UUID,对于离线账户或API无法访问时回退到原版离线UUID。

管理

Online UUID Fix

Modrinth

警告: 在安装此模组或进行任何 UUID 迁移之前,请务必备份你的整个世界文件夹。UUID 变更会影响玩家数据、进度、统计数据和宠物归属。没有自动回滚功能。

注意: 此模组的代码是在 AI(Anthropic 的 Claude)的协助下生成的。使用风险自负,在生产服务器上部署前请审查代码。

一个面向离线模式服务器的 Fabric 服务端模组,为玩家分配其真实的 Mojang/Microsoft UUID,而非原版的离线 UUID。

当服务器以离线模式(online-mode=false)运行时,Minecraft 会使用本地哈希根据玩家用户名生成 UUID。这意味着同一玩家获得的 UUID 会与在线模式服务器上的不同,从而破坏与在线服务器玩家数据的兼容性,并在玩家更换用户名时引发问题。

此模组在登录时拦截 UUID 分配,从 Mojang API 获取真实 UUID,对于非 Mojang 账户或 API 无法访问的情况,则回退到原版离线 UUID。


环境要求

  • Minecraft 1.21.11
  • Fabric Loader 0.18.2+
  • 仅服务端 —— 无需安装在客户端

安装

  1. 从发布页面下载 modid-1.0.0.jar,或自行构建(见下文)
  2. 将其放入服务器的 mods/ 文件夹
  3. 启动服务器 —— 无需任何配置

模组会在玩家首次登录时记录解析出的 UUID:

[OnlineUuidFix] Resolved Steve -> xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

UUID 查询结果会缓存到 config/online-uuid-fix/uuid-cache.json,这样每个用户名只会调用一次 Mojang API。


从源码构建

要求:JDK 21(Eclipse Adoptium —— 安装 JDK,而非 JRE)

# Windows — 如果你同时安装了 JDK 和 JRE,请设置 JDK
$env:JAVA_HOME = "C:\Program Files\Eclipse Adoptium\jdk-21.0.10.7-hotspot"

./gradlew build

输出的 jar:build/libs/modid-1.0.0.jar


将现有服务器迁移到在线 UUID

如果你的服务器已经以离线 UUID 存储了玩家数据,你需要将这些文件重命名为正确的在线 UUID,否则玩家将从零开始。

玩家数据存储在:

world/playerdata/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.dat
world/advancements/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.json
world/stats/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.json

分步迁移

1. 找到每个玩家的离线 UUID(当前文件名)

文件名即服务器分配的 UUID。列出 world/playerdata/ 以查看所有文件。

2. 找到玩家的真实在线 UUID

在 namemc.com 查询,或直接使用 Mojang API:

https://api.mojang.com/users/profiles/minecraft/<username>

响应中的 id 字段即为不带连字符的 UUID —— 按 8-4-4-4-12 的模式插入连字符。

你也可以使用以下计算器:

https://minecraft.wiki/w/Calculators/Player_UUID

3. 重命名文件

在服务器停止的情况下,重命名每个文件:

world/playerdata/<offline-uuid>.dat  →  world/playerdata/<online-uuid>.dat
world/advancements/<offline-uuid>.json  →  world/advancements/<online-uuid>.json
world/stats/<offline-uuid>.json  →  world/stats/<online-uuid>.json

4. 安装此模组后启动服务器

新的登录将获得在线 UUID,与重命名后的文件相匹配。


迁移未涵盖的内容

宠物与已驯服的动物

宠物归属以主人的 UUID 存储在宠物的 NBT 数据中。重命名玩家文件后,宠物仍会引用旧的离线 UUID,不会将玩家识别为主人。

有两种修复方法:

方案 A —— 游戏内命令(服务器需运行中)

站在宠物旁边并运行:

/execute as @e[type=wolf,distance=..10] run data modify entity @s Owner set from entity @p UUID

这会将 10 格范围内所有狼的归属重新分配给最近的玩家。将 wolf 替换为其他宠物类型(如 cat、parrot、horse),并按需调整距离。

方案 B —— NBTExplorer(服务器需离线)

使用 NBTExplorer 直接编辑世界 NBT 数据:

  • 在区域文件中搜索旧的离线 UUID 字符串
  • 将每一处替换为新的在线 UUID

进度

进度存储在单独的 .json 文件中(不在 .dat 内)。这些文件同样需要重命名 —— 见上文第 3 步。

其他玩家的物品栏

如果你需要将一名玩家的物品栏复制给另一名玩家(例如合并账户):

  1. 备份两个 .dat 文件
  2. 将源玩家的 .dat 复制并重命名为目标玩家的 UUID
  3. 目标玩家随后将拥有源玩家的物品栏、经验和位置

这不会转移宠物归属 —— 见上文说明。


工作原理

此模组通过 Mixin 注入到 net.minecraft.core.UUIDUtil.createOfflinePlayerUUID。每当服务器要从用户名生成离线 UUID 时,模组会先查询 Mojang API(api.mojang.com/users/profiles/minecraft/<name>)。如果返回结果,则使用该 UUID。如果 API 返回 404(无 Mojang 账户)或无法访问,则回退使用原版离线 UUID。