effect · `teleport_armies`

Definition

Supported scope:STATE
Supported target:any

Description

teleport armies in state to another state or province. example :
teleport_armies = { 
  #only define one. if neither is defined will teleport to unit to their capital  to_state = 123 #id of the state to teleport
  to_state_array = array_name #an array of states to teleport (will be randomly picked)
  to_province = 123 #id of the province to teleport

  limit = { 
     # trigger will be checked for owner of armies and will only teleport if true. scope if the owner of the army and prev is the scope that calls teleport_armies
  } 
}

实战 · 配合 · 坑

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

实战用法

teleport_armies 常用于剧本事件或决议触发时，将某地区的部队强制转移到指定位置，例如模拟撤退、增援或包围歼灭后的重组。典型场景包括：玩家完成某项决议后，将占领州的驻守部队瞬间调回本土首都，或在随机事件中将敌方孤立部队传送到其首都以模拟"脱困"。

# 在一个 state scope 的 immediate 块中：
123 = {  # 某前线州
    teleport_armies = {
        to_state = 456  # 传送至后方集结州
        limit = {
            # 仅传送由德国控制的部队
            tag = GER
        }
    }
}

配合关系

[is_controlled_by](/wiki/trigger/is_controlled_by)：在调用 teleport_armies 前用于验证该州当前的控制权归属，确保只在预期的占领/控制条件下触发传送逻辑。
[set_state_controller_to](/wiki/effect/set_state_controller_to)：传送部队后往往需要同步变更该州的控制方，两者组合才能完整模拟"撤军并移交控制权"的流程。
[add_manpower](/wiki/effect/add_manpower)：部队传送后若涉及兵员损耗的叙事，可在同一块内向目标州补充人力，强化事件的逻辑自洽性。
[state_event](/wiki/effect/state_event)：传送完成后触发一个后续州级事件，用于通知玩家或推进剧情，形成"传送→事件反馈"的完整链条。

常见坑

同时定义多个目标字段：to_state、to_state_array、to_province 只能选其一，若同时写入多个，游戏只会采用其中一个（优先级不透明），其余被静默忽略，导致传送目的地与预期不符，调试时极难发现。
limit 的 scope 误解：limit 内的触发器 scope 是部队所属国家（即军队的拥有者 country），而非当前的州 scope，新手常误用州级触发器（如 is_controlled_by）在此处进行判断，实际应使用国家级触发器（如 tag），否则条件永远不成立导致无部队被传送。

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

teleport_armies is commonly used in scripted events or decision triggers to forcibly relocate units from one region to a designated location, simulating scenarios such as withdrawals, reinforcements, or reorganization after encirclement and destruction. Typical use cases include: after a player completes a decision, instantly recalling garrison forces from an occupied state back to the national capital, or in random events teleporting isolated enemy units to their capital to simulate "breaking free."

# In the immediate block of a state scope:
123 = {  # A frontline state
    teleport_armies = {
        to_state = 456  # Teleport to rear staging area state
        limit = {
            # Only teleport units controlled by Germany
            tag = GER
        }
    }
}

Synergy

[is_controlled_by](/wiki/trigger/is_controlled_by): Use before calling teleport_armies to verify the current control status of the state, ensuring the teleport logic only triggers under the intended occupation/control conditions.
[set_state_controller_to](/wiki/effect/set_state_controller_to): After teleporting units, it is often necessary to simultaneously update the state's controller. The two work together to properly simulate the complete "withdrawal and transfer of control" flow.
[add_manpower](/wiki/effect/add_manpower): If the unit teleport involves narrative manpower losses, you can replenish human resources to the destination state within the same block to strengthen the logical consistency of the event.
[state_event](/wiki/effect/state_event): Trigger a follow-up state event after teleportation completes, informing the player or advancing the narrative, forming a complete "teleport → event feedback" chain.

Common Pitfalls

Defining multiple target fields simultaneously: to_state, to_state_array, and to_province can only be used one at a time. If multiple are written together, the game will only use one of them (priority is opaque), and the rest are silently ignored, causing the destination to differ from expectations and making debugging extremely difficult.
Misunderstanding limit scope: The trigger scope within limit is the country that owns the army (the army's owner), not the current state scope. Beginners often mistakenly use state-level triggers (such as is_controlled_by) here, when they should actually use country-level triggers (such as tag). Otherwise the condition will never be met and no units will be teleported.

effect · teleport_armies