effect · `meta_effect`

Definition

Supported scope:any
Supported target:THIS, ROOT, PREV, FROM, OWNER, CONTROLLER, OCCUPIED, CAPITAL

Description

meta effects can be used for building effects from strings and running them. following example will give Germany 42 pp:
meta_effect = {
    text = {
        [COUNTRY] = {
            add_political_power = [POW]
        }
    }
    COUNTRY = "GER"
    POW = 42
    debug = no #set to yes if you want to see what game actually executes
}

实战 · 配合 · 坑

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

实战用法

meta_effect 适合需要动态拼接执行目标或数值的场景，例如根据变量决定向哪个国家执行某操作，或将同一套逻辑复用于不同参数而避免大量重复代码。常见于通用事件框架、动态联盟系统、或需要把脚本变量里存储的国家标签直接当作 scope 执行的场合。

# 将某个存在变量 target_country 中的国家标签添加政治点数
meta_effect = {
    text = {
        [TARGET] = {
            add_political_power = [AMOUNT]
        }
    }
    TARGET = "var:target_country"
    AMOUNT = "var:bonus_pp"
    debug = no
}

配合关系

[set_variable](/wiki/effect/set_variable) / [set_temp_variable](/wiki/effect/set_temp_variable)：在调用 meta_effect 前先把目标标签或数值写入变量，再通过 var: 引用传入，是最常见的前置步骤。
[hidden_effect](/wiki/effect/hidden_effect)：将 meta_effect 包裹在 hidden_effect 内，避免将调试过程或中间步骤暴露给玩家 tooltip，保持 UI 整洁。
[if](/wiki/effect/if)：在 meta_effect 外层加条件判断，确保拼接的变量已经被赋值且合法，防止向空标签执行操作导致报错。
[has_variable](/wiki/trigger/has_variable)：作为 if 的条件，验证传入 meta_effect 的变量确实存在后再执行，避免因变量未定义引发的静默失败。

常见坑

var: 引用的变量必须存储的是字符串形式的国家/State 标签，而非数字 ID；如果变量里存的是数值型 ID（如 42），直接作为 scope 传入会无法正确解析，需要提前用 set_variable 将正确的字符串标签赋值进去。
text 块中的占位符必须与外层键名完全一致（区分大小写），例如 [COUNTRY] 对应外层必须写 COUNTRY = "..."，拼写或大小写不匹配时游戏不会报显式错误，而是静默跳过整段 effect，非常难以排查，建议开发期间始终保持 debug = yes。

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

meta_effect is well-suited for scenarios requiring dynamic concatenation of execution targets or values, such as deciding which country to execute an operation on based on a variable, or reusing the same logic across different parameters while avoiding large amounts of duplicate code. It is commonly used in generic event frameworks, dynamic alliance systems, or situations where you need to directly use country tags stored in script variables as scopes for execution.

# Add political power to a country tag stored in the target_country variable
meta_effect = {
    text = {
        [TARGET] = {
            add_political_power = [AMOUNT]
        }
    }
    TARGET = "var:target_country"
    AMOUNT = "var:bonus_pp"
    debug = no
}

Synergy

[set_variable](/wiki/effect/set_variable) / [set_temp_variable](/wiki/effect/set_temp_variable): Before calling meta_effect, first write the target tag or value into a variable, then reference it via var: syntax to pass it in. This is the most common prerequisite step.
[hidden_effect](/wiki/effect/hidden_effect): Wrap meta_effect inside hidden_effect to avoid exposing debugging processes or intermediate steps in player tooltips, keeping the UI clean.
[if](/wiki/effect/if): Add conditional checks outside the meta_effect to ensure the concatenated variables have been properly assigned and are valid, preventing errors from executing operations on empty tags.
[has_variable](/wiki/trigger/has_variable): Use as a condition for if to verify that variables passed to meta_effect actually exist before executing, avoiding silent failures caused by undefined variables.

Common Pitfalls

Variables referenced via var: must store country/State tags as strings, not numeric IDs: If a variable contains a numeric ID (like 42), passing it directly as a scope will fail to parse correctly. You need to pre-assign the correct string tag using set_variable.
Placeholders in the text block must exactly match the outer key names (case-sensitive): For example, [COUNTRY] requires COUNTRY = "..." in the outer layer. When spelling or casing mismatches occur, the game will not report an explicit error but will silently skip the entire effect block, making it extremely difficult to debug. It is strongly recommended to always keep debug = yes during development.

effect · meta_effect