add GameLoop events for SMAPI 3.0 (#310)

5 files changed, 99 insertions, 0 deletions

diff --git a/src/SMAPI/Events/GameLoopLaunchedEventArgs.cs b/src/SMAPI/Events/GameLoopLaunchedEventArgs.cs
new file mode 100644
index 00000000..6a42e4f9
--- /dev/null
+++ b/src/SMAPI/Events/GameLoopLaunchedEventArgs.cs
@@ -0,0 +1,7 @@
+using System;
+
+namespace StardewModdingAPI.Events
+{
+    /// <summary>Event arguments for an <see cref="IGameLoopEvents.Launched"/> event.</summary>
+    public class GameLoopLaunchedEventArgs : EventArgs { }
+}
diff --git a/src/SMAPI/Events/GameLoopUpdatedEventArgs.cs b/src/SMAPI/Events/GameLoopUpdatedEventArgs.cs
new file mode 100644
index 00000000..3ad34b69
--- /dev/null
+++ b/src/SMAPI/Events/GameLoopUpdatedEventArgs.cs
@@ -0,0 +1,36 @@
+using System;
+
+namespace StardewModdingAPI.Events
+{
+    /// <summary>Event arguments for an <see cref="IGameLoopEvents.Updated"/> event.</summary>
+    public class GameLoopUpdatedEventArgs : EventArgs
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The number of ticks elapsed since the game started, including the current tick.</summary>
+        public uint Ticks { get; }
+
+        /// <summary>Whether <see cref="Ticks"/> is a multiple of 60, which happens approximately once per second.</summary>
+        public bool IsOneSecond { get; }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="ticks">The number of ticks elapsed since the game started, including the current tick.</param>
+        public GameLoopUpdatedEventArgs(uint ticks)
+        {
+            this.Ticks = ticks;
+            this.IsOneSecond = this.IsMultipleOf(60);
+        }
+
+        /// <summary>Get whether <see cref="Ticks"/> is a multiple of the given <paramref name="number"/>. This is mainly useful if you want to run logic intermittently (e.g. <code>e.IsMultipleOf(30)</code> for every half-second).</summary>
+        /// <param name="number">The factor to check.</param>
+        public bool IsMultipleOf(uint number)
+        {
+            return this.Ticks % number == 0;
+        }
+    }
+}
diff --git a/src/SMAPI/Events/GameLoopUpdatingEventArgs.cs b/src/SMAPI/Events/GameLoopUpdatingEventArgs.cs
new file mode 100644
index 00000000..d6a8b5c2
--- /dev/null
+++ b/src/SMAPI/Events/GameLoopUpdatingEventArgs.cs
@@ -0,0 +1,36 @@
+using System;
+
+namespace StardewModdingAPI.Events
+{
+    /// <summary>Event arguments for an <see cref="IGameLoopEvents.Updating"/> event.</summary>
+    public class GameLoopUpdatingEventArgs : EventArgs
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The number of ticks elapsed since the game started, including the current tick.</summary>
+        public uint Ticks { get; }
+
+        /// <summary>Whether <see cref="Ticks"/> is a multiple of 60, which happens approximately once per second.</summary>
+        public bool IsOneSecond { get; }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="ticks">The number of ticks elapsed since the game started, including the current tick.</param>
+        public GameLoopUpdatingEventArgs(uint ticks)
+        {
+            this.Ticks = ticks;
+            this.IsOneSecond = this.IsMultipleOf(60);
+        }
+
+        /// <summary>Get whether <see cref="Ticks"/> is a multiple of the given <paramref name="number"/>. This is mainly useful if you want to run logic intermittently (e.g. <code>e.IsMultipleOf(30)</code> for every half-second).</summary>
+        /// <param name="number">The factor to check.</param>
+        public bool IsMultipleOf(uint number)
+        {
+            return this.Ticks % number == 0;
+        }
+    }
+}
diff --git a/src/SMAPI/Events/IGameLoopEvents.cs b/src/SMAPI/Events/IGameLoopEvents.cs
new file mode 100644
index 00000000..a56b3de3
--- /dev/null
+++ b/src/SMAPI/Events/IGameLoopEvents.cs
@@ -0,0 +1,17 @@
+using System;
+
+namespace StardewModdingAPI.Events
+{
+    /// <summary>Events linked to the game's update loop. The update loop runs roughly ≈60 times/second to run game logic like state changes, action handling, etc. These can be useful, but you should consider more semantic events like <see cref="IInputEvents"/> if possible.</summary>
+    public interface IGameLoopEvents
+    {
+        /// <summary>Raised after the game is launched, right before the first update tick. This happens once per game session (unrelated to loading saves). All mods are loaded and initialised at this point, so this is a good time to set up mod integrations.</summary>
+        event EventHandler<GameLoopLaunchedEventArgs> Launched;
+
+        /// <summary>Raised before the game performs its overall update tick (≈60 times per second).</summary>
+        event EventHandler<GameLoopUpdatingEventArgs> Updating;
+
+        /// <summary>Raised after the game performs its overall update tick (≈60 times per second).</summary>
+        event EventHandler<GameLoopUpdatedEventArgs> Updated;
+    }
+}
diff --git a/src/SMAPI/Events/IModEvents.cs b/src/SMAPI/Events/IModEvents.cs
index 16ec6557..cf2f8cb8 100644
--- a/src/SMAPI/Events/IModEvents.cs
+++ b/src/SMAPI/Events/IModEvents.cs
@@ -3,6 +3,9 @@ namespace StardewModdingAPI.Events
     /// <summary>Manages access to events raised by SMAPI.</summary>
     public interface IModEvents
     {
+        /// <summary>Events linked to the game's update loop. The update loop runs roughly ≈60 times/second to run game logic like state changes, action handling, etc. These can be useful, but you should consider more semantic events like <see cref="Input"/> if possible.</summary>
+        IGameLoopEvents GameLoop { get; }
+
         /// <summary>Events raised when the player provides input using a controller, keyboard, or mouse.</summary>
         IInputEvents Input { get; }