13,241
edits
(Major update and rewrite, mostly based on readme and comments in source files) |
|||
Line 1: | Line 1: | ||
[[File:Fgaddonslogo202x89.png|right]] | |||
[[File:Fgaddonslogo202x89.png| | To make it easier to create '''addons''' there is since FlightGear 2017.3 a new way to create addons. In essence FlightGear will load an overlay XML into the property tree and start 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 | |||
and | |||
|url = https://forum.flightgear.org/viewtopic.php?p= | |||
|title = <nowiki> Re: | |||
|author = <nowiki> | |||
|date = | |||
|added = | |||
|script_version = 0.40 | |script_version = 0.40 | ||
}}</ref> | }}</ref> | ||
We now have a simple way to add addons to FlightGear without the need to mess around with <code>FGData/Nasal</code> or <code>FGHome/Nasal</code> directories.<ref name="Forum_announcement">{{cite web | |||
|url = https://forum.flightgear.org/viewtopic.php?p= | |url = https://forum.flightgear.org/viewtopic.php?p=314563#p314563 | ||
|title = <nowiki> | |title = <nowiki> New Feature: Addon - "API" </nowiki> | ||
|author = <nowiki> | |author = <nowiki> Torsten </nowiki> | ||
|date = | |date = Jul 18th, 2017 | ||
}}</ref> | }}</ref> | ||
{{TOC limit|3}} | |||
== Installing and using an addon == | |||
Download and copy the addon to a directory on your computer. | |||
Use the command line switch <code>--addon=/path/to/some/addon</code>.<ref name="Forum_announcement"/> | |||
== Creating an addon == | |||
There is a very simple Skeleton addon available in FGAddon to be used as a template.<ref name="Forum_announcement"/> See {{fgaddon source|path=Addons/Skeleton}}. | |||
=== Minimum configuration === | |||
An addon may be installed in a directory anywhere on your hard disk and need at least two files:<ref name="Forum_announcement"/> | |||
* <code>/config.xml</code> - A standard [[PropertyList XML files|PropertyList XML file]] to be used to populate or modify the [[property tree]]. (Same as to be used in <code>--config=foo.xml</code>) | |||
* <code>/main.nas</code> - The Nasal hook for the logic. This file needs a function called <code>main()</code> which will be called from the global addon initializer (<code>addons.nas</code>) | |||
=== Additional common files === | |||
* <code>/addon-metadata.xml</code> - A PropertyList XML file with metadata about the addon it. | |||
* <code>/addon-menubar-items.xml</code> - A PropertyList XML file describing menus to be added to the FlightGear menu bar. | |||
* <code>/gui/dialogs/<my-foobar-dialog>.xml</code> - PropertyList XML files to create custom dialogs. | |||
The new addon "API" lets you add a addon-config.xml to override the settings in defaults.xml. | === Good to know === | ||
The new addon "API" lets you add a <code>addon-config.xml</code> to override the settings in <code>defaults.xml</code> and other files. | |||
That easily allows to | That easily allows to | ||
* Override key bindings (as in the spoken | * Override key bindings (as in the spoken ATC addon) | ||
* Add or override autopilots and property rules | * Add or override autopilots and property rules | ||
* And of course introduce XML | * 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 | Unless your really want to add/change/remove those at runtime, this should cater for most use cases.<ref>{{cite web | ||
Line 74: | Line 63: | ||
}}</ref> | }}</ref> | ||
== APIs == | |||
{{hatnote|For more details about these APIs, see the readme file, {{readme file|add-ons}}.}} | |||
=== C++ API === | |||
There is a C++ API on FlightGear's side that handle some on the addon related tasks manly through the <code>AddonManager()</code>, <code>Addon()</code> and <code>AddonVersion()</code> classes. | |||
* [ | == Addon initialization == | ||
* | On initialization fgfs takes care of: | ||
* | * Through {{flightgear source|path=src/Main/options.cxx|text=<code>options.cxx</code>}}:<ref name="Forum_announcement"/> | ||
* [ | ** Creating a property under <code>/addons/addon[n]/path=/path/to/some/addon</code> | ||
* | ** Loading <code>/path/to/some/addon/config.xml</code> into the property tree (same as <code>--config=/path/to/some/addon/config.xml</code>) | ||
** Adding <code>/path/to/some/addon</code> to the list of allowed directories (same as <code>--fg-aircraft=/path/to/some/addon</code>) | |||
* Through {{fgdata source|path=Nasal/addons.nas|text=<code>addons.nas</code>}}: | |||
** Loading <code>/foo/bar/baz/addon-main.nas</code> into namespace <code>__addon[ADDON_ID]__</code> | |||
** Calling <code>main(addonGhost)</code> from <code>/foo/bar/baz/addon-main.nas</code>. | |||
=== Nasal API === | |||
The Nasal add-on API lives in the 'addons' namespace and can for example do queries to <code>AddonManager()</code> and read data from <code>addons.Addon</code> objects. It can for example compare addon versions if there is dependencies. | |||
== Background == | |||
{{See also|Howto:Creating a simple modding framework}} | |||
ATC chatter was removed in 2015, see fgdata commit: [https://sourceforge.net/p/flightgear/fgdata/ci/81607f734e13add9be02816ddaec305d05bc4e47/ 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)<ref>{{cite web | |||
|url = https://forum.flightgear.org/viewtopic.php?p= | |url = https://forum.flightgear.org/viewtopic.php?p=288388#p288388 | ||
|title = <nowiki> Re: Whatever happened to radom radio | |title = <nowiki> Re: Whatever happened to radom radio </nowiki> | ||
|author = <nowiki> Hooray </nowiki> | |author = <nowiki> Hooray </nowiki> | ||
|date = | |date = Jun 11th, 2016 | ||
|added = | |added = Jun 11th, 2016 | ||
|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 | |||
|url = https://forum.flightgear.org/viewtopic.php?p=288392#p288392 | |||
|title = <nowiki> Re: Whatever happened to radom radio </nowiki> | |||
|author = <nowiki> Hooray </nowiki> | |||
|date = Jun 11th, 2016 | |||
|added = Jun 11th, 2016 | |||
|url = https://forum.flightgear.org/viewtopic.php?p= | |||
|title = <nowiki> | |||
|author = <nowiki> | |||
|date = | |||
|added = | |||
|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 | |||
|url = https://forum.flightgear.org/viewtopic.php?p= | |||
|title = <nowiki> Re: | |||
|author = <nowiki> | |||
|date = | |||
|added = | |||
|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> | |||
== List of Addons == | == List of Addons == | ||
You can find the official repository | You can find the official repository at {{fgaddon source|path=Addons}} | ||
* ATC Chatter (ported by Torsten) {{progressbar|100}} | * ATC Chatter (ported by Torsten) {{progressbar|100}} | ||
* | * cockpit-view (work in progress by wkitty42)<ref>{{cite web | ||
|url = https://forum.flightgear.org/viewtopic.php?p= | |url = https://forum.flightgear.org/viewtopic.php?p=316498#p316498 | ||
|title = <nowiki> Re: </nowiki> | |title = <nowiki> Re: </nowiki> | ||
|author = <nowiki> | |author = <nowiki> wkitty42 </nowiki> | ||
|date = | |date = Aug 13th, 2017 | ||
|added = | |added = Aug 13th, 2017 | ||
|script_version = 0.40 | |script_version = 0.40 | ||
}}</ref> | }}</ref> | ||
* [[ | * [[Earthview#Customization]] - High resolution customization | ||
* [[ | * [[FaceTrackNoIR]] (ported by HHS)<ref>{{cite web | ||
|url = https://sourceforge.net/p/flightgear/mailman/message/36454826/ | |||
|url = https:// | |||
|title = <nowiki> Re: </nowiki> | |title = <nowiki> Re: </nowiki> | ||
|author = <nowiki> | |author = <nowiki> Unknown, HHS</nowiki> | ||
|date = | |date = Nov 1th, 2018 | ||
}}</ref> - An addon to interface this [[Head tracking|head tracker]] with FlightGear | |||
* [[A Failure Management Framework for FlightGear]] | |||
}}</ref> | * [[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 | ||
|title = <nowiki> Re: Alternative camera control </nowiki> | |title = <nowiki> Re: Alternative camera control </nowiki> | ||
Line 190: | Line 143: | ||
|added = Jul 19th, 2017 | |added = Jul 19th, 2017 | ||
|script_version = 0.40 | |script_version = 0.40 | ||
}}</ref> <ref>{{cite web | }}</ref><ref>{{cite web | ||
|url = https://forum.flightgear.org/viewtopic.php?p=319804#p319804 | |url = https://forum.flightgear.org/viewtopic.php?p=319804#p319804 | ||
|title = <nowiki> Re: New Feature: Addon - "API" </nowiki> | |title = <nowiki> Re: New Feature: Addon - "API" </nowiki> | ||
Line 197: | Line 150: | ||
|added = Oct 2nd, 2017 | |added = Oct 2nd, 2017 | ||
|script_version = 0.40 | |script_version = 0.40 | ||
}}</ref> | }}</ref> | ||
* [[Ground Services]] (ported by ThomasS<ref>{{cite web | * [[FGPlot]] | ||
* [[Ground Services]] (ported 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 | ||
|title = <nowiki> Re: </nowiki> | |title = <nowiki> Re: </nowiki> | ||
Line 205: | Line 159: | ||
|added = Aug 12th, 2017 | |added = Aug 12th, 2017 | ||
|script_version = 0.40 | |script_version = 0.40 | ||
}}</ref> | }}</ref> | ||
* | * [[Landing Rate addon]] [https://forum.flightgear.org/viewtopic.php?f=6&t=33101&p=327787#p327787] | ||
|url = https://forum.flightgear.org/viewtopic.php?p= | * [https://gitlab.com/mdanil/flightgear-hax mdanilov hax!]: landing evaluation and aircraft development tools, TerraSync toggler | ||
* [[Model Cockpit View]] | |||
* [[Oscilloscope addon]] - Allows displaying a property of Nasal function over time | |||
* [[PAR instrument]] - Precision Approach Radar and Ground Controlled Approach | |||
* [[Red Griffin ATC]] - Speaking Air Traffic Controller<ref>{{cite web | |||
|url = https://forum.flightgear.org/viewtopic.php?f=6&t=36755 | |||
|title = <nowiki> Re: </nowiki> | |||
|author = <nowiki> RedGriffin </nowiki> | |||
|date = Jan 6th, 2020 | |||
|added = Jan 6th, 2020 | |||
|script_version = 1.0.0 RC2 | |||
}}</ref> | |||
* [[Spoken ATC]] (ported by Torsten<ref>){{cite web | |||
|url = https://forum.flightgear.org/viewtopic.php?p=314095#p314095 | |||
|title = <nowiki> Re: </nowiki> | |title = <nowiki> Re: </nowiki> | ||
|author = <nowiki> | |author = <nowiki> Torsten </nowiki> | ||
|date = | |date = Jul 10th, 2017 | ||
|added = | |added = Jul 10th, 2017 | ||
|script_version = 0.40 | |script_version = 0.40 | ||
}}</ref> | }}</ref> | ||
* [[ | * [[Spoken GCA]] - An offline ground controlled approach (GCA) addon | ||
* [[YASim Development Tools]] (by jsb) | |||
* [[ | |||
== Ideas == | == Ideas == | ||
=== Hooking into features using legacy OpenGL code === | === Hooking into features using legacy OpenGL code === | ||
{{See also|Unifying the 2D rendering backend via canvas}} | {{See also|Unifying the 2D rendering backend via canvas}} | ||
Line 230: | Line 190: | ||
=== Catalog & Package Manager support === | === 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 ?<ref>{{cite web | 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 ?<ref>{{cite web | ||
|url = https://sourceforge.net/p/flightgear/mailman/message/35953179/ | |url = https://sourceforge.net/p/flightgear/mailman/message/35953179/ | ||
Line 252: | Line 211: | ||
== References == | == References == | ||
{{Appendix}} | {{Appendix}} | ||
== Related content == | |||
=== Wiki articles === | |||
* [[FlightGear configuration via XML]] | |||
* [[FlightGear configuration via XML#preferences.xml]] | |||
* [[Nasal]] | |||
* [[Property tree]] | |||
* [[Properties persistent between sessions]] | |||
* [[PropertyList XML File]] | |||
=== Forum topics === | |||
* {{forum link|t=32561|title=New Feature: Addon - "API"}} | |||
=== Readme file === | |||
* {{readme file|add-ons}} | |||
=== Source code === | |||
==== FGAddon ==== | |||
* {{fgaddon source|path=Addons/Skeleton}} - Skeleton addon to be used as a template. | |||
==== FGData ==== | |||
* {{fgdata source|path=Nasal/addons.nas}} | |||
==== FlightGear ==== | |||
* {{flightgear source|path=src/Main/options.cxx}} | |||
* {{flightgear source|path=src/Add-ons/}} |