This is the ground truth document for [#120406: Slotted Actions Planning](https://projects.blender.org/blender/blender/issues/120406).

# Slotted Actions Planning

For more context, see:

- [2024: Animation 2025: Progress & Planning][blogpost-baklava]
- [2023: Layered Animation workshop][workshop-2023]
- [2022: Character Animation workshop][workshop-2022]

[blogpost-baklava]: https://code.blender.org/2024/02/animation-2025-progress-planning/
[workshop-2023]: https://code.blender.org/2023/07/animation-workshop-june-2023/
[workshop-2022]: https://developer.blender.org/docs/features/animation/module/character_animation_workshop_2022/

Goals: ability to animate with the new multi-slot Action, and having different data-blocks animated by the same Action.

Non-goals: layers, strips on layers, animation-level constraints, bone pickers.

**Each phase after 3 should have some time to iterate on the new functionality with animators.**

## 1: ✅ ~~Existing code for the data model → `main`~~

~~#118677: Implement the Data Model~~

## 2: ✅ ~~Data Model access via existing UI~~

#119875: add layered Action to anim filtering code

Goal: minimal working state for animators to animate *anything*.

- [x] Hooking up to the existing animation filtering code
- [x] Research existing code
- [x] Add layered Action support
- [x] Dope Sheet
- [x] Graph Editor
- [x] Adding Slots to animation filtering code
- [x] Action editor ([#122672](https://projects.blender.org/blender/blender/pulls/122672))
- [x] ~~Dope Sheet~~ (decided to not show slots here)
- [x] ~~Graph Editor~~ (decided to not show slots here)
- [x] Key Insertion:
- [x] From 3D Viewport ([#119669](https://projects.blender.org/blender/blender/pulls/119669))
- [x] From context menu on properties
- [x] From Graph Editor
- [x] From Dope Sheet Editor (all modes except Action/GP)
- [x] From Action Editor (worked, but not longer after slots are shown there)
- [x] From Grease Pencil dope sheet mode
- [x] 'Follow Path' constraint, which sets up animation stuff by itself.
- [ ] ~~Finding all other use sites of keyframe-insertion code.~~ (Discussed in a meeting with Sergey, and he suggested just getting the knowns working, and let the unknowns get discovered through testing rather than scouring the code base.)
- [x] Key insertion (also via Python): XYZ-to-RGB
- [ ] ~~Icon design for slots → discuss with Pablo Vazquez.~~ (moved to a later phase to not delay marking this one as finished)

**End-of-subphase goal:** Animators can animate with a file that has been set up for animation by the devs. **Update:** practical animation will likely be too hindered by not having F-Curve groups (which also causes things like 'only for selected bones' to not work).

## ✅ ~~3: Creating & Assigning Actions~~

- [x] Action assigning UI
- [x] Selecting the slot in the Action editor (#125416)
- [x] Action + Slot selector in Properties panel (#125666), also for non-Object datablocks. `WEEK 1 Sybren`
- [x] Action creation UI/UX
- [x] Creating new Action + slot through inserting the first key
- [x] Ensuring (Object + Object Data) and (ID + embedded ID) by default use the same Action (#126655, `WEEK 1 Christoph`)
- [x] Slot creation via key insertion.
- [x] Slot creation via operators on the selector. (#126943) `WEEK 0 Sybren`
- [x] Slot unassignment operators. (#126943) `WEEK 0 Sybren`
- [x] Deleting Slots. (#127112, `WEEK 1 Sybren`)

**End-of-subphase goal:** Animators can animate a file from scratch.

## ✅ ~~4: Organisation of animation channels~~

This phase focuses on getting feature parity with the legacy Action F-Curve groups.

- [x] Key selection via group rows in action/dopesheet editor. (There's a bug currently that makes this not work properly.) `WEEK 1 Nathan + Sybren`
- [x] Flags (enable/disable, protected, etc).
- [x] Automatic creation of new groups, when new F-Curves are created.
- [x] Automatically add new F-Curves to existing groups, when they already exist.
- [x] Manual grouping & un-grouping of FCurves, and moving FCurves and groups up/down in the channel list. `WEEK 1 Nathan`
- [x] Python API for groups on channel bags.
- [x] Backwards-compatibility Python API on `action.groups`. `WEEK 1 Sybren`
- [x] Fixing indentation of animation channels. `WEEK 1 Nathan`
- [x] Channel list in Action editor: dim the contents of a slot when that slot is unassigned. `WEEK 1 Nathan`

**End-of-subphase goal:** Animators don't get lost in their long lists of channels.

## ✅ ~~5: Data Model Polishing~~

- [x] Change how strips store their data. Instead of storing the data inside the strip itself, the strip data should be stored in a flat array on the Action. Strips should reference this array, to make instancing trivial. `WEEK 2 + 3 Nathan`
- [x] Implement the new data model ([#126559](https://projects.blender.org/blender/blender/pulls/126559))
- [x] Type refinement of RNA structs for the Strip ([#127859](https://projects.blender.org/blender/blender/pulls/127859))
- [x] Deleting unused strip data array entries ([#127837](https://projects.blender.org/blender/blender/pulls/127837))

## ✅ ~~6: Feature Par with Actions~~

- [x] Autokeying
- [x] Selection syncing (objects/bones/otherthings vs. their animation channels) if feasible to do with the current code base for this.
- [x] Cycle-aware keying? At least to the point how it works now.
- [x] Dopesheet & Graph Editor filters.
- [x] Cleanup pass on C++ API moving some F-Curve related functions from `KeyframeStrip` to `ChannelBag`.
- [x] Icon design for slots (#123372).

**End-of-subphase goal:** Animators can work with the multi-slot Actions as comfortably as with legacy Actions.

## ✅ ~~7: Ensuring all the other code can work with layered Actions~~

There will be much code that doesn't go through the animation filtering or key insertion systems, but directly accesses `action->curves`. This code needs to be updated to handle layered Actions.

- [x] Make existing code deal with layered/slotted Actions ([#123424: Anim: make existing code deal with layered Actions](https://projects.blender.org/blender/blender/issues/123424)) `WEEK 4 Sybren & WEEK 4+5 Nathan`
- [x] Action Constraints (`WEEK 3 Sybren`, [#127749](https://projects.blender.org/blender/blender/pulls/127749))
- [x] Action+Slot Swapping (`WEEK 3 Sybren`, [#127871](https://projects.blender.org/blender/blender/pulls/127871))

## 8: ✅ ~~Tooling~~

- [x] Conversion operator from Legacy to Layered Action.
- [x] Converting groups properly in legacy → layered action conversion operator. `WEEK 1 Christoph`
- [x] ~~Conversion from single-slot Action to legacy Action?~~ somewhat automatic given backward-compatible API + forward compatibility.
- [x] Tools for joining & splitting Actions (#126937) `WEEK 3 Christoph`
- [x] Join all Actions of the selected objects into the Action of the active Object. (#127414)
- [x] Join action of object data (+ embedded IDs) into the Action of the active Object.
- [x] Split `1` multi-slot Action → `N` single-slot Actions.
- [x] In Action editor: right-click on slot → Move to New Action (#128171)
- [x] Action menu in Action editor, to hold these operations. (#128171)`WEEK 3 Christoph`
- [x] Library Override / non-editability of non-overridden linked data. Even when nothing should be overridable, there should be time to think about this and make clear decisions (+ document those). `WEEK 4 Sybren` ([#128708](https://projects.blender.org/blender/blender/pulls/128708), if there's more we can fix those when we find them)

## 9: ✅ ~~Proven Explanations & Documentation~~

- [x] We need to be able to explain multi-slot Actions.
- [x] The explanation needs to be written down in the [technical documentation](https://developer.blender.org/docs/features/animation/animation_system/baklava/#phase-1-multi-data-block-animation).

## 10: ✅ ~~NLA and Pose Library support~~

- [x] Investigate what is necessary for NLA support of single-layer, multi-slot Actions.
- [x] NLA support for single-layer Actions. `WEEK 2 Sybren`
- [x] NLA Strips: add Slot selector
- [x] Make animation evaluation work properly (without F-Curve/strip modifiers)
- [x] Support Tweak Mode
- [x] Support F-Curve/strip modifiers
- [x] Pose Library should produce & work with multi-slot Actions. ([#128594](https://projects.blender.org/blender/blender/pulls/128594) and [#128686](https://projects.blender.org/blender/blender/pulls/128686)) `WEEK 5 Nathan`
- [x] Push Down (`WEEK 5 Sybren`, [#128444](https://projects.blender.org/blender/blender/pulls/128444))
- [x] Stash ([#128696](https://projects.blender.org/blender/blender/pulls/128696))
- [x] Key insertion: allow in NLA tweak mode (`WEEK 5 Sybren`, [#128446](https://projects.blender.org/blender/blender/pulls/128446))
- [x] Key insertion: NLA time remapping (`WEEK 5 Sybren`, [#128700](https://projects.blender.org/blender/blender/pulls/128700))
- [x] Check other places where NLA time remapping is done (is fine, `BKE_nla_tweakedit_remap()` does not directly use the Action itself)
- [x] (not NLA/Poselib, but also to do:) Test motion tracker. (is fine, doesn't create an Action itself, just inserts keys)

## 11: Going out of Experimental

- [x] Versioning to convert legacy Actions to layered ones (behind experimental flag). (`WEEK 3 Christoph` [#127842](https://projects.blender.org/blender/blender/pulls/127842))
- [x] Make the Python API for legacy Actions work with single-slot, single-layer Actions as well.
- [x] Forward compatibility: write F-Curves of the first slot, first strip, first layer as legacy F-Curves as well.
- [x] Do not return `MutableSpan<>` any more (for slots/layers/etc.) but always use `Span<>`. `WEEK 5 Sybren`
- [x] Add copying of tmpact slot and handle in `rna_AnimaData_override_apply`
- [x] Remove the experimental flag
- [x] Make PR `WEEK 6 Sybren` ([#128889](https://projects.blender.org/blender/blender/pulls/128889))
- [x] Land in `main` for Blender 4.4 (`WEEK 6+ Sybren`)
- [x] Updating the User Manual
- [x] Make PR for Action page `WEEK 5+ Nathan`: [#104974](https://projects.blender.org/blender/blender-manual/pulls/104974)
- [x] Update other pages that show/reference the action selector to also show/reference the slot selector:
- [x] Properties editor page: [149039f85a8e](https://projects.blender.org/blender/blender-manual/commit/149039f85a8ebd930aeeece6c1052529e48c244a)
- [x] Action Editor page: [7fbe4e0cbd68](https://projects.blender.org/blender/blender-manual/commit/7fbe4e0cbd68721e1c333276600df3501c1bf0a2)
- [x] NLA Sidebar page: [07232187c361](https://projects.blender.org/blender/blender-manual/commit/07232187c3619e188e7a2b7ed9b517bfbebee97c)

## 12: A Few Hours Lateur (well, weeks or months)

- [ ] Remove code that deals with the legacy Action data `WEEK (NOW+2)+`

This is mostly to remove then-dead code. It is deferred until we're confident that the new code is doing the right thing, and we don't need the old code as reference any more for regressions.

## Unplanned but related

Other things, which **will likely have to wait** until later phases:

- [ ] Per-FCurve-group modifiers. But maybe those become 'modifier strips', and scoping of those is done on a per-layer level.
- [ ] Animation Filtering code replacement. Becomes a little more important when looking at FCurve groups. Those will likely be reimplemented from scratch to get rid of weird `ListBase` dependent stuff.
- [ ] Fine-grained dependency graph nodes. Currently the Action can only be tagged for update as a whole, causing a full re-evaluation of all animated data-blocks. This should be more granular.
- [ ] Enriching F-Curve grouping functionality:
- [ ] Automatic creation of "manual" groups
- [ ] Automatic (implicit) grouping of FCurves?
- [ ] Automatic sorting of FCurves:
- [ ] First location, then rotation, then scale, then the rest
- [ ] Keeping array elements sequential & in array order
- [ ] Manual reordering of Slots within an Animation