TrueUUID

English | 简体中文

TrueUUID добавляет проверку аккаунтов на модифицированных серверах Minecraft, работающих в offline-режиме. Токен доступа премиум-игрока остаётся на его собственном компьютере; сервер получает только подтверждение входа, необходимое для проверки его UUID и скина.

Один и тот же JAR-файл TrueUUID должен быть установлен и на клиенте, и на сервере. Всегда выбирайте JAR, собранный под вашу точную версию Minecraft и загрузчик.

[!IMPORTANT] Версия 1.2.0 публикует только 36 точных целей, утверждённых в матрице целей. Пропущенные патчи Minecraft не поддерживаются по умолчанию.

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

1. Скачайте или соберите JAR под ваш точный загрузчик и версию Minecraft.
2. Поместите этот же JAR в папки mods клиента и сервера.

3. Переведите сервер в offline-режим:

   online-mode=false

4. Запустите сервер один раз, чтобы сгенерировать конфигурацию TrueUUID.
5. Зайдите с подходящим модифицированным клиентом. HUD показывает зелёный цвет для подтверждённого премиум-входа и красный, когда сервер принимает offline-фолбэк.

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

Что делает TrueUUID

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

Все 36 объявленных на данный момент адаптеров включают миграцию данных из offline в подтверждённые, админ-команды и API аддонов. Каждая точная цель прошла матрицу установленного JAR для премиума, offline-фолбэка, подтверждённой миграции и отказа для известных имён. Сверяйтесь с матрицей целей, а не предполагайте, что каждая реализованная возможность или пропущенный соседний патч Minecraft был протестирован.

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

1. Сервер в offline-режиме отправляет клиенту одноразовый запрос на вход.
2. Клиент использует свою локальную сессию, чтобы ответить на запрос через вызов joinServer от Mojang. Его токен доступа никогда не покидает клиент.
3. Сервер проверяет результат через эндпоинт hasJoined от Mojang.
4. Успешный вход получает подтверждённый UUID и подписанные свойства скина.
5. Неудачная проверка или проверка с истёкшим таймаутом либо отклоняется, либо обрабатывается настроенной политикой offline-фолбэка.

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

Установка

Сервер

1. Установите загрузчик и версию Minecraft, соответствующие имени файла TrueUUID.
2. Скопируйте JAR в директорию mods сервера.
3. Установите online-mode=false в server.properties.
4. Держите сервер за файрволом, пока настраиваете и тестируете его.

Prism Launcher

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

Не используй Forge JAR в NeoForge или JAR, собранный для другой версии Minecraft. Для Fabric используй remapped JAR из build/libs, а не development JAR из build/devlibs.

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

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. Другие моды могут узнать, вошёл ли игрок как premium или через офлайн-фолбэк:

AccountStatus status = TrueuuidApi.getStatus(serverPlayer);
if (status.isOffline()) {
    // Apply your server's offline-player policy.
}

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

Собрать один JAR для Prism Launcher

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 на любой ID из release/targets.json, например:

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 is the standalone Gradle 9.5 target:
.\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/<loader>-<minecraft-version>/build/libs/

Для локального запуска клиента/сервера во время разработки см. тестирование локального рантайма.

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

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

Лицензия

TrueUUID распространяется под лицензией GNU LGPL 3.0.

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

Поддерживается @YuWan-030, @wish131400 и @F1xGOD.