Persistent Variables - MOARdV/AvionicsSystems GitHub Wiki

Background

Persistent variables are a key element of custom and complex IVA designs. Based on RasterPropMonitor experience, there are several use patterns with persistent variables:

Toggle Variable

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).

Numeric Variable

In JSINumericInput, the persistent variable is manipulated by adding or subtracting a value (with the option for automatic repeating).

Avionics Systems Implementation

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).

This section lists several the important persistent variable functions. Refer to the Persistent Vars category in the documentation for a complete listing of functions.

  • fc.AddPersistent(persistentName, amount): Adds amount to the named persistent value. Returns the new sum. If the persistent doesn't exist, it is initialized to amount.

  • fc.AddPersistentClamped(persistentName, amount, minValue, maxValue): 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.

  • fc.AddPersistentWrapped(persistentName, amount, minValue, maxValue): 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.

  • fc.AppendPersistent(persistentName, addon, maxLength): 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.

  • fc.GetPersistent(persistentName): 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.

  • fc.GetPersistentAsNumber(persistentName): 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.

  • fc.SetPersistent(persistentName, value): Sets the named persistent to the value specified. The persistent is created if it did not already exist. Returns the new value. value may be a number or a string.

  • fc.InitializePersistent(persistentName, value): If the persistent does not already exist, create it and set it to the value specified in value. If the persistent already exists, this function does not affect it.

  • fc.TogglePersistent(persistentName): 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.

Global Variables

The Global Persistent Variables from RPM is not implemented. A future update will provide a per-vessel persistent storage system.