Module UNIT_SCRIPT_INTERFACE
Extensions to the game's unit object.
Functions
| ConvertUnit (unit_key) | Replaces the unit with a new unit type in the same military force (matching the engine upgrade path). |
| Disband () | Disbands and removes this unit from its military force. |
| GetActionPoints () | Remaining movement action points for this unit. |
| GetMaxNumMen () | Maximum soldier capacity (full strength count) for this unit. |
| GetMemoryAddress () | Memory address of the unit object in hexadecimal format. |
| GetNumMen () | Current number of surviving soldiers in the unit. |
| SetActionPoints (value) | Sets the movement action points for this unit. |
| SetMaxNumMen (value) | Sets the maximum soldier capacity (full strength count) for this unit. |
| SetNumMen (value) | Sets the number of surviving soldiers in the unit. |
Functions
- ConvertUnit (unit_key)
-
Replaces the unit with a new unit type in the same military force (matching the engine upgrade path).
Key mechanics: - Scales soldier count proportionally to the new unit's max capacity. - Preserves experience chevron rank, battle kills, and combat statistics. - If the unit is a general's bodyguard, synchronises the commander's bodyguard record. - Note: Destroys the old unit object; retrieve the replacement from the force's unit list.
Parameters:
- unit_key
string
the unit record key from
main_units_tables(e.g."att_merc_ger_agathyrsi_warriors","att_inf_melee_spear_att")
Returns:
-
boolean
true if the unit was converted, false otherwise
Usage:
-- Upgrade or convert a unit in an army: local unit = force:unit_list():item_at(0) local ok = unit:ConvertUnit("att_merc_ger_agathyrsi_warriors") if ok then -- Note: 'unit' is now invalid; fetch the updated unit from force:unit_list() local updated_unit = force:unit_list():item_at(0) end
- unit_key
string
the unit record key from
- Disband ()
-
Disbands and removes this unit from its military force.
Updates campaign force state, unit counts, and UI bookkeeping in a single transaction. Save/load safe.
Returns:
-
boolean
true if successfully disbanded, false otherwise
Usage:
local unit = force:unit_list():item_at(force:unit_list():num_items() - 1) local ok = unit:Disband()
- GetActionPoints ()
-
Remaining movement action points for this unit.
Returns:
-
integer
action points
Usage:
local ap = unit:GetActionPoints()
- GetMaxNumMen ()
-
Maximum soldier capacity (full strength count) for this unit.
Returns:
-
integer
maximum number of men
Usage:
local max_men = unit:GetMaxNumMen()
- GetMemoryAddress ()
-
Memory address of the unit object in hexadecimal format.
Returns:
-
string
memory address (e.g. "0x12345678")
Usage:
local addr = unit:GetMemoryAddress()
- GetNumMen ()
-
Current number of surviving soldiers in the unit.
Returns:
-
integer
current number of men
Usage:
local men = unit:GetNumMen() local max_men = unit:GetMaxNumMen() if men < max_men * 0.5 then -- Unit is below 50% strength and heavily depleted end
- SetActionPoints (value)
-
Sets the movement action points for this unit.
Parameters:
- value integer new action points
Returns:
-
boolean
true on success, false otherwise
Usage:
-- Reset unit action points: unit:SetActionPoints(100)
- SetMaxNumMen (value)
-
Sets the maximum soldier capacity (full strength count) for this unit.
Parameters:
- value integer new maximum number of men
Returns:
-
boolean
true on success, false otherwise
Usage:
-- Increase unit max strength cap to 150: unit:SetMaxNumMen(150)
- SetNumMen (value)
-
Sets the number of surviving soldiers in the unit.
Immediately updates the unit's health bar and strength percentage.
Parameters:
- value
integer
new number of men (clamped between 0 and
max_num_men)
Returns:
-
boolean
true on success, false otherwise
Usage:
-- Replenish unit immediately to full strength: unit:SetNumMen(unit:GetMaxNumMen()) -- Or set specific casualty count after an event: unit:SetNumMen(20)
- value
integer
new number of men (clamped between 0 and