Wiki

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
  } 
}

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

  1. 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.
  2. 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.