Tutorial 1 Throttle - MOARdV/AvionicsSystems GitHub Wiki

This example will walk through the MAS_ThrottleCtrl prop, which provides a throttle lever that responds to the main throttle position on the vessel. It also includes some emissive components that provide help locating the control in the dark. The configuration file is found at MOARdV/MAS_ASET/ThrottleCtrl/MAS_ThrottleCtrl.cfg. The reader should already be familiar with prop configuration files, so this example focuses on the MAS-specific MODULE.

MODULE
{
  name = MASComponent

The prop module for any MAS prop that is not a monitor is MASComponent. There should only be one MASComponent per prop. A MASComponent contains one or more nodes that do various things, such as moving part of the prop, or changing its color, or adding text.

  ROTATION
  {
    name = throttleLever_001
    transform = throttleLever_001

The first node in this MASComponent is a ROTATION node. Per the documentation for a ROTATION node, this node will rotate a part of the prop around the specified transform. This rotation is most commonly used for simulating mechanical components of a prop, such as the hands of an altimeter, or, in this case, the position of a throttle lever.

This node is named throttleLever_001. The name field is an optional field, but it should always be included. Its purpose is to provide feedback on where in a prop configuration an error was found.

As a general rule, MAS will display

[AvionicsSystems]: INITIALIZATION ERROR, CHECK MESSAGE LOG

when loading a vessel with an error with prop configuration. Searching in the KSP.log file for "INITIALIZATION ERROR" will locate the error, which will have additional information to help understand why it caused an error.

The transform entry tells MAS which transform in the prop's model will be rotated by this node. In this case, the transform is throttleLever_001, which happens to be why this node was named the way it was.

    variable = fc.GetThrottle()
    range = 0.0, 1.0
    blend = true

These entries tell MAS what function will control the rotation, and how to interpret the value results of the function.

variable identifies the controlling variable. In this case, fc.GetThrottle(). The fc. identifies GetThrottle() as part of the MASFlightComputerProxy module. The majority of MAS functionality comes from the flight computer module, although there are other modules for specialized features or interaction with mods such as mechjeb., far., and parachute.. If we look at the documentation for fc.GetThrottle(), we see that it returns the current throttle position, between 0 (engines off) and 1 (full power).

range tells MAS how the variable will be used. Many MASComponent nodes can be configured in one of several different modes. The simplest mode is called "Boolean mode". In Boolean mode, the only thing that matters is whether the variable is greater than zero or not. This mode is useful when the exact value of the variable is not important. The next mode is "Threshold mode". In threshold mode, we add the range variable to stipulate what range of values will trigger the action. For instance, we could have a warning lamp that switches on when a vessel's fuel is between 0% and 10% by using range = 0, 0.1 (with the appropriate variable, of course).

In this case, neither of those modes are what we want. We want the throttle to slide from full-off to full-on proportionally to the throttle setting. To accomplish that, we add blend = true. This setting puts the ROTATION node in "Blend mode".

    startRotation = 0,0,0
    endRotation = 75,0,0
    speed = 1.0
  }

The startRotation and endRotation specified the rotation (in degrees) around the transform's X, Y, and Z axes, respectively. The startRotation represents the rotation that applies when the variable is at or below the first value of its range (0 in this case), while the endRotation represents the rotation that applies when the variable exceeds the second value of its range. Since this prop uses Blend Mode, and value between the two ranges will be interpolated here.

The speed field tells MAS that the prop should not instantly snap between positions when the variable changes. Instead, it will take 1 second to go from full-off to full-on. Setting this value to a larger value will make it move faster, while a smaller value will make it slow down (for instance, a speed of 3 means the rotation needs 1/3 of a second to move between the two extremes). If the speed field is omitted, or set to 0, the rotation will instantly snap to the specified location.

  COLOR_SHIFT
  {
    name = HandleLightsObj Backlight
    transform = HandleLightsObj

Here, we see a COLOR_SHIFT node. Color shifts allow part of the prop to change color. Most commonly, this color change corresponds to a part of the prop that simulates illumination (instrument panel backlights, warning lamps, etc). The node's name is slightly more helpful - it suggests that the color shift represents backlight illumination. The transform identifies which transform the color shift will affect.

    passiveColor = 0,0,0,255
    activeColor = COLOR_ASET_SWITCHER_MARK_POSITIVECOLOR
    range = 0, 1
    blend = true

The passiveColor indicates the color that applies when the controlling variable is out of range, or at the first value in the range field (as in this case). It lists an RGBA sequence using 8-bit color values (0 through 255). In this case, the color is opaque black (0, 0, 0, alpha = 255). Since this node does not indicate otherwise, this color is applied to the emissive color of the prop. A black color means "no emissive" - so this part of the prop does not glow.

The activeColor indicates the value to apply when the variable is at the maximum value of the range (1, in this example). This value is an example of the Named Colors. Named Colors have two important benefits: they allow a group of props to use a common color scheme, and they allow IVA creators to override those colors without having to create copies of the props.

The range and blend fields indicate that this node is using a blended (interpolated) mode, like the previous node.

    variable = fc.Conditioned(fc.GetPersistentAsNumber("Backlight"))
  }

This variable is more complex than the previous variable, but it illustrates two important features in MAS: Persistent Variables and functional behavior. We'll parse this field from the inside out.

fc.GetPersistentAsNumber("Backlight") tells MAS to find the prop-creator-defined variable named "Backlight", and interpret its value as a number. Persistent variables can have practically any name, and they provide a way to store variables (numbers or strings) that can be accessed later, and that can be accessed by multiple props. By calling fc.GetPersistentAsNumber, the prop creator can guarantee that a number will be returned - a zero is returned if the variable has not previously been defined, or if the variable can not be converted into a number for some reason. Prop creators will always want to use fc.GetPersistentAsNumber anywhere that a number is needed, such as in a variable.

In this case, the name of the variable is "Backlight". This variable is used to control the brightness level of instrument panel backlights.

fc.Conditioned is an immersion method. MAS uses fc.Conditioned to simulate the effects of loss of power or electrical disruption due to high g-forces on the vessel. A prop installed in a pod that is configured to support power disruption may use fc.Conditioned to cause variables to randomly go to zero during high g-loads, or when the vessel's power is disrupted.

Clearly, this effect should not be applied to every variable: having the throttle lever suddenly go to the 0% throttle position if the power goes out, for instance, would look weird. However, having the illuminated bands on the throttle flicker is reasonable.

The second COLOR_SHIFT node is identical to this one, other than controlling a different transform.

The next step in creating a prop is to create an interactive prop. For that, take a look at Tutorial 2 Action Group Button.