Table of Contents

Class EntityBuilder

Namespace
KeenEyes
Assembly
KeenEyes.Core.dll

Fluent builder for creating entities with components.

public sealed class EntityBuilder : IEntityBuilder<EntityBuilder>, IEntityBuilder
Inheritance
EntityBuilder
Implements
IEntityBuilder<EntityBuilder>
IEntityBuilder
Inherited Members

Remarks

Performance Note: Components are temporarily boxed during entity construction. This incurs one heap allocation per component added via With<T>(T). However, entity creation is typically not a performance-critical path in ECS applications. Once built, components are stored unboxed in archetype arrays for zero-copy access during iteration.

The boxing overhead only affects the entity creation path. Query iteration and system processing (the hot paths in ECS) operate directly on unboxed component data in contiguous archetype storage with zero allocations.

If batch entity creation becomes a bottleneck, consider:

  • Creating entities in larger batches during initialization rather than per-frame
  • Using object pooling for frequently created/destroyed entity types
  • Profiling to confirm entity creation is actually the bottleneck (not queries/systems)

This design trade-off prioritizes API ergonomics and simplicity while maintaining excellent performance where it matters most: query iteration and system execution.

Properties

World

The world this builder creates entities in.

public World World { get; }

Property Value

World

Methods

Build()

Builds the entity and adds it to the world.

public Entity Build()

Returns

Entity

The created entity.

WithBoxed(ComponentInfo, object)

Adds a component to the entity being built using a boxed value.

public EntityBuilder WithBoxed(ComponentInfo info, object value)

Parameters

info ComponentInfo

The component info from the component registry.

value object

The boxed component value.

Returns

EntityBuilder

This builder for method chaining.

Remarks

This method is primarily intended for serialization and deserialization scenarios where the component type is not known at compile time. For normal usage, prefer the generic With<T>(T) method.

The value must be assignable to the component type specified in the info.

Exceptions

ArgumentNullException

Thrown when info or value is null.

WithName(string?)

Sets the name of the entity being built.

public EntityBuilder WithName(string? entityName)

Parameters

entityName string

The name to assign to the entity. Can be null to clear the name.

Returns

EntityBuilder

This builder for method chaining.

Examples

var player = world.Spawn()
    .WithName("Player")
    .With(new Position { X = 0, Y = 0 })
    .Build();

// Later, find the entity by name
var found = world.FindEntity("Player");

Remarks

Entity names are useful for debugging, editor integration, and finding specific entities. Names can be looked up using GetName(Entity).

Names do not need to be unique within a world, but unique names make lookup by name more predictable.

WithParent(Entity)

Sets the parent entity for the entity being built.

public EntityBuilder WithParent(Entity parent)

Parameters

parent Entity

The parent entity. The parent-child relationship will be established after entity creation.

Returns

EntityBuilder

This builder for method chaining.

Examples

var parent = world.Spawn()
    .WithName("Parent")
    .Build();

var child = world.Spawn()
    .WithName("Child")
    .WithParent(parent)
    .Build();

// The child is now parented to the parent entity

Remarks

When the entity is built, SetParent(Entity, Entity) will be called to establish the parent-child relationship. This enables hierarchical entity structures useful for UI, scene graphs, and object ownership.

The parent entity must be alive when Build() is called, otherwise the parent relationship will not be established.

WithTag(string)

Adds a string tag to be applied to the entity when built.

public EntityBuilder WithTag(string tag)

Parameters

tag string

The string tag to add. Cannot be null, empty, or whitespace.

Returns

EntityBuilder

This builder for method chaining.

Examples

var enemy = world.Spawn()
    .With(new Position { X = 0, Y = 0 })
    .WithTag("Enemy")
    .WithTag("Hostile")
    .Build();

// Check tags later
if (world.HasTag(enemy, "Hostile"))
{
    // Handle hostile entity
}

Remarks

String tags provide runtime-flexible tagging that complements type-safe tag components. Use WithTag<T>() for compile-time type-safe tags, or this method for runtime-determined tags from data files, editors, or dynamic content.

Exceptions

ArgumentNullException

Thrown when tag is null.

ArgumentException

Thrown when tag is empty or whitespace.

See Also
AddTag(Entity, string)

WithTag<T>()

Adds a tag component to the entity being built.

public EntityBuilder WithTag<T>() where T : struct, ITagComponent

Returns

EntityBuilder

This builder for method chaining.

Type Parameters

T

The tag component type to add.

Remarks

Tag components are marker types with no data. They are used for filtering entities in queries (e.g., world.Query<Position>().With<EnemyTag>()).

Like With<T>(T), this method temporarily boxes a default struct value during entity construction. For tag components, this is typically a zero-byte struct, making the allocation overhead minimal.

With<T>(T)

Adds a component to the entity being built.

public EntityBuilder With<T>(T component) where T : struct, IComponent

Parameters

component T

The component data to add.

Returns

EntityBuilder

This builder for method chaining.

Type Parameters

T

The component type to add.

Remarks

This method temporarily boxes the struct component during entity construction. The component is unboxed when copied to archetype storage during Build(), where it is stored in contiguous unboxed arrays for efficient iteration.

If called multiple times with the same component type, only the last value is used. This allows overriding component values during builder configuration.

Edit this page