TrueUUID

TrueUUID - мод для Майнкрафт, который решает одну из самых больных проблем владельцев серверов: как пустить на сервер и лицензионных (премиум), и пиратских (offline-mode) игроков одновременно, не ломая при этом UUID, скины и статистику.

Если вы когда-нибудь держали сервер в offline mode, то знаете эту боль. Игрок с лицензией заходит - а у него другой UUID, скин слетает, инвентарь пустой, потому что сервер выдал ему локальный профиль вместо настоящего. TrueUUID исправляет именно это: премиум-игрок проходит проверку через Mojang и сохраняет свой реальный UUID и подписанный скин, а пиратский игрок заходит как обычно в offline-режиме.

Какую проблему решает TrueUUID

В ванильном Майнкрафт есть два режима: online-mode=true (только лицензия, сервер проверяет каждого через Mojang) и online-mode=false (пускает всех, но UUID генерируется локально). Второй вариант удобен для пиратских серверов, но ломает всё для лицензионных игроков - их настоящий профиль Mojang игнорируется.

TrueUUID добавляет третий путь. Сервер остаётся в offline mode, но мод проверяет премиум-сессию через стандартный механизм joinServer / hasJoined от Mojang. Ключевой момент: access token игрока никогда не покидает его компьютер. Сервер получает только результат проверки - UUID, имя с правильным регистром и подписанные свойства скина. Это принципиально отличает TrueUUID от костылей вроде плагинов на пароли, где нужно вводить /login и /register.

По сути, это аналог authlib-injector или подобных решений, но в формате мода, который ставится и на клиент, и на сервер.

Как работает проверка входа

Механика довольно элегантная:

1. Сервер в offline mode отправляет клиенту одноразовый вызов (challenge).
2. Клиент отвечает на него через свою локальную сессию Mojang, используя стандартный вызов joinServer. Токен доступа при этом не передаётся.
3. Сервер проверяет результат через эндпоинт hasJoined у Mojang.
4. При успешной проверке игрок получает свой настоящий UUID и подписанные свойства скина.
5. При неудаче или таймауте - либо отказ во входе, либо переход в offline fallback, в зависимости от политики сервера.

Для сторонних Yggdrasil-провайдеров (типа LittleSkin) используется тот же поток через их HTTPS-эндпоинт сессии. Кастомные эндпоинты по умолчанию отключены - их хост нужно явно добавить в белый список.

Что мод делает на практике

• Проверяет сессии Mojang без отправки access token на сервер.
• Использует проверенный UUID, правильный регистр имени и подписанные свойства скина при входе.
• Может пускать offline-игроков, но блокирует повторное использование имён, которые ранее были подтверждены как премиум. Это защита от того, чтобы пират зашёл под ником лицензионного игрока и украл его инвентарь.
• Хранит реестр проверенных имён в файле trueuuid-registry.json.
• Показывает локализованный фидбек при входе и небольшой бейдж статуса (премиум/оффлайн) в HUD.
• Поддерживает ограниченные таймауты входа, лимиты ответов, проверку HTTPS, проверку публичного адреса и отказ от редиректов.
• Поддерживает Yggdrasil/authlib-injector сервисы на адаптерах, которые указаны в матрице целей.

Все 36 заявленных адаптеров включают миграцию данных из offline в verified, админские команды и addon API. Каждый exact target прошёл матрицу тестирования: премиум-вход, offline fallback, подтверждённая миграция и отказ по известному имени.

Установка

Важный нюанс

Один и тот же JAR-файл TrueUUID должен стоять и на клиенте, и на сервере. Берите сборку строго под вашу версию Minecraft и загрузчик. Не ставьте Forge JAR на NeoForge и наоборот. Для Fabric используйте remapped JAR из build/libs, а не development JAR из build/devlibs.

Сервер

1. Установите нужный загрузчик (Fabric, Forge или NeoForge) и версию Minecraft, совпадающую с именем файла TrueUUID.
2. Скопируйте JAR в папку mods сервера.
3. В server.properties выставите:

online-mode=false

4. Запустите сервер один раз, чтобы сгенерировался конфиг.
5. Держите сервер за файрволом на этапе настройки и тестирования.

Клиент (Prism Launcher)

1. Откройте инстанс с нужной версией Minecraft и загрузчиком.
2. Edit → Mods → Add file.
3. Выберите собранный JAR TrueUUID.
4. Убедитесь, что на сервере стоит тот же самый JAR.

Проверка

Зайдите на сервер с модифицированным клиентом. HUD покажет зелёный индикатор при подтверждённом премиум-входе и красный, если сервер принял offline fallback.

Не выставляйте в интернет dev-сервер, созданный через run-dev-target.sh - он намеренно привязан к localhost и работает в offline mode для тестирования.

Конфигурация

Forge и NeoForge генерируют:

config/trueuuid-common.toml

Fabric генерирует:

config/trueuuid.json

Основные параметры политики входа (TOML для Forge/NeoForge, для 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

Рекомендуемые настройки по умолчанию: неизвестное offline-имя пускается, но после того как имя прошло верификацию как премиум, оно больше не может зайти в offline-режиме. Это ключевая защита от подделки ников.

Позиция бейджа

Все три загрузчика позволяют настроить расположение индикатора аккаунта:

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

Сторонние провайдеры аутентификации

Для Yggdrasil/authlib-injector сервисов добавляйте только те хосты, которым доверяете:

auth.yggdrasil.apiRootWhitelist = ["littleskin.cn"]

Пустой белый список означает, что принимается только Mojang.

Миграция и админские команды

TrueUUID умеет переносить данные offline-игрока (инвентарь, статистику, достижения) на верифицированный UUID. Миграция требует подтверждения и сохраняет как старые offline-данные, так и существующие данные на целевом UUID перед изменением файлов.

Доступные команды:

/trueuuid cleanupuuid <имя>
/trueuuid migrateuuid <имя>

Обе команды требуют уровень прав 4 (оператор). Матрица целей показывает, какие адаптеры поддерживают миграцию.

Addon API для разработчиков

Серверный API доступен через cn.alini.trueuuid.api.TrueuuidApi. Другие моды могут запрашивать, зашёл ли игрок как премиум или через offline fallback:

AccountStatus status = TrueuuidApi.getStatus(serverPlayer);
if (status.isOffline()) {
    // Применить политику сервера для offline-игроков.
}

API также предоставляет callback на вход и доступ к реестру проверенных имён. Перед использованием проверьте матрицу целей.

Поддерживаемые версии и загрузчики

Проект поддерживает Fabric, Forge и NeoForge. Из свежих данных также упоминаются Paper и Spigot. Версия 1.2.0 публикует только 36 точных целей из матрицы поддержки - соседние патчи Minecraft не поддерживаются неявно.

Примеры доступных целей:

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

Актуальные версии Minecraft: 1.20.1 - 1.20.6 и 1.21.x.

Сборка из исходников

Gradle должен запускаться с Java 21 для всех целей. Цели на Java 17 компилируются автоматически с заявленным toolchain.

На 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"

Готовый JAR для Prism Launcher:

platform/neoforge-1.21.11/build/libs/trueuuid-1.2.0-neoforge-1.21.11.jar

На Windows PowerShell:

.\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

Каждый готовый production JAR записывается в:

platform/<загрузчик>-<версия-minecraft>/build/libs/

Приватность и безопасность

• Access token игрока остаётся на клиенте.
• Сервер получает nonce-результат, UUID, имя и подписанные свойства профиля - но не токен.
• Кастомные эндпоинты аутентификации должны использовать HTTPS и проходить проверки хоста, DNS/IP, таймаута, размера ответа и редиректов.
• Offline fallback - это политика сервера. На общих серверах держите защиту известных имён включённой.

Совет от практика

Если вы собираете гибридный сервер (лицензия + пиратка), TrueUUID - это must-have. Без него вы либо теряете лицензионных игроков (их UUID и скины ломаются), либо вынуждены ставить костыли вроде AuthMe с паролями, что раздражает всех. Тут же лицензионный игрок просто заходит и играет, а пиратский - тоже заходит, но под своим offline-профилем. Главное - не забудьте включить knownPremiumDenyOffline, иначе любой сможет зайти под чужим премиум-ником после перезапуска.

Для запуска сервера с друзьями мод отлично работает на BungeeHost (https://bungee.host) - установка в один клик, и вы можете сразу тестировать гибридный режим без возни с хостингом.

Лицензия

TrueUUID распространяется под GNU LGPL 3.0. Текстуры бейджа-замка - Copyright (C) 2026 F1xGOD, распространяются под той же лицензией.

Скачать мод TrueUUID для Майнкрафт и настроить гибридный сервер - это, пожалуй, самое разумное решение для тех, кто не хочет выбирать между лицензией и пираткой.