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

# Images and resource packs

You can place static PNG images and animated GIFs in your menus to create panel backgrounds, header logos, icon buttons, and decorative accents. All source image files live under `plugins/ArcMenu/images/`, and ArcMenu packages them into your server resource pack automatically.

## Storing and referencing images

You can organize your assets into subdirectories inside `images/` however you like. Folder names and filenames may use lowercase English letters (`a`–`z`), digits (`0`–`9`), underscores (`_`), hyphens (`-`), and periods (`.`).

When referencing an image in a menu configuration, treat `images/` as the root directory and start the `source` path with `/`:

| File path on disk                            | `source` in menu YAML  |
| -------------------------------------------- | ---------------------- |
| `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` |
| `plugins/ArcMenu/images/ui/banner.gif`       | `/ui/banner.gif`       |

Here is an example of a static PNG image element in `frontend`:

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

Field details:

* `type`: Use `image` for static PNGs, or `gif` for animated GIFs (see [Animated GIFs](/en/feature-configuration/gif.md) for GIF options).
* `source`: Image path starting with `/`, ending in `.png` or `.gif`.
* `width` and `height`: Display width and height on the menu canvas, specified as positive numbers greater than `0`. If you omit either dimension, it defaults to the original pixel dimension of the source image.
* `opacity`: Optional opacity from `0` to `255`, where `255` is fully opaque.
* `color`: Optional hex color tint formatted as `'#RRGGBB'` or `'&#RRGGBB'`.

Mouse cursor textures and 9-slice tooltip skins are also stored in `images/`; see [Touch, Mouse and Vision input](/en/feature-configuration/input-modes.md) and [Tooltips](/en/feature-configuration/tooltips.md) for their configuration.

## Switching images dynamically

`source` accepts PlaceholderAPI placeholders, and pairing it with an `update` interval lets you swap images dynamically based on a player's live status:

```yaml
frontend:
  rank-badge:
    type: image
    source: /ranks/%player_rank%.png
    update: 20
```

Set `update` to a positive integer in game ticks (`20` ticks is roughly 1 second), or `-1` to resolve the path once when the menu opens. Make sure every image file that the placeholder can resolve to (such as `/ranks/vip.png` and `/ranks/admin.png`) is placed in `images/` ahead of time and built into the resource pack.

## Generating and merging resource packs

Whenever you add, replace, or delete images, cursors, or tooltip skins, regenerate the resource pack and distribute the updated pack to connected clients.

### Integration with custom content plugins

When CraftEngine, Nexo, or ItemsAdder is installed on the server, those plugins automatically pull in and merge ArcMenu's generated assets whenever they build their resource pack.

* When you modify assets or install a package containing textures through the in-game visual editor or project manager, ArcMenu automatically asks the active plugin to rebuild the resource pack, checking in the order **CraftEngine → Nexo → ItemsAdder**.
* When you add or replace files in `images/` manually on disk, first run `/arcmenu resources` (or `/arcmenu reload all`) to generate ArcMenu's resource output, then run your content plugin's pack command:
  * **CraftEngine**: `/ce reload pack` (or `/ce reload all`)
  * **Nexo**: `/nexo reload pack`
  * **ItemsAdder**: `/iazip`

If more than one resource-pack plugin is installed on the same server, have only one of them host and send the final merged resource pack so clients do not receive duplicate pack prompts.

### Standalone generation and external hosting

On servers without those plugins, running `/arcmenu reload all` or `/arcmenu resources` builds a complete standalone resource pack at:

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

You can upload this ZIP to a file host and configure its URL in `server.properties`, or merge it with another pack tool (preserving the entire `assets/arcmenu/` directory and the overlay entries in `pack.mcmeta`). If you only edited coordinates or text in your menu YAML files without changing any image assets, `/arcmenu reload` applies your changes without rebuilding the pack.

## Manual client installation and load detection

Instead of automatic server delivery, players can also place `arcmenu-resourcepack.zip` into their client's local `resourcepacks` folder and enable it manually. Whenever the server updates its images or cursor settings, regenerate the ZIP and have players replace their local copy.

In `config.yml`, `mouse.assume-resource-pack-loaded` controls how Mouse mode checks whether the client has the companion resource pack ready:

```yaml
mouse:
  assume-resource-pack-loaded: true
```

This setting accepts `true` or `false` and defaults to **`true`**:

* When set to **`true`**: ArcMenu trusts that the client has the companion resource pack enabled. Even if the player installed the pack manually in their local `resourcepacks` folder and the client never sent a server resource-pack load acknowledgement packet, Mouse mode enables menu depth, fixed FOV, flat lighting, the local cursor, and local GIF animations right away.
* When set to **`false`**: Mouse mode waits until the server receives a resource-pack load success acknowledgement from the client. While the pack is still loading—or if loading fails—visual and cursor features that depend on the companion pack remain disabled.

This option only governs how Mouse mode checks for companion pack readiness. Touch mode uses standard in-world rendering, while Vision mode and the independent editor preview use the dedicated renderer and native cursor built into ArcMenu Editor on the client. Across all modes, custom menu images and custom fonts still require the client to have the resource pack loaded.

## Asset dimensions and format limits

To keep menu visuals crisp while keeping client memory usage reasonable, files in `images/` follow these specifications:

* **Static PNGs**: Full alpha transparency is supported. Each image must be between `1` and `4096` pixels wide and high, with a maximum file size of `16 MiB` per PNG. The `images/` directory supports up to `4096` images and frame glyphs in total, up to a combined source size of `128 MiB`.
* **Automatic font-atlas scaling**: Minecraft font atlases cap individual glyph bitmaps at `256` pixels per side. When you use a high-resolution PNG wider or taller than `256` pixels, ArcMenu automatically generates an atlas-compatible scaled bitmap inside the resource pack while keeping the exact display dimensions you configured in the menu; your original file in `images/` is never modified.
* **Animated GIFs**: Each GIF file can be up to `16 MiB`, with dimensions up to `4096` pixels, up to `1024` frames, and up to `16,777,216` total decoded canvas pixels per file. During resource generation, decoded frame sequences are written directly into the generated ZIP package, leaving only the original `.gif` file in `images/`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.myarc.icu/en/feature-configuration/resource-packs.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.