
Modrinth · Minecraft mod
TrueUUID
TrueUUID lets premium and offline-mode Minecraft players play together on the same server. Premium players keep their real Minecraft UUID and skin, while offline players can still join normally.
Quick answer
Which TrueUUID release should I use?
TrueUUID 1.3.0+forge-1.21.6 targets 1.21.6 with Forge. Installation on the client is optional. Installation on the dedicated server is optional. No extra mods listed for this file.
Where it goes
Is TrueUUID required on the client, server, or both?
Installation on the client is optional. Installation on the dedicated server is optional.
The source marks this as usable on both the client and server.
What else does TrueUUID 1.3.0+forge-1.21.6 need?
1.3.0+forge-1.21.6. Change the file and its required mods may change too.
This file does not list any required mods. Do not add a library just because a different file uses it.
This file does not list any required or optional mods.
Before you install it
Add TrueUUID without breaking your instance.
Built for TrueUUID 1.3.0+forge-1.21.6. Pick another file and the loader, install side or required mods may change.
- 01
Stick to this file
Use 1.3.0+forge-1.21.6. It targets 1.21.6 with Forge; another release may have different loader, side or dependency requirements.
- 02
Bring the mods it needs
This file does not list any required mods. Do not add a library just because a different file uses it.
- 03
Put it on the correct side
Installation on the client is optional. Installation on the dedicated server is optional.
- 04
Pick the file you checked
Use the “Get this file” button beside 1.3.0+forge-1.21.6. It opens that exact file at the source.
About this project
What does TrueUUID add?
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=falseStart 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 inbuild/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.
Project description from Modrinth.
Pick your setup
TrueUUID by Minecraft version and loader
Choose the version and loader you play, then open the matching release.
1.21.10
3 loader builds1.21.9
3 loader builds1.21.8
3 loader builds1.21.7
3 loader builds1.21.6
3 loader builds1.21.5
3 loader builds1.21.4
3 loader builds1.21.3
3 loader builds1.21.2
2 loader builds1.21.1
3 loader builds1.21
3 loader buildsShowing the newest 12 of 18 game versions. Older files are in the list below.
Check the dependencies, then try the file in a copied instance before changing a world you care about.
Recent files
TrueUUID versions and loaders
1.3.0+forge-1.21.6
trueuuid-1.3.0-forge-1.21.6.jar
13 Sept 2026
1.3.0+fabric-1.20.2
trueuuid-1.3.0-fabric-1.20.2.jar
13 Sept 2026
1.3.0+neoforge-1.20.1
trueuuid-1.3.0-neoforge-1.20.1.jar
13 Sept 2026
1.3.0+fabric-1.20.3
trueuuid-1.3.0-fabric-1.20.3.jar
13 Sept 2026
1.3.0+neoforge-1.20.4
trueuuid-1.3.0-neoforge-1.20.4.jar
13 Sept 2026
1.3.0+forge-1.21.9
trueuuid-1.3.0-forge-1.21.9.jar
13 Sept 2026
1.3.0+fabric-1.20.1
trueuuid-1.3.0-fabric-1.20.1.jar
13 Sept 2026
1.3.0+fabric-1.21.7
trueuuid-1.3.0-fabric-1.21.7.jar
13 Sept 2026
1.3.0+neoforge-1.21.10
trueuuid-1.3.0-neoforge-1.21.10.jar
13 Sept 2026
1.3.0+fabric-1.21.8
trueuuid-1.3.0-fabric-1.21.8.jar
13 Sept 2026
1.3.0+forge-1.20.3
trueuuid-1.3.0-forge-1.20.3.jar
13 Sept 2026
1.3.0+fabric-1.21.6
trueuuid-1.3.0-fabric-1.21.6.jar
13 Sept 2026
Looking for an older file? The official Modrinth project page is in Resources.