[RELEASED] Rukhanka - ECS (DOTS) Animation System

Rukhanka is an animation system for the Entities Component System (ECS). It works (and requires) Entities and Entities Graphics packages. Rukhanka animates skinned meshes and passes prepared data to the Entities Graphics package which renders animated objects. There is only Generic animation type support for now.

[ Asset Store ]
[ Documentation | YouTube | Discord | Support ]​

It is made with three main principles in mind:

• Complex inside - simple outside. Usage and setup are trivial. Use familiar Unity animation tools such as Mecanim and Animation Clips as authoring components. Rukhanka converts them during the baking phase and internally processes the animator state machine and plays all required animations.
• Performance in all aspects. Everything is fully bursted. ISystem-based and fully parallel with per-bone granularity (not per-skeleton). This allows achieving high thread utilization for low-bone and high-bone meshes.
• Behavior is nearly 100% similar to Unity Mecanim. Although I try to achieve 100% behavior identity, I am not a Unity employee and have no access to the Unity Animation system source code. Everything in Rukhanka is achieved by reading public documentation and investigating Unity's behavior.

Getting started video:

IMPORTANT: Make sure to refer to Feature Support Tables to figure out what functionality is supported before purchase.

 

Very nice!
I couldn't find explicit info. Your animation system doesn't require a compute shader, right?

How long did you work on this asset?
Unity devs, why is this dev out-pacing you in one of the most crucial parts of a game?

 

Hi. You are right, compute shaders don't required. Pure Entities + Burst. I am worked approximately 4 monthes till v1.0.0 release.

 

Version 1.0.1 is released.

Changelog:
Changed

• Crowd and Stress Test samples now have control for skeleton visualization enabling (with RUKHANKA_DEBUG_INFO defined).
• Crowd and Stress Test samples now show total number of animated bones in scene.

Added

• IEnableableComponent interface for AnimatorControllerLayerComponent and RigDefinitionComponent.
• Description of main Rukhanka entity components.

Fixed

• Incorrect handling handling of uniform scale in animations.

 

Version 1.0.3 is released.

Changelog:
Fixed

• Incorrect handling of very small transition exit time during state loops.
• Preventing NANs (division by zero) when transition duration is zero.
• Memory allocation error in PerfectHash tests.
• Controller parameters order in authoring animator does not coincide with generated AnimatorControllerParameter buffer.
• Empty animations to process buffer were handled incorrectly.
• Exit states of state machines are now handled properly.
• Animator state `Cycle Offset` treated as animation normalized time offset as in Unity.Animator.

Added

• Adding authoring Unity.Animator and all used Unity.Animation in the baker dependency list.
• Extended animator controller logging with RUKHANKA_DEBUG_INFO which displays all states parameters and transitions of baked state machines.

 

Version 1.1.0 is released.

Changelog:
Added

• 'Unity Netcode for Entities' package support. Animations and controllers can be synchronized using interpolated and predicted modes.
• New 'Netcode Demo' sample with 'Rukhanka' and 'Netcode for Entities' collaboration showcase.
• Animator parameter aspect to simplify animator controller parameter data manipulation.

Changed

• Minimum 'Entities' and 'Entities.Graphics' packages version is 1.0.10.

Fixed

• State machine transitions with exit time 0 were handled incorrectly.
• Transitions with exit time 1 are looped contrary to Unity documentation. 'Rukhanka' behavior changed to match 'Mecanim' in this aspect.
• Various deprecated API usage warnings.

 

Just bought it. Looks promising. Though I do notice that the skeleton Rukhanka creates ignores the "Scale Factor" in the Mesh import settings. So the scaled mesh gets applied to the unscaled skeleton and thus looks deformed. Is this by design?

 

Thank you for using Rukhanka. No, this behavior is not by design, but I have not so many test animated meshes with various scale setups. Would you be so kind as send me one example mesh plus one animation, please? I will do necessary fixes. support@rukhanka.com

 

You can test this on any skinned mesh. Since the Scale Factor is a setting in
the import settings of the mesh, not scaling on the mesh or skeleton themselves.




This is what happens when I set the Scale Factor to 2 on the Ellen asset of the sample scene

 

Looks like this is a problem with URP and skinned mesh importer. You can check this by dragging one of the models out of entity subscene and default unity animator will produce exact same results during animation and rendering.
HDRP behaves differently. If model and animation (these are in seprate files) are scaled equivalently then animation palyed correctly.

 

That's weird. I've used URP and skinned meshes before and this never happened with the Scale Factor applied. If I drag the Ellen prefab or model from the project folder into the parent scene, apply the same URP materials as the Rukhanaka version and set the Scale Factor to 2 on the model and animation files then it scales appropriately.

see in this pic the Monobehavior version looks normal while the Rukhanak versions are distorted.




Edit:

Just tested again, something strange is going on. If I copy that properly scaling version and add it to the Subscene and apply the Rukhanka rig definition script I get the proper scaling on that Entity.



edit 2:
I think it is because that the models in the example scene aren't linked to the model file/prefab anymore and are just normal gameobjects, that's why the scale didn't transfer to the skeleton. Now I just need to check why my at runtime instanced Entities are not scaling right.

edit 3:
I tested with my own models and animations and the reason why it didn't scale properly was that I needed to set the same scale factor on the animation files. Which, if I remember correctly, wasn't necessary for the normal Unity MonoBehaviour animation system. You should probably add that in the documentation.

 

Version 1.2.0 was released.

Changelog:
Added

• Compute deformation node for 'Amplify Shader Editor'. Now it is possible to make 'Entities.Graphics' deformation-compatible shaders with this tool.
• Trigger set API for 'AnimatorParametersAspect'.
• Animator parameter access performance tests.
• Own entity command buffer system for optimizing ECB usage after 'AnimationControllerSystem'.
• Animator state query aspect for access to runtime animator data.

Changed

• Animator parameter internal hash code representation was moved from Hash128 to uint. This leads to a smaller 'AnimatorControllerParameterComponent' size and better chunk utilization.

Fixed

• The state machine states without an assigned motion field had incorrect weight calculation.
• Exit and enter transition events that happened in the same frame lead to one incorrectly processed frame. This was clearly observable with transitions from/to "no-motion" states.
• Trigger parameters were reset even if the transition cumulative condition (all conditions must be true) is not met.
• Entering through the sub-state machine's 'Enter' state was handled incorrectly.
• Exiting from nested sub-state machines using the 'Exit' state was handled incorrectly.
• Multiple transitions from the 'Enter' state machine state were handled incorrectly.

 

Rukhanka is part of "Dev Days of Summer" sale. The price is reduced by 50%

 

Version 1.3.0 was released. Main feature of this version is Humanoid animation and avatars support.

Changelog
Added

• Humanoid-type support for models and animations.
• Humanoid avatar mask support.
• Humanoid avatars and animations sample scene.

Changed

• The rig definition authoring script now contains zero configuration fields. The avatar mask used for rig definition is not needed anymore. All required information Rukhanka reads from Unity Avatar. This is a breaking change. Please carefully read the upgrade process.

Fixed

• AnimatorControllerParameterComponent buffer did not replicate with NetCode.

 

Version 1.4.0 was released. This release contains a lot of changes and improvements. The most notable ones are physics collider attachment support, better root motion, and bone entity stripping feature. As a neat bonus Rukhanka is on the sale now with 50% off.

Fixed

• Several memory leaks during baking and runtime.
• Incorrect additive animation calculation for humanoid animations.

Added

• Two new sample scenes: Ragdoll and Simple Physics.
• Animation keyframe binary search was implemented.
• Rukhanka can now work with unparented bone entities. This allows to properly handle physics body bone attachments.
• Unneeded bone entity stripping functionality. Refer to documentation for the detailed description.
• Internal bone animation data is now exposed as a RuntimeAnimationData singleton.
• Full root motion support for Humanoid and Generic rigs. All root motion animation configuration parameters are supported.
• Rukhanka now requires UNITY_BURST_EXPERIMENTAL_ATOMIC_INTRINSICS script compilation symbol. It will be added to project scripting define symbols automatically if not present.

Changed

• Updated Entities dependency to version 1.0.16.
• Removed synchronization point related to AnimationToProcess buffer filling.
• Removed synchronization point related to root motion delta states processing.
• The animation process system is split into two distinct parts: animation calculation and animation application. This allows to injection of animation results post-processing and modifications (for example IK) functionality.
• Runtime created bone-name-to-index hash map was removed. It has been replaced with a blob perfect hash map created during baking time.
• Samples were moved to the samples tab of package properties. There are shared HDRP/URP sample scenes now. Materials and scene properties will adapt to the current renderer pipeline automatically.
• Animation controller layer weight is a runtime property of AnimatorControllerLayerComponent now.

 

Version 1.4.1 is out. This mostly bugfix release with important changes related to humanoid rigs. It is strongly advised to update, if you use humanoid avatars and animations (with or without root motion).
Changed

• All runtime systems TempJob allocations was changed to WorldUpdateAllocator.
• Code cleanup with more extensive SystemAPI usage.
• Moving shared utility code into separate Rukhanka.Toolbox assembly.

Fixed

• Incorrect root bone indexing for humanoid rigs.
• Incorrect non-root motion of humanoid rig hips.

 

Hi there,

The Loop Pose function in Animation Properties doesn't work under humanoid types.

You can reproduce it by setting one of EllenCombos to obviously "non-loop-match", in `HumanoidAnimationStateMachine` in 15. Humanoid Animations sample.


The pose under unity animator works with Loop Pose but baked three don't.

Using Rukhanka Animation v1.3.1 and Unity 2022.3.6f1.

 

Please update to the v1.4.1. This issue was fixed in this release.

 

Hi,
Are you planning to add animation events support in future releases? Or something else that gives similar possibilities?
Feature-wise this asset looks great, but we use a lot of events in our project and it would be hard to replace them with anything else.

 

Hi. Yes, animation events are planned in one of the next releases.

 

Hello,
I have a question about the Ragdoll example, when I change the state to ragdoll (without animation), after that I want to change the state to GetUp animation, but how do I synchronize the positions? How to start GetUp animation (its bones positions) from the ragdoll's bones LocalTransforms?

 

Hi. Your goal is achievable, but some work is required. You need to make a system that blends current bone poses (after ragdoll application) and animated bone poses for GetUp animation over some time.

Basically algorithm is follows:
* At start of "get up" event memorize bone poses for entity. Dynamic buffer component can be used for example, or attach component with recoreded pose to the entities that contains AnimatorEntityRefComponent.
* Write a system that blends between memorized pose and animated pose over time. This is simply as lerp(memPose, localTransformPose, transitionTime). Note that this system sould run after RukhankaAnimationSystemGroup.

That's all. Quick and simple "get up" sequence system. Far from ideal but maybe will fit your needs.

 

Thanks, everything is clear, except I can’t figure out how to blend between saved positions of the bones and the GetUp animation bones transforms before actually playing the animation? I think I am doing something wrong...

Code (CSharp):

1. case CharacterState.GetUpState: //GetUp event
2.  {
3.  
4.             //Memorize the Ragdoll bones transforms to MemPose component
5.             ecb.AddComponent(entity, new MemPose{
6.                 pelvisPosition = pelvis_Transform.Position,
7.                 pelvisRotation = pelvis_Transform.Rotation,
8.                 spinePosition ...
9.             });
10.  
11.             //Play the GetUp animation
12.             new ProcessInputJob() {
13.                 _clipIndex = 16,  //change to getup animation
14.                 _ragdoll = false,
15.                 _speed = 1f,
16.                 _blending = newBlend  // getup animation depends on pelvis orientation
17.             }.ScheduleParallel();
18.          
19.             break;
20. }

Now I want to blend between memorized and animated pose, but if I start the GetUp animation it's already jumps to another location

Code (CSharp):

1. [UpdateAfter(typeof(RukhankaAnimationSystemGroup))]
2. public partial struct CustomSystem : ISystem
3. {
4.        //...
5.        public void OnUpdate(ref SystemState state)
6.        {
7.              foreach ( var (memPose, animatorState, characterComponent, entity) in
8.                 SystemAPI.Query<MemPose, AnimatorStateQueryAspect, PlatformerCharacterComponent>().WithAll<MemPose>().WithEntityAccess())
9.              {
10.                 //...
11.                 var transitionState = animatorState.GetLayerCurrentTransitionInfo(0);
12.                  if (transitionState.hash == ragdollToGetUpTransitionHash)
13.                   {
14.                     //...
15.                     pelvis_Transform.Position = math.lerp(memPose.pelvisPosition, pelvis_Transform.Position, TimeData.DeltaTime);
16.                     pelvis_Transform.Rotation = math.slerp(memPose.pelvisRotation, pelvis_Transform.Rotation, TimeData.DeltaTime);
17.                     //...
18.                   }
19.  
20.               }
21.         }
22. }

I think I lost my brain) I guess I need to get the GetUp animation bone positions and lerp them before the animation starts playing, but how can I do that?

 

Sorry for late response. Turns out that things a little more complicated then expected. I forgot that at a point of time after RukhankaAnimationSystemGroup calculated animations already applied to skeleton as skinned mesh matrices, so there is no effect of modifying them after animation processing. You need to move your system after AnimationProcessSystem but before AnimationApplicationSystem. There you should modify internal Rukhanka's animation poses for bones. As reference to how to access this data for specific entity you can look at PropagateBoneTransformToEntityTRSJob. In your system you need to adjust internal bone poses by discussed earlier algorithm (lerping poses).

 

Version v1.4.2 is out. This release has some important fixes and additions related to animator state machine processing.

Fixed

• The last syncpoint of AnimationProcessSystem job has been removed by moving all frame initialization code into a separate job.
• Fixed incorrect excessive internal hash map capacity setting.
• Fixed memory leaks during blob creation in several baking systems.
• Internal perfect hash tables gain better validation. This change fixes rare creation errors from valid data.
• Correct handling of inexistent conditions during state machine baking.
• Fixed "enter transition"->"exit transition" sequence that appeared in one frame.
• Fixed warning of implicit usage of ToNativeArray() calls.
• The transition offset were measured in normalized time. It is correctly in seconds now.

Added

• Sub-state machine transitions was implemented.

Changed

• Animator parameter usage documentation has been changed to emphasize AnimatorParametersAspect as the preferred runtime interface to parameters data.

 

Hey, thank you. Everything seems clear, except how do I get the positions of bones of needed animation before applying the animation?
I mean in GetUpState I change the animation in a job with AnimatorControllerParameterComponent and it starts playing immediately. Ragdoll "jumps" to the new position of "get up" animation.
I even added my system in RukhankaSystemsBootstrap after AnimationProcessSystem but before AnimationApplicationSystem.

Code (CSharp):

1. ...
2. var boneData = RuntimeAnimationData.GetAnimationDataForRigRO(boneTransforms, entityToDataOffsetMap, rigDef, animatorRef.animatorEntity);
3.              
4. lt.Position = math.lerp(memPose.bonePosition, boneData[animatorRef.boneIndexInAnimationRig].pos, deltaTime);
5. lt.Rotation = math.slerp(memPose.boneRotation, boneData[animatorRef.boneIndexInAnimationRig].rot, deltaTime);
6. lt.Scale = boneData[animatorRef.boneIndexInAnimationRig].scale.x;

But "boneData" is an old ragdoll positions data, because the "get up" animation has not yet been applied. And if it is appllied - it jumps to its animation positions immediately...
What am I doing wrong? Help me out please

 

Hi.

boneData will contain animated bone positions. Because you are manipulating bone poses just after animation calculation, but before animations are applied to rig, you are in right spot to adjust bone positions as you wish.

Yes, bone positions are not applied yet. You need pass your lerped pose not into local transform of bone entity, but to the boneData back. To get readwrite data buffers you need to use RuntimeAnimationData.GetAnimationDataForRigRW call.

 

My apologies, but I can’t solve this for daysss now ((
When I need character to get up, I save ragdoll bones positions (LocalTransforms) to DynamicBuffer in IJobEntity:

Code (CSharp):

1.                    bonesBuffer.Add(new RagdollBonesBuffer()
2.                     {
3.                         Index = animatorRef.boneIndexInAnimationRig,
4.                         Position = lt.Position,
5.                         Rotation = lt.Rotation,
6.                         Scale = lt.Scale
7.                     });

When this job IsCompleted I change animation from Ragdoll state (with no motion) to getup state (1D blend tree) (conditions: Ragdoll = false, clipIndex = 16, Transition duration (s): 0)

Code (CSharp):

1.                    var clipIndex = animatorControllerBuffer[0];
2.                     clipIndex.IntValue = 16;
3.                     animatorControllerBuffer[0] = clipIndex;
4.                     var setRagdoll = animatorControllerBuffer[3];
5.                     setRagdoll.BoolValue = false;
6.                     animatorControllerBuffer[3] = setRagdoll;

...
In my custom system (after AnimationProcessSystem, but before AnimationApplicationSystem) I check for this buffer and write back to the boneData with IJobEntity:

Code (CSharp):

1. var boneData = RuntimeAnimationData.GetAnimationDataForRigRW(boneTransforms, entityToDataOffsetMap, rigDef, animatorRef.animatorEntity);
2.                
3. for (int i = 0; i < bonesBuffer.Length; i++)
4. {
5.                    boneData[bonesBuffer.Index].pos = math.lerp(bonesBuffer.Position, boneData[bonesBuffer.Index].pos, dt);
6.                    boneData[bonesBuffer.Index].rot = math.slerp(bonesBuffer.Rotation, boneData[bonesBuffer.Index].rot, dt);
7.                    boneData[bonesBuffer.Index].scale.x = bonesBuffer.Scale;
8. }

But it's not working. What's wrong with this logic?
Here is a demo GIF I made:

https://i.ibb.co/PWrx7bP/new-ragdoll-01.gif


And here is a demo GIF if I set Transition Duration (s) of this state to something like 0.5

https://i.ibb.co/Jr100YQ/new-ragdoll-04-transition-05.gif

there is something like lerping, but it starts from the middle of character (doesn't matter if I change root transform positions), maybe it's because there is no motion in ragdoll state..

 

Version 1.5.0 was released. Main new features of this release are Animation Results Customization with some Inverse Kinematics algorithms and Animation and Animator Controller Events.

Fixed

• The BoneTransform.Inverse function worked incorrectly with respect to scale.
• User curves were parsed incorrectly in humanoid animation clips.

Added

• Animation modification injection point represented by RukhankaAnimationInjectionSystemGroup.
• AnimationStream structure to simplify working with animation data.
• Several inverse kinematics algorithms:
  • Aim.
  • Override transform.
  • Forward And Backward Reaching Inverse Kinematics (FABRIK).
  • Two Bone.
• Animation events.
• Animator controller events.
• The debug bone renderer was extended to be able to draw various primitive geometry (lines, triangles, cones, cubes, etc.) and moved to separate DebugDrawer assembly. It is independent from other Rukhanka assemblies and can be used as a standalone library.
• Two new samples: Events and IK.

Changed

• The package's internal name has been changed to com.rukhanka.animation.
• Bone stripping functionality has an additional Automatic mode now.
• The RukhankaDebugConfiguration new options to log all animation and animator controller events.
• Multiple bone visualization systems can run. This is useful to display skeletons in multiple worlds (particularly when using NetCode).

 

Sorry, compeletely forgot to answer you during v1.5.0 preparation. Are you succeed with your task. Actually it is hard to say what is going wrong without actual debugging.I am suggesting to enable bone visualization and do a frame-by-frame investigation.

 

Terrific! these 2 features are most required for us at present.
Much appreciated!

 

Version 1.5.1 was released. This is mostly a small bug fix release.

[1.5.1]
Fixed

• Removed empty DebugDrawer draw calls in case of no primitives submitted.
• Server world missed the animation injection system group.
• Some memory leaks during baking.

Added

• Duplicated bone names checker during baking.

Changed

• AnimationStream bone hierarchy recalculation rework. There is no need for RebuildOutdatedBonePoses explicit calls anymore. All dependent bones will be recalculated automatically during Get calls. AnimationStream is derived from an IDisposable interface now, and disposal is required after its usage.

 

Version 1.6.0 was released. New features of this release are Animation Frustum Culling and Skinned Mesh Bounding Box Recalculation. Please read appropriate documentation sections about new features. Incorrect configuration can lead to errors/degraded performance. Also note that minimum Entities version is set to 1.2.0-pre.6 for this release.

[1.6.0]
Fixed

• User curves incorrect multiple layers blending.
• IK targets incorrect world pose calculation if the animated entity is not a hierarchy root.

Added

• Animation frustum culling ability.
• Skinned mesh renderer bounding box recalculation ability.
• Sample showcase scene to demonstrate animation culling and bounding box recalculation features.
• IsInTransition utility function of AnimatorStateQueryAspect.

Changed

• Updated Entities dependency to version 1.2.0-pre.6
• Making DebugDrawer a client only system.

 

Version 1.6.1 was released. This is a small bugfix release mostly dedicated to the DebugDrawer fix related to the line rendering.

[1.6.1]
Fixed

• DebugDrawer incorrect line renderer in Unity versions newer than 2022.3.17f1.
• Authoring object copy for animation sampling is not created if avatar is missing on animator.

 

Version 1.6.2 was released. This release mostly dedicated to animation events fixes: negative animation direction, big animation steps, edge cases, etc.

[1.6.2]
Fixed

• Animation events edge cases (start and end animation).
• Correcting events for looped animations.
• Exception during renderers bounding box recalculation if skinned mesh renderer root bone property is null.

 

this looks really awesome and is one of the key things currently missing the the unity dots area.. i just need to save up before buying

 

Version 1.6.3 was released.

[1.6.3]
Changed

• Reverting Entities dependency to version 1.0.16 with appropriate changes. No functionality was affected.