Skip to content

GlobalUsings

ERS uses a 64-bit unsigned integer for the IDs of Entities. To provide the best performance, the C# bindings don't use an Entity struct or class, but use UInt64 / ulong directly as entities. Using extension methods on UInt64 / ulong, ERS adds convenience functions like AddComponent<T>():

// Without extension methods
SubModel subModel = SubModel.Get();
subModel.AddComponent<TransformComponent>(entity);

// With extension methods
entity.AddComponent<TransformComponent>();

The following extensions methods on UInt64 / ulong are added by ERS:

  • IsValid: Check whether an entity is valid.
  • GetComponent<T>(): Gets the submodel and uses its GetComponent<T>().
  • AddComponent<T>(): Gets the submodel and uses its AddComponent<T>().
  • RemoveComponent<T>(): Gets the submodel and uses its RemoveComponent<T>().
  • HasComponent<T>(): Gets the submodel and uses its HasComponent<T>().
  • GetName(): Gets the NameComponent and retrieving the name.

However, there is no distinction between an entity and a UInt64 / ulong. C# allows creating type aliases using the using keyword, which would allow ERS to add a type alias of Entity to UInt64 / ulong. Unfortunately, C# does not allow exporting such aliases to dependents. This means any alias defined in ERS is only usable within ERS and not any projects that use ERS.

To still have a clear distinction between UInt64 / ulong and ERS entities, we recommend adding a global using file to C# projects using ERS:

// GlobalUsings.cs
global using Entity = System.UInt64;

Placing this file in the root directory of a C# project allows using Entity as a type instead of ulong and prevents confusion:

// Without GlobalUsings.cs
SubModel subModel = SubModel.Get();
ulong someEntity = subModel.CreateEntity("SomeEntity");
ulong someNumber = 123;

// With GlobalUsing.cs
SubModel subModel = SubModel.Get();
Entity someEntity = subModel.CreateEntity("SomeEntity");
ulong someNumber = 123;

Note

Note that this way Entity is still actually a ulong and C# allows mixing the two: C# will not prevent you from using an Entity as if it were a ulong. For example, a ulong and an Entity can be assigned to each other, subtracted, multiplied, etc. The alias is meant to help improve readability.

Was this page helpful?