JSIVariableLabel

What it Does

This module displays a variable and/or text using KSP's built-in text rendering system. This module can display text, and it can use formatting strings and variables. For non-changing text (see oneShot below), it has low overhead. It permits you to use all the variable processing features of RasterPropMonitor while displaying the text the same way the stock InternalSpeed module does it.

When to Use It

Use this module to display simple text, such as labels on controls. It's useful in places where a little bit of configurable text is needed, but going through all of the effort of a full RasterPropMonitor is not justifiable (eg, adding a label to a switch). There are limitations to JSIVariableLabel: first, the only font available is Arial. Second, there is no way to change the justification or placement of the text - it is always left-justified, and anchored so the text is to the right of the named transform. For different font options and text placement options, look at JSILabel.

How to Use It

This module is appropriate to use when you need to display a variable somewhere, but a full RasterPropMonitor is overkill. The inherent drawback of the method is that you can only use the same font that InternalSpeed does. You can't supply your own. On the plus side, it's nowhere as resource intensive as a full RPM.

Configuration:

• fontSize -- The size of the font. Defaults to 0.008 -- 1 means that the font character height occupies one space unit vertically, so by default you get fonts as large as a meter. Don't blame me, I'm just reaching into the guts of a stock feature here. :)
• labelText -- The text to be printed and processed. Obeys the same rules as the text given directly in prop.cfg, i.e. { and } must be replaced with <= and => respectively. Colortags (eg. [#RRGGBBAA]) are supported just like in the monitors, but all other types of tags aren't. A quote (") can be used at the beginning of the text to allow it to prevent leading whitespace from being removed. The quote character is removed before the string is displayed (if you want a quotation mark at the beginning of the text, use two in a row, eg "").
• negativeColor -- An optional RGBA sequence (eg. '255, 255, 0, 255') or Named Color used for coloring the text. See color changing mode below.
• oneshot -- A boolean, defaults to false. When it is true, label text will only be processed once on IVA creation and will no longer refresh -- useful for action button labels. A label that contains no variable processing syntax is automatically oneshot.
• positiveColor -- An optional RGBA sequence (eg. '255, 255, 0, 255') or Named Color used for coloring the text. See color changing mode below.
• refreshRate -- How often the text will be recomputed.
• transformName -- The name of the transform the text will be attached to. The transform needs to be a Unity collider oriented Z- away from the surface the text is to be visible on and X+ to the right.
• variableName -- An optional name of one of the defined variables. This variable is evaluated for color changing mode (see below).
• zeroColor -- An optional RGBA sequence (eg. '255, 255, 0, 255') or Named Color used for coloring the text. See color changing mode below.

Color Change Mode

While the text's color in a JSIVariableLabel can be changed using tags, using a variable to change those tags can be a costly operation, since the variable must be queried and the string reformatted. If the only thing the variable is used for is to change text color, and that variable is not noisy (that is, it doesn't change frequently, like 'LIGHTS' or 'BRAKES'), it is usually much, much better to use JSIVariableLabel's color change mode.

This mode is enabled by including all four of variableName, positiveColor, negativeColor, and zeroColor. In use, it works the same as the C# text formatting option for numeric variables: if the result of variableName is positive, the text color is set to positiveColor. For negative values, the text color is set to negativeColor, and for zero, zeroColor.

When using callback mode, refreshRate is ignored (unless the text has variables to process, as well). Instead, the text color is change immediately when RasterPropMonitor detects the change.

Color tags still work when color change mode is enabled. The color in the tag is multiplied by the color change mode color (where all the values are normalized between 0 and 1, instead of 0 and 255).