Module CHARACTER_SCRIPT_INTERFACE

Extensions to the game's character object.

Functions

AddTrait (trait_key[, points=1[, show_message=false]]) Adds the specified character trait to this character using the engine's native command queue.
GetActionPoints () Current campaign action points remaining for the character.
GetArtSet () Returns the ARTSET_SCRIPT_INTERFACE for this character, or nil if none.
GetClanName () Active onscreen clan name of the character.
GetClanNameKey () Database localisation key for the character's clan name (e.g.
GetFamilyName () Active onscreen family name (surname) of the character.
GetFamilyNameKey () Database localisation key for the character's family name (e.g.
GetForename () Active onscreen forename of the character.
GetForenameKey () Database localisation key for the character's forename (e.g.
GetFullName () Returns the full formatted onscreen name of the character (combining non-empty forename, clan name, family name, and other name).
GetInfluence () Political influence / gravitas of the character.
GetLoyalty () Calculated total loyalty level of the character (0 to 10), taking into account ruler authority, gravitas difference, marriage, ministerial offices, traits, and direct modifiers.
GetLoyaltyFactorList () Returns a key-value dictionary table breakdown of all active loyalty factors contributing to this character's loyalty.
GetLoyaltyModifier () Direct loyalty modifier value applied to this character.
GetMemoryAddress () Memory address of the character object in hexadecimal format.
GetOtherName () Active onscreen other name (title / nickname) of the character.
GetOtherNameKey () Database localisation key for the character's other name/title (e.g.
GetPoliticalParty () Returns the character's political party (CAMPAIGN_POLITICAL_PARTY_SCRIPT_INTERFACE), or nil if none.
GetResurrectionTurns () Turns remaining until resurrection for a wounded immortal character.
GetTraitList () Returns a table array of all trait record keys currently present on this character.
IsImmortal () Checks whether the character is flagged as immortal (will be wounded instead of dying).
RemoveTrait (trait_key) Removes the specified trait from this character and recalculates active character bonus effects and skill attributes.
SetActionPoints (value) Sets the campaign action points for the character.
SetArtSet (art_set_key) Sets the art set for this character, immediately updating all 3D models (campaign map avatar, battle commander, politician panel) and 2D UI portholes/portraits.
SetClanName (name) Sets the clan name of the character as direct custom text (UTF-8).
SetClanNameKey (key) Sets the database localisation key for the character's clan name (e.g.
SetDefaultBodyGuard (unit_key) Overrides the default bodyguard unit record for a general so that whenever the general is recruited into an army (including re-recruitment after being wounded or disbanded, or through 'Replace this general' in the UI), they receive this unit type as their default bodyguard.
SetFamilyName (name) Sets the family name (surname) of the character as direct custom text (UTF-8).
SetFamilyNameKey (key) Sets the database localisation key for the character's family name (e.g.
SetForename (name) Sets the forename of the character as direct custom text (UTF-8).
SetForenameKey (key) Sets the database localisation key for the character's forename (e.g.
SetImmortal (immortal) Sets the immortality flag of the character.
SetInfluence (value) Sets the political influence / gravitas of the character.
SetLoyaltyModifier (value) Sets a direct loyalty modifier on the character that directly alters their overall loyalty score.
SetOtherName (name) Sets the other name (title / nickname) of the character as direct custom text (UTF-8).
SetOtherNameKey (key) Sets the database localisation key for the character's other name/title (e.g.
SetPoliticalParty (party) Sets the character's political party allegiance.
SetResurrectionTurns (turns) Sets the turns remaining until resurrection for a wounded immortal character.
TransferToFaction (target_faction[, options]) Instantly transfers the character and their commanded military force to another faction in the current tick.


Functions

AddTrait (trait_key[, points=1[, show_message=false]])
Adds the specified character trait to this character using the engine's native command queue. Automatically calculates and applies all associated trait effect bundles and attribute bonuses.

Parameters:

  • trait_key string the trait record key from character_traits_tables (e.g. "att_trait_all_personality_brave")
  • points integer trait level / points to grant (default: 1) (default 1)
  • show_message boolean whether to trigger the on-screen event notification message (default: false) (default false)

Returns:

    boolean true on success, false otherwise

Usage:

    -- Add 1 point of brave trait silently:
char:AddTrait("att_trait_all_personality_brave", 1, false)

-- Add trait with on-screen notification:
char:AddTrait("att_trait_all_personality_brave", 1, true)
GetActionPoints ()
Current campaign action points remaining for the character.

Returns:

    integer action points

Usage:

    local ap = char:GetActionPoints()
if ap < 20 then
    -- Replenish movement points if army is exhausted:
    char:SetActionPoints(100)
end
GetArtSet ()
Returns the ARTSET_SCRIPT_INTERFACE for this character, or nil if none. Allows inspecting portrait paths, cultural variations, gender, aging, and faction leader flags.

Returns:

    ARTSET_SCRIPT_INTERFACE or nil character art set interface, or nil if none

Usage:

    local art_set = char:GetArtSet()
if art_set then
    local path = art_set:GetPortraitPath()
    -- Sample path: "UI/Portraits/Portholes/att_cult_nomadic/att_frontend_faction_leader_huns_0.png"
    if not art_set:IsMale() then
        -- Process female character art set
    end
end
GetClanName ()
Active onscreen clan name of the character. Returns custom text if set via SetClanName, or the translated string from the database if set via SetClanNameKey, or the database key as fallback.

Returns:

    string clan name string

Usage:

    local clan = char:GetClanName()
GetClanNameKey ()
Database localisation key for the character's clan name (e.g. "names_name_12345"). Returns the raw key string if assigned via database or SetClanNameKey, or an empty string if direct custom text was assigned via SetClanName.

Returns:

    string database localisation key string, or empty string if custom text is used

Usage:

    local key = char:GetClanNameKey()
GetFamilyName ()
Active onscreen family name (surname) of the character. Returns custom text if set via SetFamilyName, or the translated string from the database if set via SetFamilyNameKey, or the database key as fallback.

Returns:

    string family name string

Usage:

    local fam = char:GetFamilyName()
GetFamilyNameKey ()
Database localisation key for the character's family name (e.g. "names_name_12345"). Returns the raw key string if assigned via database or SetFamilyNameKey, or an empty string if direct custom text was assigned via SetFamilyName.

Returns:

    string database localisation key string, or empty string if custom text is used

Usage:

    local key = char:GetFamilyNameKey()
GetForename ()
Active onscreen forename of the character. Returns custom text if set via SetForename, or the translated string from the database if set via SetForenameKey, or the database key as fallback.

Returns:

    string forename string

Usage:

    local fn = char:GetForename()
GetForenameKey ()
Database localisation key for the character's forename (e.g. "names_name_12345"). Returns the raw key string if assigned via database or SetForenameKey, or an empty string if direct custom text was assigned via SetForename.

Returns:

    string database localisation key string, or empty string if custom text is used

Usage:

    local key = char:GetForenameKey()
GetFullName ()
Returns the full formatted onscreen name of the character (combining non-empty forename, clan name, family name, and other name). Concatenates active name slots in native UI display order: Forename [ClanName] [FamilyName] [OtherName].

Returns:

    string full composite name (e.g. "Witch-king NazgulClan Angmar the Nazgul")

Usage:

    local name = char:GetFullName()
GetInfluence ()
Political influence / gravitas of the character. Used by the politics and senate simulation to evaluate political power and family standing.

Returns:

    integer influence value

Usage:

    local gravitas = char:GetInfluence()
if gravitas < 15 then
    -- Character lacks gravitas to secure ministerial offices
end
GetLoyalty ()
Calculated total loyalty level of the character (0 to 10), taking into account ruler authority, gravitas difference, marriage, ministerial offices, traits, and direct modifiers.

Returns:

    integer total loyalty level clamped between 0 and 10

Usage:

    local loyalty = char:GetLoyalty()
if loyalty <= 2 then
    -- Character is dangerously disloyal and at imminent risk of civil war or rebellion
end
GetLoyaltyFactorList ()
Returns a key-value dictionary table breakdown of all active loyalty factors contributing to this character's loyalty. Each key is the database identifier from loyalty_factors_tables mapped to its integer point value (positive for loyalty bonuses, negative for grievances and penalties).

Returns:

    table map of [db_factor_key] = integer_point_value for all active non-zero factors

Usage:

    -- Sample returned table:
-- {
--     ["att_loyalty_factor_leader_authority"] = 2,
--     ["att_loyalty_factor_gravitas_difference"] = -3,
--     ["att_loyalty_factor_office_held"] = 1,
--     ["att_loyalty_factor_direct_modifier"] = -10
-- }

local factors = char:GetLoyaltyFactorList()

-- Check a specific grievance penalty:
local gravitas_penalty = factors["att_loyalty_factor_gravitas_difference"] or 0
if gravitas_penalty < 0 then
    -- Character resents the faction leader having lower gravitas
end

-- Sum total negative grievances:
local total_grievances = 0
for factor_key, points in pairs(factors) do
    if points < 0 then
        total_grievances = total_grievances + points
    end
end
GetLoyaltyModifier ()
Direct loyalty modifier value applied to this character.

Returns:

    integer loyalty modifier value (between -128 and 127)

Usage:

    local mod = char:GetLoyaltyModifier()
GetMemoryAddress ()
Memory address of the character object in hexadecimal format.

Returns:

    string memory address (e.g. "0x12345678")

Usage:

    local addr = char:GetMemoryAddress()
GetOtherName ()
Active onscreen other name (title / nickname) of the character. Returns custom text if set via SetOtherName, or the translated string from the database if set via SetOtherNameKey, or the database key as fallback.

Returns:

    string other name string

Usage:

    local on = char:GetOtherName()
GetOtherNameKey ()
Database localisation key for the character's other name/title (e.g. "names_titles_the_great"). Returns the raw key string if assigned via database or SetOtherNameKey, or an empty string if direct custom text was assigned via SetOtherName.

Returns:

    string database localisation key string, or empty string if custom text is used

Usage:

    local key = char:GetOtherNameKey()
GetPoliticalParty ()
Returns the character's political party (CAMPAIGN_POLITICAL_PARTY_SCRIPT_INTERFACE), or nil if none.

Returns:

    CAMPAIGN_POLITICAL_PARTY_SCRIPT_INTERFACE or nil party object, or nil if none

Usage:

    local party = char:GetPoliticalParty()
if party and not party:IsPrimary() then
    -- Character belongs to an opposition house; reassign to the ruling party:
    local ruler_party = faction:GetPrimaryParty()
    char:SetPoliticalParty(ruler_party)
end
GetResurrectionTurns ()
Turns remaining until resurrection for a wounded immortal character.

Returns:

    integer turns to resurrection

Usage:

    local turns = char:GetResurrectionTurns()
GetTraitList ()
Returns a table array of all trait record keys currently present on this character.

Returns:

    table array of trait key strings (e.g. {"att_trait_all_personality_brave", ...})

Usage:

    -- Sample returned table:
-- {
--     [1] = "att_trait_all_personality_brave",
--     [2] = "att_trait_general_cavalry_commander",
--     [3] = "att_trait_all_political_ambitious"
-- }

local traits = char:GetTraitList()

-- Check if character has a specific trait:
local is_brave = false
for _, trait_key in ipairs(traits) do
    if trait_key == "att_trait_all_personality_brave" then
        is_brave = true
        break
    end
end
IsImmortal ()
Checks whether the character is flagged as immortal (will be wounded instead of dying).

Returns:

    boolean true if immortal, false otherwise

Usage:

    local immortal = char:IsImmortal()
RemoveTrait (trait_key)
Removes the specified trait from this character and recalculates active character bonus effects and skill attributes.

Parameters:

  • trait_key string the trait record key to remove

Returns:

    boolean true if the trait was found and removed, false otherwise

Usage:

    -- Remove a specific personality trait:
local ok = char:RemoveTrait("att_trait_all_personality_brave")
SetActionPoints (value)
Sets the campaign action points for the character.

Parameters:

  • value integer new action points (e.g. 0 to immobilize, 100+ for full movement)

Returns:

    boolean true on success, false otherwise

Usage:

    -- Immobilize character for one turn:
char:SetActionPoints(0)

-- Restore full movement range:
char:SetActionPoints(100)
SetArtSet (art_set_key)
Sets the art set for this character, immediately updating all 3D models (campaign map avatar, battle commander, politician panel) and 2D UI portholes/portraits.

Parameters:

  • art_set_key string art set ID key from campaign_character_art_sets_tables (e.g. "att_general_nomadic_16")

Returns:

    boolean true on success, false on failure

Usage:

    -- Swap general appearance and portrait:
char:SetArtSet("att_general_nomadic_16")
SetClanName (name)
Sets the clan name of the character as direct custom text (UTF-8). Clears any existing database localisation key, ensuring the custom string is displayed directly across all UI panels regardless of game language. Persisted natively across turns and save/load. To use a localized string from names.loc, use SetClanNameKey instead.

Parameters:

  • name string new custom clan name text in UTF-8

Returns:

    boolean true on success, false otherwise

Usage:

    char:SetClanName("NazgulClan")
SetClanNameKey (key)
Sets the database localisation key for the character's clan name (e.g. "names_name_12345"). Clears any active custom in-memory text, allowing the game engine to translate the name dynamically from localized database files (names.loc) based on the player's active language. Persisted natively across turns and save/load. To assign arbitrary text without editing database files, use SetClanName instead.

Parameters:

  • key string database localisation key string

Returns:

    boolean true on success, false otherwise

Usage:

    char:SetClanNameKey("names_name_12345")
SetDefaultBodyGuard (unit_key)
Overrides the default bodyguard unit record for a general so that whenever the general is recruited into an army (including re-recruitment after being wounded or disbanded, or through 'Replace this general' in the UI), they receive this unit type as their default bodyguard.

Persisted natively in savegames and read by the recruitment panel as the pre-selected default choice.

Parameters:

  • unit_key string unit record key from main_units_tables (e.g. "att_rom_cav_general_guards", "att_merc_ger_agathyrsi_warriors")

Returns:

    boolean true if the record was found and applied, false otherwise

Usage:

    -- Assign an elite bodyguard to the general:
local ok = char:SetDefaultBodyGuard("att_merc_ger_agathyrsi_warriors")
SetFamilyName (name)
Sets the family name (surname) of the character as direct custom text (UTF-8). Clears any existing database localisation key, ensuring the custom string is displayed directly across all UI panels regardless of game language. Persisted natively across turns and save/load. To use a localized string from names.loc, use SetFamilyNameKey instead.

Parameters:

  • name string new custom family name text in UTF-8

Returns:

    boolean true on success, false otherwise

Usage:

    char:SetFamilyName("Angmar")
SetFamilyNameKey (key)
Sets the database localisation key for the character's family name (e.g. "names_name_12345"). Clears any active custom in-memory text, allowing the game engine to translate the name dynamically from localized database files (names.loc) based on the player's active language. Persisted natively across turns and save/load. To assign arbitrary text without editing database files, use SetFamilyName instead.

Parameters:

  • key string database localisation key string

Returns:

    boolean true on success, false otherwise

Usage:

    char:SetFamilyNameKey("names_name_12345")
SetForename (name)
Sets the forename of the character as direct custom text (UTF-8). Clears any existing database localisation key, ensuring the custom string is displayed directly across all UI panels regardless of game language. Persisted natively across turns and save/load. To use a localized string from names.loc, use SetForenameKey instead.

Parameters:

  • name string new custom forename text in UTF-8

Returns:

    boolean true on success, false otherwise

Usage:

    char:SetForename("Witch-king")
SetForenameKey (key)
Sets the database localisation key for the character's forename (e.g. "names_name_12345"). Clears any active custom in-memory text, allowing the game engine to translate the name dynamically from localized database files (names.loc) based on the player's active language. Persisted natively across turns and save/load. To assign arbitrary text without editing database files, use SetForename instead.

Parameters:

  • key string database localisation key string

Returns:

    boolean true on success, false otherwise

Usage:

    char:SetForenameKey("names_name_12345")
SetImmortal (immortal)
Sets the immortality flag of the character.

Parameters:

  • immortal boolean true to make immortal, false to make mortal

Returns:

    boolean true on success, false otherwise

Usage:

    char:SetImmortal(true)
SetInfluence (value)
Sets the political influence / gravitas of the character. Persisted in savegames. Directly modifies the character's political weight in the faction senate.

Parameters:

  • value integer new influence value

Returns:

    boolean true on success, false otherwise

Usage:

    -- Elevate character influence to qualify for high political office:
char:SetInfluence(60)
SetLoyaltyModifier (value)
Sets a direct loyalty modifier on the character that directly alters their overall loyalty score.

To permanently zero out loyalty or prime a character for rebellion/defection, pass a strong negative value (e.g. -100).

Parameters:

  • value integer new modifier value (-128 to 127)

Returns:

    boolean true on success, false otherwise

Usage:

    -- Prime character for civil war / defection:
char:SetLoyaltyModifier(-100)

-- Reward character with a loyalty boost (+10):
char:SetLoyaltyModifier(10)
SetOtherName (name)
Sets the other name (title / nickname) of the character as direct custom text (UTF-8). Clears any existing database localisation key, ensuring the custom string is displayed directly across all UI panels regardless of game language. Persisted natively across turns and save/load. To use a localized string from names_titles_tables / names.loc, use SetOtherNameKey instead.

Parameters:

  • name string new other name custom text (e.g. "the Nazgul")

Returns:

    boolean true on success, false otherwise

Usage:

    char:SetOtherName("the Nazgul")
SetOtherNameKey (key)
Sets the database localisation key for the character's other name/title (e.g. "names_titles_the_great"). Clears any active custom in-memory text, allowing the game engine to translate the title dynamically from localized database files (names.loc) based on the player's active language. Persisted natively across turns and save/load. To assign arbitrary text without editing database files, use SetOtherName instead.

Parameters:

  • key string database localisation key string

Returns:

    boolean true on success, false otherwise

Usage:

    char:SetOtherNameKey("names_titles_the_great")
SetPoliticalParty (party)
Sets the character's political party allegiance.

Supports two calling styles: - Party userdata: char:SetPoliticalParty(party_obj) - Party record key string: char:SetPoliticalParty("att_politics_hunni_council")

Directly updates the character's party pointer in memory and updates family tree representation.

Parameters:

  • party CAMPAIGN_POLITICAL_PARTY_SCRIPT_INTERFACE or string party object or party record key string

Returns:

    boolean true if successfully set, false otherwise

Usage:

    -- Option 1: Assign via party userdata:
local ruler_party = faction:GetPrimaryParty()
char:SetPoliticalParty(ruler_party)

-- Option 2: Assign via database record key:
char:SetPoliticalParty("att_politics_hunni_council")
SetResurrectionTurns (turns)
Sets the turns remaining until resurrection for a wounded immortal character.

Parameters:

  • turns integer resurrection countdown turns (0 for healthy/ready)

Returns:

    boolean true on success, false otherwise

Usage:

    char:SetResurrectionTurns(3)
TransferToFaction (target_faction[, options])
Instantly transfers the character and their commanded military force to another faction in the current tick.

Automatic engine side-effects: - Unassigns any active governorship or minister post held by the character. - Ends active trade commerce raids and updates trade routes. - Cancels pending political actions targeting this character. - Reassigns all units, recalculates senior unit commander, and re-sorts force containers. - Emits native events (MILITARY_FORCE_FACTION_CHANGE, REPORT_CHARACTER_RENDER_DETAILS_CHANGE, CHARACTER_FACTION_CHANGE). - Reloads character voiceover culture and lines if the receiving faction is human-controlled.

Parameters:

  • target_faction FACTION_SCRIPT_INTERFACE target faction receiving the character and their force
  • options table optional table { replenish_units = false, rebel_region = nil }: - replenish_units (boolean): if true, restores all units in the force to 100% full soldier capacity. - rebel_region (REGION_SCRIPT_INTERFACE|nil): optional region interface. When provided, binds the army to this region as a provincial rebel force with rebel AI objectives and unrest reduction upon defeat. (optional)

Returns:

    boolean true on success, false otherwise

Usage:

  • -- Basic transfer:
char:TransferToFaction(target_faction)
  •  -- Transfer with options:
char:TransferToFaction(target_faction, {
    replenish_units = true,         -- replenish all units to 100% strength (default: false)
    rebel_region = region           -- bind as provincial rebel army in this region (default: nil)
})
generated by LDoc 1.5.0