Supply named variables to a Smart String through groups of serialized assets, without passing arguments.
The Persistent variables source lets you reference named values inside a placeholder instead of passing them as arguments to Smart.Format. Values live in a VariablesGroupAsset, a ScriptableObject that holds named variables. You register one or more groups with the source, each under a unique name, and reach a variable with dot notation:
{group-name.variable-name}
{group-name.nested-group-name.variable-name}
A VariablesGroupAsset contains multiple persistent variables and nested groups. Create one from the Assets menu: Assets > Create > Smart Strings > Variables Group.
Add variables in script with the Add method. Register the source with Smart.Default.AddExtensions(...) or on a specific SmartFormatter.
The source first checks the current value for a matching variable group, then any group registered on the source. The value a variable returns is handled by the remaining sources and formatters, so you can apply formatters such as Choose to it.
The following example shows how to create and use named persistent variables:
var group = ScriptableObject.CreateInstance<VariablesGroupAsset>();
group.Add("my-float", new FloatVariable { Value = 1.23f });
group.Add("my-string", new StringVariable { Value = "This is an example" });
group.Add("my-bool", new BoolVariable { Value = true });
var source = new PersistentVariablesSource();
source.Add("global", group);
var smart = Smart.CreateDefaultSmartFormat();
smart.AddExtensions(source);
// "My float value is 1.23"
smart.Format("My float value is {global.my-float}", null);
Group names and variable names must be unique and must not contain whitespace; any whitespace is replaced with - when a name is added.
| Smart String | Result |
|---|---|
My float value is {global.my-float} |
My float value is 1.23 |
{global.my-string} of using variables. |
This is an example of using 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 |
The following variable types are available by default. Each holds a single value of its type:
| Type | Description |
|---|---|
BoolVariable |
A single bool value. |
SByteVariable, ByteVariable
|
A single signed or unsigned byte value. |
ShortVariable, UShortVariable
|
A single signed or unsigned short value. |
IntVariable, UIntVariable
|
A single signed or unsigned int value. |
LongVariable, ULongVariable
|
A single signed or unsigned long value. |
FloatVariable, DoubleVariable
|
A single float or double value. |
StringVariable |
A single string value. |
ObjectVariable |
A reference to a UnityEngine ObjectThe fundamental object in Unity scenes, which can represent characters, props, scenery, cameras, waypoints, and more. A GameObject’s functionality is defined by the Components attached to it. More info See in Glossary. |
NestedVariablesGroup |
A reference to another VariablesGroupAsset, which allows variables to nest. |
Each variable derives from Variable<T> and raises a ValueChanged event when its Value changes. Variables that implement IVariableValueChanged can drive automatic updates in callers that subscribe to that event. To change several variables and notify once at the end, wrap the changes in an update scope:
using (PersistentVariablesSource.UpdateScope())
{
floatVariable.Value = 2.5f;
stringVariable.Value = "Updated";
}
A custom variable must be [Serializable] and implement IVariable. Return the value from GetSourceValue, which other sources and formatters then process. Implement IVariableValueChanged to support automatic updates.
[Serializable]
public class DateTimeVariable : IVariable
{
public object GetSourceValue(ISelectorInfo selector) => DateTime.Now;
}