Variable handlers

Sometimes, it is necessary to get into variables data that is not available unless a certain plugin is loaded. Instead of making RPM depend on that plugin, it has the variable handler API, which is, in particular, used to provide much more sensible data for delta V than RasterPropMonitor can compute on it's own if MechJeb is installed and available on the vessel.

To provide variables, your plugin must satisfy the following conditions:

• It must be a PartModule. RasterPropMonitorComputer module will take care of instantiating it on the pod it lives on if needed, but it will use the one that is already there if there is one, so your handler plugin can keep persistent data by getting written into the part config as a regular MODULE {}.
• It must have a method that returns an object and takes a string. The string is the name of the variable, the object is whatever it returns. None of the native variables return anything except doubles and strings, and none of the further formatting functions will work with anything else, mind you -- if you want to return a boolean, you must take care of converting it to a double.
• That method must return null if the variable is not among those it actually handles.

RasterPropMonitorComputer looks around GameData for *.cfg files with the RPMCVARIABLEHANDLER block, like this:

RPMCVARIABLEHANDLER
{
    name = MechJebRPMVariables
    method = ProcessVariable
    variable = MECHJEBAVAILABLE,0
    variable = DELTAV,fallback
    variable = DELTAVSTAGE,fallback
}

The configuration options therein are:

• name -- The name of the module to be loaded.
• method -- The method within it to call. (public object Method(string variableName))
• variable -- <name of the variable>[,<default value>[,<caheability>]]] -- variables this module handles.

The actual meaning of the components to a variable definition is a bit more involved:

• Name of the variable is, obviously, required. By convention, variable names are always uppercase, though this is not actually a requirement.
• The default value is what gets returned by RPMC if the variable handler could not, for whatever reason, be loaded -- it is zero if not given, but you can replace it with any number that fits into a double. If the value for the default value cannot be parsed as a double, it is treated as a string. If the default value is given as fallback, when the module cannot be used to return this variable, it is treated as if it doesn't exist, so subsequent processing might determine it.
• 'cacheability' is a boolean, so either true or false, and it defaults to true. If a variable is cacheable, RPMC will avoid computing it more than once per update cycle.

Variable handlers are processed before RPMC's own variable handling kicks in and can, therefore, override natively provided variables. If the plugin is to be instantiated by RPM, the entire block is passed to module initialization as a MODULE {} block, so any options not recognised by handler loader (and even those that are) will be available to it as KSPFields.

It is recommended that all variable handlers come with '...AVAILABLE' variable, which is 0 if the handler's variables are not available, and 1 if it is. -1 can be used to mean something else.

Builtin variable handlers

MechJebRPMVariable

The one module the whole rigmarole is about, MechJebRPMVariable comes preconfigured:

RPMCVARIABLEHANDLER
{
    name = MechJebRPMVariables
    method = ProcessVariable
    ....
}

and handles the following variables:

• MECHJEBAVAILABLE -- 1 if MechJeb is present on the system and available on the vessel. 0 if MechJeb is not present on the system. -1 if MechJeb is present on the system but not available on the vessel.
• PREDICTEDLANDINGERROR -- The predicted distance from a landing target where the vessel is expected to land, according to the MechJeb landing predictor. -1 if the current orbit does not land, or if the predictor is not enabled (either in the MJ Landing Guidance menu, or via MechJebRPMButtons ButtonEnableLandingPrediction).
• DELTAV -- Total vacuum delta v for the entire ship. Overrides the native DELTAV variable.
• DELTAVSTAGE -- Total vacuum delta v for the current stage. Overrides the native DELTAVSTAGE variable.