Global Variables

The Global Variables Source pulls data from an external source and converts it into a Smart String without requiring any additional arguments. When the value of a Global Variable changes, you can configure it to automatically update any LocalizedStrings that currently use it.

Access Global Variables by using dot notation inside a placeholder with the following structure:

{group-name.variable-name}
{group-name.nested-group-name.variable-name}

Global Variables Group

A Global Variables Group is an asset that can contain one or more Global Variables and/or Nested Global Variable Groups. Create a Global Variable Group through the Assets menu: Assets > Create > Localization > Global Variables Group

Each Global Variable has a name which must contain no spaces and be unique to the group. Add new variables to a Global Variable Group by selecting the Add (+) button.

Global Variables Source

To allow Smart Strings to access Global Variables, you must add a Global Variables Source to the Smart Format Sources list.

You can add Global Variable Groups to the list, so long as each group has a unique name with no spaces.

The following example shows a single group with the name global.

Smart String	Result
My Floats value is {global.my-float}	My Floats value is 1.23
{global.my-string} of using global variables.	This is an example of using global variables.
The door is {global.my-bool:Open\|Closed}.	The door is Open.
This is an integer {global.int-variable} as Hex {global.int-variable:X}.	This is an integer 255 as Hex FF.
Values can be nested {global.nested-group.player-name}	Values can be nested Player 1

Triggering Updates

Global Variables can trigger automatic updates to any LocalizedStrings that are currently using it. This means there is no need to keep track of what UI fields need to be updated. If a value changes, the LocalizedStrings automatically update to the new value. To configure a Global Variable to automatically update LocalizedStrings, have the Global Variable implement the IGlobalVariableValueChanged interface. The LocalizedString checks which Global Variables it references, and adds itself to the Value Changed events of those Global Variables. When a value is changed, the Value Changed events run and the LocalizedStrings are automatically refreshed to the new value.

void UpdateValue()
{
    var source = LocalizationSettings.StringDatabase.SmartFormatter.GetSourceExtension<GlobalVariablesSource>();
    var myFloat = source["global"]["my-float"] as FloatGlobalVariable;
    myFloat.Value = 123; // This will trigger an update
}

You can choose to stop the automatic updates of the LocalizedStrings when changing multiple Global Variables by updating within a GlobalVariablesSource Update Scope. Use this to prevent unnecessary updates.

public class RandomPlayerStats : MonoBehaviour
{
    public string[] stats = new[] { "vitality", "endurance", "strength", "dexterity", "intelligence" };

    public void RandomStats()
    {
        var source = LocalizationSettings.StringDatabase.SmartFormatter.GetSourceExtension<GlobalVariablesSource>();
        var nestedGroup = source["global-sample"]["player"] as NestedGlobalVariablesGroup;

        // An UpdateScope or using BeginUpdating and EndUpdating can be used to combine multiple changes into a single Update.
        // This prevents unnecessary string refreshes when updating multiple Global Variables.
        using (GlobalVariablesSource.UpdateScope())
        {
            foreach (var name in stats)
            {
                var variable = nestedGroup.Value[name] as IntGlobalVariable;
                variable.Value = Random.Range(0, 10);
            }
        }
    }
}

Custom Global Variables

A custom Global Variable must be Serializable and implement IGlobalVariable. The following example demonstrates how to use a Global Variable to return the current time.

/// <summary>
/// This is an example of a Global Variable that can return the current time.
/// </summary>
[DisplayName("Current Date Time")]
public class CurrentTime : IGlobalVariable
{
    public object SourceValue => DateTime.Now;
}

The IGlobalVariableValueChanged interface must be implemented in order to trigger updates to any LocalizedString that uses the Global Variable.

[Serializable]
public class MyGlobalVariable : IGlobalVariableValueChanged
{
    [SerializeField]
    string m_Value;

    public string Value
    {
        get => m_Value;
        set
        {
            if (m_Value == value)
                return;

            m_Value = value;
            ValueChanged?.Invoke(this);
        }
    }

    public object SourceValue => Value;

    public event Action<IGlobalVariable> ValueChanged;
}

Custom Global Variable Groups

Use Custom Global Variable Groups to return custom Global Variables. The following example demonstrates this.

struct ReturnValue : IGlobalVariable
{
    public object SourceValue { get; set; }
}

/// <summary>
/// This example shows how a nested group can be used to return custom data without the need for Reflection.
/// </summary>
[DisplayName("Weapon Damage")]
[Serializable]
public class WeaponDamageGroup : IVariableGroup, IGlobalVariable
{
    public object SourceValue => this;

    public bool TryGetValue(string key, out IGlobalVariable value)
    {
        switch (key)
        {
            case "sword":
                value = new ReturnValue { SourceValue = 6 };
                return true;

            case "mace":
                value = new ReturnValue { SourceValue = 5 };
                return true;

            case "axe":
                value = new ReturnValue { SourceValue = 8 };
                return true;

            case "dagger":
                value = new ReturnValue { SourceValue = 2 };
                return true;
        }

        value = null;
        return false;
    }
}