effect · destroy_entity

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

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