> For the complete documentation index, see [llms.txt](https://scripting.breeze.rip/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://scripting.breeze.rip/hud_scripting.md).

# HUD Scripting

HUD scripts let you render custom 2D overlays on screen using the `hudManager` and `hudRenderer` namespaces. Elements are draggable in the HUD editor and their positions persist to config automatically.

***

## Render Pipeline

Each frame breeze renders scripted HUD elements in two passes:

1. **Background pass** — your `onBackground` callback returns a list of `RoundedRect` shapes. These are collected alongside all other HUD backgrounds and rendered together (with blur/shadow) before any content is drawn.
2. **Render pass** — your `onRender` callback runs. Use `hudRenderer` functions here to draw text, shapes, and items.

All drawing in both passes uses screen-space coordinates with the origin at the top-left corner (x right, y down). The `hudManager.x()` / `hudManager.y()` values give you the top-left corner of your element's current dragged position — offset everything you draw from those values.

***

## hudManager

Registers callbacks and exposes layout information for your element.

### Callbacks

All callbacks must be registered during script initialization.

```js
// Called every frame to draw your element's content.
// x, y, scale are passed in directly so you don't need to call hudManager.x() etc. inside the callback.
hudManager.onRender((x, y, scale) => {
    // use hudRenderer here
});

// Returns an array of RoundedRect shapes drawn as the blurred background.
hudManager.onBackground(() => {
    return [new RoundedRect(hudManager.x(), hudManager.y(), width, height, 4 * hudManager.scale())];
});

// Returns the pixel width of your element. Used by the HUD editor for snapping.
hudManager.onWidth(() => 160);

// Returns the pixel height of your element.
hudManager.onHeight(() => 40);
```

### Position & Layout

| Function                  | Returns  | Description                                                             |
| ------------------------- | -------- | ----------------------------------------------------------------------- |
| `hudManager.x()`          | `number` | Left edge of the element on screen                                      |
| `hudManager.y()`          | `number` | Top edge of the element on screen                                       |
| `hudManager.scale()`      | `number` | User-configured HUD scale (use this to scale padding, radii, and sizes) |
| `hudManager.fontHeight()` | `number` | Pixel height of the selected HUD font                                   |

`hudManager.x()`, `hudManager.y()`, and `hudManager.scale()` are also passed directly into `onRender` as `(x, y, scale)` — you only need to call these getters explicitly in `onBackground`, `onWidth`, or `onHeight`.

***

## hudRenderer

All drawing functions take absolute screen coordinates. Inside `onRender` use the `x` and `y` parameters passed to you; in other contexts call `hudManager.x()` / `hudManager.y()`.

### Text

```js
// Pixel width of a string in the current HUD font.
const w = hudRenderer.stringWidth("Hello");

// Draw text. Optional fifth argument enables a drop shadow.
hudRenderer.drawString(x, y, "Hello", new Color(255, 255, 255, 255));
hudRenderer.drawString(x, y, "Hello", new Color(255, 255, 255, 255), true);
```

### Rectangles

```js
// Solid color, uniform corner radius.
hudRenderer.drawRect(x, y, w, h, radius, color);

// Solid color, per-corner radii (TL, TR, BR, BL).
hudRenderer.drawRect(x, y, w, h, rtl, rtr, rbr, rbl, color);

// Two-color gradient. vertical=true → top-to-bottom, false → left-to-right.
hudRenderer.drawRectGradient(x, y, w, h, radius, color1, color2, vertical);

// Solid color with an outer glow. glowColor alpha controls max intensity.
hudRenderer.drawRectGlow(x, y, w, h, radius, color, glowRadius, glowColor);

// Uses the current HUD effect (rainbow / gradient / pulse / none). alpha is 0.0–1.0.
hudRenderer.drawRectWithEffect(x, y, w, h, radius, alpha);
```

### Circles

```js
hudRenderer.drawCircle(cx, cy, radius, color);

// Hollow ring.
hudRenderer.drawRing(cx, cy, radius, thickness, color);

// Uses the current HUD effect. alpha is 0.0–1.0.
hudRenderer.drawCircleWithEffect(cx, cy, radius, alpha);
```

### Items

```js
// Draw an ItemStack icon. size=16 is native resolution.
hudRenderer.drawItemStack(stack, x, y, size);

// With count and durability bar overlay.
hudRenderer.drawItemStack(stack, x, y, size, true);
```

***

## RoundedRect

Used exclusively in `onBackground` to describe the blurred background region.

```js
// Uniform radius
new RoundedRect(x, y, w, h, radius)

// Per-corner radii (TL, TR, BR, BL)
new RoundedRect(x, y, w, h, rtl, rtr, rbr, rbl)
```

***

## Minimal Example

```js
script.description = "Displays the player's health.";

const PAD = 6;

hudManager.onWidth(() => 120);
hudManager.onHeight(() => hudManager.fontHeight() + PAD * 2 * hudManager.scale());

hudManager.onBackground(() => {
    const s = hudManager.scale();
    return [new RoundedRect(hudManager.x(), hudManager.y(), 120, hudManager.fontHeight() + PAD * 2 * s, 4 * s)];
});

hudManager.onRender((x, y, scale) => {
    const pad = PAD * scale;

    const hp = mc.player != null ? Math.ceil(mc.player.getHealth()) : 0;
    hudRenderer.drawString(x + pad, y + pad, "Health: " + hp, new Color(255, 255, 255, 220), true);
});
```

***

## Tips

* **Scale everything** — multiply all padding, corner radii, and icon sizes by `hudManager.scale()` so the element looks right at any user scale.
* **Guard nulls** — `mc.player` and `mc.world` can be null (e.g. on the main menu). Check before accessing them.
* **Background vs content** — only use `onBackground` for the blurred rect outline. Decorations and text go in `onRender`.
* **Dynamic size** — `onWidth` / `onHeight` are called every frame, so you can return a value based on current content.

***

## See Also

* [hudManager namespace](/api/namespaces/hudmanager.md)
* [hudRenderer namespace](/api/namespaces/hudrenderer.md)
* [Defining Settings](/defining_settings.md)
* [Example: PlayerInfo](/examples/playerinfo.md)