Hi fellow wiki editors!

To help newly registered users get more familiar with the wiki (and maybe older users too) there is now a {{Welcome to the wiki}} template. Have a look at it and feel free to add it to new users discussion pages (and perhaps your own).

I have tried to keep the template short, but meaningful. /Johan G

Difference between revisions of "Addons"

From FlightGear wiki
Jump to: navigation, search
m (main.nas: out od date)
(Addon re-load support for addon development)
 
(15 intermediate revisions by 6 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 49: Line 49:
  
  
The new addon "API" lets you add a config.xml to override the settings in defaults.xml.
+
The new addon "API" lets you add a addon-config.xml to override the settings in defaults.xml.
  
 
That easily allows to
 
That easily allows to
Line 96: 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)
 +
 
 +
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 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
+
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 146: Line 148:
  
 
== 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 ==
 +
You can find the official repository [https://sourceforge.net/p/flightgear/fgaddon/HEAD/tree/trunk/Addons/ on sourceforge.net (fgaddon/Addons)]
 
* [[Landing Rate addon]] [https://forum.flightgear.org/viewtopic.php?f=6&t=33101&p=327787#p327787]
 
* [[Landing Rate addon]] [https://forum.flightgear.org/viewtopic.php?f=6&t=33101&p=327787#p327787]
 
* [[YASim Development Tools]] (by jsb)
 
* [[YASim Development Tools]] (by jsb)
Line 169: Line 170:
 
   |added  =  Jul 10th, 2017  
 
   |added  =  Jul 10th, 2017  
 
   |script_version = 0.40  
 
   |script_version = 0.40  
   }}</ref>) {{progressbar|90}}
+
   }}</ref>)
 +
* [[Oscilloscope_addon]]
 +
* [[PAR_instrument]] (Precision Approach Radar and Ground Controlled Approach)
 
* [[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  
Line 202: Line 205:
 
   }}</ref>)
 
   }}</ref>)
 
* [[A Failure Management Framework for FlightGear]]
 
* [[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 ===

Latest revision as of 05: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 .