English | 简体中文

TrueUUID is a Minecraft authentication mod for offline-mode servers. It securely verifies premium accounts during login while keeping each player's access token on their own client.

It also supports configured Yggdrasil/authlib-injector skin-site accounts. The current tested and planned target status is maintained in the target matrix.

Both the client and the server must install this mod. The server must run with:

online-mode=false

Features

• Privacy-preserving authentication: the player's access token is only used locally on the client.
• Premium/Yggdrasil UUID support on offline-mode servers.
• Correct username casing after successful verification.
• Signed skin texture injection during login.
• Player info refresh after joining, helping skins update correctly.
• Clear join feedback for premium, skin-site, and offline fallback states.
• Localized UI text through Minecraft language files, so each client sees messages in its selected language.
• Offline-to-verified player data migration with confirmation and backups.
• Protection against known verified players rejoining with the same name in offline mode.

Why

Offline-mode servers normally cannot trust player UUIDs. TrueUUID improves identity integrity while keeping the server in offline mode.

Verified players can keep their official Mojang or Yggdrasil UUID and skin data, while the server never sees their access token.

This is useful for modpacks, LAN-style servers, private offline-mode communities, and servers that want better identity consistency without enabling Mojang online-mode directly.

How It Works

1. The server runs in offline mode.
2. During login, the server sends a custom login query with a nonce.
3. The modded client receives the query and locally calls joinServer with the player's profile, token, and nonce. The token never leaves the client.
4. The client replies with the authentication result and the selected authentication source.
5. The server verifies the nonce through Mojang Session Server or a supported Yggdrasil hasJoined endpoint.
6. If verification succeeds:
   • The pending login profile is replaced with the verified UUID.
   • Username casing is corrected.
   • Signed skin texture properties are injected.
   • The authentication source is recorded.
   • Player info is refreshed after joining.
7. If verification fails or times out:
   • Behavior is controlled by the config.
   • Known verified names can be prevented from falling back to offline mode.
   • Unknown names may still be allowed to use offline fallback if configured.

Offline Data Migration

TrueUUID includes a safer migration flow for players who used to play offline and later switch to a premium or skin-site account with the same name.

When a verified login detects matching offline UUID data, the player will see a confirmation screen. Migration only happens after confirmation.

Before migration, TrueUUID backs up both the old offline data and any existing target verified UUID data.

Supported migration targets include:

• Vanilla playerdata
• Vanilla playerdata_old
• Advancements
• Stats
• Cosmetic Armor .cosarmor data
• Open Parties and Claims
• FTB Chunks
• FTB Essentials
• FTB Teams
• FTB Quests
• FTB Ranks
• CustomNPCs playerdata

Requirements

Current runtime-proven target:

• Minecraft: 1.20.1
• Loader: Forge
• Java: 17

Do not infer support from a source directory or a successful build. See docs/architecture/target-matrix.md for the exact status of every adapter.

Client and server must both install TrueUUID.

Installation

Server:

1. Set online-mode=false in server.properties.
2. Place the matching TrueUUID jar in the server's mods folder.

Client:

1. Place the matching TrueUUID jar in the client's mods folder.

If the client does not have this mod installed, the server will not receive the expected login query response. Depending on configuration, the player may be kicked or allowed to fall back to offline mode.

Configuration

After the first run, the config file is generated at:

config/trueuuid-common.toml

Important options:

auth.timeoutMs = 30000

Login-phase wait time in milliseconds.

auth.allowOfflineOnTimeout = false

false: kick on timeout.

true: allow offline fallback on timeout.

auth.allowOfflineOnFailure = true

true: allow offline fallback for normal verification failures.

false: disconnect on verification failure.

auth.knownPremiumDenyOffline = true

If a name has already been verified as premium or Yggdrasil, deny later offline fallback for that name.

auth.allowOfflineForUnknownOnly = true

Only allow offline fallback for names that have never been verified before.

auth.recentIpGrace.enabled = true
auth.recentIpGrace.ttlSeconds = 10

Allows a short same-IP reconnect grace period after a verified player disconnects. This grace is not used when the client explicitly rejects authentication or logs in as offline.

auth.showJoinFeedback = true

Show the join feedback chat message for premium, skin-site, offline fallback, and single-player states. Set to false to silence it without changing authentication or skin refresh behavior.

auth.showJoinTitle = false

Additionally show a full-screen title/subtitle on join. Off by default, because the persistent account-status overlay below already reports the same state without interrupting the screen. Set to true to restore the old title behavior.

auth.showAccountOverlay = true

Shows a small client-side badge after a TrueUUID handshake: green Premium or red Offline, drawn as plain corner text with no backdrop. It is client-local and only appears after a TrueUUID-enabled server has responded.

Default feedback and disconnect messages are sent as Minecraft translation keys and rendered by the player's client language files (en_us / zh_cn). If you previously generated a config with custom bilingual strings, change those message values back to trueuuid.* keys or regenerate the config to use client-side localization.

/trueuuid cleanupuuid <name>

Admin-only command, permission level 4. It backs up and removes the duplicate offline UUID data for a player name without touching the verified UUID data.

/trueuuid migrateuuid <name>

Admin-only command, permission level 4. It approves inheriting the same-name offline UUID data by migrating it to the verified Mojang/Yggdrasil UUID with backups.

auth.yggdrasil.apiRootWhitelist = []

Allowlist for Yggdrasil/authlib-injector hasJoined hosts. An empty list rejects all client-reported endpoints and keeps Mojang as the safe default. Add an exact host such as "littleskin.cn", or an explicit wildcard such as "*.example.com". Custom endpoints must pass HTTPS/443, path, DNS/IP, response-size, timeout, and no-redirect checks.

The account-status badge position is configurable:

auth.overlayCorner = "bottom_right"
auth.overlayOffsetX = 0
auth.overlayOffsetY = 0
auth.overlayScale = 1.25

overlayCorner accepts top_left, top_right, bottom_left, or bottom_right. bottom_right is the default because vanilla keeps status effects and advancement toasts in the top right, chat in the bottom left, and other mods commonly claim the top left. The offsets nudge the badge by that many pixels (positive = right/down) if it still collides with another mod's HUD. overlayScale sizes the padlock and label together; whole numbers (1.0, 2.0) keep Minecraft's bitmap font perfectly crisp, values in between are slightly soft.

These options behave identically on every supported target.

Addon API

TrueUUID exposes a small server-side API (cn.alini.trueuuid.api) so other mods can branch on whether an online player authenticated as premium or through offline fallback — for example, sending offline players to a separate spawn.

AccountStatus is one of PREMIUM_VERIFIED, ONLINE_MODE, OFFLINE_FALLBACK, or UNKNOWN (with isPremium() / isOffline() helpers).

Query a player's status at any time while they are online:

import cn.alini.trueuuid.api.TrueuuidApi;
import cn.alini.trueuuid.api.AccountStatus;

AccountStatus status = TrueuuidApi.getStatus(serverPlayer);
if (status.isOffline()) {
    // e.g. restrict permissions, or teleport to an offline-only world
}

Or register a callback fired on the server thread the moment a player's status is known at join (register once during your mod's setup):

TrueuuidApi.registerLoginCallback((player, status) -> {
    if (status.isOffline()) {
        // first-join spawn handling for offline accounts
    }
});

Also available: TrueuuidApi.isKnownPremiumName(name) and TrueuuidApi.getPremiumUuid(name) for the persistent verified-name registry.

Compatibility Notes

• Proxies: Mojang's hasJoined IP parameter is optional. Verification can still work when the real client IP is hidden by a proxy.
• Skins: TrueUUID injects signed skin properties during login and refreshes player info after joining. If a client still shows stale skins, rejoining or clearing the skin cache may help.
• Offline fallback: Offline fallback is configurable. In the recommended setup, previously verified names cannot be reused by offline clients.
• Registry: TrueUUID stores known verified names in trueuuid-registry.json. If this file is cleared, the server forgets previous premium/Yggdrasil bindings.

Building

Windows:

.\gradlew.bat build

macOS/Linux:

./gradlew build

Each platform build writes its target-specific artifact to its own platform/<loader>-<minecraft-version>/build/libs/ directory. Forge 1.20.1 is the runtime-proven target; see docs/architecture/target-matrix.md for the exact target status and release model.

Privacy

The player's access token is never sent to the server.

The client uses the token locally for joinServer. The server only receives the authentication result and verifies the nonce through Mojang Session Server or a supported Yggdrasil endpoint.

License

GNU LGPL 3.0

Credits

• Mojang authlib and session API
• Sponge Mixin
• ForgeGradle
• NeoForge / ModDevGradle

---

Maintained by @YuWan-030, @wish131400, and @F1xGOD.