com.lhkbob.entreri

Interface Component

All Superinterfaces:

Ownable, Owner

public interface Component
extends Owner, Ownable

Component represents a grouping of reusable and related states that are added to an Entity. An Entity's behavior is defined by the union of all components attached to it, and the system's configured tasks that process the entities. Tasks must be implemented and used in order to take advantage of a particular component configuration.

An entity can be considered as a collection of aspects represented by component instances. An entity can have at most one instance of a component type at a time, although over its lifetime the specific component instance may change.

Logically a component definition is a set of named and typed properties, and a method-based API to get and set the values of each property. Specific types of component are defined by creating a sub-interface of Component. Using the Named, SharedInstance, Factory and custom Attribute annotations defined by Property implementations, the data properties of the component type are specified in the sub-interface. A declaration model similar to the Java Bean model is used and is outlined below:

1. Non-void, zero-argument methods starting with 'get', 'is', and 'has' declare a property. The property type is inspected from the return type of the method. The property name is the method name minus the 'get'/'is'/'has' prefix with its first letter made lower-case. The Named annotation can be used to override the name.
2. Single-argument methods starting with 'set' are assumed to be a setter corresponding to a property. The single parameter's type must equal the type the getter. The Named annotation can be applied to either the setter or the parameter to specify the property name.
3. Multi-argument methods starting with 'set' are assumed to be a setter that assigns values to multiple property, one for each argument. Each argument must be annotated with Named to specify the property, and the argument type must equal the type of the matching property.
4. Setter methods must return void or return the components type, in which case the proxy will return itself to allow for method chaining.
5. Getters with void return types or more than 0 arguments, setters with an invalid return type or no arguments, and any other method not matching the conventions above will cause the system to throw an IllegalComponentDefinitionException.

Internally, the entity system will generate proxy implementations of the component interfaces that implement the property getters and setters but store all of the values in Property instances of a compatible type. This allows iteration over components to have much better cache locality if the component is defined in terms of primitives or types that have specialized Property implementations that can pack and unpack an instance. The SharedInstance annotation can be added to the getter method of a property to specify that the ShareableProperty API should be leveraged by the generated class.

Additional attribute annotations can be added to the getter method to influence the behavior of the PropertyFactory used for each property in the component definition. Besides using the Factory annotation to specify the factory type, a property implementation can be associated with a type with canonical name C by adding the file META-INF/entreri/mapping/C to the classpath, where its contents must be:

     <BINARY NAME OF PROPERTY>
 

where the value is suitable for passing into Class.forName(String).

Attribute annotations provided by the default property implementations are outlined below:

• DefaultBoolean - set value for boolean properties
• DefaultByte - set value for byte properties
• DefaultShort - set value for short properties
• DefaultInt - set value for int properties
• DefaultLong - set value for long properties
• DefaultFloat - set value for float properties
• DefaultDouble - set value for double properties
• DefaultChar - set value for char properties
• Clone - specify clone policy used with entity or component templates

Note that there are no annotations that work with general object types. This is because the scope of that problem is intractable. The default ObjectProperty implementation assumes null values are allowed and that the default value is null.

The generated proxies will implement equals() and hashCode() based on their type and the id of their owning entity. The ComponentIterator class creates flyweight component instances whose identity changes as iteration proceeds; equals() and hashCode() will behave appropriately. This means that flyweight components should not be stored in collections that depend on equality or hashes. Flyweight components are used for performance reasons when iterating over the entities in a system with specific component configurations because the JVM does not need to load each unique component instance into the cache.

Component implements both Ownable and Owner. This can be used to create hierarchies of both components and entities that share a lifetime. When a component is removed from an entity, 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
Entity	getEntity() Get the entity that this component is attached to.
EntitySystem	getEntitySystem()
int	getIndex() Get the underlying index of this component used to access its properties.
Class<? extends Component>	getType() Get the class identifier for this component.
int	getVersion() Get the current version of the data of this component.
boolean	isAlive() Get whether or not the component is still attached to an alive entity in an entity system.
boolean	isFlyweight() Get whether or not this particular instance is a flyweight component object.
void	updateVersion() Increment the version of the component accessed by this instance.

Methods inherited from interface com.lhkbob.entreri.Owner

notifyOwnershipGranted, notifyOwnershipRevoked

Methods inherited from interface com.lhkbob.entreri.Ownable

getOwner, setOwner

Method Detail

getEntitySystem

EntitySystem getEntitySystem()

Returns:

The EntitySystem that created this component

getEntity

Entity getEntity()

Get the entity that this component is attached to. If the component has been removed from the entity, or is otherwise not live, this will return null.

Returns:

The owning entity, or null

isAlive

boolean isAlive()

Get whether or not the component is still attached to an alive entity in an entity system. This will return false if it or its entity has been removed. If the component is a flyweight object used in iteration, it can also return false when iteration has terminated.

Using property getters or setters on a dead component produces undefined behavior.

Returns:

True if the component is still attached to an entity in the entity system, or false if it or its entity has been removed

isFlyweight

boolean isFlyweight()

Get whether or not this particular instance is a flyweight component object. A flyweight instance is used by ComponentIterators to efficiently view the underlying component data iteratively. It is safe to set the owner of a flyweight component or to set the flyweight as an owner of another object. It will correctly register the canonical component as the owner.

Components returned by Entity.add(Class), Entity.get(Class), and its other component returning functions will always return non-flyweight components. These components are the 'canonical' instances for that component type and entity.

Returns:

True if this component is a flyweight instance iterating over a list of components

getIndex

int getIndex()

Get the underlying index of this component used to access its properties. For most uses, you should not need to use this method. As an EntitySystem manages and compacts the component data storage, a component's index can change. The index should be used to access decorated properties, which will be kept in-sync with any compactions.

Additionally, some component instances may be flyweight objects used for iteration. In this case, every iteration will update its index and the component object's identity will change as well. See ComponentIterator for more information.

Returns:

The current index of component

getVersion

int getVersion()

Get the current version of the data of this component. When a component's data is mutated, implementations increment its version so comparing a previously cached version number can be used to determine when changes have been made.

Within a component type for an entity system, version values will be unique across component instances. Thus, entity.as(T.class).getVersion() != cachedVersion will correctly detect changes to the original component instance as well as the removal and replacement by a new component of type T.

Returns:

The current version, or a negative number if the data is invalid

updateVersion

void updateVersion()

Increment the version of the component accessed by this instance. This will be automatically called by all exposed setters by the generated proxies, but if necessary it can be invoked manually as well.

See Also:

getVersion()

getType

Class<? extends Component> getType()

Get the class identifier for this component. This will be the specific sub-interface of Component that this object is an instance of. getType() should be used instead of Object.getClass() because that will return a specific and most likely generated proxy implementation of the component type.

Returns:

The component type