API Hero Overview

[HERO] Hero Management Commands

Category: Hero Management Commands: 40 commands API Version: 1.3.14.11 Status: STABLE

---

Overview

Hero management commands provide comprehensive control over individual characters in Mount & Blade II: Bannerlord. These commands allow you to modify hero properties, manage clan affiliations, control hero states (alive, dead, imprisoned), and configure relationships between heroes.

Heroes are the foundation of Bannerlord's character system, representing lords, companions, wanderers, merchants, and notables. The hero management command set enables you to create custom scenarios, test gameplay mechanics, balance relationships, and manipulate hero attributes for roleplaying purposes.

All hero management commands require campaign mode to be active. Many operations permanently modify game state, so it's recommended to backup your save file before performing irreversible actions like killing heroes or removing them from clans.

---

Command Reference

Quick Reference Table

Command	Description	Category	Status
gm.hero.set_clan	Transfer hero to different clan	Clan Management	STABLE
gm.hero.remove_clan	Remove hero from their clan	Clan Management	STABLE
gm.hero.kill	Kill a hero permanently	State Management	STABLE
gm.hero.imprison	Imprison a hero	State Management	STABLE
gm.hero.release	Release hero from captivity	State Management	STABLE
gm.hero.set_age	Set hero's age	Attributes	STABLE
gm.hero.set_gold	Set hero's gold amount	Attributes	STABLE
gm.hero.add_gold	Add or subtract gold	Attributes	STABLE
gm.hero.heal	Heal hero to full health	Attributes	STABLE
gm.hero.rename	Change hero's display name	Attributes	STABLE
gm.hero.set_culture	Change hero's culture	Attributes	STABLE
gm.hero.edit_appearance	Open native face generator UI	Appearance	STABLE
gm.hero.save_appearance	Save hero appearance to file	Appearance	STABLE
gm.hero.load_appearance	Load saved appearance onto hero	Appearance	STABLE
gm.hero.list_appearances	List all saved appearance files	Appearance	STABLE
gm.hero.save_development	Save hero skills/attributes/perks to file	Development	STABLE
gm.hero.load_development	Load saved development onto hero	Development	STABLE
gm.hero.list_developments	List all saved development files	Development	STABLE
gm.hero.save_traits	Save hero traits to file	Traits	STABLE
gm.hero.load_traits	Load saved traits onto hero	Traits	STABLE
gm.hero.list_traits	List all saved trait files	Traits	STABLE
gm.hero.export_character	Export full character data to file	Character Sets	STABLE
gm.hero.load_character	Load character set onto existing hero	Character Sets	STABLE
gm.hero.import_character	Create new hero from character set file	Character Sets	STABLE
gm.hero.list_characters	List all saved character set files	Character Sets	STABLE
gm.hero.equip_hero	Equip hero with skill-based equipment	Equipment	STABLE
gm.hero.open_inventory	Open native inventory screen for a hero	Inventory	STABLE
gm.hero.set_relation	Set relationship between heroes	Relationships	STABLE
gm.hero.marry	Marry two heroes	Relationships	STABLE
gm.hero.divorce	Divorce hero from spouse	Relationships	STABLE
gm.hero.impregnate	Make female hero pregnant	Relationships	STABLE
gm.hero.give_birth	Force immediate birth for pregnant hero	Relationships	STABLE
gm.hero.abort_pregnancy	Terminate pregnancy without birth	Relationships	STABLE
gm.hero.add_hero_to_party	Add hero to another's party	Party Management	STABLE
gm.hero.create_party	Create party for hero	Party Management	STABLE
gm.hero.edit_party	Open native party editor for hero	Party Management	STABLE
gm.hero.create_lord	Create fresh lord with minimal stats	Generation	STABLE
gm.hero.generate_lords	Generate lords with good equipment	Generation	STABLE
gm.hero.create_companions	Create companions for a party	Generation	STABLE
gm.hero.start_convrsation	Start conversation with hero	Conversation	STABLE

---

Command Categories

Clan Management Commands

Commands for managing hero clan affiliations and memberships.

gm.hero.set_clan - Transfer a hero from their current clan to another clan. Useful for rebalancing factions or creating custom clan compositions.

gm.hero.remove_clan - Remove a hero from their current clan, leaving them without clan affiliation. Creates independent wanderers or free agents.

State Management Commands

Commands for controlling hero life states and imprisonment status.

gm.hero.kill - Permanently kills a hero. This action cannot be undone. Optionally displays the in-game death log notification.

gm.hero.imprison - Makes one hero a prisoner of another. The captor must have a valid party or settlement to hold prisoners.

gm.hero.release - Frees a hero from captivity, returning them to active status. Hero must currently be imprisoned.

Attribute Management Commands

Commands for modifying hero attributes, resources, and health.

gm.hero.set_age - Sets a hero's age to a specific value (0-128 range). Affects eligibility for marriage and other age-dependent game mechanics.

gm.hero.set_gold - Sets a hero's gold to an exact amount. Useful for balancing hero wealth or testing economic scenarios.

gm.hero.add_gold - Adds or subtracts gold from a hero's current amount. Use negative values to reduce gold.

gm.hero.heal - Instantly heals a hero to maximum hit points. Cannot revive dead heroes.

Appearance Management Commands

Commands for modifying hero visual appearance.

gm.hero.edit_appearance - Opens the native face generator UI to edit the specified hero's appearance. This allows full customization of facial features, hair, beard, and body properties for any hero in the game, not just the player character.

gm.hero.save_appearance - Saves a hero's appearance (face, hair, tattoos, body shape, height) to a JSON file. Age is not included. The saved file can be loaded onto any hero of the same gender.

gm.hero.load_appearance - Loads a previously saved appearance onto a hero. Gender matching is enforced by default; use force:true to allow cross-gender loading.

gm.hero.list_appearances - Lists all saved appearance files in the BLGM appearances directory.

Development Management Commands

Commands for saving, loading, and managing hero skill progression.

gm.hero.save_development - Saves a hero's full development state (skills, attributes, perks, focus points, XP, level) to a JSON file. The saved file can be applied to any hero.

gm.hero.load_development - Loads a previously saved development state onto a hero. Level is recalculated after loading to match the loaded skills.

gm.hero.list_developments - Lists all saved development files in the BLGM developments directory.

Trait Management Commands

Commands for saving, loading, and managing hero traits.

gm.hero.save_traits - Saves all of a hero's traits (personality, persona, political, role/skill) to a JSON file. Captures all traits including those added by mods.

gm.hero.load_traits - Loads a previously saved trait set onto a hero. Traits not found in the current game session are skipped gracefully.

gm.hero.list_traits - Lists all saved trait files in the BLGM traits directory.

Character Set Commands

Commands for exporting, loading, and importing complete hero character snapshots.

gm.hero.export_character - Exports a hero's complete data (appearance, development, traits, battle equipment, civilian equipment) to a single JSON character set file. The most comprehensive save option.

gm.hero.load_character - Loads a character set file onto an existing hero. Applies appearance, development, traits, equipment, age, and culture. Does NOT change the hero's name, gender, StringId, MBGUID, or occupation.

gm.hero.import_character - Creates a brand new hero using a previously exported character set file. The new hero receives all the saved visual and gameplay data with a fresh identity (new name, StringId, MBGUID).

gm.hero.list_characters - Lists all saved character set files in the BLGM character sets directory.

Equipment Management Commands

Commands for managing hero equipment and gear.

gm.hero.equip_hero - Equips a hero with level-appropriate equipment based on their combat skills. The system analyzes hero skills to determine optimal weapon loadout (one-handed, two-handed, polearm, bow, crossbow, throwing, shield) and selects culturally appropriate armor and weapons for the specified tier. Tier can be specified or auto-calculated from hero level. Optionally replaces civilian equipment as well.

Party Editor Commands

Commands for managing party troop composition through the native UI.

gm.hero.edit_party - Opens the native party editor UI for a hero's party. In single-hero mode, the left side is populated with all game troops (100 each) as a discard roster for freely adding or removing troops. In two-hero mode, troops can be transferred between both heroes' parties.

Inventory Management Commands

Commands for managing hero inventory through the native UI.

gm.hero.open_inventory - Opens the native inventory screen for a specified hero, allowing item management and transfers. The hero's equipment is shown in the center panel, their party inventory on the left, and the other hero's (or player's) party inventory on the right. Supports cross-clan inventory access using synthetic roster support.

Relationship Management Commands

Commands for managing diplomatic and personal relationships between heroes.

gm.hero.set_relation - Sets the relationship value between two heroes. Relations range from -100 (enemies) to 100 (close friends). Affects diplomacy, marriage eligibility, and hero interactions.

gm.hero.marry - Marries two heroes together. The second hero joins the first hero's clan by default. Supports forceMarriage to bypass native validation (gender, age, relation checks) and joinClan to control clan transfer behavior.

gm.hero.divorce - Divorces the specified hero from their current spouse. Both the hero and their spouse have their marriage status cleared. Only one hero needs to be specified.

gm.hero.impregnate - Makes a female hero pregnant. Optionally specify a father, or the system will use the mother's spouse or a random nearby male hero. Supports allowAnyCulture to bypass culture restrictions.

gm.hero.give_birth - Forces immediate birth for a pregnant hero, bypassing the normal pregnancy duration. Optionally specify the father and child gender. Delivers the offspring, fires native birth events, and clears pregnancy state.

gm.hero.abort_pregnancy - Terminates a hero's pregnancy without delivering a child. Removes the pregnancy record and clears the pregnancy flag cleanly.

Hero Generation Commands

Commands for creating new hero characters.

gm.hero.create_lord - Creates a single lord from random templates with good gear and decent stats. Specify name, culture, gender, clan, party creation, settlement, randomization factor, level, and age. Default level is random 10-25 and default age is random 18-30. Supports withParty control and optional settlement placement.

gm.hero.generate_lords - Creates multiple lords with good equipment and decent stats. Default level is random 10-25 per hero and default age is random 18-30 per hero. High-tier culturally appropriate equipment. Can specify count, clan, settlement, level, and age. If no clan specified, lords are distributed across different clans for balance.

gm.hero.create_companions - Creates companions and adds them directly to a party leader's party. Default level is random 1-14 per companion and default age is random 18-30. Supports culture, gender, randomization, level, and age parameters.

---

Common Parameters

Hero Identifier

Most commands accept flexible hero identification:

• StringId - Exact game identifier (e.g., lord_1_1, wanderer_empire_1)
• Partial Name - Substring match in hero name (e.g., raganvad, john)
• Special Keywords - player for the player character

Clan Identifier

Commands involving clans accept:

• StringId - Exact clan identifier (e.g., clan_empire_south_1)
• Partial Name - Substring match in clan name (e.g., empire, battania)

Value Ranges

• Age - 0 to 128 (float values accepted)
• Gold - Any integer value (can be negative for subtraction)
• Relation - -100 to 100 (integer)

---

Usage Examples

Example 1: Creating a Custom Clan Composition

Transfer multiple heroes to form a custom clan:

gm.hero.set_clan wanderer_empire_1 clan_empire_south_1
gm.hero.set_clan wanderer_empire_2 clan_empire_south_1
gm.hero.set_clan lord_3_2 clan_empire_south_1

Result: Three heroes are now members of the same clan, creating a custom faction composition.

Example 2: Diplomatic Relationship Management

Improve relations between allied heroes:

gm.hero.set_relation lord_1_1 lord_2_1 75
gm.hero.set_relation lord_1_1 lord_3_1 50

Result: Lord 1_1 now has strong positive relationships with two other lords, improving diplomacy.

Example 3: Prisoner Management Workflow

Capture and later release a hero:

gm.hero.imprison lord_battania_1 player

Later, after desired story/gameplay:

gm.hero.release lord_battania_1

Result: Hero is first captured, then released when appropriate.

Example 4: Economic Balance

Distribute wealth among heroes:

gm.hero.set_gold lord_1_1 50000
gm.hero.add_gold wanderer_1 10000
gm.hero.add_gold merchant_1 25000

Result: Heroes have balanced starting wealth for custom scenarios.

Example 5: Age Adjustment for Marriage Eligibility

Set appropriate ages for marriage scenarios:

gm.hero.set_age lord_1_1 25
gm.hero.set_age lady_2_1 22
gm.hero.set_relation lord_1_1 lady_2_1 30

Result: Heroes are set to appropriate ages with positive relationship for marriage potential.

Example 6: Creating Custom Lords

Generate new lords for specific purposes:

gm.hero.create_lord male CustomLord empire_south
gm.hero.add_gold CustomLord 10000
gm.item.add CustomLord imperial_armor 1

Result: Custom named lord with starting gold and equipment.

Example 7: Quickly Populating Clans

Generate multiple lords to strengthen or populate clans:

gm.hero.generate_lords 5 empire_south
gm.hero.generate_lords 3 battania

Result: Multiple well-equipped lords added to specified clans.

---

Best Practices

TIP: Use Query Commands First

Always use query commands to find exact hero StringIds before executing management commands:

gm.query.hero raganvad

This ensures you're targeting the correct hero and reduces errors from ambiguous partial name matches.

TIP: Backup Save Files

Before executing permanent actions (kill, remove_clan), create a save game backup. These operations cannot be undone through commands.

TIP: Verify Hero State

Check hero status with query commands before imprisonment or release operations:

gm.query.hero_info lord_1_1

This confirms the hero's current state (alive, dead, prisoner) before attempting state changes.

TIP: Incremental Gold Changes

Use add_gold instead of set_gold when adjusting hero wealth incrementally. This preserves existing wealth and avoids accidentally zeroing hero gold.

TIP: Relationship Balance

When setting relationships, consider the broader diplomatic network. A hero with exclusively high or low relationships may behave unexpectedly in AI decision-making.

TIP: Lord Generation Options

Choose between two lord creation commands based on your needs:

• Use create_lord for custom-named lords you want to equip yourself
• Use generate_lords for quick, battle-ready lords with equipment

gm.hero.create_lord male MyLord clan  // Minimal, customizable
gm.hero.generate_lords 5 clan         // Pre-equipped, ready for battle

TIP: Balanced Clan Population

Distribute generated lords across multiple clans for game balance:

gm.hero.generate_lords 10  // Automatically distributes across different clans

Or strengthen specific clans:

gm.hero.generate_lords 5 weakened_clan

---

Notes & Warnings

WARNING: Permanent Actions

The following commands permanently modify game state and cannot be undone:

• gm.hero.kill - Permanently removes hero from active gameplay
• gm.hero.remove_clan - Cannot be undone without re-executing set_clan

Always backup save files before these operations.

WARNING: Clan Transfer Limitations

When transferring heroes between clans:

• Clan leaders cannot be transferred (remove leadership first)
• Heroes with active parties may experience gameplay disruptions
• Kingdom rulers require special handling (change ruler before transfer)

NOTE: Party Requirements

Some hero operations require the hero to belong to a party:

• Imprisonment requires captor to have a valid party or settlement
• Healing affects hero hit points (party member status doesn't matter)
• Gold operations work on all heroes regardless of party status

NOTE: Relationship Thresholds

Relationship values have specific gameplay thresholds:

• Below -10 - Heroes dislike each other, affecting diplomacy
• -10 to 10 - Neutral relationship
• Above 10 - Positive relationship, improves cooperation
• Above 50 - Strong friendship, enables marriage consideration

NOTE: Age Mechanics

Hero age affects:

• Marriage eligibility (typically 18+)
• Death probability (increases with age)
• Physical attribute decay (very high ages)
• Coming of age events (around 18)

NOTE: Generated Lord Properties

Lords created through generation commands have these characteristics:

create_lord:

• Age: 18-30 (random, or specify with age parameter, minimum 18)
• Level: 10-25 (random, or specify with level parameter, range 1-62)
• Equipment: High-tier armor and weapons matching culture
• Custom name specified by user
• Random appearance
• Optional party creation and settlement placement

generate_lords:

• Age: 18-30 per hero (random, or specify with age parameter, minimum 18)
• Level: 10-25 per hero (random, or specify with level parameter, range 1-62)
• Equipment: High-tier armor and weapons matching culture
• Auto-generated culture-appropriate names
• Random gender distribution

create_companions:

• Age: 18-30 per companion (random, or specify with age parameter, minimum 18)
• Level: 1-14 per companion (random, or specify with level parameter, range 1-62)
• Equipment: Basic equipment matching culture
• Auto-generated culture-appropriate names
• Added directly to specified party leader's party

---

Related Documentation

Command Groups

• Clan Management Commands - Manage clans that heroes belong to
• Kingdom Management Commands - Manage kingdoms and diplomacy
• Item Management Commands - Manage hero equipment and inventory
• Query Commands - Search and find heroes

Reference Materials

• Cultures Reference - Cultural backgrounds for heroes
• Traits Reference - Personality traits affecting hero behavior
• Skills Reference - Hero skills and progression
• Attributes Reference - Physical and mental attributes
• Factions Reference - Political affiliations and kingdoms

User Guides

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

---

Last Updated: 3/3/2026 API Version: 1.3.14.11

Return to API Reference | Home