Template:Op troops

Troops
What troops are.

There are two major types of troops: heroes and regulars. They are treated very differently by the game, so it's important not to confuse them. At the same time, most Module System operations will not make any differentiation between hero and regular troops.

First of all, hero troops do not stack. You cannot have a stack of heroes in a party, each hero will always occupy a separate troop slot. At the same time, you can put any number of regular troops into a single troop slot.

Second, the way the game treats equipment of heroes and troops is also different. All heroes' items are treated in the same way as player's (no big surprise, since player is actually a hero troop himself). Meanwhile, items that the troop has are just suggestions for what this troop *might* take into battle. On the battlefield, each agent spawned from the regular troop, will only take a limited number of items from the inventory provided by the troop definition in module_troops.py. Choice is absolutely random (Vetrogor: it is not random. If you restart battle with 2 agents of the same troop their equipment will be the same. For research...) and modder has only limited control over it through the use of guarantee flags.

There's one more additional caveat: while you can easily change the outfit of a hero troop and your changes will persist through the game, same applies to regular troops. In other words, by changing equipment of some regular troop, you are changing all instances of that troop throughout the entire game. In other words, you cannot re-equip a stack of regulars in a single party - your changes will affect all parties in the world.

Third, while all heroes have a single predefined face code, which is used consistently through the game, troops have entire range of face codes. This range is used to randomize each agent's face within those constraints, so a group of 12 pikemen will not look like a bunch of clones.

Fourth, hero troops can't be killed in battle. Every time hero's hit points are reduced to zero, hero is always knocked down. For regular troops, chance to be knocked down depends on the number of factors, but their default fate when driven to zero health is death.

Conditional operators
troop_has_item_equipped = 151
 * (troop_has_item_equipped, , ),
 * Checks that the troop has this item equipped (worn or wielded).

troop_is_mounted = 152
 * (troop_is_mounted, ),
 * Checks the troop for tf_mounted flag (see header_troops.py). Does NOT check that the troop has a horse.

troop_is_guarantee_ranged = 153
 * (troop_is_guarantee_ranged, ),
 * Checks the troop for tf_guarantee_ranged flag (see header_troops.py). Does not check that troop actually has some ranged weapon.

troop_is_guarantee_horse = 154
 * (troop_is_guarantee_horse, ),
 * Checks the troop for tf_guarantee_horse flag (see header_troops.py). Does not check that troop actually has some horse.

troop_is_hero = 1507
 * (troop_is_hero, ),
 * Checks the troop for tf_hero flag (see header_troops.py). Hero troops are actual characters and do not stack in party window.

troop_is_wounded = 1508
 * (troop_is_wounded, ),
 * Checks that the troop is wounded. Only works for hero troops.

player_has_item = 150
 * (player_has_item, ),
 * Checks that player has the specified item.

Slot operations for troops
Slots numbers start from 0 and end at maximum 1'048'575=0xFFFFF. Any other slot will return 0 as value.

troop_set_slot = 500
 * (troop_set_slot, , , ),

troop_get_slot = 520
 * (troop_get_slot,, , ),

troop_slot_eq = 540
 * (troop_slot_eq, , , ),

troop_slot_ge = 560
 * (troop_slot_ge, , , ),

Troop attributes and skills
troop_set_type = 1505
 * (troop_set_type, <troop_id>, ),
 * Changes the troop skin. There are two skins in Native: male and female, so in effect this operation sets troop gender. However mods may declare other skins.

troop_get_type = 1506
 * (troop_get_type,, <troop_id>),
 * Returns troop current skin (i.e. gender).

troop_set_class = 1517
 * (troop_set_class, <troop_id>, ),
 * Sets troop class (infantry, archers, cavalry or any of custom classes). Accepts values in range 0..8. See grc_* constants in header_mission_templates.py.

troop_get_class = 1516
 * (troop_get_class,, <troop_id>),
 * Retrieves troop class. Returns values in range 0..8.

class_set_name = 1837
 * (class_set_name, <sub_class>, <string_id>),
 * Sets a new name for troop class (aka "Infantry", "Cavalry", "Custom Group 3"...).

add_xp_to_troop = 1062
 * (add_xp_to_troop,, [troop_id]),
 * Adds some xp points to troop. Only makes sense for player and hero troops. Default troop_id is player. Amount of xp can be negative.

add_xp_as_reward = 1064
 * (add_xp_as_reward, ),
 * Adds the specified amount of xp points to player. Typically used as a quest reward operation.

troop_get_xp = 1515
 * (troop_get_xp,, <troop_id>),
 * Retrieves total amount of xp specified troop has.

store_attribute_level = 2172
 * (store_attribute_level,, <troop_id>, <attribute_id>),
 * Stores current value of troop attribute. See ca_* constants in header_troops.py for reference.

troop_raise_attribute = 1520
 * (troop_raise_attribute, <troop_id>, <attribute_id>, ),
 * Increases troop attribute by the specified amount. See ca_* constants in header_troops.py for reference. Use negative values to reduce attributes. When used on non-hero troop, will affect all instances of that troop.

store_skill_level = 2170
 * (store_skill_level,, <skill_id>, [troop_id]),
 * Stores current value of troop skill. See header_skills.py for reference.

troop_raise_skill = 1521
 * (troop_raise_skill, <troop_id>, <skill_id>, ),
 * Increases troop skill by the specified value. Value can be negative. See header_skills.py for reference. When used on non-hero troop, will affect all instances of that troop.

store_proficiency_level = 2176
 * (store_proficiency_level,, <troop_id>, <attribute_id>),
 * Stores current value of troop weapon proficiency. See wpt_* constants in header_troops.py for reference.

troop_raise_proficiency = 1522
 * (troop_raise_proficiency, <troop_id>, <proficiency_no>, ),
 * Increases troop weapon proficiency by the specified value. Value can be negative. Increase is subject to limits defined by Weapon Master skill. When used on non-hero troop, will affect all instances of that troop.

troop_raise_proficiency_linear = 1523
 * (troop_raise_proficiency_linear, <troop_id>, <proficiency_no>, ),
 * Same as (troop_raise_proficiency), but does not take Weapon Master skill into account (i.e. can increase proficiencies indefinitely).

troop_add_proficiency_points = 1525
 * (troop_add_proficiency_points, <troop_id>, ),
 * Adds some proficiency points to a hero troop which can later be distributed by player.

store_troop_health = 2175
 * (store_troop_health,, <troop_id>, [absolute]),: set absolute to 1 to get actual health; otherwise this will return percentage health in range (0-100)
 * Retrieves current troop health. Use absolute = 1 to retrieve actual number of hp points left, use absolute = 0 to retrieve a value in 0..100 range (percentage).

troop_set_health = 1560
 * (troop_set_health, <troop_id>, <relative health (0-100)>),
 * Sets troop health. Accepts value in range 0..100 (percentage).

troop_get_upgrade_troop = 1561
 * (troop_get_upgrade_troop,, <troop_id>, <upgrade_path>),
 * Retrieves possible directions for non-hero troop upgrade. Use 0 to retrieve first upgrade path, and 1 to return second. Result of -1 means there's no such upgrade path for this troop.

store_character_level = 2171
 * (store_character_level,, [troop_id]),
 * Retrieves character level of the troop. Default troop is the player.

get_level_boundary = 991
 * (get_level_boundary,, <level_no>),
 * Returns the amount of experience points required to reach the specified level (will return 0 for 1st level). Maximum possible level in the game is 63.

add_gold_as_xp = 1063
 * (add_gold_as_xp,, [troop_id]),: Default troop is player
 * Adds a certain amount of experience points, depending on the amount of gold specified. Conversion rate is unclear and apparently somewhat randomized (three runs with 1000 gold produced values 1091, 804 and 799).

Troop equipment handling
troop_set_auto_equip = 1509
 * (troop_set_auto_equip, <troop_id>, ),
 * Sets (value = 1) or disables (value = 0) auto-equipping the troop with any items added to it's inventory or purchased. Similar to tf_is_merchant flag.

troop_ensure_inventory_space = 1510
 * (troop_ensure_inventory_space, <troop_id>, ),
 * Removes items from troop inventory until troop has specified number of free inventory slots. Will free inventory slots starting from the end (items at the bottom of inventory will be removed first if there's not enough free space).

troop_sort_inventory = 1511
 * (troop_sort_inventory, <troop_id>),
 * Sorts items in troop inventory by their price (expensive first).

troop_add_item = 1530
 * (troop_add_item, <troop_id>, <item_id>, [modifier]),
 * Adds an item to the troop, optionally with a modifier (see imod_* constants in header_item_modifiers.py).

troop_remove_item = 1531
 * (troop_remove_item, <troop_id>, <item_id>),
 * Removes an item from the troop equipment or inventory. Operation will remove first matching item it finds.

troop_clear_inventory = 1532
 * (troop_clear_inventory, <troop_id>),
 * Clears entire troop inventory. Does not affect equipped items.

troop_equip_items = 1533
 * (troop_equip_items, <troop_id>),
 * Makes the troop reconsider it's equipment. If troop has better stuff in it's inventory, he will equip it. Note this operation sucks with weapons and may force the troop to equip himself with 4 two-handed swords.

troop_inventory_slot_set_item_amount = 1534
 * (troop_inventory_slot_set_item_amount, <troop_id>, <inventory_slot_no>, ),
 * Sets the stack size for a specified equipment or inventory slot. Only makes sense for items like ammo or food (which show stuff like "23/50" in inventory). Equipment slots are in range 0..9, see ek_* constants in header_items.py for reference.

troop_inventory_slot_get_item_amount = 1537
 * (troop_inventory_slot_get_item_amount,, <troop_id>, <inventory_slot_no>),
 * Retrieves the stack size for a specified equipment or inventory slot (if some Bread is 23/50, this operation will return 23).

troop_inventory_slot_get_item_max_amount = 1538
 * (troop_inventory_slot_get_item_max_amount,, <troop_id>, <inventory_slot_no>),
 * Retrieves the maximum possible stack size for a specified equipment or inventory slot (if some Bread is 23/50, this operation will return 50).

troop_add_items = 1535
 * (troop_add_items, <troop_id>, <item_id>, ),
 * Adds multiple items of specified type to the troop.

troop_remove_items = 1536
 * (troop_remove_items, <troop_id>, <item_id>, ),
 * Removes multiple items of specified type from the troop. Total price of actually removed items will be stored in reg0. Doesn't take item modifiers. Will not fail if <troop_id> does not have the required items.

troop_loot_troop = 1539
 * (troop_loot_troop, <target_troop>, <source_troop_id>, ),
 * Adds to target_troop's inventory some items from source_troop's equipment and inventory with some probability. Does not actually remove items from source_troop. Commonly used in Native to generate random loot after the battle.

troop_get_inventory_capacity = 1540
 * (troop_get_inventory_capacity,, <troop_id>),
 * Returns the total inventory capacity (number of inventory slots) for the specified troop. Note that this number will include equipment slots as well. Substract num_equipment_kinds (see header_items.py) to get the number of actual *inventory* slots.

troop_get_inventory_slot = 1541
 * (troop_get_inventory_slot,, <troop_id>, <inventory_slot_no>),
 * Retrieves the item_id of a specified equipment or inventory slot. Returns -1 when there's nothing there.

troop_get_inventory_slot_modifier = 1542
 * (troop_get_inventory_slot_modifier,, <troop_id>, <inventory_slot_no>),
 * Retrieves the modifier value (see imod_* constants in header_items.py) for an item in the specified equipment or inventory slot. Returns 0 when there's nothing there, or if item does not have any modifiers.

troop_set_inventory_slot = 1543
 * (troop_set_inventory_slot, <troop_id>, <inventory_slot_no>, <item_id>),
 * Puts the specified item into troop's equipment or inventory slot. Be careful with setting equipment slots this way.

troop_set_inventory_slot_modifier = 1544
 * (troop_set_inventory_slot_modifier, <troop_id>, <inventory_slot_no>, <imod_value>),
 * Sets the modifier for the item in the troop's equipment or inventory slot. See imod_* constants in header_items.py for reference.

store_item_kind_count = 2165
 * (store_item_kind_count,, <item_id>, [troop_id]),
 * Calculates total number of items of specified type that the troop has. Default troop is player.

store_free_inventory_capacity = 2167
 * (store_free_inventory_capacity,, [troop_id]),
 * Calculates total number of free inventory slots that the troop has. Default troop is player.

Merchandise handling
reset_price_rates = 1170
 * (reset_price_rates),
 * Resets customized price rates for merchants.

set_price_rate_for_item = 1171
 * (set_price_rate_for_item, <item_id>, <value_percentage>),
 * Sets individual price rate for a single item type. Normal price rate is 100. Deprecated, as Warband uses (game_get_item_[buy/sell]_price_factor) scripts instead.

set_price_rate_for_item_type = 1172
 * (set_price_rate_for_item_type, <item_type_id>, <value_percentage>),
 * Sets individual price rate for entire item class (see header_items.py for itp_type_* constants). Normal price rate is 100. Deprecated, as Warband uses (game_get_item_[buy/sell]_price_factor) scripts instead.

set_merchandise_modifier_quality = 1490
 * (set_merchandise_modifier_quality, ),
 * Affects the probability of items with quality modifiers appearing in merchandise. Value is percentage, standard value is 100.

set_merchandise_max_value = 1491
 * (set_merchandise_max_value, ),
 * Not used in Native. Apparently prevents items with price higher than listed from being generated as merchandise.

reset_item_probabilities = 1492
 * (reset_item_probabilities, ),
 * Sets all items probability of being generated as merchandise to the provided value. Use zero with subsequent calls to (set_item_probability_in_merchandise) to only allow generation of certain items.

set_item_probability_in_merchandise = 1493
 * (set_item_probability_in_merchandise, <item_id>, ),
 * Sets item probability of being generated as merchandise to the provided value.

troop_add_merchandise = 1512
 * (troop_add_merchandise, <troop_id>, <item_type_id>, ),
 * Adds a specified number of random items of certain type (see itp_type_* constants in header_items.py) to troop inventory. Only adds items with itp_merchandise flags.

troop_add_merchandise_with_faction = 1513
 * (troop_add_merchandise_with_faction, <troop_id>, <faction_id>, <item_type_id>, ),:faction_id is given to check if troop is eligible to produce that item
 * Same as (troop_add_merchandise), but with additional filter: only adds items which belong to specified faction, or without any factions at all.

Miscellaneous troop information
troop_set_name = 1501
 * (troop_set_name, <troop_id>, <string_no>),
 * Renames the troop, setting a new singular name for it.

troop_set_plural_name = 1502
 * (troop_set_plural_name, <troop_id>, <string_no>),
 * Renames the troop, setting a new plural name for it.

troop_set_face_key_from_current_profile = 1503
 * (troop_set_face_key_from_current_profile, <troop_id>),
 * Forces the troop to adopt the face from player's currently selected multiplayer profile.

troop_add_gold = 1528
 * (troop_add_gold, <troop_id>, ),
 * Adds gold to troop. Generally used with player or hero troops.

troop_remove_gold = 1529
 * (troop_remove_gold, <troop_id>, ),
 * Removes gold from troop. Generally used with player or hero troops.

store_troop_gold = 2149
 * (store_troop_gold,, <troop_id>),
 * Retrieves total number of gold that the troop has.

troop_set_faction = 1550
 * (troop_set_faction, <troop_id>, <faction_id>),
 * Sets a new faction for the troop (mostly used to switch lords allegiances in Native).

store_troop_faction = 2173
 * (store_troop_faction,, <troop_id>),
 * Retrieves current troop faction allegiance.

store_faction_of_troop = 2173
 * (store_faction_of_troop,, <troop_id>),
 * Alternative spelling of the above operation.

troop_set_age = 1555
 * (troop_set_age, <troop_id>, <age_slider_pos>),
 * Defines a new age for the troop (will be used by the game engine to generate appropriately aged face). Age is in range 0.100. {slot_troop_age} and {slot_troop_age_appearance} will not be set.

store_troop_value = 2231
 * (store_troop_value,, <troop_id>),
 * Stores some value which is apparently related to troop's overall fighting value. Swadian infantry line troops from Native produced values 24, 47, 80, 133, 188. Calling on player produced 0.

Troop face code handling
str_store_player_face_keys = 2747
 * (str_store_player_face_keys, <string_no>, <player_id>),
 * Version 1.161+. Stores player's face keys into string register.

player_set_face_keys = 2748
 * (player_set_face_keys, <player_id>, <string_no>),
 * Version 1.161+. Sets player's face keys from string.

str_store_troop_face_keys = 2750
 * (str_store_troop_face_keys, <string_no>, <troop_no>, [ ]),
 * Version 1.161+. Stores specified troop's face keys into string register. Use optional parameter to determine what facekey set to retrieve: 0 for first and 1 for second.

troop_set_face_keys = 2751
 * (troop_set_face_keys, <troop_no>, <string_no>, [ ]),
 * Version 1.161+. Sets troop face keys from string. Use optional parameter to determine what face keys to update: 0 for first and 1 for second.

face_keys_get_hair = 2752
 * (face_keys_get_hair,, <string_no>),
 * Version 1.161+. Unpacks selected hair mesh from string containing troop/player face keys to.

face_keys_set_hair = 2753
 * (face_keys_set_hair, <string_no>, ),
 * Version 1.161+. Updates face keys string with a new hair value. Hair meshes associated with skin (as defined in module_skins) are numbered from 1. Use 0 for no hair.

face_keys_get_beard = 2754
 * (face_keys_get_beard,, <string_no>),
 * Version 1.161+. Unpacks selected beard mesh from string containing troop/player face keys to.

face_keys_set_beard = 2755
 * (face_keys_set_beard, <string_no>, ),
 * Version 1.161+. Updates face keys string with a new beard value. Beard meshes associated with skin (as defined in module_skins) are numbered from 1. Use 0 for no beard.

face_keys_get_face_texture = 2756
 * (face_keys_get_face_texture,, <string_no>),
 * Version 1.161+. Unpacks selected face texture from string containing troop/player face keys to.

face_keys_set_face_texture = 2757
 * (face_keys_set_face_texture, <string_no>, ),
 * Version 1.161+. Updates face keys string with a new face texture value. Face textures associated with skin (as defined in module_skins) are numbered from 0.

face_keys_get_hair_texture = 2758
 * (face_keys_get_hair_texture,, <string_no>),
 * Version 1.161+. Unpacks selected hair texture from string containing troop/player face keys to . Apparently hair textures have no effect. 4 research.

face_keys_set_hair_texture = 2759
 * (face_keys_set_hair_texture, <string_no>, ),
 * Version 1.161+. Updates face keys string with a new hair texture value. Doesn't seem to have an effect. 4research.

face_keys_get_hair_color = 2760
 * (face_keys_get_hair_color,, <string_no>),
 * Version 1.161+. Unpacks hair color slider value from face keys string. Values are in the range of 0..63. Mapping to specific colors depends on the hair color range defined for currently selected skin / face_texture combination.

face_keys_set_hair_color = 2761
 * (face_keys_set_hair_color, <string_no>, ),
 * Version 1.161+. Updates face keys string with a new hair color slider value. Value should be in the 0..63 range.

face_keys_get_age = 2762
 * (face_keys_get_age,, <string_no>),
 * Version 1.161+. Unpacks age slider value from face keys string. Values are in the range of 0..63.

face_keys_set_age = 2763
 * (face_keys_set_age, <string_no>, ),
 * Version 1.161+. Updates face keys string with a new age slider value. Value should be in the 0..63 range.

face_keys_get_skin_color = 2764
 * (face_keys_get_skin_color,, <string_no>),
 * Version 1.161+. Apparently doesn't work. Should retrieve skin color value from face keys string into.

face_keys_set_skin_color = 2765
 * (face_keys_set_skin_color, <string_no>, ),
 * Version 1.161+. Apparently doesn't work. Should update face keys string with a new skin color value.

face_keys_get_morph_key = 2766
 * (face_keys_get_morph_key,, <string_no>, <key_no>),
 * Version 1.161+. Unpacks morph key value from face keys string. See morph key indices in module_skins.py file. Note that only 8 out of 27 morph keys are actually accessible (from 'chin_size' to 'cheeks'). Morph key values are in the 0..7 range.

face_keys_set_morph_key = 2767
 * (face_keys_set_morph_key, <string_no>, <key_no>, ),
 * Version 1.161+. Updates face keys string with a new morph key value. See morph key indices in module_skins.py file. Note that only 8 out of 27 morph keys are actually accessible (from 'chin_size' to 'cheeks'). Morph key values should be in the 0..7 range.