What BlackBox Does:

BlackBox constructs an xml diagnostic gauge that can be used to display in readout form the numerical or string values of all or selected A:, E:, P:, L:, C:, G:*, and @c and @g macro (related to the FS9 or FSX gps module) variables of the gauge you are editing/building. It can display important parameters such as boolean, L: and A: variables that are not often displayed directly by the gauge you are building. As such, it is very useful for debugging xml gauge logic; you can see what the variables are actually doing as MS Flight Simulator flies.

Initial Operation:

  1. Launch BlackBox.
  2. Select the File icon located on the toolbar and ‘Open’ the gauge.xml file you are editing/building.
  3. BlackBox will list all variables except G: found in your gauge. Included in the list are any FS gps.dll variables called by @c or @g macros in your gauge's xml code. After opening your gauge (Step 2), select or de-select the variables that you want displayed as Flight Simulator runs. G: variables cannot be read by other gauges and, consequently, the BlackBox xml gauge will not have access to your gauge’s G:Vars. Because of this, BlackBox will overlook your G: variables. Read the suggested workaround for this limitation, below.
  4. BlackBox initially lists the variables by order of occurrence in your xml file. If you wish to sort the BlackBox readout display differently, select the Sort icon from the toolbar to sort the variables according to Type, Name, Units, order of Occurrence, or Selected variables.
    Note - your gauge xml file is never affected by BlackBox – sorting only changes the order that BlackBox displays the variables.
  5. Select the File icon from the toolbar again, choose Save As and give the BlackBox output file a name such as 'VarList'. Blackbox will create an xml file named VarList.xml. The full directory path of the ‘VarList’ xml file is displayed on the bottom BlackBox toolbar. As an example:
    C:\Program Files\Microsoft Games\Flight Simulator 9\Aircraft\F1_Cessna_421\Panel\Custom_Gauges\VarList.xml
    Note that it isn’t necessary to .cab your gauge or BlackBox xml files as you are building your gauge.
  6. Minimize or close BlackBox.
  7. Edit your panel.cfg file to add the new VarList gauge – something like: 
    gaugeNN=Custom_Gauges!VarList,		420, 10, 200, 500
  8. Run MS Flight Simulator. The BlackBox ‘gauge’ appears as a list of the selected variables and their associated real-time values. It uses white lettering on a clear background (using the ‘Size’ tag rather than a bitmap image) usually best positioned high on the screen in the ‘sky’, or in a separate un-docked window. Default syntax is !10.2f! for most variables. Exceptions are booleans which are displayed as !10d! and Latitude or Longitude variables which are displayed as !10.4f!. Lastly, BlackBox displays any A: or L: variable with 'string' units and gps.dll string variables as !10s!.

Subsequent Operation:

After you make further edits/additions to the gauge you are building, or if you just want to select different variables to display in BlackBox –


  1. Maximize or open BlackBox. It remembers the file names, file paths and selected variables that you were last working on.
  2. Select Reload from the bottom toolbar. This will update BlackBox with the latest variables added or changed in the gauge you are building. If the variables have changed since BlackBox output was last saved, an asterisk will appear next to the file path\name on the bottom tool bar.
  3. Select or de-select variables that you want displayed.
  4. Select the File icon from the toobar and choose Save. This will save your new selections by overwriting the file VarList. Alternatively, you can choose Save As to give the BlackBox gauge a new file name. In this case, of course, you will need to edit panel.cfg again to change the BlackBox gauge name or add another BlackBox gauge – something you might want to do to display variables from more than one gauge.
    Hint - Use the keyboard shortcut ctrl+S to speed up the process of saving your updated BlackBox file.
  5. Run MS Flight Simulator.

Displaying GVars:

Add the following in the <Update> section of the gauge you are editing/building:

(G:Var1) (>L:GVar1,number) (G:Var2) (>L:GVar2,number) (G:Var3) (>L:GVar3,number)
(G:Var4) (>L:GVar4,number) (G:Var5) (>L:GVar5,number) (G:Var6) (>L:GVar6,number)
(G:Var7) (>L:GVar7,number) (G:Var8) (>L:GVar8,number) (G:Var9) (>L:GVar9,number)

BlackBox will list variables named L:GVar1 through L:GVar9. The GVar values that your gauge generates can now be displayed as L:GVar1, etc. It is suggested that you delete or comment out the (G:Var1) (>L:GVar1,number) … lines from your gauge when you are finished editing it.

Displaying Other FS generated variables:

To display any variable that MS Flight Simulator generates even if it is not included in your gauge’s xml code, add the variable name(s) to your gauge within a comment, for example:

<!-- (A:AUTOPILOT GLIDESLOPE HOLD,bool) (A:GROUND ALTITUDE,feet) -->

BlackBox parses your gauge file for parentheses and gauge name syntax, so it can find variable names even within a comment. Because Flight Simulator generates A:, E:, P:, C: and FS gps.dll values, it will not matter to BlackBox that the variables are part of a comment in your gauge.

Modifying BlackBox Display:

To modify the BlackBox display to change, for example, number format, font or font color, open BlackBox.jar with an archiving program such as 7-Zip, WinZip or WinRar. In the 'res' folder, you will find several .xml files that can be edited to achieve the desired display format. The line.xml file can be edited to change font and font color. The formatting.xml file contains default number format definitions, a list of the gps.dll variables that require string syntax according to the FSX SDK, and Latitude and Longitude variables that should display at least 4 decimal places. Edit this file to change number or string format. The BlackBox gauge 'background' can be changed by editing prefix.xml, where, for example, a bitmap can be substituted in place of the Size tag.

Scrolling Option:

If your BlackBox selection list is especially long, you may want to scroll up and down the list as Flight Simulator runs in order to see particular variables. To permanently enable scrolling:


  1. Edit both the prefix.xml and suffix.xml files to remove the comment (<!- - and - - >) identifiers.
  2. Copy the BBScroll.bmp file into the directory that contains the BlackBox output file - for example, into the Custom_Gauges folder following the examples above.

To scroll, Left click and hold the Up or Down arrow or use the mouse wheel when the mouse cursor is over the Up/Down arrow bitmap.

BlackBox File Information:

Input File: Any text file can be read by BlackBox. Normally, the input file will be the xml gauge file you are editing/building. However, .txt, .ini, .doc, etc. text files can also be read and parsed for FS xml gauge syntax.


Output File: BlackBox prevents saving the output file using 'SaveAs' with the same name as the input file to avoid accidentally overwriting the gauge you are editing/building. As an additional safeguard, the following comment is added as the first line of BlackBox output files:

<!-- BlackBox Test Gauge -->

BlackBox will not save it's output file using 'Save' or 'ctrl+S' unless this comment appears as the first line of the file. This is meant to prevent accidental saving using 'Save' to an xml file not generated by BlackBox.

The BlackBox display in MS Flight Simulator:

Screenshot showing BlackBox display (the VarList.xml gauge) to the left of a work-in-progress attitude display gauge. The numbers displayed are real-time values of a selection of variables from the xml code generating the attitude gauge on the right.


BlackBox Screenshot
Screenshot of BlackBox (with scrolling enabled)