effect · `destroy_entity`

Definition

Supported scope:any
Supported target:any

Description

destroys an existing entity
destroy_entity = 123 #id

实战 · 配合 · 坑

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

实战用法

destroy_entity 常用于动态场景演出 mod 中，需要在某个事件触发后移除地图上通过 create_entity 生成的视觉实体（如爆炸特效、建筑模型、标记物件）。典型场景是：先在 immediate 块生成一个实体并记录其 ID，再在后续 option 或延时事件中将其销毁，确保地图上不留残影。

# 假设之前 create_entity 返回的 ID 已存入变量
effect = {
    destroy_entity = var:entity_id_var
}

配合关系

[create_entity](/wiki/effect/create_entity)：destroy_entity 的前提通常是先用 create_entity 生成实体并记录 ID，二者构成完整的"创建—销毁"生命周期管理。
[set_variable](/wiki/effect/set_variable) / [set_temp_variable](/wiki/effect/set_temp_variable)：生成实体后需要把返回的 entity ID 存入变量，销毁时才能正确引用，避免硬编码数字 ID 导致不可维护。
[if](/wiki/effect/if)：在销毁前用 if 条件块配合 [has_variable](/wiki/trigger/has_variable) 判断 ID 变量是否存在，防止因实体已不存在而触发报错。

常见坑

直接硬编码数字 ID：entity ID 在不同存档或游戏进程中并不固定，直接写 destroy_entity = 123 极易销毁错误实体或无效报错，应始终通过变量传递 create_entity 返回的实际 ID。
销毁已不存在的实体：若实体在其他逻辑路径中已被销毁，再次调用 destroy_entity 指向同一 ID 会产生脚本报错；务必在销毁前用 [has_variable](/wiki/trigger/has_variable) 或逻辑标记确认实体仍然存在。

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

destroy_entity is commonly used in dynamic scene scripting mods to remove visual entities generated via create_entity from the map after certain events trigger (such as explosion effects, building models, or marker objects). The typical workflow is: first generate an entity in the immediate block and store its ID, then destroy it in subsequent options or delayed events, ensuring no visual artifacts remain on the map.

# Assuming the ID returned by create_entity was previously stored in a variable
effect = {
    destroy_entity = var:entity_id_var
}

Synergy

[create_entity](/wiki/effect/create_entity): destroy_entity typically requires first using create_entity to generate an entity and record its ID; the two form a complete "create—destroy" lifecycle management pattern.
[set_variable](/wiki/effect/set_variable) / [set_temp_variable](/wiki/effect/set_temp_variable): After generating an entity, store the returned entity ID in a variable so it can be correctly referenced during destruction, avoiding hardcoded numeric IDs that lead to unmaintainable code.
[if](/wiki/effect/if): Use if conditional blocks paired with [has_variable](/wiki/trigger/has_variable) before destruction to verify the ID variable exists, preventing script errors when the entity no longer exists.

Common Pitfalls

Hardcoding numeric IDs directly: Entity IDs are not fixed across different save games or game sessions; directly writing destroy_entity = 123 easily destroys the wrong entity or produces meaningless errors. Always pass the actual ID returned by create_entity through variables.
Destroying non-existent entities: If an entity has already been destroyed through a different code path, calling destroy_entity on the same ID again will generate a script error; always confirm the entity still exists using [has_variable](/wiki/trigger/has_variable) or logical flags before destruction.

effect · destroy_entity