Конфиг server.json

Серверные настройки WebGUI хранятся в config/webgui/server.json.

Файл создаётся автоматически при первом запуске. Также создаётся шаблон config/webgui/server.example.json. Если tokenSecretBase64 пустой, новый секрет генерируется и сохраняется автоматически.

Полный пример

{
  "enableTokens": true,
  "tokenTtlSeconds": 900,
  "queryParamName": "webgui_token",
  "tokenSecretBase64": "<авто-генерируется или ваш секрет>",

  "autoHudOnJoin": false,
  "autoHudUrl": "",

  "mainMenuUrl": "",
  "deathScreenUrl": "",

  "serveBundledPages": true,
  "bundledPagesDir": "web",

  "requireClientMod": false,
  "pageEventsPerSecond": 20,
  "assetBytesPerSecond": 4194304,

  "updateCheckUrl": "",

  "trustedCommandOrigins": []
}

Поля

Подписанные токены

Подписанные токены позволяют вашему бэкенду убедиться, что запрос пришёл от настоящего клиента WebGUI.

Поле	Тип	По умолчанию	Описание
enableTokens	bool	true	Добавлять подписанный токен к каждому URL, который открывает мод.
tokenTtlSeconds	int	900	Время жизни токена в секундах. Минимум, применяемый модом: 60.
queryParamName	string	"webgui_token"	Имя query-параметра для передачи токена.
tokenSecretBase64	string	авто	Base64 HMAC-секрет, общий с вашим бэкендом. Генерируется автоматически, если пустой.

Авто-HUD

Поле	Тип	По умолчанию	Описание
autoHudOnJoin	bool	false	Автоматически открывать HUD-оверлей при входе игрока на сервер.
autoHudUrl	string	""	URL для авто-HUD. Обязателен, если autoHudOnJoin равен true.

Главное меню

Поле	Тип	По умолчанию	Описание
mainMenuUrl	string	""	URL, отправляемый клиентам при входе для экрана главного меню (открывается нажатием F6). Пустая строка — клавиша ничего не делает.

Экран смерти

Заменяет ванильный экран смерти вашей страницей.

Поле	Тип	По умолчанию	Описание
deathScreenUrl	string	""	Страница вместо ванильного экрана смерти. Пусто — остаётся ванильный.

Функция включается явно, потому что на этом экране находится единственный способ возродиться. Когда URL задан:

• Страница получает событие webgui:death с описанием того, кто или что убило игрока.
• Возрождение — вызов window.webgui.respawn() со страницы.
• Esc не закрывает страницу, ровно как ванильный экран не закрывается. Но если страница не загрузилась, Esc снова начинает возрождать — сломанная страница не запрёт игрока.
• Если игрок умер, пока браузер ещё стартует, он увидит ванильный экран: рисовать страницу пока попросту негде.

Ванильный HUD продолжает рисоваться под страницей — так же, как под ванильным экраном смерти. Если не хотите видеть хотбар насквозь, сделайте фон страницы непрозрачным.

Страницы, которые раздаёт сам сервер

Хостинг для WebGUI не нужен. Положите файлы в config/webgui/web/ и укажите их в любой настройке через схему webgui::

{ "mainMenuUrl": "webgui:/index.html", "deathScreenUrl": "webgui:/death.html" }

Папка создаётся при первом запуске с рабочим index.html внутри — чтобы было что править раньше, чем появится что настраивать.

/webgui reload подхватывает изменения без перезапуска: все, кто онлайн, узнают о новых файлах, а встроенная страница, уже открытая у игрока, перезагружается на месте — можно править файл и сразу видеть результат. Страницы с внешнего хостинга не трогаются: их перезагружают так же, как в браузере.

Поле	Тип	По умолчанию	Описание
serveBundledPages	bool	true	Раздавать config/webgui/web/ игрокам. При пустой папке ничего не делает.
bundledPagesDir	string	"web"	Каталог относительно config/webgui. Выйти за его пределы нельзя.
assetBytesPerSecond	int	4194304	Сколько байт страниц игрок может выкачать за секунду. 0 — без ограничения.

Файлы едут по тому соединению, по которому игрок и так играет: порт открывать не нужно, наружу ничего не торчит, работает за NAT. Каждый файл адресуется своим SHA-256, поэтому уже скачанный не запрашивается повторно, а изменённый — это просто другое имя.

Прочитайте это перед тем, как собирать страницу

Страницы, которые раздаёт сервер — разбор всей механики: на каком origin работает страница, почему абсолютные пути к ассетам дают 404 и как это правится в каждом сборщике, CORS и WebSocket к вашему бэкенду, все ограничения и таблица «симптом → причина → что делать». Почти любая проблема при первой настройке — это одна её строка.

Внешний хостинг работает ровно как раньше

http:// и https:// не трогаются вообще. Смешивать можно свободно: встроенная страница грузит скрипты с CDN, а внешняя берёт картинки из встроенных.

У встроенной страницы другой origin

Она отдаётся с http://127.0.0.1:25580, а не с вашего домена, поэтому ваш API должен назвать этот origin в CORS. При этом у внутриигрового браузера web security по умолчанию выключена (настройка Rinku), так что кросдоменный fetch пройдёт и без этого — но игрок может её включить, поэтому CORS всё равно настройте. Вместо жёсткого порта страница может читать window.webgui.assetsBase.

Проверка версии клиента

Поле	Тип	По умолчанию	Описание
requireClientMod	bool	false	Не пускать игроков без совместимого WebGUI вместо того, чтобы пускать с предупреждением.

При заходе сервер сообщает клиенту, какой WebGUI на нём стоит. Дальше всё зависит от клиента:

Клиент	requireClientMod: false (по умолчанию)	requireClientMod: true
Тот же протокол	Ничего — всё работает.	Ничего.
Старый WebGUI	Заходит; в чат приходит сообщение с обеими версиями.	Отключается, обе версии указаны в причине.
Без WebGUI	Заходит; заметка в чат, если сервер действительно использует страницы.	Отключается с сообщением, что мод обязателен.

Обновление с 1.7.0 и раньше на NeoForge

Те версии регистрировали каналы как обязательные, поэтому NeoForge-сервер не пускал никого без ровно того же WebGUI — и писал при этом «Incompatible client! Please use NeoForge <версия>», то есть указывал вообще не на тот мод. С 1.7.1 каналы необязательные, и игрок узнаёт, в чём дело на самом деле. Хотите по-прежнему не пускать — поставьте requireClientMod: true, теперь с внятным сообщением.

Ограничение частоты событий

Поле	Тип	По умолчанию	Описание
pageEventsPerSecond	int	20	Сколько сообщений postToGame страницы одного игрока могут отправить за секунду. 0 — без ограничения.

События страницы обрабатываются в серверном потоке, а страница — это веб-контент: зациклившийся ваш же JavaScript или враждебная страница, которую игрока уговорили открыть, иначе слали бы их со скоростью соединения. Всё сверх лимита отбрасывается и один раз логируется на игрока. Поднимите значение, если ваш интерфейс легально разговорчив.

Проверка обновлений

Поле	Тип	По умолчанию	Описание
updateCheckUrl	string	""	URL, возвращающий информацию о версии. Поддерживаемые форматы: {"version":"1.2.3"} или {"tag_name":"v1.2.3","html_url":"..."}. Пустая строка — отключено.

Доверенные origin для команд

Страницы могут выполнять команды Minecraft от лица игрока (см. runCommand). Так как в webview может открыться произвольный веб-контент, это ограничено по origin: команда принимается только с главного фрейма origin из этого списка.

Поле	Тип	По умолчанию	Описание
trustedCommandOrigins	string[]	[]	Origin'ы (scheme://host[:port]), чьи страницы могут выполнять команды. Пустой список — ни одна страница не может.

{ "trustedCommandOrigins": ["https://ui.myserver.example", "http://localhost:3000"] }

• Команды идут с правами самого игрока — как ввод в чат, без повышения привилегий.
• Запросы с любого другого origin (после редиректа или из <iframe>) отклоняются.
• Список отправляется клиенту при входе и очищается при отключении — доверие не переносится между серверами.
• Порты по умолчанию (443/80) нормализуются: https://x ≡ https://x:443.

Примечания

• Если вы используете подписанные токены, ваш бэкенд должен проверять их с тем же секретом, указанным в tokenSecretBase64.
• Путь к конфигу — config/webgui/server.json — обратите внимание: webgui, а не webui.