NOTE: This is incomplete, and is planned to be adopted by goatcorp and finished eventually. Only this page is half-finished (no images). A link to the finished book will be linked here when that happens.
This minibook provides a brief explanation of how to create Dalamud plugins.
- Visual Studio 2019 with the .NET Framework 4.7.2 targetting pack
Also see SamplePlugin and other existing plugins for real examples.
There are currently two main methods for creating a project:
Open Visual Studio and create a new project. Select Class Library (.NET Standard) from the list. Set the solution name to your plugin's name.
All C# projects are structured according to their .csproj files. .NET Framework projects have an old .csproj
format that looks awful and is harder to edit than the "SDK-style" equivalent that .NET Standard projects start
with, so we're going to create a .NET Framework project from a .NET Standard project.
Open your .csproj by double-clicking on it.
Set the TargetFramework tag to net472. While we're here, add the following line inside of that PropertyGroup:
<LangVersion>9.0</LangVersion>[!Screenshot assets/open_csproj.png]
Setting LangVersion allows you to take advantage of new features in C# that would normally be disabled in .NET
Framework projects.
Before we begin programming, we also need to add project references to Dalamud, so that we have access to its types.
Right-click on "Dependencies" and click "Add Assembly reference...". Click Browse and navigate to
%AppData%/XIVLauncher/addon/Hooks. Add the following files to your project:
Dalamud.dllImGui.NET.dllImGuiScene.dllLumina.dllLumina.Generated.dllNewtonsoft.Json.dll
Now we need to set up our code files. Right-click on the precreated Class1.cs and rename it to your own plugin's name.
Then confirm that you would like to rename every instance of Class1 in your solution to your plugin's name.
Now we can program.
All Dalamud plugins implement the IDalamudPlugin interface. Do the same for yours:
[!Screenshot assets/idalamudplugin.png]
This should redline, noting that you have not actually implemented the interface. Hover over IDalamudPlugin until
the lightbulb appears, and click on it. Select "Implement interface" to generate stubs for the required class
members. Let's go over them one-by-one.
This is the property that your plugin's name is read from. It does not need to match your exact plugin name, but there's generally no reason not to set it as such. Whatever you put here will show up in the chat log when your plugin loads.
[!Screenshot assets/name_property.png]
Dispose() is generated above this, but it makes more sense to explain Initialize() first. Initialize() runs
immediately when your plugin loads. Use this like a constructor. You'll want to save the plugin interface that
is passed in so you can do useful things with it later.
[!Screenshot assets/initialize.png]
Dispose() is run when your plugin is unloaded. If you add any event hooks (discussed later) in your initializer,
you'll want to remove them here in order to avoid interfering with other plugins. If any resources you are using
have not been disposed yet (such as the plugin interface), you'll also dispose those here by calling their
respective Dispose() methods.
[!Screenshot assets/dispose.png]
We now have the bare-minimum of a Dalamud plugin. If we build this now and load it into Dalamud (using the
%AppData%/XIVLauncher/devPlugins folder), its name should be printed in the chat log when we restart our game.
We probably want to do something interesting with our plugin, though. Let's see how to do that in the
next section.
Navigate to the DalamudPluginProject repository
and either create your own repository from it, clone it down, and open the solution file, or download the zip
of the latest release and put it in your
Documents\Visual Studio 2019\Templates\ProjectTemplates folder and create a project from it in Visual Studio.
Make sure to change the values in Plugin.json to suit your own project, and rename the code files to include
your plugin name if you like.
Let's move on.