> For the complete documentation index, see [llms.txt](https://walksy.gitbook.io/walksylib-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://walksy.gitbook.io/walksylib-docs/advanced/hud-elements.md).

# Hud Elements

WalksyLib can manage your HUD elements for you. Users drag and scale them in the **Edit HUD** screen, positions are saved automatically, and elements are drawn for you.

## 1. Implement `HudElement`

```java
public final class CounterHud implements HudElement {
    @Override
    public void render(WLGraphics2D graphics, float x, float y, float scale, boolean editing) {
    }

    @Override
    public float width(float scale) {
        return 40 * scale;
    }

    @Override
    public float height(float scale) {
        return 12 * scale;
    }
}
```

`editing` is `true` while the user is currently on the Edit HUD screen. 

Optional overrides:

| Method                                  | Default | Purpose                             |
| --------------------------------------- | ------- | ----------------------------------- |
| `visible()`                             | `true`  | Return `false` to hide the element  |
| `scaleStep()`                           | `0.1`   | How much each scroll step scales it |
| `defaultOffsetX()` / `defaultOffsetY()` | `0`     | Starting position                   |

## 2. Attach it to an option

Attach the element to any option with `.hudSpace(name, element)`:

```java
Options.ofBoolean("Show Counter", () -> showCounter, true, value -> showCounter = value)
    .hudSpace("Counter", new CounterHud())
    .build();
```

Or add it as its own row with an "Edit HUD" entry:

```java
Options.ofHudSpace("Counter", new CounterHud()).build();
```

To only show it while a condition holds, wrap it with `HudElements.when`:

```java
.hudSpace("Counter", HudElements.when(() -> showCounter, new CounterHud()))
```

Pixel grid animation options have a built-in renderer, so they only need a name: `.hudSpace("Crosshair")`, or `.hudSpace("Crosshair", () -> showCrosshair)`.

## Holding a reference

If you need the element's position or scale elsewhere, create the `HudSpace` yourself and pass it to an option:

```java
public static final HudSpace COUNTER = WalksyLib.getInstance().getHudSpaces().create("Counter", new CounterHud());

Options.ofHudSpace(COUNTER).build();
```

{% hint style="warning" %}
A `HudSpace` created with `create(...)` but never passed to an option is not registered. It won't be drawn, it won't appear in Edit HUD, and its position won't be saved
{% endhint %}