Skip to content

Background handlers

Jump to bottom
MOARdV edited this page Oct 11, 2017 · 92 revisions

Background handlers produce backgrounds for pages:

		PAGE
		{
			button = ThatButtonTransform
			text = some text.
			BACKGROUNDHANDLER
			{
				name = YourModuleName
				method = TheMethodToCall
			}
		}

The method in question is passed the RenderTexture of the screen as it's first parameter, the value of the monitor's cameraAspect parameter as the second (float), and must return a bool value. (public bool Method(RenderTexture screen, float cameraAspect)) It can then draw on that texture with anything Unity lets one use -- which is somewhat limited, but mostly sufficient. Whatever text is defined for the page will be printed over the results afterwards. Upon successful completion the method must return true. If it returns false, the page will be cleared to emptyColor. Whether it returns true or false has no bearing on what will get printed.

Notice that this happens before any matrix operations on the RenderTexture are performed, so it's the author's responsibility to GL.PushMatrix, GL.PopMatrix and otherwise set it up for whatever they plan to draw on it.

The same optional parameters as for Page Handlers regarding pageActiveMethod and buttonClickMethod, getHandlerReferencesMethod as well as the multiHandler are also available. Notice that one page can have both a page handler and a background handler, and in case of a buttonClickMethod and pageActiveMethod, both handlers will receive the method call, unless you pointed those parameters to the same method on the same instance of your module. Notice also that while the same plugin can be both a page handler and a background handler, two separate copies will be loaded in the same page unless the multiHandler option is used.

There is one extra optional parameter that only makes sense for background handlers: showNoSignal. If this parameter is present in the background handler definition block, in cases where the background handler returns false, the screen will be cleared to the no signal texture, rather than with the blanking color, which is the default.

Included background handlers

JSISteerableCamera has its own page, since it has a number of advanced options.

JSIGraphingBackground

This background handler provides a way to display multiple bar-graph styled information displays on a page. These graphs can be used to provide visual information based on any defined variable in RPM. Setting up a graphing background in the page handler is simple:

 BACKGROUNDHANDLER
 {
    name = JSIGraphingBackground
    method = RenderBackground
    layout = ascentGraph
 }
  • layout - The name of the RPM_GRAPHING_BACKGROUND node that describes the page's layout.

Due to the potential complexity of the graphs, most of the configuration is done separately from the MFD's page setup:

RPM_GRAPHING_BACKGROUND
{
   layout = ascentGraph
   backgroundColor = 0,0,8,255

   DATA_SET
   {
      borderPosition = 32,64,48,256
      borderWidth = 3
      borderColor = 228,228,255,255

      graphType = VerticalUp
      variableName = ALTITUDE
      scale = 0,ORBITBODYATMOSPHERETOP
      passiveColor = 0,192,255,255
      activeColor = 0,0,128,255
   }
}

Layout Options:

There are only two configuration options in the RPM_GRAPHING_BACKGROUND.

  • layout -- The name of this layout node.
  • backgroundColor -- The background color of this node. The page is cleared to this color before drawing anything.

Data Set Options:

The Data Set contains the information needed to display one graph. There can be any number of DATA_SET entries in a single layout. Many of the descriptions are similar to the JSIVariableAnimator's use for color shifting.

  • borderPosition -- (Required) Describes the top-left corner and the width of a graph in pixels, measured from the top-left corner of the display. Even if there is no border drawn, these values are required.
  • borderWidth -- (Optional) An integer that tells RPM how many pixels wide the border will be. If omitted or set to zero, no border is drawn.
  • borderColor -- (Optional) The RGBA color of the border. If omitted, no border is drawn.
  • graphType -- (Required) The style of graph. See below for the complete listing and descriptions.
  • variableName -- (Required) The defined or custom variable that controls drawing this graph.
  • scale -- (Required) The range of values to be considered when graphing. Can be numeric or variables.
  • passiveColor -- The fill color of the graph when the variable is below the bottom of the scale. Defaults to clear if omitted.
  • activeColor -- The fill color of the graph when the variable is above the top of the scale. Defaults to clear if omitted.
  • threshold -- (Optional) Can be used to put the graph in threshold mode, where the passive color is used if the variable is outside of the threshold's range, and the active color is used otherwise. Particularly useful for a Lamp graphType.
  • flashingDelay -- (Optional) This value can be used to cause a threshold variable to flash, with the delay indicating how long the lamp will be on (or off) in seconds.
  • reverse -- (Optional) When set to true, it inverts the results (for instance, to report values outside of a threshold's range instead of within the threshold range).

Graph Types

There are seven graph types available for a JSIGraphingBackground:

  • HorizontalLeft -- A graph that fills in from the right side, growing to the left.
  • HorizontalRight -- A graph that fills in from the left side, growing to the right.
  • HorizontalSplit -- A graph that grows from the middle, expanding either left or right, depending on whether the variable is less than or greater than the mean of the scale's two ends.
  • Lamp -- A solid block that fills the defined region. This can be used to simulate the backlight of an indicator lamp, for instance.
  • VerticalDown -- A graph that fills in from the top side, growing down.
  • VerticalSplit -- A graph that grows from the middle, expanding either down or up, depending on whether the variable is less than or greater than the mean of the scale's two ends.
  • VerticalUp -- A graph that fills in from the bottom side, growing up.

Details and Notes

The defined variable is evaluated based on the scale, and a normalized value (in the range of 0.0 - 1.0) results. This value is used to blend between the passiveColor and activeColor, and it's used to control the proportion of the bar graph that's drawn. In the case of a split graph, a normalized value of 0.5 will draw a single line right in the middle of the graph, while values less than 0.5 will fill to the left or bottom of the graph, and values greater than 0.5 will fill the other sides. If reverse is set to true, the normalized value is subtracted from 1.0.

Data Sets are drawn in the order they are listed, and multiple data sets can draw to the same location. One way to make use of this feature is to have multiple colored lamps that draw in the same location with different criteria (for instance, an amber lamp when fuel is between 10% and 25%, and a red lamp when fuel is below 10%).

JSIHeadsUpDisplay

This background handler is intended to represent a 2D type flight display, such as what one might use for a heads-up display in an aircraft, as opposed to the more space-oriented navball. It includes a number of configurable features that can make it useful for far more than just a HUD / PFD.

In particular a set of configurable vertical bars are supported. In a HUD, they could be used to display altitude and vertical speed. However, they can be used without the horizon texture and heading texture, so that one could have scrolling graphs or gauges as the background of any page.

			BACKGROUNDHANDLER
			{
				name = JSIHeadsUpDisplay
				method = RenderHUD
				...configuration options go here.
			}

Configuration Options:

  • backgroundColor -- The color of the background of this page.
  • cameraTransform -- The name of an optional cameraTransform to use as a background to the HUD. Allows for overlaying the HUD on an "out-the-window" view.
  • drawingLayer -- The layer to use for rendering. Defaults to 17 (and it shouldn't need to be changed, normally).
  • headingBar -- The name of the texture to use for rendering the HUD's horizontal heading strip. If omitted, no heading strip is drawn.
  • headingBarPosition -- <xPosition>, <yPosition>, <width>, <height> the X and Y coordinates (measured where from the top-left corner of the display) and the width and height of the heading bar, all measured in pixels.
  • headingBarProgradeTexture -- An optional URI to a texture to use for the prograde icon (sideslip indicator) on the heading bar. If this texture is not listed, the stock prograde icon is used.
  • headingBarWidth -- The portion of the heading bar texture, in texels, that will be visible within the aforementioned rectangle.
  • horizonEnableVariable -- Optional, a variable that can be used to control when the HUD ladder is rendered. If not present, the ladder is always rendered.
  • horizonEnableRange -- Optional, two values (numbers or Defined Variables). When the horizonEnableVariable is within the range, the HUD ladder is rendered. If the variable is outside that range, it is not.
  • horizonOffset -- By default, the HUD ladder is centered in the window. If you wish to move it off-center, horizonOffset is the <horizontal>,<vertical> distance it will be moved in pixels.
  • horizonSize -- <width>, <height> The size of the area where the horizon texture should be drawn, in pixels. The horizon is drawn centered in the display.
  • horizontalBar -- A semi-colon delimited list of JSIHUD_HORIZONTAL_BAR configurations to be used for the moving horizontal data bars in the display. Note the order the bars are listed will control the order of the bars when drawn (those earlier in the list will draw above those later in the list), allowing for overlapping horizontal bars.
  • horizonTexture -- The name of the texture to use for rendering the HUD's artificial horizon / ladder. If no name is specified, the horizon is not drawn. For a 360 degree texture, the 0 degree pitch position is the middle of the texture (vertically). +90 is half way between the center and the top of the image, and -90 is half way between the center and the bottom of the image. For a 180 degree texture, 0 is again in the middle, +90 is at the top, and -90 is at the bottom.
  • horizonTextureSize -- <width>, <height> The portion of the horizon texture (in texels) that should be drawn within the horizon area when the craft is wings level. For instance, if the horizon texture is 256 texels wide, and horizonTextureWidth is 128, then the middle 128 texels of the texture (from column 64 to 192) will be visible when the craft has a roll of 0. The area outside the horizonTextureWidth region will only be visible when the craft is rolled to the side.
  • hudFov -- The field of view of the optional HUD camera, in degrees. Defaults to 60.
  • iconPixelSize -- The size of the prograde icon, in pixels. Defaults to 64.
  • ladderProgradeTexture -- An optional URI to a texture that will be used to mark the prograde vector (AoA) on the ladder. If this field is omitted, the stock prograde icon is used.
  • progradeColor -- The color of the prograde icon used to show slip and angle-of-attack on the heading bar and the pitch ladder, respectively. Defaults to (214, 250, 0, 255).
  • showHeadingBarPrograde -- Indicates whether a prograde icon is displayed in the heading strip (as a proxy for a slip indicator). Defaults to true.
  • showLadderPrograde -- Indicates whether a prograde icon is displayed in the ladder / horizon (as a proxy for angle of attack). Defaults to true.
  • staticOverlay -- An optional overlay texture that is drawn after everything else has been drawn.
  • use360horizon -- Defaults to true. Indicates whether the horizonTexture is a 360 degree pitch texture (when true) or a 180 degree pitch texture (when false). The horizon texture clamps, so a 180 degree texture will show nothing "above" the 90 degree pitch mark, and nothing "below" the -90 degree pitch mark.
  • verticalBar -- A semi-colon delimited list of JSIHUD_VERTICAL_BAR configurations to be used for the moving vertical data bars in the display. Note the order the bars are listed will control the order of the bars when drawn (those earlier in the list will draw above those later in the list), allowing for overlapping vertical bars.

Horizontal and Vertical Bar Gauges

The HUD supports an arbitrary number of bar gauges. Each vertical bar graph must be defined in its own JSIHUD_VERTICAL_BAR config node, and each graph needs to have a unique name. More than one HUD can use a given bar graph config. Each horizontal bar is defined in a JSIHUD_HORIZONTAL_BAR.

  • enablingVariable, enablingVariableRange -- An optional defined variable and range of values to control when the bar is visible. If these values are omitted, the bar is always visible. If the values are present, the bar is only visible when the enablingVariable falls in the range specified.
  • textureName -- The name of the texture to use for rendering a vertical bar gauge on the HUD.
  • position -- <xPosition>, <yPosition>, <width>, <height> The position and size of the bar gauge, in pixels relative to the top-left corner of the screen.
  • scale -- <minimum>,<maximum> The minimum and maximum values of the variable used for the bar. Results outside of this range are clamped to these limits.
  • textureLimit -- <minValuePosition>, <maxValuePosition> The pixel locations (measured from the top of the texture for vertical bars, left of the texture for horizontal bars) that correspond to the minimum and maximum values of the bar.
  • textureSize -- The height of the visible portion of the vertical bar texture, in texture pixels, or the width of the visible portion of a horizontal bar texture. The current value is always centered in the vertical/horizontal bar.
  • variableName -- The variable used to control this graph. See Defined Variables.
  • useLog10 -- Optional, defaults to false. When this Boolean is set to "true", the result of evaluating variableName and scale are rescaled as follows: for values between -1 and +1, the value is unchanged. For values outside that range, the value becomes (1 + log10(abs(value))) * sign(value). For instance, 10.0 becomes 2, and -100.0 becomes -3. This allows for the creation of gauges that are less precise the farther away from 0 the value becomes. When using one of the variables that end in "LOG10", set it to false.

Updating HUDs from v0.20.0 or Earlier

RPM v0.21.0 introduced a new configuration setup for the vertical bars that is not backwards compatible. Config files using the old system must be updated. For the most part, it should be straightforward to update the old configs to the new format - look at the variables above and the section below to see what variables need to be transferred. Some specific changes: vertBar?Texture is now called textureName. vertBar?Limit is now called scale. Both of these changes get the HUD config closer to other configs (like JSIActionGroupSwitch and JSIVariableAnimator).

Vertical Bar Configuration Example

The vertical bars have a number of configuration parameters, all of which are required for the vertical bars to work well. While they are described above, here is an example to help illustrate how they're used:

Let's say we want a radar altimeter that tells us how high above the surface we are. We don't really care about tracking altitude above 10km, and we know we're never going to be below ground. We have a texture, /myHUD/radarAltTexture, that is 128 pixels wide and 1024 pixels high. It has a log10 scale (as described above under useLog10), with the 0 mark at (0, 878) and the 10000 mark at (0, 146). We want this on the left side of the screen. We set up the basic parameters as so:

JSIHUD_VERTICAL_BAR
{
name = MyRadarAltOceanGauge
texture = /myHUD/radarAltTexture
useLog10 = true
variableName = RADARALTOCEAN
scale = 0, 10000
position = 0,0,128,640
}

Since the 0 mark is at y=878 and the 10000 mark is at y=146 in the texture, we add

textureLimit = 878,146

We decide we want 256 pixels of the texture (about 1/4 of its height) to be visible at any given time, so we finally add

textureSize = 256

Vertical bar textures clamp (that is, they do not wrap around from top to bottom), so it is safe to have very small top and bottom margins.

Now, to use that config in a HUD, all we have to do is add MyRadarAltOceanGauge to the list of gauges in verticalBar in the HUD config.

JSIOrbitDisplay

The JSIOrbitDisplay background handler draws a representation of the current vessel's orbit, along with circles marking the planet / moon / sun that the vessel is orbiting (and the extent of that body's atmosphere, if applicable). MapView icons for the vessel, Ap, Pe, AN, DN, and maneuver node are drawn on the orbit.

If a vessel in the same SoI is targeted, the target vessel's orbit is drawn, along with the target's position and its Ap and Pe. If a maneuver is planned, the resulting orbit is drawn, as well.

The display rescales and moves each update as needed to keep the current vessel's orbit on screen.

			BACKGROUNDHANDLER
			{
				name = JSIOrbitDisplay
				method = RenderOrbit
				...configuration options go here.
			}
  • backgroundColor -- The color that the screen is cleared to prior to rendering.
  • iconColorSelf -- The color used to render the current vessel's icon on the display.
  • orbitColorSelf -- The color of the current vessel's orbit.
  • iconColorTarget -- The color of the targeted vessel, if applicable.
  • iconColorShadow -- The color of icon drop shadows.
  • iconColorAP -- The color of the apoapsis icon on the current vessel's orbit.
  • iconColorPE -- The color of the periapsis icon on the current vessel's orbit.
  • iconColorClosestApproach -- The color of the tick marks denoting the ship and target vessel's position at closest approach.
  • orbitColorNextNode -- The color of the orbit that will be in effect after executing the next maneuver node, if applicable.
  • orbitDisplayPosition -- <left>, <top>, <width>, <height> The region of the screen that JSIOrbitDisplay will draw to. Using less than the full area of the screen allows for header and/or footer text to render without the text hiding parts of the orbit display. All values are in pixels.
  • iconPixelSize -- The size, in pixels, of the various orbital icons.
  • iconShadowShift -- The offset of the icon shadows.
  • orbitPoints -- The number of subdivisions used to render the various circles, ellipses, and hyperbolae on the display.

JSIPrimaryFlightDisplay

This background handler might be used to construct a Primary Flight Display, which is mostly a flat representation of a stock-like navball with extra bells and whistles. This is accomplished by placing a real model into the scene and taking pictures of it with a camera, which involved far more dirty hacks than I would like, but looks very neat.

			BACKGROUNDHANDLER
			{
				name = JSIPrimaryFlightDisplay
				method = RenderPFD
				buttonClickMethod = ButtonProcessor
				...configuration options go here.
			}

Configuration options:

  • backgroundColor -- The background color of the screen. Defaults to black, but if you want a clear screen you might want to try 0,0,0,0 instead.
  • ballOpacity -- The opacity of the ball image. Defaults to 0.8, 1 being the highest (fully opaque).
  • drawingLayer -- There is considerable confusion about which Unity object layers are available to safely use in KSP for a purpose like this. Apparently, 17 is unoccupied, so this is the default. Altering it to something else can produce amusing results or actually be an improvement.
  • headingAboveOverlay -- If set to true, heading bar will be drawn above the overlay texture, otherwise below. Defaults to false (heading bar below overlay).
  • headingBar -- Texture URL of the heading bar, i.e. compass. You want it to be a long, thin horizontal ribbon that loops, starts at 0 degrees and covers the entire 360.
  • headingBarPosition -- x,y,width,height of the heading bar, in units.
  • headingSpan -- How much of the heading texture should be visible on the heading bar at any given time. Defaults to 0.25, meaning 1/4 of the heading bar texture is visible.
  • horizonTexture -- The texture URL for the actual navball. This parameter is optional, if it is not present, the bundled texture from the Library will be used.
  • navBallCenter -- the pixel coordinates of the middle of the navball.
  • navBallDiameter -- the diameter of the navball, in pixels.
  • navBallModel -- The model URL for the actual navball. This parameter is optional, if it is not present, the bundled model from the Library will be used. When making your own, you want it to be mapped in such a way that the point marking 0,0,0 on the ball is the one you see if you look from a camera positioned in Z+ direction. Unless there's a pressing reason to make a new model, you should probably stick with the Library model and change the texture using horizonTexture.
  • progradeColor, maneuverColor, targetColor, normalColor, radialColor, dockingColor, waypointColor -- Colors of the respective markers. "Docking" is the target dock orientation marker. Since marker alpha color is used to enable ghosting, alpha in these colors will be ignored. If waypointColor is not defined, the waypoint icon will use the same color as the icon on the regular (game interface) NavBall.
  • speedModeButton -- Number of globalButton pressing which will switch speed display mode, which affects what prograde/retrograde markers actually designate. Defaults to 4. The effect is the same as clicking the speed indicator in normal GUI or clicking the InternalSpeedDisplay prop, so it's not exactly required -- if you don't wish to use it, set this value to -1 or omit the "buttonClickMethod" option.
  • staticOverlay -- The texture URL for static overlay elements of the navball assembly -- the 'plane' in the middle and other things.

Updating from v0.20.0 or Earlier

The PFD / navball code was significantly redesigned in v0.21.0.

The following configuration fields were completely removed: ballIsEmissive, ballColor, cameraSpan, cameraShift.

The following fields changed:

  • markerScale is now markerSize, and it indicates the size of the markers (prograde, etc) in /pixels/.
  • headingBarPosition now defines the center position and size of the heading bar in units of pixels as (center X, center Y, width, height).

The following fields were added: navBallCenter, navBallDiameter.

The texture used for static overlays now only needs to cover the exact area of the screen, instead of potentially being bloated to fit if cameraSpan was not 1.0.

JSISCANsatRPM

NOTE: SCANsat RPM is part of the SCANsat mapping plugin. This documentation may be outdated. This is a case of a background handler that interoperates with an alien plugin that I neither wrote nor include in the package -- it started out as a separate DLL, and went on to become part of it, so technically, it should be documented with it, but for the moment this section of the documentation will remain.

This background handler will access the maps collected by the SCANsat mapping plugin and display them, marking them up with icons denoting things of interest. It lives within SCANsat.dll and is not available without it. If you set up a monitor page to use it, and SCANsat is not installed, the monitor will still work, you just won't have anything on the background on the particular page that calls it.

Caveats:

  • SCANsat map drawing routine assumes that pixels are square, i.e. that if your monitor texture is 512x256, the monitor is twice as wide as it is tall when in the IVA itself. Plan accordingly. While it is possible to correct for this during rendering in theory, it turned out to be easier to adjust the screen texture size instead.

  • This module makes use of globalButtons functionality, and is not particularly fun without it, so it is recommended to put it in a monitor that has at least four such buttons.

      		BACKGROUNDHANDLER
  		{
  			name = JSISCANsatRPM
  			method = MapRenderer
  			buttonClickMethod = ButtonProcessor
  			pageActiveMethod = PageActive
  			...configuration options go here.
  		}

Configuration options:

  • buttonUp -- Number of the globalButton that will zoom the map out.
  • buttonDown -- Number of the globalButton that will zoom the map in.
  • buttonEnter -- Number of the globalButton that will switch between relief, slope and biome map drawing modes.
  • buttonEsc -- Number of the globalButton that will switch between color and grayscale map drawing modes.
  • buttonHome -- Number of the globalButton that will switch between showing and not showing trails and orbits.
  • maxZoom -- Maximum zoom level. The first zoom level will make SCANsat fit the map width, rather than height to screen. To adjust for this if you don't have a 2x1 screen, you can use the zoomModifier parameter.
  • zoomModifier -- You want to adjust this value so that the lowest zoom level does not wrap the map vertically, it defaults to 1.5, but that's what it was for the testing screen, yours is probably different. You want to do it because otherwise, orbits may not get drawn correctly.
  • iconPixelSize -- The icons will be this size in pixels when drawn onto the screen. The module uses stock map icons, which are square.
  • iconShadowShift -- Defaults to 1,1. Icons will have drop shadows drawn at the position offset by this number of pixels.
  • redrawEdge -- SCANsat takes quite a while to redraw the map and drops the framerate quite a lot while it's in progress. (The computations involved are massive, and while there are faster methods to assemble a texture in memory pixel-by-pixel in Unity, they're tremendously difficult to use.) To do it less often, the plugin will only redraw the map itself when the marker denoting the active ship moves sufficiently far to the edge of the screen to warrant it. This value controls how far exactly, and defaults to 0.8, i.e. 80% counted from the opposite edge. This calculation pretends the screen is square, so on non-square monitors, this will be less than 80% of the width of the screen.
  • iconColorSelf -- Color of the ship icon.
  • iconColorTarget -- Color of the icon denoting the target vessel. This icon will not be drawn if there is no target or the target is not a vessel. (KSP does not natively have any provision to target a spot on the ground no matter what MechJeb might want you to believe.)
  • iconColorUnvisitedAnomaly -- Color of anomalies that have not been detail scanned yet.
  • iconColorVisitedAnomaly -- Color of anomalies that have been detail scanned.
  • iconColorShadow -- Color of the icon shadows.
  • iconColorAP, iconColorPE -- Color of apoapsis and periapsis icons on all orbits, respectively.
  • iconColorANDN -- Color of the icons for ascending and descending nodes.
  • iconColorNode -- Color of the icon of the maneuver node and projected post-node orbit.
  • orbitPoints -- The module will attempt to draw the orbit of the vessel and the target vessel (if any) for the next orbital period. The orbits will be drawn with the same color as the icons of the vessel and the target respectively. This parameter sets the resolution of the line, i.e. how many individual points will be used to calculate it -- try to set the lowest you think looks good. Setting this to 0 will turn off the drawing of orbits.

Positioning the scale bar

The module can display the scale of the map in kilometers using the scale bar, which requires two textures -- one for a horizontal bar, which will be resized to fit the appropriate number of meters on the map, and another to display a label saying how long the bar is. (There is, unfortunately, no opportunity to report this to the monitor itself, so it has to be done this way.)

  • scaleBar -- Texture for the scale bar itself. 4 pixels from every edge will not be scaled when stretching the bar.
  • scaleLabels -- Texture for the scale labels. Labels must be arranged on it vertically in descending order and have the same size.
  • scaleLevels -- A comma-separated list of values in meters corresponding to each label.
  • scaleBarPosition -- x,y of the bottom left corner of the bar, in pixels, from the bottom left corner of the screen.
  • scaleBarSizeLimit -- Every time the scale bar is to be drawn, the length it would take in pixels is computed and checked against this limit. If it is higher than this limit, the next highest value in scaleLevels will be used.

The labels are always displayed immediately to the right of the bar itself, the height of the bar on screen is equal to the height of the label. The height of an individual label is computed based on their number and the height of the texture containing them.

Trails

The map module can draw trails depicting the path the vessel actually took. Trails are time rather than space dependent and they will not persist.

  • trailLimit -- Number of trail points to remember, defaults to 100. If you do not want to show trails, set it to 0.
  • trailColor -- Color of the trail line.
  • trailPointEvery -- Number of seconds that elapse between trail points. Defaults to 30.

Map markup

JSISCANsatRPM supports marking up the map with lines defined as a chain of longitude/latitude points on the sphere, which lets you draw airstrip approach "funnels" and otherwise draw on the map itself. The lines are drawn exactly like the orbits and trails are, i.e. with vectors.

A markup line is defined using a top-level config section "JSISCANSATVECTORMARK", which needs to be in it's own .cfg file. The file can be located anywhere at all, all markup sections defined anywhere in any file within GameData will be drawn. (Unfortunately that means they will only refresh if you reload the GameDatabase, which somewhat complicates editing.) Each section draws exactly one line, from start point to end, i.e. it draws a line between each consecutive pair of points. One file can contain any number of sections. For example:

JSISCANSATVECTORMARK
{
	body = Kerbin
	color = 255,0,0,128
	vertex = 0,0
	vertex = 0,5
	vertex = 5,5
	vertex = 5,0
	vertex = 0,0
}

body is the name of the celestial body the section applies to, color is the color to draw the line with -- it is optional and defaults to white. vertex points are <longitude>,<latitude>, i.e. x,y, expressed as degrees with fractional values. This example will draw a square on the map of Kerbin, which starts in longitude 0, latitude 0, goes on to 0,5 and eventually loops back to 0,0 completing the square, using a red color with alpha value 0.5. You can use www.kerbalmaps.com to look up coordinates of the points -- remember that it lists latitude above longitude, while JSISCANsatRPM wants longitude first, latitude second.

JSIVariableGraph

This background handler will draw a nice time-based graph of whichever variables you wish. (See Defined variables) Limitations:

  • There is no hard limit of number of variables per graph, but all the variables within the same graph will be graphed to the same scale.

  • Graph data points will not persist.

      BACKGROUNDHANDLER
  {
  	name = JSIVariableGraph
  	method = RenderGraphs
  	...configuration options go here
  }

Configuration options:

  • graphSet -- Name of the graph set to draw, see below. Required.
  • graphRect -- <left>,<bottom>,<right>,<top> -- Edges of the graph on the screen, in pixels, counting from the bottom left corner of the screen.
  • xSpan -- Number of seconds that fits in the graph across X.
  • ySpan -- <minimum>,<maximum> -- Minimum and maximum of the graph across Y.
  • secondsBetweenSamples -- How often will the values be sampled for inclusion in the graph. Defaults to once per 0.5 seconds.
  • borderColor -- Color that will be used to draw the lines denoting the edges of the graph. Defaults to white.
  • borders -- 0, 2 or 4. If 0, no borders will be drawn. If 2, two lines will be drawn - the minimum X and minimum Y, this is the default. If 4, all four borders will be drawn.
  • backgroundColor -- Defaults to black.
  • backgroundTextureURL -- If this URL is present, that texture will be used for background instead of the color.

Defining graph sets

Due to limitations of KSP's configuration reading system, graph sets need to be defined in a separate file. This file must have the .cfg extension, but can be located anywhere within GameData, the appropriate block will be found by name:

JSIGRAPHSET
{
	name = ExperimentalGraphSet
	GRAPH
	{
		variableName = ALTITUDE
		color = 255,0,0,255
	}
	GRAPH
	{
		variableName = HORZVELOCITY
		color = 0,255,0,255
	}
}
  • color -- Color the graph line will be drawn with.
  • floatingMaximum,floatingMinimum -- If either of these parameters is present, the graph of this particular variable will ignore the ySpan settings regarding the minimum and maximum vertical span values -- instead, they will be computed to make the minimum of the graph correspond to the smallest recorded and maximum to the highest recorded value respectively.
  • variableName -- Name of a defined variable. You can obviously only use variables that return numbers. You can use a number in place of a variable, which will result in a straight horizontal line, although you probably don't want to.

You can have any number of separate graph sets or any number of individual variables within the graph set.

Clone this wiki locally