Add documentation and move storyboard init logic

osu.Game.Tests/Visual/TestCaseBackgroundScreenBeatmap.cs

@@ -284,7 +284,7 @@ namespace osu.Game.Tests.Visual
             /// <summary>
             /// Make sure every time a screen gets pushed, the background doesn't get replaced
             /// </summary>
-            /// <returns>Whether or not the original background is still the current background</returns>
+            /// <returns>Whether or not the original background (The one created in DummySongSelect) is still the current background</returns>
             public bool AssertBackgroundCurrent()
             {
                 return ((FadeAccessibleBackground)Background).IsCurrentScreen();

osu.Game/Graphics/Containers/UserDimContainer.cs

@@ -10,19 +10,41 @@ using osuTK.Graphics;
 
 namespace osu.Game.Graphics.Containers
 {
+    /// <summary>
+    /// A container that applies user-configured dim levels to its contents.
+    /// This container specifies behavior that applies to both Storyboards and Backgrounds.
+    /// </summary>
     public class UserDimContainer : Container
     {
         protected Bindable<double> DimLevel;
+
         protected Bindable<bool> ShowStoryboard;
-        public Bindable<bool> EnableUserDim = new Bindable<bool>();
+
+        /// <summary>
+        /// Whether or not user-configured dim levels should be applied to the container.
+        /// </summary>
+        public readonly Bindable<bool> EnableUserDim = new Bindable<bool>();
+
+        /// <summary>
+        /// Whether or not the storyboard loaded should completely hide the background behind it.
+        /// </summary>
         public Bindable<bool> StoryboardReplacesBackground = new Bindable<bool>();
+
         protected Container DimContainer;
+
         protected override Container<Drawable> Content => DimContainer;
 
         private readonly bool isStoryboard;
 
         private const float background_fade_duration = 800;
 
+        /// <summary>
+        /// </summary>
+        /// <param name="isStoryboard">
+        /// Whether or not this instance of UserDimContainer contains a storyboard.
+        /// While both backgrounds and storyboards allow user dim levels to be applied, storyboards can be toggled via <see cref="ShowStoryboard"/>
+        /// and can cause backgrounds to become hidden via <see cref="StoryboardReplacesBackground"/>.
+        /// </param>
         public UserDimContainer(bool isStoryboard = false)
         {
             DimContainer = new Container { RelativeSizeAxes = Axes.Both };
@@ -41,6 +63,12 @@ namespace osu.Game.Graphics.Containers
             StoryboardReplacesBackground.ValueChanged += _ => updateBackgroundDim();
         }
 
+        protected override void LoadComplete()
+        {
+            base.LoadComplete();
+            updateBackgroundDim();
+        }
+
         private void updateBackgroundDim()
         {
             if (isStoryboard)
@@ -49,7 +77,7 @@ namespace osu.Game.Graphics.Containers
             }
             else
             {
-                // The background needs to be hidden in the case of it being replaced
+                // The background needs to be hidden in the case of it being replaced by the storyboard
                 DimContainer.FadeTo(ShowStoryboard.Value && StoryboardReplacesBackground.Value ? 0 : 1, background_fade_duration, Easing.OutQuint);
             }
 

osu.Game/Screens/Backgrounds/BackgroundScreenBeatmap.cs

@@ -14,10 +14,16 @@ namespace osu.Game.Screens.Backgrounds
     public class BackgroundScreenBeatmap : BlurrableBackgroundScreen
     {
         private WorkingBeatmap beatmap;
+
+        /// <summary>
+        /// Whether or not user dim settings should be applied to this Background.
+        /// </summary>
         public Bindable<bool> EnableUserDim = new Bindable<bool>();
+
         public Bindable<bool> StoryboardReplacesBackground = new Bindable<bool>();
 
         protected UserDimContainer FadeContainer;
+
         protected virtual UserDimContainer CreateFadeContainer() => new UserDimContainer { RelativeSizeAxes = Axes.Both };
 
         public virtual WorkingBeatmap Beatmap

osu.Game/Screens/Play/Player.cs

@@ -345,7 +345,12 @@ namespace osu.Game.Screens.Play
                 .Delay(250)
                 .FadeIn(250);
 
-            ShowStoryboard.ValueChanged += _ => UpdateBackgroundElements();
+            ShowStoryboard.ValueChanged += _ =>
+            {
+                if (ShowStoryboard.Value && storyboard == null)
+                    initializeStoryboard(true);
+            };
+
             Background.EnableUserDim.Value = true;
             storyboardContainer.StoryboardReplacesBackground.Value = Beatmap.Value.Storyboard.ReplacesBackground && Beatmap.Value.Storyboard.HasDrawable;
             storyboardContainer.StoryboardReplacesBackground.BindTo(Background?.StoryboardReplacesBackground);
@@ -433,9 +438,6 @@ namespace osu.Game.Screens.Play
             if (!this.IsCurrentScreen()) return;
 
             base.UpdateBackgroundElements();
-
-            if (ShowStoryboard.Value && storyboard == null)
-                initializeStoryboard(true);
         }
 
         protected virtual Results CreateResults(ScoreInfo score) => new SoloResults(score);