API Query Troop troop

gm.query.troop

Endpoint: gm.query.troop

Syntax

gm.query.troop [search_terms...] [type_flags...] [sort:field[:order]]

Description

Search and list troops based on search terms, type filters, tier levels, and sorting options. Supports AND logic (all specified filters must match). The system automatically filters out heroes, lords, and non-combat NPCs to show only actual military units.

Parameters

Parameter	Type	Required	Description
search_terms	string	No	Text to match against troop name or ID
type_flags	flags	No	Filter by troop types (see Type Flags below)
sort:field[:order]	string	No	Sort results (see Sorting Options below)

Type Flags

Formation Types:

• infantry - Infantry formation troops
• ranged - Ranged formation troops (archers)
• cavalry - Cavalry formation troops (mounted melee)
• horsearcher - Horse archer formation troops (mounted ranged)
• mounted - All mounted troops (cavalry + horse archers)

Troop Line Types:

• regular - Regular/main culture troop line
• noble - Noble/elite troop line (knights, nobles)
• militia - Militia/garrison troops
• mercenary - Mercenary troops
• caravan - Caravan guards, caravan masters, armed traders
• peasant - Combat-capable villagers and townsfolk
• minorfaction - Minor faction troops (Eleftheroi, Brotherhood, etc.)

Equipment Types:

• shield - Troops with shields
• 2h / twohanded - Troops with two-handed weapons
• polearm - Troops with polearms
• bow - Troops with bows
• crossbow - Troops with crossbows
• throwing - Troops with throwing weapons

Tier Keywords:

• tier0 through tier6 - Tier 0-6 troops
• tier6plus - Tier 6+ troops (includes tier 7+ if modded)

Culture Keywords:

• empire - Empire culture troops
• vlandia - Vlandian culture troops
• sturgia - Sturgian culture troops
• aserai - Aserai culture troops
• khuzait - Khuzait culture troops
• battania - Battanian culture troops
• nord - Nord culture troops (Warsails DLC)
• bandit - Bandit culture troops

Sorting Options

• sort:id - Sort by StringId (default)
• sort:name - Sort alphabetically by name
• sort:tier - Sort by tier level (0-6+)
• sort:level - Sort by troop level
• sort:culture - Sort by culture name
• sort:occupation - Sort by occupation type
• sort:formation - Sort by formation class
• sort:[type_flag] - Sort by any type flag (e.g., sort:noble, sort:cavalry)

Add :desc for descending order or :asc for ascending (default):

• sort:tier:desc - Sort by tier, highest first
• sort:level:desc - Sort by level, highest first

Examples

Basic search by name:

gm.query.troop legionary
gm.query.troop archer
gm.query.troop knight

Filter by formation type:

gm.query.troop infantry
gm.query.troop ranged
gm.query.troop cavalry
gm.query.troop horsearcher

Filter by equipment type:

gm.query.troop shield
gm.query.troop bow
gm.query.troop crossbow
gm.query.troop polearm

Filter by tier:

gm.query.troop tier3
gm.query.troop tier5
gm.query.troop tier6plus

Filter by culture:

gm.query.troop empire
gm.query.troop vlandia
gm.query.troop battania

Combined filtering:

gm.query.troop imperial infantry tier3
gm.query.troop battania ranged bow tier4
gm.query.troop empire cavalry noble tier5
gm.query.troop vlandia infantry shield tier2

Sort results:

gm.query.troop sort:name
gm.query.troop sort:tier:desc
gm.query.troop cavalry sort:level:desc
gm.query.troop infantry sort:culture

Complex queries:

gm.query.troop empire cavalry noble tier5 sort:level:desc
gm.query.troop battania infantry shield tier3 sort:name
gm.query.troop aserai horsearcher tier4 sort:tier

Output

Success:

Found N troop(s) matching [criteria]:
[StringId]    [Name]    [Category]    Tier: [Tier]    Level: [Level]    Culture: [Culture]    Formation: [Formation]

Example output:

Found 3 troop(s) matching search: 'imperial', types: cavalry:
imperial_cavalry    Imperial Cavalry    [Regular]    Tier: 3    Level: 18    Culture: Empire    Formation: Cavalry
imperial_elite_cavalry    Imperial Elite Cavalry    [Noble/Elite]    Tier: 5    Level: 30    Culture: Empire    Formation: Cavalry
imperial_cataphract    Imperial Cataphract    [Noble/Elite]    Tier: 6    Level: 32    Culture: Empire    Formation: Cavalry

Automatic Filtering

The system automatically excludes:

• Heroes and lords (use hero query commands)
• Town NPCs (merchants, blacksmiths, etc.)
• Wanderers and companions
• Children and teenagers
• Templates and test characters
• Non-combat civilians

Notes

NOTE: Troops are CharacterObjects representing nameless units. Heroes and lords are NOT troops - use hero query commands for them.

TIP: The category display (e.g., [Regular], [Noble/Elite]) helps quickly identify troop classification.

TIP: Start broad with formation type, then narrow with tier and culture filters.

Related Commands

• gm.query.troop_any - Search with OR logic
• gm.query.troop_info - Get detailed troop information
• API-Query-Overview - All query commands

Last Updated: 2025-12-16