API для других модов

Другие Fabric-моды могут открывать WebGUI-оверлеи для игроков программно — без команд. Стабильная точка входа — класс WebviewApi в пакете land.webgui.api.

Подключение зависимости

Добавьте WebGUI как зависимость в build.gradle:

repositories {
    maven { url "https://modrinth.maven.pm/maven" } // или другой репозиторий
}

dependencies {
    modImplementation "land.webgui:webgui:<version>"
}

Объявите мягкую зависимость в fabric.mod.json, чтобы ваш мод загружался после WebGUI:

{
  "depends": {
    "webgui": ">=1.0.0"
  }
}

Используйте "suggests" вместо "depends", если WebGUI необязателен для вашего мода.

API-класс

package land.webgui.api;

public final class WebviewApi {

    /** Открывает полноэкранный GUI для игрока. */
    public static void openGui(ServerPlayerEntity player, String url) { ... }

    /** Открывает прозрачный HUD-оверлей для игрока. */
    public static void openHud(ServerPlayerEntity player, String url) { ... }

    /**
     * Отправляет игроку URL главного меню.
     * Игрок открывает его в любой момент нажатием клавиши главного меню (по умолчанию F6).
     */
    public static void sendMainMenuUrl(ServerPlayerEntity player, String url) { ... }

    /**
     * Привязывает сущность к WebGUI URL.
     * При нажатии ПКМ по сущности GUI откроется автоматически.
     * urlTemplate поддерживает плейсхолдеры: {entity_id}, {entity_uuid},
     * {entity_type}, {player_name}, {player_uuid}.
     */
    public static void bindEntity(UUID entityUuid, String urlTemplate, boolean cancelInteraction) { ... }

    /** Удаляет WebGUI-привязку для указанного UUID сущности. */
    public static void unbindEntity(UUID entityUuid) { ... }

    /** Возвращает привязку сущности по UUID, если она существует. */
    public static Optional<EntityBinding> getEntityBinding(UUID entityUuid) { ... }

    /** Максимальная длина URL, принимаемого модом (16 384 символа). */
    public static int maxUrlLength() { ... }

    /** Версия S2C-протокола этой сборки мода. */
    public static int protocolVersion() { ... }
}

Все методы должны вызываться из серверного потока.

GUI vs HUD

	GUI (openGui)	HUD (openHud)
Отображение	Полноэкранный, заменяет вид игры	Прозрачный оверлей поверх игры
Закрывается по Esc	Да	Нет (переключается клавишей интерактивного режима)
Применение	Магазины, меню, формы	Постоянные панели, миникарты, статусные бары

Открытие полноэкранного GUI

import land.webgui.api.WebviewApi;

// Показать игроку экран магазина
WebviewApi.openGui(player, "https://your-site.example.com/shop");

Игрок закрывает экран нажатием Esc. Если в server.json включён enableTokens, токен добавляется к URL автоматически.

Открытие HUD-оверлея

// Показать постоянный оверлей (миникарта, статусная панель)
WebviewApi.openHud(player, "https://ваш-hud.example.com");

Мод автоматически добавляет подписанный токен к URL, если в server.json включён enableTokens. Ваш бэкенд получает токен как ?webgui_token=<значение> и может проверить личность игрока.

Установка URL главного меню

WebviewApi.sendMainMenuUrl(player, "https://ваш-menu.example.com");

Заменяет URL, отправленный сервером при входе. Для сброса меню передайте пустую строку:

WebviewApi.sendMainMenuUrl(player, "");

Практические примеры

Открытие GUI из кастомной команды

CommandRegistrationCallback.EVENT.register((dispatcher, registryAccess, environment) -> {
    dispatcher.register(CommandManager.literal("shop")
        .executes(ctx -> {
            ServerPlayerEntity player = ctx.getSource().getPlayerOrThrow();
            WebviewApi.openGui(player, "https://your-site.example.com/shop?player=" + player.getUuidAsString());
            return 1;
        }));
});

Открытие HUD при входе игрока

ServerPlayConnectionEvents.JOIN.register((handler, sender, server) -> {
    ServerPlayerEntity player = handler.player;
    WebviewApi.openHud(player, "https://ваш-hud.example.com");
});

Переключение с HUD на GUI по взаимодействию

// При нажатии ПКМ на кастомный блок (серверный поток)
WebviewApi.openGui(player, "https://your-site.example.com/terminal?block=" + blockPos);

Программная привязка сущностей к GUI

// Привязать конкретную сущность по UUID — cancelInteraction=true скрывает экран торговли
UUID npcUuid = ...; // напр. entity.getUuid()
WebviewApi.bindEntity(npcUuid, "https://example.com/shop?npc={entity_id}", true);

// Удалить привязку позже
WebviewApi.unbindEntity(npcUuid);

Привязки автоматически сохраняются в config/webgui/entity_bindings.json.

URL-плейсхолдеры

Плейсхолдер	Значение
{entity_id}	UUID сущности
{entity_uuid}	UUID сущности (псевдоним)
{entity_type}	Тип с неймспейсом, напр. minecraft:villager
{player_name}	Отображаемое имя взаимодействующего игрока
{player_uuid}	UUID взаимодействующего игрока

Проверка наличия WebGUI

Если WebGUI — необязательная зависимость, защитите вызовы проверкой присутствия мода:

private static final boolean WEBGUI_PRESENT = FabricLoader.getInstance()
        .isModLoaded("webgui");

public static void tryOpenHud(ServerPlayerEntity player, String url) {
    if (WEBGUI_PRESENT) {
        WebviewApi.openHud(player, url);
    }
}

Ограничения URL

Ограничение	Значение
Максимальная длина URL	16 384 символа
Query-параметр токена	Добавляется автоматически при enableTokens = true
Null / пустой URL	Мод использует страницу по умолчанию