Skip to content

Latest commit

 

History

History
210 lines (172 loc) · 9.49 KB

README.md

File metadata and controls

210 lines (172 loc) · 9.49 KB
Raw

Flecs.NET

Flecs.NET is a high-level wrapper for flecs. Low-level bindings to the C api are included and generated with Bindgen.NET. Native libraries are cross-compiled with Vezel-Dev's Zig Toolsets.

Show me the code!

// Copy, paste, and run in a .NET project!

using Flecs.NET.Core;

using World ecs = World.Create();

Entity entity = ecs.Entity()
    .Set(new Position(10, 20))
    .Set(new Velocity(1, 2));

ecs.Each((ref Position p, ref Velocity v) =>
{
    p.X += v.X;
    p.Y += v.Y;
});

public record struct Position(float X, float Y);
public record struct Velocity(float X, float Y);

Overview

Flecs.NET - High-level C# port of the C++ wrapper

  • Modern .NET 8
  • Near feature parity with the C++ API
  • Struct-based API with minimal GC interaction
  • Supports both unmanaged and managed types as components
  • Implicitly registers components on-the-fly

Flecs.NET.Bindings - Low-level bindings of the C API

  • Build your own wrapper to suite your personal needs
  • Auto-generated bindings for the entire flecs API
  • Fully blittable interface with no runtime marshalling

Flecs.NET.Native - Precompiled native libraries

  • Provides both shared and static libraries for Windows, MacOS, Linux, iOS, and WASM
  • Packaged with Zig for dependency free cross-compilation everywhere

NuGet

You can download the nuget package and use Flecs.NET right away!

Flecs.NET (Wrapper + Bindings + Native Libraries): Release | Debug

dotnet add PROJECT package Flecs.NET.Release --version *-*

Flecs.NET.Bindings (Bindings + Native Libraries): Release | Debug

dotnet add PROJECT package Flecs.NET.Bindings.Release --version *-*

Flecs.NET.Native (Native Libraries): Release | Debug

dotnet add PROJECT package Flecs.NET.Native.Release --version *-*

Flecs.NET provides both release and debug packages for nuget. It is recommended that the debug packages be used when developing as they include checks for incorrect usage of the API. To include both of them in your project based on your build configuration, use the package references below. The latest stable or prerelease versions will be added to your project.

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net8.0</TargetFramework>
    </PropertyGroup>

    <ItemGroup>
        <PackageReference Include="Flecs.NET.Debug" Version="*-*" Condition="'$(Configuration)' == 'Debug'" />
        <PackageReference Include="Flecs.NET.Release" Version="*-*" Condition="'$(Configuration)' == 'Release'" />
    </ItemGroup>
</Project>

Static Linking

Flecs.NET provides precompiled static libraries that can be used when PublishAOT is enabled. To enable static linking, add <FlecsStaticLink>true</FlecsStaticLink> to a property group. To prevent shared libraries from being copied to the output directory, add ExcludeAssets="native" to your package reference.

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <PublishAot>true</PublishAot>
        <FlecsStaticLink>true</FlecsStaticLink>
    </PropertyGroup>

    <ItemGroup>
        <PackageReference Include="Flecs.NET.Debug" Version="*-*" ExcludeAssets="native"/>
    </ItemGroup>
</Project>

GitHub Package Registry

For more up-to-date packages, development builds are available on the GitHub package registry. Packages are automatically uploaded on every commit to the main branch.

To access development builds from your project, you first need to create a GitHub personal access token with the read:packages permission. (See Creating a personal access token (classic))

Once you have created a personal access token, run the following command to add the GitHub feed as a new package source. Replace YOUR_GITHUB_USERNAME with your GitHub username and YOUR_GITHUB_TOKEN with your personal access token.

dotnet nuget add source --name "flecs.net" --username "YOUR_GITHUB_USERNAME" --password "YOUR_GITHUB_TOKEN" --store-password-in-clear-text "https://nuget.pkg.github.com/BeanCheeseBurrito/index.json"

You can now reference any package from the GitHub feed!

dotnet add PROJECT package Flecs.NET.Release --version *-build.*
<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net8.0</TargetFramework>
    </PropertyGroup>

    <ItemGroup>
        <PackageReference Include="Flecs.NET.Debug" Version="*-build.*"/>
    </ItemGroup>
</Project>

By default, the GitHub feed will be added to your global nuget.config file and can be referenced by any project on your machine. If wish to add the feed to a single project/solution, create a nuget.config file at the root of your project/solution directory and run the following command with the --configfile option.

dotnet nuget add source --configfile "./nuget.config" --name "flecs.net" --username "YOUR_GITHUB_USERNAME" --password "YOUR_GITHUB_TOKEN" --store-password-in-clear-text "https://nuget.pkg.github.com/BeanCheeseBurrito/index.json"

To remove the GitHub feed from your NuGet package sources, run the following command.

dotnet nuget remove source "flecs.net"

GitHub Actions workflows can be authenticated using the GITHUB_TOKEN secret.

- name: Add GitHub source
  run: dotnet nuget add source --name "flecs.net" --username "USERNAME" --password "${{ secrets.GITHUB_TOKEN }}" --store-password-in-clear-text "https://nuget.pkg.github.com/BeanCheeseBurrito/index.json"

Warning

Development feed packages may be deleted without warning to free up space.

Running examples

To run any of the example programs, use dotnet runand set the "Example" property to the example's path relative to the Flecs.NET.Examples project. Each level of the path must be separated by an underscore.

Example:

dotnet run --project src/Flecs.NET.Examples --property:Example=Entities_Basics

Building from source

Clone the repo

Clone the repo and it's submodules.

git clone --recursive https://github.com/BeanCheeseBurrito/Flecs.NET.git
cd Flecs.NET

Restore dependencies

Run the following command on the solution to restore all project dependencies.

dotnet restore

Build Flecs.NET

Compile the wrapper and native libraries. The zig compiler will automatically be downloaded and cached in your local nuget package folder. Native libraries will be cross-compiled for linux, macos, and windows.

dotnet build

Reference the project

Reference the project and import the native libraries. You should now be able to use Flecs.NET from your project.

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net8.0</TargetFramework>
    </PropertyGroup>

    <ItemGroup>
        <ProjectReference Include="PATH/Flecs.NET/src/Flecs.NET/Flecs.NET.csproj" />
    </ItemGroup>
</Project>

Running the bindings generator

Low-level bindings to the flecs C API are pre-generated and included in the Flecs.NET.Bindings project by default. If needed, you can run the following command to regenerate the bindings file.

dotnet run --project src/Flecs.NET.Bindgen

Running the code generator

Flecs.NET relies on code generation to avoid manual code duplication. If any changes are made to the Flecs.NET.Codegen project, you can run the following command to rerun the code generators. The generated files will be output to this folder.

dotnet run --project src/Flecs.NET.Codegen

Contributing

Feel free to open an issue or pull request. All contributions are welcome!

Ways to contribute:

  • Bug Fixes/Reports
  • Feature Requests
  • Documentation
  • Examples/Snippets
  • Demos
  • Typo Corrections