> ## Documentation Index
> Fetch the complete documentation index at: https://entities.lodemc.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](https://entities.lodemc.net/gui.md) can paint a custom image over the whole chest window — the usual "custom GUI" trick. LodeEntities 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

Create `plugins/LodeEntities/gui/` (the plugin doesn't make it for you), drop a `.png` in it 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 `lodeentities:gui`.

Size the image the way you want it drawn: with `height: -1` it renders at its own pixel size, one texture pixel per GUI pixel. A 6-row chest window is **176×222** px; the bundled default is **182×140**, a frame over the chest half of the window.

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

The overlay paints the **window**; buttons are items, which a font glyph can't draw, so they go through a separate route. With `item-icons: true`, every button in the menu, the editor, the gear screen and the anvil prompt is repainted from `plugins/LodeEntities/gui/items/<name>.png`. **All of them are bundled**, so the buttons are textured on a plain install; drop your own file of the same name to replace one.

Each button is a plain vanilla item with a custom model data number of its own:

| File | Button | Item |
| :- | :- | :- |
| `createnew.png` | New entity | `nether_star` + `781` |
| `search.png` | Search | `name_tag` + `782` |
| `model.png` | Editor: Model | `armor_stand` + `783` |
| `baseentity.png` | Editor: Base entity | `spawner` + `784` |
| `prev.png` | Previous page (every menu) | `arrow` + `785` |
| `next.png` | Next page (every menu) | `arrow` + `786` |
| `back.png` | Back (editor and gear screen) | `creeper_banner_pattern` + `787` |
| `clear.png` | Clear filter | `barrier` + `788` |
| `confirm.png` | Anvil prompt: apply | `name_tag` + `789` |
| `invalid.png` | Anvil prompt: value not accepted | `barrier` + `790` |
| `display.png` | Editor: Display name | `name_tag` + `791` |
| `type.png` | Editor: Type | `emerald` + `792` |
| `dialog.png` | Editor: Dialog | `writable_book` + `793` |
| `look.png` | Editor: Looks at players | `ender_eye` + `794` |
| `health.png` | Editor: Health | `golden_apple` + `795` |
| `damage.png` | Editor: Attack damage | `iron_sword` + `796` |
| `armor.png` | Editor: Armor | `iron_horse_armor` + `797` |
| `speed.png` | Editor: Movement speed | `sugar` + `798` |
| `scale.png` | Editor: Scale | `slime_ball` + `799` |
| `glowing.png` | Editor: Glowing | `glowstone_dust` + `800` |
| `gravity.png` | Editor: Gravity | `feather` + `801` |
| `invulnerable.png` | Editor: Invulnerable | `totem_of_undying` + `802` |
| `persistent.png` | Editor: Persistent | `lodestone` + `803` |
| `namevisible.png` | Editor: Name always visible | `oak_sign` + `804` |
| `ai.png` | Editor: AI | `redstone_torch` + `805` |
| `silent.png` | Editor: Silent | `music_disc_11` + `806` |
| `collidable.png` | Editor: Collidable | `piston` + `807` |
| `invisible.png` | Editor: Invisible | `glass` + `808` |
| `pickup.png` | Editor: Picks up items | `hopper` + `809` |
| `knockbackresistance.png` | Editor: Knockback resistance | `anvil` + `810` |
| `followrange.png` | Editor: Follow range | `lead` + `811` |
| `attackknockback.png` | Editor: Attack knockback | `stick` + `812` |
| `faction.png` | Editor: Faction | `piglin_banner_pattern` + `813` |
| `child.png` | Editor: Child | `wheat` + `814` |
| `growsinto.png` | Editor: Grows into | `egg` + `815` |
| `growtime.png` | Editor: Grow time | `bone_meal` + `816` |
| `equipment.png` | Editor: Equipment | `armor_stand` + `817` |
| `dropchance.png` | Gear screen: drop chance, slot filled | `lime_dye` + `818` |
| `dropchanceempty.png` | Gear screen: drop chance, slot empty | `gray_dye` + `819` |

Spawn eggs and the gear screen's worn items show the real item, so they are never repainted. Buttons without art of their own carry `777`, which falls through to the item's ordinary model.

* **Each button owns its number**, because materials repeat: Search and Display name are both name tags, so a shared number would repaint both.
* **Size icons 16x16 or 32x32.** A sprite that isn't a power-of-two square renders as the missing-texture checkerboard, so other sizes are padded (never stretched) up to the next power of two, with a console line saying so.
* `gui/items/` is a **subfolder** of `gui/`, and only files directly in `gui/` become window overlays. Putting `createnew.png` in `gui/` itself would bake it as a title glyph instead.

> [!WARNING]
>
> Binding a texture to a vanilla item means the pack ships that item's definition, for example `assets/minecraft/items/nether_star.json`, which **replaces** vanilla's own. Ordinary nether stars still look ordinary, and another plugin's custom item on the same material with a different number keeps its own look. But if another pack writes the same path, whichever is applied last wins. Turn `item-icons` off to leave the buttons as plain items and bind the textures in your own pack instead.

This is written to the modern pack only: item definitions don't exist in the formats older clients use.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.