# PvPScout (WoW Retail)

PvPScout shows WoW PvP ratings from the official leaderboards directly in unit tooltips and via the `/pvpscout` command. Data is generated outside the game and written to `PvPScout/Data.lua`.

Highlights:

- Tooltip integration for 2v2, 3v3, Solo Shuffle, Rated Battlegrounds (10v10), Blitz RBG
- Options panel: enable/disable, show rank, minimap icon, per-bracket visibility, and bracket ordering
- Minimap button with right-click menu for quick toggles
- “Updated X ago” header and optional stale-data notice; optional color-by-rating
- Automated data refresh every ~3 hours via GitHub Actions
- Slash commands: `/pvpscout`, `/pvpscout enable`, `/pvpscout disable`

## How it works

- A small Node.js fetcher (in `tools/`) calls the Blizzard Game Data APIs, normalizes names/realms, and writes a compact `Data.lua`.
- The addon uses that data to display ratings in the tooltip and on demand.

## Repository layout

- `PvPScout/` – the WoW addon
- `tools/` – the Node.js fetcher that writes `PvPScout/Data.lua`
- `.github/workflows/` – automation for hourly updates, packaging, and (optional) CurseForge upload

## Maintainer setup (recommended: cloud-only)

The repository ships with an hourly workflow (`.github/workflows/update-data.yml`) that updates `Data.lua`, commits changes, and produces a `PvPScout.zip` artifact. To enable it:

1. Create a Blizzard OAuth client and note the Client ID/Secret: <https://develop.battle.net/access/clients>

2. Add GitHub Actions secrets in your repo (Settings → Secrets and variables → Actions)

- `BLIZZARD_CLIENT_ID`
- `BLIZZARD_CLIENT_SECRET`

That’s it. The workflow runs hourly and can also be triggered manually from the Actions tab (Run workflow).

Artifacts:

- The job always builds `PvPScout.zip` and uploads it as an artifact you can download.
- If `Data.lua` changed, the workflow commits it to the repository automatically.

## Optional: automated releases and CurseForge upload

There are two pieces here:

1. Manual release from the hourly workflow

- Use the “Update PvP data and package” workflow → Run workflow → set `release` to `true` (and choose bump type).
- This bumps the version in `PvPScout/PvPScout.toc`, creates a tag `vX.Y.Z`, rebuilds the ZIP, and creates a GitHub Release.

1. Upload to CurseForge on tags (`.github/workflows/curseforge-upload.yml`)

- Add the repository secret `CF_API_KEY` (your CurseForge API token from the Authors Portal).
- Ensure your TOC contains your project ID:

  ```ini
  ## X-Curse-Project-ID: 1350552
  ```

- Pushing a tag that starts with `v` (e.g. `v0.1.1`) triggers a build and upload via `BigWigsMods/packager` for Retail (`-g retail`).

Manual tag alternative (PowerShell):

```powershell
git fetch --tags
git tag v0.1.1
git push origin v0.1.1
```

Verification:

- In Actions, the workflow “Upload to CurseForge (on tag)” should show:
  - “Check CF_API_KEY secret” → run=true
  - “Check CurseForge Project ID in TOC” → Found … 1350552
  - “Pack and upload via BigWigsMods/packager” completes successfully

Security note: Treat the CurseForge token like a password. If it leaks, revoke it and rotate the GitHub secret.

## Local development (optional)

You only need this if you want to test the fetcher locally. Users don’t need any of it.

1. Copy `tools/.env.example` to `tools/.env` and fill in:

- `BLIZZARD_CLIENT_ID`
- `BLIZZARD_CLIENT_SECRET`
- `WOW_ADDON_DIR` – absolute path to the `PvPScout` addon folder
  - Windows: `C:\Program Files (x86)\World of Warcraft\_retail_\Interface\AddOns\PvPScout`
  - macOS: `/Applications/World of Warcraft/_retail_/Interface/AddOns/PvPScout`
- Optionally adjust `REGIONS` and `BRACKETS`.

1. Install dependencies and run a fetch (PowerShell):

```powershell
cd tools ; npm ci
cd tools ; npm run fetch
```

You should see `PvPScout/Data.lua` updated.

### Offline mode (no Blizzard credentials)

Wenn du keine API-Credentials hast oder nur lokal testen willst, kannst du den Fetcher im OFFLINE-Modus laufen lassen und Daten aus einer Datei/URL importieren.

- Setze die Umgebungsvariable `OFFLINE_SOURCE` auf eine JSON- oder CSV-Datei (oder eine HTTP(S)-URL).
- Unterstützte Formate:
  - JSON: `{ "season": 0, "eu": { "2v2": { "Name-Realm": {"rating": 2100, "rank": 123} } } }`
  - CSV: `region,bracket,name,realm,rating,rank`
- Beispielfiles: `tools/offline-data.sample.json`, `tools/offline-data.sample.csv`

Beispiel (PowerShell):

```powershell
$env:OFFLINE_SOURCE = "C:\\Projekte\\PvPScout\\tools\\offline-data.sample.json"
cd tools ; npm run fetch
```

Wenn `BLIZZARD_CLIENT_ID/SECRET` fehlen, aber `OFFLINE_SOURCE` gesetzt ist (oder eine `offline-data.json/csv` in `tools/` bzw. Repo-Root gefunden wird), importiert der Fetcher daraus und erzeugt `Data.lua` entsprechend.

### Optional: schedule locally

If you don’t want to use GitHub Actions, you can run the fetcher on a schedule locally.

Windows (Task Scheduler):

1. Create Task → General: Run whether user is logged on or not
2. Triggers: On a schedule → Repeat every 1 hour
3. Actions: Start a program
   - Program/script: `powershell.exe`
   - Add arguments:

     ```powershell
     -NoProfile -ExecutionPolicy Bypass -Command "cd 'C:\Projekte\PvPScout\tools'; npm run fetch"
     ```

   - Start in: `C:\Projekte\PvPScout\tools`

macOS (launchd): create `~/Library/LaunchAgents/com.pvpscout.fetch.plist` and load it:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key><string>com.pvpscout.fetch</string>
    <key>ProgramArguments</key>
    <array>
      <string>/bin/zsh</string>
      <string>-lc</string>
      <string>cd \"$HOME/Projekte/PvPScout/tools\" && npm run fetch</string>
    </array>
    <key>StartInterval</key><integer>3600</integer>
    <key>RunAtLoad</key><true/>
  </dict>
  </plist>
```

```bash
launchctl load ~/Library/LaunchAgents/com.pvpscout.fetch.plist
```

## In-game usage

- Hover a player: ratings per enabled bracket are appended to the tooltip (if the character is on the official ladder).
- `/pvpscout enable` or `/pvpscout disable` to toggle tooltip lines.
- `/pvpscout` (with a player targeted) prints ratings in chat.

Notes:

- Only characters present on the official leaderboards will show ratings.
- Region is auto-detected from the client’s portal; it can be overridden in SavedVariables if needed.

## Troubleshooting

Blizzard Developer Portal login:

- Use the official URL: <https://develop.battle.net>
- If you get redirected to a `community.developer.battle.net/login/callback?...` 404:
  - Re-login via <https://develop.battle.net> (not the community subdomain)
  - Clear cookies/cache for `battle.net` or use a private window
  - Check extensions that might block redirects

Missing ratings in-game:

- Very new or low-rated characters may not yet be on the ladder snapshot.
- If a specific name/realm should be present but isn’t, open an issue; we can refine normalization.

## Development notes

- TOC Interface `110002` targets DF 11.0.2; update when the client API changes.
- The fetcher limits to the top ~5000 entries per region/bracket to keep `Data.lua` small.
- Supported brackets: `2v2`, `3v3`, `shuffle`, `rbg`, `blitz` (with API slug fallbacks in the fetcher).

## License

MIT
