Guides

How to animate textures with a .mcmeta file

Minecraft animates a block or item texture when the PNG holds several frames stacked on top of each other and a small .mcmeta file sits next to it. This works the same way in every Java Edition version from 1.19 to the latest.

1. Draw the frames as a vertical strip

Put every frame in one PNG, top to bottom. The image keeps the width of one frame and gets taller with each frame you add. Four 16×16 frames make a 16×64 image:

16 px wide
┌────────┐
│ frame 0│  y 0–15
├────────┤
│ frame 1│  y 16–31
├────────┤
│ frame 2│  y 32–47
├────────┤
│ frame 3│  y 48–63
└────────┘

The game's own animated textures, such as block/sea_lantern.png or block/magma.png, are laid out this way, so they make good examples.

2. Save it under the texture's name

Save the strip where the normal texture lives in your pack, for example assets/minecraft/textures/block/magma.png.

3. Add the .mcmeta file

Next to the PNG, create a text file with the same name plus .mcmeta: magma.png.mcmeta. The smallest one that works is:

{
  "animation": {}
}

That plays every frame in order, one game tick each. Without this file the game doesn't animate the texture and treats the whole strip as one tall image.

4. Set the speed with frametime

frametime is how long each frame stays on screen, in game ticks. The game runs at 20 ticks per second, so 2 is a tenth of a second and 20 is one second.

{
  "animation": {
    "frametime": 4
  }
}

5. Smooth it with interpolate

With "interpolate": true the game blends each frame into the next while it is shown. This suits slow colour changes like glowing ore or water, and looks muddy on animations with sharp movement.

{
  "animation": {
    "frametime": 8,
    "interpolate": true
  }
}

6. Reorder frames or change one frame's timing

The frames list sets the order. Each entry is a frame number (counting from 0) or an object with its own time. Frames can repeat:

{
  "animation": {
    "frametime": 2,
    "frames": [0, 1, 2, 3, 2, 1, { "index": 0, "time": 40 }]
  }
}

This plays forward, then back, then holds the first frame for two seconds.

7. Test in game

Load the pack, then press F3 + T after each change to reload it. If the texture shows as a squashed strip, the .mcmeta file name doesn't match the PNG or its JSON has an error; the game log names the file it couldn't read.

Frames are square by default. For frames that aren't, add "width" and "height" (in pixels) to the animation object.

Doing the same in MineTexture

Open a texture and use the animation panel: add frames, paint each one (onion skin shows the frame before), set the frame time, and tick interpolation. You can also let Auto Animate generate frames from one of its effects. When you export, MineTexture writes the frame strip and the .mcmeta file for you.