Naming and documentation improvements

osu.Game.Rulesets.Osu/Objects/Drawables/DrawableHitCircle.cs

@@ -128,16 +128,16 @@ namespace osu.Game.Rulesets.Osu.Objects.Drawables
             ApplyResult(r => r.Type = result);
         }
 
-        protected override void UpdatePreemptState()
+        protected override void UpdateInitialTransforms()
         {
-            base.UpdatePreemptState();
+            base.UpdateInitialTransforms();
 
             ApproachCircle.FadeIn(Math.Min(HitObject.TimeFadeIn * 2, HitObject.TimePreempt));
             ApproachCircle.ScaleTo(1.1f, HitObject.TimePreempt);
             ApproachCircle.Expire(true);
         }
 
-        protected override void UpdateCurrentState(ArmedState state)
+        protected override void UpdateStateTransforms(ArmedState state)
         {
             glow.FadeOut(400);
 

osu.Game.Rulesets.Osu/Objects/Drawables/DrawableOsuHitObject.cs

@@ -38,7 +38,7 @@ namespace osu.Game.Rulesets.Osu.Objects.Drawables
 
         protected sealed override double InitialLifetimeOffset => HitObject.TimePreempt;
 
-        protected override void UpdatePreemptState() => this.FadeIn(HitObject.TimeFadeIn);
+        protected override void UpdateInitialTransforms() => this.FadeIn(HitObject.TimeFadeIn);
 
         private OsuInputManager osuActionInputManager;
         internal OsuInputManager OsuActionInputManager => osuActionInputManager ?? (osuActionInputManager = GetContainingInputManager() as OsuInputManager);

osu.Game.Rulesets.Osu/Objects/Drawables/DrawableRepeatPoint.cs

@@ -47,7 +47,7 @@ namespace osu.Game.Rulesets.Osu.Objects.Drawables
                 ApplyResult(r => r.Type = drawableSlider.Tracking.Value ? HitResult.Great : HitResult.Miss);
         }
 
-        protected override void UpdatePreemptState()
+        protected override void UpdateInitialTransforms()
         {
             animDuration = Math.Min(150, repeatPoint.SpanDuration / 2);
 
@@ -57,7 +57,7 @@ namespace osu.Game.Rulesets.Osu.Objects.Drawables
             );
         }
 
-        protected override void UpdateCurrentState(ArmedState state)
+        protected override void UpdateStateTransforms(ArmedState state)
         {
             switch (state)
             {

osu.Game.Rulesets.Osu/Objects/Drawables/DrawableSlider.cs

@@ -190,7 +190,7 @@ namespace osu.Game.Rulesets.Osu.Objects.Drawables
             });
         }
 
-        protected override void UpdateCurrentState(ArmedState state)
+        protected override void UpdateStateTransforms(ArmedState state)
         {
             Ball.FadeIn();
             Ball.ScaleTo(HitObject.Scale);

osu.Game.Rulesets.Osu/Objects/Drawables/DrawableSliderTick.cs

@@ -55,13 +55,13 @@ namespace osu.Game.Rulesets.Osu.Objects.Drawables
                 ApplyResult(r => r.Type = Tracking ? HitResult.Great : HitResult.Miss);
         }
 
-        protected override void UpdatePreemptState()
+        protected override void UpdateInitialTransforms()
         {
             this.FadeOut().FadeIn(ANIM_DURATION);
             this.ScaleTo(0.5f).ScaleTo(1f, ANIM_DURATION * 4, Easing.OutElasticHalf);
         }
 
-        protected override void UpdateCurrentState(ArmedState state)
+        protected override void UpdateStateTransforms(ArmedState state)
         {
             switch (state)
             {

osu.Game.Rulesets.Osu/Objects/Drawables/DrawableSpinner.cs

@@ -196,9 +196,9 @@ namespace osu.Game.Rulesets.Osu.Objects.Drawables
             symbol.RotateTo(Disc.Rotation / 2, 500, Easing.OutQuint);
         }
 
-        protected override void UpdatePreemptState()
+        protected override void UpdateInitialTransforms()
         {
-            base.UpdatePreemptState();
+            base.UpdateInitialTransforms();
 
             circleContainer.ScaleTo(Spinner.Scale * 0.3f);
             circleContainer.ScaleTo(Spinner.Scale, HitObject.TimePreempt / 1.4f, Easing.OutQuint);
@@ -213,7 +213,7 @@ namespace osu.Game.Rulesets.Osu.Objects.Drawables
                 .ScaleTo(1, 500, Easing.OutQuint);
         }
 
-        protected override void UpdateCurrentState(ArmedState state)
+        protected override void UpdateStateTransforms(ArmedState state)
         {
             var sequence = this.Delay(Spinner.Duration).FadeOut(160);
 

osu.Game/Rulesets/Objects/Drawables/DrawableHitObject.cs

@@ -118,8 +118,6 @@ namespace osu.Game.Rulesets.Objects.Drawables
             }
         }
 
-        protected override void ClearInternal(bool disposeChildren = true) => throw new InvalidOperationException($"Should never clear a {nameof(DrawableHitObject)}");
-
         protected override void LoadComplete()
         {
             base.LoadComplete();
@@ -136,8 +134,19 @@ namespace osu.Game.Rulesets.Objects.Drawables
             }, true);
         }
 
+        #region State / Transform Management
+
+        /// <summary>
+        /// Enables automatic transform management of this hitobject. Implementation of transforms should be done in <see cref="UpdateInitialTransforms"/> and <see cref="UpdateStateTransforms"/> only. Rewinding and removing previous states is done automatically.
+        /// </summary>
+        /// <remarks>
+        /// Going forward, this is the preferred way of implementing <see cref="DrawableHitObject"/>s. Previous functionality
+        /// is offered as a compatibility layer until all rulesets have been migrated across.
+        /// </remarks>
         protected virtual bool UseTransformStateManagement => false;
 
+        protected override void ClearInternal(bool disposeChildren = true) => throw new InvalidOperationException($"Should never clear a {nameof(DrawableHitObject)}");
+
         private void updateState(ArmedState state)
         {
             if (UseTransformStateManagement)
@@ -149,13 +158,13 @@ namespace osu.Game.Rulesets.Objects.Drawables
 
                 using (BeginAbsoluteSequence(transformTime, true))
                 {
-                    UpdatePreemptState();
+                    UpdateInitialTransforms();
 
                     var judgementOffset = Math.Min(HitObject.HitWindows?.HalfWindowFor(HitResult.Miss) ?? double.MaxValue, Result?.TimeOffset ?? 0);
 
                     using (BeginDelayedSequence(InitialLifetimeOffset + judgementOffset, true))
                     {
-                        UpdateCurrentState(state);
+                        UpdateStateTransforms(state);
                         State.Value = state;
                     }
                 }
@@ -168,19 +177,11 @@ namespace osu.Game.Rulesets.Objects.Drawables
             UpdateState(state);
         }
 
-        protected override void SkinChanged(ISkinSource skin, bool allowFallback)
+        protected virtual void UpdateInitialTransforms()
-        {
-            base.SkinChanged(skin, allowFallback);
-
-            if (HitObject is IHasComboInformation combo)
-                AccentColour.Value = skin.GetValue<SkinConfiguration, Color4?>(s => s.ComboColours.Count > 0 ? s.ComboColours[combo.ComboIndex % s.ComboColours.Count] : (Color4?)null) ?? Color4.White;
-        }
-
-        protected virtual void UpdatePreemptState()
         {
         }
 
-        protected virtual void UpdateCurrentState(ArmedState state)
+        protected virtual void UpdateStateTransforms(ArmedState state)
         {
         }
 
@@ -200,6 +201,16 @@ namespace osu.Game.Rulesets.Objects.Drawables
         {
         }
 
+        #endregion
+
+        protected override void SkinChanged(ISkinSource skin, bool allowFallback)
+        {
+            base.SkinChanged(skin, allowFallback);
+
+            if (HitObject is IHasComboInformation combo)
+                AccentColour.Value = skin.GetValue<SkinConfiguration, Color4?>(s => s.ComboColours.Count > 0 ? s.ComboColours[combo.ComboIndex % s.ComboColours.Count] : (Color4?)null) ?? Color4.White;
+        }
+
         /// <summary>
         /// Bind to apply a custom state which can override the default implementation.
         /// </summary>