Addons

From FlightGear wiki
Jump to: navigation, search
This article is a stub. You can help the wiki by expanding it.
Jigsaw.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]

Good to know

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


The new addon "API" lets you add a 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.[5]

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


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

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 under /addons/addon[n]/path=/path/to/some/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 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:

  • 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)

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

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


config.xml

Ideally, a minimal config.xml should look like this:

<?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>
  <!-- FIXME: this should probably be using conditions -->
  <require>
   <min-flightgear-version></min-flightgear-version>
   <addon-api-version></adddon-api-version>
  </require>
  <name></name>
  <!-- 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>

For the time being the <version>, <authors> and <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 <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

var main = func(root) {

print("my addon loaded !");

}; # main()


In general, it is recommended to also register event handlers (/sim/signals) to deal with relevant events like pause/unpause, reset/reinit etc - for example, like this:

1rightarrow.png See Using_listeners_and_signals_with_Nasal#Signals for the main article about this subject.

setlistener("/sim/signals/reinit", func() {
 print("addon: re-init !");
});

setlistener("/sim/signals/exit", func() {
 print("addon: exiting !");
});

setlistener("/sim/signals/screenshot", func() {
 print("addon: screentshot being taken");
});

It is also a good idea to overload settimer/setlistener respectively, to ensure that listeners/callbacks don't leak:

Implementation

For the time being, the addon.nas module will:

  • initialize addons configured with --addon=foobar command line switch
  • loop over /addons/addon[n] nodes
  • get root path in /addons/addon[n]/path property (set by options.cxx from --addon=/foo/bar)
  • load main.nas therein into namespace __addon[n]__
  • 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 [11]

List of Addons

Ideas

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 ?[16] 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[17]

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. Torsten  (Jul 19th, 2017).  Re: New Feature: Addon - "API" .
  5. Torsten  (Jul 23rd, 2017).  Re: Spoken .
  6. Torsten  (Jul 19th, 2017).  Re: Spoken ATC .
  7. Hooray  (Sep 27th, 2016).  Re: Whatever happened to radom radio chatter?? .
  8. Torsten Dreyer  (Jul 18th, 2017).  [Flightgear-devel] Simple API for creating FlightGear addons/plugins .
  9. Torsten  (Jul 18th, 2017).  New Feature: Addon - "API" .
  10. Torsten  (Jul 18th, 2017).  Re: Spoken ATC .
  11. https://sourceforge.net/p/flightgear/flightgear/ci/f6698a0b1f9e8c0791314aa09cbe1625927ef3ff/
  12. Torsten  (Jul 10th, 2017).  Re: .
  13. Torsten  (Jul 19th, 2017).  Re: Alternative camera control .
  14. ThomasS  (Aug 12th, 2017).  Re: .
  15. wkitty42  (Aug 13th, 2017).  Re: .
  16. Edward d'Auvergne  (Jul 19th, 2017).  Re: [Flightgear-devel] Simple API for creating FlightGear addons/plugins .
  17. Edward d'Auvergne  (Jul 19th, 2017).  Re: [Flightgear-devel] Simple API for creating FlightGear addons/plugins .