Vassal & Suzerains: Villager Recruits Addon

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