Code cleanup for AnimationMixer

Discussion
,
1

I’ve been studying the Threejs animation system for animated models, which hinges around AnimationMixer. The API is a bit confusing. For example methods like mixer.uncacheRoot(root) accept a root object to cleanup, giving the impression that a mixer can have multiple roots, while the AnimationMixer’s constructor requires a single specific root which gives the impression that the mixer has to be associated with a single root. This, and other problems, make the API confusing because:

  • are we supposed to call uncacheRoot() to clean up?
  • are we supposed to call uncacheClip() on all clips to clean up?
  • are we supposed to call uncacheAction() on all actions to clean up?
  • are we supposed to call stopAllAction() to clean up?
  • how do we add more roots?
  • how do we remove roots?

I believe that we can make some choices and end with a simpler and cleaner API, but it would be a breaking change (otherwise supporting the current API for back compat would be just horrendous, and I’d leave it as is).

For example, if mixers should be able to have multiple roots, then we should remove the root parameter of the constructor and instead add a method like addRoot, and make the API hinge around the idea of managing multiple roots so that it is clear, making it easy to add actions for specific roots. In this format, we’d make it clear that you add a root, and you can uncache a root. Other methods like uncachClip and uncacheAction would uncache for all roots always. And APIs like stopAllAction should be thought about because there is no equivalent startAllAction, and it seems more like some sort of disposal API (but that’s not clear).

Alternatively, maybe we want to explicitly design AnimationMixer to be strictly associated with a single root, and if you want to manage multiple root nodes with animations then you associate N mixers with N roots, but make it clear that mixers can share clips or actions, etc. A mixer would have a dispose() method. I believe this organization would just be simpler and easier to understand right away. Disposing a mixer would unnassociate any clips and actions from the mixer’s root.