Quick start

Quick start

In this first step, a goblin scout enters the clockwork arena with a position and velocity. We will register those types, create the scout, and advance it by one tick.

1. Install the packages

Add the runtime and source generator to the game project:

dotnet add package DeltaECS
dotnet add package DeltaECS.Generators

The packages are also available on NuGet: DeltaECS and DeltaECS.Generators.

The runtime stores the world and components. The generator supplies the typed query and iteration overloads used below.

2. Define the scout's components

Put these types in Components.cs:

public struct Position
{
    public float X;
    public float Y;
}

public struct Velocity
{
    public float X;
    public float Y;
}

public struct Goblin { }

Position and Velocity hold changing data. Goblin is a marker with no data, so it will be registered as a tag.

3. Create a world and register the components

In Program.cs, create a world and register each component type before creating entities that use it:

using System;
using Delta.ECS;

var layouts = new ComponentRegistry();

layouts.Register<Position>(new SchemaId(1));
layouts.Register<Velocity>(new SchemaId(2));
layouts.Register<Goblin>(new SchemaId(3));

using var world = new World(layouts);

4. Create the scout

Create and initialize the two data components, then give the entity its race tag:

Entity scout = world.Create<Position>();
world.GetRef<Position>(scout) = new Position { X = 4f, Y = 2f };
world.Add(scout, new Velocity { X = 0.5f, Y = -1f });

world.Add<Goblin>(scout);

5. Select and move it

The query describes which entities the movement pass needs. The callback receives writable Position and read-only Velocity:

Query scouts = world.WhereAll<Goblin, Position, Velocity>();

world.ForEach(
    in scouts,
    static (ref Position position, in Velocity velocity) =>
    {
        position.X += velocity.X;
        position.Y += velocity.Y;
    }).Invoke();

Position result = world.Get<Position>(scout);
Console.WriteLine($"{result.X}, {result.Y}");

This is the basic loop used throughout the wiki: register the data shape, create entities with that shape, select the intended group, then run a focused pass over it.

Previous: Home · Next: Components, Tags and Queries