jecs/docs/api/world-entity-management.md

Entity Management

This section covers methods for managing entities in the jecs World.

delete

Deletes an entity (and its components/relationships) from the world entirely.

function World:delete(entity: Entity): void

Parameters

Name	Type	Description
entity	Entity	The entity to delete from the world

Behavior

1. Invokes any OnRemove hooks for all components on the entity
2. Triggers any cleanup actions based on OnDelete and OnDeleteTarget relationships
3. Removes the entity from all archetypes
4. Recycles the entity ID for future use

Example

::: code-group

local world = jecs.World.new()

-- Create an entity
local entity = world:entity()
world:set(entity, Position, {x = 0, y = 0})

-- Delete the entity
world:delete(entity)

-- The entity no longer exists in the world
assert(not world:contains(entity))

import { World } from "@rbxts/jecs";

const world = new World();

// Create an entity
const entity = world.entity();
world.set(entity, Position, {x: 0, y: 0});

// Delete the entity
world.delete(entity);

// The entity no longer exists in the world
assert(!world.contains(entity));

:::

Child Entity Deletion

When an entity has children (via the ChildOf relationship), deleting the parent can also delete the children if the appropriate cleanup policy is set:

-- Set up parent-child relationship
local ChildOf = world:component()
world:add(ChildOf, jecs.pair(jecs.OnDeleteTarget, jecs.Delete))

local parent = world:entity()
local child = world:entity()

-- Make child a child of parent
world:add(child, jecs.pair(ChildOf, parent))

-- Deleting parent will also delete child
world:delete(parent)
assert(not world:contains(child))

Component Deletion

The delete method can also be used to delete a component definition:

local Temporary = world:component()
world:add(Temporary, jecs.pair(jecs.OnDelete, jecs.Remove))

-- Add Temporary to entities
local e1 = world:entity()
local e2 = world:entity()
world:add(e1, Temporary)
world:add(e2, Temporary)

-- Delete the component definition
world:delete(Temporary)

-- Temporary is removed from all entities
assert(not world:has(e1, Temporary))
assert(not world:has(e2, Temporary))

remove

Removes a component from a given entity.

function World:remove(entity: Entity, component: Id): void

Parameters

Name	Type	Description
entity	Entity	The entity to modify
component	Id	The component or relationship to remove

Behavior

1. Invokes any OnRemove hook for the component being removed
2. Removes the component from the entity
3. May cause the entity to transition to another archetype

Example

::: code-group

local world = jecs.World.new()

-- Create components
local Health = world:component()
local Shield = world:component()

-- Create an entity with both components
local entity = world:entity()
world:set(entity, Health, 100)
world:set(entity, Shield, 50)

-- Remove just the Shield component
world:remove(entity, Shield)

-- Entity still exists but no longer has Shield
assert(world:contains(entity))
assert(world:has(entity, Health))
assert(not world:has(entity, Shield))

import { World } from "@rbxts/jecs";

const world = new World();

// Create components
const Health = world.component();
const Shield = world.component();

// Create an entity with both components
const entity = world.entity();
world.set(entity, Health, 100);
world.set(entity, Shield, 50);

// Remove just the Shield component
world.remove(entity, Shield);

// Entity still exists but no longer has Shield
assert(world.contains(entity));
assert(world.has(entity, Health));
assert(!world.has(entity, Shield));

:::

Removing Relationships

The remove method can also be used to remove relationship pairs:

local ChildOf = world:component()
local parent = world:entity()
local child = world:entity()

-- Establish parent-child relationship
world:add(child, jecs.pair(ChildOf, parent))

-- Remove the relationship
world:remove(child, jecs.pair(ChildOf, parent))

-- Child is no longer related to parent
assert(not world:has(child, jecs.pair(ChildOf, parent)))

Differences Between delete and remove

Method	What It Affects	Entity Existence	Cleanup Policies
delete	Entity and all its components	Entity no longer exists	Triggers all cleanup policies
remove	Only the specified component	Entity still exists	Only triggers component-specific OnRemove hook

When to Use Each Method

• Use delete when you want to completely remove an entity from the world
• Use remove when you want to keep the entity but remove specific components
• Use delete on a component definition to remove that component from all entities

Performance Considerations

Both operations may cause archetype transitions, which have performance implications:

• delete typically has more overhead because it has to remove all components
• remove is generally faster for individual component removal
• Both methods are optimized in jecs to be as efficient as possible

For performance-critical code dealing with many entities, consider batching operations to minimize archetype transitions.