Module `FACTION_SCRIPT_INTERFACE`

Extensions to the game's faction object.

Functions

CreateAgent (agent_key[, settlement_or_x[, y]])	Creates and spawns a new agent character on the campaign map for this faction in the current tick.
GetMemoryAddress ()	Memory address of the faction object in hexadecimal format.
GetPoliticalParty (party_key)	Retrieves the political party in this faction matching the given record key.
GetPoliticalPartyList ()	List interface (POLITICAL_PARTY_LIST_SCRIPT_INTERFACE) for the faction's campaign political parties.
GetPrimaryParty ()	Primary (leading / ruling) political party of the faction.
GetTechnologyStatus (technology_key)	Gets the current research status of a technology for this faction.
GetTreasury ()	Amount of gold in the faction's treasury.
HasPoliticalParties ()	Checks whether the faction participates in the campaign politics system and has political parties.
InstantlyResearchTechnology (technology_key[, report_to_ui=false])	Instantly completes research of the given technology for the faction, using the game's own internal path for finishing a technology.
SetCapital (region)	Makes the specified region the faction's primary capital / home region.
SetFactionLeader (new_character[, old_character[, heir_coming_of_age=false]])	Sets a new leader for the faction.
SetTechnologyStatus (technology_key, status)	Sets the research status of a technology for this faction and recalculates effects and availabilities.
SetTreasury (value)	Sets the amount of gold in the faction's treasury.

Functions

CreateAgent (agent_key[, settlement_or_x[, y]])

Creates and spawns a new agent character on the campaign map for this faction in the current tick.

Supports two calling styles: - Settlement: faction:CreateAgent(agent_key, settlement) — spawns the agent on the campaign map adjacent to the specified settlement. - Map coordinates: faction:CreateAgent(agent_key, x, y) — spawns the agent at or adjacent to the specified map coordinates.

Parameters:

agent_key string database key of the agent (e.g. "champion", "spy", "dignitary", "priest")
settlement_or_x userdata or number SETTLEMENT_SCRIPT_INTERFACE object or map X coordinate (defaults to faction capital) (optional)
y number map Y coordinate (required when settlement_or_x is an X coordinate) (optional)

Returns:

boolean

Usage:

-- Example 1: Spawn a champion next to a settlement
local capital = faction:home_region():settlement()
faction:CreateAgent("champion", capital)

-- Example 2: Spawn a dignitary at specific map coordinates (x, y)
faction:CreateAgent("dignitary", 516, 381)

GetMemoryAddress ()

Memory address of the faction object in hexadecimal format.

Returns:

string

Usage:

local addr = faction:GetMemoryAddress()

GetPoliticalParty (party_key)

Retrieves the political party in this faction matching the given record key.

Parameters:

party_key string the party record key from political_parties_tables (e.g. "att_politics_hunni_ruler", "att_politics_hunni_council")

Returns:

CAMPAIGN_POLITICAL_PARTY_SCRIPT_INTERFACE or nil

Usage:

local party = faction:GetPoliticalParty("att_politics_hunni_ruler")
if party then
    twdll.core.Log("Found party with senators:", party:GetSenators())
end

GetPoliticalPartyList ()

List interface (POLITICAL_PARTY_LIST_SCRIPT_INTERFACE) for the faction's campaign political parties. Use num_items() and zero-based item_at(index) to iterate the parties.

Returns:

POLITICAL_PARTY_LIST_SCRIPT_INTERFACE

Usage:

local party_list = faction:GetPoliticalPartyList()
for i = 0, party_list:num_items() - 1 do
    local party = party_list:item_at(i)
    twdll.core.Log(string.format("Party [%s]: Senators=%d, Power=%.1f%%, Primary=%s",
        party:GetKey(), party:GetSenators(), party:GetPower() * 100, tostring(party:IsPrimary())))
end

GetPrimaryParty ()

Primary (leading / ruling) political party of the faction.

Returns:

CAMPAIGN_POLITICAL_PARTY_SCRIPT_INTERFACE or nil

Usage:

local ruler_party = faction:GetPrimaryParty()
if ruler_party then
    twdll.core.Log("Ruling party key:", ruler_party:GetKey(), "Senators:", ruler_party:GetSenators())
end

GetTechnologyStatus (technology_key)

Gets the current research status of a technology for this faction.

Status enum values: - 0 = RESEARCHED (fully unlocked and active) - 1 = RESEARCHED_BUT_DISABLED (researched, but effect bundle disabled) - 2 = BEING_RESEARCHED (currently selected in faction research queue) - 3 = AVAILABLE (all prerequisites met, eligible to be researched) - 4 = UNAVAILABLE (prerequisites missing / locked in technology tree) - 5 = NOT_PRESENT (technology node not present in faction's tree) - 6 = LOCKED_FACTION_LEVEL (locked by faction imperium / tier level)

Parameters:

technology_key string the technology record key from technologies_tables

Returns:

integer or nil

BUT

RESEARCHED, 3=AVAILABLE, 4=UNAVAILABLE, 5=NOT

FACTION

Usage:

local status = faction:GetTechnologyStatus("att_hunnic_military_tactical_formations")

GetTreasury ()

Amount of gold in the faction's treasury.

Returns:

integer

Usage:

local gold = faction:GetTreasury()

HasPoliticalParties ()

Checks whether the faction participates in the campaign politics system and has political parties.

Returns:

boolean

Usage:

if faction:HasPoliticalParties() then
    local parties = faction:GetPoliticalPartyList()
    twdll.core.Log("Faction has politics with party count:", parties:num_items())
end

InstantlyResearchTechnology (technology_key[, report_to_ui=false])

Instantly completes research of the given technology for the faction, using the game's own internal path for finishing a technology.

This triggers all native engine completion mechanics: - Fires research completion campaign events. - Grants technology-related campaign achievements. - Applies unit upgrades and building unlocks immediately. - Completes parent prerequisites automatically.

Note: this differs from the game's built-in cm:unlock_technology, which only makes a technology selectable in the UI and never actually finishes research.

Parameters:

technology_key string the technology record key from technologies_tables (e.g. "att_tech_military_barracks", "att_hunnic_military_combat_at_distance")
report_to_ui boolean whether to generate UI event feed messages (default: false) (default false)

Returns:

boolean

Usage:

local ok = faction:InstantlyResearchTechnology("att_hunnic_military_combat_at_distance")
if ok then
    twdll.core.Log("Technology researched instantly!")
end

SetCapital (region)

Makes the specified region the faction's primary capital / home region.

Works even if the faction currently has no home region (e.g. horde settling): properly assigns the faction's capital, original home region, and home theatre.

Parameters:

region REGION_SCRIPT_INTERFACE the region to become the new capital

Usage:

local region = game:model():world():region_manager():region_by_key("att_reg_scandza_hafn")
faction:SetCapital(region)

SetFactionLeader (new_character[, old_character[, heir_coming_of_age=false]])

Sets a new leader for the faction.

Supports three operational modes: 1. Silent swap (faction:SetFactionLeader(new_char)): changes the faction leader immediately without firing succession events or modifying political stability. 2. Standard succession (faction:SetFactionLeader(new_char, old_char)): triggers the standard faction_succession (or faction_succession_regency) campaign event. 3. Heir coming of age (faction:SetFactionLeader(new_char, old_char, true)): triggers the faction_succession_heir_comes_of_age campaign event.

Automatically resets the new leader's heir status and aligns political party leadership.

Parameters:

new_character CHARACTER_SCRIPT_INTERFACE the character to become the new leader
old_character CHARACTER_SCRIPT_INTERFACE the outgoing leader (triggers succession event if provided) (optional)
heir_coming_of_age boolean fire the heir-comes-of-age event variant (default: false) (default false)

Usage:

-- Mode 1: Silent swap without event popup:
faction:SetFactionLeader(new_general)

-- Mode 2: Standard succession with in-game succession event:
local old_leader = faction:faction_leader()
faction:SetFactionLeader(new_general, old_leader)

-- Mode 3: Heir coming of age succession:
faction:SetFactionLeader(heir_general, old_leader, true)

SetTechnologyStatus (technology_key, status)

Sets the research status of a technology for this faction and recalculates effects and availabilities.

Status enum values: - 0 = RESEARCHED (instantly unlocks and applies all faction effects) - 1 = RESEARCHED_BUT_DISABLED (marks researched, but disables faction bonuses) - 2 = BEING_RESEARCHED (sets as active research target) - 3 = AVAILABLE (makes available to be clicked and researched) - 4 = UNAVAILABLE (locks / disables from research) - 5 = NOT_PRESENT (marks unassigned) - 6 = LOCKED_FACTION_LEVEL (locks under faction level requirements)

Engine Save / Load Behavior & Persistence Notice:

The vanilla Total War save format (.save) only serializes the list of researched technologies (RESEARCHED = 0 and RESEARCHED_BUT_DISABLED = 1) in its RESEARCHED_TECHS block. Intermediate non-researched states (AVAILABLE = 3, UNAVAILABLE = 4, BEING_RESEARCHED = 2, LOCKED_FACTION_LEVEL = 6) are never serialized to disk; they are dynamically reconstructed upon campaign load by the engine's database dependency solver (technologies_nodes_tables).

Furthermore, during save loading (post_load_fixup), the engine's native solver recursively ensures that all parent prerequisites of any researched child technology are automatically marked as researched (0).

Recommendation for Modders:

If your script sets non-standard tree states (e.g. locking specific parent nodes while children are researched, or manually setting nodes to UNAVAILABLE = 4), re-apply your SetTechnologyStatus calls in a FirstTickAfterWorldCreated or LoadingGame campaign event callback upon loading a save game.

Parameters:

technology_key string the technology record key from technologies_tables
status integer status integer (0=RESEARCHED, 1=RESEARCHEDBUTDISABLED, 2=BEINGRESEARCHED, 3=AVAILABLE, 4=UNAVAILABLE, 5=NOTPRESENT, 6=LOCKEDFACTIONLEVEL)

Returns:

boolean

Usage:

-- Revert a researched technology back to available (unresearched):
faction:SetTechnologyStatus("att_hunnic_military_tactical_formations", 3)

-- Re-apply custom lock on campaign load:
events.FirstTickAfterWorldCreated[#events.FirstTickAfterWorldCreated + 1] = function()
    faction:SetTechnologyStatus("att_hunnic_military_supply_acquisition", 4)
end

SetTreasury (value)

Sets the amount of gold in the faction's treasury. Persisted natively in savegames and immediately available for building and recruitment.

Parameters:

value integer new gold amount

Returns:

boolean

Usage:

-- Give faction 50,000 gold:
faction:SetTreasury(50000)

twdll

Contents

Modules

Topics

Module FACTION_SCRIPT_INTERFACE

Functions

Functions

Parameters:

Returns:

Usage:

Returns:

Usage:

Parameters:

Returns:

Usage:

Returns:

Usage:

Returns:

Usage:

Parameters:

Returns:

Usage:

Returns:

Usage:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Engine Save / Load Behavior & Persistence Notice:

Recommendation for Modders:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Module `FACTION_SCRIPT_INTERFACE`