> 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/gif.md).

# Animated GIFs

You can place `.gif` animations directly into menus as animated backgrounds, banners, icons, or decorations, or include them in Effect cutscenes. Just like standard PNG images, all source GIF files are stored in `plugins/ArcMenu/images/`.

## Adding a GIF to a menu

Under `frontend` in a menu configuration file, set the element `type` to `gif` and specify the image path and playback speed:

```yaml
frontend:
  animated-banner:
    type: gif
    source: /ui/banner.gif
    width: 160
    height: 40
    speed: 1
    offset: {y: 30, z: 1}
```

The example above references `plugins/ArcMenu/images/ui/banner.gif`. In the visual editor, you can also pick GIF files directly from your asset library using the GIF tool.

A GIF element accepts the following fields:

* `type`: Always set to `gif`.
* `source`: Relative path starting with `/` (relative to `images/`), using lowercase letters, digits, underscores, hyphens, or periods for directory and file names. Also supports PlaceholderAPI placeholders and dynamic path refreshes via `update`.
* `width` and `height`: Optional display dimensions on the canvas; accepts numbers greater than `0`. When omitted, the GIF's original pixel width and height are used.
* `speed`: Optional playback speed; accepts a number greater than `0` and defaults to `1`.
* Standard appearance properties: Supports `offset` (position), `rotation`, `scale`, `opacity` (`0`–`255` opacity), and `color` (hex color tinting), working the exact same way as on regular images.

## Controlling playback speed (`speed`)

`speed` sets **how many frames the animation advances per Minecraft game tick**, defaulting to `1`. This setting overrides the internal frame delays and loop metadata stored inside the GIF file so the animation loops steadily at the rate you configure:

| `speed` value | Playback result (at a normal server rate of 20 ticks per second)                                       |
| ------------- | ------------------------------------------------------------------------------------------------------ |
| `0.5`         | Advances 1 frame every 2 ticks (each frame stays on screen for 2 ticks, playing 10 frames per second). |
| `1`           | Advances 1 frame every tick (playing 20 frames per second).                                            |
| `2`           | Advances 2 frames every tick, displaying frames 0, 2, 4, and so on.                                    |

When a GIF is used inside [Effect cutscenes](/en/feature-configuration/effect.md), its playback progress follows the Effect timeline playhead directly, supporting pausing, scrubbing, layer trimming, and `speed` keyframes for smooth speed ramps.

## Client-local playback and server-side frame playback

ArcMenu provides two GIF rendering mechanisms, controlled by `client-playback.local-gifs` in `config.yml`:

```yaml
client-playback:
  local-gifs: true
```

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

* **Client-local animated textures (`local-gifs: true`)**: In Mouse mode, when a GIF is completely opaque (`opacity: 255` with no translucent pixels in the source image), has no `color` tint, and uses a constant `speed`, ArcMenu generates a native client animated texture for it in the resource pack. The client advances frames on its own without the server sending network update packets every tick.
* **Playback clock behavior**: The clock for a client animated texture starts running as soon as the resource pack loads, and all instances sharing the same asset and speed share that same playback clock. If you need a GIF to always start strictly from frame 0 every time a menu opens, set `client-playback.local-gifs` to `false` to use server-side frame synchronization instead.
* **Server-side frame synchronization**: Touch mode, Vision mode, editor previews, GIFs with transparency or color tinting, and GIFs inside Effect timelines automatically render using server-side frame glyphs, ensuring accurate alpha blending, shader compatibility, and timeline scrubbing in each mode.

Local GIFs in Mouse mode require the client to have the current generated companion resource pack loaded. In `config.yml`, `mouse.assume-resource-pack-loaded` defaults to `true`, which trusts a manually installed companion resource pack; setting it to `false` checks the server's resource-pack load confirmation instead. See [Images and resource packs](/en/feature-configuration/resource-packs.md) for details.

## Resource pack generation and file specifications

After adding or replacing GIF files in `images/`, rebuild and distribute the resource pack:

* When working alongside a custom-content plugin, run `/arcmenu resources` (or `/arcmenu reload all`) first, then run that plugin's pack command (`/ce reload pack` for CraftEngine, `/nexo reload pack` for Nexo, or `/iazip` for ItemsAdder).
* When managing the resource pack standalone, run `/arcmenu reload all` and distribute the newly generated `plugins/ArcMenu/generated/arcmenu-resourcepack.zip` to clients.

During resource pack generation, ArcMenu automatically composites partial GIF frames, alpha channels, and disposal methods, writing the frame sequence directly into the generated ZIP archive without cluttering your `images/` directory with extracted frame files. When you export a menu package with ArcPack, both the original `.gif` file and its `speed` settings are packaged together.

Each GIF file must meet the following specifications: file size up to `16 MiB`, width and height between `1` and `4096` pixels, total frame count up to `1024` frames, and total full-size decoded pixels per file (`width × height × frames`) up to `16,777,216`.


---

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