Tweak brake cylinder animations to work within the limits of .s files

Author: SteelFill

Source/Documentation/Manual/features-rollingstock.rst

@@ -1560,12 +1560,14 @@ start with `ORTSBRAKECYLINDER`. This animation type should NOT be used for any b
 that can be actuated by the brake cylinder and the handbrakes. See the section on brake rigging
 animation for details.
 
-Unlike other animation types, the keyframes for brake cylinders do not represent time.
-Instead, the key value represents the level of brake cylinder extension. A value of 0.8
-represents the state where the brake cylinder has taken up the slack in the brake rigging,
-1.0 represents the level of brake cylinder extension at 50 psi/3.5 bar, and the maximum
-value of cylinder extension is 1.6, which should not be possible in normal operation.
-These values are the same regardless of the settings used in the engine or wagon file.
+Unlike other animation types, the keyframes for brake cylinders do not represent time, and cannot
+be set to arbitrary values. Instead, the key value represents the level of brake cylinder
+extension. A keyframe value of 8 represents the state where the brake cylinder has taken up the
+slack in the brake rigging, 10 represents the level of brake cylinder extension at 50 psi/3.5
+bar, and the maximum value of cylinder extension is 16, which should not be possible in normal
+operation. These values are the same regardless of the settings used in the engine or wagon file.
+NOTE: Brake animations should at minimum have 2 animation frames, one at keyframe 0 and the
+second at keyframe 8. Other keyframes are optional and may be included to fine-tune the animation.
 
 Note that the advanced brake cylinder calculations are only run on air brake systems on the
 player train to save computing power. As such, brake cylinder animations on AI trains
@@ -1575,7 +1577,8 @@ Handbrake Animation
 -------------------
 
 Handbrake wheels and levers can also be animated using the same process as two-state animations
-such as mirrors. The matrix name for animated handbrakes must begin with `ORTSHANDBRAKE`.
+such as mirrors, and the keyframe values will represent time in seconds like other animations.
+The matrix name for animated handbrakes must begin with `ORTSHANDBRAKE`.
 
 Brake Rigging and Brake Shoe Animation
 --------------------------------------
@@ -1585,10 +1588,10 @@ this includes brake rigging and brake shoes, but sometimes also includes brake c
 use animations with a matrix name starting with `ORTSBRAKERIGGING`. For this type of animation, the
 animation state will respond to the brake cylinder travel or the handbrake, whichever input is greater.
 
-The same keyframe rules as brake cylinder animations apply here. The 0.8 key should represent the state
+The same keyframe rules as brake cylinder animations apply here. A key value of 8 should represent the state
 where the brake shoes have made contact with the friction surface, and no further motion of brake shoes
-should occur after 0.8. Applying the handbrake will drive the animation to the 1.0 state, the same
-as a 50 psi/3.5 bar application of the brakes.
+should occur after 8, though the brake levers may still animate beyond this point. Applying the
+handbrake will also drive the animation to keyframe 10 (ie: same as 50 psi/3.5 bar application).
 
 Coupler and Airhose Animation
 =============================

Source/Orts.Simulation/Simulation/RollingStocks/SubSystems/Brakes/MSTS/ManualBraking.cs

@@ -358,7 +358,7 @@ public override float GetTotalCylVolumeM3()
 
         public override float GetNormalizedCylTravel()
         {
-            return ManualBrakingCurrentFraction;
+            return Car.BrakeShoeForceN > 0.0f ? 1.0f : 0.0f;
         }
 
         public override float GetVacResVolume()

Source/RunActivity/Viewer3D/AnimatedPart.cs

@@ -31,8 +31,8 @@ public class AnimatedPart
         // Shape that we're animating.
         readonly PoseableShape PoseableShape;
 
-        // Number of animation key-frames that are used by this part. This is calculated from the matrices provided.
-        public int FrameCount;
+        // Maximum animation key-frame value used by this part. This is calculated from the matrices provided.
+        public int MaxFrame;
 
         // Current frame of the animation.
         float AnimationKey;
@@ -55,26 +55,26 @@ public void AddMatrix(int matrix)
         {
             if (matrix < 0) return;
             MatrixIndexes.Add(matrix);
-            UpdateFrameCount(matrix);
+            UpdateMaxFrame(matrix);
         }
 
-        void UpdateFrameCount(int matrix)
+        void UpdateMaxFrame(int matrix)
         {
             if (PoseableShape.SharedShape.Animations != null
                 && PoseableShape.SharedShape.Animations.Count > 0
                 && PoseableShape.SharedShape.Animations[0].anim_nodes.Count > matrix
                 && PoseableShape.SharedShape.Animations[0].anim_nodes[matrix].controllers.Count > 0
                 && PoseableShape.SharedShape.Animations[0].anim_nodes[matrix].controllers[0].Count > 0)
             {
-                FrameCount = Math.Max(FrameCount, PoseableShape.SharedShape.Animations[0].anim_nodes[matrix].controllers[0].ToArray().Cast<KeyPosition>().Last().Frame);
+                MaxFrame = Math.Max(MaxFrame, PoseableShape.SharedShape.Animations[0].anim_nodes[matrix].controllers[0].ToArray().Cast<KeyPosition>().Last().Frame);
                 // Sometimes there are more frames in the second controller than in the first
                 if (PoseableShape.SharedShape.Animations[0].anim_nodes[matrix].controllers.Count > 1
                 && PoseableShape.SharedShape.Animations[0].anim_nodes[matrix].controllers[1].Count > 0)
-                    FrameCount = Math.Max(FrameCount, PoseableShape.SharedShape.Animations[0].anim_nodes[matrix].controllers[1].ToArray().Cast<KeyPosition>().Last().Frame);
+                    MaxFrame = Math.Max(MaxFrame, PoseableShape.SharedShape.Animations[0].anim_nodes[matrix].controllers[1].ToArray().Cast<KeyPosition>().Last().Frame);
             }
             for (var i = 0; i < PoseableShape.Hierarchy.Length; i++)
                 if (PoseableShape.Hierarchy[i] == matrix)
-                    UpdateFrameCount(i);
+                    UpdateMaxFrame(i);
         }
 
         /// <summary>
@@ -98,7 +98,7 @@ void SetFrame(float frame)
         /// </summary>
         public void SetFrameClamp(float frame)
         {
-            if (frame > FrameCount) frame = FrameCount;
+            if (frame > MaxFrame) frame = MaxFrame;
             if (frame < 0) frame = 0;
             SetFrame(frame);
         }
@@ -109,8 +109,8 @@ public void SetFrameClamp(float frame)
         public void UpdateFrameClamp(float frame, ElapsedTime elapsedTime)
         {
             float newState;
-            if (Math.Abs(frame - AnimationKey) > 1.0f * elapsedTime.ClockSeconds)
-                newState = AnimationKey + Math.Sign(frame - AnimationKey) * elapsedTime.ClockSeconds;
+            if (Math.Abs(frame - AnimationKey) > 10.0f * elapsedTime.ClockSeconds)
+                newState = AnimationKey + Math.Sign(frame - AnimationKey) * 10.0f * elapsedTime.ClockSeconds;
             else
                 newState = frame;
 
@@ -122,19 +122,19 @@ public void UpdateFrameClamp(float frame, ElapsedTime elapsedTime)
         /// </summary>
         public void SetFrameCycle(float frame)
         {
-            // Animates from 0-FrameCount then FrameCount-0 for values of 0>=frame<=2*FrameCount.
-            SetFrameClamp(FrameCount - Math.Abs(frame - FrameCount));
+            // Animates from 0-MaxFrame then MaxFrame-0 for values of 0>=frame<=2*MaxFrame.
+            SetFrameClamp(MaxFrame - Math.Abs(frame - MaxFrame));
         }
 
         /// <summary>
         /// Sets the animation to a particular frame whilst wrapping it around the frame count range.
         /// </summary>
         public void SetFrameWrap(float frame)
         {
-            // Wrap the frame around 0-FrameCount without hanging when FrameCount=0.
-            while (FrameCount > 0 && frame < 0) frame += FrameCount;
+            // Wrap the frame around 0-MaxFrame without hanging when MaxFrame=0.
+            while (MaxFrame > 0 && frame < 0) frame += MaxFrame;
             if (frame < 0) frame = 0;
-            frame %= FrameCount;
+            frame %= MaxFrame;
             SetFrame(frame);
         }
 
@@ -143,7 +143,7 @@ public void SetFrameWrap(float frame)
         /// </summary>
         public void SetState(bool state)
         {
-            SetFrame(state ? FrameCount : 0);
+            SetFrame(state ? MaxFrame : 0);
         }
 
         /// <summary>
@@ -161,23 +161,23 @@ public void UpdateState(bool state, ElapsedTime elapsedTime)
         public float UpdateAndReturnState(bool state, ElapsedTime elapsedTime)
         {
             SetFrameClamp(AnimationKey + (state ? 1 : -1) * elapsedTime.ClockSeconds);
-            return AnimationKey / FrameCount;
+            return AnimationKey / MaxFrame;
         }
 
         /// <summary>
         /// Returns the animation key fraction (between 0 and 1)
         /// </summary>
         public float AnimationKeyFraction()
         {
-            return AnimationKey / FrameCount;
+            return AnimationKey / MaxFrame;
         }
 
         /// <summary>
         /// Updates an animated part that loops (e.g. running gear), changing by the given amount.
         /// </summary>
         public void UpdateLoop(float change)
         {
-            if (PoseableShape.SharedShape.Animations == null || PoseableShape.SharedShape.Animations.Count == 0 || FrameCount == 0)
+            if (PoseableShape.SharedShape.Animations == null || PoseableShape.SharedShape.Animations.Count == 0 || MaxFrame == 0)
                 return;
 
             // The speed of rotation is set at 8 frames of animation per rotation at 30 FPS (so 16 frames = 60 FPS, etc.).
@@ -190,12 +190,12 @@ public void UpdateLoop(float change)
         /// </summary>
         public void UpdateLoop(bool running, ElapsedTime elapsedTime, float frameRateMultiplier = 1.5f)
         {
-            if (PoseableShape.SharedShape.Animations == null || PoseableShape.SharedShape.Animations.Count == 0 || FrameCount == 0)
+            if (PoseableShape.SharedShape.Animations == null || PoseableShape.SharedShape.Animations.Count == 0 || MaxFrame == 0)
                 return;
 
             // The speed of cycling is as default 1.5 frames of animation per second at 30 FPS.
             var frameRate = PoseableShape.SharedShape.Animations[0].FrameRate * frameRateMultiplier / 30f;
-            if (running || (AnimationKey > 0 && AnimationKey + elapsedTime.ClockSeconds * frameRate < FrameCount))
+            if (running || (AnimationKey > 0 && AnimationKey + elapsedTime.ClockSeconds * frameRate < MaxFrame))
                 SetFrameWrap(AnimationKey + elapsedTime.ClockSeconds * frameRate);
             else
                 SetFrame(0);

Source/RunActivity/Viewer3D/RollingStock/MSTSLocomotiveViewer.cs

@@ -4206,7 +4206,7 @@ public void Update(MSTSLocomotiveViewer locoViewer, ElapsedTime elapsedTime)
 
             if (locoViewer.ThreeDimentionCabRenderer.ControlMap.TryGetValue(Key, out CabViewControlRenderer cvfr))
             {
-                float index = cvfr is CabViewDiscreteRenderer renderer ? renderer.GetDrawIndex() : cvfr.GetRangeFraction() * FrameCount;
+                float index = cvfr is CabViewDiscreteRenderer renderer ? renderer.GetDrawIndex() : cvfr.GetRangeFraction() * MaxFrame;
                 SetFrameClamp(index);
             }
         }

Source/RunActivity/Viewer3D/RollingStock/MSTSWagonViewer.cs

@@ -437,9 +437,9 @@ from data in effect.Value
             RightWindowRear.SetState(MSTSWagon.WindowStates[MSTSWagon.RightWindowRearIndex] >= MSTSWagon.WindowState.Opening);
             Item1TwoState.SetState(MSTSWagon.GenericItem1);
             Item2TwoState.SetState(MSTSWagon.GenericItem2);
-            BrakeCylinders.SetFrameClamp(MSTSWagon.BrakeSystem.GetNormalizedCylTravel());
+            BrakeCylinders.SetFrameClamp(MSTSWagon.BrakeSystem.GetNormalizedCylTravel() * 10.0f);
             Handbrakes.SetState(MSTSWagon.GetTrainHandbrakeStatus());
-            BrakeRigging.SetFrameClamp(Math.Max(MSTSWagon.BrakeSystem.GetNormalizedCylTravel(), MSTSWagon.GetTrainHandbrakeStatus() ? 1.0f : 0.0f));
+            BrakeRigging.SetFrameClamp(Math.Max(MSTSWagon.BrakeSystem.GetNormalizedCylTravel(), MSTSWagon.GetTrainHandbrakeStatus() ? 1.0f : 0.0f) * 10.0f);
             UnloadingParts.SetState(MSTSWagon.UnloadingPartsOpen);
 
             InitializeUserInputCommands();
@@ -690,9 +690,9 @@ public override void PrepareFrame(RenderFrame frame, ElapsedTime elapsedTime)
             UnloadingParts.UpdateState(MSTSWagon.UnloadingPartsOpen, elapsedTime);
             Item1TwoState.UpdateState(MSTSWagon.GenericItem1, elapsedTime);
             Item2TwoState.UpdateState(MSTSWagon.GenericItem2, elapsedTime);
-            BrakeCylinders.UpdateFrameClamp(MSTSWagon.BrakeSystem.GetNormalizedCylTravel(), elapsedTime);
+            BrakeCylinders.UpdateFrameClamp(MSTSWagon.BrakeSystem.GetNormalizedCylTravel() * 10.0f, elapsedTime);
             Handbrakes.UpdateState(MSTSWagon.GetTrainHandbrakeStatus(), elapsedTime);
-            BrakeRigging.UpdateFrameClamp(Math.Max(MSTSWagon.BrakeSystem.GetNormalizedCylTravel(), MSTSWagon.GetTrainHandbrakeStatus() ? 1.0f : 0.0f), elapsedTime);
+            BrakeRigging.UpdateFrameClamp(Math.Max(MSTSWagon.BrakeSystem.GetNormalizedCylTravel(), MSTSWagon.GetTrainHandbrakeStatus() ? 1.0f : 0.0f) * 10.0f, elapsedTime);
             UpdateAnimation(frame, elapsedTime);
 
             var car = Car as MSTSWagon;
@@ -774,11 +774,11 @@ public override void PrepareFrame(RenderFrame frame, ElapsedTime elapsedTime)
                 foreach (ParticleEmitterViewer drawer in drawers)
                     drawer.PrepareFrame(frame, elapsedTime);
 
-            if (!(car is MSTSLocomotive) && (LeftWindowFront.FrameCount > 0 || RightWindowFront.FrameCount > 0))
+            if (!(car is MSTSLocomotive) && (LeftWindowFront.MaxFrame > 0 || RightWindowFront.MaxFrame > 0))
             {
-                if (LeftWindowFront.FrameCount > 0)
+                if (LeftWindowFront.MaxFrame > 0)
                     car.SoundHeardInternallyCorrection[MSTSWagon.LeftWindowFrontIndex] = LeftWindowFront.AnimationKeyFraction();
-                if (RightWindowFront.FrameCount > 0)
+                if (RightWindowFront.MaxFrame > 0)
                     car.SoundHeardInternallyCorrection[MSTSWagon.RightWindowFrontIndex] = RightWindowFront.AnimationKeyFraction();
             }
         }