> For the complete documentation index, see [llms.txt](https://simple.superiormc.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://simple.superiormc.cn/arcmenu-wiki/feature-configuration/resource-packs.md).

# Images and resource packs

Custom images can provide backgrounds, logos, buttons and decoration. Image files live on the server, and ArcMenu builds them into a resource pack. Players must load that pack to display the images correctly.

This page applies to Paper, Folia, Leaf and similar servers. Spigot does not support custom images, ArcMenu pack generation or CraftEngine resource merging.

## Preparing images

Place PNG files in `plugins/ArcMenu/images/`. Organize them in subdirectories if needed, for example:

```
plugins/ArcMenu/images/ui/logo.png
plugins/ArcMenu/images/ui/background.png
plugins/ArcMenu/images/buttons/confirm.png
```

### File and path requirements

* Use valid PNG files; transparent backgrounds are supported. Renaming a JPEG or another format to `.png` does not convert it.
* Use lowercase English letters, digits, underscores, hyphens or dots for file and directory names. Avoid spaces and non-English names.
* Menu references start with `/`, end with `.png` and use `/` between directories.
* Do not use `.` or `..` as directory names or consecutive `//` separators.
* `source` refers to a local image. It does not accept web links or full server filesystem paths.

Menu paths are relative to the `images/` directory:

| Server image                                 | Menu `source`          |
| -------------------------------------------- | ---------------------- |
| `plugins/ArcMenu/images/example.png`         | `/example.png`         |
| `plugins/ArcMenu/images/ui/logo.png`         | `/ui/logo.png`         |
| `plugins/ArcMenu/images/buttons/confirm.png` | `/buttons/confirm.png` |

### Image limits

| Property                 | Limit                                     |
| ------------------------ | ----------------------------------------- |
| Image width and height   | Each dimension from `1` to `4096` pixels. |
| Individual PNG file size | At most `16 MiB`.                         |
| Combined PNG file size   | At most `128 MiB`.                        |
| PNG file count           | At most `4096`.                           |

These limits cover all PNG files in the image directory, including bundled files and subdirectories. Prepare images for their intended display size rather than using unnecessarily large artwork.

## Referencing images in menus

Image elements belong under `frontend` and use `type: image`:

```yaml
frontend:
  server-logo:
    type: image
    source: /ui/logo.png
    width: 96
    height: 32
    offset: {x: 0, y: 40, z: 1}
```

Merge this fragment into an existing menu's `frontend` and provide `images/ui/logo.png`.

`width` and `height` are display dimensions on the canvas. They do not modify the original PNG. Set them independently; an omitted dimension uses the corresponding original pixel dimension. Preserve the original aspect ratio to avoid stretching.

See [Frontend element types](/arcmenu-wiki/menu-configuration/menus/frontend.md#image-image) for opacity, tint and shared placement properties, and [Canvas, coordinates and screen placement](/arcmenu-wiki/menu-configuration/menus/canvas.md) for units and coordinates.

An image only supplies visible content. To use it as a button, create a matching hit region in `backend`.

### Dynamic images

Paper-family servers allow placeholders in `source` and periodic path updates through the image's `update` setting. Add every potential image to the directory and generated pack in advance. Expanded paths must also follow the rules above.

`update` selects which image path to display. It does not read an edited PNG from disk or send a resource pack to players. Changing image content still requires the update workflow below.

## Building and updating resources

After preparing images, the recommended commands are:

```
/arcmenu validate
/arcmenu reload all
```

They require `arcmenu.admin` and work in-game or in the console. Omit the leading `/` in the console.

| Command               | Purpose                                                                          |
| --------------------- | -------------------------------------------------------------------------------- |
| `/arcmenu validate`   | Checks configuration without building a pack.                                    |
| `/arcmenu reload`     | Reloads configuration without rebuilding image resources.                        |
| `/arcmenu reload all` | Reloads configuration and templates, then rebuilds the pack.                     |
| `/arcmenu resources`  | Rebuilds the pack using loaded configuration without rereading menu definitions. |

Use `reload all` when editing both menu files and images. Use `resources` when only image files changed and configuration does not need reloading.

The generated ZIP is:

```
plugins/ArcMenu/generated/arcmenu-resourcepack.zip
```

ArcMenu generates the contents of `generated/`; it is not a source artwork directory. Direct edits to generated resources are overwritten by the next build.

## Distributing the pack

Building the pack and loading it on clients are separate steps. A successful build does not mean players have received the updated content. Continue with your server's distribution method.

### Without CraftEngine

1. Run `/arcmenu reload all` and confirm that the build succeeds.
2. Upload `arcmenu-resourcepack.zip` to your resource pack host or process it through your existing pack tools.
3. Update the download URL and any required verification information in your server's pack distribution settings.
4. Have players accept and load the updated pack, then reopen the menu to check it.

The URL should download the ZIP directly. Avoid links requiring sign-in or displaying only a download webpage. ArcMenu does not host or send this file automatically.

If your server already has a pack, use your existing merge workflow to include the complete ArcMenu resources. Copying only the original PNG files is insufficient. Preserve the pack's root structure and resolve conflicting filenames, then distribute the merged result.

### With CraftEngine

After changing menu images or related configuration, run these commands in order:

```
/arcmenu reload all
/ce reload all
```

Wait for ArcMenu to finish successfully before rebuilding the CraftEngine pack. When the integration works, CraftEngine merges ArcMenu resources into its own pack.

Use your existing CraftEngine pack distribution setup to have players load the new merged pack. Players need the updated result rather than the previous pack.

If the log reports a merge failure, fix it before rebuilding and distributing again. A CraftEngine reload completion message alone does not establish that ArcMenu images were included.

## Mouse, tooltips and resource updates

Mouse mode needs the accompanying resources even for menus containing only text and vanilla items.

After changing cursor images, sensitivity, size or related screen settings, rebuild the pack and have players update it. See [Touch and mouse input](/arcmenu-wiki/feature-configuration/input-modes.md) for those settings.

Tooltip images also belong in `images/`. New or replacement image skins require rebuilding and distributing resources. See [Tooltips](/arcmenu-wiki/feature-configuration/tooltips.md) for settings and reload requirements.

## Troubleshooting display

| Symptom                                         | What to check                                                                                                                         |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Image is invisible                              | Check that the PNG referenced by `source` exists, its path and filename match, and resources were rebuilt. Missing images are hidden. |
| Boxes, unexpected characters or the wrong image | Confirm that the player loaded the latest pack containing current ArcMenu content and that merged resources are complete.             |
| Edited PNG still displays the old image         | Rebuild, update the hosted or merged pack and have players load it. `reload` alone does not update images.                            |
| Stretched image                                 | Compare the original aspect ratio with the element's `width`, `height` and `scale`.                                                   |
| Resource build fails                            | Follow the error message to check PNG format, lowercase paths, dimensions and size limits.                                            |
| Dynamic image disappears after switching        | Check the expanded placeholder path and whether its image was included in the generated pack.                                         |
| CraftEngine pack lacks menu images              | Check merge errors, rebuild ArcMenu before CraftEngine and confirm the player loaded the new merged pack.                             |

Test with the bundled `/example.png` first to check the pack, then investigate custom artwork. Cover the actual client versions allowed on your server. Client loading and the merged pack's appearance require in-game verification.