API Settlement Overview

[SETTLEMENT] Settlement Management Commands

Category: Settlement Management Commands: 19 commands BLGM Version: v1.3.13.4 Game Version: v1.3.13 Status: STABLE

---

Overview

Settlement management commands provide comprehensive control over settlements in Mount & Blade II: Bannerlord. These commands enable you to manipulate settlement properties, manage resources, control military strength, and customize settlement characteristics across all settlement types including cities, castles, villages, and hideouts.

Settlements are the core economic and military infrastructure in Bannerlord, serving as centers of trade, production, and defense. Each settlement type has unique properties and capabilities. Cities and castles have prosperity, loyalty, and security systems along with garrisons and militia. Villages have hearth values representing population and productivity. The settlement management system allows you to fine-tune economic balance, test gameplay scenarios, and customize the campaign world.

Note: Caravan creation and management commands have been moved to the Caravan Management category.

All settlement commands require campaign mode to be active. Many operations directly modify settlement state and affect gameplay mechanics, so careful consideration is recommended for maintaining game balance.

---

Command Reference

Quick Reference Table

Command	Description	Category	Status
gm.settlement.set_prosperity	Set city/castle prosperity	Properties	STABLE
gm.settlement.set_hearths	Set village hearth value	Properties	STABLE
gm.settlement.set_village_bound_settlement	Change village bound settlement	Village	STABLE
gm.settlement.set_village_trade_bound_settlement	Change village trade bound settlement	Village	STABLE
gm.settlement.rename	Rename any settlement	Properties	STABLE
gm.settlement.reset_name	Reset settlement to original name	Properties	STABLE
gm.settlement.reset_all_names	Reset all settlements to original names	Properties	STABLE
gm.settlement.set_culture	Change settlement culture	Properties	STABLE
gm.settlement.set_loyalty	Set city/castle loyalty	Properties	STABLE
gm.settlement.set_security	Set city/castle security	Properties	STABLE
gm.settlement.set_owner	Change settlement owner to hero	Ownership	STABLE
gm.settlement.set_owner_clan	Change settlement owner clan	Ownership	STABLE
gm.settlement.set_owner_kingdom	Change settlement owner kingdom	Ownership	STABLE
gm.settlement.upgrade_buildings	Upgrade all buildings to level	Resources	STABLE
gm.settlement.give_food	Add/remove food stock	Resources	STABLE
gm.settlement.give_gold	Add/remove treasury gold	Resources	STABLE
gm.settlement.add_militia	Add militia troops	Military	STABLE
gm.settlement.fill_garrison	Fill garrison to capacity	Military	STABLE
gm.settlement.spawn_wanderer	Spawn wanderer hero	NPCs	STABLE

---

Command Categories

Property Management

Commands for managing core settlement properties and characteristics.

gm.settlement.set_prosperity - Sets prosperity level for cities and castles. Prosperity affects tax income, available goods, and settlement growth. Higher prosperity increases economic output but makes settlements more valuable targets. Valid range: 0-20000.

gm.settlement.set_hearths - Sets hearth value for villages, which represents population and productivity. Hearths affect tax income, militia recruitment, and production capacity. Higher hearth values increase village economic contribution. Valid range: 0-2000.

gm.settlement.rename - Changes the display name of any settlement type. Useful for customization, role-playing scenarios, or localizing settlement names. Works on cities, castles, villages, and hideouts. Names persist through save/load cycles.

gm.settlement.reset_name - Resets a single settlement to its original game name after it has been renamed. Useful for reverting custom names.

gm.settlement.reset_all_names - Resets all renamed settlements to their original game names in one command. Useful for clearing all custom names at once.

gm.settlement.set_culture - Changes the culture of a settlement, affecting available troops, architecture style, and settlement character. Valid cultures: empire, sturgia, aserai, vlandia, battania, khuzait.

gm.settlement.set_loyalty - Sets loyalty level for cities and castles. Loyalty affects rebellion risk, tax efficiency, and local support. Low loyalty can trigger rebellion events. Valid range: 0-100.

gm.settlement.set_security - Sets security level for cities and castles. Security affects crime rate, bandit spawns, and local stability. Higher security reduces criminal activity and improves settlement safety. Valid range: 0-100.

Ownership Management

Commands for changing settlement ownership between heroes, clans, and kingdoms.

gm.settlement.set_owner - Changes the settlement owner to a specific hero. Also updates the owner clan to the hero's clan and map faction to the hero's faction. Applies to cities and castles.

gm.settlement.set_owner_clan - Changes the settlement owner clan to a specific clan. Also updates the owner to the clan leader and map faction to the clan's kingdom. Applies to cities and castles.

gm.settlement.set_owner_kingdom - Changes the settlement owner to a kingdom's ruling clan. Also updates the owner to the kingdom ruler and map faction to the kingdom. Applies to cities and castles.

Resource Management

Commands for managing settlement economic resources and construction.

gm.settlement.add_construction - Adds construction points to cities and castles for building projects. Construction points determine how quickly building upgrades complete. Useful for accelerating settlement development or testing building mechanics.

gm.settlement.upgrade_buildings - Instantly upgrades all buildings in a city or castle to the specified level (0-3). Bypasses normal construction time and costs. WARNING: Level 4+ will crash the game. Useful for quickly developing settlements or creating test scenarios.

gm.settlement.give_food - Adds or removes food from settlement food stock. Food affects population growth, garrison upkeep, and siege resistance. Can use negative values to reduce food stocks. Essential for managing settlement economics and siege scenarios.

gm.settlement.give_gold - Adds or removes gold from settlement treasury. Treasury gold is used for garrison wages, construction projects, and settlement upkeep. Can use negative values to reduce treasury. Important for managing settlement financial health.

Military Management

Commands for managing settlement military strength and defense.

gm.settlement.add_militia - Adds militia troops to cities and castles. Militia provide passive defense and reinforce garrisons during sieges. Militia troops are automatically generated based on settlement properties but can be manually adjusted for testing or balance.

gm.settlement.fill_garrison - Automatically fills garrison to maximum capacity using proportional troop composition. Analyzes existing garrison troops and adds more of the same types proportionally until reaching party size limit. Requires at least one troop in garrison as template.

NPC and Caravan Management

Commands for spawning NPCs and creating caravans in settlements.

gm.settlement.spawn_wanderer - Spawns a random wanderer hero in a city or castle. The wanderer is created from available templates with proper name, portrait, and stats (age 25-35). Wanderers appear as notables and can be recruited as companions.

gm.settlement.create_notable_caravan - Creates a caravan owned by a notable in a city. Automatically finds an available notable without a caravan and assigns the new caravan to them. The caravan will trade between settlements and generate income for the notable.

gm.settlement.create_player_caravan - Creates a caravan for the player's clan in a city. Optionally assign a companion hero to lead the caravan. The caravan generates trade profits for the player's clan and can be managed like other party assets.

---

Common Parameters

Settlement Identifier

Most commands accept flexible settlement identification:

• StringId - Exact game identifier (e.g., town_ES1, castle_B1, village_EN1)
• Partial Name - Substring match in settlement name (e.g., pen, pravend, zeonica)

Settlement Types

Different commands apply to specific settlement types:

• Cities - Towns with prosperity, loyalty, security, garrisons, and militias
• Castles - Fortifications with prosperity, loyalty, security, garrisons, and militias
• Villages - Rural settlements with hearth values
• Hideouts - Bandit camps (limited functionality, mainly rename)

Value Ranges

• Prosperity - 0 to 20000 (cities/castles only)
• Hearths - 0 to 2000 (villages only)
• Loyalty - 0 to 100 (cities/castles only)
• Security - 0 to 100 (cities/castles only)
• Construction - 0 to 100000 (cumulative points)
• Food - Any integer (can be negative to remove)
• Gold - Any integer (can be negative to remove)
• Militia - 0 to 1000 (cities/castles only)

---

Usage Examples

Example 1: Developing a New Settlement

Transform a struggling settlement into a thriving city:

gm.settlement.set_prosperity pen 15000
gm.settlement.set_loyalty pen 100
gm.settlement.set_security pen 100
gm.settlement.give_gold pen 50000
gm.settlement.give_food pen 1000
gm.settlement.add_militia pen 200

Result: Penraic becomes a highly prosperous, loyal, and secure city with substantial resources and strong defenses.

Example 2: Economic Rebalancing

Adjust settlement economics across different territories:

gm.settlement.set_prosperity vostrum 8000
gm.settlement.give_gold vostrum 20000
gm.settlement.set_prosperity zeonica 12000
gm.settlement.give_gold zeonica 35000

Result: Balanced economic development across multiple settlements.

Example 3: Village Development

Improve village productivity and population:

gm.settlement.set_hearths car_pherpi 1500
gm.settlement.give_food car_pherpi 500

Result: Village has high productivity with substantial food reserves.

Example 4: Military Preparation

Prepare settlements for defensive scenarios:

gm.settlement.add_militia pravend 150
gm.settlement.fill_garrison pravend
gm.settlement.give_food pravend 2000
gm.settlement.set_loyalty pravend 100

Result: Settlement has full garrison, strong militia, ample food, and high loyalty for siege defense.

Example 5: Rapid Construction

Accelerate building projects for testing:

gm.settlement.add_construction zeonica 5000
gm.settlement.give_gold zeonica 100000

Result: Settlement has substantial construction points and funds for immediate building upgrades.

Example 6: Settlement Customization

Create themed or localized settlements:

gm.settlement.rename pen NewPenraic
gm.settlement.rename pravend Pravendtown
gm.settlement.rename vostrum TheVostrum

Result: Settlements have customized names for role-playing or localization.

Example 7: Populating Settlements with NPCs

Add wanderers and caravans to settlements:

gm.settlement.spawn_wanderer pen
gm.settlement.spawn_wanderer pravend
gm.settlement.create_notable_caravan pen
gm.settlement.create_player_caravan vostrum companion_hero

Result: Settlements have new wanderers for recruitment and active caravans for trade.

---

Best Practices

TIP: Settlement Type Awareness

Always consider settlement type when using commands:

• Cities and castles support: prosperity, loyalty, security, militia, garrisons
• Villages only support: hearths (not prosperity)
• All settlement types support: rename, food, gold
• Attempting to set prosperity on a village will error (use set_hearths instead)

TIP: Balanced Development

Maintain balance across settlement properties:

gm.settlement.set_prosperity pen 10000
gm.settlement.set_loyalty pen 80
gm.settlement.set_security pen 70
gm.settlement.add_militia pen 100

Balanced properties provide realistic gameplay without extreme advantages.

TIP: Garrison Filling Strategy

Before using fill_garrison, ensure garrison has diverse troop types:

// First add some troops manually for diversity
gm.troop.give_hero_troops player imperial_recruit 20
gm.troop.give_hero_troops player imperial_infantry 10
// Then transfer to garrison and fill
gm.settlement.fill_garrison pen

This ensures a balanced troop composition when filling.

TIP: Food Management for Sieges

Prepare settlements for siege scenarios:

gm.settlement.give_food target_city 5000
gm.settlement.fill_garrison target_city
gm.settlement.set_loyalty target_city 100

High food stocks, full garrison, and maximum loyalty maximize siege resistance.

TIP: Construction Acceleration

Speed up development for testing:

gm.settlement.add_construction test_city 10000
gm.settlement.give_gold test_city 200000

Large construction points allow immediate building upgrades.

TIP: Caravan Management

Create multiple caravans for economic growth:

gm.settlement.create_player_caravan pen companion_1
gm.settlement.create_player_caravan pravend companion_2
gm.settlement.create_notable_caravan vostrum

Player caravans generate clan income, while notable caravans add to world economy.

TIP: Wanderer Spawning

Use wanderers to expand companion options:

gm.settlement.spawn_wanderer pen
gm.settlement.spawn_wanderer pravend
gm.settlement.spawn_wanderer vostrum

Wanderers can be recruited as companions or left as settlement notables.

---

Notes & Warnings

NOTE: Prosperity vs Hearths

Understanding the distinction:

• Cities/Castles use prosperity (0-20000)
• Villages use hearths (0-2000)
• These are separate systems - villages do NOT have prosperity
• Attempting to set prosperity on villages will fail
• Use set_hearths for villages, set_prosperity for cities/castles

NOTE: Reflection Usage

Some commands use reflection to modify read-only properties:

• add_construction - Modifies private _construction field
• add_militia - Modifies private _militia field
• rename - Modifies private _name field

This is necessary due to Bannerlord API design where these properties are read-only. These operations are stable but may be affected by game version updates.

NOTE: Garrison Party Size Limits

fill_garrison respects maximum party size limits:

• Party size limit varies by settlement and faction
• Garrison will not exceed this limit
• Excess capacity may be available through upgrades
• Check party size settings if garrison seems incomplete

WARNING: Resource Negative Values

The give_food and give_gold commands accept negative values:

gm.settlement.give_food pen -1000  // Removes 1000 food
gm.settlement.give_gold pen -5000  // Removes 5000 gold

Be cautious with negative values to avoid depleting resources below functional levels. Settlements with insufficient food or gold may have gameplay issues.

WARNING: Loyalty and Rebellion

Low loyalty can trigger rebellion events:

• Loyalty below 25 significantly increases rebellion risk
• Rebellions can cause settlement to change ownership
• Monitor loyalty after reducing it
• Set loyalty to 50+ for stable gameplay

NOTE: Settlement Development Effects

Property changes affect gameplay mechanics:

• Prosperity - Increases tax income, trade goods, recruitment
• Hearths - Increases village production, tax income, militia
• Loyalty - Affects rebellion risk, tax efficiency, garrison morale
• Security - Reduces crime, bandit spawns, improves prosperity growth
• Militia - Provides passive defense during sieges

Balance these properties for intended gameplay experience.

NOTE: Caravan Creation Requirements

Caravans can only be created in cities:

• Cities - Supported for both notable and player caravans
• Castles - Not supported
• Villages - Not supported
• Hideouts - Not supported

Notable caravans require an available notable without existing caravans. Player caravans can optionally have companion leaders.

NOTE: Wanderer Spawning Locations

Wanderers can be spawned in:

• Cities - Supported
• Castles - Supported
• Villages - Not supported
• Hideouts - Not supported

Spawned wanderers have age 25-35 and appear as settlement notables.

---

Related Documentation

Command Groups

• Settlement Query Commands - Search and find settlements
• Kingdom Management Commands - Manage settlement ownership through kingdoms
• Troop Management Commands - Manage garrison troops

Reference Materials

• Settlement Types Reference - Settlement categories and mechanics
• Factions Reference - Faction control and ownership

User Guides

• Quick Start Guide - Getting started with GameMaster commands
• Best Practices - Recommended usage patterns
• Troubleshooting - Common issues and solutions

---

Last Updated: 2025-01-07 API Version: v1.3.13.3

Return to API Reference | Home