Frame tags

Named coloured ranges over the frames timeline. Useful for marking out walk-cycle, idle, attack, death sub-ranges on a single shared timeline so you (and the engine consuming the export) can locate sequences quickly.

Tags are positional (Aseprite-style): they reference frame indices, not frame ids. If you reorder frames, the indices stay the same — retarget the tag explicitly if needed.

---

Where to find it

A bar above the frame thumbnails in the Frames timeline.

---

Anatomy

• Tag bar — coloured rectangles spanning the affected frames. Each tag's bar:
  • Width = (toIndex − fromIndex + 1) frames
  • Position = aligned to the underlying frame thumbnails (slot width = 64 px + 8 px gap)
• + Tag button — adds a new tag covering only the active frame.
• Tag editor — appears below the bar when you click a tag.

---

Create a tag

1. Click the frame you want the tag to start on.
2. Click + Tag. A tag is created covering that single frame, with a default name and colour.
3. The editor opens automatically. Use it to expand the range, rename, recolour, or change direction.

Tag editor

Control	What
Color picker	Tag's bar colour (any hex).
Name	Tag identifier.
From / To	1-based frame indices the tag covers (inclusive both ends).
Direction	forward / reverse / pingpong — playback hint for animations referencing this tag.
Trash	Delete the tag.
×	Close the editor without deleting.

---

Direction hints

The direction field is metadata for tools that consume tag ranges:

• forward — play 1 → 2 → … → N
• reverse — N → N−1 → … → 1
• pingpong — 1 → 2 → … → N → N−1 → … → 1

Direction is exported to .mstack and to JSON via the sprite-sheet exporter — engines like Aseprite-compatible importers, Phaser, or Godot can use it directly.

---

Tag invariants on frame mutations

The editor automatically adjusts tag ranges:

• Insert frame at index i → tags fully after i shift by +1; tags whose range contains or starts at i extend by 1 (the new frame becomes part of the tag).
• Delete frame at index i → tags after i shift by −1; tags overlapping i shrink by 1; tags whose only frame was i are removed.
• Reorder frame → tags don't move. Indices stay the same. (Aseprite-positional, not identity-tracking.)

---

Why use tags? — concrete examples

🎮 Game character with multiple animations on one sheet

You have a single character sprite sheet with all animations packed into one timeline:

Frames	Animation
1–4	idle
5–12	walk
13–18	attack
19–22	hurt
23–28	die (forward only — direction: once would be a tag-level hint, here we use forward)

Without tags, you'd have to remember "walk is 5–12" forever. With tags, the timeline shows coloured bars labelled idle, walk, attack, … above each range. You can rename, recolour, and re-target them as the project grows.

Bonus: when you export to a sprite sheet with JSON, the JSON includes a frameTags array. Engines like Phaser, Solar2D, and several Godot importers read this directly so your code can do sprite.play('walk') instead of sprite.play(5, 12). Same effect, way more readable.

📌 Visual landmarks in long timelines

Even if you never export the tags, they're useful for navigation. With a 60-frame project, "I want to fix the death animation" is much easier when there's a red bar labelled die at frames 50–60 than scrubbing through thumbnails.

↪️ Direction hints

direction (forward / reverse / pingpong) is metadata. It doesn't change how the editor plays the timeline, but it's exported so the consuming engine can use it. Useful when you reuse one set of frames for multiple play modes — e.g. a "rise" animation (forward) and a "fall" animation that reuses the same frames in reverse.

When tags aren't the right tool

• For alternative organisation of frames as named sets that can overlap, prefer Sprites. A frame can belong to multiple sprites; with tags, frames belong to a single global timeline.
• For playback sequences with custom step ordering and loop modes, use Animations. Animations can reference any subset of frames in any order; tags are just "this contiguous range has a name".

---

Tips

• Tags are per-project, not per-sprite. They live on the global frameOrder.
• Use a distinctive colour for each tag — the editor auto-rotates 8 default colours to start.
• The editor caps tag colours to hex — if you copy/paste a colour, make sure it's a 6-character hex string.
• The bar truncates the tag name when it's too narrow — hover over the tag to see the full info in a tooltip.

---

Related

• Frames & timeline
• Sprites & animations — animations can reference tag ranges
• Sprite sheet export — tags are emitted as JSON metadata