Aseprite Animations in JSON UI

Every image control in JSON UI has a base texture, a UV starting coordinate, and a UV size. Normally, animating a sprite sheet requires defining a `uv` animation type and chaining individual keyframes, where each keyframe shifts the UV coordinate to the next cell in the grid and waits for a set duration.

However, the UI parser includes built-in support for Aseprite's JSON Array export structure. When you place the exported `.json` file in the exact same folder as your `.png` sprite sheet and give them identical base filenames, the game automatically links them. You can then bypass standard keyframe definitions in your UI files and instead reference the frame tags or frame sequences generated by Aseprite.

To generate a compatible sprite sheet in Aseprite, open your animated sprite and go to File > Export Sprite Sheet (or press Ctrl+E). In the Layout tab, any sheet type (Horizontal Strip, Vertical Strip, or Packed) will work because the engine reads the exact coordinates of each cell from the JSON file rather than assuming a uniform grid. However, avoid enabling trimming or extruded borders until you have tested your base setup, as trimmed frames can shift the visual anchor of the image inside its UI control.

Switch to the Output tab. Check both Output File (saving your PNG inside your resource pack's `textures/ui/` folder) and JSON Data. Both files must share the exact same name, such as `loading_spinner.png` and `loading_spinner.json`. Directly beneath the JSON Data path, change the JSON format dropdown from Hash to Array. This step is critical: Bedrock's UI parser iterates through the `frames` property as an indexed JSON array `[...]` and will fail to read the default Hash object `{...}`.

If your file contains multiple animations—for example, an icon that has both an 'idle' loop and an 'active' burst—open the Meta section in the Output tab and ensure Tags is checked. This writes your timeline tags into the `meta.frameTags` array, allowing your UI controls to play specific frame ranges by name.

{
  "frames": [
    {
      "filename": "loading_spinner 0.aseprite",
      "frame": { "x": 0, "y": 0, "w": 16, "h": 16 },
      "rotated": false,
      "trimmed": false,
      "spriteSourceSize": { "x": 0, "y": 0, "w": 16, "h": 16 },
      "sourceSize": { "w": 16, "h": 16 },
      "duration": 100
    },
    {
      "filename": "loading_spinner 1.aseprite",
      "frame": { "x": 16, "y": 0, "w": 16, "h": 16 },
      "rotated": false,
      "trimmed": false,
      "spriteSourceSize": { "x": 0, "y": 0, "w": 16, "h": 16 },
      "sourceSize": { "w": 16, "h": 16 },
      "duration": 100
    }
  ],
  "meta": {
    "app": "http://www.aseprite.org/",
    "version": "1.2.40-x64",
    "image": "loading_spinner.png",
    "format": "RGBA8888",
    "size": { "w": 32, "h": 16 },
    "scale": "1",
    "frameTags": [
      { "name": "spin", "from": 0, "to": 1, "direction": "forward" }
    ]
  }
}

Before wiring up the UI control, it helps to understand which parts of the exported JSON file the game actually consumes. If you don't own Aseprite, you can even write or generate this file yourself using any sprite sheet packer that supports the standard JSON-Array texture atlas format.

Note that Aseprite records frame durations in milliseconds (where 100 equals a tenth of a second), whereas standard JSON UI animations define their `duration` in seconds. When Bedrock parses an Aseprite JSON file, it converts the millisecond values for you automatically.

Once both the `.png` and `.json` files are sitting in your `textures/ui/` folder, you can create your image control in your UI file. Just like any other animated UV texture, the image control needs its `texture` path pointing to the sprite sheet (without the file extension) and an explicit `uv_size` matching a single frame's dimensions.

For standard keyframe animations, you attach an animation definitions array to the `uv` property using the `@namespace.anim_name` syntax. When using an Aseprite sheet, you still attach a `uv` animation, or configure the image control's `aseprite_flip_book` properties depending on how your animation is structured. Below is the foundational setup of the image control alongside a standard UV animation wrapper that initializes the flipbook coordinates.

{
  "namespace": "custom_hud",

  "spinner_uv_anim": {
    "anim_type": "aseprite_flip_book",
    "initial_uv": [ 0, 0 ]
  },

  "custom_spinner_image": {
    "type": "image",
    "texture": "textures/ui/loading_spinner",
    "size": [ 16, 16 ],
    "uv_size": [ 16, 16 ],
    "uv": "@custom_hud.spinner_uv_anim"
  }
}

While `aseprite_flip_book` is convenient for complex pixel art with variable frame timings, it requires an extra JSON file in your textures directory for every animated asset. For simple two- or three-frame animations with constant frame durations, you can skip the Aseprite JSON export entirely and use a standard `flip_book` animation type right inside your UI file.

A native `flip_book` animation only requires the PNG strip. You specify `frame_count`, `frame_step` (how many pixels to advance the UV on each frame), and `fps`. Reserve the Aseprite JSON workflow for animations where individual frames hold for different lengths of time (such as a glint that pauses for two seconds before flashing across an icon) or when your artist is already authoring assets directly in Aseprite.

{
  "namespace": "simple_anim",

  "basic_strip_anim": {
    "anim_type": "flip_book",
    "initial_uv": [ 0, 0 ],
    "frame_count": 4,
    "frame_step": 16,
    "fps": 10,
    "reversible": false
  },

  "animated_icon": {
    "type": "image",
    "texture": "textures/ui/four_frame_strip",
    "size": [ 16, 16 ],
    "uv_size": [ 16, 16 ],
    "uv": "@simple_anim.basic_strip_anim"
  }
}

Applies to Minecraft Bedrock 1.16.0 and later, including current 1.21.x releases. JSON UI and Aseprite flipbook animations are part of the core resource pack system and do not require any experimental toggles.

Read out of the game itself, so the ids match the version you are building for.