Entity

The Entity, an abstract being, equipped with data.

In an entity component system (ECS), an entity is simply a unique ID tag. It represents an object in the game or application, but has no logic or data itself. The data and behavior come from components that are attached to this entity.

An Entity is nothing more than a simple record struct Entity{ int ID, int WorldId, int Version }. Either you work directly on this entity and its methods, or you simply use PURE_ECS. More on this later.

Its components can be anything, primitive data types, structs and even classes! YOU determine which components and attributes an entity receives, there are no restrictions here!

Lifecycle

Creating entities is really simple!

var world = World.Create(); // World must exist somewhere

// A dwarf with a string, position and velocity component was born and killed
var dwarf = world.Create(new Dwarf("Gimli"), new Position(0,0), new Velocity());
if(dwarf.IsAlive()) world.Destroy(dwarf);

Components may vary and this example uses generics, if you don't feel like using generics, there are still plenty of APIs without them.

How does it feel to be a god? Now lets step one further.

Change

Changing entities is of course also possible and also very easy.

// Create our beloved dwarf
var dwarf = world.Create(new Dwarf("Gimli"), new Position(0,0), new Velocity());

// Telepor the dwarf
ref var position = ref dwarf.Get<Position>();
position.X++;
position.Y++;

// Force him to move on its own
dwarf.Set(new Velocity(1,1));

// Give the dwarf a pickaxe and make him sad by taking it away
if(!dwarf.Has<Pickaxe>()) dwarf.Add(new Pickaxe());
dwarf.Remove<Pickaxe>();

The safety check using .Has<T>() is important. Arch does not do this itself because because our mantra is raw performance and we trust you as a developer to know when to check and when not to.

We have now added a component to the entity (the pickaxe) and removed it again immediately. Now let's see how we can do this for several components at the same time.

// Adding components to our dwarf in batch (We could also pass them as parameters)
dwarf.Add<Pickaxe, DwarfArmor, LeatherBoots, IronHelmet>();

// Receiving components in batch and modifying them
var equipment = dwarf.Get<Pickaxe, DwarfArmor, LeatherBoots, IronHelmet>();
equipment.t0.Durability = 100f;
equipment.t1.Defence = 100f;
equipment.t3.Weight = 0.5f;

// Overwriting components since, why not? 
dwarf.Set(new DwarfArmor(110f), new LeatherBoots(Sole.GRIPPY));

// Dwarf happy now, lets ensure he does not wear any other gear by removing it
if(dwarf.Has<Bow, ElvishArmor, LongWhiteHair>()){
    dwarf.Remove<Bow, ElvishArmor, LongWhiteHair>();
}

Up to 25 generic overloads are available, order does not matter. This often saves code and is often faster.

Reference

We can easily reference other entities using the Entity struct. Even if the entities recycle (and thus the Id of an entity can reappear), each Entity has an Entity.Version which functions as a timestamp.

var dwarf = world.Create<Dwarf, Position, Velocity>();
world.Destroy(dwarf);
var recycledDwarf = world.Create<Dwarf, Position, Velocity>();

Console.WriteLine($"Dwarf-Id: {dwarf.Id} and RecycledDwarf-Id: {recycledDwarf.Id}");
Console.WriteLine(dwarf == recycledDwarf); // False, same Id but different versions

We should always compare the Entitys directly, never just via the Id!

So you can simply save an Entity somewhere and use it as a direct reference to access it at any time.

Inspect

Inspecting entities is also a rather simple task.

var types = dwarf.GetComponentTypes();       // Getting all types, readonly
var components = dwarf.GetComponents();      // Getting all components by boxing
Console.WriteLine(dwarf);                    // Printing the entity

The entity also has a debug view which reveals even more information.

Pitfalls

There are no hidden costs in Arch, everything happens directly without any black magic under the hood or hidden code slowing down your system. This means that everything is executed directly, without abstraction costs, the only disadvantage is that you have to make sure and check that your action makes sense at that point.

Even if it is possible to create entities during a query, change its structure or destroy it, we recommend buffering these operations and performing them after the query. Take a look at the examples!