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.

// 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

// 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

// 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

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

// 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.

// 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

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

• hudRenderer namespace

• Defining Settings

• Example: PlayerInfo