structural-change-cost-model

Structural Change Cost Model

Intent

Choose between value mutation, enableable component toggle, and structural add/remove based on change frequency, providing the canonical decision model for ECS state transitions.

Use When

Designing any system that needs to change entity state. This is the architectural decision that most directly affects ECS runtime performance.

Avoid When

There is no "avoid when" — this model applies to every state change decision in ECS.

Senior Pattern (Decision Tree)

1. Value mutation (field on existing component): zero structural change, O(1) write, cheapest. Use when the state is a continuous quantity (health, position, speed) or a discrete enum field.
2. Enableable component (IEnableableComponent toggle): O(1) bit flip per entity, no chunk migration. Use when binary active/inactive state toggles more than once per second per entity.
3. Structural change (AddComponent / RemoveComponent): O(entity) chunk migrations. Use when the state change is infrequent (less than once per second per entity) AND semantic clarity from different archetypes is valuable.

Frequency Rule

• Frequency > 1/sec per entity → value or enableable.
• Frequency 1/sec – 1/minute per entity → enableable preferred, structural acceptable.
• Frequency < 1/minute per entity → structural is fine and semantically clearest.
• When in doubt: measure. The three-mode benchmark below is the definitive reference.

Code Template

// VALUE — continuous state, always cheapest
public struct EnemyState : IComponentData
{
    public float Health;         // mutate directly
    public float Speed;          // mutate directly
    public EnemyBehavior Mode;   // enum field — value mutation
}

// ENABLEABLE — binary toggle, high-frequency
public struct Stunned : IComponentData, IEnableableComponent
{
    public float RemainingDuration;
}
// Toggle: enabledRef.ValueRW = false  (O(1), no chunk move)

// STRUCTURAL — infrequent semantic archetype boundary
public struct Dead : IComponentData { }
// Add: ecb.AddComponent<Dead>(entity)  (once, when entity dies)
// Natural exclusion: all AI/movement queries use .WithNone<Dead>()