Addon: Difference between revisions
(23 intermediate revisions by 6 users not shown) | |||
Line 1: | Line 1: | ||
{{Stub}} | {{Stub}} | ||
[[File: | [[File:Fgaddonslogo202x89.png|thumb]] | ||
{{forum|10000|FlightGear Addons}} | {{forum|10000|FlightGear Addons}} | ||
== Background == | == Background == | ||
Line 35: | Line 35: | ||
|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> | |||
== Good to know == | == Good to know == | ||
Line 47: | 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 94: | 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 | * 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 | 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 142: | Line 146: | ||
}}</ref> | }}</ref> | ||
== Implementation == | == Implementation == | ||
For the time being, the | 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 | ||
* | * 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> | 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] | |||
* [[YASim Development Tools]] (by jsb) | |||
* [[Model Cockpit View]] | * [[Model Cockpit View]] | ||
* [[FGPlot]] | * [[FGPlot]] | ||
Line 244: | Line 170: | ||
|added = Jul 10th, 2017 | |added = Jul 10th, 2017 | ||
|script_version = 0.40 | |script_version = 0.40 | ||
}}</ref>) | }}</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 277: | 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 === |
Revision as of 10:37, 24 December 2018
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]
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]
- 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[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/
- 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.[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)
- Landing Rate addon [1]
- YASim Development Tools (by jsb)
- Model Cockpit View
- FGPlot
- ATC Chatter (ported by Torsten)
- Spoken ATC (ported by Torsten [15])
- Oscilloscope_addon
- PAR_instrument (Precision Approach Radar and Ground Controlled Approach)
- FGCamera (work in progress by Torsten [16] [17])
- Ground Services (ported by ThomasS[18])
- cockpit-view (work in progress by wkitty42 [19])
- A Failure Management Framework for FlightGear
- mdanilov hax!: landing evaluation and aircraft development tools, TerraSync toggler
- FaceTrackNoIR (ported by HHS[20])
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]