> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nmentities.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Menu Overlay

> Paint a custom image over the Entities menu, baked into the generated pack.

The [Entities menu](gui) can paint a custom image over the whole chest window — the usual "custom GUI" trick. NMEntities does it by baking your image into the generated resource pack as a font glyph and carrying it as the first character of the menu's title.

A default ships with the plugin and is baked in automatically, so a plain install already has one. Nothing to set up unless you want your own.

## Using your own image

Drop a `.png` into `plugins/NMEntities/gui/` and reload.

* Name it **`category.png`** to replace the bundled default.
* Name it anything else to **add** one, then point `menu-texture` at it.

Each image in that folder becomes a character in the font `nmentities:gui`.

## Options

All under `gui-overlay` in [`config.yml`](config-reference):

| Option         | Default    | What it does                                                                                                                                         |
| :------------- | :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`      | `true`     | Master switch. Off writes no font to the pack and leaves titles as plain text.                                                                       |
| `menu-texture` | `category` | Which image paints over the menu — the bundled default, or `gui/<name>.png`. Naming one that does not exist logs a warning and leaves a plain title. |
| `ascent`       | `18`       | Pixels the glyph is raised above the title's baseline. Larger moves the image **up**. Whole numbers only.                                            |
| `height`       | `140`      | Rendered height in pixels, applied to every overlay image. `-1` renders each image at its own height instead.                                        |
| `offset-x`     | `-11`      | Pixels the glyph is nudged sideways. More negative moves it **left**.                                                                                |
| `item-icons`   | `true`     | Repaint the menu buttons from `gui/items/<name>.png`.                                                                                                |

## Getting the position right

Two numbers do the work, and both have a meaningful zero:

* **`ascent: 13`** lines the glyph's top edge up with the chest window's. The bundled art sits 5px above that, which is where `18` comes from.
* **`offset-x: -8`** sits flush with the window's left edge, because the title starts 8px inside the GUI. The bundled art has 3px of its own margin, hence `-11`.

`height: 140` is the bundled `category.png`'s own height, so it draws one texture pixel per GUI pixel. Once you add images of different sizes, `-1` is usually what you want.

The label never drifts with the image: the rewind space is derived from `offset-x`, so the two always cancel out.

## Button textures

With `item-icons: true`, the menu's buttons are repainted from `plugins/NMEntities/gui/items/<name>.png`. `createnew.png` is bundled, for the **New entity** button.

Each button is a vanilla item carrying custom model data `777`, so binding a texture to one means the pack must ship an item definition for that vanilla item — for example `assets/minecraft/items/nether_star.json` for the New entity button.

<Warning>
  That file **replaces** vanilla's own. A second pack writing the same path wins over this one. Plain nether stars still render normally either way — only the custom-model-data variant is affected.
</Warning>

Turn `item-icons` off to leave the buttons as plain items and bind the textures in your own pack instead.

## Players without the pack

A client that has not received the resource pack cannot see the glyph and renders a missing-character box in front of the title. The title text itself stays perfectly readable either way.

If your players do not receive a pack at all, set `enabled: false` and the menu is plain text with no stray box.