mfgames-gallium-cil/docs/entity.md

Entity

The Entity class is a simplistic data structure that contains only two properties: a semi-unique identifier and a collection of components. It is immutable and thread-safe.

Identifier

Creating a new entity without any parameters will assign a new id, this is currently implemented as an int that is initialized by a static property managed by the Interlock to make it a thread-safe operation.

Entity entity = new();

NOTE: This means there is an effective limitation of 4.3 billion entities. The current reasoning is that most games don't need to have that many concurrent objects and will rarely roll over.

In situations were a more custom identifier management is needed, one of the constructors takes the int as a parameter.

var idManager;
Entity entity = new(idManager.GetNext());

In addition, there is a copy constructor that takes another entity and copies both the identifier and the components of the entity.

Entity entity1 = new();
Entity entity2 = new(entity1);

Assert.Equal(entity1.Id, entity2.Id);

Components

In addition to the identifier, entities have a collection of components. This is exposed as an immutable collection. Adding, removing, and setting components are immutable operations that create a new Entity object with the same identifier and a new collection of components.

Entity entity1 = new();
Entity entity2 = entity1.Add(23).Add("string value");
Entity entity3 = entity2.Set(56);

Assert.Equal(entity1.Id, entity2.Id);
Assert.Equal(entity1.Id, entity3.Id);
Assert.Equal(2, entity2.Components.Count);
Assert.Equal(2, entity3.Components.Count);
Assert.Equal(23, entity2.Get<int>());
Assert.Equal(56, entity3.Get<int>());