# 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`.