fix: NetworkAnimator conditional exit transitions (2.0.0) (#4240)

* Fix NetworkAnimator conditional exit transitions

* fix: resolve NetworkAnimator root and parent Entry exits, match lookup by originating state

- Exit from the root state machine, or from a sub-state machine with no outgoing transition, resolves through the Entry node.
- Trigger transitions into a sub-state machine resolve to its default and entry states.
- The late-join lookup keeps every transition into a destination and picks the one from the current originating state.
- Editor tests are guarded by COM_UNITY_MODULES_ANIMATION, with the define added to the test asmdef.
- CHANGELOG entry.

* test: use the develop-2.0.0 editor test namespace for NetworkAnimatorEditorTests

* fix: late-joining client cross-fades when not on the originating state

A late-joining client starts in its default state, so requiring the originating state left it stuck there. Adds a runtime test that joins mid-transition from a non-default state.

* chore: add PR number to CHANGELOG entry

* fix: match NetworkAnimator transition info by originating state only

Transitions not in the table no longer fall back to the first entry for the destination, and a missing sub-state machine reference no longer throws while the table is built.

* fix: late-joining client cross-fades from the originating state

CrossFade normalizes the transition duration to the current state's length, so cross-fading from the default state blended at the wrong speed when the clip lengths differ.

---------

Co-authored-by: B. Zaky <benrabahzaky@gmail.com>

Author: NoelStephensUnity

com.unity.netcode.gameobjects/CHANGELOG.md

@@ -22,8 +22,9 @@ Additional documentation and release notes are available at [Multiplayer Documen
 
 ### Fixed
 
-- Issue where bits written with `BitWriter` were lost when a later `BitWriter.TryBeginWriteBits` call in the same bitwise context grew the `FastBufferWriter`. The bytes written earlier in that context were replaced with zeros or uninitialized memory. (#4225)
+- Issue where `NetworkAnimator` logged an error for a trigger-conditioned transition into an Exit node, and a client that joined during that transition, or during one into a sub-state machine, did not synchronize with it. Transitions that pass through Exit, Entry or sub-state machine nodes now resolve to the state they reach, and a late-joining client cross-fades from the matching originating state when several states transition into the same destination. (#4240)
 - Issue where `NetworkTime` reported a `TickOffset` of almost a whole tick, instead of zero, for some times that land on a tick (for example 0.3 at a tick rate of 10), which put `TickWithPartial` one tick ahead or, in long sessions, `Tick` one tick behind. Times between minus one tick and zero now report tick -1 with a positive `TickOffset`, as other negative times do. (#4227)
+- Issue where bits written with `BitWriter` were lost when a later `BitWriter.TryBeginWriteBits` call in the same bitwise context grew the `FastBufferWriter`. The bytes written earlier in that context were replaced with zeros or uninitialized memory. (#4225)
 - Issue where a growable `FastBufferWriter` created with a size of 0 never returned from its first write or `TryBeginWrite` call that needed the buffer to grow. (#4223)
 - Issue where a `FastBufferReader` created with an offset and the default length of -1 read past the end of its source. The `ArraySegment<byte>` overload that takes an offset now applies it from the start of the segment. (#4221)
 - Issue where a client promoted to session owner could throw an exception when synchronizing a newly joining client. (#4217)

com.unity.netcode.gameobjects/Runtime/Components/NetworkAnimator.cs

@@ -272,8 +272,8 @@ public Animator Animator
         internal List<TransitionStateInfo> TransitionStateInfoList;
 
         // Used to get the associated transition information required to synchronize late joining clients with transitions
-        // [Layer][DestinationState][TransitionStateInfo]
-        private readonly Dictionary<int, Dictionary<int, TransitionStateInfo>> m_DestinationStateToTransitionInfo = new Dictionary<int, Dictionary<int, TransitionStateInfo>>();
+        // [Layer][DestinationState][TransitionStateInfo per originating state]
+        private readonly Dictionary<int, Dictionary<int, List<TransitionStateInfo>>> m_DestinationStateToTransitionInfo = new Dictionary<int, Dictionary<int, List<TransitionStateInfo>>>();
 
         // Named differently to avoid serialization conflicts with NetworkBehaviour
         internal NetworkManager LocalNetworkManager;
@@ -285,14 +285,43 @@ public Animator Animator
         /// </summary>
         private void BuildDestinationToTransitionInfoTable()
         {
+            m_DestinationStateToTransitionInfo.Clear();
             foreach (var entry in TransitionStateInfoList)
             {
-                m_DestinationStateToTransitionInfo.TryAdd(entry.Layer, new Dictionary<int, TransitionStateInfo>());
+                m_DestinationStateToTransitionInfo.TryAdd(entry.Layer, new Dictionary<int, List<TransitionStateInfo>>());
                 var destinationStateTransitionInfo = m_DestinationStateToTransitionInfo[entry.Layer];
-                destinationStateTransitionInfo.TryAdd(entry.DestinationState, entry);
+                if (!destinationStateTransitionInfo.TryGetValue(entry.DestinationState, out var transitions))
+                {
+                    transitions = new List<TransitionStateInfo>();
+                    destinationStateTransitionInfo.Add(entry.DestinationState, transitions);
+                }
+                transitions.Add(entry);
             }
         }
 
+        /// <summary>
+        /// Gets the transition info for a destination state, matched by originating state since several states can
+        /// transition into the same destination. Transitions not in the table, such as non-trigger ones, return false.
+        /// </summary>
+        internal bool TryGetTransitionInfo(int layer, int destinationState, int originatingState, out TransitionStateInfo transitionInfo)
+        {
+            transitionInfo = null;
+            if (!m_DestinationStateToTransitionInfo.TryGetValue(layer, out var layerTransitions) || !layerTransitions.TryGetValue(destinationState, out var transitions))
+            {
+                return false;
+            }
+
+            foreach (var entry in transitions)
+            {
+                if (entry.OriginatingState == originatingState)
+                {
+                    transitionInfo = entry;
+                    return true;
+                }
+            }
+            return false;
+        }
+
         [Serializable]
         internal class AnimatorParameterEntry
         {
@@ -323,7 +352,83 @@ internal class AnimatorParametersListContainer
 
         private readonly Dictionary<int, AnimatorControllerParameter> m_ParameterToNameLookup = new Dictionary<int, AnimatorControllerParameter>();
 
-        private void ParseStateMachineStates(int layerIndex, ref AnimatorController animatorController, ref AnimatorStateMachine stateMachine)
+        private void AddTransitionStateInfo(int layerIndex, AnimatorState originatingState, AnimatorState destinationState, AnimatorStateTransition transition, AnimatorControllerParameter parameter, int transitionIndex)
+        {
+            var transitionInfo = new TransitionStateInfo()
+            {
+                Layer = layerIndex,
+                OriginatingState = originatingState.nameHash,
+                DestinationState = destinationState.nameHash,
+                TransitionDuration = transition.duration,
+                TriggerNameHash = parameter.nameHash,
+                TransitionIndex = transitionIndex
+            };
+            TransitionStateInfoList.Add(transitionInfo);
+        }
+
+        private void AddStateMachineDestinations(int layerIndex, AnimatorState originatingState, AnimatorStateMachine destinationStateMachine, AnimatorStateTransition transition,
+            AnimatorControllerParameter parameter, int transitionIndex, HashSet<AnimatorStateMachine> visitedStateMachines)
+        {
+            if (!visitedStateMachines.Add(destinationStateMachine))
+            {
+                return;
+            }
+
+            if (destinationStateMachine.defaultState != null)
+            {
+                AddTransitionStateInfo(layerIndex, originatingState, destinationStateMachine.defaultState, transition, parameter, transitionIndex);
+            }
+
+            foreach (var entryTransition in destinationStateMachine.entryTransitions)
+            {
+                if (entryTransition.destinationState != null)
+                {
+                    AddTransitionStateInfo(layerIndex, originatingState, entryTransition.destinationState, transition, parameter, transitionIndex);
+                }
+                else if (entryTransition.destinationStateMachine != null)
+                {
+                    AddStateMachineDestinations(layerIndex, originatingState, entryTransition.destinationStateMachine, transition, parameter, transitionIndex, visitedStateMachines);
+                }
+            }
+        }
+
+        private void AddExitTransitionStateInfo(int layerIndex, AnimatorState originatingState, AnimatorStateMachine exitingStateMachine, AnimatorStateTransition transition,
+            AnimatorControllerParameter parameter, int transitionIndex, List<AnimatorStateMachine> parentStateMachines, int parentIndex)
+        {
+            // Exiting the layer's root state machine re-enters it through its Entry node
+            if (parentIndex < 0)
+            {
+                AddStateMachineDestinations(layerIndex, originatingState, exitingStateMachine, transition, parameter, transitionIndex, new HashSet<AnimatorStateMachine>());
+                return;
+            }
+
+            var parentStateMachine = parentStateMachines[parentIndex];
+            var stateMachineTransitions = parentStateMachine.GetStateMachineTransitions(exitingStateMachine);
+            // With no transition out of the sub-state machine, its Exit goes through the parent's Entry node
+            if (stateMachineTransitions.Length == 0)
+            {
+                AddStateMachineDestinations(layerIndex, originatingState, parentStateMachine, transition, parameter, transitionIndex, new HashSet<AnimatorStateMachine>());
+                return;
+            }
+
+            foreach (var stateMachineTransition in stateMachineTransitions)
+            {
+                if (stateMachineTransition.destinationState != null)
+                {
+                    AddTransitionStateInfo(layerIndex, originatingState, stateMachineTransition.destinationState, transition, parameter, transitionIndex);
+                }
+                else if (stateMachineTransition.destinationStateMachine != null)
+                {
+                    AddStateMachineDestinations(layerIndex, originatingState, stateMachineTransition.destinationStateMachine, transition, parameter, transitionIndex, new HashSet<AnimatorStateMachine>());
+                }
+                else if (stateMachineTransition.isExit)
+                {
+                    AddExitTransitionStateInfo(layerIndex, originatingState, parentStateMachine, transition, parameter, transitionIndex, parentStateMachines, parentIndex - 1);
+                }
+            }
+        }
+
+        private void ParseStateMachineStates(int layerIndex, ref AnimatorController animatorController, ref AnimatorStateMachine stateMachine, List<AnimatorStateMachine> parentStateMachines = null)
         {
             for (int y = 0; y < stateMachine.states.Length; y++)
             {
@@ -355,23 +460,17 @@ private void ParseStateMachineStates(int layerIndex, ref AnimatorController anim
                             {
                                 case AnimatorControllerParameterType.Trigger:
                                     {
-                                        if (transition.destinationStateMachine != null)
+                                        if (transition.destinationState != null)
+                                        {
+                                            AddTransitionStateInfo(layerIndex, animatorState, transition.destinationState, transition, parameter, z);
+                                        }
+                                        else if (transition.isExit)
                                         {
-                                            var destinationStateMachine = transition.destinationStateMachine;
-                                            ParseStateMachineStates(layerIndex, ref animatorController, ref destinationStateMachine);
+                                            AddExitTransitionStateInfo(layerIndex, animatorState, stateMachine, transition, parameter, z, parentStateMachines, parentStateMachines != null ? parentStateMachines.Count - 1 : -1);
                                         }
-                                        else if (transition.destinationState != null)
+                                        else if (transition.destinationStateMachine != null)
                                         {
-                                            var transitionInfo = new TransitionStateInfo()
-                                            {
-                                                Layer = layerIndex,
-                                                OriginatingState = animatorState.nameHash,
-                                                DestinationState = transition.destinationState.nameHash,
-                                                TransitionDuration = transition.duration,
-                                                TriggerNameHash = parameter.nameHash,
-                                                TransitionIndex = z
-                                            };
-                                            TransitionStateInfoList.Add(transitionInfo);
+                                            AddStateMachineDestinations(layerIndex, animatorState, transition.destinationStateMachine, transition, parameter, z, new HashSet<AnimatorStateMachine>());
                                         }
                                         else
                                         {
@@ -387,6 +486,18 @@ private void ParseStateMachineStates(int layerIndex, ref AnimatorController anim
                     }
                 }
             }
+
+            var childStateMachineParents = parentStateMachines != null ? new List<AnimatorStateMachine>(parentStateMachines) : new List<AnimatorStateMachine>();
+            childStateMachineParents.Add(stateMachine);
+            foreach (var childStateMachine in stateMachine.stateMachines)
+            {
+                var nestedStateMachine = childStateMachine.stateMachine;
+                // A missing sub-state machine asset reference leaves this null
+                if (nestedStateMachine != null)
+                {
+                    ParseStateMachineStates(layerIndex, ref animatorController, ref nestedStateMachine, childStateMachineParents);
+                }
+            }
         }
 
         /// <summary>
@@ -996,14 +1107,11 @@ private void WriteSynchronizationData<T>(ref BufferSerializer<T> serializer) whe
                         stateHash = nextState.fullPathHash;
 
                         // Check if this transition can be synchronized using cross-fading
-                        if (m_DestinationStateToTransitionInfo.TryGetValue(layer, out var layerTransitions))
+                        if (TryGetTransitionInfo(layer, nextState.shortNameHash, synchronizationStateInfo.shortNameHash, out var transitionInfo))
                         {
-                            if (layerTransitions.TryGetValue(nextState.shortNameHash, out var transitionInfo))
-                            {
-                                stateHash = transitionInfo.OriginatingState;
-                                // Set the destination state to cross-fade to from the originating state
-                                animationState.DestinationStateHash = transitionInfo.DestinationState;
-                            }
+                            stateHash = transitionInfo.OriginatingState;
+                            // Set the destination state to cross-fade to from the originating state
+                            animationState.DestinationStateHash = transitionInfo.DestinationState;
                         }
                     }
 
@@ -1460,13 +1568,20 @@ private void UpdateAnimationState(AnimationState animationState)
             {
                 // At this point all entries in the lookup table should be valid.
                 // Look up the transition info for this layer and destination state.
-                if (m_DestinationStateToTransitionInfo.TryGetValue(animationState.Layer, out var layerTransitions))
+                if (m_DestinationStateToTransitionInfo.ContainsKey(animationState.Layer))
                 {
-                    if (layerTransitions.TryGetValue(animationState.DestinationStateHash, out var transitionInfo))
+                    if (TryGetTransitionInfo(animationState.Layer, animationState.DestinationStateHash, animationState.StateHash, out var transitionInfo))
                     {
-                        // Make sure we are on the originating/starting state we are going to cross-fade into
-                        if (currentState.shortNameHash == animationState.StateHash)
+                        var onOriginatingState = currentState.shortNameHash == animationState.StateHash;
+                        if (onOriginatingState || !m_Animator.IsInTransition(animationState.Layer))
                         {
+                            // A late-joining client starts in its default state. CrossFade normalizes the duration to the
+                            // current state's length, so enter the originating state first and apply it before cross-fading.
+                            if (!onOriginatingState)
+                            {
+                                m_Animator.Play(animationState.StateHash, animationState.Layer, 0.0f);
+                                m_Animator.Update(0.0f);
+                            }
                             // Cross-fade from the current to the destination state for the transitions duration while starting at the server's current normalized time of the transition
                             m_Animator.CrossFade(transitionInfo.DestinationState, transitionInfo.TransitionDuration, transitionInfo.Layer, 0.0f, animationState.NormalizedTime);
                         }