Battle Documentation

Scripting Homepage

Search

Search battle only




Game Areas

• Campaign Index
• > Battle Index
• Frontend Index

On this page

Key

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

• Unit
•   Creation
•   Usage
•   Scriptunits and Generated Battles
•   Identification
•     name
•     unique_ui_id
•     type
•     alliance_index
•     army_index
•     unit_class
•     is_cavalry
•     is_infantry
•     is_artillery
•     is_limbered_artillery
•     is_commanding_unit
•   Location and Movement
•     position
•     ordered_position
•     can_reach_position
•     bearing
•     ordered_bearing
•     ordered_width
•     position_of_officer
•     unit_in_range
•     unit_distance
•     is_moving
•     is_moving_fast
•     is_idle
•     is_leaving_battle
•     is_valid_target
•     is_currently_garrisoned
•     is_currently_flying
•     can_fly
•     has_ships
•     is_dismounted_ships
•   Visibility
•     is_hidden
•     is_visible_to_alliance
•   Combat
•     is_under_missile_attack
•     is_in_melee
•     number_of_enemies_killed
•   Unit Strength
•     initial_number_of_men
•     number_of_men_alive
•     unary_of_men_alive
•     kill_number_of_men
•     unary_hitpoints
•   Morale and Fatigue
•     is_wavering
•     is_routing
•     is_rampaging
•     is_shattered
•     is_left_flank_threatened
•     is_right_flank_threatened
•     is_rear_flank_threatened
•     fatigue_state
•   Ammunition and Range
•     ammo_left
•     starting_ammo
•     set_current_ammo_unary
•     missile_range
•   Special Abilities
•     can_perform_special_ability
•     can_use_magic
•   Unit Behaviours
•     can_use_behaviour
•     is_behaviour_active
•   Unit Attributes
•     set_stat_attribute
•   Sounds
•     trigger_sound_charge
•     trigger_sound_taunt
•   Miscellaneous
•     play_anim_for_captain
•     deploy_reinforcement
•     select_in_ui
•     mark_as_ally

Battle Topics

• Battle Index
• Battle Hierarchy
• Lua Language
• Scripted Events

Game Code Pages

• Battle
• Alliances
• Alliance
• Armies
• Army
• Units
• > Unit
• Unitcontroller
• AI Planners
• Assault Equipment
• Building
• Buildings
• Camera
• Debug Drawing
• Sound Effects
• Subtitles
• Vector
• Effect
• ScriptedValueRegistry
• UIComponents

Script Pages

• Battle Manager
• Core
• Advice Manager
• Battle UI Manager
• Convex Areas
• Battle Cutscenes
• Generated Battle
• Global
• Infotext Manager
• Objectives Manager
• Script AI Planner
• Script Messager
• Script Unit
• Text Pointers
• Timer Manager

Unit

A unit object may be created in script to represent a logical unit of soldiers taking part in the battle. The unit object interface permits querying of the state of the unit - to issue orders to the unit a battle_unitcontroller object must be created to which the unit object may then be associated.

Loaded in Battle

Unit objects are created from the battle_hierarchy. They appear at the bottom of this hierarchy - see the battle_hierarchy page for more information on how unit objects relate to (and are created from) armies and alliances. Alternatively, and preferably, see the section on scriptunits below for a shorthand method of unit object creation.

Once a handle to a sound effect object is obtained, functions may be called on it to query or modify its state in the following form.

Example - Specification:

Example - Creation and Usage:

It is highly recommended for client scripts to work with script_unit objects through the interface provided by the script libraries rather than attempting to manage unit objects individually. By creating a script_unit object, a unit object is automatically created and can be accessed at <script_unit>.unit. See the script_unit documentation for more information.

Alternatively the generated_battle script framework can be used. This automatically creates script_unit objects (with associated unit objects) and negates the need to set up references to anything more granular than an army.

Unit attributes define certain intrinsic properties of a unit in battle. Attributes are generally assigned to a unit type in the game database, but may be enabled or disabled per-unit in script using the unit:set_stat_attribute function. Valid attribute keys are shown in the following list:        

Attribute Key	Description
all_ranks_fire	All ranks can fire if using a weapon that only allows one rank.
berserk	This unit will occasionally go berserk.
cant_run	This unit cannot run - generally for limbered artillery.
campaign_stealth	This unit is able to move around the campaign map without being seen.
charge_reflector	Charge reflection vs all.
charge_reflector_vs_large	Charge reflection vs large units only.
causes_fear	This unit frightens all enemy units, reducing their morale when nearby. It is also immune to fear.
causes_terror	The unit can cause terror, making enemies rout for a short time but without morale penalties. It is also immune to terror and fear.
commander_hunter	This unit is changed in various ways to make them better at killing commanders.
disciplined	This unit doesn't suffer morale penalty from general's death.
encourages	This unit provides a morale bonus to nearby allies.
fatigue_res	Fatigue doesn't have as much of an effect.
fatigue_immune	Fatigue doesn't an effect.
fire_while_moving	This infantry unit can fire while moving.
formed_attack	This unit will try to stay in formation when in melee.
guerrilla_deploy	Can deploy outside deployment zone (vanguard deployment).
hide_forest	Can hide in forest.
hide_grass	Can hide in grass.
hide_scrub_and_forest	Can hide in scrubland.
hide_building	Can hide in buildings.
ignore_ground_move_mod	Doesn't get slowed down by terrain.
strider	Strider attribute.
immune_to_psychology	The unit is immune to psychological attacks (fear and terror).
impetuous	This unit is impetuous and can be hard to withdraw from battle.
mighty_knockback	This unit causes extra damage when they knock back the enemy.
mounted_fire	The unit can fire while on a mount.
mounted_fire_move	The unit can fire while on a moving mount.
mounted_fire_parthian	The unit can fire while on a moving mount in a Parthian fashion.
rampage	This unit may rampage if put under pressure.
resist_cold	This unit doesn't take extra casualties from cold climates in campaign.
resist_heat	This unit doesn't take extra casualties from hot climates in campaign.
run_amok	This unit may run amok if put under pressure.
scare_horse	This unit scares horses.
scare_immune	This unit is immune to fear effects.
snipe	The unit remains hidden while firing.
stalk	This unit can remain hidden while moving.
unbreakable	This unit's morale cannot be broken.
undead	The unit is undead (does not rout, immune to terror, receives crumble damage when morale is low).
unspottable	If this unit is able to hide in its current location, it will not be spotted by enemies until they are very close.
expendable	A normal (non-expendable) unit's morale does not suffer from witnessing an expendable unit routing.
construct	The unit is a statue.
wallbreaker	The unit can attack walls physically.
ignore_trees	The unit ignores trees.
moulder_monster	The unit is a moulder monster that can be targeted by Throt's abilities.
ogre_charge	The unit has ogre charge.

Not all attributes will be supported by each game.