effect · `swap_ruler_traits`

Definition

Supported scope:COUNTRY
Supported target:none

Description

swap 2 traits on current ruler. 
 Syntax: swap_ruler_traits = { remove = <trait> add = <trait> }

实战 · 配合 · 坑

实战内容由 AI 生成,并已对照 vanilla 命令词表校验 —— 请当作起点而非权威依据。上方的定义节才是游戏自带文档原文。

实战用法

swap_ruler_traits 常用于国策、决策或事件中替换国家领导人特质，模拟领袖经历某一历史事件后性格或能力的转变（例如战争失利后从"强硬外交官"变为"孤立主义者"）。适合制作历史向 mod 时，在关键剧情节点动态调整领袖定位，而无需销毁并重建整个领导人角色。

# 某决策执行后，用更激进的特质替换原有温和特质
country_event = {
    id = mymod.1
    option = {
        name = mymod.1.a
        swap_ruler_traits = {
            remove = trait_moderate_diplomat
            add = trait_ultranationalist_demagogue
        }
    }
}

配合关系

[has_country_leader_with_trait](/wiki/trigger/has_country_leader_with_trait) — 在执行替换前先检查领导人是否真的拥有目标特质，避免 remove 字段指向不存在特质时静默失效。
[add_country_leader_trait](/wiki/effect/add_country_leader_trait) — 当需要在替换的同时额外叠加第三个新特质时配合使用，二者分工明确：一个负责"换"，一个负责"加"。
[has_country_leader](/wiki/trigger/has_country_leader) — 在 scope 切换或多国联动脚本中，先确认当前 scope 内存在有效的执行中领导人，防止对无领导人国家执行指令引发错误。
[country_event](/wiki/effect/country_event) — 常把 swap_ruler_traits 包裹在事件 option 中触发，通过事件弹窗给玩家展示叙事背景，增强沉浸感。

常见坑

remove 的特质必须已挂载在当前领袖身上，若领袖实际并未持有该特质，指令不会报错但 add 同样不会生效，导致新特质无声无息地丢失——务必提前用 [has_country_leader_with_trait](/wiki/trigger/has_country_leader_with_trait) 做条件保护。
Scope 必须是 COUNTRY 而非 character，新手容易在 every_character 或 create_country_leader 的子块内直接调用此指令，实际上需要退回到国家 scope 再执行，否则会触发 scope 类型不匹配错误。

Hands-On Notes

Hands-on notes are AI-generated and checked against the vanilla command vocabulary — treat them as a starting point, not authoritative reference. The definition above is the game's own documentation.

Hands-On Usage

swap_ruler_traits is commonly used in national focuses, decisions, or events to replace a country's leader traits, simulating shifts in a leader's personality or capabilities following a historical event (for example, shifting from "hardened diplomat" to "isolationist" after military defeat). This is ideal for history-focused mods, allowing dynamic repositioning of leaders at key narrative moments without destroying and rebuilding the entire leader character.

# After a decision is executed, replace moderate traits with more radical ones
country_event = {
    id = mymod.1
    option = {
        name = mymod.1.a
        swap_ruler_traits = {
            remove = trait_moderate_diplomat
            add = trait_ultranationalist_demagogue
        }
    }
}

Synergy

[has_country_leader_with_trait](/wiki/trigger/has_country_leader_with_trait) — Check that the leader actually possesses the target trait before executing the swap, preventing silent failure if the remove field points to a non-existent trait.
[add_country_leader_trait](/wiki/effect/add_country_leader_trait) — Use in conjunction when you need to layer a third new trait alongside the swap; the two have distinct responsibilities: one handles "replacement," the other handles "addition."
[has_country_leader](/wiki/trigger/has_country_leader) — In scope transitions or multi-country scripts, confirm an active leader exists within the current scope first, preventing errors when executing commands on leaderless nations.
[country_event](/wiki/effect/country_event) — Typically wrap swap_ruler_traits within an event option to trigger it; use the event popup to present narrative context to the player, enhancing immersion.

Common Pitfalls

The trait in remove must already be equipped on the current leader. If the leader does not actually possess that trait, the command will not error but the add will likewise fail silently, causing the new trait to disappear without warning—always protect with a conditional check using [has_country_leader_with_trait](/wiki/trigger/has_country_leader_with_trait) beforehand.
Scope must be COUNTRY, not character. Beginners often call this command directly inside every_character or create_country_leader blocks; you actually need to exit back to country scope first, otherwise it triggers a scope type mismatch error.

effect · swap_ruler_traits