wave7-companion-go-lifecycle

Companion GO Lifecycle — Marker/Spawn/Sync/Destroy

Intent

Manage the full creation, synchronization, and destruction lifecycle of a companion GameObject paired with an ECS entity using the four-phase marker/spawn/sync/destroy pattern.

Use When

• An entity needs a companion GO for VFX, audio, or UI that cannot be rendered by Entities Graphics
• Companion GO must be created and destroyed in sync with ECS entity lifecycle

Avoid When

• Pure ECS rendering via Entities Graphics is sufficient — companion GOs add main-thread cost and GC pressure
• The companion GO count is very high (>500) — main-thread instantiation and sync become bottlenecks

Senior Pattern

// Marker component (baked or added at runtime):
public struct CompanionGoNeeded : IComponentData { }

// Reference component (added after spawn):
public struct CompanionGoRef : IComponentData
{
    public UnityObjectRef<GameObject> Go;
}

// PHASE 1 — SPAWN: create GO when marker present, ref absent:
[UpdateInGroup(typeof(InitializationSystemGroup))]
public partial class CompanionGoSpawnSystem : SystemBase
{
    protected override void OnUpdate()
    {
        var ecb = new EntityCommandBuffer(Allocator.Temp);

        foreach (var (_, entity) in
            SystemAPI.Query<RefRO<CompanionGoNeeded>>()
                     .WithNone<CompanionGoRef>()
                     .WithEntityAccess())
        {
            var go = new GameObject("Companion_" + entity.Index);
            ecb.AddComponent(entity, new CompanionGoRef { Go = go });
            ecb.RemoveComponent<CompanionGoNeeded>(entity);
        }

        ecb.Playback(EntityManager);
        ecb.Dispose();
    }
}

// PHASE 2 — SYNC: update GO transform every frame (PresentationSystemGroup):
// See wave7-ecs-to-go-transform-sync.md

// PHASE 3 — DESTROY: clean up GO when ref present but entity marked for removal:
[UpdateInGroup(typeof(InitializationSystemGroup))]
public partial class CompanionGoDestroySystem : SystemBase
{
    protected override void OnUpdate()
    {
        var ecb = new EntityCommandBuffer(Allocator.Temp);

        // ICleanupComponentData pattern — entity destroyed but CompanionGoRef remains:
        foreach (var (goRef, entity) in
            SystemAPI.Query<RefRO<CompanionGoRef>>()
                     .WithNone<CompanionGoNeeded>()
                     .WithEntityAccess())
        {
            var go = goRef.ValueRO.Go.Value;
            if (go != null)
                UnityEngine.Object.Destroy(go);

            ecb.RemoveComponent<CompanionGoRef>(entity);
        }

        ecb.Playback(EntityManager);
        ecb.Dispose();
    }
}