Debugging - Dalamud

Overview

Debugging Dalamud plugins requires attaching to the game process. This guide covers debugging techniques, common issues, and best practices.

Prerequisites:

Visual Studio 2022, JetBrains Rider, or VS Code with C# debugger
Your plugin built in Debug configuration
FFXIV running with Dalamud

Attaching the Debugger

Visual Studio

Build in Debug Mode

Ensure your project is built in Debug configuration:

dotnet build -c Debug

Or select Debug from the configuration dropdown in Visual Studio.

Start the Game

Launch Final Fantasy XIV through XIVLauncher with Dalamud enabled.

Attach to Process

In Visual Studio: Debug → Attach to Process (or Ctrl+Alt+P)
In the process list, find ffxiv_dx11.exe
Click Attach

Alternatively, use the search box at the top to quickly filter for “ffxiv”.

Set Breakpoints

Click in the left margin of your code editor to set breakpoints on the lines you want to debug.When the code executes, Visual Studio will pause execution and let you inspect variables.

JetBrains Rider

Configure Attach Settings

Run → Edit Configurations
Click + → Attach to Process
Name it “Attach to FFXIV”
Set the filter to “ffxiv_dx11.exe”

Attach

Build your project in Debug mode
Start FFXIV with Dalamud
In Rider: Run → Attach to Process → Select your configuration
Set breakpoints and debug

Visual Studio Code

Create a launch.json configuration:

.vscode/launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to FFXIV",
      "type": "coreclr",
      "request": "attach",
      "processName": "ffxiv_dx11.exe"
    }
  ]
}

Then:

Press F5 or Run → Start Debugging
Select “Attach to FFXIV”

Debug Configuration

Optimize your .csproj for debugging:

.csproj

<PropertyGroup Condition="'$(Configuration)' == 'Debug'">
  <DebugSymbols>true</DebugSymbols>
  <DebugType>full</DebugType>
  <Optimize>false</Optimize>
  <DefineConstants>DEBUG;TRACE</DefineConstants>
</PropertyGroup>

This ensures:

Full debug symbols are generated
Optimizations are disabled (easier to debug)
DEBUG constant is defined

Debugging Techniques

Conditional Breakpoints

Break only when specific conditions are met:

Right-click a breakpoint
Select Conditions
Add a condition, e.g., userId == 12345

The debugger will only break when the condition is true.

Immediate Window

Execute code while debugging:

While paused at a breakpoint, open Debug → Windows → Immediate (or Ctrl+Alt+I)
Type expressions and press Enter:

player.Name
chatGui.Print("Debug message")
config.Enabled = true

Watch Window

Monitor variables continuously:

Open Debug → Windows → Watch → Watch 1
Add expressions to watch
Values update as you step through code

Call Stack

Inspect the call stack:

Open Debug → Windows → Call Stack (or Ctrl+Alt+C)
See the sequence of method calls that led to the current point
Click on frames to navigate

Tracepoints

Log messages without stopping execution:

Right-click in the margin where you’d set a breakpoint
Select Tracepoint
Enter a message like: Player HP: {player.CurrentHp}
Messages appear in the Output window

Logging

Use Dalamud’s logging system for runtime diagnostics:

using Dalamud.Plugin.Services;

public class Plugin : IDalamudPlugin
{
    private readonly IPluginLog log;

    public Plugin(IPluginLog log)
    {
        this.log = log;
        
        // Different log levels
        log.Verbose("Detailed trace information");
        log.Debug("Debug information");
        log.Information("General information");
        log.Warning("Warning message");
        log.Error("Error message");
        log.Fatal("Critical error");
    }
}

View Logs

Logs appear in:

Dalamud log - /xllog in-game
Log file - %AppData%\XIVLauncher\dalamud.log
Output window - In your IDE when debugging

Structured Logging

Use structured parameters:

log.Information("Player {PlayerName} used action {ActionId}", 
    player.Name, actionId);

This is better than string interpolation for parsing and analysis.

Exception Handling

Try-Catch Blocks

Always wrap risky operations:

try
{
    var data = LoadDataFromFile();
    ProcessData(data);
}
catch (FileNotFoundException ex)
{
    log.Error(ex, "Could not find data file");
    chatGui.PrintError("Plugin data file is missing!");
}
catch (Exception ex)
{
    log.Error(ex, "Unexpected error processing data");
}

First-Chance Exceptions

Catch all exceptions in Visual Studio:

Debug → Windows → Exception Settings (or Ctrl+Alt+E)
Check Common Language Runtime Exceptions
Debugger will break on all exceptions, even caught ones

The game throws many internal exceptions. You may want to uncheck this after finding your issue.

Exception Filter

Break only on specific exceptions:

try
{
    DangerousOperation();
}
catch (SpecificException ex) when (ex.Code == 404)
{
    log.Warning("Expected error: {Message}", ex.Message);
}

Set exception breakpoint conditions for only certain exception types or messages.

Common Issues

Breakpoints Not Hitting

Causes:

Plugin not loaded or outdated version
Code not matching the compiled assembly
Debugging symbols not loaded

Solutions:

Verify plugin is loaded: /xlplugins
Rebuild in Debug mode
Ensure breakpoint is on an executable line
Check Debug → Windows → Modules to see if your DLL is loaded
Right-click the DLL → Load Symbols

Game Crashes When Debugging

Causes:

Unhandled exception in plugin code
Invalid memory access
Deadlock or infinite loop

Solutions:

Enable first-chance exceptions to catch the error
Add try-catch blocks around suspicious code
Check for null references
Validate memory addresses before dereferencing
Review recent changes to plugin code

Variables Show Optimized Away

Cause: Building in Release mode with optimizations enabled.Solution: Build in Debug mode:

dotnet build -c Debug

Cannot Edit Code While Debugging

Limitation: Edit and Continue is not supported for plugins since they run in a separate AssemblyLoadContext.Workaround:

Stop debugging
Make changes
Build
Hot reload your plugin: /xldev → Reload Plugin
Re-attach debugger

Performance Issues While Debugging

Causes:

Too many breakpoints
Watching complex expressions
First-chance exceptions enabled

Solutions:

Remove unnecessary breakpoints
Simplify watch expressions
Disable first-chance exceptions
Use tracepoints instead of breakpoints for logging

Hot Reload

Dev plugins support hot reloading without restarting the game:

Make Code Changes

Edit your plugin code as needed.

Build

Build your project:

dotnet build -c Debug

Ensure the output is copied to your devPlugins folder.

Reload in Game

Type /xldev in-game
Go to the Plugin Dev tab
Find your plugin
Click Reload

Your plugin will unload and reload with the new code.

Re-attach Debugger (Optional)

If you want to debug the reloaded plugin:

Detach the debugger (Debug → Detach All)
Re-attach to ffxiv_dx11.exe
Set breakpoints

Set up a post-build event to automatically copy files:

<Target Name="PostBuild" AfterTargets="PostBuildEvent">
  <Exec Command="xcopy /Y /I /E &quot;$(TargetDir)*&quot; &quot;$(AppData)\XIVLauncher\devPlugins\$(ProjectName)\&quot;" />
</Target>

Memory Debugging

When working with memory and pointers:

Memory Window

View raw memory:

Debug → Windows → Memory → Memory 1
Enter an address expression
View bytes, words, or other formats

Pointer Validation

Always validate pointers:

unsafe
{
    var ptr = GetSomePointer();
    
    if (ptr == IntPtr.Zero)
    {
        log.Error("Null pointer");
        return;
    }
    
    try
    {
        var value = *(int*)ptr;
    }
    catch (AccessViolationException ex)
    {
        log.Error(ex, "Invalid memory access at {Address:X}", ptr);
    }
}

Using SigScanner

Debug signature scanning:

var sigScanner = pluginInterface.GetService<ISigScanner>();

try
{
    var address = sigScanner.ScanText("E8 ?? ?? ?? ?? 48 8B 5C 24");
    log.Debug("Found signature at {Address:X}", address);
}
catch (KeyNotFoundException)
{
    log.Error("Signature not found - may be outdated");
}

Performance Profiling

Stopwatch Timing

Measure execution time:

using System.Diagnostics;

var sw = Stopwatch.StartNew();
ExpensiveOperation();
sw.Stop();

log.Debug("Operation took {Elapsed}ms", sw.ElapsedMilliseconds);

if (sw.ElapsedMilliseconds > 100)
{
    log.Warning("Operation is too slow!");
}

Frame Time Monitoring

Monitor UI draw performance:

private Stopwatch drawTimer = new();

private void Draw()
{
    drawTimer.Restart();
    
    // Draw UI
    DrawWindows();
    
    drawTimer.Stop();
    
    if (drawTimer.ElapsedMilliseconds > 16) // More than one frame at 60fps
    {
        log.Warning("Draw took {Elapsed}ms - too slow!", drawTimer.ElapsedMilliseconds);
    }
}

Draw methods are called every frame (60+ times per second). Keep them fast!

Testing Strategies

Unit Testing

While full unit testing is challenging, you can test pure functions:

Tests/UtilityTests.cs

using Xunit;

public class UtilityTests
{
    [Fact]
    public void ParseItemId_ValidInput_ReturnsId()
    {
        var result = ItemParser.ParseItemId("[Item:12345]");
        Assert.Equal(12345, result);
    }
    
    [Fact]
    public void ParseItemId_InvalidInput_ReturnsNull()
    {
        var result = ItemParser.ParseItemId("Invalid");
        Assert.Null(result);
    }
}

Integration Testing

Test in-game with controlled scenarios:

private void TestFeature()
{
    try
    {
        log.Information("Starting test: Feature X");
        
        // Setup
        var initialState = GetState();
        
        // Execute
        PerformAction();
        
        // Verify
        var finalState = GetState();
        if (finalState != expectedState)
        {
            log.Error("Test failed: Expected {Expected}, got {Actual}",
                expectedState, finalState);
        }
        else
        {
            log.Information("Test passed");
        }
    }
    finally
    {
        // Cleanup
        ResetState();
    }
}

Debug Commands

Add debug commands for testing:

if (pluginInterface.IsDev)
{
    commandManager.AddHandler("/pdebug", new CommandInfo(OnDebugCommand)
    {
        HelpMessage = "Debug commands",
        ShowInHelp = false
    });
}

private void OnDebugCommand(string command, string args)
{
    var parts = args.Split(' ');
    
    switch (parts[0])
    {
        case "test":
            RunTests();
            break;
        case "dump":
            DumpState();
            break;
        case "reset":
            ResetState();
            break;
        default:
            chatGui.Print("Unknown debug command");
            break;
    }
}

Best Practices

Log Liberally

Add logging statements throughout your code. You can filter by log level later.

Validate Inputs

Always validate data from external sources (game memory, files, IPC) before using it.

Use Assertions

Use Debug.Assert for invariants that should never be false:

Debug.Assert(player != null, "Player should be loaded");

Test Edge Cases

Test your plugin with unusual conditions: level 1 character, empty inventory, etc.

Remote Debugging

For debugging on another machine:

Install Remote Debugging Tools on the game machine
Start the remote debugger: msvsmon.exe
In Visual Studio: Debug → Attach to Process
Change Connection type to Remote (no authentication)
Enter the remote machine name
Select ffxiv_dx11.exe

Remote debugging requires both machines to be on the same network and have appropriate firewall rules.

Next Steps

Troubleshooting

Common issues and solutions

Testing Guide

Learn about testing strategies

Game Integration

Work with game state and data

Advanced Topics

Explore hooking, memory, and signatures

Get Started

Core Concepts

Plugin Development

UI & ImGui

Game Integration

IPC & Shared Data

Advanced Topics

Guides

​Overview

​Attaching the Debugger

​Visual Studio

​JetBrains Rider

​Visual Studio Code

​Debug Configuration

​Debugging Techniques

​Conditional Breakpoints

​Immediate Window

​Watch Window

​Call Stack

​Tracepoints

​Logging

​View Logs

​Structured Logging

​Exception Handling

​Try-Catch Blocks

​First-Chance Exceptions

​Exception Filter

​Common Issues

​Hot Reload

​Memory Debugging

​Memory Window

​Pointer Validation

​Using SigScanner

​Performance Profiling

​Stopwatch Timing

​Frame Time Monitoring

​Testing Strategies

​Unit Testing

​Integration Testing

​Debug Commands

​Best Practices

Log Liberally

Validate Inputs

Use Assertions

Test Edge Cases

​Remote Debugging

​Next Steps

Troubleshooting

Testing Guide

Game Integration

Advanced Topics

Build docs developers (and LLMs) love

Overview

Attaching the Debugger

Visual Studio

JetBrains Rider

Visual Studio Code

Debug Configuration

Debugging Techniques

Conditional Breakpoints

Immediate Window

Watch Window

Call Stack

Tracepoints

Logging

View Logs

Structured Logging

Exception Handling

Try-Catch Blocks

First-Chance Exceptions

Exception Filter

Common Issues

Hot Reload

Memory Debugging

Memory Window

Pointer Validation

Using SigScanner

Performance Profiling

Stopwatch Timing

Frame Time Monitoring

Testing Strategies

Unit Testing

Integration Testing

Debug Commands

Best Practices

Remote Debugging

Next Steps