LibGuildRoster-1.0 — Reliable Guild Roster Tracking for WoW Addons

LibGuildRoster-1.0 is a small, drop-in library for World of Warcraft addons that need to know the current state of the player's guild — who's in it, who's online, and who just joined or left. It handles the awkward edge cases that bite anyone who tries to use GetGuildRosterInfo directly: the streaming login roster, the partial-snapshot misfires, and the stale server responses that briefly re-list a player you just watched leave.

Why this exists

Tracking the guild roster sounds simple. It isn't. On retail, the roster streams in across multiple GUILD_ROSTER_UPDATE events after login or /reload. Naively diffing those events tells you that 150 of your guildmates just joined when really the previous event captured a partial roster. The GetGuildRosterInfo iteration is also silently filtered by the guild panel's "show offline" toggle on retail — flip it off and your "roster" only contains currently-online members.

This library solves both. It wipes and rebuilds the roster from scratch on every GUILD_ROSTER_UPDATE (no stale entries possible), gates the OnRosterReady callback behind a stabilization phase that requires two consecutive rebuilds at the same member total, and forces the show-offline toggle on at login on retail. Joins fire from the authoritative CHAT_MSG_SYSTEM "has joined the guild" message, never from a roster diff that could be confused by a partial snapshot.

Public API

lib:IsInGuild(name) — boolean. Accepts short names or Name-Realm.
lib:IsOnline(name) — boolean.
lib:GetMember(name) — table or nil: { name, class, level, rankIndex, rankName, isOnline }.
lib:GetAllMembers() — array of Name-Realm strings.
lib:GetOnlineMembers() — array of online Name-Realm strings.

Callbacks (via CallbackHandler-1.0)

OnRosterReady() — fired once after the first stabilized full build. This is when consumers can trust IsInGuild, GetMember, and friends.
OnRosterUpdated() — fired after every full rebuild.
OnMemberOnline(name) / OnMemberOffline(name) — presence transitions.
OnMemberJoined(name) — fires only on the CHAT_MSG_SYSTEM "has joined the guild" message. Never from roster diffs.
OnMemberLeft(name) — fires on "has left the guild" or "has been kicked out of the guild".

Compatibility

Classic Era (1.15.x)
Burning Crusade Classic (2.5.x)
Wrath Classic (3.4.x)
Cataclysm Classic (4.4.x)
Mainline / Retail (11.x and 12.x)

Required dependency

Ace3 — supplies LibStub and CallbackHandler-1.0. CurseForge installs Ace3 automatically when you install this addon, so most players don't need to do anything special.

Embedding in your addon

The recommended path is to reference this lib as an external in your addon's .pkgmeta:

externals:
  Libs/LibGuildRoster-1.0:
    url: https://github.com/Pimptasty/GuildRoster
    tag: latest-release

Then load it from your .toc after LibStub and CallbackHandler-1.0 (provided by your own embeds, Ace3, or another lib):

Libs\LibGuildRoster-1.0\LibGuildRoster-1.0.lua

Quick example

local lib = LibStub("LibGuildRoster-1.0")

lib.callbacks:RegisterCallback(self, "OnRosterReady", function()
    print("Guild roster ready,", #lib:GetAllMembers(), "members.")
end)

lib.callbacks:RegisterCallback(self, "OnMemberJoined", function(_, name)
    print("Welcome,", name)
end)

Caveats

Retail show-offline toggle — the lib calls SetGuildRosterShowOffline(true) at PLAYER_LOGIN on Mainline. If your addon also touches that flag, leave it on, otherwise the roster will only contain currently-online members and join callbacks will misfire when an offline guildie later logs on.
Recently-left dedup — a 60-second window after OnMemberLeft suppresses OnMemberJoined for the same player. A legitimate rejoin within 60 seconds will not fire OnMemberJoined.

Recent Updates

v0.0.4 — Retail "secret string" taint fix

Retail (TWW+) CHAT_MSG_SYSTEM taint errors silenced. Some internal BNet / whisper-related system messages on retail carry a protected "secret" flag — touching them with any string operation throws an "attempt to compare ... a secret string value, while execution tainted by <addon>" error and could cause the lib to miss subsequent legitimate guild events. The lib now detects protected values up-front and ignores them safely.

v0.0.3 — Ace3 dependency, install fix

Standalone install no longer errors. v0.0.1 and v0.0.2 could log a Lua warning about missing LibStub.lua on first load; this is resolved by depending on Ace3 (which supplies LibStub and CallbackHandler-1.0).
Ace3 is now a required dependency. CurseForge installs it automatically when you install this addon.

v0.0.2 — Locale fix, expanded member data, rank-change callback

Non-English clients now work properly. Online, offline, join, and leave events fire in real time on every locale; previously the hardcoded English chat patterns silently failed on German, French, Russian, Chinese, and other clients.
More data on every guild member. GetMember now returns zone, public note, officer note, AFK/DND status, mobile-app connection flag, and offline duration (years/months/days/hours).
New lib:IsReady() getter. Consumers loading after the lib (or registering callbacks after the first roster build) can now check readiness and bootstrap themselves without missing OnRosterReady.
New OnMemberRankChanged(name, oldRankIndex, newRankIndex) callback. Fires when a guildmate is promoted or demoted, detected from the rebuild diff. Safe against partial-roster login streams.

v0.0.1 — Initial release

First standalone release of LibGuildRoster-1.0 on CurseForge, extracted from its prior home as a vendored copy inside FastGuildInvite.
Supports Classic Era, Burning Crusade Classic, Wrath Classic, Cataclysm Classic, and Mainline / Retail.
Full public API and callback surface as documented above.

Contact

Bug reports, feature requests, questions, or just chatting: Join the Discord.