Linked entity groups

A LinkedEntityGroup instance is a Dynamic Buffer that has special semantics:

The first element of an entity's LinkedEntityGroup buffer must always be the entity itself.

Prefabs that the baking process creates always have a LinkedEntityGroup at the root. Instances created from those prefabs also have one.

Working with linked entity groups

LinkedEntityGroup and transform hierarchy are separate concepts. For example, adding children under a parent with a LinkedEntityGroup doesn't automatically add them to the LinkedEntityGroup. Similarly, removing entities from a LinkedEntityGroup doesn't remove them from the parent.

Unity doesn't process LinkedEntityGroup instances recursively. If an entity which is part of a LinkedEntityGroup A has a LinkedEntityGroup B of its own, processing LinkedEntityGroup A doesn't include the contents of LinkedEntityGroup B. To prevent confusion, avoid nesting groups.

Destroying entities

LinkedEntityGroup must only contain valid entities. When entities which are part of a LinkedEntityGroup are individually destroyed, they also have to be explicitly removed from the group.

When destroying entities with a query, either all the entities within a LinkedEntityGroup need to match the query, or that none of them match. Therefore, the contents of a LinkedEntityGroup can't partially match the query.

This is relevant if you use entity scenes, because when Unity unloads an entity scene, it uses the SceneTag shared component value of the entity scene to identify the entities that it needs to destroy. When you add entities to LinkedEntityGroups which are part of a scene, make sure that those entities have the proper SceneTag.

Add an entity to a linked entity group

The following is an example of how to add an entity to a linked entity group in a system:

partial struct SomeSystem:ISystem

{
    public void OnUpdate(ref SystemState state)
    {
        //Get the targeted entity for which you would like to modify the LinkedEntityGroup
        var q = SystemAPI.QueryBuilder().WithAll<SomeComponent>().WithAll<LinkedEntityGroup>().Build().ToEntityArray(Allocator.Temp);

        //Create the child entity and add the SceneTag
        var child = state.EntityManager.CreateEntity();
        var sceneTag = state.EntityManager.GetSharedComponent<SceneTag>(q[0]);
        state.EntityManager.AddSharedComponent<SceneTag>(child, sceneTag);

        //If needed add the new entity as a child in the transform hierarchy 
        state.EntityManager.AddComponentData(child, new Parent { Value = q[0] });

        //Get the LinkedEntityGroup and add the newly created child entity
        var leg = SystemAPI.GetBuffer<LinkedEntityGroup>(q[0]);
        leg.Add(child);

        state.Enabled = false;
    }
}

Additional resources