Howto:Add new fgcommands to FlightGear: Difference between revisions

So there is a certain marshaling/conversion overhead involved here. While this is certainly negligible for simple commands that are run rarely, this overhead may add up once a certain fgcommand gets called repeatedly at a high rate. In such cases it may be more efficient to let the command work with argument lists (vectors) rather than just a single argument, so that multiple tasks can be completed by a single invocation.

Beginning with FlightGear 2.11+, new fgcommands can now also be implemented in [[Nasal]] and registered through new Nasal extension functions:

This allows you to make up new fgcommands just by implementing them in Nasal:

addcommand("hello", func {

  print("hello");

to process arguments, you can pass a property tree with nodes:

addcommand("hello", func(node) {

  print("hello ", node.getNode('name').getValue() );

</syntaxhighlight>

{{FGCquote

}}

* have static linkage

{{IO Restrictions}}

<syntaxhighlight lang="cpp">

Next, you could run the modified fgcommand by using the Nasal console (make sure to watch your console):

  fgcommand("null");

</syntaxhighlight>

These all need to be first set up in the property tree separately, i.e. using setprop:

  setprop("/temp1/path","my path" );

  setprop("/temp1/file","filename" );

You could just as well use a temporary property tree object, rather than the global property tree:

  var myTree = props.Node.new( {"filename": "stars.jpeg"} );

  fgcommand("null", myTree);

This would turn the hash initialized into a property tree structure, an even shorter version would be:

  fgcommand("null", props.Node.new( {"filename": "stars.jpeg"} ) );

</syntaxhighlight>

In general, using a temporary property tree object is preferable and recommended if you don't need to access the data in the global property tree otherwise.

<syntaxhighlight lang="cpp">

== Exception handling ==

To be on the safe side, complex fgcommands, which may terminate for one reason or another (such as missing files), should make use of exception handling to catch exceptions and deal with them gracefully, so that they cannot affect the simulator critically.  

This is accomplished by using standard C++ try/catch blocks, usually catching an sg_exception. The SG_LOG() macro can be used to print debugging information to the console. If you'd like to display error information using the native FlightGear GUI, you can use the "guiErrorMessage(const char*,sg_exception)" helper.

<syntaxhighlight lang="cpp">

== Hello World ==

For example, to implement a new "hello_world" command, that accepts a single parameter named "name":

After adding the new callback to the callback list and rebuilding FlightGear, you can easily invoke the new "hello_world" fgcommand using the Nasal console like this:

  fgcommand("hello_world", props.Node.new( {"name": "Howard Hughes"} ));

</syntaxhighlight>

= Adding new commands =

== Reaching out to subsystems ==

Quite possibly, you may need to reach out to some other subsystems to implement a certain fgcommand, such as accessing the sound system, the networking/multiplayer system or the FDM system, this is accomplished by using the <code>globals-></code> pointer, which allows you to access other subsystems easily.  

In general, you will always want to add a NULL pointer check to ensure that the corresponding subsystem handle could actually be retrieved:

Equally, it may be appropriate to wrap code in between try/catch blocks, too.

== Subsystem specific fgcommands ==

fgcommands having implicit dependencies on other subsystems, should not be added in a hard-coded fashion, but via the ctor/init or postinit() methods of the corresponding subsystem itself - otherwise, such code is conflicting with James' reset/-reinit work - in particular, the very fgcommands intended to allow subsystems to be shut-down and re-initialized.

Even if such additions don't break FG immediately, they contribute to crippling the reset/re-init effort - and will make it increasingly difficult to allow run-time dependencies to be better established and formalized.

We've had a long discussion about this exact issue WRT to Nasal/CppBind bindings added unconditionally, which is causing the same problem. The general consensus was that subsystem-specific functionality must be initialized and cleaned up by the corresponding subsystem itself, instead of always assuming that all subsystems are available.

<syntaxhighlight lang="cpp">

#include <simgear/structure/commands.hxx>

</pre>

Equally, there's an API for removing fgcommands on demand, e.g. when shutting down a subsystem - which would be typically done inside your SGSubsystem's dtor:

== Finally ==

When you send patches or file merge requests for new fgcommands, please also make sure to send patches for README.commands, too - so that your new commands are documented there. Otherwise, people may have a hard time using/maintaining your fgcommands, possibly years after you added them, without you even being around by then.