Namespace nadena.dev.ndmf.animator
Classes
- AnimatorServicesContext
Provides a number of NDMF services based on virtualizing animator controllers. While this context is active, NDMF will automatically track object renames, and apply them to all known animators. It will also keep animators cached in the VirtualControllerContext (which is also, as a convenience, available through this class). Note that any new objects created should be registered in the ObjectPathRemapper if they'll be used in animations; this ensures that subsequent movements will be tracked properly. Likewise, use ObjectPathRemapper to obtain (virtual) object paths for newly created objects.
- CloneContext
The CloneContext keeps track of which virtual objects have been cloned from which original objects, and therefore avoids double-cloning. It also keeps track of various context used during cloning, such as virtual layer offsets. Most users shouldn't use CloneContext directly; use the Clone wrappers in VirtualControllerContext instead.
- ObjectPathRemapper
The ObjectPathRemapper is used to track GameObject movement in the hierarchy, and to update animation paths accordingly. While the ObjectPathRemapper is active, there are a few important rules around hierarchy and animation maniuplation that must be observed.
- The ObjectPathRemapper takes a snapshot of the object paths that were present at time of activation;
as such, any new animations added while it is active must use those paths, not those of the current
hierarchy. To help with this, you can use the
GetVirtualPathForObjectmethod to get the path that should be used for newly generated animations. - Objects can be moved freely within the hierarchy; however, if you want to remove an object, you must call
ReplaceObjecton it first. - Objects can be freely added; if you want to use those objects in animations, use
GetVirtualPathForObjectto get the path that should be used. This will automatically register that object, if necessary. If you'd like to use animation clips with pre-existing paths on, for example, a newly instantiated prefab hierarchy, useRecordObjectTreeto ensure that those objects have their current paths recorded first. This ensures that if those objects are moved in later stages, the paths will be updated appropriately. Note that it's possible that these paths may collide with paths that previously existed, so it's still recommended to useGetVirtualPathForObjectto ensure that the path is unique.
- The ObjectPathRemapper takes a snapshot of the object paths that were present at time of activation;
as such, any new animations added while it is active must use those paths, not those of the current
hierarchy. To help with this, you can use the
- VirtualAnimatorController
Represents an animator controller that has been indexed by NDMF for faster manipulation. This class also guarantees that certain assets have been cloned, specifically:
- AnimatorController
- StateMachine
- AnimatorState
- AnimatorStateTransition
- BlendTree
- AnimationClip
- Any state behaviors attached to the animator controller
- VirtualClip
An abstraction over Unity AnimationClips. This class is designed to allow for low-overhead mutation of animation clips, and in particular provides helpers for common operations (e.g. rewriting all paths in a clip).
- VirtualControllerContext
This extension context converts all "innate" animator controllers bound to the avatar into virtual controllers. By "innate", we mean controllers which are understood by the underlying platform (e.g. VRChat). As part of this, the controllers and animations are cloned, so that changes to them do not affect the original assets. This context acts as a key-value map from arbitrary context keys to virtual controllers. For VRChat controllers, the context will be a
VRCAvatarDescriptor.AnimLayerTypeenum value. For other sub-components which have animator controllers (e.g. the unityAnimatorcomponent), the context key will be that controller. Otherwise, it's up to the IPlatformAnimatorBindings implementation to define the context key. Upon deactivation, any changes to virtual controllers will be written back to their sources. You may also add arbitrary virtual controllers to the context, by setting the value for a given key. These controllers will be generally ignored, unless you choose to do something with them. Note that these controllers will not be preserved across a context deactivation.Limitations
When this context is active, you must not modify the original controllers or their animations. This is because certain virtual objects may reference the original assets, and thus changes to them may result in undefined behavior. After deactivating this context, you must not modify the virtual controllers or their animations. This is because subsequent NDMF processing steps may directly modify the serialized animator controllers; conversely, when the virtual controller context is reactivated, it may or may not reuse the same virtual nodes as before.
- VirtualLayer
A layer within a VirtualAnimatorController
- VirtualNode
Base class for all virtual animation nodes. Contains common functionality for cache invalidation. Generally, external libraries should not use this class directly.
- VirtualStateMachine
Represents a state machine in a virtual layer.
Structs
Interfaces
- IVirtualizeAnimatorController
Implement this interface on your component to request that an animator attached to this component be automatically registered in the VirtualControllerContext, with the component being the context key. This is, for example, implemented by ModularAvatarMergeAnimator to ensure that object renames are tracked appropriately at all times.