Addon: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
(45 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{Stub}}
{{Stub}}
[[File:Jigsaw.png|thumb]]
[[File:Fgaddonslogo202x89.png|thumb]]  
{{forum|10000|FlightGear Addons}}
{{forum|10000|FlightGear Addons}}
== Background ==
== Background ==
Line 17: Line 17:
   |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
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
Line 28: Line 26:
   |script_version = 0.40  
   |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
  |url    =  https://forum.flightgear.org/viewtopic.php?p=192632#p192632
  |title  =  <nowiki> Re: NavCache:init failed:Sqlite error:Sqlite API abuse </nowiki>
  |author =  <nowiki> zakalawe </nowiki>
  |date  =  Oct 26th, 2013
  |added  =  Oct 26th, 2013
  |script_version = 0.40
  }}</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>


== Good to know ==
== Good to know ==
this API does nothing more than loading a overlay XML into the property tree and starts a well known Nasal function<ref>{{cite web
  |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>
The new addon "API" lets you add a addon-config.xml to override the settings in defaults.xml.
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.<ref>{{cite web
  |url    =  https://forum.flightgear.org/viewtopic.php?p=314902#p314902
  |title  =  <nowiki> Re: Spoken  </nowiki>
  |author =  <nowiki> Torsten </nowiki>
  |date  =  Jul 23rd, 2017
  |added  =  Jul 23rd, 2017
  |script_version = 0.40
  }}</ref>
We have some instructions how to use SVN [[FGAddon|in our wiki]]. It covers mostly aircraft development but the workflow is pretty much the same for addons.<ref>{{cite web
  |url    =  https://forum.flightgear.org/viewtopic.php?p=314647#p314647
  |title  =  <nowiki> Re: Spoken ATC </nowiki>
  |author =  <nowiki> Torsten </nowiki>
  |date  =  Jul 19th, 2017
  |added  =  Jul 19th, 2017
  |script_version = 0.40
  }}</ref>
* [[Property tree]]
* [[Property tree]]
* [[PropertyList XML File]]
* [[PropertyList XML File]]
Line 51: Line 96:


== API ==
== API ==
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  
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  
* creating a property under /addons/addon[n]/path=/path/to/some/addon  
* creating a property subtree under /addons for each addon
* adding /path/to/some/addon/config.xml as a config file (same as --config=/path/to/some/addon/config.xml)  
* adding /path/to/some/addon/addon-config.xml as a config file (same as --config=/path/to/some/addon/addon-config.xml)  
* adding /path/to/some/addon to the list of allowed directories (same as --fg-aircraft=/path/to/some/addon)  
* adding /path/to/some/addon to the list of allowed directories (same as --fg-aircraft=/path/to/some/addon)  


The addon may be installed anywhere on your hard disk and it needs at least two files:  
The addon may be installed anywhere on your hard disk and it needs at least two files:  
* 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-config.xml - a standard PropertyList 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 initialier (FGData/addons.nas)  
* 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)  


It is pretty simple but does it's job nicely with our two addons we currently have in FGAddon (ATCChatter and SpokenATC). 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
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/  
   |url    =  https://sourceforge.net/p/flightgear/mailman/message/35951307/  
   |title  =  <nowiki> [Flightgear-devel] Simple API for creating FlightGear addons/plugins </nowiki>  
   |title  =  <nowiki> [Flightgear-devel] Simple API for creating FlightGear addons/plugins </nowiki>  
Line 99: Line 146:
   }}</ref>
   }}</ref>


== config.xml ==
Ideally, a minimal config.xml should look like this:
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<!--
This file is part of FlightGear.
FlightGear is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
(at your option) any later version.
FlightGear is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with FlightGear.  If not, see <http://www.gnu.org/licenses/>.
-->
<PropertyList>
  <!-- addon version -->
  <version type="double">1.0</version>
  <authors>list of contributors</authors>
  <description>short text describing the addon</description>
  <changelog>list of recent improvements/changes (e.g. to be shown when updating an addon)</changelog>
</PropertyList>
</syntaxhighlight>
For the time being the {{tag|version}}, {{tag|authors}} and {{tag|description}} are strictly optional. However, addon developers are strongly encouraged to provide such meta information, which is entirely in line with the existing practice in [[Aircraft-set.xml]] files, and doing so will make it much easier in the future to extend/improve on the addon framework, e.g. by making breaking changes, provided that addons specify the proper {{tag|version}} tag.
Furthermore, agreeing early on to provide, require and use such meta-information, will make it increasingly easy to also use the scenery/aircraft management back-ends implemented on top of the [[Catalog metadata]] and [[Package manager]] systems to also use these for installing, managing/updating, and removing addons in the future.
==  main.nas ==
<syntaxhighlight lang="javascript">
</syntaxhighlight>


== Implementation ==
== Implementation ==
For the time being, the addon.nas module will:
For the time being, the addons.nas module will:
* initialize addons configured with --addon=foobar command line switch
* initialize addons configured with --addon=foobar command line switch
* loop over /addons/addon[n] nodes
* get the list of registered add-ons
get root path in /addons/addon[n]/path property (set by options.cxx from --addon=/foo/bar)
* load the addon-main.nas file of each add-on into namespace __addon[ADDON_ID]__
* load main.nas therein into namespace __addon[n]__
* call function main() from every such addon-main.nas with the add-on ghost as argument.
* call function main() from that main.nas with addon-path as arg
 


It depend on a change to options.cxx to accept an optional --addon argument <ref>https://sourceforge.net/p/flightgear/flightgear/ci/f6698a0b1f9e8c0791314aa09cbe1625927ef3ff/</ref>
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 ==
* Chatter
You can find the official repository [https://sourceforge.net/p/flightgear/fgaddon/HEAD/tree/trunk/Addons/ on sourceforge.net (fgaddon/Addons)]
* [[Spoken ATC]]
* [[Landing Rate addon]] [https://forum.flightgear.org/viewtopic.php?f=6&t=33101&p=327787#p327787]
* [[FGCamera]] (work in progress)
* [[YASim Development Tools]] (by jsb)
* [[Model Cockpit View]]
* [[FGPlot]]
* ATC Chatter (ported by Torsten) {{progressbar|100}}
* [[Spoken ATC]] (ported by Torsten <ref>{{cite web
  |url    =  https://forum.flightgear.org/viewtopic.php?p=314095#p314095
  |title  =  <nowiki> Re:  </nowiki>
  |author =  <nowiki> Torsten </nowiki>
  |date  =  Jul 10th, 2017
  |added  =  Jul 10th, 2017
  |script_version = 0.40
  }}</ref>)
* [[Oscilloscope_addon]]
* [[PAR_instrument]] (Precision Approach Radar and Ground Controlled Approach)
* [[FGCamera]] (work in progress by Torsten <ref>{{cite web
  |url    =  https://forum.flightgear.org/viewtopic.php?p=314650#p314650
  |title  =  <nowiki> Re: Alternative camera control </nowiki>
  |author =  <nowiki> Torsten </nowiki>
  |date  =  Jul 19th, 2017
  |added  =  Jul 19th, 2017
  |script_version = 0.40
  }}</ref> <ref>{{cite web
  |url    =  https://forum.flightgear.org/viewtopic.php?p=319804#p319804
  |title  =  <nowiki> Re: New Feature: Addon - "API" </nowiki>
  |author =  <nowiki> slawekmikula </nowiki>
  |date  =  Oct 2nd, 2017
  |added  =  Oct 2nd, 2017
  |script_version = 0.40
  }}</ref>)
* [[Ground Services]] (ported by ThomasS<ref>{{cite web
  |url    =  https://forum.flightgear.org/viewtopic.php?p=316400#p316400
  |title  =  <nowiki> Re:  </nowiki>
  |author =  <nowiki> ThomasS </nowiki>
  |date  =  Aug 12th, 2017
  |added  =  Aug 12th, 2017
  |script_version = 0.40
  }}</ref>)
* cockpit-view (work in progress by wkitty42 <ref>{{cite web
  |url    =  https://forum.flightgear.org/viewtopic.php?p=316498#p316498
  |title  =  <nowiki> Re:  </nowiki>
  |author =  <nowiki> wkitty42 </nowiki>
  |date  =  Aug 13th, 2017
  |added  =  Aug 13th, 2017
  |script_version = 0.40
  }}</ref>)
* [[A Failure Management Framework for FlightGear]]
* [https://gitlab.com/mdanil/flightgear-hax mdanilov hax!]: landing evaluation and aircraft development tools, TerraSync toggler
* [[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 ===
{{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) <ref>https://sourceforge.net/p/flightgear/mailman/message/36399261/</ref> <ref>https://sourceforge.net/p/flightgear/mailman/message/36399261/</ref>


=== Catalog & Package Manager support ===
=== Catalog & Package Manager support ===

Revision as of 10:37, 24 December 2018

This article is a stub. You can help the wiki by expanding it.
Fgaddonslogo202x89.png

Background

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)[1]

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 ...[2]

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

As of 12/2017, the addon API is in the process of being significantly updated [4] [5] [6]

Good to know

this API does nothing more than loading a overlay XML into the property tree and starts a well known Nasal function[7]


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

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.[8]

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.[9]


Overlays

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" ... ;-) 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. 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[10]

API

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

  • creating a property subtree under /addons for each addon
  • adding /path/to/some/addon/addon-config.xml as a config file (same as --config=/path/to/some/addon/addon-config.xml)
  • adding /path/to/some/addon to the list of allowed directories (same as --fg-aircraft=/path/to/some/addon)

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 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. [11] [12]

Triggered by this addon, Torsten has overhauled the addon "API" to make it a little easier to use.

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/ It is now very easy to use (given you have FlightGear compiled from git HEAD or use FlightGear 2017.3.x or later.

you need at least these commits:

FlightGear: https://sourceforge.net/p/flightgear/flightgear/ci/f6698a0b1f9e8c0791314aa09cbe1625927ef3ff/

FGData: https://sourceforge.net/p/flightgear/fgdata/ci/5c1f4a69f131a55521050f4631b8fda42f050dd2/

done.[13]


Implementation

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 [14]

List of Addons

You can find the official repository on sourceforge.net (fgaddon/Addons)

Ideas

Hooking into features using legacy OpenGL code

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) [21] [22]

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 ?[23] 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[24]

References

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