Documentation/content/ui-systems/hud-manager.en.md

---
title: HUD Manager
type: docs
weight: 1
---

The `HudManager` controls which HUD components are visible to the player.

**Package:** `com.hypixel.hytale.server.core.entity.entities.player.hud`

## HUD Components

All available HUD components:

| Component | Description |
|-----------|-------------|
| `HudComponent.Hotbar` | Player's item hotbar |
| `HudComponent.StatusIcons` | Status effect icons |
| `HudComponent.Reticle` | Crosshair/targeting reticle |
| `HudComponent.Chat` | Chat window |
| `HudComponent.Requests` | Pending requests UI |
| `HudComponent.Notifications` | Alert notifications |
| `HudComponent.KillFeed` | Kill/death messages |
| `HudComponent.InputBindings` | Control hints |
| `HudComponent.PlayerList` | Tab player list |
| `HudComponent.EventTitle` | Large event titles |
| `HudComponent.Compass` | Direction compass |
| `HudComponent.ObjectivePanel` | Quest/objective tracker |
| `HudComponent.PortalPanel` | Portal interface |
| `HudComponent.BuilderToolsLegend` | Builder tool hints |
| `HudComponent.Speedometer` | Speed indicator |
| `HudComponent.UtilitySlotSelector` | Utility slot UI |
| `HudComponent.BlockVariantSelector` | Block variant picker |
| `HudComponent.BuilderToolsMaterialSlotSelector` | Builder material slots |
| `HudComponent.Stamina` | Stamina bar |
| `HudComponent.AmmoIndicator` | Ammunition counter |
| `HudComponent.Health` | Health bar |
| `HudComponent.Mana` | Mana bar |
| `HudComponent.Oxygen` | Oxygen/breath bar |
| `HudComponent.Sleep` | Sleep indicator |

## Default Components

These components are visible by default:

```java
Set<HudComponent> DEFAULT = Set.of(
    HudComponent.UtilitySlotSelector,
    HudComponent.BlockVariantSelector,
    HudComponent.StatusIcons,
    HudComponent.Hotbar,
    HudComponent.Chat,
    HudComponent.Notifications,
    HudComponent.KillFeed,
    HudComponent.InputBindings,
    HudComponent.Reticle,
    HudComponent.Compass,
    HudComponent.Speedometer,
    HudComponent.ObjectivePanel,
    HudComponent.PortalPanel,
    HudComponent.EventTitle,
    HudComponent.Stamina,
    HudComponent.AmmoIndicator,
    HudComponent.Health,
    HudComponent.Mana,
    HudComponent.Oxygen,
    HudComponent.BuilderToolsLegend,
    HudComponent.Sleep
);
```

## Accessing the HUD Manager

```java
Player player = ...;
HudManager hudManager = player.getHudManager();
```

## Showing Components

```java
// Show specific components (additive)
hudManager.showHudComponents(player.getPlayerRef(),
    HudComponent.Health,
    HudComponent.Stamina,
    HudComponent.Hotbar
);

// Show from a Set
Set<HudComponent> components = Set.of(
    HudComponent.Chat,
    HudComponent.Notifications
);
hudManager.showHudComponents(player.getPlayerRef(), components);
```

## Hiding Components

```java
// Hide specific components
hudManager.hideHudComponents(player.getPlayerRef(),
    HudComponent.Compass,
    HudComponent.Speedometer
);
```

## Setting Components

Replace all visible components:

```java
// Set exact visible components (replaces all)
hudManager.setVisibleHudComponents(player.getPlayerRef(),
    HudComponent.Hotbar,
    HudComponent.Health
);

// Clear all HUD components (empty)
hudManager.setVisibleHudComponents(player.getPlayerRef());
```

## Querying Visible Components

```java
Set<HudComponent> visible = hudManager.getVisibleHudComponents();

if (visible.contains(HudComponent.Health)) {
    // Health bar is visible
}
```

## Resetting the HUD

```java
// Reset to default components and clear custom HUD
hudManager.resetHud(player.getPlayerRef());

// Reset entire UI state
hudManager.resetUserInterface(player.getPlayerRef());
```

## Custom HUD Overlay

For persistent overlays:

```java
public class ScoreboardHud extends CustomUIHud {

    public ScoreboardHud(PlayerRef ref) {
        super(ref);
    }

    @Override
    protected void build(UICommandBuilder builder) {
        // Extension .ui is REQUIRED
        builder.append("Hud/Scoreboard.ui");
        builder.set("#score", 1500);
        builder.set("#rank", "Gold");
    }
}

// Set custom HUD
hudManager.setCustomHud(player.getPlayerRef(), new ScoreboardHud(player.getPlayerRef()));

// Remove custom HUD
hudManager.setCustomHud(player.getPlayerRef(), null);
```

## Practical Examples

### Cinematic Mode

Hide all UI for cutscenes:

```java
public void enterCinematicMode(Player player) {
    HudManager hud = player.getHudManager();

    // Store current state if needed for restoration
    Set<HudComponent> previous = new HashSet<>(hud.getVisibleHudComponents());

    // Clear all HUD
    hud.setVisibleHudComponents(player.getPlayerRef());
}

public void exitCinematicMode(Player player, Set<HudComponent> restore) {
    player.getHudManager().setVisibleHudComponents(player.getPlayerRef(), restore);
}
```

### Minimal HUD Mode

Show only essential components:

```java
public void setMinimalHud(Player player) {
    player.getHudManager().setVisibleHudComponents(player.getPlayerRef(),
        HudComponent.Hotbar,
        HudComponent.Health,
        HudComponent.Reticle
    );
}
```

### Builder Mode HUD

Show builder-specific components:

```java
public void enableBuilderHud(Player player) {
    HudManager hud = player.getHudManager();
    hud.showHudComponents(player.getPlayerRef(),
        HudComponent.BuilderToolsLegend,
        HudComponent.BuilderToolsMaterialSlotSelector,
        HudComponent.BlockVariantSelector
    );
}
```

## Best Practices

{{< callout type="info" >}}
**HUD Guidelines:**
- Always use `PlayerRef` when calling HUD methods
- Store previous state before clearing if you need to restore later
- Consider game mode when deciding which components to show
- Use `resetHud()` to return to default state
{{< /callout >}}

{{< callout type="warning" >}}
**Performance Note:** Avoid rapid toggling of HUD components as each change sends packets to the client.
{{< /callout >}}