# Player Notes

A [Dalamud](https://dalamud.dev/) plugin for FFXIV that keeps two pools of tracked players — a **friend list** and a **blacklist** — with notes, per-pool tags, chat alerts when listed players join your party (or you join theirs), and JSON export/import so the lists can move between PCs.

## Features

- **Two tabs, identical UI**: Friends and Blacklist each show a scrollable player list on the left and a notes editor on the right.
- **Right-click to add**: right-click a player name in the chat log → *Add to Friends* / *Add to Blacklist*. The player's ContentId and home world are stored, so party matching works even when players on different worlds share the same name (the world is shown next to each entry).
- **Tags per pool**: each pool has its own tag set (e.g. friends: `raider`, `healer`; blacklist: `toxic behavior`, `progression point liar`). Tags are fully user-configurable in the JSON data file — see [Tag configuration](#tag-configuration).
- **Party alerts**: a colored chat message appears when you join a party that contains listed players, and when listed players join your own party. Blacklist entries take priority over friend entries.
- **Export / import**: one click exports both pools (and tag definitions) to a JSON file; importing replaces the current data with the imported file's contents. The same format is used for the on-disk data file, so copying `PlayerNotes.json` between machines works too.
- **Quality-of-life extras**: add-by-name field (type `Name [World]` to disambiguate; Enter or the Add button submits), list filter box, move-between-pools button (drops tags invalid in the destination pool), two-step remove confirmation, hover tooltips showing a player's tags, and the `/playernotes` chat command to open the window.

## Building

Requires the [.NET SDK](https://dotnet.microsoft.com/download) (the project targets `net10.0-windows`, which the Dalamud SDK sets). A local Dalamud install is needed for the build to resolve game types:

- Windows / XIVLauncher: `%APPDATA%\XIVLauncher\addon\Hooks\dev\`
- Linux / XIVLauncherCore: `~/.xlcore/dalamud/Hooks/dev/`
- (overridable with the `DALAMUD_HOME` environment variable)

```sh
dotnet build PlayerNotes.slnx
```

The output is a loadable plugin zip at `PlayerNotes/bin/Debug/net10.0-windows/PlayerNotes.zip`.

## Loading in game (dev plugin)

1. In chat: `/xlsettings` → **Experimental** → **Dev Plugin Locations**.
2. Add the build output directory (`PlayerNotes/bin/Debug/net10.0-windows/`).
3. Reload plugins with `/xllreloadplugin` (or restart the game).
4. Open the window with `/playernotes`, or right-click a player name in chat to start adding entries.

## Data file & tag configuration

All data lives in a single JSON file inside the plugin's config directory:

- Windows / XIVLauncher: `%APPDATA%\XIVLauncher\plugin_config\PlayerNotes\PlayerNotes.json`
- Linux / XIVLauncherCore: `~/.xlcore/dalamud/plugin_config/PlayerNotes/PlayerNotes.json`

The file is created automatically with default tags on first run. It's hand-editable — comments are allowed and ignored, so you can annotate it freely. After editing the file out-of-game (or while the plugin isn't saving), use **Reload from disk** in the window to pick up changes.

Example:

```jsonc
{
  // Tags available for each pool. Edit these lists to match how you organize players.
  "tags": {
    "friends": ["raider", "healer", "tank", "dps", "speedrunner", "lfg friendly"],
    "blacklist": [
      "toxic behavior",
      "impatient",
      "progression point liar",
      "afk / leaves early",
      "griefer",
      "no comms"
    ]
  },

  // One entry per tracked player. contentId is optional (null when added by name only);
  // world disambiguates same-name players across worlds; notes and tags are free-form.
  "friends": [
    {
      "name": "Some Healer",
      "world": "Phoenix",
      "contentId": 123456789,
      "notes": "Great on oGcd, ping before pull.",
      "tags": ["healer", "raider"],
      "addedAtUtc": "2026-10-28T12:00:00Z"
    }
  ],

  "blacklist": [
    {
      "name": "Bad Player",
      "world": "",
      "contentId": null,
      "notes": "Left mid-pull in a raid.",
      "tags": ["afk / leaves early"],
      "addedAtUtc": "2026-10-28T13:30:00Z"
    }
  ]
}
```

## Export / import (moving between PCs)

- **Export**: writes both pools plus the tag definitions to a JSON file of your choosing. Copy that file to the other PC and use **Import** there, or simply copy `PlayerNotes.json` into the new machine's plugin config directory before first launch.
- **Import**: parses the chosen file and *replaces* the current data (both pools and tag sets) with it.

## Known limitations

- Party alerts are detected by polling the party list each frame, so a player who joins while you're in a loading screen may not trigger an alert on re-entry — the watcher resets when you're solo, so re-grouping re-triggers notifications.
- A player can exist in both pools; the blacklist alert takes priority.
- Players added by name (no ContentId) are matched to party members by name only.

## Project layout

```
PlayerNotes/
  PlayerNotes.csproj   # SDK + manifest metadata (name, author, version)
  Plugin.cs            # entrypoint: context menu, /playernotes command, pool dedupe
  Configuration.cs     # data model: Pool, PlayerEntry, TagSets, PlayerNotesData
  Storage.cs           # JSON load/save/parse of PlayerNotes.json
  PartyWatcher.cs      # party polling + colored chat alerts
  Windows/
    MainWindow.cs      # tabs, list/detail UI, tags, notes, export/import dialogs
```