HUD Ensemble

HUD Ensemble

HUD Ensemble is a server-side Hytale plugin that enables multi-layer HUD composition per player.

In vanilla behavior, only one CustomUIHud can be active at a time — which means plugins often overwrite each other. HUD Ensemble solves this by composing multiple HUD layers into a single composite HUD so different systems (or different plugins) can display UI at the same time.

Key Features

• Multi-layer HUD
  Stack multiple CustomUIHud layers for the same player.

• Namespaced layers (no collisions)
  Each plugin can use its own namespace via a client handle, preventing accidental ID conflicts.

• Fast updates (no rebuild required)
  Update UI elements inside an existing layer using updateLayer(...) without rebuilding the whole HUD.

• Broadcast helpers
  Show/remove layers for all online players (best-effort; scheduled per world-thread).

• Cleanup safety
  Proper close() removes your layers. A best-effort GC safety net exists if a client becomes unreachable, but it does not replace calling close().

Installation

1. Build the plugin .jar.
2. Drop it into your server’s plugins folder.
3. Start (or restart) the server.

Recommended:

• Keep HUD Ensemble loaded before plugins that depend on it.
• Always test with at least two plugins that set a HUD to confirm composition works as expected.

Demo Commands

These commands exist only for testing on a server. For real integrations, use the API (see below).

• /hudens demo — enables demo HUD layers
• /hudens clean — removes demo HUD layers

Developer Guide (API)

HUD Ensemble provides a public API designed for other server plugins.

1) Get the service / open a client

Use a client handle to automatically namespace your layer IDs and simplify cleanup.

import com.example.hudensemble.api.HudEnsemble;
import com.example.hudensemble.api.HudEnsembleClient;

public class MyPlugin extends JavaPlugin {
  private HudEnsembleClient hud;

  @Override
  protected void setup() {
    hud = HudEnsemble.openClientOrThrow(this);
  }

  @Override
  protected void shutdown() {
    if (hud != null) {
      hud.close(); // IMPORTANT: cleanup
      hud = null;
    }
  }
}

If HUD Ensemble is not installed or not compatible, openClientOrThrow(...) throws a clear error.

2) Show a HUD layer to a specific player

hud.setLayer(player, playerRef, "greeting", new MyHud());

Replace the same layer ID later to update the layer (full rebuild for that layer).

3) Remove a layer (or clear all layers owned by this client)

hud.removeLayer(player, "greeting");

hud.clear(player);

4) Update UI inside an existing layer (fast path)

If the layer already exists, update UI commands in-place:

hud.updateLayer(player, "greeting", cmd -> {
  cmd.set("#Title.Text", "Hello, HUD Ensemble!");
  cmd.set("#Counter.Text", "42");
});

Selectors are written normally. HUD Ensemble automatically prefixes them into the correct layer root.

5) Broadcast (all online players)

Show a layer for all connected players:

int scheduled = hud.setLayerForAllOnline("watermark", pr -> new MyHud());

Remove a layer for all online players:

int scheduled = hud.removeLayerForAllOnline("watermark");

Clear all layers owned by this client for all online players:

int scheduled = hud.clearForAllOnline();

The returned number is how many players were scheduled for the operation.

Compatibility Notes (Important)

Other plugins that do NOT use this API

• If another plugin sets a CustomUIHud before HUD Ensemble is activated for a player, that HUD can be preserved as a “base layer”.
• If another plugin sets a CustomUIHud after the ensemble is active, it will overwrite the composite HUD (this is how setCustomHud works), and HUD Ensemble layers will disappear.

Fallback behavior

HUD Ensemble relies on a bridge to build commands for layering. If the current server version does not support it, the plugin may fall back to a single-HUD mode. In that mode:

• layering may be unavailable,
• per-layer remove/update may not behave as expected.

API Versioning

HUD Ensemble exposes an API version number so dependent plugins can validate compatibility.

int v = HudEnsemble.getServiceOrThrow().getApiVersion();

Contacts

• Discord / Telegram / socials: artur_hatoka