From d5671b86596e8766f5ff007a92a37a5f89388bca Mon Sep 17 00:00:00 2001 From: Kaz Wolfe Date: Mon, 29 Jul 2024 19:00:47 -0700 Subject: [PATCH 1/2] Add new Project Layout section - wip-ish, we need other pages. --- .../interaction/_category_.yml | 5 +- docs/plugin-development/plugin-submission.md | 4 +- docs/plugin-development/project-layout.md | 66 +++++++++++++++++++ docs/plugin-development/restrictions.md | 6 +- 4 files changed, 73 insertions(+), 8 deletions(-) create mode 100644 docs/plugin-development/project-layout.md diff --git a/docs/plugin-development/interaction/_category_.yml b/docs/plugin-development/interaction/_category_.yml index fe53468..399dfac 100644 --- a/docs/plugin-development/interaction/_category_.yml +++ b/docs/plugin-development/interaction/_category_.yml @@ -1,6 +1,5 @@ label: Interacting With The Game position: 3 link: - type: generated-index - title: Interacting With The Game - description: Learn how to interact and tie into the game in a richer fashion than just showing a window. + type: doc + id: index diff --git a/docs/plugin-development/plugin-submission.md b/docs/plugin-development/plugin-submission.md index d591837..290f0ce 100644 --- a/docs/plugin-development/plugin-submission.md +++ b/docs/plugin-development/plugin-submission.md @@ -60,12 +60,12 @@ for plugin developers, while encouraging them to stay true to that intent. Technical criteria include a thorough code review, that the plugin works and that it does not upload any personal data. All of this can take a while, which is why it's not uncommon for a new plugin to sit in the queue for more than a -week - all of the team members are doing this in their free time, so they might +week - all the team members are doing this in their free time, so they might not get to it before then. We also require all new plugins to go through the plugin testing track beforehand, which distributes the plugin to testing users before it goes out to -everyone using Dalamud. This helps tracking down potential issues and bugs. +everyone using Dalamud. This helps track down potential issues and bugs. ## Updates to plugins diff --git a/docs/plugin-development/project-layout.md b/docs/plugin-development/project-layout.md new file mode 100644 index 0000000..20e9d47 --- /dev/null +++ b/docs/plugin-development/project-layout.md @@ -0,0 +1,66 @@ +# Project Layout and Configuration + +Dalamud does not strictly require much in the form of project layout, but will require a few things nevertheless. + +As an example, please see the following directory layout: + +``` +MySolution +|- MyPlugin +| |- MyPlugin.csproj +| |- MyPlugin.json +| |- packages.lock.json +| |- Plugin.cs +|- MySolution.sln +``` + +When building your plugin, your primary plugin DLL must also be named accordingly. This will usually happen by default, +so unless you're changing settings you don't really need to worry about this. + +Your project directory can be nested under subdirectories (e.g. `src/`), and you may have other projects within the same +solution. There is no restriction to the programming language used for any other projects in the same solution. + +## The Internal Name + +Your plugin's `AssemblyName`, generally auto-set to your `.csproj` file name, will become what's known as the plugin's +**`InternalName`**. Once set this value ***may not be changed***, so it's important to choose a name that you will be +happy with. + +This internal name will be used for your plugin's config directory, is attached to all log entries, and is used as the +name on your plugin's DLL and D17 submissions. + +You may use a different name for the plugin's display name by setting the `Name` field of your plugin manifest +accordingly. + +## Manifest File + +Your plugin DLL must be distributed alongside a **manifest file**, which contains certain key information such as your +author name, the plugin's punchline, the internal name declaration, and other miscellaneous data. See our [manifest] +section for more detailed information as to what needs to be contained within it. This data is also used to generate our +PluginMaster (repository) files which are delivered to users to populate the installer. + +Normally, our `DalamudPackager` helper (included in the Dalamud SDK and referenced in our `.targets` file) will +automatically generate your manifest using a template file in your project directory. This template file may be of type +`.json` or `.yml`, and must be named following your plugin's Internal Name (e.g. `MyPlugin.json`). The `DalamudPackager` +helper will automatically add critical fields such as `InternalName`, `AssemblyVersion`, `DalamudApiLevel`, and others. + +At a minimum, your template manifest for `DalamudPackager` must contain the following keys: + +```json +{ + "Name": "My Awesome Plugin", + "Author": "You!", + "Punchline": "An awesome plugin that does cool things.", + "Description": "Did you ever feel like your game could be even more awesome? This plugin is the answer!", + "RepoUrl": "https://github.com/AwesomePluginDev/MyAwesomePlugin" +} +``` + +## The Plugin Entrypoint + +Dalamud will scan your DLL for a class that extends `IDalamudPlugin`. This class will then be initialized, injecting +any [services] declared in the class' constructor. Your plugin may only have *one* such entrypoint. + +As `IDalamudPlugin` inherits from `IDisposable`, your plugin must also specify a `void Dispose()` method to clean up +after itself. Plugin developers are required to implement a fully-functional dispose cycle and, ideally, not leak any +resources. \ No newline at end of file diff --git a/docs/plugin-development/restrictions.md b/docs/plugin-development/restrictions.md index e3ee23c..689c68d 100644 --- a/docs/plugin-development/restrictions.md +++ b/docs/plugin-development/restrictions.md @@ -28,9 +28,9 @@ Please make sure that, as much as possible: - your plugin does not have a hard dependency on any plugin that violates the Plugin Guidelines -If you are not sure about whether or not your plugin will be allowed, _please_ -contact us before you start work on it. We don't want to have to turn you down -after you've already done the work! +If you are not sure whether your plugin will be allowed, _please_ contact us +before you start work on it. We don't want to have to turn you down after +you've already done the work! Plugins that violate these rules will not be accepted into the Dalamud plugin repository, and you will not receive support from the Dalamud community. From 2687e8d0529f72b701b086cbe7917f2f25cff743 Mon Sep 17 00:00:00 2001 From: Kaz Wolfe Date: Mon, 29 Jul 2024 19:03:16 -0700 Subject: [PATCH 2/2] lint. --- docs/plugin-development/plugin-submission.md | 4 +- docs/plugin-development/project-layout.md | 79 ++++++++++-------- docs/plugin-development/restrictions.md | 6 +- docs/versions/v10.md | 84 +++++++++++++++----- 4 files changed, 114 insertions(+), 59 deletions(-) diff --git a/docs/plugin-development/plugin-submission.md b/docs/plugin-development/plugin-submission.md index 290f0ce..4b3dde4 100644 --- a/docs/plugin-development/plugin-submission.md +++ b/docs/plugin-development/plugin-submission.md @@ -60,8 +60,8 @@ for plugin developers, while encouraging them to stay true to that intent. Technical criteria include a thorough code review, that the plugin works and that it does not upload any personal data. All of this can take a while, which is why it's not uncommon for a new plugin to sit in the queue for more than a -week - all the team members are doing this in their free time, so they might -not get to it before then. +week - all the team members are doing this in their free time, so they might not +get to it before then. We also require all new plugins to go through the plugin testing track beforehand, which distributes the plugin to testing users before it goes out to diff --git a/docs/plugin-development/project-layout.md b/docs/plugin-development/project-layout.md index 20e9d47..ba0c1f7 100644 --- a/docs/plugin-development/project-layout.md +++ b/docs/plugin-development/project-layout.md @@ -1,50 +1,59 @@ # Project Layout and Configuration -Dalamud does not strictly require much in the form of project layout, but will require a few things nevertheless. +Dalamud does not strictly require much in the form of project layout, but will +require a few things nevertheless. As an example, please see the following directory layout: -``` -MySolution -|- MyPlugin -| |- MyPlugin.csproj -| |- MyPlugin.json -| |- packages.lock.json -| |- Plugin.cs -|- MySolution.sln -``` + MySolution + |- MyPlugin + | |- MyPlugin.csproj + | |- MyPlugin.json + | |- packages.lock.json + | |- Plugin.cs + |- MySolution.sln -When building your plugin, your primary plugin DLL must also be named accordingly. This will usually happen by default, -so unless you're changing settings you don't really need to worry about this. +When building your plugin, your primary plugin DLL must also be named +accordingly. This will usually happen by default, so unless you're changing +settings you don't really need to worry about this. -Your project directory can be nested under subdirectories (e.g. `src/`), and you may have other projects within the same -solution. There is no restriction to the programming language used for any other projects in the same solution. +Your project directory can be nested under subdirectories (e.g. `src/`), and you +may have other projects within the same solution. There is no restriction to the +programming language used for any other projects in the same solution. ## The Internal Name -Your plugin's `AssemblyName`, generally auto-set to your `.csproj` file name, will become what's known as the plugin's -**`InternalName`**. Once set this value ***may not be changed***, so it's important to choose a name that you will be +Your plugin's `AssemblyName`, generally auto-set to your `.csproj` file name, +will become what's known as the plugin's **`InternalName`**. Once set this value +**_may not be changed_**, so it's important to choose a name that you will be happy with. -This internal name will be used for your plugin's config directory, is attached to all log entries, and is used as the -name on your plugin's DLL and D17 submissions. +This internal name will be used for your plugin's config directory, is attached +to all log entries, and is used as the name on your plugin's DLL and D17 +submissions. -You may use a different name for the plugin's display name by setting the `Name` field of your plugin manifest -accordingly. +You may use a different name for the plugin's display name by setting the `Name` +field of your plugin manifest accordingly. ## Manifest File -Your plugin DLL must be distributed alongside a **manifest file**, which contains certain key information such as your -author name, the plugin's punchline, the internal name declaration, and other miscellaneous data. See our [manifest] -section for more detailed information as to what needs to be contained within it. This data is also used to generate our -PluginMaster (repository) files which are delivered to users to populate the installer. +Your plugin DLL must be distributed alongside a **manifest file**, which +contains certain key information such as your author name, the plugin's +punchline, the internal name declaration, and other miscellaneous data. See our +\[manifest] section for more detailed information as to what needs to be +contained within it. This data is also used to generate our PluginMaster +(repository) files which are delivered to users to populate the installer. -Normally, our `DalamudPackager` helper (included in the Dalamud SDK and referenced in our `.targets` file) will -automatically generate your manifest using a template file in your project directory. This template file may be of type -`.json` or `.yml`, and must be named following your plugin's Internal Name (e.g. `MyPlugin.json`). The `DalamudPackager` -helper will automatically add critical fields such as `InternalName`, `AssemblyVersion`, `DalamudApiLevel`, and others. +Normally, our `DalamudPackager` helper (included in the Dalamud SDK and +referenced in our `.targets` file) will automatically generate your manifest +using a template file in your project directory. This template file may be of +type `.json` or `.yml`, and must be named following your plugin's Internal Name +(e.g. `MyPlugin.json`). The `DalamudPackager` helper will automatically add +critical fields such as `InternalName`, `AssemblyVersion`, `DalamudApiLevel`, +and others. -At a minimum, your template manifest for `DalamudPackager` must contain the following keys: +At a minimum, your template manifest for `DalamudPackager` must contain the +following keys: ```json { @@ -58,9 +67,11 @@ At a minimum, your template manifest for `DalamudPackager` must contain the foll ## The Plugin Entrypoint -Dalamud will scan your DLL for a class that extends `IDalamudPlugin`. This class will then be initialized, injecting -any [services] declared in the class' constructor. Your plugin may only have *one* such entrypoint. +Dalamud will scan your DLL for a class that extends `IDalamudPlugin`. This class +will then be initialized, injecting any \[services] declared in the class' +constructor. Your plugin may only have _one_ such entrypoint. -As `IDalamudPlugin` inherits from `IDisposable`, your plugin must also specify a `void Dispose()` method to clean up -after itself. Plugin developers are required to implement a fully-functional dispose cycle and, ideally, not leak any -resources. \ No newline at end of file +As `IDalamudPlugin` inherits from `IDisposable`, your plugin must also specify a +`void Dispose()` method to clean up after itself. Plugin developers are required +to implement a fully-functional dispose cycle and, ideally, not leak any +resources. diff --git a/docs/plugin-development/restrictions.md b/docs/plugin-development/restrictions.md index 689c68d..1cff3da 100644 --- a/docs/plugin-development/restrictions.md +++ b/docs/plugin-development/restrictions.md @@ -28,9 +28,9 @@ Please make sure that, as much as possible: - your plugin does not have a hard dependency on any plugin that violates the Plugin Guidelines -If you are not sure whether your plugin will be allowed, _please_ contact us -before you start work on it. We don't want to have to turn you down after -you've already done the work! +If you are not sure whether your plugin will be allowed, _please_ contact us +before you start work on it. We don't want to have to turn you down after you've +already done the work! Plugins that violate these rules will not be accepted into the Dalamud plugin repository, and you will not receive support from the Dalamud community. diff --git a/docs/versions/v10.md b/docs/versions/v10.md index 4ce3783..8d3b043 100644 --- a/docs/versions/v10.md +++ b/docs/versions/v10.md @@ -22,46 +22,88 @@ all of these changes - **.NET Version:** .NET 8.0 ## New Features + - New APIs have been added. - - `IConsole` lets you add console variables and commands to the Dalamud console(`/xllog`). These are distinct to chat commands and offer various convenience features such as completion and support for types. No string parsing needed. - - `IMarketBoard` lets you access market board data events that Dalamud already had implemented to provide Universalis with it's pricing data. This will allow users to subscribe to these events without having to hook those events themselves. + - `IConsole` lets you add console variables and commands to the Dalamud + console(`/xllog`). These are distinct to chat commands and offer various + convenience features such as completion and support for types. No string + parsing needed. + - `IMarketBoard` lets you access market board data events that Dalamud already + had implemented to provide Universalis with it's pricing data. This will + allow users to subscribe to these events without having to hook those events + themselves. ## Major Changes -- There has been refactoring in relation to what interfaces/classes Dalamud provides. Generally speaking Dalamud will now provide interfaces where possible. This should make it easier for plugins to unit test/mock as required. - - The majority of public facing classes provided by dalamud services to plugins have been interfaced. - - `DalamudPluginInterface` is now `IDalamudPluginInterface`, you must request a `IDalamudPluginInterface` in your plugin's constructor. +- There has been refactoring in relation to what interfaces/classes Dalamud + provides. Generally speaking Dalamud will now provide interfaces where + possible. This should make it easier for plugins to unit test/mock as + required. + + - The majority of public facing classes provided by dalamud services to + plugins have been interfaced. + - `DalamudPluginInterface` is now `IDalamudPluginInterface`, you must request + a `IDalamudPluginInterface` in your plugin's constructor. - `UiBuilder` is now `IUiBuilder` - - For a full list please see [Class/Interface Changes](#classinterface-changes) - + - For a full list please see + [Class/Interface Changes](#classinterface-changes) + - `ITextureProvider` has been reworked to be more performant and easier to use. - - All of the functions inside now return a `ISharedImmediateTexture`, instead of a texture wrap. This represents an instance of a texture that may or may not be loaded yet. All textures are loaded asynchronously to avoid making the game hitch. - - You don't need to maintain your own "texture cache" anymore. Caching `IDalamudTextureWrap` is now **explicitly discouraged**, as it sidesteps all of the asynchronous loading and performance optimizations in the new texture provider implementation. You should try to remove your caches and use `ISharedImmediateTexture.GetWrapOrEmpty()`, `ISharedImmediateTexture.GetWrapOrDefault()` or `ISharedImmediateTexture.TryGetWrap()`. The former `GetWrapOrEmpty()` function will return a transparent 4x4 texture if it hasn't loaded yet, allowing easy upgrades. - - `ISharedImmediateTexture.RentAsync()` can be used to obtain a `IDalamudTextureWrap` that stays valid, but it's a **legacy option** and should only be used if you need to acquire a texture **off the main thread**, for example, inside a task. You should always prefer to use the other functions if you are planning to use the texture to render with ImGui. - - Please refer to the updated documentation of `ITextureProvider` and `ISharedImmediateTexture` for more guidance. -- `ITextureReadbackProvider` has been added to allow accessing raw RGBA data of textures as streams, or saving them to a file. + - All of the functions inside now return a `ISharedImmediateTexture`, instead + of a texture wrap. This represents an instance of a texture that may or may + not be loaded yet. All textures are loaded asynchronously to avoid making + the game hitch. + - You don't need to maintain your own "texture cache" anymore. Caching + `IDalamudTextureWrap` is now **explicitly discouraged**, as it sidesteps all + of the asynchronous loading and performance optimizations in the new texture + provider implementation. You should try to remove your caches and use + `ISharedImmediateTexture.GetWrapOrEmpty()`, + `ISharedImmediateTexture.GetWrapOrDefault()` or + `ISharedImmediateTexture.TryGetWrap()`. The former `GetWrapOrEmpty()` + function will return a transparent 4x4 texture if it hasn't loaded yet, + allowing easy upgrades. + - `ISharedImmediateTexture.RentAsync()` can be used to obtain a + `IDalamudTextureWrap` that stays valid, but it's a **legacy option** and + should only be used if you need to acquire a texture **off the main + thread**, for example, inside a task. You should always prefer to use the + other functions if you are planning to use the texture to render with ImGui. + - Please refer to the updated documentation of `ITextureProvider` and + `ISharedImmediateTexture` for more guidance. + +- `ITextureReadbackProvider` has been added to allow accessing raw RGBA data of + textures as streams, or saving them to a file. ## Minor Changes + - Some `IBattleChara` properties were renamed. + - In `BattleChara`, `TotalCastTime` was renamed to `BaseCastTime`. - In `BattleChara`, `AdjustedTotalCastTime` was renamed to `TotalCastTime`. - `Dalamud.ClientLanguage` was moved to `Dalamud.Game.ClientLanguage`. + - The `ToLumina()` extension method was moved to `Dalamud.Utility`. - -- `IDalamudPluginInstaller.OpenPluginInstaller()` was removed. Please use `OpenPluginInstallerTo()` instead. -- The type returned by `IDalamudPluginInterface.InstalledPlugins` has been changed to `IExposedPlugin` +- `IDalamudPluginInstaller.OpenPluginInstaller()` was removed. Please use + `OpenPluginInstallerTo()` instead. + +- The type returned by `IDalamudPluginInterface.InstalledPlugins` has been + changed to `IExposedPlugin` + - Functions to open the main and config UIs have been added. - Some changes were made to unify texture wraps. - - The public `DalamudTextureWrap` class has been removed. Please use `IDalamudTextureWrap` instead. - - `IDalamudTextureWrap` has been moved out of an internal namespace into `Dalamud.Interface.Textures.TextureWraps` + + - The public `DalamudTextureWrap` class has been removed. Please use + `IDalamudTextureWrap` instead. + - `IDalamudTextureWrap` has been moved out of an internal namespace into + `Dalamud.Interface.Textures.TextureWraps` - `ImRaii` style functions will now throw if an invalid type is specified. -- The `RequiredVersion` attribute for injected services has been removed. You don't need to replace it with anything. +- The `RequiredVersion` attribute for injected services has been removed. You + don't need to replace it with anything. ## Errata @@ -77,8 +119,9 @@ this patch cycle: These are relevant changes made to FFXIVClientStructs, listed here for reference. We want to thank aers, Pohky, WildWolf and the other FFXIVClientStructs contributors for their work. - + ## Class/Interface Changes + - DalamudPluginInterface -> IDalamudPluginInterface - UiBuilder -> IUiBuilder - AetheryteEntry -> IAetheryteEntry @@ -102,4 +145,5 @@ FFXIVClientStructs contributors for their work. - DtrBarEntry -> IDtrBarEntry - PartyFinderListing -> IPartyFinderListing - PartyFinderListingEventArgs -> IPartyFinderListingEventArgs -- TitleScreenMenuEntry -> ITitleScreenMenuEntry and IReadOnlyTitleScreenMenuEntry +- TitleScreenMenuEntry -> ITitleScreenMenuEntry and + IReadOnlyTitleScreenMenuEntry