transform-usage-flags

TransformUsageFlags

Intent

Declare exactly which transform components an entity needs at bake time, preventing spurious LocalTransform/LocalToWorld components on data-only entities and missing transforms on moving entities.

Use When

Every call to GetEntity() and CreateAdditionalEntity() in a Baker. The flag must match the entity's actual runtime behavior.

Avoid When

There is no "avoid when" — TransformUsageFlags must always be specified explicitly. Never guess; derive the flag from how the entity will be used at runtime.

Senior Pattern

• TransformUsageFlags.None — data-only entities (config, singletons, tags, staging entities). No LocalTransform added.
• TransformUsageFlags.Dynamic — entities that move at runtime. Adds LocalTransform + LocalToWorld.
• TransformUsageFlags.Renderable — entities rendered but not moved by ECS systems (static mesh renderers). Adds LocalToWorld only.
• TransformUsageFlags.ManualOverride — Baker takes full responsibility for adding transform components. Used when batch-adding many components via ComponentTypeSet to minimize archetype migrations.
• For prefab entity references: GetEntity(authoring.PrefabField, TransformUsageFlags.Dynamic).

Code Template

class Baker : Baker<EnemyAuthoring>
{
    public override void Bake(EnemyAuthoring authoring)
    {
        // Moving enemy — needs LocalTransform
        var entity = GetEntity(TransformUsageFlags.Dynamic);
        AddComponent(entity, new EnemyData { Speed = authoring.Speed });

        // Config singleton — no transform needed
        var configEntity = CreateAdditionalEntity(TransformUsageFlags.None);
        AddComponent(configEntity, new EnemyConfig { MaxCount = authoring.MaxCount });

        // Batch add via ManualOverride — single structural change
        var tileEntity = CreateAdditionalEntity(TransformUsageFlags.ManualOverride);
        AddComponent(tileEntity, new ComponentTypeSet(
            ComponentType.ReadWrite<LocalTransform>(),
            ComponentType.ReadWrite<LocalToWorld>(),
            ComponentType.ReadWrite<TileData>()
        ));
        SetComponent(tileEntity, LocalTransform.FromPosition(authoring.TileOffset));
    }
}