Template:Featured article

From FSAirlinesWiki
Revision as of 18:39, 20 November 2010 by Alasizon (Talk | contribs)

Jump to: navigation, search
Featured article: Blackbox

The Blackbox is a Client module running during flight and recording certain events which can be defined in a xml file. There are two output possibilities:

  • Text output to the flight log. The text is uploaded together with the flight report and can be viewed on the website after the flight.
  • Immediate sound output. User-defined wav-files can be played immediately when an event occurs.

With these two options it's possible to record predefined flight states for a more detailed flight analysis and to enhance the flight environment with sounds. You could for example play a flight attendant announcement sound when you reach a certain altitude or some Co-Pilot sounds when the it's time to turn off the landing lights... there are endless possibilites. The Client comes with a basic blackbox file to get you started but you can easily adapt it to your own needs. If there's something you're missing or if you need help please don't hesitate to ask in the forums.


Blackbox Packages

If you created your own blackbox.xml and want to share it with others, please add a link here. In case you don't have webspace on your own you can always contact the devs and they will upload it to the fsairlines server, thanks :).

Link Description
FSAirlines Client The standard blackbox package coming with the Client. Includes some gear, flaps and landing light info plus an applause sound when the aircraft touches ground.
Blackbox by Erwin Polreich Standard-Blackbox with some extra warnings, as for instance "switch on/off landing lights!" or "too fast!". A more detailed description of the extensions and the installation guidance is contained in the zip-file.

Configuration

The configuration of the Blackbox is saved in the blackbox.xml file which resides in the Client data folder. This xml file can be freely edited with any text-editor using the following commands.

General structure

The blackbox.xml basically only consists of a couple of event tags encapsulated by the blackbox tag. Each of these event tags contains attributes describing the event to record. The following example is the standard blackbox.xml coming with every Client release:

<blackbox>
  <event var="landinglights" value="1" method="equal" multiple="1" text="Landing Lights on" />
  <event var="landinglights" value="0" method="equal" multiple="1" text="Landing Lights off" />
  <event var="gear" value="1" method="equal" multiple="1" text="Gear down" />
  <event var="gear" value="0" method="equal" multiple="1" text="Gear up" />
  <event var="flaps" value="1" method="equal" multiple="1" text="Flaps 100%" />
  <event var="flaps" value="0.5" method="equal" multiple="1" text="Flaps 50%" />
  <event var="flaps" value="0" method="equal" multiple="1" text="Flaps retracted" />
  <event var="vs" value="-200" method="greater" multiple="0" flightstate="landed" sound="snd_applause.wav" />
</blackbox>

Event criteria

As you can see in the example above each event tag consists of several attributes defining when to activate the event. Let's take the first line as an example:

<event var="landinglights" value="1" method="equals" multiple="1" text="Landing Lights on" />

First of all there is var, defining which Flight Simulator variable is tested. In this case the value is landinglights which means that the Client checks the landing lights status. The following attribute is value. This is the reference value for the Client. Together with the method attribute the Client can then test the current status of the variable to see if the event has to be activated. So, the first three attributes can be read as: "If the status of the landing lights equals 1, then activate the event".

There are additional attributes for more control over the event activation. These are multiple and flightstate. If multiple is set to 1, then the event can be activated several times. So in this case each time the landing lights are turned on, the event gets executed. Setting this value to 0 would only allow this event to be activated the first time the landing lights are turned on. The flightstate attribute restricts the event activation to a single flightstate. Hence if you only want the event to be activated during take off you could set this to takeoff.

Event actions

The final step is to tell the Client what happens when the event is executed. There are two possibilities: Text output to the log or immediate sound output. If you add the text attribute, the text will be shown in the log on the website.

If you add a sound attribute, the defined sound will be immediately played when the event is activated. The Client can play any .wav file which is located in the Client's sound directory. If you want to publish a blackbox.xml to your pilots don't forget to send them the required sound files. Let's give a little example here: Say you want to play a sound file called FL100.wav when the airplane climbs above FL100. First you create a folder for all your personal sound files inside your Client sound directory. This not mandatory but we recommend to do it this way so the different sound files don't get mixed up. We call it my_va. The Client sound folder looks like this then:

sounds/en/*.wav
sounds/my_va/FL100.wav

In the blackbox.xml we have to tell the Client to play this sound when the aircraft climbs above 10,000ft the first time. The final event tag looks like this:

<event var="altitudestd" value="10000" method="greater" multiple="0" sound="my_va/FL100.wav" />

Combination tag

The combination tag allows to check if multiple events are active at the same time. In other words you can check for a combination of events. The following example shows a combination of two events, the first one being activated when the aircraft climbs above 10000ft and the second one being activated when the landing lights are on. This means that the combination event will be activated when the landing lights are on above 10000ft.

<blackbox>
  <combination text="Landing Lights on above FL100" sound="lightsFL100.wav" multiple="0">
    <event var="altitudestd" value="10000" method="greater" multiple="1" />
    <event var="landinglights" value="1" method="equal" multiple="1" />
  </combination>
<blackbox>

Startflight tag

The startflight tag is activated immediately when you start the flight with the Client. You can add a sound and a text attribute to the startflight tag, all other attributes are ignored.

<blackbox>
  <startflight text="Flight started!" sound="boarding.wav" />
<blackbox>

Comments

With the blackbox.xml being a standard xml-file you can easily add comments between the single tags to improve the readability in bigger files. A comment starts with <!-- and ends with -->. Here is a little exampe:

<blackbox>
  <!-- log start of flight -->
  <startflight text="Flight started!" sound="boarding.wav" />
  <!-- log landing lights on -->
  <event var="landinglights" value="1" method="equal" multiple="1" />
<blackbox>

Overview

This section contains three tables giving you a quick overview over all the variables and options you can add to your own blackbox.xml.

Tags

Tag Attributes Description
event see Event attributes below See Event criteria and Event actions
combination text, sound and multiple from Event attributes table See Combination tag
startflight text and sound from Event attributes table See Startflight tag

Event attributes

Attribute Possible values Standard value
var altitudeagl
altitudestd
flaps
gear
ias
landinglights
vs
flightstate
aircrafttype
destination
closestairport
ias
value depends on variable (see Event variables table below) 0
method less
equal
greater
equal
multiple 0
1
0
flightstate boarding
taxi
takeoff
climb
cruise
descent
landed
undefined
text any text up to 255 characters undefined
sound relative path from Client sound directory to .wav file undefined

Event variables

Variable Values Description
landinglights 0 or 1 Status of the landing lights. 1 = on, 0 = off.
gear 0 or 1 Status of the gear. 1 = down, 0 = up.
flaps 0.0 - 1.0 Status of the flaps. 0 = fully retracted, 1 = fully extended.
ias 0 - 9999 Indicated airspeed (knots).
groundspeed 0 - 9999 Ground speed (knots).
vs -9999 - 9999 Vertical speed (fpm).
altitudestd 0 - 999999 Altitude above 1013.25hP (Standard atmosphere) in feet.
altitudeagl 0 - 999999 Altitude above ground level (feet).
flightstate 0 (Boarding)
1 (Taxi)
2 (Take Off)
3 (Landed)
4 (On Block)
5 (Climb)
6 (Cruise)
7 (Descent)
8 (Crashed)
The current flightstate. Use the correct number and method="equal".
aircrafttype XXXX The booked aircraft type. Use 4-letter ICAO designator (e.g. B744) and method="equal".
destination XXXX The destination of the booked route. Use 4-letter ICAO designator (e.g. KJFK) and method="equal".
closestairport XXXX The airport closest to the current aircraft position. Use 4-letter ICAO designator (e.g. KJFK) and method="equal". Updates only at the beginning of the flight and after touch-down.

Need more variables? Don't hesitate to ask in the forums!

Requested Additions

More features which have been requested:

  • Actual route flown distance
  • add a timer for events (e.g. event triggered after x secs/mins elapsed or event action occurs after a delay of x secs/mins)

Usage

These usage notes will not be included in articles bearing this template.

This article feeds the main page.