Vassal and Suzerain is an addon for Recruits that adds a persistent feudal politics layer on top of the existing faction system. It lets factions form structured liege-vassal hierarchies, enforce title rules, manage tribute obligations, and view those relationships directly in the UI, all without modifying the base Recruits mod itself.

Core feudal hierarchy:
- Every faction can have at most one direct suzerain and multiple direct vassals.
- Hierarchies are stored persistently and survive relogs and server restarts.
- Circular hierarchies are blocked automatically.
- A faction cannot become its own suzerain or create invalid hierarchy loops.
- Hierarchies are based on faction IDs, making the system lightweight and data-driven.

Title system:
- Factions can be assigned one of three titles:
KING
DUKE
COUNT

Title rules are enforced:
- KING cannot have a suzerain.
- DUKE can only serve under a KING.
- COUNT can only serve under a DUKE.
- Invalid title pairings are rejected.
- Title changes that would break existing vassal relationships are prevented.

Vassalization flow:
- Suzerainty is not forced instantly through normal gameplay flow.
/feudal vassalize <faction> sends a request to the target faction.

- The receiving faction leader must accept or reject it.
- If the target leader is offline, the request is preserved and shown when they next log in.
/feudal requests lists pending requests with clickable accept/reject options.
- Admins can still use set_suzerain as a direct override.

Relationship control:
- /feudal release <faction> only works for the direct suzerain.
- A vassal cannot release itself from its liege.
- /feudal hierarchy shows the current chain of liege relationships.
- /feudal contract info lets a vassal view their active tribute contract at any time.

Diplomacy and rebellion:
- Direct liege-vassal pairs are protected from normal hostility.
- A vassal cannot freely keep switching war status against its suzerain.
- Rebellion works through diplomacy:
- A vassal can set its direct suzerain to ENEMY to begin a rebellion.
- While rebellion is active, direct combat between liege and vassal is allowed.
- If the relation is changed back to NEUTRAL or ALLY, rebellion ends and the relation is forced back to ALLY.
- After rebellion ends, that vassal cannot rebel again for 5 real-life days by default.
- Outside rebellion, direct liege-vassal aggression and targeting are blocked.
- This is enforced through addon-side rules without editing Recruits internals.

Tribute contract system:
Suzeraints can configure tribute contracts for their direct vassals through a keybind UI.

Tribute contracts define:
- target vassal
- item to pay
- item amount
- real-time interval
- The tribute UI supports searching all registered items by id or display name.
- Item lists are scanned and cached client-side for fast searching.
- Tribute intervals are configurable from 2 minutes up to 30 real-life days.
- Suzeraints bind a destination chest with /feudal vault.
- Vassals bind their payment chest with /feudal tribute.
- On each tribute interval, the addon transfers matching items from the vassal chest to the suzerain chest if possible.

Tribute persistence and reliability:
- Tribute contracts, bound chests, and execution timing are saved in persistent world data.
- Tribute setup survives logout/login and server restart.
- Contract updates are also persistent.
- If a suzerain changes a tribute contract while the vassal leader is offline, the vassal is notified on next login.
- Vassals can always review their current tribute obligations with /feudal contract info.

Tribute ledger book:
- Every tribute cycle is logged automatically.
- The suzerain chest receives a written ledger book that records payment history.
- Successful transfers are logged as complete payments.
- Failed or partial transfers are logged with the missing amount and item.
- If the ledger book is removed or destroyed, a new updated one is spawned on the next record cycle.
- The ledger history is stored in saved contract data, so the book is only the visible copy, not the only record.

Faction and claim UI:
- The Recruits faction list is enhanced with hierarchy visuals:
- a suzerain banner appears above a faction’s banner
- direct vassal banners appear below
- hovering entries shows the hierarchy chain
- Claim display text is extended to show liege information without changing claim ownership.
- Claim colors remain the faction’s own normal colors outside special map mode.

World map feudal mode:
- The Recruits world map includes a client-side Feudal Colors toggle.
- When enabled, direct vassal claims are recolored locally to match their suzerain’s color.
- This is purely visual and client-side:
- it does not alter server data
- each player can toggle it independently