wave7-add-component-object-hybrid-attach

AddComponentObject — Hybrid Managed Object Attachment

Intent

Attach a managed Unity object (MonoBehaviour, ScriptableObject, or any UnityEngine.Object subclass) to an ECS entity at runtime or bake time for hybrid access.

Use When

• A system needs to read or write a MonoBehaviour component that lives on a companion GameObject linked to an entity
• Animator, AudioSource, or other UnityEngine.Object must be driven per-entity from an ECS system

Avoid When

• The data can be baked into a blittable IComponentData — prefer baking over runtime hybrid attachment
• The attachment changes frequently at high entity counts — GC thrash

Senior Pattern

// Bake-time attachment (preferred — avoids runtime sync point):
public class HybridAuthoring : MonoBehaviour
{
    public Animator Animator;
}

public class HybridBaker : Baker<HybridAuthoring>
{
    public override void Bake(HybridAuthoring authoring)
    {
        var entity = GetEntity(TransformUsageFlags.Dynamic);
        AddComponentObject(entity, authoring.Animator);  // UnityEngine.Object subclass
    }
}

// Read in non-Burst system (main thread only):
[UpdateInGroup(typeof(PresentationSystemGroup))]
public partial class AnimationDriveSystem : SystemBase
{
    protected override void OnUpdate()
    {
        foreach (var animator in SystemAPI.Query<Animator>())
        {
            animator.SetTrigger("Attack");
        }
    }
}

// Runtime attachment (main thread only, triggers sync point):
entityManager.AddComponentObject(entity, someAnimator);

Anti-Patterns

• Calling AddComponentObject at runtime inside a job — not allowed; main thread only.
• Querying managed components inside [BurstCompile] systems — compile error.
• Using AddComponentObject for data that changes every frame at high entity counts — GC thrash; use a blittable mirror component instead.
• Forgetting DependsOn() in Baker when the attached object references other assets — incremental baking may miss changes.

Runtime Risks

• Main-thread-only access; if the managed object is destroyed (GO destroyed externally), the reference becomes a missing reference exception — add null guard in the consuming system.
• Runtime AddComponentObject triggers a structural change sync point — batch all attachments in InitializationSystemGroup.