Component/relationship properties roadmap

[SanderMertens]

Creating this discussion to keep track of current & future relationship properties (documentation for current properties can be found here: https://flecs.docsforge.com/master/relations-manual/#relation-properties).

Background

Glossary

Word	Description
Component	Id that when added to an entity, instantiates a value of associated type T
Tag	Id that when added to an entity instantiates no value
Pair	Id that can be added to an entity, and consists out of 2 elements (e.g. (Eats, Apples))
Relation	First element of a pair (e.g. Eats)
Object	Second element of a pair (e.g. Apples)
Subject	Entity to which a component/tag/pair is added (e.g. Bob in Bob.add(Eats, Apples))

Pairs & Components

Pairs can either be tags or components, depending on its elements. The following rules determine the pair (component) type:

• if both parts of a pair are a tag, the pair is a tag:
  (Eats, Apples) is a tag if both Eats and Apples are tags.

• if one part of a pair is a component, the pair type is that component
  The type of (Eats, Apples) is Eats if Eats is a component and Apples is a tag
  The type of (Start, Position) is Position if Start is a tag and Position is a component

• if both parts of a pair are a component, the pair type is the first pair element
  The type of (Expire, Position) is Expire if both Expire and Position are components.

Existing properties

For existing properties, see the component traits manual: https://www.flecs.dev/flecs/md_docs_2ComponentTraits.html

Future properties

The following properties haven't been implemented yet but are on the roadmap. Subject to change.

Relation(T)

Forces T to be used in a pair as relation. May throw an error when used as component or pair object.

Usage:

ChildOf.add(Relation);

Target(T)

Forces the T to be used in a pair as target. May throw an error when used as component or pair relation.

Usage:

Delete.add(Object);

OneWith(R, T)

Forces the object of pairs with R to have T.

Usage:

Target.add(OneWith, Enemy);

OppositeOf(X, Y)

Entity cannot both have X and Y, or (X, O) and (Y, O). Adding (OppositeOf, Y) to X will add (OppositeOf, X) to Y.

Usage:

Ally.add(OppositeOf, Enemy);

SameAs(X, Y)

X is equivalent to Y. Adding (SameAs, X) to Y will add (SameAs, Y) to X. Queries for X and (X, O) should include results for Y and (Y, O), and vice versa.

Usage:

LocatedIn.add(SameAs, LocatedAt);

Requires(X, Y)

X or (X, O) can only be added to entities with Y or (Y, O)

Usage:

Trading.add(Requires, Ally);

Storage(T, O)

Specifies storage policy O for instances of T. Valid values of O are:

• Table: instances of T are stored in a table (fragments tables)
• Archetype: instances of T are stored on an archetype (does not fragment tables, 1 archetype can point to N tables)
• World: instances of T are stored on the world (does not fragment tables, one storage for T per world)

Usage:

Movement.add(Storage, Archetype)

Const(T)

Instances of component T cannot be modified after adding, but instances of T can be removed. Prevents creation of queries for T with an inout or out modifier.

Usage

Component.add(Const);

Singleton(T)

Component T can only be used as singleton (cannot be added to entities other than itself). Prevents creation of queries for T that do not have T as subject.

Usage

Game.add(Singleton);