Dalamud Plugin Template

A starting point for FFXIV/Dalamud plugins on the Hellion Forge.

Distilled from the HellionChat plugin patterns: csproj layout, configuration handling, window scaffolding, custom-repo manifest, Forge-Auto-Announce workflow, and the version-bump checklist.

How to use this template

Click "Use this template" at the top of the repository page on the Forge.
Pick a name like MyPlugin and clone your new repo locally.

Find-and-replace PluginNameTemplate everywhere with your plugin's name (case-sensitive).

git ls-files | xargs sed -i 's/PluginNameTemplate/MyPlugin/g'
git mv PluginNameTemplate.csproj MyPlugin.csproj
git mv PluginNameTemplate.yaml MyPlugin.yaml

Replace images/icon.png with your plugin icon (512x512 PNG, transparent background).
Update repo.json with your real DownloadLinkInstall URLs once your CI publishes releases.
Implement your plugin in src/Plugin.cs and friends.

After the rename, this README should be replaced with your plugin's actual README — the template-usage notes don't belong in your shipped plugin.

Project structure

.
├── .editorconfig                  Code style
├── .gitea/
│   ├── ISSUE_TEMPLATE/             Standard issue forms
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── workflows/
│       ├── ci.yml                  Build verification on push/PR
│       └── forge-auto-announce.yml Discord announcement on tag
├── docs/CHANGELOG.md               Long-form changelog (slim main copy)
├── images/icon.png                 Plugin icon (replace before shipping)
├── src/
│   ├── Plugin.cs                   IDalamudPlugin entry point
│   ├── PluginConfiguration.cs      IPluginConfiguration
│   └── Windows/
│       └── ConfigWindow.cs         Skeleton config window
├── PluginNameTemplate.csproj       Dalamud-SDK csproj
├── PluginNameTemplate.yaml         Dalamud manifest
├── repo.json                       Custom-repo manifest for testers
├── CHANGELOG.md                    Slim changelog (latest 2-4 versions)
├── CODEOWNERS                      Default reviewer
├── LICENSE                         MIT
└── README.md                       This file (replace before shipping)

Build

dotnet restore
dotnet build -c Release

DalamudPackager produces the .zip artifact under bin/Release/<PluginName>/latest.zip.

Note: Don't override the default DalamudPackager.targets from your csproj — it'll silently strip the icon and ImageUrls from your manifest. If you need custom packaging, do it via csproj properties only.

Versioning

Synchronized version fields (bump all at once):

<PluginName>.csproj → AssemblyVersion
<PluginName>.yaml → assembly_version + changelog
repo.json → AssemblyVersion, TestingAssemblyVersion, all 3 DownloadLink* URLs, Description, Changelog
CHANGELOG.md (slim) and docs/CHANGELOG.md (full) — keep the latest 2-4 versions in the slim copy
.gitea/forge-posts/v<X.Y.Z>.md — Discord announcement payload

Sanity-check before tagging:

grep -rn "<old-version>" . | grep -v -E '(bin|obj|node_modules|.git/)'

The Forge-Auto-Announce workflow reads from the tagged tree, not main. If a fix-commit lands after the tag, force-push the tag.

Testing

Service classes coupled to Dalamud (IPluginInterface, IDataManager, etc.) cannot be instantiated directly in xUnit because the Dalamud assembly isn't on the test AppDomain. Patterns that work:

Pure helpers — extract logic into Dalamud-free classes, test those directly
Constructor injection — pass utility dependencies in, mock them in tests
External test repo — keep tests in a private side-repo if they need a richer harness

The default csproj has no test project. Add one when there's something to test.

License

MIT — see LICENSE.

4.1 KiB Raw Blame History