Addon: Difference between revisions

Jump to navigation Jump to search

Addon (view source)

Revision as of 16:08, 10 July 2020

1,203 bytes removed ,  10 July 2020
Major update and rewrite, mostly based on readme and comments in source files
(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/}}
Retrieved from "https://wiki.flightgear.org/Special:MobileDiff/126203"

Navigation menu