User Manual
Swap Animator for Blender — Manual
Swap Animator streamlines replacement animation in Blender—perfect for lip-sync mouth shapes, eye blinks, props, costumes, and other on/off elements. It automates visibility keyframes for objects and (optionally) items inside collections, keeping complex puppets tidy and fast to animate.
1) Introduction
What it is: a Blender add-on that automates visibility swaps for replacement animation. Ideal for stop-motion style workflows, CG puppet face sets, and any shot where you rapidly toggle parts on/off at specific frames.
Who it’s for: animators working in stop motion, claymation, CG, previs, and education who need clean, repeatable swaps with minimal manual keyframing.
Key Idea: Keep your puppet components (mouths, brows, props, etc.) as separate objects or organized inside collections. Use Swap Animator to keyframe which one is visible at a given frame—automatically.
2) Installation
- Download the add-on ZIP (do not unzip).
- In Blender, go to Edit → Preferences → Add-ons.
- Click Install…, select the ZIP, then enable Swap Animator.
- Open the 3D Viewport, press N to show the Sidebar, look for the Swap Animator tab/panel.
Tip: If updating, disable the old version first, remove it, then install the new ZIP to avoid duplicates.
3) Quick Start (5 minutes)
Setup
- Prepare a set of mouth shapes (or props) as separate objects Recommended or as objects inside a single collection.
- Name them clearly: Mouth_A, Mouth_E, Mouth_FV, etc.
- Place them at the correct position on the puppet head (use one as a driver for transforms; keep others hidden).
Animate
- Open the Swap Animator panel.
- Select the target group (objects or collection members) in the UI list.
- On a frame (e.g., 1), click the variant you want visible → a visibility keyframe is set.
- Move to a new frame (e.g., 5), pick another variant → another keyframe.
Note on Collections: Due to Blender’s current limitations, keyframing LayerCollection visibility isn’t reliable. The recommended workflow is to leave collections ON and let Swap Animator keyframe the objects inside that collection.
4) Features
Object Swapping
Toggle visibility between a set of objects (e.g., mouth shapes). Swap Animator ensures only the selected object is visible at a given frame and inserts the necessary keyframes.
- One-Click Keyframing: Click a variant; visibility tracks are updated.
- Non-destructive: Objects are not renamed or moved.
- Works with Collections: Objects can live inside organized collections.
Members → Collections (Organize by Set)
Group related variants inside a collection for cleanliness (e.g., COL_Mouths). Keep the collection itself enabled; the add-on targets the members for visibility keys.
Why? Blender doesn’t currently expose a stable, animatable API for LayerCollection toggles in the Outliner. Targeting object visibility is robust across versions.
One-Click Visibility Keyframes
Every swap writes keyframes to the appropriate visibility channels (viewport/render as designed by the add-on). No manual toggling or inserting keys needed.
UI Panel (N-Panel)
Find the controls in the 3D Viewport Sidebar (press N). The panel lists your swap sets (objects or collection members) and provides buttons to apply swaps at the current frame.
Performance-Safe
Visibility swaps are lightweight—great for dense puppet sets. For very large sets, consider hiding off-shot collections to keep the viewport snappy.
Storage Migration / Recovery (Linked Characters)
When to use: If you Link a character into a shot file and create a Library Override, groups stored on the character’s root object (e.g., the rig’s root Empty) may appear in Swap Animator but be greyed out. That’s because they’re tied to the linked datablock and are read-only.
Solution (v1.2.1+): Migrate those groups to Scene storage so they become local & editable:
- In the Swap Animator panel, open Storage Migration / Recovery.
- Click Copy Object → Scene.
This will:
- Copy all groups from the linked root object into the Scene storage.
- Make them local and editable in your shot file.
- Leave the original Object groups intact (you simply won’t animate with those).
From this point on: add/remove groups, switch between groups, and animate normally using the Scene storage.
5) Best Practices & Workflows
- Naming: Use consistent, readable names (e.g., Mouth_A, Mouth_E, Mouth_FV).
- One Set Per Collection: Group related replacements in a single collection for clarity (brows, eyes, mouths, props).
- Keep Collections ON: Let the tool key the members; don’t rely on collection on/off animation.
- Rig Anchors: Use an Empty or a driver object to align all variants; parent the shapes to it to simplify placement.
- Version Control: Save a new Blender file per shot or per major pass; Swap Animator keys are standard visibility tracks, so they travel with your file.
- Playback: If swaps “lag” in heavy scenes, enable Viewport Subdiv Off or lower display settings during animation.
Linked Characters (Library Overrides) — Recommended Workflow
- Rig File (Setup): Store groups on the character’s root object.
- Shot File (Animation): Link the character, create a Library Override, then run Storage Migration / Recovery → Copy Object → Scene once.
- Animate using the Scene storage groups from then on.
6) Troubleshooting & FAQ
“My keyframes disappear from the Timeline when I scrub.”
Most often, the Timeline/Dope Sheet filter Only Show Selected is enabled. Either:
- Disable Only Show Selected, or
- Select one of the swapped objects so their channels are shown.
“Collection animation isn’t working.”
Animating LayerCollection visibility isn’t reliably supported. The recommended approach is to keep collections ON and let Swap Animator keyframe the objects inside the collection.
“Two variants show at once.”
Make sure each variant is part of the same swap set and that you’re swapping via the panel (so the add-on writes mutually exclusive visibility keys). Also check for extra manual keys you may have added earlier.
“Do I need specific render settings?”
No special settings. Swaps are standard visibility keys; they render normally in both Eevee and Cycles.
Supported Blender versions?
Designed for Blender 4.x. If you encounter issues on older versions, update Blender and try again.
How do I uninstall / update?
- Edit → Preferences → Add-ons → uncheck Swap Animator.
- Click the arrow to remove the old version.
- Install the new ZIP and enable.
Linked character groups are shown but greyed out
Cause: After linking a character and creating a Library Override, groups stored on the character’s root object are still tied to the linked datablock and are read-only.
Fix (v1.2.1+): In the Swap Animator panel go to Storage Migration / Recovery → click Copy Object → Scene. This copies those groups into Scene storage, making them local & editable while leaving the originals unchanged.
7) Versioning & Release Notes
| Version | Date | Changes |
|---|---|---|
| v1.2.1 | 2025-09-08 | Added Storage Migration / Recovery with Copy Object → Scene for linked characters (Library Overrides). Solves greyed-out groups by making them local & editable in shot files. |
| v1.1.x | 2025-09-08 | Stabilized object-level swaps; clarified collection workflow; documentation pass. |
| v1.1.5 | 2025-09-01 | Fixed multi-collection edge case; ensured previous visibility keys persist across sets. |
| v1.1.4 | 2025-08-31 | UI refinements, faster listing of members, minor bug fixes. |
8) Support & Credits
Author: John Spigler Jr.
Support: For issues and feature requests, contact us via the contact form or reply to your purchase email.
