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 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 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