> For the complete documentation index, see [llms.txt](https://flipcard.superiormc.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://flipcard.superiormc.cn/features/custom-animation.md).

# 🎥Custom Animation

Custom frame animations work in both `INVENTORY` and `ARCMENU`. They are selected on a card using `animate: <id>`.

ArcMenu [presentations](https://flipcard.superiormc.cn/features/arcmenu-presentations.md) are a separate feature. A presentation can surround a chest animation with a background, labels and other elements while preserving the chest's frame playback.

## Create a frame animation

Create `animations/chest.yml` in the FlipCard data folder. The filename is the animation ID; put frame definitions under `frames`:

```yaml
# Frame order is playback order; the final frame is the revealed background.
frames:
  chest_1:
    rotation: 0.0
    y_translation: 0.0
    z_translation: 28.0
    x_scale: 1.9
    y_scale: 1.9
  chest_2:
    rotation: 0.0
    y_translation: 0.0
    z_translation: 28.0
    x_scale: 1.9
    y_scale: 1.9
  chest_3:
    rotation: 0.0
    y_translation: 0.0
    z_translation: 28.0
    x_scale: 1.9
    y_scale: 1.9
  chest_4:
    rotation: 0.0
    y_translation: 0.0
    z_translation: 28.0
    x_scale: 1.9
    y_scale: 1.9
  chest_5:
    rotation: 0.0
    y_translation: 0.0
    z_translation: 28.0
    x_scale: 1.9
    y_scale: 1.9
  chest_6:
    rotation: 0.0
    y_translation: 0.0
    z_translation: 28.0
    x_scale: 1.9
    y_scale: 1.9
  chest_7:
    rotation: 0.0
    y_translation: -18.0
    z_translation: -28.0
    x_scale: 1.9
    y_scale: 1.9
```

Put the matching PNG files, such as `chest_1.png` through `chest_7.png`, under `texture/animation/`.

* Frame order is the YAML order.
* The first frame is the idle item shown before opening.
* The final frame is the revealed background; it is excluded from the moving frame sequence.
* Moving frames are scheduled two ticks apart.
* At least two frame entries are required. The bundled chest has seven; seven is not a mandatory count.
* Use lowercase letters, digits, underscores and hyphens in frame names.
* `material` and `cmd` are generated when rebuilding the resource pack. Preserve existing values when moving an animation between files.

Frame model properties are `rotation`, `x_translation`, `y_translation`, `z_translation`, `x_scale` and `y_scale`. Translation and scale configure the Inventory GUI model. ArcMenu uses a normalized FIXED item transform, retaining the frame's rotation; its placement and size are controlled by ArcMenu settings and, when selected, the presentation.

Run `/flipcard reload`, then apply the regenerated resource pack. When using a resource-pack manager, rebuild and send the merged pack too.

## Select the animation on a card

Replace that card's `front` and `back` selection with `animate`:

```yaml
card_1:
  animate: chest
  amount: 4
  max: 3
  name: '&eOpen a chest'
  lore:
    - '&7Cost: %price%'
  prices:
    1:
      free: true
      apply: [1, 2, 3]
      placeholder: '&aFree'
  rewards:
    1:
      material: IRON_INGOT
      amount: 1
      rate: 10
      edge: common
    2:
      material: DIAMOND
      amount: 1
      rate: 1
      edge: very_rare
```

Reward edges remain optional. In ArcMenu, `rarity-display` controls whether to use an outline, a custom PNG frame, the edge item texture or no frame.

For a chest with a presentation, add this to the menu settings:

```yaml
settings:
  gui-type: ARCMENU
  arcmenu:
    presentation: destiny
    style: AUTO
```

ArcMenu plays the configured chest frames as the subject, ignoring the presentation's outer card rotation. Decoration and sound with `trigger: REVEAL` follow the actual chest reveal time.

The bundled `ui/arcmenu_chest_example.yml` is a complete example.

## Migrate the old config.yml format

The old `config.yml` section `animations.<id>` is still supported. To move it to an independent file:

1. Create `animations/<id>.yml`.
2. Move the contents of the old animation section under `frames`.
3. Keep frame order and existing `material`/`cmd` values.
4. Reload and apply the rebuilt pack.

If an independent file and `config.yml` define the same animation ID, the independent file takes priority and generated CMD values are written back to it. The old copy is not automatically deleted.

If an existing server has `animations.chest` in `config.yml`, FlipCard does not automatically install the default independent `animations/chest.yml` over that selection.
