ME.BECS (Bursted Entity Component System)

The KNN library is distributed as a Unity Package. To install it, add the git URL to your project's manifest.json file.

# Add the git URL to your package manifest

To perform a single query for the $k$ nearest neighbours of a specific position using Burst acceleration, use the QueryKNearestJob.

Note: While knnContainer.QueryKNearest exists for basic usage, it is not Burst accelerated. For performance-critical applications, always use the job-based approach.

const int kNeighbours = 10;
float3 queryPosition = float3.zero;
var result = new NativeArray<int>(kNeighbours, Allocator.TempJob);

// Use the job for Burst acceleration
var queryJob = new QueryKNearestJob(knnContainer, queryPosition, result);
queryJob.Schedule().Complete();

// 'result' now contains indices into the original points array

Aspects allow you to group multiple components into a single interface for easier access, often used in queries. Implement IAspect and define properties that expose components using RefRW<T> (Read/Write) or RefRO<T> (Read Only). Use the [QueryWith] attribute to specify which components are required for the aspect's query.

public struct MyAspect : IAspect {
    public Ent ent { get; set; }

    [QueryWith]
    private RefRW<MyComponent1> component1Data;
    private RefRW<MyComponent3> component2Data;
    
    public ref MyComponent1 component1 => ref this.component1Data.Get(this.ent.id);
    public ref MyComponent2 component2 => ref this.component2Data.Get(this.ent.id);
}

// Usage:
var aspect = ent.GetOrCreateAspect<MyAspect>();
aspect.component1.data = 123;

Components in ME.BECS must implement the IComponent interface. They can contain unmanaged data or ObjectReference<T> for persistent UnityEngine.Object references. You can optionally provide a Default static property to initialize components with specific data and use [EditorComment] for documentation in the Components Viewer.

[EditorComment("My component help description")]
[ComponentGroup(typeof(MyComponentGroup))]
public struct Component : IComponent {
    public static Component Default => new Component() { data = 100 };
    public int data;
    public ObjectReference<UnityEngine.Mesh> unityObjectReference;
}

ME.BECS supports efficient world state management for networking, rollbacks, and saving:

• Clone: Creates a completely new world instance from an existing one.
• Copy: Copies the state from a source world into the current world.
• Serialize: Converts the world state into a byte array.
• Deserialize: Creates a new world from a byte array.

// Clone
var newWorld = world.Clone();

// Copy
world.CopyFrom(sourceWorld);

// Serialize
var bytes = world.Serialize();

// Deserialize
var world = World.Create(bytes);

ME.BECS provides specialized job interfaces for high-performance parallel processing of entities and components. You can schedule these from a system using API.Query(world, dependsOn).

• Aspect Parallel Query: Use IJobForAspects<TAspect>.
• Component Parallel Query: Use IJobForComponents<T1, T2, ...>.
• Mixed Parallel Query: Use IJobFor1Aspects2Components<TAspect, T1, T2>.

[BurstCompile]
private struct MyJob : IJobForAspects<MyAspect> {
    public void Execute(in JobInfo jobInfo, in Ent ent, ref MyAspect aspect) {
        // Logic
    }
}

// In a system:
var query = API.Query(world, dependsOn).AsParallel().Schedule<MyJob, MyAspect>(new MyJob());
context.SetDependency(query);

Systems are implemented by defining a struct that implements one of the lifecycle interfaces. You can use [BurstCompile] to optimize the system's lifecycle methods or [WithoutBurst] to exclude specific methods from Burst compilation.

Supported lifecycle interfaces:

• IAwake: OnAwake(ref SystemContext context)
• IStart: OnStart(ref SystemContext context)
• IUpdate: OnUpdate(ref SystemContext context)
• IDestroy: OnDestroy(ref SystemContext context)
• IDrawGizmos: OnDrawGizmos(ref SystemContext context)

[BurstCompile]
public struct TestSystem : IUpdate {
    [WithoutBurst]
    public void OnUpdate(ref SystemContext context) {
        // System logic here
    }
}

To query multiple points simultaneously across multiple threads, use the QueryKNearestBatchJob. This is highly efficient for large datasets.

Requirements:

• A NativeArray<float3> containing all query positions.
• A NativeArray<int> for results, sized as queryPoints.Length * kNeighbours.

const int kNeighbours = 10;
const int queryPoints = 100000;
var results = new NativeArray<int>(queryPoints * kNeighbours, Allocator.TempJob);
var queryPositions = new NativeArray<float3>(queryPoints, Allocator.TempJob);

// ... fill queryPositions ...

var batchQueryJob = new QueryKNearestBatchJob(knnContainer, queryPositions, results);

// Schedule with batch size (e.g., queryPoints / 32)
batchQueryJob.ScheduleBatch(queryPositions.Length, queryPoints / 32).Complete();