# IHUDManager
> Manages HUD rendering effects for players running the Lectern client.
`gg.lode.lecternapi.api.manager.IHUDManager`
---
## Signature
```java
public interface IHUDManager
```
---
## Enums
### HorizontalAlignment
```java
IHUDManager.HorizontalAlignment
```
| Value | Description |
|---|---|
| `LEFT` | Align to the left edge. |
| `CENTER` | Align to the horizontal center. |
| `RIGHT` | Align to the right edge. |
### VerticalAlignment
```java
IHUDManager.VerticalAlignment
```
| Value | Description |
|---|---|
| `TOP` | Align to the top edge. |
| `CENTER` | Align to the vertical center. |
| `BOTTOM` | Align to the bottom edge. |
### TextAlignment
```java
IHUDManager.TextAlignment
```
| Value | Description |
|---|---|
| `AUTO` | Automatically aligns text based on the horizontal alignment. |
| `LEFT` | Left-align text. |
| `CENTER` | Center-align text. |
| `RIGHT` | Right-align text. |
### HudEasing
```java
gg.lode.lecternapi.api.hud.HudEasing
```
Easing curves for [[#Move Animations|move animations]].
| Value | Description |
|---|---|
| `LINEAR` | Constant speed. |
| `EASE_IN` | Starts slow, accelerates. |
| `EASE_OUT` | Starts fast, decelerates. |
| `EASE_IN_OUT` | Slow at both ends. |
### HudElement
```java
gg.lode.lecternapi.api.hud.HudElement
```
Individual vanilla HUD pieces that can be hidden on their own — see [[#Hiding Vanilla HUD Elements]].
| Value | Description |
|---|---|
| `HEARTS` | The health bar. |
| `HUNGER` | The food bar. |
| `HOTBAR` | The hotbar and its item slots. |
| `ARMOR` | The armour bar. |
| `OXYGEN` | The air bubbles shown underwater. |
| `EXPERIENCE` | The experience bar and level number. |
---
## Methods
### renderTexture
```java
void renderTexture(Player player, String reference, String textureId, float x, float y, int layer, float width, float height, float alpha, HorizontalAlignment horizontalAlignment, VerticalAlignment verticalAlignment)
```
Renders a texture on the player's HUD.
| Parameter | Type | Description |
|---|---|---|
| `player` | `Player` | The target player. |
| `reference` | `String` | A unique identifier for this texture element. |
| `textureId` | `String` | The texture identifier (e.g. `"namespace:path"`). |
| `x` | `float` | Horizontal position. |
| `y` | `float` | Vertical position. |
| `layer` | `int` | The render layer (z-index). |
| `width` | `float` | The texture width. |
| `height` | `float` | The texture height. |
| `alpha` | `float` | The opacity (0.0 to 1.0). |
| `horizontalAlignment` | `HorizontalAlignment` | Horizontal alignment. |
| `verticalAlignment` | `VerticalAlignment` | Vertical alignment. |
---
### removeTexture
```java
void removeTexture(Player player, String reference)
```
Removes a rendered texture from the player's HUD.
| Parameter | Type | Description |
|---|---|---|
| `player` | `Player` | The target player. |
| `reference` | `String` | The unique identifier of the texture to remove. |
---
### renderHead
```java
void renderHead(Player player, String reference, String headUuid, float x, float y, int layer, float width, float height, HorizontalAlignment horizontalAlignment, VerticalAlignment verticalAlignment)
```
Renders a player head on the HUD.
| Parameter | Type | Description |
|---|---|---|
| `player` | `Player` | The target player. |
| `reference` | `String` | A unique identifier for this head element. |
| `headUuid` | `String` | The UUID of the player whose head to render. |
| `x` | `float` | Horizontal position. |
| `y` | `float` | Vertical position. |
| `layer` | `int` | The render layer. |
| `width` | `float` | The head width. |
| `height` | `float` | The head height. |
| `horizontalAlignment` | `HorizontalAlignment` | Horizontal alignment. |
| `verticalAlignment` | `VerticalAlignment` | Vertical alignment. |
---
### removeHead
```java
void removeHead(Player player, String reference)
```
Removes a rendered head from the player's HUD.
| Parameter | Type | Description |
|---|---|---|
| `player` | `Player` | The target player. |
| `reference` | `String` | The unique identifier of the head to remove. |
---
### renderPlayer
```java
void renderPlayer(Player player, String reference, String identifier, float x, float y, float width, float height, HorizontalAlignment horizontalAlignment, VerticalAlignment verticalAlignment)
```
Renders a player bust on the HUD.
| Parameter | Type | Description |
|---|---|---|
| `player` | `Player` | The target player. |
| `reference` | `String` | A unique identifier for this player element. |
| `identifier` | `String` | The username or UUID of the player to render. |
| `x` | `float` | Horizontal position. |
| `y` | `float` | Vertical position. |
| `width` | `float` | The render width. |
| `height` | `float` | The render height. |
| `horizontalAlignment` | `HorizontalAlignment` | Horizontal alignment. |
| `verticalAlignment` | `VerticalAlignment` | Vertical alignment. |
---
### removePlayer
```java
void removePlayer(Player player, String reference)
```
Removes a rendered player bust from the player's HUD.
| Parameter | Type | Description |
|---|---|---|
| `player` | `Player` | The target player. |
| `reference` | `String` | The unique identifier of the player element to remove. |
---
### startButtonOverlay
```java
void startButtonOverlay(Player player, float blur)
```
Starts the button overlay layer with an optional blur amount.
| Parameter | Type | Description |
|---|---|---|
| `player` | `Player` | The target player. |
| `blur` | `float` | The background blur amount. |
---
### stopButtonOverlay
```java
void stopButtonOverlay(Player player)
```
Stops the button overlay layer.
| Parameter | Type | Description |
|---|---|---|
| `player` | `Player` | The target player. |
---
### addButton
```java
void addButton(Player player, String reference, String textureId, int x, int y, int width, int height, float alpha, HorizontalAlignment horizontalAlignment, VerticalAlignment verticalAlignment)
```
Adds a button to the button overlay.
| Parameter | Type | Description |
|---|---|---|
| `player` | `Player` | The target player. |
| `reference` | `String` | A unique identifier for this button. |
| `textureId` | `String` | The button texture identifier. |
| `x` | `int` | Horizontal position. |
| `y` | `int` | Vertical position. |
| `width` | `int` | The button width. |
| `height` | `int` | The button height. |
| `alpha` | `float` | The opacity. |
| `horizontalAlignment` | `HorizontalAlignment` | Horizontal alignment. |
| `verticalAlignment` | `VerticalAlignment` | Vertical alignment. |
---
### removeButton
```java
void removeButton(Player player, String reference)
```
Removes a button from the button overlay.
| Parameter | Type | Description |
|---|---|---|
| `player` | `Player` | The target player. |
| `reference` | `String` | The unique identifier of the button to remove. |
---
### clearButtons
```java
void clearButtons(Player player)
```
Clears all buttons from the button overlay.
| Parameter | Type | Description |
|---|---|---|
| `player` | `Player` | The target player. |
---
### setLetterbox
```java
void setLetterbox(Player player, boolean enabled)
```
Enables or disables the letterbox (black bars) effect on the player's screen.
| Parameter | Type | Description |
|---|---|---|
| `player` | `Player` | The target player. |
| `enabled` | `boolean` | `true` to enable letterboxing. |
---
### setHudHidden
```java
void setHudHidden(Player player, boolean hidden)
```
Hides or shows the vanilla HUD on the player's screen.
| Parameter | Type | Description |
|---|---|---|
| `player` | `Player` | The target player. |
| `hidden` | `boolean` | `true` to hide the HUD. |
---
### setGuiScale
```java
void setGuiScale(Player player, int scale)
```
Overrides the GUI scale on the player's client.
| Parameter | Type | Description |
|---|---|---|
| `player` | `Player` | The target player. |
| `scale` | `int` | The GUI scale value. |
---
### resetGuiScale
```java
void resetGuiScale(Player player)
```
Resets the GUI scale to the player's default.
| Parameter | Type | Description |
|---|---|---|
| `player` | `Player` | The target player. |
---
### showSecondBar
```java
void showSecondBar(Player player, float progress, int red, int green, int blue, float alpha)
```
Displays a secondary progress bar on the player's HUD.
| Parameter | Type | Description |
|---|---|---|
| `player` | `Player` | The target player. |
| `progress` | `float` | The bar progress (0.0 to 100.0). |
| `red` | `int` | Red color component (0-255). |
| `green` | `int` | Green color component (0-255). |
| `blue` | `int` | Blue color component (0-255). |
| `alpha` | `float` | The opacity (0.0 to 1.0). |
---
### hideSecondBar
```java
void hideSecondBar(Player player)
```
Hides the secondary progress bar.
| Parameter | Type | Description |
|---|---|---|
| `player` | `Player` | The target player. |
---
### renderText (String)
```java
void renderText(Player player, String reference, String text, float x, float y, int layer, float scale, HorizontalAlignment horizontalAlignment, VerticalAlignment verticalAlignment, TextAlignment textAlignment)
```
Renders text on the player's HUD. Plain strings and MiniMessage strings are parsed through Adventure's MiniMessage parser and serialized to JSON server-side. JSON strings are sent as-is.
| Parameter | Type | Description |
|---|---|---|
| `player` | `Player` | The target player. |
| `reference` | `String` | A unique identifier for this text element. |
| `text` | `String` | The text content (plain string, MiniMessage format, or JSON text component). |
| `x` | `float` | Horizontal position. |
| `y` | `float` | Vertical position. |
| `layer` | `int` | The render layer (z-index). |
| `scale` | `float` | The text scale. |
| `horizontalAlignment` | `HorizontalAlignment` | Horizontal alignment. |
| `verticalAlignment` | `VerticalAlignment` | Vertical alignment. |
| `textAlignment` | `TextAlignment` | Text alignment within the element. |
---
### renderText (Component)
```java
void renderText(Player player, String reference, Component component, float x, float y, int layer, float scale, HorizontalAlignment horizontalAlignment, VerticalAlignment verticalAlignment, TextAlignment textAlignment)
```
Renders a Kyori Adventure Component on the player's HUD. The component is serialized to JSON for the client to parse.
| Parameter | Type | Description |
|---|---|---|
| `player` | `Player` | The target player. |
| `reference` | `String` | A unique identifier for this text element. |
| `component` | `Component` | The Adventure component to render. |
| `x` | `float` | Horizontal position. |
| `y` | `float` | Vertical position. |
| `layer` | `int` | The render layer (z-index). |
| `scale` | `float` | The text scale. |
| `horizontalAlignment` | `HorizontalAlignment` | Horizontal alignment. |
| `verticalAlignment` | `VerticalAlignment` | Vertical alignment. |
| `textAlignment` | `TextAlignment` | Text alignment within the element. |
---
### removeText
```java
void removeText(Player player, String reference)
```
Removes rendered text from the player's HUD.
| Parameter | Type | Description |
|---|---|---|
| `player` | `Player` | The target player. |
| `reference` | `String` | The unique identifier of the text to remove. |
---
### addItemCooldown
```java
void addItemCooldown(Player player, String id, int ticks)
```
Adds an item cooldown indicator on the player's HUD. Items with a matching `lodestone:cooldown` NBT tag will display a cooldown overlay.
| Parameter | Type | Description |
|---|---|---|
| `player` | `Player` | The target player. |
| `id` | `String` | The cooldown identifier (must match the item's `lodestone:cooldown` NBT value). |
| `ticks` | `int` | The duration in ticks. |
---
### removeItemCooldown
```java
void removeItemCooldown(Player player, String id)
```
Removes an item cooldown indicator from the player's HUD.
| Parameter | Type | Description |
|---|---|---|
| `player` | `Player` | The target player. |
| `id` | `String` | The cooldown identifier to remove. |
---
### clearItemCooldowns
```java
void clearItemCooldowns(Player player)
```
Clears all item cooldown indicators from the player's HUD.
| Parameter | Type | Description |
|---|---|---|
| `player` | `Player` | The target player. |
---
## Fade Envelopes
Every element type has an overload with three extra trailing parameters that animate its opacity client-side:
```java
void renderTexture(Player player, String reference, String textureId, float x, float y, int layer, float width, float height, float alpha, HorizontalAlignment horizontalAlignment, VerticalAlignment verticalAlignment, long fadeInMillis, long fadeOutMillis, long durationMillis)
void renderHead(Player player, String reference, String headUuid, float x, float y, int layer, float width, float height, float alpha, HorizontalAlignment horizontalAlignment, VerticalAlignment verticalAlignment, long fadeInMillis, long fadeOutMillis, long durationMillis)
void renderText(Player player, String reference, String text, float x, float y, int layer, float scale, float alpha, HorizontalAlignment horizontalAlignment, VerticalAlignment verticalAlignment, TextAlignment textAlignment, long fadeInMillis, long fadeOutMillis, long durationMillis)
void renderText(Player player, String reference, Component component, float x, float y, int layer, float scale, float alpha, HorizontalAlignment horizontalAlignment, VerticalAlignment verticalAlignment, TextAlignment textAlignment, long fadeInMillis, long fadeOutMillis, long durationMillis)
void renderPlayer(Player player, String reference, String identifier, float x, float y, int layer, float width, float height, float alpha, HorizontalAlignment horizontalAlignment, VerticalAlignment verticalAlignment, long fadeInMillis, long fadeOutMillis, long durationMillis)
```
| Parameter | Type | Description |
|---|---|---|
| `fadeInMillis` | `long` | Fade-in length when the element appears. `0` shows instantly. |
| `fadeOutMillis` | `long` | Fade-out length — plays before expiry *and* when the element is removed. `0` hides instantly. |
| `durationMillis` | `long` | Lifetime after which the element removes itself (fade-out finishes exactly at expiry). `0` keeps it until removed. |
Notes:
- All zeros behave exactly like the fade-less overloads.
- Calling `removeTexture` / `removeHead` / `removeText` / `removePlayer` on an element with a `fadeOutMillis` plays the fade-out first, then removes it.
- The head overload also introduces an `alpha` parameter — the plain `renderHead` renders fully opaque.
- Self-expiring elements (`durationMillis > 0`) are **not** re-sent on reconnect; permanent elements are.
---
## Move Animations
Glides an already-rendered element to a new position with a built-in easing curve. The coordinates are in the same space and alignment the element was rendered with.
```java
void moveTexture(Player player, String reference, float toX, float toY, long durationMillis, HudEasing easing)
void moveHead(Player player, String reference, float toX, float toY, long durationMillis, HudEasing easing)
void moveText(Player player, String reference, float toX, float toY, long durationMillis, HudEasing easing)
void movePlayer(Player player, String reference, float toX, float toY, long durationMillis, HudEasing easing)
```
| Parameter | Type | Description |
|---|---|---|
| `player` | `Player` | The target player. |
| `reference` | `String` | The reference of the element to move. |
| `toX` | `float` | Destination horizontal position. |
| `toY` | `float` | Destination vertical position. |
| `durationMillis` | `long` | Glide length. `0` snaps instantly. |
| `easing` | `HudEasing` | The easing curve. `null` falls back to `LINEAR`. |
Notes:
- Retargeting an element mid-move starts the new glide from its currently rendered position.
- Moves compose with [[#Fade Envelopes|fades]] — an element can glide while fading.
- Unknown references are ignored (the element may have expired client-side).
---
## Hiding Vanilla HUD Elements
Strips individual pieces of the vanilla HUD while leaving the rest drawing. Each element is suppressed at its own draw call, so nothing reflows — hiding hearts leaves the gap where they were.
### setHiddenHudElements
```java
void setHiddenHudElements(Player player, Set<HudElement> elements)
```
Hides the given elements and shows every other one. Full state, not a delta — pass the complete set each time. An empty set shows everything.
### setHudElementHidden
```java
void setHudElementHidden(Player player, HudElement element, boolean hidden)
```
Hides or shows a single element, leaving the others as they are.
### clearHiddenHudElements
```java
void clearHiddenHudElements(Player player)
```
Shows every HUD element again.
---
## Related Pages
- [[ILecternAPI]] — Access via `getHUDManager()`