com.lhkbob.entreri

Interface EntitySystem

All Superinterfaces:

Iterable<Entity>

public interface EntitySystem
extends Iterable<Entity>

EntitySystem is the main container for the entities within a logical system such as a game or physics world. It contains all entities needed for processing the scene or data. Entities are created with addEntity() or addEntity(Entity). They can be removed (and effectively destroyed) with removeEntity(Entity).

After an Entity is created, Components can be added to it to store domain-specific data and configure its behaviors. The specifics of the data and behavior depends on the Component implementations and Tasks used to process your data.

The Scheduler of an EntitySystem can be used to create Jobs composed of Tasks that will process the entities within an entity system in an organized fashion. Generally, the processing of all controllers through their different phases constitutes a complete "frame".

When Entities are created by an EntitySystem, the created instance is assigned an ID which represents its true identity.

Use EntitySystem.Factory.create() to get a new instance of an EntitySystem.

Author:

Michael Ludwig

See Also:

Entity, Component

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	EntitySystem.Factory

Method Summary

Methods

Modifier and Type	Method and Description
Entity	addEntity() Add a new Entity to this EntitySystem.
Entity	addEntity(Entity template) Add a new Entity to this EntitySystem.
void	compact() Compact the entity and component data so that iteration is more efficient.
<T extends Component,P extends Property> P	decorate(Class<T> type, PropertyFactory<P> factory) Dynamically update the available properties of the given Component type by adding a Property created by the given PropertyFactory.
ComponentIterator	fastIterator() Return a new ComponentIterator that must be configured with required and optional components before use.
Collection<Class<? extends Component>>	getComponentTypes() Get all Component interfaces currently used by the EntitySystem.
<T extends Component> Collection<Class<? extends T>>	getComponentTypes(Class<T> type) Get all Component types within this EntitySystem that have types assignable to the input type.
Scheduler	getScheduler() Return the Scheduler for this EntitySystem that can be used to organize processing of the system using Task implementations.
Iterator<Entity>	iterator() Return an iterator over all of the entities within the system.
<T extends Component> Iterator<T>	iterator(Class<T> type) Return an iterator over all components of with the given type.
void	removeEntity(Entity e) Remove the given entity from this system.

Method Detail

getComponentTypes

<T extends Component> Collection<Class<? extends T>> getComponentTypes(Class<T> type)

Get all Component types within this EntitySystem that have types assignable to the input type.

Parameters:

type - The query type

Returns:

All Component interfaces that have components in this EntitySystem that are subclasses of the input component data type

Throws:

NullPointerException - if type is null

getComponentTypes

Collection<Class<? extends Component>> getComponentTypes()

Get all Component interfaces currently used by the EntitySystem. If a type has had all of its components removed, it will still be returned here.

Returns:

All TypeIds at one point used by this system

getScheduler

Scheduler getScheduler()

Return the Scheduler for this EntitySystem that can be used to organize processing of the system using Task implementations.

Returns:

The Scheduler for this system

iterator

Iterator<Entity> iterator()

Return an iterator over all of the entities within the system. The returned iterator's remove() method will remove the entity from the system with behavior identical to calling removeEntity(Entity).

Specified by:

iterator in interface Iterable<Entity>

Returns:

An iterator over the entities of the system

iterator

<T extends Component> Iterator<T> iterator(Class<T> type)

Return an iterator over all components of with the given type. The returned iterator uses a single flyweight Component instance of T, so it is a fast iterator. This effectively wraps a ComponentIterator in a standard Iterator with a single required component type.

Parameters:

type - The type of component to iterate over

Returns:

A fast iterator over components in this system

fastIterator

ComponentIterator fastIterator()

Return a new ComponentIterator that must be configured with required and optional components before use.

Returns:

A new iterator over the components in this system

compact

void compact()

Compact the entity and component data so that iteration is more efficient. In the life time of an entity system, entities and components are added and removed, possibly causing the list of components for a given type to be in a different order than the list of entities. This is due to implementation details needed to make additions and removals constant time.

Invoking compact() after a large number of additions or removals to the system is a good idea. Alternatively, invoking it every few frames in a game works as well. An entity system that has no additions or removals of entities (or their components) gains no benefit from compacting, except potentially freeing excess memory.

Compacting is not overly fast or slow, so it should not cause noticeably drops in frame rate. As an example, on a test system with 20,000 entities compact() took ~2ms on an Intel i5 processor. Of course, mileage may very.

addEntity

Entity addEntity()

Add a new Entity to this EntitySystem. The created Entity will not have any attached Components. You can create a new entity from a template by calling addEntity(Entity).

Returns:

A new Entity in the system, without any components

addEntity

Entity addEntity(Entity template)

Add a new Entity to this EntitySystem. If template is not null, the components attached to the template will have their state cloned onto the new entity. The semantics of cloning is defined by PropertyFactory.clone(com.lhkbob.entreri.property.Property, int, com.lhkbob.entreri.property.Property, int), but by default it follows Java's reference/value rule.

Specifying a null template makes this behave identically to addEntity().

Parameters:

template - The template to clone

Returns:

A new Entity in the system with the same component state as the template

Throws:

IllegalStateException - if the template is not a live entity

removeEntity

void removeEntity(Entity e)

Remove the given entity from this system. The entity and its attached components are removed from the system. This will cause the entity and its components to no longer be alive. Any ComponentData's referencing the entity's components will become invalid until assigned to a new component.

When an entity is removed, it will set its owner to null, and disown all of its owned objects. If any of those owned objects are entities or components, they are removed from the system as well.

Parameters:

e - The entity to remove

Throws:

NullPointerException - if e is null

IllegalArgumentException - if the entity was not created by this system, or already removed

decorate

<T extends Component,P extends Property> P decorate(Class<T> type,
                                                  PropertyFactory<P> factory)

Dynamically update the available properties of the given Component type by adding a Property created by the given PropertyFactory. The property will be managed by the system as if it was a declared property of the component type.

All components, current and new, will initially have their starting values for the decorated property be the default as defined by the factory. The returned property can be accessed and used by Tasks to add dynamic runtime data to statically defined component types.

Type Parameters:

P - The created property type

Parameters:

type - The component type to mutate

factory - The property factory that creates the decorating property

Returns:

The property that has decorated the given component type

Throws:

NullPointerException - if type or factory are null