Breaking Changes

[BeanCheeseBurrito]

Breaking changes will be posted here.

[BeanCheeseBurrito]

The Query.World property has been removed. Use Query.World() or Query.RealWorld() instead.

Old:

ecs_world_t* world = query.World;

New:

World world = query.World();
World realWorld = query.RealWorld();

[BeanCheeseBurrito]

Entity.Remove<T>() no longer removes (T, *) pair when using an enum type argument. Entity.Remove<T>(Ecs.Wildcard) should be used instead.

Entity.Has<T>() no longer checks for existence of (T, *) when using an enum type argument. Entity.Has<T>(Ecs.Wildcard) should be used instead.

Old:

Entity e = world.Entity()
    .Add(Color.Red)
    .Set(Color.Red);

e.Has<Color>(Ecs.Wildcard); // True
e.Has<Color>();             // True

e.Remove<Color>();
e.Has<Color>(Ecs.Wildcard); // False
e.Has<Color>();             // True

New:

Entity e = world.Entity()
    .Add(Color.Red)
    .Set(Color.Red);

e.Has<Color>(Ecs.Wildcard); // True
e.Has<Color>();             // True

e.Remove<Color>();
e.Has<Color>(Ecs.Wildcard); // True
e.Has<Color>();             // False

[BeanCheeseBurrito]

Instanced queries have been removed. See this post for more information SanderMertens/flecs#466 (comment)

[BeanCheeseBurrito]

The following fields have been renamed:

• RoutineBuilder.RoutineDesc renamed to SystemBuilder.Desc
• ObserverBuilder.ObserverDesc renamed to ObserverBuilder.Desc
• PipelineBuilder.PipelineDesc renamed to PipelineBuilder.Desc
• AlertBuilder.AlertDesc renamed to PipelineBuilder.Desc
• AlertBuilder.Id renamed to AlertBuilder.AlertId
• AlertBuilder.Var renamed to AlertBuilder.AlertVar

Routines have been renamed to System to more closely match the C++ API.
Routine renamed to System_
RoutineBuilder renamed to SystemBuilder
world.Routine() renaed to world.System()

[BeanCheeseBurrito]

A new type-safe generic query API has been added to help reduce common errors relating to queries.

Old:

using Query query = world.Query<Position, Velocity>();
query.Each((ref Position p, ref Velocity v) => { });

New:

using Query<Position, Velocity> query = world.Query<Position, Velocity>();
query.Each((ref Position p, ref Velocity v) => { }); // Parameter types must match the query's type list.

When calling factory methods for query types using type parameters (ex. World.Query<T1, ...>), a generic query object will be returned instead of an untyped query.

• World.Query<T1, ...>() returns Query<T1, ...>
• World.QueryBuilder<T1, ...>() returns QueryBuilder<T1, ...>
• World.Observer<T1, ...> returns Observer<T1, ...>
• World.System<T1, ...> returns System<T1, ...>

Using tags in the above factory methods is no longer allowed and will trigger an assert in debug mode. Use .With<Tag>() to query for tag types.

IterIterable, PageIterable, and WorkerIterable types now have generic versions as well.

• IIterable.Iter() returns IterIterable<T1, ...>
• IIterable.Page() returns PageIterable<T1, ...>
• IIterable.Worker() returns WorkerIterable<T1, ...>

[BeanCheeseBurrito]

Minimum target version bumped to .NET 8

All projects must now target .NET 8 or above. Support for .NET 7 and lower versions have been removed. This change is a prerequisite to implementing pinned array storage for managed types in the future #21. The Unity package will no longer be updated.

[BeanCheeseBurrito]

Id.Entity() has been renamed to Id.ToEntity()

Old:

e.Each((Id id) =>
{
    if (id.IsEntity())
    {
        Entity comp = id.Entity();
        Console.Write(comp.ToString());
    }
});

New:

e.Each((Id id) =>
{
    if (id.IsEntity())
    {
        Entity comp = id.ToEntity(); // Renamed to ToEntity()
        Console.Write(comp.ToString());
    }
});

[BeanCheeseBurrito]

The callback signature for AppBuilder.Init() has been changed to accept a World instead of ecs_world_t*

Old:

using World world = World.Create();

world.App()
    .Init(Setup)
    .Run();

static void Setup(ecs_world_t* worldPtr)
{
    World world = World.Create(worldPtr);
    world.Import<Module1>();
    world.Import<Module2>();
    world.Import<Module3>();
}

New:

using World world = World.Create();

world.App()
    .Init(Setup)
    .Run();

static void Setup(World world)
{
    world.Import<Module1>();
    world.Import<Module2>();
    world.Import<Module3>();
}

[BeanCheeseBurrito]

Managed types are now allowed to be passed as user context to systems and observers. Previously only pointers to unmanaged types were allowed.

Old:

int value = 10;

world.System()
    .Ctx(&value) // Pointer has to be passed.
    .Each(static (Iter it, int _) =>
    {
        ref int ctx = ref it.Ctx<int>();
        Console.WriteLine(ctx); // Prints 10
    });

New:

world.System()
    .Ctx("Context") // Context is passed by value
    .Each(static (Iter it, int _) =>
    {
        ref string ctx = ref it.Ctx<string>();
        Console.WriteLine(ctx); // Prints "String"
    });

A callback can be provided to run clean-up logic before the context object is freed.

world.System()
    .Ctx("Context", static (ref string ctx) =>
    {
        Console.WriteLine("Context is being freed");
    }) 
    .Each(...);

[BeanCheeseBurrito]

World is now a readonly struct. World.Reset() has been removed.

Old:

World world = World.Create();
world.Reset();

New:

World world = World.Create();
world.Dispose();
world = World.Create();

[BeanCheeseBurrito]

The raw bindings have been updated to use modern .NET 8 features.

• DisableRuntimeMarshalling attribute to applied to Flecs.NET.Bindings
• Native booleans are translated to System.Boolean instead of System.Byte
• Function pointers are translated to unmanaged function pointers instead of System.IntPtr

[BeanCheeseBurrito]

Minimum target version bumped to .NET 9

All projects must now target .NET 9. This upgrade was done to allow support for ref structs as generic type arguments as well as make it possible to implement IEnumerable foreach iterators for queries.

[BeanCheeseBurrito]

World.DeleteEmptyTables has been changed to take aDeleteEmptyTablesDesc parameter.

Old:

ulong id = ...;
ushort clearGeneration = ...;
ushort deleteGeneration = ...;
int minIdCount = ...;
double timeBudgetSeconds = ...;

int deletedCount = world.DeleteEmptyTables(id, clearGeneration, deleteGeneration, minIdCount, timeBudgetSeconds);

New:

int deletedCount = world.DeleteEmptyTables(new DeleteEmptyTablesDesc
{
    ClearGeneration = ...,
    DeleteGeneration = ...,
    TimeBudgetSeconds = ...
});

[BeanCheeseBurrito]

WorldToJsonDesc, EntityToJsonDesc, and IterTojsonDesc has been changed to use property setters/getters.

Old:

EntityToJsonDesc desc = world.EntityToJsonDesc()
    .EntityId()
    .Doc()
    .FullPaths()
    .Values();

string json = entity.ToJson(desc)
// Or
string json = entity.ToJson(ref desc)

New:

The following methods

• Entity.ToJson(ecs_entity_to_json_desc_t*)
• Entity.ToJson(EntityToJsonDesc)
• Entity.ToJson(ref EntityToJsonDesc)

Are now consolidated into a single method, allowing descriptions to be passed in by both value and reference.

• Entity.ToJson(in EntityToJsonDesc)

World.ToJson and Iter.ToJson signatures have also been updated with the above changes.

// Pass desc as value
string json = entity.ToJson(new EntityToJsonDesc
{
    SerializeEntityId =  true,
    SerializeDoc =       true,
    SerializeFullPaths = true,
    SerializeValues =    true,
    ...
});

// Pass desc as reference
EntityToJsonDesc desc = new EntityToJsonDesc
{
    SerializeEntityId =  true,
    SerializeDoc =       true,
    SerializeFullPaths = true,
    SerializeValues =    true,
    ...
}

string json = entity.ToJson(in desc);

[BeanCheeseBurrito]

Flecs.NET.Core.Types has been renamed to Flecs.NET.Core.FlecsType

Old:

Types type = entity.Type();

New:

FlecsType type = entity.Type();