English | 简体中文
TrueUUID 为运行在离线模式下的模组化 Minecraft 服务器添加了账户验证功能。正版玩家的访问令牌保留在其本地计算机上;服务器仅接收用于验证其 UUID 和皮肤所需的登录凭证。
客户端和服务端必须安装相同的 TrueUUID JAR 文件。请务必选择与你的 Minecraft 版本及加载器完全匹配的 JAR。
[!IMPORTANT] 版本 1.2.0 仅发布 目标矩阵 中批准的 36 个确切目标。未包含的 Minecraft 补丁不隐含支持。
快速开始
-
下载或构建与你所用加载器和 Minecraft 版本完全匹配的 JAR 文件。
-
将该 JAR 文件放入客户端和服务端的
mods文件夹中。 -
将服务端设置为离线模式:
online-mode=false -
启动一次服务端以生成 TrueUUID 配置文件。
-
使用匹配的模组化客户端加入游戏。HUD 会显示绿色表示已验证的正版登录,当服务端接受离线回退时则显示红色。
请勿将 run-dev-target.sh 创建的测试服务端暴露到互联网。它故意绑定到 localhost 并使用离线模式进行测试。
TrueUUID 的功能
- 在不向服务器发送玩家访问令牌的情况下验证 Mojang 会话。
- 在登录时使用已验证的 UUID、用户名大小写以及签名的皮肤属性。
- 允许离线玩家加入,同时阻止之前已验证过的名称被重复用于离线模式。
- 将已知已验证的名称存储在
trueuuid-registry.json中。 - 显示本地化的登录反馈以及小型的正版/离线状态徽章。
- 支持有界的登录超时、响应限制、HTTPS 验证、公共地址检查以及拒绝重定向。
- 对于目标矩阵中标注了该功能的适配器,支持配置的 Yggdrasil/authlib-injector 服务。
所有目前声明的 36 个适配器均包含离线到已验证的数据迁移、管理员命令以及插件 API。每一个确切目标都通过了正版、离线回退、确认迁移以及已知名称拒绝的安装 JAR 矩阵测试。请参阅目标矩阵,不要假设每个已实现的功能或未包含的相邻 Minecraft 补丁都已经过测试。
登录验证工作原理
- 离线模式服务端向客户端发送一次性登录挑战。
- 客户端使用其本地会话通过 Mojang 的
joinServer调用回应挑战。其访问令牌永远不会离开客户端。 - 服务端通过 Mojang 的
hasJoined端点检查结果。 - 成功的登录将获得已验证的 UUID 和签名的皮肤属性。
- 失败或超时的检查将被拒绝或由配置的离线回退策略处理。
对于允许的 Yggdrasil 提供商,相同的流程使用其 HTTPS 会话端点。自定义端点在主机被明确列入白名单之前处于禁用状态。
安装
服务端
- 安装与 TrueUUID 文件名相匹配的加载器和 Minecraft 版本。
- 将 JAR 文件复制到服务端的
mods目录中。 - 在
server.properties中设置online-mode=false。 - 在配置和测试期间,让服务端保持在防火墙后面。
Prism Launcher
- 打开与 JAR 文件的 Minecraft 版本和加载器匹配的实例。
- 选择 Edit → Mods → Add file。
- 从目标的
build/libs目录中选择构建好的 TrueUUID JAR。 - 在服务端安装相同的 JAR。
请勿在 NeoForge 中使用 Forge JAR,也不要使用为其他 Minecraft 补丁构建的 JAR。对于 Fabric,请使用 build/libs 中的重映射 JAR,切勿使用 build/devlibs 中的开发 JAR。
配置
Forge 和 NeoForge 生成:
config/trueuuid-common.toml
Fabric 生成:
config/trueuuid.json
Forge 和 NeoForge 使用以下 TOML 键。Fabric 将匹配的登录策略设置存储在 JSON 的 auth 对象中;目标矩阵列出了任何适配器特定的差异。
主要策略选项如下:
auth.timeoutMs = 30000
auth.allowOfflineOnTimeout = false
auth.allowOfflineOnFailure = true
auth.knownPremiumDenyOffline = true
auth.allowOfflineForUnknownOnly = true
auth.recentIpGrace.enabled = true
auth.recentIpGrace.ttlSeconds = 10
auth.showJoinFeedback = true
auth.showJoinTitle = false
auth.showAccountOverlay = true
推荐的默认值允许未知的离线名称,但阻止该名称在完成已验证登录后回退到离线模式。
三种加载器都可以定位账户徽章。Forge 和 NeoForge 使用 TOML;Fabric 使用 JSON auth 对象内的匹配键:
auth.overlayCorner = "bottom_right"
auth.overlayOffsetX = 0
auth.overlayOffsetY = 0
auth.overlayScale = 1.25
对于 Yggdrasil/authlib-injector 提供商,仅添加你信任的主机:
auth.yggdrasil.apiRootWhitelist = ["littleskin.cn"]
空的白名单将使 Mojang 成为唯一接受的会话服务。
迁移和管理员命令
TrueUUID 可以备份并将同名离线玩家数据移动到已验证的 UUID。迁移需要确认,并在更改文件之前保留旧的离线数据和任何现有的目标数据。
可用的管理员命令:
/trueuuid cleanupuuid <name>
/trueuuid migrateuuid <name>
这两个命令都需要权限等级 4。目标矩阵标识了当前哪些适配器包含迁移功能。
插件 API
服务端 API 公开了 cn.alini.trueuuid.api.TrueuuidApi。其他模组可以查询玩家是以正版身份加入还是通过离线回退加入:
AccountStatus status = TrueuuidApi.getStatus(serverPlayer);
if (status.isOffline()) {
// 应用你的服务器的离线玩家策略。
}
API 还提供登录回调和对已验证名称注册表的访问。在使用之前请检查目标矩阵。
为 Prism Launcher 构建单个 JAR
Gradle 必须使用 Java 21 启动,以支持所有目标平台。Java 17 目标仍会自动使用其声明的 Java 17 工具链进行编译和运行。
在 Linux 上,从仓库检出目录执行:
cd ~/TrueUUID
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
export PATH="$JAVA_HOME/bin:$PATH"
TARGET=neoforge-1.21.11
./scripts/ci/build-target.sh "$TARGET"
生成的适用于 Prism 的 JAR 文件路径如下:
platform/neoforge-1.21.11/build/libs/trueuuid-1.2.0-neoforge-1.21.11.jar
将 TARGET 更改为 release/targets.json 中的任意 ID,例如:
forge-1.20.1
forge-1.21.6
forge-1.21.8
fabric-1.20.1
fabric-1.20.2
fabric-1.20.4
fabric-1.20.6
fabric-1.21.1
fabric-1.21.3
fabric-1.21.4
fabric-1.21.5
fabric-1.21.6
fabric-1.21.8
fabric-1.21.10
fabric-1.21.11
neoforge-1.20.4
neoforge-1.21.11
列出所有可用目标的方法:
jq -r '.targets[].id' release/targets.json
在 Windows PowerShell 中,已选择 Java 21 的情况下:
.\gradlew.bat :platform:neoforge-1.21.11:build --no-daemon
# Forge 1.21.11 是独立的 Gradle 9.5 目标:
.\platform\forge-1.21.11\gradlew.bat -p platform/forge-1.21.11 build --no-daemon
若要构建所有目标,请执行:
./scripts/ci/build-all-targets.sh
每个完成的生产用 JAR 文件均写入至以下路径:
platform/<loader>-<minecraft-version>/build/libs/
有关本地客户端/服务器开发运行,请参阅 本地运行时测试。
隐私与安全
- 玩家的访问令牌仅保留在客户端。
- 服务器接收的是非ce结果、UUID、用户名以及签名的配置文件属性——而非令牌本身。
- 自定义认证端点必须使用 HTTPS,并通过配置的 host、DNS/IP、超时时间、响应大小及重定向检查。
- 离线回退是一种服务器策略。在公共服务器上请保持已知名称保护功能启用。
许可证
TrueUUID 遵循 GNU LGPL 3.0 许可协议。
原始 TrueUUID 锁徽标纹理版权归 © 2026 F1xGOD 所有,并随项目一同分发,同样采用 GNU LGPL 3.0 许可协议。
由 @YuWan-030、@wish131400 和 @F1xGOD 维护。
English | 简体中文
TrueUUID adds account verification to modded Minecraft servers that run in offline mode. A premium player's access token stays on their own computer; the server receives only the login proof needed to verify their UUID and skin.
The same TrueUUID JAR must be installed on the client and server. Always choose the JAR made for your exact Minecraft version and loader.
[!IMPORTANT] Version 1.2.0 publishes only the 36 exact targets approved in the target matrix. Omitted Minecraft patches are not implicitly supported.
Quick start
-
Download or build the JAR for your exact loader and Minecraft version.
-
Put that same JAR in the client's and server's
modsfolders. -
Set the server to offline mode:
online-mode=false -
Start the server once to generate the TrueUUID configuration.
-
Join with a matching modded client. The HUD shows green for a verified premium login and red when the server accepts offline fallback.
Do not expose a development server created by run-dev-target.sh to the
internet. It deliberately binds to localhost and uses offline mode for testing.
What TrueUUID does
- Verifies Mojang sessions without sending the player's access token to the server.
- Uses the verified UUID, username casing, and signed skin properties during login.
- Can allow offline players while blocking offline reuse of names that were previously verified.
- Stores known verified names in
trueuuid-registry.json. - Shows localized login feedback and a small premium/offline status badge.
- Supports bounded login timeouts, response limits, HTTPS validation, public address checks, and redirect refusal.
- Supports configured Yggdrasil/authlib-injector services on adapters that list that feature in the target matrix.
All 36 currently declared adapters include offline-to-verified data migration, admin commands, and the addon API. Every exact target passed the premium, offline fallback, confirmed migration, and known-name denial installed-JAR matrix. Consult the target matrix instead of assuming every implemented feature or an omitted adjacent Minecraft patch was exercised.
How login verification works
- The offline-mode server sends the client a one-time login challenge.
- The client uses its local session to answer the challenge through Mojang's
joinServercall. Its access token never leaves the client. - The server checks the result with Mojang's
hasJoinedendpoint. - A successful login receives the verified UUID and signed skin properties.
- A failed or timed-out check is either rejected or handled by the configured offline-fallback policy.
For an allowed Yggdrasil provider, the same flow uses its HTTPS session endpoint. Custom endpoints are disabled until their host is explicitly allowlisted.
Installation
Server
- Install the loader and Minecraft version matching the TrueUUID filename.
- Copy the JAR into the server's
modsdirectory. - Set
online-mode=falseinserver.properties. - Keep the server behind a firewall while configuring and testing it.
Prism Launcher
- Open the instance matching the JAR's Minecraft version and loader.
- Select Edit → Mods → Add file.
- Select the built TrueUUID JAR from the target's
build/libsdirectory. - Install the same JAR on the server.
Do not use a Forge JAR in NeoForge, or a JAR built for another Minecraft patch.
For Fabric, use the remapped JAR in build/libs, never the development JAR in
build/devlibs.
Configuration
Forge and NeoForge generate:
config/trueuuid-common.toml
Fabric generates:
config/trueuuid.json
Forge and NeoForge use the TOML keys below. Fabric stores the matching login
policy settings in the JSON auth object; the target matrix lists any
adapter-specific gaps.
The main policy options are:
auth.timeoutMs = 30000
auth.allowOfflineOnTimeout = false
auth.allowOfflineOnFailure = true
auth.knownPremiumDenyOffline = true
auth.allowOfflineForUnknownOnly = true
auth.recentIpGrace.enabled = true
auth.recentIpGrace.ttlSeconds = 10
auth.showJoinFeedback = true
auth.showJoinTitle = false
auth.showAccountOverlay = true
The recommended defaults allow an unknown offline name but stop that name from falling back to offline mode after it has completed a verified login.
All three loaders can position the account badge. Forge and NeoForge use TOML;
Fabric uses the matching keys inside the JSON auth object:
auth.overlayCorner = "bottom_right"
auth.overlayOffsetX = 0
auth.overlayOffsetY = 0
auth.overlayScale = 1.25
For Yggdrasil/authlib-injector providers, add only hosts you trust:
auth.yggdrasil.apiRootWhitelist = ["littleskin.cn"]
An empty allowlist keeps Mojang as the only accepted session service.
Migration and admin commands
TrueUUID can back up and move same-name offline player data to a verified UUID. Migration requires confirmation and preserves both the old offline data and any existing destination data before changing files.
Available admin commands:
/trueuuid cleanupuuid <name>
/trueuuid migrateuuid <name>
Both commands require permission level 4. The target matrix identifies which adapters currently include migration.
Addon API
The server-side API exposes cn.alini.trueuuid.api.TrueuuidApi. Other mods can
query whether a player joined as premium or through offline fallback:
AccountStatus status = TrueuuidApi.getStatus(serverPlayer);
if (status.isOffline()) {
// Apply your server's offline-player policy.
}
The API also provides a login callback and access to the verified-name registry. Check the target matrix before depending on it.
Build one JAR for Prism Launcher
Gradle must be launched with Java 21 for every target. Java 17 targets are still compiled and run with their declared Java 17 toolchain automatically.
On Linux, from the repository checkout:
cd ~/TrueUUID
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
export PATH="$JAVA_HOME/bin:$PATH"
TARGET=neoforge-1.21.11
./scripts/ci/build-target.sh "$TARGET"
The Prism-ready JAR is then:
platform/neoforge-1.21.11/build/libs/trueuuid-1.2.0-neoforge-1.21.11.jar
Change TARGET to any ID in release/targets.json, for example:
forge-1.20.1
forge-1.21.6
forge-1.21.8
fabric-1.20.1
fabric-1.20.2
fabric-1.20.4
fabric-1.20.6
fabric-1.21.1
fabric-1.21.3
fabric-1.21.4
fabric-1.21.5
fabric-1.21.6
fabric-1.21.8
fabric-1.21.10
fabric-1.21.11
neoforge-1.20.4
neoforge-1.21.11
List every available target with:
jq -r '.targets[].id' release/targets.json
On Windows PowerShell, with Java 21 selected:
.\gradlew.bat :platform:neoforge-1.21.11:build --no-daemon
# Forge 1.21.11 is the standalone Gradle 9.5 target:
.\platform\forge-1.21.11\gradlew.bat -p platform/forge-1.21.11 build --no-daemon
To build every target instead:
./scripts/ci/build-all-targets.sh
Each finished production JAR is written to:
platform/<loader>-<minecraft-version>/build/libs/
For local client/server development runs, see local runtime testing.
Privacy and security
- The player's access token stays on the client.
- The server receives a nonce result, UUID, username, and signed profile properties—not the token.
- Custom authentication endpoints must use HTTPS and pass the configured host, DNS/IP, timeout, response-size, and redirect checks.
- Offline fallback is a server policy. Keep known-name protection enabled on shared servers.
License
TrueUUID is licensed under the GNU LGPL 3.0.
The original TrueUUID lock badge textures are Copyright (C) 2026 F1xGOD and are distributed with the project under the same GNU LGPL 3.0 license.
Maintained by @YuWan-030, @wish131400, and @F1xGOD.
下载 TrueUUID
下载 TrueUUID
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 TrueUUID
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 TrueUUID
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 TrueUUID
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 TrueUUID
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 TrueUUID
下载 TrueUUID
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 TrueUUID
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 TrueUUID
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
English
TrueUUID 1.3.0 is a security update for every Forge, Fabric, and NeoForge build. It also delivers the exact-patch coverage prepared for 1.2.1, which was never published. This release contains 52 exact mod builds for Minecraft 1.20.1 through 1.21.11 and new server plugins for Spigot 1.20.1 and Paper 1.20.1. The login flow of every mod build passed the installed-JAR login matrix: premium login, offline fallback, confirmed migration, and known-name denial.
Security fixes
- A timeout, a silent or malformed client response, or a failed session check no longer falls back to offline admission. Only a TrueUUID client that explicitly reports it has no local premium session reaches the offline-fallback policy.
- Removed the short same-IP reconnect grace. A reconnecting player must verify again.
- Fixed a Forge and NeoForge login race that could let a native offline login finish before the TrueUUID check started. Minecraft 1.20.2 and later install the gate at
startClientVerification, and 1.20.1 installs it right after the login profile is set, before Forge publishes negotiation state. Fabric was not affected. - Fixed premium verification failing with HTTP 204 behind proxies, NAT, or split IPv4/IPv6 routing. TrueUUID no longer sends the server-observed client IP to the
hasJoinedendpoint. - Fixed NeoForge 1.20.3 login answers, which used the wrong NeoForge payload wrapper and failed during login.
New builds
- Fabric and NeoForge: 1.20.3, 1.20.5, 1.21, 1.21.2, 1.21.7, and 1.21.9.
- Forge: 1.20.3, 1.21, 1.21.7, and 1.21.9. Forge never published a loader for Minecraft 1.20.5 or 1.21.2.
New server plugins
- TrueUUID now runs as a plugin on Spigot 1.20.1 and Paper 1.20.1 servers, with no server mod. The plugin needs ProtocolLib 5.1.0 or newer.
- A player with the matching TrueUUID client mod is verified through the mod. A premium player without the mod is verified through the normal Mojang login.
- The plugin works with any Spigot or Paper 1.20.1 build whose login internals match, and it refuses to start when BungeeCord or Velocity forwarding is enabled.
- Name collisions between premium and offline players wait for a one-time administrator approval. See the identity policy guide in the repository.
Other changes
- A player without TrueUUID on the client is disconnected with a plain message asking them to install it.
- The offline-fallback chat notice is shorter and states that the account was not premium-verified.
- Join notices show a bold blue TrueUUID gradient, and a server started in an interactive terminal prints the same gradient at startup. Log files stay plain.
Upgrade notes for server owners
- If you relied on
allowOfflineOnFailure = trueto admit players while Mojang or the network was unavailable, those logins are now denied. Players on an offline launcher with TrueUUID installed are still handled by the offline-fallback policy. allowOfflineOnTimeoutand therecentIpGracekeys remain in existing config files for compatibility. They are ignored.
Supported downloads
- Forge: 1.20.1, 1.20.2, 1.20.3, 1.20.4, 1.20.6, 1.21, 1.21.1, and 1.21.3 through 1.21.11.
- Fabric: every Minecraft release from 1.20.1 through 1.21.11.
- NeoForge: every Minecraft release from 1.20.1 through 1.21.11.
- Server plugins: Spigot 1.20.1 and Paper 1.20.1.
中文
TrueUUID 1.3.0 是针对所有 Forge、Fabric 和 NeoForge 构建的安全更新。它还包含了原本为 1.2.1 准备但从未发布的精确补丁覆盖内容。本次发布包含针对 Minecraft 1.20.1 至 1.21.11 的 52 个精确模组构建,以及适用于 Spigot 1.20.1 和 Paper 1.20.1 的新服务端插件。每个模组构建的登录流程均通过了已安装 JAR 的登录矩阵测试:正版登录、离线回退、确认迁移和已知名称拒绝。
安全修复
- 超时、客户端无响应或响应格式错误、会话检查失败时,不再降级为离线放行。只有明确报告本地没有正版会话的 TrueUUID 客户端才会进入离线回退策略。
- 移除了短时间同 IP 重连宽限期。重新连接的玩家必须再次验证。
- 修复了可能导致原生离线登录在 TrueUUID 检查开始之前完成的 Forge 和 NeoForge 登录竞态条件。Minecraft 1.20.2 及更高版本在
startClientVerification处安装网关,而 1.20.1 则在设置登录档案后、Forge 发布协商状态前安装该网关。Fabric 未受影响。 - 修复了在代理、NAT 或 IPv4/IPv6 分流路由环境下,因返回 HTTP 204 而导致正版验证失败的问题。TrueUUID 不再向
hasJoined端点发送服务端观察到的客户端 IP。 - 修复了 NeoForge 1.20.3 登录响应使用错误的 NeoForge 载荷包装器并在登录期间失败的问题。
新增构建
- Fabric 和 NeoForge:1.20.3、1.20.5、1.21、1.21.2、1.21.7 和 1.21.9。
- Forge:1.20.3、1.21、1.21.7 和 1.21.9。Forge 从未发布过 Minecraft 1.20.5 或 1.21.2 的加载器。
新增服务端插件
- TrueUUID 现在可以作为插件运行在 Spigot 1.20.1 和 Paper 1.20.1 服务器上,无需服务端模组。该插件需要 ProtocolLib 5.1.0 或更高版本。
- 安装了匹配 TrueUUID 客户端模组的玩家通过模组进行验证。未安装模版的正版玩家通过常规 Mojang 登录进行验证。
- 该插件适用于任何登录内部结构匹配的 Spigot 或 Paper 1.20.1 构建,当启用 BungeeCord 或 Velocity 转发时会拒绝启动。
- 正版玩家与离线玩家之间的名称冲突需等待管理员一次性批准。请参阅仓库中的身份策略指南。
其他更改
- 客户端未安装 TrueUUID 的玩家将被断开连接,并收到一条纯文本消息提示其安装该模组。
- 离线回退的聊天通知更简短,并说明该账号未经过正版验证。
- 加入服务器通知显示加粗蓝色的 TrueUUID 渐变效果,在交互式终端中启动的服务器也会在启动时打印相同的渐变效果。日志文件保持纯文本格式。
服务器所有者升级须知
- 如果您此前依赖
allowOfflineOnFailure = true在 Mojang 或网络不可用时允许玩家登录,此类登录现在将被拒绝。安装了 TrueUUID 的离线启动器玩家仍由离线回退策略处理。 allowOfflineOnTimeout和recentIpGrace键保留在现有配置文件中以兼容旧版,但会被忽略。
支持的下载
- Forge:1.20.1、1.20.2、1.20.3、1.20.4、1.20.6、1.21、1.21.1,以及 1.21.3 至 1.21.11。
- Fabric:1.20.1 至 1.21.11 的所有 Minecraft 版本。
- NeoForge:1.20.1 至 1.21.11 的所有 Minecraft 版本。
- 服务端插件:Spigot 1.20.1 和 Paper 1.20.1。
关于这个资源的讨论、问题反馈与使用心得
还没有讨论,来发第一帖吧
你是这个资源的作者?登录后可认领此资源。
相似资源
模组
一个用于收集生物掉落物的多区块模组。
模组
显示你正在注视的方块的信息。(适用于 Minecraft 1.16+ 的 Hwyla/Waila 分支)
模组
使用 JavaScript 编辑配方、添加自定义物品、编写世界事件!
模组
查看物品与配方
模组
在游戏画面角落显示附近世界地形、玩家、生物和实体的地图。可创建路径点,帮助你找到标记过的位置。
模组
AE2:一款流行的自动化与存储模组
评论 0
登录后参与评分
还没有评论,来抢沙发吧