TrueUUID

TrueUUID - это мод для Minecraft, который решает давнюю проблему серверов в офлайн-режиме. Когда сервер работает с online-mode=false, любой может зайти под любым ником, включая ники премиум-игроков. Из-за этого у владельцев лицензионных аккаунтов меняется UUID, скины не отображаются, а данные могут перепутаться. TrueUUID добавляет проверку подлинности аккаунта прямо в игру: премиум-игроки получают свой реальный UUID и скин, а офлайн-игроки по-прежнему могут заходить без лицензии. При этом ваш токен доступа (access token) никогда не покидает ваш компьютер - сервер получает только результат проверки.

Мод доступен для Fabric, Forge и NeoForge, поддерживает версии Minecraft от 1.20.1 до 1.21.11. Полный список поддерживаемых версий смотрите в матрице целей (target matrix).

Быстрый старт

1. Скачайте JAR-файл для вашего загрузчика (Fabric/Forge/NeoForge) и версии Minecraft.
2. Поместите этот же файл в папку mods как на клиенте, так и на сервере.
3. В server.properties установите online-mode=false.
4. Запустите сервер один раз, чтобы сгенерировался конфиг TrueUUID.
5. Зайдите на сервер с модифицированным клиентом. На экране появится индикатор: зеленый - верифицированный премиум-вход, красный - офлайн-режим.

Важно: не используйте JAR, собранный для другой версии Minecraft или загрузчика. Для Fabric используйте перемаркированный JAR из build/libs, а не из build/devlibs.

Как работает верификация

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

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

Настройка

Для Forge и NeoForge конфиг лежит в config/trueuuid-common.toml, для Fabric - в config/trueuuid.json.

Основные опции политики входа:

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

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

Положение значка аккаунта настраивается так:

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

Для Yggdrasil-провайдеров добавьте только доверенные хосты:

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

Пустой список оставляет Mojang единственным принятым сервисом.

Команды и миграция данных

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

Доступные команды (уровень прав 4):

/trueuuid cleanupuuid <ник>
/trueuuid migrateuuid <ник>

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

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

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

API также предоставляет колбэк при входе и доступ к реестру верифицированных имен. Проверьте матрицу целей, прежде чем полагаться на API.

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

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

Лицензия

TrueUUID распространяется под лицензией GNU LGPL 3.0. Текстуры оригинального значка TrueUUID защищены авторским правом (C) 2026 F1xGOD и распространяются с проектом под той же лицензией.