-
Notifications
You must be signed in to change notification settings - Fork 29
Persistent Variables
User-defined variables are a key element of custom and complex IVA designs. Based on RasterPropMonitor experience, there are several use patterns with persistent variables:
For basic switches, a simple on/off persistent is used to maintain state
from session to session. In RPM, the default was to use the name
switch%PROPID%_%MODULEID%. A user-supplied name may also be used
for cases where the persistent value is used by multiple props in the
vessel (such as console backlights). For all of these uses, the counter is only a
0 or 1 value, and all it needs is a toggle method (that is, if it's currently
0, make it 1; if it's currently 1, make it 0).
In JSINumericInput, the persistent variable is manipulated by adding or subtracting a value (with the option for automatic repeating).
For performance and implementation reasons, most persistent variables were per-pod, meaning that duplicate variables in different pods had different values. Some values could be forced to global, but user control of it was awkward.
A persistent variable in MAS can be one of two types: a number or a string. MAS will convert from one to the other when needed (such as AddPersistent or GetPersistentAsNumber, below).
Adds amount to the named persistent value. Returns the new sum. If the
persistent doesn't exist, it is initialized to 0, and then amount is added.
Adds amount to the named persistent value and clamps it to the range
[minValue, maxValue]. Returns the new clamped sum. If the
persistent doesn't exist, it is initialized to 0, and then amount is added and clamped.
Adds amount to the named persistent value. If the new value exceeds
the bounds [minValue, maxValue), it wraps around.
Returns the new value. If the
persistent doesn't exist, it is initialized to 0, amount is added, and then it is wrapped.
Example:
fc.AddPersistentWrapped("AutopilotHeading", 1, 0, 360)
Each time this method is called, 1 is added to the persistent
named "AutopilotHeading". When "AutopilotHeading" equals 360, it
resets to 0. If the 1 parameter was -1 instead, this method
would subtract 1 from "AutopilotHeading". When the value became
-1, it would be set to 359, instead.
This method can be used to add characters to the end of a string
persistent variable. One obvious application of this capability
is to implement a numeric keypad. addon can be any string literal,
such as "2" or "Kerbin".
maxLength specifies the maximum length
of the resulting string. Any characters appended to the end of
the string beyond maxLength are discarded.
If the named persistent is not a string, it is converted to a string
before addon is appended. If the persistent did not already exist,
it is created and initialized to addon.
Returns the current value of the persistent. If it doesn't exist, the persistentName is returned, instead. This method will return a string if the named persistent variable was a string, or it will return a number if the named persistent was a number.
Returns the current value of the persistent as a number. If the persistent
is a string that can be converted to a number, such as "15.4", it is
converted to a number. If it is a string, and it can not be converted,
or if the named persistent does not exist, this method returns 0. For
use in MASComponent nodes that use numeric variables, this method should always be
used instead of fc.GetPersistent() since it safely returns a number, even
if the persistent variable does not exist yet.
Sets the named persistent to the value specified. Created if it doesn't exist. Returns the new value. The value may be a number or a string.
Toggles the named persistent between 0 and 1. If the persistent doesn't exist, it is created and set to 1. If the persistent is a string, it is converted to a number (if possible) and then toggled; if it can not be toggled, the name is returned. Returns the new value.
The persistent variable manipulation methods are incomplete. There will be additional string manipulation methods in the future - at the very least, a way to delete characters from the beginning or end of a string.
The Global Persistent Variables from RPM at not implemented. Due to the difficulty in implementing a satisfactory way to handle merging and splitting databases between parts and the vessel (especially during dock / undock), this feature may not be added to MAS.