Merge branch 'master' into tabcontrol-initial-autosort

README.md

···
 
 A game framework written with [osu!](https://github.com/ppy/osu) in mind.
 
-## Requirements
+## Developing a game using osu!framework
+
+If you are interested in **creating a project** using the framework, please start from the [getting started](https://github.com/ppy/osu-framework/wiki/Setting-up-your-first-project) wiki resources (or jump straight over to the [project templates](https://github.com/ppy/osu-framework/tree/master/osu.Framework.Templates). You can either start off from an empty project, or take a peek at a working sample game. Either way, full project structure, cross-platform support, and  a testing setup are included!
 
-- A desktop platform with the [.NET 5.0 SDK](https://dotnet.microsoft.com/download) or higher installed.
-- When running on linux, please have a system-wide ffmpeg installation available to support video decoding.
-- When running on Windows 7 or 8.1, *[additional prerequisites](https://docs.microsoft.com/en-us/dotnet/core/install/windows?tabs=net50&pivots=os-windows#dependencies)** may be required to correctly run .NET 5 applications if your operating system is not up-to-date with the latest service packs.
-- When working with the codebase, we recommend using an IDE with intellisense and syntax highlighting, such as [Visual Studio 2019+](https://visualstudio.microsoft.com/vs/), [Jetbrains Rider](https://www.jetbrains.com/rider/) or [Visual Studio Code](https://code.visualstudio.com/).
+The rest of the information on this page is related to working *on* the framework, not *using* it!
 
 ## Objectives
 
···
 - Common elements used by games (texture caching, font loading) will be automatically initialised at runtime.
 - Allow for isolated development of components via a solid testing environment (`VisualTests` and `TestCases`). Check the [wiki](https://github.com/ppy/osu-framework/wiki/Development-and-Testing) for more information on how these can be used to streamline development.
 
+## Requirements
+
+- A desktop platform with the [.NET 5.0 SDK](https://dotnet.microsoft.com/download) or higher installed.
+- When running on linux, please have a system-wide ffmpeg installation available to support video decoding.
+- When running on Windows 7 or 8.1, *[additional prerequisites](https://docs.microsoft.com/en-us/dotnet/core/install/windows?tabs=net50&pivots=os-windows#dependencies)** may be required to correctly run .NET 5 applications if your operating system is not up-to-date with the latest service packs.
+- When working with the codebase, we recommend using an IDE with intellisense and syntax highlighting, such as [Visual Studio 2019+](https://visualstudio.microsoft.com/vs/), [Jetbrains Rider](https://www.jetbrains.com/rider/) or [Visual Studio Code](https://code.visualstudio.com/).
+
 ### Building
 
 Build configurations for the recommended IDEs (listed above) are included. You should use the provided Build/Run functionality of your IDE to get things going. When testing or building new components, it's highly encouraged you use the `VisualTests` project/configuration. More information on this provided [below](#contributing).
···
 
 The BASS audio library (a dependency of this framework) is a commercial product. While it is free for non-commercial use, please ensure to [obtain a valid licence](http://www.un4seen.com/bass.html#license) if you plan on distributing any application using it commercially.
 
-## Developing a game using osu!framework
-
-If you want to get started making your own game project using osu!framework, check out our [project templates](https://github.com/ppy/osu-framework/tree/master/osu.Framework.Templates). You can either start off from an empty project, or take a peek at a working sample game. Either way, full project structure, cross-platform support, and testing setup are included!
-
 ## Projects that use osu!framework
 
 [osu!](https://github.com/ppy/osu) – rhythm is just a *click* away!
···
  - Must be a GitHub link (i.e. your project is open source)
  - Must be actively developed (and have executable releases)
 -->
+

osu.Framework.Android/AndroidGameHost.cs

···
 
         public override Storage GetStorage(string path) => new AndroidStorage(path, this);
 
-        public override string UserStoragePath => Application.Context.GetExternalFilesDir(string.Empty).ToString();
+        public override IEnumerable<string> UserStoragePaths => new[]
+        {
+            Application.Context.GetExternalFilesDir(string.Empty).ToString()
+        };
 
         public override void OpenFileExternally(string filename)
             => throw new NotImplementedException();

osu.Framework.Tests/Platform/UserStorageLookupTest.cs

···
+// Copyright (c) ppy Pty Ltd <[e-mail]>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+using System;
+using System.Collections.Generic;
+using System.IO;
+using NUnit.Framework;
+using osu.Framework.Testing;
+
+namespace osu.Framework.Tests.Platform
+{
+    [TestFixture]
+    public class UserStorageLookupTest
+    {
+        private static readonly string path1 = Path.Combine(TestRunHeadlessGameHost.TemporaryTestDirectory, "path1");
+        private static readonly string path2 = Path.Combine(TestRunHeadlessGameHost.TemporaryTestDirectory, "path2");
+
+        private const string game_name = "test_game";
+
+        [TearDown]
+        public void TearDown()
+        {
+            try
+            {
+                File.Delete(path1);
+                File.Delete(path2);
+            }
+            catch
+            {
+            }
+
+            try
+            {
+                Directory.Delete(path1, true);
+                Directory.Delete(path2, true);
+            }
+            catch
+            {
+            }
+        }
+
+        [Test]
+        public void TestFirstBaseExisting()
+        {
+            Directory.CreateDirectory(path1);
+
+            using (var host = new StorageLookupHeadlessGameHost())
+            {
+                runHost(host);
+                Assert.IsTrue(host.Storage.GetFullPath(string.Empty).StartsWith(path1, StringComparison.Ordinal));
+            }
+        }
+
+        [Test]
+        public void TestSecondBaseExistingStillPrefersFirst()
+        {
+            Directory.CreateDirectory(path2);
+
+            using (var host = new StorageLookupHeadlessGameHost())
+            {
+                runHost(host);
+                Assert.IsTrue(host.Storage.GetFullPath(string.Empty).StartsWith(path1, StringComparison.Ordinal));
+            }
+        }
+
+        [Test]
+        public void TestSecondBaseUsedIfFirstFails()
+        {
+            // write a file so directory creation fails.
+            File.WriteAllText(path1, "");
+
+            using (var host = new StorageLookupHeadlessGameHost())
+            {
+                runHost(host);
+                Assert.IsTrue(host.Storage.GetFullPath(string.Empty).StartsWith(path2, StringComparison.Ordinal));
+            }
+        }
+
+        [Test]
+        public void TestFirstDataExisting()
+        {
+            Directory.CreateDirectory(Path.Combine(path1, game_name));
+
+            using (var host = new StorageLookupHeadlessGameHost())
+            {
+                runHost(host);
+                Assert.IsTrue(host.Storage.GetFullPath(string.Empty).StartsWith(path1, StringComparison.Ordinal));
+            }
+        }
+
+        [Test]
+        public void TestSecondDataExisting()
+        {
+            Directory.CreateDirectory(Path.Combine(path2, game_name));
+
+            using (var host = new StorageLookupHeadlessGameHost())
+            {
+                runHost(host);
+                Assert.IsTrue(host.Storage.GetFullPath(string.Empty).StartsWith(path2, StringComparison.Ordinal));
+            }
+        }
+
+        [Test]
+        public void TestPrefersFirstData()
+        {
+            Directory.CreateDirectory(Path.Combine(path1, game_name));
+            Directory.CreateDirectory(Path.Combine(path2, game_name));
+
+            using (var host = new StorageLookupHeadlessGameHost())
+            {
+                runHost(host);
+                Assert.IsTrue(host.Storage.GetFullPath(string.Empty).StartsWith(path1, StringComparison.Ordinal));
+            }
+        }
+
+        [Test]
+        public void TestPrefersSecondDataOverFirstBase()
+        {
+            Directory.CreateDirectory(path1);
+            Directory.CreateDirectory(Path.Combine(path2, game_name));
+
+            using (var host = new StorageLookupHeadlessGameHost())
+            {
+                runHost(host);
+                Assert.IsTrue(host.Storage.GetFullPath(string.Empty).StartsWith(path2, StringComparison.Ordinal));
+            }
+        }
+
+        private static void runHost(StorageLookupHeadlessGameHost host)
+        {
+            TestGame game = new TestGame();
+            game.Schedule(() => game.Exit());
+            host.Run(game);
+        }
+
+        private class StorageLookupHeadlessGameHost : TestRunHeadlessGameHost
+        {
+            public StorageLookupHeadlessGameHost()
+                : base(game_name)
+            {
+            }
+
+            public override IEnumerable<string> UserStoragePaths => new[]
+            {
+                path1,
+                path2,
+            };
+        }
+    }
+}

osu.Framework.Tests/Visual/Sprites/TestSceneVideo.cs

···
             AddUntilStep("decoding ran", () => didDecode);
         }
 
+        [TestCase(false)]
+        [TestCase(true)]
+        public void TestDecodingStopsBeforeStartTime(bool looping)
+        {
+            AddStep("Set looping", () => video.Loop = looping);
+
+            AddStep("Jump back to before start time", () => clock.CurrentTime = -30000);
+
+            AddUntilStep("decoding stopped", () => video.State == VideoDecoder.DecoderState.Ready);
+
+            AddStep("reset decode state", () => didDecode = false);
+
+            AddWaitStep("wait a bit", 10);
+            AddAssert("decoding didn't run", () => !didDecode);
+
+            AddStep("seek close to start", () => clock.CurrentTime = -500);
+            AddUntilStep("decoding ran", () => didDecode);
+        }
+
         [Test]
         public void TestJumpForward()
         {

osu.Framework.iOS/IOSGameHost.cs

···
 
         public override Storage GetStorage(string path) => new IOSStorage(path, this);
 
-        public override string UserStoragePath => Environment.GetFolderPath(Environment.SpecialFolder.Personal);
-
         public override void OpenFileExternally(string filename) => throw new NotImplementedException();
 
         public override void OpenUrlExternally(string url)

osu.Framework/Graphics/Animations/AnimationClockComposite.cs

···
         {
             get
             {
-                if (Loop)
-                    return manualClock.CurrentTime % Duration;
+                double current = manualClock.CurrentTime;
+
+                if (Loop) current %= Duration;
 
-                return Math.Min(manualClock.CurrentTime, Duration);
+                return Math.Clamp(current, 0, Duration);
             }
             set
             {

osu.Framework/Graphics/Performance/FrameTimeDisplay.cs

···
             elapsedSinceLastUpdate = 0;
 
             counter.Text = $"{displayFps:0}fps ({rollingElapsed:0.00}ms)"
-                           + (clock.Throttling ? $"{(clock.MaximumUpdateHz < 10000 ? clock.MaximumUpdateHz.ToString("0") : "∞").PadLeft(4)}hz" : string.Empty);
+                           + (clock.Throttling ? $"{(clock.MaximumUpdateHz > 0 && clock.MaximumUpdateHz < 10000 ? clock.MaximumUpdateHz.ToString("0") : "∞").PadLeft(4)}hz" : string.Empty);
         }
 
         private class CounterText : SpriteText

osu.Framework/Graphics/Video/Video.cs

···
                     seekIntoSync();
             }
 
-            var nextFrame = availableFrames.Count > 0 ? availableFrames.Peek() : null;
+            var peekFrame = availableFrames.Count > 0 ? availableFrames.Peek() : null;
+            bool outOfSync = false;
 
-            if (nextFrame != null)
+            if (peekFrame != null)
             {
-                bool tooFarBehind = Math.Abs(PlaybackPosition - nextFrame.Time) > lenience_before_seek &&
-                                    (!Loop ||
-                                     (Math.Abs(PlaybackPosition - decoder.Duration - nextFrame.Time) > lenience_before_seek &&
-                                      Math.Abs(PlaybackPosition + decoder.Duration - nextFrame.Time) > lenience_before_seek)
-                                    );
+                outOfSync = Math.Abs(PlaybackPosition - peekFrame.Time) > lenience_before_seek;
 
-                // we are too far ahead or too far behind
-                if (tooFarBehind && decoder.CanSeek)
+                if (Loop)
                 {
-                    Logger.Log($"Video too far out of sync ({nextFrame.Time}), seeking to {PlaybackPosition}");
-                    seekIntoSync();
+                    // handle looping bounds (as we could be in the roll-over process between loops).
+                    outOfSync &= Math.Abs(PlaybackPosition - decoder.Duration - peekFrame.Time) > lenience_before_seek &&
+                                 Math.Abs(PlaybackPosition + decoder.Duration - peekFrame.Time) > lenience_before_seek;
                 }
+            }
+
+            // we are too far ahead or too far behind
+            if (outOfSync && decoder.CanSeek)
+            {
+                Logger.Log($"Video too far out of sync ({peekFrame.Time}), seeking to {PlaybackPosition}");
+                seekIntoSync();
             }
 
             var frameTime = CurrentFrameTime;

osu.Framework/Platform/GameHost.cs

···
         /// <param name="path">The absolute path to be used as a root for the storage.</param>
         public abstract Storage GetStorage(string path);
 
-        public abstract string UserStoragePath { get; }
+        /// <summary>
+        /// All valid user storage paths in order of usage priority.
+        /// </summary>
+        public virtual IEnumerable<string> UserStoragePaths => Environment.GetFolderPath(Environment.SpecialFolder.Personal).Yield();
 
         /// <summary>
         /// The main storage as proposed by the host game.
···
 
         private double maximumUpdateHz;
 
+        /// <summary>
+        /// The target number of update frames per second when the game window is active.
+        /// </summary>
+        /// <remarks>
+        /// A value of 0 is treated the same as "unlimited" or <see cref="double.MaxValue"/>.
+        /// </remarks>
         public double MaximumUpdateHz
         {
             get => maximumUpdateHz;
···
 
         private double maximumDrawHz;
 
+        /// <summary>
+        /// The target number of draw frames per second when the game window is active.
+        /// </summary>
+        /// <remarks>
+        /// A value of 0 is treated the same as "unlimited" or <see cref="double.MaxValue"/>.
+        /// </remarks>
         public double MaximumDrawHz
         {
             get => maximumDrawHz;
             set => DrawThread.ActiveHz = maximumDrawHz = value;
         }
 
+        /// <summary>
+        /// The target number of updates per second when the game window is inactive.
+        /// This is applied to all threads.
+        /// </summary>
+        /// <remarks>
+        /// A value of 0 is treated the same as "unlimited" or <see cref="double.MaxValue"/>.
+        /// </remarks>
         public double MaximumInactiveHz
         {
             get => DrawThread.InactiveHz;
···
         /// Finds the default <see cref="Storage"/> for the game to be used if <see cref="Game.CreateStorage"/> is not overridden.
         /// </summary>
         /// <returns>The <see cref="Storage"/>.</returns>
-        protected virtual Storage GetDefaultGameStorage() => GetStorage(UserStoragePath).GetStorageForDirectory(Name);
+        protected virtual Storage GetDefaultGameStorage()
+        {
+            // first check all valid paths for any existing install.
+            foreach (var path in UserStoragePaths)
+            {
+                var storage = GetStorage(path);
+
+                // if an existing data directory exists for this application, prefer it immediately.
+                if (storage.ExistsDirectory(Name))
+                    return storage.GetStorageForDirectory(Name);
+            }
+
+            // if an existing directory could not be found, use the first path that can be created.
+            foreach (var path in UserStoragePaths)
+            {
+                try
+                {
+                    return GetStorage(path).GetStorageForDirectory(Name);
+                }
+                catch
+                {
+                    // may fail on directory creation.
+                }
+            }
+
+            throw new InvalidOperationException("No valid user storage path could be resolved.");
+        }
 
         /// <summary>
         /// Pauses all active threads. Call <see cref="Resume"/> to resume execution.

osu.Framework/Platform/HeadlessGameHost.cs

···
 
         public override void OpenUrlExternally(string url) => Logger.Log($"Application has requested URL \"{url}\" to be opened.");
 
-        public override string UserStoragePath => "./headless/";
+        public override IEnumerable<string> UserStoragePaths => new[] { "./headless/" };
 
         public HeadlessGameHost(string gameName = null, bool bindIPC = false, bool realtime = true, bool portableInstallation = false)
             : base(gameName ?? Guid.NewGuid().ToString(), bindIPC, portableInstallation: portableInstallation)
···
         {
             base.SetupForRun();
 
-            MaximumDrawHz = double.MaxValue;
-            MaximumUpdateHz = double.MaxValue;
-            MaximumInactiveHz = double.MaxValue;
+            // We want the draw thread to run, but it doesn't matter how fast it runs.
+            // This limiting is mostly to reduce CPU overhead.
+            MaximumDrawHz = 60;
 
-            if (!realtime) customClock = new FramedClock(new FastClock(CLOCK_RATE));
+            if (!realtime)
+            {
+                customClock = new FramedClock(new FastClock(CLOCK_RATE));
+
+                // time is incremented per frame, rather than based on the real-world time.
+                // therefore our goal is to run frames as fast as possible.
+                MaximumUpdateHz = MaximumInactiveHz = 0;
+            }
+            else
+            {
+                // in realtime runs, set a sane upper limit to avoid cpu overhead from spinning.
+                MaximumUpdateHz = MaximumInactiveHz = 1000;
+            }
         }
 
         protected override void DrawFrame()

osu.Framework/Platform/Linux/LinuxGameHost.cs

···
 // See the LICENCE file in the repository root for full licence text.
 
 using System;
+using System.Collections.Generic;
 using System.IO;
 using osu.Framework.Platform.Linux.SDL2;
 
···
 
         protected override IWindow CreateWindow() => new SDL2DesktopWindow();
 
-        public override string UserStoragePath
+        public override IEnumerable<string> UserStoragePaths
         {
             get
             {
-                string home = Environment.GetFolderPath(Environment.SpecialFolder.Personal);
                 string xdg = Environment.GetEnvironmentVariable("XDG_DATA_HOME");
-                string[] paths =
-                {
-                    xdg ?? Path.Combine(home, ".local", "share"),
-                    Path.Combine(home)
-                };
+
+                if (!string.IsNullOrEmpty(xdg))
+                    yield return xdg;
 
-                foreach (string path in paths)
-                {
-                    if (Directory.Exists(path))
-                        return path;
-                }
+                yield return Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.Personal), ".local", "share");
 
-                return paths[0];
+                foreach (var path in base.UserStoragePaths)
+                    yield return path;
             }
         }
 

osu.Framework/Platform/MacOS/MacOSGameHost.cs

···
 
         protected override IWindow CreateWindow() => new MacOSWindow();
 
-        public override string UserStoragePath
+        public override IEnumerable<string> UserStoragePaths
         {
             get
             {
-                string home = Environment.GetFolderPath(Environment.SpecialFolder.Personal);
                 string xdg = Environment.GetEnvironmentVariable("XDG_DATA_HOME");
-                string[] paths =
-                {
-                    xdg ?? Path.Combine(home, ".local", "share"),
-                    Path.Combine(home)
-                };
 
-                foreach (string path in paths)
-                {
-                    if (Directory.Exists(path))
-                        return path;
-                }
+                if (!string.IsNullOrEmpty(xdg))
+                    yield return xdg;
 
-                return paths[0];
+                yield return Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.Personal), ".local", "share");
+
+                foreach (var path in base.UserStoragePaths)
+                    yield return path;
             }
         }
 

osu.Framework/Platform/Windows/WindowsGameHost.cs

···
 using System.Diagnostics;
 using System.IO;
 using System.Linq;
+using osu.Framework.Extensions.IEnumerableExtensions;
 using osu.Framework.Input;
 using osu.Framework.Input.Bindings;
 using osu.Framework.Input.Handlers;
···
 
         public override Clipboard GetClipboard() => new WindowsClipboard();
 
-        public override string UserStoragePath => Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData);
+        public override IEnumerable<string> UserStoragePaths =>
+            // on windows this is guaranteed to exist (and be usable) so don't fallback to the base/default.
+            Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData).Yield();
 
 #if NET5_0
         [System.Runtime.Versioning.SupportedOSPlatform("windows")]

osu.Framework/Statistics/PerformanceMonitor.cs

···
 
         private Thread thread;
 
-        public double FrameAimTime => 1000.0 / (Clock?.MaximumUpdateHz ?? double.MaxValue);
+        public double FrameAimTime => 1000.0 / (Clock?.MaximumUpdateHz > 0 ? Clock.MaximumUpdateHz : double.MaxValue);
 
         internal PerformanceMonitor(GameThread thread, IEnumerable<StatisticsCounterType> counters)
         {

osu.Framework/Testing/TestBrowserTestRunner.cs

···
         {
             base.LoadComplete();
 
-            host.MaximumDrawHz = int.MaxValue;
-            host.MaximumUpdateHz = int.MaxValue;
-            host.MaximumInactiveHz = int.MaxValue;
-
             AddInternal(browser);
 
             Console.WriteLine($@"{(int)Time.Current}: Running {browser.TestTypes.Count} visual test cases...");

osu.Framework/Testing/TestRunHeadlessGameHost.cs

···
 // Copyright (c) ppy Pty Ltd <[e-mail]>. Licensed under the MIT Licence.
 // See the LICENCE file in the repository root for full licence text.
 
+using System.Collections.Generic;
 using System.IO;
+using osu.Framework.Extensions.IEnumerableExtensions;
 using osu.Framework.Logging;
 using osu.Framework.Platform;
 
···
     {
         private readonly bool bypassCleanup;
 
-        public override string UserStoragePath { get; }
+        public override IEnumerable<string> UserStoragePaths { get; }
 
         public static string TemporaryTestDirectory = Path.Combine(Path.GetTempPath(), "of-test-headless");
 
···
             : base(name, bindIPC, realtime, portableInstallation)
         {
             this.bypassCleanup = bypassCleanup;
-            UserStoragePath = TemporaryTestDirectory;
+            UserStoragePaths = TemporaryTestDirectory.Yield();
         }
 
         protected override void Dispose(bool isDisposing)

osu.Framework/Testing/TestSceneTestRunner.cs

···
                 if (volume != null) volume.Value = volumeAtStartup;
             }
 
-            protected override void LoadComplete()
-            {
-                base.LoadComplete();
-
-                host.MaximumDrawHz = int.MaxValue;
-                host.MaximumUpdateHz = int.MaxValue;
-                host.MaximumInactiveHz = int.MaxValue;
-            }
-
             /// <summary>
             /// Blocks execution until a provided <see cref="TestScene"/> runs to completion.
             /// </summary>

osu.Framework/Threading/GameThread.cs

···
         private CultureInfo culture;
 
         /// <summary>
-        /// The refresh rate this thread should run at when active. Only applies when the underlying clock is throttling.
+        /// The target number of updates per second when the game window is active.
         /// </summary>
+        /// <remarks>
+        /// A value of 0 is treated the same as "unlimited" or <see cref="double.MaxValue"/>.
+        /// </remarks>
         public double ActiveHz
         {
             get => activeHz;
···
         private double activeHz = DEFAULT_ACTIVE_HZ;
 
         /// <summary>
-        /// The refresh rate this thread should run at when inactive. Only applies when the underlying clock is throttling.
+        /// The target number of updates per second when the game window is inactive.
         /// </summary>
+        /// <remarks>
+        /// A value of 0 is treated the same as "unlimited" or <see cref="double.MaxValue"/>.
+        /// </remarks>
         public double InactiveHz
         {
             get => inactiveHz;

osu.Framework/Timing/ThrottledFrameClock.cs

···
     public class ThrottledFrameClock : FramedClock
     {
         /// <summary>
-        /// The number of updated per second which is permitted.
+        /// The target number of updates per second. Only used when <see cref="Throttling"/> is <c>true</c>.
         /// </summary>
+        /// <remarks>
+        /// A value of 0 is treated the same as "unlimited" or <see cref="double.MaxValue"/>.
+        /// </remarks>
         public double MaximumUpdateHz = 1000.0;
 
         /// <summary>
-        /// Whether throttling should be enabled. Defaults to true.
+        /// Whether throttling should be enabled. Defaults to <c>true</c>.
         /// </summary>
         public bool Throttling = true;
 
···
 
             if (Throttling)
             {
-                if (MaximumUpdateHz > 0)
+                if (MaximumUpdateHz > 0 && MaximumUpdateHz < double.MaxValue)
                 {
                     throttle();
                 }