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