trigger · `distance_to`

Definition

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

Description

check distance between two states

实战 · 配合 · 坑

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

实战用法

distance_to 常用于判断两个地块是否在"战略辐射范围"内，例如限制某个决议只对邻近首都或核心地区才可用，或在抵抗运动脚本中让远离占领中心的地块获得额外加成。典型场景是：当某地块距离特定目标超过一定距离时，禁止建造或触发事件。

# 在某决议的 available 块中，要求当前地块距离 ROOT 国家的首都不超过指定距离
available = {
    distance_to = {
        target = CAPITAL
        max_distance < 500
    }
}

配合关系

[is_controlled_by](/wiki/trigger/is_controlled_by)：常与 distance_to 搭配，先确认地块被特定国家控制，再判断距离，避免对遥远飞地误触发逻辑。
[any_neighbor_state](/wiki/trigger/any_neighbor_state)：当需要对"距离目标较近的所有邻接地块"批量检测时，在 any_neighbor_state 的 limit 里嵌套 distance_to 可以进一步筛选范围。
[has_state_flag](/wiki/trigger/has_state_flag)：用于给已通过距离检测的地块打上标记，配合 distance_to 形成"标记-再判断"的二段式条件链，防止重复触发。
[resistance](/wiki/trigger/resistance)：在抵抗运动机制中，可用 distance_to 判断地块是否远离控制中心，再结合 resistance 数值决定是否施加额外惩罚或奖励。

常见坑

target 填写了不在白名单内的 scope：新手常把具体国家 TAG（如 GER）直接写进 target，但该 trigger 只接受 THIS、ROOT、PREV、FROM、OWNER、CONTROLLER、OCCUPIED、CAPITAL 这几个固定 scope 关键字，填错会导致条件静默失效或报错。
在非 STATE scope 下使用：distance_to 仅在 STATE scope 下有效，若写在 COUNTRY 或 CHARACTER 的条件块中不会报语法错误但永远不会返回真，排查时极易忽略。

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

distance_to is commonly used to determine whether two states are within "strategic influence range," such as restricting certain decisions to only apply near a capital or core territories, or in resistance mechanics to grant bonuses to states far from occupation centers. Typical use cases include: preventing construction or triggering events when a state exceeds a certain distance from a specific target.

# In the available block of a decision, require the current state to be within a specified distance from the ROOT country's capital
available = {
    distance_to = {
        target = CAPITAL
        max_distance < 500
    }
}

Synergy

[is_controlled_by](/wiki/trigger/is_controlled_by): Often paired with distance_to to first confirm that a state is controlled by a specific country before checking distance, preventing logic from triggering on distant enclaves.
[any_neighbor_state](/wiki/trigger/any_neighbor_state): When batch-checking "all adjacent states near a target," nesting distance_to within the limit of any_neighbor_state can further refine the scope.
[has_state_flag](/wiki/trigger/has_state_flag): Used to mark states that have passed distance checks. Combined with distance_to, it creates a two-stage conditional chain of "mark and re-evaluate," preventing duplicate triggers.
[resistance](/wiki/trigger/resistance): In resistance mechanics, distance_to can determine whether a state is far from control centers, then combined with resistance values to decide whether to apply additional penalties or bonuses.

Common Pitfalls

Using a scope not on the whitelist for target: Beginners often directly write specific country TAGs (such as GER) into target, but this trigger only accepts fixed scope keywords like THIS, ROOT, PREV, FROM, OWNER, CONTROLLER, OCCUPIED, and CAPITAL. Incorrect entries cause conditions to silently fail or throw errors.
Using outside STATE scope: distance_to is only valid within STATE scope. Writing it in COUNTRY or CHARACTER condition blocks produces no syntax errors but will never return true, making it easy to overlook during debugging.

trigger · distance_to