Dalamud

Integrating Dalamud

If you’re developing your own launcher, you might be interested in integrating Dalamud support. Here’s a detailed walk-through of setting up a proper Dalamud environment.

Grabbing .NET Runtime #

You’ll need a .NET environment to actually launch Dalamud, since it’s based it uses .NET. It won’t try to use your system .NET, and will require to put it into a separate directory.

In order to determine which .NET runtime you need, first check the Dalamud Distribution server using the following URL:

https://kamori.goats.dev/Dalamud/Release/VersionInfo

This will return a JSON containing keys for runtimeVersion. This is the required .NET runtime, which then can be fetched directly from Microsoft:

https://dotnetcli.azureedge.net/dotnet/Runtime/%1/dotnet-runtime-%1-win-x64.zip

https://dotnetcli.azureedge.net/dotnet/WindowsDesktop/%1/windowsdesktop-runtime-%1-win-x64.zip

You can then extract both zip files into some directory, henceforth called $RUNTIME_DIR.

Grabbing Dalamud #

Now you can grab Dalamud from Dalamud Distribution (https://kamori.goats.dev/Dalamud/Release/VersionInfo) where the URL is downloadUrl.

You can then extract this zip file, and the resulting directory will be referred to as $DALAMUD_DIR.

Note: You can find out the version of Dalamud you have installed by reading the dependencies file, located under $DALAMUD_DIR/Dalamud.deps.json.

Grabbing Dalamud assets #

These are not grabbed by Dalamud (for some reason) and instead you must download these yourself. These include fonts, icons and other things which are required for regular operation.

You can find the asset manifest at:

https://kamori.goats.dev/Dalamud/Asset/Meta

This is simply a long JSON describing where to find the assets, the current version and where to put them. It’s recommended to use the packageUrl to download all of the assets at once. The directory you put assets in will be called $DALAMUD_ASSET_DIR.

Launching Dalamud #

Now with all of your ugly ducklings in a row, you can begin launching Dalamud! First, please make sure these environment variables are set on the game process and all relevant processes and children. Please double check these, as Dalamud may silently fail without them.

  1. Launch $DALAMUD_DIR/Dalamud.Injector.exe.
    • You may be able to launch the injector without any additional configuration, but it’s recommended to set these.
    • Arguments:
      1. The arguments for the game.
      2. Base64-encoding of a JSON dictionary which may contain these options:
        • WorkingDirectory - overrides the working directory for Dalamud
        • ConfigurationPath - the file path of dalamudConfig.json
        • PluginDirectory - the directory for the installedPlugins folder
        • AssetDirectory - should point to $DALAMUD_ASSET_DIR.
        • DefaultPluginDirectory - the default directory for the devPlugin folder.
        • DelayinitializeMs - how much Dalamud should wait before injection
        • GameVersion - the (base) game version string
        • Language - language code of the game
        • OptOutMbCollection - whether or not to opt out from anonymous marketboard statistics collection
  2. If successful, the game should freeze for a few momements and Dalamud will successfully inject!

Creating your own Dalamud repository

Note

This is for creating a 3rd party repository, which is probably not what you want. Almost all plugins should be submitted to the main repository, see https://dalamud.dev/plugin-development/plugin-submission.

Creating a 3rd party Dalamud repository is easy, because it’s stateless and can be on any publicly accessible static location on the web.

Plugin Manifests #

First you need to craft a folder somewhere (preferably with version control like Git) and start putting plugin manifests inside. These manifest.toml contain vital information like where we check the plugin source code from and more. In your manifest folder, create a stable subfolder. And then create more folders as needed inside, which correspond to the plugin name.

<manifest dir> /
  PluginA /
    manifest.toml
  PluginB /
    manifest.toml

The manifest.toml is in this format:

[plugin]
repository = "<git repository>"
commit = "<git hash>"
owners = [ "<your name>" ]
changelog = '''
Your changelog in here.
'''

All plugins require an icon.png, which you need to provide inside of an images folder:

<manifest dir> /
  PluginA /
    images /
      icon.png
    manifest.toml
  PluginB /
    images /
      icon.png
    manifest.toml

Now your manifest folder is ready to go, we’ll move onto setting up the build system next.

Setting up and using Plogon #

Plogon is the preferred method of building plugins, and it’s used for the main Dalamud repository. It uses Docker to standardize the building process and takes care of repository state for you. Follow their README and continue this guide once you have a folder with a State.toml and your built plugins.

Creating the repo JSON #

Now that we have our built plugin DLLs, our new repository is almost usable inside of Dalamud. But Dalamud does not consume the State.toml directly, the plugin manifests need to be concentrated into a single JSON file. XLWebServices does this, but I built a smaller tool just for this purpose called DalamudRepoTool. Install it via Cargo:

cargo install --git https://github.com/redstrate/DalamudRepoTool.git

And then run it on your repository:

DalamudRepoTool --download-host <URL to your hosted repository without the stable channel path> --repo-path <your repository path where the State.toml is>

When it’s done, it will create a repo.json where the State.toml was. Your repository is complete and can now be used in Dalamud!

Building Dalamud plugins on Linux

It’s trivial to develop Dalamud plguins on Linux since they moved to .NET Core!

The .NET SDK #

You need the .NET SDK of course, which is already in many package managers:

Currently Dalamud requires .NET 9.0 as of API 12.

devPlugin path #

Remember that when entering the dev plugin path in the Dalamud settings, to prepend it with Z: and take care of your slashes so they make sense under Wine.