Addon: Difference between revisions
Line 250: | Line 250: | ||
|added = Jul 19th, 2017 | |added = Jul 19th, 2017 | ||
|script_version = 0.40 | |script_version = 0.40 | ||
}}</ref>) | }}</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]] (work in progress by ThomasS <ref>{{cite web | * [[Ground Services]] (work in progress 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 |
Revision as of 11:31, 3 October 2017
This article is a stub. You can help the wiki by expanding it. |
The FlightGear forum has a subforum related to: FlightGear Addons |
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]
- Property tree
- PropertyList XML File
- FlightGear configuration via XML
- Properties persistent between sessions
- FlightGear_configuration_via_XML#preferences.xml
- Nasal
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/
- 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.[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:
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
- ATC Chatter (ported by Torsten)
- Spoken ATC (ported by Torsten [12])
- FGCamera (work in progress by Torsten [13] [14]
)
- Ground Services (work in progress by ThomasS [15])
- cockpit-view (work in progress by wkitty42 [16])
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 ?[17] 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[18]