FlightGear wiki - User contributions [en]

Howto talk:Start core development

2026-05-28T14:19:02Z

Servo: /* Duplicating docs.flightgear.org */

== Open questions ==
* merge requests (post follow-up to mailing list and file review via issue tracker)
{{unsigned|12:46, 6 May 2012‎|Hooray}}

== Planned improvements ==
* navigating the source trees (FG + SG)
* FG entry point (bootstrap.cxx)
* the FG main loop
* FG subsystems
* adding new fgcommands
* adding new network protocols
* adding new telnet/props commands
* adding new startup options (options.cxx)
* adding new subsystems
* networking
* scripting
* GUI code
* instruments
* list of FG related projects (URLs, type of software)
* list of FG related websites
* list of FG related people (i.e. developers)
* gdb, valgrind, gprof, gcov
{{unsigned|15:48, 3 January - 01:27, 7 January 2012‎|Hooray}}

== Use of "repo" links in wiki pages. ==

I'm not sure there's much advantage to using the "repo" link system. It's an abstraction that protects us against something that happens extremely rarely (changing of the main git repositories) at the cost of an obscure macro-like thing in the wiki text. Personally i'm with the Python philosophy of "Explicit is better than implicit" in this case. Apart from anything else, the most likely change to repositories is not a simple move to different location, but a merging of flightgear and simgear into a single repository, for which the repo macro is useless. [[User:Cgdae|Cgdae]] ([[User talk:Cgdae|talk]]) 10:34, 22 November 2020 (EST)

: It was agreed on by the people involved in updating the wiki after the last migration, and given that another migration is currently being discussed, it might not be such a bad idea. I do think that the existing macros could be adapted to reflect a merged repository (if the need arises). If in doubt, Johan and bugman were primarily involved in establishing these "link templates", but it seemed other wiki admins were also convinced it's a good idea, here's the original context: http://wiki.flightgear.org/index.php?title=FlightGear_wiki:Village_pump&oldid=87148#Repository_link_templates --[[User:Hooray|Hooray]] ([[User talk:Hooray|talk]]) 11:09, 22 November 2020 (EST)

:: I manually did the large part of that migration myself. The pain is insane! The changes could not be scripted - my attempts ended in a large proportion of dead links. There is too much variability and redundancy in the PHP query strings. I dealt with something like 5000 dead gitorious links manually, one by one. It took me weeks, and innumerable hours of work. If there is another infrastructure change, now with the {{tl|repo link}} family of templates I can migrate all of those 5000 links within seconds. Or if SourceForge, GitHub, GitLab, or the Gitorious archive change their URLs or PHP query string interface, I can fix all links within a single location. In 20 years we will still have the wiki and we would probably have gone through one or two infrastructure migrations, just as we have been through 3 different infrastructures in the previous 20 years (Curt's CVS server, Gitorious, and SourceForge). So there is a very big advantage for the long term viability of the wiki.

:: A merged repository is also no problem for these templates. Just as I experimented with creating that merged repository, I also looked into what is required for the templates, and this is trivial (either for a merged repository, a submodule, or a subtree).

:: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 16:32, 22 November 2020 (EST)

::: Agreed, I am entirely with bugman on this ...wiki admins (and hosting providers) come and go, but we don't really have many people interested in doing such tedious work. In fact, I wish there were more people with the privileges that Simon and Gijs have, so this mediawiki installation itself could be better maintained here. For instance, these template are enormously helpful, but obviously it could really go a long way if such helper templates were properly integrated in the WYSIWYG editor/interface - this, and many similar requests have been made over the years, but were rarely implemented by our server admins. Thus, templates like these are a compromise obviously, but I'd rather use these than have no option at all. So, thank you bugman for all your work here !! (to be fair, {{Usr|Red Leader}} did have an instrumental role in the development of the original idea. --[[User:Hooray|Hooray]] ([[User talk:Hooray|talk]]) 16:40, 22 November 2020 (EST)

:::: To be fair, you'd need to have seen it or looked at the {{tl|repo link}} history to know that I did some major work on that template. From its history it is clear that {{usr|Red Leader}} started these templates. I only extended the family and the dealt with the direct and dead link Gitorious mess.

:::: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 16:55, 22 November 2020 (EST)

Ok, fair enough, thanks everyone for explaining things.

Is there more information about the repository links system somewhere? I couldn't see anything in [[Special:SpecialPages]] for example?

[[User:Cgdae|Cgdae]] ([[User talk:Cgdae|talk]]) 05:22, 23 November 2020 (EST)

: Everything is reachable from [[:Category:Repository_link_templates]], and each template is documented. Maybe the table in {{tl|Repo link/doc related}} could be better documented?

: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 05:27, 23 November 2020 (EST)

== YouTube playlist link not working ==

Hi, I just found out that the link to the YouTube tutorial playlist doesn't work any more, as YouTube changed their playlist links and ID's: http://www.youtube.com/view_play_list?p=1D6727247CA35794. I also wasn't able to find the playlist on YouTube.
[[User:The FL3dd0x|The FL3dd0x]] ([[User talk:The FL3dd0x|talk]]) 13:12, 9 May 2021 (UTC)

== Duplicating docs.flightgear.org ==

Hi Servo,

Thanks for all the hard work you're doing on the wiki!

In this case, I'd strongly discourage copying content from docs.flightgear.org to the wiki. The whole idea is that documentation like this is moved/rewritten to docs.flightgear.org, not the other way around. Having to maintain it in two places is a nightmare and undermines the goal of having a central docs repo.

[[User:Gijs|Gijs]] ([[User talk:Gijs|talk]]) 12:50, 28 May 2026 (UTC)

: oh, thanks. I just want to replace the out-of-date content.

: [[User:Servo|Servo]] ([[User talk:Servo|talk]]) 14:18, 28 May 2026 (UTC)

Howto talk:Start core development

2026-05-28T14:18:25Z

Servo:

Howto talk:Start core development

2026-05-28T14:09:18Z

Servo: /* Duplicating docs.flightgear.org */

== Open questions ==
* merge requests (post follow-up to mailing list and file review via issue tracker)
{{unsigned|12:46, 6 May 2012‎|Hooray}}

== Planned improvements ==
* navigating the source trees (FG + SG)
* FG entry point (bootstrap.cxx)
* the FG main loop
* FG subsystems
* adding new fgcommands
* adding new network protocols
* adding new telnet/props commands
* adding new startup options (options.cxx)
* adding new subsystems
* networking
* scripting
* GUI code
* instruments
* list of FG related projects (URLs, type of software)
* list of FG related websites
* list of FG related people (i.e. developers)
* gdb, valgrind, gprof, gcov
{{unsigned|15:48, 3 January - 01:27, 7 January 2012‎|Hooray}}

== Use of "repo" links in wiki pages. ==

I'm not sure there's much advantage to using the "repo" link system. It's an abstraction that protects us against something that happens extremely rarely (changing of the main git repositories) at the cost of an obscure macro-like thing in the wiki text. Personally i'm with the Python philosophy of "Explicit is better than implicit" in this case. Apart from anything else, the most likely change to repositories is not a simple move to different location, but a merging of flightgear and simgear into a single repository, for which the repo macro is useless. [[User:Cgdae|Cgdae]] ([[User talk:Cgdae|talk]]) 10:34, 22 November 2020 (EST)

: It was agreed on by the people involved in updating the wiki after the last migration, and given that another migration is currently being discussed, it might not be such a bad idea. I do think that the existing macros could be adapted to reflect a merged repository (if the need arises). If in doubt, Johan and bugman were primarily involved in establishing these "link templates", but it seemed other wiki admins were also convinced it's a good idea, here's the original context: http://wiki.flightgear.org/index.php?title=FlightGear_wiki:Village_pump&oldid=87148#Repository_link_templates --[[User:Hooray|Hooray]] ([[User talk:Hooray|talk]]) 11:09, 22 November 2020 (EST)

:: I manually did the large part of that migration myself. The pain is insane! The changes could not be scripted - my attempts ended in a large proportion of dead links. There is too much variability and redundancy in the PHP query strings. I dealt with something like 5000 dead gitorious links manually, one by one. It took me weeks, and innumerable hours of work. If there is another infrastructure change, now with the {{tl|repo link}} family of templates I can migrate all of those 5000 links within seconds. Or if SourceForge, GitHub, GitLab, or the Gitorious archive change their URLs or PHP query string interface, I can fix all links within a single location. In 20 years we will still have the wiki and we would probably have gone through one or two infrastructure migrations, just as we have been through 3 different infrastructures in the previous 20 years (Curt's CVS server, Gitorious, and SourceForge). So there is a very big advantage for the long term viability of the wiki.

:: A merged repository is also no problem for these templates. Just as I experimented with creating that merged repository, I also looked into what is required for the templates, and this is trivial (either for a merged repository, a submodule, or a subtree).

:: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 16:32, 22 November 2020 (EST)

::: Agreed, I am entirely with bugman on this ...wiki admins (and hosting providers) come and go, but we don't really have many people interested in doing such tedious work. In fact, I wish there were more people with the privileges that Simon and Gijs have, so this mediawiki installation itself could be better maintained here. For instance, these template are enormously helpful, but obviously it could really go a long way if such helper templates were properly integrated in the WYSIWYG editor/interface - this, and many similar requests have been made over the years, but were rarely implemented by our server admins. Thus, templates like these are a compromise obviously, but I'd rather use these than have no option at all. So, thank you bugman for all your work here !! (to be fair, {{Usr|Red Leader}} did have an instrumental role in the development of the original idea. --[[User:Hooray|Hooray]] ([[User talk:Hooray|talk]]) 16:40, 22 November 2020 (EST)

:::: To be fair, you'd need to have seen it or looked at the {{tl|repo link}} history to know that I did some major work on that template. From its history it is clear that {{usr|Red Leader}} started these templates. I only extended the family and the dealt with the direct and dead link Gitorious mess.

:::: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 16:55, 22 November 2020 (EST)

Ok, fair enough, thanks everyone for explaining things.

Is there more information about the repository links system somewhere? I couldn't see anything in [[Special:SpecialPages]] for example?

[[User:Cgdae|Cgdae]] ([[User talk:Cgdae|talk]]) 05:22, 23 November 2020 (EST)

: Everything is reachable from [[:Category:Repository_link_templates]], and each template is documented. Maybe the table in {{tl|Repo link/doc related}} could be better documented?

: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 05:27, 23 November 2020 (EST)

== YouTube playlist link not working ==

Hi, I just found out that the link to the YouTube tutorial playlist doesn't work any more, as YouTube changed their playlist links and ID's: http://www.youtube.com/view_play_list?p=1D6727247CA35794. I also wasn't able to find the playlist on YouTube.
[[User:The FL3dd0x|The FL3dd0x]] ([[User talk:The FL3dd0x|talk]]) 13:12, 9 May 2021 (UTC)

== Duplicating docs.flightgear.org ==

Hi Servo,

Thanks for all the hard work you're doing on the wiki!

In this case, I'd strongly discourage copying content from docs.flightgear.org to the wiki. The whole idea is that documentation like this is moved/rewritten to docs.flightgear.org, not the other way around. Having to maintain it in two places is a nightmare and undermines the goal of having a central docs repo.

[[User:Gijs|Gijs]] ([[User talk:Gijs|talk]]) 12:50, 28 May 2026 (UTC)

oh, thanks. I just want to replace the out-of-date content.

Volunteer

2026-05-28T08:05:13Z

Servo: /* Check out the Discord server */

{{Volunteer Intro}}

== Media ==
=== Screenshots ===
Another easy way for getting started contributing is to create nice FlightGear screenshots. You can upload these to the wiki where they can then be used to illustrate articles and to highlight articles via the [[:Category:Picture of the week|picture of the week]] on the main page.

[[Howto: Make nice screenshots]] provides some tips on how to create stunning shots, while [[Help:Upload]] discusses how to upload screenshots to the wiki.

=== Videos ===
Many users like to capture their flights in FlightGear as a video, [[YouTube channels|YouTube]] for example is an excellent way for sharing such videos with fellow FlightGear users. YouTube videos can also be directly embedded in forum postings and wiki articles.

=== Screencasts (video tutorials) ===
Creating FlightGear related video tutorials is another excellent way for getting started contributing.

== Documentation ==
{{forum|72|FlightGear Documentation}}

=== FAQ-Maintainers ===
The FlightGear project is looking for people who are willing to help maintain the FAQ which, given the constant development of the project, is chronically out of date. If you you would like to get involved, follow the {{forum link|text=forum}} to stay current on the latest news, problems, and of course on what questions are asked more frequently, and simply start editing the [[FAQ|wiki FAQ]].

=== Maintaining the wiki ===
You can easily [[Special:UserLogin|register an account]] and help [[Portal:Wiki|improve the wiki]], and provide your help in reviewing articles, fixing their look and readability, updating them and adding what you think is missing, for example many articles could be greatly improved just by adding a handful of relevant screenshots for illustration purposes. Proof reading of existing articles is also greatly appreciated.

Registering takes less than a minute. After registration, you'll have to confirm your registration by clicking on the link sent to you by email.

=== Translating the wiki and FlightGear ===
You can also help localize the wiki by [[Help:Translate|translating]] important articles into different languages. Please see the [[translation requests]].

Also, FlightGear itself can be easily translated by updating the files in [[$FG_ROOT]]/Translations. For details please see [[Howto: Translate FlightGear|Translating FlightGear]].

=== Wiki article writers ===
Various aspects of FlightGear are currently not yet sufficiently documented, and available documentation is often not really suitable to be used by non-developers. This results in users being unaware of the wide range of features and possibilities that FlightGear supports already.

As an "article writer" you should be able to document your own experiences with FlightGear in a clear and concise [[FlightGear wiki:Manual of Style|style]], so that others can easily follow your instructions in order to make use of the less known features of FlightGear. These articles don't need to be very comprehensive, they shall only provide users with easy to follow instructions on how to achieve something, and possibly some caveats and hints.

* [[:Category:Volunteer: Writing]]

=== Contributing to the manual ===
The wiki is not the only documentation here, of course. FlightGear comes with a set of illustrated documentation, notably [[FlightGear Manual|"The Manual"]]. If you are skilled and a little bit familiar with LaTex, your help would be really welcome. More on this at the [[manual]] wiki page. You'll find the source code in the {{getstart source|text=Getstart repository}}.

=== Documentation Editors/Reviewers ===
{{Main article|Howto:Write a FlightGear Review}}
The documentation that comes with FlightGear base package might be inaccurate (outdated) due to the advances in FlightGear's code. You can check the current documentation and identify areas for improvement, by directly making corresponding suggestions for augmentations, or even writing new help documents altogether, while staying current with the mailing list.

Smaller corrections shall be sent by email to the developer mailing list, preferably in unified diff format (for patch to work). Alternatively, small text files can also be sent directly to the mailing list, more complex modifications should be only made available by uploading them to a webpage and linking to the corresponding files from your emails.

If you intend to redo a major part of the current documentation, first discuss this with the developers, to avoid documenting code that may also be under development or deprecation.

== Development ==
=== Creating interactive tutorials ===
FlightGear has a built-in [[Tutorials|tutorial]] system that is based on its scripting language [[Nasal]], this system is very flexible and can be used for creating interactive tutorials (or even missions) for use in FlightGear itself, in other words these tutorials run directly in the simulator.

Creating new tutorials, or updating and improving existing ones, is another great way for getting more familiar with FlightGear. For details please see [[Tutorials]].

=== Providing patches for aircraft's -set.xml status fields ===
One way you could easily contribute would be to submit patches to HEAD setting the "status" flag on each aircraft accurately. While it will require learning a bit about SCM, and XML, that would be a fine contribution. For a details on how the status should be arrived at see [[Aircraft status indication]].

=== Creating Scenery Models ===
The FlightGear project maintains a steadily growing repository of [http://scenemodels.flightgear.org 3D models] for adding some eye-candy to the scenery. The world has always enough room left for your [http://scenemodels.flightgear.org/contribute.php contribution]. Please take the time to investigate what is already there and enjoy populating your favourite area.

Note that you don't have to create any models yourself. You can simply [[Howto: Place 3D objects with the UFO|place existing models using the UFO]]. For example, placing objects in the scenery with the [[UFO]] and submitting them to the database is pretty straightforward and takes very little time. Even an hour spent doing this makes a difference.

If anyway you'd like to [[Modeling - Getting Started|test your modeling skills]], here some suggestions:
* We need people to go out and take good pictures of all the buildings at their local airports, build models, and create textures (that could be different people for each task).
* We need people to start modelling identifiable human-made landmarks like bridges, stadiums, and major buildings. Around the San Francisco Bay area, bridges are especially important. Once you have identified some buildings or objects you would like to have (Aircraft carriers, fuel bowsers, cars, towers, ...) you will need to check out the tools for creating and placing these objects.

It would be helpful if people would model the area they are interested in. Generally contributions are going to be from FlightGear users who find scenery lacking in some area and choose to improve it. You are encouraged to research your own area for airport, navaid and scenery information, to contribute the data or dive right in to airport and scenery design.

=== Making airports ===
Sometimes you'd like to populate your favourite airport with objects, but you find it has a wrong layout or that it doesn't exist at all! So, you'll want to [[Howto:Make an airport|make or improve that layout]], which can be done with [[WED]]. Remember that we're maintaining an open (GPL) airport database in common with X-Plane simulator.

Other than just fix the look, you might want to add interactive details like [[AI Traffic]] and maybe update navaids and comm frequencies. We need people to go over paper lists and airport diagrams for countries that don't publish air navigation data free online (i.e. almost everyone but the U.S.) and fill in the blanks in our navaid and airport databases.

To be sure the airport you're interested in is not already being worked on, check the [[Airports under construction]] article. Also, note that since we switched to a newer format for the airport database, there are many airports that need to be converted from the older (810) format to the newer (850). All the info is in [[Howto:Make an airport]].

=== Contributing to the scenery terrain ===
We need people to collect geodata to give us more accurate roads, rivers, etc., especially outside the U.S. and Europe. Note that since we're now allowed to use OpenStreetMap data for this, you might consider contributing to that project too. With time, more and more features will be imported from OSM, beginning with roads and rails, and going on with power lines and antennas and whatnot.

The first step into this is learning how to [[Using TerraGear|use TerraGear]]. Remember that all the data you plan to use must be GPL compatible. You might also consider editing some of that source data and contribute it to the Scenery Project that would make good use of it!

=== Core development ===
{{Main article|Howto:Start core development}}
If you know Git, consider contributing to the [[Howto:Start core development|core development]] at [https://gitlab.com/flightgear gitlab.com/flightgear]. Apart from the three core repositories (simgear, flightgear and terragear), you don't need to have an in-depth understanding of C++.

== Other ==
=== Submitting bugs to the Bug Tracker ===
Bugs can be reported to {{tickets|the issue tracker}} (select the respective project, or <code>flightgear</code> if unsure). Reporting bugs accurately helps make bug fixing significantly easier for the developers. Another thing that is very helpful, is reviewing posted bug reports and see if you can reproduce/confirm them on your system.

=== Artwork Creators/Contributors ===
FlightGear itself would not be possible without the contribution of various types of artwork:
* Aircraft developers need photographs, images and sounds to realistically model a particular aircraft.
* The splash screen displayed when loading the simulator can be personalized, and you can [[Howto: Create custom splash screens|create one for your favourite aircraft]].
* Sound recordings of aircraft are also very valuable - particularly engine sounds for unusual aircraft.

In general, you can find requests and post your offers of this kind in the Developers forum, but you can also browse [[:Category:Aircraft by status|existing aircraft projects]] and see if there's anything you'd like to improve.

=== Pre-Release Testers ===
Prior to a release, release candidates are provided to the community. By directly providing feedback about your experiences with FlightGear's development code, you will become a crucial part of the development process and you will basically serve as quality control for FlightGear, your experiences will determine whether FlightGear's development code is ready for a next official release or not. See the [[Release plan]] to find out when release candidates will be distributed.

Note: If you are interested in actually doing development for FlightGear, make sure to check out the [[Portal:Developer|Developer section]].

=== Hosting a multiplayer server ===
If you have access to an Unix based server, another good opportunity for contributing would be to set up a multiplayer server for use with FlightGear, for details please check out [[Howto: Set up a multiplayer server]].

=== Tell us if FlightGear works with your hardware ===
You can help fellow FlightGear users by telling us if FlightGear works with your hardware. Please see [[Hardware Recommendations]].

=== Participate in the FlightGear Forums ===
If you haven't done so already, please consider registering at the {{forum link|text=FlightGear forum}}, this is a very simple thing to do, but it makes it very easy to obtain and provide help and other support within the FlightGear community.

Taking extra care in your posting to avoid requiring the attention of the moderators is in some ways also a contribution. Doing so helps self-police the forums so that the moderators can spend their time doing constructive development.

=== Check out the Discord server ===
{{Main article|Discord}}
To talk to fellow FlightGear users in realtime, you may want to check out our [[Discord]] server (and other unofficial servers). This is also an excellent way for getting and providing community help.

=== Tell us about your own ideas and feature requests for improving FlightGear ===
If you think you have a good idea or feature request for improving FlightGear, the FlightGear forums and the IRC channel are also an excellent way for getting feedback.

Another new way for posting feature requests and making suggestions is provided at http://flightgear-bugs.googlecode.com

=== Help us write the FlightGear Newsletter ===
The FlightGear newsletter is a community driven newsletter that is created and edited using the wiki. All FlightGear users are invited to contribute to the newsletter. The only thing that is required is a wiki account, which is free and easy to register.

Please feel free to add news about your own FlightGear related projects, or projects started by others to the newsletter.

You can find the draft of next month's newsletter at: [[Next newsletter]]

Just tracking the forums, mailing lists or the IRC channel should provide you with plenty of opportunities for things that could be added to the newsletter. One simple thing for getting started - even without writing anything - is uploading screen shots showing recent FlightGear developments for use in the FlightGear newsletter.

=== Reviews ===
Another thing that can be easily done is reviewing FlightGear (or just certain parts of it, like for example scenery and/or aircraft) and submit your reviews to some of the flight simulation portals. Of course, you can also directly write your reviews using the FlightGear wiki, see: [[FlightGear Reviews]].

[[Category:Contribution requests]]
[[Category:Community]]

[[es:Tener a bien]]
[[fr:Volontaires]]

Volunteer

2026-05-28T08:04:47Z

Servo: minor improvements

{{Volunteer Intro}}

== Media ==
=== Screenshots ===
Another easy way for getting started contributing is to create nice FlightGear screenshots. You can upload these to the wiki where they can then be used to illustrate articles and to highlight articles via the [[:Category:Picture of the week|picture of the week]] on the main page.

[[Howto: Make nice screenshots]] provides some tips on how to create stunning shots, while [[Help:Upload]] discusses how to upload screenshots to the wiki.

=== Videos ===
Many users like to capture their flights in FlightGear as a video, [[YouTube channels|YouTube]] for example is an excellent way for sharing such videos with fellow FlightGear users. YouTube videos can also be directly embedded in forum postings and wiki articles.

=== Screencasts (video tutorials) ===
Creating FlightGear related video tutorials is another excellent way for getting started contributing.

== Documentation ==
{{forum|72|FlightGear Documentation}}

=== FAQ-Maintainers ===
The FlightGear project is looking for people who are willing to help maintain the FAQ which, given the constant development of the project, is chronically out of date. If you you would like to get involved, follow the {{forum link|text=forum}} to stay current on the latest news, problems, and of course on what questions are asked more frequently, and simply start editing the [[FAQ|wiki FAQ]].

=== Maintaining the wiki ===
You can easily [[Special:UserLogin|register an account]] and help [[Portal:Wiki|improve the wiki]], and provide your help in reviewing articles, fixing their look and readability, updating them and adding what you think is missing, for example many articles could be greatly improved just by adding a handful of relevant screenshots for illustration purposes. Proof reading of existing articles is also greatly appreciated.

Registering takes less than a minute. After registration, you'll have to confirm your registration by clicking on the link sent to you by email.

=== Translating the wiki and FlightGear ===
You can also help localize the wiki by [[Help:Translate|translating]] important articles into different languages. Please see the [[translation requests]].

Also, FlightGear itself can be easily translated by updating the files in [[$FG_ROOT]]/Translations. For details please see [[Howto: Translate FlightGear|Translating FlightGear]].

=== Wiki article writers ===
Various aspects of FlightGear are currently not yet sufficiently documented, and available documentation is often not really suitable to be used by non-developers. This results in users being unaware of the wide range of features and possibilities that FlightGear supports already.

As an "article writer" you should be able to document your own experiences with FlightGear in a clear and concise [[FlightGear wiki:Manual of Style|style]], so that others can easily follow your instructions in order to make use of the less known features of FlightGear. These articles don't need to be very comprehensive, they shall only provide users with easy to follow instructions on how to achieve something, and possibly some caveats and hints.

* [[:Category:Volunteer: Writing]]

=== Contributing to the manual ===
The wiki is not the only documentation here, of course. FlightGear comes with a set of illustrated documentation, notably [[FlightGear Manual|"The Manual"]]. If you are skilled and a little bit familiar with LaTex, your help would be really welcome. More on this at the [[manual]] wiki page. You'll find the source code in the {{getstart source|text=Getstart repository}}.

=== Documentation Editors/Reviewers ===
{{Main article|Howto:Write a FlightGear Review}}
The documentation that comes with FlightGear base package might be inaccurate (outdated) due to the advances in FlightGear's code. You can check the current documentation and identify areas for improvement, by directly making corresponding suggestions for augmentations, or even writing new help documents altogether, while staying current with the mailing list.

Smaller corrections shall be sent by email to the developer mailing list, preferably in unified diff format (for patch to work). Alternatively, small text files can also be sent directly to the mailing list, more complex modifications should be only made available by uploading them to a webpage and linking to the corresponding files from your emails.

If you intend to redo a major part of the current documentation, first discuss this with the developers, to avoid documenting code that may also be under development or deprecation.

== Development ==
=== Creating interactive tutorials ===
FlightGear has a built-in [[Tutorials|tutorial]] system that is based on its scripting language [[Nasal]], this system is very flexible and can be used for creating interactive tutorials (or even missions) for use in FlightGear itself, in other words these tutorials run directly in the simulator.

Creating new tutorials, or updating and improving existing ones, is another great way for getting more familiar with FlightGear. For details please see [[Tutorials]].

=== Providing patches for aircraft's -set.xml status fields ===
One way you could easily contribute would be to submit patches to HEAD setting the "status" flag on each aircraft accurately. While it will require learning a bit about SCM, and XML, that would be a fine contribution. For a details on how the status should be arrived at see [[Aircraft status indication]].

=== Creating Scenery Models ===
The FlightGear project maintains a steadily growing repository of [http://scenemodels.flightgear.org 3D models] for adding some eye-candy to the scenery. The world has always enough room left for your [http://scenemodels.flightgear.org/contribute.php contribution]. Please take the time to investigate what is already there and enjoy populating your favourite area.

Note that you don't have to create any models yourself. You can simply [[Howto: Place 3D objects with the UFO|place existing models using the UFO]]. For example, placing objects in the scenery with the [[UFO]] and submitting them to the database is pretty straightforward and takes very little time. Even an hour spent doing this makes a difference.

If anyway you'd like to [[Modeling - Getting Started|test your modeling skills]], here some suggestions:
* We need people to go out and take good pictures of all the buildings at their local airports, build models, and create textures (that could be different people for each task).
* We need people to start modelling identifiable human-made landmarks like bridges, stadiums, and major buildings. Around the San Francisco Bay area, bridges are especially important. Once you have identified some buildings or objects you would like to have (Aircraft carriers, fuel bowsers, cars, towers, ...) you will need to check out the tools for creating and placing these objects.

It would be helpful if people would model the area they are interested in. Generally contributions are going to be from FlightGear users who find scenery lacking in some area and choose to improve it. You are encouraged to research your own area for airport, navaid and scenery information, to contribute the data or dive right in to airport and scenery design.

=== Making airports ===
Sometimes you'd like to populate your favourite airport with objects, but you find it has a wrong layout or that it doesn't exist at all! So, you'll want to [[Howto:Make an airport|make or improve that layout]], which can be done with [[WED]]. Remember that we're maintaining an open (GPL) airport database in common with X-Plane simulator.

Other than just fix the look, you might want to add interactive details like [[AI Traffic]] and maybe update navaids and comm frequencies. We need people to go over paper lists and airport diagrams for countries that don't publish air navigation data free online (i.e. almost everyone but the U.S.) and fill in the blanks in our navaid and airport databases.

To be sure the airport you're interested in is not already being worked on, check the [[Airports under construction]] article. Also, note that since we switched to a newer format for the airport database, there are many airports that need to be converted from the older (810) format to the newer (850). All the info is in [[Howto:Make an airport]].

=== Contributing to the scenery terrain ===
We need people to collect geodata to give us more accurate roads, rivers, etc., especially outside the U.S. and Europe. Note that since we're now allowed to use OpenStreetMap data for this, you might consider contributing to that project too. With time, more and more features will be imported from OSM, beginning with roads and rails, and going on with power lines and antennas and whatnot.

The first step into this is learning how to [[Using TerraGear|use TerraGear]]. Remember that all the data you plan to use must be GPL compatible. You might also consider editing some of that source data and contribute it to the Scenery Project that would make good use of it!

=== Core development ===
{{Main article|Howto:Start core development}}
If you know Git, consider contributing to the [[Howto:Start core development|core development]] at [https://gitlab.com/flightgear gitlab.com/flightgear]. Apart from the three core repositories (simgear, flightgear and terragear), you don't need to have an in-depth understanding of C++.

== Other ==
=== Submitting bugs to the Bug Tracker ===
Bugs can be reported to {{tickets|the issue tracker}} (select the respective project, or <code>flightgear</code> if unsure). Reporting bugs accurately helps make bug fixing significantly easier for the developers. Another thing that is very helpful, is reviewing posted bug reports and see if you can reproduce/confirm them on your system.

=== Artwork Creators/Contributors ===
FlightGear itself would not be possible without the contribution of various types of artwork:
* Aircraft developers need photographs, images and sounds to realistically model a particular aircraft.
* The splash screen displayed when loading the simulator can be personalized, and you can [[Howto: Create custom splash screens|create one for your favourite aircraft]].
* Sound recordings of aircraft are also very valuable - particularly engine sounds for unusual aircraft.

In general, you can find requests and post your offers of this kind in the Developers forum, but you can also browse [[:Category:Aircraft by status|existing aircraft projects]] and see if there's anything you'd like to improve.

=== Pre-Release Testers ===
Prior to a release, release candidates are provided to the community. By directly providing feedback about your experiences with FlightGear's development code, you will become a crucial part of the development process and you will basically serve as quality control for FlightGear, your experiences will determine whether FlightGear's development code is ready for a next official release or not. See the [[Release plan]] to find out when release candidates will be distributed.

Note: If you are interested in actually doing development for FlightGear, make sure to check out the [[Portal:Developer|Developer section]].

=== Hosting a multiplayer server ===
If you have access to an Unix based server, another good opportunity for contributing would be to set up a multiplayer server for use with FlightGear, for details please check out [[Howto: Set up a multiplayer server]].

=== Tell us if FlightGear works with your hardware ===
You can help fellow FlightGear users by telling us if FlightGear works with your hardware. Please see [[Hardware Recommendations]].

=== Participate in the FlightGear Forums ===
If you haven't done so already, please consider registering at the {{forum link|text=FlightGear forum}}, this is a very simple thing to do, but it makes it very easy to obtain and provide help and other support within the FlightGear community.

Taking extra care in your posting to avoid requiring the attention of the moderators is in some ways also a contribution. Doing so helps self-police the forums so that the moderators can spend their time doing constructive development.

=== Check out the Discord server ===
{{Main article|Discord}}
To talk to fellow FlightGear users in realtime, you may want to check out our [[Discord]] server (and other smaller unofficial servers). This is also an excellent way for getting and providing community help.

=== Tell us about your own ideas and feature requests for improving FlightGear ===
If you think you have a good idea or feature request for improving FlightGear, the FlightGear forums and the IRC channel are also an excellent way for getting feedback.

Another new way for posting feature requests and making suggestions is provided at http://flightgear-bugs.googlecode.com

=== Help us write the FlightGear Newsletter ===
The FlightGear newsletter is a community driven newsletter that is created and edited using the wiki. All FlightGear users are invited to contribute to the newsletter. The only thing that is required is a wiki account, which is free and easy to register.

Please feel free to add news about your own FlightGear related projects, or projects started by others to the newsletter.

You can find the draft of next month's newsletter at: [[Next newsletter]]

Just tracking the forums, mailing lists or the IRC channel should provide you with plenty of opportunities for things that could be added to the newsletter. One simple thing for getting started - even without writing anything - is uploading screen shots showing recent FlightGear developments for use in the FlightGear newsletter.

=== Reviews ===
Another thing that can be easily done is reviewing FlightGear (or just certain parts of it, like for example scenery and/or aircraft) and submit your reviews to some of the flight simulation portals. Of course, you can also directly write your reviews using the FlightGear wiki, see: [[FlightGear Reviews]].

[[Category:Contribution requests]]
[[Category:Community]]

[[es:Tener a bien]]
[[fr:Volontaires]]

Howto:Start core development

2026-05-28T07:19:35Z

Servo: advanced

{{note|You'll need to familiarize yourself with setting up a development environment and building FlightGear in order to contribute code. See
[https://docs.flightgear.org/contributors-guide/guidelines/building.html Developing on the codebase] if you do not already
have a working setup. Some understanding of ''Git'' will also be
necessary; this free, online [https://git-scm.com/book/en/v2 Git book] is quite useful.}}

This page introduces how to contribute to the core [[FlightGear Git|Git repositories]] of [[FlightGear]].

= Filing pull requests =

The most efficient way to contribute changes to the FlightGear code base is to
file a merge request (this doesn't apply to [[aircraft]] or [[addon|add-ons]], which are
managed differently). We'll first give an overview of the process including
its main prerequisites, then explain each step in more detail.

== Overview ==

The basic workflow for first-time contributors to a core [[Git]] repository
is:

#. '''Fork the repository.'''
Fork the relevant FlightGear repository into your GitLab account. You will
need to know which repository contains the code you are trying to change.
Familiarizing yourself with the code base and the purpose of each
repository is strongly recommended.

#. '''Set up a local clone.'''
Prepare a clone of the repository on your hard disk that is convenient for
getting updates from the upstream repository and pushing changes to your
fork. You'll also use this clone to perform test builds.

#. '''Build the project.'''
If you haven't already done so, this will be the time to set up your
development environment so that you can build FlightGear.

#. '''Create a new branch.'''
Create a branch on your clone to isolate your changes. Use a clear and
descriptive name for your branch (e.g. <code>fix-menubar-typo</code> or
<code>add-new-joystick-configs</code>).

#. '''Make changes.'''
Make the changes on your branch in small, focused commits. Each commit
should be self-contained and represent one logical change.

#. '''Test and double-check.'''
Before you submit your changes to the FlightGear team for review,
double-check your work. Ensure that your code builds and that tests pass.

#. '''Rebase and push.'''
Check if the upstream repository was updated in the meantime. If so, rebase
your work on its latest state and perform a final test run to make sure
everything still works fine.

#. '''Submit a merge request.'''
Open a merge request (MR) to propose your changes for review. Be sure to
use the ''Merge Request Template'' to provide necessary context for
reviewers. Feel free to ask on the developer mailing list if you're unsure
whom to add as a reviewer.

#. '''Code review.'''
Once you have created a merge request, other developers will review your
work, give feedback, and sometimes request changes be made. This is a
crucial part of the development process, as it helps reduce bugs and
improves code quality.

#. '''Clean up.'''
If your merge request was applied, pull your changes from the upstream
branch and delete the local branch you created for the merge request.

In order to present these steps in more detail, we'll now assume that you
intend to make your first contribution to the [https://gitlab.com/flightgear/simgear SimGear repository] (and thus,
that you haven't already forked it). Except for the target branch name which
may differ, the process would be the same for any Git repository of the
FlightGear project.

== Fork the Repository ==

For what follows, you'll need to create a [https://gitlab.com/ GitLab] account if you don't already
have one. Once you are logged into your account, go to the repository home
page ([https://gitlab.com/flightgear/simgear here] in our example) and click on the
Fork button as shown in
; after
filling some information, this will lead to the creation of a copy of the
upstream repository in your own GitLab namespace under
<code><nowiki>https://gitlab.com/YourUserName/</nowiki></code>.

[[File:01_forking.png|thumb|alt=how to find the Fork button on the main page of the repository|Forking the upstream repository]]

Once you've clicked on the button, a new page is loaded as shown in
. The ''Project name'' will be prominent but it's
only a label—choose it as you wish (“My SimGear fork” in the example). For the
''Project URL'', you'll want to select your GitLab username after the initial
portion <code><nowiki>https://gitlab.com/</nowiki></code>.

[[File:02 project name, URL, slug.png|thumb|alt=dialog that allows one to enter the project name, URL and slug for a fork|Entering the project name, URL and slug for your fork]]

The ''Project slug'' is the final part of the base URL for the fork you're about
to create; let's choose <code>flightgear-simgear</code> so that all your forks of
repositories of the FlightGear project are named <code>flightgear-something</code>.
This way, they will be easy to distinguish from non-FlightGear repositories
you might want to publish under <code><nowiki>https://gitlab.com/YourUserName/</nowiki></code>. Beware
that if you modify the ''Project name'', the GitLab user interface automatically
modifies the ''Project slug''; so, better fill them in this order: ''Project name''
then ''Project slug''.

There are a few fields left to enter. If you choose to include only the
default branch, you'll save a little amount of space but might have to fetch
other upstream branches later. Give your fork public visiblity so that reviews
can take place. When ready, click on the Fork project button to
actually create your fork of the upstream repository.



== Set Up a Local Clone ==

Since we want to pull updates from the upstream repository, it is convenient
to clone it to your hard disk and modify the clone so that pushes go by
default to your fork (which is online under
<code><nowiki>https://gitlab.com/YourUserName/</nowiki></code>). Cloning the upstream SimGear repository
can be done with:

<syntaxhighlight lang="bash">
git clone https://gitlab.com/flightgear/simgear.git
</syntaxhighlight>

{{tip|If you use <code>download_and_compile.sh</code> and it manages the repository you
want to contribute to (this is obviously the case for SimGear), there is
no need to create a new clone: you can simply use the repository clone it
created on your disk.}}

Now, let's add a Git remote that points to your fork of the upstream
repository. We configure this remote so that pushing to it uses <abbr title="Secure Shell">SSH</abbr> authentication. We also configure your repository clone so
that pushes go to your fork by default.

<syntaxhighlight lang="bash">
git remote add flo https://gitlab.com/frougon/flightgear-simgear.git
git remote set-url --push flo git@gitlab.com:frougon/flightgear-simgear.git
git config remote.pushDefault flo
</syntaxhighlight>

In the above commands, replace <code>flo</code> (name of the created remote) with an
appropriate name of your choice; also replace <code>frougon</code> with your GitLab
username.

== Build the Project ==

Make sure you can build FlightGear using the repository clone set up in the
previous step and that the resulting executables run normally. This way,
you'll be able to properly test any changes you later make in this clone.

{{note|The following steps will have to be repeated for each
“self-contained changeset” that you intend to contribute.}}

== Create a New Branch ==

Create a branch based on <code>origin/next</code> that tracks <code>origin/next</code> and make
sure it is up-to-date. Instead of <code>new-branch-name</code>, choose a name that
makes it clear what the changes in the created branch are supposed to do.

<syntaxhighlight lang="bash">
git checkout -b new-branch-name origin/next
git pull
</syntaxhighlight>

{{note|Here, <code>origin</code> is a remote that points to the upstream repository
you cloned from, and <code>next</code> is the name of the development branch
in the [https://gitlab.com/flightgear/simgear SimGear repository] (this is also the case for [https://gitlab.com/flightgear/flightgear FlightGear] and [https://gitlab.com/flightgear/fgdata FGData]). If
you were to contribute to a different repository such as [https://gitlab.com/flightgear/documentation FlightGear documentation], the branch
to base your work on might have a different name (e.g., <code>main</code>).}}

== Make Changes ==

Commit the desired changes to the branch you created in the previous step. If
you need help with <code>git</code>, this online [https://git-scm.com/book/en/v2 book] is a great resource.

Each commit message should start with a single, not too long summary line (no
more than 72—80 characters if possible), then a blank line, then normal
explanations. Example commit message:

<pre>
HID: allow sending output reports from Nasal

- make watched properties only react on a value change
- refactor the larger usage enums to their own file
</pre>

Like here, it is useful when the beginning of the first line is short and
makes it clear to readers which part of the code (subsystem, class, etc.) is
affected by the changes.

== Test and Double-check ==

Rebuild FlightGear with your changes, carefully test. Build the FlightGear
test suite and verify that the tests still pass. This can be done by running
<code>make test_suite</code> or <code>ninja test_suite</code> from the FlightGear build directory
(not the source repository!).

Use commands like:

* <code>git status</code> to check the state of your working directory and repository;
* <code>git log -p</code> to proofread your commit diffs and messages;
* <code>git commit --amend</code> to modify the most recent commit on the branch;
* <code>git rebase -i <ref></code> to modify commits located further
in the ancestry graph (namely, descendants of commit <code><ref></code>; see the
<code>git rebase</code> manual page for explanations).

The <code>gitk</code> program is not essential but can be nice for examining
commits and visualizing the commit graph. If <code>gitk</code> appears to see
local changes that really aren't there, run <code>git status</code> then rerun
<code>gitk</code>.

The <code>pre-commit</code> and <code>clang-format</code> programs are useful to run code quality
checks and apply the project formatting rules. Some of the configured
<code>pre-commit</code> hooks will for instance check for common mistakes
including typos, mixed whitespace or line endings, and so on. If you've
[https://pre-commit.com/#3-install-the-git-hook-scripts installed] the
<code>pre-commit</code> hooks in your repository clone, <code>pre-commit</code>
will be automatically run every time you commit.

{{note|In most cases, the GitLab CI (Continuous Integration) runs
the <code>pre-commit</code> and <code>clang-format</code> checks as part
of the automatic verifications that need to pass, before a merge request can be applied.}}

== Rebase and Push ==

If the upstream branch you started from has changed in the meantime, your work
needs to be rebased on top of its latest state. This can be done with the
following command:

<syntaxhighlight lang="bash">
git pull --rebase
</syntaxhighlight>

In case someone was working on the same files as you, this may trigger
conflicts (so it's a good idea to first announce what you're going to work on
in order to minimize friction and benefit from the insight of experienced
people). Conflicts don't happen very often and it's not the end of the world
when they do. Again, this [https://git-scm.com/book/en/v2 Git book] is a very useful resource in such cases.

If the rebasing did grab upstream changes, perform a final build-and-test run
to be sure everything works fine. Finally, push the branch to your fork:

<syntaxhighlight lang="bash">
git push
</syntaxhighlight>

With no additional arguments, this pushes the current branch to the remote
specified with the <code>remote.pushDefault</code> setting, i.e. to your clone if you
followed the [[#section-Set-up-a-local-clone|above]] instructions. Once
the push is successful, <code>git</code> will show a URL; following it will start the next step.

== Submit a Merge Request ==

The web page opened from the URL output by <code>git</code> when you pushed to
your fork allows to create a merge request from the branch that was pushed.
From this page, select the proper target branch: for development code in
[https://gitlab.com/flightgear/simgear SimGear], that would be <code>next</code>. Select yourself as
an ''assignee'' (meaning that ''you'' are going to shape the merge request into
its final form). Select one or more reviewers to look at it—you can ask on the
[https://sourceforge.net/p/flightgear/mailman/flightgear-devel/ flightgear-devel mailing-list] if unsure, or just leave the field as
''Unassigned''. Don't worry too much about the milestone ''(a priori,'' <code>next</code>
should do unless the merge request is specifically a fix for a release
branch). Select applicable labels, etc.

Regarding the ''Delete source branch when merge request is accepted'' option, we
advise you to make sure it is enabled, otherwise your fork will soon have tons
of branches. What this option does is the following: when the branch from your
merge request is merged into the upstream branch, GitLab will automatically
delete the merge request branch (that you pushed) from your fork. This happens
online at GitLab, not in your local clone. Thus, even after this
occurs, the branch will still be present locally in your clone, until you
delete it yourself (cf. [[#local-branch-removal|below]]).

Finally, the ''Squash commits when merge request is accepted'' option can be
used in case you pushed several commits but would rather have them coalesced
into a single one when the merge request is applied. This is something that
can be done locally using <code>git</code> before pushing (in particular, with
<code>git rebase -i</code>), however the option is still useful in case commits are added
to the merge request after the initial push, be it by you or by reviewers.

== Code Review ==

After a few minutes, hours or days, you'll receive feedback from the
FlightGear developers about your merge request. Reviewing merge requests
requires expertise and takes some time, so please carefully read the remarks
and suggestions, follow up on the questions and requests for changes.

== Clean Up ==

Once the branch is merged, update the local branch of your clone that tracks
the upstream branch your merge request went to (this is the <code>next</code> branch in
our SimGear example):

<syntaxhighlight lang="bash">
git checkout next
git pull --rebase
</syntaxhighlight>

(Normally, the <code>--rebase</code> option shouldn't be necessary here as you
shouldn't have any local commits on top of the upstream ones in this branch,
however it doesn't hurt and can make things easier if you've been forgetful.)



You can now delete the local branch you created earlier to avoid cluttering
your local clone with legacy, unneeded branches:

<syntaxhighlight lang="bash">
git branch -d new-branch-name
</syntaxhighlight>

In case this branch hasn't been merged ''exactly as is'' into the upstream
branch (same commit contents and metadata), <code>git</code> will warn and
refuse to delete the branch unless you insist using <code>-D</code>. If this happens,
you'll have to evaluate yourself (by using <code>git log -p</code>, by comparing
files...) if deleting your local branch <code>new-branch-name</code> is really the
right thing to do. In the likely case that what was merged is a strict
improvement over what you have in <code>new-branch-name</code>, then deleting is the
way to go.

{{tip|If you really, really messed up and deleted the branch before
realizing that it was a mistake, <code>git reflog</code> is likely to save you:
among other things, it shows the commit hashes corresponding to previous
positions of the tips of various branches. As long as no garbage collection occurred in the meantime (<code>git gc</code>), the commit
hashes are all you need to restore “lost commits”: simply create a
branch or tag from the desired commit (before doing do, you may want
to use <code>git show <hash></code> to see the commit for a given hash, or <code>git log <hash></code> to examine its ancestry).}}

From time to time, you may also want to run <code>git fetch -p flo</code> (replace
<code>flo</code> with the name of a remote that points to your fork,
cf. [[#section-Set-up-a-local-clone]]). This removes the <code>flo/...</code>
branches from your local clone that have been deleted from your fork at GitLab
due to the ''Delete source branch when merge request is accepted'' option on the
merge request page (note that for instance, <code>flo/new-branch-name</code> and
<code>new-branch-name</code> are different branches in your clone; they'll both clutter
the display when using <code>git log</code> or <code>gitk</code> until you delete them).

= Advanced =
A C++ API reference is available at [https://docs.flightgear.org/reference/cpp-reference.html docs.flightgear.org].

= External links =
* [https://docs.flightgear.org/contributors-guide/core-developers-guide/git-workflow.html How to Contribute Code]
* [https://git-scm.com/book/en/v2 The Git book]

[[Category:Howto]]
[[Category:Core developer documentation]]
[[ru:Howto:Приступая к разработке ядра]]
[[Category:Hackathon Materials]]

Canvas GUI

2026-05-28T07:08:49Z

Servo: add 2024.2 content

{{Note| the GUI API documentation can be found here: [[Canvas GUI API]]}}
{{Canvas Navigation}}
The '''Canvas GUI''' is going to replace the old [[PUI]] in version 2024.2.
[[File:Canvas menu 2024.2+.png|thumb|The canvas menu in 2024.2 nightly.]]

== Background ==
{{See also|Canvas widget matrix}}
In order and switch to the [[FlightGear and OpenGL Core Profile|core profile]], the [[PUI]] will be phased out completely. We now have the [[Canvas]] system, and there’s a formal decision to modernize the GUI using the Canvas, and completely replace PUI sooner rather than later.

The shortcomings of PUI in particular, have been repeatedly brought up on the devel list over the years.
It was a lot of work to get rid of hard-coded PUI dialogs, and we still have a bunch of hard-coded PUI widgets – as long as we have those, getting totally rid of PUI will be increasingly difficult, because each hard-coded widget will either need to be phased out or manually ported.

== Creating canvas widgets ==
{{Main article|Howto:Creating a Canvas GUI Widget}}

== PUI widgets ==
{{Main article|pui2canvas}}
There is a Nasal/Canvas module dynamically "translating" legacy PUI/XML dialogs into Canvas dialogs (at runtime), in {{fgdata file|Nasal/gui/XMLDialog.nas}} <ref>https://sourceforge.net/p/flightgear/fgdata/ci/fe7c87b21a69f88ddb87d89453c48d12b69660e2/</ref>

[[Category:Canvas GUI]]

Implementing new features for FlightGear

2026-05-28T06:50:06Z

Servo: shortened the page and removed out-of-date contents

{{Working together}}

We've been seeing an increasing number of discussions on the forum started by people who are eager to become potential contributors. Unfortunately, this has caused some friction over time, because people expected their involvement to work differently.

We do appreciate any community involvement, but people who are serious about bringing changes to FlightGear will find that just making suggestions is typically not enough. As contributors, we would also appreciate it if it would suffice to just make a suggestion — but that's not how things work.

We are now documenting how "bootstrapping" a feature works ''conceptually'': from having an idea to turning it into a feature, without having to do all the work on your own. This model has been shown to work for newcomers.

Note that this is not the only way to accomplish something, but it is a tested and proven way that "just works" for contributors.

This article is based on write-ups from contributors who have worked on novel FlightGear features that initially didn't receive much support, including:
* [[Advanced weather]]
* [[Atmospheric light scattering|Atmospheric Light Scattering]] (ALS)
* [[World Scenery 3.0]]
* [[Procedural Texturing]]
* [[Canvas]] system
* [[MapStructure]] framework
* [[Earthview|Earthview orbital rendering]] engine

None of these were implemented through "core development" alone. Many started as "mods" and later became official parts of FlightGear. The contributors who wrote this are not all core developers — many work on middleware and base package content (XML, scripts, effects, shaders, textures, 3D models).

== What is this about? ==

Like many FG users, you probably reach a point when you think 'Wouldn't it be nice if we had feature XY?' From this point, there are various options:

* Mention it in the forum: Likely outcome: several users agree it's a good idea, a few long-term contributors point out difficulties, and it ends there.
* Make a formal feature request: Likely outcome: a few comments, then low priority, and not much else.
* Make it your own project to get XY implemented: This means you actively manage what happens rather than just putting an idea out there. If you're willing to do this, read on.

== Some truths up front ==

# FlightGear relies on a contributor base, not a user base: Unlike a commercial project, FG does not need customers to survive. Development focuses on what contributors want to build. Arguments like "many more users will join" leave developers unimpressed. Arguments like "this enables new contributors to improve the simulator" are more interesting.
# Developers are free to do what they want: They work in their free time. You need to convince them voluntarily to help you.
# Development tends to be inclusive: New features are usually implemented in an optional way. Dropping existing features is very difficult.
# FG is not focused on end-user polish: Usability may lag behind commercial software. However, modern efforts like the [[Canvas]] system have greatly improved accessibility.

== Test the waters ==

If you want your idea to become part of FlightGear (not a fork or addon), test the waters early. Use the forum or [https://sourceforge.net/p/flightgear/mailman/flightgear-devel/ flightgear-devel] mailing list. Announce your project. If your project involves software or the base package, use GitLab to conduct development in the open so others can track your work and provide feedback.

Lessons from past events:

* Beautiful airport scenery could not be committed because it used textures with a "no commercial use" license — incompatible with FG's GPL license. Check licenses early!
* A large scenery collection was structured incorrectly — scenery data must follow specific formats. Study the project structure.
* Huge patches announced shortly before a release create workload for others. Use GitLab regularly and communicate early.

== Gather information ==

Find out who inside the project can help you. Learn how the effect framework works, how effects are configured, etc. The Wiki is your friend. Look up who has done related work (e.g., on [[ALS]], [[WS3.0]], [[Canvas]]). Other community members will gladly provide pointers.

== Make a proposal ==

Do:
* Point out how your idea makes FG a better simulation.
* Be concrete about what you want changed.
* Demonstrate you have done your homework.
* Summarize your ideas on the wiki so they don't get lost.

Don't:
* Demand anything.
* Be rude or angry at criticism.
* Say FG will fail if your idea is not implemented.
* Say you "can't do anything" because you don't know C++/XML — you can learn.

Compare: "Wouldn't it be cool if we had better clouds like X-Plane?" versus "Would it be possible to extend the ALS shader system to support volumetric cloud shadows? I can provide cloud textures and test data if someone helps with the shader code."

If you have a track record of finishing projects, people are far more likely to support you. If you are new, create a proof of concept — even in Nasal scripting. Once people see you are investing time, you are more likely to get support.

== Getting people involved ==

The most common showstopper is lack of networking and unwillingness to compromise. People want ''their'' idea implemented immediately, expecting others to drop everything. That is not how things work.

To get people involved, you need to get them interested. People are motivated by actions, not just ideas. Find overlapping areas of interest. Very often, people may not work directly toward your final goal, but toward interim milestones that are part of a longer-term roadmap.

This is exactly how recent projects succeeded:
* The Advanced Weather system started as a Nasal script and later received C++ help once it proved viable.
* The [[Atmospheric light scattering|Atmospheric Light Scattering]] (ALS) effect was initially a shader prototype that grew into a full rendering option.
* The [[Canvas]] system took 18 months from wiki introduction to full adoption.
* The [[MapStructure]] framework unified multiple hard-coded instruments (radar, map dialog) into a single reusable system.

Successful contributors realize that overlapping areas are opportunities to get involved in other projects, learn new skills, and build relationships.

== Be persistent ==

If you fail to get help, revise your proposal. Consider workarounds — Nasal scripting is often a viable alternative to C++, and subsystems can be converted later. Starting with something "good enough" and improving it is more likely to succeed than trying to be perfect up front.

Example: In the beginning, the idea of using Nasal to implement a weather system was not taken seriously. Once written in a working (though inefficient) way, it received C++ help and became Advanced Weather, one of the most sophisticated weather systems in flight simulation.

The perfect is the enemy of the good. Countless good proposals failed because people refused to make concessions, leading to hundreds of forum posts and wasted hours.

== Honor your commitments ==

If someone does work for you because you promised to do XY, and you don't do XY, no one will help you again. If you cannot meet a deadline, be candid about it early.

== Release early, document your efforts ==

Use the forum and wiki to show progress. People need to be aware of what you are doing before they can help.

For long-debated topics (multiplayer improvements, combat support, better threading, scenery improvements), there are often hundreds of posts over many years. It is not effective to start yet another debate. Instead, use the wiki to document ideas, proposals, and status over time. Some wiki articles on these topics get 12k+ views in months, while forum threads get 4k views in years.

Complex ideas often have a shelf life of 12–18 months. The Canvas system took 18 months from introduction to adoption. Use the wiki to let time work for you.

Make your efforts available for testing early. When ready, submit a merge request on GitLab, talk to someone with commit rights, and enjoy your feature being part of a future release.

== Collaboration and consistency ==

Consistency is difficult. It requires looking at other places and potential use-cases that may benefit from your work — including stuff you never use yourself.

Examples of consistency challenges in FlightGear:
* Multiple competing I/O systems (generic protocol, httpd, telnet, multiplayer) that share similar requirements but are poorly integrated.
* Aircraft that could support [[AI traffic]], multiplayer [[dual control|dual-pilot]], replay, checklists, weight & balance, and the [[bombable]] addon — but most contributors only scratch their own itch.

The Canvas/MapStructure work is a success story: for over a decade, hard-coded instruments (wxradar, agradar, navdisplay, map dialog) existed separately. Canvas unified them into a framework under 1,000 lines of code, making over 9,000–15,000 lines of C++ obsolete. This took 24 months — but the result is far more accessible and future-proof.

However, this kind of work is not "fun". It involves refactoring, talking, and coordinating — not just coding. But it is what makes the project sustainable.

== Case study: empowering the masses ==

A common suggestion: "If coders spent time making tools that take the coding out of making stuff, modders would spend time doing the rest."

In practice, this has been tried:
* The terrain texturing system now has XML-configured regional definitions and documented effects. The actual work (gathering aerial imagery, finding textures, trial and error) requires almost zero coding — just XML. Yet very few people use it.
* The MapStructure framework is extensively documented (14k+ views in 6 months) and provides a plugin system. Still, few third-party modules have appeared.

The lesson: It is not enough to build tools. Contributors need to show they will actually use them before developers invest time.

== Case study: when is rendering simple? ==

A common question: Why do we not have simple water reflections when we have complex effects like [[ALS]]?

The answer: Graphics cards are optimized for local computations (eye → surface → light). Water reflections require non-local computations (eye → water → reflected object → light). Raytracing solves this but is too slow for real-time. There are approximations (e.g., shadow camera passes in deferred rendering), but they require significant resources.

Many things that look mathematically simple are not simple in real-time rendering. The cost-benefit analysis may be poor — would you work six months and lose half your framerate for water reflections?

(Note: First-person shooters can run fancy effects because movement is restricted to "levels." FlightGear renders from ground to orbit — a much harder problem.)

== See also ==

* [[How the FlightGear project works]]
* [[Howto:Understand the FlightGear development process]]
* [[Howto:Start core development]]
* [[Canvas]]
* [[MapStructure]]
* [[Advanced weather]]
* [[Atmospheric light scattering]]

[[Category:Development]]
[[Category:Working together]]

Howto:Start core development

2026-05-28T06:25:55Z

Servo: /* Overview */

{{note|You'll need to familiarize yourself with setting up a development environment and building FlightGear in order to contribute code. See
[https://docs.flightgear.org/contributors-guide/guidelines/building.html Developing on the codebase] if you do not already
have a working setup. Some understanding of ''Git'' will also be
necessary; this free, online [https://git-scm.com/book/en/v2 Git book] is quite useful.}}

This page introduces how to contribute to the core [[FlightGear Git|Git repositories]] of [[FlightGear]].

The most efficient way to contribute changes to the FlightGear code base is to
file a merge request (this doesn't apply to [[aircraft]] or [[addon|add-ons]], which are
managed differently). We'll first give an overview of the process including
its main prerequisites, then explain each step in more detail.

== Overview ==

The basic workflow for first-time contributors to a core [[Git]] repository
is:

#. '''Fork the repository.'''
Fork the relevant FlightGear repository into your GitLab account. You will
need to know which repository contains the code you are trying to change.
Familiarizing yourself with the code base and the purpose of each
repository is strongly recommended.

#. '''Set up a local clone.'''
Prepare a clone of the repository on your hard disk that is convenient for
getting updates from the upstream repository and pushing changes to your
fork. You'll also use this clone to perform test builds.

#. '''Build the project.'''
If you haven't already done so, this will be the time to set up your
development environment so that you can build FlightGear.

#. '''Create a new branch.'''
Create a branch on your clone to isolate your changes. Use a clear and
descriptive name for your branch (e.g. <code>fix-menubar-typo</code> or
<code>add-new-joystick-configs</code>).

#. '''Make changes.'''
Make the changes on your branch in small, focused commits. Each commit
should be self-contained and represent one logical change.

#. '''Test and double-check.'''
Before you submit your changes to the FlightGear team for review,
double-check your work. Ensure that your code builds and that tests pass.

#. '''Rebase and push.'''
Check if the upstream repository was updated in the meantime. If so, rebase
your work on its latest state and perform a final test run to make sure
everything still works fine.

#. '''Submit a merge request.'''
Open a merge request (MR) to propose your changes for review. Be sure to
use the ''Merge Request Template'' to provide necessary context for
reviewers. Feel free to ask on the developer mailing list if you're unsure
whom to add as a reviewer.

#. '''Code review.'''
Once you have created a merge request, other developers will review your
work, give feedback, and sometimes request changes be made. This is a
crucial part of the development process, as it helps reduce bugs and
improves code quality.

#. '''Clean up.'''
If your merge request was applied, pull your changes from the upstream
branch and delete the local branch you created for the merge request.

In order to present these steps in more detail, we'll now assume that you
intend to make your first contribution to the [https://gitlab.com/flightgear/simgear SimGear repository] (and thus,
that you haven't already forked it). Except for the target branch name which
may differ, the process would be the same for any Git repository of the
FlightGear project.

== Fork the Repository ==

For what follows, you'll need to create a [https://gitlab.com/ GitLab] account if you don't already
have one. Once you are logged into your account, go to the repository home
page ([https://gitlab.com/flightgear/simgear here] in our example) and click on the
Fork button as shown in
; after
filling some information, this will lead to the creation of a copy of the
upstream repository in your own GitLab namespace under
<code><nowiki>https://gitlab.com/YourUserName/</nowiki></code>.

[[File:01_forking.png|thumb|alt=how to find the Fork button on the main page of the repository|Forking the upstream repository]]

Once you've clicked on the button, a new page is loaded as shown in
. The ''Project name'' will be prominent but it's
only a label—choose it as you wish (“My SimGear fork” in the example). For the
''Project URL'', you'll want to select your GitLab username after the initial
portion <code><nowiki>https://gitlab.com/</nowiki></code>.

[[File:02 project name, URL, slug.png|thumb|alt=dialog that allows one to enter the project name, URL and slug for a fork|Entering the project name, URL and slug for your fork]]

The ''Project slug'' is the final part of the base URL for the fork you're about
to create; let's choose <code>flightgear-simgear</code> so that all your forks of
repositories of the FlightGear project are named <code>flightgear-something</code>.
This way, they will be easy to distinguish from non-FlightGear repositories
you might want to publish under <code><nowiki>https://gitlab.com/YourUserName/</nowiki></code>. Beware
that if you modify the ''Project name'', the GitLab user interface automatically
modifies the ''Project slug''; so, better fill them in this order: ''Project name''
then ''Project slug''.

There are a few fields left to enter. If you choose to include only the
default branch, you'll save a little amount of space but might have to fetch
other upstream branches later. Give your fork public visiblity so that reviews
can take place. When ready, click on the Fork project button to
actually create your fork of the upstream repository.



== Set Up a Local Clone ==

Since we want to pull updates from the upstream repository, it is convenient
to clone it to your hard disk and modify the clone so that pushes go by
default to your fork (which is online under
<code><nowiki>https://gitlab.com/YourUserName/</nowiki></code>). Cloning the upstream SimGear repository
can be done with:

<syntaxhighlight lang="bash">
git clone https://gitlab.com/flightgear/simgear.git
</syntaxhighlight>

{{tip|If you use <code>download_and_compile.sh</code> and it manages the repository you
want to contribute to (this is obviously the case for SimGear), there is
no need to create a new clone: you can simply use the repository clone it
created on your disk.}}

Now, let's add a Git remote that points to your fork of the upstream
repository. We configure this remote so that pushing to it uses <abbr title="Secure Shell">SSH</abbr> authentication. We also configure your repository clone so
that pushes go to your fork by default.

<syntaxhighlight lang="bash">
git remote add flo https://gitlab.com/frougon/flightgear-simgear.git
git remote set-url --push flo git@gitlab.com:frougon/flightgear-simgear.git
git config remote.pushDefault flo
</syntaxhighlight>

In the above commands, replace <code>flo</code> (name of the created remote) with an
appropriate name of your choice; also replace <code>frougon</code> with your GitLab
username.

== Build the Project ==

Make sure you can build FlightGear using the repository clone set up in the
previous step and that the resulting executables run normally. This way,
you'll be able to properly test any changes you later make in this clone.

{{note|The following steps will have to be repeated for each
“self-contained changeset” that you intend to contribute.}}

== Create a New Branch ==

Create a branch based on <code>origin/next</code> that tracks <code>origin/next</code> and make
sure it is up-to-date. Instead of <code>new-branch-name</code>, choose a name that
makes it clear what the changes in the created branch are supposed to do.

<syntaxhighlight lang="bash">
git checkout -b new-branch-name origin/next
git pull
</syntaxhighlight>

{{note|Here, <code>origin</code> is a remote that points to the upstream repository
you cloned from, and <code>next</code> is the name of the development branch
in the [https://gitlab.com/flightgear/simgear SimGear repository] (this is also the case for [https://gitlab.com/flightgear/flightgear FlightGear] and [https://gitlab.com/flightgear/fgdata FGData]). If
you were to contribute to a different repository such as [https://gitlab.com/flightgear/documentation FlightGear documentation], the branch
to base your work on might have a different name (e.g., <code>main</code>).}}

== Make Changes ==

Commit the desired changes to the branch you created in the previous step. If
you need help with <code>git</code>, this online [https://git-scm.com/book/en/v2 book] is a great resource.

Each commit message should start with a single, not too long summary line (no
more than 72—80 characters if possible), then a blank line, then normal
explanations. Example commit message:

<pre>
HID: allow sending output reports from Nasal

- make watched properties only react on a value change
- refactor the larger usage enums to their own file
</pre>

Like here, it is useful when the beginning of the first line is short and
makes it clear to readers which part of the code (subsystem, class, etc.) is
affected by the changes.

== Test and Double-check ==

Rebuild FlightGear with your changes, carefully test. Build the FlightGear
test suite and verify that the tests still pass. This can be done by running
<code>make test_suite</code> or <code>ninja test_suite</code> from the FlightGear build directory
(not the source repository!).

Use commands like:

* <code>git status</code> to check the state of your working directory and repository;
* <code>git log -p</code> to proofread your commit diffs and messages;
* <code>git commit --amend</code> to modify the most recent commit on the branch;
* <code>git rebase -i <ref></code> to modify commits located further
in the ancestry graph (namely, descendants of commit <code><ref></code>; see the
<code>git rebase</code> manual page for explanations).

The <code>gitk</code> program is not essential but can be nice for examining
commits and visualizing the commit graph. If <code>gitk</code> appears to see
local changes that really aren't there, run <code>git status</code> then rerun
<code>gitk</code>.

The <code>pre-commit</code> and <code>clang-format</code> programs are useful to run code quality
checks and apply the project formatting rules. Some of the configured
<code>pre-commit</code> hooks will for instance check for common mistakes
including typos, mixed whitespace or line endings, and so on. If you've
[https://pre-commit.com/#3-install-the-git-hook-scripts installed] the
<code>pre-commit</code> hooks in your repository clone, <code>pre-commit</code>
will be automatically run every time you commit.

{{note|In most cases, the GitLab CI (Continuous Integration) runs
the <code>pre-commit</code> and <code>clang-format</code> checks as part
of the automatic verifications that need to pass, before a merge request can be applied.}}

== Rebase and Push ==

If the upstream branch you started from has changed in the meantime, your work
needs to be rebased on top of its latest state. This can be done with the
following command:

<syntaxhighlight lang="bash">
git pull --rebase
</syntaxhighlight>

In case someone was working on the same files as you, this may trigger
conflicts (so it's a good idea to first announce what you're going to work on
in order to minimize friction and benefit from the insight of experienced
people). Conflicts don't happen very often and it's not the end of the world
when they do. Again, this [https://git-scm.com/book/en/v2 Git book] is a very useful resource in such cases.

If the rebasing did grab upstream changes, perform a final build-and-test run
to be sure everything works fine. Finally, push the branch to your fork:

<syntaxhighlight lang="bash">
git push
</syntaxhighlight>

With no additional arguments, this pushes the current branch to the remote
specified with the <code>remote.pushDefault</code> setting, i.e. to your clone if you
followed the [[#section-Set-up-a-local-clone|above]] instructions. Once
the push is successful, <code>git</code> will show a URL; following it will start the next step.

== Submit a Merge Request ==

The web page opened from the URL output by <code>git</code> when you pushed to
your fork allows to create a merge request from the branch that was pushed.
From this page, select the proper target branch: for development code in
[https://gitlab.com/flightgear/simgear SimGear], that would be <code>next</code>. Select yourself as
an ''assignee'' (meaning that ''you'' are going to shape the merge request into
its final form). Select one or more reviewers to look at it—you can ask on the
[https://sourceforge.net/p/flightgear/mailman/flightgear-devel/ flightgear-devel mailing-list] if unsure, or just leave the field as
''Unassigned''. Don't worry too much about the milestone ''(a priori,'' <code>next</code>
should do unless the merge request is specifically a fix for a release
branch). Select applicable labels, etc.

Regarding the ''Delete source branch when merge request is accepted'' option, we
advise you to make sure it is enabled, otherwise your fork will soon have tons
of branches. What this option does is the following: when the branch from your
merge request is merged into the upstream branch, GitLab will automatically
delete the merge request branch (that you pushed) from your fork. This happens
online at GitLab, not in your local clone. Thus, even after this
occurs, the branch will still be present locally in your clone, until you
delete it yourself (cf. [[#local-branch-removal|below]]).

Finally, the ''Squash commits when merge request is accepted'' option can be
used in case you pushed several commits but would rather have them coalesced
into a single one when the merge request is applied. This is something that
can be done locally using <code>git</code> before pushing (in particular, with
<code>git rebase -i</code>), however the option is still useful in case commits are added
to the merge request after the initial push, be it by you or by reviewers.

== Code Review ==

After a few minutes, hours or days, you'll receive feedback from the
FlightGear developers about your merge request. Reviewing merge requests
requires expertise and takes some time, so please carefully read the remarks
and suggestions, follow up on the questions and requests for changes.

== Clean Up ==

Once the branch is merged, update the local branch of your clone that tracks
the upstream branch your merge request went to (this is the <code>next</code> branch in
our SimGear example):

<syntaxhighlight lang="bash">
git checkout next
git pull --rebase
</syntaxhighlight>

(Normally, the <code>--rebase</code> option shouldn't be necessary here as you
shouldn't have any local commits on top of the upstream ones in this branch,
however it doesn't hurt and can make things easier if you've been forgetful.)



You can now delete the local branch you created earlier to avoid cluttering
your local clone with legacy, unneeded branches:

<syntaxhighlight lang="bash">
git branch -d new-branch-name
</syntaxhighlight>

In case this branch hasn't been merged ''exactly as is'' into the upstream
branch (same commit contents and metadata), <code>git</code> will warn and
refuse to delete the branch unless you insist using <code>-D</code>. If this happens,
you'll have to evaluate yourself (by using <code>git log -p</code>, by comparing
files...) if deleting your local branch <code>new-branch-name</code> is really the
right thing to do. In the likely case that what was merged is a strict
improvement over what you have in <code>new-branch-name</code>, then deleting is the
way to go.

{{tip|If you really, really messed up and deleted the branch before
realizing that it was a mistake, <code>git reflog</code> is likely to save you:
among other things, it shows the commit hashes corresponding to previous
positions of the tips of various branches. As long as no garbage collection occurred in the meantime (<code>git gc</code>), the commit
hashes are all you need to restore “lost commits”: simply create a
branch or tag from the desired commit (before doing do, you may want
to use <code>git show <hash></code> to see the commit for a given hash, or <code>git log <hash></code> to examine its ancestry).}}

From time to time, you may also want to run <code>git fetch -p flo</code> (replace
<code>flo</code> with the name of a remote that points to your fork,
cf. [[#section-Set-up-a-local-clone]]). This removes the <code>flo/...</code>
branches from your local clone that have been deleted from your fork at GitLab
due to the ''Delete source branch when merge request is accepted'' option on the
merge request page (note that for instance, <code>flo/new-branch-name</code> and
<code>new-branch-name</code> are different branches in your clone; they'll both clutter
the display when using <code>git log</code> or <code>gitk</code> until you delete them).

== External links ==
* [https://docs.flightgear.org/contributors-guide/core-developers-guide/git-workflow.html How to Contribute Code]
* [https://git-scm.com/book/en/v2 The Git book]

[[Category:Howto]]
[[Category:Core developer documentation]]
[[ru:Howto:Приступая к разработке ядра]]
[[Category:Hackathon Materials]]

Howto:Start core development

2026-05-28T06:24:52Z

Servo: /* Overview */

{{note|You'll need to familiarize yourself with setting up a development environment and building FlightGear in order to contribute code. See
[https://docs.flightgear.org/contributors-guide/guidelines/building.html Developing on the codebase] if you do not already
have a working setup. Some understanding of ''Git'' will also be
necessary; this free, online [https://git-scm.com/book/en/v2 Git book] is quite useful.}}

This page introduces how to contribute to the core [[FlightGear Git|Git repositories]] of [[FlightGear]].

The most efficient way to contribute changes to the FlightGear code base is to
file a merge request (this doesn't apply to [[aircraft]] or [[addon|add-ons]], which are
managed differently). We'll first give an overview of the process including
its main prerequisites, then explain each step in more detail.

== Overview ==

The basic workflow for first-time contributors to the core Git repository
is:

#. '''Fork the repository.'''
Fork the relevant FlightGear repository into your GitLab account. You will
need to know which repository contains the code you are trying to change.
Familiarizing yourself with the code base and the purpose of each
repository is strongly recommended.

#. '''Set up a local clone.'''
Prepare a clone of the repository on your hard disk that is convenient for
getting updates from the upstream repository and pushing changes to your
fork. You'll also use this clone to perform test builds.

#. '''Build the project.'''
If you haven't already done so, this will be the time to set up your
development environment so that you can build FlightGear.

#. '''Create a new branch.'''
Create a branch on your clone to isolate your changes. Use a clear and
descriptive name for your branch (e.g. <code>fix-menubar-typo</code> or
<code>add-new-joystick-configs</code>).

#. '''Make changes.'''
Make the changes on your branch in small, focused commits. Each commit
should be self-contained and represent one logical change.

#. '''Test and double-check.'''
Before you submit your changes to the FlightGear team for review,
double-check your work. Ensure that your code builds and that tests pass.

#. '''Rebase and push.'''
Check if the upstream repository was updated in the meantime. If so, rebase
your work on its latest state and perform a final test run to make sure
everything still works fine.

#. '''Submit a merge request.'''
Open a merge request (MR) to propose your changes for review. Be sure to
use the ''Merge Request Template'' to provide necessary context for
reviewers. Feel free to ask on the developer mailing list if you're unsure
whom to add as a reviewer.

#. '''Code review.'''
Once you have created a merge request, other developers will review your
work, give feedback, and sometimes request changes be made. This is a
crucial part of the development process, as it helps reduce bugs and
improves code quality.

#. '''Clean up.'''
If your merge request was applied, pull your changes from the upstream
branch and delete the local branch you created for the merge request.

In order to present these steps in more detail, we'll now assume that you
intend to make your first contribution to the [https://gitlab.com/flightgear/simgear SimGear repository] (and thus,
that you haven't already forked it). Except for the target branch name which
may differ, the process would be the same for any Git repository of the
FlightGear project.

== Fork the Repository ==

For what follows, you'll need to create a [https://gitlab.com/ GitLab] account if you don't already
have one. Once you are logged into your account, go to the repository home
page ([https://gitlab.com/flightgear/simgear here] in our example) and click on the
Fork button as shown in
; after
filling some information, this will lead to the creation of a copy of the
upstream repository in your own GitLab namespace under
<code><nowiki>https://gitlab.com/YourUserName/</nowiki></code>.

[[File:01_forking.png|thumb|alt=how to find the Fork button on the main page of the repository|Forking the upstream repository]]

Once you've clicked on the button, a new page is loaded as shown in
. The ''Project name'' will be prominent but it's
only a label—choose it as you wish (“My SimGear fork” in the example). For the
''Project URL'', you'll want to select your GitLab username after the initial
portion <code><nowiki>https://gitlab.com/</nowiki></code>.

[[File:02 project name, URL, slug.png|thumb|alt=dialog that allows one to enter the project name, URL and slug for a fork|Entering the project name, URL and slug for your fork]]

The ''Project slug'' is the final part of the base URL for the fork you're about
to create; let's choose <code>flightgear-simgear</code> so that all your forks of
repositories of the FlightGear project are named <code>flightgear-something</code>.
This way, they will be easy to distinguish from non-FlightGear repositories
you might want to publish under <code><nowiki>https://gitlab.com/YourUserName/</nowiki></code>. Beware
that if you modify the ''Project name'', the GitLab user interface automatically
modifies the ''Project slug''; so, better fill them in this order: ''Project name''
then ''Project slug''.

There are a few fields left to enter. If you choose to include only the
default branch, you'll save a little amount of space but might have to fetch
other upstream branches later. Give your fork public visiblity so that reviews
can take place. When ready, click on the Fork project button to
actually create your fork of the upstream repository.



== Set Up a Local Clone ==

Since we want to pull updates from the upstream repository, it is convenient
to clone it to your hard disk and modify the clone so that pushes go by
default to your fork (which is online under
<code><nowiki>https://gitlab.com/YourUserName/</nowiki></code>). Cloning the upstream SimGear repository
can be done with:

<syntaxhighlight lang="bash">
git clone https://gitlab.com/flightgear/simgear.git
</syntaxhighlight>

{{tip|If you use <code>download_and_compile.sh</code> and it manages the repository you
want to contribute to (this is obviously the case for SimGear), there is
no need to create a new clone: you can simply use the repository clone it
created on your disk.}}

Now, let's add a Git remote that points to your fork of the upstream
repository. We configure this remote so that pushing to it uses <abbr title="Secure Shell">SSH</abbr> authentication. We also configure your repository clone so
that pushes go to your fork by default.

<syntaxhighlight lang="bash">
git remote add flo https://gitlab.com/frougon/flightgear-simgear.git
git remote set-url --push flo git@gitlab.com:frougon/flightgear-simgear.git
git config remote.pushDefault flo
</syntaxhighlight>

In the above commands, replace <code>flo</code> (name of the created remote) with an
appropriate name of your choice; also replace <code>frougon</code> with your GitLab
username.

== Build the Project ==

Make sure you can build FlightGear using the repository clone set up in the
previous step and that the resulting executables run normally. This way,
you'll be able to properly test any changes you later make in this clone.

{{note|The following steps will have to be repeated for each
“self-contained changeset” that you intend to contribute.}}

== Create a New Branch ==

Create a branch based on <code>origin/next</code> that tracks <code>origin/next</code> and make
sure it is up-to-date. Instead of <code>new-branch-name</code>, choose a name that
makes it clear what the changes in the created branch are supposed to do.

<syntaxhighlight lang="bash">
git checkout -b new-branch-name origin/next
git pull
</syntaxhighlight>

{{note|Here, <code>origin</code> is a remote that points to the upstream repository
you cloned from, and <code>next</code> is the name of the development branch
in the [https://gitlab.com/flightgear/simgear SimGear repository] (this is also the case for [https://gitlab.com/flightgear/flightgear FlightGear] and [https://gitlab.com/flightgear/fgdata FGData]). If
you were to contribute to a different repository such as [https://gitlab.com/flightgear/documentation FlightGear documentation], the branch
to base your work on might have a different name (e.g., <code>main</code>).}}

== Make Changes ==

Commit the desired changes to the branch you created in the previous step. If
you need help with <code>git</code>, this online [https://git-scm.com/book/en/v2 book] is a great resource.

Each commit message should start with a single, not too long summary line (no
more than 72—80 characters if possible), then a blank line, then normal
explanations. Example commit message:

<pre>
HID: allow sending output reports from Nasal

- make watched properties only react on a value change
- refactor the larger usage enums to their own file
</pre>

Like here, it is useful when the beginning of the first line is short and
makes it clear to readers which part of the code (subsystem, class, etc.) is
affected by the changes.

== Test and Double-check ==

Rebuild FlightGear with your changes, carefully test. Build the FlightGear
test suite and verify that the tests still pass. This can be done by running
<code>make test_suite</code> or <code>ninja test_suite</code> from the FlightGear build directory
(not the source repository!).

Use commands like:

* <code>git status</code> to check the state of your working directory and repository;
* <code>git log -p</code> to proofread your commit diffs and messages;
* <code>git commit --amend</code> to modify the most recent commit on the branch;
* <code>git rebase -i <ref></code> to modify commits located further
in the ancestry graph (namely, descendants of commit <code><ref></code>; see the
<code>git rebase</code> manual page for explanations).

The <code>gitk</code> program is not essential but can be nice for examining
commits and visualizing the commit graph. If <code>gitk</code> appears to see
local changes that really aren't there, run <code>git status</code> then rerun
<code>gitk</code>.

The <code>pre-commit</code> and <code>clang-format</code> programs are useful to run code quality
checks and apply the project formatting rules. Some of the configured
<code>pre-commit</code> hooks will for instance check for common mistakes
including typos, mixed whitespace or line endings, and so on. If you've
[https://pre-commit.com/#3-install-the-git-hook-scripts installed] the
<code>pre-commit</code> hooks in your repository clone, <code>pre-commit</code>
will be automatically run every time you commit.

{{note|In most cases, the GitLab CI (Continuous Integration) runs
the <code>pre-commit</code> and <code>clang-format</code> checks as part
of the automatic verifications that need to pass, before a merge request can be applied.}}

== Rebase and Push ==

If the upstream branch you started from has changed in the meantime, your work
needs to be rebased on top of its latest state. This can be done with the
following command:

<syntaxhighlight lang="bash">
git pull --rebase
</syntaxhighlight>

In case someone was working on the same files as you, this may trigger
conflicts (so it's a good idea to first announce what you're going to work on
in order to minimize friction and benefit from the insight of experienced
people). Conflicts don't happen very often and it's not the end of the world
when they do. Again, this [https://git-scm.com/book/en/v2 Git book] is a very useful resource in such cases.

If the rebasing did grab upstream changes, perform a final build-and-test run
to be sure everything works fine. Finally, push the branch to your fork:

<syntaxhighlight lang="bash">
git push
</syntaxhighlight>

With no additional arguments, this pushes the current branch to the remote
specified with the <code>remote.pushDefault</code> setting, i.e. to your clone if you
followed the [[#section-Set-up-a-local-clone|above]] instructions. Once
the push is successful, <code>git</code> will show a URL; following it will start the next step.

== Submit a Merge Request ==

The web page opened from the URL output by <code>git</code> when you pushed to
your fork allows to create a merge request from the branch that was pushed.
From this page, select the proper target branch: for development code in
[https://gitlab.com/flightgear/simgear SimGear], that would be <code>next</code>. Select yourself as
an ''assignee'' (meaning that ''you'' are going to shape the merge request into
its final form). Select one or more reviewers to look at it—you can ask on the
[https://sourceforge.net/p/flightgear/mailman/flightgear-devel/ flightgear-devel mailing-list] if unsure, or just leave the field as
''Unassigned''. Don't worry too much about the milestone ''(a priori,'' <code>next</code>
should do unless the merge request is specifically a fix for a release
branch). Select applicable labels, etc.

Regarding the ''Delete source branch when merge request is accepted'' option, we
advise you to make sure it is enabled, otherwise your fork will soon have tons
of branches. What this option does is the following: when the branch from your
merge request is merged into the upstream branch, GitLab will automatically
delete the merge request branch (that you pushed) from your fork. This happens
online at GitLab, not in your local clone. Thus, even after this
occurs, the branch will still be present locally in your clone, until you
delete it yourself (cf. [[#local-branch-removal|below]]).

Finally, the ''Squash commits when merge request is accepted'' option can be
used in case you pushed several commits but would rather have them coalesced
into a single one when the merge request is applied. This is something that
can be done locally using <code>git</code> before pushing (in particular, with
<code>git rebase -i</code>), however the option is still useful in case commits are added
to the merge request after the initial push, be it by you or by reviewers.

== Code Review ==

After a few minutes, hours or days, you'll receive feedback from the
FlightGear developers about your merge request. Reviewing merge requests
requires expertise and takes some time, so please carefully read the remarks
and suggestions, follow up on the questions and requests for changes.

== Clean Up ==

Once the branch is merged, update the local branch of your clone that tracks
the upstream branch your merge request went to (this is the <code>next</code> branch in
our SimGear example):

<syntaxhighlight lang="bash">
git checkout next
git pull --rebase
</syntaxhighlight>

(Normally, the <code>--rebase</code> option shouldn't be necessary here as you
shouldn't have any local commits on top of the upstream ones in this branch,
however it doesn't hurt and can make things easier if you've been forgetful.)



You can now delete the local branch you created earlier to avoid cluttering
your local clone with legacy, unneeded branches:

<syntaxhighlight lang="bash">
git branch -d new-branch-name
</syntaxhighlight>

In case this branch hasn't been merged ''exactly as is'' into the upstream
branch (same commit contents and metadata), <code>git</code> will warn and
refuse to delete the branch unless you insist using <code>-D</code>. If this happens,
you'll have to evaluate yourself (by using <code>git log -p</code>, by comparing
files...) if deleting your local branch <code>new-branch-name</code> is really the
right thing to do. In the likely case that what was merged is a strict
improvement over what you have in <code>new-branch-name</code>, then deleting is the
way to go.

{{tip|If you really, really messed up and deleted the branch before
realizing that it was a mistake, <code>git reflog</code> is likely to save you:
among other things, it shows the commit hashes corresponding to previous
positions of the tips of various branches. As long as no garbage collection occurred in the meantime (<code>git gc</code>), the commit
hashes are all you need to restore “lost commits”: simply create a
branch or tag from the desired commit (before doing do, you may want
to use <code>git show <hash></code> to see the commit for a given hash, or <code>git log <hash></code> to examine its ancestry).}}

From time to time, you may also want to run <code>git fetch -p flo</code> (replace
<code>flo</code> with the name of a remote that points to your fork,
cf. [[#section-Set-up-a-local-clone]]). This removes the <code>flo/...</code>
branches from your local clone that have been deleted from your fork at GitLab
due to the ''Delete source branch when merge request is accepted'' option on the
merge request page (note that for instance, <code>flo/new-branch-name</code> and
<code>new-branch-name</code> are different branches in your clone; they'll both clutter
the display when using <code>git log</code> or <code>gitk</code> until you delete them).

== External links ==
* [https://docs.flightgear.org/contributors-guide/core-developers-guide/git-workflow.html How to Contribute Code]
* [https://git-scm.com/book/en/v2 The Git book]

[[Category:Howto]]
[[Category:Core developer documentation]]
[[ru:Howto:Приступая к разработке ядра]]
[[Category:Hackathon Materials]]

Howto:Start core development

2026-05-28T06:22:52Z

Servo: top

{{note|You'll need to familiarize yourself with setting up a development environment and building FlightGear in order to contribute code. See
[https://docs.flightgear.org/contributors-guide/guidelines/building.html Developing on the codebase] if you do not already
have a working setup. Some understanding of ''Git'' will also be
necessary; this free, online [https://git-scm.com/book/en/v2 Git book] is quite useful.}}

This page introduces how to contribute to the core [[FlightGear Git|Git repositories]] of [[FlightGear]].

The most efficient way to contribute changes to the FlightGear code base is to
file a merge request (this doesn't apply to [[aircraft]] or [[addon|add-ons]], which are
managed differently). We'll first give an overview of the process including
its main prerequisites, then explain each step in more detail.

== Overview ==

The basic workflow for first-time contributors to a FlightGear Git repository
is:

#. '''Fork the repository.'''
Fork the relevant FlightGear repository into your GitLab account. You will
need to know which repository contains the code you are trying to change.
Familiarizing yourself with the code base and the purpose of each
repository is strongly recommended.

#. '''Set up a local clone.'''
Prepare a clone of the repository on your hard disk that is convenient for
getting updates from the upstream repository and pushing changes to your
fork. You'll also use this clone to perform test builds.

#. '''Build the project.'''
If you haven't already done so, this will be the time to set up your
development environment so that you can build FlightGear.

#. '''Create a new branch.'''
Create a branch on your clone to isolate your changes. Use a clear and
descriptive name for your branch (e.g. <code>fix-menubar-typo</code> or
<code>add-new-joystick-configs</code>).

#. '''Make changes.'''
Make the changes on your branch in small, focused commits. Each commit
should be self-contained and represent one logical change.

#. '''Test and double-check.'''
Before you submit your changes to the FlightGear team for review,
double-check your work. Ensure that your code builds and that tests pass.

#. '''Rebase and push.'''
Check if the upstream repository was updated in the meantime. If so, rebase
your work on its latest state and perform a final test run to make sure
everything still works fine.

#. '''Submit a merge request.'''
Open a merge request (MR) to propose your changes for review. Be sure to
use the ''Merge Request Template'' to provide necessary context for
reviewers. Feel free to ask on the developer mailing list if you're unsure
whom to add as a reviewer.

#. '''Code review.'''
Once you have created a merge request, other developers will review your
work, give feedback, and sometimes request changes be made. This is a
crucial part of the development process, as it helps reduce bugs and
improves code quality.

#. '''Clean up.'''
If your merge request was applied, pull your changes from the upstream
branch and delete the local branch you created for the merge request.

In order to present these steps in more detail, we'll now assume that you
intend to make your first contribution to the [https://gitlab.com/flightgear/simgear SimGear repository] (and thus,
that you haven't already forked it). Except for the target branch name which
may differ, the process would be the same for any Git repository of the
FlightGear project.

== Fork the Repository ==

For what follows, you'll need to create a [https://gitlab.com/ GitLab] account if you don't already
have one. Once you are logged into your account, go to the repository home
page ([https://gitlab.com/flightgear/simgear here] in our example) and click on the
Fork button as shown in
; after
filling some information, this will lead to the creation of a copy of the
upstream repository in your own GitLab namespace under
<code><nowiki>https://gitlab.com/YourUserName/</nowiki></code>.

[[File:01_forking.png|thumb|alt=how to find the Fork button on the main page of the repository|Forking the upstream repository]]

Once you've clicked on the button, a new page is loaded as shown in
. The ''Project name'' will be prominent but it's
only a label—choose it as you wish (“My SimGear fork” in the example). For the
''Project URL'', you'll want to select your GitLab username after the initial
portion <code><nowiki>https://gitlab.com/</nowiki></code>.

[[File:02 project name, URL, slug.png|thumb|alt=dialog that allows one to enter the project name, URL and slug for a fork|Entering the project name, URL and slug for your fork]]

The ''Project slug'' is the final part of the base URL for the fork you're about
to create; let's choose <code>flightgear-simgear</code> so that all your forks of
repositories of the FlightGear project are named <code>flightgear-something</code>.
This way, they will be easy to distinguish from non-FlightGear repositories
you might want to publish under <code><nowiki>https://gitlab.com/YourUserName/</nowiki></code>. Beware
that if you modify the ''Project name'', the GitLab user interface automatically
modifies the ''Project slug''; so, better fill them in this order: ''Project name''
then ''Project slug''.

There are a few fields left to enter. If you choose to include only the
default branch, you'll save a little amount of space but might have to fetch
other upstream branches later. Give your fork public visiblity so that reviews
can take place. When ready, click on the Fork project button to
actually create your fork of the upstream repository.



== Set Up a Local Clone ==

Since we want to pull updates from the upstream repository, it is convenient
to clone it to your hard disk and modify the clone so that pushes go by
default to your fork (which is online under
<code><nowiki>https://gitlab.com/YourUserName/</nowiki></code>). Cloning the upstream SimGear repository
can be done with:

<syntaxhighlight lang="bash">
git clone https://gitlab.com/flightgear/simgear.git
</syntaxhighlight>

{{tip|If you use <code>download_and_compile.sh</code> and it manages the repository you
want to contribute to (this is obviously the case for SimGear), there is
no need to create a new clone: you can simply use the repository clone it
created on your disk.}}

Now, let's add a Git remote that points to your fork of the upstream
repository. We configure this remote so that pushing to it uses <abbr title="Secure Shell">SSH</abbr> authentication. We also configure your repository clone so
that pushes go to your fork by default.

<syntaxhighlight lang="bash">
git remote add flo https://gitlab.com/frougon/flightgear-simgear.git
git remote set-url --push flo git@gitlab.com:frougon/flightgear-simgear.git
git config remote.pushDefault flo
</syntaxhighlight>

In the above commands, replace <code>flo</code> (name of the created remote) with an
appropriate name of your choice; also replace <code>frougon</code> with your GitLab
username.

== Build the Project ==

Make sure you can build FlightGear using the repository clone set up in the
previous step and that the resulting executables run normally. This way,
you'll be able to properly test any changes you later make in this clone.

{{note|The following steps will have to be repeated for each
“self-contained changeset” that you intend to contribute.}}

== Create a New Branch ==

Create a branch based on <code>origin/next</code> that tracks <code>origin/next</code> and make
sure it is up-to-date. Instead of <code>new-branch-name</code>, choose a name that
makes it clear what the changes in the created branch are supposed to do.

<syntaxhighlight lang="bash">
git checkout -b new-branch-name origin/next
git pull
</syntaxhighlight>

{{note|Here, <code>origin</code> is a remote that points to the upstream repository
you cloned from, and <code>next</code> is the name of the development branch
in the [https://gitlab.com/flightgear/simgear SimGear repository] (this is also the case for [https://gitlab.com/flightgear/flightgear FlightGear] and [https://gitlab.com/flightgear/fgdata FGData]). If
you were to contribute to a different repository such as [https://gitlab.com/flightgear/documentation FlightGear documentation], the branch
to base your work on might have a different name (e.g., <code>main</code>).}}

== Make Changes ==

Commit the desired changes to the branch you created in the previous step. If
you need help with <code>git</code>, this online [https://git-scm.com/book/en/v2 book] is a great resource.

Each commit message should start with a single, not too long summary line (no
more than 72—80 characters if possible), then a blank line, then normal
explanations. Example commit message:

<pre>
HID: allow sending output reports from Nasal

- make watched properties only react on a value change
- refactor the larger usage enums to their own file
</pre>

Like here, it is useful when the beginning of the first line is short and
makes it clear to readers which part of the code (subsystem, class, etc.) is
affected by the changes.

== Test and Double-check ==

Rebuild FlightGear with your changes, carefully test. Build the FlightGear
test suite and verify that the tests still pass. This can be done by running
<code>make test_suite</code> or <code>ninja test_suite</code> from the FlightGear build directory
(not the source repository!).

Use commands like:

* <code>git status</code> to check the state of your working directory and repository;
* <code>git log -p</code> to proofread your commit diffs and messages;
* <code>git commit --amend</code> to modify the most recent commit on the branch;
* <code>git rebase -i <ref></code> to modify commits located further
in the ancestry graph (namely, descendants of commit <code><ref></code>; see the
<code>git rebase</code> manual page for explanations).

The <code>gitk</code> program is not essential but can be nice for examining
commits and visualizing the commit graph. If <code>gitk</code> appears to see
local changes that really aren't there, run <code>git status</code> then rerun
<code>gitk</code>.

The <code>pre-commit</code> and <code>clang-format</code> programs are useful to run code quality
checks and apply the project formatting rules. Some of the configured
<code>pre-commit</code> hooks will for instance check for common mistakes
including typos, mixed whitespace or line endings, and so on. If you've
[https://pre-commit.com/#3-install-the-git-hook-scripts installed] the
<code>pre-commit</code> hooks in your repository clone, <code>pre-commit</code>
will be automatically run every time you commit.

{{note|In most cases, the GitLab CI (Continuous Integration) runs
the <code>pre-commit</code> and <code>clang-format</code> checks as part
of the automatic verifications that need to pass, before a merge request can be applied.}}

== Rebase and Push ==

If the upstream branch you started from has changed in the meantime, your work
needs to be rebased on top of its latest state. This can be done with the
following command:

<syntaxhighlight lang="bash">
git pull --rebase
</syntaxhighlight>

In case someone was working on the same files as you, this may trigger
conflicts (so it's a good idea to first announce what you're going to work on
in order to minimize friction and benefit from the insight of experienced
people). Conflicts don't happen very often and it's not the end of the world
when they do. Again, this [https://git-scm.com/book/en/v2 Git book] is a very useful resource in such cases.

If the rebasing did grab upstream changes, perform a final build-and-test run
to be sure everything works fine. Finally, push the branch to your fork:

<syntaxhighlight lang="bash">
git push
</syntaxhighlight>

With no additional arguments, this pushes the current branch to the remote
specified with the <code>remote.pushDefault</code> setting, i.e. to your clone if you
followed the [[#section-Set-up-a-local-clone|above]] instructions. Once
the push is successful, <code>git</code> will show a URL; following it will start the next step.

== Submit a Merge Request ==

The web page opened from the URL output by <code>git</code> when you pushed to
your fork allows to create a merge request from the branch that was pushed.
From this page, select the proper target branch: for development code in
[https://gitlab.com/flightgear/simgear SimGear], that would be <code>next</code>. Select yourself as
an ''assignee'' (meaning that ''you'' are going to shape the merge request into
its final form). Select one or more reviewers to look at it—you can ask on the
[https://sourceforge.net/p/flightgear/mailman/flightgear-devel/ flightgear-devel mailing-list] if unsure, or just leave the field as
''Unassigned''. Don't worry too much about the milestone ''(a priori,'' <code>next</code>
should do unless the merge request is specifically a fix for a release
branch). Select applicable labels, etc.

Regarding the ''Delete source branch when merge request is accepted'' option, we
advise you to make sure it is enabled, otherwise your fork will soon have tons
of branches. What this option does is the following: when the branch from your
merge request is merged into the upstream branch, GitLab will automatically
delete the merge request branch (that you pushed) from your fork. This happens
online at GitLab, not in your local clone. Thus, even after this
occurs, the branch will still be present locally in your clone, until you
delete it yourself (cf. [[#local-branch-removal|below]]).

Finally, the ''Squash commits when merge request is accepted'' option can be
used in case you pushed several commits but would rather have them coalesced
into a single one when the merge request is applied. This is something that
can be done locally using <code>git</code> before pushing (in particular, with
<code>git rebase -i</code>), however the option is still useful in case commits are added
to the merge request after the initial push, be it by you or by reviewers.

== Code Review ==

After a few minutes, hours or days, you'll receive feedback from the
FlightGear developers about your merge request. Reviewing merge requests
requires expertise and takes some time, so please carefully read the remarks
and suggestions, follow up on the questions and requests for changes.

== Clean Up ==

Once the branch is merged, update the local branch of your clone that tracks
the upstream branch your merge request went to (this is the <code>next</code> branch in
our SimGear example):

<syntaxhighlight lang="bash">
git checkout next
git pull --rebase
</syntaxhighlight>

(Normally, the <code>--rebase</code> option shouldn't be necessary here as you
shouldn't have any local commits on top of the upstream ones in this branch,
however it doesn't hurt and can make things easier if you've been forgetful.)



You can now delete the local branch you created earlier to avoid cluttering
your local clone with legacy, unneeded branches:

<syntaxhighlight lang="bash">
git branch -d new-branch-name
</syntaxhighlight>

In case this branch hasn't been merged ''exactly as is'' into the upstream
branch (same commit contents and metadata), <code>git</code> will warn and
refuse to delete the branch unless you insist using <code>-D</code>. If this happens,
you'll have to evaluate yourself (by using <code>git log -p</code>, by comparing
files...) if deleting your local branch <code>new-branch-name</code> is really the
right thing to do. In the likely case that what was merged is a strict
improvement over what you have in <code>new-branch-name</code>, then deleting is the
way to go.

{{tip|If you really, really messed up and deleted the branch before
realizing that it was a mistake, <code>git reflog</code> is likely to save you:
among other things, it shows the commit hashes corresponding to previous
positions of the tips of various branches. As long as no garbage collection occurred in the meantime (<code>git gc</code>), the commit
hashes are all you need to restore “lost commits”: simply create a
branch or tag from the desired commit (before doing do, you may want
to use <code>git show <hash></code> to see the commit for a given hash, or <code>git log <hash></code> to examine its ancestry).}}

From time to time, you may also want to run <code>git fetch -p flo</code> (replace
<code>flo</code> with the name of a remote that points to your fork,
cf. [[#section-Set-up-a-local-clone]]). This removes the <code>flo/...</code>
branches from your local clone that have been deleted from your fork at GitLab
due to the ''Delete source branch when merge request is accepted'' option on the
merge request page (note that for instance, <code>flo/new-branch-name</code> and
<code>new-branch-name</code> are different branches in your clone; they'll both clutter
the display when using <code>git log</code> or <code>gitk</code> until you delete them).

== External links ==
* [https://docs.flightgear.org/contributors-guide/core-developers-guide/git-workflow.html How to Contribute Code]
* [https://git-scm.com/book/en/v2 The Git book]

[[Category:Howto]]
[[Category:Core developer documentation]]
[[ru:Howto:Приступая к разработке ядра]]
[[Category:Hackathon Materials]]

How the FlightGear project works

2026-05-28T06:20:52Z

Servo: /* Overview */ link

{{Working together}}
''See also [[Volunteer|volunteering]].''

As [[FlightGear]] is becoming increasingly popular each year, we've been seeing a number of controversial discussions regarding the inner workings of the FlightGear project recently. Meanwhile, it is a well-known fact among long-time contributors that the FlightGear development model may seem irritating at first and it is known to cause some confusions or even frustration among new contributors who may already have experience contributing in other flight sim communities or even other OSS software.

This page describes the organizational structure and development workflow of the FlightGear open-source flight simulator project. It is intended for newcomers who want to understand how decisions are made, who does what, and how to get involved.

== Overview ==

FlightGear is an open-source, multi-platform flight simulator developed by a worldwide community of [[Volunteer|volunteers]]. The project is not owned by any company; it is managed by a group of core contributors who coordinate development, review contributions, and maintain the infrastructure.

The project consists of several [[FlightGear Git|Git repositories]] hosted on [https://gitlab.com/flightgear GitLab], with the main ones being:

* flightgear – the main simulator application
* simgear – the simulation libraries for FlightGear
* fgdata – base data package
* manual – introduction for beginners

== Governance Model ==

FlightGear follows a loosely structured, meritocratic governance model:

* Users – provide feedback, bug reports, and feature requests
* Contributors – submit code, [[aircraft]], [[scenery]], documentation, or translations
* Reviewers – experienced contributors who regularly review merge requests
* Core Developers – a group of long-standing contributors with write access to the main repositories and the authority to merge changes

== Development Model ==

FlightGear uses a GitLab-based workflow very similar to the one described in [[Howto:Start core development]].

=== Branching Strategy ===

Most active repositories (simgear, flightgear, fgdata) use the following branches:

* next – primary development branch; all new features and non-critical fixes go here
* release/{{current release|full}} – stable release branches (e.g., <code>release/2024.1.6</code>) used for backporting critical fixes

The <code>next</code> branch is always open for contributions. It is regularly merged into release branches shortly before a new version is published.

=== Release Cycle ===
{{Main article|release plan}}

== Communication Channels ==

The project uses several communication platforms:

* [[Mailing list]] – [https://sourceforge.net/p/flightgear/mailman/flightgear-devel/ flightgear-devel] for development discussions
* [https://gitlab.com/groups/flightgear/-/issues GitLab Issues] – bug tracking and feature requests per repository
* GitLab Merge Requests – code review and contribution integration
* Forum – [https://forum.flightgear.org/ FlightGear Forum] for user support and aircraft/showcase discussions
* [[Discord]] – real-time chat

== Roles and Responsibilities ==

=== Contributors ===

Anyone can contribute by:

* Submitting merge requests (code, aircraft, scenery, docs)
* Reporting bugs with clear steps to reproduce
* Helping other users on the forum or chat
* Translating the interface or documentation
* Donating hardware, hosting, or financial support (via [https://www.flightgear.org/donate/ the official page])

=== Reviewers ===

Reviewers are trusted contributors who:

* Triage issues and merge requests
* Request changes or approve contributions
* Ensure code quality, style, and testing standards are met
* Mentor new contributors

=== Core Team ===

Core team members have:

* Commit access to one or more main repositories
* Permission to merge approved merge requests
* Responsibility for release management and infrastructure
* The ability to vote (informally) on major project decisions

== Getting Involved ==

If you want to contribute to the official repository:
* See [[Howto:Start core development]]

[[Category:Working together]]
[[fr:Comment fonctionne le projet Flightgear]]

Howto:Understand the FlightGear development process

2026-05-28T06:19:23Z

Servo:

{{stub}}
{{Working together}}

The '''[[FlightGear]] development process''' is described below, with an accessible language and lots of links to Wikipedia for terms you might not know. To learn more, see [[Release Plan]].

== Understanding code development ==
=== Code development for the unaware ===
Usually, the process of ''compiling a program'' refers to taking its [[wikipedia:source code|source code]] (written in some [[wikipedia:programming language|programming language]] and running it through a so called [[wikipedia:compiler|compiler]], which compiles, assembles and links the human readable source code to come up with the resulting binary and [[wikipedia:executable|executable]] files, which contain the [[wikipedia:machine code|machine code]] that can be run by your computer (CPU).

When you simply download a pre-compiled FlightGear release, you do not have to do this yourself, because other people have already done this for you. These are so called [[wikipedia:release management|release managers]], who often also happen to be software developers themselves.

This is because the process of compiling a piece of software such as FlightGear requires a so called [[wikipedia:build environment|build environment]] which consists of a number of tools (such as a compiler), and custom project configuration settings to turn human readable source code into the machine code that is required for actually running a program.

Programs are usually written in a plain text editor. However, there are very complex "word processors" specifically designed to deal with source code in various programming languages. They are called [[wikipedia:Integrated development environment|Integrated development environment]]s or IDEs, because they usually also provide comprehensive integration with the build environment, including its various tools. For example, an '''IDE''' may provide integrated support for syntax highlighting, as well as support for running certain commands, i.e. to recompile/rebuild parts of the program (or all of it). In addition, IDEs typically provide support for source code management to access a corresponding respository.

==== The repository ====
{{Main article|FlightGear Git}}
The human-readable source code is stored on a shared place. It's called generally [[wikipedia:Repository (version control)|repository]], and FlightGear specifically uses [[FlightGear Git|Git]] (once, CVS). Repositories do not only store code, but allow concurrent contributions without stepping on each other's toes. In very simple terms, all changes to a single piece of code are tracked, so that people can easily look up who made a certain change, or if there were any changes made in a certain time frame (e.g. to prevent conflicts between people working with the same files). Imagine it like a revision history on wikipedia or the FlightGear wiki: for any changes there's someone who's responsible for it, and if several people made conflicting changes, the software will show the difference to merge things easily.

This repository does not store only the FlightGear core project, but also other sister ones, like [[TerraGear]], [[SimGear]] and the [[#Understanding the base package|base package]], as well as several related tools.

=== Normal and core developers ===
People who build FlightGear from source code and make modifications to this source code, are usually called [[wikipedia:programmer|programmer]]s or more generally [[wikipedia:software developer|developers]]. People who have commit rights to the master [[FlightGear Git]] repository, are called ''core developers'' -- because they are the ones who develop the FlightGear "core".

Other programmers/developers may provide patches to the source code, which need to be reviewed, improved and committed by those core developers.

== Understanding the base package ==
The base package contains the data: scenery, aircraft, sounds, images/textures, configuration files, scripts. It has its own section in the main repository.

Most data kept in the base package does not involve any coding/programming, the only exceptions are [[Nasal]] scripts and GLSL [[Shaders]]. However, none of these require a dedicated build environment, people able to run FlightGear, will automatically have an environment suitable to develop and test Nasal and shaders.

You can contribute to the base package without being a hardcore programmer. See [[Volunteer]].

=== Configuration files ===
A [[wikipedia:configuration file|configuration file]] provides a convenient interface to customize a program's behavior without having to be a programmer or developer. Similarly, [[wikipedia:command line argument|command line argument]]s are another way for customizing program behavior without having to change a program's source code.

Imagine it like the difference between a carpenter and someone who merely takes a pre-fabricated piece of furniture (like a chair or table) and customizes it by changing its color, or adding/removing some features. Similarly, just because you are able to refuel your car or change your tyres you would not necessarily be referred to as a "car mechanic".

So, unless you start modifying the source code (logics) of the program (FlightGear) in order to change existing behavior, your changes would normally not qualify as ''developing'', even changing XML files does not fall under ''development'', because [[wikipedia:Xml|XML]] is a markup (i.e. description) language and not a ''programming'' language. To see what's XML used for in FligthGear, visit [[XML|this article]].

{{Note|To be absolutely fair, some FlightGear XML files do support programming related constructs, especially condition handling via SGCondition, but also the state machine stuff, as well as the autopilot system, the latter providing various building blocks to come up with configurable autopilot components like PID controllers and filters.In addition, FDM development itself is often done via XML files and can be an extremely complex topic, despite not necessarily involving programming in the conventional sense.}}

=== Non programming developers ===
People who do development largely within the confines of the base package (i.e. by creating or modifying aircraft/instruments and/or scenery or other base package resources) are usually also called ''developers'', specifying their area of interest. Terms you'll mostly see here are for example ''aircraft developer'' or ''scenery developer'', both of which imply that their work takes usually place in the base package. Some people may refer to them as ''base package developers'' or as ''[[wikipedia:middlware|middlware]] developers''.

This distinction is largely due to the different set of skills required for producing these resources. While programming and software development in general requires dealing with source code of programs in different programming languages, aircraft or scenery development is no longer primarily about programming. These people don't ''program'' aircraft or scenery, but usually they ''design'' things primarily (i.e. [[wikipedia:3d modeling|3D models, textures]]) and may then add various other resources (such as for example sounds, animations, flight models).

Programming in this context usually refers to tiny scripted programs that are stored in and loaded from the base package, reusable components often provided by others.
Programs written in such [[wikipedia:scripting language|scripting language]]s are usually not separately compiled, and can be easily created by people new to programming or software development in general.

== Modding ==
{{Main article|addon}}
Of course, you can also literally ''compile'' parts (like certain scenery or aircraft) of FlightGear to create a custom version of it. So, someone who simply takes FlightGear, and who creates a custom version of it by downstripping the base package, omitting certain resources and adding new ones or creating custom configurations, would probably not normally be referred to as a "developer" here. The most appropriate term would be [[wikipedia:Modding|modder]] in that case, because you are "modding" FlightGear to come up with a special version for a specific purpose, without doing any actual "development" like for example C++ coding, Nasal scripting or more generally aircraft/scenery development.

Normally, "developing" something implies changing functionality and logics, in the sense of "programming" and "creating" things, features and code. Someone who customizes a piece of software by editing configuration files and by adding or removing such files would usually not be called a developer.

== Developing documentation ==
There are also documentation developers, including manual writers and wiki editors.

[[Category:Howto]]
[[Category:Working together]]

TerraGear

2026-05-28T06:14:03Z

Servo: /* Platform specific */ remove dead links

{{Hatnote|Not to be confused with [[TerraSync]], a tool to download scenery on-the-fly.}}

[[File:TerraGear The Hague wireframe.png|thumb|270px|A wireframe view of detailed [[CORINE]] and [[OSM]] scenery, generated by TerraGear.]]
'''TerraGear''' is a collection of open-source tools and rendering libraries which can transform publically available GIS data in 3D representations (i.e. 3D models or 3D maps) of the earth for use in real time rendering projects. TerraGear can import 3D data sets such as DEM terrain grids, 2D polygon data sets such as coastlines, city outlines, lake outlines, and 2D raster data sets such as the 1 km NAOO land use/land cover data. It also has tools for generating realistic [[airport]]s, runways, and lighting based on available FAA data.

TerraGear is the primary tool used to generate the [[scenery]] for the [[FlightGear]] project.

Without terragear, it is possible to change Terrain '''textures''' but not terrain '''shapes'''. If you want to change the texture for cities, you change the materials file. If you want to change the coast line, you need terragear.
Check the material files in directory FGDATA/Material. Identify the material file that includes Montevideo, which is probably latin_american_cities.xml ([[Howto:Regional texturing]] and this page [[Procedural Texturing]]<ref>{{cite web
|url = https://forum.flightgear.org/viewtopic.php?p=311143#p311143
|title = <nowiki> Re: Improving terrain realism </nowiki>
|author = <nowiki> ludomotico </nowiki>
|date = May 25th, 2017
|added = May 25th, 2017
|script_version = 0.40
}}</ref>

== Introduction ==
For a variety of reasons you might want to build terrain yourself, rather than downloading it from the available scenery on FlightGear. For instance, if you use [[WED]] to create or modify an airport layout, you might wish to see how that modified airport would look in the Scenery before deciding you're happy with the results. And normally, to see and use the airport in the scenery, it's necessary to submit the modifications to the FlightGear scenery staff and then wait untill the next update of the scenery of that area is available via [[TerraSync]] or in the [http://www.flightgear.org/download/scenery/ official FlightGear Scenery] build. If you can build terrain yourself, you can start using it right away.

Maybe the official scenery is too detailed for your slow machine, and you'd like to build terrain using a digital elevation model (DEM) with poorer resolution, to decrease the number of polygons and thus improve your framerates. Or maybe you've got a fantastically fast machine, and you want to build your own terrain using higher resolution vector data (vmap1, Tiger) to get better roads/rivers. For all these reasons learning how to use TerraGear is a good idea.

== Getting TerraGear ==
=== Using the download_and_compile.sh script (Linux distros using apt) ===
Get the script download_and_compile.sh if you don't already have it. Copy it into a specific directory, no need to be root.
{{#tag: syntaxhighlight |
wget {{fgmeta url|view=raw|path=download_and_compile.sh}}
mv download_and_compile.sh\?format\=raw download_and_compile.sh
chmod 755 download_and_compile.sh
./download_and_compile.sh SIMGEAR TERRAGEAR
| lang="bash"
}}
This will build SIMGEAR (pre-requisite) and TERRAGEAR properly, installing dependencies if necessary and you will be done for the TG compilation part of the process.

=== Source ===
The source is hold in a [[Git]] repository at SourceForge..
{{#tag: syntaxhighlight |
{{terragear clone|post=flightgear-terragear}}
| lang="bash"
}}

you have to use the stable branch called "scenery/ws2.0"!
{{terragear url|branch=scenery/ws2.0/~}}

== Compilation ==
=== Dependencies ===
* TerraGear
** [[SimGear]] - '''Not''' simgear-cs! (simgear-dev package)
*** SimGear can be compiled without OSG support thus eliminating many deps, like OSG. Use "-DSIMGEAR_HEADLESS=YES" for a minimal build.
** [http://www.cgal.org/ CGAL] - For high accuracy geometric calculations
** [http://www.gdal.org/ libgdal]

=== Building ===
cmake . [options]
make install
<tt>cmake</tt> options:
-DCMAKE_PREFIX_PATH="/path/to/lib/install/prefix"

=== Platform specific ===
==== Debian ====
* [[Building FlightGear - Debian#TerraGear]]
==== Gentoo ====
* emerge -av terragear</tt>
See [[Building Flightgear - Gentoo]].

== GUI Tool ==
A [[TerraGear GUI]] is available for those that would like to use TerraGear without knowing/using the command line options.

== Related content ==
* [[Using Terragear]]
* [[Howto:Use TerraGear without wanting to kill yourself]]
* [[TerraGear CORINE]]
* [[TerraGear Documentation]]
* [http://api-docs.freeflightsim.org/terragear/ TerraGear API docs]

{{Terra}}
{{Building}}

[[Category:TerraGear]]

[[es:TerraGear]]
[[fr:TerraGear]]

How the FlightGear project works

2026-05-28T06:10:33Z

Servo: renew the page

{{Working together}}
''See also [[Volunteer|volunteering]].''

As [[FlightGear]] is becoming increasingly popular each year, we've been seeing a number of controversial discussions regarding the inner workings of the FlightGear project recently. Meanwhile, it is a well-known fact among long-time contributors that the FlightGear development model may seem irritating at first and it is known to cause some confusions or even frustration among new contributors who may already have experience contributing in other flight sim communities or even other OSS software.

This page describes the organizational structure and development workflow of the FlightGear open-source flight simulator project. It is intended for newcomers who want to understand how decisions are made, who does what, and how to get involved.

== Overview ==

FlightGear is an open-source, multi-platform flight simulator developed by a worldwide community of [[Volunteer|volunteers]]. The project is not owned by any company; it is managed by a group of core contributors who coordinate development, review contributions, and maintain the infrastructure.

The project consists of several Git repositories hosted on [https://gitlab.com/flightgear GitLab], with the main ones being:

* flightgear – the main simulator application
* simgear – the simulation libraries for FlightGear
* fgdata – base data package
* manual – introduction for beginners

== Governance Model ==

FlightGear follows a loosely structured, meritocratic governance model:

* Users – provide feedback, bug reports, and feature requests
* Contributors – submit code, [[aircraft]], [[scenery]], documentation, or translations
* Reviewers – experienced contributors who regularly review merge requests
* Core Developers – a group of long-standing contributors with write access to the main repositories and the authority to merge changes

== Development Model ==

FlightGear uses a GitLab-based workflow very similar to the one described in [[Howto:Start core development]].

=== Branching Strategy ===

Most active repositories (simgear, flightgear, fgdata) use the following branches:

* next – primary development branch; all new features and non-critical fixes go here
* release/{{current release|full}} – stable release branches (e.g., <code>release/2024.1.6</code>) used for backporting critical fixes

The <code>next</code> branch is always open for contributions. It is regularly merged into release branches shortly before a new version is published.

=== Release Cycle ===
{{Main article|release plan}}

== Communication Channels ==

The project uses several communication platforms:

* [[Mailing list]] – [https://sourceforge.net/p/flightgear/mailman/flightgear-devel/ flightgear-devel] for development discussions
* [https://gitlab.com/groups/flightgear/-/issues GitLab Issues] – bug tracking and feature requests per repository
* GitLab Merge Requests – code review and contribution integration
* Forum – [https://forum.flightgear.org/ FlightGear Forum] for user support and aircraft/showcase discussions
* [[Discord]] – real-time chat

== Roles and Responsibilities ==

=== Contributors ===

Anyone can contribute by:

* Submitting merge requests (code, aircraft, scenery, docs)
* Reporting bugs with clear steps to reproduce
* Helping other users on the forum or chat
* Translating the interface or documentation
* Donating hardware, hosting, or financial support (via [https://www.flightgear.org/donate/ the official page])

=== Reviewers ===

Reviewers are trusted contributors who:

* Triage issues and merge requests
* Request changes or approve contributions
* Ensure code quality, style, and testing standards are met
* Mentor new contributors

=== Core Team ===

Core team members have:

* Commit access to one or more main repositories
* Permission to merge approved merge requests
* Responsibility for release management and infrastructure
* The ability to vote (informally) on major project decisions

== Getting Involved ==

If you want to contribute to the official repository:
* See [[Howto:Start core development]]

[[Category:Working together]]
[[fr:Comment fonctionne le projet Flightgear]]

New to FlightGear

2026-05-28T05:51:13Z

Servo: /* How you can help */

'''Welcome to [[FlightGear]]!''' Here we will try to get you up in the virtual air in the shortest time possible. We will also introduce you to some of the features of this flight simulator and also a few information on its community.

== Installation and setup ==
=== Hardware requirements ===
For FlightGear to run smoothly, it requires a video card with OpenGL drivers 4.0 or higher. This is usually not a problem, but take a look at the [[hardware recommendations]] to have a better idea.

=== Getting FlightGear ===
You may download the latest files from the [https://www.flightgear.org/download/ FlightGear download] page. Choose the source or binary files appropriate for your particular system. {{Wikipedia|AppImage|AppImage}} binary files for Linux are also available with 2020.3 LTS and later. Most Linux users will find that most distributions have a packaged version of FlightGear (the package name could be <code>fgfs</code> or <code>flightgear</code>.)

Depending on your technical expertise you may choose the [[Git]] development version of FlightGear, which typically has more features and can be required by some of the latest developmental aircraft, but can be unstable and is more complicated to get for non-Windows users. In general, the development version is not advised to the average user, but if you are willing to do some testing there is a nightly build available for [https://www.flightgear.org/download/nightly/ download]. If you are using a Git version controlled copy of FlightGear, you may choose to synchronise your aircraft using the version controlled [[FGAddon|FGAddon aircraft development repository]].

=== Installing on Windows ===
After you downloaded the installer, run it and follow its instructions to install FlightGear.

Defender SmartScreen on Windows may block the installation simply because the binary file is not signed with a key that Microsoft respects. Of course, the key is paid. In this case, we need to click on the inconspicuous "More info" link. Only then will the "Run anyway" button appear. You can safely trust that this is not a dangerous application, as long as you have actually downloaded it from official sources.

If you're using third-party antivirus software for some reason, it may be blocking FlightGear from installing. This isn't something we can control, so it's entirely up to you how you want to handle it.

With the Windows installer, you may choose where to install FlightGear. The [[$FG_ROOT]] directory would be <code><your chosen directory>/data</code>.

=== Installing on macOS ===
Installing FlightGear on macOS is very simple. Just drag and drop the FlightGear icon to the <code>/Applications</code> folder. That is it.

The first time you launch FlightGear, its icon on the Dock bounces for several seconds while loading aircraft and airport info. When the GUI launcher appears, select the aircraft and airport, then click "Fly!" to launch the simulator. You can configure more options using the GUI launcher. See the [http://flightgear.sourceforge.net/manual/next/en/getstart-ench4.html#takeoff-how-to-start-the-program official manual] for more details.

If you would like to launch FlightGear using command-line, launch the Terminal app and type the following.

cd /Applications/FlightGear.app/Contents/MacOS
./fgfs --options.....

The [[$FG_ROOT]] and [[$FG_SCENERY]] are not set on macOS. If you want to specify these variables yourself for command-line use, run the followings on the Terminal app:

FG_ROOT=/Applications/FlightGear.app/Contents/Resources/data
FG_SCENERY=[[$FG_ROOT]]/Scenery

After launching the GUI launcher, you will have the alias to [[$FG_ROOT]] at <code>$HOME/Documents/FlightGear/<version></code> so you can browse the data folder using Finder.

Note: Once you have installed FlightGear, Mac users can locate their [[$FG_ROOT]] folder by opening their applications folder in Finder, right clicking on FlightGear, and clicking "Show Package Contents". This will take you inside the FlightGear folder. You are now able to access all files including Data/Aircraft to [[Howto: Install aircraft#Macintosh OS X|install new aircraft]].

=== Installing from source ===
Main article: [[Building FlightGear]]

=== Getting scenery ===
A limited set of [[scenery]] comes installed with FlightGear. For FlightGear 2024.1 this consists of
* The area surrounding the featured airport for the release which is [[Keflavik_Airport|Keflavik International Airport]] (BIKF)
* The tutorial airport for the [[Cessna_172P|Cessna 172P]] which is [[Hilo_International_Airport|Hilo International Airport]] (PHTO)

In FlightGear, scenery is generally stored in you [[$FG_ROOT]] directory, and is divided into three kinds of data:
* '''Airports''' holds airport data, like runway usage and parking spots.
* '''Objects''' and '''Models''' are the buildings, bridges and radio towers, etc. that represent three-dimensional structures.
* '''Terrain''' represents the contours, elevations and type of ground you fly/taxi over.

The current way of "installing" new scenery is enabling [[TerraSync]], which will automatically download and update any place you visit - even on the fly! If you have a slow Internet connection and/or computer you could instead use a scenery manager, for example [[TerraMaster]]. In addition you can also manually download and install new scenery parts, either the official [[World Scenery]] or custom scenery.

The scenery is also available on the [https://www.flightgear.org/download/mirrors/ mirrors page] of the FlightGear website, and can be installed following [[Howto: Install scenery]]. '''This is recommended for users with weak internet connections or weak computers!'''

Custom scenery is available in many places. For example, on the {{forum link|f=5|text=FlightGear forum}} or within repositories. An internet search should be able to find them. See [[Suggested_custom_scenery|suggested custom scenery]] page for a few recent releases.

FlightGear 2020.3.7 LTS and later added an experimental rollout of 3 dimensional buildings, roads, and objects based on OpenStreetMap data for the entire world to automatically downloaded TerraSync data - see [[OSM2City 1st Worldbuild|1st OSM2City world-build]] notes (March 2021). Some manual downloads of 3d structures for regions or entire countries is available on the [[Areas populated with osm2city scenery|osm2City downloads]] wiki page.

=== Getting aircraft ===
Additional [[aircraft]] can be downloaded and installed through the [[Qt-launcher|launcher]]. Alternatively, you can go to the FlightGear website and navigate to the [http://www.flightgear.org/download/ download page], then choose the aircraft download link that fits your FlightGear version. In addition there are many third party [[hangars]]. For the installation, see [[Howto: Install aircraft]].

== Running FlightGear ==
=== Starting FlightGear ===
The easiest way to start FlightGear is to use the desktop icon. This starts the graphical interface [[FlightGear Qt launcher]] where you can choose aircraft, start position etc. Remember the Qt launcher only has basic options to get you started. A lot of options for graphics, scenery, [[Weather|weather]], [https://www.flightgear.org/tours/simulating-the-ever-changing-scenery/ environment], [[Input_device|input devices]] etc. are available from the [[menu]] inside the simulator.

Many users choose however to start FlightGear directly from the command line. The executable name is <code>fgfs</code> and can be run without options. If it is "not found", it is likely not in your [https://en.wikipedia.org/wiki/PATH_(variable) path]. The location depends on your particular system and choices you made during compile and installation. There is a list of [[Command Line Parameters]] which must be used to change many options, like the aircraft you want. The most important:

fgfs --launcher # opens the FlightGear Qt launcher
fgfs --show-aircraft # displays a list of installed aircraft
fgfs --aircraft=c172p # start FG with the aircraft "c172p" (from the list)

The Qt launcher also lets users add command line parameters for options that are normally changed from the menu inside the simulator, as well as quite advanced options that are only available from the command line (as of August 2020).

=== Configuring rendering and UI ===
[[File:Rendering options 2024.1.png|thumb|View > Rendering Options dialog.]]
If your render quality or framerate is too low, click "View > Rendering Options" to adjust the graphic settings. For newer hardware, it's recommended to set "graphics quality" to high and check "use disk space for faster loading", "animated jetways" and "satellite photoscenery".

If the menu text appears too small on high DPI or large screens, you can manually [[Menubar#How to Change the Default Menubar Font Size|change the menubar font size]] by editing the data file, or simply click "Debug > Cycle GUI Style".

=== Using the keyboard and/or mouse ===
Users with limited access to a [[joystick]] or other controllers sometimes use the keyboard or mouse to control their aircraft. Using the keyboard to fly can be difficult and the mouse is recommended over the keyboard for flying, yet even a cheap joystick would improve the experience so much.

To get help with keyboard commands, with FlightGear running, go to the ''Help'' menu, look under ''Basic Keys'' (for simulator related commands) and ''Common Aircraft Keys'' (for commands universal to all aircraft) and ''Aircraft Help'' (for key commands specific to your aircraft). If the main menu is hidden press {{key press|F10}}. If you come from other simulators, check [[key commands compared to other simulators]] for an overview of the difference between the key commands of that sim and FlightGear.

To use the mouse to fly the aircraft, press {{key press|Tab}} (the cursor should change to a cross) and move the mouse to direct the aircraft. Press {{key press|Tab}} again to look around (cursor should show a two sided arrow), and press {{key press|Tab}} again to return to normal mode, used to click stuff in the cockpit.

For most users lacking a rudder axis control, it’s difficult to manually coordinate [[aileron]] and [[rudder]] movements during a turn. To enable auto-coordination and make flight easier, you may click "Settings", then click the "Show more" button on the right of "General", and finally click "Enable auto-coordination" in the launcher.

=== First time in the cockpit ===
Finding your way around the cockpit can be daunting the first time.

Where is the "virtual cockpit"? Not all FlightGear aircraft come with an interior actually, some research projects may not even come with an exterior model. A 2D panel may display over the 3D cockpit if one exists. You may turn this off through ''Main Menu'' > ''View'' > ''View Options'' and deselecting ''Show 2D panel'' in the ''Display Options'' section, or by pressing {{key press|Shift|P}}. Otherwise, you should be sitting in the virtual cockpit when FlightGear starts, as long as the Cockpit View is selected (if not pressing {{key press|Ctrl|V}} should get you to the pilot view).

You may find it difficult to read some of the displays, dials and gauges on the instrument panel. You can use the ''view'' mode of the mouse (press {{key press|Tab}} until you get a cursor shaped like a double arrow) to pan and the mouse wheel to zoom, or pan with the joystick hat and zoom with {{key press|X}} and {{key press|Shift|X}}.

One of the first steps that many take on entering an unfamiliar cockpit is to press {{key press|Ctrl|C}} to highlight all the "hotspots", that is instrument controls, buttons, knobs, etc. Many aircraft also offer a specific help menu.

Some functions, such as starter or magneto, may be difficult to use or simply lack clickable "hotspots", especially in aircraft models which are in development. In most cases you can go for the equivalent controls on a 2D panel or resort to the keyboard. The keyboard always work according to the assignments listed on the ''Help'' menu, but sometimes these are reassigned by an aircraft or configuration. Again, remember to check all the help dialogs.

=== Starting the engine ===
You are eager to fly, but the engine is off. Well, turning on the engines is not always easy. Some aircraft have an ''autostart'' entry in their custom menu, but here is a general procedure that should work in many cases:

In general to start the engine on a piston-engine type aircraft, you need (after making sure the game is not paused {{key press|p}}):
# Fuel: Some aircraft start the simulation with no fuel. You can add it in ''Equipment'' > ''Fuel and Payload''.
# Correct fuel mixture: This is generally ''rich'', so push the red knob all the way in, or use the key {{key press|m}} to enrich ({{key press|Shift|m}} leans.)
# Magnetos set on ''both'': Turn the key or press {{key press|}}} ''three times'' to move through ''R'', ''L'', ''Both''.
# Throttle: Some engines start better with a little gas.
# Run the starter: Click the ''Start'' position of the key on the panel, or press {{key press|s}}. Hold the starter for sufficient time, even 10 seconds.

Starting all engines in a multi-engine aircraft is similar to the single engine - except you must follow the same start sequence for each and every engine. FlightGear provides a convenient way to do this for all engines at once: Press {{key press|~}} and all the procedure above will work for all the engines. Note though that the default 2D panel is connected to ''only one engine'' and the {{key press|~}} trick might not work. Also, give some gas to be sure that all the engines are on.

These instructions may not work for jet aircraft, helicopters, or other types of aircraft with complex start procedures. Check the instructions in the aircraft help menu (press {{key press|?}}) and/or look at [[Aircraft|the aircraft's article on this wiki]]. In general to start the engine on a jet engine type aircraft, you need to:
# Set cutoff ''ON''
# Engage the starter
# Once the engines spools up to approximately 5% N1, set cutoff ''OFF''
# Disengage the starter once the engine has reached operational speed

== Learning to fly ==
=== FlightGear's Manual ===
FlightGear has an official [https://www.flightgear.org/support/manual/ manual] that covers the basics of flight. As a beginner, you may want to start with [https://flightgear.gitlab.io/getstart/release-{{current release|cr}}/en/HTML/getstart-ench8.html Chapter 8: A Basic Flight Simulator Tutorial].

=== Tutorials ===
Many aircraft have their own interactive [[tutorials|tutorial]]. With tutorials, you can learn to operate particular aircraft but also learn to fly. You can access tutorials by going to ''Main menu'' > ''Help'' > ''Tutorial''. A great place to start is the tutorial for the [[Cessna 172P]] aircraft, commonly used in real life to learn to fly fixed-winged aircraft.

If the tutorial starts without a runway and surrounded by water, your setup of FlightGear is missing the scenery for the airport at which the tutorial was supposed to run. To get scenery see the [[#Getting scenery]] section above.

== Making your first flight ==
=== Realism ===
One of the most frequent questions novice pilots ask about any flight simulator, but more so to FlightGear, is "Why is my aircraft turning left all the time?" Although it could be due to wind gusts crossing the runway, it is more likely due to the [[Understanding Propeller Torque and P-Factor|propeller torque and p-factor]].

In certain other flight simulators, despite marketing slogans to the contrary, some settings are turned down to make the aircraft easier to fly. This reduces effects such as the above. The realism is always turned up in FlightGear.

Here are some of the FlightGear realism points, which may be confusing to first time pilots:
* "Left turning syndrome" for the previously mentioned reasons.
* Compass turning error: A compass, when subjected to the forces of flight, tends to turn in the opposite direction for a brief period before settling on the correct heading. This is not a malfunction (see also the Wikipedia article {{wikipedia|Aircraft compass turns}}).
* The Vertical Speed Indicator (VSI) is also subject to error.
* The [[Horizontal Situation Indicator]] (HSI) is driven by a gyroscope (that is why it is sometimes called a Directional Gyroscope), which is subject to ''gyro drift''. The indicator will drift from its current heading and must be periodically (every ~15 minutes) calibrated to agree with the magnetic compass heading.
* You cannot just cancel a turn or climb by centering the yoke or stick. You must turn or push the stick the other way to get to level and level flight. But even then, the plane will not maintain its altitude or heading by itself. A common mistake is trying to find a hands off yoke position. While with trimming one could leave the plane for a couple of seconds, one must use autopilot or constantly adjust the yoke.

Many forces act on an aircraft in flight as well as on the [[avionics and instruments]] used for control and navigation, and may be counter-intuitive. Pilots must learn to recognize these phenomena and compensate for their effects. ''FlightGear models instrument errors that exist in the real world''.

=== Airports and navigation aids ===
When you first start FlightGear, whether from the command line or the graphical interface of the launchers, you may wonder how to determine what airports are available. The launcher displays a list of airports, but you will not see details such as tower or [[ILS]] frequencies. You will not find a map showing [[VOR]]s and their frequencies. What can you do? See [[Getting aeronautical charts]].

In-sim, there is a map you can use in ''Main Menu'' > ''Equipment'' > ''Map'', which will allow you to see navigation data and the position of airports and aids. For more help with navigation see [[Understanding navigation]].

=== Flying using the autopilot ===
Some aircraft require you to use the [[autopilot]] available from the ''Autopilot'' menu, which is the original FlightGear autopilot. This is a ''generic'' autopilot and as such, many aircraft come with their own ''specific'' autopilot, frequently a model of the real life one.

For aircraft that provide their own autopilot, you should use the autopilot controls available in the virtual cockpit. This means clicking on the instrument panel in the virtual cockpit. The Autopilot menu will be grayed out and unavailable when the aircraft supplies its own autopilot in some aircraft, including the Airbuses and the [[Cessna 172P|C172P]].

The Cessna 172 comes with a [[Bendix/King KAP140 Autopilot]] in its virtual cockpit. You can use both the autopilot device in the cockpit and the [[Autopilot#Autopilot Settings|autopilot settings]] from the menu.

== Advanced ==
=== Flying ===
{{Main article|Aircraft}}

* If you continue to fly light civilian aircraft, [[Cessna 182S]] which is more complex than C172P and [[Piper PA28 Warrior II|PA28]] are good choices.
* If you are interested in flying airlines, [[Airbus A320 family]], Boeing [[Boeing 777|777]]/[[Boeing 787-8 Dreamliner|787]], [[MD-11]] and [[MD-80]] are suggested.
* If you are fascinated by fighter aircrafts, choose a highly rated military aircraft (such as [[General Dynamics F-16 Fighting Falcon|F-16]]/[[F-15]]) from [[Aircraft#Modern military aircraft|here]], and enable multiplayer damage or install [[Bombable]].
* If you switch to helicopters, it is recommended to fly [[Eurocopter EC130 B4]].

Besides common aircraft, there are also detailed [[Space Shuttle|space shuttles]] available.

=== Scenery ===
It is fascinating to explore the [[scenery]] (or just test the graphics/frame rate) with [[UFO]]. First of all, [[#Configuring rendering and UI|increase your graphics quality]]. If you don't see buildings initially, keep FG open and wait for a while for [[TerraSync]] to finish downloading and for the buildings to appear.
There are plenty of [[Suggested airports|well-developed airports]] and scenery areas. You can also explore the scenery objects on the [https://scenery.flightgear.org/map model map].

=== Multiplayer ===
FlightGear has some multiplayer servers that will let you fly in more lively skies, see [[Howto: Multiplayer]]. There are also [[OpenRadar]] and [[ATC-pie]], standalone programs that will let you be an [[Air traffic control|air traffic controller]].

There is also a [[MPMap|multiplayer map]] that lets you see who is online right now, and even what [[navaids]] are nearby.

=== Menu items ===
For a quick reference about the usage of each menu item in FlightGear, see [[menu]].

=== Addons ===
FlightGear has a lot of third-party [[Addon|addons]] containing enhancements. For beginners, [[Logbook Add-on|Logbook]] and [[Which Runway Add-on|Which Runway]] may be the most useful addons.

== The FlightGear community ==
=== Getting help ===
This page is designed to give the user the essential things they need to know about using FlightGear for the first time. Besides the [[Portal:User|User portal]] of this wiki, there are other pages you may want to read:
*[[Troubleshooting problems]] to help you with the most common issues;
*[[Frequently asked questions]];
...and communication channels that can be used to obtain information or request help:
*The [[FlightGear Manual]], a ''must read'' for beginners;
*{{forum link|text=FlightGear Forum}} and its subforums;
*[[Discord|FlightGear's Discord server]], the quickest way to get help;
*[[FlightGear IRC channel]];
*[[Mailing list|FlightGear users mailing list]], biggest chance to get in contact with core developers;
*Documents bundled with the release package.

=== Customizing FlightGear without compiling it ===
[https://www.flightgear.org/download/ Our website] offers precompiled binaries for download and install on Windows, macOS and Linux. In addition, most Linux distributions provide a packaged version in their repositories.

Although the install is binary, most of FlightGear's systems are open to configuration through [[XML]] files and [[NASAL scripting]]. You are free ''and encouraged'' to make changes to aircraft flight models, scenery, textures, OpenGL [[shader]]s and any other feature you wish to change for your personal satisfaction or to share with other FlightGear users. If this is what you intend to do, take a look at the [[Portal:Developer|Developer portal]].

=== How you can help ===
{{Main article|Volunteer}}
FlightGear is an open source, volunteer based project. That means that whatever you find here comes from passion, spare time and nothing else. This includes the simulator, the scenery, the aircraft, the wiki, the {{forum link|text=forum}} and everything else. Volunteers, in essence ''people that do things'', are fundamental to this project. Without them, it would not make a single step forward. So it is essential that contributors have fun in what they do.

If you plan to contribute to this project, you should take a look at some articles that will give you some hints:
*[[Howto:Understand the FlightGear development process]]
*[[Implementing new features for FlightGear]]
*[[How the FlightGear project works]]

The fields where their help would be appreciated are many:
;Testing:
*[[Building FlightGear|Build]] the latest Git code
*[https://gitlab.com/flightgear/flightgear/-/issues File bug reports]
*Running FlightGear via valgrind to track down memory leaks

;Support:
*Help new users with downloading, compiling, installing and running FlightGear ({{forum link|text=on the forum}} or on [[Discord]])
*Provide ideas & suggestions, see: [[Feature Requests / Proposals / Ideas]]
*Help [[Portal:Wiki|clean up this wiki]]
*Help provide new contents for missing wiki pages

;Development:
*Core codebase:
**Provide [[Howto:Start core development|source code / data / documentation contributions]]
**Provide [[Bugs|bug fixes]] or new features
*Aircraft development (3D modeling, textures, FDMs, scripting)
*Scenery development (terrain, model, weather)
*Get involved in any of the other FlightGear-affiliated projects

[[Category:FlightGear]]

[[ca:Nou a FlightGear]]
[[de:Neu bei FlightGear]]
[[es:Nuevo en FlightGear]]
[[fi:Uusi_käyttäjä]]
[[fr:Nouveau sur flightgear]]
[[it:Nuovo per FlightGear]]
[[ja:FlightGear入門]]
[[nl:Nieuw bij FlightGear]]
[[pl:Nowy w FlightGear]]
[[pt:Novo no FlightGear]]
[[sr:Novi u FlightGear-u]]
[[th:New to FlightGear]]

New to FlightGear

2026-05-28T05:49:44Z

Servo: /* How you can help */ typo

'''Welcome to [[FlightGear]]!''' Here we will try to get you up in the virtual air in the shortest time possible. We will also introduce you to some of the features of this flight simulator and also a few information on its community.

== Installation and setup ==
=== Hardware requirements ===
For FlightGear to run smoothly, it requires a video card with OpenGL drivers 4.0 or higher. This is usually not a problem, but take a look at the [[hardware recommendations]] to have a better idea.

=== Getting FlightGear ===
You may download the latest files from the [https://www.flightgear.org/download/ FlightGear download] page. Choose the source or binary files appropriate for your particular system. {{Wikipedia|AppImage|AppImage}} binary files for Linux are also available with 2020.3 LTS and later. Most Linux users will find that most distributions have a packaged version of FlightGear (the package name could be <code>fgfs</code> or <code>flightgear</code>.)

Depending on your technical expertise you may choose the [[Git]] development version of FlightGear, which typically has more features and can be required by some of the latest developmental aircraft, but can be unstable and is more complicated to get for non-Windows users. In general, the development version is not advised to the average user, but if you are willing to do some testing there is a nightly build available for [https://www.flightgear.org/download/nightly/ download]. If you are using a Git version controlled copy of FlightGear, you may choose to synchronise your aircraft using the version controlled [[FGAddon|FGAddon aircraft development repository]].

=== Installing on Windows ===
After you downloaded the installer, run it and follow its instructions to install FlightGear.

Defender SmartScreen on Windows may block the installation simply because the binary file is not signed with a key that Microsoft respects. Of course, the key is paid. In this case, we need to click on the inconspicuous "More info" link. Only then will the "Run anyway" button appear. You can safely trust that this is not a dangerous application, as long as you have actually downloaded it from official sources.

If you're using third-party antivirus software for some reason, it may be blocking FlightGear from installing. This isn't something we can control, so it's entirely up to you how you want to handle it.

With the Windows installer, you may choose where to install FlightGear. The [[$FG_ROOT]] directory would be <code><your chosen directory>/data</code>.

=== Installing on macOS ===
Installing FlightGear on macOS is very simple. Just drag and drop the FlightGear icon to the <code>/Applications</code> folder. That is it.

The first time you launch FlightGear, its icon on the Dock bounces for several seconds while loading aircraft and airport info. When the GUI launcher appears, select the aircraft and airport, then click "Fly!" to launch the simulator. You can configure more options using the GUI launcher. See the [http://flightgear.sourceforge.net/manual/next/en/getstart-ench4.html#takeoff-how-to-start-the-program official manual] for more details.

If you would like to launch FlightGear using command-line, launch the Terminal app and type the following.

cd /Applications/FlightGear.app/Contents/MacOS
./fgfs --options.....

The [[$FG_ROOT]] and [[$FG_SCENERY]] are not set on macOS. If you want to specify these variables yourself for command-line use, run the followings on the Terminal app:

FG_ROOT=/Applications/FlightGear.app/Contents/Resources/data
FG_SCENERY=[[$FG_ROOT]]/Scenery

After launching the GUI launcher, you will have the alias to [[$FG_ROOT]] at <code>$HOME/Documents/FlightGear/<version></code> so you can browse the data folder using Finder.

Note: Once you have installed FlightGear, Mac users can locate their [[$FG_ROOT]] folder by opening their applications folder in Finder, right clicking on FlightGear, and clicking "Show Package Contents". This will take you inside the FlightGear folder. You are now able to access all files including Data/Aircraft to [[Howto: Install aircraft#Macintosh OS X|install new aircraft]].

=== Installing from source ===
Main article: [[Building FlightGear]]

=== Getting scenery ===
A limited set of [[scenery]] comes installed with FlightGear. For FlightGear 2024.1 this consists of
* The area surrounding the featured airport for the release which is [[Keflavik_Airport|Keflavik International Airport]] (BIKF)
* The tutorial airport for the [[Cessna_172P|Cessna 172P]] which is [[Hilo_International_Airport|Hilo International Airport]] (PHTO)

In FlightGear, scenery is generally stored in you [[$FG_ROOT]] directory, and is divided into three kinds of data:
* '''Airports''' holds airport data, like runway usage and parking spots.
* '''Objects''' and '''Models''' are the buildings, bridges and radio towers, etc. that represent three-dimensional structures.
* '''Terrain''' represents the contours, elevations and type of ground you fly/taxi over.

The current way of "installing" new scenery is enabling [[TerraSync]], which will automatically download and update any place you visit - even on the fly! If you have a slow Internet connection and/or computer you could instead use a scenery manager, for example [[TerraMaster]]. In addition you can also manually download and install new scenery parts, either the official [[World Scenery]] or custom scenery.

The scenery is also available on the [https://www.flightgear.org/download/mirrors/ mirrors page] of the FlightGear website, and can be installed following [[Howto: Install scenery]]. '''This is recommended for users with weak internet connections or weak computers!'''

Custom scenery is available in many places. For example, on the {{forum link|f=5|text=FlightGear forum}} or within repositories. An internet search should be able to find them. See [[Suggested_custom_scenery|suggested custom scenery]] page for a few recent releases.

FlightGear 2020.3.7 LTS and later added an experimental rollout of 3 dimensional buildings, roads, and objects based on OpenStreetMap data for the entire world to automatically downloaded TerraSync data - see [[OSM2City 1st Worldbuild|1st OSM2City world-build]] notes (March 2021). Some manual downloads of 3d structures for regions or entire countries is available on the [[Areas populated with osm2city scenery|osm2City downloads]] wiki page.

=== Getting aircraft ===
Additional [[aircraft]] can be downloaded and installed through the [[Qt-launcher|launcher]]. Alternatively, you can go to the FlightGear website and navigate to the [http://www.flightgear.org/download/ download page], then choose the aircraft download link that fits your FlightGear version. In addition there are many third party [[hangars]]. For the installation, see [[Howto: Install aircraft]].

== Running FlightGear ==
=== Starting FlightGear ===
The easiest way to start FlightGear is to use the desktop icon. This starts the graphical interface [[FlightGear Qt launcher]] where you can choose aircraft, start position etc. Remember the Qt launcher only has basic options to get you started. A lot of options for graphics, scenery, [[Weather|weather]], [https://www.flightgear.org/tours/simulating-the-ever-changing-scenery/ environment], [[Input_device|input devices]] etc. are available from the [[menu]] inside the simulator.

Many users choose however to start FlightGear directly from the command line. The executable name is <code>fgfs</code> and can be run without options. If it is "not found", it is likely not in your [https://en.wikipedia.org/wiki/PATH_(variable) path]. The location depends on your particular system and choices you made during compile and installation. There is a list of [[Command Line Parameters]] which must be used to change many options, like the aircraft you want. The most important:

fgfs --launcher # opens the FlightGear Qt launcher
fgfs --show-aircraft # displays a list of installed aircraft
fgfs --aircraft=c172p # start FG with the aircraft "c172p" (from the list)

The Qt launcher also lets users add command line parameters for options that are normally changed from the menu inside the simulator, as well as quite advanced options that are only available from the command line (as of August 2020).

=== Configuring rendering and UI ===
[[File:Rendering options 2024.1.png|thumb|View > Rendering Options dialog.]]
If your render quality or framerate is too low, click "View > Rendering Options" to adjust the graphic settings. For newer hardware, it's recommended to set "graphics quality" to high and check "use disk space for faster loading", "animated jetways" and "satellite photoscenery".

If the menu text appears too small on high DPI or large screens, you can manually [[Menubar#How to Change the Default Menubar Font Size|change the menubar font size]] by editing the data file, or simply click "Debug > Cycle GUI Style".

=== Using the keyboard and/or mouse ===
Users with limited access to a [[joystick]] or other controllers sometimes use the keyboard or mouse to control their aircraft. Using the keyboard to fly can be difficult and the mouse is recommended over the keyboard for flying, yet even a cheap joystick would improve the experience so much.

To get help with keyboard commands, with FlightGear running, go to the ''Help'' menu, look under ''Basic Keys'' (for simulator related commands) and ''Common Aircraft Keys'' (for commands universal to all aircraft) and ''Aircraft Help'' (for key commands specific to your aircraft). If the main menu is hidden press {{key press|F10}}. If you come from other simulators, check [[key commands compared to other simulators]] for an overview of the difference between the key commands of that sim and FlightGear.

To use the mouse to fly the aircraft, press {{key press|Tab}} (the cursor should change to a cross) and move the mouse to direct the aircraft. Press {{key press|Tab}} again to look around (cursor should show a two sided arrow), and press {{key press|Tab}} again to return to normal mode, used to click stuff in the cockpit.

For most users lacking a rudder axis control, it’s difficult to manually coordinate [[aileron]] and [[rudder]] movements during a turn. To enable auto-coordination and make flight easier, you may click "Settings", then click the "Show more" button on the right of "General", and finally click "Enable auto-coordination" in the launcher.

=== First time in the cockpit ===
Finding your way around the cockpit can be daunting the first time.

Where is the "virtual cockpit"? Not all FlightGear aircraft come with an interior actually, some research projects may not even come with an exterior model. A 2D panel may display over the 3D cockpit if one exists. You may turn this off through ''Main Menu'' > ''View'' > ''View Options'' and deselecting ''Show 2D panel'' in the ''Display Options'' section, or by pressing {{key press|Shift|P}}. Otherwise, you should be sitting in the virtual cockpit when FlightGear starts, as long as the Cockpit View is selected (if not pressing {{key press|Ctrl|V}} should get you to the pilot view).

You may find it difficult to read some of the displays, dials and gauges on the instrument panel. You can use the ''view'' mode of the mouse (press {{key press|Tab}} until you get a cursor shaped like a double arrow) to pan and the mouse wheel to zoom, or pan with the joystick hat and zoom with {{key press|X}} and {{key press|Shift|X}}.

One of the first steps that many take on entering an unfamiliar cockpit is to press {{key press|Ctrl|C}} to highlight all the "hotspots", that is instrument controls, buttons, knobs, etc. Many aircraft also offer a specific help menu.

Some functions, such as starter or magneto, may be difficult to use or simply lack clickable "hotspots", especially in aircraft models which are in development. In most cases you can go for the equivalent controls on a 2D panel or resort to the keyboard. The keyboard always work according to the assignments listed on the ''Help'' menu, but sometimes these are reassigned by an aircraft or configuration. Again, remember to check all the help dialogs.

=== Starting the engine ===
You are eager to fly, but the engine is off. Well, turning on the engines is not always easy. Some aircraft have an ''autostart'' entry in their custom menu, but here is a general procedure that should work in many cases:

In general to start the engine on a piston-engine type aircraft, you need (after making sure the game is not paused {{key press|p}}):
# Fuel: Some aircraft start the simulation with no fuel. You can add it in ''Equipment'' > ''Fuel and Payload''.
# Correct fuel mixture: This is generally ''rich'', so push the red knob all the way in, or use the key {{key press|m}} to enrich ({{key press|Shift|m}} leans.)
# Magnetos set on ''both'': Turn the key or press {{key press|}}} ''three times'' to move through ''R'', ''L'', ''Both''.
# Throttle: Some engines start better with a little gas.
# Run the starter: Click the ''Start'' position of the key on the panel, or press {{key press|s}}. Hold the starter for sufficient time, even 10 seconds.

Starting all engines in a multi-engine aircraft is similar to the single engine - except you must follow the same start sequence for each and every engine. FlightGear provides a convenient way to do this for all engines at once: Press {{key press|~}} and all the procedure above will work for all the engines. Note though that the default 2D panel is connected to ''only one engine'' and the {{key press|~}} trick might not work. Also, give some gas to be sure that all the engines are on.

These instructions may not work for jet aircraft, helicopters, or other types of aircraft with complex start procedures. Check the instructions in the aircraft help menu (press {{key press|?}}) and/or look at [[Aircraft|the aircraft's article on this wiki]]. In general to start the engine on a jet engine type aircraft, you need to:
# Set cutoff ''ON''
# Engage the starter
# Once the engines spools up to approximately 5% N1, set cutoff ''OFF''
# Disengage the starter once the engine has reached operational speed

== Learning to fly ==
=== FlightGear's Manual ===
FlightGear has an official [https://www.flightgear.org/support/manual/ manual] that covers the basics of flight. As a beginner, you may want to start with [https://flightgear.gitlab.io/getstart/release-{{current release|cr}}/en/HTML/getstart-ench8.html Chapter 8: A Basic Flight Simulator Tutorial].

=== Tutorials ===
Many aircraft have their own interactive [[tutorials|tutorial]]. With tutorials, you can learn to operate particular aircraft but also learn to fly. You can access tutorials by going to ''Main menu'' > ''Help'' > ''Tutorial''. A great place to start is the tutorial for the [[Cessna 172P]] aircraft, commonly used in real life to learn to fly fixed-winged aircraft.

If the tutorial starts without a runway and surrounded by water, your setup of FlightGear is missing the scenery for the airport at which the tutorial was supposed to run. To get scenery see the [[#Getting scenery]] section above.

== Making your first flight ==
=== Realism ===
One of the most frequent questions novice pilots ask about any flight simulator, but more so to FlightGear, is "Why is my aircraft turning left all the time?" Although it could be due to wind gusts crossing the runway, it is more likely due to the [[Understanding Propeller Torque and P-Factor|propeller torque and p-factor]].

In certain other flight simulators, despite marketing slogans to the contrary, some settings are turned down to make the aircraft easier to fly. This reduces effects such as the above. The realism is always turned up in FlightGear.

Here are some of the FlightGear realism points, which may be confusing to first time pilots:
* "Left turning syndrome" for the previously mentioned reasons.
* Compass turning error: A compass, when subjected to the forces of flight, tends to turn in the opposite direction for a brief period before settling on the correct heading. This is not a malfunction (see also the Wikipedia article {{wikipedia|Aircraft compass turns}}).
* The Vertical Speed Indicator (VSI) is also subject to error.
* The [[Horizontal Situation Indicator]] (HSI) is driven by a gyroscope (that is why it is sometimes called a Directional Gyroscope), which is subject to ''gyro drift''. The indicator will drift from its current heading and must be periodically (every ~15 minutes) calibrated to agree with the magnetic compass heading.
* You cannot just cancel a turn or climb by centering the yoke or stick. You must turn or push the stick the other way to get to level and level flight. But even then, the plane will not maintain its altitude or heading by itself. A common mistake is trying to find a hands off yoke position. While with trimming one could leave the plane for a couple of seconds, one must use autopilot or constantly adjust the yoke.

Many forces act on an aircraft in flight as well as on the [[avionics and instruments]] used for control and navigation, and may be counter-intuitive. Pilots must learn to recognize these phenomena and compensate for their effects. ''FlightGear models instrument errors that exist in the real world''.

=== Airports and navigation aids ===
When you first start FlightGear, whether from the command line or the graphical interface of the launchers, you may wonder how to determine what airports are available. The launcher displays a list of airports, but you will not see details such as tower or [[ILS]] frequencies. You will not find a map showing [[VOR]]s and their frequencies. What can you do? See [[Getting aeronautical charts]].

In-sim, there is a map you can use in ''Main Menu'' > ''Equipment'' > ''Map'', which will allow you to see navigation data and the position of airports and aids. For more help with navigation see [[Understanding navigation]].

=== Flying using the autopilot ===
Some aircraft require you to use the [[autopilot]] available from the ''Autopilot'' menu, which is the original FlightGear autopilot. This is a ''generic'' autopilot and as such, many aircraft come with their own ''specific'' autopilot, frequently a model of the real life one.

For aircraft that provide their own autopilot, you should use the autopilot controls available in the virtual cockpit. This means clicking on the instrument panel in the virtual cockpit. The Autopilot menu will be grayed out and unavailable when the aircraft supplies its own autopilot in some aircraft, including the Airbuses and the [[Cessna 172P|C172P]].

The Cessna 172 comes with a [[Bendix/King KAP140 Autopilot]] in its virtual cockpit. You can use both the autopilot device in the cockpit and the [[Autopilot#Autopilot Settings|autopilot settings]] from the menu.

== Advanced ==
=== Flying ===
{{Main article|Aircraft}}

* If you continue to fly light civilian aircraft, [[Cessna 182S]] which is more complex than C172P and [[Piper PA28 Warrior II|PA28]] are good choices.
* If you are interested in flying airlines, [[Airbus A320 family]], Boeing [[Boeing 777|777]]/[[Boeing 787-8 Dreamliner|787]], [[MD-11]] and [[MD-80]] are suggested.
* If you are fascinated by fighter aircrafts, choose a highly rated military aircraft (such as [[General Dynamics F-16 Fighting Falcon|F-16]]/[[F-15]]) from [[Aircraft#Modern military aircraft|here]], and enable multiplayer damage or install [[Bombable]].
* If you switch to helicopters, it is recommended to fly [[Eurocopter EC130 B4]].

Besides common aircraft, there are also detailed [[Space Shuttle|space shuttles]] available.

=== Scenery ===
It is fascinating to explore the [[scenery]] (or just test the graphics/frame rate) with [[UFO]]. First of all, [[#Configuring rendering and UI|increase your graphics quality]]. If you don't see buildings initially, keep FG open and wait for a while for [[TerraSync]] to finish downloading and for the buildings to appear.
There are plenty of [[Suggested airports|well-developed airports]] and scenery areas. You can also explore the scenery objects on the [https://scenery.flightgear.org/map model map].

=== Multiplayer ===
FlightGear has some multiplayer servers that will let you fly in more lively skies, see [[Howto: Multiplayer]]. There are also [[OpenRadar]] and [[ATC-pie]], standalone programs that will let you be an [[Air traffic control|air traffic controller]].

There is also a [[MPMap|multiplayer map]] that lets you see who is online right now, and even what [[navaids]] are nearby.

=== Menu items ===
For a quick reference about the usage of each menu item in FlightGear, see [[menu]].

=== Addons ===
FlightGear has a lot of third-party [[Addon|addons]] containing enhancements. For beginners, [[Logbook Add-on|Logbook]] and [[Which Runway Add-on|Which Runway]] may be the most useful addons.

== The FlightGear community ==
=== Getting help ===
This page is designed to give the user the essential things they need to know about using FlightGear for the first time. Besides the [[Portal:User|User portal]] of this wiki, there are other pages you may want to read:
*[[Troubleshooting problems]] to help you with the most common issues;
*[[Frequently asked questions]];
...and communication channels that can be used to obtain information or request help:
*The [[FlightGear Manual]], a ''must read'' for beginners;
*{{forum link|text=FlightGear Forum}} and its subforums;
*[[Discord|FlightGear's Discord server]], the quickest way to get help;
*[[FlightGear IRC channel]];
*[[Mailing list|FlightGear users mailing list]], biggest chance to get in contact with core developers;
*Documents bundled with the release package.

=== Customizing FlightGear without compiling it ===
[https://www.flightgear.org/download/ Our website] offers precompiled binaries for download and install on Windows, macOS and Linux. In addition, most Linux distributions provide a packaged version in their repositories.

Although the install is binary, most of FlightGear's systems are open to configuration through [[XML]] files and [[NASAL scripting]]. You are free ''and encouraged'' to make changes to aircraft flight models, scenery, textures, OpenGL [[shader]]s and any other feature you wish to change for your personal satisfaction or to share with other FlightGear users. If this is what you intend to do, take a look at the [[Portal:Developer|Developer portal]].

=== How you can help ===
{{Main article|Volunteer}}
FlightGear is an open source, volunteer based project. That means that whatever you find here comes from passion, spare time and nothing else. This includes the simulator, the scenery, the aircraft, the wiki, the {{forum link|text=forum}} and everything else. Volunteers, in essence ''people that do things'', are fundamental to this project. Without them, it would not make a single step forward. So it is essential that contributors have fun in what they do.

If you plan to contribute to this project, you should take a look at some articles that will give you some hints:
*[[Howto:Understand the FlightGear development process]]
*[[Implementing new features for FlightGear]]
*[[How the FlightGear project works]]

There are never enough people contributing, and the fields where their help would be appreciated are many:
;Testing:
*[[Building FlightGear|Build]] the latest Git code
*[https://gitlab.com/flightgear/flightgear/-/issues File bug reports]
*Running FlightGear via valgrind to track down memory leaks

;Support:
*Help new users with downloading, compiling, installing and running FlightGear ({{forum link|text=on the forum}} or on [[Discord]])
*Provide ideas & suggestions, see: [[Feature Requests / Proposals / Ideas]]
*Help [[Portal:Wiki|clean up this wiki]]
*Help provide new contents for missing wiki pages

;Development:
*Core codebase:
**Provide [[Howto:Start core development|source code/data/documentation contributions]]
**Provide [[Bugs|bug fixes]] or new features
*Aircraft development (3D modeling, textures, FDMs, scripting)
*Scenery development (terrain, model, weather)
*Get involved in any of the other FlightGear-affiliated projects

[[Category:FlightGear]]

[[ca:Nou a FlightGear]]
[[de:Neu bei FlightGear]]
[[es:Nuevo en FlightGear]]
[[fi:Uusi_käyttäjä]]
[[fr:Nouveau sur flightgear]]
[[it:Nuovo per FlightGear]]
[[ja:FlightGear入門]]
[[nl:Nieuw bij FlightGear]]
[[pl:Nowy w FlightGear]]
[[pt:Novo no FlightGear]]
[[sr:Novi u FlightGear-u]]
[[th:New to FlightGear]]

New to FlightGear

2026-05-28T05:49:12Z

Servo: /* How you can help */

'''Welcome to [[FlightGear]]!''' Here we will try to get you up in the virtual air in the shortest time possible. We will also introduce you to some of the features of this flight simulator and also a few information on its community.

== Installation and setup ==
=== Hardware requirements ===
For FlightGear to run smoothly, it requires a video card with OpenGL drivers 4.0 or higher. This is usually not a problem, but take a look at the [[hardware recommendations]] to have a better idea.

=== Getting FlightGear ===
You may download the latest files from the [https://www.flightgear.org/download/ FlightGear download] page. Choose the source or binary files appropriate for your particular system. {{Wikipedia|AppImage|AppImage}} binary files for Linux are also available with 2020.3 LTS and later. Most Linux users will find that most distributions have a packaged version of FlightGear (the package name could be <code>fgfs</code> or <code>flightgear</code>.)

Depending on your technical expertise you may choose the [[Git]] development version of FlightGear, which typically has more features and can be required by some of the latest developmental aircraft, but can be unstable and is more complicated to get for non-Windows users. In general, the development version is not advised to the average user, but if you are willing to do some testing there is a nightly build available for [https://www.flightgear.org/download/nightly/ download]. If you are using a Git version controlled copy of FlightGear, you may choose to synchronise your aircraft using the version controlled [[FGAddon|FGAddon aircraft development repository]].

=== Installing on Windows ===
After you downloaded the installer, run it and follow its instructions to install FlightGear.

Defender SmartScreen on Windows may block the installation simply because the binary file is not signed with a key that Microsoft respects. Of course, the key is paid. In this case, we need to click on the inconspicuous "More info" link. Only then will the "Run anyway" button appear. You can safely trust that this is not a dangerous application, as long as you have actually downloaded it from official sources.

If you're using third-party antivirus software for some reason, it may be blocking FlightGear from installing. This isn't something we can control, so it's entirely up to you how you want to handle it.

With the Windows installer, you may choose where to install FlightGear. The [[$FG_ROOT]] directory would be <code><your chosen directory>/data</code>.

=== Installing on macOS ===
Installing FlightGear on macOS is very simple. Just drag and drop the FlightGear icon to the <code>/Applications</code> folder. That is it.

The first time you launch FlightGear, its icon on the Dock bounces for several seconds while loading aircraft and airport info. When the GUI launcher appears, select the aircraft and airport, then click "Fly!" to launch the simulator. You can configure more options using the GUI launcher. See the [http://flightgear.sourceforge.net/manual/next/en/getstart-ench4.html#takeoff-how-to-start-the-program official manual] for more details.

If you would like to launch FlightGear using command-line, launch the Terminal app and type the following.

cd /Applications/FlightGear.app/Contents/MacOS
./fgfs --options.....

The [[$FG_ROOT]] and [[$FG_SCENERY]] are not set on macOS. If you want to specify these variables yourself for command-line use, run the followings on the Terminal app:

FG_ROOT=/Applications/FlightGear.app/Contents/Resources/data
FG_SCENERY=[[$FG_ROOT]]/Scenery

After launching the GUI launcher, you will have the alias to [[$FG_ROOT]] at <code>$HOME/Documents/FlightGear/<version></code> so you can browse the data folder using Finder.

Note: Once you have installed FlightGear, Mac users can locate their [[$FG_ROOT]] folder by opening their applications folder in Finder, right clicking on FlightGear, and clicking "Show Package Contents". This will take you inside the FlightGear folder. You are now able to access all files including Data/Aircraft to [[Howto: Install aircraft#Macintosh OS X|install new aircraft]].

=== Installing from source ===
Main article: [[Building FlightGear]]

=== Getting scenery ===
A limited set of [[scenery]] comes installed with FlightGear. For FlightGear 2024.1 this consists of
* The area surrounding the featured airport for the release which is [[Keflavik_Airport|Keflavik International Airport]] (BIKF)
* The tutorial airport for the [[Cessna_172P|Cessna 172P]] which is [[Hilo_International_Airport|Hilo International Airport]] (PHTO)

In FlightGear, scenery is generally stored in you [[$FG_ROOT]] directory, and is divided into three kinds of data:
* '''Airports''' holds airport data, like runway usage and parking spots.
* '''Objects''' and '''Models''' are the buildings, bridges and radio towers, etc. that represent three-dimensional structures.
* '''Terrain''' represents the contours, elevations and type of ground you fly/taxi over.

The current way of "installing" new scenery is enabling [[TerraSync]], which will automatically download and update any place you visit - even on the fly! If you have a slow Internet connection and/or computer you could instead use a scenery manager, for example [[TerraMaster]]. In addition you can also manually download and install new scenery parts, either the official [[World Scenery]] or custom scenery.

The scenery is also available on the [https://www.flightgear.org/download/mirrors/ mirrors page] of the FlightGear website, and can be installed following [[Howto: Install scenery]]. '''This is recommended for users with weak internet connections or weak computers!'''

Custom scenery is available in many places. For example, on the {{forum link|f=5|text=FlightGear forum}} or within repositories. An internet search should be able to find them. See [[Suggested_custom_scenery|suggested custom scenery]] page for a few recent releases.

FlightGear 2020.3.7 LTS and later added an experimental rollout of 3 dimensional buildings, roads, and objects based on OpenStreetMap data for the entire world to automatically downloaded TerraSync data - see [[OSM2City 1st Worldbuild|1st OSM2City world-build]] notes (March 2021). Some manual downloads of 3d structures for regions or entire countries is available on the [[Areas populated with osm2city scenery|osm2City downloads]] wiki page.

=== Getting aircraft ===
Additional [[aircraft]] can be downloaded and installed through the [[Qt-launcher|launcher]]. Alternatively, you can go to the FlightGear website and navigate to the [http://www.flightgear.org/download/ download page], then choose the aircraft download link that fits your FlightGear version. In addition there are many third party [[hangars]]. For the installation, see [[Howto: Install aircraft]].

== Running FlightGear ==
=== Starting FlightGear ===
The easiest way to start FlightGear is to use the desktop icon. This starts the graphical interface [[FlightGear Qt launcher]] where you can choose aircraft, start position etc. Remember the Qt launcher only has basic options to get you started. A lot of options for graphics, scenery, [[Weather|weather]], [https://www.flightgear.org/tours/simulating-the-ever-changing-scenery/ environment], [[Input_device|input devices]] etc. are available from the [[menu]] inside the simulator.

Many users choose however to start FlightGear directly from the command line. The executable name is <code>fgfs</code> and can be run without options. If it is "not found", it is likely not in your [https://en.wikipedia.org/wiki/PATH_(variable) path]. The location depends on your particular system and choices you made during compile and installation. There is a list of [[Command Line Parameters]] which must be used to change many options, like the aircraft you want. The most important:

fgfs --launcher # opens the FlightGear Qt launcher
fgfs --show-aircraft # displays a list of installed aircraft
fgfs --aircraft=c172p # start FG with the aircraft "c172p" (from the list)

The Qt launcher also lets users add command line parameters for options that are normally changed from the menu inside the simulator, as well as quite advanced options that are only available from the command line (as of August 2020).

=== Configuring rendering and UI ===
[[File:Rendering options 2024.1.png|thumb|View > Rendering Options dialog.]]
If your render quality or framerate is too low, click "View > Rendering Options" to adjust the graphic settings. For newer hardware, it's recommended to set "graphics quality" to high and check "use disk space for faster loading", "animated jetways" and "satellite photoscenery".

If the menu text appears too small on high DPI or large screens, you can manually [[Menubar#How to Change the Default Menubar Font Size|change the menubar font size]] by editing the data file, or simply click "Debug > Cycle GUI Style".

=== Using the keyboard and/or mouse ===
Users with limited access to a [[joystick]] or other controllers sometimes use the keyboard or mouse to control their aircraft. Using the keyboard to fly can be difficult and the mouse is recommended over the keyboard for flying, yet even a cheap joystick would improve the experience so much.

To get help with keyboard commands, with FlightGear running, go to the ''Help'' menu, look under ''Basic Keys'' (for simulator related commands) and ''Common Aircraft Keys'' (for commands universal to all aircraft) and ''Aircraft Help'' (for key commands specific to your aircraft). If the main menu is hidden press {{key press|F10}}. If you come from other simulators, check [[key commands compared to other simulators]] for an overview of the difference between the key commands of that sim and FlightGear.

To use the mouse to fly the aircraft, press {{key press|Tab}} (the cursor should change to a cross) and move the mouse to direct the aircraft. Press {{key press|Tab}} again to look around (cursor should show a two sided arrow), and press {{key press|Tab}} again to return to normal mode, used to click stuff in the cockpit.

For most users lacking a rudder axis control, it’s difficult to manually coordinate [[aileron]] and [[rudder]] movements during a turn. To enable auto-coordination and make flight easier, you may click "Settings", then click the "Show more" button on the right of "General", and finally click "Enable auto-coordination" in the launcher.

=== First time in the cockpit ===
Finding your way around the cockpit can be daunting the first time.

Where is the "virtual cockpit"? Not all FlightGear aircraft come with an interior actually, some research projects may not even come with an exterior model. A 2D panel may display over the 3D cockpit if one exists. You may turn this off through ''Main Menu'' > ''View'' > ''View Options'' and deselecting ''Show 2D panel'' in the ''Display Options'' section, or by pressing {{key press|Shift|P}}. Otherwise, you should be sitting in the virtual cockpit when FlightGear starts, as long as the Cockpit View is selected (if not pressing {{key press|Ctrl|V}} should get you to the pilot view).

You may find it difficult to read some of the displays, dials and gauges on the instrument panel. You can use the ''view'' mode of the mouse (press {{key press|Tab}} until you get a cursor shaped like a double arrow) to pan and the mouse wheel to zoom, or pan with the joystick hat and zoom with {{key press|X}} and {{key press|Shift|X}}.

One of the first steps that many take on entering an unfamiliar cockpit is to press {{key press|Ctrl|C}} to highlight all the "hotspots", that is instrument controls, buttons, knobs, etc. Many aircraft also offer a specific help menu.

Some functions, such as starter or magneto, may be difficult to use or simply lack clickable "hotspots", especially in aircraft models which are in development. In most cases you can go for the equivalent controls on a 2D panel or resort to the keyboard. The keyboard always work according to the assignments listed on the ''Help'' menu, but sometimes these are reassigned by an aircraft or configuration. Again, remember to check all the help dialogs.

=== Starting the engine ===
You are eager to fly, but the engine is off. Well, turning on the engines is not always easy. Some aircraft have an ''autostart'' entry in their custom menu, but here is a general procedure that should work in many cases:

In general to start the engine on a piston-engine type aircraft, you need (after making sure the game is not paused {{key press|p}}):
# Fuel: Some aircraft start the simulation with no fuel. You can add it in ''Equipment'' > ''Fuel and Payload''.
# Correct fuel mixture: This is generally ''rich'', so push the red knob all the way in, or use the key {{key press|m}} to enrich ({{key press|Shift|m}} leans.)
# Magnetos set on ''both'': Turn the key or press {{key press|}}} ''three times'' to move through ''R'', ''L'', ''Both''.
# Throttle: Some engines start better with a little gas.
# Run the starter: Click the ''Start'' position of the key on the panel, or press {{key press|s}}. Hold the starter for sufficient time, even 10 seconds.

Starting all engines in a multi-engine aircraft is similar to the single engine - except you must follow the same start sequence for each and every engine. FlightGear provides a convenient way to do this for all engines at once: Press {{key press|~}} and all the procedure above will work for all the engines. Note though that the default 2D panel is connected to ''only one engine'' and the {{key press|~}} trick might not work. Also, give some gas to be sure that all the engines are on.

These instructions may not work for jet aircraft, helicopters, or other types of aircraft with complex start procedures. Check the instructions in the aircraft help menu (press {{key press|?}}) and/or look at [[Aircraft|the aircraft's article on this wiki]]. In general to start the engine on a jet engine type aircraft, you need to:
# Set cutoff ''ON''
# Engage the starter
# Once the engines spools up to approximately 5% N1, set cutoff ''OFF''
# Disengage the starter once the engine has reached operational speed

== Learning to fly ==
=== FlightGear's Manual ===
FlightGear has an official [https://www.flightgear.org/support/manual/ manual] that covers the basics of flight. As a beginner, you may want to start with [https://flightgear.gitlab.io/getstart/release-{{current release|cr}}/en/HTML/getstart-ench8.html Chapter 8: A Basic Flight Simulator Tutorial].

=== Tutorials ===
Many aircraft have their own interactive [[tutorials|tutorial]]. With tutorials, you can learn to operate particular aircraft but also learn to fly. You can access tutorials by going to ''Main menu'' > ''Help'' > ''Tutorial''. A great place to start is the tutorial for the [[Cessna 172P]] aircraft, commonly used in real life to learn to fly fixed-winged aircraft.

If the tutorial starts without a runway and surrounded by water, your setup of FlightGear is missing the scenery for the airport at which the tutorial was supposed to run. To get scenery see the [[#Getting scenery]] section above.

== Making your first flight ==
=== Realism ===
One of the most frequent questions novice pilots ask about any flight simulator, but more so to FlightGear, is "Why is my aircraft turning left all the time?" Although it could be due to wind gusts crossing the runway, it is more likely due to the [[Understanding Propeller Torque and P-Factor|propeller torque and p-factor]].

In certain other flight simulators, despite marketing slogans to the contrary, some settings are turned down to make the aircraft easier to fly. This reduces effects such as the above. The realism is always turned up in FlightGear.

Here are some of the FlightGear realism points, which may be confusing to first time pilots:
* "Left turning syndrome" for the previously mentioned reasons.
* Compass turning error: A compass, when subjected to the forces of flight, tends to turn in the opposite direction for a brief period before settling on the correct heading. This is not a malfunction (see also the Wikipedia article {{wikipedia|Aircraft compass turns}}).
* The Vertical Speed Indicator (VSI) is also subject to error.
* The [[Horizontal Situation Indicator]] (HSI) is driven by a gyroscope (that is why it is sometimes called a Directional Gyroscope), which is subject to ''gyro drift''. The indicator will drift from its current heading and must be periodically (every ~15 minutes) calibrated to agree with the magnetic compass heading.
* You cannot just cancel a turn or climb by centering the yoke or stick. You must turn or push the stick the other way to get to level and level flight. But even then, the plane will not maintain its altitude or heading by itself. A common mistake is trying to find a hands off yoke position. While with trimming one could leave the plane for a couple of seconds, one must use autopilot or constantly adjust the yoke.

Many forces act on an aircraft in flight as well as on the [[avionics and instruments]] used for control and navigation, and may be counter-intuitive. Pilots must learn to recognize these phenomena and compensate for their effects. ''FlightGear models instrument errors that exist in the real world''.

=== Airports and navigation aids ===
When you first start FlightGear, whether from the command line or the graphical interface of the launchers, you may wonder how to determine what airports are available. The launcher displays a list of airports, but you will not see details such as tower or [[ILS]] frequencies. You will not find a map showing [[VOR]]s and their frequencies. What can you do? See [[Getting aeronautical charts]].

In-sim, there is a map you can use in ''Main Menu'' > ''Equipment'' > ''Map'', which will allow you to see navigation data and the position of airports and aids. For more help with navigation see [[Understanding navigation]].

=== Flying using the autopilot ===
Some aircraft require you to use the [[autopilot]] available from the ''Autopilot'' menu, which is the original FlightGear autopilot. This is a ''generic'' autopilot and as such, many aircraft come with their own ''specific'' autopilot, frequently a model of the real life one.

For aircraft that provide their own autopilot, you should use the autopilot controls available in the virtual cockpit. This means clicking on the instrument panel in the virtual cockpit. The Autopilot menu will be grayed out and unavailable when the aircraft supplies its own autopilot in some aircraft, including the Airbuses and the [[Cessna 172P|C172P]].

The Cessna 172 comes with a [[Bendix/King KAP140 Autopilot]] in its virtual cockpit. You can use both the autopilot device in the cockpit and the [[Autopilot#Autopilot Settings|autopilot settings]] from the menu.

== Advanced ==
=== Flying ===
{{Main article|Aircraft}}

* If you continue to fly light civilian aircraft, [[Cessna 182S]] which is more complex than C172P and [[Piper PA28 Warrior II|PA28]] are good choices.
* If you are interested in flying airlines, [[Airbus A320 family]], Boeing [[Boeing 777|777]]/[[Boeing 787-8 Dreamliner|787]], [[MD-11]] and [[MD-80]] are suggested.
* If you are fascinated by fighter aircrafts, choose a highly rated military aircraft (such as [[General Dynamics F-16 Fighting Falcon|F-16]]/[[F-15]]) from [[Aircraft#Modern military aircraft|here]], and enable multiplayer damage or install [[Bombable]].
* If you switch to helicopters, it is recommended to fly [[Eurocopter EC130 B4]].

Besides common aircraft, there are also detailed [[Space Shuttle|space shuttles]] available.

=== Scenery ===
It is fascinating to explore the [[scenery]] (or just test the graphics/frame rate) with [[UFO]]. First of all, [[#Configuring rendering and UI|increase your graphics quality]]. If you don't see buildings initially, keep FG open and wait for a while for [[TerraSync]] to finish downloading and for the buildings to appear.
There are plenty of [[Suggested airports|well-developed airports]] and scenery areas. You can also explore the scenery objects on the [https://scenery.flightgear.org/map model map].

=== Multiplayer ===
FlightGear has some multiplayer servers that will let you fly in more lively skies, see [[Howto: Multiplayer]]. There are also [[OpenRadar]] and [[ATC-pie]], standalone programs that will let you be an [[Air traffic control|air traffic controller]].

There is also a [[MPMap|multiplayer map]] that lets you see who is online right now, and even what [[navaids]] are nearby.

=== Menu items ===
For a quick reference about the usage of each menu item in FlightGear, see [[menu]].

=== Addons ===
FlightGear has a lot of third-party [[Addon|addons]] containing enhancements. For beginners, [[Logbook Add-on|Logbook]] and [[Which Runway Add-on|Which Runway]] may be the most useful addons.

== The FlightGear community ==
=== Getting help ===
This page is designed to give the user the essential things they need to know about using FlightGear for the first time. Besides the [[Portal:User|User portal]] of this wiki, there are other pages you may want to read:
*[[Troubleshooting problems]] to help you with the most common issues;
*[[Frequently asked questions]];
...and communication channels that can be used to obtain information or request help:
*The [[FlightGear Manual]], a ''must read'' for beginners;
*{{forum link|text=FlightGear Forum}} and its subforums;
*[[Discord|FlightGear's Discord server]], the quickest way to get help;
*[[FlightGear IRC channel]];
*[[Mailing list|FlightGear users mailing list]], biggest chance to get in contact with core developers;
*Documents bundled with the release package.

=== Customizing FlightGear without compiling it ===
[https://www.flightgear.org/download/ Our website] offers precompiled binaries for download and install on Windows, macOS and Linux. In addition, most Linux distributions provide a packaged version in their repositories.

Although the install is binary, most of FlightGear's systems are open to configuration through [[XML]] files and [[NASAL scripting]]. You are free ''and encouraged'' to make changes to aircraft flight models, scenery, textures, OpenGL [[shader]]s and any other feature you wish to change for your personal satisfaction or to share with other FlightGear users. If this is what you intend to do, take a look at the [[Portal:Developer|Developer portal]].

=== How you can help ===
{{Main article|Volunteer}}
FlightGear is an open source, volunteer based project. That means that whatever you find here comes from passion, spare time and nothing else. This includes the simulator, the scenery, the aircraft, the wiki, the {{forum link|text=forum}} and everything else. Volunteers, in essence ''people that do things'', are fundamental to this project. Without them, it would not make a single step forward. So it is essential that contributors have fun in what they do.

If you plan to contribute to this project, you should take a look at some articles that will give you some hints:
*[[Howto:Understand the FlightGear development process]]
*[[Implementing new features for FlightGear]]
*[[How the FlightGear project works]]

There are never enough people contributing, and the fields where their help would be appreciated are many:
;Testing:
*[[Building FlightGear|Build]] the latest Git code
*[https://gitlab.com/flightgear/flightgear/-/issues File bug reports]
*Running FlightGear via valgrind to track down memory leaks

;Support:
*Help new users with downloading, compiling, installing and running FlightGear ({{forum link|text=on the forum}} or on [[Discord]])
*Provide ideas & suggestions, see: [[Feature Requests / Proposals / Ideas]]
*Help [[Portal:Wiki|clean up this wiki]]
*Help provide new contents for missing wiki pages

;Development:
*core codebase:
**Provide [[Howto:Start core development|source code/data/documentation contributions]]
**Provide [[Bugs|bug fixes]] or new features
*Aircraft development (3D modeling, textures, FDMs, scripting)
*Scenery development (terrain, model, weather)
*Get involved in any of the other FlightGear-affiliated projects

[[Category:FlightGear]]

[[ca:Nou a FlightGear]]
[[de:Neu bei FlightGear]]
[[es:Nuevo en FlightGear]]
[[fi:Uusi_käyttäjä]]
[[fr:Nouveau sur flightgear]]
[[it:Nuovo per FlightGear]]
[[ja:FlightGear入門]]
[[nl:Nieuw bij FlightGear]]
[[pl:Nowy w FlightGear]]
[[pt:Novo no FlightGear]]
[[sr:Novi u FlightGear-u]]
[[th:New to FlightGear]]

New to FlightGear

2026-05-28T05:48:45Z

Servo: /* How you can help */

'''Welcome to [[FlightGear]]!''' Here we will try to get you up in the virtual air in the shortest time possible. We will also introduce you to some of the features of this flight simulator and also a few information on its community.

== Installation and setup ==
=== Hardware requirements ===
For FlightGear to run smoothly, it requires a video card with OpenGL drivers 4.0 or higher. This is usually not a problem, but take a look at the [[hardware recommendations]] to have a better idea.

=== Getting FlightGear ===
You may download the latest files from the [https://www.flightgear.org/download/ FlightGear download] page. Choose the source or binary files appropriate for your particular system. {{Wikipedia|AppImage|AppImage}} binary files for Linux are also available with 2020.3 LTS and later. Most Linux users will find that most distributions have a packaged version of FlightGear (the package name could be <code>fgfs</code> or <code>flightgear</code>.)

Depending on your technical expertise you may choose the [[Git]] development version of FlightGear, which typically has more features and can be required by some of the latest developmental aircraft, but can be unstable and is more complicated to get for non-Windows users. In general, the development version is not advised to the average user, but if you are willing to do some testing there is a nightly build available for [https://www.flightgear.org/download/nightly/ download]. If you are using a Git version controlled copy of FlightGear, you may choose to synchronise your aircraft using the version controlled [[FGAddon|FGAddon aircraft development repository]].

=== Installing on Windows ===
After you downloaded the installer, run it and follow its instructions to install FlightGear.

Defender SmartScreen on Windows may block the installation simply because the binary file is not signed with a key that Microsoft respects. Of course, the key is paid. In this case, we need to click on the inconspicuous "More info" link. Only then will the "Run anyway" button appear. You can safely trust that this is not a dangerous application, as long as you have actually downloaded it from official sources.

If you're using third-party antivirus software for some reason, it may be blocking FlightGear from installing. This isn't something we can control, so it's entirely up to you how you want to handle it.

With the Windows installer, you may choose where to install FlightGear. The [[$FG_ROOT]] directory would be <code><your chosen directory>/data</code>.

=== Installing on macOS ===
Installing FlightGear on macOS is very simple. Just drag and drop the FlightGear icon to the <code>/Applications</code> folder. That is it.

The first time you launch FlightGear, its icon on the Dock bounces for several seconds while loading aircraft and airport info. When the GUI launcher appears, select the aircraft and airport, then click "Fly!" to launch the simulator. You can configure more options using the GUI launcher. See the [http://flightgear.sourceforge.net/manual/next/en/getstart-ench4.html#takeoff-how-to-start-the-program official manual] for more details.

If you would like to launch FlightGear using command-line, launch the Terminal app and type the following.

cd /Applications/FlightGear.app/Contents/MacOS
./fgfs --options.....

The [[$FG_ROOT]] and [[$FG_SCENERY]] are not set on macOS. If you want to specify these variables yourself for command-line use, run the followings on the Terminal app:

FG_ROOT=/Applications/FlightGear.app/Contents/Resources/data
FG_SCENERY=[[$FG_ROOT]]/Scenery

After launching the GUI launcher, you will have the alias to [[$FG_ROOT]] at <code>$HOME/Documents/FlightGear/<version></code> so you can browse the data folder using Finder.

Note: Once you have installed FlightGear, Mac users can locate their [[$FG_ROOT]] folder by opening their applications folder in Finder, right clicking on FlightGear, and clicking "Show Package Contents". This will take you inside the FlightGear folder. You are now able to access all files including Data/Aircraft to [[Howto: Install aircraft#Macintosh OS X|install new aircraft]].

=== Installing from source ===
Main article: [[Building FlightGear]]

=== Getting scenery ===
A limited set of [[scenery]] comes installed with FlightGear. For FlightGear 2024.1 this consists of
* The area surrounding the featured airport for the release which is [[Keflavik_Airport|Keflavik International Airport]] (BIKF)
* The tutorial airport for the [[Cessna_172P|Cessna 172P]] which is [[Hilo_International_Airport|Hilo International Airport]] (PHTO)

In FlightGear, scenery is generally stored in you [[$FG_ROOT]] directory, and is divided into three kinds of data:
* '''Airports''' holds airport data, like runway usage and parking spots.
* '''Objects''' and '''Models''' are the buildings, bridges and radio towers, etc. that represent three-dimensional structures.
* '''Terrain''' represents the contours, elevations and type of ground you fly/taxi over.

The current way of "installing" new scenery is enabling [[TerraSync]], which will automatically download and update any place you visit - even on the fly! If you have a slow Internet connection and/or computer you could instead use a scenery manager, for example [[TerraMaster]]. In addition you can also manually download and install new scenery parts, either the official [[World Scenery]] or custom scenery.

The scenery is also available on the [https://www.flightgear.org/download/mirrors/ mirrors page] of the FlightGear website, and can be installed following [[Howto: Install scenery]]. '''This is recommended for users with weak internet connections or weak computers!'''

Custom scenery is available in many places. For example, on the {{forum link|f=5|text=FlightGear forum}} or within repositories. An internet search should be able to find them. See [[Suggested_custom_scenery|suggested custom scenery]] page for a few recent releases.

FlightGear 2020.3.7 LTS and later added an experimental rollout of 3 dimensional buildings, roads, and objects based on OpenStreetMap data for the entire world to automatically downloaded TerraSync data - see [[OSM2City 1st Worldbuild|1st OSM2City world-build]] notes (March 2021). Some manual downloads of 3d structures for regions or entire countries is available on the [[Areas populated with osm2city scenery|osm2City downloads]] wiki page.

=== Getting aircraft ===
Additional [[aircraft]] can be downloaded and installed through the [[Qt-launcher|launcher]]. Alternatively, you can go to the FlightGear website and navigate to the [http://www.flightgear.org/download/ download page], then choose the aircraft download link that fits your FlightGear version. In addition there are many third party [[hangars]]. For the installation, see [[Howto: Install aircraft]].

== Running FlightGear ==
=== Starting FlightGear ===
The easiest way to start FlightGear is to use the desktop icon. This starts the graphical interface [[FlightGear Qt launcher]] where you can choose aircraft, start position etc. Remember the Qt launcher only has basic options to get you started. A lot of options for graphics, scenery, [[Weather|weather]], [https://www.flightgear.org/tours/simulating-the-ever-changing-scenery/ environment], [[Input_device|input devices]] etc. are available from the [[menu]] inside the simulator.

Many users choose however to start FlightGear directly from the command line. The executable name is <code>fgfs</code> and can be run without options. If it is "not found", it is likely not in your [https://en.wikipedia.org/wiki/PATH_(variable) path]. The location depends on your particular system and choices you made during compile and installation. There is a list of [[Command Line Parameters]] which must be used to change many options, like the aircraft you want. The most important:

fgfs --launcher # opens the FlightGear Qt launcher
fgfs --show-aircraft # displays a list of installed aircraft
fgfs --aircraft=c172p # start FG with the aircraft "c172p" (from the list)

The Qt launcher also lets users add command line parameters for options that are normally changed from the menu inside the simulator, as well as quite advanced options that are only available from the command line (as of August 2020).

=== Configuring rendering and UI ===
[[File:Rendering options 2024.1.png|thumb|View > Rendering Options dialog.]]
If your render quality or framerate is too low, click "View > Rendering Options" to adjust the graphic settings. For newer hardware, it's recommended to set "graphics quality" to high and check "use disk space for faster loading", "animated jetways" and "satellite photoscenery".

If the menu text appears too small on high DPI or large screens, you can manually [[Menubar#How to Change the Default Menubar Font Size|change the menubar font size]] by editing the data file, or simply click "Debug > Cycle GUI Style".

=== Using the keyboard and/or mouse ===
Users with limited access to a [[joystick]] or other controllers sometimes use the keyboard or mouse to control their aircraft. Using the keyboard to fly can be difficult and the mouse is recommended over the keyboard for flying, yet even a cheap joystick would improve the experience so much.

To get help with keyboard commands, with FlightGear running, go to the ''Help'' menu, look under ''Basic Keys'' (for simulator related commands) and ''Common Aircraft Keys'' (for commands universal to all aircraft) and ''Aircraft Help'' (for key commands specific to your aircraft). If the main menu is hidden press {{key press|F10}}. If you come from other simulators, check [[key commands compared to other simulators]] for an overview of the difference between the key commands of that sim and FlightGear.

To use the mouse to fly the aircraft, press {{key press|Tab}} (the cursor should change to a cross) and move the mouse to direct the aircraft. Press {{key press|Tab}} again to look around (cursor should show a two sided arrow), and press {{key press|Tab}} again to return to normal mode, used to click stuff in the cockpit.

For most users lacking a rudder axis control, it’s difficult to manually coordinate [[aileron]] and [[rudder]] movements during a turn. To enable auto-coordination and make flight easier, you may click "Settings", then click the "Show more" button on the right of "General", and finally click "Enable auto-coordination" in the launcher.

=== First time in the cockpit ===
Finding your way around the cockpit can be daunting the first time.

Where is the "virtual cockpit"? Not all FlightGear aircraft come with an interior actually, some research projects may not even come with an exterior model. A 2D panel may display over the 3D cockpit if one exists. You may turn this off through ''Main Menu'' > ''View'' > ''View Options'' and deselecting ''Show 2D panel'' in the ''Display Options'' section, or by pressing {{key press|Shift|P}}. Otherwise, you should be sitting in the virtual cockpit when FlightGear starts, as long as the Cockpit View is selected (if not pressing {{key press|Ctrl|V}} should get you to the pilot view).

You may find it difficult to read some of the displays, dials and gauges on the instrument panel. You can use the ''view'' mode of the mouse (press {{key press|Tab}} until you get a cursor shaped like a double arrow) to pan and the mouse wheel to zoom, or pan with the joystick hat and zoom with {{key press|X}} and {{key press|Shift|X}}.

One of the first steps that many take on entering an unfamiliar cockpit is to press {{key press|Ctrl|C}} to highlight all the "hotspots", that is instrument controls, buttons, knobs, etc. Many aircraft also offer a specific help menu.

Some functions, such as starter or magneto, may be difficult to use or simply lack clickable "hotspots", especially in aircraft models which are in development. In most cases you can go for the equivalent controls on a 2D panel or resort to the keyboard. The keyboard always work according to the assignments listed on the ''Help'' menu, but sometimes these are reassigned by an aircraft or configuration. Again, remember to check all the help dialogs.

=== Starting the engine ===
You are eager to fly, but the engine is off. Well, turning on the engines is not always easy. Some aircraft have an ''autostart'' entry in their custom menu, but here is a general procedure that should work in many cases:

In general to start the engine on a piston-engine type aircraft, you need (after making sure the game is not paused {{key press|p}}):
# Fuel: Some aircraft start the simulation with no fuel. You can add it in ''Equipment'' > ''Fuel and Payload''.
# Correct fuel mixture: This is generally ''rich'', so push the red knob all the way in, or use the key {{key press|m}} to enrich ({{key press|Shift|m}} leans.)
# Magnetos set on ''both'': Turn the key or press {{key press|}}} ''three times'' to move through ''R'', ''L'', ''Both''.
# Throttle: Some engines start better with a little gas.
# Run the starter: Click the ''Start'' position of the key on the panel, or press {{key press|s}}. Hold the starter for sufficient time, even 10 seconds.

Starting all engines in a multi-engine aircraft is similar to the single engine - except you must follow the same start sequence for each and every engine. FlightGear provides a convenient way to do this for all engines at once: Press {{key press|~}} and all the procedure above will work for all the engines. Note though that the default 2D panel is connected to ''only one engine'' and the {{key press|~}} trick might not work. Also, give some gas to be sure that all the engines are on.

These instructions may not work for jet aircraft, helicopters, or other types of aircraft with complex start procedures. Check the instructions in the aircraft help menu (press {{key press|?}}) and/or look at [[Aircraft|the aircraft's article on this wiki]]. In general to start the engine on a jet engine type aircraft, you need to:
# Set cutoff ''ON''
# Engage the starter
# Once the engines spools up to approximately 5% N1, set cutoff ''OFF''
# Disengage the starter once the engine has reached operational speed

== Learning to fly ==
=== FlightGear's Manual ===
FlightGear has an official [https://www.flightgear.org/support/manual/ manual] that covers the basics of flight. As a beginner, you may want to start with [https://flightgear.gitlab.io/getstart/release-{{current release|cr}}/en/HTML/getstart-ench8.html Chapter 8: A Basic Flight Simulator Tutorial].

=== Tutorials ===
Many aircraft have their own interactive [[tutorials|tutorial]]. With tutorials, you can learn to operate particular aircraft but also learn to fly. You can access tutorials by going to ''Main menu'' > ''Help'' > ''Tutorial''. A great place to start is the tutorial for the [[Cessna 172P]] aircraft, commonly used in real life to learn to fly fixed-winged aircraft.

If the tutorial starts without a runway and surrounded by water, your setup of FlightGear is missing the scenery for the airport at which the tutorial was supposed to run. To get scenery see the [[#Getting scenery]] section above.

== Making your first flight ==
=== Realism ===
One of the most frequent questions novice pilots ask about any flight simulator, but more so to FlightGear, is "Why is my aircraft turning left all the time?" Although it could be due to wind gusts crossing the runway, it is more likely due to the [[Understanding Propeller Torque and P-Factor|propeller torque and p-factor]].

In certain other flight simulators, despite marketing slogans to the contrary, some settings are turned down to make the aircraft easier to fly. This reduces effects such as the above. The realism is always turned up in FlightGear.

Here are some of the FlightGear realism points, which may be confusing to first time pilots:
* "Left turning syndrome" for the previously mentioned reasons.
* Compass turning error: A compass, when subjected to the forces of flight, tends to turn in the opposite direction for a brief period before settling on the correct heading. This is not a malfunction (see also the Wikipedia article {{wikipedia|Aircraft compass turns}}).
* The Vertical Speed Indicator (VSI) is also subject to error.
* The [[Horizontal Situation Indicator]] (HSI) is driven by a gyroscope (that is why it is sometimes called a Directional Gyroscope), which is subject to ''gyro drift''. The indicator will drift from its current heading and must be periodically (every ~15 minutes) calibrated to agree with the magnetic compass heading.
* You cannot just cancel a turn or climb by centering the yoke or stick. You must turn or push the stick the other way to get to level and level flight. But even then, the plane will not maintain its altitude or heading by itself. A common mistake is trying to find a hands off yoke position. While with trimming one could leave the plane for a couple of seconds, one must use autopilot or constantly adjust the yoke.

Many forces act on an aircraft in flight as well as on the [[avionics and instruments]] used for control and navigation, and may be counter-intuitive. Pilots must learn to recognize these phenomena and compensate for their effects. ''FlightGear models instrument errors that exist in the real world''.

=== Airports and navigation aids ===
When you first start FlightGear, whether from the command line or the graphical interface of the launchers, you may wonder how to determine what airports are available. The launcher displays a list of airports, but you will not see details such as tower or [[ILS]] frequencies. You will not find a map showing [[VOR]]s and their frequencies. What can you do? See [[Getting aeronautical charts]].

In-sim, there is a map you can use in ''Main Menu'' > ''Equipment'' > ''Map'', which will allow you to see navigation data and the position of airports and aids. For more help with navigation see [[Understanding navigation]].

=== Flying using the autopilot ===
Some aircraft require you to use the [[autopilot]] available from the ''Autopilot'' menu, which is the original FlightGear autopilot. This is a ''generic'' autopilot and as such, many aircraft come with their own ''specific'' autopilot, frequently a model of the real life one.

For aircraft that provide their own autopilot, you should use the autopilot controls available in the virtual cockpit. This means clicking on the instrument panel in the virtual cockpit. The Autopilot menu will be grayed out and unavailable when the aircraft supplies its own autopilot in some aircraft, including the Airbuses and the [[Cessna 172P|C172P]].

The Cessna 172 comes with a [[Bendix/King KAP140 Autopilot]] in its virtual cockpit. You can use both the autopilot device in the cockpit and the [[Autopilot#Autopilot Settings|autopilot settings]] from the menu.

== Advanced ==
=== Flying ===
{{Main article|Aircraft}}

* If you continue to fly light civilian aircraft, [[Cessna 182S]] which is more complex than C172P and [[Piper PA28 Warrior II|PA28]] are good choices.
* If you are interested in flying airlines, [[Airbus A320 family]], Boeing [[Boeing 777|777]]/[[Boeing 787-8 Dreamliner|787]], [[MD-11]] and [[MD-80]] are suggested.
* If you are fascinated by fighter aircrafts, choose a highly rated military aircraft (such as [[General Dynamics F-16 Fighting Falcon|F-16]]/[[F-15]]) from [[Aircraft#Modern military aircraft|here]], and enable multiplayer damage or install [[Bombable]].
* If you switch to helicopters, it is recommended to fly [[Eurocopter EC130 B4]].

Besides common aircraft, there are also detailed [[Space Shuttle|space shuttles]] available.

=== Scenery ===
It is fascinating to explore the [[scenery]] (or just test the graphics/frame rate) with [[UFO]]. First of all, [[#Configuring rendering and UI|increase your graphics quality]]. If you don't see buildings initially, keep FG open and wait for a while for [[TerraSync]] to finish downloading and for the buildings to appear.
There are plenty of [[Suggested airports|well-developed airports]] and scenery areas. You can also explore the scenery objects on the [https://scenery.flightgear.org/map model map].

=== Multiplayer ===
FlightGear has some multiplayer servers that will let you fly in more lively skies, see [[Howto: Multiplayer]]. There are also [[OpenRadar]] and [[ATC-pie]], standalone programs that will let you be an [[Air traffic control|air traffic controller]].

There is also a [[MPMap|multiplayer map]] that lets you see who is online right now, and even what [[navaids]] are nearby.

=== Menu items ===
For a quick reference about the usage of each menu item in FlightGear, see [[menu]].

=== Addons ===
FlightGear has a lot of third-party [[Addon|addons]] containing enhancements. For beginners, [[Logbook Add-on|Logbook]] and [[Which Runway Add-on|Which Runway]] may be the most useful addons.

== The FlightGear community ==
=== Getting help ===
This page is designed to give the user the essential things they need to know about using FlightGear for the first time. Besides the [[Portal:User|User portal]] of this wiki, there are other pages you may want to read:
*[[Troubleshooting problems]] to help you with the most common issues;
*[[Frequently asked questions]];
...and communication channels that can be used to obtain information or request help:
*The [[FlightGear Manual]], a ''must read'' for beginners;
*{{forum link|text=FlightGear Forum}} and its subforums;
*[[Discord|FlightGear's Discord server]], the quickest way to get help;
*[[FlightGear IRC channel]];
*[[Mailing list|FlightGear users mailing list]], biggest chance to get in contact with core developers;
*Documents bundled with the release package.

=== Customizing FlightGear without compiling it ===
[https://www.flightgear.org/download/ Our website] offers precompiled binaries for download and install on Windows, macOS and Linux. In addition, most Linux distributions provide a packaged version in their repositories.

Although the install is binary, most of FlightGear's systems are open to configuration through [[XML]] files and [[NASAL scripting]]. You are free ''and encouraged'' to make changes to aircraft flight models, scenery, textures, OpenGL [[shader]]s and any other feature you wish to change for your personal satisfaction or to share with other FlightGear users. If this is what you intend to do, take a look at the [[Portal:Developer|Developer portal]].

=== How you can help ===
{{Main article|Volunteer}}
FlightGear is an open source, volunteer based project. That means that whatever you find here comes from passion, spare time and nothing else. This includes the simulator, the scenery, the aircraft, the wiki, the {{forum link|text=forum}} and everything else. Volunteers, in essence ''people that do things'', are fundamental to this project. Without them, it would not make a single step forward. So it is essential that contributors have fun in what they do.

If you plan to contribute to this project, you should take a look at some articles that will give you some hints:
*[[Howto:Understand the FlightGear development process]]
*[[Implementing new features for FlightGear]]
*[[How the FlightGear project works]]

There are never enough people contributing, and the fields where their help would be appreciated are many:
;Testing:
*[[Building FlightGear|Build]] the latest Git code
*[https://gitlab.com/flightgear/flightgear/-/issues File bug reports]
*Running FlightGear via valgrind to track down memory leaks

;Support:
*Help new users with downloading, compiling, installing and running FlightGear ({{forum link|text=on the forum}} or on [[Discord]])
*Provide ideas & suggestions, see: [[Feature Requests / Proposals / Ideas]]
*Help [[Portal:Wiki|clean up this wiki]]
*Help provide new contents for missing wiki pages

;Development:
*core codebase:
**Provide [[Howto:Start core development|source code/data/documentation contributions]]
**Provide [[Bugs|bug fixes]] or new features
**Get involved in any of the other FlightGear-affiliated projects
*Aircraft development (3D modeling, textures, FDMs, scripting)
*Scenery development (terrain, model, weather)

[[Category:FlightGear]]

[[ca:Nou a FlightGear]]
[[de:Neu bei FlightGear]]
[[es:Nuevo en FlightGear]]
[[fi:Uusi_käyttäjä]]
[[fr:Nouveau sur flightgear]]
[[it:Nuovo per FlightGear]]
[[ja:FlightGear入門]]
[[nl:Nieuw bij FlightGear]]
[[pl:Nowy w FlightGear]]
[[pt:Novo no FlightGear]]
[[sr:Novi u FlightGear-u]]
[[th:New to FlightGear]]

New to FlightGear

2026-05-28T05:47:56Z

Servo: /* How you can help */ link

'''Welcome to [[FlightGear]]!''' Here we will try to get you up in the virtual air in the shortest time possible. We will also introduce you to some of the features of this flight simulator and also a few information on its community.

== Installation and setup ==
=== Hardware requirements ===
For FlightGear to run smoothly, it requires a video card with OpenGL drivers 4.0 or higher. This is usually not a problem, but take a look at the [[hardware recommendations]] to have a better idea.

=== Getting FlightGear ===
You may download the latest files from the [https://www.flightgear.org/download/ FlightGear download] page. Choose the source or binary files appropriate for your particular system. {{Wikipedia|AppImage|AppImage}} binary files for Linux are also available with 2020.3 LTS and later. Most Linux users will find that most distributions have a packaged version of FlightGear (the package name could be <code>fgfs</code> or <code>flightgear</code>.)

Depending on your technical expertise you may choose the [[Git]] development version of FlightGear, which typically has more features and can be required by some of the latest developmental aircraft, but can be unstable and is more complicated to get for non-Windows users. In general, the development version is not advised to the average user, but if you are willing to do some testing there is a nightly build available for [https://www.flightgear.org/download/nightly/ download]. If you are using a Git version controlled copy of FlightGear, you may choose to synchronise your aircraft using the version controlled [[FGAddon|FGAddon aircraft development repository]].

=== Installing on Windows ===
After you downloaded the installer, run it and follow its instructions to install FlightGear.

Defender SmartScreen on Windows may block the installation simply because the binary file is not signed with a key that Microsoft respects. Of course, the key is paid. In this case, we need to click on the inconspicuous "More info" link. Only then will the "Run anyway" button appear. You can safely trust that this is not a dangerous application, as long as you have actually downloaded it from official sources.

If you're using third-party antivirus software for some reason, it may be blocking FlightGear from installing. This isn't something we can control, so it's entirely up to you how you want to handle it.

With the Windows installer, you may choose where to install FlightGear. The [[$FG_ROOT]] directory would be <code><your chosen directory>/data</code>.

=== Installing on macOS ===
Installing FlightGear on macOS is very simple. Just drag and drop the FlightGear icon to the <code>/Applications</code> folder. That is it.

The first time you launch FlightGear, its icon on the Dock bounces for several seconds while loading aircraft and airport info. When the GUI launcher appears, select the aircraft and airport, then click "Fly!" to launch the simulator. You can configure more options using the GUI launcher. See the [http://flightgear.sourceforge.net/manual/next/en/getstart-ench4.html#takeoff-how-to-start-the-program official manual] for more details.

If you would like to launch FlightGear using command-line, launch the Terminal app and type the following.

cd /Applications/FlightGear.app/Contents/MacOS
./fgfs --options.....

The [[$FG_ROOT]] and [[$FG_SCENERY]] are not set on macOS. If you want to specify these variables yourself for command-line use, run the followings on the Terminal app:

FG_ROOT=/Applications/FlightGear.app/Contents/Resources/data
FG_SCENERY=[[$FG_ROOT]]/Scenery

After launching the GUI launcher, you will have the alias to [[$FG_ROOT]] at <code>$HOME/Documents/FlightGear/<version></code> so you can browse the data folder using Finder.

Note: Once you have installed FlightGear, Mac users can locate their [[$FG_ROOT]] folder by opening their applications folder in Finder, right clicking on FlightGear, and clicking "Show Package Contents". This will take you inside the FlightGear folder. You are now able to access all files including Data/Aircraft to [[Howto: Install aircraft#Macintosh OS X|install new aircraft]].

=== Installing from source ===
Main article: [[Building FlightGear]]

=== Getting scenery ===
A limited set of [[scenery]] comes installed with FlightGear. For FlightGear 2024.1 this consists of
* The area surrounding the featured airport for the release which is [[Keflavik_Airport|Keflavik International Airport]] (BIKF)
* The tutorial airport for the [[Cessna_172P|Cessna 172P]] which is [[Hilo_International_Airport|Hilo International Airport]] (PHTO)

In FlightGear, scenery is generally stored in you [[$FG_ROOT]] directory, and is divided into three kinds of data:
* '''Airports''' holds airport data, like runway usage and parking spots.
* '''Objects''' and '''Models''' are the buildings, bridges and radio towers, etc. that represent three-dimensional structures.
* '''Terrain''' represents the contours, elevations and type of ground you fly/taxi over.

The current way of "installing" new scenery is enabling [[TerraSync]], which will automatically download and update any place you visit - even on the fly! If you have a slow Internet connection and/or computer you could instead use a scenery manager, for example [[TerraMaster]]. In addition you can also manually download and install new scenery parts, either the official [[World Scenery]] or custom scenery.

The scenery is also available on the [https://www.flightgear.org/download/mirrors/ mirrors page] of the FlightGear website, and can be installed following [[Howto: Install scenery]]. '''This is recommended for users with weak internet connections or weak computers!'''

Custom scenery is available in many places. For example, on the {{forum link|f=5|text=FlightGear forum}} or within repositories. An internet search should be able to find them. See [[Suggested_custom_scenery|suggested custom scenery]] page for a few recent releases.

FlightGear 2020.3.7 LTS and later added an experimental rollout of 3 dimensional buildings, roads, and objects based on OpenStreetMap data for the entire world to automatically downloaded TerraSync data - see [[OSM2City 1st Worldbuild|1st OSM2City world-build]] notes (March 2021). Some manual downloads of 3d structures for regions or entire countries is available on the [[Areas populated with osm2city scenery|osm2City downloads]] wiki page.

=== Getting aircraft ===
Additional [[aircraft]] can be downloaded and installed through the [[Qt-launcher|launcher]]. Alternatively, you can go to the FlightGear website and navigate to the [http://www.flightgear.org/download/ download page], then choose the aircraft download link that fits your FlightGear version. In addition there are many third party [[hangars]]. For the installation, see [[Howto: Install aircraft]].

== Running FlightGear ==
=== Starting FlightGear ===
The easiest way to start FlightGear is to use the desktop icon. This starts the graphical interface [[FlightGear Qt launcher]] where you can choose aircraft, start position etc. Remember the Qt launcher only has basic options to get you started. A lot of options for graphics, scenery, [[Weather|weather]], [https://www.flightgear.org/tours/simulating-the-ever-changing-scenery/ environment], [[Input_device|input devices]] etc. are available from the [[menu]] inside the simulator.

Many users choose however to start FlightGear directly from the command line. The executable name is <code>fgfs</code> and can be run without options. If it is "not found", it is likely not in your [https://en.wikipedia.org/wiki/PATH_(variable) path]. The location depends on your particular system and choices you made during compile and installation. There is a list of [[Command Line Parameters]] which must be used to change many options, like the aircraft you want. The most important:

fgfs --launcher # opens the FlightGear Qt launcher
fgfs --show-aircraft # displays a list of installed aircraft
fgfs --aircraft=c172p # start FG with the aircraft "c172p" (from the list)

The Qt launcher also lets users add command line parameters for options that are normally changed from the menu inside the simulator, as well as quite advanced options that are only available from the command line (as of August 2020).

=== Configuring rendering and UI ===
[[File:Rendering options 2024.1.png|thumb|View > Rendering Options dialog.]]
If your render quality or framerate is too low, click "View > Rendering Options" to adjust the graphic settings. For newer hardware, it's recommended to set "graphics quality" to high and check "use disk space for faster loading", "animated jetways" and "satellite photoscenery".

If the menu text appears too small on high DPI or large screens, you can manually [[Menubar#How to Change the Default Menubar Font Size|change the menubar font size]] by editing the data file, or simply click "Debug > Cycle GUI Style".

=== Using the keyboard and/or mouse ===
Users with limited access to a [[joystick]] or other controllers sometimes use the keyboard or mouse to control their aircraft. Using the keyboard to fly can be difficult and the mouse is recommended over the keyboard for flying, yet even a cheap joystick would improve the experience so much.

To get help with keyboard commands, with FlightGear running, go to the ''Help'' menu, look under ''Basic Keys'' (for simulator related commands) and ''Common Aircraft Keys'' (for commands universal to all aircraft) and ''Aircraft Help'' (for key commands specific to your aircraft). If the main menu is hidden press {{key press|F10}}. If you come from other simulators, check [[key commands compared to other simulators]] for an overview of the difference between the key commands of that sim and FlightGear.

To use the mouse to fly the aircraft, press {{key press|Tab}} (the cursor should change to a cross) and move the mouse to direct the aircraft. Press {{key press|Tab}} again to look around (cursor should show a two sided arrow), and press {{key press|Tab}} again to return to normal mode, used to click stuff in the cockpit.

For most users lacking a rudder axis control, it’s difficult to manually coordinate [[aileron]] and [[rudder]] movements during a turn. To enable auto-coordination and make flight easier, you may click "Settings", then click the "Show more" button on the right of "General", and finally click "Enable auto-coordination" in the launcher.

=== First time in the cockpit ===
Finding your way around the cockpit can be daunting the first time.

Where is the "virtual cockpit"? Not all FlightGear aircraft come with an interior actually, some research projects may not even come with an exterior model. A 2D panel may display over the 3D cockpit if one exists. You may turn this off through ''Main Menu'' > ''View'' > ''View Options'' and deselecting ''Show 2D panel'' in the ''Display Options'' section, or by pressing {{key press|Shift|P}}. Otherwise, you should be sitting in the virtual cockpit when FlightGear starts, as long as the Cockpit View is selected (if not pressing {{key press|Ctrl|V}} should get you to the pilot view).

You may find it difficult to read some of the displays, dials and gauges on the instrument panel. You can use the ''view'' mode of the mouse (press {{key press|Tab}} until you get a cursor shaped like a double arrow) to pan and the mouse wheel to zoom, or pan with the joystick hat and zoom with {{key press|X}} and {{key press|Shift|X}}.

One of the first steps that many take on entering an unfamiliar cockpit is to press {{key press|Ctrl|C}} to highlight all the "hotspots", that is instrument controls, buttons, knobs, etc. Many aircraft also offer a specific help menu.

Some functions, such as starter or magneto, may be difficult to use or simply lack clickable "hotspots", especially in aircraft models which are in development. In most cases you can go for the equivalent controls on a 2D panel or resort to the keyboard. The keyboard always work according to the assignments listed on the ''Help'' menu, but sometimes these are reassigned by an aircraft or configuration. Again, remember to check all the help dialogs.

=== Starting the engine ===
You are eager to fly, but the engine is off. Well, turning on the engines is not always easy. Some aircraft have an ''autostart'' entry in their custom menu, but here is a general procedure that should work in many cases:

In general to start the engine on a piston-engine type aircraft, you need (after making sure the game is not paused {{key press|p}}):
# Fuel: Some aircraft start the simulation with no fuel. You can add it in ''Equipment'' > ''Fuel and Payload''.
# Correct fuel mixture: This is generally ''rich'', so push the red knob all the way in, or use the key {{key press|m}} to enrich ({{key press|Shift|m}} leans.)
# Magnetos set on ''both'': Turn the key or press {{key press|}}} ''three times'' to move through ''R'', ''L'', ''Both''.
# Throttle: Some engines start better with a little gas.
# Run the starter: Click the ''Start'' position of the key on the panel, or press {{key press|s}}. Hold the starter for sufficient time, even 10 seconds.

Starting all engines in a multi-engine aircraft is similar to the single engine - except you must follow the same start sequence for each and every engine. FlightGear provides a convenient way to do this for all engines at once: Press {{key press|~}} and all the procedure above will work for all the engines. Note though that the default 2D panel is connected to ''only one engine'' and the {{key press|~}} trick might not work. Also, give some gas to be sure that all the engines are on.

These instructions may not work for jet aircraft, helicopters, or other types of aircraft with complex start procedures. Check the instructions in the aircraft help menu (press {{key press|?}}) and/or look at [[Aircraft|the aircraft's article on this wiki]]. In general to start the engine on a jet engine type aircraft, you need to:
# Set cutoff ''ON''
# Engage the starter
# Once the engines spools up to approximately 5% N1, set cutoff ''OFF''
# Disengage the starter once the engine has reached operational speed

== Learning to fly ==
=== FlightGear's Manual ===
FlightGear has an official [https://www.flightgear.org/support/manual/ manual] that covers the basics of flight. As a beginner, you may want to start with [https://flightgear.gitlab.io/getstart/release-{{current release|cr}}/en/HTML/getstart-ench8.html Chapter 8: A Basic Flight Simulator Tutorial].

=== Tutorials ===
Many aircraft have their own interactive [[tutorials|tutorial]]. With tutorials, you can learn to operate particular aircraft but also learn to fly. You can access tutorials by going to ''Main menu'' > ''Help'' > ''Tutorial''. A great place to start is the tutorial for the [[Cessna 172P]] aircraft, commonly used in real life to learn to fly fixed-winged aircraft.

If the tutorial starts without a runway and surrounded by water, your setup of FlightGear is missing the scenery for the airport at which the tutorial was supposed to run. To get scenery see the [[#Getting scenery]] section above.

== Making your first flight ==
=== Realism ===
One of the most frequent questions novice pilots ask about any flight simulator, but more so to FlightGear, is "Why is my aircraft turning left all the time?" Although it could be due to wind gusts crossing the runway, it is more likely due to the [[Understanding Propeller Torque and P-Factor|propeller torque and p-factor]].

In certain other flight simulators, despite marketing slogans to the contrary, some settings are turned down to make the aircraft easier to fly. This reduces effects such as the above. The realism is always turned up in FlightGear.

Here are some of the FlightGear realism points, which may be confusing to first time pilots:
* "Left turning syndrome" for the previously mentioned reasons.
* Compass turning error: A compass, when subjected to the forces of flight, tends to turn in the opposite direction for a brief period before settling on the correct heading. This is not a malfunction (see also the Wikipedia article {{wikipedia|Aircraft compass turns}}).
* The Vertical Speed Indicator (VSI) is also subject to error.
* The [[Horizontal Situation Indicator]] (HSI) is driven by a gyroscope (that is why it is sometimes called a Directional Gyroscope), which is subject to ''gyro drift''. The indicator will drift from its current heading and must be periodically (every ~15 minutes) calibrated to agree with the magnetic compass heading.
* You cannot just cancel a turn or climb by centering the yoke or stick. You must turn or push the stick the other way to get to level and level flight. But even then, the plane will not maintain its altitude or heading by itself. A common mistake is trying to find a hands off yoke position. While with trimming one could leave the plane for a couple of seconds, one must use autopilot or constantly adjust the yoke.

Many forces act on an aircraft in flight as well as on the [[avionics and instruments]] used for control and navigation, and may be counter-intuitive. Pilots must learn to recognize these phenomena and compensate for their effects. ''FlightGear models instrument errors that exist in the real world''.

=== Airports and navigation aids ===
When you first start FlightGear, whether from the command line or the graphical interface of the launchers, you may wonder how to determine what airports are available. The launcher displays a list of airports, but you will not see details such as tower or [[ILS]] frequencies. You will not find a map showing [[VOR]]s and their frequencies. What can you do? See [[Getting aeronautical charts]].

In-sim, there is a map you can use in ''Main Menu'' > ''Equipment'' > ''Map'', which will allow you to see navigation data and the position of airports and aids. For more help with navigation see [[Understanding navigation]].

=== Flying using the autopilot ===
Some aircraft require you to use the [[autopilot]] available from the ''Autopilot'' menu, which is the original FlightGear autopilot. This is a ''generic'' autopilot and as such, many aircraft come with their own ''specific'' autopilot, frequently a model of the real life one.

For aircraft that provide their own autopilot, you should use the autopilot controls available in the virtual cockpit. This means clicking on the instrument panel in the virtual cockpit. The Autopilot menu will be grayed out and unavailable when the aircraft supplies its own autopilot in some aircraft, including the Airbuses and the [[Cessna 172P|C172P]].

The Cessna 172 comes with a [[Bendix/King KAP140 Autopilot]] in its virtual cockpit. You can use both the autopilot device in the cockpit and the [[Autopilot#Autopilot Settings|autopilot settings]] from the menu.

== Advanced ==
=== Flying ===
{{Main article|Aircraft}}

* If you continue to fly light civilian aircraft, [[Cessna 182S]] which is more complex than C172P and [[Piper PA28 Warrior II|PA28]] are good choices.
* If you are interested in flying airlines, [[Airbus A320 family]], Boeing [[Boeing 777|777]]/[[Boeing 787-8 Dreamliner|787]], [[MD-11]] and [[MD-80]] are suggested.
* If you are fascinated by fighter aircrafts, choose a highly rated military aircraft (such as [[General Dynamics F-16 Fighting Falcon|F-16]]/[[F-15]]) from [[Aircraft#Modern military aircraft|here]], and enable multiplayer damage or install [[Bombable]].
* If you switch to helicopters, it is recommended to fly [[Eurocopter EC130 B4]].

Besides common aircraft, there are also detailed [[Space Shuttle|space shuttles]] available.

=== Scenery ===
It is fascinating to explore the [[scenery]] (or just test the graphics/frame rate) with [[UFO]]. First of all, [[#Configuring rendering and UI|increase your graphics quality]]. If you don't see buildings initially, keep FG open and wait for a while for [[TerraSync]] to finish downloading and for the buildings to appear.
There are plenty of [[Suggested airports|well-developed airports]] and scenery areas. You can also explore the scenery objects on the [https://scenery.flightgear.org/map model map].

=== Multiplayer ===
FlightGear has some multiplayer servers that will let you fly in more lively skies, see [[Howto: Multiplayer]]. There are also [[OpenRadar]] and [[ATC-pie]], standalone programs that will let you be an [[Air traffic control|air traffic controller]].

There is also a [[MPMap|multiplayer map]] that lets you see who is online right now, and even what [[navaids]] are nearby.

=== Menu items ===
For a quick reference about the usage of each menu item in FlightGear, see [[menu]].

=== Addons ===
FlightGear has a lot of third-party [[Addon|addons]] containing enhancements. For beginners, [[Logbook Add-on|Logbook]] and [[Which Runway Add-on|Which Runway]] may be the most useful addons.

== The FlightGear community ==
=== Getting help ===
This page is designed to give the user the essential things they need to know about using FlightGear for the first time. Besides the [[Portal:User|User portal]] of this wiki, there are other pages you may want to read:
*[[Troubleshooting problems]] to help you with the most common issues;
*[[Frequently asked questions]];
...and communication channels that can be used to obtain information or request help:
*The [[FlightGear Manual]], a ''must read'' for beginners;
*{{forum link|text=FlightGear Forum}} and its subforums;
*[[Discord|FlightGear's Discord server]], the quickest way to get help;
*[[FlightGear IRC channel]];
*[[Mailing list|FlightGear users mailing list]], biggest chance to get in contact with core developers;
*Documents bundled with the release package.

=== Customizing FlightGear without compiling it ===
[https://www.flightgear.org/download/ Our website] offers precompiled binaries for download and install on Windows, macOS and Linux. In addition, most Linux distributions provide a packaged version in their repositories.

Although the install is binary, most of FlightGear's systems are open to configuration through [[XML]] files and [[NASAL scripting]]. You are free ''and encouraged'' to make changes to aircraft flight models, scenery, textures, OpenGL [[shader]]s and any other feature you wish to change for your personal satisfaction or to share with other FlightGear users. If this is what you intend to do, take a look at the [[Portal:Developer|Developer portal]].

=== How you can help ===
{{Main article|Volunteer}}
FlightGear is an open source, volunteer based project. That means that whatever you find here comes from passion, spare time and nothing else. This includes the simulator, the scenery, the aircraft, the wiki, the {{forum link|text=forum}} and everything else. Volunteers, in essence ''people that do things'', are fundamental to this project. Without them, it would not make a single step forward. So it is essential that contributors have fun in what they do.

If you plan to contribute to this project, you should take a look at some articles that will give you some hints:
*[[Howto:Understand the FlightGear development process]]
*[[Implementing new features for FlightGear]]
*[[How the FlightGear project works]]

There are never enough people contributing, and the fields where their help would be appreciated are many:
;Testing:
*[[Building FlightGear|Build]] the latest Git code
*[https://gitlab.com/flightgear/flightgear/-/issues File bug reports]
*Running FlightGear via valgrind to track down memory leaks

;Support:
*Help new users with downloading, compiling, installing and running FlightGear ({{forum link|text=on the forum}} or on [[Discord]])
*Provide ideas & suggestions, see: [[Feature Requests / Proposals / Ideas]]
*Help [[Portal:Wiki|clean up this wiki]]
*Help provide new contents for missing wiki pages

;Development:
*C/C++ Coding:
**Provide [[Howto:Start core development|source code/data/documentation contributions]]
**Provide [[Bugs|bug fixes]] or new features
**Get involved in any of the other FlightGear-affiliated projects
*Aircraft development (3D modeling, textures, FDMs, scripting)
*Scenery development (terrain, model, weather)

[[Category:FlightGear]]

[[ca:Nou a FlightGear]]
[[de:Neu bei FlightGear]]
[[es:Nuevo en FlightGear]]
[[fi:Uusi_käyttäjä]]
[[fr:Nouveau sur flightgear]]
[[it:Nuovo per FlightGear]]
[[ja:FlightGear入門]]
[[nl:Nieuw bij FlightGear]]
[[pl:Nowy w FlightGear]]
[[pt:Novo no FlightGear]]
[[sr:Novi u FlightGear-u]]
[[th:New to FlightGear]]

Howto:Start core development

2026-05-28T05:25:05Z

Servo: /* Fork the Repository */

{{note|You'll need to familiarize yourself with setting up a development environment and building FlightGear in order to contribute code. See
[https://docs.flightgear.org/contributors-guide/guidelines/building.html Developing on the codebase] if you do not already
have a working setup. Some understanding of ''Git'' will also be
necessary; this free, online [https://git-scm.com/book/en/v2 Git book] is quite useful.}}

The most efficient way to contribute changes to the FlightGear code base is to
file a merge request (this doesn't apply to [[aircraft]] or [[addon|add-ons]], which are
managed differently). We'll first give an overview of the process including
its main prerequisites, then explain each step in more detail.

== Overview ==

The basic workflow for first-time contributors to a FlightGear Git repository
is:

#. '''Fork the repository.'''
Fork the relevant FlightGear repository into your GitLab account. You will
need to know which repository contains the code you are trying to change.
Familiarizing yourself with the code base and the purpose of each
repository is strongly recommended.

#. '''Set up a local clone.'''
Prepare a clone of the repository on your hard disk that is convenient for
getting updates from the upstream repository and pushing changes to your
fork. You'll also use this clone to perform test builds.

#. '''Build the project.'''
If you haven't already done so, this will be the time to set up your
development environment so that you can build FlightGear.

#. '''Create a new branch.'''
Create a branch on your clone to isolate your changes. Use a clear and
descriptive name for your branch (e.g. <code>fix-menubar-typo</code> or
<code>add-new-joystick-configs</code>).

#. '''Make changes.'''
Make the changes on your branch in small, focused commits. Each commit
should be self-contained and represent one logical change.

#. '''Test and double-check.'''
Before you submit your changes to the FlightGear team for review,
double-check your work. Ensure that your code builds and that tests pass.

#. '''Rebase and push.'''
Check if the upstream repository was updated in the meantime. If so, rebase
your work on its latest state and perform a final test run to make sure
everything still works fine.

#. '''Submit a merge request.'''
Open a merge request (MR) to propose your changes for review. Be sure to
use the ''Merge Request Template'' to provide necessary context for
reviewers. Feel free to ask on the developer mailing list if you're unsure
whom to add as a reviewer.

#. '''Code review.'''
Once you have created a merge request, other developers will review your
work, give feedback, and sometimes request changes be made. This is a
crucial part of the development process, as it helps reduce bugs and
improves code quality.

#. '''Clean up.'''
If your merge request was applied, pull your changes from the upstream
branch and delete the local branch you created for the merge request.

In order to present these steps in more detail, we'll now assume that you
intend to make your first contribution to the [https://gitlab.com/flightgear/simgear SimGear repository] (and thus,
that you haven't already forked it). Except for the target branch name which
may differ, the process would be the same for any Git repository of the
FlightGear project.

== Fork the Repository ==

For what follows, you'll need to create a [https://gitlab.com/ GitLab] account if you don't already
have one. Once you are logged into your account, go to the repository home
page ([https://gitlab.com/flightgear/simgear here] in our example) and click on the
Fork button as shown in
; after
filling some information, this will lead to the creation of a copy of the
upstream repository in your own GitLab namespace under
<code><nowiki>https://gitlab.com/YourUserName/</nowiki></code>.

[[File:01_forking.png|thumb|alt=how to find the Fork button on the main page of the repository|Forking the upstream repository]]

Once you've clicked on the button, a new page is loaded as shown in
. The ''Project name'' will be prominent but it's
only a label—choose it as you wish (“My SimGear fork” in the example). For the
''Project URL'', you'll want to select your GitLab username after the initial
portion <code><nowiki>https://gitlab.com/</nowiki></code>.

[[File:02 project name, URL, slug.png|thumb|alt=dialog that allows one to enter the project name, URL and slug for a fork|Entering the project name, URL and slug for your fork]]

The ''Project slug'' is the final part of the base URL for the fork you're about
to create; let's choose <code>flightgear-simgear</code> so that all your forks of
repositories of the FlightGear project are named <code>flightgear-something</code>.
This way, they will be easy to distinguish from non-FlightGear repositories
you might want to publish under <code><nowiki>https://gitlab.com/YourUserName/</nowiki></code>. Beware
that if you modify the ''Project name'', the GitLab user interface automatically
modifies the ''Project slug''; so, better fill them in this order: ''Project name''
then ''Project slug''.

There are a few fields left to enter. If you choose to include only the
default branch, you'll save a little amount of space but might have to fetch
other upstream branches later. Give your fork public visiblity so that reviews
can take place. When ready, click on the Fork project button to
actually create your fork of the upstream repository.



== Set Up a Local Clone ==

Since we want to pull updates from the upstream repository, it is convenient
to clone it to your hard disk and modify the clone so that pushes go by
default to your fork (which is online under
<code><nowiki>https://gitlab.com/YourUserName/</nowiki></code>). Cloning the upstream SimGear repository
can be done with:

<syntaxhighlight lang="bash">
git clone https://gitlab.com/flightgear/simgear.git
</syntaxhighlight>

{{tip|If you use <code>download_and_compile.sh</code> and it manages the repository you
want to contribute to (this is obviously the case for SimGear), there is
no need to create a new clone: you can simply use the repository clone it
created on your disk.}}

Now, let's add a Git remote that points to your fork of the upstream
repository. We configure this remote so that pushing to it uses <abbr title="Secure Shell">SSH</abbr> authentication. We also configure your repository clone so
that pushes go to your fork by default.

<syntaxhighlight lang="bash">
git remote add flo https://gitlab.com/frougon/flightgear-simgear.git
git remote set-url --push flo git@gitlab.com:frougon/flightgear-simgear.git
git config remote.pushDefault flo
</syntaxhighlight>

In the above commands, replace <code>flo</code> (name of the created remote) with an
appropriate name of your choice; also replace <code>frougon</code> with your GitLab
username.

== Build the Project ==

Make sure you can build FlightGear using the repository clone set up in the
previous step and that the resulting executables run normally. This way,
you'll be able to properly test any changes you later make in this clone.

{{note|The following steps will have to be repeated for each
“self-contained changeset” that you intend to contribute.}}

== Create a New Branch ==

Create a branch based on <code>origin/next</code> that tracks <code>origin/next</code> and make
sure it is up-to-date. Instead of <code>new-branch-name</code>, choose a name that
makes it clear what the changes in the created branch are supposed to do.

<syntaxhighlight lang="bash">
git checkout -b new-branch-name origin/next
git pull
</syntaxhighlight>

{{note|Here, <code>origin</code> is a remote that points to the upstream repository
you cloned from, and <code>next</code> is the name of the development branch
in the [https://gitlab.com/flightgear/simgear SimGear repository] (this is also the case for [https://gitlab.com/flightgear/flightgear FlightGear] and [https://gitlab.com/flightgear/fgdata FGData]). If
you were to contribute to a different repository such as [https://gitlab.com/flightgear/documentation FlightGear documentation], the branch
to base your work on might have a different name (e.g., <code>main</code>).}}

== Make Changes ==

Commit the desired changes to the branch you created in the previous step. If
you need help with <code>git</code>, this online [https://git-scm.com/book/en/v2 book] is a great resource.

Each commit message should start with a single, not too long summary line (no
more than 72—80 characters if possible), then a blank line, then normal
explanations. Example commit message:

<pre>
HID: allow sending output reports from Nasal

- make watched properties only react on a value change
- refactor the larger usage enums to their own file
</pre>

Like here, it is useful when the beginning of the first line is short and
makes it clear to readers which part of the code (subsystem, class, etc.) is
affected by the changes.

== Test and Double-check ==

Rebuild FlightGear with your changes, carefully test. Build the FlightGear
test suite and verify that the tests still pass. This can be done by running
<code>make test_suite</code> or <code>ninja test_suite</code> from the FlightGear build directory
(not the source repository!).

Use commands like:

* <code>git status</code> to check the state of your working directory and repository;
* <code>git log -p</code> to proofread your commit diffs and messages;
* <code>git commit --amend</code> to modify the most recent commit on the branch;
* <code>git rebase -i <ref></code> to modify commits located further
in the ancestry graph (namely, descendants of commit <code><ref></code>; see the
<code>git rebase</code> manual page for explanations).

The <code>gitk</code> program is not essential but can be nice for examining
commits and visualizing the commit graph. If <code>gitk</code> appears to see
local changes that really aren't there, run <code>git status</code> then rerun
<code>gitk</code>.

The <code>pre-commit</code> and <code>clang-format</code> programs are useful to run code quality
checks and apply the project formatting rules. Some of the configured
<code>pre-commit</code> hooks will for instance check for common mistakes
including typos, mixed whitespace or line endings, and so on. If you've
[https://pre-commit.com/#3-install-the-git-hook-scripts installed] the
<code>pre-commit</code> hooks in your repository clone, <code>pre-commit</code>
will be automatically run every time you commit.

{{note|In most cases, the GitLab CI (Continuous Integration) runs
the <code>pre-commit</code> and <code>clang-format</code> checks as part
of the automatic verifications that need to pass, before a merge request can be applied.}}

== Rebase and Push ==

If the upstream branch you started from has changed in the meantime, your work
needs to be rebased on top of its latest state. This can be done with the
following command:

<syntaxhighlight lang="bash">
git pull --rebase
</syntaxhighlight>

In case someone was working on the same files as you, this may trigger
conflicts (so it's a good idea to first announce what you're going to work on
in order to minimize friction and benefit from the insight of experienced
people). Conflicts don't happen very often and it's not the end of the world
when they do. Again, this [https://git-scm.com/book/en/v2 Git book] is a very useful resource in such cases.

If the rebasing did grab upstream changes, perform a final build-and-test run
to be sure everything works fine. Finally, push the branch to your fork:

<syntaxhighlight lang="bash">
git push
</syntaxhighlight>

With no additional arguments, this pushes the current branch to the remote
specified with the <code>remote.pushDefault</code> setting, i.e. to your clone if you
followed the [[#section-Set-up-a-local-clone|above]] instructions. Once
the push is successful, <code>git</code> will show a URL; following it will start the next step.

== Submit a Merge Request ==

The web page opened from the URL output by <code>git</code> when you pushed to
your fork allows to create a merge request from the branch that was pushed.
From this page, select the proper target branch: for development code in
[https://gitlab.com/flightgear/simgear SimGear], that would be <code>next</code>. Select yourself as
an ''assignee'' (meaning that ''you'' are going to shape the merge request into
its final form). Select one or more reviewers to look at it—you can ask on the
[https://sourceforge.net/p/flightgear/mailman/flightgear-devel/ flightgear-devel mailing-list] if unsure, or just leave the field as
''Unassigned''. Don't worry too much about the milestone ''(a priori,'' <code>next</code>
should do unless the merge request is specifically a fix for a release
branch). Select applicable labels, etc.

Regarding the ''Delete source branch when merge request is accepted'' option, we
advise you to make sure it is enabled, otherwise your fork will soon have tons
of branches. What this option does is the following: when the branch from your
merge request is merged into the upstream branch, GitLab will automatically
delete the merge request branch (that you pushed) from your fork. This happens
online at GitLab, not in your local clone. Thus, even after this
occurs, the branch will still be present locally in your clone, until you
delete it yourself (cf. [[#local-branch-removal|below]]).

Finally, the ''Squash commits when merge request is accepted'' option can be
used in case you pushed several commits but would rather have them coalesced
into a single one when the merge request is applied. This is something that
can be done locally using <code>git</code> before pushing (in particular, with
<code>git rebase -i</code>), however the option is still useful in case commits are added
to the merge request after the initial push, be it by you or by reviewers.

== Code Review ==

After a few minutes, hours or days, you'll receive feedback from the
FlightGear developers about your merge request. Reviewing merge requests
requires expertise and takes some time, so please carefully read the remarks
and suggestions, follow up on the questions and requests for changes.

== Clean Up ==

Once the branch is merged, update the local branch of your clone that tracks
the upstream branch your merge request went to (this is the <code>next</code> branch in
our SimGear example):

<syntaxhighlight lang="bash">
git checkout next
git pull --rebase
</syntaxhighlight>

(Normally, the <code>--rebase</code> option shouldn't be necessary here as you
shouldn't have any local commits on top of the upstream ones in this branch,
however it doesn't hurt and can make things easier if you've been forgetful.)



You can now delete the local branch you created earlier to avoid cluttering
your local clone with legacy, unneeded branches:

<syntaxhighlight lang="bash">
git branch -d new-branch-name
</syntaxhighlight>

In case this branch hasn't been merged ''exactly as is'' into the upstream
branch (same commit contents and metadata), <code>git</code> will warn and
refuse to delete the branch unless you insist using <code>-D</code>. If this happens,
you'll have to evaluate yourself (by using <code>git log -p</code>, by comparing
files...) if deleting your local branch <code>new-branch-name</code> is really the
right thing to do. In the likely case that what was merged is a strict
improvement over what you have in <code>new-branch-name</code>, then deleting is the
way to go.

{{tip|If you really, really messed up and deleted the branch before
realizing that it was a mistake, <code>git reflog</code> is likely to save you:
among other things, it shows the commit hashes corresponding to previous
positions of the tips of various branches. As long as no garbage collection occurred in the meantime (<code>git gc</code>), the commit
hashes are all you need to restore “lost commits”: simply create a
branch or tag from the desired commit (before doing do, you may want
to use <code>git show <hash></code> to see the commit for a given hash, or <code>git log <hash></code> to examine its ancestry).}}

From time to time, you may also want to run <code>git fetch -p flo</code> (replace
<code>flo</code> with the name of a remote that points to your fork,
cf. [[#section-Set-up-a-local-clone]]). This removes the <code>flo/...</code>
branches from your local clone that have been deleted from your fork at GitLab
due to the ''Delete source branch when merge request is accepted'' option on the
merge request page (note that for instance, <code>flo/new-branch-name</code> and
<code>new-branch-name</code> are different branches in your clone; they'll both clutter
the display when using <code>git log</code> or <code>gitk</code> until you delete them).

== External links ==
* [https://docs.flightgear.org/contributors-guide/core-developers-guide/git-workflow.html How to Contribute Code]
* [https://git-scm.com/book/en/v2 The Git book]

[[Category:Howto]]
[[Category:Core developer documentation]]
[[ru:Howto:Приступая к разработке ядра]]
[[Category:Hackathon Materials]]

File:01 forking.png

2026-05-28T05:23:41Z

Servo: Uploaded a work by fg contributors from https://docs.flightgear.org/contributors-guide/core-developers-guide/git-workflow.html with UploadWizard

=={{int:filedesc}}==
{{Information
|description={{en|1=01 forking}}
|date=2026-05-28
|source=https://docs.flightgear.org/contributors-guide/core-developers-guide/git-workflow.html
|author=fg contributors
|permission=
|other versions=
}}

=={{int:license-header}}==
{{subst:Custom license marker added by UW}}
GPLv2+

File:02 project name, URL, slug.png

2026-05-28T05:22:49Z

Servo: Uploaded a work by fg contributors from https://docs.flightgear.org/contributors-guide/core-developers-guide/git-workflow.html with UploadWizard

=={{int:filedesc}}==
{{Information
|description={{en|1=02 project name, URL, slug}}
|date=2026-05-28
|source=https://docs.flightgear.org/contributors-guide/core-developers-guide/git-workflow.html
|author=fg contributors
|permission=
|other versions=
}}

=={{int:license-header}}==
{{subst:Custom license marker added by UW}}
GPLv2+

Template:Volunteer Intro

2026-05-28T05:14:01Z

Servo: typo

Many people think that contributing to the [[FlightGear]] project requires writing C++ code or doing [[Portal:Developer/3D Modelers|3D modeling]] and that it takes lots of time, and therefore feel that they cannot contribute directly. Not so. There's a whole variety of ways to make a valuable and satisfying contribution to FlightGear without being a developer.

The '''[[Volunteer]]''' page is intended to provide a starting point for those wanting to contribute, but who don't know how. Of course, these are just suggestions. So if you have already a specific idea in mind, please do get in touch with the community to ask for feedback, using the [https://gitlab.com/groups/flightgear/-/issues issue tracker], [[mailing list]]s, {{forum link|text=forum}} or the [[Discord]] (chat).

Remember that work in non-development areas will be appreciated as much as developer contributions (or more!), because generally more visible to the end user.

If you'd like to learn more about getting your own ideas and features into FlightGear, check out [[Implementing new features for FlightGear]].

If you are '''contributing to the core simulator''', or an aircraft in the '''master repository''', you should be part of the FlightGear-devel mailing list, which is the primary point of contact for all discussions regarding the development of the simulator. You may want to check out also [[Howto: Understand the FlightGear development process]] and [[Howto: Starting core development]].<noinclude>
[[Category:Undocumented templates]]
</noinclude>

Template:Volunteer Intro

2026-05-28T05:13:26Z

Servo: add issue tracker

Many people think that contributing to the [[FlightGear]] project requires writing C++ code or doing [[Portal:Developer/3D Modelers|3D modeling]] and that it takes lots of time, and therefore feel that they cannot contribute directly. Not so. There's a whole variety of ways to make a valuable and satisfying contribution to FlightGear without being a developer.

The '''[[Volunteer]]''' page is intended to provide a starting point for those wanting to contribute, but who don't know how. Of course, these are just suggestions. So if you have already a specific idea in mind, please do get in touch with the community to ask for feedback, using the [[https://gitlab.com/groups/flightgear/-/issues issue tracker], [[mailing list]]s, {{forum link|text=forum}} or the [[Discord]] (chat).

Remember that work in non-development areas will be appreciated as much as developer contributions (or more!), because generally more visible to the end user.

If you'd like to learn more about getting your own ideas and features into FlightGear, check out [[Implementing new features for FlightGear]].

If you are '''contributing to the core simulator''', or an aircraft in the '''master repository''', you should be part of the FlightGear-devel mailing list, which is the primary point of contact for all discussions regarding the development of the simulator. You may want to check out also [[Howto: Understand the FlightGear development process]] and [[Howto: Starting core development]].<noinclude>
[[Category:Undocumented templates]]
</noinclude>

Volunteer

2026-05-28T05:13:15Z

Servo: removed cppbind ideas

{{Volunteer Intro}}

== Media ==
=== Screenshots ===
Another easy way for getting started contributing is to create nice FlightGear screenshots. You can upload these to the wiki where they can then be used to illustrate articles and to highlight articles via the [[:Category:Picture of the week|picture of the week]] on the main page.

[[Howto: Make nice screenshots]] provides some tips on how to create stunning shots, while [[Help:Upload]] discusses how to upload screenshots to the wiki.

=== Videos ===
Many users like to capture their flights in FlightGear as a video, YouTube for example is an excellent way for sharing such videos with fellow FlightGear users. YouTube videos can also be directly embedded in forum postings and wiki articles.

=== Screencasts (video tutorials) ===
Creating FlightGear related video tutorials is another excellent way for getting started contributing.

== Documentation ==

{{forum|72|FlightGear Documentation}}

=== FAQ-Maintainers ===
The FlightGear project is looking for people who are willing to help maintain the FAQ which, given the constant development of the project, is chronically out of date. If you you would like to get involved, follow the {{forum link|text=forum}} to stay current on the latest news, problems, and of course on what questions are asked more frequently, and simply start editing the [[FAQ|wiki FAQ]].

=== Maintaining the wiki ===
You can easily [[Special:UserLogin|register an account]] and help [[Portal:Wiki|improve the wiki]], and provide your help in reviewing articles, fixing their look and readability, updating them and adding what you think is missing, for example many articles could be greatly improved just by adding a handful of relevant screenshots for illustration purposes. Proof reading of existing articles is also greatly appreciated.

Registering takes less than 10 seconds. After registration, you'll have to confirm your registration by clicking on the link sent to you by email.

=== Translating the wiki and FlightGear ===
You can also help localize the wiki by [[Help:Translate|translating]] important articles into different languages. Please see the [[translation requests]].

Also, FlightGear itself can be easily translated by updating the files in [[$FG_ROOT]]/Translations. For details please see [[Howto: Translate FlightGear|Translating FlightGear]].

=== Wiki article writers ===
Various aspects of FlightGear are currently not yet sufficiently documented, and available documentation is often not really suitable to be used by non-developers. This results in users being unaware of the wide range of features and possibilities that FlightGear supports already.

As an "article writer" you should be able to document your own experiences with FlightGear in a clear and concise style, so that others can easily follow your instructions in order to make use of the less known features of FlightGear. These articles don't need to be very comprehensive, they shall only provide users with easy to follow instructions on how to achieve something, and possibly some caveats and hints.

* [[:Category:Volunteer: Writing]]

=== Contributing to "The Manual" ===
The wiki is not the only documentation here, of course. FlightGear comes with a set of illustrated documentation, notably [[FlightGear Manual|"The Manual"]]. If you are a skilled writer and a little bit familiar with LaTex, your help would be really welcome. More on this at "The Manual" wiki page. You'll find the source code in the {{getstart source|text=Getstart repository}}.

=== Documentation Editors/Reviewers ===
{{Main article|Howto:Write a FlightGear Review}}
The documentation that comes with FlightGear base package is lacking, terse or simply inaccurate (outdated), due to the advances in FlightGear's code. You should check the current documentation and identify areas for improvement, by directly making corresponding suggestions for augmentations, or even writing new help documents altogether, while staying current with the mailing list.

Smaller corrections shall be sent by email to the developer mailing list, preferably in unified diff format (for patch to work). Alternatively, small text files can also be sent directly to the mailing list, more complex modifications should be only made available by uploading them to a webpage and linking to the corresponding files from your emails. Please consider trying [http://kdiff3.sourceforge.net/ KDiff3], a GUI frontend to the diff and patch utilities that works on several platforms (also Windows).

If you intend to redo a major part of the current documentation, first discuss this with the developers, to avoid documenting code that may also be under development or deprecation.

== Development ==
=== Creating interactive tutorials ===
FlightGear has a built-in [[Tutorials|tutorial]] system that is based on its scripting language [[Nasal]], this system is very flexible and can be used for creating interactive tutorials (or even missions) for use in FlightGear itself, in other words these tutorials run directly in the simulator.

Creating new tutorials, or updating and improving existing ones, is another great way for getting more familiar with FlightGear. For details please see [[Tutorials]].

=== Providing patches for aircraft's -set.xml status fields ===
One way you could easily contribute would be to submit patches to HEAD setting the "status" flag on each aircraft accurately. While it will require learning a bit about SCM, and XML, that would be a fine contribution. For a details on how the status should be arrived at see [[Aircraft status indication]].

=== Creating Scenery Models ===
The FlightGear project maintains a steadily growing repository of [http://scenemodels.flightgear.org 3D models] for adding some eye-candy to the scenery. The world has always enough room left for your [http://scenemodels.flightgear.org/contribute.php contribution]. Please take the time to investigate what is already there and enjoy populating your favourite area.

Note that you don't have to create any models yourself. You can simply [[Howto: Place 3D objects with the UFO|place existing models using the UFO]]. For example, placing objects in the scenery with the [[UFO]] and submitting them to the database is pretty straightforward and takes very little time. Even an hour spent doing this makes a difference.

If anyway you'd like to [[Modeling - Getting Started|test your modeling skills]], here some suggestions:
* We need people to go out and take good pictures of all the buildings at their local airports, build models, and create textures (that could be different people for each task).
* We need people to start modelling identifiable human-made landmarks like bridges, stadiums, and major buildings. Around the San Francisco Bay area, bridges are especially important. Once you have identified some buildings or objects you would like to have (Aircraft carriers, fuel bowsers, cars, towers, ...) you will need to check out the tools for creating and placing these objects.

It would be helpful if people would model the area they are interested in. Generally contributions are going to be from FlightGear users who find scenery lacking in some area and choose to improve it. You are encouraged to research your own area for airport, navaid and scenery information, to contribute the data or dive right in to airport and scenery design.

=== Making airports ===
Sometimes you'd like to populate your favourite airport with objects, but you find it has a wrong layout or that it doesn't exist at all! So, you'll want to [[Howto:Make an airport|make or improve that layout]], which can be done with [[WED]]. Remember that we're maintaining an open (GPL) airport database in common with X-Plane simulator.

Other than just fix the look, you might want to add interactive details like [[AI Traffic]] and maybe update navaids and comm frequencies. We need people to go over paper lists and airport diagrams for countries that don't publish air navigation data free online (i.e. almost everyone but the U.S.) and fill in the blanks in our navaid and airport databases (''note: especially for the last part, see the website of the current maintainer: [https://gateway.x-plane.com/ X-Plane Scenery Gateway]''.)

To be sure the airport you're interested in is not already being worked on, check the [[Airports under construction]] article. Also, note that since we switched to a newer format for the airport database, there are many airports that need to be converted from the older (810) format to the newer (850). All the info is in [[Howto:Make an airport]].

=== Contributing to the scenery terrain ===
We need people to collect geodata to give us more accurate roads, rivers, etc., especially outside the U.S. and Europe. Note that since we're now allowed to use OpenStreetMap data for this, you might consider contributing to that project too. With time, more and more features will be imported from OSM, beginning with roads and rails, and going on with power lines and antennas and whatnot.

The first step into this is learning how to [[Using TerraGear|use TerraGear]]. Remember that all the data you plan to use must be GPL compatible. You might also consider editing some of that source data and contribute it to the Scenery Project that would make good use of it!

=== Core development ===
{{Main article|Howto:Start core development}}
If you actually happen to be a C++ programmer and know Git, consider contributing to [[Howto:Start core development|core development]].

== Other ==
=== Submitting bugs to the Bug Tracker ===
Bugs can be reported to {{tickets|the issue tracker}} (select the respective project, or <code>flightgear</code> if unsure). Reporting bugs accurately helps make bug fixing significantly easier for the developers. Another thing that is very helpful, is reviewing posted bug reports and see if you can reproduce/confirm them on your system.

=== Artwork Creators/Contributors ===
FlightGear itself would not be possible without the contribution of various types of artwork:
* Aircraft developers need photographs, images and sounds to realistically model a particular aircraft.
* The splash screen displayed when loading the simulator can be personalized, and you can [[Howto: Create custom splash screens|create one for your favourite aircraft]].
* Sound recordings of aircraft are also very valuable - particularly engine sounds for unusual aircraft.

In general, you can find requests and post your offers of this kind in the Developers forum, but you can also browse [[:Category:Aircraft by status|existing aircraft projects]] and see if there's anything you'd like to improve.

=== Pre-Release Testers ===
Prior to a release, release candidates are provided to the community. By directly providing feedback about your experiences with FlightGear's development code, you will become a crucial part of the development process and you will basically serve as quality control for FlightGear, your experiences will determine whether FlightGear's development code is ready for a next official release or not. See the [[Release plan]] to find out when release candidates will be distributed.

Note: If you are interested in actually doing development for FlightGear, make sure to check out the [[Portal:Developer|Developer section]].

=== Hosting a multiplayer server ===
If you have access to an Unix based server, another good opportunity for contributing would be to set up a multiplayer server for use with FlightGear, for details please check out [[Howto: Set up a multiplayer server]].

=== Tell us if FlightGear works with your hardware ===
You can help fellow FlightGear users by telling us if FlightGear works with your hardware. Please see [[FlightGear Hardware Recommendations]], [[Problematic Video Cards]] and [[Notebooks known to run FlightGear]].

=== Participate in the FlightGear Forums ===
If you haven't done so already, please consider registering at the {{forum link|text=FlightGear forum}}, this is a very simple thing to do, but it makes it very easy to obtain and provide help and other support within the FlightGear community.

Taking extra care in your posting to avoid requiring the attention of the moderators is in some ways also a contribution. Doing so helps self-police the forums so that the moderators can spend their time doing constructive development.

=== Check out the FlightGear Chat channel ===
{{Main article|FlightGear IRC channel}}
To talk to fellow FlightGear users in realtime, you may want to check out the IRC chat channel.
This is also an excellent way for getting and providing community help, or for getting the latest news about FlightGear.

=== Tell us about your own ideas and feature requests for improving FlightGear ===
If you think you have a good idea or feature request for improving FlightGear, the FlightGear forums and the IRC channel are also an excellent way for getting feedback.

Another new way for posting feature requests and making suggestions is provided at http://flightgear-bugs.googlecode.com

=== Help us write the FlightGear Newsletter ===
The FlightGear newsletter is a community driven newsletter that is created and edited using the wiki. All FlightGear users are invited to contribute to the newsletter. The only thing that is required is a wiki account, which is free and easy to register.

Please feel free to add news about your own FlightGear related projects, or projects started by others to the newsletter.

You can find the draft of next month's newsletter at: [[Next newsletter]]

Just tracking the forums, mailing lists or the IRC channel should provide you with plenty of opportunities for things that could be added to the newsletter. One simple thing for getting started - even without writing anything - is uploading screen shots showing recent FlightGear developments for use in the FlightGear newsletter.

=== Reviews ===
Another thing that can be easily done is reviewing FlightGear (or just certain parts of it, like for example scenery and/or aircraft) and submit your reviews to some of the flight simulation portals. Of course, you can also directly write your reviews using the FlightGear wiki, see: [[FlightGear Reviews]].

[[Category:Contribution requests]]
[[Category:Community]]

[[es:Tener a bien]]
[[fr:Volontaires]]

Mailing lists

2026-05-28T05:07:18Z

Servo: issue tracker note

{{note|Bugs should preferably be {{create ticket|reported to the issue tracker}} instead of posting them to a mailing list.
You may have to register a GitLab account first.}}
'''Mailing lists''' are used for some of the FlightGear community's communications, in particular among the core developers who are working on the flight simulator itself.

Some questions are better asked on the mailing list instead of the forum, especially those related to core development or project infrastructure, but you do not strictly have to be a core developer to subscribe and/or post to the mailing lists.

== Overview of mailing lists==

===Discussion lists===
Discussion lists are used by the FlightGear contributor community to discuss work on the FlightGear project.
{| class="wikitable"
!List
!Status
!Contents

!Archive

!Subscribe
!E-mail address
!Remarks

|-
| rowspan="1" style="background: green; color: black; vertical-align: middle;" |flightgear-devel
|Active
|FlightGear developer discussions
|{{Mailing list archive|flightgear-devel}}
|{{Mailing list subscription link|flightgear-devel}}
|{{Mailing list e-mail address|flightgear-devel}}
|Most active list (primary)
|-
| rowspan="1" style="background: #ff6e67; color: black; vertical-align: middle;" |flightgear-announce
|Inactive
|FlightGear announcements

|{{Mailing list archive|flightgear-announce}}
|
{{Mailing list subscription link|flightgear-announce}}
|{{Mailing list e-mail address|flightgear-announce}}
| Last post 2015
|-
| rowspan="1" style="background: #ff6e67; color: black; vertical-align: middle;" |flightgear-bugs
|Inactive
| Bug tracker messages '''(no longer for reporting bugs)'''
|{{Mailing list archive|flightgear-bugs}}
|{{Mailing list subscription link|flightgear-bugs}}
|{{Mailing list e-mail address|flightgear-bugs}}
|'''Deprecated in favor of the {{Create ticket|issue tracker}}.'''
|-
| rowspan="1" style="background: #ff6e67; color: black; vertical-align: middle;" | flightgear-flightmodel
|Inactive
|Flight model discussions
|{{Mailing list archive|flightgear-flightmodel}}
|{{Mailing list subscription link|flightgear-flightmodel}}
|{{Mailing list e-mail address|flightgear-flightmodel}}
| Last post 2017.
|-
| rowspan="1" style="background: #ff6e67; color: black; vertical-align: middle;" |flightgear-newsletter
|Inactive
|[[FlightGear Newsletter|Newsletter]] announcements and discussions
|{{Mailing list archive|flightgear-newsletter}}
|{{Mailing list subscription link|flightgear-newsletter}}
|{{Mailing list e-mail address|flightgear-newsletter}}
|Last post 2012
|-
| rowspan="1" style="background: #ff6e67; color: black; vertical-align: middle;" |flightgear-scenery
|Inactive
|Discussion of scenery development: code, tools, GIS data, models, etc.
|{{Mailing list archive|flightgear-scenery}}
|{{Mailing list subscription link|flightgear-scenery}}
|{{Mailing list e-mail address|flightgear-scenery}}
|
|-
| rowspan="1" style="background: #ff6e67; color: black; vertical-align: middle;" |flightgear-users
| Inactive
| FlightGear user discussions
|{{Mailing list archive|flightgear-users}}
|{{Mailing list subscription link|flightgear-users}}
|{{Mailing list e-mail address|flightgear-users}}
|Mostly replaced by [http://forum.flightgear.org the forum]
|}

===Automated lists===
These mailing lists are not used for discussion, but are intended to provide information for developers about the status of builds and commit activity.
{| class="wikitable"
!List
!Status
!Contents

!Archive

!Subscribe
!E-mail address
!Remarks

|-
| rowspan="1" style="background: green; color: black; vertical-align: middle;" |flightgear-builds
|Active
|Chatter from the FlightGear build servers
|{{Mailing list archive|flightgear-builds}}
|{{Mailing list subscription link|flightgear-builds}}
|{{Mailing list e-mail address|flightgear-builds}}
|
|-
| rowspan="1" style="background: green; color: black; vertical-align: middle;" |flightgear-commitlogs
|Active
|Source code change commit logs
| {{Mailing list archive|flightgear-commitlogs}}
|{{Mailing list subscription link|flightgear-commitlogs}}
|{{Mailing list e-mail address|flightgear-commmitlogs}}
|
|-
| rowspan="1" style="background: green; color: black; vertical-align: middle;" |flightgear-fgaddon-commitlogs
|Active
|Commit logs for the [[FGAddon]] repository (content developers)
|{{Mailing list archive|flightgear-fgaddon-commitlogs}}
|{{Mailing list subscription link|flightgear-fgaddon-commitlogs}}
|{{Mailing list e-mail address|flightgear-fgaddon-commitlogs}}
|
|-
| rowspan="1" style="background: #ff6e67; color: black; vertical-align: middle;" |flightgear-cvslogs
|Inactive
|CVS commit logs

|{{Mailing list archive|flightgear-cvslogs}}
|
{{Mailing list subscription link|flightgear-cvslogs}}
|{{Mailing list e-mail address|flightgear-cvslogs}}
|Apparently dismissed. Last post 2010.
|}

==Subscribing to a mailing list==
To sign up for one of the above mailing lists, follow these steps:
# Click a '''Subscribe''' link in the list above to get to the mailing list subscription form.[[File:SourceForge_Mailing_List_Signup_Page.png|none|thumb|795x795px]]
#Enter your e-mail address in the '''Email''' field.
#Select your country in the '''Country''' field.
#Select whether you wish to receive '''SourceForge Newsletters.'''
#Agree to the '''SourceForge''' '''Privacy Policy.'''
<ol start="3">
<li> Click the {{button|Subscribe}} button. </li>
<li> You will be sent a confirmation e-mail, go to your email client and open the confirmation email (check your Spam folder if necessary). </li>
<li>Click on '''Confirm Your Subscription.''' [[File:Mailing_List_Email_Confirmation.png|none|thumb|813x813px]] </li>
<li>This will take you to a SourceForge page confirming that you have successfully joined the mailing list. You can close this tab.[[File:Mailing_list_confirmation_complete.png|none|thumb|815x815px]]</li>
<li>Afterwards, you will receive a welcome email from SourceForge summarizing the details of your subscription.{{warning|SourceForge will send you an auto-generated password in cleartext in the welcome email. This has certain security implications, and it is strongly recommended that you should not re-use this password anywhere else.}}
[[File:Mailing_list_welcome_message.png|frameless|819x819px]]
</li>
</ol>

==Posting to mailing lists==
To protect list subscribers from spam, you are allowed to post there only after you have subscribed, and to send e-mails from the address you are subscribed with.<ref name="MLPolicy">{{cite web
|url = https://forum.flightgear.org/viewtopic.php?p=244916
|title = <nowiki>Re: Why is my post rejected from devel list?</nowiki>
|author = <nowiki>curt</nowiki>
|date = May 31st, 2015
|added = May 5th, 2016
|script_version = 0.32
}}
</ref> For the same reason, first posts are subject to moderator approval to catch the cases where people sign up for the sole purpose of posting spam.<ref name="MLPolicy" />

When posting to the lists, discuss your problem laying it out in as much detail you can and show that you are interested in the problem. If you are willing to work on it will also help, even if it is not related to coding itself. If your discussion is more than just asking for features to be added you have a better chance of getting help and you may find people there who can give you pointers on how to approach your problem. Also, be civil - avoid bringing conflicts or noise.

Keep in mind that getting a response from the lists is usually slower than the forum and that responses may take several days. Should it take more than a week, you might want to probe the interest by responding to your own message; sometimes, there might be no reply as there is none.

== Mailing list archives==
Searchable archives are available at [https://marc.info/?l=flightgear-devel&r=1&w=2 '''marc.info''']. This site allows searching by topic name, searching by content of mailing list posts, browsing each month's topics, and searching by author. It doesn't have a thread view, but it has links to the next and previous posts in each topic thread.

The archives are useful if you want to check or confirm details of some aspect of FG, as there will likely be relevant discussion from when a feature was implemented as well as surrounding design considerations/constraints. They can also be useful for new comers, or to check for information from long ago.

The mailing lists are also searchable from the [https://sourceforge.net/p/flightgear/mailman/search/?q= sourceforge website]. Tips: Try searching the relevant mailing list e.g. 'fg-devel', increasing number of results, and click on the post date column to change sorting order from newest to oldest. Each results contains a view entire thread link down the bottom, but as of writing this (April 2021), the thread view is a broken or inconsistent.

==External links==
*[http://www.flightgear.org/mail.html FlightGear mailing list details]
*[[sourceforge:p/flightgear/mailman/|List of all project mailing lists on SourceForge]]

{{appendix}}

[[Category:FlightGear]]
[[Category:Community]]

Howto:Start core development

2026-05-28T05:06:45Z

Servo: replaced with https://docs.flightgear.org/contributors-guide/core-developers-guide/git-workflow.html

{{note|You'll need to familiarize yourself with setting up a development environment and building FlightGear in order to contribute code. See
[https://docs.flightgear.org/contributors-guide/guidelines/building.html Developing on the codebase] if you do not already
have a working setup. Some understanding of ''Git'' will also be
necessary; this free, online [https://git-scm.com/book/en/v2 Git book] is quite useful.}}

The most efficient way to contribute changes to the FlightGear code base is to
file a merge request (this doesn't apply to [[aircraft]] or [[addon|add-ons]], which are
managed differently). We'll first give an overview of the process including
its main prerequisites, then explain each step in more detail.

== Overview ==

The basic workflow for first-time contributors to a FlightGear Git repository
is:

#. '''Fork the repository.'''
Fork the relevant FlightGear repository into your GitLab account. You will
need to know which repository contains the code you are trying to change.
Familiarizing yourself with the code base and the purpose of each
repository is strongly recommended.

#. '''Set up a local clone.'''
Prepare a clone of the repository on your hard disk that is convenient for
getting updates from the upstream repository and pushing changes to your
fork. You'll also use this clone to perform test builds.

#. '''Build the project.'''
If you haven't already done so, this will be the time to set up your
development environment so that you can build FlightGear.

#. '''Create a new branch.'''
Create a branch on your clone to isolate your changes. Use a clear and
descriptive name for your branch (e.g. <code>fix-menubar-typo</code> or
<code>add-new-joystick-configs</code>).

#. '''Make changes.'''
Make the changes on your branch in small, focused commits. Each commit
should be self-contained and represent one logical change.

#. '''Test and double-check.'''
Before you submit your changes to the FlightGear team for review,
double-check your work. Ensure that your code builds and that tests pass.

#. '''Rebase and push.'''
Check if the upstream repository was updated in the meantime. If so, rebase
your work on its latest state and perform a final test run to make sure
everything still works fine.

#. '''Submit a merge request.'''
Open a merge request (MR) to propose your changes for review. Be sure to
use the ''Merge Request Template'' to provide necessary context for
reviewers. Feel free to ask on the developer mailing list if you're unsure
whom to add as a reviewer.

#. '''Code review.'''
Once you have created a merge request, other developers will review your
work, give feedback, and sometimes request changes be made. This is a
crucial part of the development process, as it helps reduce bugs and
improves code quality.

#. '''Clean up.'''
If your merge request was applied, pull your changes from the upstream
branch and delete the local branch you created for the merge request.

In order to present these steps in more detail, we'll now assume that you
intend to make your first contribution to the [https://gitlab.com/flightgear/simgear SimGear repository] (and thus,
that you haven't already forked it). Except for the target branch name which
may differ, the process would be the same for any Git repository of the
FlightGear project.

== Fork the Repository ==

For what follows, you'll need to create a [https://gitlab.com/ GitLab] account if you don't already
have one. Once you are logged into your account, go to the repository home
page ([https://gitlab.com/flightgear/simgear here] in our example) and click on the
Fork button as shown in
; after
filling some information, this will lead to the creation of a copy of the
upstream repository in your own GitLab namespace under
<code><nowiki>https://gitlab.com/YourUserName/</nowiki></code>.

[[File:01_forking.png|thumb|alt=how to find the Fork button on the main page of the repository|Forking the upstream repository]]

Once you've clicked on the button, a new page is loaded as shown in
. The ''Project name'' will be prominent but it's
only a label—choose it as you wish (“My SimGear fork” in the example). For the
''Project URL'', you'll want to select your GitLab username after the initial
portion <code><nowiki>https://gitlab.com/</nowiki></code>.

[[File:02_project_name_URL_slug.png|thumb|alt=dialog that allows one to enter the project name, URL and slug for a fork|Entering the project name, URL and slug for your fork]]

The ''Project slug'' is the final part of the base URL for the fork you're about
to create; let's choose <code>flightgear-simgear</code> so that all your forks of
repositories of the FlightGear project are named <code>flightgear-something</code>.
This way, they will be easy to distinguish from non-FlightGear repositories
you might want to publish under <code><nowiki>https://gitlab.com/YourUserName/</nowiki></code>. Beware
that if you modify the ''Project name'', the GitLab user interface automatically
modifies the ''Project slug''; so, better fill them in this order: ''Project name''
then ''Project slug''.

There are a few fields left to enter. If you choose to include only the
default branch, you'll save a little amount of space but might have to fetch
other upstream branches later. Give your fork public visiblity so that reviews
can take place. When ready, click on the Fork project button to
actually create your fork of the upstream repository.



== Set Up a Local Clone ==

Since we want to pull updates from the upstream repository, it is convenient
to clone it to your hard disk and modify the clone so that pushes go by
default to your fork (which is online under
<code><nowiki>https://gitlab.com/YourUserName/</nowiki></code>). Cloning the upstream SimGear repository
can be done with:

<syntaxhighlight lang="bash">
git clone https://gitlab.com/flightgear/simgear.git
</syntaxhighlight>

{{tip|If you use <code>download_and_compile.sh</code> and it manages the repository you
want to contribute to (this is obviously the case for SimGear), there is
no need to create a new clone: you can simply use the repository clone it
created on your disk.}}

Now, let's add a Git remote that points to your fork of the upstream
repository. We configure this remote so that pushing to it uses <abbr title="Secure Shell">SSH</abbr> authentication. We also configure your repository clone so
that pushes go to your fork by default.

<syntaxhighlight lang="bash">
git remote add flo https://gitlab.com/frougon/flightgear-simgear.git
git remote set-url --push flo git@gitlab.com:frougon/flightgear-simgear.git
git config remote.pushDefault flo
</syntaxhighlight>

In the above commands, replace <code>flo</code> (name of the created remote) with an
appropriate name of your choice; also replace <code>frougon</code> with your GitLab
username.

== Build the Project ==

Make sure you can build FlightGear using the repository clone set up in the
previous step and that the resulting executables run normally. This way,
you'll be able to properly test any changes you later make in this clone.

{{note|The following steps will have to be repeated for each
“self-contained changeset” that you intend to contribute.}}

== Create a New Branch ==

Create a branch based on <code>origin/next</code> that tracks <code>origin/next</code> and make
sure it is up-to-date. Instead of <code>new-branch-name</code>, choose a name that
makes it clear what the changes in the created branch are supposed to do.

<syntaxhighlight lang="bash">
git checkout -b new-branch-name origin/next
git pull
</syntaxhighlight>

{{note|Here, <code>origin</code> is a remote that points to the upstream repository
you cloned from, and <code>next</code> is the name of the development branch
in the [https://gitlab.com/flightgear/simgear SimGear repository] (this is also the case for [https://gitlab.com/flightgear/flightgear FlightGear] and [https://gitlab.com/flightgear/fgdata FGData]). If
you were to contribute to a different repository such as [https://gitlab.com/flightgear/documentation FlightGear documentation], the branch
to base your work on might have a different name (e.g., <code>main</code>).}}

== Make Changes ==

Commit the desired changes to the branch you created in the previous step. If
you need help with <code>git</code>, this online [https://git-scm.com/book/en/v2 book] is a great resource.

Each commit message should start with a single, not too long summary line (no
more than 72—80 characters if possible), then a blank line, then normal
explanations. Example commit message:

<pre>
HID: allow sending output reports from Nasal

- make watched properties only react on a value change
- refactor the larger usage enums to their own file
</pre>

Like here, it is useful when the beginning of the first line is short and
makes it clear to readers which part of the code (subsystem, class, etc.) is
affected by the changes.

== Test and Double-check ==

Rebuild FlightGear with your changes, carefully test. Build the FlightGear
test suite and verify that the tests still pass. This can be done by running
<code>make test_suite</code> or <code>ninja test_suite</code> from the FlightGear build directory
(not the source repository!).

Use commands like:

* <code>git status</code> to check the state of your working directory and repository;
* <code>git log -p</code> to proofread your commit diffs and messages;
* <code>git commit --amend</code> to modify the most recent commit on the branch;
* <code>git rebase -i <ref></code> to modify commits located further
in the ancestry graph (namely, descendants of commit <code><ref></code>; see the
<code>git rebase</code> manual page for explanations).

The <code>gitk</code> program is not essential but can be nice for examining
commits and visualizing the commit graph. If <code>gitk</code> appears to see
local changes that really aren't there, run <code>git status</code> then rerun
<code>gitk</code>.

The <code>pre-commit</code> and <code>clang-format</code> programs are useful to run code quality
checks and apply the project formatting rules. Some of the configured
<code>pre-commit</code> hooks will for instance check for common mistakes
including typos, mixed whitespace or line endings, and so on. If you've
[https://pre-commit.com/#3-install-the-git-hook-scripts installed] the
<code>pre-commit</code> hooks in your repository clone, <code>pre-commit</code>
will be automatically run every time you commit.

{{note|In most cases, the GitLab CI (Continuous Integration) runs
the <code>pre-commit</code> and <code>clang-format</code> checks as part
of the automatic verifications that need to pass, before a merge request can be applied.}}

== Rebase and Push ==

If the upstream branch you started from has changed in the meantime, your work
needs to be rebased on top of its latest state. This can be done with the
following command:

<syntaxhighlight lang="bash">
git pull --rebase
</syntaxhighlight>

In case someone was working on the same files as you, this may trigger
conflicts (so it's a good idea to first announce what you're going to work on
in order to minimize friction and benefit from the insight of experienced
people). Conflicts don't happen very often and it's not the end of the world
when they do. Again, this [https://git-scm.com/book/en/v2 Git book] is a very useful resource in such cases.

If the rebasing did grab upstream changes, perform a final build-and-test run
to be sure everything works fine. Finally, push the branch to your fork:

<syntaxhighlight lang="bash">
git push
</syntaxhighlight>

With no additional arguments, this pushes the current branch to the remote
specified with the <code>remote.pushDefault</code> setting, i.e. to your clone if you
followed the [[#section-Set-up-a-local-clone|above]] instructions. Once
the push is successful, <code>git</code> will show a URL; following it will start the next step.

== Submit a Merge Request ==

The web page opened from the URL output by <code>git</code> when you pushed to
your fork allows to create a merge request from the branch that was pushed.
From this page, select the proper target branch: for development code in
[https://gitlab.com/flightgear/simgear SimGear], that would be <code>next</code>. Select yourself as
an ''assignee'' (meaning that ''you'' are going to shape the merge request into
its final form). Select one or more reviewers to look at it—you can ask on the
[https://sourceforge.net/p/flightgear/mailman/flightgear-devel/ flightgear-devel mailing-list] if unsure, or just leave the field as
''Unassigned''. Don't worry too much about the milestone ''(a priori,'' <code>next</code>
should do unless the merge request is specifically a fix for a release
branch). Select applicable labels, etc.

Regarding the ''Delete source branch when merge request is accepted'' option, we
advise you to make sure it is enabled, otherwise your fork will soon have tons
of branches. What this option does is the following: when the branch from your
merge request is merged into the upstream branch, GitLab will automatically
delete the merge request branch (that you pushed) from your fork. This happens
online at GitLab, not in your local clone. Thus, even after this
occurs, the branch will still be present locally in your clone, until you
delete it yourself (cf. [[#local-branch-removal|below]]).

Finally, the ''Squash commits when merge request is accepted'' option can be
used in case you pushed several commits but would rather have them coalesced
into a single one when the merge request is applied. This is something that
can be done locally using <code>git</code> before pushing (in particular, with
<code>git rebase -i</code>), however the option is still useful in case commits are added
to the merge request after the initial push, be it by you or by reviewers.

== Code Review ==

After a few minutes, hours or days, you'll receive feedback from the
FlightGear developers about your merge request. Reviewing merge requests
requires expertise and takes some time, so please carefully read the remarks
and suggestions, follow up on the questions and requests for changes.

== Clean Up ==

Once the branch is merged, update the local branch of your clone that tracks
the upstream branch your merge request went to (this is the <code>next</code> branch in
our SimGear example):

<syntaxhighlight lang="bash">
git checkout next
git pull --rebase
</syntaxhighlight>

(Normally, the <code>--rebase</code> option shouldn't be necessary here as you
shouldn't have any local commits on top of the upstream ones in this branch,
however it doesn't hurt and can make things easier if you've been forgetful.)



You can now delete the local branch you created earlier to avoid cluttering
your local clone with legacy, unneeded branches:

<syntaxhighlight lang="bash">
git branch -d new-branch-name
</syntaxhighlight>

In case this branch hasn't been merged ''exactly as is'' into the upstream
branch (same commit contents and metadata), <code>git</code> will warn and
refuse to delete the branch unless you insist using <code>-D</code>. If this happens,
you'll have to evaluate yourself (by using <code>git log -p</code>, by comparing
files...) if deleting your local branch <code>new-branch-name</code> is really the
right thing to do. In the likely case that what was merged is a strict
improvement over what you have in <code>new-branch-name</code>, then deleting is the
way to go.

{{tip|If you really, really messed up and deleted the branch before
realizing that it was a mistake, <code>git reflog</code> is likely to save you:
among other things, it shows the commit hashes corresponding to previous
positions of the tips of various branches. As long as no garbage collection occurred in the meantime (<code>git gc</code>), the commit
hashes are all you need to restore “lost commits”: simply create a
branch or tag from the desired commit (before doing do, you may want
to use <code>git show <hash></code> to see the commit for a given hash, or <code>git log <hash></code> to examine its ancestry).}}

From time to time, you may also want to run <code>git fetch -p flo</code> (replace
<code>flo</code> with the name of a remote that points to your fork,
cf. [[#section-Set-up-a-local-clone]]). This removes the <code>flo/...</code>
branches from your local clone that have been deleted from your fork at GitLab
due to the ''Delete source branch when merge request is accepted'' option on the
merge request page (note that for instance, <code>flo/new-branch-name</code> and
<code>new-branch-name</code> are different branches in your clone; they'll both clutter
the display when using <code>git log</code> or <code>gitk</code> until you delete them).

== External links ==
* [https://docs.flightgear.org/contributors-guide/core-developers-guide/git-workflow.html How to Contribute Code]
* [https://git-scm.com/book/en/v2 The Git book]

[[Category:Howto]]
[[Category:Core developer documentation]]
[[ru:Howto:Приступая к разработке ядра]]
[[Category:Hackathon Materials]]

Howto:Optimizing FlightGear for mobile devices

2026-05-24T03:21:07Z

Servo:

{{out of date}}
{{Portability Navbar}}
== Background ==
Also see: [[Flightgear On Android]].

{{FGCquote
|There are a few users wanting to run FlightGear on mobile devices or gaming consoles - others want to use it for UAV stuff, and even others want to run it in "headless" mode, without displaying any graphics at all (certainly not Rembrandt/ALS or other effect/shader stuff) - all of those are valid use-cases, as is running FlightGear on an outdated OS, including even on 10-year old hardware with a nvidia 7600 GPU - ideally, FlightGear should "just work", using what's available - analogous to installing a modern Linux 3.0 distro on a 586 PC with 133 mhz and 32 mb of RAM - give it a try, it actually works reasonably well
|{{cite web |url={{forum url|p=237545}}
|title=<nowiki>Re: Cloning fgdata with GIT submodules</nowiki>
|author=<nowiki>Hooray</nowiki>
|date=<nowiki>Wed Apr 01</nowiki>
}}
}}
Increasingly, people want to try running FlightGear on mobile devices, like the Apple IPhone/IPad, Android phones or Nokia Maemo devices. FlightGear isn't currently optimized for such devices, so that it would require a fair amount of customizations to make this happen, not just optimization-wise, but also related to the user-interface, i.e. lack of keyboard/mouse/yoke and screen space.

== Status (09/2013) ==
{{cquote|<nowiki>far more useful would be to get ARM
working so we can run parts of the stack on Pis, Pandaboards and so on. This would be materially useful for various add-on functions, especially the canvas
and fgcom.

(I spend an increasing amount of my work time on OpenGL on ARM platforms, they have plenty of power to run graphics, depending on which GPU is on the SoC)</nowiki><ref>{{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg40713.html|title=<nowiki>Re: [Flightgear-devel] portability of simgear</nowiki>|author=<nowiki>James Turner</nowiki>|date=<nowiki>Sun, 08 Sep 2013 22:30:54 -0700</nowiki>}}</ref>|<nowiki>James Turner</nowiki>}}

{{cquote|<nowiki>I'm currently busy on other areas but it will be either Raspbian or a custom buildroot Linux deployment. Although, since my current buildroot uses ulibc, that would mean discovering all the places in SG+FG where we've assumed glibc. Note we can't run FG itself without major work, since these platforms only support GLES1 or GLES2, and there's many legacy areas of the renderer which would not work.

(BTW I believe OSG compiles out of the box on ARM targets now, Android at least, but I didn't try it myself yet)</nowiki><ref>{{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg40738.html|title=<nowiki>Re: [Flightgear-devel] portability of simgear</nowiki>|author=<nowiki>James Turner</nowiki>|date=<nowiki>Thu, 12 Sep 2013 23:14:47 -0700</nowiki>}}</ref>|<nowiki>James Turner</nowiki>}}

<references/>

== Motivation ==
This an interesting concept. Such a version would have the potential to greatly expand the ability to use FG, and increase public awareness of the project. However, it would would require a well coordinated project with people who really understand both flightgear and mobile devices.

Thats a good point about the publicity that an app would give FG, however about the graphics, I don't know what specs an iPhone has butit is obviously very limited, so maybe the graphics can't be improved, or any better than the XPlane app.

== Problem ==
Basically, it doesn't really matter if you want to run FG on an IPhone, Android device or on Maemo - there are certain shared challenges and issues for each target. In fact, FlightGear isn't currently too well suited for less powerful systems, like netbooks or old computers.

Currently flightgear development results in software oriented towards high performance desktops/graphics cards and increased simulation accuracy. Given the limited resources of the project, I think the bigger issue would be finding people interesting in working on such a 'mobile flightgear', or iphone specific one.

I would be interested in running such a mobile version on my laptop as well, as the regular versions system requirements leave me unable to run it. There is a very large gap in hardware between fg 1 and the iphone though, and I think even very old late 90s versions would be too high.

They key to orchestrating a version of FG for mobile devices would be finding a technically skilled person with a interest in the concept, who could evaluate how a mobile versions could be written and what direction to take.

Some educated guesses about would be required would be a stripped down FDM, and limited terrain data. With the original FG, the there was NASA laRCsim for the FDM, and OpenGL. However, FG is written in C/C++.

Also, the system requirement of mobile devices are very low compared to PC and also very narrow. Someone with more technical expertise would have to evaluate how feasible a mobile fg would be.

== Issues ==
* For instance, maybe for the interface have the 3d cockpit buttons be clickable with a touch screen directly.
* The idea is good - but immensely surrealistic. It's a phone, not a PC. And I don't even want to imagine the interface (keyboard and mouse wise) such a version of FG would need.
* Wouldn't that be waaaaaaay complicated for the controls though? flaps, magnetos, etc. Unless you're putting out a simplified version.
* Flight simulators are kinda hard to play with small screens. I currently play Leo's flight simulator on my pocketPC and it works pretty well, some of the controls are a bit hard to manage, but it's still quite the feat they accomplished.
* if you can delete the extra goodies such as HIGH detailed models, HIGH detailed textures and things like that it would cut those high specs down i am trying to make an iphone app so im not sure if ill pursue this as my friend is a developer for the iphone and from his personal experience porting 3d into iphone and ipod touch and or ipad is a helluva job and requires ALOT of patience

== Linux-based Targets (Android, Maemo etc) ==
Now, Android/Maemo support should be easier to implement than Playstation, Nintendo Wii, IPhone and all the other platforms that people keep asking about - simply, because Android/Maemo is basically a downstripped Linux version, so compiling/building FG would certainly be possible. However, running would still be "interesting", there are MANY potential issues here, even on a "full" Linux-System like Android: http://stackoverflow.com/questions/653453/how-would-i-go-about-making-a-flight-gear-port-for-wiibrew

Cross-compiling FlightGear for Android devices is not that problematic. However, running FlightGear on an Android device, requires a fair share of customizations, i.e. a downstripped base package, and custom aircraft modifications (key bindings, mouse vs. touch screen support etc). Also, many FlightGear defaults would be unnecessarily high and would not work "as is", these could be reduced (scenery complexity, shaders, rendering settings).

== OpenGL vs. OpenGL ES ==
If FG could be made to run with opengl ES (supported by OSG), it could potentially run on mobile devices that support it and have high enough resources, so long as the rest of the FDM, terrain, and models would work too. However, how to compile the code would depend on the OS, and it seems the iphone uses a cut-down embedded version of OS X. Regular FG can work with regular OS X, so it seems plausible that it could be compiled for the modified OSX (maybe the iphone sdk would help here).

I have hope this is possible if we can find somone with more expertise in programming. I mean, we know FG can run on OS X, and that it needs Open GL. The iphone can use OpenGl ES and seems to use a cut down OS X.
If the differences between them can be over come, then it would be a matter of getting FG system requirements low enough. There is enough hard drive space for even the full version, so its a matter of running it (if the software issues can be overcome). 128 mb memory and the processor seems low, but rendering hvga or qvga is less demanding too.

Also see: http://forum.flightgear.org/viewtopic.php?f=71&t=21964

== Embedded Platforms ==
Anybody interested in this could just as well start out by optimizing FlightGear for smaller devices, like netbooks, or older computers. That work would also be useful for any other/future mobile/embedded target platforms and wouldn't be specific to just a certain target.

Keep in mind that the processing power of modern mobile devices and many other "phones" are more advanced then PCs of some time ago, and the platform is not as different as it once was. The current generation Iphone supports Open GL ES and runs a stripped down/modified OS X- it is foreseeable (or at least plausible) that a future phone with greater hardware specifications could run fg 1.0.

These days, a mobile platform may have multi-core CPUs running at 1-2 ghz with 512+ MB of RAM and hardware-accelerated rendering using OpenGL/OpenGL ES. These platforms are probably at least as powerful as PCs were a decade ago.

Embedded technology has come a lot further. But still, this is a 3D game which even runs with limited fps (80 without 3D clouds) on my rather modern PC (quadcore 2.5GHz, Radeon HD 3650, 4GB ram). The iPhone doesn't nearly have these specifications - especially the video ram is going to be a *big* problem. Maybe in a few years this concept will become interesting, but for now the hardware won't be able to keep up. And like I said earlier, I don't even want to imagine the kind of tiny micro movements I'd need to turn left without crashing. The current generation of phones won't be able to do this - open this topic again in a year or two.

My earlier thoughts about mobile FG were if its hardware demands could be radically reduced by the lower resolution, lower textures, lower vector on terrain, and perhaps simpler FDM it was plausible- in essence taking it back to lower hardware requirements of past versions (less video memory).

== Base Package ==

There are lots of useful customizations that can be done at the base package-level, which won't require any coding experience at all. If you are familiar with developing FlightGear resources (textures, aircraft, scenery) or just editing XML files, you can get involved in helping with this part of the effort.

=== GUI ===
However, the challenges remain - you could just as well try running FG on a netbook with Intel GMA graphics, while it works, there are certain challenges: my IPhone has about 1/5 of the screen estate that my netbook has ...

Then, a custom FG package for Android could probably just as well need its own custom set of GUI dialogs, because most of the default dialogs are not intended to work on small screens - just try running FG with low settings, i.e. 800x600 or even 640x480, and you'll see for yourself that there are many issues here.
Many of these issues also affect other devices, like netbooks for example - so it would be great to come up with a solution here.

Until FlightGear 2.8, the GUI is PUI-based and thus cannot be scaled dynamically. However, the new upcoming [[Canvas Widgets]] based GUI will use a vector-driven approach, so that the GUI can be fully scaled as required.

=== Textures ===
{{FGCquote
|The original structure/design was in support of video cards that could 
only do 256x256 max texture sizes (or video cards with limited memory that 
couldn't handle a complete set of textures with higher resolutions.) We 
are easily a decade beyond those days, so if this causes anyone a problem, 
maybe they are trying to run flightgear on a phone?
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32768042/
|title=<nowiki>Re: [Flightgear-devel] Textures/ vs Textures.high/ (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Curtis Olson</nowiki>
|date=<nowiki>2014-08-27</nowiki>
}}
}}

=== Scenery ===
To learn more about creating a customized and downstripped materials.xml file, see {{forum link|p=165319}}.

It might even be an option to come up with a custom scenery build for Android devices, specifically aimed at low resource usage - i.e. just the KSFO region, and some basic aircraft, which can be easily adapted for non-PC devices, such as the ufo.

Yes, it's worth pointing out that even the X-Plane "IPhone App" is a significantly customized and down-stripped version of the original program and of the original data sets (scenery and aircraft-wise).
While it would be trivial to come up with custom GUI dialogs and simple aircraft like the ufo, creating custom scenery tiles using TerraGear is a little more involved.

As memory space is limited on an Android, perhaps there should be a basic landform with a detuned visual scenery just showing mountain ranges, savanah, forest and desert, basicaly like a semi 3d world map. then downloads of airports for continents ie Africa divided by three with ten airports per sector. The reason I suggest this is because lets face it most people like to fly in specific areas ie Africa or North America etc. Lets face it are we flying or looking at scenery? the average android screen, while a lot bigger then a cell phone is still not a desktop. Personaly I only want to fly and scenery is secondary, besides having some auto generated mountains and hills around would suffice for low and slow, just suggestions mind you, probably impractical as I dont know enough about the program and I am just talking off the top of my head. At the end of the day this idea will send Flightgear where FS never really went

In fact the perfect scenery for your phone (and FG in general) is NO SCENERY, i.e. OCEAN TILES
You could reduce the CPU/GPU load by customizing the scenery tile, using custom resolutions and textures.

=== XML/Property Tree level optimizations ===
Just so that you know: I just finished building and running FG 2.8 on an old (5 years) computer, and the default settings left FG basically unusable (even when using just the ufo), the largest impact had disabling the AI traffic/model system (which was causing severe stutter, which also showed up in the system monitor) and ALL the shader support. Starting FlightGear in a no-scenery location gives me about 350 fps in 800x600, starting at KSFO is well above 60 fps (frame throttling disabled), usually between 50-90 fps and frame spacing between 35-45 ms.

So, I'd suggest to customize your FG version accordingly and keep these settings disabled for starters.
There are probably a number of other opportunities to customize FG without touching the C++ code (even though optimizing the C++ code would definitely seem like a good idea in my opinion). Custom texture packs and custom-built scenery tiles were already mentioned. Making use of frame throttling and adjusting the FDM update interval (model-hz) would also seem to make sense.

I didn't check the specs of the Android phones, but I'd also make sure to set up the threading mode properly.

In other words, even if you don't have access to an Android phone, there are certain things that can be done, and which would help (using an Android emulator via VirtualBox would be another option). Just customizing FG for limited targets like netbooks would also help, and if you have an old computer with an nvidia 6x/7x generation card, you could just as well try running FG.

=== Minimal Startup Profile ===
Basically, the point of the following settings is to disable EVERYTHING that could have an effect on performance, to ensure that we get a working FlightGear window up and running with no eye candy at all, and maximum frame rate.

Once that is working, features can be re-enabled step by step. Features should only be re-enabled after evaluating their impact on performance, using the frame rate counter, frame spacing indicator, the built-in system monitor (can be inspected via telnet/http using --telnet5900) and the OSG on-screen stats.

Depending on the hardware specs of the target platform, adjusting the threading mode of FG/OSG may also help: [[Howto:Activate multi core and multi GPU support]].

* --airport=ksfo
* --offset-distance=4000
* --offset-azimuth=90
* --altitude=500
* --heading=0
* --model-hz=60
* --bpp=16
* --enable-wireframe
* --disable-random-objects
* --prop:/sim/rendering/quality-level=0
* --prop:/sim/rendering/shaders/quality-level=0
* --disable-ai-traffic
* --prop:/sim/ai/enabled=0
* --aircraft=ufo
* --disable-sound
* --prop:/sim/rendering/random-vegetation=0
* --prop:/sim/rendering/random-buildings=0
* --disable-specular-highlight
* --disable-ai-models
* --disable-clouds
* --disable-clouds3d
* --disable-skyblend
* --disable-textures
* --fog-fastest
* --visibility=5000
* --disable-distance-attenuation
* --disable-enhanced-lighting
* --disable-real-weather-fetch

Using these settings, I am getting frame rates between 400-500 fps and a steady frame spacing (latency) of 3-11 ms, on a notebook from 2007 (1024x768). Disabling wireframe mode lowers the framerate by about 50-80 fps.

[[File:Fgfs28-bare-bones.png|thumb 200px|FlightGear bare bones]]

Additional resources can be freed by flying in areas without scenery (ocean tiles), and by using simple aircraft like the ufo. And by using a HUD instead of a 2D/3D cockpit panel.
In addition, custom texture packs may help to reduce the memory footprint. Further memory savings can be achieved by reducing the size of the NavDB in $FG_ROOT

Also, it helps not to use subsystems like instruments and/or the autopilot system, by not loading the via the aircraft-set.xml

So, custom scenery/aircraft packs, with customized textures or rebuilding scenery via TerraGear may help.

=== Disabling Nasal modules ===
Nasal sub modules like [[local weather]] can be "disabled" by removing the sub folders in $FG_ROOT/Nasal.
Individual Nasal modules in $FG_ROOT/Nasal can be disabled by changing the *.nas file extension.

=== Customizing and Disabling Effects/Shaders ===

Currently, all shaders are disabled by default.
However, shaders may actually help improve performance, i.e. using the stencil test to discard geometry that's invisible or by using a dynamic LOD algorithm: http://rastergrid.com/blog/2010/10/gpu-based-dynamic-geometry-lod/

Overall, some shaders could probably be ported to [http://www.khronos.org/files/opengles_shading_language.pdf OpenGL ES GLSL], while others should remain disabled. Some new shaders with optimizations may help reduce the runtime footprint even further.

Effects and shaders could be used to simplify and optimize the FG scenery, such that there's less complexity, and simpler textures used - to reduce the total runtime footprint of FG.
The idea is to use really simple graphics, like in the early 90s of flight simulators - so that FG can also be run on old hardware, such as for example [http://server.faia.upm.es/flight/gallery/dayrunway.jpg shown here].

Fred said: "You may want to use the same shader for all materials and proceed like Thorsten did for the procedural shading. Then you put the complexity you want in that shader. The geometry is here to stay anyhow."

=== Optimizing 3D Models and Textures ===

Please see [http://code.google.com/p/flightgear-bugs/issues/detail?id=733] for reference on how to optimize 3D models.
* http://support.strata.com/index.php?action=artikel&cat=20&id=101&artlang=en
* http://www.openscenegraph.org/documentation/OpenSceneGraphReferenceDocs/a01494.html
* http://stackoverflow.com/questions/tagged/opengl-es-2.0

== Optimizing at the Source Code Level ==
Preparing FlightGear to be run on mobile platforms will require some heavy customizations, not just at the XML/property tree level, but also the source code level.

That being said, it would make sense for people to team up with other FlightGear users who are interested in running FlightGear on such devices (mobile phones, netbooks, game consoles), if we manage to cooperate, we could actually make this work, regardless of the target platform - simply because these customizations will be useful for all related efforts.

First of all, this is about reducing the FlightGear resource footprint (CPU, GPU, RAM, disk space), but also targeting FlightGear for devices which may not have a real screen, or keyboard/mouse support will be necessary.

Obviously, you will need to be able to build FG from source, probably using a cross compiler.
Ideally, you would be familiar with using Virtualization (e.g via VirtualBox or VMWare) or emulators, so that you can actually run the binaries yourself. Obviously, having access to real hardware would be just as good.

So if you know C++, and especially OpenGL/OSG, you could definitely help optimize FlightGear such that it's less resource hungry.
As was said in the Android thread, there are a number of resource-hungry subsystems that could be simply disabled individually, such as the AI traffic system, or shader support.

Being able to disable subsystems individually will be useful for the whole simulator, not just for this effort: [[FlightGear Run Levels]].

There are many other subsystems which are started by default and which cannot be currently disabled, so more CPU/RAM resources can be saved by editing {{flightgear source|path=src/Main/fg_init.cxx|line=1043|pre=$FG_SRC}} and by making more subsystems optional there, using a property to decide if the subsystem shall be started or not, e.g.:

<syntaxhighlight lang="cpp">
std::string target_mode = fgGetString("/startup/target", "default");
if (target_mode == "default") {
// default code
}
else if (target_mode =="android") {
// android-specific code
}
else if (target_mode =="maemo") {
// maemo-specific code
}
</syntaxhighlight>

To test the non-default code path, just start up with something like --prop:/startup/target=android

This is really just intended to get us started. Ideally, subsystem-specific switches would be added, so that all subsystems can be individually disabled or customized, analogous to how other subsystems like the AI traffic system can already be disabled purely from the command line using a --prop:/foo/feature=true/false switch.

Some possible candidates include:
* {{flightgear source|path=src/Main/fg_init.cxx|line=1052|text=the sounds system}}
* {{flightgear source|path=src/Main/fg_init.cxx|line=1081|text=the performance monitor}} (during development this should definitely be useful, especially once customized)
* {{flightgear source|path=src/Main/fg_init.cxx|line=1133|text=the autopilot/route manager systems}}
* {{flightgear source|path=src/Main/fg_init.cxx|line=1178|text=the ATC system}}
* {{flightgear source|path=src/Main/fg_init.cxx|line=1196|text=the traffic manager}}
* {{flightgear source|path=src/Main/fg_init.cxx|line=1225|text=the replay system}}
* {{flightgear source|path=src/Main/fg_init.cxx|line=1230|text=the voice system}}

To check what else is initialized, see the "globals" files in $FG_SRC/Main:
* {{flightgear url|src/Main/globals.cxx}}
* {{flightgear url|src/Main/globals.hxx}}

While disabling these systems can be fairly easily accomplished using ifdefs, care must be taken that FlightGear still builds properly and that no other systems are trying to access disabled subsystems at runtime, so this will involve repeated edit/build/debugging sessions using gdb. But that doesn't need to be done on the target device, it could just as well be completed on a conventional PC.

To see how this can be done using a class template and listeners, please have a look at [[FlightGear Run Levels]]

Potential pitfalls are also discussed at [[FGCanvas#Open Issues]].

== Tracking Memory Utilization at the Subsystem-level ==
In order to help reduce the memory footprint of FlightGear, it might be beneficial to extend the built-in [[Howto:Use the system monitor|performance monitor system]] such that it also supports tracking memory consumption per subsystem.

The performance monitor is initialized in fg_init.cxx: {{flightgear url|src/Main/fg_init.cxx|line=1083}}
The performance monitor is implemented as part of SimGear, <simgear/structure/SGPerfMon.hxx>
As can be seen, it hooks into the [http://simgear.sourceforge.net/doxygen/classSGSubsystem.html SGSubsystem] code, so that it gets invoked by all subsystems in order to create runtime samples.

The commits implementing the performance monitor are these:
* {{simgear commit|27a1c02|text=SimGear commit}}
* {{flightgear commit|4b2506d|text=FlightGear commit}}

The performance monitor dialog reads all data from the property tree and it is created dynamically using a Nasal module in {{fgdata source|Nasal/performance_monitor/monitor.nas|pre=$FG_ROOT}}

It would probably suffice to use "placement new" (i.e. pool memory) here, and overload the new operator at the SGSubsystem level (i.e. in SimGear), so that all subsystems use the overloaded new operator automatically and write allocation reports to the performance monitor.

This would allow us to keep track of the number of memory allocations per subsystem, and also the amount of total RAM allocated by single subsystems. In addition, we could also track freeing via delete, too. And publish all the info to the property tree.

We could even provide a facility to register our own new/malloc operator for SimGear code, so that also non-FG/SG (subsystem) code, such as the Nasal GC, could be tracked memory-wise.

Once the performance monitor is extended like that, it should become obvious how much memory is used by each subsystem, so that it will be easier to do further optimizations, i.e. possibly using a lazy allocation scheme or by optimizing the underlying data structures.

== Related ==
* {{forum url|t=21964}}
* {{forum url|p=160255}}
* {{forum url|t=17091}}
* {{forum url|t=6337}}
* {{forum url|t=8251}}
* {{forum url|t=1833}}
* http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg27635.html
* http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg30391.html
* http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg32369.html

[[Category: Core development projects]]

FGCanvas

2026-05-24T02:57:41Z

Servo: already been implemented

#redirect [[Canvas]]

Initializing Nasal early

2026-05-24T02:53:22Z

Servo: redirect outdated

#redirect [[Nasal Initialization]]

Reset & re-init

2026-05-24T02:50:34Z

Servo:

{{Portability Navbar}}
: ''See also [[Initializing Nasal early]], [[Aircraft Center]] and [[FGCanvas]].''

[[FlightGear]] has a reset feature accessed via "File > Reset", which is useful after your plane crashes.

== Implementation ==
* The init / shutdown code, including FGGlobals, needs to be adjusted to do the actual deletion and run init again. Most of the other init steps (configuration options) are already re-factored in this direction anyway.
* Any subsystems which should be retained, such as tile-manager or renderer, need to be checked very carefully.
** This likely requires some new SGSubsystemGroup hooks to extract the subsystems from their owning groups so they escape shutdown and deletion.
* Any systems with other threads need to be inerted during the reset. In particular any osgDB paged loaders, or TerraSync threads, need to be paused or audited for safety. TerraSync should be relatively simple (since it's a regular subsystem), osgDB interactions, especially with properties, will be harder.
** All animations and effects will need to be destroyed for sure, since they have [[property tree]] references.

[[Category:Developer Plans]]

Reset & re-init

2026-05-24T02:50:07Z

Servo: Replaced content with "{{infobox subsystem |name = Reset & Re-init |started= 01/2013 |description = Fixing reset & re-init |status = merged (under active development as of 01/2013) |maintainers = {{Usr|Zakalawe}} |developers = User:Zakalawe (since 01/2013), }} {{Portability Navbar}} File:Patching-fg-3.2-to-make-more-subsystems-optional.png|450px|thumb|Screen shot showing a the performance monitor in a patched version of FlightGear 3.2 where subsystem initialization is made bette..."

{{infobox subsystem
|name = Reset & Re-init
|started= 01/2013
|description = Fixing reset & re-init
|status = merged (under active development as of 01/2013)
|maintainers = {{Usr|Zakalawe}}
|developers = [[User:Zakalawe]] (since 01/2013),
}}

{{Portability Navbar}}

[[File:Patching-fg-3.2-to-make-more-subsystems-optional.png|450px|thumb|Screen shot showing a the performance monitor in a patched version of FlightGear 3.2 where subsystem initialization is made better configurable and increasingly optional by allowing subsystems to be explicitly disabled/enabled during startup. Decoupling internal subsystem dependencies means that we can more easily provide support for [[FlightGear Benchmark|benchmarking]], but also [[FlightGear Headless|headless]] regression testing - and eventually, also a standalone [[FGCanvas]] startup mode.]]

: ''See also [[Initializing Nasal early]], [[Aircraft Center]] and [[FGCanvas]].''

[[FlightGear]] has a reset feature accessed via "File > Reset", which is useful after your plane crashes.

== Implementation ==
* The init / shutdown code, including FGGlobals, needs to be adjusted to do the actual deletion and run init again. Most of the other init steps (configuration options) are already re-factored in this direction anyway.
* Any subsystems which should be retained, such as tile-manager or renderer, need to be checked very carefully.
** This likely requires some new SGSubsystemGroup hooks to extract the subsystems from their owning groups so they escape shutdown and deletion.
* Any systems with other threads need to be inerted during the reset. In particular any osgDB paged loaders, or TerraSync threads, need to be paused or audited for safety. TerraSync should be relatively simple (since it's a regular subsystem), osgDB interactions, especially with properties, will be harder.
** All animations and effects will need to be destroyed for sure, since they have [[property tree]] references.

[[Category:Developer Plans]]

How the Nasal GC works

2026-05-24T02:44:01Z

Servo: remove outdated quotes

{{Template:Nasal Internals}}
{{Multicore}}

This page explains how the Nasal GC works.

= High Level Architecture =
{{Main article|High-Level Architecture}}
{{FGCquote
|1= Regarding Nasal as a scripting language and AW, I'm hopeful that the work I'm doing on HLA will allow us to run Nasal in a separate thread from the FDM and display, so Nasal GC no-longer can impact frame-rates. It would also allow for writing a weather simulation completely external to the FlightGear instance, which could be quite neat.
|2= {{cite web
| url = http://forum.flightgear.org/viewtopic.php?p=265721#p265721
| title = <nowiki>Re: the real cost of the Nasal Garbage Collector</nowiki>
| author = <nowiki>stuart</nowiki>
| date = Nov 24th, 2015
| added = Nov 24th, 2015
| script_version = 0.23
}}
}}

{{FGCquote
|1= I do like the idea of a stand-alone script interpreter communicating via HLA or some similar IPC, but we still have to consider fragments of script code embedded in models to create or enhance fancy animations. Not all script fragments make sense to run externally.
|2= {{cite web
| url = http://forum.flightgear.org/viewtopic.php?p=270412#p270412
| title = <nowiki>Re: FGPython an propose for Python as an nasal alternative</nowiki>
| author = <nowiki>curt</nowiki>
| date = Dec 28th, 2015
| added = Dec 28th, 2015
| script_version = 0.23
}}
}}

{{FGCquote
|1= if scripting is a major performance hog, off-load it to a different thread. I don't think we have many situation where it is, but that's what HLA is going to do.
|2= {{cite web
| url = http://forum.flightgear.org/viewtopic.php?p=270463#p270463
| title = <nowiki>Re: FGPython an propose for Python as an nasal alternative</nowiki>
| author = <nowiki>Thorsten</nowiki>
| date = Dec 29th, 2015
| added = Dec 29th, 2015
| script_version = 0.23
}}
}}

{{FGCquote
|1= haven't made too many tests with Nasal active as anyone can do that (adjust paths to have no terrain if necessary).
But most of this becomes less relevant with the HLA changes that Stuart's working on.
|2= {{cite web
| url = http://forum.flightgear.org/viewtopic.php?p=265726#p265726
| title = <nowiki>Re: the real cost of the Nasal Garbage Collector</nowiki>
| author = <nowiki>Richard</nowiki>
| date = Nov 24th, 2015
| added = Nov 24th, 2015
| script_version = 0.23
}}
}}

= Mark/Sweep =

When using a mark-and-sweep collector, unreachable objects are not immediately reclaimed. Instead, garbage is allowed to accumulate until all available memory has been exhausted. When that happens, the execution of the program is suspended temporarily while the mark-and-sweep algorithm collects all the garbage. Once all unreferenced objects have been reclaimed, the normal execution of the program can resume.

Obviously, the main disadvantage of the mark-and-sweep approach is the fact that that normal program execution is suspended while the garbage collection algorithm runs. In particular, this can be a problem in a program that must satisfy real-time execution constraints (like a flight simulator). For example, an interactive application that uses mark-and-sweep garbage collection becomes unresponsive periodically.

The mark-and-sweep algorithm is called a tracing garbage collector because is traces out the entire collection of objects that are directly or indirectly accessible by the program. The objects that a program can access directly are those objects which are referenced by local variables on the processor stack as well as by any static variables that refer to objects. In the context of garbage collection, these variables are called the roots . An object is indirectly accessible if it is referenced by a field in some other (directly or indirectly) accessible object. An accessible object is said to be live . Conversely, an object which is not live is garbage.

The mark-and-sweep algorithm consists of two phases: In the first phase, it finds and marks all accessible objects. The first phase is called the mark phase. In the second phase, the garbage collection algorithm scans through the heap and reclaims all the unmarked objects. The second phase is called the sweep phase.

The mark/sweep algorithm can also be easily expressed using pseudo code, i.e. in Nasal itself:

<syntaxhighlight lang="nasal">

var garbageCollect = func (roots) {
foreach(var root; roots) {
mark(root);
}
sweep();
}

</syntaxhighlight>

The mark() function would just recursively check (i.e. calling itself) if the "marked" flag is set or not, and make sure to set the mark bit for all referenced objects:

<syntaxhighlight lang="nasal">

var mark = func (obj) {
if (!obj.marked) {
obj.marked=1;
foreach( var referenced; referenced_by(obj) )
mark(referenced);
}
}
</syntaxhighlight>

Finally, the sweep() function (reap() in the Nasal GC), will free all unreachable objects and reclaim the memory:

<syntaxhighlight lang="nasal">

var sweep = func {
foreach(var obj; allocated_objects) {
if (obj.marked) obj.marked=0;
else reclaim(obj);
}
}

</syntaxhighlight>

Nasal's implementation of sweep() ( called reap() ) works such that it is always executed for a handful of different type-specific memory pools. In addition, it also makes sure to allocate new memory if required.

= Pool storage =
A [http://en.wikipedia.org/wiki/Memory_pool memory pool] is basically a preallocated region of memory, which is dynamically resized. The Nasal GC works such that it manages a handful of global memory pools for all native Nasal types (strings, functions, vectors, hashes etc). At the moment, the hard coded defaults ensure that 25-50% of additional object "slots" (memory blocks) are kept available during each execution of reap() [{{simgear source|path=simgear/nasal/gc.c|line=287|full=1}}].

Whenever new memory is requested to create a new type (such as a vector or a string), the available memory in the corresponding pool will be checked, reachable objects will be marked, and dead objects will be removed from all pools using a mark/sweep collector, new memory blocks will be allocated if necessary. All of this happens atomically, i.e. single-threaded, in a "stop-the-world" fashion.

== Memory blocks ==

[[File:NasalBlockStruct.png|thumb|450px|Nasal Block structure]]

A Nasal memory pool consists of memory blocks.

A memory block is a [http://en.wikipedia.org/wiki/Linked_list#Linear_and_circular_lists singly linked list]: {{simgear source|path=simgear/nasal/gc.c|line=10}}.

[[File:NasalNewBlockCallgraph.png|thumb|400px|Callgraph for newBlock()]]

Each block contains a field to store its size, a pointer to the allocated memory, and another pointer to the next block.

<syntaxhighlight lang="C">
struct Block {
int size; // size of the block
char* block; // pointer to the memory region
struct Block* next; // pointer to the next block
};
</syntaxhighlight>

New memory blocks are allocated using newBlock() and the memory is initialized with 0: {{simgear source|path=simgear/nasal/gc.c|line=167}}

<syntaxhighlight lang="C">
static void newBlock(struct naPool* p, int need)
{
int i;
struct Block* newb;
if(need < MIN_BLOCK_SIZE) need = MIN_BLOCK_SIZE;
// allocate a new Block
newb = naAlloc(sizeof(struct Block));
// initialize the Block
newb->block = naAlloc(need * p->elemsz); // number of elements * size of element
newb->size = need; // set block size
// memory blocks are circular linked lists:
newb->next = p->blocks;
p->blocks = newb;
naBZero(newb->block, need * p->elemsz);

if(need > p->freesz - p->freetop) need = p->freesz - p->freetop;
p->nfree = 0;
p->free = p->free0 + p->freetop;
// mark all new blocks as unreachable and add them to the pool's free list
for(i=0; i < need; i++) {
// initialize each new new memory blocks by setting up an naRef (the container for all Nasal references)
struct naObj* o = (struct naObj*)(newb->block + i*p->elemsz);
o->mark = 0;
p->free[p->nfree++] = o;
}
p->freetop += need;
}
</syntaxhighlight>

== Nasal memory pools ==

For each of the 7 Nasal data types, there is a separate storage pool available, declared as part of the "Globals" structure.

As can be seen, each storage pool is addressed by its enum index (0..6): {{simgear source|path=simgear/nasal/data.h|line=65}}
<syntaxhighlight lang="C">
enum { T_STR, T_VEC, T_HASH, T_CODE, T_FUNC, T_CCODE, T_GHOST, NUM_NASAL_TYPES }; // V. important that this come last!
</syntaxhighlight>

For example, '''globals->pools[T_VEC]''' refers to the storage pools for vectors:

<syntaxhighlight lang="C">
globals->pools[T_VEC];
</syntaxhighlight>

The 7 storage pools are declared in code.h as part of the "Globals" structure: {{simgear source|path=simgear/nasal/code.h|line=40}}

The relevant part is:

<syntaxhighlight lang="C">
struct Globals {
// Garbage collecting allocators:
struct naPool pools[NUM_NASAL_TYPES];
int allocCount;
// Dead blocks waiting to be freed when it is safe
void** deadBlocks;
int deadsz;
int ndead;
//...
};
</syntaxhighlight>

So, we have these pools:

* globals->pools[T_STR]
* globals->pools[T_VEC]
* globals->pools[T_HASH]
* globals->pools[T_CODE]
* globals->pools[T_FUNC]
* globals->pools[T_CCODE]
* globals->pools[T_GHOST]

== The Globals structure ==

[[File:NasalGlobalsStruct.png|thumb|500px|Nasal Globals structure]]

The complete Globals structure looks like this:
<syntaxhighlight lang="C">
struct Globals {
// Garbage collecting allocators:
struct naPool pools[NUM_NASAL_TYPES];
int allocCount;
// Dead blocks waiting to be freed when it is safe
void** deadBlocks;
int deadsz;
int ndead;

// Threading stuff

int nThreads;

int waitCount;

int needGC;

int bottleneck;

void* sem;

void* lock;

// Constants

naRef meRef;

naRef argRef;

naRef parentsRef;

// A hash of symbol names
naRef symbols;
naRef save;
struct Context* freeContexts;
struct Context* allContexts;
};
</syntaxhighlight>

== The naPool structure ==

[[File:NasalnaPoolStruct.png|thumb|400px|Nasal naPool structure]]

The structure keeping all pool-related information is named "naPool", the layout of the naPool structure can be seen in data.h: {{simgear source|path=simgear/nasal/data.h|line=181}}
<syntaxhighlight lang="C">
struct naPool {
int type; // one of T_STR, T_VEC, T_HASH etc
int elemsz; // size of each element - determined via naTypeSize(T_*)
struct Block* blocks;
void** free0; // pointer to the alloced buffer
int freesz; // size of the alloced buffer
void** free; // current "free frame"
int nfree; // down-counting index within the free frame
int freetop; // curr. top of the free list
};
</syntaxhighlight>

Each memory pool is initialized using naGC_init(): {{simgear source|path=simgear/nasal/gc.c|line=192}}

<syntaxhighlight lang="C">
void naGC_init(struct naPool* p, int type)
{
p->type = type;
p->elemsz = naTypeSize(type);
p->blocks = 0;
p->free0 = p->free = 0;
p->nfree = p->freesz = p->freetop = 0;
reap(p);
}
</syntaxhighlight>

As can be seen, "elemsz" just stores the size of each type-specific structure, so that it can be used for new allocations.

naGC_init is called in initGlobals() in code.c for each Nasal type (T_STR, T_VEC etc): {{simgear source|path=simgear/nasal/code.c|line=172}}
<syntaxhighlight lang="C">
for(i=0; i<NUM_NASAL_TYPES; i++)
naGC_init(&(globals->pools[i]), i);
</syntaxhighlight>

The size of a memory pool is determined using poolsize(): {{simgear source|path=simgear/nasal/gc.c|line=203}}

<syntaxhighlight lang="C">
static int poolsize(struct naPool* p)
{
int total = 0;
struct Block* b = p->blocks;
while(b) { total += b->size; b = b->next; }
return total;
}
</syntaxhighlight>

The function poolsize() just iterates over all memory blocks in the pool, and computes the total size of the pool by adding up the "size" field of all blocks in the linked list.

= Allocating Nasal types =

All Nasal types (scalars, vectors, hashes, funcs, ghosts) are allocated via wrappers in {{simgear source|path=simgear/nasal/misc.c|text=misc.c}}.

These wrappers are:
* naNewString(): {{simgear source|path=simgear/nasal/misc.c|line=77}}
* naNewVector(): {{simgear source|path=simgear/nasal/misc.c|line=87}}
* naNewHash(): {{simgear source|path=simgear/nasal/misc.c|line=94}}
* naNewCode(): {{simgear source|path=simgear/nasal/misc.c|line=101}}
* naNewCCode(): {{simgear source|path=simgear/nasal/misc.c|line=106}}
* naNewFunc(): {{simgear source|path=simgear/nasal/misc.c|line=131}}
* naNewGhost(): {{simgear source|path=simgear/nasal/misc.c|line=140}}
* naNewGhost2(): {{simgear source|path=simgear/nasal/misc.c|line=154}}

All of these wrappers are really just helpers on top of naNew(), they just set up type-specific information and initialize each Nasal type properly.
For instance, first naNew() is called for the given context, along with the type info (to set up the size properly)- and then each type is initialized:
<syntaxhighlight lang="C">
// The naNew* helpers are just wrappers to set up type-specific structures, after allocating the memory using naNew()
naRef naNewString(struct Context* c)
{
naRef s = naNew(c, T_STR);
PTR(s).str->emblen = 0;
PTR(s).str->data.ref.len = 0;
PTR(s).str->data.ref.ptr = 0;
PTR(s).str->hashcode = 0;
return s;
}
</syntaxhighlight>

= naNew() =

As can be seen, the key allocator function is {{simgear source|path=simgear/nasal/misc.c|line=66|text=naNew()}}.
All memory allocations done via the naNew*() helpers will first of all set up memory using naNew().

naNew() is really just a fancy malloc() replacement, i.e. it's just getting passed the Nasal execution context, and the nasal type (which is mapped to the size of the requested memory region using naTypeSize()).

{{FGCquote|1= New nasal objects are added to a temporary bin when they are created, because further allocation might cause a garbage collection to happen before the code that created the object can store a reference to it where the garbage collector can find it. For performance and simplicity, this list is stored per-context. When the context next executes code, it clears this list. Here's the problem: we do a lot of our naNewXX() calls in FlightGear using the old "global context" object that is created at startup. But this context is no longer used to execute scripts* at runtime, so as Csaba discovered, it's temporaries are never flushed. That essentially causes a resource leak: those allocations (mostly listener nodes) will never be freed. And all the extra "reachable" Nasal data floating around causes the garbage collector to take longer and longer to do a full collection as time goes on, causing "stutter". And scripts that use listeners extensively (the cmdarg() they use was one of the affected allocations) will see the problem more seriously.|2= {{cite web | url = http://sourceforge.net/p/flightgear/mailman/message/15645369/ | title = <nowiki>[Flightgear-devel] Stutter/Nasal issue resolved (was: FlightGear/Plib periodic stutter notes)</nowiki> | author = <nowiki>Andy Ross</nowiki> | date = Oct 24th, 2007 }}}}

{{FGCquote|1= Once listeners were added, scripts could be recursive: (script A sets property X which causes listener L to fire and cause script B to run) We need two or more contexts on the stack to handle that; a single global one won't work. I didn't like the fix though. Exposing the temporary bin as part of the Nasal public API is ugly; it's an internal design feature, not something users should tune. Instead, I just hacked at the FlightGear code to reinitialie this context every frame, thus cleaning it up. A "proper" fix would be to remove the global context entirely, but that would touch a bunch of code.|2= {{cite web | url = http://sourceforge.net/p/flightgear/mailman/message/15645369/ | title = <nowiki>[Flightgear-devel] Stutter/Nasal issue resolved (was: FlightGear/Plib periodic stutter notes)</nowiki> | author = <nowiki>Andy Ross</nowiki> | date = Oct 24th, 2007 }}}}

The naNew() function is also implemented in misc.c, see {{simgear source|path=simgear/nasal/misc.c|line=66}}:

<syntaxhighlight lang="C">
naRef naNew(struct Context* c, int type)
{
naRef result;
if(c->nfree[type] == 0)
c->free[type] = naGC_get(&globals->pools[type],
OBJ_CACHE_SZ, &c->nfree[type]);
result = naObj(type, c->free[type][--c->nfree[type]]);
naTempSave(c, result);
return result;
}
</syntaxhighlight>

First, the conditional checks if there's any free memory in the Nasal storage pools for the requested Nasal data type, if there isn't any free memory left, new memory is assigned to the contexts->free[type] pool via naGC_get().

'''Note:''' naGC_get() is the only function which really manages all memory pools and which triggers the GC. Allocations via naNew()* will end up calling naNew() and naNew() ends up calling naGC_get() '''always'''.

For the time being, OBJ_CACHE_SZ can be ignored, it's defined in code.h: {{simgear source|path=simgear/nasal/code.h|line=12}}
<syntaxhighlight lang="C">
// Number of objects (per pool per thread) asked for using naGC_get().
// The idea is that contexts can "cache" allocations to prevent thread
// contention on the global pools. But in practice this interacts
// very badly with small subcontext calls, which grab huge numbers of
// cached objects and don't use them, causing far more collections
// than necessary. Just leave it at 1 pending a rework of the
// collector synchronization.
#define OBJ_CACHE_SZ 1
</syntaxhighlight>

The final argument to the naGC_get() function is a pointer to to the context's nfree[type] member which is updated by the function.

Next, a new naRef structure is set up using the allocated naObj memory and the type info:

<syntaxhighlight lang="C">
result = naObj(type, c->free[type][--c->nfree[type]]);
</syntaxhighlight>

<syntaxhighlight lang="C">
naRef naObj(int type, struct naObj* o)
{
naRef r;
SETPTR(r, o);
o->type = type;
return r;
}
</syntaxhighlight>

= The GC interface =

[[File:Nasal-gc.png|thumb|650px|Nasal GC]]
TODO: {{simgear source|path=simgear/nasal/data.h|line=204}}

* void naGC_init(struct naPool* p, int type);
* struct naObj** naGC_get(struct naPool* p, int n, int* nout);
* void naGC_swapfree(void** target, void* val); (used for vector/hash resizing)
* void naGC_freedead();
* void naiGCMark(naRef r);
* void naiGCMarkHash(naRef h);

= The pool manager =

[[File:NasalNaGetCallgraph.png|thumb|550px|Callgraph for naGC_get()]]

All high level type allocators (naNewString, naNewVector, naNewHash etc) make use of the naNew() call introduced earlier.

naNew() doesn't directly allocate new memory from the heap using naAlloc(), but instead uses the naGC_get() helper which manages memory from the global pools (i.e. preallocated memory for each type).

For each native Nasal data type (scalars, vectors, hashes, funcs etc) , there are separate memory pools in globals->pools[n]. The index (n) is one of T_VEC, T_HASH, T_FUNC etc.

The naGC_get() pool "manager" is located in gc.nas: {{simgear source|path=simgear/nasal/gc.c|line=211}}

<syntaxhighlight lang="C">
struct naObj** naGC_get(struct naPool* p, int n, int* nout)
{
struct naObj** result;
naCheckBottleneck();
LOCK();
while(globals->allocCount < 0 || (p->nfree == 0 && p->freetop >= p->freesz)) {
globals->needGC = 1;
bottleneck();
}
if(p->nfree == 0)
newBlock(p, poolsize(p)/8);
n = p->nfree < n ? p->nfree : n;
*nout = n;
p->nfree -= n;
globals->allocCount -= n;
result = (struct naObj**)(p->free + p->nfree);
UNLOCK();
return result;
}
</syntaxhighlight>

As can be seen, the garbage collector itself is triggered by setting the global "needGC" flag to 1 in the globals structure and then calling the bottleneck() function: {{simgear source|path=simgear/nasal/gc.c|line=105}}.

The memory region from the global pool is cast back to a pointer (struct naObj**): {{simgear source|path=simgear/nasal/gc.c|line=226}}
the "nout" parameter is just there to update c->nfree[type] with the amount of free memory.

In other words, whenever new Nasal types are allocated, new memory from one of the 7 Nasal pools is requested. All of these allocation requests are channeled through naNew() and finally naGC_get(). naGC_get() is the de facto memory manager in Nasal, all memory management is triggered here - new memory block allocations for each pool, as well as garbage collection via the bottleneck() call.

This also means that we basically just need to provide an alternate naGC_get() function, next to the existing one, to add support for alternate GC schemes.

= Supporting additional GC implementations =
It would probably make sense to change the pool manager interface/signature such that additional implementations can be easily provided and registered, so that merely a GC_CALLBACK pointer must be set during initialization in order to use a different GC scheme:

<syntaxhighlight lang="diff">
diff --git a/simgear/nasal/data.h b/simgear/nasal/data.h
index deb4fbd..f3fcaa1 100644
--- a/simgear/nasal/data.h
+++ b/simgear/nasal/data.h
@@ -202,7 +202,7 @@ int naiHash_sym(struct naHash* h, struct naStr* sym, naRef* out);
void naiHash_newsym(struct naHash* h, naRef* sym, naRef* val);

void naGC_init(struct naPool* p, int type);
-struct naObj** naGC_get(struct naPool* p, int n, int* nout);
+void naGC_alloc(struct Context* c, int type, int n);
void naGC_swapfree(void** target, void* val);
void naGC_freedead();
void naiGCMark(naRef r);
diff --git a/simgear/nasal/gc.c b/simgear/nasal/gc.c
index e9d9b7b..3bae313 100644
--- a/simgear/nasal/gc.c
+++ b/simgear/nasal/gc.c
@@ -191,8 +191,10 @@ static int poolsize(struct naPool* p)
return total;
}

-struct naObj** naGC_get(struct naPool* p, int n, int* nout)
+void naGC_alloc(struct Context* c, int type, int n)
{
+ struct naPool* p = &globals->pools[type]; // type-specific memory pool
+ int* nout = &c->nfree[type]; //
struct naObj** result;
naCheckBottleneck();
LOCK();
@@ -208,7 +210,7 @@ struct naObj** naGC_get(struct naPool* p, int n, int* nout)
globals->allocCount -= n;
result = (struct naObj**)(p->free + p->nfree);
UNLOCK();
- return result;
+ c->free[type]=result;
}

static void markvec(naRef r)
diff --git a/simgear/nasal/misc.c b/simgear/nasal/misc.c
index dae0bfe..5caeb76 100644
--- a/simgear/nasal/misc.c
+++ b/simgear/nasal/misc.c
@@ -66,9 +66,7 @@ naRef naStringValue(naContext c, naRef r)
naRef naNew(struct Context* c, int type)
{
naRef result;
- if(c->nfree[type] == 0)
- c->free[type] = naGC_get(&globals->pools[type],
- OBJ_CACHE_SZ, &c->nfree[type]);
+ if(! c->nfree[type] ) naGC_alloc(c, type, OBJ_CACHE_SZ);
result = naObj(type, c->free[type][--c->nfree[type]]);
naTempSave(c, result);
return result;

</syntaxhighlight>

= Disabling the current GC =

The overhead caused by managing the memory pools and constantly scanning the heap (mark/reap) can be examined by modifying the naGC_get() function such that it no longer uses any pool memory, but directly allocates via malloc()/naAlloc() - without ever freeing any memory (i.e. leaking). While the fgfs process will eventually get killed this way, the GC will be basically switched off.

<syntaxhighlight lang="C">
struct naObj** naGC_get(struct naPool* p, int n, int* nout)
{
struct naObj** result;
naCheckBottleneck();
LOCK();
#define LEAKY
#ifndef LEAKY
while(globals->allocCount < 0 || (p->nfree == 0 && p->freetop >= p->freesz)) {
globals->needGC = 1;
bottleneck();
}
if(p->nfree == 0)
newBlock(p, poolsize(p)/8);
n = p->nfree < n ? p->nfree : n;
*nout = n;
p->nfree -= n;
globals->allocCount -= n;
result = (struct naObj**)(p->free + p->nfree);
#else
result = (struct naObj**) naAlloc( naTypeSize(n) );
#endif
UNLOCK();
return result;
}
</syntaxhighlight>

= bottleneck() =

[[File:NasalCheckBottleneckCallerGraph.png|thumb|450px|Callergraph of naCheckBottleneck()]]
[[File:NasalCheckBottleneckCallgraph.png|thumb|400px|Callgraph of naCheckBottleneck()]]

Whenever new memory from one of the global pools is being requested via naGC_get(), naCheckBottleneck() will also be invoked:

{{simgear source|path=simgear/nasal/gc.c|line=131}}

<syntaxhighlight lang="C">
void naCheckBottleneck()
{
if(globals->bottleneck) { LOCK(); bottleneck(); UNLOCK(); }
}
</syntaxhighlight>

This checks if globals->bottleneck is true, and if it is, it makes sure that the bottleneck() function is only invoked after acquiring a lock.

[[File:NasalBottleneckCallgraph.png|thumb|550px|Callgraph of bottleneck()]]

{{simgear source|path=simgear/nasal/gc.c|line=100}}
<syntaxhighlight lang="C">
// Must be called with the main lock. Engages the "bottleneck", where
// all threads will block so that one (the last one to call this
// function) can run alone. This is done for GC, and also to free the
// list of "dead" blocks when it gets full (which is part of GC, if
// you think about it).
static void bottleneck()
{
struct Globals* g = globals;
g->bottleneck = 1;
while(g->bottleneck && g->waitCount < g->nThreads - 1) {
g->waitCount++;
UNLOCK(); naSemDown(g->sem); LOCK();
g->waitCount--;
}
if(g->waitCount >= g->nThreads - 1) {
freeDead();
if(g->needGC) garbageCollect();
if(g->waitCount) naSemUp(g->sem, g->waitCount);
g->bottleneck = 0;
}
}
</syntaxhighlight>

The actual garbage collection takes place in {{simgear source|path=simgear/nasal/gc.c|line=114|text=line 114}} where dead objects from the memory pool are freed, and the garbageCollect() function is called if globals.needGC is true.

= garbageCollect() =

[[File:NasalGarbageCollectCallgraph.png|thumb|550px|Callgraph of garbageCollect()]]

This is the function that does the mark/sweep part using mark() to recursively mark reachable objects, and reap() to collect unreachable objects.

{{simgear source|path=simgear/nasal/gc.c|line=35}}

<syntaxhighlight lang="C">
// Must be called with the big lock!
static void garbageCollect()
{
int i;
struct Context* c;
globals->allocCount = 0;
c = globals->allContexts;
while(c) {
for(i=0; i<NUM_NASAL_TYPES; i++)
c->nfree[i] = 0;
for(i=0; i < c->fTop; i++) {
mark(c->fStack[i].func);
mark(c->fStack[i].locals);
}
for(i=0; i < c->opTop; i++)
mark(c->opStack[i]);
mark(c->dieArg);
marktemps(c);
c = c->nextAll;
}
mark(globals->save);
mark(globals->symbols);
mark(globals->meRef);
mark(globals->argRef);
mark(globals->parentsRef);
// Finally collect all the freed objects
for(i=0; i<NUM_NASAL_TYPES; i++)
reap(&(globals->pools[i]));
// Make enough space for the dead blocks we need to free during
// execution. This works out to 1 spot for every 2 live objects,
// which should be limit the number of bottleneck operations
// without imposing an undue burden of extra "freeable" memory.
if(globals->deadsz < globals->allocCount) {
globals->deadsz = globals->allocCount;
if(globals->deadsz < 256) globals->deadsz = 256;
naFree(globals->deadBlocks);
globals->deadBlocks = naAlloc(sizeof(void*) * globals->deadsz);
}
globals->needGC = 0;
}
</syntaxhighlight>

For each invocation of garbageCollect(), the following takes place:
* For each context:
** The counter for each type-specific pool will be reset to 0: {{simgear source|path=simgear/nasal/gc.c|line=43}}
** for each stack frame of the given context, all reachable locals and functions will be marked as reachable: {{simgear source|path=simgear/nasal/gc.c|line=45}}
** All instructions in the opcode stack will be marked as reachable from top to bottom: {{simgear source|path=simgear/nasal/gc.c|line=49}}
** mark(die->Arg)
** temporary variables are marked reachable
* root references (constants) are marked reachable: {{simgear source|path=simgear/nasal/gc.c|line=56}}
* foreach Nasal data type:
** unreachable objects are then collected: {{simgear source|path=simgear/nasal/gc.c|line=63}}
* dead blocks are freed and new memory is allocated: {{simgear source|path=simgear/nasal/gc.c|line=67}}
* the needGC flag is set to 0

= mark() =

[[File:NasalMarkCallgraph.png|thumb|400px|Callgraph of mark()]]

All reachable objects are recursively marked using tagged naRef structures {{simgear source|path=simgear/nasal/data.h|line=50}}, so that unreachable objects can be collected (i.e. because the reftag bit is not set) and freed.

TODO: {{simgear source|path=simgear/nasal/gc.c|line=223}}
<syntaxhighlight lang="C">

</syntaxhighlight>

= reap() =

[[File:NasalReapCallgraph.png|thumb|450px|Callgraph for reap()]]

This is the collector function called by garbageCollect() which also frees elements and allocates new blocks for the specified pool:

<syntaxhighlight lang="C">
// Collects all the unreachable objects into a free list, and
// allocates more space if needed.
static void reap(struct naPool* p)
{
struct Block* b;
int elem, freesz, total = poolsize(p);
freesz = total < MIN_BLOCK_SIZE ? MIN_BLOCK_SIZE : total;
freesz = (3 * freesz / 2) + (globals->nThreads * OBJ_CACHE_SZ);
if(p->freesz < freesz) {
naFree(p->free0);
p->freesz = freesz;
p->free = p->free0 = naAlloc(sizeof(void*) * p->freesz);
}
p->nfree = 0;
p->free = p->free0;
for(b = p->blocks; b; b = b->next)
for(elem=0; elem < b->size; elem++) {
struct naObj* o = (struct naObj*)(b->block + elem * p->elemsz);
if(o->mark == 0)
freeelem(p, o);
o->mark = 0;
}
p->freetop = p->nfree;
// allocs of this type until the next collection
globals->allocCount += total/2;
// Allocate more if necessary (try to keep 25-50% of the objects
// available)
if(p->nfree < total/4) {
int used = total - p->nfree;
int avail = total - used;
int need = used/2 - avail;
if(need > 0)
newBlock(p, need);
}
}
</syntaxhighlight>

=swapfree() =
[[File:NasalGC swapfreeCallgraph.png|thumb|450px|Callgraph of swapfree()]]

= freeelem() =

[[File:NasalFreeelemCallgraph.png|thumb|Callgraph of freeelem()]]

Frees individual elements and adds freed pointers to the globals free list, implemented in gc.c: {{simgear source|path=simgear/nasal/gc.c|line=153}}
<syntaxhighlight lang="C">
static void freeelem(struct naPool* p, struct naObj* o)
{
// Clean up any intrinsic storage the object might have...
switch(p->type) {
case T_STR: naStr_gcclean ((struct naStr*) o); break;
case T_VEC: naVec_gcclean ((struct naVec*) o); break;
case T_HASH: naiGCHashClean ((struct naHash*) o); break;
case T_CODE: naCode_gcclean ((struct naCode*) o); break;
case T_GHOST: naGhost_gcclean((struct naGhost*)o); break;
}
p->free[p->nfree++] = o; // ...and add it to the free list
}
</syntaxhighlight>

= Type destructors =
Will be called by freelem(), implemented for all native Nasal types:

* strings (T_STR): naStr_gcclean {{simgear source|path=simgear/nasal/string.c|line=113}}
* vectors (T_VEC): naVec_gcclean {{simgear source|path=simgear/nasal/vector.c|line=22}}
* hashes (T_HASH): naiGCHashClean {{simgear source|path=simgear/nasal/hash.c|line=221}}
* code (T_CODE): naCode_gcclean {{simgear source|path=simgear/nasal/gc.c|line=136}}
* ghosts (T_GHOST): naGhost_gcclean {{simgear source|path=simgear/nasal/gc.c|line=147}}

= Contexts =

{{cquote|<nowiki>New nasal objects are added to a temporary
bin when they are created, because further allocation might cause a
garbage collection to happen before the code that created the object
can store a reference to it where the garbage collector can find it.
For performance and simplicity, this list is stored per-context. When
the context next executes code, it clears this list.

Here's the problem: we do a lot of our naNewXX() calls in FlightGear
using the old "global context" object that is created at startup. But
this context is no longer used to execute scripts* at runtime, so as
Csaba discovered, it's temporaries are never flushed. That
essentially causes a resource leak: those allocations (mostly listener
nodes) will never be freed. And all the extra "reachable" Nasal data
floating around causes the garbage collector to take longer and longer
to do a full collection as time goes on, causing "stutter". And
scripts that use listeners extensively (the cmdarg() they use was one
of the affected allocations) will see the problem more seriously.

(That's a feature, not a bug. Once listeners were added, scripts
could be recursive: (script A sets property X which causes listener
L to fire and cause script B to run) We need two or more contexts on
the stack to handle that; a single global one won't work.)

I didn't like the fix though. Exposing the temporary bin as part of
the Nasal public API is ugly; it's an internal design feature, not
something users should tune. Instead, I just hacked at the FlightGear
code to reinitialize this context every frame, thus cleaning it up. A
"proper" fix would be to remove the global context entirely, but that
would touch a bunch of code.

</nowiki><ref>{{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg13028.html|title=<nowiki>[Flightgear-devel] Stutter/Nasal issue resolved (was: FlightGear/Plib periodic stutter notes)</nowiki>|author=<nowiki>Andy Ross</nowiki>|date=<nowiki>Wed, 24 Oct 2007 11:33:36 -0700</nowiki>}}</ref>|<nowiki>Andy Ross</nowiki>}}

{{cquote|<nowiki>
The problem is the fact that Nasal recycles context objects - it keeps a pool of freed contexts around. At the point we shutdown Nasal, all contexts should be inactive, i.e in the free list (and they are, phew). Free-ed contexts are still considered for GC however, and there seems to be an issue that the opStack (part of the stack machine which implements the core bytecode interpreter of Nasal) doesn’t end up empty in some situations.

So my work around is to clear the opStack (and frameStack) to zero, inside naFreeContext. This then matches the state for a new (non-recycled) context, and ensures that on the next GC cycle, items referenced by the opStack aren’t marked as in-use. (At least to me it makes sense, that a freed context - which is therefore inaccessible - shouldn’t be retaining items in its opStack into its next re-use)

The ideal fix would be to find out *why* the opStack doesn’t return to empty ‘naturally’ before the context is freed
</nowiki><ref>{{cite web |url=https://sourceforge.net/p/flightgear/mailman/message/36765215/|title=<nowiki>[Flightgear-devel] Resetting Nasal (was Re: Implementing aircraft.nas in C++)</nowiki>|author=<nowiki>James Turner</nowiki>|date=<nowiki>2019-09-17 17:43:53</nowiki>}}</ref>|<nowiki>James Turner</nowiki>}}

<references/>

Also see: {{flightgear source|path=src/Scripting/NasalSys.cxx}} (in FGNasalSys::update)

<syntaxhighlight lang="c">
// The global context is a legacy thing. We use dynamically
// created contexts for naCall() now, so that we can call them
// recursively. But there are still spots that want to use it for
// naNew*() calls, which end up leaking memory because the context
// only clears out its temporary vector when it's *used*. So just
// junk it and fetch a new/reinitialized one every frame. This is
// clumsy: the right solution would use the dynamic context in all
// cases and eliminate _context entirely. But that's more work,
// and this works fine (yes, they say "New" and "Free", but
// they're very fast, just trust me). -Andy
</syntaxhighlight>

'''Consider using coccinelle here to rewrite naContext handling in all places at once'''

[[Category:Developer Plans]]

[[File:NasalContextStruct.png|thumb|500px|Nasal Context structure]]

{{simgear source|path=simgear/nasal/code.h|line=76}}
<syntaxhighlight lang="C">
struct Context {

// Stack(s)

struct Frame fStack[MAX_RECURSION];

int fTop;

naRef opStack[MAX_STACK_DEPTH];

int opFrame; // like Frame::bp, but for C functions

int opTop;

int markStack[MAX_MARK_DEPTH];

int markTop;

// Free object lists, cached from the global GC

struct naObj** free[NUM_NASAL_TYPES];

int nfree[NUM_NASAL_TYPES];

// GC-findable reference point for objects that may live on the

// processor ("real") stack during execution. naNew() places them

// here, and clears the array each instruction

struct naObj** temps;

int ntemps;

int tempsz;

// Error handling

jmp_buf jumpHandle;

char error[128];

naRef dieArg;

// Sub-call lists

struct Context* callParent;

struct Context* callChild;

// Linked list pointers in globals

struct Context* nextFree;

struct Context* nextAll;

void* userData;

};
</syntaxhighlight>

= Stack frames =
{{simgear source|path=simgear/nasal/code.h|line=33}}

= Tagged structures =
{{simgear source|path=simgear/nasal/data.h|line=84}}

= Core allocations =
All core memory allocation takes place via wrappers in {{simgear source|path=simgear/nasal/misc.c|line=8|text=misc.c}}:

<syntaxhighlight lang="C">
void naFree(void* m) { free(m); }
void* naAlloc(int n) { return malloc(n); }
void* naRealloc(void* b, int n) { return realloc(b, n); }
void naBZero(void* m, int n) { memset(m, 0, n); }
</syntaxhighlight>

<references/>

[[Category:Core developer documentation]]
[[Category:Core development projects]]
[[Category:Nasal]]

[[Category:Nasal Garbage Collection]]

Chat menu

2026-05-23T06:56:45Z

Servo:

There's a '''chat menu''' in [[FlightGear]] since v1.0.0. In this special menu are some prefabricated messages stored. They're ready to use. You don't have to write them first, just choose a message and press the corresponding number. The message is send like a normal chat messages, so all the pilots and [[ATC]]s will see it.

You can find the Chat Menu in the [[menu|menubar]] under <tt>Multiplayer > Chat Menu</tt>. The Chat Menu can also be opened with a shortcut: {{key press|-}} (minus).

{{FGCquote
|1= Users can type messages that are displayed to all users within MP range. The messages are displayed within a dialog box, and optionally to the screen using the current Nasal message system. This allows the messages to be TTS'd by festival.
|2= {{cite web
| url = http://sourceforge.net/p/flightgear/mailman/message/13968945/
| title = <nowiki>[Flightgear-devel] Multiplayer chat patch</nowiki>
| author = <nowiki>Buchanan, Stuart</nowiki>
| date = Sep 23rd, 2006
| added = Sep 23rd, 2006
| script_version = 0.23
}}
}}

== Editing entries ==
To edit the entries in the Chat Menu you've to change this file: <tt>[[$FG_ROOT]]/ATC/chat-menu-entries.xml</tt>.

With these symbols you could add information that depends on the moment. So things like altitude, direction and aircraft type are automatically filled in at the places of the symbols.

{| class="wikitable"
! Function
! Symbol
! Discription
|-
| Airport direction
| !
|
|-
| Airport distance
| ^
|
|-
| Aircraft type
|%
| First word from /sim/description
|-
| Callsign
| #
|
|-
| Current Altitude
| $
|
|-
| Airport ID
| *
|
|-
| Current runway
| (
|
|}

Here's an example:

<syntaxhighlight lang="xml">
<menu>
<name>* Ground, #, request taxi instructions for departure.</name>
</menu>
</syntaxhighlight>

It'll looks something like this when using FlightGear:

'''KSFO''' Ground, '''F-WWDD''', request taxi instructions for departure.

As you noticed in the example above I've placed some extra stuff. Every entry has to start with the <tt><name></tt> tag and close with <tt></name></tt>. One row in FlightGear is one <menu>...</menu> tag. Here's an example of the Formation menu:

<syntaxhighlight lang="xml">
<menu>
<name>[Formation]</name>
<menu>
<name>Form up on my wing.</name>
</menu>
<menu>
<name>Break left.</name>
</menu>
<menu>
<name>Break right.</name>
</menu>
</menu>
</syntaxhighlight>

A row extra could be formed with two <menu> tags. It'll looks like this:

<syntaxhighlight lang="xml">
<menu>
<name>[ATC]</name>
<menu>
<name>[Ground]</name>
<menu>
<name>* Ground, #, request taxi instructions for departure.</name>
</menu>
</menu>
</menu>
</syntaxhighlight>

In the two examples above you see things like this <tt>[ATC]</tt>. The [ and ] are there to indicate that the text should not be included in the messages.

[[Category:Menubar]]
[[Category:FlightGear feature]]
[[Category:Multiplayer]]

Aircraft rating system

2026-05-23T06:53:50Z

Servo:

The '''aircraft rating system''' is an attempt to help you find the aircraft you're looking for among the thousands of [[aircraft]] available for [[FlightGear]].

The rating system gives an aircraft a 0–5 score in four areas - ''[[FDM]]'', ''systems'', ''cockpit'' and ''external model''. These ratings can then be encoded in the <code>aircraft-set.xml</code> file from where they can be picked up by launchers, web pages etc. The sum of the scores in the four criteria provides an overall 0–20 score, which can be mapped to a textual overall aircraft status.

{{Package Management}}
== Who rates an aircraft? ==
It is the responsibility of the aircraft maintainer/developer if there is an active one. The rating system was specifically setup to be easy for the aircraft maintainer/developer to do because it assumes that the person doing the rating is very familiar with both the real-life aircraft specifications and systems and knows how close the model is to those. The procedure is very brief, more so any update.

It is possible for the third party to do the rating but it is a nontrivial undertaking for someone who is not intimately familiar with the real-life aircraft specifications and the FDM that would require a lot of time and effort at least for any aircraft that was at a somewhat advanced state of development. Of course early development phase aircraft would be easier to rate since the criteria for those levels does not require so much aircraft specific knowledge. Most of the unrated aircraft are probably unmaintained and many of them are probably aircraft that will end up with lower ratings if they are rated.

If one plans to add ratings to an aircraft, a good plan is the following:
#Try to locate the maintainer by pinging the devel [[mailing list]] and also asking on the forum. If there is a maintainer nicely ask them to rate their aircraft.
#If there is a maintainer but he/she is unable or unwilling to rate the aircraft ask permission to do the work. If you get permission then make the change and ask for it to be merged into the base package.
#If a maintainer can not be located or the aircraft is known to be abandoned do the rating and ask for the change to be merged into the base package.

See [[#Considerations on the rating procedure|below]] for some considerations on this rating procedure.

== Rating criteria ==
=== Flight Dynamics Model (FDM) ===
* 0: None, or using FDM from other aircraft
* 1: JSBSim Aeromatic or YASim geometric model used without tuning. Flaps modeled.
* 2: FDM tuned for cruise configuration.
* 3: FDM tuned for rate of climb and cruise Pilot Operating Handbook (PoH) performance numbers
* 4: FDM matches PoH in 90% of configurations
* 5: FDM matches PoH and most known test data.

=== Systems ===
* 0: No controllable systems: engine is always on, generic radio,
* 1: Generic engine start/stop (}}s), correct size/number of fuel tanks, generic (untuned) autopilot, working flaps/gear
* 2: Working electrical system, fuel feed cockpit controls, stable autopilot
* 3: Accurate startup procedure, tuned autopilot with cockpit controls matching real aircraft systems, generic failure modelling (Vne, +ve/-ve G, gear limits). No unrealistic systems.
* 4: Primary aircraft-specific systems modelled (aero-tow, radar, GPWS, weapons, external stores). User able to follow normal PoH checklists (e.g. startup, shutdown) in entirety
* 5: Some aircraft-specific failure modes implemented (e.g. flame-out, inverted engine limitations). Some emergency procedures implemented (RAT, emergency gear release), able to follow some emergency PoH checklists in entirety.

Obviously some aircraft (e.g. glider) have fewer systems than other (e.g. and airliner). If your aircraft does not have a given system, ignore it for the purposes of rating. E.g. a glider does not need a stable autopilot for a 2 rating.

Furthermore, for a 3 or above, the aircraft should not implement systems not present in the real aircraft (e.g. flaps if none present IRL). The exception to this is an autopilot accessed through the menu (considered useful for flight testing purposes).

=== Cockpit ===
* 0: No cockpit
* 1: 2D panel, no cockpit.
* 2: 2D panel in 3D cockpit, or incomplete 3D panel
* 3: 3D panel and cockpit
* 4: 3D panel and accurately modelled 3D cockpit, plain texturing. Hotspots for majority of controls.
* 5: 3D panel and accurately modelled 3D cockpit with photo-realistic texturing.

=== External Model ===
* 0: None
* 1: Simple 3D model, no animations
* 2: Accurate 3D model with animated control surfaces (elevator, aileron, rudder, flaps)
* 3: Accurate 3D model with animated control surfaces, gear detailing (retraction, rotation), prop
* 4: Accurate 3D model with animated control surfaces, gear, prop, livery support (if applicable).
* 5: Highly accurate 3D model (down to minor components such as control rods), with animated control surfaces, gear, prop, livery support, tyre smoke, shader effects.

Objectively differentiating between a 4 and a 5 is very difficult. As a guideline, a "5" model is as realistic as possible given the available rendering technology.
{{note | The difference between a 3 and a 4 seems to be just the livery support. I propose to add "detailed parts (realistic lights, exhausts, airing)" for a 4
(you are free to remove this NOTE after reviewed this proposition)}}

== Overall status ==
Sum the ratings of the 4 criteria, to produce an overall score from 0 to 20.

This maps to overall status as follows:

* 18 or higher: [[:Category:Aircraft status: Advanced production|advanced-production]] (minimum 4 in each rating)
* 16 to 17: [[:Category:Aircraft status: Production|production]] (minimum 4 in each rating)
* 12 to 15: [[:Category:Aircraft status: Early production|early-production]] (minimum 3 in each rating)
* 9 to 11: [[:Category:Aircraft status: Beta|beta]]
* 8 or lower:[[:Category:Aircraft status: Alpha|alpha]]

== Encoding the rating ==
=== In the -set.xml file ===
The ratings should be encoded in the -set.xml file for the aircraft, under <sim> as follows.

<syntaxhighlight lang="xml">
<status>early-production</status>
<rating>
<FDM type="int">5</FDM>
<systems type="int">4</systems>
<cockpit type="int">3</cockpit>
<model type="int">3</model>
</rating>
</syntaxhighlight>

=== In aircraft articles on the wiki ===
Status ratings can be (optionally) included in an aircraft's wiki article. '''Please note that those posted on the wiki are only used by the wiki itself and do not substitue the rating in -set.xml, as described above!'''

The overall status is auto-calculated and will be displayed. Remove the <tt>|status =</tt> line if you use the official system and add the following lines, each with a rating on a scale of 0 to 5. See [[Template:Infobox Aircraft]] for more info.

...
| status-fdm = 5
| status-systems = 4
| status-cockpit = 3
| status-model = 3
...

You can find the current wiki aircraft pages within each status level via the [[:Category:Aircraft by status|aircraft status category]] page.

== Considerations on the rating procedure ==
Is it right that aircraft are only rated by their respective developers? Many lack a rating, and in many cases the maintainer is absent or just doesn't care. If, as originally, the rating is intended open to everyone, should unrated aircraft be rated by users? It would be reasonable for alpha development versions (they're easy to rate), but could lead to wrong ratings for the more developed ones. Yet this might incentivize their maintainers (hardly a well developed project is not maintained) to fix those, so far, unused ratings. Some insights on this were examined in the forum thread on this topic: see [http://forum.flightgear.org/viewtopic.php?f=4&t=12193&p=211086#p211086 this forum post].

== Related content ==
=== Wiki articles ===
* [[Catalog metadata]]

=== Forum topics ===
Some topics on the FlightGear forum related to the background behind the aircraft rating system:
* [http://forum.flightgear.org/viewtopic.php?f=4&t=12193 Aircraft Rating System] (First post dated Thu May 26, 2011)
* [http://forum.flightgear.org/viewtopic.php?f=4&t=10080 Aircraft model/cockpit rating (see first post)] (First post dated Mon Nov 15, 2010)
* [http://forum.flightgear.org/viewtopic.php?f=4&t=9680 Discussing aircraft status's] (First post dated Sat Oct 02, 2010)
* [http://forum.flightgear.org/viewtopic.php?f=6&t=4999 Aircraft ranking on wiki] (First post dated Sat May 30, 2009)

[[Category:FlightGear]]
[[Category:Aircraft enhancement]]

[[ca:Sistema de qualificació d'aeronaus]]
[[de:Flugzeugbewertung]]
[[fr:Aircraft status indication]]