pyxen.world.destroy()

Destroy an existing Entity and remove it from the world.

This permanently deletes the entity and all of its components.

Syntax

pyxen.world.destroy(entity)

Parameters

Returns

None

What Happens When You Destroy an Entity

Calling destroy() will:

• ❌ Remove the entity from the world
• ❌ Remove all attached components (Sprite, Sound, Music, GridMap, GridBody, etc.)
• ❌ Remove parent/child relationships
• ❌ Free its internal ID for reuse (generation-safe)

After destruction, the entity should no longer be used.

Example

Destroy an Entity

enemy = pyxen.world.spawn(sprite=assets.enemy, x=40, y=12)

# Later…
pyxen.world.destroy(enemy)

Destroying from Gameplay Logic

if player.health <= 0:
    pyxen.world.destroy(player)

Common Pattern: Timed Removal

explosion = pyxen.world.spawn(sprite=assets.explosion, x=32, y=16)

if explosion_timer.finished():
    pyxen.world.destroy(explosion)

Important Notes

⚠️ Do Not Reuse Destroyed Entities

Once destroyed:

pyxen.world.destroy(enemy)

enemy.x = 10  # ❌ Invalid usage

The entity is no longer valid inside the world.

If you need a new one — call spawn() again.

Parent / Child Behavior

If the destroyed entity:

• Has children → they are automatically removed
• Has a parent → it is removed from the hierarchy

Destruction is recursive and safe.

Type Safety

If a non-Entity object is passed:

pyxen.world.destroy("not an entity")

A runtime error will occur.

Always pass a valid Entity.

Design Philosophy

In Pyxen:

• Entities are lightweight handles
• Components define behavior
• Destroying removes the full composition

This keeps memory predictable and ECS-friendly.