mod-token-turnin

An AzerothCore module for mod-playerbots that turns tier tokens into gear — no alt log in, no trips to the vendor!

Overview

Playerbots loot tier tokens just like real players, but unlike real players they can't walk themselves to a vendor and turn them in. Left alone, those tokens just sit in bag slots until someone logs into that specific character and does it manually — impractical when you're managing a full raid of bots.

mod-token-turnin adds a single chat command that scans a player's own bags (off by default, see below) and (if grouped) their party's or raid's bags, for tier tokens. For every token found, it resolves the correct class- and spec-appropriate gear piece, destroys the token, and awards the item instantly.

The module is deliberately narrow in scope: it's a bot-management convenience tool, not a way to make gearing easier for real players — by default it only touches playerbots in your group, never your own character or real grouped players unless you explicitly opt in.

Features

• One command, two modes — check for a dry-run preview of what would happen, redeem to actually perform the conversion.
• Full raid/party scanning — point it at your group and it sweeps every bot's bags in one pass.
• Spec-aware resolution — reads each bot's actual invested talent tree (not just their "declared" spec) to award the correct itemization: tank gear for a Protection Paladin, healer gear for a Restoration Druid, and so on.
• Class-correct token handling — tokens shared across multiple classes (e.g. a token usable by Warrior, Priest, and Druid alike) resolve to the right class's gear automatically.
• Inventory-safe — a bot with no free bag space keeps its token and gets a clear message, instead of losing the token for nothing.
• Readable, clickable output — check and redeem report real, quality-colored, clickable item links in chat, not plain text.
• Configurable scope — opt in to including your own character or real (non-bot) group members if you want the convenience for yourself too.
• No vendor, no vendor-run mechanics — token in, item out. No secondary materials, no NPC dialogue, no travel.

Installation

1. Clone this module into your AzerothCore modules/ directory:

   cd azerothcore-wotlk/modules
   git clone https://github.com/Zerathane/mod-token-turnin
   

2. Re-run CMake and rebuild worldserver as usual — modules are picked up automatically:

   cd ../build
   cmake .. -DCMAKE_INSTALL_PREFIX=$HOME/azeroth-server -DCMAKE_BUILD_TYPE=RelWithDebInfo
   make -j$(nproc) && make install
   

3. Copy the generated mod_token_turnin.conf.dist from your server's conf/ directory to mod_token_turnin.conf and adjust settings if desired (see Configuration below).
4. Apply the module's world database update — this happens automatically on next worldserver start via the DB updater, provided your server is configured to auto-apply updates.
5. Restart worldserver.

This module has no hard dependency on mod-playerbots to compile — it builds and runs standalone. Without playerbots installed, group scans simply have no bots to find, and TokenTurnIn.IncludeRealPlayers becomes a no-op. It's meant to be used alongside mod-playerbots.

⚠️ Upgrading from an earlier version: this release changes both the module's code and its database table, and the two must match. If you pull the new files and restart worldserver without rebuilding, the new SQL gets applied against the old binary — which silently awards an arbitrary one of the two Ahn'Qiraj pieces, without requiring or consuming an idol, rather than reporting an error. Always rebuild after pulling.

Configuration

All options live in mod_token_turnin.conf:

Option	Default	Description
TokenTurnIn.Enable	1	Master on/off switch for the .tokenturnin commands.
TokenTurnIn.IncludeSelf	0	Include the invoking player's own character in the scan. Off by default — this module is for bot management, not player convenience.
TokenTurnIn.IncludeRealPlayers	0	Include real (non-bot) group members, not just playerbots. Requires mod-playerbots to be built in; otherwise a no-op.

TokenTurnIn.IncludeSelf and TokenTurnIn.IncludeRealPlayers are independent — any combination of on/off is valid.

Text Commands

Command	Description
.tokenturnin check	Dry run. Scans and reports what would be converted, without destroying or awarding anything.
.tokenturnin redeem	Live run. Performs the conversion — destroys tokens, awards gear.

Scope auto-detection:

• Not grouped, and IncludeSelf is off (default) → nothing to scan, and you'll get a clear message saying so.
• In a party or raid → scans other group members who are playerbots by default. Real grouped players and your own character are excluded unless you've opted in via config.

You always trigger this manually — there's no passive or automatic conversion on loot.

Example output

[TokenTurnIn] === Redeem (4 characters) ===
[TokenTurnIn] BotWarrior1 (Protection) -> Converted Token: [Gloves of the Wayward Protector] -> Item: [Valorous Siegebreaker Gauntlets]
[TokenTurnIn] BotDruid2 (Restoration) -> Failed to convert Token: [Chestguard of the Fallen Defender] -> Item: [Chestguard of Malorne] (no inventory space, token not consumed)
[TokenTurnIn] No talents invested - spec cannot be determined, skipped: BotPaladin3
[TokenTurnIn] No convertible tokens found on: BotMage4
[TokenTurnIn] Summary: 1 converted, 1 failed (no space), 2 characters with nothing to convert.

Item and token names render as real in-game chat links, colored by item quality and clickable for a tooltip — just like a vendor or loot window.

How It Works

1. Scan — the command walks the invoker's bags, and (if grouped) the bags of every eligible group member, looking for item entries that match a known tier token.
2. Resolve spec — for each bot carrying a token, the module reads the character's actual invested talent points from core's talent data to determine their dominant talent tree.
3. Look up the item — token, class, and talent tree together resolve to exactly one gear piece via the module's data table.
4. Convert — on redeem, the token is destroyed and the resolved item awarded. If there's no free bag space, the bot keeps the token and you're told why.

Supported Content

Tier token data is added incrementally, tier by tier, and verified in-game before being considered done.

Tier	Raid(s)	Difficulty	Status
ZG, AQ20	Zul'Gurub, The Ruins of Ahn'Qiraj	20-man	✅ Implemented
T2.5	The Temple of Ahn'Qiraj	40-man	✅ Implemented
T3	Naxxramas	40-man	✅ Implemented
T4	Karazhan / Gruul's Lair / Magtheridon's Lair	10-man & 25-man	✅ Implemented
T5	Serpentshrine Cavern / The Eye	25-man	✅ Implemented
T6	Black Temple / Hyjal Summit / Sunwell Plateau	25-man	✅ Implemented
T7	Naxxramas / The Eye of Eternity / The Obsidian Sanctum	10-man & 25-man	✅ Implemented
T8	Ulduar	10-man & 25-man	✅ Implemented
T9	Trial of the Crusader	10-man & 25-man	❌ Out of scope — see below
T10	Icecrown Citadel	10-man & 25-man	❌ Out of scope — see below

T2.5 now fully implemented The shoulders and boots of this tier work differently to every other tier token: a "Qiraji Bindings" token doesn't map to a single item — the same token covers both the shoulder and the boot piece. What decides which one you get is the Idol carried alongside it, so the module reads that too. An example of how T2.5 redeeming works:

• Token + one matching idol → that piece is awarded.
• Token + both idols, one piece already owned → the piece you're missing is awarded (worn gear counts, so a bot that already equipped its shoulders gets the boots).
• Token + both idols, neither piece owned → shoulders redeemed, with the boots still available for the next Bindings token.
• Token + no idol → nothing is converted, and the report tells you which token is waiting on an idol.
• 2 Tokens + both idols → both items converted in a single redeem command

T9/T10 are intentionally out of scope. In those tiers, base tier gear is purchased from a vendor with emblem currency rather than looted as a token, and the heroic upgrade item isn't slot-specific — it requires a player's choice of which piece to upgrade. Neither mechanic fits this module's "find token, destroy it, award its paired item".

Contributing

Found a wrong token/item mapping, a class that resolves to the wrong gear, or anything else? Bug reports and pull requests are welcome — see the AzerothCore contributing guide for the general process.

License

Released under the MIT License.