Initial template setup

2026-05-09 16:41:15 +02:00
commit 4a2e840888
20 changed files with 561 additions and 0 deletions
@@ -0,0 +1,103 @@
+# 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`.