State overlay system: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
m (Tu-144.)
(9 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Stub}}
Using the '''state overlay system''', aircraft developers can add startup state overlays to an aircraft, that users can select when starting FlightGear.


== Objective ==
== Choosing a startup state ==
<!--
To start FlightGear with an existing state overlay add <code>--state=statename</code> to you command line.
https://sourceforge.net/p/flightgear/mailman/search/?q=aircraft+%2B+state+%2B+overlay
 
-->
In the launchers main tab, you can choose which state you want to start with:
== Status ==
 
To start FlightGear with an existing overlay add <code>--state=statename</code> to you command line.
[[File:States dropdown box.png|States dropdown box in  launcher]]
 
If you choose the Automatic state, FlightGear will try to guess which state you want.


For now there is no definitive list of possible states. These are my first suggestions:
That guess is based on the name (inside the state file). It will look for these names:


* parking (meaning cold and dark)
* parked (meaning cold and dark)
* taxi (all systems running and ready to taxi)
* take-off (standing on the runway with take-off configuration)
* take-off (standing on the runway with take-off configuration)
* cruise (cruise configuration)
* cruise (cruise configuration)
* approach (approach 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)


== Implementation ==
== Implementing state overlays in an aircraft ==
=== overlay file ===
=== Create state overlay files ===
To add state overlays to your aircraft, create a folder called <code>states</code>. In there you can put your <code>$state-overlay.xml</code>. In the beginning your overlay.xml should look like this:
To add state overlays to your aircraft, create a folder for example called <code>States</code>. In there you can put your state overlay files. In the beginning a state overlay file should look like this:
<syntaxhighlight lang="xml">
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<PropertyList>
<PropertyList>
   <name type="string" n="1">parking</name>
   <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>


Line 28: Line 34:
</PropertyList>
</PropertyList>
</syntaxhighlight>
</syntaxhighlight>
Now you can put your items, which need to be set between the overlay tags. You only need to put properties in there, which differ from your default setup.
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 <code>"/"</code> to something like <code>"/controls"</code> or whatever folder you want to dump.}}
 
It is possible to [[Howto:Create_animation_XML_files_from_Nasal|dump the PropertyTree]] with a Nasal command. Open up the Nasal console from the developer menu and put in the following:


Another rule of thumb is that you use the hierarchy of the property-tree's root. It speeded up my research by quite a bit, when I found out, it's possible to [[Howto:Create_animation_XML_files_from_Nasal|dump the PropertyTree]] with a nasal command. Open up the Nasal-console from the developer-menu and put in the following: <code>io.write_properties( path: "/home/myName/.fgfs/Export/PropTree.xml", prop: "/" );</code>
io.write_properties( path: "/home/myName/.fgfs/Export/PropTree.xml", prop: "/" );


Beware! This outputs the '''entire''' PropertyTree! This is several thousand lines long. You might want to dump only single folders of the PropertyTree by changing the <code>"/"</code> to sth like <code>"/controls"</code> or whatever folder you want to dump. Now you can simply delete everything from that file, that you don't need and copy&paste it into your overlay.xml.
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 ===
=== Include state overlay files into the Aircraft-set.xml file ===
Now you need to include your overlay.xml in your <code>$Aircraft-set.xml</code> file like this:
Now you need to include your state overlay file in your <code>Aircraft-set.xml</code> file like this:
<syntaxhighlight lang="xml">
<syntaxhighlight lang="xml">
<PropertyList>
<PropertyList>
   <sim>
   <sim>
     ...
     ...
     <state include="states/parking-overlay.xml" n="0" />
     <state include="States/parked-overlay.xml" n="0" />
     <state include="states/taxi-overlay.xml" n="1" />
     <state include="States/taxi-overlay.xml" n="1" />
     ...
     ...
   </sim>
   </sim>
</PropertyList>
</PropertyList>
</syntaxhighlight>
</syntaxhighlight>
=== Setting gear state for YASim aircraft ===
By default, YASim will attempt to set the gear state (<code>/control/gear/gear-down</code>) 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 <code>/fdm/yasim/respect-external-gear-state=true</code>.


== Background ==
== Background ==
Line 59: Line 74:
At this moment, the [https://sourceforge.net/p/flightgear/fgaddon/HEAD/tree/trunk/Aircraft/Citation Citation], the [[Saab 37 Viggen]], the [https://sourceforge.net/p/flightgear/fgaddon/HEAD/tree/trunk/Aircraft/J3Cub J3 Cub], the [https://github.com/HHS81/c182s Cessna 182s] and the [http://wiki.flightgear.org/Tupolev_Tu-144 Tu-144] have this implemented.
At this moment, the [https://sourceforge.net/p/flightgear/fgaddon/HEAD/tree/trunk/Aircraft/Citation Citation], the [[Saab 37 Viggen]], the [https://sourceforge.net/p/flightgear/fgaddon/HEAD/tree/trunk/Aircraft/J3Cub J3 Cub], the [https://github.com/HHS81/c182s Cessna 182s] and the [http://wiki.flightgear.org/Tupolev_Tu-144 Tu-144] have this implemented.


== Motivation ==
== References ==
{{Appendix}}


== Related ==
== Related content ==
<!-- https://sourceforge.net/p/flightgear/mailman/search/?q=aircraft+%2B+state+%2B+overlay
-->
=== Source code ===
* {{flightgear source|path=src/Main/options.hxx}}
* {{flightgear source|path=src/Main/options.cxx}}
* {{flightgear source|path=src/Aircraft/initialstate.hxx}}
* {{flightgear source|path=src/Aircraft/initialstate.cxx}}


== References ==
[[Category:FlightGear feature]]
{{Appendix}}
[[Category:Startup related]]

Revision as of 12:30, 4 April 2020

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