acdream/docs/research/deepdives/r11-allegiance.md

R11 — Allegiance System Deep Dive

Scope: patron / vassal tree, swearing + breaking, XP pass-up, rank, chat channels (@a / @v / @p / @m / @c), MOTD, allegiance houses, officer permissions, wire messages, UI panel.

Authorities (in order of trust, per CLAUDE.md hierarchy):

• Retail acclient.exe decompiled — docs/research/decompiled/chunk_00570000.c, chunk_00560000.c, chunk_005B0000.c, chunk_005D0000.c, chunk_00580000.c, chunk_006B0000.c. Client-side strings, channel bitmasks, error paths, UI hooks.
• ACE server — references/ACE/Source/ACE.Server/Entity/AllegianceNode.cs, AllegianceRank.cs, Managers/AllegianceManager.cs, WorldObjects/Allegiance.cs, WorldObjects/Player_Allegiance.cs, Network/GameEvent/Events/Allegiance*.cs, Network/Structure/AllegianceData.cs, Network/Structure/AllegianceHierarchy.cs, Network/Structure/AllegianceProfile.cs, Network/Enum/AllegianceIndex.cs. Full server-side implementation of the system, plus the exact wire-format writer.
• Asheron Wikia / Fandom wiki — cited inline in AllegianceManager.cs (ranking, XP passup formulas). This is the documented retail behavior ACE codes against.

acdream is a client, so our primary job is:

1. Decode inbound AllegianceUpdate / AllegianceInfoResponse packets into an in-memory allegiance tree.
2. Render the tree as a UI panel.
3. Construct and send the outbound GameActions (SwearAllegiance, BreakAllegiance, AllegianceInfoRequest, officer commands, MOTD commands, etc).
4. Handle the five allegiance-related chat channels correctly.

We do not compute pass-up XP — that is server-authoritative. But we document the formula anyway so the acdream server-adjacent code (mock server for testing, plugin API exposing it) can match retail.

---

1. Tree structure

1.1 Data model

From AllegianceNode.cs:

class AllegianceNode {
    ObjectGuid PlayerGuid;        // this node's player
    AllegianceNode Monarch;       // top of tree (self for monarch)
    AllegianceNode Patron;        // direct parent; null for monarch
    Dictionary<uint, AllegianceNode> Vassals;  // direct children
    uint Rank;                    // 0-10
    bool IsMonarch => Patron == null;
}

Every player in an allegiance has exactly:

• one monarch (root of the tree; MonarchId player property)
• one patron (direct parent; PatronId player property; null for monarch)
• 0 to 11 direct vassals (children; capped, see below)

The tree is reconstructed each time any member swears or breaks by walking every online/offline player who reports the same MonarchId and threading the PatronId -> Vassals links. See AllegianceManager.Rebuild and Allegiance.BuildPatronVassals.

1.2 Breadth cap

Max direct vassals: 11. From Player_Allegiance.cs::IsPledgable:

if (targetNode.TotalVassals >= 11) {
    Session.Network.EnqueueSend(new GameMessageSystemChat(
        $"{target.Name} already has the maximum # of vassals",
        ChatMessageType.Broadcast));
    return false;
}

This corresponds to retail error 0x416 seen in the decompiled client: L"%s cannot have any more Vassals".

1.3 Depth cap

There is no hard-coded depth cap in either the retail client strings or ACE's enforcement. The effective cap comes from Rank, which is clamped at 10 (see §4). Practically, once ranks get deep enough the tree can keep extending downward indefinitely; the rank value just stops climbing.

1.4 Loop prevention

A monarch cannot swear back into their own subtree:

if (selfNode != null && selfNode.IsMonarch) {
    if (selfNode.PlayerGuid == targetNode.Monarch.PlayerGuid) {
        // refuse
    }
}

This is the only cycle guard — and it only fires when the self side is currently a monarch. It prevents A->B->A directly, but the same check is implicitly satisfied elsewhere because once you are a vassal you cannot swear at all (§2.3).

1.5 Counts

• TotalVassals = count of direct children.
• TotalFollowers = recursive sum (vassals of vassals…). Used for the wire-level totalVassals field in the allegiance profile, and for rank display counts.
• TotalMembers = from the allegiance root, full tree size.

---

2. Swearing and breaking

2.1 Swear flow (client -> server)

Opcode: GameActionType.SwearAllegiance = 0x001D.

The client sends a single 4-byte payload: the target patron's guid.

struct SwearAllegianceRequest {
    uint32_t targetPatronGuid;
};

Server-side handler (Player_Allegiance.cs::HandleActionSwearAllegiance):

1. Look up target. Must be online.
2. Run IsPledgable(patron). Checks (in order):
   • Self not Olthoi, target not Olthoi.
   • Target hasn't set CharacterOption.IgnoreAllegianceRequests (which is "@allegiance ignore" in retail).
   • Self doesn't already have a patron (PatronId != null).
   • Target is not self.
   • Target has < 11 direct vassals.
   • Self is not already in target's allegiance tree (no loops).
   • If allegiance is locked: either self is in ApprovedVassals, or target is a Castellan+ officer.
   • Self is not in target's ban list.
   • Self does not own a monarch-only house (mansion). If they do: error 0x??? via WeenieError.CannotSwearAllegianceWhileOwningMansion.
3. Create a MoveToChain toward the patron at Allegiance_MaxSwearDistance = 2.0f (retail). ACE has 4.0 commented out — retail is the tighter 2.0 meters. After the move succeeds, run SwearAllegiance(...).
4. SwearAllegiance:
   • Send a Confirmation_SwearAllegiance to the target first. Target must click yes.
   • On confirmation: set PatronId, walk up to get MonarchId, set both as PropertyInstanceId.Monarch.
   • Set ExistedBeforeAllegianceXpChanges iff patron's level >= own level (only equal-or-higher patrons can pass XP up in the post-2004 system — see §3.2).
   • If self was previously a monarch with vassals, walk the subtree and update every child's MonarchId to the new monarch. Clear officers in the old allegiance (HandleMonarchSwear).
   • Broadcast Motion_Kneel (kneeling animation).
   • Rebuild the allegiance tree (AllegianceManager.OnSwearAllegiance).
   • Reset AllegianceXPGenerated = 0, AllegianceOfficerRank = null.
   • Send GameEventAllegianceUpdate + GameEventAllegianceAllegianceUpdateDone.
   • Join Turbine chat channel "Allegiance" if the option is enabled.

2.2 Cooldown?

There is no 24-hour cooldown on swearing itself. Looking at both ACE and the decompiled strings:

• ACE: HandleActionSwearAllegiance → IsPledgable → SwearAllegiance. No timestamp check.
• Decompiled: error set 0x40B-0x416 covers the swear failure modes (already sworn, not enough XP, not in allegiance, already maxed vassals). No cooldown error.

There IS a 24-hour cooldown on allegiance name changes (see §7.3). The "break once a day" player folklore is not reflected in the code; the only cost to break is a generic 3-second animation. Players frequently re-swore the same day, and the client/server permit it.

The wikia does mention a "1 hour cooldown" on /allegiance house open after closing. Searching ACE, I don't see this enforced explicitly.

2.3 Break flow (client -> server)

Opcode: GameActionType.BreakAllegiance = 0x001E.

Payload is again a single uint32 guid (the patron OR vassal you're breaking from). Handler (Player_Allegiance.cs::HandleActionBreakAllegiance):

1. IsBreakable(targetGuid) — target exists and is either self's patron (PatronId == target.Guid.Full) or one of self's vassals (target.PatronId == Guid.Full). Anything else: silent refuse.
2. If breaking from vassal:
   • Target's PatronId = null.
   • Target's MonarchId becomes self OR null depending on whether target has vassals themselves (new fragment root vs solo player).
   • Walk target's subtree and reset every descendant's MonarchId to the target.
3. If breaking from patron:
   • Self's PatronId = null, MonarchId = null.
   • Walk self's subtree and reset every descendant's MonarchId to self (self is the new fragment monarch).
4. Messages:
   • To target: "{Name} has broken their Allegiance to you!"
   • To self: "You have broken your Allegiance to {target.Name}!"
5. Rebuild both allegiances.
6. Check the allegiance house — boot self and/or target if they lost mansion access (CheckAllegianceHouse).
7. Send GameEventAllegianceUpdate + done.

2.4 Involuntary separation

• Boot (GameActionType.BreakAllegianceBoot = 0x0277, Seneschal+ required): remove one member + their subtree. Error strings include L"Your Allegiance has been dissolved!\n" and L"Your patron\'s Allegiance to you has been broken!\n" (errors 0x??? and 0x??? per decompiled chunk_00570000 lines 1944-1948).
• Ban (AddAllegianceBan = 0x02A1): prevents future swearing and kicks if already a member.
• Player delete: AllegianceManager.HandlePlayerDelete collapses a patron out of the tree; vassals each become their own new monarch.

---

3. XP pass-up formula

This is the most complex part of the system. From AllegianceManager.cs (quoted verbatim) + wiki references:

3.1 Two epochs

Pre-patch (before January 12 2004): Used a complex formula based on the Self attribute, loyalty/leadership caps, with an effective Loyalty of 175 being enough to max patron-to-grandpatron passup. Only kill XP passed up. ACE does not implement this and acdream doesn't need to.

Post-patch (2004 onward, extended October 2009 to all XP): Simpler formula, decoupled from Self. This is what retail ran during its final years and what ACE emulates.

3.2 Eligibility gate — ExistedBeforeAllegianceXpChanges

This flag is confusingly named — it's really "can this vassal pass XP up?" From Player_Allegiance.cs line 105:

ExistedBeforeAllegianceXpChanges = (patron.Level ?? 1) >= (Level ?? 1);

At swear time, if your patron's level is less than yours, you are flagged as not passing XP. The flag flips on when your patron levels above you (AllegianceNode.OnLevelUp). This prevents a low-level player from being used as a "dummy patron" above a high-level farmer.

If this flag is false, no XP passes up from that vassal at all (DoPassXP early-outs before any calculation).

3.3 The formula

From the comment block in AllegianceManager.cs (verbatim, cited to http://asheron.wikia.com/wiki/XP_Passup, "Xerxes of Thistledown, four months of testing"):

Generated% = 50.0 + 22.5 * (Loyalty    / 291) * (1.0 + (RT  / 730) * (IG  / 720))
Received%  = 50.0 + 22.5 * (Leadership / 291) * (1.0 + V * (RT2 / 730) * (IG2 / 720))
Passup%    = Generated% * Received% / 100

Where:

Variable	Meaning	Cap
Loyalty	Buffed Loyalty skill on vassal	291
Leadership	Buffed Leadership skill on patron	291
RT	Real-world days vassal has been sworn to patron	730
IG	In-game hours vassal has been sworn to patron	720
RT2	Avg real days patron's vassals sworn to patron	730
IG2	Avg in-game hours patron's vassals sworn	720
V	Vassal-count factor: 1→0.25, 2→0.50, 3→0.75, 4+→1.00	1.00

Ranges:

• Generated% from 50% (new swear, zero loyalty) up to ~90% (long-term, maxed loyalty). This is the fraction deducted from the vassal's earned XP — not literally taken from them, but computed for the passup calculation.
• Received% from 50% up to ~90% similarly.
• Passup% from 25% to 90% of the vassal's earned XP.

3.4 Recursion (ultrathink — this is the "fraction scales with depth")

Grandpatron pass-up. When vassal V earns N XP, patron P gets N * Passup%(V,P). Then P's patron (grandpatron GP) gets a share of what P received, not of the original N.

But the recursion uses different constants:

private static void DoPassXP(vassalNode, amount, bool direct)
{
    ...
    var factor1 = direct ? 50.0f : 16.0f;
    var factor2 = direct ? 22.5f : 8.0f;
    ...
    // recursive call with direct = false
    DoPassXP(patronNode, passupAmount, false);
}

So the grandpatron formula is:

Generated_indirect% = 16 + 8 * (Loyalty    / 291) * (1.0 + (RT  / 730) * (IG  / 720))
Received_indirect%  = 16 + 8 * (Leadership / 291) * (1.0 + V * (RT2 / 730) * (IG2 / 720))
Passup_indirect%    = Generated_indirect% * Received_indirect% / 100

Caps: Generated% from 16% to 24%, Received% likewise. So Passup_indirect% is bounded roughly from 0.16 * 0.16 = 2.56% up to 0.24 * 0.24 = 5.76% in the "direct"-scale interpretation. Against the wiki's stated 0%–10% range, that checks out (the wiki's 10% max is the "max leadership + max time" scenario, matching 0.24²·~1.73 = ~10% when you account for the full time/vassal multiplier being close to 2).

This fraction scales per generation: a tier-3 passup is Direct * Indirect ≈ 0.9 * 0.1 = 9% at maximum, or 0.25 * 0 = 0% at minimum. Deep trees don't feed the monarch much in practice — the interesting XP is at direct patron level, which is why retail players optimized around 2-3 deep at most.

The recursion terminates when patronNode == null (i.e., we hit the monarch, who has no patron).

3.5 Earning side

When a vassal gains XP (via GrantXP), the amount is passed to AllegianceManager.PassXP(vassalNode, amount, direct=true):

• generated fraction is added to vassal's AllegianceXPGenerated (tracked for player "tithed" stat).
• passup fraction is added to patron's AllegianceXPCached.
• If patron is online: they immediately redeem the cached XP via AddAllegianceXP() (which grants it with XpType.Allegiance).
• If patron is offline: XP accumulates and is granted on next login (with login message "Your Vassals have produced experience points for you…").

3.6 ACE simplifications

ACE's implementation currently uses capped constants for the time modifiers:

var timeReal = Math.Min(RealCap, RealCap);  // = RealCap
var timeGame = Math.Min(GameCap, GameCap);  // = GameCap

i.e., it always treats every vassal as "maxed time". This is a known simplification; to fully match retail, the server needs to track TimeSwornToPatron per vassal and compute actual RT/IG values. For our client work this doesn't matter — we don't compute passup, we just read AllegianceXPCached, AllegianceXPGenerated, AllegianceXPReceived from packets.

---

4. Rank

From AllegianceNode.cs::CalculateRank (cited to http://asheron.wikia.com/wiki/Rank):

A player's allegiance rank is a function of the number of Vassals and how they are organized. First, take the two highest ranked vassals. Now the Patron's rank will either be one higher than the lower of the two, or equal to the highest rank vassal, whichever is greater.

var sortedVassals = Vassals.Values.OrderByDescending(v => v.Rank).ToList();
var r1 = sortedVassals.Count > 0 ? sortedVassals[0].Rank : 0;
var r2 = sortedVassals.Count > 1 ? sortedVassals[1].Rank : 0;

var lower  = Math.Min(r1, r2);
var higher = Math.Max(r1, r2);

Rank = Math.Min(10, Math.Max(lower + 1, higher));

• Starting rank: 0 (or 1 depending on interpretation — a lone sworn member with no vassals gets rank 0 here, and AllegianceTitle returns "" for rank 0; rank 1 kicks in when you have one vassal).
• Max rank: 10 (the "High King" / "Aulin" / "Tah" tier).
• Rank 9 requires a "Fibonacci-like" branching structure — two vassals of rank 8 each, or one rank 9 + one rank 8.

4.1 Rank progression table

Approximate minimum-tree sizes to reach each rank:

Rank	Tree structure	Name (Aluvian Male)
0	solo / brand new (no vassals)	—
1	1 direct vassal	Yeoman
2	2 vassals at rank 1	Baronet
3	2 vassals at rank 2	Baron
4	2 vassals at rank 3	Reeve
5	2 vassals at rank 4	Thane
6	2 vassals at rank 5	Ealdor
7	2 vassals at rank 6	Duke
8	2 vassals at rank 7	Aetheling
9	2 vassals at rank 8	King
10	2 vassals at rank 9	High King

With an 11-vassal cap, each rank level roughly doubles the tree size minimum, so rank 10 requires a ~2^10 = 1024 member tree at minimum (ignoring the "higher" branch).

4.2 Heritage-gendered titles

Each of 9 heritages × 2 genders = ~18 title tables, each with 10 rank strings. See AllegianceTitle.cs lines 80-384 for the full table (Aluvian, Gharundim, Sho, Viamontian, Shadowbound/Penumbraen, Tumerok (gender-neutral), Gearknight (gender-neutral), Lugian (gender-neutral), Empyrean, Undead).

acdream will copy this table byte-for-byte — these are the exact strings retail displays on the allegiance panel and in tells/broadcasts.

---

5. Chat channels

Five logical channels, visible through distinct prefixes in the retail client. Searched chunk_00570000.c for the exact prefix strings:

Logical	Client prefix (from decompile)	ChatMessageType flag	Command
Allegiance	"[Allegiance Broadcast] You say, \""	0x2000000	@a / broadcast
Co-Vassals	"[Co-Vassals] You say, \""	0x1000000	@c
Patron tell	"Your patron <Tell:...> says to you, \""	0x1000	@p
Vassal tell	"Your vassal <Tell:...> says to you, \""	0x2000	@v
Follower tell	"Your follower <Tell:...> says to you, \""	0x4000	@m (monarch)

From chunk_00570000.c around line 700-810, the client dispatches chat input by comparing piVar4 (channel mask) to these hex values.

Additionally chunk_006B0000.c::FUN_006b1460 maps the string "Allegiance" to ChatMessageType 0x12 (18). That's the server-side enum value; the 0x1000000 etc. above are per-send client-side flag bits used to choose a prefix.

5.1 Channel permissions

• @v (vassal tell): send to one specific direct vassal. Only works if target is currently your vassal.
• @p (patron tell): send to your patron. Only works while you have a patron.
• @m (monarch tell): send to your monarch. @mr replies to last @m "only works for monarchs" — i.e., the monarch's receive side is special because many vassals can @m them.
• @c (co-vassals): broadcast to all peers with the same direct patron as you. Decompiled at chunk_00570000.c:707.
• @a / allegiance broadcast: whole allegiance tree. Subject to gag/boot filters. The decompiled strings at line 2991-3005 cover the gag/un-gag notifications.

5.2 Gag / boot

• HandleActionAllegianceChatGag / Boot: Speaker+ permission.
• ChatFilters: Dictionary<ObjectGuid, DateTime> — timestamp of when the filter expires. DateTime.MaxValue means permanent boot.
• Allegiance.IsFiltered(playerGuid) checks and auto-removes expired filters.
• Gag duration: Player.AllegianceChat_GagTime = TimeSpan.FromMinutes(5).

5.3 "Listen to allegiance chat" option

CharacterOption.ListenToAllegianceChat — if set, player joins the turbine chat channel "Allegiance" on swear and login, leaves on break. This is how cross-landblock allegiance chat works retail-side (Turbine chat room backplane).

---

6. Allegiance house / mansion

Mansions (and some villas) can be flagged HouseRequiresMonarch — only rank-N+ monarchs can purchase them, and they function as allegiance houses where vassals gain access.

6.1 Purchase restrictions

From the decompiled client (chunk_00570000.c:1516):

• L"You must be a monarch to purchase this dwelling.\n" (error 0x48a)
• L"You must be above level %s to purchase this dwelling.\n" (0x488)
• L"You must be at or below level %s to purchase this dwelling.\n" (0x489)
• L"You must be above allegiance rank %s to purchase this dwelling.\n" (~0x476)
• L"You must be at or below allegiance rank %s to purchase this dwelling.\n" (~0x477)

These are the 5 gates: monarch-status, level-min, level-max, rank-min, rank-max. Level/rank thresholds come from the SlumLord weenie.

6.2 Allegiance access

Action enum from AllegianceHouseAction.cs:

enum AllegianceHouseAction : uint {
    Undef        = 0,
    Help         = 1,
    CheckStatus  = 1,  // "@allegiance house help" is alias for check
    GuestOpen    = 2,
    GuestClose   = 3,
    StorageOpen  = 4,
    StorageClose = 5,
}

Only Castellan+ can toggle (AllegiancePermissionLevel.Castellan).

6.3 Sanctuary / hometown recall

Monarch can set a bindstone for the whole allegiance. Stored as Allegiance.Sanctuary (a Position). Vassals recall via GameActionType.RecallAllegianceHometown = 0x02AB, which fires MotionCommand.AllegianceHometownRecall animation and teleports.

6.4 Booting members

When a player swears away, breaks, or gets booted from allegiance, any mansion access they had is revoked (Player.CheckAllegianceHouse).

---

7. MOTD and allegiance name

7.1 MOTD

Stored on the Allegiance worldobject as AllegianceMotd + AllegianceMotdSetBy (string properties). On each login (after a 3s delay) the client receives it as a system chat message:

"\"{motd}\" -- {setBy}"

• Set: HandleActionSetMotd (Speaker+)
• Clear: HandleActionClearMotd (Speaker+)
• Query: HandleActionQueryMotd (anyone in allegiance)
• Server sends via GameMessageSystemChat, not via GameEventAllegiance*.

Decompiled client error strings around line 2068 include L"Please use the allegiance panel to view your own information.", meaning the client recognizes an allegiance-info request against self and redirects to the panel.

7.2 Allegiance name

AllegianceName (string property on the Allegiance object). Castellan+ only. Validation rules (per decompiled error strings 2883-2912):

• Not empty (command is @allegiance name clear for that).
• Max 40 chars.
• Only letters, spaces, -, '.
• Not in banned-words list from portal.dat.
• Not duplicate of another allegiance's name.
• Change cooldown: once every 24 hours (L"You may only change your allegiance name once every 24 hours. You may change your allegiance name again in %s.\n").

7.3 Officer titles

Rank 1/2/3 → Speaker/Seneschal/Castellan by default. Castellans can rename them via SetAllegianceOfficerTitle (rank: 1-3, string title).

---

8. Officer permissions

From Player_Allegiance.cs lines 1478-1517 and AllegiancePermissionLevel.cs:

Level (enum)	Numeric	Powers
None	0	member, no powers
Speaker	1	allegiance chat kick/gag; allegiance broadcast; set/clear MOTD
Seneschal	2	promote/demote Speakers; boot; ban; allegiance info; lock/unlock
Castellan	3	promote/demote any rank; rename titles; set allegiance name; bindstone; mansion permissions; bypass lock with approved vassals
Monarch	4	all of the above; clear all officers; everything

AllegianceOfficerLevel (wire enum, uint32): Undef=0, Speaker=1, Seneschal=2, Castellan=3. Monarch is implicit (Monarch doesn't have an officer rank; they're the root).

Promote: SetAllegianceOfficer(playerName, level) — Seneschal+ (with caveat Seneschal can only promote to rank 1).

Officer count limits: seen in decompile line 2738 L"You already have the maximum number of allegiance officers. You must remove some before you add any more.\n". ACE doesn't implement a cap. Retail may have had one (~12?) but it's not enforced in ACE and no hard number appears in strings.

---

9. Wire messages

9.1 Server -> client events

From GameEventType.cs:

Event	Opcode	Sent when
AllegianceUpdateAborted	0x0003	Operation cancelled (e.g., target declined swear)
AllegianceUpdate	0x0020	Full tree refresh (panel open, swear, break)
AllegianceAllegianceUpdateDone	0x01C8	End-of-stream marker after AllegianceUpdate
AllegianceLoginNotification	0x027A	Ally logged in/out (if listen option on)
AllegianceInfoResponse	0x027C	Reply to AllegianceInfoRequest

9.2 AllegianceUpdate payload

From GameEventAllegianceUpdate.cs + AllegianceProfile + AllegianceHierarchy + AllegianceData:

GameEventAllegianceUpdate {
    uint32_t rank;           // receiving player's rank
    AllegianceProfile prof;  // tree
}

AllegianceProfile {
    uint32_t totalMembers;   // whole allegiance (monarch + all followers)
    uint32_t totalVassals;   // self's direct+indirect followers
    AllegianceHierarchy hierarchy;
}

AllegianceHierarchy {
    uint16_t recordCount;    // number of ALL tree entries sent
    uint16_t oldVersion;     // 0x000B (latest / only supported)
    PHashTable<Guid, uint32> officers;   // empty in retail, present for parser compat
    uint32_t officerTitleCount;
    WideString[] officerTitles;
    uint32_t monarchBroadcastTime;
    uint32_t monarchBroadcastsToday;
    uint32_t spokesBroadcastTime;
    uint32_t spokesBroadcastsToday;
    WideString motd;          // EMPTY in ACE to avoid decal parse bugs; retail sent it
    WideString motdSetBy;     // EMPTY in ACE
    uint32_t chatRoomID;      // allegiance biota ID (chat channel)
    Position bindPoint;       // sanctuary/bindstone (cell + pos + rot)
    WideString allegianceName;
    uint32_t nameLastSetTime; // "counts upward for some reason"
    uint32_t isLocked;        // 0 or 1
    int32_t approvedVassal;   // legacy field (always 0?)
    AllegianceData monarchData;          // first record: the monarch
    (Guid treeParent, AllegianceData)[recordCount-1] records;
}

AllegianceData {
    uint32_t characterID;
    uint32_t cpCached;       // AllegianceXPCached clamped to uint32 max
    uint32_t cpTithed;       // AllegianceXPGenerated
    uint32_t bitfield;       // AllegianceIndex flags
    uint8_t  gender;
    uint8_t  heritage;
    uint16_t rank;
    // if HasPackedLevel(0x8):
    uint32_t level;
    uint16_t loyalty;
    uint16_t leadership;
    // if HasAllegianceAge(0x4):
    uint32_t timeOnline;
    uint32_t allegianceAge;
    // else:
    uint64_t uTimeOnline;
    WideString name;
}

Per AllegianceHierarchy.cs comments (aclogview-derived):

• record 0 = monarch (no treeParent guid prefix, sent inline)
• record 1 = self's patron (treeParent = monarch)
• record 2 = self (treeParent = patron)
• record 3+ = self's direct vassals (treeParent = self)

This is a compact slice centered on the receiving player — NOT the whole tree. To show the whole tree, the client aggregates successive updates by walking up/down via AllegianceInfoRequest.

9.3 Bitfield (AllegianceIndex)

[Flags] enum AllegianceIndex : uint {
    Undefined           = 0x00,
    LoggedIn            = 0x01,
    Update              = 0x02,
    HasAllegianceAge    = 0x04,
    HasPackedLevel      = 0x08,
    MayPassupExperience = 0x10,
}

Sent with HasAllegianceAge | HasPackedLevel baseline; LoggedIn added if player is online; MayPassupExperience for non-monarch vassals with ExistedBeforeAllegianceXpChanges flag.

9.4 Client -> server actions

From GameActionType.cs:

GameAction	Opcode	Payload
SwearAllegiance	0x001D	uint32 patronGuid
BreakAllegiance	0x001E	uint32 targetGuid
AllegianceUpdateRequest	0x001F	uint32 uiPanelBool
QueryAllegianceName	0x0030	(empty)
ClearAllegianceName	0x0031	(empty)
SetAllegianceName	0x0033	string16L name
SetAllegianceOfficer	0x003B	string16L name, uint32 level
SetAllegianceOfficerTitle	0x003C	uint32 rank, string16L title
ListAllegianceOfficerTitles	0x003D	(empty)
ClearAllegianceOfficerTitles	0x003E	(empty)
DoAllegianceLockAction	0x003F	uint32 AllegianceLockAction
SetAllegianceApprovedVassal	0x0040	string16L name
AllegianceChatGag	0x0041	string16L name, uint32 bool
DoAllegianceHouseAction	0x0042	uint32 AllegianceHouseAction
ModifyAllegianceGuestPermission	0x0267	…
ModifyAllegianceStoragePermission	0x0268	…
BreakAllegianceBoot	0x0277	string16L name, uint32 bool
AllegianceInfoRequest	0x027B	string16L playerName
AllegianceChatBoot	0x02A0	string16L name, string16L reason
AddAllegianceBan	0x02A1	string16L name
RemoveAllegianceBan	0x02A2	string16L name
ListAllegianceBans	0x02A3	(empty)
RemoveAllegianceOfficer	0x02A5	string16L name
ListAllegianceOfficers	0x02A6	(empty)
ClearAllegianceOfficers	0x02A7	(empty)
RecallAllegianceHometown	0x02AB	(empty)

9.5 ConfirmationType.SwearAllegiance

Swearing is two-phase: target gets a Confirmation_SwearAllegiance request. They must click Yes/No. The response comes back as a GameAction confirmation type; ACE routes it through the ConfirmationManager. acdream's client side needs to render the confirmation dialog.

---

10. UI panel

The retail client's Allegiance tab (one of the main UI panels, reachable via a bottom-bar icon) shows:

• Header: allegiance name + MOTD.
• Patron row (above center): icon + name + rank/title.
• Self row (center): highlighted; shows rank, level, loyalty, leadership, CP tithed, CP received.
• Vassal rows (below center): each with login-status indicator (* for online, per retail text "An asterisk (*) indicates that the character is currently online"), rank, name, optional level.
• Buttons: Swear (disabled if already sworn), Break (only if patron present), View (opens info request), View Monarch, Bindstone recall (if allegiance has a sanctuary).

Clicking a member fires AllegianceInfoRequest → server responds with a wider AllegianceInfoResponse, which the client renders as the member's own node + their vassals (same record format).

Navigation: the client supports walking up (click patron) and down (click vassal) to view the whole tree piecewise. The server always sends the 3-generation slice centered on the queried player: patron, self, direct vassals.

10.1 Client commands (text input)

From decompile chunk_00570000 lines 6834-6852 (help output):

• @help allegiances — overview.
• @allegiance — allegiance commands menu.
• @allegiance motd [text] — set/clear MOTD (same as @motd).
• @allegiance swear <name> — alternative to right-click swear.
• @allegiance break [name] — break from patron/vassal.
• @allegiance boot <name> [account] — Seneschal+.
• @allegiance chat gag <name> / ungag — Speaker+.
• @allegiance chat kick <name> <reason> — Speaker+ (permanent).
• @allegiance ban add/remove/list — Seneschal+.
• @allegiance lock on/off/toggle/check — Seneschal+.
• @allegiance approved add/clear/check — Castellan+.
• @allegiance name [new]/clear/? — Castellan+.
• @allegiance officer <title|rank> <level> <name> — Seneschal+/Castellan+.
• @allegiance officers list/clear/titles — members see list; Seneschal+ manage.
• @allegiance house help/guest/storage open/close — Castellan+.
• @allegiance hometown — recall.
• @allegiance ignore on/off — per-player flag (CharacterOption.IgnoreAllegianceRequests).
• @allegiance info <name> — detailed info on specific member.

10.2 Chat shortcuts

• @a <text> — allegiance broadcast.
• @c <text> — co-vassals.
• @v <name> <text> — tell one vassal.
• @p <text> — tell patron.
• @pr <text> — reply to last @p.
• @m <text> — tell monarch.
• @mr <text> — monarch reply to last @m.

---

11. Port plan for acdream

11.1 Data types (src/acdream.core / acdream.protocol)

public readonly record struct AllegianceGuid(uint Value);

public sealed class AllegianceNode {
    public AllegianceGuid PlayerGuid { get; init; }
    public string Name { get; init; } = "";
    public HeritageGroup Heritage { get; init; }
    public Gender Gender { get; init; }
    public uint Rank { get; set; }
    public uint Level { get; set; }
    public ushort Loyalty { get; set; }
    public ushort Leadership { get; set; }
    public ulong AllegianceXPCached { get; set; }
    public ulong AllegianceXPGenerated { get; set; }
    public bool IsLoggedIn { get; set; }
    public bool MayPassupExperience { get; set; }
    public TimeSpan TimeOnline { get; set; }
    public TimeSpan AllegianceAge { get; set; }

    public AllegianceNode? Patron { get; set; }
    public List<AllegianceNode> Vassals { get; } = new();

    public bool IsMonarch => Patron is null;

    // Retail rank algorithm (AllegianceNode.cs:69-88).
    public void RecalculateRank() { ... }
}

public sealed class AllegianceTree {
    public AllegianceNode Monarch { get; private set; }
    public AllegianceNode Self { get; private set; }
    public string? AllegianceName { get; set; }
    public string? Motd { get; set; }
    public string? MotdSetBy { get; set; }
    public Position? BindPoint { get; set; }
    public bool IsLocked { get; set; }
    public uint ChatRoomId { get; set; }

    public void ApplyUpdate(AllegianceUpdatePacket pkt) { ... }
    public void ApplyInfoResponse(AllegianceInfoPacket pkt) { ... }
}

11.2 Wire codecs (src/acdream.protocol.events)

Port AllegianceData, AllegianceHierarchy, AllegianceProfile as pure C# readers — reverse of ACE's Writer classes. Cross-reference against references/Chorizite.ACProtocol/Types/ for field-order confirmation.

Event handlers to register with the dispatcher:

• 0x0003 AllegianceUpdateAborted
• 0x0020 AllegianceUpdate
• 0x01C8 AllegianceAllegianceUpdateDone (just acks end of update, can trigger UI redraw)
• 0x027A AllegianceLoginNotification (update online status in tree)
• 0x027C AllegianceInfoResponse

11.3 Outbound actions (src/acdream.protocol.actions)

One builder per GameAction listed in §9.4. Match the payload layouts exactly. Test round-trip against captured retail pcaps if available (none in repo currently; treat ACE's writer as ground truth in the meantime).

11.4 UI panel (src/acdream.ui.allegiance)

Following the architecture doc's component pattern:

public sealed class AllegiancePanel : IUiPanel {
    private readonly AllegianceTree _tree;
    private readonly IPlayerNetworkClient _net;

    public void Render(ImDrawList draw) {
        // Header: name + motd
        // Patron row (tinted, above center)
        // Self row (highlighted, center)
        // Vassal list (indented, below center)
        // Buttons: Swear / Break / Info / Recall
    }

    public void OnClickNode(AllegianceGuid guid)
        => _net.SendGameAction(new AllegianceInfoRequestAction(name));
}

Title strings: port the full AllegianceTitle table verbatim — all 18 heritage/gender variants.

11.5 Chat integration

Extend the chat layer (R6/UI slice 05) to handle the five channel prefixes. Channel routing:

• Inbound: match ChatMessageType enum value 0x12 ("Allegiance") for allegiance broadcasts; prefix by [Allegiance] in the render.
• Outbound: when user types @a ..., map to broadcast; @c, @v <name>, @p, @m each go to a specific recipient guid via directed chat (text + flag bits per §5).
• Gag/boot filter: client honors no filter state locally — server does the enforcement — but if gagged, client should gray out the "send to allegiance chat" button and show a status line.

11.6 MOTD hook

Subscribe to GameMessageSystemChat containing the MOTD pattern ("…" -- …) and also proactively request via QueryAllegianceName when opening the panel. Cache in AllegianceTree.Motd.

11.7 Testing strategy

1. Conformance tests: build an allegiance tree programmatically and check rank calculation matches ACE's algorithm on edge cases (solo, 1-chain, 11-branch wide, 10-deep narrow).
2. Wire round-trip: given an AllegianceHierarchy writer output from a mocked ACE server, decode it with acdream's reader and verify all fields match.
3. Title table: parameterized test asserting every (heritage, gender, rank) pair matches the retail string in AllegianceTitle.cs.
4. Channel routing: feed synthetic chat-flag bytes (0x1000, 0x2000, 0x4000, 0x1000000, 0x2000000) into the parser; verify they produce the correct prefix and channel tag.

11.8 Phasing

This is a later-phase feature — not needed for R1 (terrain render) or R2 (basic movement). Suggested slot in the roadmap:

• Phase A.4 or later (after world-server login is working), when the client first receives AllegianceUpdate packets.
• Initial pass: decode and log; no UI. Use logs to verify wire format.
• Second pass: render read-only tree panel.
• Third pass: outbound commands (swear/break/info) — each tested against a mock server before pointing at a real ACEmulator instance.
• Fourth pass: chat channel integration — easy once generic chat plumbing exists.

The plugin API should expose the entire tree, the self-node, and a "send allegiance command" function. Automation scripts want to see allegiance info and send MOTD updates or boot commands.

---

12. Key files for future work

File	What's in it
references/ACE/.../Entity/AllegianceNode.cs	Rank algorithm, tree walking
references/ACE/.../Entity/AllegianceRank.cs (AllegianceTitle)	Full heritage × gender × rank string table
references/ACE/.../Managers/AllegianceManager.cs	XP pass-up formulas, tree rebuild
references/ACE/.../WorldObjects/Allegiance.cs	Allegiance worldobject (name, MOTD, bans, officers)
references/ACE/.../WorldObjects/Player_Allegiance.cs	All player-side handlers (swear, break, chat, etc.)
references/ACE/.../Network/Structure/Allegiance*.cs	Wire format writers — reverse for acdream reader
references/ACE/.../Network/GameEvent/Events/Allegiance*.cs	Server-to-client event definitions
references/ACE/.../Network/GameAction/Actions/Allegiance*.cs	Client-to-server action definitions
references/ACE/.../Entity/Enum/Allegiance*.cs	Officer level, permission level, lock action, house action enums
docs/research/decompiled/chunk_00570000.c	Client-side chat channel bitmasks, error strings, help text
docs/research/decompiled/chunk_00560000.c	Allegiance information panel rendering (line 7245)
docs/research/decompiled/chunk_006B0000.c	ChatMessageType enum values (Allegiance = 0x12)

---

Next steps once we're in Phase 4+ (networking live):

1. Capture an AllegianceUpdate packet from a live ACE shard.
2. Decode it with acdream's port of the hierarchy reader.
3. Spot-verify every field matches what ACE's writer would have produced for the same node.
4. Build the tree renderer on top of that model.
5. Add outbound actions one at a time (start with AllegianceUpdateRequest — it's the simplest and used most).