You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+65-45Lines changed: 65 additions & 45 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,70 +1,78 @@
1
1
# EQ2 Lexicon — ACT Plugin
2
2
3
-
An [Advanced Combat Tracker](https://advancedcombattracker.com) plugin that uploads parsed EverQuest 2 encounters to the [EQ2 Lexicon](https://github.com/VortexUK/EQ2CensusBot) website after each fight ends.
> v0.1.0 — scaffold only. The end-of-combat hook, settings UI, and HTTP upload land in subsequent commits.
6
+
An [Advanced Combat Tracker](https://advancedcombattracker.com) plugin that uploads parsed EverQuest 2 encounters to the [EQ2 Lexicon](https://eq2lexicon.up.railway.app) website automatically after each fight ends.
6
7
7
-
## How it works (when complete)
8
+
## Install (end users)
8
9
9
-
1. You configure the plugin once with an API token minted from the EQ2 Lexicon website (`/settings/tokens`)
10
-
2. ACT continues to parse your EQ2 combat log as normal
11
-
3. Each time an encounter ends, the plugin builds an ACT-shaped JSON payload of the encounter / combatants / damage / heal / cure / threat data and `POST`s it to `/api/parses/ingest` with your bearer token
12
-
4. The website resolves your guild via the Census API, stores the parse, and surfaces it on `/parses` for any signed-in user to browse
10
+
1. Sign in at <https://eq2lexicon.up.railway.app> and mint an API token at `/settings/tokens`.
11
+
2. Download `EQ2Lexicon.ACTPlugin.dll` from the [latest release](https://github.com/VortexUK/EQ2LexiconACTPlugin/releases/latest).
12
+
3. Drop the DLL into `%APPDATA%\Advanced Combat Tracker\Plugins\`.
13
+
4. In ACT: **Options → Plugins → Browse**, pick the DLL, then **Add/Enable Plugin**.
14
+
5. Open the new **EQ2 Lexicon** tab in ACT and paste your token. Hit **Test Connection** to verify, then **Save**.
13
15
14
-
Your EQ2 character name is read from ACT directly (`ActGlobals.charName`) so the website knows whose parse it is without you configuring anything beyond the token.
16
+
You're done. ACT will continue parsing your combat log as normal; finished encounters get uploaded in the background.
15
17
16
-
## Building
18
+
## How it works
17
19
18
-
### Prerequisites
19
-
20
-
-**.NET Framework 4.8 Developer Pack** — [download from Microsoft](https://dotnet.microsoft.com/en-us/download/dotnet-framework/net48) (pick "Developer Pack", not "Runtime"). ~80 MB single installer.
21
-
-**`dotnet` CLI** (.NET SDK 6 or newer). Check with `dotnet --version`. If missing, install the [latest .NET SDK](https://dotnet.microsoft.com/en-us/download).
22
-
-**Advanced Combat Tracker** installed locally — the build references `Advanced Combat Tracker.exe` as a .NET assembly. Default expected location is `C:\Program Files (x86)\Advanced Combat Tracker\`. If yours is elsewhere, set the `ACT_INSTALL_DIR` environment variable.
20
+
1. The plugin polls ACT's active zone every 2 seconds for encounters that have settled (no new combat activity for 15 s).
21
+
2. When one settles, it snapshots the ACT data (encounter, combatants, damage / heal / cure / threat rollups, per-ability breakdowns) and builds an ACT-shaped JSON payload.
22
+
3. The payload `POST`s to `/api/parses/ingest` with your bearer token over HTTPS.
23
+
4. The site resolves your guild via the Daybreak Census API, stores the parse, and surfaces it under your guild on `/parses` for any signed-in user to browse.
23
24
24
-
### Build the DLL
25
+
Your EQ2 character name comes from parsing the active log filename (`eq2log_<character>.txt`) — `ActGlobals.charName` returns the string `"YOU"` for EQ2 and can't be used directly.
The output DLL lands at `src\bin\Release\net48\EQ2Lexicon.ACTPlugin.dll`.
29
+
### Prerequisites
33
30
34
-
### Install into ACT
31
+
-**.NET Framework 4.8 Developer Pack** — [download from Microsoft](https://dotnet.microsoft.com/en-us/download/dotnet-framework/net48) (pick "Developer Pack", not "Runtime"). ~80 MB.
32
+
-**.NET SDK 8.0.421** — pinned via [`global.json`](global.json). `dotnet --version` should match or be a higher 8.0.x.
33
+
-**Advanced Combat Tracker** installed locally so the build can reference `Advanced Combat Tracker.exe`. Default expected location is `C:\Program Files (x86)\Advanced Combat Tracker\`; override via the `ACT_INSTALL_DIR` environment variable.
Restart ACT. In **Plugins → Plugin Listing**, the "EQ2 Lexicon Uploader" should appear with a green check. Click the new **EQ2 Lexicon** tab to confirm it's alive.
41
+
Output lands at `src\bin\Release\net48\EQ2Lexicon.ACTPlugin.dll`. Copy it to `%APPDATA%\Advanced Combat Tracker\Plugins\` and restart ACT.
44
42
45
43
## Project layout
46
44
45
+
Two assemblies in one solution, plus a test project:
46
+
47
47
```
48
-
EQ2Lexicon.ACTPlugin.sln # solution file for Visual Studio users
48
+
EQ2Lexicon.ACTPlugin.sln
49
49
src/
50
-
EQ2Lexicon.ACTPlugin.csproj # net48 class library, references ACT.exe
51
-
Plugin.cs # IActPluginV1 entry point
52
-
SettingsPanel.cs # dark-themed settings UI
53
-
EncounterCapture.cs # 2 s polling + ACT → snapshot adapter
54
-
PayloadBuilder.cs # pure snapshot → ingest-JSON transform
55
-
Snapshots.cs # DTOs decoupling payload logic from ACT
.githooks/pre-push # format + build + test on every push
62
+
EQ2Lexicon.ACTPlugin.Tests/ # xUnit, net48 — references Core only
63
+
.github/
64
+
workflows/ci.yml # build + test + coverage on every push
65
+
workflows/release.yml # auto-publish DLL on v* tag push
66
+
dependabot.yml # weekly dep update PRs
67
+
.githooks/pre-push # format + build + test + vuln scan
68
+
global.json # pinned .NET SDK version
63
69
```
64
70
71
+
The pure layer exists so the build/sanitise/upload logic is testable without instantiating ACT's sealed types, and so CI can compile + test it on runners that don't have ACT.
72
+
65
73
## Running checks locally
66
74
67
-
The pre-push hook runs three checks. **Activate it once after cloning:**
75
+
Activate the pre-push hook once after cloning:
68
76
69
77
```powershell
70
78
git config core.hooksPath .githooks
@@ -75,24 +83,36 @@ After that, every `git push` runs:
75
83
| Step | Command |
76
84
|------|---------|
77
85
| Format check |`dotnet format EQ2Lexicon.ACTPlugin.sln --verify-no-changes`|
78
-
| Build (acts as type-check) |`dotnet build EQ2Lexicon.ACTPlugin.sln -c Release`|
| Tests |`dotnet test EQ2Lexicon.ACTPlugin.sln --no-build -c Release`|
88
+
| Vulnerability scan |`dotnet list EQ2Lexicon.ACTPlugin.sln package --vulnerable --include-transitive`|
80
89
81
90
To fix formatting issues:
82
91
83
92
```powershell
84
93
dotnet format EQ2Lexicon.ACTPlugin.sln
85
94
```
86
95
87
-
To run the tests on their own:
96
+
GitHub Actions runs the same gates on every push and PR, plus collects code coverage via Coverlet + ReportGenerator (Markdown summary posted to the job page, HTML uploaded as an artifact). It builds the UI assembly too by fetching `ACTv3.zip` from the upstream ACT release.
97
+
98
+
The test suite covers `PayloadBuilder` (shape, NaN sanitiser, UTC formatter, JSON serialiser), `PluginConfig` (defaults, blacklist, XML round-trip, DPAPI round-trip), and `UploadClient`'s JSON / truncate helpers + URL validator.
99
+
100
+
The ACT-coupled bits (`EncounterCapture.CaptureSnapshot`, `SettingsPanel`, `Plugin`) aren't unit-tested — they're integration-tested by running the DLL in ACT.
101
+
102
+
## Releasing
103
+
104
+
Releases are fully automated. Bump `<Version>` in both csproj files, commit, push, then:
88
105
89
106
```powershell
90
-
dotnet test
107
+
git tag -a vX.Y.Z -m "vX.Y.Z - <summary>"
108
+
git push origin vX.Y.Z
91
109
```
92
110
93
-
The test suite covers `PayloadBuilder` (encounter/combatant/damage-type/attack-type shape, NaN sanitiser, UTC formatter), `PluginConfig` (defaults, IsBlacklisted, XML round-trip), and `UploadClient`'s JSON / truncate helpers.
111
+
The [release workflow](.github/workflows/release.yml) fetches ACT on the runner, builds the UI DLL, generates release notes from the commit log since the previous tag, and creates a draft release with the DLL attached. Review the notes on GitHub, then publish:
94
112
95
-
The ACT-coupled bits (`EncounterCapture.CaptureSnapshot`, `SettingsPanel`, `Plugin`) aren't unit-tested — they're integration-tested by running the DLL in ACT.
0 commit comments