gaemstone.ECS/README.md

# gaemstone.ECS

.. is a medium-level managed wrapper library around the [flecs-cs] bindings for the amazing [Entity Component System (ECS)][ECS] framework [Flecs]. It is used as part of the [gæmstone] game engine, but may be used in other projects as well. To efficiently use this library, a thorough understanding of [Flecs] is required.

These classes have been split from the main [gæmstone] project. It is still a little unclear what functionality belongs where, and structural changes may occur. In its current state, I recommend to use this repository simply as a reference for building similar projects.

[ECS]: https://en.wikipedia.org/wiki/Entity_component_system
[Flecs]: https://github.com/SanderMertens/flecs
[flecs-cs]: https://github.com/flecs-hub/flecs-cs
[gæmstone]: https://git.mcft.net/copygirl/gaemstone

## Features

- Convenient wrapper types such as [Id], [Entity] and [EntityType].
- [EntityPath] uses a unix-like path, for example `/Game/Players/copygirl`.
- Fast type-to-entity lookup using generic context on [World]. (See below.)
- Define your own [Components] as both value or reference types.
- Query the ECS with [Iterators], [Filters], [Queries] and [Rules].
- Create [Systems] for game logic and [Observers] to act on changes.

[Id]:         ./src/gaemstone.ECS/Id.cs
[Entity]:     ./src/gaemstone.ECS/Entity.cs
[EntityType]: ./src/gaemstone.ECS/EntityType.cs
[EntityPath]: ./src/gaemstone.ECS/EntityPath.cs
[World]:      ./src/gaemstone.ECS/World.cs
[Components]: ./src/gaemstone.ECS/Component.cs
[Iterators]:  ./src/gaemstone.ECS/Iterator.cs
[Filters]:    ./src/gaemstone.ECS/Filter.cs
[Queries]:    ./src/gaemstone.ECS/Query.cs
[Rules]:      ./src/gaemstone.ECS/Rule.cs
[Systems]:    ./src/gaemstone.ECS/System.cs
[Observers]:  ./src/gaemstone.ECS/Observer.cs

## Example

```cs
var world = new World<Program>();

var position = world
	.New("Position")    // Create a new EntityBuilder, and set its name.
	.Symbol("Position") // Set entity's symbol. (Used in query expression.)
	.Build()            // Actually create the entity in-world.
	// Finally, create a component from this entity.
	// "Position" is defined at the bottom of this example.
	.InitComponent<Position>();

// Create an "Entities" parent with two positioned entities inside.
var entities = world.New("Entities").Build();
entities.NewChild("One").Set(new Position(-5,  0)).Build();
entities.NewChild("Two").Set(new Position(10, 20)).Build();

// Changed my mind: Let's multiply each entity's position by 10.
foreach (var child in entities.GetChildren()) {
	ref var pos = ref child.GetRefOrThrow<Position>();
	pos = new(pos.X * 10, pos.Y * 10);
}

// The following systems run in the "OnUpdate"
// phase of the default pipeline provided by Flecs.
var dependsOn = world.LookupPathOrThrow("/flecs/core/DependsOn");
var onUpdate  = world.LookupPathOrThrow("/flecs/pipeline/OnUpdate");

// Create a system that will move all entities with
// the "Position" component downwards by 2 every frame.
world.New("FallSystem")
	.Add(dependsOn, onUpdate)
	.Build().InitSystem(new("Position"), iter => {
		var posColumn = iter.Field<Position>(1);
		for (var i = 0; i < iter.Count; i++) {
			ref var pos = ref posColumn[i];
			pos = new(pos.X, pos.Y - 2);
		}
	});

// Create a system that will print out entities' positions.
world.New("PrintPositionSystem").Build()
	.Add(dependsOn, onUpdate)
	.InitSystem(new("[in] Position"), iter => {
		var posColumn = iter.Field<Position>(1);
		for (var i = 0; i < iter.Count; i++) {
			var entity = iter.Entity(i);
			var pos    = posColumn[i];
			Console.WriteLine($"{entity.Name} is at {pos}");
		}
	});

// Infinite loop that runs the "game" at 30 FPS.
while (true) {
	var delta = TimeSpan.FromSeconds(1.0f / 30);
	// Progress returns false if quit was requested.
	if (!world.Progress(delta)) break;
	Thread.Sleep(delta);
}

record struct Position(int X, int Y);
```

## Instructions

```sh
# Clone the repository. Recurse into submodules to include flecs-cs and flecs.
git clone --recurse-submodules https://git.mcft.net/copygirl/gaemstone.ECS.git

# If you want to add it to your own repository as a submodule:
git submodule add https://git.mcft.net/copygirl/gaemstone.ECS.git

# To add a reference to this library to your .NET project:
dotnet add reference gaemstone.ECS/gaemstone.ECS.csproj

# To generate flecs-cs' bindings:
./gaemstone.ECS/src/flecs-cs/library.sh
```

## On the `TContext` type parameter

Entities may be looked up simply by their type, once they're registered with `CreateLookup` or `InitComponent`. Under the hood, this is made possible using a nested static generic class that hold onto an `Entity` field. Theoretically this could be compiled into a simple field lookup and therefore be faster than dictionary lookups.

To support scenarios where multiple worlds may be used simultaneously, each with their own unique type lookups, we specify a generic type as that context.

In cases where only a single world is used, the amount of typing can be reduced by including a file similar to the following, defining global aliases:

```cs
global using Entity   = gaemstone.ECS.Entity<Context>;
global using Id       = gaemstone.ECS.Id<Context>;
global using Iterator = gaemstone.ECS.Iterator<Context>;
global using World    = gaemstone.ECS.World<Context>;
// Add more aliases as you feel they are needed.

public struct Context {  }
```