Merge pull request #18100 from peppy/snapping-tidy-distance

Add xmldoc for `IDistanceSnapProvider` and related properties

osu.Game.Rulesets.Osu.Tests/Editor/TestSceneOsuDistanceSnapGrid.cs

@@ -195,9 +195,9 @@ namespace osu.Game.Rulesets.Osu.Tests.Editor
 
             public double DistanceToDuration(HitObject referenceObject, float distance) => distance;
 
-            public double GetSnappedDurationFromDistance(HitObject referenceObject, float distance) => 0;
+            public double FindSnappedDuration(HitObject referenceObject, float distance) => 0;
 
-            public float GetSnappedDistanceFromDistance(HitObject referenceObject, float distance) => 0;
+            public float FindSnappedDistance(HitObject referenceObject, float distance) => 0;
         }
     }
 }

osu.Game.Rulesets.Osu/Edit/Blueprints/Sliders/SliderPlacementBlueprint.cs

@@ -220,7 +220,7 @@ namespace osu.Game.Rulesets.Osu.Edit.Blueprints.Sliders
 
         private void updateSlider()
         {
-            HitObject.Path.ExpectedDistance.Value = snapProvider?.GetSnappedDistanceFromDistance(HitObject, (float)HitObject.Path.CalculatedDistance) ?? (float)HitObject.Path.CalculatedDistance;
+            HitObject.Path.ExpectedDistance.Value = snapProvider?.FindSnappedDistance(HitObject, (float)HitObject.Path.CalculatedDistance) ?? (float)HitObject.Path.CalculatedDistance;
 
             bodyPiece.UpdateFrom(HitObject);
             headCirclePiece.UpdateFrom(HitObject.HeadCircle);

osu.Game.Tests/Editing/TestSceneHitObjectComposerDistanceSnapping.cs

@@ -213,10 +213,10 @@ namespace osu.Game.Tests.Editing
             => AddAssert($"distance = {distance} -> duration = {expectedDuration}", () => composer.DistanceToDuration(new HitObject(), distance) == expectedDuration);
 
         private void assertSnappedDuration(float distance, double expectedDuration)
-            => AddAssert($"distance = {distance} -> duration = {expectedDuration} (snapped)", () => composer.GetSnappedDurationFromDistance(new HitObject(), distance) == expectedDuration);
+            => AddAssert($"distance = {distance} -> duration = {expectedDuration} (snapped)", () => composer.FindSnappedDuration(new HitObject(), distance) == expectedDuration);
 
         private void assertSnappedDistance(float distance, float expectedDistance)
-            => AddAssert($"distance = {distance} -> distance = {expectedDistance} (snapped)", () => composer.GetSnappedDistanceFromDistance(new HitObject(), distance) == expectedDistance);
+            => AddAssert($"distance = {distance} -> distance = {expectedDistance} (snapped)", () => composer.FindSnappedDistance(new HitObject(), distance) == expectedDistance);
 
         private class TestHitObjectComposer : OsuHitObjectComposer
         {

osu.Game.Tests/Visual/Editing/TestSceneDistanceSnapGrid.cs

@@ -175,9 +175,9 @@ namespace osu.Game.Tests.Visual.Editing
 
             public double DistanceToDuration(HitObject referenceObject, float distance) => distance;
 
-            public double GetSnappedDurationFromDistance(HitObject referenceObject, float distance) => 0;
+            public double FindSnappedDuration(HitObject referenceObject, float distance) => 0;
 
-            public float GetSnappedDistanceFromDistance(HitObject referenceObject, float distance) => 0;
+            public float FindSnappedDistance(HitObject referenceObject, float distance) => 0;
         }
     }
 }

osu.Game/Beatmaps/BeatmapInfo.cs

@@ -1,21 +1,23 @@
 // 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.
 
+#nullable enable
+
 using System;
 using System.Linq;
 using JetBrains.Annotations;
 using Newtonsoft.Json;
 using osu.Framework.Testing;
+using osu.Game.Beatmaps.ControlPoints;
 using osu.Game.Database;
 using osu.Game.Models;
 using osu.Game.Online.API.Requests.Responses;
 using osu.Game.Overlays.BeatmapSet.Scores;
 using osu.Game.Rulesets;
+using osu.Game.Rulesets.Edit;
 using osu.Game.Scoring;
 using Realms;
 
-#nullable enable
-
 namespace osu.Game.Beatmaps
 {
     /// <summary>
@@ -109,6 +111,16 @@ namespace osu.Game.Beatmaps
 
         public bool SamplesMatchPlaybackRate { get; set; } = true;
 
+        /// <summary>
+        /// The ratio of distance travelled per time unit.
+        /// Generally used to decouple the spacing between hit objects from the enforced "velocity" of the beatmap (see <see cref="DifficultyControlPoint.SliderVelocity"/>).
+        /// </summary>
+        /// <remarks>
+        /// The most common method of understanding is that at a default value of 1.0, the time-to-distance ratio will match the slider velocity of the beatmap
+        /// at the current point in time. Increasing this value will make hit objects more spaced apart when compared to the cursor movement required to track a slider.
+        ///
+        /// This is only a hint property, used by the editor in <see cref="IDistanceSnapProvider"/> implementations. It does not directly affect the beatmap or gameplay.
+        /// </remarks>
         public double DistanceSpacing { get; set; } = 1.0;
 
         public int BeatDivisor { get; set; }

osu.Game/Rulesets/Edit/DistancedHitObjectComposer.cs

@@ -145,10 +145,10 @@ namespace osu.Game.Rulesets.Edit
             return distance / GetBeatSnapDistanceAt(referenceObject) * beatLength;
         }
 
-        public virtual double GetSnappedDurationFromDistance(HitObject referenceObject, float distance)
+        public virtual double FindSnappedDuration(HitObject referenceObject, float distance)
             => BeatSnapProvider.SnapTime(referenceObject.StartTime + DistanceToDuration(referenceObject, distance), referenceObject.StartTime) - referenceObject.StartTime;
 
-        public virtual float GetSnappedDistanceFromDistance(HitObject referenceObject, float distance)
+        public virtual float FindSnappedDistance(HitObject referenceObject, float distance)
         {
             double startTime = referenceObject.StartTime;
 

osu.Game/Rulesets/Edit/IDistanceSnapProvider.cs

@@ -8,11 +8,14 @@ using osu.Game.Rulesets.Objects;
 
 namespace osu.Game.Rulesets.Edit
 {
+    /// <summary>
+    /// A snap provider which given a reference hit object and proposed distance from it, offers a more correct duration or distance value.
+    /// </summary>
     [Cached]
     public interface IDistanceSnapProvider : IPositionSnapProvider
     {
         /// <summary>
-        /// The spacing multiplier applied to beat snap distances.
+        /// A multiplier which changes the ratio of distance travelled per time unit.
         /// </summary>
         /// <seealso cref="BeatmapInfo.DistanceSpacing"/>
         IBindable<double> DistanceSpacingMultiplier { get; }
@@ -25,7 +28,7 @@ namespace osu.Game.Rulesets.Edit
         float GetBeatSnapDistanceAt(HitObject referenceObject);
 
         /// <summary>
-        /// Converts a duration to a distance.
+        /// Converts a duration to a distance without applying any snapping.
         /// </summary>
         /// <param name="referenceObject">An object to be used as a reference point for this operation.</param>
         /// <param name="duration">The duration to convert.</param>
@@ -33,7 +36,7 @@ namespace osu.Game.Rulesets.Edit
         float DurationToDistance(HitObject referenceObject, double duration);
 
         /// <summary>
-        /// Converts a distance to a duration.
+        /// Converts a distance to a duration without applying any snapping.
         /// </summary>
         /// <param name="referenceObject">An object to be used as a reference point for this operation.</param>
         /// <param name="distance">The distance to convert.</param>
@@ -41,20 +44,22 @@ namespace osu.Game.Rulesets.Edit
         double DistanceToDuration(HitObject referenceObject, float distance);
 
         /// <summary>
-        /// Converts a distance to a snapped duration.
+        /// Given a distance from the provided hit object, find the valid snapped duration.
         /// </summary>
         /// <param name="referenceObject">An object to be used as a reference point for this operation.</param>
         /// <param name="distance">The distance to convert.</param>
         /// <returns>A value that represents <paramref name="distance"/> as a duration snapped to the closest beat of the timing point.</returns>
-        double GetSnappedDurationFromDistance(HitObject referenceObject, float distance);
+        double FindSnappedDuration(HitObject referenceObject, float distance);
 
         /// <summary>
-        /// Converts an unsnapped distance to a snapped distance.
+        /// Given a distance from the provided hit object, find the valid snapped distance.
-        /// The returned distance will always be floored (as to never exceed the provided <paramref name="distance"/>.
         /// </summary>
         /// <param name="referenceObject">An object to be used as a reference point for this operation.</param>
         /// <param name="distance">The distance to convert.</param>
-        /// <returns>A value that represents <paramref name="distance"/> snapped to the closest beat of the timing point.</returns>
+        /// <returns>
-        float GetSnappedDistanceFromDistance(HitObject referenceObject, float distance);
+        /// A value that represents <paramref name="distance"/> snapped to the closest beat of the timing point.
+        /// The distance will always be less than or equal to the provided <paramref name="distance"/>.
+        /// </returns>
+        float FindSnappedDistance(HitObject referenceObject, float distance);
     }
 }

osu.Game/Rulesets/Objects/SliderPathExtensions.cs

@@ -18,7 +18,7 @@ namespace osu.Game.Rulesets.Objects
         public static void SnapTo<THitObject>(this THitObject hitObject, IDistanceSnapProvider? snapProvider)
             where THitObject : HitObject, IHasPath
         {
-            hitObject.Path.ExpectedDistance.Value = snapProvider?.GetSnappedDistanceFromDistance(hitObject, (float)hitObject.Path.CalculatedDistance) ?? hitObject.Path.CalculatedDistance;
+            hitObject.Path.ExpectedDistance.Value = snapProvider?.FindSnappedDistance(hitObject, (float)hitObject.Path.CalculatedDistance) ?? hitObject.Path.CalculatedDistance;
         }
 
         /// <summary>

osu.Game/Screens/Edit/Compose/Components/CircularDistanceSnapGrid.cs

@@ -80,7 +80,7 @@ namespace osu.Game.Screens.Edit.Compose.Components
             Vector2 normalisedDirection = direction * new Vector2(1f / distance);
             Vector2 snappedPosition = StartPosition + normalisedDirection * radialCount * radius;
 
-            return (snappedPosition, StartTime + SnapProvider.GetSnappedDurationFromDistance(ReferenceObject, (snappedPosition - StartPosition).Length));
+            return (snappedPosition, StartTime + SnapProvider.FindSnappedDuration(ReferenceObject, (snappedPosition - StartPosition).Length));
         }
     }
 }