Companion components

This feature allows you to query MonoBehaviour components in ECS systems by attaching them to entities, without converting them to IComponentData. The link between an entity and its hosted component is stored as CompanionComponent<T> — an unmanaged IComponentData wrapping a UnityObjectRef<T> — so ECS queries can filter on it like any other unmanaged component. Dereferencing the wrapper to reach the underlying UnityEngine.Component goes through managed code, so the per-entity work that touches the component itself does not get the fast performance that pure ECS components have.

Supported components

The following graphics related companion components are supported by Entities Graphics:

  • Light
  • ReflectionProbe
  • TextMesh
  • SpriteRenderer
  • ParticleSystem
  • VisualEffect
  • DecalProjector (HDRP)
  • LocalVolumetricFog (HDRP)
  • PlanarReflectionProbe (HDRP)
  • Volume
  • Volume + Sphere/Box/Capsule/MeshCollider pair (local volumes)
  • Adaptive Probe Volume (Unity 6 and onwards)

If a MonoBehaviour component is attached to a GameObject and that component is not part of the list above, then that component will be stripped from the GameObject by the Companion components system and will no longer exist after conversion. Also note that the transform hierarchy a GameObject is part of will not be maintained by the Companion components system. All converted components are recreated as root GameObjects.

Note that the conversion of Camera (+HDAdditionalCameraData, UniversalAdditionalCameraData) components is disabled by default, because the scene main camera can't be a companion component entity. To enable this conversion, add HYBRID_ENTITIES_CAMERA_CONVERSION define to your project settings.

Companion component entities

Unity updates the transform of a companion component entity whenever it updates the LocalToWorld component. Parenting a companion component entity to a standard entity is supported. Companion component entities can be included in subscenes. The managed component is serialized in the subscene.

Query companion components

You can write ECS queries on CompanionComponent<T> like any other IComponentData. The query iteration itself is Burst-friendly, but reading the wrapped UnityEngine.Component is a managed call that must run on the main thread, so the system that does the dereference cannot be Burst-compiled and should iterate with foreach() rather than scheduling an IJobEntity.

An example of setting HDRP Light component intensity:

class AnimateHDRPIntensitySystem : SystemBase
{
    protected override void OnUpdate()
    {
        foreach (var companion in SystemAPI.Query<RefRO<CompanionComponent<HDAdditionalLightData>>>())
        {
            HDAdditionalLightData hdLight = companion.ValueRO.CompanionRef;
            hdLight.intensity = 1.5f;
        }
    }
}

The implicit conversion from UnityObjectRef<T> to T resolves the reference back to the live UnityEngine.Component instance. As an alternative, EntityManager.GetCompanion<T>(entity) returns the same instance given the entity.

Additional resources