# 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. |
---
### renderText
```java
void renderText(Player player, String reference, String text, float x, float y, int layer, float scale, HorizontalAlignment horizontalAlignment, VerticalAlignment verticalAlignment, TextAlignment textAlignment)
void renderText(Player player, String reference, String text, float x, float y, int layer, float scale, float alpha, HorizontalAlignment horizontalAlignment, VerticalAlignment verticalAlignment, TextAlignment textAlignment)
older implementations render fully opaque. renderText(player, reference, text, x, y, layer, scale, horizontalAlignment, verticalAlignment, textAlignment)
void renderText(Player player, String reference, Component component, float x, float y, int layer, float scale, HorizontalAlignment horizontalAlignment, VerticalAlignment verticalAlignment, TextAlignment textAlignment)
void renderText(Player player, String reference, Component component, float x, float y, int layer, float scale, float alpha, HorizontalAlignment horizontalAlignment, VerticalAlignment verticalAlignment, TextAlignment textAlignment)
older implementations render fully opaque. renderText(player, reference, component, x, y, layer, scale, horizontalAlignment, verticalAlignment, textAlignment)
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)
```
Renders text on the player's HUD.
Plain strings are converted to JSON text components. MiniMessage and JSON strings are sent as-is.
Renders text on the player's HUD with a uniform opacity applied to the whole element.
| Parameter | Type |
Renders a Kyori Adventure Component on the player's HUD.
The component is serialized to JSON for the client to parse.
Renders a Component on the player's HUD with a uniform opacity applied to the whole element.
| Parameter | Type |
Renders text with a fade envelope.
Renders a Component with a fade envelope.
---
### moveTexture
```java
void moveTexture(Player player, String reference, float toX, float toY, long durationMillis, HudEasing easing)
```
Glides a texture element to a new position.
| Parameter | Type |
|---|---|
| `player` | `Player` |
| `reference` | `String` |
| `toX` | `float` |
| `toY` | `float` |
| `durationMillis` | `long` |
| `easing` | `HudEasing` |
---
### moveHead
```java
void moveHead(Player player, String reference, float toX, float toY, long durationMillis, HudEasing easing)
```
Glides a head element to a new position.
| Parameter | Type |
|---|---|
| `player` | `Player` |
| `reference` | `String` |
| `toX` | `float` |
| `toY` | `float` |
| `durationMillis` | `long` |
| `easing` | `HudEasing` |
---
### moveText
```java
void moveText(Player player, String reference, float toX, float toY, long durationMillis, HudEasing easing)
```
Glides a text element to a new position.
| Parameter | Type |
|---|---|
| `player` | `Player` |
| `reference` | `String` |
| `toX` | `float` |
| `toY` | `float` |
| `durationMillis` | `long` |
| `easing` | `HudEasing` |
---
### movePlayer
```java
void movePlayer(Player player, String reference, float toX, float toY, long durationMillis, HudEasing easing)
```
Glides a player bust element to a new position.
service from the player's name; the layout editor replaces it. This does
nothing.
| Parameter | Type |
|---|---|
| `player` | `Player` |
| `reference` | `String` |
| `toX` | `float` |
| `toY` | `float` |
| `durationMillis` | `long` |
| `easing` | `HudEasing` |
---
### showBadge
```java
void showBadge(Player player, AnnouncementBadge badge)
```
Shows an announcement badge, the centre-screen trapezoid banner.
**Deprecated.** The client no longer draws badges, so this does nothing. It stays callable while the plugins that use it are moved onto layouts, which can express the same banner and a good deal more. Expect it to go once they have.
---
### hideBadge
```java
void hideBadge(Player player)
void hideBadge(Player player, String id)
```
Plays the badge's closing sweep.
**Deprecated.** Badges are retired; this does nothing. See `showBadge`.
---
### animateHudGroup
```java
void animateHudGroup(Player player, String refPrefix, HudAnimation animation)
```
Applies a group animation to every HUD element whose reference starts with
`refPrefix`, current and future, so ordering against ADDs doesn't matter.
Component elements are prefixed `":"`; prefer the
`IPacketComponentManager` overloads for those.
| Parameter | Type |
|---|---|
| `player` | `Player` |
| `refPrefix` | `String` |
| `animation` | `HudAnimation` |
---
### fadeOutHudGroup
```java
void fadeOutHudGroup(Player player, String refPrefix, int fadeOutMs)
```
Fades every element with the prefix out over `fadeOutMs` and removes them.
| Parameter | Type |
|---|---|
| `player` | `Player` |
| `refPrefix` | `String` |
| `fadeOutMs` | `int` |
---
### setAnchor
```java
void setAnchor(Player player, WorldAnchor anchor)
```
Pins a marker to a point in the world for this player, replacing any anchor with the same
id, which is how a marker on something that moves is kept current.
| Parameter | Type |
|---|---|
| `player` | `Player` |
| `anchor` | `WorldAnchor` |
---
### removeAnchor
```java
void removeAnchor(Player player, String id)
```
Unpins a marker. Any groups the anchor was positioning are left on screen: an anchor and
the elements it positions have separate lifetimes, so one can be removed without tearing
down the other.
| Parameter | Type |
|---|---|
| `player` | `Player` |
| `id` | `String` |
---
### clearAnchors
```java
void clearAnchors(Player player)
```
Removes every anchor for this player.
| Parameter | Type |
|---|---|
| `player` | `Player` |
---
### renderShape
```java
void renderShape(Player player, HudShape shape)
```
Draws a solid, rectangle, circle, triangle and the rest. Re-sending the same reference
replaces it, and it groups, fades and moves like any other HUD element.
| Parameter | Type |
|---|---|
| `player` | `Player` |
| `shape` | `HudShape` |
---
### removeShape
```java
void removeShape(Player player, String reference)
```
Removes a shape by reference.
| Parameter | Type |
|---|---|
| `player` | `Player` |
| `reference` | `String` |
---
### moveShape
```java
void moveShape(Player player, String reference, float x, float y, int durationMs, HudEasing easing)
```
Glides a shape to a new position over `durationMs`, easing as named. Zero snaps.
| Parameter | Type |
|---|---|
| `player` | `Player` |
| `reference` | `String` |
| `x` | `float` |
| `y` | `float` |
| `durationMs` | `int` |
| `easing` | `HudEasing` |
---
### playLayout
```java
void playLayout(Player player, HudLayout layout)
```
Plays an editor-authored layout, and pushes any variables it carries.
A layout with no JSON replays one the client already holds under that id, so a screen
shown repeatedly is sent in full once.
| Parameter | Type |
|---|---|
| `player` | `Player` |
| `layout` | `HudLayout` |
---
### stopLayout
```java
void stopLayout(Player player, String id)
```
Takes a layout off screen.
| Parameter | Type |
|---|---|
| `player` | `Player` |
| `id` | `String` |
---
### stopLayouts
```java
void stopLayouts(Player player)
```
Takes every layout off screen.
| Parameter | Type |
|---|---|
| `player` | `Player` |
---
### setLayoutVariable
```java
void setLayoutVariable(Player player, String name, String value)
```
Sets a single `%token%` value without replaying a layout, the update path for a
value that changes while a screen is up.
| Parameter | Type |
|---|---|
| `player` | `Player` |
| `name` | `String` |
| `value` | `String` |
---
### setLayoutVariables
```java
void setLayoutVariables(Player player, java.util.Map<String, String> variables)
```
Sets several at once, which is one packet rather than one per value.
| Parameter | Type |
|---|---|
| `player` | `Player` |
| `java.util.Map<String` | `` |
| `variables` | `String>` |
---
### clearLayoutVariables
```java
void clearLayoutVariables(Player player)
```
Clears every layout variable.
| Parameter | Type |
|---|---|
| `player` | `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()`