EntityLinkManager

This system will be included in the upcoming version 2.0.0 release. Current 2.0.0-SNAPSHOT also ships with it.

About

An optional system tracking relationships between entities. Components with [fields referencing other entities](../Entity References and Serialization) are automatically registered and tracked; per-field listeners can supplement the system with additional logic.

For release builds, it is recommended to run this with the artemis-odb-plugin (maven), as it optimizes away the reflection-based overhead from reading and writing to entity fields.

Uses/Examples

• Delete component when referenced entity dies
• Change state of old/new entity when referenced entity changes
• Perform clean-up on child entities when link with parent entity expires

Usage

Register EntityLinkManager.class with the World/WorldConfiguration. The EntityLinkManager only exposes two methods:

    /**
     * <p>Injects and associates the listener with the component. This method
     * is only recommended if only a single field references entities, or if all entity
     * fields are of the same type.</p>
     *
     * <p>Each <code>ComponentType::Field</code> pair can only have one {@link LinkListener}</p>
     *
     * @param component component type associated with listener
     * @param listener link listener
     */
    public void register(Class<? extends Component> component, LinkListener listener)

    /**
     * <p>Injects and associates the listener with a specific field for a given
     * component type.</p>
     *
     * <p>Each <code>ComponentType::Field</code> pair can only have one {@link LinkListener}</p>
     *
     * @param component component type associated with listener
     * @param field target field for listener
     * @param listener link listener
     */
    public void register(Class<? extends Component> component, String field, LinkListener listener)

Example: remove component when target dies

Consider our component:

@PooledWeaver
public class InheritScale extends Component {
    @EntityId public int target;
}

Bind an entity to another, using the component.

world.edit(entityId).create(InheritScale.class).target = targetId;

Per default, if the targetId is killed, the targetId value above will be set to -1, alternatively null - if the field is of type Entity. Oftentimes, if the component's only data is a reference to another entity, we probably want to remove it from the entity completely. This can be achieved with a simple LinkListener:

// retrieving the manager
EntityLinkManager elm = world.getSystem(EntityLinkManager.class);
// register the LinkAdapter - LinkAdapter provides stubs for the LinkListener
elm.register(InheritScale.class, new LinkAdapter() {
    // LinkListeners are subject to dependency injection upon registration
    private ComponentMapper<InheritScale> mapper;

    @Override
    public void onTargetDead(int sourceId, int deadTargetId) {
        // target is dead - better remove the component
        mapper.remove(sourceId);
    }
});

world.delete(targetId); // targetId from snippet above
world.process(); // fires onTargetDead

Tuning the system with @LinkPolicy (and LinkSites)