104 lines
4.1 KiB
Markdown
104 lines
4.1 KiB
Markdown
# Dalamud Plugin Template
|
|
|
|
A starting point for FFXIV/Dalamud plugins on the [Hellion Forge](https://gitea.hellion-forge.cloud/).
|
|
|
|
Distilled from the [HellionChat](https://gitea.hellion-forge.cloud/JonKazama-Hellion/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
|
|
|
|
1. Click **"Use this template"** at the top of the repository page on the Forge.
|
|
2. Pick a name like `MyPlugin` and clone your new repo locally.
|
|
3. Find-and-replace `PluginNameTemplate` everywhere with your plugin's name (case-sensitive).
|
|
```bash
|
|
git ls-files | xargs sed -i 's/PluginNameTemplate/MyPlugin/g'
|
|
git mv PluginNameTemplate.csproj MyPlugin.csproj
|
|
git mv PluginNameTemplate.yaml MyPlugin.yaml
|
|
```
|
|
4. Replace `images/icon.png` with your plugin icon (512x512 PNG, transparent background).
|
|
5. Update `repo.json` with your real `DownloadLinkInstall` URLs once your CI publishes releases.
|
|
6. 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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`.
|