Relations

Relations are components that store an entity target.

SIECS includes the built-in ChildOf relation:

C

ecs_set(child, ChildOf, { .target = parent });

C++

child.child_of(parent);

The generated relation struct contains:

C

typedef struct {
    ecs_entity_t target;
} ChildOf;

C++

// ChildOf is provided by the SIECS C++ wrapper.

Declare Custom Relations

Declare and define a relation:

C

ECS_RELATION_DECLARE(Targets);
ECS_RELATION_DEFINE(Targets, 0);
ECS_COMPONENT_REGISTER(world, Targets);
ecs_set(entity, Targets, { .target = other_entity });

C++

struct Targets { ecs::entity target; };

// The wrapper can store the relation value, but it has no helper for
// ECS_RELATION_DEFINE flags such as cascade deletion.
entity.set(Targets{ .target = other_entity });

ChildOf is defined with EcsRelationCascadeDelete, so killing a parent also kills its children. Custom relations only remove reverse links by default unless they opt into that flag.

Source Component

For every relation component, SIECS also creates an internal source component used to track reverse links.

C

ecs_component_t source_id = ecs_source(Targets);

C++

// Source components are internal; use the relation component itself.

Lifecycle

When a relation target changes, SIECS removes the source entity from the old target reverse list and appends it to the new target reverse list. Removing the relation removes the reverse link.

When a target entity is killed:

• relations without EcsRelationCascadeDelete remove the relation from sources
• relations with EcsRelationCascadeDelete kill the source entities too

ChildOf uses cascade delete because child entities are considered owned by their parent.