Merge pull request #1343 from goatcorp/v9-rollup

Dalamud/Plugin/DalamudPluginInterface.cs

@@ -56,7 +56,7 @@ public sealed class DalamudPluginInterface : IDisposable
 
         this.configs = Service<PluginManager>.Get().PluginConfigs;
         this.Reason = reason;
-        this.SourceRepository = this.IsDev ? LocalPluginManifest.FlagDevPlugin : plugin.Manifest.InstalledFromUrl;
+        this.SourceRepository = this.IsDev ? SpecialPluginSource.DevPlugin : plugin.Manifest.InstalledFromUrl;
         this.IsTesting = plugin.IsTesting;
 
         this.LoadTime = DateTime.Now;
@@ -118,8 +118,8 @@ public sealed class DalamudPluginInterface : IDisposable
     /// Gets the repository from which this plugin was installed.
     ///
     /// If a plugin was installed from the official/main repository, this will return the value of
-    /// <see cref="LocalPluginManifest.FlagMainRepo"/>. Developer plugins will return the value of
-    /// <see cref="LocalPluginManifest.FlagDevPlugin"/>.
+    /// <see cref="SpecialPluginSource.MainRepo"/>. Developer plugins will return the value of
+    /// <see cref="SpecialPluginSource.DevPlugin"/>.
     /// </summary>
     public string SourceRepository { get; }
 

Dalamud/Plugin/Internal/PluginManager.cs

@@ -862,7 +862,7 @@ internal partial class PluginManager : IDisposable, IServiceType
         }
 
         // Document the url the plugin was installed from
-        manifest.InstalledFromUrl = repoManifest.SourceRepo.IsThirdParty ? repoManifest.SourceRepo.PluginMasterUrl : LocalPluginManifest.FlagMainRepo;
+        manifest.InstalledFromUrl = repoManifest.SourceRepo.IsThirdParty ? repoManifest.SourceRepo.PluginMasterUrl : SpecialPluginSource.MainRepo;
 
         manifest.Save(manifestFile, "installation");
 

Dalamud/Plugin/Internal/Profiles/Profile.cs

@@ -232,4 +232,7 @@ internal class Profile
         if (apply)
             await this.manager.ApplyAllWantStatesAsync();
     }
+
+    /// <inheritdoc/>
+    public override string ToString() => $"{this.Guid} ({this.Name})";
 }

Dalamud/Plugin/Internal/Types/Manifest/LocalPluginManifest.cs

@@ -13,18 +13,6 @@ namespace Dalamud.Plugin.Internal.Types.Manifest;
 /// </summary>
 internal record LocalPluginManifest : PluginManifest, ILocalPluginManifest
 {
-    /// <summary>
-    /// Flag indicating that a plugin was installed from the official repo.
-    /// </summary>
-    [JsonIgnore]
-    public const string FlagMainRepo = "OFFICIAL";
-
-    /// <summary>
-    /// Flag indicating that a plugin is a dev plugin..
-    /// </summary>
-    [JsonIgnore]
-    public const string FlagDevPlugin = "DEVPLUGIN";
-
     /// <summary>
     /// Gets or sets a value indicating whether the plugin is disabled and should not be loaded.
     /// This value supersedes the ".disabled" file functionality and should not be included in the plugin master.
@@ -51,7 +39,7 @@ internal record LocalPluginManifest : PluginManifest, ILocalPluginManifest
     /// Gets a value indicating whether this manifest is associated with a plugin that was installed from a third party
     /// repo. Unless the manifest has been manually modified, this is determined by the InstalledFromUrl being null.
     /// </summary>
-    public bool IsThirdParty => !this.InstalledFromUrl.IsNullOrEmpty() && this.InstalledFromUrl != FlagMainRepo;
+    public bool IsThirdParty => !this.InstalledFromUrl.IsNullOrEmpty() && this.InstalledFromUrl != SpecialPluginSource.MainRepo;
 
     /// <summary>
     /// Gets the effective version of this plugin.

Dalamud/Plugin/Internal/Types/Manifest/SpecialPluginSource.cs

@@ -0,0 +1,17 @@
+namespace Dalamud.Plugin.Internal.Types.Manifest;
+
+/// <summary>
+/// A fake enum representing "special" sources for plugins.
+/// </summary>
+public static class SpecialPluginSource 
+{
+    /// <summary>
+    /// Indication that this plugin came from the official Dalamud repository. 
+    /// </summary>
+    public const string MainRepo = "OFFICIAL";
+
+    /// <summary>
+    /// Indication that this plugin is loaded as a dev plugin. See also <see cref="DalamudPluginInterface.IsDev"/>.
+    /// </summary>
+    public const string DevPlugin = "DEVPLUGIN";
+}

Dalamud/Plugin/Services/IAddonLifecycle.cs

@@ -0,0 +1,45 @@
+using System;
+
+using Dalamud.Memory;
+using FFXIVClientStructs.FFXIV.Component.GUI;
+
+namespace Dalamud.Plugin.Services;
+
+/// <summary>
+/// This class provides events for in-game addon lifecycles.
+/// </summary>
+public interface IAddonLifecycle
+{
+    /// <summary>
+    /// Event that fires before an addon is being setup.
+    /// </summary>
+    public event Action<AddonArgs> AddonPreSetup;
+    
+    /// <summary>
+    /// Event that fires after an addon is done being setup.
+    /// </summary>
+    public event Action<AddonArgs> AddonPostSetup;
+    
+    /// <summary>
+    /// Event that fires before an addon is being finalized.
+    /// </summary>
+    public event Action<AddonArgs> AddonPreFinalize;
+    
+    /// <summary>
+    /// Addon argument data for use in event subscribers.
+    /// </summary>
+    public unsafe class AddonArgs
+    {
+        private string? addonName;
+        
+        /// <summary>
+        /// Gets the name of the addon this args referrers to.
+        /// </summary>
+        public string AddonName => this.Addon == nint.Zero ? "NullAddon" : this.addonName ??= MemoryHelper.ReadString((nint)((AtkUnitBase*)this.Addon)->Name, 0x20);
+
+        /// <summary>
+        /// Gets the pointer to the addons AtkUnitBase.
+        /// </summary>
+        required public nint Addon { get; init; }
+    }
+}

Dalamud/Plugin/Services/IPluginLog.cs

@@ -0,0 +1,128 @@
+using System;
+
+using Serilog;
+using Serilog.Events;
+
+namespace Dalamud.Plugin.Services;
+
+/// <summary>
+/// An opinionated service to handle logging for plugins.
+/// </summary>
+public interface IPluginLog
+{
+    /// <summary>
+    /// Gets or sets the minimum log level that will be recorded from this plugin to Dalamud's logs. This may be set
+    /// by either the plugin or by Dalamud itself.
+    /// </summary>
+    /// <remarks>
+    /// Defaults to <see cref="LogEventLevel.Debug"/> for downloaded plugins, and <see cref="LogEventLevel.Verbose"/>
+    /// for dev plugins.
+    /// </remarks>
+    LogEventLevel MinimumLogLevel { get; set; }
+
+    /// <summary>
+    /// Gets an instance of the Serilog <see cref="ILogger"/> for advanced use cases. The provided logger will handle
+    /// tagging all log messages with the appropriate context variables and properties.
+    /// </summary>
+    /// <remarks>
+    /// Not currently part of public API - will be added after some formatter work has been completed.
+    /// </remarks>
+    internal ILogger Logger { get; }
+
+    /// <summary>
+    /// Log a <see cref="LogEventLevel.Fatal" /> message to the Dalamud log for this plugin. This log level should be
+    /// used primarily for unrecoverable errors or critical faults in a plugin.
+    /// </summary>
+    /// <param name="messageTemplate">Message template describing the event.</param>
+    /// <param name="values">Objects positionally formatted into the message template.</param>
+    void Fatal(string messageTemplate, params object[] values);
+    
+    /// <inheritdoc cref="Fatal(string,object[])"/>
+    /// <param name="exception">An (optional) exception that should be recorded alongside this event.</param>
+    void Fatal(Exception? exception, string messageTemplate, params object[] values);
+    
+    /// <summary>
+    /// Log a <see cref="LogEventLevel.Error" /> message to the Dalamud log for this plugin. This log level should be
+    /// used for recoverable errors or faults that impact plugin functionality.
+    /// </summary>
+    /// <param name="messageTemplate">Message template describing the event.</param>
+    /// <param name="values">Objects positionally formatted into the message template.</param>
+    void Error(string messageTemplate, params object[] values);
+    
+    /// <inheritdoc cref="Error(string,object[])"/>
+    /// <param name="exception">An (optional) exception that should be recorded alongside this event.</param>
+    void Error(Exception? exception, string messageTemplate, params object[] values);
+    
+    /// <summary>
+    /// Log a <see cref="LogEventLevel.Warning" /> message to the Dalamud log for this plugin. This log level should be
+    /// used for user error, potential problems, or high-importance messages that should be logged. 
+    /// </summary>
+    /// <param name="messageTemplate">Message template describing the event.</param>
+    /// <param name="values">Objects positionally formatted into the message template.</param>
+    void Warning(string messageTemplate, params object[] values);
+    
+    /// <inheritdoc cref="Warning(string,object[])"/>
+    /// <param name="exception">An (optional) exception that should be recorded alongside this event.</param>
+    void Warning(Exception? exception, string messageTemplate, params object[] values);
+    
+    /// <summary>
+    /// Log an <see cref="LogEventLevel.Information" /> message to the Dalamud log for this plugin. This log level
+    /// should be used for general plugin operations and other relevant information to track a plugin's behavior. 
+    /// </summary>
+    /// <param name="messageTemplate">Message template describing the event.</param>
+    /// <param name="values">Objects positionally formatted into the message template.</param>
+    void Information(string messageTemplate, params object[] values);
+    
+    /// <inheritdoc cref="Information(string,object[])"/>
+    /// <param name="exception">An (optional) exception that should be recorded alongside this event.</param>
+    void Information(Exception? exception, string messageTemplate, params object[] values);
+    
+    /// <summary>
+    /// Log a <see cref="LogEventLevel.Debug" /> message to the Dalamud log for this plugin. This log level should be
+    /// used for messages or information that aid with debugging or tracing a plugin's operations, but should not be
+    /// recorded unless requested.
+    /// </summary>
+    /// <remarks>
+    /// By default, this log level is below the default log level of Dalamud. Messages logged at this level will not be
+    /// recorded unless the global log level is specifically set to Debug or lower. If information should be generally
+    /// or easily accessible for support purposes without the user taking additional action, consider using the
+    /// Information level instead. Developers should <em>not</em> use this log level where it can be triggered on a
+    /// per-frame basis.
+    /// </remarks>
+    /// <param name="messageTemplate">Message template describing the event.</param>
+    /// <param name="values">Objects positionally formatted into the message template.</param>
+    void Debug(string messageTemplate, params object[] values);
+
+    /// <inheritdoc cref="Debug(string,object[])"/>
+    /// <param name="exception">An (optional) exception that should be recorded alongside this event.</param>
+    void Debug(Exception? exception, string messageTemplate, params object[] values);
+
+    /// <summary>
+    /// Log a <see cref="LogEventLevel.Verbose" /> message to the Dalamud log for this plugin. This log level is
+    /// intended almost primarily for development purposes and detailed tracing of a plugin's operations. Verbose logs
+    /// should not be used to expose information useful for support purposes.
+    /// </summary>
+    /// <remarks>
+    /// By default, this log level is below the default log level of Dalamud. Messages logged at this level will not be
+    /// recorded unless the global log level is specifically set to Verbose. Release plugins must also set the
+    /// <see cref="MinimumLogLevel"/> to <see cref="LogEventLevel.Verbose"/> to use this level, and should only do so
+    /// upon specific user request (e.g. a "Enable Troubleshooting Logs" button). 
+    /// </remarks>
+    /// <param name="messageTemplate">Message template describing the event.</param>
+    /// <param name="values">Objects positionally formatted into the message template.</param>
+    void Verbose(string messageTemplate, params object[] values);
+
+    /// <inheritdoc cref="Verbose(string,object[])"/>
+    /// <param name="exception">An (optional) exception that should be recorded alongside this event.</param>
+    void Verbose(Exception? exception, string messageTemplate, params object[] values);
+
+    /// <summary>
+    /// Write a raw log event to the plugin's log. Used for interoperability with other log systems, as well as
+    /// advanced use cases.
+    /// </summary>
+    /// <param name="level">The log level for this event.</param>
+    /// <param name="exception">An (optional) exception that should be recorded alongside this event.</param>
+    /// <param name="messageTemplate">Message template describing the event.</param>
+    /// <param name="values">Objects positionally formatted into the message template.</param>
+    void Write(LogEventLevel level, Exception? exception, string messageTemplate, params object[] values);
+}

Dalamud/Plugin/Services/ITargetManager.cs

@@ -41,4 +41,16 @@ public interface ITargetManager
     /// Set to null to clear the target.
     /// </summary>
     public GameObject? SoftTarget { get; set; }
+    
+    /// <summary>
+    /// Gets or sets the gpose target.
+    /// Set to null to clear the target.
+    /// </summary>
+    public GameObject? GPoseTarget { get; set; }
+    
+    /// <summary>
+    /// Gets or sets the mouseover nameplate target.
+    /// Set to null to clear the target.
+    /// </summary>
+    public GameObject? MouseOverNameplateTarget { get; set; }
 }

Dalamud/Plugin/Services/ITextureSubstitutionProvider.cs

@@ -1,4 +1,6 @@
-namespace Dalamud.Plugin.Services;
+using System.Collections.Generic;
+
+namespace Dalamud.Plugin.Services;
 
 /// <summary>
 /// Service that grants you the ability to replace texture data that is to be loaded by Dalamud.
@@ -17,4 +19,19 @@ public interface ITextureSubstitutionProvider
     /// Event that will be called once Dalamud wants to load texture data.
     /// </summary>
     public event TextureDataInterceptorDelegate? InterceptTexDataLoad;
+
+    /// <summary>
+    /// Get a path that may be substituted by a subscriber to ITextureSubstitutionProvider.
+    /// </summary>
+    /// <param name="originalPath">The original path to substitute.</param>
+    /// <returns>The original path, if no subscriber is registered or there is no substitution, or the substituted path.</returns>
+    public string GetSubstitutedPath(string originalPath);
+
+    /// <summary>
+    /// Notify Dalamud about substitution status for files at the specified VFS paths changing.
+    /// You should call this with all paths that were either previously substituted and are no longer,
+    /// and paths that are newly substituted.
+    /// </summary>
+    /// <param name="paths">The paths with a changed substitution status.</param>
+    public void InvalidatePaths(IEnumerable<string> paths);
 }