TrueUUID

一个适用于 Forge 1.20.1 的离线服登录期正版校验 Mod，客户端本地调用 joinServer，令牌不出客户端；服务端用随机 nonce 调用 Mojang 会话服务校验，并在成功时替换为正版 UUID、矫正名称大小写、注入皮肤属性。失败/超时的处理可配置，并在玩家进服后通过标题与聊天消息告知在线/离线模式。

注意：客户端与服务端都需要安装本 Mod；服务器需设置为离线模式。

特性

• 登录期安全校验：客户端本地 joinServer(profile, token, nonce)，令牌不上传。

• 服务端 hasJoined 校验通过：

• 替换为正版 UUID；

• 使用 Mojang 返回的名称，统一大小写；

• 注入皮肤属性（含签名），并在进服后强制刷新外观。

• 超时/失败处理可配置（默认：超时踢出；失败放行离线）。

• 进服提示：

• 正版：绿色标题“正版模式”，短副标题“已通过正版校验”；

• 离线：红色标题“离线模式”，短副标题“鉴权失败：离线模式”，并发送一条可配置的长聊天提示。

工作流程

1. 服务器离线模式下，HELLO 后下发自定义登录查询（identifier: trueuuid:auth，包含 nonce）。

2. 客户端拦截查询，读取 nonce，使用本地令牌调用 MinecraftSessionService.joinServer(...)，并仅回传一个布尔 ack。

3. 服务端调用 https://sessionserver.mojang.com/session/minecraft/hasJoined?username={name}&serverId={nonce}[&ip={ip}]。

4. 成功：

• 用正版 UUID 和官方返回的名称构造新的 GameProfile；

• 注入皮肤 textures 属性（带签名），玩家加入后强制刷新一次玩家信息；

• 显示绿色标题“正版模式”。

5. 失败：

• 默认行为：放行为原版离线（可配置为直接踢出）；

• 进服后显示红色标题“离线模式”，并发送一条可配置的聊天提示说明可能是网络问题导致鉴权失败。

6. 超时：

• 默认行为：踢出（提示语可配置）；

• 也可配置为超时时放行离线。

环境要求

• Minecraft：1.20.x；

• Forge：47.x（如 47.4.8）；

• Java：17；

• 客户端与服务端都安装本 Mod；

• 服务端 server.properties：online-mode=false。

安装

• 服务器：

• 将 server.properties 设为 online-mode=false；

• 把构建出的 JAR 放到 mods/。

• 客户端：

• 把相同的 JAR 放到 mods/。

提示：若客户端没有安装本 Mod，服务端将收不到有效回包。此时会按配置选择“踢出”或“放行为离线”。

配置

首次运行后自动生成：

• config/trueuuid-common.toml

关键项（默认值符合“超时踢出 / 失败放行离线”的需求）：

• auth.timeoutMs = 10000

• 登录阶段等待客户端回包的超时时间（毫秒）。

• auth.allowOfflineOnTimeout = false

• false：超时踢出（默认）；

• true：超时放行为离线。

• auth.allowOfflineOnFailure = true

• true：任何鉴权失败放行为离线（默认）；

• false：失败时踢出。

• auth.timeoutKickMessage = "登录超时，未完成正版校验"

• 超时时的踢出提示语。

• auth.offlineFallbackMessage = "注意：你当前以离线模式进入服务器；如果你是正版账号，可能是网络原因导致无法成功鉴权。"

• 当以离线模式放行时，发送给玩家的聊天提示。

• auth.offlineShortSubtitle = "鉴权失败：离线模式"

• 离线模式下的标题短副标题（避免过长）。

• auth.onlineShortSubtitle = "已通过正版校验"

• 正版模式下的标题短副标题。

说明

• 标题的副标题使用“短文案”，防止超出屏幕；长说明走聊天提示；

• 需要自定义更多提示文案时，可直接修改以上配置项。

兼容性与注意事项

• 代理（Bungee/Velocity）：服务端会在可行时把远端 IP 作为 ip 参数传给 Mojang 的 hasJoined。若代理隐藏了真实 IP，校验仍可成功（ip 参数为可选）；

• 皮肤：登录期已注入皮肤属性；玩家加入后会广播一次“移除+初始化”的玩家信息包来强制刷新外观；

• 未安装客户端 Mod：无法正确回包。根据配置，可能被踢出或被放行为离线。

隐私

• 玩家 access token 不会离开客户端。客户端本地完成 joinServer 调用；

• 服务器仅收到一个布尔应答，随后由服务器自行调用 Mojang 会话服务校验 nonce。