Skip to content

JSILabel

Jump to bottom
MOARdV edited this page Jun 11, 2016 · 13 revisions

What it Does

This module displays a variable and/or text using an object similar to Unity's TextMesh 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 in a similar way to the stock InternalSpeed module.

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, or a single-line display). JSILabel has more configuration options than JSIVariableLabel, including more formatter tags.

How to Use It

This module is appropriate to use when you need to display a variable or text, but a full RasterPropMonitor is overkill.

Configuration:

  • alignment -- An optional string to control text is aligned. Valid values are Left, Center, and Right. If alignment is omitted, it defaults to Left.
  • anchor -- An optional string to control how the text is placed relative to transformName. Valid values are LowerCenter, LowerLeft, LowerRight, MiddleCenter, MiddleLeft, MiddleRight, UpperCenter, UpperLeft, and UpperRight. Because alignment controls the alignment of the text relative to the anchor, the 'Center', 'Left', and 'Right' variants of the anchor behave identically.
  • emissive -- An optional string to control when the text is emissive (self-lighting or glowing) versus non-emissive. Valid options are always, never, active, or passive. Their meaning and defaults are explained below.
  • flashRate -- An optional positive numeric value that controls how frequently the text will "flash" by switch the emissive property on and off. This value is expressed in seconds per transition, so 1 means "turn on for one second, and then turn off for one second". When the flash is on, positiveColor is used; when the flash is off, negativeColor is used. If the variable in variableName is not positive, the flash is ignored (so the label does not flash if the controlling variable is in the off state). Default is 0 (no flash).
  • fontName -- The name of a font that's expected to be installed on the user's computer, or is bundled with RasterPropMonitor. If the requested font is not available, Arial is used as a fallback (since Unity guarantees Arial or an equivalent typeface is available).
  • fontQuality -- An integer that controls the quality of the rendered font. By default, it is 32. Use higher values when large text looks blurry using default settings. Note that this value currently has no effect on embedded fonts.
  • fontSize -- The size of the font. Defaults to 8.
  • lineSpacing -- Used to scale line-to-line spacing. By default, it is 1. This value is multiplied by the built-in line-to-line spacing, so lineSpacing = 0.5 means "use 0.5 x normal line spacing".
  • 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. 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. If oneshot is set to true, the text will be initialized once, and it will not be updated again, even if it contains variables that change.
  • 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.
  • transformOffset -- the optional X and Y displacement of the transform transformName. This can be used for props that were not specifically set up to use JSILabel to move the anchor to a better location (such as centering text).
  • 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. When used by itself, it sets the color of the text. See color changing mode below.
  • switchTransform -- An optional transform to a collider on the prop that can be used to change text using the Variable Text Mode (see below).
  • switchSound -- The URL name of a sound (default is 'Squad/Sounds/sound_click_flick') that is played when switchTransform is clicked. It has no effect of switchTransform is not defined.
  • switchSoundVolume -- A value from 0.0 to 1.0 that controls the volume of switchSound. By default, it is 0.5.

Bundled Fonts

In addition to installed system fonts, JSILabel can load one of several fonts that are included with RasterPropMonitor:

  • InconsolataGo-Regular and InconsolataGo-Bold -- a fixed-width font good for control panel labels.
  • digital-7 and digital-7 (mono) -- Fonts styled after 7-segment LEDs. The first version has variable width characters, while the second version uses fixed-width.
  • repet___ (three underscored) -- the Repetition font, which provides a dot-matrix styled array for displaying characters.

Any of these fonts can be selected by JSILabel in addition to the installed system fonts.

Color Change Mode

By default, a JSILabel's text is white. To change the text color, provide a value in zeroColor (even if the color change mode is otherwise not used).

Text color can also be changed based on a variable query. In this mode, any time the variable identified with variableName changes, the color of the text will be updated based on whether the variable is positive, negative, or zero.

Color change 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.

Text Formatter Tags

Like JSIVariableLabel and RasterPropMonitor page configs, JSILabel supports a number of special tag sequences to control the display of the text. Unlike HTML, these tags are not strict in their ordering when nested.

  • [#rrggbb] or [#rrggbbaa] -- These tags change the color of the text. They will override any colors defined in zeroColor, positiveColor, or negativeColor.
  • [b] -- This tag selects bold text when the selected font supports it. To exit bold text, use [/b].
  • [i] -- This tag selects italic text; exit with [/i]. Bold and italic can be combined by nesting the tags ([b][i]).
  • [size=#] -- TODO.

Note that using formatter tags make string processing more computationally expensive, since the text generator has to account for those alternate colors and formats, so they should be used sparingly in places where they are updated frequently. For oneshot use, they have no impact on performance after the initial text setup.

Emissive Text

JSILabel text can be configured to be emissive (meaning the text will 'glow in the dark'). The emissive field controls when the text is emissive versus when it is not. The valid options for emissive are

  • always - the text will always appear to be glowing or self-illuminated. This is the default for text that does not use the color change mode described above.
  • never - the text never glows. It behaves like any text printed on a surface (it requires a light source to read it).
  • active - the text is emissive when color change mode is enabled and variableName is positive (so that positiveColor is being used). This is the default when color change mode is enabled.
  • passive - the text is emissive when color change mode is enabled and variableName is not positive (so that zeroColor or negativeColor is being used).

Variable Text Mode

When a valid switchTransform is specified in the config, JSILabel operates in Variable Text Mode. In this mode, the text that is displayed can be changed by clicking on the collider specified in switchTransform. This behavior is similar to JSISwitchableVariableLabel with two differences: first, only the text can be changed (there is no color change); and second, each VARIABLESET node may specify oneshot. Each time the user clicks on the switch transform, JSILabel will update the text it displays to the next text listed under labelText. It will loop back to the first one when switching away from the last one in the list.

When Variable Text Mode is active, a sound can be played when clicking the collider. The sound is configured with switchSound and switchVolume as described in the configuration above.

Each VARIABLESET contains one required field (labelText) and one optional field (oneshot). If oneshot is not present, it defaults to false.

When in Variable Text Mode, the oneshot and labelText entries in the main module are ignored.

VARIABLESET
{
  labelText = <=0,7:SIP7.1=>m $&$ ALTITUDE
}
VARIABLESET
{
  labelText = <=0,7:SIP7.1=>m $&$ RADARALTOCEAN
}

This example will switch between showing altitude above sea level and radar altitude (altitude above the surface, or above sea level).

Clone this wiki locally