Entities & components

An entity is just an ID. What makes it interesting is the components attached to it.

Components and tags

A component is a struct implementing IComponent. It carries data, and it’s the unit archetype storage groups by.

public struct Health : IComponent { public int Current; public int Max; }

A tag is a struct implementing ITag instead. It carries no data, it just marks an entity as having some property.

public struct Stunned : ITag { }

Creating entities

All structural changes, creating entities, adding or removing components, go through a CommandBuffer. world.Commands is the world’s default one.

Entity goblin = world.Commands.CreateEntity()
    .AddComponent(new Health { Current = 10, Max = 10 })
    .AddTag<Stunned>();
world.ApplyCommands();

Nothing is queued into the world until world.ApplyCommands() runs. A query never sees a half-finished change mid-iteration.

The EntityView shortcut

CreateEntity() returns an EntityView, a chainable handle bound to one entity and the buffer it queues on. Once you have one, every mutation is a direct call on it:

goblin.RemoveTag<Stunned>()
    .AddComponent(new Health { Current = 5, Max = 10 });
world.ApplyCommands();

Tip

EntityView is a ref struct, it can’t be stored in a field, a list, or captured by a lambda, only ever a local variable or a chained expression. If all you have is a plain Entity you stored earlier, world[goblin] gets you an EntityView back for it.

See Systems for how a system’s Update gets one automatically.

Advanced

goblin.AddComponent(...) and world.Commands.AddComponent(goblin, ...) queue the exact same thing, EntityView is a thin wrapper. The direct form skips constructing a view, worth it only in a hot per-entity loop.

Destroying entities

goblin.DestroyEntity();
world.ApplyCommands();

Tip

For how archetypes actually store this and why adding a component moves the entity, see ECS Architecture.

Next

Once you can create entities, the next step is asking which ones have what. See Queries.