Integrate storyboards with gameplay.

osu.Game/Beatmaps/Beatmap.cs

@@ -46,6 +46,21 @@ namespace osu.Game.Beatmaps
         /// </summary>
         public Storyboard Storyboard = new Storyboard();
 
+        /// <summary>
+        /// Whether this beatmap's Storyboard uses the background texture in its Background layer.
+        /// </summary>
+        public bool StoryboardUsesBackground
+        {
+            get
+            {
+                var backgroundPath = BeatmapInfo.BeatmapSet.Metadata.BackgroundFile?.ToLowerInvariant();
+                if (backgroundPath == null)
+                    return false;
+
+                return Storyboard.GetLayer("Background").Elements.Any(e => e.Path.ToLowerInvariant() == backgroundPath);
+            }
+        }
+
         /// <summary>
         /// Constructs a new beatmap.
         /// </summary>

osu.Game/Beatmaps/BeatmapInfo.cs

@@ -75,6 +75,7 @@ namespace osu.Game.Beatmaps
 
         public bool LetterboxInBreaks { get; set; }
         public bool WidescreenStoryboard { get; set; }
+        public float StoryboardAspect => WidescreenStoryboard ? 16 / 9f : 4 / 3f;
 
         // Editor
         // This bookmarks stuff is necessary because DB doesn't know how to store int[]

osu.Game/Screens/Play/Player.cs

@@ -24,6 +24,8 @@ using osu.Game.Screens.Ranking;
 using osu.Framework.Audio.Sample;
 using osu.Game.Beatmaps;
 using osu.Game.Online.API;
+using osu.Game.Storyboards.Drawables;
+using OpenTK.Graphics;
 
 namespace osu.Game.Screens.Play
 {
@@ -66,6 +68,9 @@ namespace osu.Game.Screens.Play
 
         #endregion
 
+        private DrawableStoryboard storyboard;
+        private bool storyboardUsesBackground;
+
         private HUDOverlay hudOverlay;
         private FailOverlay failOverlay;
 
@@ -145,6 +150,15 @@ namespace osu.Game.Screens.Play
 
             Children = new Drawable[]
             {
+                new Container
+                {
+                    RelativeSizeAxes = Axes.Both,
+                    Clock = offsetClock,
+                    Children = new Drawable[]
+                    {
+                        storyboard = beatmap.Storyboard.CreateDrawable(),
+                    }
+                },
                 pauseContainer = new PauseContainer
                 {
                     AudioClock = decoupledClock,
@@ -196,6 +210,10 @@ namespace osu.Game.Screens.Play
 
             scoreProcessor = RulesetContainer.CreateScoreProcessor();
 
+            storyboardUsesBackground = beatmap.StoryboardUsesBackground;
+            storyboard.Width = storyboard.Height * beatmap.BeatmapInfo.StoryboardAspect;
+            storyboard.Masking = true;
+
             hudOverlay.BindProcessor(scoreProcessor);
             hudOverlay.BindRulesetContainer(RulesetContainer);
 
@@ -266,12 +284,11 @@ namespace osu.Game.Screens.Play
                 return;
 
             (Background as BackgroundScreenBeatmap)?.BlurTo(Vector2.Zero, 1500, Easing.OutQuint);
-            Background?.FadeTo(1 - (float)dimLevel, 1500, Easing.OutQuint);
+
+            applyDim();
+            dimLevel.ValueChanged += newDim => applyDim();
 
             Content.Alpha = 0;
-
-            dimLevel.ValueChanged += newDim => Background?.FadeTo(1 - (float)newDim, 800);
-
             Content
                 .ScaleTo(0.7f)
                 .ScaleTo(1, 750, Easing.OutQuint)
@@ -310,6 +327,15 @@ namespace osu.Game.Screens.Play
             return true;
         }
 
+        private void applyDim()
+        {
+            var opacity = 1 - (float)dimLevel;
+            storyboard.FadeColour(new Color4(opacity, opacity, opacity, 1), 800);
+            storyboard.FadeTo(opacity == 0 ? 0 : 1);
+
+            Background?.FadeTo(storyboardUsesBackground ? 0 : opacity, 800, Easing.OutQuint);
+        }
+
         private void fadeOut()
         {
             const float fade_out_duration = 250;

osu.Game/Storyboards/Drawables/DrawableStoryboard.cs

@@ -14,6 +14,9 @@ namespace osu.Game.Storyboards.Drawables
     {
         public Storyboard Storyboard { get; private set; }
 
+        private readonly Container<DrawableStoryboardLayer> content;
+        protected override Container<DrawableStoryboardLayer> Content => content;
+
         protected override Vector2 DrawScale => new Vector2(Parent.DrawHeight / 480);
         public override bool HandleInput => false;
 
@@ -39,6 +42,13 @@ namespace osu.Game.Storyboards.Drawables
             Size = new Vector2(640, 480);
             Anchor = Anchor.Centre;
             Origin = Anchor.Centre;
+
+            AddInternal(content = new Container<DrawableStoryboardLayer>
+            {
+                Size = new Vector2(640, 480),
+                Anchor = Anchor.Centre,
+                Origin = Anchor.Centre,
+            });
         }
 
         [BackgroundDependencyLoader]