Class CommandBuffer

Namespace

KeenEyes

Assembly

KeenEyes.Abstractions.dll

Supports all classes in the .NET class hierarchy and provides low-level services to derived classes. This is the ultimate base class of all .NET classes; it is the root of the type hierarchy.

public sealed class CommandBuffer : ICommandBuffer

Inheritance

object

CommandBuffer

Implements

ICommandBuffer

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Properties

Count

Gets the number of commands currently queued in the buffer.

public int Count { get; }

Property Value

int

Methods

AddComponent<T>(Entity, T)

Queues a command to add a component to an existing entity.

public void AddComponent<T>(Entity entity, T component) where T : struct, IComponent

Parameters

entity Entity

The entity to add the component to.

component T

The component value.

Type Parameters

T

The component type to add.

Examples

// Add a power-up component to entities that collected a power-up
buffer.AddComponent(entity, new PowerUp { Type = PowerUpType.Speed, Duration = 10f });

Remarks

The component is not added until Flush(IWorld) is called. If the entity is not alive or already has the component at flush time, the behavior matches Add<T>(Entity, in T).

AddComponent<T>(int, T)

Queues a command to add a component to an entity referenced by placeholder ID.

public void AddComponent<T>(int placeholderId, T component) where T : struct, IComponent

Parameters

placeholderId int

The placeholder ID from a previous Spawn call.

component T

The component value.

Type Parameters

T

The component type to add.

Clear()

Clears all queued commands without executing them.

public void Clear()

Remarks

Use this to abandon queued commands. The buffer can be reused after clearing.

Despawn(Entity)

Queues a command to despawn an existing entity.

public void Despawn(Entity entity)

Parameters

entity Entity

The entity to despawn.

Examples

foreach (var entity in world.Query<Health>())
{
    ref var health = ref world.Get<Health>(entity);
    if (health.Current <= 0)
    {
        buffer.Despawn(entity);
    }
}

Remarks

The entity is not destroyed until Flush(IWorld) is called. If the entity is not alive at flush time, the command is silently ignored.

Despawn(int)

Queues a command to despawn an entity referenced by placeholder ID.

public void Despawn(int placeholderId)

Parameters

placeholderId int

The placeholder ID from a previous Spawn call.

Remarks

This allows despawning entities that were spawned in the same command buffer before Flush(IWorld) is called.

Flush(IWorld)

Executes all queued commands on the specified world and clears the buffer.

public Dictionary<int, Entity> Flush(IWorld world)

Parameters

world IWorld

The world to execute commands on.

Returns

Dictionary<int, Entity>

A dictionary mapping placeholder entity IDs to the real entities created. This allows callers to track which entities were spawned.

Examples

var cmd1 = buffer.Spawn().With(new Position { X = 0, Y = 0 });
var cmd2 = buffer.Spawn().With(new Position { X = 10, Y = 10 });

var entityMap = buffer.Flush(world);

var entity1 = entityMap[cmd1.PlaceholderId];  // Get the real entity
var entity2 = entityMap[cmd2.PlaceholderId];

Remarks

Commands are executed in the order they were queued. Spawn commands are processed first in sequence, creating the placeholder-to-entity mapping that subsequent commands can use.

After execution, the buffer is cleared and ready for reuse.

Exception Handling: If a command throws an exception, subsequent commands are not executed. The buffer is still cleared to prevent duplicate execution.

RemoveComponent<T>(Entity)

Queues a command to remove a component from an existing entity.

public void RemoveComponent<T>(Entity entity) where T : struct, IComponent

Parameters

entity Entity

The entity to remove the component from.

Type Parameters

T

The component type to remove.

Examples

// Remove frozen status from entities that thaw
buffer.RemoveComponent<FrozenTag>(entity);

Remarks

The component is not removed until Flush(IWorld) is called. If the entity is not alive or does not have the component at flush time, the command is silently ignored (matches Remove<T>(Entity) behavior).

RemoveComponent<T>(int)

Queues a command to remove a component from an entity referenced by placeholder ID.

public void RemoveComponent<T>(int placeholderId) where T : struct, IComponent

Parameters

placeholderId int

The placeholder ID from a previous Spawn call.

Type Parameters

T

The component type to remove.

SetComponent<T>(Entity, T)

Queues a command to set (replace) a component value on an existing entity.

public void SetComponent<T>(Entity entity, T component) where T : struct, IComponent

Parameters

entity Entity

The entity to set the component on.

component T

The new component value.

Type Parameters

T

The component type to set.

Examples

// Update position after calculating new location
buffer.SetComponent(entity, new Position { X = newX, Y = newY });

Remarks

The component is not updated until Flush(IWorld) is called. If the entity is not alive or does not have the component at flush time, the behavior matches Set<T>(Entity, in T). Use AddComponent<T>(Entity, T) to add a new component.

SetComponent<T>(int, T)

Queues a command to set (replace) a component value on an entity referenced by placeholder ID.

public void SetComponent<T>(int placeholderId, T component) where T : struct, IComponent

Parameters

placeholderId int

The placeholder ID from a previous Spawn call.

component T

The new component value.

Type Parameters

T

The component type to set.

Spawn()

Queues a spawn command and returns a fluent builder for adding components.

public EntityCommands Spawn()

Returns

EntityCommands

An EntityCommands builder for configuring the new entity.

Examples

var entityCmd = buffer.Spawn()
    .With(new Position { X = 0, Y = 0 })
    .With(new Velocity { X = 1, Y = 0 });

// Use placeholder to add more components later
buffer.AddComponent(entityCmd.PlaceholderId, new Health { Current = 100, Max = 100 });

Remarks

The entity is not created until Flush(IWorld) is called. Use the returned builder to add components to the entity.

Each call to Spawn generates a unique placeholder ID (negative value) that can be used to reference the entity in subsequent commands.

Spawn(string?)

Queues a spawn command with an optional name and returns a fluent builder for adding components.

public EntityCommands Spawn(string? name)

Parameters

name string

The optional name for the entity. If provided, must be unique within the world at flush time.

Returns

EntityCommands

An EntityCommands builder for configuring the new entity.

Examples

var playerCmd = buffer.Spawn("Player")
    .With(new Position { X = 0, Y = 0 })
    .With(new Health { Current = 100, Max = 100 });

buffer.Flush(world);

// Later, retrieve by name
var player = world.GetEntityByName("Player");

Remarks

Named entities can be retrieved later using world.GetEntityByName(). This is useful for debugging, editor tooling, and scenarios where entities need human-readable identifiers.

The entity is not created until Flush(IWorld) is called. If the name is already in use at flush time, an exception will be thrown.