Prop modules

Monitors are not the only props this package supports, there are a number of other prop modules which can be used to create various switches, gauges, and are otherwise helpful in their construction.

Note that many of these modules have a refreshRate field. The RasterPropMonitorComputer (the module responsible for update all of the variables) will always use the smallest refresh rate it finds.

JSIActionGroupSwitch

This module will attach an IVA prop to an action (Initially, they were only action groups, but now the module can toggle a lot more things.) so that clicking on the prop will change the state of the action group as well as run an animation on the prop. Handy for making animated switches, but animation can be the primary purpose of such a switch, and animations on both the internal model and on the pod exterior can be triggered. In addition to triggering a part animation, this module can also change a material's color.

A function is included to enable and disable a light on the internal model, so you can make a light switch. Extra actions can be provided through a plugin API. Configuration options:

MODULE
{
	name = JSIActionGroupSwitch
	animationName = nameOfThatAnimation
	switchTransform = nameOfThatCollider
	actionName = custom01
	switchSound = path/to/buttonbeep
}

• actionName -- name of the action group or custom action. Valid names are: gear, brakes, lights, rcs, sas, abort, stage, custom01..custom10, intlight, dummy, plugin, transfer. The dummy action will produce a switch that animates but doesn't do anything, which can be used purely for effect or when the animation is the intended effect. "intlight" action will toggle an internal light source. The plugin action and its use is detailed in the page on Action handlers. The transfer action is detailed below.
• animationName -- name of the animation to run. First frame of the animation is the 'off' position and last frame is the 'on' position. This is not a mandatory variable -- the switch doesn't have to be animated if, for example, you want it to use this module only for the sound effect instead.
• animateExterior -- Boolean, defaults to false. If this is false, the module looks for the animation on the prop it lives in, if it is true, it searches for the animation on the part exterior -- this way, you can use an IVA switch to animate external elements of the pod.
• colorName -- Name of the color property to work with, _EmissiveColor by default.
• coloredObject -- Name of the gameObject to change the material color on. Animation takes precedence.
• consumeOnToggle -- The switch will consume a given resource when being toggled if this parameter is given. The format is <Resource name as per resource.cfg>,<Amount to consume per switching>,<on|off|both>. 'on' means 'while turning on', 'off' means 'while turning off'. Beware of master-slave switching consuming resources, as it may produce more complicated effects than you expect.
• consumeWhileActive -- The switch will consume a given resource while in the 'on' position. The format is <Resource name as per resource.cfg>,<consumption rate>. A master-slave pair where the master consumes a resource while a slave consumes a negative amount of another resource can be used to produce a primitive resource converter.
• customSpeed -- A speed multiplier, permitting you to play the animation faster or slower than it normally is. 1 is normal speed and default.
• disabledColor -- Color of that object when the switch is in the disabled state. An RGBA string (0,255,255,255) or Named Color.
• enabledColor -- Color of the object in an enabled state.
• initialState -- Valid only for switches using dummy or intlight that also define a perPodPersistenceName. The initial state of the switch (so some switches can be set to 'on' at startup).
• internalLightName -- name of the internal light to toggle, if needed. All lights sharing the same name will toggle at once.
• loopingSound, loopingSoundVolume -- The optional name and volume of a sound that loops continuously when this switch is 'on'.
• masterVariableName, masterVariableRange -- The name of a defined or custom variable, and a range of values where the variable is considered 'in spec'. When the variable is 'out of spec', this switch is disabled (and switched 'off'). Use caution with this variable - if it's applied to a switch that controls things like action groups, lights, etc, it can override keyboard input as well in IVA.
• momentarySwitch -- Boolean, defaults to false. When a switch is configured as a momentary switch, it changes state when it is pressed and when it is released (allowing for momentary brakes, for instance).
• needsElectricCharge -- Boolean, defaults to true. If the switch toggles an internal light source, it will check for the presence of electric charge on the vessel (but not consume any). If there's no electric charge, internal lights will go out. No such checks will be performed if this variable is false.
• perPodMasterSwitchName -- The per-pod global name that can be used to disable this switch. If a 'dummy' switch using this same name as its perPodPersistenceName is set to 'off', then this switch is disabled (and switched to off). The other switch must be switched on before this switch will work.
• perPodPersistenceName -- The state of switches which are not part of KSP standard action list (most importantly, 'dummy') is stored in the persistence file with a name unique to the prop the module lives in. It is possible to have a per-pod global name for a specific switch instead, which permits you to synchronise multiple switches or set up master-slave relationships between ActionGroupSwitch modules.
• perPodPersistenceIsGlobal -- Defaults to false. When true, the perPodPersistenceName value is treated as a ship-wide variable instead of a pod-local variable, and updates will affect all pods on the craft. Even with this set to true, values can become out-of-sync when craft dock.
• refreshRate -- Number of frames to skip between computing the variables.
• resourceName -- When 'needsElectricCharge' is true, this provides the defined variable name of the resource used. Defaults to 'SYSR_ELECTRICCHARGE'.
• reverse -- true if the animation (or color change) is to be played backwards, i.e. the "on" position is the first frame.
• switchGroupIdentifier -- Assigns an identifier (integer >= 0) to this switch. Other switches with a defined switchGroupIdentifier and the same perPodPersistenceName will act as a switch group (see below).
• switchSound -- An URL (in the KSP sense) of a sound file that will be played whenever the user flicks the switch or presses a button. By default uses a Squad-supplied switch sound (in Squad/Sounds) -- if you wish to disable it, put this variable into the config and keep it empty.
• switchSoundVolume -- Volume of the switch sound, defaults to 0.5.
• switchTransform -- name of the collider transform on the switch that the user will be clicking. It is by default empty. It is perfectly legal for this module to have no switchTransform at all, in which case it is a 'slave' module existing purely for it's animation capabilities, for more on the usage of that see below.

Master-slave usage of JSIActionGroupSwitch

This is an excerpt from an actual configuration of a pod for which this feature was made:

MODULE
{
	name = JSIActionGroupSwitch
	animationName = H3_SW
	switchTransform = but
	perPodPersistenceName = medhatch
	actionName = dummy
}
MODULE
{
	name = JSIActionGroupSwitch
	animationName = tesla_med_door
	animateExterior = true
	perPodPersistenceName = medhatch
	actionName = dummy
}

In this example, one switch prop operates both an internal animation of the switch itself (with the first module) and an animation on the part exterior. The second module is slaved to the first by using a single variable name to store the state of the switch, so the animation on the pod exterior is effected by toggling the IVA switch.

Switch Groups

Multiple switches with a dummy action can be assigned to a switch group. A switch group is a group of switches where one is always on. For an in-game example of this feature, look at the buttons controlling SAS during flight - one of the SAS modes is always set, and clicking a different SAS mode will turn off the previous SAS mode. For a switch group to work, all JSIActionGroupSwitch members must use the same perPodPeristenceName, and they must all have a switchGroupIdentifier. The prop(s) with an identifier of 0 will be "on" when KSP first loads; afterwards, the persistent variable system remembers which one was on. NOTE: If no switch has an identifier of 0, then it is possible for all switches to start out "off"; once any switch has been flipped, it will be impossible to turn them all off again without using a separate JSIActionGroupSwitch that uses the perPodPersistenceName, but does not have switchGroupIdentifier.

Transfer Actions

A transfer action will transfer numeric data from a plugin to a persistent variable, or from the persistent variable to a plugin, or from a defined variable to a plugin. The action is created using the following configuration option in the JSIActionGroupSwitch module:

• name -- The name of the plugin that the method resides within.
• setMethod, getMethod, getVariable -- The name of the method that is used to set the variable in the plugin, or to get the current value of the variable from the plugin. A 'set' method must take a double as its only parameter, while a 'get' method must return a double (and take no parameters). Alternatively, you can use getVariable to transfer a value from another defined variable into the persistent variable. Usually only one of these may be present in the TRANSFERACTION node.
• perPodPersistenceName -- The name of the persistent variable that holds the results of the get method, or is used to provide the parameter for the set method.
• stateVariable, stateMethod -- Optional parameters that can be used to disable a switch so it does not transfer the value. When the stateMethod returns false, or the stateVariable is less than 1 (zero or negative), the transfer is blocked.

Examples

TRANSFERACTION
{
	name = JSIMechJeb
	getMethod = GetLaunchAltitude
	perPodPersistenceName = LAUNCHALTITUDE
}

This action queries MechJeb for the current launch altitude, and it stores that result in PERSISTENT_LAUNCHALTITUDE.

TRANSFERACTION
{
	name = JSIMechJeb
	setMethod = SetLaunchAltitude
	perPodPersistenceName = LAUNCHALTITUDE
}

This action sets the MechJeb launch altitude to the value in PERSISTENT_LAUNCHALTITUDE.

TRANSFERACTION
{
	name = JSIMechJeb
	setMethod = CircularizeAtAltitude
	getVariable = APOAPSIS
}

This action takes the defined variable APOAPSIS and uses it to set MechJeb's CirularizeAtAltitude maneuver planner.

JSINumericInput

NOTE: As of v0.23.0, this is an experimental module. It may not be feature complete. Features listed below are available, but there are animation tuning parameters that are missing.

This module allows the user to edit a numeric value by pressing buttons that change the value by a specified amount. The numeric value is defined in a persistent variable. Multiple props / JSINumericInput modules may edit the same persistent variable.

Basic module configs

The following is an example configuration:

MODULE
{
	name = JSINumericInput
	perPodPersistenceName = LAUNCHALTITUDE
	defaultValue = PLUGIN_JSIMechJeb:GetLaunchAltitude
	stepSize = 1000
	minValue = ORBITBODYATMOSPHERETOP
	maxValue = 2500000
	reverse = false
	animationName = switch_B_ButtonPushAnim
	customSpeed = 1.0
	loopInput = false
	
	USERINPUTSET
	{
		switchTransform = switch_B_ButtonBody
		animationName = switch_B_ButtonPushAnim
		switchSound = ASET/ASET_Props/Sounds/tumbleClick01
		switchSoundVolume = 0.5
		increment = 1000
	}
}

• animationName -- The optional name of an animation to play when the button is pressed.
• customSpeed -- The optional parameter to change the speed of the animation played on button press (defaults to 1.0).
• defaultValue -- The default value for the persistent variable, provided it doesn't already exist. This can be a constant number or any variable.
• loopInput -- An optional Boolean (defaults to false) that causes the input range to loop between the max value and min value (useful for situations like entering a heading, where you want a heading of 359 to increase to 0 and vice versa).
• minValue -- The optional minimum permitted value (in the above example, the minimum is ORBITATMOSPHERETOP, which will prevent a craft from trying to circularize an orbit within the atmosphere). Thus value and maxValue may be any number of variable. It is your responsibility to make sure minValue < maxValue. If minValue is omitted, there is no limit to the minimum value (outside the limits of 32 bit floating point values).
• maxValue -- The optional maximum permitted value (2,500,000 above, which equates to 2,500 km). Like minValue, if this parameter is omitted, there is no upper limit to the value.
• perPodPersistenceName -- The name of the persistent variable that will be edited by this method.
• perPodPersistenceIsGlobal -- Defaults to false. When true, the perPodPersistenceName value is treated as a ship-wide variable instead of a pod-local variable, and updates will affect all pods on the craft. Even with this set to true, values can become out-of-sync when craft dock.
• reverse -- Optional. Indicates that the animation selected by animationName should be played in reverse.
• stepSize -- The interval between valid values for the variable. For instance, a stepSize of 10 will allow values of 0, 10, 20, 30, etc, but 1, or 14, or 29 would be rounded to 0, 10, or 20 (respectively). If no stepSize is specified, then any fractional value would be allowed. In the above example, the stepSize of 1000 causes LAUNCHALTITUDE to be adjusted to the nearest kilometer.

As shown above, the details of editing a value are placed in a 'USERINPUTSET' node. Multiple nodes can be used within a single JSINumericInput module to allow for a complex prop with multiple buttons. There are two ways to configure USERINPUTSETs - 'click' mode and 'press-and-hold' mode. The 'click' mode (shown above) changes the persistent value by the amount specified in increment. The 'press-and-hold' mode (shown below) changes the persistent value by a varying amount depending on how long the button is held down. A 'USERINPUTSET' using increment may not have an incrementCurve and vice-versa.

USERINPUTSET
{
	switchTransform = switch_B_ButtonBody
	animationName = switch_B_ButtonPushAnim
	incrementCurve
	{
		key = 0 1000
		key = 1 1000
		key = 2 5000
		key = 3 10000
		key = 4 25000
		key = 5 25000
	}
}

• switchTransform -- The name of the collider corresponding to this button.
• switchSound, switchSoundVolume -- The optional name of an audio clip to play, and the volume to play it at, when the button is pressed or released. The volume parameter, if omitted, defaults to 0.5.
• animationName -- The name of the animation played when the button is pressed/released.
• increment -- The amount that the persistent value changes per button press.
• incrementCurve -- a FloatCurve consisting of multiple key nodes, each of which has a time value, an increment value, and (optionally) tangent values. The time value indicates how long the button has been held down (in game seconds - not real-world seconds). The increment value indicates how much the value changes per second. Thus, a key = 1 1000 indicates that once the button has been held down for one second, the persistent value changes at the rate of 1000 units/sec.

JSIPropTextureShift

This module will shift a texture on the prop it is attached to once upon startup. Initially made to allow to use one model and one texture full of button labels to create lots of individual buttons, it can probably have other uses. Configuration options:

• transformToShift -- The name of the transform the texture on which will be shifted.
• layerToShift -- Space-separated list of the layers to operate on. "_MainTex" by default.
• x, y -- offset to apply to the texture. Must be in texture coordinates, i.e. floats. Notice that it will be added to the offset of the texture already there, which is also in floats. While the more typical situation is to have a separate texture for labels, so it's easier to calculate, adding offset in this fashion permits you to squeeze the labels into the same texture as something else -- it will work as long as they're all arranged in a group.

Once the job is done, the module selfdestructs to save memory and reduce component count, leaving the prop with the shifted texture intact until the next time it's instantiated.

JSIOdometer

This module mimics the behavior of analog numeric displays (such as that found in older automobiles). It can be configured to operate in two modes, linear and SI. In linear mode, the odometer will show an 8 digit numeric value (plus an optional sign), while in SI mode, it will display a six digit number, plus a sign and the SI prefix. Furthermore, this module can be linked to a JSIActionGroupSwitch by using a shared perPodPersistenceName. When it is linked to an action group switch, the odometer can switch between displaying two different variables (for instance, to switch between altitude ASL and radar altitude). The display is a single row of nine characters.

When in linear mode, the odometer will show only the 8 least significant digits, so 100,000,000 will look like "00000000". When in SI mode, values of less than 0.001 (1 milli-whatever) will appear as zero. Values in excess of 999.999G will be displayed incorrectly (1,000,000,000,000 will appear as 000.000G).

Prop and Texture Requirements

The JSIOdometer's screenTransform has the same requirements as a full RasterPropMonitor display. Any prop that can be used for a RasterPropMonitor can be used for a JSIOdometer (although you will want to rescale the prop to make it a 4:1 or 4.5:1 aspect ratio).

All JSIOdometer configurations require a digitTexture. This is a simple texture arranged in a vertical strip that contains the digits 9 through 0 (9 on the top, 0 on the bottom).

All JSIOdometer configurations using SI mode, and a linear JSIOdometer that wishes to display a variable's sign (+ or -) must include a characterTexture. This texture should contain eight characters arranged vertically. From top to bottom, these are '+' (or blank, if you do not want a sign to display for positive values), ' ' (a blank for neither positive nor negative), '-' (for negative values), 'G' (for the giga- prefix), 'M' (for the mega- prefix), 'k' (for the kilo- prefix), ' ' (for no prefix), and 'm' (for the milli- prefix).

In SI mode, the odometer does not display a decimal point. It skips that location, leaving it blank. To display a decimal point, use an overlayTexture that has the decimal.

In TIME mode, the odometer does not display the colon characters (':'). Those places are left blank, so an overlayTexture must be used if a colon is desired. In time mode, there is no sign (negative times will appear positive).

• screenTransform -- The name of the transform that will be used to display the odometer.
• textureLayerID -- The texture layer that will be replaced with the odometer's render texture. Defaults to "_MainTex".
• screenPixelWidth, screenPixelHeight -- Just like with a RasterPropMonitor, the width and height of the area that the odometer will draw to.
• refreshDrawRate -- How frequently the odometer updates itself, in frames rendered. The default is 6.
• variable -- The variable whose value the odometer displays.
• altVariable -- Optional. When perPodPersistenceName is defined, and its value is "true", the odometer displays this value, instead.
• perPodPersistenceName -- Optional. When defined, this value controls displaying the altVariable instead of the regular variable. Remember to define a prop with a JSIActionGroupSwitch configured to the same name to allow changing the setting.
• digitTexture -- The texture that contains the numeric digits displayed by the odometer.
• characterTexture -- The texture that contains the sign and prefix characters displayed by the odometer.
• overlayTexture -- An optional texture that is drawn on the screenTransform after the odometer has rendered.
• characterSize -- This size, in pixels, that each digit occupies on the screenTransform.
• displayPosition -- The location on the screenTransform where the odometer will start drawing.
• backgroundColor -- The color used to clear the screenTransform before drawing the odometer characters.
• odometerMode -- One of the following: LINEAR, which will display an eight-digit signed integer (eg, +12345678); SI, which will display a six-digit value using SI formatting (eg, +002.345k); or TIME_HHHMMSS, which displays the value as a time with 3 digits for hours, plus minutes and seconds.
• odometerRotationScaling -- Controls how quickly the digits rotate when changing. The default of 10 makes for quick snaps. Smaller numbers make the digits roll slower.

JSISwitchableVariableLabel

This module provides a light-weight way to display a single-line of text, like a JSIVariableLabel, but it adds the ability to use a collider (button) to cycle what is displayed. It can also change the color of a named transform. A prime example of its use would be to recycle the stock ledSpeedPanel prop to display other status information, such as SYSR_LIQUIDFUEL and SYSR_LIQUIDFUELPERCENT. Alternatively, it could be applied to the stock squareButton prop with only colors defined, so the button could be pressed to cycle through multiple colors (it wouldn't do anything useful, but it'd be something to click on).

JSISwitchableVariableLabel is configured with these options:

• labelTransform -- the name of the transform that will be used for text display. It can be omitted if no text will be shown.
• fontSize -- the size of the font, in unknown units. A size of around 0.01 or 0.008 works well for the ledSpeedPanel. The default is 0.008.
• refreshRate -- the frequency with which the text is updated, in terms of screen refresh cycles. The text is updated every 10 frames by default.
• switchTransform -- the name of the transform that is used as a button collider.
• switchSound -- the KSP-style URL of the sound to play when the button is pressed. The "sound_click_flick" stock sound is used by default.
• switchSoundVolume -- the volume, in a 0.0-1.0 range, to play the switch's sound. This value is 0.5 by default
• coloredObject -- the name of the transform that will have color shifts applied to it. It may be omitted if no color shifting is desired.
• colorName -- Name of the color property to work with, _EmissiveColor by default.

Display Configuration

The JSISwitchableVariableLabel uses one or more VARIABLESET blocks within the MODULE block to define the behaviors that are enabled. Each VARIABLESET must have either a "color" field or a "labelText" field. A VARIABLESET can have both defined. You can also alternate between "color" and "labelText" entries, so that one button press will change the color of the colorTransform object, and the next button press will change the text being displayed, if you really want.

• color -- The RGBA color that will be applied to the colorTransform object.
• labelText -- The text (including defined variables) that is parsed to display on the labelTransform.

JSIInternalFlagDecal

This is a complete equivalent of the stock FlagDecal PartModule for use inside IVA. It can be used both inside INTERNAL and inside PROP -- when inside PROP, the prop will be searched for the transform name to place the flag decal on, otherwise, the IVA model itself. Configuration options:

• transformName -- The name of the transform to search for.
• textureLayer -- The texture layer to apply the flag texture to, defaults to _MainTex.

JSIInternalEVAHatch

This module is exactly what it says -- double clicking (rather than single clicking, to reduce the number of lost kerbals) on the transform will make the kerbal you currently control in IVA go EVA. It can be used both inside INTERNAL and inside PROP just like JSIInternalFlagDecal. It is recommended to keep the collider small, as any doubleclick will register, which may be unexpected to the user.

• hatchTransform -- Name of the transform to work with.
• internalAnimation -- Optional. If this parameter is provided, the module will search for an animation with that name on it's prop (or the internal model if it's on the model) and play it to completion before kicking the kerbal out.

JSISelectivelyVisibleProp

This prop module permits you to make a prop that is only visible when looking through the eyes of occupants of specific seats in your pod -- the particular reason it was requested was to make a HUD that was projected onto the glass in such a way as to make an illusion of a display floating in mid-air, which would look silly if the other pilot saw it. There is only one configuration parameter:

• visibleFromSeats -- A comma-separated list of seat ID numbers the prop will be visible from. Seat numbering starts with zero, and the order of seats is the order the InternalSeat modules are listed in internal.cfg.

Notice that there is no way to see such a prop when the user is watching from an InternalCameraSwitch. The prop is not getting deleted, only it's rendering is disabled.

JSIPropIDFinder

This is a module that may help you configure a complex interrelated prop system where props share each other's buttons. To use it, just add it to the prop.cfg of the prop you wish to know the prop ID of and check the debug log -- at start, it will output the name of the prop it's in and it's prop ID. There are no options to configure.

Don't forget to remove it afterwards.