Animated tiles

Animated tiles let painted cells cycle through a frame sequence at runtime: water flowing in a lake, lava bubbling in a pit, torches flickering on a wall, crystals glowing in a cave. You paint one tile (the "root") and every matching cell on the map animates in lockstep.

This guide walks you through animating the 4-frame water spritesheet from the Sprout Lands pack. Once you've done it once the same flow works for any N-frame tileset.

Before you start

You need a tileset asset whose source PNG is a uniform grid of N animation frames laid out left-to-right. A typical 4-cell water sheet looks like this:

┌────┬────┬────┬────┐
│ 0  │ 1  │ 2  │ 3  │   ← frames cycle in this order
└────┴────┴────┴────┘

If your spritesheet isn't already configured as a tileset, open the asset card, click 🧩 Configure as tileset…, set cell size + columns + rows, and save. You'll land in the Tileset Inspector.

Step 1 — Open the Animations editor

In the Tileset Inspector, scroll to the Animations section and click + Add animation…. A modal opens with the full tileset on the left and an empty animation editor on the right.

Step 2 — Pick a root tile, then frames

The root tile is the one you'll paint with on the tilemap. Every cell painted with that index will animate.

• Click the first cell in the spritesheet — it becomes the root.
• The click mode flips to frame mode. Click each frame in cycle order: 0, 1, 2, 3.

Convention: make frames[0] equal to the root so the static (paused) view in Umicat's editor matches frame 0.

Shortcut: "Animate all"

For the common case of "I want every cell in this spritesheet to be one synchronized animation," click Animate all. It sets root = 0, frames = [0..N-1], and duration = 250ms (4 fps) in one go. Done.

Step 3 — Tune the cycle speed

The duration slider sets milliseconds per frame, uniform across all frames in v1. Useful starting points:

Floor is 16 ms. Save the animation when it feels right.

Step 4 — Paint with the root tile

Back in the tilemap painter palette, the root tile now has a 🎬 badge in its upper-left corner. Paint that tile anywhere on your map (brush, rect, fill — any tool works). Every painted cell starts animating immediately.

Non-root frames in the spritesheet stay paintable too, but they render static — the SDK swaps to them per-tick when the root is painted. Painting a non- root frame directly is rarely what you want.

Edit mode vs Play mode

While you're editing, scenes are paused — animations don't run. The editor view always shows each animated cell at its root index, so what you see is the authored data, not whatever frame happened to be visible when you toggled into Edit mode.

Switch to Play and animations resume on the next update tick.

When NOT to use animated tiles

• Sprite animations (player walk cycles, enemy attacks) — those are Phaser sprite animations, authored via the Sheet Editor on a spritesheet asset. Different system, different runtime.
• One-shot tile state changes (door opens, gate closes) — those are one-time tile swaps from behavior code, not data-driven cycling.
• Per-cell phase offset (each water cell offset to look organic) — v1 ships synchronized cycling only. All matching cells animate together.

Under the hood (optional reading)

Umicat stores animations in tileset metadata:

{
  "cellSize": { "width": 16, "height": 16 },
  "cols": 4, "rows": 1,
  "animations": [
    {
      "id": "water-flow",
      "rootTileIndex": 0,
      "frames": [
        { "tileIndex": 0, "duration": 250 },
        { "tileIndex": 1, "duration": 250 },
        { "tileIndex": 2, "duration": 250 },
        { "tileIndex": 3, "duration": 250 }
      ]
    }
  ]
}

The SDK installs a scene UPDATE listener that walks painted cells matching any rootTileIndex and swaps each one to the current frame. Per-frame mutations don't leak into your save data — a mid-animation save still records root indices, not whatever frame was on screen.

That's it. Paint the root, watch the world come alive.