API Troop upgrade_troops

upgrade_troops

Endpoint: gm.troops.upgrade_troops

Syntax

gm.troops.upgrade_troops <partyLeader> [tier] [infantryRatio] [rangedRatio] [calvaryRatio]

Parameters

Parameter	Type	Required	Default	Description
partyLeader	string	Yes	-	Query to find the party leader hero (e.g., "player", "raganvad")
tier	integer	No	7	Target tier for troop upgrades (1-7)
infantryRatio	float	No	0.5	Ratio of infantry troops to maintain (0.0-1.0)
rangedRatio	float	No	0.3	Ratio of ranged troops to maintain (0.0-1.0)
calvaryRatio	float	No	0.2	Ratio of cavalry troops to maintain (0.0-1.0)

Requirements

• Hero must be a party leader
• Hero must have a party with troops
• All ratios must add up to 1.0
• If only 1 or 2 ratios are specified, remaining ratios default to evenly split the remainder

Description

Upgrades all troops in the hero's party to the specified tier or to the maximum tier available for that troop type if the specified tier exceeds the troop's upgrade tree. The command intelligently attempts to maintain the specified ratio of troop types (infantry, ranged, cavalry) during the upgrade process.

If a troop cannot be upgraded to the target tier (e.g., tier 7 requested but troop maxes at tier 5), the command upgrades to the highest tier possible for that troop.

Examples

Example 1: Upgrade to max tier with default ratios

gm.troops.upgrade_troops player

Output:

Upgraded troops in Player's party to tier 7.
Infantry: 50%, Ranged: 30%, Cavalry: 20%
Party: Player's Army

Example 2: Upgrade to tier 5 with default ratios

gm.troops.upgrade_troops player 5

Output:

Upgraded troops in Player's party to tier 5.
Infantry: 50%, Ranged: 30%, Cavalry: 20%
Party: Player's Army

Example 3: Upgrade with custom ratios

gm.troops.upgrade_troops raganvad 6 0.4 0.4 0.2

Output:

Upgraded troops in Raganvad's party to tier 6.
Infantry: 40%, Ranged: 40%, Cavalry: 20%
Party: Raganvad's Army

Example 4: Upgrade with partial ratios

gm.troops.upgrade_troops derthert 7 0.6 0.3

Output:

Upgraded troops in Derthert's party to tier 7.
Infantry: 60%, Ranged: 30%, Cavalry: 10%
Party: Derthert's Army

Note: The cavalry ratio was automatically set to 0.1 to make the total equal 1.0.

Example 5: Upgrade lord's army

gm.troops.upgrade_troops lord_1_1 6

Notes

NOTE: Use gm.query.hero to find exact hero IDs if needed.

NOTE: The command respects troop upgrade trees - troops will only upgrade along their available paths.

NOTE: If a troop's maximum tier is lower than the requested tier, it will upgrade to its maximum available tier.

TIP: Use higher ratios for troop types you want to emphasize in your army composition.

TIP: Experiment with different ratios to create specialized armies (e.g., 0.7 infantry for defensive armies, 0.5 cavalry for mobile forces).

WARNING: Ratios must add up to exactly 1.0 or the command will fail validation.

WARNING: This command only works for party leaders, not party members.

Ratio Behavior

The ratio system provides flexible army composition:

Default Ratios (no ratios specified):

• Infantry: 0.5 (50%)
• Ranged: 0.3 (30%)
• Cavalry: 0.2 (20%)

Partial Ratios: If you specify fewer than 3 ratios, the remaining ratios are automatically calculated to sum to 1.0:

• gm.troops.upgrade_troops player 7 0.6 → Infantry: 0.6, Ranged: 0.2, Cavalry: 0.2
• gm.troops.upgrade_troops player 7 0.4 0.4 → Infantry: 0.4, Ranged: 0.4, Cavalry: 0.2

Custom Ratios: All three ratios must add up to exactly 1.0:

• Valid: 0.5 0.3 0.2 (sum = 1.0)
• Valid: 0.33 0.33 0.34 (sum = 1.0)
• Invalid: 0.6 0.3 0.3 (sum = 1.2)

Related Commands

• gm.troops.give_xp - Give experience to all troops in party
• gm.troops.give_hero_troops - Add specific troops to party
• gm.query.troop - Search for troop types
• gm.query.hero - Search for heroes

Last Updated: 2025-12-27 API Version: 1.3.13.1