Skip to content

Commit

Permalink
lint.
Browse files Browse the repository at this point in the history
  • Loading branch information
KazWolfe committed Jul 30, 2024
1 parent d5671b8 commit 2687e8d
Show file tree
Hide file tree
Showing 4 changed files with 114 additions and 59 deletions.
4 changes: 2 additions & 2 deletions docs/plugin-development/plugin-submission.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
79 changes: 45 additions & 34 deletions docs/plugin-development/project-layout.md
Original file line number Diff line number Diff line change
@@ -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
{
Expand All @@ -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.
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.
6 changes: 3 additions & 3 deletions docs/plugin-development/restrictions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
84 changes: 64 additions & 20 deletions docs/versions/v10.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand All @@ -102,4 +145,5 @@ FFXIVClientStructs contributors for their work.
- DtrBarEntry -> IDtrBarEntry
- PartyFinderListing -> IPartyFinderListing
- PartyFinderListingEventArgs -> IPartyFinderListingEventArgs
- TitleScreenMenuEntry -> ITitleScreenMenuEntry and IReadOnlyTitleScreenMenuEntry
- TitleScreenMenuEntry -> ITitleScreenMenuEntry and
IReadOnlyTitleScreenMenuEntry

0 comments on commit 2687e8d

Please sign in to comment.