Addon: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
(Major update and rewrite, mostly based on readme and comments in source files)
Line 1: Line 1:
{{Stub}}
[[File:Fgaddonslogo202x89.png|right]]  
[[File:Fgaddonslogo202x89.png|thumb]]  
To make it easier to create '''addons''' there is since FlightGear 2017.3 a new way to create addons. In essence FlightGear will load an overlay XML into the property tree and start a well known Nasal function.<ref>{{cite web
{{forum|10000|FlightGear Addons}}
   |url    =  https://forum.flightgear.org/viewtopic.php?p=314620#p314620
== Background ==
   |title  =  <nowiki> Re: New Feature: Addon - "API" </nowiki>  
{{See also|Howto:Creating a simple modding framework}}
   |author =  <nowiki> Torsten </nowiki>  
 
   |date  =  Jul 19th, 2017
ATC chatter was removed in 2015, see fgdata commit: [https://sourceforge.net/p/flightgear/fgdata/ci/81607f734e13add9be02816ddaec305d05bc4e47/ 81607f734e13add9be02816ddaec305d05bc4e47]
   |added  =  Jul 19th, 2017
 
and the devel list messages referenced in the commit log.
the other relevant commit is this: b60736ba7add2a7cd39af3d8a974d5be3ea46e8b
It would not be very difficult to restore this functionality, or even generalize/improve it significantly (which was the scope of the original discussion on the devel list)<ref>{{cite web
   |url    =  https://forum.flightgear.org/viewtopic.php?p=288388#p288388
   |title  =  <nowiki> Re: Whatever happened to radom radio  </nowiki>  
   |author =  <nowiki> Hooray </nowiki>  
   |date  =  Jun 11th, 2016
   |added  =  Jun 11th, 2016
   |script_version = 0.40  
   |script_version = 0.40  
   }}</ref>
   }}</ref>


The restored functionality could be distributed as a tarball that is extracted into $FG_ROOT - alternatively, into $FG_HOME, because Nasal files there are treated as overlays, which basically means that you can install user-specific extensions there without having to tamper with $FG_ROOT, it would only take  very minor changes to turn the chatter feature into a corresponding "addon" - not unlike fgcamera ...<ref>{{cite web
We now have a simple way to add addons to FlightGear without the need to mess around with <code>FGData/Nasal</code> or <code>FGHome/Nasal</code> directories.<ref name="Forum_announcement">{{cite web
   |url    =  https://forum.flightgear.org/viewtopic.php?p=288392#p288392
   |url    =  https://forum.flightgear.org/viewtopic.php?p=314563#p314563
   |title  =  <nowiki> Re: Whatever happened to radom radio  </nowiki>  
   |title  =  <nowiki> New Feature: Addon - "API" </nowiki>  
   |author =  <nowiki> Hooray </nowiki>  
   |author =  <nowiki> Torsten </nowiki>  
   |date  =  Jun 11th, 2016
   |date  =  Jul 18th, 2017
  |added  =  Jun 11th, 2016
  |script_version = 0.40
   }}</ref>
   }}</ref>


we should absolutely stop telling anyone to edit preferences.xml in FG_ROOT; any documentation or advice which says to should be changes ASAP. <ref>{{cite web
{{TOC limit|3}}
  |url    = https://forum.flightgear.org/viewtopic.php?p=192632#p192632
 
  |title  =  <nowiki> Re: NavCache:init failed:Sqlite error:Sqlite API abuse </nowiki>  
== Installing and using an addon ==
  |author = <nowiki> zakalawe </nowiki>  
Download and copy the addon to a directory on your computer.
  |date  = Oct 26th, 2013
 
  |added  =  Oct 26th, 2013
Use the command line switch <code>--addon=/path/to/some/addon</code>.<ref name="Forum_announcement"/>
  |script_version = 0.40
 
  }}</ref>
== Creating an addon ==
There is a very simple Skeleton addon available in FGAddon to be used as a template.<ref name="Forum_announcement"/> See {{fgaddon source|path=Addons/Skeleton}}.


As of 12/2017, the addon API is in the process of being significantly updated <ref>https://sourceforge.net/p/flightgear/mailman/message/36146017/</ref> <ref>https://sourceforge.net/p/flightgear/mailman/message/36150159/</ref> <ref>https://sourceforge.net/p/flightgear/mailman/message/36150444/</ref>
=== Minimum configuration ===
An addon may be installed in a directory anywhere on your hard disk and need at least two files:<ref name="Forum_announcement"/>


== Good to know ==
* <code>/config.xml</code> - A standard [[PropertyList XML files|PropertyList XML file]] to be used to populate or modify the [[property tree]]. (Same as to be used in <code>--config=foo.xml</code>)
this API does nothing more than loading a overlay XML into the property tree and starts a well known Nasal function<ref>{{cite web
* <code>/main.nas</code> - The Nasal hook for the logic. This file needs a function called <code>main()</code> which will be called from the global addon initializer (<code>addons.nas</code>)
  |url    = https://forum.flightgear.org/viewtopic.php?p=314620#p314620
  |title  =  <nowiki> Re: New Feature: Addon - "API" </nowiki>  
  |author =  <nowiki> Torsten </nowiki>  
  |date  =  Jul 19th, 2017
  |added  =  Jul 19th, 2017
  |script_version = 0.40
  }}</ref>


=== Additional common files ===
* <code>/addon-metadata.xml</code> - A PropertyList XML file with metadata about the addon it.
* <code>/addon-menubar-items.xml</code> - A PropertyList XML file describing menus to be added to the FlightGear menu bar.
* <code>/gui/dialogs/&lt;my-foobar-dialog&gt;.xml</code> - PropertyList XML files to create custom dialogs.


The new addon "API" lets you add a addon-config.xml to override the settings in defaults.xml.
=== Good to know ===
The new addon "API" lets you add a <code>addon-config.xml</code> to override the settings in <code>defaults.xml</code> and other files.


That easily allows to
That easily allows to
*  Override key bindings (as in the spoken atc addon)
*  Override key bindings (as in the spoken ATC addon)
*  Add or override autopilots and property rules
*  Add or override autopilots and property rules
*  And of course introduce XML-statemachines
*  And of course introduce XML statemachines


Unless your really want to add/change/remove those at runtime, this should cater for most use cases.<ref>{{cite web
Unless your really want to add/change/remove those at runtime, this should cater for most use cases.<ref>{{cite web
Line 74: Line 63:
   }}</ref>
   }}</ref>


== APIs ==
{{hatnote|For more details about these APIs, see the readme file, {{readme file|add-ons}}.}}
=== C++ API ===
There is a C++ API on FlightGear's side that handle some on the addon related tasks manly through the <code>AddonManager()</code>, <code>Addon()</code> and <code>AddonVersion()</code> classes.


* [[Property tree]]
== Addon initialization ==
* [[PropertyList XML File]]
On initialization fgfs takes care of:
* [[FlightGear configuration via XML]]
* Through {{flightgear source|path=src/Main/options.cxx|text=<code>options.cxx</code>}}:<ref name="Forum_announcement"/>
* [[Properties persistent between sessions]]
** Creating a property under <code>/addons/addon[n]/path=/path/to/some/addon</code>
* [[FlightGear_configuration_via_XML#preferences.xml]]
** Loading <code>/path/to/some/addon/config.xml</code> into the property tree (same as <code>--config=/path/to/some/addon/config.xml</code>)
* [[Nasal]]
** Adding <code>/path/to/some/addon</code> to the list of allowed directories (same as <code>--fg-aircraft=/path/to/some/addon</code>)
* Through {{fgdata source|path=Nasal/addons.nas|text=<code>addons.nas</code>}}:
** Loading <code>/foo/bar/baz/addon-main.nas</code> into namespace <code>__addon[ADDON_ID]__</code>
** Calling <code>main(addonGhost)</code> from <code>/foo/bar/baz/addon-main.nas</code>.
 
=== Nasal API ===
The Nasal add-on API lives in the 'addons' namespace and can for example do queries to <code>AddonManager()</code> and read data from <code>addons.Addon</code> objects.  It can for example compare addon versions if there is dependencies.
 
== Background ==
{{See also|Howto:Creating a simple modding framework}}


== Overlays ==
ATC chatter was removed in 2015, see fgdata commit: [https://sourceforge.net/p/flightgear/fgdata/ci/81607f734e13add9be02816ddaec305d05bc4e47/ 81607f734e13add9be02816ddaec305d05bc4e47]


Torsten ended up using a fairly clever method to come up with this idea for implementing addon support via PropertyList-XML overlays loaded via the --config argument - however, that also brings with it all the power for conflicting with stuff you are loading using the same mechanism, and/or any defaults you have customied. So just be aware of how this works - and again, kudos to Torsten for coming up with such a fancy approach to make this work, despite people arguing for the better part of a decade that FlightGear would not have "proper addon/modding" support" ... ;-)
And the devel list messages referenced in the commit log.
With that being said, it would probably be a good idea to formalize the whole method and stop using tons of embedded Nasal, and instead document/favor the use of io.load_nasal() and/or io.include() to load Nasal code from the addon directory.
the other relevant commit is this: b60736ba7add2a7cd39af3d8a974d5be3ea46e8b
Equally, such code should ideally wrap setlistener and settimer/maketimer to honor the /sim/signal "events" - but apart from that, it's a really clever idea<ref>{{cite web
It would not be very difficult to restore this functionality, or even generalize/improve it significantly (which was the scope of the original discussion on the devel list)<ref>{{cite web
   |url    =  https://forum.flightgear.org/viewtopic.php?p=295617#p295617
   |url    =  https://forum.flightgear.org/viewtopic.php?p=288388#p288388
   |title  =  <nowiki> Re: Whatever happened to radom radio chatter?? </nowiki>  
   |title  =  <nowiki> Re: Whatever happened to radom radio </nowiki>  
   |author =  <nowiki> Hooray </nowiki>  
   |author =  <nowiki> Hooray </nowiki>  
   |date  =  Sep 27th, 2016  
   |date  =  Jun 11th, 2016  
   |added  =  Sep 27th, 2016  
   |added  =  Jun 11th, 2016  
   |script_version = 0.40  
   |script_version = 0.40  
   }}</ref>
   }}</ref>


== API ==
The restored functionality could be distributed as a tarball that is extracted into $FG_ROOT - alternatively, into $FG_HOME, because Nasal files there are treated as overlays, which basically means that you can install user-specific extensions there without having to tamper with $FG_ROOT, it would only take  very minor changes to turn the chatter feature into a corresponding "addon" - not unlike fgcamera ...<ref>{{cite web
We now have a simple API to add addons to FlightGear without the need to mess around with FGData/Nasal or FGHome/Nasal directories. FlightGear now accepts the command line switch --addon=/path/to/some/addon (note: command line switch is just that: a command line switch - not an option to be entered into the launcher). fgfs (through options.cxx) takes care of
   |url    =  https://forum.flightgear.org/viewtopic.php?p=288392#p288392
* creating a property subtree under /addons for each addon
   |title  =  <nowiki> Re: Whatever happened to radom radio  </nowiki>  
* adding /path/to/some/addon/addon-config.xml as a config file (same as --config=/path/to/some/addon/addon-config.xml)
   |author =  <nowiki> Hooray </nowiki>  
* adding /path/to/some/addon to the list of allowed directories (same as --fg-aircraft=/path/to/some/addon)
   |date  =  Jun 11th, 2016
 
   |added  =  Jun 11th, 2016
The addon may be installed anywhere on your hard disk and it needs at least two files:
* addon-config.xml - a standard PropertyList to be used to populate or modify the property tree. (Same as to be used in --config=foo.xml)
* addon-main.nas - the Nasal hook for the logic. This file needs a function called main() which will be called from the global addon initialier (FGData/addons.nas)
 
Additional files:
* addon-menubar-items.xml to add a menu for the addon (see chapter 6 in [https://sourceforge.net/p/flightgear/fgdata/ci/next/tree/Docs/README.add-ons README.add-ons])
 
It is pretty simple but does it's job nicely. There is a /very/ simple Skeleton addon available to be used as a boilerplate here: https://sourceforge.net/p/flightgear/fgaddon/HEAD/tree/trunk/Addons/Skeleton/ As always: feedback is much appreciated. <ref>{{cite web
  |url    =  https://sourceforge.net/p/flightgear/mailman/message/35951307/
  |title  =  <nowiki> [Flightgear-devel] Simple API for creating FlightGear addons/plugins </nowiki>
  |author =  <nowiki> Torsten Dreyer </nowiki>
  |date  =  Jul 18th, 2017
  |added  =  Jul 18th, 2017
  |script_version = 0.40
  }}</ref> <ref> {{cite web
   |url    =  https://forum.flightgear.org/viewtopic.php?p=314563#p314563
   |title  =  <nowiki> New Feature: Addon - "API" </nowiki>  
   |author =  <nowiki> Torsten </nowiki>  
   |date  =  Jul 18th, 2017
   |added  =  Jul 18th, 2017
   |script_version = 0.40  
   |script_version = 0.40  
   }}</ref>
   }}</ref>


Triggered by this addon, Torsten has overhauled the addon "API" to make it a little easier to use.  
We should absolutely stop telling anyone to edit preferences.xml in FG_ROOT; any documentation or advice which says to should be changes ASAP. <ref>{{cite web
 
   |url    =  https://forum.flightgear.org/viewtopic.php?p=192632#p192632
Along with this, he added the spoken ATC feature as an addon to fgaddon: https://sourceforge.net/p/flightgear/fgaddon/HEAD/tree/trunk/Addons/SpokenATC/
   |title  =  <nowiki> Re: NavCache:init failed:Sqlite error:Sqlite API abuse </nowiki>  
It is now very easy to use (given you have FlightGear compiled from git HEAD or use FlightGear 2017.3.x or later.
   |author =  <nowiki> zakalawe </nowiki>  
 
   |date  =  Oct 26th, 2013
you need at least these commits:
   |added  =  Oct 26th, 2013
 
FlightGear: https://sourceforge.net/p/flightgear/flightgear/ci/f6698a0b1f9e8c0791314aa09cbe1625927ef3ff/
 
FGData: https://sourceforge.net/p/flightgear/fgdata/ci/5c1f4a69f131a55521050f4631b8fda42f050dd2/
* Get the addon from https://sourceforge.net/p/flightgear/fgaddon/HEAD/tree/trunk/Addons/SpokenATC/
* start flightgear with --addon=/your/full/path/to/SpokenATC
 
done.<ref>{{cite web
   |url    =  https://forum.flightgear.org/viewtopic.php?p=314562#p314562
   |title  =  <nowiki> Re: Spoken ATC </nowiki>  
   |author =  <nowiki> Torsten </nowiki>  
   |date  =  Jul 18th, 2017
   |added  =  Jul 18th, 2017
   |script_version = 0.40  
   |script_version = 0.40  
   }}</ref>
   }}</ref>


 
As of 12/2017, the addon API is in the process of being significantly updated <ref>https://sourceforge.net/p/flightgear/mailman/message/36146017/</ref> <ref>https://sourceforge.net/p/flightgear/mailman/message/36150159/</ref> <ref>https://sourceforge.net/p/flightgear/mailman/message/36150444/</ref>
== Implementation ==
{{caution| This section needs an update}}
{{note| see also [[Modules.nas]]}}
For the time being, the addons.nas module will:
* initialize addons configured with --addon=foobar command line switch
* get the list of registered add-ons
* load the addon-main.nas file of each add-on into namespace __addon[ADDON_ID]__
* call function main() from every such addon-main.nas with the add-on ghost as argument.
 
It depend on a change to options.cxx to accept an optional --addon argument <ref>https://sourceforge.net/p/flightgear/flightgear/ci/f6698a0b1f9e8c0791314aa09cbe1625927ef3ff/</ref>


== List of Addons ==
== List of Addons ==
You can find the official repository [https://sourceforge.net/p/flightgear/fgaddon/HEAD/tree/trunk/Addons/ on sourceforge.net (fgaddon/Addons)]
You can find the official repository at {{fgaddon source|path=Addons}}
* [[Landing Rate addon]] [https://forum.flightgear.org/viewtopic.php?f=6&t=33101&p=327787#p327787]
* [[YASim Development Tools]] (by jsb)
* [[Model Cockpit View]]
* [[FGPlot]]
* ATC Chatter (ported by Torsten) {{progressbar|100}}
* ATC Chatter (ported by Torsten) {{progressbar|100}}
* [[Spoken ATC]] (ported by Torsten <ref>{{cite web
* cockpit-view (work in progress by wkitty42)<ref>{{cite web
   |url    =  https://forum.flightgear.org/viewtopic.php?p=314095#p314095
   |url    =  https://forum.flightgear.org/viewtopic.php?p=316498#p316498
   |title  =  <nowiki> Re:  </nowiki>  
   |title  =  <nowiki> Re:  </nowiki>  
   |author =  <nowiki> Torsten </nowiki>  
   |author =  <nowiki> wkitty42 </nowiki>  
   |date  =  Jul 10th, 2017  
   |date  =  Aug 13th, 2017  
   |added  =  Jul 10th, 2017  
   |added  =  Aug 13th, 2017  
   |script_version = 0.40  
   |script_version = 0.40  
   }}</ref>)
   }}</ref>
* [[Oscilloscope_addon]]  
* [[Earthview#Customization]] - High resolution customization
* [[PAR_instrument]] (Precision Approach Radar and Ground Controlled Approach)
* [[FaceTrackNoIR]] (ported by HHS)<ref>{{cite web
* [[Red Griffin ATC]] (Speaking Air Traffic Controller <ref>{{cite web
   |url    =  https://sourceforge.net/p/flightgear/mailman/message/36454826/
   |url    =  https://forum.flightgear.org/viewtopic.php?f=6&t=36755
   |title  =  <nowiki> Re:  </nowiki>  
   |title  =  <nowiki> Re:  </nowiki>  
   |author =  <nowiki> RedGriffin </nowiki>  
   |author =  <nowiki> Unknown, HHS</nowiki>
   |date  =  Jan 6th, 2020
   |date  =  Nov 1th, 2018
  |added  =  Jan 6th, 2020
   }}</ref> - An addon to interface this [[Head tracking|head tracker]] with FlightGear
  |script_version = 1.0.0 RC2
* [[A Failure Management Framework for FlightGear]]
   }}</ref>)
* [[FGCamera]] (work in progress by Torsten)<ref>{{cite web
* [[FGCamera]] (work in progress by Torsten <ref>{{cite web
   |url    =  https://forum.flightgear.org/viewtopic.php?p=314650#p314650  
   |url    =  https://forum.flightgear.org/viewtopic.php?p=314650#p314650  
   |title  =  <nowiki> Re: Alternative camera control </nowiki>  
   |title  =  <nowiki> Re: Alternative camera control </nowiki>  
Line 190: Line 143:
   |added  =  Jul 19th, 2017  
   |added  =  Jul 19th, 2017  
   |script_version = 0.40  
   |script_version = 0.40  
   }}</ref> <ref>{{cite web
   }}</ref><ref>{{cite web
   |url    =  https://forum.flightgear.org/viewtopic.php?p=319804#p319804  
   |url    =  https://forum.flightgear.org/viewtopic.php?p=319804#p319804  
   |title  =  <nowiki> Re: New Feature: Addon - "API" </nowiki>  
   |title  =  <nowiki> Re: New Feature: Addon - "API" </nowiki>  
Line 197: Line 150:
   |added  =  Oct 2nd, 2017  
   |added  =  Oct 2nd, 2017  
   |script_version = 0.40  
   |script_version = 0.40  
   }}</ref>)
   }}</ref>
* [[Ground Services]] (ported by ThomasS<ref>{{cite web
* [[FGPlot]]
* [[Ground Services]] (ported by ThomasS)<ref>{{cite web
   |url    =  https://forum.flightgear.org/viewtopic.php?p=316400#p316400  
   |url    =  https://forum.flightgear.org/viewtopic.php?p=316400#p316400  
   |title  =  <nowiki> Re:  </nowiki>  
   |title  =  <nowiki> Re:  </nowiki>  
Line 205: Line 159:
   |added  =  Aug 12th, 2017  
   |added  =  Aug 12th, 2017  
   |script_version = 0.40  
   |script_version = 0.40  
   }}</ref>)
   }}</ref>
* cockpit-view (work in progress by wkitty42 <ref>{{cite web
* [[Landing Rate addon]] [https://forum.flightgear.org/viewtopic.php?f=6&t=33101&p=327787#p327787]
   |url    =  https://forum.flightgear.org/viewtopic.php?p=316498#p316498
* [https://gitlab.com/mdanil/flightgear-hax mdanilov hax!]: landing evaluation and aircraft development tools, TerraSync toggler
* [[Model Cockpit View]]
* [[Oscilloscope addon]] - Allows displaying a property of Nasal function over time
* [[PAR instrument]] - Precision Approach Radar and Ground Controlled Approach
* [[Red Griffin ATC]] - Speaking Air Traffic Controller<ref>{{cite web
  |url    =  https://forum.flightgear.org/viewtopic.php?f=6&t=36755
  |title  =  <nowiki> Re:  </nowiki>
  |author =  <nowiki> RedGriffin </nowiki>
  |date  =  Jan 6th, 2020
  |added  =  Jan 6th, 2020
  |script_version = 1.0.0 RC2
  }}</ref>
* [[Spoken ATC]] (ported by Torsten<ref>){{cite web
   |url    =  https://forum.flightgear.org/viewtopic.php?p=314095#p314095
   |title  =  <nowiki> Re:  </nowiki>  
   |title  =  <nowiki> Re:  </nowiki>  
   |author =  <nowiki> wkitty42 </nowiki>  
   |author =  <nowiki> Torsten </nowiki>  
   |date  =  Aug 13th, 2017  
   |date  =  Jul 10th, 2017  
   |added  =  Aug 13th, 2017  
   |added  =  Jul 10th, 2017  
   |script_version = 0.40  
   |script_version = 0.40  
   }}</ref>)
   }}</ref>
* [[A Failure Management Framework for FlightGear]]
* [[Spoken GCA]] - An offline ground controlled approach (GCA) addon
* [https://gitlab.com/mdanil/flightgear-hax mdanilov hax!]: landing evaluation and aircraft development tools, TerraSync toggler
* [[YASim Development Tools]] (by jsb)
* [[FaceTrackNoIR]] (ported by HHS<ref>{{cite web
  |url    =  https://sourceforge.net/p/flightgear/mailman/message/36454826/
  |title  =  <nowiki> Re:  </nowiki>
  |author =  <nowiki> Unknown, HHS</nowiki>
  |date  =  Nov 1th, 2018
  }}</ref>)


== Ideas ==
== Ideas ==
=== Hooking into features using legacy OpenGL code ===
=== Hooking into features using legacy OpenGL code ===
{{See also|Unifying the 2D rendering backend via canvas}}
{{See also|Unifying the 2D rendering backend via canvas}}
Line 230: Line 190:


=== Catalog & Package Manager support ===
=== Catalog & Package Manager support ===
if this works with more complex, pre-existing addons such as [[Bombable]], where the file layout is a replica of the old FGData layout, these types of mature addons might be better as SourceForge FlightGear sub-projects rather than being copied into FGAddon. Maybe the config file and nasal script could be used to automate the installation process ?<ref>{{cite web
if this works with more complex, pre-existing addons such as [[Bombable]], where the file layout is a replica of the old FGData layout, these types of mature addons might be better as SourceForge FlightGear sub-projects rather than being copied into FGAddon. Maybe the config file and nasal script could be used to automate the installation process ?<ref>{{cite web
   |url    =  https://sourceforge.net/p/flightgear/mailman/message/35953179/  
   |url    =  https://sourceforge.net/p/flightgear/mailman/message/35953179/  
Line 252: Line 211:
== References ==
== References ==
{{Appendix}}
{{Appendix}}
== Related content ==
=== Wiki articles ===
* [[FlightGear configuration via XML]]
* [[FlightGear configuration via XML#preferences.xml]]
* [[Nasal]]
* [[Property tree]]
* [[Properties persistent between sessions]]
* [[PropertyList XML File]]
=== Forum topics ===
* {{forum link|t=32561|title=New Feature: Addon - "API"}}
=== Readme file ===
* {{readme file|add-ons}}
=== Source code ===
==== FGAddon ====
* {{fgaddon source|path=Addons/Skeleton}} - Skeleton addon to be used as a template.
==== FGData ====
* {{fgdata source|path=Nasal/addons.nas}}
==== FlightGear ====
* {{flightgear source|path=src/Main/options.cxx}}
* {{flightgear source|path=src/Add-ons/}}

Revision as of 16:08, 10 July 2020

Fgaddonslogo202x89.png

To make it easier to create addons there is since FlightGear 2017.3 a new way to create addons. In essence FlightGear will load an overlay XML into the property tree and start a well known Nasal function.[1]

We now have a simple way to add addons to FlightGear without the need to mess around with FGData/Nasal or FGHome/Nasal directories.[2]

Installing and using an addon

Download and copy the addon to a directory on your computer.

Use the command line switch --addon=/path/to/some/addon.[2]

Creating an addon

There is a very simple Skeleton addon available in FGAddon to be used as a template.[2] See flightgear/fgaddon/trunk/Addons/Skeleton.

Minimum configuration

An addon may be installed in a directory anywhere on your hard disk and need at least two files:[2]

  • /config.xml - A standard PropertyList XML file to be used to populate or modify the property tree. (Same as to be used in --config=foo.xml)
  • /main.nas - The Nasal hook for the logic. This file needs a function called main() which will be called from the global addon initializer (addons.nas)

Additional common files

  • /addon-metadata.xml - A PropertyList XML file with metadata about the addon it.
  • /addon-menubar-items.xml - A PropertyList XML file describing menus to be added to the FlightGear menu bar.
  • /gui/dialogs/<my-foobar-dialog>.xml - PropertyList XML files to create custom dialogs.

Good to know

The new addon "API" lets you add a addon-config.xml to override the settings in defaults.xml and other files.

That easily allows to

  • Override key bindings (as in the spoken ATC addon)
  • Add or override autopilots and property rules
  • And of course introduce XML statemachines

Unless your really want to add/change/remove those at runtime, this should cater for most use cases.[3]

We have some instructions how to use SVN in our wiki. It covers mostly aircraft development but the workflow is pretty much the same for addons.[4]

APIs

For more details about these APIs, see the readme file, $FG_ROOT/Docs/README.add-ons.

C++ API

There is a C++ API on FlightGear's side that handle some on the addon related tasks manly through the AddonManager(), Addon() and AddonVersion() classes.

Addon initialization

On initialization fgfs takes care of:

  • Through options.cxx:[2]
    • Creating a property under /addons/addon[n]/path=/path/to/some/addon
    • Loading /path/to/some/addon/config.xml into the property tree (same as --config=/path/to/some/addon/config.xml)
    • Adding /path/to/some/addon to the list of allowed directories (same as --fg-aircraft=/path/to/some/addon)
  • Through addons.nas:
    • Loading /foo/bar/baz/addon-main.nas into namespace __addon[ADDON_ID]__
    • Calling main(addonGhost) from /foo/bar/baz/addon-main.nas.

Nasal API

The Nasal add-on API lives in the 'addons' namespace and can for example do queries to AddonManager() and read data from addons.Addon objects. It can for example compare addon versions if there is dependencies.

Background

See also Howto:Creating a simple modding framework.

ATC chatter was removed in 2015, see fgdata commit: 81607f734e13add9be02816ddaec305d05bc4e47

And the devel list messages referenced in the commit log. the other relevant commit is this: b60736ba7add2a7cd39af3d8a974d5be3ea46e8b It would not be very difficult to restore this functionality, or even generalize/improve it significantly (which was the scope of the original discussion on the devel list)[5]

The restored functionality could be distributed as a tarball that is extracted into $FG_ROOT - alternatively, into $FG_HOME, because Nasal files there are treated as overlays, which basically means that you can install user-specific extensions there without having to tamper with $FG_ROOT, it would only take very minor changes to turn the chatter feature into a corresponding "addon" - not unlike fgcamera ...[6]

We should absolutely stop telling anyone to edit preferences.xml in FG_ROOT; any documentation or advice which says to should be changes ASAP. [7]

As of 12/2017, the addon API is in the process of being significantly updated [8] [9] [10]

List of Addons

You can find the official repository at flightgear/fgaddon/trunk/Addons

Ideas

Hooking into features using legacy OpenGL code

See also Unifying the 2D rendering backend via canvas.

In 09/2018, James suggested that legacy features using raw OpenGL calls (e.g. HUD/2D panels) could be easily replaced via scripted Canvas/Nasal solutions at the mere cost of providing a mechanism to hook into the legacy code implementing these features (namely, the HUD/instrumentation subsystems) [18] [19]

Catalog & Package Manager support

if this works with more complex, pre-existing addons such as Bombable, where the file layout is a replica of the old FGData layout, these types of mature addons might be better as SourceForge FlightGear sub-projects rather than being copied into FGAddon. Maybe the config file and nasal script could be used to automate the installation process ?[20] The Bombable addon is one of the most popular addons out there, and a large number of aircraft in FGAddon have bombable support, so it is worth not forgetting about. Especially if the addon system one day becomes automated through a catalog.xml type system[21]

References

References
  1. ↑ Torsten  (Jul 19th, 2017).  Re: New Feature: Addon - "API" .
  2. ↑ 2.0 2.1 2.2 2.3 2.4 Torsten  (Jul 18th, 2017).  New Feature: Addon - "API" .
  3. ↑ Torsten  (Jul 23rd, 2017).  Re: Spoken .
  4. ↑ Torsten  (Jul 19th, 2017).  Re: Spoken ATC .
  5. ↑ Hooray  (Jun 11th, 2016).  Re: Whatever happened to radom radio .
  6. ↑ Hooray  (Jun 11th, 2016).  Re: Whatever happened to radom radio .
  7. ↑ zakalawe  (Oct 26th, 2013).  Re: NavCache:init failed:Sqlite error:Sqlite API abuse .
  8. ↑ https://sourceforge.net/p/flightgear/mailman/message/36146017/
  9. ↑ https://sourceforge.net/p/flightgear/mailman/message/36150159/
  10. ↑ https://sourceforge.net/p/flightgear/mailman/message/36150444/
  11. ↑ wkitty42  (Aug 13th, 2017).  Re: .
  12. ↑ Unknown, HHS (Nov 1th, 2018).  Re: .
  13. ↑ Torsten  (Jul 19th, 2017).  Re: Alternative camera control .
  14. ↑ slawekmikula  (Oct 2nd, 2017).  Re: New Feature: Addon - "API" .
  15. ↑ ThomasS  (Aug 12th, 2017).  Re: .
  16. ↑ RedGriffin  (Jan 6th, 2020).  Re: .
  17. ↑ ) Torsten  (Jul 10th, 2017).  Re: .
  18. ↑ https://sourceforge.net/p/flightgear/mailman/message/36399261/
  19. ↑ https://sourceforge.net/p/flightgear/mailman/message/36399261/
  20. ↑ Edward d'Auvergne  (Jul 19th, 2017).  Re: [Flightgear-devel] Simple API for creating FlightGear addons/plugins .
  21. ↑ Edward d'Auvergne  (Jul 19th, 2017).  Re: [Flightgear-devel] Simple API for creating FlightGear addons/plugins .

Related content

Wiki articles

Forum topics

Readme file

Source code

FGAddon

FGData

FlightGear

Retrieved from "https://wiki.flightgear.org/w/index.php?title=Addon&oldid=126203"