Skip to content

API Query Overview

Jump to bottom
SolWayward edited this page Dec 24, 2025 · 5 revisions

[QUERY] Query Commands

Category: Query & Search Commands: 25 commands API Version: 1.3.11.2 Status: STABLE

Overview

Query commands provide powerful search and filtering capabilities for discovering game entities in Mount & Blade II: Bannerlord. These commands enable you to search for heroes, clans, kingdoms, troops, items, and item modifiers using flexible text search, type-based filtering, and advanced sorting options.

The query system is the foundation for effective use of GameMaster commands. Before modifying game entities with management commands, query commands help you identify exact StringIds, verify entity states, and explore available options. The system supports both AND logic (all criteria must match) and OR logic (any criteria matches), providing precise control over search results.

All query commands work in campaign mode and provide detailed information without modifying game state. They are safe to use for exploration and entity discovery, making them essential tools for both new users and experienced mod developers.

Command Reference

Quick Reference Table

Command Description Category Status
gm.query.hero Search heroes (AND logic) Hero Queries STABLE
gm.query.hero_any Search heroes (OR logic) Hero Queries STABLE
gm.query.hero_info Get detailed hero information Hero Queries STABLE
gm.query.clan Search clans (AND logic) Clan Queries STABLE
gm.query.clan_any Search clans (OR logic) Clan Queries STABLE
gm.query.clan_info Get detailed clan information Clan Queries STABLE
gm.query.kingdom Search kingdoms (AND logic) Kingdom Queries STABLE
gm.query.kingdom_any Search kingdoms (OR logic) Kingdom Queries STABLE
gm.query.kingdom_info Get detailed kingdom information Kingdom Queries STABLE
gm.query.settlement Search settlements (AND logic) Settlement Queries STABLE
gm.query.settlement_any Search settlements (OR logic) Settlement Queries STABLE
gm.query.settlement_info Get detailed settlement information Settlement Queries STABLE
gm.query.troop Search troops by filters Troop Queries STABLE
gm.query.troop_any Find specific troop Troop Queries STABLE
gm.query.troop_info Get troop details Troop Queries STABLE
gm.query.character_objects Search character objects (AND logic) Character Queries STABLE
gm.query.character_objects_any Search character objects (OR logic) Character Queries STABLE
gm.query.character_objects_info Get character object details Character Queries STABLE
gm.query.item Search items by filters Item Queries STABLE
gm.query.item_any Find specific item Item Queries STABLE
gm.query.item_info Get item details Item Queries STABLE
gm.query.modifiers List item modifiers Modifier Queries STABLE
gm.query.modifier_info Get modifier details Modifier Queries STABLE
gm.query.culture Search cultures Culture Queries STABLE
gm.query.culture_info Get culture details Culture Queries STABLE

Command Categories

Hero Query Commands

Commands for searching and discovering heroes with flexible filtering.

gm.query.hero - Search heroes using AND logic where all specified criteria must match. Supports text search (names, IDs) and type filters (lord, wanderer, notable, merchant, child, female, male, clanleader, kingdomruler, alive, dead, prisoner, etc.). Includes sorting by various fields.

gm.query.hero_any - Search heroes using OR logic where matching any specified criteria returns results. Useful for broader searches across multiple hero types simultaneously.

gm.query.hero_info - Get comprehensive detailed information about a specific hero by StringId, including clan, kingdom, age, status, and all applicable type flags.

Clan Query Commands

Commands for searching and discovering clans with type-based filtering.

gm.query.clan - Search clans using AND logic. Supports text search and type filters (active, eliminated, bandit, nonbandit, noble, minor, rebel, mercenary, mafia, outlaw, nomad, sect, withoutkingdom, empty, player). Includes sorting by tier, gold, renown, etc.

gm.query.clan_any - Search clans using OR logic for broader matching across multiple clan types.

gm.query.clan_info - Get detailed clan information including leader, kingdom, member counts, financial status, tier, renown, and all type classifications.

Kingdom Query Commands

Commands for searching kingdoms and analyzing political structures.

gm.query.kingdom - Search kingdoms using AND logic. Supports type filters (active, eliminated, empty, player, atwar) and sorting by various metrics (clans, heroes, fiefs, strength).

gm.query.kingdom_any - Search kingdoms using OR logic for flexible matching.

gm.query.kingdom_info - Get comprehensive kingdom details including ruler, ruling clan, clan count, military strength, fiefs, diplomatic relations, and war status.

Troop Query Commands

Commands for searching military units and troop types.

gm.query.troop - Search troops with filtering by culture, tier, equipment type, and name. Essential for finding exact troop identifiers before using troop management commands.

gm.query.troop_find - Find a specific troop by name or identifier with partial matching support.

gm.query.troop_details - Get detailed information about a troop including stats, equipment, tier, culture, and upgrade paths.

Item Query Commands

Commands for searching items and equipment.

gm.query.item - Search items with filtering by category, tier, type, and name. Supports sorting by various attributes. Essential for finding exact item identifiers.

gm.query.item_find - Find specific items by name with partial matching.

gm.query.item_details - Get detailed item information including stats, value, weight, tier, and type classifications.

gm.query.item_categories - List all available item categories for filtering purposes.

Item Modifier Query Commands

Commands for querying quality modifiers and their effects.

gm.query.modifiers - List all available item quality modifiers (Fine, Masterwork, Legendary, etc.) with their stat effects and descriptions.

gm.query.modifier_details - Get detailed information about a specific modifier including exact stat bonuses and applicability.

Common Parameters

Search Terms

Text search parameters look for matches in:

  • Names - Entity names (hero names, clan names, etc.)
  • StringIds - Exact game identifiers
  • Related Entities - Clan names for heroes, kingdom names for clans

Type Keywords

Hero Types:

  • lord, wanderer, notable, merchant, child
  • female, male
  • clanleader, kingdomruler, partyleader
  • alive, dead, prisoner, fugitive
  • withoutclan, withoutkingdom, married

Clan Types:

  • active, eliminated
  • bandit, nonbandit, noble, minor
  • rebel, mercenary, mafia, outlaw, nomad, sect
  • withoutkingdom, empty, player

Kingdom Types:

  • active, eliminated
  • empty, player, atwar

Sorting Parameters

Format: sort:field or sort:field:desc

Common Sort Fields:

  • id, name
  • age, gold, renown
  • clan, kingdom
  • tier, level, strength
  • Type flags (e.g., sort:wanderer, sort:lord)

Usage Examples

Example 1: Finding Heroes for Management

Locate exact hero StringIds before executing management commands:

gm.query.hero raganvad
gm.query.hero_info lord_1_1
gm.hero.set_gold lord_1_1 50000

Result: Verified hero identity, retrieved details, executed management command safely.

Example 2: Advanced Hero Filtering

Find specific hero types with multiple criteria:

gm.query.hero empire lord female
gm.query.hero_any lord wanderer
gm.query.hero dead kingdomruler

Result: Filtered results showing only heroes matching all criteria (AND) or any criteria (OR).

Example 3: Clan Power Analysis

Analyze clan strength and resources:

gm.query.clan sort:gold:desc
gm.query.clan noble sort:renown:desc
gm.query.clan_info clan_empire_south_1

Result: Sorted clan lists showing wealthiest and most prestigious clans, detailed clan information.

Example 4: Troop Discovery

Find specific troop types for army building:

gm.query.troop imperial tier3
gm.query.troop battanian ranged tier4
gm.query.troop cavalry tier5 sort:level:desc

Result: Filtered troop lists showing specific unit types by culture, tier, and equipment.

Example 5: Item Search Workflow

Locate items before adding to inventory:

gm.query.item sword tier4
gm.query.item armor empire tier5
gm.query.item_categories
gm.item.add imperial_sword 5 player

Result: Found exact item identifiers, verified availability, executed add command.

Best Practices

TIP: Always Query Before Management

Use query commands before executing management operations:

gm.query.hero target_name
gm.hero.set_gold target_stringid 10000

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

TIP: Use Info Commands for Verification

Detailed info commands provide comprehensive state verification:

gm.query.hero_info lord_1_1
gm.query.clan_info clan_empire_south_1
gm.query.kingdom_info empire

Confirms current state before making changes.

TIP: Leverage Sorting for Analysis

Sort results to identify patterns and extremes:

gm.query.clan sort:gold:desc
gm.query.hero sort:age
gm.query.kingdom sort:strength:desc

Reveals richest clans, oldest heroes, most powerful kingdoms.

TIP: Combine Text and Type Filters

Mix search terms with type keywords for precise results:

gm.query.hero battania female clanleader
gm.query.clan empire noble sort:tier:desc

Narrows results to very specific criteria.

TIP: Use OR Logic for Broad Exploration

When unsure of exact criteria, use OR logic:

gm.query.hero_any lord wanderer notable
gm.query.clan_any mercenary rebel outlaw

Casts wider net for entity discovery.

Notes & Warnings

NOTE: AND vs OR Logic

Understanding search logic is critical:

  • AND Logic (gm.query.hero) - ALL criteria must match
  • OR Logic (gm.query.hero_any) - ANY criteria matches

Example:

  • gm.query.hero empire lord female - Must be Empire AND lord AND female
  • gm.query.hero_any lord wanderer - Can be lord OR wanderer

NOTE: Default Filters

Some queries have default filtering:

  • Hero queries - Default to living heroes (use dead keyword for deceased)
  • Clan queries - Default to active clans (use eliminated for destroyed)
  • Kingdom queries - Default to active kingdoms (use eliminated for destroyed)

NOTE: Partial Name Matching

Text search supports partial matches:

  • "rag" matches "Raganvad"
  • "empire" matches "Southern Empire", "Northern Empire"
  • "bat" matches "Battania", "Battanian"

Be specific to avoid unintended matches.

NOTE: StringId Precision

For commands that modify game state, always use exact StringIds obtained from query results rather than partial names to ensure precision.

NOTE: Sorting Performance

Sorting large result sets (100+ entities) may take slightly longer. Use filters to narrow results before sorting when possible.

NOTE: Query Safety

Query commands are read-only and never modify game state. They are completely safe to use for exploration and experimentation.

Related Documentation

Command Groups

Reference Materials

User Guides

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

Return to API Reference | Home

Quick Links

🏠 Home | Quick Reference | Syntax Guide

Hero Commands
Clan Commands
Kingdom Commands
Settlement Commands
Item Commands
Troop Commands
Caravan Commands
Bandit Commands
Query Commands

Clone this wiki locally