Interface IWorld

Namespace

KeenEyes

Assembly

KeenEyes.Abstractions.dll

Interface for ECS world operations used by systems and plugins.

public interface IWorld : IDisposable

Inherited Members

IDisposable.Dispose()

Remarks

This interface defines the core operations that systems need to interact with the ECS world. It enables plugin authors to write systems that depend only on the abstractions package rather than the full Core implementation.

For advanced serialization and introspection capabilities, check if the world implements ISnapshotCapability (for entity component introspection) or ISerializationCapability (for component registry access).

Properties

EntityCount

Gets the total number of entities in the world.

int EntityCount { get; }

Property Value

int

Id

Unique identifier for this world instance.

Guid Id { get; }

Property Value

Guid

Remarks

This identifier is useful for distinguishing between multiple worlds in the same process, such as in client-server scenarios or multi-scene games.

Name

Optional name for this world, useful for debugging and logging.

string? Name { get; set; }

Property Value

string

Remarks

When working with multiple worlds, setting meaningful names like "Client", "Server", or "MainMenu" helps with debugging and tracing issues.

Methods

Add<T>(Entity, in T)

Adds a component to an entity.

void Add<T>(Entity entity, in T component) where T : struct, IComponent

Parameters

entity Entity

The entity to add the component to.

component T

The component value to add.

Type Parameters

T

The component type to add.

Clear()

Clears all entities, components, and singletons from the world.

void Clear()

Remarks

This method removes all entities and their components, as well as all singletons. The world can still be used after clearing - it is reset to an empty state.

Systems and plugins remain installed after clearing. Only entity/component data is removed.

ClearDirtyFlags<T>()

Clears dirty flags for all entities with the specified component type.

void ClearDirtyFlags<T>() where T : struct, IComponent

Type Parameters

T

The component type to clear dirty flags for.

Remarks

Call this after processing dirty entities with GetDirtyEntities<T>() to reset the dirty state for the next frame.

Despawn(Entity)

Despawns an entity, removing it and all its components from the world.

bool Despawn(Entity entity)

Parameters

entity Entity

The entity to despawn.

Returns

bool

True if the entity was despawned; false if it wasn't alive.

DisableAutoTracking<T>()

Disables automatic dirty flag tracking for a component type.

void DisableAutoTracking<T>() where T : struct, IComponent

Type Parameters

T

The component type to stop tracking.

EnableAutoTracking<T>()

Enables automatic dirty flagtracking for a component type.

void EnableAutoTracking<T>() where T : struct, IComponent

Type Parameters

T

The component type to track.

Remarks

When enabled, any modifications to components of this type will automatically mark the entity as dirty. Use GetDirtyEntities<T>() to retrieve entities with modified components and ClearDirtyFlags<T>() to reset the dirty flags after processing.

GetAllEntities()

Gets all entities currently alive in this world.

IEnumerable<Entity> GetAllEntities()

Returns

IEnumerable<Entity>

An enumerable of all alive entities.

GetChildren(Entity)

Gets the immediate children of an entity.

IEnumerable<Entity> GetChildren(Entity entity)

Parameters

entity Entity

The entity to get children of.

Returns

IEnumerable<Entity>

An enumerable of child entities. Returns an empty enumerable if the entity has no children.

GetDirtyEntities<T>()

Gets all entities with dirty (modified) components of the specified type.

IEnumerable<Entity> GetDirtyEntities<T>() where T : struct, IComponent

Returns

IEnumerable<Entity>

An enumerable of entities with modified components.

Type Parameters

T

The component type to check for modifications.

Remarks

Entities are marked dirty when their components are modified after EnableAutoTracking<T>() is called for that component type. Use ClearDirtyFlags<T>() after processing to reset the dirty state.

GetExtension<T>()

Gets an extension registered with the world.

T GetExtension<T>() where T : class

Returns

T

The extension instance.

Type Parameters

T

The extension type.

Exceptions

InvalidOperationException

Thrown when the extension is not registered.

GetName(Entity)

Gets the name of an entity.

string? GetName(Entity entity)

Parameters

entity Entity

The entity to get the name of.

Returns

string

The entity's name, or null if unnamed.

Remarks

Entity names are optional and must be unique within the world. Names can be assigned when spawning via Spawn(string?).

GetParent(Entity)

Gets the parent entity of the specified entity.

Entity GetParent(Entity entity)

Parameters

entity Entity

The entity to get the parent of.

Returns

Entity

The parent entity, or Null if the entity has no parent.

GetSingleton<T>()

Gets a singleton value by reference, allowing direct modification.

ref T GetSingleton<T>() where T : struct

Returns

T

A reference to the singleton data for zero-copy access.

Type Parameters

T

The singleton type to retrieve.

Remarks

This method returns a reference to the boxed singleton value, enabling zero-copy access and direct modification. Changes made through the returned reference are immediately reflected in the stored singleton.

Exceptions

InvalidOperationException

Thrown when no singleton of type T exists.

Get<T>(Entity)

Gets a reference to a component on an entity.

ref T Get<T>(Entity entity) where T : struct, IComponent

Parameters

entity Entity

The entity to get the component from.

Returns

T

A reference to the component data.

Type Parameters

T

The component type.

Exceptions

InvalidOperationException

Thrown when the entity doesn't have the component.

HasExtension<T>()

Checks if an extension of the specified type is registered.

bool HasExtension<T>() where T : class

Returns

bool

True if the extension is registered; false otherwise.

Type Parameters

T

The extension type.

HasMessageSubscribers<T>()

Checks if there are any subscribers for the specified message type.

bool HasMessageSubscribers<T>()

Returns

bool

True if there are subscribers; false otherwise.

Type Parameters

T

The message type.

HasSingleton<T>()

Checks if a singleton of the specified type exists.

bool HasSingleton<T>() where T : struct

Returns

bool

true if the singleton exists; false otherwise.

Type Parameters

T

The singleton type to check for.

Has<T>(Entity)

Checks if an entity has a specific component.

bool Has<T>(Entity entity) where T : struct, IComponent

Parameters

entity Entity

The entity to check.

Returns

bool

True if the entity has the component; false otherwise.

Type Parameters

T

The component type.

IsAlive(Entity)

Checks if an entity is alive (not despawned).

bool IsAlive(Entity entity)

Parameters

entity Entity

The entity to check.

Returns

bool

True if the entity exists and is alive; false otherwise.

NextBool()

Gets a random boolean value.

bool NextBool()

Returns

bool

True or false with equal probability.

NextBool(float)

Returns a random boolean with the specified probability of being true.

bool NextBool(float probability)

Parameters

probability float

The probability (0.0 to 1.0) that the result will be true.

Returns

bool

True with the specified probability, false otherwise.

Exceptions

ArgumentOutOfRangeException

probability is less than 0.0 or greater than 1.0.

NextDouble()

Gets a random double-precision floating-point number between 0.0 (inclusive) and 1.0 (exclusive).

double NextDouble()

Returns

double

A double-precision floating point number greater than or equal to 0.0, and less than 1.0.

NextFloat()

Gets a random floating-point number between 0.0 (inclusive) and 1.0 (exclusive).

float NextFloat()

Returns

float

A single-precision floating point number greater than or equal to 0.0, and less than 1.0.

NextInt(int)

Gets a random integer between 0 (inclusive) and maxValue (exclusive).

int NextInt(int maxValue)

Parameters

maxValue int

The exclusive upper bound of the random number to be generated.

Returns

int

A 32-bit signed integer greater than or equal to 0, and less than maxValue.

Remarks

Uses the world's deterministic random number generator. If the world was created with a seed, this method will produce the same sequence of values across runs.

Exceptions

ArgumentOutOfRangeException

maxValue is less than 0.

NextInt(int, int)

Gets a random integer between minValue (inclusive) and maxValue (exclusive).

int NextInt(int minValue, int maxValue)

Parameters

minValue int

The inclusive lower bound of the random number returned.

maxValue int

The exclusive upper bound of the random number returned.

Returns

int

A 32-bit signed integer greater than or equal to minValue and less than maxValue.

Exceptions

ArgumentOutOfRangeException

minValue is greater than maxValue.

OnComponentAdded<T>(Action<Entity, T>)

Subscribes to component added events.

EventSubscription OnComponentAdded<T>(Action<Entity, T> handler) where T : struct, IComponent

Parameters

handler Action<Entity, T>

The callback to invoke when a component is added.

Returns

EventSubscription

A subscription that can be disposed to unsubscribe.

Type Parameters

T

The component type to monitor.

Remarks

The handler is invoked immediately when a component is added to an entity. The callback receives the entity and the component value.

OnComponentChanged<T>(Action<Entity, T, T>)

Subscribes to component changed events.

EventSubscription OnComponentChanged<T>(Action<Entity, T, T> handler) where T : struct, IComponent

Parameters

handler Action<Entity, T, T>

The callback to invoke when a component is changed via Set().

Returns

EventSubscription

A subscription that can be disposed to unsubscribe.

Type Parameters

T

The component type to monitor.

Remarks

The handler is invoked when a component is changed using Set<T>(Entity, in T). Direct modifications via Get<T>(Entity) do not trigger this event since there is no way to detect reference-based mutations.

The callback receives the entity, the old component value, and the new component value.

OnComponentRemoved<T>(Action<Entity>)

Subscribes to component removed events.

EventSubscription OnComponentRemoved<T>(Action<Entity> handler) where T : struct, IComponent

Parameters

handler Action<Entity>

The callback to invoke when a component is removed.

Returns

EventSubscription

A subscription that can be disposed to unsubscribe.

Type Parameters

T

The component type to monitor.

Remarks

The handler is invoked immediately after a component is removed from an entity. The component data is no longer accessible at this point.

OnEntityCreated(Action<Entity, string?>)

Registers a handler to be called when an entity is created.

EventSubscription OnEntityCreated(Action<Entity, string?> handler)

Parameters

handler Action<Entity, string>

The handler to invoke when an entity is created. Receives the entity and its optional name (null if unnamed).

Returns

EventSubscription

A subscription that can be disposed to unsubscribe.

Remarks

The handler is invoked after the entity is fully constructed with all its initial components.

OnEntityDestroyed(Action<Entity>)

Registers a handler to be called when an entity is destroyed.

EventSubscription OnEntityDestroyed(Action<Entity> handler)

Parameters

handler Action<Entity>

The handler to invoke when an entity is destroyed.

Returns

EventSubscription

A subscription that can be disposed to unsubscribe.

Remarks

The handler is invoked before the entity is removed from the world. The entity and its components are still accessible at this point for cleanup operations.

Query<T1>()

Creates a query for entities with a single component type.

IQueryBuilder Query<T1>() where T1 : struct, IComponent

Returns

IQueryBuilder

A query builder for filtering and enumerating entities.

Type Parameters

T1

The required component type.

Query<T1, T2>()

Creates a query for entities with two component types.

IQueryBuilder Query<T1, T2>() where T1 : struct, IComponent where T2 : struct, IComponent

Returns

IQueryBuilder

A query builder for filtering and enumerating entities.

Type Parameters

T1

The first required component type.

T2

The second required component type.

Query<T1, T2, T3>()

Creates a query for entities with three component types.

IQueryBuilder Query<T1, T2, T3>() where T1 : struct, IComponent where T2 : struct, IComponent where T3 : struct, IComponent

Returns

IQueryBuilder

A query builder for filtering and enumerating entities.

Type Parameters

T1

The first required component type.

T2

The second required component type.

T3

The third required component type.

Query<T1, T2, T3, T4>()

Creates a query for entities with four component types.

IQueryBuilder Query<T1, T2, T3, T4>() where T1 : struct, IComponent where T2 : struct, IComponent where T3 : struct, IComponent where T4 : struct, IComponent

Returns

IQueryBuilder

A query builder for filtering and enumerating entities.

Type Parameters

T1

The first required component type.

T2

The second required component type.

T3

The third required component type.

T4

The fourth required component type.

RemoveSingleton<T>()

Removes a singleton from the world.

bool RemoveSingleton<T>() where T : struct

Returns

bool

true if the singleton was removed; false if it didn't exist.

Type Parameters

T

The singleton type to remove.

Remove<T>(Entity)

Removes a component from an entity.

bool Remove<T>(Entity entity) where T : struct, IComponent

Parameters

entity Entity

The entity to remove the component from.

Returns

bool

True if the component was removed; false if the entity didn't have it.

Type Parameters

T

The component type to remove.

Send<T>(T)

Sends a message to all subscribers immediately.

void Send<T>(T message)

Parameters

message T

The message to send.

Type Parameters

T

The message type.

SetComponent(Entity, Type, object)

Sets or adds a component value on an entity using a boxed value and type.

void SetComponent(Entity entity, Type componentType, object value)

Parameters

entity Entity

The entity to set the component on.

componentType Type

The type of the component.

value object

The boxed component value.

Remarks

This method adds the component if the entity doesn't have it, or updates the existing value if it does. The component type must already be registered.

This is primarily used for network replication where components are deserialized as boxed values. For typed component operations, prefer Add<T>(Entity, in T) and Set<T>(Entity, in T).

SetParent(Entity, Entity)

Sets the parent of an entity, establishing a parent-child relationship.

void SetParent(Entity child, Entity parent)

Parameters

child Entity

The entity to become a child.

parent Entity

The entity to become the parent. Use Null to remove the parent.

Remarks

If the child already has a parent, it is removed from the old parent's children before being added to the new parent.

Circular relationships are detected and will throw InvalidOperationException.

Exceptions

InvalidOperationException

Thrown when the operation would create a circular relationship (parent is a descendant of child).

SetSingleton<T>(in T)

Sets a singleton value in the world, creating it if it doesn't exist.

void SetSingleton<T>(in T value) where T : struct

Parameters

value T

The value to set.

Type Parameters

T

The singleton type to set.

Remarks

Singletons are world-wide values that are not attached to any entity. They are useful for global game state like configuration, time, or shared resources.

Set<T>(Entity, in T)

Sets or replaces a component on an entity.

void Set<T>(Entity entity, in T component) where T : struct, IComponent

Parameters

entity Entity

The entity to set the component on.

component T

The component value to set.

Type Parameters

T

The component type to set.

Remarks

If the entity already has the component, it is replaced and OnComponentChanged<T>(Action<Entity, T, T>) events are fired. If the entity doesn't have the component, it is added and OnComponentAdded<T>(Action<Entity, T>) events are fired.

Spawn()

Creates an entity builder for constructing a new entity.

IEntityBuilder Spawn()

Returns

IEntityBuilder

An entity builder for fluent entity construction.

Spawn(string?)

Creates an entity builder for constructing a new named entity.

IEntityBuilder Spawn(string? name)

Parameters

name string

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

Returns

IEntityBuilder

An entity builder for fluent entity construction.

Subscribe<T>(Action<T>)

Subscribes to messages of the specified type.

EventSubscription Subscribe<T>(Action<T> handler)

Parameters

handler Action<T>

The callback to invoke when a message is received.

Returns

EventSubscription

A subscription that can be disposed to unsubscribe.

Type Parameters

T

The message type to subscribe to.

TryGetExtension<T>(out T)

Tries to get an extension registered with the world.

bool TryGetExtension<T>(out T extension) where T : class

Parameters

extension T

When this method returns, contains the extension if found.

Returns

bool

True if the extension is registered; false otherwise.

Type Parameters

T

The extension type.

TryGetSingleton<T>(out T)

Attempts to get a singleton value.

bool TryGetSingleton<T>(out T value) where T : struct

Parameters

value T

When this method returns true, contains the singleton value. When this method returns false, contains the default value.

Returns

bool

true if the singleton exists; false otherwise.

Type Parameters

T

The singleton type to retrieve.

Remarks

This method returns a copy of the value rather than a reference. Use GetSingleton<T>() when you need zero-copy access.

Update(float)

Updates all registered systems in the world.

void Update(float deltaTime)

Parameters

deltaTime float

The time elapsed since the last update in seconds.

Remarks

This method executes all enabled systems in their configured phases and order. Systems are grouped by SystemPhase and executed in ascending order within each phase.

Call this method from your main loop, typically at 60Hz or tied to your render refresh rate.