# Entity

In an [entity component system (ECS)](/arch/documentation/concepts.md), 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`](/arch/documentation/optimizations/pure_ecs.md). More on this later.

{% hint style="info" %}
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!
{% endhint %}

## Lifecycle

Creating entities is really simple! 

<pre class="language-csharp"><code class="lang-csharp">var world = World.Create(); // World must exist somewhere

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

{% hint style="info" %}
Components may vary and this example uses generics, if you don't feel like using generics, there are still [plenty of APIs without them](/arch/documentation/utilities/non-generic-api.md).
{% endhint %}

How does it feel to be a god? Now lets step one further.&#x20;

## Change

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

<pre class="language-csharp"><code class="lang-csharp">// Create our beloved dwarf
var dwarf = world.Create(new Dwarf("Gimli"), new Position(0,0), new Velocity());

// Telepor the dwarf
ref var position = ref <a data-footnote-ref href="#user-content-fn-1">dwarf.Get&#x3C;Position>();</a>
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&#x3C;Pickaxe>()) <a data-footnote-ref href="#user-content-fn-2">dwarf.Add(new Pickaxe());</a>
dwarf.Remove&#x3C;Pickaxe>();
</code></pre>

{% hint style="warning" %}
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.
{% endhint %}

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.

```csharp
// 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>();
}
```

{% hint style="info" %}
Up to 25 generic overloads are available, order does not matter. This often saves code and is often faster.
{% endhint %}

## 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.

```csharp
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
```

{% hint style="warning" %}
We should always compare the `Entity`s directly, never just via the Id!
{% endhint %}

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.&#x20;

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

{% hint style="info" %}
The entity also has a debug view which reveals even more information.
{% endhint %}

## Pitfalls

There are **no hidden costs** in Arch, [**everything** **happens directly**](/arch/documentation/concepts.md#performance-performance-performance) 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**](/arch/documentation/utilities/commandbuffer.md) **these operations and performing them after the query**. Take a look at the [examples](/arch/examples-and-guidelines/page-2.md)!

[^1]: `TryGet`also exists.

[^2]: \`Ensure\` also exists.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://arch-ecs.gitbook.io/arch/documentation/entity.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.