From 9c53a254d50718fee3b8043bb0b8bb840557e82f Mon Sep 17 00:00:00 2001 From: Jesse Plamondon-Willard Date: Sat, 25 Feb 2017 15:22:45 -0500 Subject: [PATCH] add prototype content event + helper to manipulate XNB data (#173) --- src/StardewModdingAPI/Events/ContentEvents.cs | 69 +++++++++ .../Framework/ContentEventHelper.cs | 142 ++++++++++++++++++ .../Framework/SContentManager.cs | 36 ++++- src/StardewModdingAPI/IContentEventHelper.cs | 53 +++++++ src/StardewModdingAPI/Program.cs | 1 + .../StardewModdingAPI.csproj | 3 + 6 files changed, 297 insertions(+), 7 deletions(-) create mode 100644 src/StardewModdingAPI/Events/ContentEvents.cs create mode 100644 src/StardewModdingAPI/Framework/ContentEventHelper.cs create mode 100644 src/StardewModdingAPI/IContentEventHelper.cs diff --git a/src/StardewModdingAPI/Events/ContentEvents.cs b/src/StardewModdingAPI/Events/ContentEvents.cs new file mode 100644 index 00000000..cc07f242 --- /dev/null +++ b/src/StardewModdingAPI/Events/ContentEvents.cs @@ -0,0 +1,69 @@ +using System; +using System.Collections.Generic; +using StardewModdingAPI.Framework; + +namespace StardewModdingAPI.Events +{ + /// Events raised when the game loads content. + [Obsolete("This is an undocumented experimental API and may change without warning.")] + public static class ContentEvents + { + /********* + ** Properties + *********/ + /// Tracks the installed mods. + private static ModRegistry ModRegistry; + + /// Encapsulates monitoring and logging. + private static IMonitor Monitor; + + /// The mods using the experimental API for which a warning has been raised. + private static readonly HashSet WarnedMods = new HashSet(); + + + /********* + ** Events + *********/ + /// Raised when an XNB file is being read into the cache. Mods can change the data here before it's cached. + public static event EventHandler AssetLoading; + + + /********* + ** Internal methods + *********/ + /// Injects types required for backwards compatibility. + /// Tracks the installed mods. + /// Encapsulates monitoring and logging. + internal static void Shim(ModRegistry modRegistry, IMonitor monitor) + { + ContentEvents.ModRegistry = modRegistry; + ContentEvents.Monitor = monitor; + } + + /// Raise an event. + /// Encapsulates monitoring and logging. + /// Encapsulates access and changes to content being read from a data file. + internal static void InvokeAssetLoading(IMonitor monitor, IContentEventHelper contentHelper) + { + // raise warning about experimental API + foreach (Delegate handler in ContentEvents.AssetLoading.GetInvocationList()) + { + string modName = ContentEvents.ModRegistry.GetModFrom(handler) ?? "An unknown mod"; + if (!ContentEvents.WarnedMods.Contains(modName)) + { + ContentEvents.WarnedMods.Add(modName); + ContentEvents.Monitor.Log($"{modName} used the undocumented and experimental content API, which may change or be removed without warning.", LogLevel.Warn); + } + } + + // raise event + monitor.SafelyRaiseGenericEvent($"{nameof(ContentEvents)}.{nameof(ContentEvents.AssetLoading)}", ContentEvents.AssetLoading?.GetInvocationList(), null, contentHelper); + } + + /// Get whether there are any listeners. + internal static bool HasAssetLoadingListeners() + { + return ContentEvents.AssetLoading != null; + } + } +} diff --git a/src/StardewModdingAPI/Framework/ContentEventHelper.cs b/src/StardewModdingAPI/Framework/ContentEventHelper.cs new file mode 100644 index 00000000..d4a9bbb8 --- /dev/null +++ b/src/StardewModdingAPI/Framework/ContentEventHelper.cs @@ -0,0 +1,142 @@ +using System; +using System.Collections.Generic; +using System.Text.RegularExpressions; +using Microsoft.Xna.Framework.Graphics; + +namespace StardewModdingAPI.Framework +{ + /// Encapsulates access and changes to content being read from a data file. + internal class ContentEventHelper : EventArgs, IContentEventHelper + { + /********* + ** Properties + *********/ + /// Normalises an asset key to match the cache key. + private readonly Func GetNormalisedPath; + + + /********* + ** Accessors + *********/ + /// The normalised asset path being read. The format may change between platforms; see to compare with a known path. + public string Path { get; } + + /// The content data being read. + public object Data { get; private set; } + + + /********* + ** Public methods + *********/ + /// Construct an instance. + /// The file path being read. + /// The content data being read. + /// Normalises an asset key to match the cache key. + public ContentEventHelper(string path, object data, Func getNormalisedPath) + { + this.Path = path; + this.Data = data; + this.GetNormalisedPath = getNormalisedPath; + } + + /// Get whether the asset path being loaded matches a given path after normalisation. + /// The expected asset path, relative to the game folder and without the .xnb extension (like 'Data\ObjectInformation'). + /// Whether to match a localised version of the asset file (like 'Data\ObjectInformation.ja-JP'). + public bool IsPath(string path, bool matchLocalisedVersion = true) + { + path = this.GetNormalisedPath(path); + + // equivalent + if (this.Path.Equals(path, StringComparison.InvariantCultureIgnoreCase)) + return true; + + // localised version + if (matchLocalisedVersion) + { + return + this.Path.StartsWith($"{path}.", StringComparison.InvariantCultureIgnoreCase) // starts with given path + && Regex.IsMatch(this.Path.Substring(path.Length + 1), "^[a-z]+-[A-Z]+$"); // ends with locale (e.g. pt-BR) + } + + // no match + return false; + } + + /// Get the data as a given type. + /// The expected data type. + /// The data can't be converted to . + public TData GetData() + { + if (!(this.Data is TData)) + throw new InvalidCastException($"The content data of type {this.Data.GetType().FullName} can't be converted to the requested {typeof(TData).FullName}."); + return (TData)this.Data; + } + + /// Add or replace an entry in the dictionary data. + /// The entry key type. + /// The entry value type. + /// The entry key. + /// The entry value. + /// The content being read isn't a dictionary. + public void SetDictionaryEntry(TKey key, TValue value) + { + IDictionary data = this.GetData>(); + data[key] = value; + } + + /// Add or replace an entry in the dictionary data. + /// The entry key type. + /// The entry value type. + /// The entry key. + /// A callback which accepts the current value and returns the new value. + /// The content being read isn't a dictionary. + public void SetDictionaryEntry(TKey key, Func value) + { + IDictionary data = this.GetData>(); + data[key] = value(data[key]); + } + + /// Replace the entire content value with the given value. This is generally not recommended, since it may break compatibility with other mods or different versions of the game. + /// The new content value. + /// The is null. + /// The 's type is not compatible with the loaded asset's type. + public void ReplaceWith(object value) + { + if (value == null) + throw new ArgumentNullException(nameof(value), "Can't set a loaded asset to a null value."); + if (!this.Data.GetType().IsInstanceOfType(value)) + throw new InvalidCastException($"Can't replace loaded asset of type {this.GetFriendlyTypeName(this.Data.GetType())} with value of type {this.GetFriendlyTypeName(value.GetType())}. The new type must be compatible to prevent game errors."); + + this.Data = value; + } + + + /********* + ** Private methods + *********/ + /// Get a human-readable type name. + /// The type to name. + private string GetFriendlyTypeName(Type type) + { + // dictionary + if (type.IsGenericType && type.GetGenericTypeDefinition() == typeof(Dictionary<,>)) + { + Type[] genericArgs = type.GetGenericArguments(); + return $"Dictionary<{this.GetFriendlyTypeName(genericArgs[0])}, {this.GetFriendlyTypeName(genericArgs[1])}>"; + } + + // texture + if (type == typeof(Texture2D)) + return type.Name; + + // native type + if (type == typeof(int)) + return "int"; + if (type == typeof(string)) + return "string"; + + // default + return type.FullName; + } + } +} diff --git a/src/StardewModdingAPI/Framework/SContentManager.cs b/src/StardewModdingAPI/Framework/SContentManager.cs index 2a876d72..344d3ed9 100644 --- a/src/StardewModdingAPI/Framework/SContentManager.cs +++ b/src/StardewModdingAPI/Framework/SContentManager.cs @@ -4,6 +4,7 @@ using System.Globalization; using System.Threading; using Microsoft.Xna.Framework; using StardewModdingAPI.AssemblyRewriters; +using StardewModdingAPI.Events; using StardewModdingAPI.Framework.Reflection; using StardewValley; @@ -22,7 +23,7 @@ namespace StardewModdingAPI.Framework private readonly IDictionary Cache; /// Normalises an asset key to match the cache key. - private readonly IPrivateMethod NormaliseAssetKey; + private readonly Func NormaliseAssetKey; /********* @@ -44,15 +45,23 @@ namespace StardewModdingAPI.Framework public SContentManager(IServiceProvider serviceProvider, string rootDirectory, CultureInfo currentCulture, string languageCodeOverride, IMonitor monitor) : base(serviceProvider, rootDirectory, currentCulture, languageCodeOverride) { + // initialise this.Monitor = monitor; - IReflectionHelper reflection = new ReflectionHelper(); + + // get underlying asset cache this.Cache = reflection .GetPrivateField>(this, "loadedAssets") .GetValue(); - this.NormaliseAssetKey = Constants.TargetPlatform == Platform.Windows - ? reflection.GetPrivateMethod(typeof(TitleContainer), "GetCleanPath") - : reflection.GetPrivateMethod(this, nameof(this.NormaliseKeyForMono)); + + // get asset key normalisation logic + if (Constants.TargetPlatform == Platform.Windows) + { + IPrivateMethod method = reflection.GetPrivateMethod(typeof(TitleContainer), "GetCleanPath"); + this.NormaliseAssetKey = path => method.Invoke(path); + } + else + this.NormaliseAssetKey = this.NormaliseKeyForMono; } /// Load an asset that has been processed by the content pipeline. @@ -60,8 +69,21 @@ namespace StardewModdingAPI.Framework /// The asset path relative to the loader root directory, not including the .xnb extension. public override T Load(string assetName) { - assetName = this.NormaliseAssetKey.Invoke(assetName); - return base.Load(assetName); + // pass through if no event handlers + if (!ContentEvents.HasAssetLoadingListeners()) + return base.Load(assetName); + + // skip if already loaded + string key = this.NormaliseAssetKey(assetName); + if (this.Cache.ContainsKey(key)) + return base.Load(assetName); + + // intercept load + T data = base.Load(assetName); + IContentEventHelper helper = new ContentEventHelper(assetName, data, this.NormaliseAssetKey); + ContentEvents.InvokeAssetLoading(this.Monitor, helper); + this.Cache[key] = helper.Data; + return (T)helper.Data; } diff --git a/src/StardewModdingAPI/IContentEventHelper.cs b/src/StardewModdingAPI/IContentEventHelper.cs new file mode 100644 index 00000000..98d074d9 --- /dev/null +++ b/src/StardewModdingAPI/IContentEventHelper.cs @@ -0,0 +1,53 @@ +using System; + +namespace StardewModdingAPI +{ + /// Encapsulates access and changes to content being read from a data file. + public interface IContentEventHelper + { + /********* + ** Accessors + *********/ + /// The normalised asset path being read. The format may change between platforms; see to compare with a known path. + string Path { get; } + + /// The content data being read. + object Data { get; } + + + /********* + ** Public methods + *********/ + /// Get whether the asset path being loaded matches a given path after normalisation. + /// The expected asset path, relative to the game folder and without the .xnb extension (like 'Data\ObjectInformation'). + /// Whether to match a localised version of the asset file (like 'Data\ObjectInformation.ja-JP'). + bool IsPath(string path, bool matchLocalisedVersion = true); + + /// Get the data as a given type. + /// The expected data type. + /// The data can't be converted to . + TData GetData(); + + /// Add or replace an entry in the dictionary data. + /// The entry key type. + /// The entry value type. + /// The entry key. + /// The entry value. + /// The content being read isn't a dictionary. + void SetDictionaryEntry(TKey key, TValue value); + + /// Add or replace an entry in the dictionary data. + /// The entry key type. + /// The entry value type. + /// The entry key. + /// A callback which accepts the current value and returns the new value. + /// The content being read isn't a dictionary. + void SetDictionaryEntry(TKey key, Func value); + + /// Replace the entire content value with the given value. This is generally not recommended, since it may break compatibility with other mods or different versions of the game. + /// The new content value. + /// The is null. + /// The 's type is not compatible with the loaded asset's type. + void ReplaceWith(object value); + } +} diff --git a/src/StardewModdingAPI/Program.cs b/src/StardewModdingAPI/Program.cs index b7947df1..18a83e32 100644 --- a/src/StardewModdingAPI/Program.cs +++ b/src/StardewModdingAPI/Program.cs @@ -97,6 +97,7 @@ namespace StardewModdingAPI InternalExtensions.Shim(this.ModRegistry); Log.Shim(this.DeprecationManager, this.GetSecondaryMonitor("legacy mod"), this.ModRegistry); Mod.Shim(this.DeprecationManager); + ContentEvents.Shim(this.ModRegistry, this.Monitor); PlayerEvents.Shim(this.DeprecationManager); TimeEvents.Shim(this.DeprecationManager); #pragma warning restore 618 diff --git a/src/StardewModdingAPI/StardewModdingAPI.csproj b/src/StardewModdingAPI/StardewModdingAPI.csproj index ee37379d..9b86adac 100644 --- a/src/StardewModdingAPI/StardewModdingAPI.csproj +++ b/src/StardewModdingAPI/StardewModdingAPI.csproj @@ -117,6 +117,7 @@ + @@ -147,6 +148,7 @@ + @@ -158,6 +160,7 @@ +