Merge pull request #13894 from peppy/fix-beat-synced-container-alt

Fix multiple issues with `BeatSyncedContainer`

osu.Game/Graphics/Containers/BeatSyncedContainer.cs

@@ -1,19 +1,32 @@
 // Copyright (c) ppy Pty Ltd <contact@ppy.sh>. Licensed under the MIT Licence.
 // See the LICENCE file in the repository root for full licence text.
 
+using System;
+using System.Diagnostics;
 using osu.Framework.Allocation;
 using osu.Framework.Audio.Track;
 using osu.Framework.Bindables;
 using osu.Framework.Graphics.Containers;
+using osu.Framework.Timing;
 using osu.Game.Beatmaps;
 using osu.Game.Beatmaps.ControlPoints;
+using osu.Game.Screens.Play;
 
 namespace osu.Game.Graphics.Containers
 {
+    /// <summary>
+    /// A container which fires a callback when a new beat is reached.
+    /// Consumes a parent <see cref="GameplayClock"/> or <see cref="Beatmap"/> (whichever is first available).
+    /// </summary>
+    /// <remarks>
+    /// This container does not set its own clock to the source used for beat matching.
+    /// This means that if the beat source clock is playing faster or slower, animations may unexpectedly overlap.
+    /// Make sure this container's Clock is also set to the expected source (or within a parent element which provides this).
+    ///
+    /// This container will also trigger beat events when the beat matching clock is paused at <see cref="TimingControlPoint.DEFAULT"/>'s BPM.
+    /// </remarks>
     public class BeatSyncedContainer : Container
     {
-        protected readonly IBindable<WorkingBeatmap> Beatmap = new Bindable<WorkingBeatmap>();
-
         private int lastBeat;
         private TimingControlPoint lastTimingPoint;
 
@@ -23,6 +36,19 @@ namespace osu.Game.Graphics.Containers
         /// </summary>
         protected double EarlyActivationMilliseconds;
 
+        /// <summary>
+        /// While this container automatically applied an animation delay (meaning any animations inside a <see cref="OnNewBeat"/> implementation will
+        /// always be correctly timed), the event itself can potentially fire away from the related beat.
+        ///
+        /// By setting this to false, cases where the event is to be fired more than <see cref="MISTIMED_ALLOWANCE"/> from the related beat will be skipped.
+        /// </summary>
+        protected bool AllowMistimedEventFiring = true;
+
+        /// <summary>
+        /// The maximum deviance from the actual beat that an <see cref="OnNewBeat"/> can fire when <see cref="AllowMistimedEventFiring"/> is set to false.
+        /// </summary>
+        public const double MISTIMED_ALLOWANCE = 16;
+
         /// <summary>
         /// The time in milliseconds until the next beat.
         /// </summary>
@@ -43,16 +69,49 @@ namespace osu.Game.Graphics.Containers
         /// </summary>
         public double MinimumBeatLength { get; set; }
 
+        /// <summary>
+        /// Whether this container is currently tracking a beatmap's timing data.
+        /// </summary>
         protected bool IsBeatSyncedWithTrack { get; private set; }
 
+        protected virtual void OnNewBeat(int beatIndex, TimingControlPoint timingPoint, EffectControlPoint effectPoint, ChannelAmplitudes amplitudes)
+        {
+        }
+
+        [Resolved]
+        protected IBindable<WorkingBeatmap> Beatmap { get; private set; }
+
+        [Resolved(canBeNull: true)]
+        protected GameplayClock GameplayClock { get; private set; }
+
+        protected IClock BeatSyncClock
+        {
+            get
+            {
+                if (GameplayClock != null)
+                    return GameplayClock;
+
+                if (Beatmap.Value.TrackLoaded)
+                    return Beatmap.Value.Track;
+
+                return null;
+            }
+        }
+
         protected override void Update()
         {
             ITrack track = null;
             IBeatmap beatmap = null;
 
-            double currentTrackTime = 0;
-            TimingControlPoint timingPoint = null;
-            EffectControlPoint effectPoint = null;
+            TimingControlPoint timingPoint;
+            EffectControlPoint effectPoint;
+
+            IClock clock = BeatSyncClock;
+
+            if (clock == null)
+                return;
+
+            double currentTrackTime = clock.CurrentTime;
 
             if (Beatmap.Value.TrackLoaded && Beatmap.Value.BeatmapLoaded)
             {
@@ -60,23 +119,26 @@ namespace osu.Game.Graphics.Containers
                 beatmap = Beatmap.Value.Beatmap;
             }
 
-            if (track != null && beatmap != null && track.IsRunning && track.Length > 0)
+            IsBeatSyncedWithTrack = beatmap != null && clock.IsRunning && track?.Length > 0;
+
+            if (IsBeatSyncedWithTrack)
             {
-                currentTrackTime = track.CurrentTime + EarlyActivationMilliseconds;
+                Debug.Assert(beatmap != null);
 
                 timingPoint = beatmap.ControlPointInfo.TimingPointAt(currentTrackTime);
                 effectPoint = beatmap.ControlPointInfo.EffectPointAt(currentTrackTime);
             }
-
-            IsBeatSyncedWithTrack = timingPoint?.BeatLength > 0;
-
-            if (timingPoint == null || !IsBeatSyncedWithTrack)
+            else
             {
+                // this may be the case where the beat syncing clock has been paused.
+                // we still want to show an idle animation, so use this container's time instead.
                 currentTrackTime = Clock.CurrentTime;
                 timingPoint = TimingControlPoint.DEFAULT;
                 effectPoint = EffectControlPoint.DEFAULT;
             }
 
+            currentTrackTime += EarlyActivationMilliseconds;
+
             double beatLength = timingPoint.BeatLength / Divisor;
 
             while (beatLength < MinimumBeatLength)
@@ -89,7 +151,7 @@ namespace osu.Game.Graphics.Containers
                 beatIndex--;
 
             TimeUntilNextBeat = (timingPoint.Time - currentTrackTime) % beatLength;
-            if (TimeUntilNextBeat < 0)
+            if (TimeUntilNextBeat <= 0)
                 TimeUntilNextBeat += beatLength;
 
             TimeSinceLastBeat = beatLength - TimeUntilNextBeat;
@@ -97,21 +159,16 @@ namespace osu.Game.Graphics.Containers
             if (timingPoint == lastTimingPoint && beatIndex == lastBeat)
                 return;
 
-            using (BeginDelayedSequence(-TimeSinceLastBeat))
-                OnNewBeat(beatIndex, timingPoint, effectPoint, track?.CurrentAmplitudes ?? ChannelAmplitudes.Empty);
+            // as this event is sometimes used for sound triggers where `BeginDelayedSequence` has no effect, avoid firing it if too far away from the beat.
+            // this can happen after a seek operation.
+            if (AllowMistimedEventFiring || Math.Abs(TimeSinceLastBeat) < MISTIMED_ALLOWANCE)
+            {
+                using (BeginDelayedSequence(-TimeSinceLastBeat))
+                    OnNewBeat(beatIndex, timingPoint, effectPoint, track?.CurrentAmplitudes ?? ChannelAmplitudes.Empty);
+            }
 
             lastBeat = beatIndex;
             lastTimingPoint = timingPoint;
         }
-
-        [BackgroundDependencyLoader]
-        private void load(IBindable<WorkingBeatmap> beatmap)
-        {
-            Beatmap.BindTo(beatmap);
-        }
-
-        protected virtual void OnNewBeat(int beatIndex, TimingControlPoint timingPoint, EffectControlPoint effectPoint, ChannelAmplitudes amplitudes)
-        {
-        }
     }
 }