Mod API

Other Fabric mods can open WebGUI overlays for players programmatically — no commands needed. The stable entry point is WebviewApi in the land.webgui.api package.

Dependency setup

Add WebGUI as a dependency in your build.gradle:

repositories {
    maven { url "https://modrinth.maven.pm/maven" } // or your preferred repo
}

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

And declare a soft dependency in fabric.mod.json so your mod loads after WebGUI:

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

Use "suggests" instead of "depends" if WebGUI is optional for your mod.

API class

package land.webgui.api;

public final class WebviewApi {

    /** Opens a full-screen GUI for the player. */
    public static void openGui(ServerPlayerEntity player, String url) { ... }

    /** Opens a transparent HUD overlay for the player. */
    public static void openHud(ServerPlayerEntity player, String url) { ... }

    /**
     * Sends a main menu URL to the player.
     * The player opens it any time with the main menu keybind (default F6).
     */
    public static void sendMainMenuUrl(ServerPlayerEntity player, String url) { ... }

    /**
     * Binds an entity to a WebGUI URL.
     * When a player right-clicks the entity, the GUI opens automatically.
     * The urlTemplate may contain placeholders: {entity_id}, {entity_uuid},
     * {entity_type}, {player_name}, {player_uuid}.
     */
    public static void bindEntity(UUID entityUuid, String urlTemplate, boolean cancelInteraction) { ... }

    /** Removes the WebGUI binding for the given entity UUID. */
    public static void unbindEntity(UUID entityUuid) { ... }

    /** Returns the entity binding for the given UUID, if one exists. */
    public static Optional<EntityBinding> getEntityBinding(UUID entityUuid) { ... }

    /** Maximum URL length accepted by the mod (16 384 characters). */
    public static int maxUrlLength() { ... }

    /** S2C protocol version this build uses. */
    public static int protocolVersion() { ... }
}

All methods must be called from the server thread.

GUI vs HUD

	GUI (openGui)	HUD (openHud)
Display	Full-screen, replaces the game view	Transparent overlay on top of the game
Closes on Esc	Yes	No (toggle with the interactive mode key)
Use case	Shops, menus, forms	Persistent info panels, minimaps, status bars

Opening a full-screen GUI

import land.webgui.api.WebviewApi;

// Show a shop screen to the player
WebviewApi.openGui(player, "https://your-site.example.com/shop");

The player can close it with Esc. If signed tokens are enabled in server.json, a token is appended to the URL automatically.

Opening a HUD overlay

// Show a persistent overlay (e.g. a minimap or status bar)
WebviewApi.openHud(player, "https://your-hud.example.com");

The mod appends a signed token to the URL automatically if enableTokens is true in server.json. Your backend receives the token as ?webgui_token=<value> and can verify the player's identity.

Setting the main menu URL

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

This replaces whatever URL the server sent on join. Call it again with an empty string to clear the menu:

WebviewApi.sendMainMenuUrl(player, "");

Practical examples

Open a GUI from a custom command

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;
        }));
});

Open a HUD when player joins

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

Switch from HUD to GUI on interaction

// When a player right-clicks a custom block (server thread)
WebviewApi.openGui(player, "https://your-site.example.com/terminal?block=" + blockPos);

Bind entities to GUIs programmatically

// Bind a specific entity by UUID — cancelInteraction=true hides the trade screen
UUID npcUuid = ...; // e.g. from entity.getUuid()
WebviewApi.bindEntity(npcUuid, "https://example.com/shop?npc={entity_id}", true);

// Remove the binding later
WebviewApi.unbindEntity(npcUuid);

All bindings are persisted to config/webgui/entity_bindings.json automatically.

URL placeholders

Placeholder	Value
{entity_id}	Entity UUID
{entity_uuid}	Entity UUID (alias)
{entity_type}	Namespaced type, e.g. minecraft:villager
{player_name}	The interacting player's display name
{player_uuid}	The interacting player's UUID

Checking WebGUI is present

If WebGUI is a soft dependency, guard your calls with a presence check:

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 limits

Constraint	Value
Max URL length	16 384 characters
Token query param	Appended automatically when enableTokens = true
Null/blank URL	Falls back to the mod's default page