XIVLoot Auto-Importer

A Dalamud plugin for FINAL FANTASY XIV that keeps your in-game equipped gear in sync with your claimed character on xivloot.

What it does

• First-time setup — a short wizard logs you in to xivloot via OAuth device-code flow (no password ever touches the plugin), lets you pick which claimed character maps to the character you're logged in on, and offers to import your currently equipped gear.
• Ongoing sync — while you're logged in on the linked character, the plugin watches for gear changes. When you equip a piece that xivloot tracks, it asks whether to update your loadout. If the piece is savage gear, it also asks how it was obtained — book vs loot — and records the source.
• Stays out of the way — non-savage updates can be pushed silently (a setting), untracked gear is ignored, and syncing only runs for the character you linked so alts on the same PC are never touched.

Open the plugin any time with /xivloot.

How it works

xivloot's backend is authoritative for "is this item tracked?" and "is it savage / does it need an acquisition source?" — the plugin never classifies gear itself, it asks the API. Gear changes are detected via Dalamud's IGameInventory events on the EquippedItems container, debounced on the framework tick so equipping a full glamour plate produces one prompt, not a storm.

Area	File
Config, tokens, character binding	XivlootAutoImporter/Configuration.cs
Slots, DTOs, prompt model	XivlootAutoImporter/Models.cs
xivloot REST client (auth + gear)	XivlootAutoImporter/Services/XivlootApiClient.cs
Read equipped gear	XivlootAutoImporter/Services/GearReader.cs
Change detection + prompt queue	XivlootAutoImporter/Services/GearChangeWatcher.cs
Setup wizard / prompt / settings / dashboard	XivlootAutoImporter/Windows/*.cs
Plugin entry point & wiring	XivlootAutoImporter/Plugin.cs

Backend API contract

The plugin expects the following endpoints (align paths and JSON field names with xivloot's actual backend — the JsonPropertyName values in Models.cs are the single source of truth):

• POST /oauth/device/code — begin device authorization (RFC 8628)
• POST /oauth/device/token — poll for the token (authorization_pending / slow_down)
• POST /oauth/token/refresh — refresh an expired access token
• GET /me/characters — the user's claimed characters
• POST /characters/{id}/gear/check — { itemIds } → [{ itemId, tracked, savage, requiresSource }]
• POST /characters/{id}/gear/import — bulk initial import
• PUT /characters/{id}/gear/{slot} — single-slot update

acquisition is BOOK | LOOT | null, mapped to xivloot's existing loot-source field, and is only sent when requiresSource is true.

Building

Prerequisites:

• XIVLauncher, FINAL FANTASY XIV, and Dalamud installed, with the game run once under Dalamud (so the dev libraries exist at %AppData%\XIVLauncher\addon\Hooks\dev). Set DALAMUD_HOME if you use a custom path.
• A recent .NET SDK (this project builds against Dalamud.NET.Sdk/15.0.0).

dotnet build XivlootAutoImporter/XivlootAutoImporter.csproj -c Release

The plugin is produced at XivlootAutoImporter/bin/Release/XivlootAutoImporter.dll.

Running in-game (dev plugin)

1. /xlsettings → Experimental → add the full path to XivlootAutoImporter.dll under Dev Plugin Locations (only needed once).
2. /xlplugins → Dev Tools › Installed Dev Plugins → enable XIVLoot Auto-Importer.
3. Run /xivloot to open the plugin and start the setup wizard.

To test against a local xivloot instance, set the API base URL in the plugin's Settings window before running setup.

License

AGPL-3.0-or-later. See LICENSE.md.

All participation in this repository is governed by the Dalamud Code of Conduct.