docs(link): roster members carry guild rank
Amends Protocol 4 in place rather than bumping it: the protocol has not reached `main`, and a bump is owed only once a protocol has been released. The roster shipped as the standard actor object, which carries no rank. Teams phase 2 found the consequence -- the website could learn leadership only from the board's single `leader` field, so it could name exactly one leader while a UO guild routinely has several, and TEAMS.md §2.5 treats multiple leaders as the normal case. Roster members now carry `rank` (0-4, 4 being Leader) plus `rankCliloc`, or `rankName` where a shard's custom rank definitions use literal names. Rank is on roster members only -- it is a property of a mobile's membership of THIS guild, not of the mobile, and every other actor the bridge writes is a bystander, a killer or a governor. Both files carry the trap this found, because it is the kind of thing a consumer gets wrong silently: **`PlayerMobile.GuildRank` returns Leader for anyone at GameMaster or above, whatever their real rank.** It is a gameplay convenience so staff can operate a guild stone, and the true value has no accessor -- so the bridge omits the rank entirely for a staff account rather than publish a leadership claim it knows is false. An absent rank therefore means "not known", and a consumer must read it as neither 0 (which silently demotes them) nor leadership (which republishes the lie). INTEGRATION.md also states the other half plainly for an outside integrator: `guild.update`'s single `leader` is the founder-leader, not the set of leaders, so "who leads this guild" is a read of the roster's ranks. Recorded too: the sidecar needs no change and no store migration, because it treats roster members as opaque values and never reads a field inside one. That is the forwarder design paying off, and it is worth having written down the next time someone adds a member field. Pairs with servuo-plugins (the emitter) and Module-uo (the ingest and the provider). Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
@@ -286,11 +286,18 @@ Guilds expose only one in-game event (a member joining), so the roster is polled
|
||||
| `guild.update` | `id`, `name`, `abbr`, `members`, `online`, `alliance` (or null), `leader` (actor object or null) | A guild's leader/alliance/name changed, its member count moved, or its first sight this connection. |
|
||||
| `guild.remove` | `id` | The guild disbanded (leader gone) or was removed. Drop the row. |
|
||||
| `guild.join` | `id`, `name`, `abbr`, `who` (actor object) | Real-time: a player joined a guild (`EventSink.JoinGuild`). |
|
||||
| `guild.roster` **(4)** | `id`, `name`, `abbr`, `total`, `seq`, `more`, `members` (array of actor objects) | The full member list. Emitted whenever the member set changes. **`seq` 0 supersedes whatever roster you hold for that guild; `more: false` ends it.** |
|
||||
| `guild.roster` **(4)** | `id`, `name`, `abbr`, `total`, `seq`, `more`, `members` (array of actor objects **carrying rank**) | The full member list. Emitted whenever the member set changes. **`seq` 0 supersedes whatever roster you hold for that guild; `more: false` ends it.** |
|
||||
| `guild.leave` **(4)** | `id`, `name`, `who` (serial string) | Real-time: a member left. Advisory — see below. |
|
||||
|
||||
The `leader`/`who` **actor object** is `{serial, name, acct?, webId?, player}` — `acct`/`webId` present when the mobile has an account / a linked website user. Note `guild.leave`'s `who` is a bare **serial string**, not an actor object: the mobile has already left, so there is nothing to attribute.
|
||||
|
||||
**A roster member carries rank as well.** `rank` is 0–4 with 4 being Leader, plus `rankCliloc` (the cliloc the game names that rank with) or `rankName` when a shard uses custom rank definitions with literal names. Only the raw rank is sent: ServUO ships no text for those clilocs, so turning 1062960 into "Warlord" is the consumer's job.
|
||||
|
||||
Two things to get right, both of which bite:
|
||||
|
||||
- **Several members can hold rank 4.** `guild.update`'s single `leader` is the guild's founder-leader; it is not the set of leaders. If you need "who leads this guild", read the roster's ranks and treat `leader` as one more entry rather than the answer.
|
||||
- **An absent `rank` means "not known" — never 0, and never leadership.** It has one deliberate cause: `PlayerMobile.GuildRank` reports Leader for any account at GameMaster or above whatever their real rank, so the bridge omits the rank for staff rather than publishing a claim it knows is false. Defaulting a missing rank to 0 silently demotes them; reading absence as leadership republishes exactly the lie the bridge avoided.
|
||||
|
||||
**On Protocol 4.** Before it, a guild's membership was a *count* and a leave surfaced only as that count dropping. `guild.roster` carries the members themselves, and `guild.leave` names who went.
|
||||
|
||||
`guild.leave` is **advisory**: any change to the member set re-emits the whole roster, so a consumer holding a membership table stays correct even if it ignores every leave event. Handle it when you want a "so-and-so left" feed to update without waiting for the sweep.
|
||||
|
||||
Reference in New Issue
Block a user