Custom Variables

Because different IVA developers have different needs for their warning indicators and data displays, RasterPropMonitor allows the creation of custom variables. One category of custom variable is called a Custom Variable. These variables report Boolean values (true or false) based on one or more defined variables. The other type of custom variable is a Mapped Variable. A Mapped Variable takes a source variable and range, and it converts it to a destination variable and range. This allows an IVA maker to control displacements of variables on a text display based on any source variable.

##Creating a Custom Variable A custom variable is defined in a CFG file. This file may be placed anywhere in the KSP GameData directory structure, and it may be placed in a file that has prop configurations or other part configs. This allows the IVA designer to place the custom variable definition in the same file as the props that use it. However, they can also be placed anywhere else that is convenient. The only requirement is that they must be in a .cfg file, so KSP will add it to the game database.

A custom variable consists of a name, an operator, and one or more source variables. The source variables consist of a variable name and a range. These values are all defined below, after the example.

RPM_CUSTOM_VARIABLE
{
  name = GROUND_PROXIMITY_ALERT
  operator = AND
  SOURCE_VARIABLE
  {
    name = RADARALT
    range = -10, 100
  }
  SOURCE_VARIABLE
  {
    name = VERTSPEED
    range = -10000, -4
  }
}

###RPM_CUSTOM_VARIABLE The RPM_CUSTOM_VARIABLE node defines a custom variable. It tells RasterPropMonitor the name of the custom variable, and how the source variables are combined to generate the result.

• name -- The name of the custom variable. When used in RPM, this name is prefixed by CUSTOM_. For the example above, the prop would use the variable name CUSTOM_GROUND_PROXIMITY_ALERT.
• operator -- This is a logical operator that is applied to the source variables. Supported operators are AND (returns 1 if all source variables fall within their specified range), OR (returns 1 if any source variable falls within its specified range), NAND (returns 1 if any source variable is outside of its specified range), NOR (returns 1 if all source variables fall outside their specified ranges), and XOR (for two variables, returns 1 if only one variable is in range, for more variables, it returns true if an odd number of source variables are within their defined ranges). All variables are evaluated, and they are evaluated in the order they appear in this definition.

###SOURCE_VARIABLE

• name -- The name of the variable to query. Caution: You may use custom variables as source variables, which also means you could set up a recursive loop that will crash KSP if you query a custom variable from within itself (or from within a custom variable that it queries).
• range -- The range of values that will cause the source variable to evaluate as true. These are the minimum and maximum value for the source variable, inclusive. Defined variables or floats may be used for the range end points.

In the above example, a custom variable named CUSTOM_GROUND_PROXIMITY_ALERT was created. It applies the AND operator to the variables listed, which are RADARALT, the radar altitude, and VERTSPEED, the vertical speed indicator. The radar altitude evaluates to true when it's between -10m and 100m, and the vertical speed evaluates to true when it's between -10000m/s and -4m/s, so this variable can be used to warn the player when they are close to the ground (below 100 meters) with a significant downward speed (more than 4 meters per second downward).

Creating a Mapped Variable

Like the Custom Variable, a Mapped Variable is defined in a config file somewhere in the GameData directory. There are no restrictions for where the custom variable is defined, so a prop maker can put it in the same config file as the prop that uses it.

RPM_MAPPED_VARIABLE
{
  sourceVariable = ALTITUDE
  sourceRange = 0,ORBITBODYATMOSPHERETOP
  mappedVariable = MAX_ALTITUDE
  mappedRange = 0,1
}

###RPM_MAPPED_VARIABLE An RPM_MAPPED_VARIABLE node defined a mapped variable. It maps the value in sourceVariable between the values defined in sourceRange to the range of values in mappedRange, and it uses the mappedVariable as the name of the new custom value.

• sourceVariable -- The name of the variable to query. Like a Custom Variable, you may use any variable here, including other mapped variables, so you could cause Bad Things to happen if you have to variables referring to each other.
• sourceRange -- A pair of values that define the minimum and maximum bounds of the range you wish to map. You may use variable names in both of these fields. In the above example, the range would be from 0 to 70000 on Kerbin.
• mappedVariable -- The name of the mapped variable. This name is prefixed by MAPPED_, so to use the example above, you would use MAPPED_MAX_ALTITUDE.
• mappedRange -- The range to map to. These values must be numbers - variable names are not currently supported.