Skip to main content

​
Prerequisites

Before you start developing Dalamud plugins, ensure you have the following installed on your Windows development machine:
1

.NET SDK

Download and install the .NET 8.0 SDK (or later) from Microsoft’s official site.
# Verify installation
dotnet --version
You should see output like 8.0.100 or higher.
Dalamud plugins target .NET 8.0 by default. Make sure you have the SDK, not just the runtime.
2

IDE or Text Editor

Choose a development environment:

Visual Studio 2022

Full-featured IDE with excellent C# support (Community edition is free)

JetBrains Rider

Premium C# IDE with advanced refactoring tools

Visual Studio Code

Lightweight editor with C# extension support
For Visual Studio, install the .NET desktop development workload during setup.
3

Git (Optional but Recommended)

Install Git for Windows to clone templates and manage your plugin source code.
git --version
4

XIVLauncher & Dalamud

Install XIVLauncher which includes Dalamud for testing your plugins.
You need a running FFXIV installation with Dalamud to test plugins. XIVLauncher handles this automatically.

​
Project Setup

The easiest way to start is by cloning the official Sample Plugin template:
1

Clone the Template

git clone https://github.com/goatcorp/SamplePlugin.git MyAwesomePlugin
cd MyAwesomePlugin
2

Rename and Configure

Open the solution in your IDE and rename the project:
  1. Rename the .csproj file
  2. Update the Name and InternalName in the plugin manifest JSON
  3. Update the namespace in source files
  4. Modify the plugin class name if desired
3

Restore Dependencies

dotnet restore
This downloads the Dalamud API package and other dependencies.

​
Option 2: Manual Project Creation

If you prefer to set up from scratch:
1

Create a Class Library Project

dotnet new classlib -n MyPlugin -f net8.0-windows
cd MyPlugin
2

Add the Dalamud Package

Add the Dalamud API NuGet package to your project:
dotnet add package DalamudPackager
The DalamudPackager includes the Dalamud API and build tools needed for plugin development.
3

Configure the Project File

Edit your .csproj file to include these properties:
MyPlugin.csproj
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0-windows</TargetFramework>
    <LangVersion>latest</LangVersion>
    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
    <ProduceReferenceAssembly>false</ProduceReferenceAssembly>
    <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
    <OutputPath>bin\$(Configuration)\</OutputPath>
    <DalamudLibPath>$(AppData)\XIVLauncher\addon\Hooks\dev\</DalamudLibPath>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="DalamudPackager" Version="2.1.13" />
  </ItemGroup>
</Project>
4

Create the Plugin Manifest

Create a JSON manifest file (e.g., MyPlugin.json) in your project root:
MyPlugin.json
{
  "Author": "Your Name",
  "Name": "My Awesome Plugin",
  "Punchline": "A short description of your plugin",
  "Description": "A longer description that explains what your plugin does and why it's useful.",
  "InternalName": "MyAwesomePlugin",
  "ApplicableVersion": "any",
  "Tags": ["utility", "ui"]
}
The InternalName must be unique and is used to identify your plugin in the Dalamud ecosystem.

​
Development Environment Configuration

​
DalamudLibPath Setup

For your IDE to find Dalamud assemblies, you need to set the DalamudLibPath correctly:
The default path is:
%AppData%\XIVLauncher\addon\Hooks\dev\
This is typically:
C:\Users\YourName\AppData\Roaming\XIVLauncher\addon\Hooks\dev\
If your IDE shows errors for Dalamud types, verify that DalamudLibPath points to a valid directory containing Dalamud.dll.

​
Enable DevPlugin Loading

To test your plugin during development:
1

Open Dalamud Settings

In-game, type /xlsettings to open the Dalamud settings window.
2

Enable DevPlugins

Go to the Experimental tab and check Enable DevPlugin loading.
3

Set DevPlugin Path

In the DevPlugins section, click Add and browse to your plugin’s build output directory:
C:\Path\To\Your\Plugin\bin\Debug\
4

Load Your Plugin

Click Load next to your plugin in the DevPlugins list. It should now appear in /xlplugins.

​
Build and Test

​
Building Your Plugin

dotnet build
The output DLL will be in bin\Debug\ or bin\Release\ depending on your configuration.

​
Testing In-Game

1

Launch FFXIV via XIVLauncher

Start the game through XIVLauncher (not the official launcher).
2

Open Plugin Installer

Press Escape and click the Plugin Installer button, or type /xlplugins.
3

View DevPlugins Tab

Navigate to the Dev Plugins tab to see your plugin listed.
4

Load and Test

Click Load to initialize your plugin. Use /xldev to access the developer menu for debugging.

​
Hot Reload During Development

For faster iteration, you can unload and reload your plugin without restarting the game:
  1. Click Unload in the DevPlugins tab
  2. Rebuild your plugin (dotnet build)
  3. Click Load again
This works as long as you properly dispose of all resources in your plugin’s Dispose() method.

​
Debugging

​
Attach Debugger

You can attach your IDE’s debugger to the game process:
  1. Go to Debug → Attach to Process
  2. Find ffxiv_dx11.exe in the process list
  3. Click Attach
  4. Set breakpoints in your plugin code
Debugging works best when your plugin is built in Debug configuration.

​
Logging

Use the IPluginLog service for logging: 
public class MyPlugin : IDalamudPlugin
{
    private readonly IPluginLog log;
    
    public MyPlugin(IPluginLog pluginLog)
    {
        this.log = pluginLog;
        this.log.Info("Plugin initialized!");
    }
}
View logs in-game using /xllog or check the log file at: 
%AppData%\XIVLauncher\dalamud.log

​
Common Issues

Error: Cannot find Dalamud assembliesSolution: Verify that XIVLauncher is installed and has run at least once. The DalamudLibPath directory is created when Dalamud loads for the first time.
Error: Plugin appears but won’t loadSolution:
  • Check that your plugin class implements IDalamudPlugin
  • Ensure the manifest JSON has a unique InternalName
  • Verify that all services are injected correctly in the constructor
  • Check /xllog for specific error messages
Error: Game data types or services are null at runtimeSolution: Some services may not be available until the player is logged in. Always check for null before using game state services.

​
Next Steps

Now that your environment is set up, you’re ready to build your first plugin!

Create Your First Plugin

Follow the quickstart guide to build a working plugin in minutes
For a deeper understanding of plugin architecture, check out:

Plugin Lifecycle

Learn how plugins are initialized and disposed

Dependency Injection

Understand service injection patterns

Build docs developers (and LLMs) love

Get started for freeTalk to us