Attaching Entities

Attachables provides a mechanism for attaching entities to other entities, allowing them to follow the movement of their "owner" entity. This system is particularly useful for creating lightweight relationships between entities or for implementing attachment points for equipment, effects and more.

Key Features

• Supports attachment in both local and world space
• Automatically updates attached entities' Movable
• Efficient handling of multiple attachments

Intended Use

Basic Attachment

To attach one entity to another, add an Attachable component to the entity you want to attach:

var attachedEntity = EntityManager.CreateEntity(typeof(LocalTransform), typeof(LocalToWorld), typeof(Movable), typeof(Attachable));
EntityManager.SetComponentData(attachedEntity, Attachable.WithOwner(ownerEntity));

The AttachableSystem will automatically update the attached entity's position to match its owner.

World Space Attachment

For attachments that need to maintain their world space position relative to the owner, use world space mode:

EntityManager.SetComponentData(attachedEntity, Attachable.WithOwner(ownerEntity, worldSpace: true));

Detaching Entities

To detach an entity, simply set its Attachable.Owner to Entity.Null:

var attachable = EntityManager.GetComponentData<Attachable>(attachedEntity);
attachable.Owner = Entity.Null;
EntityManager.SetComponentData(attachedEntity, attachable);

Temporary Disabling Attachment

You can temporarily disable the attachment behavior by disabling the Attachable component:

EntityManager.SetComponentEnabled<Attachable>(attachedEntity, false);

Threshold Attachable

There is a case where we need the attached entity only if over a certain threshold distance to the owner entity. To solve this case we introduced ThresholdAttachable to supplement Attachable that can be used to set the threshold distance to determine if the entity is attached or not.

EntityManager.AddComponentData(attachedEntity, new ThresholdAttachable() {
   Distance = thresholdDistance
});

Best Practices

1. Use local space attachment when possible for better performance.
2. Be mindful of long chains of attached entities, as updates to these unroll over multiple frames.
3. Use world space attachment only when necessary, such as for objects that need to maintain a specific world position relative to their owner.

Integration with Movables

The AttachableSystem works in tandem with Movables. Attached entities should have both Attachable and Movable components. The AttachableSystem updates the Movable component's target position, which is then processed by the MovableSystem.