Documentation

Unity Engine

User Manual

Script Reference

Unity Engine

Persistent variables source

Supply named variables to a Smart String through groups of serialized assets, without passing arguments.
Read time 3 minutesLast updated 6 days ago
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}

Variables group asset

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

Variable types

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 Object.
NestedVariablesGroup
A reference to another 
VariablesGroupAsset
, which allows variables to nest.

Triggering updates

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";            }

Custom variables

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;    }

Additional resources