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:IsReady() — boolean. True once the first stabilized full roster build has completed (when OnRosterReady has fired).
• 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, zone, publicNote, officerNote, status, isMobile, lastOnline }.
• lib:GetAllMembers() — array of Name-Realm strings.
• lib:GetOnlineMembers() — array of online Name-Realm strings.
• lib:GetNormalizedPlayer() — string or nil. The local player's own Name-Realm, in the same form as the roster keys (compare it directly against GetMember / GetAllMembers). Falls back to the bare name before the realm resolves.
• lib:NormalizeName(name) — string or nil. The same normalization the lib applies to roster keys; use it to build a key that matches.
• lib:GetRealmName() — string. The connected-realm-aware realm name, cached after login.

Cross-guild API (sister rosters)

New in 0.2.0. The library can track one or more sister guilds alongside your own — useful when a player belongs to two allied guilds and wants to share data across both. Your own guild stays self-scanned and authoritative; sister rosters are fed in from outside (your addon discovers and syncs them). The lib only stores, normalizes, hashes, diffs, queries, and ages presence; it does no networking and persists nothing. All of this is additive — the methods above are unchanged.

• lib:GetHomeGuildKey() — string or nil. Your guild's key, "Faction-GuildName" (e.g. "Horde-The Brave Ones"); nil when guildless.
• lib:SetSisterRoster(guildKey, members, meta) — wipe-and-replace a sister guild's roster. members are "Name-Realm" strings or { name, class, level, rank } tables; meta is optional opaque data the lib stores but never interprets (a re-feed that omits it keeps the previous value; only RemoveSisterRoster clears it).
• lib:RemoveSisterRoster(guildKey) — stop tracking a sister guild.
• lib:MarkOnline(guildKey, names) — stamp a last-seen time for sister members.
• lib:GetOnlineMembersScoped(guildKey) — array of online Name-Realm (home: live status; sister: members seen within lib.PRESENCE_TTL, default 120s).
• lib:IsInAnyRoster(name) — guildKey or nil; your own guild takes precedence.
• lib:IsInGuildScoped(guildKey, name) — boolean.
• lib:GetRoster(guildKey) — the roster table, or nil.
• lib:GetRosterMeta(guildKey) — the opaque meta you passed to SetSisterRoster, or nil.
• lib:GetKnownRosters() — array of every guildKey currently tracked.
• lib:GetRosterHash(guildKey) — a stable digest of the membership set only (excludes presence/rank/status), so two clients with the same members produce the same hash.

Presence is a separate overlay from membership: a roster resync never wipes liveness, and the lib never asserts "offline" — presence simply ages out and self-corrects. Persist sister rosters in your own SavedVariables and re-feed them on login; the first feed for a guild is treated as a baseline, so it won't re-welcome every member. Because the lib ships embedded in several addons, depend on a copy at MINOR 6 or newer and feature-detect each method (if lib.SetSisterRoster then ...).

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, guildKey) — home guild: fires only on the CHAT_MSG_SYSTEM "has joined the guild" message, never from roster diffs; sister guild: fires from the SetSisterRoster diff. The guildKey 2nd argument is new in 0.2.0; one-arg consumers ignore it.
• OnMemberLeft(name, guildKey) — home: "has left the guild" or "has been kicked out of the guild"; sister: the SetSisterRoster diff.
• OnRosterHashChanged(guildKey, newHash) — fires when a roster's membership set changes (not presence): the home roster on a post-stabilization rebuild, a sister roster on each SetSisterRoster that alters the set.

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.2.1 — Retail taint safety, and faster message scanning

• No longer taints retail execution during instanced content. On retail, system chat lines are flagged protected ("secret") while you're in an active Mythic+, raid encounter, or rated PvP match. Reading one with a string operation taints execution and shows up as unrelated Blizzard errors (money frames, world-map tooltips, and the like). The lib now checks Blizzard's C_ChatInfo.InChatMessagingLockdown state and skips parsing while it's active, so it never touches a protected value. Guild presence, joins, and leaves work normally everywhere else — only those locked-down windows are skipped, and membership catches up on the next roster rebuild. Classic, BCC, Wrath, and Cata have no such system and are unaffected.
• Cheaper CHAT_MSG_SYSTEM scanning. The handler now rejects the flood of unrelated system messages (loot, achievements, instance notices, ...) with a single cheap text check before doing any heavy pattern work, so the library does far less work per chat line. This matters because it sits in the chat hot path of every addon that embeds it.

v0.2.0 — Cross-guild (sister-roster) support

• Track sister guilds alongside your own. A new multi-roster store lets a consumer feed in one or more sister-guild rosters (membership + presence) and query them the same way as the home guild. Everything from the previous release is unchanged and home-only; all the new behaviour is additive.
• New methods: GetHomeGuildKey, SetSisterRoster, RemoveSisterRoster, MarkOnline, GetOnlineMembersScoped, IsInAnyRoster, IsInGuildScoped, GetRoster, GetRosterMeta, GetKnownRosters, GetRosterHash.
• New OnRosterHashChanged(guildKey, newHash) callback and a guildKey 2nd argument on OnMemberJoined / OnMemberLeft (one-arg consumers are unaffected).
• Presence is a separate, transient overlay — a roster resync never wipes liveness, and the lib never asserts "offline"; presence ages out on its own. Nothing is persisted by the lib.

v0.1.0 — Player normalization helper, documented API

• New lib:GetNormalizedPlayer() getter. Returns the local player's own Name-Realm string in the same form as the roster keys, so you can match yourself against GetMember / GetAllMembers without rebuilding the string by hand. Falls back to the bare name before the realm resolves.
• NormalizeName and GetRealmName are now documented. Both have always been available; they're now listed as public API for consumers that build Name-Realm keys or compare against roster keys.

v0.0.4 — Retail "secret string" taint fix

• Retail (TWW+) CHAT_MSG_SYSTEM taint errors silenced. Some retail system messages carry a protected "secret" flag, and touching one with a string operation throws a taint error that could cause the lib to miss later guild events. This release suppressed the visible error. (This quieted the crash but did not fully prevent the underlying taint — that was properly fixed in v0.2.1.)

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.