direct-entity-manager-structural-changes

Direct EntityManager Structural Changes

Intent

Use EntityManager directly for structural changes outside of any active query iteration — appropriate for one-shot initialisation, infrequent config-driven respawns, and batch operations on the main thread.

Use When

One-shot init systems (state.Enabled = false after first run). Mass respawn triggered by config change. Any structural change that happens once at startup or once on a significant event, not per-frame.

Avoid When

Inside a SystemAPI.Query foreach — iterator is invalidated. Inside a scheduled job — EntityManager is not accessible from jobs. In per-frame simulation hot paths — use ECB for deferred execution.

Senior Pattern

• Disable the system after first run: state.Enabled = false; at the start of OnUpdate (set before any work so even exceptions during work don't leave the system enabled for next frame).
• Use batch overloads exclusively:
  • state.EntityManager.Instantiate(prefab, count, Allocator.Temp) — spawns N entities in one archetype operation.
  • state.EntityManager.AddComponent<T>(query) — adds T to all matching entities in one pass.
  • state.EntityManager.RemoveComponent<T>(query) — removes T from all matching in one pass.
  • state.EntityManager.DestroyEntity(query) — destroys all matching in one pass.
• Use state.EntityManager.AddBuffer<T>(entity) for per-entity buffer initialisation after batch spawn.

Code Template

[BurstCompile]
public partial struct WorldSetupSystem : ISystem
{
    public void OnCreate(ref SystemState state)
        => state.RequireForUpdate<WorldConfig>();

    public void OnUpdate(ref SystemState state)
    {
        state.Enabled = false;  // one-shot — set before work begins

        var config = SystemAPI.GetSingleton<WorldConfig>();

        // Batch spawn — single archetype operation for all N entities
        var enemies = state.EntityManager.Instantiate(
            config.EnemyPrefab, config.EnemyCount, Allocator.Temp);

        // Per-entity init using the spawned array
        for (int i = 0; i < enemies.Length; i++)
        {
            state.EntityManager.SetComponentData(enemies[i],
                LocalTransform.FromPosition(new float3(i * 2f, 0, 0)));
        }

        // Batch tag all spawned enemies
        var enemyQuery = SystemAPI.QueryBuilder()
            .WithAll<EnemyData>().WithNone<EnemyReady>().Build();
        state.EntityManager.AddComponent<EnemyReady>(enemyQuery);
    }
}