EntityFactory

DEPRECATED and removed in 2.0.0

There are many problems with current entity factories:

• entity factory definitions are still verbose
• no default way of attaching logic to entity factory instances (onCreate etc).
• they deal with single entities; in my experience, a conceptual entity that we want to express in entity factories, in fact, span multiple entities. (current project; 38 prefabs, of which only 2 deal with a single entity)
• type-erasure lures behind extended interfaces, requiring the developer to organize their method calls according to interface hierarchy
• no default and automatic way of attaching annotation processors to IDE:s, gradle and maven + interop between IDE+gradle/maven.
• annotation processors have limited introspective capabilities

Summary

Entity factories offer a simple, but efficient method for creating entities with a predefined component composition. Each factory is backed by an Archetype instance, ensuring fast insertion into Entity Systems.

Note: This API is experimental and prone to change in the future.

Using

After enabling the annotation processor, you can use Entity Factories.

The annotation processor will implement your entity factories interfaces automatically. Wire your entity factories, or retrieve them via World#createFactory(Class<EntityFactory>).

Basic Example

import com.artemis.EntityFactory;

// components that make up created entities.
@Bind({Sprite.class, Cullible.class, Position.class,
	Velocity.class, Asset.class, Size.class, HitPoints.class})
public interface Grunt extends EntityFactory<Grunt> {

	// By convention, method name is mapped to class with same name.
	Grunt position(float x, float y);

	// By convention, Parameters are mapped to class fields.
	Grunt velocity(float x, float y);
}

Usage

Make sure Annotation-Processor has been set up.

@Wire
public class ExampleSystem extends VoidEntitySystem {

     private Grunt grunt;

     @Override
     public void initialize() 
     {
        Entity grunt1 = grunt.position(10,10).create();
        Entity grunt2 = grunt.create();
        Entity grunt3 = grunt.position(20,20).velocity(10,10).create();
     }
}

Advanced

Entity Composition

Specifies what components make up the created entity. Matching methods are not required.

@Bind({Sprite.class, Cullible.class, Position.class,
	Velocity.class, Asset.class, Size.class, HitPoints.class})
public interface Grunt extends EntityFactory<Grunt> {

Optional Components

Factories currently do not support optional components. see https://github.com/junkdog/artemis-odb/issues/228

Pervasive properties (@Sticky)

Stickied methods are meant for pervasive component properties that apply for all entities. They can only be called before the first call to EntityFactory#create.

public interface Grunt extends EntityFactory<Grunt> {
	@Sticky Grunt size(float width, float height);
}

To update the sticky methods in an entity factory, create a new instance with EntityFactory#copy().

Exposing component methods on factory (@UseSetter)

public interface Grunt extends EntityFactory<Grunt> {
        @Bind(Asset.class) @UseSetter Grunt path(String uri);
}

Invokes Bind#path(String). Method-level @Bind is required for setter injection.

Custom factory method names

Use @Bind on methods directly to use different method names.

public interface Grunt extends EntityFactory<Grunt> {
	@Bind(HitPoints.class) Grunt hp(int current);
}

Or, to customize setter calls.

public interface Grunt extends EntityFactory<Grunt> {
        @Bind(Asset.class) @UseSetter("setPath") Grunt path(String uri);
}