Dirty flag pattern

This tutorial explains the dirty flag programming pattern and how you can use it in your Unity projects. Make sure to download the Level up your code with design patterns and SOLID sample project from the Unity Asset Store to follow along with the examples in this tutorial.

Sometimes game development starts to get complicated – or at least computationally expensive. The dirty flag pattern can help when you have a lot of calculations or updates happening in your scenes.

A dirty flag pattern is simply a boolean that indicates whether an object's state has changed since the last time it was processed or rendered. If an object is "dirty," it gets updated; otherwise, it's skipped, saving computational resources.

A common use case is traversing a complex hierarchy or managing a large scene file. The dirty flag can help minimize calculations until certain objects are marked "dirty.” For example, child GameObject transforms could ignore updates until the parent GameObject or root transform requires one. This can help minimize unnecessary calculations with dynamic objects that frequently change state.

Using the dirty flag pattern means strategically placing checks at points where GameObject states are likely to change. This might be within event handlers, physics updates, or animation systems. The checks then ensure that only a subset of the game world is updated in response to player actions or game events. Every resource saved helps reduce overhead.

Consider a large, open-world game. It’s often resource-prohibitive to load the entire game environment at once. Instead, a common tactic is to load just a portion of the game world that the player currently sees.

To manage this, the game world can be divided into smaller Unity scenes, loading each one as necessary. However, this scene loading process is relatively slow and can cause brief pauses that disrupt gameplay.

Thus, we only want to update the game world when necessary. In this example, we introduce a mechanism that only executes when certain conditions are met. We mark the world with a dirty flag when it’s ready for an update. Otherwise, the update loop skips over the expensive logic.

As the player navigates through the level, this game world only updates when the player character moves near the boundary of the current sector. This saves compute resources to help ensure a seamless gameplay experience.

Explore the sample implementation to see one way to apply this pattern:

• The game world is divided into sectors or regions, each with associated content that needs to load when the player is nearby.
• A manager script tracks the player's movement and determines which sectors are relevant based on the player's current location.
• Each sector has a dirty flag that indicates whether its content needs to be loaded or unloaded, based on the player's proximity and interaction.

Because scene loading is a relatively expensive operation, the dirty flag pattern makes sure that the expensive game world update only runs when necessary. Here, the GameSectors script manages what parts of the game world loads at runtime.

public class GameSectors: MonoBehaviour
{
    public Player player;
    public Sector[] sectors;

    private void Update()
    {
        foreach (Sector sector in sectors)
        {
            bool isPlayerClose = sector.IsPlayerClose(player.transform.position);
            
            // Check if the sector's state needs to change
            If (isPlayerClose != sector.IsLoaded)
            {
                sector.MarkDirty();
            }

            // Update the sector based on its dirty flag
            if(sector.IsDirty)
            {
                If (isPlayerClose)
                {
                    sector.LoadContent();
                }
                else
                {
                    sector.UnloadContent();
                }

                // Reset the dirty flag
                sector.Clean(); 
            }
        }
    }
}

The sample scene illustrates how to visualize material changes and scene loading/unloading in response to the player’s proximity. By using the dirty flag pattern, content loading and unloading operations are only performed when the player character moves close enough to or far enough from a sector.

This minimizes unnecessary processing and memory usage as the application shows a limited section of the game world at a time.

Each Sector in this example maintains its own distance to the player as the threshold to load or unload assets. Here’s a snippet of sample:

public class Sector : MonoBehaviour
    {

        [Tooltip("Minimum distance to load")] 
        public float m_LoadRadius;
        ...

        public bool IsLoaded { get; private set; } = false;
        public bool IsDirty { get; private set; } = false;
        
        void Awake()
        {

            ...
            Clean();
            IsLoaded = false;
        }

        public void MarkDirty()
        {
            IsDirty = true;
            Debug.Log($"Sector {gameObject.name} is marked dirty");
            ...
        }

        public void LoadContent()
        {
            IsLoaded = true;
            ...
            // Logic to load scene content from the project
        }

        public void UnloadContent()
        {
            IsLoaded = false;
            ...
            // Logic to unload scene content 
        }

        public bool IsPlayerClose(Vector3 playerPosition)
        {
            return Vector3.Distance(playerPosition, transform.position + m_CenterOffset) <= m_LoadRadius;
        }

        public void Clean()
        {
            IsDirty = false;
        }
        ...

In this setup, a SceneLoader component selectively loads and unloads parts of the game as the player moves through the level.

The camera in the scene provides a top-down view to illustrate how this system works. In a real application, imagine a camera following the player character, showing only a limited field of view. In this scenario, the game could then selectively load and display only those areas immediately within the player's visibility.

Though we can further optimize this (and not use an Update function at all), this example shows a simple case of using a dirty flag to reduce the expensive calls to the SceneManagement API.

The dirty flag pattern is particularly valuable in large simulations or systems generating procedural content. Because costly operations only execute when needed, it minimizes unnecessary calculations and can boost memory efficiency – vital for platforms with limited memory like mobile devices.

On the negative side, be aware that the dirty flag pattern can introduce tight coupling between components. This adds a layer of dependency and risk. Also, since updates are postponed until the dirty flag is set, the application's state might temporarily lag, appearing outdated until the necessary update occurs.

Use the dirty flag pattern whenever you want to minimize the impact of an expensive calculation or operation, such as in the following cases.

• Complex hierarchical transforms. If you have child transforms of an animated character, minimize animations until the parent transform updates (for example, only update the lower limbs if the upper limbs or body is moving). If you had a strategy game where the units are in formation, have the units update their motions only after the entire group formation is marked dirty.
• Physics simulations: For physics simulations involving complex interactions or large numbers of objects, recalculate only when the state of the GameObjects changes (like position, velocity, or external forces) in order to optimize performance.
• Pathfinding: Recalculating paths for AI agents can be expensive. Using dirty flags to update paths only when obstacles move or the target location changes.
• Procedural Content Generation: Much like the scene-loading example, this pattern can tell the system when to regenerate procedural terrain based on specific triggers like player movement or game events.
• UI Layouts: In a complex UI system, elements might need to rearrange themselves when certain conditions change (like window resizing, content updates, etc.). The dirty flag pattern can be used to update the layout only when necessary, avoiding constant recalculations. For example, a VisualElement in UI Toolkit includes a MarkDirtyRepaint method. Likewise, the EditorUtility has ClearDirty and SetDirty methods.

If you want to learn more about design programming patterns and how you can use them in your Unity projects, make sure to read the updated guide Level up your code with design patterns and SOLID and follow along with the Level up your code with design patterns and SOLID sample project on the Unity Asset Store.

Additionally, watch the Game Programming Patterns Tutorials video tutorials playlist where you can see a lot of these programming patterns in action:

• Command pattern video tutorial
• Factory pattern video tutorial
• Model-view-presenter video tutorial
• Pattern combo video tutorial
• Object pooling video tutorial

You can find all advanced Unity technical e-books and articles on the best practices hub. The e-books are also available on the Advanced best practices page in the documentation.