State overlay system

From FlightGear wiki
Revision as of 07:30, 4 April 2020 by Stuart (Talk | contribs) (Implementing state overlays in an aircraft)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Using the state overlay system, aircraft developers can add startup state overlays to an aircraft, that users can select when starting FlightGear.

Choosing a startup state

To start FlightGear with an existing state overlay add --state=statename to you command line.

In the launchers main tab, you can choose which state you want to start with:

States dropdown box in  launcher

If you choose the Automatic state, FlightGear will try to guess which state you want.

That guess is based on the name (inside the state file). It will look for these names:

  • parked (meaning cold and dark)
  • take-off (standing on the runway with take-off configuration)
  • cruise (cruise configuration)
  • approach (approach configuration)
  • carrier-approach (approach configuration for an aircraft carrier landing)
  • carrier-take-off (take-off configuration for an aircraft carrier take-off, typically via catapult)

Implementing state overlays in an aircraft

Create state overlay files

To add state overlays to your aircraft, create a folder for example called States. In there you can put your state overlay files. In the beginning a state overlay file should look like this:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<PropertyList>
  <name type="string">parked</name>
  <readable-name type="string">Parked</readable-name>
  <description type="string">Parked, cold and dark.  Everything switched off</description>

  <overlay>

  </overlay>
</PropertyList>

Now you can add your properties and values, which need to be set between the overlay tags. You only need to put properties in there that differ from your default setup. You should use the hierarchy of the root of the property tree.

Copying the property tree from the Nasal console

Note  This outputs the entire PropertyTree! This is several thousand lines long. You might want to dump only single folders of the property tree by changing the "/" to something like "/controls" or whatever folder you want to dump.

It is possible to dump the PropertyTree with a Nasal command. Open up the Nasal console from the developer menu and put in the following:

io.write_properties( path: "/home/myName/.fgfs/Export/PropTree.xml", prop: "/" );

Now you can simply delete everything from that file that you do not need and copy and paste it into your state overlay file.

Include state overlay files into the Aircraft-set.xml file

Now you need to include your state overlay file in your Aircraft-set.xml file like this:

<PropertyList>
  <sim>
    ...
    <state include="States/parked-overlay.xml" n="0" />
    <state include="States/taxi-overlay.xml" n="1" />
    ...
  </sim>
</PropertyList>

Setting gear state for YASim aircraft

By default, YASim will attempt to set the gear state (/control/gear/gear-down) depending on whether the aircraft is on the ground or in the air. To over-ride this behaviour and ensure that whatever you set in the overlay file is respected, set /fdm/yasim/respect-external-gear-state=true.

Background

Wayne Bragg has been working a bit with James on the state overly system.[1]

At this moment, the Citation, the Saab 37 Viggen, the J3 Cub, the Cessna 182s and the Tu-144 have this implemented.

References

References

Related content

Source code