NetworkVariable.CheckDirtyState() doesn't sync latest changes if already dirty

[spaceapplesoft]

Description

Updating collection in a NetworkVariable and then calling CheckDirtyState() doesn't sync latest changes if it's already dirty.

Reproduce Steps

On host (didn't test actual clients)

1. Update collection
2. Call CheckDirtyState()
3. Update collection again
4. CheckDirtyState()

Actual Outcome

On client, NetworkVariable .OnValueChanged is called, but collection has only the first change

Expected Outcome

On client, NetworkVariable .OnValueChanged is called and collection has the latest changes

Environment

• OS: Windows 11
• Unity Version: 6000.0.25f1
• Netcode Version: 2.2.0

Additional Context

I had a stats system, which was represented by a simple Dictionary<int, int>.
When I equip an item, it modifies the stats and calls the CheckDirtyState - client gets notified with new value and everything's good.
But if I immediately add another item, which modifies stats some more, and call CheckDirtyState - new value does not get sent unless I do the forceCheck.

Documentation states that CheckDirtyState exits early if it's already dirty. While doing so, it doesn't take the latest changes. I guess the reason for this early exit can be interpreted in two ways:

1. If something is dirty, there's no need to check if it's dirty again. Then, at the end of the frame or whenever serialization runs - actual changes would be calculated and synced with the client.
2. A way to optimize calling this multiple times

If intended reasoning is 1 - then there's a bug, if 2 - forceCheck should default to true, and "false" becomes logically unnecessary. I could elaborate on that.

Here's an example to test this behaviour:

using System;
using System.Collections;
using System.Collections.Generic;
using Unity.Netcode;
using UnityEngine;

public class TestBehaviour: NetworkBehaviour
{
	public NetworkVariable<Dictionary<int,int>> _stats = new NetworkVariable<Dictionary<int, int>>(new Dictionary<int, int>());

	private void Awake()
	{
	}

	public override void OnNetworkSpawn()
	{
		base.OnNetworkSpawn();

		if (IsClient)
		{
			_stats.OnValueChanged += OnValuesChanged;
		}

		if (IsServer)
		{
			StartCoroutine(TriggerChanges());
		}
	}

	private IEnumerator TriggerChanges()
	{
		yield return new WaitForSeconds(1f);

		_stats.Value[0] = 1;

		_stats.CheckDirtyState();

		_stats.Value[0] = 2;

		_stats.CheckDirtyState(); // If I add true to this, everything works as expected
	}

	private void OnValuesChanged(Dictionary<int, int> previousValue, Dictionary<int, int> newValue)
	{
		Debug.Log($"Values changed on client: {(_stats.Value.ContainsKey(0) ? _stats.Value[0].ToString() : "N/A")}");
	}
}

In this example, only this is printed:
Values changed on client: 1

[NoelStephensUnity]

@spaceapplesoft
This is actually working as expected.

Because we allow nested collections forcing a full check each time once something is dirty would be a performance hit when you have the option of doing something like this:

	private IEnumerator TriggerChanges()
	{
		yield return new WaitForSeconds(1f);
                // Make your changes to (n) items
		_stats.Value[0] = 1;
		_stats.Value[0] = 2;
                // Check for dirty state
		_stats.CheckDirtyState();
	}

Or if you have code somewhere else that is invoked at potentially different intervals or different events could cause the change:

	private IEnumerator TriggerChangesFirst()
	{
		yield return new WaitForSeconds(0.5f);
                // Make your changes
		_stats.Value[0] = 1;
                // Check for dirty state
		_stats.CheckDirtyState(_stats.IsDirty());
	}

	private IEnumerator TriggerChangesSecond()
	{
		yield return new WaitForSeconds(1.5f);
                // Make your changes to (n) items
		_stats.Value[0] = 2;
                // Check for dirty state
		_stats.CheckDirtyState(_stats.IsDirty());
	}

Where you might or might not have changes...if it is dirty then force check and if not then allow it to do the more optimized check.

The forcecheck parameter is specifically for handling the scenario where you might apply changes to the same item or perhaps a nested collection item of the same item.

[spaceapplesoft]

@NoelStephensUnity Thanks for taking time to respond.

I guess what I find a bit difficult to understand is why forceCheck doesn't default to true, or in other words, why would I use CheckDirtyState(false) if there's CheckDirtyState(true)?

Let's say I make some sequential changes, like this:

_stats.Value[0] = 1;
_stats.Value[0] = 2;
// Check for dirty state
_stats.CheckDirtyState();

Is it any different than this?

_stats.Value[0] = 1;
_stats.Value[0] = 2;
// Check for dirty state
_stats.CheckDirtyState(true);

If I make changes which are not sequential, seems like CheckDirtyState(false) is not even an option, because it introduces a bug (doesn't broadcast the change).

To try and rephrase it a bit more clearly, if for sequential changes CheckDirtyState(true) and CheckDirtyState(false) act the same, and in non sequential changes CheckDirtyState(false) is not an option, why is the forceCheck given as an option?

EDIT: Sorry, I accidentally closed this issue while writing this comment

[NoelStephensUnity]

You are right and that was a typo on my side.

This:

_stats.Value[0] = 1;
_stats.Value[0] = 2;
_stats.CheckDirtyState();

Is effectively the same as this:

_stats.Value[0] = 1;
_stats.Value[0] = 2;
// Check for dirty state
_stats.CheckDirtyState(true);

If you don't have any other places making changes to the collection.

Really you can do this if you are not concerned about getting local notifications each time it changes:

_stats.Value[0] = 1;
// Check for dirty state
_stats.CheckDirtyState();
_stats.Value[0] = 2;

And it will still synchronize clients =but= will not invoke OnValueChanged on the client/server side with write permissions the second time you make a change. The only purpose behind the forceCheck once you know something is already dirty is to get a local notification which could be for scenarios where the authority (write permissions) instance registers for OnValueChanged and has script that will make other changes based on what changed within the collection.

As an example:

using System;
using System.Collections.Generic;
using Unity.Netcode;
using UnityEngine;

public class NetworkVariableCollection : NetworkBehaviour
{
    public bool UpdateList = true;

    [Tooltip("When enabled, it will check dirty state at the end of changes, otherwise it will check dirty after the 1st change.")]
    public bool CheckDirtyAtEnd = false;

    [Tooltip("How fequently the NetworkVariable will be updated.")]
    [Range(0.1f, 5.0f)]
    public float UpdateTime = 1.0f;

    [HideInInspector]
    public NetworkVariable<Dictionary<int, int>> _stats = new NetworkVariable<Dictionary<int, int>>(new Dictionary<int, int>());

    private float m_LastUpdate;

    protected override void OnNetworkPostSpawn()
    {
        // When client-server the server has write permissions.
        // When distributed authority the session owner client has write permissions.
        if (HasAuthority)
        {
            // Reset our timer
            m_LastUpdate = Time.realtimeSinceStartup;
        }
        _stats.OnValueChanged += OnStatsValueChanged;

        base.OnNetworkPostSpawn();
    }

    private void OnStatsValueChanged(Dictionary<int,int> previous, Dictionary<int,int> current)
    {
        Debug.Log($"Count: {current[0]}");
    }

    public override void OnNetworkDespawn()
    {
        // When client-server the server has write permissions.
        // When distributed authority the session owner client has write permissions.
        if (HasAuthority)
        {
            // Clear out the dictionary if despawning or shutting down
            _stats.Value.Clear();
        }
        base.OnNetworkDespawn();
    }

    private int m_count;

    private void UpdateCount()
    {
        m_count++;
        _stats.Value[0] = m_count;
        if (!CheckDirtyAtEnd)
        {
            _stats.CheckDirtyState();
        }

        m_count++;
        _stats.Value[0] = m_count;

        if (CheckDirtyAtEnd)
        {
            _stats.CheckDirtyState();
        }
    }

    private void Update()
    {
        if (!IsSpawned || !HasAuthority || !UpdateList)
        {
            return;
        }
        // Check to see if we can apply the next update
        if (m_LastUpdate < Time.realtimeSinceStartup)
        {
            UpdateCount();
            m_LastUpdate = Time.realtimeSinceStartup + UpdateTime;
        }
    }
}

This produces the following output (host on left and client on right) when CheckDirtyAtEnd is false:

Where the host is only notified of the change the first time and then not notified the second time.
When CheckDirtyAtEnd is true you see this:

Where the host is being notified of the final change... you could have two CheckDirtyState calls where the 2nd one passes in true and it would effectively be the same as CheckDirtyAtEnd = true with the added expense of having to run through the collection and compare all items.

It might seem trivial, but if you have a complicated collection with nested collections like:
NetworkVariable<Dictionary<int, Dictionary<int, List<ulong>>>
And there were many network prefab instances with that kind of NetworkVariable collection type... it could become expensive.

Apologies for the error in my response as the intention was to say just invoke CheckDirtyState once when you are done modifying the collection.

[spaceapplesoft]

@NoelStephensUnity Thanks a lot for this extensive example and for your time responding.

I think I now understand the need for forceCheck = false.

I've been thinking about this from the narrow perspective of being a host, where I'd always want to listed to changes on host as I'm also one of the players. From the perspective of a standalone server, it makes no sense to have forceCheck = true. With these both cases, it makes sense that forceCheck is optional.

I'n my code, I'll probably end up doing something similar to CheckDirtyState(isHost).

Thanks again for getting back to me,