Addon

From FlightGear wiki
(Redirected from Add-on)
Jump to navigation Jump to search
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.[1]

We now have a simple way to add addons to FlightGear without the need to mess around with FGData/Nasal or FGHome/Nasal directories.[2]

Installing and using an addon

Download and copy the addon to a directory on your computer.

If you use the launcher, select the Add-ons page from the icon bar on the left, then find the section Add-on Module folders and click the Add(+) button. Select the folder where you put the addon. Once the addon is shown in the list, make sure its check box is selected.

Use the command line switch --addon=/path/to/some/addon.[2]

Creating an addon

There is a very simple Skeleton addon available in FGAddon to be used as a template.[2] See flightgear/fgaddon/trunk/Addons/Skeleton.

A leading slash (/) in this section indicates the base directory of the directory structure of the addon.

Minimum configuration

An addon may be installed in a directory anywhere on your hard disk and need at least two files:

  • /addon-config.xml - A standard PropertyList XML file 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 initializer (addons.nas)

Additional common files

  • /addon-metadata.xml - A PropertyList XML file with metadata about the addon it.
  • /addon-menubar-items.xml - A PropertyList XML file describing menus to be added to the FlightGear menu bar.
  • /gui/dialogs/<my-foobar-dialog>.xml - PropertyList XML files to create custom dialogs.

Good to know

The new addon mechanism lets you add a addon-config.xml to override the settings in defaults.xml and other files.

That will allow an addon to

  • Override key bindings (as in the spoken ATC addon)
  • Add or override autopilots and property rules
  • Introduce XML state machines

Unless your really want to add/change/remove those at runtime, this should cater for most use cases.[3]

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

Sound Support

Sound support is available using fgcommand's.

See Nasal FAQ "play-audio-sample"

https://sourceforge.net/p/flightgear/flightgear/ci/5acf2e26d085b7553b2387b9753e9253e8b4bff4

Hackathon Proposal:Addon specific Sound Queues

Addon initialization

On initialization fgfs takes care of:

  • Through options.cxx:[2]
    • Creating a property under /addons/addon[n]/path=/path/to/some/addon
    • Loading /path/to/some/addon/addon-config.xml into the property tree (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)
  • Through addons.nas:
    • Loading /foo/bar/baz/addon-main.nas into namespace __addon[ADDON_ID]__
    • Calling main(addonGhost) from /foo/bar/baz/addon-main.nas.

Aircraft specific config (addon-hints)

Some addons need per-aircraft configuration. While addons should strive to be self-contained (ie. the addon should contain means to detect different aircraft and apply config from whithin the addon) there is also the possibility for the addon to read so called "addon-hints".

For this, a special property tree exists: /sim/addon-hints/<addon>/... The tree is expected to be populated from the aircraft.xml file. The addon can then read the properties from a common place regardless of loaded aircraft. 

<sim>
  <addon-hints>
    <my-addon>
        ...
    </my-addon>
  </addon-hints>
</sim>

APIs

For more details about these APIs, see the readme file, $FG_ROOT/Docs/README.add-ons.

C++ API

There is a C++ API on FlightGear's side that handle some on the addon related tasks manly through the AddonManager(), Addon() and AddonVersion() classes.

Nasal API

The Nasal add-on API lives in the 'addons' namespace and can for example do queries to AddonManager() and read data from addons.Addon 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: 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)[5]

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

We should absolutely stop telling anyone to edit preferences.xml in FG_ROOT; any documentation or advice which says to should be changes ASAP. [7]

As of 12/2017, the addon API is in the process of being significantly updated [8] [9] [10]

List of Addons

You can find the official repository at flightgear/fgaddon/trunk/Addons

Experimental Addons

Addons which are in the development stage/unfinished but can be used as a quick view of addon functionality

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) [20] [21]

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 ?[22] 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[23]

References

References
  1. ↑ Torsten  (Jul 19th, 2017).  Re: New Feature: Addon - "API" .
  2. ↑ 2.0 2.1 2.2 2.3 Torsten  (Jul 18th, 2017).  New Feature: Addon - "API" .
  3. ↑ Torsten  (Jul 23rd, 2017).  Re: Spoken .
  4. ↑ Torsten  (Jul 19th, 2017).  Re: Spoken ATC .
  5. ↑ Hooray  (Jun 11th, 2016).  Re: Whatever happened to radom radio .
  6. ↑ Hooray  (Jun 11th, 2016).  Re: Whatever happened to radom radio .
  7. ↑ zakalawe  (Oct 26th, 2013).  Re: NavCache:init failed:Sqlite error:Sqlite API abuse .
  8. ↑ https://sourceforge.net/p/flightgear/mailman/message/36146017/
  9. ↑ https://sourceforge.net/p/flightgear/mailman/message/36150159/
  10. ↑ https://sourceforge.net/p/flightgear/mailman/message/36150444/
  11. ↑ Roman Ludwicki (PlayeRom)  (Aug 14th, 2022).  Re: Aerotow Everywhere .
  12. ↑ Wayne Bragg (wlbragg) .  Re: Cargo Towing Addon .
  13. ↑ wkitty42  (Aug 13th, 2017).  Re: .
  14. ↑ Unknown, HHS (Nov 1th, 2018).  Re: .
  15. ↑ Stefan Frank  (Aug 8th, 2021).  Re: .
  16. ↑ ThomasS  (Aug 12th, 2017).  Re: .
  17. ↑ Roman Ludwicki (PlayeRom)  (Dec 11th, 2022).  Re: Logbook Add-on .
  18. ↑ RedGriffin  (Jan 6th, 2020).  Re: .
  19. ↑ Torsten  (Jul 10th, 2017).  Re: .
  20. ↑ https://sourceforge.net/p/flightgear/mailman/message/36399261/
  21. ↑ https://sourceforge.net/p/flightgear/mailman/message/36399261/
  22. ↑ Edward d'Auvergne  (Jul 19th, 2017).  Re: [Flightgear-devel] Simple API for creating FlightGear addons/plugins .
  23. ↑ Edward d'Auvergne  (Jul 19th, 2017).  Re: [Flightgear-devel] Simple API for creating FlightGear addons/plugins .

Related content

Wiki articles

Forum topics

Readme files

Source code

FGAddon

FGData

FlightGear

Retrieved from "https://wiki.flightgear.org/w/index.php?title=Addon&oldid=140241"