wave7-system-api-managed-api-query

SystemAPI.ManagedAPI — Managed Component Query

Intent

Query managed IComponentData and UnityEngine components from ECS systems using the correct non-Burst API surface (SystemAPI.ManagedAPI or SystemAPI.Query for managed types).

Use When

• A system needs to read or write managed components (class IComponentData or MonoBehaviour attachments) per-entity
• Singleton managed component access is needed via ManagedAPI.GetSingleton

Avoid When

• The system is [BurstCompile] — managed API access is illegal inside Burst; compile error
• High-frequency per-entity access at large entity counts — managed queries are main-thread only bottleneck

Senior Pattern

// Non-Burst SystemBase in PresentationSystemGroup:
[UpdateInGroup(typeof(PresentationSystemGroup))]
public partial class HybridSyncSystem : SystemBase
{
    protected override void OnUpdate()
    {
        // Query managed + blittable components together:
        foreach (var (animator, transform) in
            SystemAPI.Query<Animator, RefRO<LocalToWorld>>())
        {
            animator.transform.SetPositionAndRotation(
                transform.ValueRO.Position,
                transform.ValueRO.Rotation);
        }
    }
}

// ManagedAPI for explicit managed singleton access:
var config = SystemAPI.ManagedAPI.GetSingleton<GameConfigManaged>();
int maxEnemies = config.Asset.MaxEnemies;

// ManagedAPI per-entity query:
foreach (var go in SystemAPI.ManagedAPI.Query<UnityEngine.GameObject>())
{
    go.SetActive(true);
}

// Mixing managed class component with blittable struct component in one query:
foreach (var (spriteData, health) in
    SystemAPI.Query<ManagedSpriteData, RefRO<Health>>())
{
    if (health.ValueRO.Current <= 0)
        spriteData.Sprite = deadSprite;
}

Anti-Patterns

• Calling SystemAPI.Query() inside [BurstCompile] — compile error.
• Mixing managed and unmanaged component access in the same Burst job — not possible; fails at compile.
• Using Entities.ForEach with managed components — deprecated; use SystemBase with SystemAPI.Query.
• Calling SystemAPI.ManagedAPI inside ISystem (struct system) — ManagedAPI requires SystemBase context or main-thread ISystem; ensure system is not Burst-compiled.