From 0c73b02d58712f7f340f4326143d5439d6cd7f93 Mon Sep 17 00:00:00 2001 From: Jesse Plamondon-Willard Date: Sun, 15 Jan 2017 18:23:09 -0500 Subject: add save events (#215) --- src/StardewModdingAPI/Events/SaveEvents.cs | 46 ++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 src/StardewModdingAPI/Events/SaveEvents.cs (limited to 'src/StardewModdingAPI/Events') diff --git a/src/StardewModdingAPI/Events/SaveEvents.cs b/src/StardewModdingAPI/Events/SaveEvents.cs new file mode 100644 index 00000000..2921003a --- /dev/null +++ b/src/StardewModdingAPI/Events/SaveEvents.cs @@ -0,0 +1,46 @@ +using System; +using StardewModdingAPI.Framework; + +namespace StardewModdingAPI.Events +{ + /// Events raised before and after the player saves/loads the game. + public static class SaveEvents + { + /********* + ** Events + *********/ + /// Raised before the game begins writes data to the save file. + public static event EventHandler BeforeSave; + + /// Raised after the game finishes writing data to the save file. + public static event EventHandler AfterSave; + + /// Raised after the player loads a save slot. + public static event EventHandler AfterLoad; + + + /********* + ** Internal methods + *********/ + /// Raise a event. + /// Encapsulates monitoring and logging. + internal static void InvokeBeforeSave(IMonitor monitor) + { + monitor.SafelyRaisePlainEvent($"{nameof(SaveEvents)}.{nameof(SaveEvents.BeforeSave)}", SaveEvents.BeforeSave?.GetInvocationList(), null, EventArgs.Empty); + } + + /// Raise a event. + /// Encapsulates monitoring and logging. + internal static void InvokeAfterSave(IMonitor monitor) + { + monitor.SafelyRaisePlainEvent($"{nameof(SaveEvents)}.{nameof(SaveEvents.AfterSave)}", SaveEvents.AfterSave?.GetInvocationList(), null, EventArgs.Empty); + } + + /// Raise a event. + /// Encapsulates monitoring and logging. + internal static void InvokeAfterLoad(IMonitor monitor) + { + monitor.SafelyRaisePlainEvent($"{nameof(SaveEvents)}.{nameof(SaveEvents.AfterLoad)}", SaveEvents.AfterLoad?.GetInvocationList(), null, EventArgs.Empty); + } + } +} -- cgit From 64a72c45e3c4b504c7a1b61a539f1cbc9b9d23cc Mon Sep 17 00:00:00 2001 From: Jesse Plamondon-Willard Date: Sun, 15 Jan 2017 19:21:26 -0500 Subject: deprecate events replaced by save events (#215) --- release-notes.md | 5 +++ src/StardewModdingAPI/Events/PlayerEvents.cs | 20 +++++++++-- src/StardewModdingAPI/Events/TimeEvents.cs | 10 +++++- .../Framework/InternalExtensions.cs | 21 ++++++++++++ src/StardewModdingAPI/Framework/ModRegistry.cs | 40 +++++++++++++++++----- 5 files changed, 84 insertions(+), 12 deletions(-) (limited to 'src/StardewModdingAPI/Events') diff --git a/release-notes.md b/release-notes.md index ffcfd560..6b1ee02f 100644 --- a/release-notes.md +++ b/release-notes.md @@ -13,6 +13,11 @@ For players: * Updated list of incompatible mods. For mod developers: +* Added three events: `SaveEvents.BeforeSave`, `SaveEvents.AfterSave`, and `SaveEvents.AfterLoad`. +* Deprecated three events: + * `TimeEvents.OnNewDay` is unreliable, use `TimeEvents.DayOfMonthChanged` or `SaveEvents` instead; + * `PlayerEvents.LoadedGame` is replaced by `SaveEvents.AfterLoad`; + * `PlayerEvents.FarmerChanged` serves no purpose. * Fixed error when reading a custom JSON file from a directory that doesn't exist. For SMAPI developers: diff --git a/src/StardewModdingAPI/Events/PlayerEvents.cs b/src/StardewModdingAPI/Events/PlayerEvents.cs index 3f301b07..dd3ff220 100644 --- a/src/StardewModdingAPI/Events/PlayerEvents.cs +++ b/src/StardewModdingAPI/Events/PlayerEvents.cs @@ -14,9 +14,11 @@ namespace StardewModdingAPI.Events ** Events *********/ /// Raised after the player loads a saved game. + [Obsolete("Use " + nameof(SaveEvents) + "." + nameof(SaveEvents.AfterLoad) + " instead")] public static event EventHandler LoadedGame; /// Raised after the game assigns a new player character. This happens just before ; it's unclear how this would happen any other time. + [Obsolete("should no longer be used")] public static event EventHandler FarmerChanged; /// Raised after the player's inventory changes in any way (added or removed item, sorted, etc). @@ -34,7 +36,14 @@ namespace StardewModdingAPI.Events /// Whether the save has been loaded. This is always true. internal static void InvokeLoadedGame(IMonitor monitor, EventArgsLoadedGameChanged loaded) { - monitor.SafelyRaiseGenericEvent($"{nameof(PlayerEvents)}.{nameof(PlayerEvents.LoadedGame)}", PlayerEvents.LoadedGame?.GetInvocationList(), null, loaded); + if (PlayerEvents.LoadedGame == null) + return; + + string name = $"{nameof(PlayerEvents)}.{nameof(PlayerEvents.LoadedGame)}"; + Delegate[] handlers = PlayerEvents.LoadedGame.GetInvocationList(); + + Program.DeprecationManager.WarnForEvent(handlers, name, "1.6", DeprecationLevel.Notice); + monitor.SafelyRaiseGenericEvent(name, handlers, null, loaded); } /// Raise a event. @@ -43,7 +52,14 @@ namespace StardewModdingAPI.Events /// The new player character. internal static void InvokeFarmerChanged(IMonitor monitor, Farmer priorFarmer, Farmer newFarmer) { - monitor.SafelyRaiseGenericEvent($"{nameof(PlayerEvents)}.{nameof(PlayerEvents.FarmerChanged)}", PlayerEvents.FarmerChanged?.GetInvocationList(), null, new EventArgsFarmerChanged(priorFarmer, newFarmer)); + if (PlayerEvents.FarmerChanged == null) + return; + + string name = $"{nameof(PlayerEvents)}.{nameof(PlayerEvents.FarmerChanged)}"; + Delegate[] handlers = PlayerEvents.FarmerChanged.GetInvocationList(); + + Program.DeprecationManager.WarnForEvent(handlers, name, "1.6", DeprecationLevel.Notice); + monitor.SafelyRaiseGenericEvent(name, handlers, null, new EventArgsFarmerChanged(priorFarmer, newFarmer)); } /// Raise an event. diff --git a/src/StardewModdingAPI/Events/TimeEvents.cs b/src/StardewModdingAPI/Events/TimeEvents.cs index 1b367230..dedd7e77 100644 --- a/src/StardewModdingAPI/Events/TimeEvents.cs +++ b/src/StardewModdingAPI/Events/TimeEvents.cs @@ -22,6 +22,7 @@ namespace StardewModdingAPI.Events public static event EventHandler SeasonOfYearChanged; /// Raised when the player is transitioning to a new day and the game is performing its day update logic. This event is triggered twice: once after the game starts transitioning, and again after it finishes. + [Obsolete("Use " + nameof(TimeEvents) + "." + nameof(DayOfMonthChanged) + " or " + nameof(SaveEvents) + " instead")] public static event EventHandler OnNewDay; @@ -71,7 +72,14 @@ namespace StardewModdingAPI.Events /// Whether the game just started the transition (true) or finished it (false). internal static void InvokeOnNewDay(IMonitor monitor, int priorDay, int newDay, bool isTransitioning) { - monitor.SafelyRaiseGenericEvent($"{nameof(TimeEvents)}.{nameof(TimeEvents.OnNewDay)}", TimeEvents.OnNewDay?.GetInvocationList(), null, new EventArgsNewDay(priorDay, newDay, isTransitioning)); + if (TimeEvents.OnNewDay == null) + return; + + string name = $"{nameof(TimeEvents)}.{nameof(TimeEvents.OnNewDay)}"; + Delegate[] handlers = TimeEvents.OnNewDay.GetInvocationList(); + + Program.DeprecationManager.WarnForEvent(handlers, name, "1.6", DeprecationLevel.Notice); + monitor.SafelyRaiseGenericEvent(name, handlers, null, new EventArgsNewDay(priorDay, newDay, isTransitioning)); } } } diff --git a/src/StardewModdingAPI/Framework/InternalExtensions.cs b/src/StardewModdingAPI/Framework/InternalExtensions.cs index 415785d9..c4bd2d35 100644 --- a/src/StardewModdingAPI/Framework/InternalExtensions.cs +++ b/src/StardewModdingAPI/Framework/InternalExtensions.cs @@ -86,5 +86,26 @@ namespace StardewModdingAPI.Framework // anything else return exception.ToString(); } + + /**** + ** Deprecation + ****/ + /// Log a deprecation warning for mods using an event. + /// The deprecation manager to extend. + /// The event handlers. + /// A noun phrase describing what is deprecated. + /// The SMAPI version which deprecated it. + /// How deprecated the code is. + public static void WarnForEvent(this DeprecationManager deprecationManager, Delegate[] handlers, string nounPhrase, string version, DeprecationLevel severity) + { + if (handlers == null || !handlers.Any()) + return; + + foreach (Delegate handler in handlers) + { + string modName = Program.ModRegistry.GetModFrom(handler) ?? "an unknown mod"; // suppress stack trace for unknown mods, not helpful here + deprecationManager.Warn(modName, nounPhrase, version, severity); + } + } } } diff --git a/src/StardewModdingAPI/Framework/ModRegistry.cs b/src/StardewModdingAPI/Framework/ModRegistry.cs index b593142d..51ec7123 100644 --- a/src/StardewModdingAPI/Framework/ModRegistry.cs +++ b/src/StardewModdingAPI/Framework/ModRegistry.cs @@ -36,6 +36,34 @@ namespace StardewModdingAPI.Framework return (from mod in this.Mods select mod); } + /// Get the friendly mod name which handles a delegate. + /// The delegate to follow. + /// Returns the mod name, or null if the delegate isn't implemented by a known mod. + public string GetModFrom(Delegate @delegate) + { + return @delegate?.Target != null + ? this.GetModFrom(@delegate.Target.GetType()) + : null; + } + + /// Get the friendly mod name which defines a type. + /// The type to check. + /// Returns the mod name, or null if the type isn't part of a known mod. + public string GetModFrom(Type type) + { + // null + if (type == null) + return null; + + // known type + string assemblyName = type.Assembly.FullName; + if (this.ModNamesByAssembly.ContainsKey(assemblyName)) + return this.ModNamesByAssembly[assemblyName]; + + // not found + return null; + } + /// Get the friendly name for the closest assembly registered as a source of deprecation warnings. /// Returns the source name, or null if no registered assemblies were found. public string GetModFromStack() @@ -49,16 +77,10 @@ namespace StardewModdingAPI.Framework // search stack for a source assembly foreach (StackFrame frame in frames) { - // get assembly name MethodBase method = frame.GetMethod(); - Type type = method.ReflectedType; - if (type == null) - continue; - string assemblyName = type.Assembly.FullName; - - // get name if it's a registered source - if (this.ModNamesByAssembly.ContainsKey(assemblyName)) - return this.ModNamesByAssembly[assemblyName]; + string name = this.GetModFrom(method.ReflectedType); + if (name != null) + return name; } // no known assembly found -- cgit