Layer linking

A linked layer shares its pixel buffer with same-named layers in other frames. Editing the linked layer in any frame updates the shared content for all of them. Use it for:

• Backgrounds that should look identical on every frame
• Static UI overlays (HUD bars, frames)
• Reference grids while you animate the foreground
• Anything you'd otherwise have to duplicate frame-by-frame and keep in sync manually

This is the equivalent of Aseprite's "linked cels" feature.

---

Where to find it

Each row in the Layers panel has a chain icon between the lock and the name:

• Chain off (zinc) — layer is independent
• Chain on (green) — layer is linked across frames

---

Link a layer across all frames

1. Activate the layer you want to share.
2. Click the chain icon in its row.
3. Every layer in every frame matching the same name gets linked to the active one's pixel buffer. The active layer's content propagates — any other versions of "Background" (or whatever the layer is called) are overwritten.

The link key is shared by layer name, not by id. Frames that don't have a layer with that exact name are unaffected.

After linking, painting on the layer in frame 1 immediately updates frames 2, 3, … because they're all looking at the same buffer.

---

Unlink a single layer

To break a layer's participation in a link group while keeping its current pixels:

1. Activate the layer (in any frame).
2. Click its (now green) chain icon.
3. The shared buffer is cloned into a fresh private buffer for that one layer. The other frames in the group remain linked to each other.

Use this when you need a one-off variant for a specific frame.

---

Link semantics

• Same buffer key. Linked layers internally point to the same bufferKey (in the buffer store). Reads and writes go through an alias map so existing tool code is unchanged.
• Order is independent. Linked layers don't have to be at the same position in different frames — only the name has to match.
• Per-frame metadata stays separate. Visibility, lock, opacity, blend mode, group membership are still per-layer (per-frame). Only the pixels are shared.
• Persistence dedupes. .mstack writes one PNG per link key; Dexie stores one Blob per key. Loading rebuilds the alias map automatically.

---

Naming matters

Because linking is name-based:

• Renaming a linked layer in one frame does not rename the others. The link survives by id, not name — but if you create a new link from another frame, only same-named layers will join.
• If two unrelated layers happen to share the same name across frames, linking will join them. Watch for this when you have generic names like "Layer 1".

A safe convention: name shared layers explicitly (Background, HUD, Sky) and let frame-specific layers auto-name (Layer 1, Layer 2).

---

Why use it? — concrete examples

🌅 Animated character on a static background

The classic case. You have an 8-frame walk cycle, but the background never changes:

1. Frame 1: add two layers, name them Background and Character. Paint the background. Paint the first walk pose on Character.
2. Duplicate the frame 7 times. Now you have 8 frames, each with a (cloned) background and (cloned) character.
3. Activate Background in Frame 1 → click the chain icon. All 8 frames now share the same background buffer.
4. Paint each pose on Character per-frame (no linking — each frame has its own character).
5. Touch up the background → the change appears on every frame instantly.

Without linking, fixing a typo on a sign in the background means painting the same fix 8 times, manually. With linking, you fix it once.

🪟 UI / HUD overlays

Same pattern, different content. Your animation has a fixed UI bar (health, ammo, name) that shouldn't change between frames. Link the HUD layer across all frames; the dynamic content (e.g. character behind the HUD) lives on its own per-frame layer.

📐 Reference grids

While animating, you might want a faint grid (perspective lines, character pivot, motion path) that's the same on every frame for guidance. Put it on a Grid layer, link it across frames, then delete the Grid layer when you're done.

🎨 Shared palette swatches in a sprite sheet

If you're building a sprite sheet and want a consistent set of "colour samples" visible only while editing (not in the final export), put them on a linked layer that you toggle visible / hidden as needed.

When linking isn't the right tool

• If you want each frame to differ in some pixels — don't link. The whole point of linking is shared content.
• If you only need it on 2-3 frames out of many — linking is project-wide (matches by name across all frames). For partial linking, keep the layer un-linked and copy-paste pixels manually.

Quick test

To see linking working: paint something on a linked layer in Frame 1, then switch to Frame 2. The same pixels are there. Paint over them in Frame 2 — Frame 1 updates too. The two layers are looking at the same buffer.

---

Tips

• A duplicated layer is always private — duplicating doesn't carry over the link key. This prevents accidental aliasing.
• Linking is a project-wide operation: it scans every frame's layers for the same name. If you have many frames, the propagation is fast (one buffer copy + N alias entries).
• Combine with layer groups: you can have a group containing both linked and unlinked layers — only the pixels are shared, group membership is per-frame.

---

Related

• Layer basics
• Layer groups
• Frames & timeline