Skip to content

Prop modules

Jump to bottom
Eugene Medvedev edited this page Jun 16, 2014 · 71 revisions

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.

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
}
  • 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.
  • 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.
  • 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.
  • coloredObject -- Name of the gameObject to change the material color on. Animation takes precedence.
  • disabledColor -- Color of that object when the switch is in the disabled state.
  • enabledColor -- Color of the object in an enabled state.
  • colorName -- Name of the color property to work with, _EmissiveColor by default.
  • reverse -- true if the animation (or color change) is to be played backwards, i.e. the "on" position is the first frame.
  • customSpeed -- A speed multiplier, permitting you to play the animation faster or slower than it normally is. 1 is normal speed and default.
  • actionName -- name of the action group or custom action. Valid names are: gear, brakes, lights, rcs, sas, abort, stage, custom01..custom10, intlight, dummy, plugin. 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 it's use is detailed in the page on Action handlers.
  • internalLightName -- name of the internal light to toggle, if needed. All lights sharing the same name will toggle at once.
  • 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.
  • 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.
  • 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.

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.

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.

JSIVariableAnimator

This module will animate a prop or change it's texture color according to the results of variable computation, interpolating the animation (or colors, or positions, or texture offsets) given between a minimum and a maximum value according to the output of a variable. The variables are the same as for the RasterPropMonitor (see Defined variables), though keep in mind that you can't use those that are returned as strings. A single instance of the module can drive as many elements as you like, but configuration is slightly complicated:

MODULE 
{
	name = JSIVariableAnimator
	refreshRate = 3
	VARIABLESET
	{
		...
	}
}

There is only one global module configuration parameter:

  • refreshRate -- Number of frames to skip between computing the variables.

Everything else is done in VARIABLESET blocks, and you can have as many as you like:

  • scale -- <variable or float value>,<variable or float value> -- the first variable or value corresponds to the beginning of the scale, second variable or value corresponds to the end of the scale.
  • reverse -- A boolean. If true, the actuation of the scale will be reversed.
  • variableName -- Name of the driving variable. This is actually something of a misnomer, in that it can also be a floating point number, i.e. you can drive a scale around a static number if you want to.

For example, to drive a fuel gauge, you give it scale = 0,SYSR_LIQUIDFUELMAX and variableName = SYSR_LIQUIDFUEL.

Once the scale is defined, you have a choice of four actuation modes. Only one of the four can be used in a single VARIABLESET block. There is nothing stopping you from applying multiple actuation modes to the same object in different VARIABLESET blocks, as long as they are all different actuation modes -- using multiple variable blocks to apply the same actuation to the same object is probably not going to give you satisfactory results.

Animation mode

  • animationName -- Name of the animation to run.
  • animateExterior -- If this variable is present, the animation is located on the exterior of the pod, otherwise, it is searched for on the prop itself.

Animation mode is actually the easiest to use, since you define everything else in the Unity editor when defining the animation -- the beginning and end of the scale will correspond to the first and last frame respectively.

Color shift mode

  • coloredObject -- Name of the transform which will be color shifted.
  • passiveColor,activeColor -- Colors of the 'off' and 'on' state respectively. Mandatory if you wish to use color shift mode.
  • colorName -- The name of the color property to drive in color shift mode. Defaults to _EmissiveColor.

The color shift mode will interpolate or switch between two color properties of a texture. Usually you want the _EmissiveColor, but not necessarily.

Rotation mode

  • controlledTransform -- Name of the transform that will be rotated.
  • localRotationStart,localRotationEnd -- <x>,<y>,<z> Rotations, in degrees, that will correspond to the beginning and end of the scale respectively. Notice that the initial rotation of the transform is remembered, these values are relative to whatever the initial rotation was.
  • longPath -- If the angle between your rotations is less than 180 degrees, rotation will go along the shortest path. Sometimes, this isn't what you want. In that case, you can longPath = yes, which will use a somewhat worse algorithm which will nevertheless correctly interpolate along the longer path.

Translation mode

  • controlledTransform -- Name of the transform that will be moved.
  • localTranslationStart,localTranslationEnd -- <x>,<y>,<z> Positions, that will correspond to the beginning and end of the scale respectively. Notice that the initial position of the transform is remembered, these values are relative to whatever the initial position was, and in scale based on the parent transform.

Scale mode

  • controlledTransform -- Name of the transform that will be scaled.
  • localScaleStart,localScaleEnd -- <x>,<y>,<z> Scales, per axis, that will correspond to the beginning and end of the scale respectively. Notice that the initial scale of the transform is remembered, these values are relative to whatever the initial scale was, and it is also relative to the parent transform.

Texture shift mode

  • controlledTransform -- Name of the transform the material on which will be affected.
  • textureLayers -- A comma-separated list of texture layers to affect, i.e. _MainTex,_Emissive.
  • textureShiftStart,textureShiftEnd -- <x>,<y> vectors denoting start and end positions of the texture offset.

Texture scale mode

  • controlledTransform -- Name of the transform the material on which will be affected.
  • textureLayers -- A comma-separated list of texture layers to affect, i.e. _MainTex,_Emissive.
  • textureScaleStart,textureScaleEnd -- <x>,<y> vectors denoting start and end scales of the texture.

Notice that texture shift and texture scale modes will work independently of each other on the same material.

Threshold mode

Threshold mode works regardless of which actuation method you choose, and is initiated when the threshold parameter is present. In threshold mode, actuation does not smoothly interpolate between states, but instead flips instantly between the ends of the scale. Extra configuration parameters available only in threshold mode:

  • threshold -- <minimum>,<maximum> -- If this parameter is present, threshold mode is enabled. The variable is scaled in between the minimum (0) and maximum (1) of the scale. If it falls within the range given as the threshold after that, the animation is immediately flipped to the end and the alarm, if any, is triggered. Otherwise, it's kept at start.
  • flashingDelay -- In seconds. If this parameter is present, if the threshold condition is satisfied, the animation (or color) will flip between states continuously, spending only flashingDelay seconds in each state.
  • alarmSound -- A sound URL. If present, this sound will start playing when the threshold is entered.
  • alarmSoundVolume -- Sound volume. Defaults to 0.5.
  • alarmMustPlayOnce -- A boolean, defaults to false. If true, the alarm sound must finish playing and cannot be interrupted by the threshold condition disappearing.
  • alarmSoundLooping -- A boolean. True if the alarm should loop when it's triggered. Defaults to false.
  • alarmShutdownButton -- The name of a collider clicking which with a mouse will stop the sound alarm. Stopping the sound will have no effect on the state of the animation. If the variable isn't present, there will be no way to stop the alarm.

For example, this will create an animated "low fuel" alarm light that will engage when you drop to 10% of total fuel capacity and play a looping alarm sound, which will be stopped when the user clicks it:

MODULE 
{
	name = JSIVariableAnimator
	animationName = LightThatButton
	variableName = SYSR_LIQUIDFUEL
	scale = 0,SYSR_LIQUIDFUELMAX
	threshold = 0.0,0.1
	alarmSound = MyPropLocation/AnnoyingSound
	alarmSoundLoop = true
	alarmShutdownButton = FuelButtonCollider
}

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.

JSIVariableLabel

This module is appropriate to use when you need to display a variable somewhere, but a full RasterPropMonitor is overkill. 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. 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:

  • 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 are supported just like in the monitors, but all other types of tags aren't.
  • 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.
  • 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. :)
  • refreshRate -- How often the text will be recomputed.
  • 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.

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.

Clone this wiki locally