com.lhkbob.entreri

Interface Entity

All Superinterfaces:

Comparable<Entity>, Iterable<Component>, Ownable, Owner

public interface Entity
extends Iterable<Component>, Comparable<Entity>, Ownable, Owner

An Entity represents a collection of Components within an EntitySystem. Entities are created by calling EntitySystem.addEntity() or the similar function that takes another Entity as a template.

Once created the Entity object will not change its identity. There are no flyweight entities, unlike components which do use that design pattern.

Entity implements both Ownable and Owner. This can be used to create hierarchies of both components and entities that share a lifetime. When an entity is removed from the system, all of its owned objects are disowned. If any of them were entities or components, they are also removed from the system.

Author:

Michael Ludwig

Method Summary

Methods

Modifier and Type	Method and Description
<T extends Component> T	add(Class<T> componentType) Add a new Component with a data type T to this Entity.
<T extends Component> T	add(T toClone) Add a new Component with a of type T to this Entity, but the new component's state will be cloned from the given Component instance.
<T extends Component> T	as(Class<T> type) Get the canonical component instance of type T on this Entity.
<T extends Component> T	get(Class<T> componentType) Get the Component instance of the given type that's attached to this Entity.
EntitySystem	getEntitySystem()
int	getId()
boolean	has(Class<? extends Component> type) Check whether or not the a component of the given type is attached to this entity.
boolean	isAlive()
Iterator<Component>	iterator() Return an iterator over the components currently attached to the Entity.
boolean	remove(Class<? extends Component> componentType) Remove any attached Component with the data type from this Entity.

Methods inherited from interface java.lang.Comparable

compareTo

Methods inherited from interface com.lhkbob.entreri.Ownable

getOwner, setOwner

Methods inherited from interface com.lhkbob.entreri.Owner

notifyOwnershipGranted, notifyOwnershipRevoked

Method Detail

getId

int getId()

Returns:

The unique (in the scope of the entity system) id of this entity

getEntitySystem

EntitySystem getEntitySystem()

Returns:

The owning EntitySystem of this entity

isAlive

boolean isAlive()

Returns:

True if this Entity is still in its EntitySystem, or false if it has been removed

get

<T extends Component> T get(Class<T> componentType)

Get the Component instance of the given type that's attached to this Entity. A null value is returned if the component type has not been attached to the entity.

Type Parameters:

T - The parameterized type of ComponentData of the component

Parameters:

componentType - The given type

Returns:

The current Component of type T attached to this entity

Throws:

NullPointerException - if componentType is null

add

<T extends Component> T add(Class<T> componentType)

Add a new Component with a data type T to this Entity. If there already exists a component of type T, it is removed first, and a new one is instantiated.

Type Parameters:

T - The parameterized type of component being added

Parameters:

componentType - The component type

Returns:

A new component of type T

Throws:

NullPointerException - if componentId is null

add

<T extends Component> T add(T toClone)

Add a new Component with a of type T to this Entity, but the new component's state will be cloned from the given Component instance. The toClone instance must still be live. If there already exists a component of type T, it is removed first, and a new one is instantiated.

The new component is initialized by cloning the property values from toClone into the values of the new component.

Type Parameters:

T - The parameterized type of component to add

Parameters:

toClone - The existing T to clone when attaching to this component

Returns:

A new component of type T

Throws:

NullPointerException - if toClone is null

IllegalStateException - if toClone is not a live component instance

as

<T extends Component> T as(Class<T> type)

Get the canonical component instance of type T on this Entity. Unlike get(Class), this will add the component if it is not present. Thus, this is a convenience for getting the component, and adding it if the get returned null.

Type Parameters:

T - The parameterized type of component

Parameters:

type - The class interface of the component to add

Returns:

The component of type T, potentially new if it wasn't already on the entity

has

boolean has(Class<? extends Component> type)

Check whether or not the a component of the given type is attached to this entity. This is a convenience for getting the component and then checking if it's null.

Parameters:

type - The component type to check for

Returns:

True if the entity currently has the attached type, in which case get() will return a non-null alive component

remove

boolean remove(Class<? extends Component> componentType)

Remove any attached Component with the data type from this Entity. True is returned if a component was removed, and false otherwise. If a component is removed, the component should no longer be used and it will return false from Component.isAlive().

When a Component 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:

componentType - The component type

Returns:

True if a component was removed

Throws:

NullPointerException - if componentId is null

iterator

Iterator<Component> iterator()

Return an iterator over the components currently attached to the Entity. The iterator supports the remove operation and will detach the component from the entity just like a call to remove(Class).

Components reported by the iterator are not flyweight.

Specified by:

iterator in interface Iterable<Component>

Returns:

An iterator over the entity's components