📦 Lesson 4.2: Components & Archetypes

Installing Entities

ECS lives in the Entities package. Open Window ▸ Package Manager, and install Entities (it pulls in Burst, Collections, and Mathematics from Module 3 as dependencies). To render entities you also want Entities Graphics, which adds the hybrid renderer that draws entities through URP. Installing Entities Graphics is the simplest route — it brings Entities along with it.

After install you'll see new editor windows under Window ▸ Entities (Hierarchy, Systems, Components) and DOTS options in the project settings. Those windows are UI Toolkit panels — throughout this module we describe and diagram them rather than screenshot them, exactly as with the other node-editor windows in the course.

Defining Components

A component is a struct implementing IComponentData, holding only blittable data. Here are a couple we'll use — note the Unity.Mathematics types from Module 3:

using Unity.Entities;
using Unity.Mathematics;

// Pure data. No methods, no MonoBehaviour, no references.
public struct Velocity : IComponentData
{
    public float3 Value;
}

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

These join the built-in components you already met: Unity.Transforms.LocalTransform (position/rotation/scale) and the rendering components that Entities Graphics attaches. Every field must be blittable — no string (use FixedString), no class references, no managed arrays. If you need a variable-length list per entity, there's a special DynamicBuffer element type, but plain IComponentData covers most data.

Tag Components

A component with no fields is a tag — it carries no data, it just marks an entity as being of some kind. Tags are free (zero bytes) and enormously useful, because systems query by component presence:

public struct Enemy : IComponentData { }       // a tag — marks "this is an enemy"
public struct Wandering : IComponentData { }    // a tag — marks a behaviour state

A system that should run only over enemies queries for the Enemy tag; a wandering-behaviour system queries for Wandering. You add and remove tags to change what an entity is and therefore which systems touch it — the ECS equivalent of flipping a boolean, but expressed in the type system where queries can see it.

Creating Entities in Code

Entities live in a World, and the EntityManager is the API for creating and editing them. In play mode the default world already exists:

using Unity.Entities;
using Unity.Mathematics;
using Unity.Transforms;

EntityManager em = World.DefaultGameObjectInjectionWorld.EntityManager;

// Create one empty entity, then add components (each Add is a structural change).
Entity e = em.CreateEntity();
em.AddComponentData(e, LocalTransform.FromPosition(new float3(0, 1, 0)));
em.AddComponentData(e, new Velocity { Value = new float3(1, 0, 0) });
em.AddComponentData(e, new Health  { Current = 100, Max = 100 });
em.AddComponent<Enemy>(e);   // add a tag (no data)

// Read and write component data:
Velocity v = em.GetComponentData<Velocity>(e);
em.SetComponentData(e, new Velocity { Value = v.Value * 2f });

That's the imperative way to build entities — handy for spawners and tests. In production you'll usually author entities with GameObjects and bake them (Lesson 4.4), but doing it by hand here makes the data model concrete: an entity is an ID, and you attach typed data to it.

💡 Where does the code run? You can call the EntityManager from a MonoBehaviour (to bootstrap a scene) or, more idiomatically, from inside a system — which is Lesson 4.3. Either way it's the same manager editing the same world.

Archetypes Explicitly

Adding components one by one works, but each add is a structural change that moves the entity between archetypes. When you're creating many identical entities, it's far better to declare the archetype up front and create them all at once:

// Declare the exact component set once.
EntityArchetype archetype = em.CreateArchetype(
    typeof(LocalTransform),
    typeof(Velocity),
    typeof(Enemy)
);

// Batch-create 10,000 entities of that archetype in one call — no per-entity churn.
NativeArray<Entity> enemies = em.CreateEntity(archetype, 10000, Allocator.Temp);

for (int i = 0; i < enemies.Length; i++)
{
    em.SetComponentData(enemies[i], LocalTransform.FromPosition(RandomPos(i)));
    em.SetComponentData(enemies[i], new Velocity { Value = RandomDir(i) });
}
enemies.Dispose();   // the array of handles; the entities live on in the world

All 10,000 entities share one archetype, so they pack into the same chunks and any system that queries { LocalTransform, Velocity, Enemy } streams straight through them. This is precisely how the 25,600-entity render in Lesson 4.1 was built — one archetype, one batch instantiate, then set each entity's data.

Inside a Chunk

Recall from Lesson 4.1 that entities of one archetype are stored together in 16 KB chunks, each component type as its own packed array. How many entities fit in a chunk depends on the archetype's total size per entity — a lean archetype packs more per chunk (better cache use); a fat one packs fewer.

Structural Changes & Enableable Components

Adding a component, removing one, creating or destroying an entity — these are structural changes. Because they move an entity between chunks (or allocate/free chunk space), they're heavier than editing a value, and they can't happen safely from inside a running job. That's why bulk creation uses archetypes, and why systems batch structural changes through an EntityCommandBuffer (Lesson 4.3).

But sometimes you want to toggle state constantly — stun an enemy this frame, un-stun it next — and adding/removing a tag every time would thrash the chunks. The fix is an enableable component: a component you can switch on and off without a structural change.

using Unity.Entities;

// IEnableableComponent lets you toggle presence cheaply — no chunk move.
public struct Stunned : IComponentData, IEnableableComponent { }

// Toggle it like a flag; queries can filter on enabled/disabled state.
em.SetComponentEnabled<Stunned>(entity, true);   // stun
em.SetComponentEnabled<Stunned>(entity, false);  // recover

The entity keeps the component in its archetype the whole time; only a bit flips. Queries can be told to consider only entities where Stunned is enabled. Reach for enableable components whenever a flag changes often — it keeps the memory layout stable and avoids structural-change cost on the hot path.

Hands-on Challenge

Summary

🚀 What's Next?

You can build ECS data; now you need behaviour. In Lesson 4.3: Systems & Queries — ISystem & SystemAPI we write systems that query these components every frame, edit them in bulk, and (with IJobEntity) run that work as Burst-compiled parallel jobs.