20,741
edits
Howto:Add new fgcommands to FlightGear: Difference between revisions
Jump to navigation
Jump to search
m
Howto:Add new fgcommands to FlightGear (view source)
Revision as of 13:57, 12 March 2015
, 12 March 2015no edit summary
m (→Adding new commands: https://gitorious.org/fg/flightgear/commit/956054afe719f6b4917017b2a070c7c804f62611#comment_110786) |
mNo edit summary |
||
| Line 228: | Line 228: | ||
fgcommand("hello_world", props.Node.new( {"name": "Howard Hughes"} )); | fgcommand("hello_world", props.Node.new( {"name": "Howard Hughes"} )); | ||
</syntaxhighlight> | </syntaxhighlight> | ||
= Adding new commands = | |||
All new commands must have the previously described signature, the functions should then be added to the list of built-in commands, beginning in line [http://gitorious.org/fg/flightgear/blobs/next/src/Main/fg_commands.cxx#line1552 1552]. The list of built-in commands maps the human-readable names used in README.commands to the names of the internal C++ functions implementing them. | |||
== Reaching out to subsystems == | == 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 system or the FDM system, this is accomplished by using the globals-> pointer, which allows you to access other subsystems easily. Please refer to [http://gitorious.org/fg/flightgear/blobs/next/src/Main/globals.cxx#line120 $FG_SRC/Main/globals.cxx] and its header file [http://gitorious.org/fg/flightgear/blobs/next/src/Main/globals.hxx globals.hxx]. A number of helpful usage examples can be found by searching fg_commands.cxx for "globals->". | 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. | ||
Please refer to [http://gitorious.org/fg/flightgear/blobs/next/src/Main/globals.cxx#line120 $FG_SRC/Main/globals.cxx] and its header file [http://gitorious.org/fg/flightgear/blobs/next/src/Main/globals.hxx globals.hxx]. A number of helpful usage examples can be found by searching fg_commands.cxx for "globals->". | |||
In general, you will always want to add a NULL pointer check to ensure that the corresponding subsystem handle could actually be retrieved: | In general, you will always want to add a NULL pointer check to ensure that the corresponding subsystem handle could actually be retrieved: | ||
| Line 247: | Line 253: | ||
A list of methods available to access certain subsystems is provided here in [http://gitorious.org/fg/flightgear/blobs/next/src/Main/globals.hxx#line220 globals.hxx, beginning in line 220]. | A list of methods available to access certain subsystems is provided here in [http://gitorious.org/fg/flightgear/blobs/next/src/Main/globals.hxx#line220 globals.hxx, beginning in line 220]. | ||
= | == Subsystem specific fgcommands == | ||
In addition to directly editing the default initialization routine in fg_init.cxx, you can also dynamically add/remove fgcommands from your SGSubsystem, by getting a handle to the SGCommandMgr singleton, specifying a command name, and a corresponding callback (which can be a static member of your SGSubsystem). | In addition to directly editing the default initialization routine in fg_init.cxx, you can also dynamically add/remove fgcommands from your SGSubsystem, by getting a handle to the SGCommandMgr singleton, specifying a command name, and a corresponding callback (which can be a static member of your SGSubsystem). | ||
| Line 290: | Line 294: | ||
</pre> | </pre> | ||
=== removing fgcommands === | |||
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: | 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: | ||
| Line 303: | Line 308: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
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. | === 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. | |||
Also, depending on the nature of functionality that you would like to add to FlightGear, you may want to use a more sophisticated method of adding new features, such as [[Howto:Extend Nasal|adding custom Nasal extension functions]], or [[Howto:Create new subsystems|adding a dedicated SGSubsystem]], a full property tree wrapper using listeners, or the cppbind framework in Simgear in order to expose full classes/objects. | |||
This was just an introduction intended to get you started, most of the missing information can be learned by referring to the plethora of existing fgcommands and seeing how they are implemented and working. | This was just an introduction intended to get you started, most of the missing information can be learned by referring to the plethora of existing fgcommands and seeing how they are implemented and working. | ||