API Item Overview

[ITEM] Item Management Commands

Category: Item Management Commands: 21 commands API Version: 1.3.11.2 Status: STABLE

---

Overview

Item management commands provide comprehensive control over inventory and equipment systems in Mount & Blade II: Bannerlord. These commands enable you to add/remove items from party inventories, manage hero equipment (both battle and civilian), save and load complete equipment sets, and manipulate item quantities and quality modifiers.

Items are the physical objects in Bannerlord including weapons, armor, mounts, trade goods, and consumables. The item management system spans inventory operations (party-level storage), equipment operations (hero-equipped items), and equipment persistence (save/load functionality). This powerful command set allows you to rapidly outfit heroes, test equipment combinations, manage trade goods, and create reusable equipment templates.

All item commands require campaign mode to be active. Heroes must belong to parties to hold items in inventory. The system supports quality modifiers (Fine, Masterwork, Legendary) and provides separate management for battle and civilian equipment sets.

---

Command Reference

Quick Reference Table

Command	Description	Category	Status
gm.item.add	Add items to party inventory	Inventory	STABLE
gm.item.remove	Remove items from party	Inventory	STABLE
gm.item.remove_all	Clear all party inventory	Inventory	STABLE
gm.item.transfer	Transfer items between parties	Inventory	STABLE
gm.item.list_inventory	View party inventory	Inventory	STABLE
gm.item.equip	Auto-equip item to hero	Equipment	STABLE
gm.item.unequip	Remove specific equipped item	Equipment	STABLE
gm.item.equip_slot	Equip to specific slot	Equipment	STABLE
gm.item.unequip_slot	Unequip specific slot	Equipment	STABLE
gm.item.unequip_all	Unequip all items	Equipment	STABLE
gm.item.remove_equipped	Delete all equipped items	Equipment	STABLE
gm.item.list_equipped	View equipped items	Equipment	STABLE
gm.item.save_equipment	Save battle equipment to file	Equipment Sets	STABLE
gm.item.save_equipment_civilian	Save civilian equipment	Equipment Sets	STABLE
gm.item.save_equipment_both	Save both equipment sets	Equipment Sets	STABLE
gm.item.load_equipment	Load battle equipment	Equipment Sets	STABLE
gm.item.load_equipment_civilian	Load civilian equipment	Equipment Sets	STABLE
gm.item.load_equipment_both	Load both equipment sets	Equipment Sets	STABLE
gm.item.set_equipped_modifier	Set quality modifier on equipped item	Advanced	STABLE
gm.item.set_inventory_modifier	Set quality modifier on inventory item	Advanced	STABLE
gm.item.remove_equipped_modifier	Remove quality modifier from equipped item	Advanced	STABLE

---

Command Categories

Inventory Operations

Commands for managing party-level item storage.

Basic Inventory Commands:

• gm.item.add - Adds items to a hero's party inventory. Supports quantities from 1-10,000 per command.
• gm.item.remove - Removes specific items from party inventory. Requires sufficient quantity available.
• gm.item.remove_all - Clears all items from party inventory. Permanent deletion, use with caution.
• gm.item.transfer - Transfers items between two hero parties. Both heroes must have parties.
• gm.item.list_inventory - Displays organized inventory listing by category (weapons, armor, mounts, other).

Equipment Operations

Commands for managing hero-equipped items (worn/wielded gear).

Equipment Commands:

• gm.item.equip - Automatically equips an item to the appropriate slot. System detects correct slot based on item type.
• gm.item.unequip - Removes a specific equipped item. Searches both battle and civilian equipment.
• gm.item.equip_slot - Equips item to a specific equipment slot (Weapon0-3, Head, Body, Leg, Gloves, Cape, Horse, HorseHarness).
• gm.item.unequip_slot - Unequips item from specific slot. Returns error if slot is empty.
• gm.item.unequip_all - Removes all equipped items and moves them to party inventory. Preserves items.
• gm.item.remove_equipped - Permanently deletes all equipped items. Does not move to inventory.
• gm.item.list_equipped - Displays all equipped items organized by battle/civilian sets.

Equipment Save/Load System

Commands for persisting equipment configurations to files for reuse and backup.

Equipment Persistence:

• gm.item.save_equipment - Saves hero's battle equipment to JSON file in Documents folder.
• gm.item.save_equipment_civilian - Saves civilian equipment to separate JSON file.
• gm.item.save_equipment_both - Saves both battle and civilian equipment with single command.
• gm.item.load_equipment - Loads previously saved battle equipment from file.
• gm.item.load_equipment_civilian - Loads civilian equipment from file.
• gm.item.load_equipment_both - Loads both equipment sets from files.

All save/load operations preserve item quality modifiers and handle missing items gracefully.

Advanced Item Operations

Commands for specialized item manipulation.

Advanced Commands:

• gm.item.add_with_modifier - Adds items with specific quality modifiers (Fine, Masterwork, Legendary, etc.).
• gm.item.set_quantity - Sets the quantity of a specific item stack in party inventory.

---

Common Parameters

Item Identifier

Most commands accept flexible item identification:

• StringId - Exact game identifier (e.g., imperial_sword, western_mail_coif)
• Partial Name - Substring match in item name (e.g., sword, armor, horse)

Hero Identifier

Commands involving heroes accept:

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

Equipment Slots

Valid equipment slot names:

• Weapons: Weapon0, Weapon1, Weapon2, Weapon3
• Armor: Head, Body, Leg, Gloves, Cape
• Mounts: Horse, HorseHarness

Equipment Type

• Battle - Default equipment set for combat
• Civilian - Equipment for town/non-combat situations
• Use civilian keyword to specify civilian equipment

Quantity

• Range: 1 to 10,000 items per command
• Type: Integer

---

Usage Examples

Example 1: Rapid Army Equipment

Quickly equip multiple heroes with battle gear:

gm.item.add imperial_sword 5 player
gm.item.add steel_shield 5 player
gm.item.add chainmail 5 player
gm.item.equip imperial_sword player
gm.item.equip chainmail player

Result: Party has weapons and armor inventory, player equipped with combat gear.

Example 2: Equipment Template System

Create reusable equipment templates:

gm.item.save_equipment_both elite_warrior elite_template
gm.item.load_equipment_both new_companion elite_template

Result: New companion receives exact same equipment as the elite warrior.

Example 3: Complete Hero Outfit

Equip a hero with full equipment set:

gm.item.equip_slot imperial_sword player Weapon0
gm.item.equip_slot steel_shield player Weapon1
gm.item.equip_slot helmet player Head
gm.item.equip_slot chainmail player Body
gm.item.equip_slot boots player Leg
gm.item.equip_slot destrier player Horse

Result: Hero has complete battle equipment in specific slots.

Example 4: Civilian vs Battle Equipment

Manage separate equipment sets:

gm.item.equip armor player
gm.item.equip robe player civilian
gm.item.list_equipped player

Result: Hero has armor for battle, robe for civilian situations.

Example 5: Inventory Management Workflow

Transfer and organize items between parties:

gm.item.list_inventory player
gm.item.transfer imperial_sword 3 player companion
gm.item.remove food 50 player

Result: Items transferred and unwanted items removed.

---

Best Practices

TIP: Save Equipment Before Experiments

Always save equipment before testing new configurations:

gm.item.save_equipment_both player backup_before_test

This allows quick restoration if experiments go wrong.

TIP: Use Query Commands for Item IDs

Find exact item identifiers before adding:

gm.query.item imperial
gm.query.item armor tier5

Ensures correct item selection and reveals available items.

TIP: Unequip vs Remove Equipped

Understand the difference:

• gm.item.unequip_all - Moves items to inventory (preserves items)
• gm.item.remove_equipped - Permanently deletes items

Use unequip_all unless you specifically want to delete items.

TIP: Equipment Slot Organization

Follow conventional slot usage:

• Weapon0 - Primary weapon (sword, polearm, bow)
• Weapon1 - Shield or secondary weapon
• Weapon2-3 - Backup weapons or additional ammunition

TIP: Quality Modifiers

Use quality modifiers for better equipment:

gm.item.add_with_modifier player imperial_sword masterwork 1

Quality levels: crude, chipped, rusty, bent, fine, masterwork, legendary

---

Notes & Warnings

WARNING: Remove vs Unequip Distinction

Critical difference in item destruction:

• gm.item.remove_equipped - PERMANENTLY DELETES equipped items
• gm.item.unequip_all - Moves items to inventory (safe)

Always use unequip_all unless deletion is intended.

WARNING: Equipment File Overwrite

Saving equipment with existing filename overwrites without warning:

• No confirmation prompt
• Previous equipment data is lost
• Use unique filenames or backup files

NOTE: Party Requirement

Heroes must belong to parties for inventory operations:

• Wanderers without parties cannot hold inventory items
• Imprisoned heroes may lack parties
• Equipment operations work regardless of party status

NOTE: Equipment Save Locations

Equipment files are stored in:

• Battle: Documents\Mount and Blade II Bannerlord\Configs\GameMaster\HeroSets\{filename}.json
• Civilian: Documents\Mount and Blade II Bannerlord\Configs\GameMaster\HeroSets\civilian\{filename}.json

Files are in JSON format, editable with text editors.

NOTE: Missing Items During Load

When loading equipment:

• Missing items (from removed mods) are skipped with notification
• Available items still equip normally
• Partial loads succeed gracefully

NOTE: Item Stack Quantities

Inventory items stack by type:

• Consumables (food) stack in large quantities
• Equipment items typically stack individually
• Use set_quantity to adjust stack sizes

---

Related Documentation

Command Groups

• Hero Management Commands - Manage heroes who own equipment
• Query Commands - Search for items and modifiers

Query Commands

For finding items before adding:

• gm.query.item - Search items by name, type, tier
• gm.query.item_categories - View all item categories
• gm.query.modifiers - List quality modifiers and effects

Reference Materials

• Item Types Reference - Complete item type catalog
• Item Modifiers Reference - Quality modifiers and stats
• Equipment Slots Reference - Slot system details

User Guides

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

---

Last Updated: 2025-12-16 API Version: 1.3.11.2

Return to API Reference | Home