Skip to content

Custom Variables

Jump to bottom
MOARdV edited this page Oct 18, 2017 · 12 revisions

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. Another 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. One use of this feature is to allow an IVA maker to control displacements of information on a text display based on any source variable. The third type of custom variable is the Math Variable. The Math Variable takes one or more defined variables, and it applies a mathematical operators to those variables, returning the result. This can be used to add values together, convert into different units, etc. As a fourth option, a Select Variable allows a single named variable to represent multiple values, depending on the settings of other variables. This feature is similar to the core SELECTEDSPEED variable, which reports the current speed (surface, orbital, target relative) depending on the 'mode' of the stock navball's speed indicator.

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.

NOTE: Custom variables use an optimization to speed up evaluation under certain conditions. For AND and NAND variables, the first source variable that returns false will stop processing the custom variable. Similarly, as soon as a source variable evaluates to true, an OR or NOR custom variable will stop processing. This can be used to make custom variables less expensive to evaluate by changing the order of the source variables.

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), 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), or ISNANORINF (returns 1 if any variable is NaN or Inf; the range is not evaluated). Variables 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).

CUSTOM_ variables apply an optimization that will cause them to stop evaluation under the following circumstances: for AND and NAND, evaluation stops at the first variable that is out of range. For OR, NOR, and ISNANORINF, evaluation stops at the first variable that is in range. When configuration one of these custom variables, try to order the variables that are tested so that the most likely to be false variable is listed first for AND/NAND, and the most likely to be true variable is first for the other three, to make the evaluation as quick as possible.

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 may be numbers or variables.

Creating a Math Variable

Like the other custom variables, a Math variable is defined in a config file somewhere in the GameData directory. If there is an error processing a math variable, the result is zero.

RPM_MATH_VARIABLE
{
   name = ALTITUDE_FEET
   operator = MULTIPLY

   sourceVariable = ALTITUDE
   sourceVariable = MetersToFeet
}

RPM_MATH_VARIABLE

An RPM_MATH_VARIABLE defines the Math Variable. It consists of at least three entries: the name, the operator, and one or more sourceVariable.

  • name -- The name of the variable. When used in RPM, this name is prefixed with 'MATH_', so the example above would be accessed as 'MATH_ALTITUDE_FEET'.
  • operator -- One of the operators defined below.
  • sourceVariable -- Any Defined Variables or number may be used as a source variable. One or more sourceVariable entry needs to be in the math variable. The values are evaluated in the order they are listed in the config file. For instance, if the operator in the example above was DIVIDE, the resulting value would be the altitude divided by MetersToFeet (MetersToFeet is a special defined variable described in Defined Variables.

Operators

  • ADD adds all of the source variables together.
  • SUBTRACT subtracts the second and subsequent variables from the first one.
  • MULTIPLY multiplies the variables together.
  • DIVIDE divides the first variable by the second and all subsequent variables.
  • POWER raises the first variable by the second and all subsequent variables.
  • ANGLEDELTA returns the difference between two angles (in degrees).
  • ATAN2 returns the angle (in degrees) created by taking the arctangent of the first two values provided.
  • MAX returns the value of the largest of the listed variables.
  • MIN returns the value of the smallest of the listed variables.
  • MODULO returns the mathematical modulo of the first two variables.
  • MAXINDEX returns the index of the largest listed variable (starting with '0' for the first variable, '1' for the next, etc).
  • MININDEX returns the index of the smallest listed variable (starting with '0' for the first variable, '1' for the next, etc).

Creating a Select Variable

The RPM_SELECT_VARIABLE allows a single variable to represent multiple values, depending on the state of controlling variables. It is similar to a JSIVariablePageTextSwitcher module, but it affects a single numeric variable.

RPM_SELECT_VARIABLE
{
	name = DISTANCE
	
	defaultValue = ALTITUDE
	
	VARIABLE_DEFINITION
	{
		name = SURFSPEED
		range = 0, 350
		
		value = RADARALTITUDEOCEAN
	}
	(... additional VARIABLE_DEFINITION here ...)
}

RPM_SELECT_VARIABLE

All fields in an RPM_SELECT_VARIABLE entry are mandatory. VARIABLE_DEFINITION is optional, but it's pointless to use this variable without at least one such entry. There are no practical limits to the number of VARIABLE_DEFINITION fields that can be used.

  • name -- The name of the select variable. It is accessed in RPM by prefixing with 'SELECT_' (the above example would be 'SELECT_DISTANCE'.
  • defaultValue -- The value that is returned when no VARIABLE_DEFINITION fields are used. It can be one of defined variables, a numeric literal (eg, '10'), or a string literal when prefixed by '$' (eg, '$My text', which will return 'My text'). Note that string literals strip leading and trailing whitespace.

VARIABLE_DEFINITION

The alternate values that will be returned. The 'name' variable is evaluated. If it falls within the 'range' specified, then 'value' will be used for this Select Variable.

  • name -- The name of the variable that will be evaluated.
  • range -- The range of values where name is considered in range.
  • value -- The variable or number that is returned if name is in range. This can be a defined variable, a numeric literal, or a string literal.

In the example above, when SURFSPEED is between 0m/s and 350m/s (roughly below Mach 1), SELECT_DISTANCE returns RADARALTOCEAN. Otherwise, SELECT_DISTANCE returns ALTITUDE.

Clone this wiki locally