BeanCheeseBurrito / Flecs.NET

A C# wrapper for flecs
MIT License
145 stars 18 forks source link

Implement type-safe query api, upgrade to .NET 8, remove Unity package support #42

Closed BeanCheeseBurrito closed 1 month ago

BeanCheeseBurrito commented 1 month ago

This pull request adds a type-safe query API to prevent common errors when providing incorrect callback signatures.

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 was made because it is a prerequisite to implementing pinned array storage for managed types in the future. The Unity package will no longer be updated. https://github.com/BeanCheeseBurrito/Flecs.NET/issues/21

Typed Queries

When calling world.Query<T1, ...>(), a generic Query<T1, ...> object will be returned instead of a Query. This applies to all iterable query objects such as systems and observers.

Old:

Query query = world.Query<Position, Velocity>();

New:

Query<Position, Velocity> query = world.Query<Position, Velocity>();

The new generic types will help avoid common errors a user could encounter when working with queries. The parameter types in the query callback must match the types in the query's generic type list.

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

Zero-sized structs are not allowed as type arguments for queries.

public record struct Position(int X, int Y);
public struct Tag;

// Invalid and will trigger assert.
Query<Position, Tag> query = world.QueryBuilder<Position, Tag>()
    .Build()

// Correct
Query<Position> query = world.QueryBuilder<Position>()
    .With<Tag>()
    .Build()

Routine renamed to System

Routine and RoutineBuilder have been renamed to System and SystemBuilder to more closely match the C++ API.

System<Position, Velocity> system = world.System<Position, Velocity>()
    .Each((ref Position p, ref Velocity v) =>
    {
        p.X += v.X;
        p.Y += v.Y;
    });

// Systems that contain no type arguments have an underscore at the end to prevent clashing with the System namespace.
System_ system = world.System().Run((Iter it) => { });

Other Breaking Changes