Starter ECS workflow

This example demonstrates a basic Entity Component System (ECS) workflow, and includes the following tasks:

Create an ECS component.
Create an ECS system that creates an entity and adds a component to it.
View the entity in the Entities Hierarchy window in Runtime data mode.

Prerequisites

This workflow requires a Unity 6 project with the Entities package installed.

Create an ECS component

ECS has multiple component types, and this example uses the most common one, a component based on the IComponentData interface.

The example component type is a struct. It's an unmanaged type which has a lot of performance benefits compared with GameObject components, which are always managed types.

To create an ECS component:

Create a new C# script called HelloWorld.cs and replace the contents of the file with the following code example.

using Unity.Entities;
using Unity.Collections;
using UnityEngine;

// This is an example of an unmanaged ECS component.
public struct HelloComponent : IComponentData
{
    // FixedString32Bytes is used instead of string, because
    // struct IComponentData can only contain unmanaged types.
    public FixedString32Bytes Message;
}

The HelloComponent component contains a Message variable of type FixedString32Bytes. Since struct IComponentData can only contain unmanaged types, you cannot use a regular C# string type variable. This example uses the FixedString32Bytes type, which is an unmanaged type, and has a fixed size.

Now the project has an ECS component that you can add to entities.

Create an ECS system

In ECS, you use systems to create and manipulate entities and components. An ECS system is a struct that implements the ISystem interface.

To create an ECS system:

In the HelloWorld.cs script, add the following struct based on the ISystem interface:

public partial struct ExampleSystem : ISystem
{
    public void OnCreate(ref SystemState state)
    {
        var entity = state.EntityManager.CreateEntity();
        // Initialize and add a HelloComponent component to the entity.
        state.EntityManager.AddComponentData(entity, new HelloComponent 
            { Message = "Hello ECS World" });
        // Set the name of the entity to make it easier to identify it.
        state.EntityManager.SetName(entity, "Hello World Entity");
    }

    public void OnUpdate(ref SystemState state)
    {
        // The query retrieves all entities with a HelloComponent component.
        foreach (var message in
                    SystemAPI.Query<RefRO<HelloComponent>>())
        {
            Debug.Log(message.ValueRO.Message);
        }
    }
}

Enter Play mode.

The console displays the Hello ECS World message.

The system creates a new entity in the OnCreate method, and adds an instance of the HelloWorld component to that entity.

In the OnUpdate method, the system uses a query expression to find all entities that have the HelloComponent component, and writes a message from the component in the console.

View the entity in Entities Hierarchy window

The system creates the entity at runtime, which means that the entity is only visible in the Editor when you enter Play mode. Since the entity is not a GameObject, it’s not visible in the regular Hierarchy window. ECS provides a special Entities Hierarchy window where you can view entities in an ECS world.

To view the entity that the system creates:

Open the Entities Hierarchy window using the menu Window > Entities > Hierarchy.
Enter Play mode.
In the Entities Hierarchy window, switch to the Runtime data mode.
The Entities Hierarchy window displays the new entity with the Hello World Entity name, as defined in the EntityManager.SetName method.
Select the new entity and view it in the Inspector window in the Runtime data mode. The Inspector window displays the Hello Component.

Complete code

This is the complete code of the HelloWorld.cs script:

using Unity.Entities;
using Unity.Collections;
using UnityEngine;

// This is an example of an unmanaged ECS component.
public struct HelloComponent : IComponentData
{
    // FixedString32Bytes is used instead of string, because
    // struct IComponentData can only contain unmanaged types.
    public FixedString32Bytes Message;
}

public partial struct ExampleSystem : ISystem
{
    public void OnCreate(ref SystemState state)
    {
        var entity = state.EntityManager.CreateEntity();
        // Initialize and add a HelloComponent component to the entity.
        state.EntityManager.AddComponentData(entity, new HelloComponent 
            { Message = "Hello ECS World" });
        // Set the name of the entity to make it easier to identify it.
        state.EntityManager.SetName(entity, "Hello World Entity");
    }

    public void OnUpdate(ref SystemState state)
    {
        // The query retrieves all entities with a HelloComponent component.
        foreach (var message in
                    SystemAPI.Query<RefRO<HelloComponent>>())
        {
            Debug.Log(message.ValueRO.Message);
        }
    }
}