effect · `set_entity_movement`

Definition

Supported scope:any
Supported target:any

Description

sets the position & rotation of an existing entity using two coordinates
set_entity_movement = {
  id = 123 # id of entity 
  start = { 
    # position can be set using following 
    x = 42 
    y = 21 
    province = 123 
    state = 42 
    z = 3 #if wanted you can specify a z to shift height of the entity
  } 
  target = { 
    # position can be set using following 
    x = 42 
    y = 21 
    province = 123 
    state = 42 
    z = 3 #if wanted you can specify a z to shift height of the entity
  } 
  ratio = 0.5 # a ratio in between 0 - 1. the entity is positioned in between start & target position using this ratio 
  rotation = 1.2 # angle in radio, entity is rotated using the direction and this angle is added after that 
}

实战 · 配合 · 坑

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

实战用法

set_entity_movement 常用于剧情动画 mod 中，让地图上的自定义实体（飞机、舰船、车辆模型等）沿着指定路径做插值位移，配合事件链逐帧推进可实现过场动画效果。例如在一个展示舰队移动的剧情事件中，通过不断改变 ratio 值来模拟实体从出发港口滑向目标海域：

# 在某个事件的 immediate 块中，让实体移动到起点与终点的中间位置
set_entity_movement = {
    id = 101
    start = {
        province = 11620  # 出发港口所在省份
    }
    target = {
        province = 11634  # 目标海域省份
    }
    ratio = 0.5           # 当前停在路途中间
    rotation = 1.57       # 朝向调整为大致向东（弧度）
}

配合关系

[create_entity](/wiki/effect/create_entity) — 实体必须先被创建才能通过本命令移动，二者通常配合出现在同一事件链的不同阶段。
[set_entity_rotation](/wiki/effect/set_entity_rotation) — 若只需精确调整朝向而不做位移插值，可与本命令分工；也可在移动后用它做最终朝向校正。
[set_entity_animation](/wiki/effect/set_entity_animation) — 移动过程中往往需要同步切换实体的行进动画状态，与本命令同步调用可保证视觉一致性。
[destroy_entity](/wiki/effect/destroy_entity) — 动画结束后清理不再需要的实体，与本命令构成"创建→移动→销毁"的完整生命周期。

常见坑

ratio 超出 0–1 范围不会报错但行为未定义：新手有时用变量动态传入 ratio，若变量因累加超过 1.0，实体会被插值到 target 之外的位置，导致模型凭空出现在地图边缘。务必在赋值前用 [clamp_variable](/wiki/effect/clamp_variable) 或 [clamp_temp_variable](/wiki/effect/clamp_temp_variable) 将变量限制在合法区间。
id 与 create_entity 的 id 必须严格对应：如果引用了一个尚未创建或已被 destroy_entity 销毁的实体 id，游戏不会崩溃但命令会静默失效，排查时极难发现，建议在同一文件中用注释明确标注每个 id 的生命周期。

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

set_entity_movement is commonly used in cinematic animation mods to make custom entities on the map (aircraft, ships, vehicle models, etc.) interpolate along a specified path. Combined with event chains that advance frame-by-frame, this creates cutscene effects. For example, in a story event showcasing fleet movement, you can simulate an entity gliding from a departure port to a target sea zone by continuously adjusting the ratio value:

# In the immediate block of an event, move the entity to the midpoint between start and target
set_entity_movement = {
    id = 101
    start = {
        province = 11620  # Province of departure port
    }
    target = {
        province = 11634  # Province of target sea zone
    }
    ratio = 0.5           # Currently positioned halfway along the route
    rotation = 1.57       # Rotation adjusted roughly eastward (in radians)
}

Synergy

[create_entity](/wiki/effect/create_entity) — Entities must be created before they can be moved by this command; both typically appear in different stages of the same event chain.
[set_entity_rotation](/wiki/effect/set_entity_rotation) — If you only need to adjust rotation without interpolating position, you can use this separately; it can also be called after movement for final rotation correction.
[set_entity_animation](/wiki/effect/set_entity_animation) — Movement often requires syncing the entity's animation state in parallel. Calling this command alongside movement ensures visual consistency.
[destroy_entity](/wiki/effect/destroy_entity) — Clean up entities no longer needed after the animation finishes, forming a complete lifecycle of "create → move → destroy" with this command.

Common Pitfalls

ratio values outside the 0–1 range don't error but produce undefined behavior: Beginners sometimes pass ratio dynamically via variables. If a variable exceeds 1.0 through accumulation, the entity will interpolate beyond the target position, causing the model to appear off-map at an edge. Always constrain variables to the legal range using [clamp_variable](/wiki/effect/clamp_variable) or [clamp_temp_variable](/wiki/effect/clamp_temp_variable) before assignment.
The id must correspond exactly with the id from create_entity: If you reference an entity id that hasn't been created yet or has already been destroyed by destroy_entity, the game won't crash but the command silently fails, making it extremely difficult to debug. It's recommended to clearly annotate the lifecycle of each id in comments within the same file.

effect · set_entity_movement