From e91bf951d29bd4a7ca42c7c5d0c1138524b15481 Mon Sep 17 00:00:00 2001
From: DanW <danw@noreply.dev.sp-tarkov.com>
Date: Tue, 5 Dec 2023 09:39:28 +0000
Subject: [PATCH] Added HasRaidStarted Method to RaidTimeUtil (!41)

To avoid issues when somebody calls `GetRemainingRaidSeconds()` or `GetRaidTimeRemainingFraction()` when a raid isn't in progress, I throw an exception if `GameTimer` isn't running. However, this can be confusing for modders since `GameTimer` starts well after `GameWorld` is instantiated. Therefore, I added a new `HasRaidStarted()` method so it's more clear when these methods can be called. Additionally, I updated the documentation for those methods to warn the user that `HasRaidStarted()` must be true or they'll throw an exception.

Alternatively, I can change the return type from `float` to `float?` for those methods and return null if a raid hasn't started. However, I felt like a null response is less intuitive than an exception in this case.

Co-authored-by: dwesterwick <dwesterwick@yahoo.com>
Reviewed-on: https://dev.sp-tarkov.com/SPT-AKI/Modules/pulls/41
Co-authored-by: DanW <danw@noreply.dev.sp-tarkov.com>
Co-committed-by: DanW <danw@noreply.dev.sp-tarkov.com>
---
 .../Utils/InRaid/RaidTimeUtil.cs              | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/project/Aki.SinglePlayer/Utils/InRaid/RaidTimeUtil.cs b/project/Aki.SinglePlayer/Utils/InRaid/RaidTimeUtil.cs
index 2fc54e4..b0f3598 100644
--- a/project/Aki.SinglePlayer/Utils/InRaid/RaidTimeUtil.cs
+++ b/project/Aki.SinglePlayer/Utils/InRaid/RaidTimeUtil.cs
@@ -10,13 +10,22 @@ namespace Aki.SinglePlayer.Utils.InRaid
     public static class RaidTimeUtil
     {
         /// <summary>
-        /// Calculates the seconds remaining in the current raid
+        /// Determines if a raid is in-progress by checking if the GameTimer has started
+        /// </summary>
+        public static bool HasRaidStarted()
+        {
+            return Singleton<AbstractGame>.Instance.GameTimer.Started();
+        }
+
+        /// <summary>
+        /// <para>Calculates the seconds remaining in the current raid.</para>
+        /// <para>Please ensure <see cref="HasRaidStarted"/> is <c>true</c>, or this will throw an exception.</para>
         /// </summary>
         /// <returns>Seconds remaining in the raid</returns>
         /// <exception cref="InvalidOperationException">Thrown if there is no raid in progress</exception>
         public static float GetRemainingRaidSeconds()
         {
-            if (!Singleton<AbstractGame>.Instance.GameTimer.Started())
+            if (!HasRaidStarted())
             {
                 throw new InvalidOperationException("The raid-time remaining can only be calculated when a raid is in-progress");
             }
@@ -28,10 +37,12 @@ namespace Aki.SinglePlayer.Utils.InRaid
         }
 
         /// <summary>
-        /// Calculates the fraction of raid-time remaining relative to the original escape time for the map. 
-        /// 1.0 = the raid just started, and 0.0 = the raid is over (and you're MIA).
+        /// <para>Calculates the fraction of raid-time remaining relative to the original escape time for the map. 
+        /// 1.0 = the raid just started, and 0.0 = the raid is over (and you're MIA).</para>
+        /// <para>Please ensure <see cref="HasRaidStarted"/> is <c>true</c>, or this will throw an exception.</para>
         /// </summary>
         /// <returns>The fraction of raid-time remaining (0.0 - 1.0) relative to the original escape time for the map</returns>
+        /// <exception cref="InvalidOperationException">Thrown if there is no raid in progress</exception>
         public static float GetRaidTimeRemainingFraction()
         {
             return GetRemainingRaidSeconds() / RaidChangesUtil.OriginalEscapeTimeSeconds;