API Query Hero hero

gm.query.hero

Endpoint: gm.query.hero

Syntax

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

Description

Search for heroes using text search and type filters with AND logic (all criteria must match). Supports flexible combinations of search terms and type keywords. Without specifying life status keywords, defaults to showing only living heroes.

Parameters

Parameter	Type	Required	Description
search_terms	string	No	Text to search in hero names, IDs, clan names, and kingdom names
type_flags	flags	No	Filter by hero types (see Type Flags below)
sort:field[:order]	string	No	Sort results by field (see Sorting Options below)

Type Flags

Status Types:

• lord - Noble lords
• wanderer - Companions available in taverns
• notable - Settlement notables
• merchant - Merchant heroes
• child - Child heroes
• alive - Living heroes (default)
• dead - Deceased heroes
• prisoner - Imprisoned heroes
• fugitive - Heroes on the run

Gender:

• female - Female heroes
• male - Male heroes

Roles:

• clanleader - Clan leaders
• kingdomruler - Kingdom rulers
• partyleader - Party leaders

Relationships:

• married - Married heroes
• withoutclan - Heroes without a clan
• withoutkingdom - Heroes without a kingdom

Sorting Options

• sort:id - Sort by StringId (default)
• sort:name - Sort alphabetically by name
• sort:age - Sort by age
• sort:clan - Sort by clan name
• sort:kingdom - Sort by kingdom name
• sort:[type_flag] - Sort by any type flag (e.g., sort:wanderer, sort:lord)

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

• sort:name:desc - Sort Z to A
• sort:age:desc - Sort oldest first
• sort:age:asc - Sort youngest first

Examples

Find female lords in Empire:

gm.query.hero empire lord female

Find all wanderers:

gm.query.hero wanderer

Find dead kingdom rulers:

gm.query.hero dead kingdomruler

Search by name:

gm.query.hero john

Sort heroes by name:

gm.query.hero sort:name

Sort by age (oldest first):

gm.query.hero sort:age:desc

Sort lords by clan name:

gm.query.hero lord sort:clan

Sort by wanderer type (wanderers first):

gm.query.hero sort:wanderer

Output

Success:

Found N hero(es) matching [criteria]:
[Name] ([StringId]) - Clan: [ClanName], Kingdom: [KingdomName], Age: [Age], Status: [Alive/Dead/Prisoner]

Notes

NOTE: Without type keywords specifying life status, the command defaults to showing only living heroes. Use dead keyword to search deceased heroes.

TIP: Use this command before management commands to find exact StringIds and ensure you're targeting the correct heroes.

Related Commands

• gm.query.hero_any - Search with OR logic
• gm.query.hero_info - Get detailed hero information
• API-Query-Overview - All query commands

Last Updated: 2025-12-16