Namespace nadena.dev.ndmf.animator
Classes
- AnimationIndex
AnimationIndex indexes the full set of animations known to the
VirtualControllerContext, and allows for efficient querying of animations by object path or binding, as well as some bulk editing operations. The AnimationIndex registers invalidation callbacks with all nodes in the virtual controller hierarchy, and will therefore be automatically updated if anything changes in the hierarchy. Normally, you should obtain an AnimationIndex from theAnimatorServicesContext, but constructors are provided for testing purposes.
- 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 while this context is active.
- 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.
- CommitContext
The CommitContext tracks mappings of virtual objects to real unity objects, and avoids infinite recursion during animator graph serialization. Normally, you should not need to interact with this class directly; it is used internally by
VirtualControllerContextwhen converting virtualized animators to real animators. This is primarily exposed for testing purposes.
- GenericPlatformAnimatorBindings
Base platform bindings for generic unity animators.
- 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
- VirtualAvatarMask
Represents a virtualized @"AvatarMask" object.
- 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
- LayerPriority
Controls the sorting order of layers in the @"VirtualAnimatorController".
Interfaces
- IPlatformAnimatorBindings
The IPlatformAnimatorBindings interface is used to provide platform-specific bindings for the animator service. This is used, for example, to identify which animator controllers are referenced by the avatar's platform-specific components, and to process platform-specific state behaviours.
- 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.
When VirtualControllerContext is deactivated, the animator will be committed back to the IVirtualizeAnimatorController component (if the component has not been destroyed)