FlightGear wiki - User contributions [en]

Howto:Install aircraft

2013-03-31T03:18:04Z

Moksha: /* Choosing aircraft */ remove = symbol

{{installing}}
The latest official [[aircraft]] can be downloaded at [http://www.flightgear.org/download/aircraft-2-10-filterable/ FlightGear.org Aircraft], which then usually require unzipping software to extract from a compressed file format. Then these must be manually installed in a FlightGear software installation to use. The details depend on the method of download, operating system, and user setup.

An open source file archiver is [http://www.7-zip.org/ 7-Zip], although be aware of user setup.

You may also want to take a look at:
* [[Aircraft]]
* [[Helicopter]]
* [[Vehicle]]
* [[Table of models]]

=== Linux ===
(Ubuntu 7.10)
# Download the aircraft
# Open Terminal and log in as root
# Navigate to /usr/share/Games/FlightGear/Aircraft
# Extract your aircraft file into the folder
# Start up flight gear. Your aircraft should show up in the launcher

=== Macintosh OS X ===

# Open GUI Launcher for FlightGear Mac
# Click on "Others" tab at middle right of launcher
# Click "Install Add-On Data" link at bottom of launcher
# Select aircraft folder from menu, and click "Open"
# Click OK on pop-up box.

=== Windows ===
# Download an aircraft and save it on your desktop.
# Unzip the file, using a file archiver like 7-Zip.
# Move the unzipped folder (usually the aircraft's name) to your <tt>FlightGear/data/Aircraft</tt> directory.

'''!!! IMPORTANT !!!'''

"Modern" Windows Versions (e.g. XP, Vista, Win7) tinkering a lot with user rights on access level. Therefore it's a bad idea to install and run FlightGear to and from "C:\Program Files" (German: C:\Programme). Find another drive / folder where you as logged in user have all neccesary right to read, write and execute the files you installed. Additionally there's a space / blank in folder's name which could cause weird behaviour. Use something like "C:\FlightGear".

== Choosing aircraft ==
If you are looking for information to decide what aircraft to download, try [[Table of models]] or [[Aircraft]]. External links to third party aircraft can be found at [[FlightGear hangars]]. Remember that the latest aircraft may not load with previous versions, so look for older aircraft in the links section.

== For developers ==
Help develop the [[FlightGear Package Manager]] which is intended to support automatic aircraft and scenery installation, currently in alpha development and in need of testing.

== Related content ==
* [[Installing Scenery]]

[[fr:Howto_Installer_un_avion]]

Nasal scripting language

2011-12-25T05:43:02Z

Moksha: /* Garbage collection */ sentence improvement

''Please note that a considerable amount of resources has not yet been incorporated here, you can check these out by going to the "[[Talk:Nasal_scripting_language|discussion]]" page, where we are collecting links to webpages and mailing list discussions/postings related to Nasal.''

==Nasal = Not another scripting language!==

The short summary is that Nasal is a scripting language that is tightly integrated with FlightGear itself,
and provides a very easy way to manipulate the property tree, which is the core data structure within the
simulator that exposes all the important internal runtime states of FlightGear.

[[FlightGear]] offers a very powerful functional scripting language called [http://plausible.org/nasal/ "Nasal"], which supports reading and writing of internal [[Property Tree Intro|FlightGear properties]], accessing internal data via extension functions, creating GUI dialogs and much more.

Nasal uses some of the concepts of ECMA/JavaScript, Python and Perl and implements a simple but complete way of Object Oriented Programming (OOP), Nasal uses an internal garbage collector so that no manual memory management is required by the programmer.

People familiar with other programming languages, and scripting languages like JavaScript in particular, are usually able to learn Nasal rather quickly. FlightGear provides a rich library of simulation-specific and general-purpose functions that can be accessed by Nasal scripts.

Nasal code can be run by aircraft configuration files, and it can be embedded in various [[XML]] files (dialog files, animation files, bindings for joysticks, keyboard and cockpit controls, and even in [[Howto: Nasal in scenery object XML files|scenery objects]]). Nasal is platform independent and designed to be thread safe.

=== Some success stories ===
These were taken from the developers mailing list:

* "Nasal is *very* well designed, compact, and efficient. It is used heavily throughout many areas of FlightGear."
* "It's interesting though how much nasal you can actually get away with using without making a blip on frame rates. Nasal is *very* efficient and powerful for being an interpreted script language."
* "FlightGear needed a built-in scripting language, and it has one. A compact, clean, elegant and fast one, Nasal extension functions interface perfectly to the property tree, the event manager, the built-in XML parser etc. Nasal is very tightly integrated in fgfs and used all over the place."
* "There's no question that scripting languages are good; fgfs has a lot of Nasal code now. In my profiling I have never seen the nasal interpreter as a hot spot"
* "I'm a simple content contributor with very little background in programming. When I made my first Aircraft (the bf109) I was confronted with the need to deploy slats automatically at a given speed. I din't want to embed C++ code or had such a complex script that the error messages in FG wouldn't help me and I previously only used a bit of python. I looked at some Nasal scripts and within a few hours it worked. I was impressed how easy it is to write even complex Nasal scripts. Later I started developing the walker feature that made it possible to walk around in the scenery, all with nasal. Stuart kindly enhanced the walker and added an animation system to it (see bluebird), again with nasal. Others have made Flight computers with it (see V-22 and Su-37). Nasal is a worthy tool"
* "I used Nasal to build several rather complex systems, like Fuel System, Stab Augmentation System, Autopilot Logic, Terrain Avoidance Radar, Radar Warning Receiver and much more, and yes, I love Nasal too. Learning Nasal use was easy and fun and I din't found any limitation yet."
* There are many vital parts of FlightGear currently coded in nasal. There are also random bits of nasal code scattered around in joystick configurations, instrument and aircraft models, scenery models... everywhere.
* "We have an entire directory full of Nasal 'function' libraries now, and I'm quite happy using them instead of rolling my own duplicate functionality."
* Nearly every sophisticated Aircraft uses some kind of Nasal, be it Effects like tyre smoke or important functionalities like Engine and electric management, The Bluebird FDM is completely written in Nasal, vital parts of the V-22 Osprey rely on it, Flyby and Model View wouldn't work anymore, no more interactive objects in the scenery, lots of the MP System would be gone, ... Nasal is THE tool which makes FG development fun and adds nearly unlimited possibilities. If you need an example, look at the Bluebird animated walker, all done in Nasal."
* "there are good reasons to use Nasal - first of all the user base which regularly compiles their own code is small, whereas people do install addon packages - so I get a lot more feedback and test results. Second that one usually can't really crash the whole system from Nasal. Third, it's very easy to quickly try something and very maintenance-friendly. Fourth, you can actually start developing something without knowing how the core code ties together - which I suppose takes a lot of time to learn. And so on."
* "Hard-coding every instrument in C++ instead of nasal means only developers following/building the latest cvs head code get to use whatever until the next release cycle."
* "Hard coding every instrument/flight control in C++ means my WW-II storch (et.al.) is stuck with an autobrake functionality it doesn't have nor need."
* "I think it boils down to the fact that we have two approaches that can accomplish the same thing. The C/C++ approach offers high performance but there is a dependence on when the C/C++ code was added to FlightGear. The Nasal approach offers fast prototyping, flexibility, and more (but not complete) independence from the C/C++ code."
* "A basic problem with C++ functions is it is hard/impossible to override them for a special purpose. Writing in pure nasal allows function name hijacking and other tricks that can't be used on C++ code."
* "Given the fact that FG is platform independent, I don't know if the embedded C++ is doing the same on Windows, Linux, PPC and intel Macs. Apart from the fact that if I was able to code c++ I would embed it to FG rather than in an Aircraft specific script"
* "If we ported Nasal code over to C++ we'd lose the ability to change small things "on the fly" without compiling over and over again. We'd also lose good programmers, who prefer scripting over C++. Aircraft creation would not be customizable etc etc."
* "The argument against Nasal is essentially that C++ is faster than Nasal - which, everything else being equal, is certainly correct. But highly specialized Nasal code written for a particular problem outperforms general purpose C++ code - I've given several examples in the past. If someone were e.g. to add movement to Nasal spawned models by adding a velocity property, I'm not sure it would outperform my Nasal quadtree-sorted adaptive range code which priorizes movement for things actually inside the field of view. Of course, if you'd hard-code that specialized algorithm, it would be faster than the Nasal version - but then you couldn't apply it to other problems any more."
* "How many airplane developer will you loose if you remove the Nasal engine from FGFS because they can write Nasal code but not C++ code?"
* "The algorithm being equal, I don't think there's a question that C++ is faster (I doubt the factor 10 though - that seems to be an extreme case). Everything else being equal, I also don't think there's a question that Nasal code is more accessible. And I would base any decision what to hard-code and what not on that balance."
* "Nasal is just much better suited for FlightGear than many alternatives because of it's size, processing speed and because a number of FlightGear core developers have a good idea what's going on."
* "In theory we could even use VBScript but Nasal has proven to be valuable for almost 10 years, so no reason to change or add another scripting language. Besides, if you know JavaScript then learning Nasal would take little effort."
* "The pool of people with commit rights to the core C++ code is very, very small."

Nasal really is an excellent choice for prototyping and implementing new features and even completely new systems in FlightGear.

For example, the [[bombable]] script implements "dog fighting" support on top of FlightGear, without ANY changes to the C++ side of the code, just by using some fairly advanced scripted code (implemented in the built-in Nasal programming language). You can basically imagine it like a "MOD" of FlightGear. In other words, the bombable script creates a completely new "mode" in FlightGear.

No matter if it's scenery, aircraft, AI scenarios or whatever: many things that were originally never planned to be supported by FlightGear core developers, are now implicitly supported because of the loose coupling between highly configurable and flexible systems, such as the property tree and the Nasal scripting language.

So we are really standing on the shoulders of giants here, because we are now -after 10+ years- in the position to create significant new features (and even completely new systems in FlightGear) within the constraints of the FlightGear base package, without even touching the C++ source code at all - simply because FlightGear has become so flexible and extensible.

All of this became possible by some important architectural decisions, such as for example the use of XML and plain text files for pretty much all configuration files in FlightGear (and thus open file formats in general), a publicly accessible tree of state variables that can be easily inspected and modified at runtime (the property tree). Similarly, the decision to embed a scripting language that can be used for scripting the entire simulator was another important decision.

In FlightGear, Nasal is the most accessible method of customizing the whole simulator to a very high degree. Nasal code can be easily edited using a conventional text editor, there are no special tools required: Nasal source code is interpreted, compiled to bytecode and run by the Nasal "virtual machine" using FlightGear itself.

The emerging [[A local weather system|Local weather]] system was entirely prototyped in Nasal space, and is now being increasingly augmented by moving performance-critical functions to C++ space instead.

Using Nasal, it is even possible to create entirely scripted flights and smart "AI bots":

I have something here that I think is kind of fun. I've been fiddling with
this off and on since last fall and decided it was time to clean it up a bit
and quit hording all the fun for myself. Basically I have taken the F-14b
and created a high performance Navy "drone" out of it. It can auto-launch
from a carrier, auto fly a route (if you've input one) and can do circle
holds (compensating for wind.) I've added a simulated
gyro stabilized camera that will point at anything you click on and then
hold that view steady no matter what the airplane does (similar to what real
uav's can do.) Finally, you can command it to return home and it will find
the carrier, setup a reasonable approach and nail the landing perfectly
every time (factoring in wind, carrier speed, etc.): http://www.flightgear.org/uas-demo/

As of 03/2009, there were approximately 170.000 lines of reported Nasal source code in the FlightGear base package [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg21333.html], compared to 2006 this is almost a rate of growth of 600% within 3 years [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg01728.html]. This illustrates the sheer adoption rate Nasal is experiencing in FlightGear.

(As of 10/2011, the FlightGear base package contained 326.000 lines of Nasal source code in *.nas files)

Note that this page is mostly about FlightGear-specific APIs/extension functions and usage patterns.
Thus, you may also want to have a look here:

* [http://plausible.org/nasal/lib.html core language/library documentation]
* [http://plausible.org/nasal/sample.nas annotated source code examples]
* [http://plausible.org/nasal/doc.html Nasal design document]
* [http://www.plausible.org/nasal/flightgear.html a helpful tutorial about using Nasal in FlightGear].

In addition, the [http://gitorious.org/fg/fgdata/trees/master/Nasal Nasal directory] in the FlightGear base package contains a wealth of tested, proven and usually well-commented source code that you may want to check out for additional examples of using the Nasal scripting language in FlightGear [http://gitorious.org/fg/fgdata/trees/master/Nasal].

If you have any Nasal specific questions, you will want to check out the [[Nasal FAQ]], feel free to ask new questions or help answer or refine existing ones. If you would like to learn more about existing Nasal modules in FlightGear, you may want to check out [[Nasal Modules]].

If you are a developer and interested in extending Nasal, you may want to check out [[Howto:Extending Nasal]].

Many short "howto"-style tutorials on Nasal programming can be found in the [[Category:Nasal|Nasal category]].

== Some words on Nasal for fellow C++ programmers ==

Compared to C++, there is really nothing "low quality" about Nasal per se: Nasal is just the "script glue" that connects different parts of the simulator: Many Nasal scripts leverage C++ code - and it is very easy to add new C++ code that can be called from Nasal.

History has shown, that most code in FlightGear will eventually be made more configurable and more accessible, this usually happens in the same steps: 1) replacing static variables with variables stored in the property tree, 2) using listeners to get update notifications for important variables, 3) fully exposing a "control" interface by making it accessible it in the property tree, 4) providing scripting hooks.

Even if you should know C or C++ already, Nasal probably remains the most accessible and the most powerful method for customizing the simulator, simply because it is extremely easy and fast to get started, you don't need an "integrated development environment", you don't need to install compilers and you don't need to satisfy any 3rd party dependencies; bottom line being: if you can run FlightGear, you can also run Nasal and create new code.

In addition, Nasal code is fairly abstract code, too. Once you start looking at some existing Nasal scripts, you will see that it is also fairly high level code, much more high level than C++ - so Nasal has a much higher density of code, too. Nasal's role in FlightGear really is like JavaScript's role in Firefox, where it is also used for many/most core-related logics (CSS/XUL).

=== Performance ===

Obviously, C++ code will usually be faster than the corresponding Nasal code. But, while performance is not a design goal, Nasal isn't especially slow either. For example, early benchmarks of the garbage collector showed it as faster than perl's reference counter, and its number crunching performance is on par with python. But in all cases, simplicity, transparency and a sane feature set are preferred over speed in Nasal.

Nasal was specifically designed for use as an extension language in an larger project such as FlightGear. The problem with many otherwise excellent languages in this environment is that they are huge. Perl and python are great, but enormous. Even their "core" interpreters and library code are larger than most projects that require an embedded language. They cannot be readily shipped with their host application and need to be installed system-wide. This is a pain and a compatibility hassle.

The real goal with Nasal is to have a language that supports most "normal" programming idioms (objects, functions, arrays, hashes) while avoiding the bloat that comes from "platform" scripting languages like perl, python, ruby and php.

=== Garbage collection ===
Nasal garbage collects runtime storage, so the programmer need not worry about manual allocation, or even circular references. The current implementation is a simple mark/sweep collector, which should be acceptable for most applications. Future enhancements will include a "return early" capability for latency-critical applications. The collector can be instructed to return after a certain maximum delay, and be restarted later.

As far as speed goes, the last time any benchmarking for Nasal was done, it was about as fast as Perl 5 or Python 2.2 at most things. It's garbage collector was faster, its symbol lookup about the same or slightly faster, and its bytecode interpreter somewhat slower.
i

=== Thread safety ===
Unlike almost all other script interpreters (and unlike the FlightGear/Nasal interface itself) , Nasal is thread safe and scalable when called from multiple CPU threads (as opposed to the userspace interpreter threads implemented by Ruby).

No special treatment is required (as for perl, which clones a separate interpreter with separate data for each thread and uses locking around specifically-designated shared data) and the threads can be scheduled simultaneously. There is no global lock on the interpreter, as used by Python or Lua. The only limit on scalability is garbage collection, which must block all interpreter threads before running.

When running threaded code, Nasal provides "minimal threadsafety", meaning that the interpreter itself can be safely called from multiple CPU threads without risk of corrupting or deadlocking the interpreter internals. Multithreaded operations are therefore "safe", although they are not guaranteed to be atomic. In particular, poorly synchronized insertions into containers can "drop" objects into oblivion (which is OK from an interpreter stability standpoint, since the GC will clean them up normally). Nasal itself provides no synchronization primitives to address this; thread architecture is a "top-level" design job, and Nasal is intended to be an extension language in a larger project. Choice of synchronization mechanisms is going to be highly application dependent.

=== Exception handling ===
Like python, nasal supports exception handling as a first-class language feature, with built-in runtime-inspectable stack trace. Rather like perl, however, there is no special "try" syntax for exception handling, nor inheritance-based catching semantics. Instead, you use the call() builtin to invoke a function object and inspect the results to determine what error was thrown (either with the die() builtin or via an internal runtime error) and what the stack trace looked like. Elaborate exception handling isn't really appropriate for embedded scripting languages.

=== High level programming ===

Thus, programmers already familiar with C++ shouldn't just disregard Nasal as a "toy" that doesn't seem suitable for serious development: some of the more complex Nasal scripts can literally make one's head spin around and it would quite obviously take much more C++ or Java code to implement the same features, while sacrificing all the flexibility and power that a scripting language offers.

Some features can certainly be more easily implemented in Nasal space, than in C++ space. Often, the Nasal solution is "on par" with similar solutions in C++.

=== Accessibility ===

For instance, Nasal code cannot only be easily run and contributed by all users, but it can also be easily reused and maintained by other users. This means, that given the number of active C++ developers, compared to the number of base package contributors, your Nasal code is more likely to be actively maintained by fellow users if it is written in Nasal.

In other words, if there are some experimental features you'd like to explore, Nasal is an excellent way to ensure that other FlightGear '''users''' can easily test your new features. This could be witnessed during the development of the local weather system or the bombable addon,too.

This is in stark contrast to features developed solely in C++ space, because these can usually only be tested by people able to build FlightGear from source, especially if your code isn't yet in the main repository, where it would eventually be available in the form of a binary snapshot.

Obviously, none of this is to say that Nasal is the perfect solution for any problem, there are many things for which Nasal isn't necessarily a perfect choice, such as low level code for example (i.e. rendering).

On the other hand, Nasal really is a powerful tool in FlightGear, and if you find that something should, but cannot, be done in Nasal space, it is extremely easy to add support for new features to the Nasal engine using extension functions or property listeners to trigger C/C++ code.

== Creating new Scripts ==

Nasal scripts need to be plain text files, saved with a *.nas extension.

=== Aircraft specific Nasal code ===

Generally, aircraft specific Nasal scripts reside in the corresponding aircraft's folder (or a corresponding /Nasal subfolder) where they are usually included by adding a corresponding <nasal> tag to the aircraft-set.xml file (see [[Writing_simple_scripts_in_%22nasal%22|Writing simple scripts in "nasal"]]). Also see the section on [[Nasal_scripting_language#Namespaces|namespaces]] which contains more specific examples.

=== Instrument specific Nasal code ===

While instrument specific scripts are saved within the instrument's folder (as previously mentioned, Nasal scripts can also be embedded in various other XML files), Nasal scripts driving shared instruments are generally stored in [[$FG ROOT]]/Aircraft/Generic/

=== Nasal code as bindings in XML files ===
Nasal scripts can also be used as "binding" objects, and can therefore appear anywhere in a configuration file (keyboard, mouse and joystick bindings, etc...) that accepts a <binding> tag. The relevant command type is "nasal", and you place your Nasal code inside of the <script> tag:

<binding>
<command>nasal</command>
<script>
print("Binding Invoked!");
</script>
</binding>

The code above invokes the print() function. This is a simple extension function that simply prints out its arguments, in order, to the FlightGear console as a single-line log entry. It is useful for debugging, but little else.

=== System-wide Nasal code ===

Nasal scripts that are not specific to certain aircraft, instruments or other uses, generally reside in the system-wide [[$FG ROOT]]/Nasal directory.

Nasal scripts that are placed inside [[$FG ROOT]]/Nasal (with a *.nas extension) are automatically loaded and run during FlightGear startup.

=== Nasal sub modules ===

As of 06/2011, FlightGear also supports so called Nasal "sub modules" which may reside in their own sub folder under $FG_ROOT/Nasal/ and which provide support for on-demand loading at runtime by toggling properties.

Some advantages are:

* Nasal files can be grouped neatly instead of all scripts being mixed up in a single fgdata/Nasal directory. Grouping makes a lot of sense for modules consisting of several scripts - local weather is the best example.
* Guaranteed loading sequence. Submodules are loaded _after_ the main fgdata/Nasal scripts, so they can rely on all fgdata/Nasal content to be already present. No more need for awkward listener callbacks, just to make sure that basic "props" or "gui" modules are available.
* Finally, users have the option to disable loading modules. Unfortunately, just loading scripts (code/data) into memory already causes certain _run-time_ performance effects - even if the Nasal code was never executed (so even when all listeners/timers were disabled).

Please note that there is a difference between the _individual_ Nasal files in fgdata/Nasal and files belonging to a common Nasal _module in general (no matter whether loaded at run-time or loaded at start-up using a "<nasal>" tag).

The individual Nasal files in fgdata/Nasal have an own namespace _each_. The namespace get's the name of the Nasal file itself. So if you have a "gui.nas" in the directory, then you can reference a symbol "foo" using "gui.foo".

Nasal modules also have a single namespace. But all files belonging to the module share this _single_ namespace. The name of their namespace is made from its directory (for the run-time loadable modules), or from the specific tag given below the <nasal> XML element, which are often used for a/c specific modules (e.g. <nasal><ufo>...</ufo></nasal> creates the ufo Nasal namespace in ufo-set.xml).

'''So each Nasal file in a new Nasal "module" folder now shares the same namespace.'''

For more information on Nasal sub modules, please see [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg32657.html] and [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg33458.html].

=== User specific Nasal scripts ===

It's also possible to put Nasal files into $FG_HOME/Nasal/, that is: ~/.fgfs/Nasal/ on Unix, and %APPDATA%\flightgear.org\Nasal\ on MS Windows. This has the following advantages:

* one doesn't have to mix local extensions with standard files
* one is less likely to lose such local additions when upgrading
* one doesn't need write permission to $FG_ROOT/Nasal/ or
* one doesn't have to become "root" to edit such files

The files are guaranteed to be read after all the files in $FG_ROOT/Nasal/, so one can safely use elements of files like props.nas (props.Node), or globals.nas (setlistener() without leading underscore).

The files are guaranteed to be read in alphabetic order. So, if there are two files where one depends on the other, just name them appropriately.

The contents of each file are added to a namespace derived from the filename. So, all functions and variables of a file ~/.fgfs/nasal/local.nas will be added to nasal namespace "local", and a function test() is globally accessible as local.test().

It's possible to extend a standard module like "math" with definitions in ~/.fgfs/Nasal/math.nas, though this should, of course, not be exploited by code that is to be submitted to cvs.

== Hello world ==

A simple hello world example in Nasal would be:

# hello.nas
print('Hello World!');

This will show the "Hello World" string during startup in the console window. The hash sign (#) just introduces comments (i.e. will be ignored by the interpreter).

Note: Script-specific symbols such as global variables (or functions) will be put into a scope (namespace) based on the script's name, scripts embedded via aircraft-set.xml files can separately specify a corresponding module name (see [[Howto: Make an aircraft]] for details).

Strings in Nasal can also use double quotes which support escaping:
# hello.nas
print("Hello\nWorld!");

Double quotes support typical escape sequences:

* \n Newline
* \t Horizontal Tab
* \v Vertical Tab
* \b Backspace
* \r Carriage Return
* \f Form feed
* \a Audible Alert (bell)
* \\ Backslash
* \? Question mark
* \' Single quote
* \" Double quote

For example, to print a new line, use:

print ("\n");

To print a quoted string, use:

print ("\"quoted string\"");

and so on.

Single quotes treat everything as literal except for embedded single quotes (including embedded whitespace like newlines).

Nasal strings are always arrays of bytes (never characters: see the utf8 library if you want character-based equivalents of substr() et. al.). They can be indexed just like in C (although note that there is no nul termination -- get the length with size()):

== Editing code files ==

Note that there is currently no way to tell FlightGear to reload Nasal scripts from the global Nasal directory at runtime, so in order to see changes take effect, you will have to exit and restart FlightGear for the time being. Note that there are some workarounds available, see: [[Nasal_scripting_language#Loading.2Freloading_Nasal_code_without_re-starting_Flightgear|reloading Nasal code without re-starting FlightGear]].

Also, note that as of 05/2009, Nasal in FlightGear does not yet support any form of dependency resolution. In other words, there's no "import", "require" or "include" directive - this is also why most code in FlightGear is wrapped inside a _setlistener() call instead, which in turn waits for a FlightGear signal before executing the code (see below for details).

== Variables ==
Nasal scripts should make use of the var keyword when declaring variables. The "var" keyword makes a variable guaranteed to be local. Nasal, natively provides support for scalars (numbers, strings), lists (arrays, vectors) and hashes (objects or dictionaries), more complex data structures (such as trees) can be built using vectors or hashes.

var w=100; # w is a local numerical variable
var x="hello"; # x is a local string variable
var y=[]; # y is a local vector (array)
var z={}; # z is a local hash (dictionary or table) - also used for OOP

Nasal supports a "nil" value for use as a null pointer equivalent:

var foo=nil;

Also, note that Nasal symbols are case-sensitive, these are all different variables:

var show = func(what) {print(what,"\n");}
var abc=1; # these are all different symbols
var ABC=2; # different from abc
var aBc=3; # different from abc and ABC

show(abc);
show(ABC);
show(aBc);

Please note that functions assigned to variables are no exception. If you write code without using "var" on variables, then you risk (often hard to debug) breakage at a later time because you may be overwriting symbols in another namespace.

So functions bound to variables should use the "var" keyword as well:

var hello = func {
print("hello\n");
}

But there's another reason why "var" should be used consequently, even if a variable is safe enough from later side effects, because it has a relatively specific or unique name: The "var" keyword makes
reading code for others (and for the author after some time) easier, as it makes clear: "this variable starts its life *HERE*". No need to search around to see whether assigning a value to it means something to other code outside or not. Also, with an editor offering proper syntax highlighting reading such code is actually easier, despite the "noise".

The problem with nasal code that does not make use of the var keyword is, that it can break other code, and with it the whole system, but no Nasal error message will point you there, as it's syntactically and semantically correct code. Just doing things that it wasn't supposed to do.
For a more in-depth discussion, please see [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg13557.html].

Also, Nasal scripts that are loaded from $FG_ROOT/Nasal are automatically placed inside a namespace that is based on the script's name.

For example, referring to our earlier "Hello World" example, global variables defined in the hello.nas script would be accessible by using "hello" as prefix from other modules:

# hello.nas
var greeting="Hello World"; # define a greeting symbol inside the hello namespace

If you were now to read out the value from the greeting variable from another Nasal module, you would have to use the hello prefix:

# greetme.nas
print(hello.greeting); # the hello prefix is referring to the hello namespace (or module).

==Namespaces==
The Nasal Console built into FlightGear is quite handy when it comes to debugging code. However, here the namespaces need to be considered. In addition, Nasal sub modules (see above) have some special rules, too - basically, all Nasal files part of a "sub module" share a single name space based on the folder's name rather than the name of the individual Nasal files.

For cases of Nasal code specific for an aircraft (like instruments, for example), the corresponding scripts could be loaded through the aircraft's <tt>-set.xml</tt> file by putting it into the <tt><nasal>...</nasal><tt> section

<nasal>
...
<moduleA>
<file>path/to/file1.nas</file>
<file>path/to/file2.nas</file>
</moduleA>
<moduleB>
<file>path/to/file3.nas</file>
</moduleB>
</nasal>

In this case, variables in files <tt>path/to/file1.nas</tt> and <tt>path/to/file2.nas</tt> can be used in the Nasal console as

moduleA.varName;

Variables in <tt>path/to/file3.nas</tt> can be accessed as

moduleB.varName;

Please note that Nasal sub modules (i.e. files loaded and run from their own Nasal sub directory), are subject to some special rules, as all Nasal source files are automatically loaded into the same namespace, which is by default based on the sub module's folder name.

'''''More information can be found by clicking [http://wiki.flightgear.org/Namespaces_and_Methods here].'''''

== Variables - Advanced Uses ==

Nasal, also supports Multi-assignment expressions. You can assign more than one variable (or lvalue) at a time by putting them in a parenthesized list:

(var a, var b) = (1, 2);
var (a, b) = (1, 2); # Shorthand for (var a, var b)
(var a, v[0], obj.field) = (1,2,3) # Any assignable lvalue works
var color = [1, 1, 0.5];
var (r, g, b) = color; # works with runtime vectors too

Vectors (lists or arrays) can be created from others using an ordered list of indexes and ranges.
This is usually called "vector slicing".
For example:

var v1 = ["a","b","c","d","e"]
#
var v2 = v1[3,2]; # == ["d","c"];
var v3 = v1[1:3]; # i.e. range from 1 to 3: ["b","c","d"];
var v4 = v1[1:]; # no value means "to the end": ["b","c","d","e"]
var i = 2;
var v5 = v1[i]; # runtime expressions are fine: ["c"]
var v6 = v1[-2,-1]; # negative indexes are relative to end: ["d","e"]

The range values can be computed at runtime (e.g. i=1; v5=v1[i:]). Negative indices work the same way they do with the vector functions (-1 is the last element, -2 is 2nd to last, etc...).

== Storage: property tree vs. Nasal ==
With FlightGear's built-in property tree and Nasal's support for it, there are two obvious, and two somewhat competing, ways for storing scalar data: native Nasal variables and FlightGear properties, both of which can be easily accessed and managed from Nasal.

The advantage to native Nasal-space data is that it's fast and simple. If the only thing that will care about the value is your script, they are good choices.

The property tree is an inter-subsystem communication thing. This is what you want if you want to share data with the C++ world (for example, YASim <control-output> tags write to properties -- they don't understand Nasal), or read in via configuration files.

Also, native Nasal data structures are usually far faster than their equivalent in property tree space. This is because there are several layers of indirection in retrieving a property tree value.

In general, this means that you shouldn't make overly excessive use of the property tree for storing state that isn't otherwise relevant to FlightGear or any of its subsystems. Doing that would in fact have adverse effects on the performance of your code. In general, you should favor Nasal variables and data structures and should only make use of properties to interface with the rest of FlightGear, or to easily provide debugging information at run time.

As of FG 2.4.0, retrieving a value from the property tree via getprop is about 50% slower than accessing a native Nasal variable, and accessing the value via node.getValue() is 10-20% slower yet. This is an insignificant amount of time if you are retrieving and storing a few individual values from the property tree, but adds up fast if you are storing or retrieving hashes or large amounts of data. (You can easily benchmark times on your own code using systime() or debug.benchmark.)

In addition, it is worth noting that the Nasal/FlightGear APIs cannot currently be considered to be thread safe, this mean that -at least for now- the explicit use of pure Nasal space variables is the only way to exploit possible parallelism in your code by making use of threads.

== Functions ==

=== What is a function ? ===

A "function" is a piece of code that can be easily used repeatedly (without repeating the same code over and over again), this is achieved by associating a symbolic name with the piece of code, such as "print", "show" or "get" for example. Whenever this symbolic name is then used in the program, the program will "jump" to the definition of the function and start running it, once the called function has completed it will automatically return to the instruction following the call.

By using so called "function arguments" (see below) it is possible to parametrize a function (using variables) so that it may use data that is specific to each invocation.

As previously shown, Nasal functions are implemented using the func keyword, The following snippet of code defines a new function named "log_message" with an empty function body (the curly braces).

var log_message = func {}

=== Function bodies ===

To add a function body, you need to add code in between these curly braces.

=== Anonymous function arguments ===

In Nasal, arguments are by default passed in the "arg" array, not unlike perl. To understand how this works, you should probably first read up on Nasal vectors.

var log_message = func {
print(arg[0]);
}

Note that this is equivalent to:

var log_message = func() {
print(arg[0]);
}

In other words, the argument list "()" can be omitted if it is empty.
However, if you are new to Nasal or programming in general, it is probably a good idea to ALWAYS use parentheses, i.e. also for functions with empty argument lists - that makes it easy to get used to the syntax.

Note that this is just an assignment of an (anonymous) function argument to the local "log_message" variable. There is no function declaration syntax in Nasal.

Also, Nasal being a functional programming language, all passed arguments will be local to the corresponding scope. If you want to modify state in a function, you'll preferably return new state to the caller.

===Named function arguments===
You can also pass named arguments to a function, thus saving the typing and performance costs of extracting them from the arg array:

var log_message = func(msg) {
print(msg);
}

The list of function arguments is called a function's "signature".

=== Default values for function arguments ===

Function arguments can have default values, as in C++. Note that the default value must be a scalar (number, string, function, nil) and not a mutable composite object (list, hash).

var log_message = func(msg="error") {
print(msg);
}

If some arguments have default values and some do not, those with default values must come first in the argument list:

#Incorrect:
var log_message = func(msg="error", line, object="ground") { #some code }

#Correct:
var log_message = func(msg="error", object="ground", line) { #some code }

Any extra arguments after the named list are placed in the "arg" vector as above. You can rename this to something other than "arg" by specifying a final argument name with an ellipsis:

listify = func(elements...) { return elements; }
listify(1, 2, 3, 4); # returns a list: [1, 2, 3, 4]

=== Returning from functions ===

In Nasal, functions return implicitly the values of the last expression (i.e. "nil" in empty function bodies), you can also add an explicit "return" statement, for example to leave a function early. In addition, it is possible to return values, too.

So, semantically, the previous snippet of code is equivalent to these:

var log_message = func {return;}

var log_message = func {nil;}

var log_message = func {};

var log_message = func return;

var log_message = func nil;

===Named arguments in function calls===
Nasal supports named function arguments in function calls, too.

As an alternative to the comma-separated list of ''positional'' function arguments, you can specify a hash literal in place of ordered function arguments, and it will become the local variable namespace for the called function, with variables named according to the hash indexes and with values according to the hash values. This makes functions with many arguments more readable.

And it also makes it possible to call function's without having to take care of the right order of passing arguments.

Examples:
#if we have functions defined:
var log_message = func (msg="") { #some code to log variable msg }
var lookat = func (heading=0, pitch=0, roll=0, x=nil, y=nil, z=nil, time=hil, fov=20) { #some code using those variables }

#we can use them them the usual way with comma separated list of arguments:
log_message("Hello World!");
lookat (180, 20, 0, XO, YO, ZO, now, 55);

#or we can use the hash literal arguments instead:
log_message(msg:"Hello World!");
lookat(heading:180, pitch:20, roll:0, x:X0, y:Y0, z:Z0,time:now, fov:55);

Both methods for calling the functions above are equivalent, but note the the second method is more readable, less prone to error, and self-documenting in the code for the function call.

As another example, consider:

var setPosition = func (latitude_deg, longitude_deg, altitude_ft) {
# do something here
}
# the actual function call:
setPosition( latitude_deg:34.00, longitude_deg:7.00, alt_ft:10000);

In other words, such function calls become much more self-explanatory because everybody can see immediately what a value is doing.
This is a good practice, as you may eventually have to take a longer break, away from your code - and then even you yourself will come to appreciate such small things that make code more intuitive to work with.

Declared arguments are checked and defaulted as would be expected: it's an error if you fail to pass a value for an undefaulted argument, missing default arguments get assigned as usual, and any rest parameter (e.g. "func(a,b=2,rest...){}") will be assigned with an empty vector.

===Nested functions, implicit return ===
Also, Nasal functions can be easily nested, for example:

var calculate = func(param1,param2,operator) {
var add = func(p1,p2) {p1+p2;}
var sub = func(p1,p2) {p1-p2;}
var mul = func(p1,p2) {p1*p2;}
var div = func(p1,p2) {p1/p2;}
if (operator=="+") return add(param1,param2);
if (operator=="-") return sub(param1,param2);
if (operator=="*") return mul(param1,param2);
if (operator=="/") return div(param1,param2);
}

Note that the add,sub,mul and div functions in this example do not make use of an explicit return statement, instead the result of each expression is implicitly returned to the caller.

Nasal functions that just consist of such simple expressions can also be further simplified to read:

var add = func(val1,val2) val1+val2;

=== Function overloading ===

Note that Nasal functions can generally not be [[http://en.wikipedia.org/wiki/Function_overloading overloaded]], and that operator overloading in particular is also not supported.

However, the effects of '''function overloading''' can obviously be implemented individually by each function, simply by processing the number and type of passed arguments at the start of the function body. The FlightGear code base contains a number of examples for this, i.e. it is for example possible to pass properties in the form of plain strings to a callback or in the form of a Nasal wrapper like props.Node.

So this can be accomplished by first checking the argument count and then the types of arguments passed to the function.

To provide an example, here's a simple function to multiply two numbers, no matter if they are provided as scalars, as a vector or as x/y members of a hash:

var multiply2 = func (params) {
if (typeof(params)=="scalar") return params*arg[0];
if (typeof(params)=="vector") return params[0]*params[1];
if (typeof(params)=="hash") return params.x*params.y;
die("cannot do what you want me to do");
}

So, now you have a very simple form of an "overloaded" function that supports different argument types and numbers:

multiply2( 2,6); # multiply two scalars
multiply2( [5,7] ); # multiply two scalars stored in a vector
multiply2( {x:8, y:9} ); # multiply two scalars stored in a hash

You could obviously extend this easily to support an arbitrary number of arguments by just using a for loop here.

As you can see, the basic idea is pretty simple and also scalable, you could easily extend this to and also return different types of values, such as vectors or hashes. This could for example be used to create wrappers in Nasal space for doing 3D maths, with vectors and matrices, so that a matrix multiplication could return a new matrix, too.

===Functional programming, higher order functions, generators;===
As previously mentioned, arguments to a Nasal function can also be functions themselves (Nasal being a functional programming language), this means that Nasal functions are higher order functions so that you can easily pass and return functions to and from Nasal functions. This can for example be used to dynamically create new functions (such functions are commonly called 'generators'):

# a function that returns a new custom function
var i18n_hello = func(hello) {
return func(name) { # returns an anonymous/unnamed function
print(hello,name);
}
}

# create three new functions
var english_hello = i18n_hello("Good Day ");
var spanish_hello = i18n_hello("Buenos Dias ");
var italian_hello = i18n_hello("Buon giorno ");

# actually call these functions
english_hello("FlightGear");
spanish_hello("FlightGear");
italian_hello("FlightGear");

=== Using helper functions ===

It is possible to simplify complex function calls by introducing small helper functions, for example consider:

var l = thermalLift.new(ev.lat, ev.lon, ev.radius, ev.height, ev.cn, ev.sh, ev.max_lift, ev.f_lift_radius);

So, you could just as well create a small helper function named"thermalLift.new_from_ev(ev)":

thermalLift.new_from_ev = func (ev) {
thermalLift.new(ev.lat, ev.lon, ev.radius, ev.height, ev.cn, ev.sh, ev.max_lift, ev.f_lift_radius);
}

var l=thermalLift.new_from_ev(ev);

Note that the expression to invoke your code would then also become less complicated and much more comprehensible.

When you have expressions of nested method calls, such as:

t.getNode("latitude-deg").setValue(f.getNode("latitude-deg").getValue());
t.getNode("longitude-deg").setValue(f.getNode("longitude-deg").getValue());

You could just as easily introduce a small helper function to wrap the code, that would be less typing for you, less code to read (and understand) for others and generally it would help localize functionality (and possible errors):

var copyNode = func(t,f,path) t.getNode(path).setValue(f.getNode(path).getValue());

So you would simply take the complex expression and generalize it by adding variables that you pass in from a function object, then you could simply call your new function like this:

copyNode(t,f,"latitude-deg");
copyNode(t,f,"longitude-deg");

or:

foreach(var p; ["latitude-deg", "longitude-deg","generated-flag"])
copyNode(t,f,p);

or as a complete function accepting a vector of properties:

var copyNode = func(target,source,properties) {
if (typeof(properties)!="vector") properties=[properties];
if (typeof(target)!="hash") target=props.globals.getNode(target);
if (typeof(source)!="hash") target=props.globals.getNode(source)
foreach(var path; properties)
target.getNode(path).setValue( source.getNode(path).getValue() );
}

copyNode("/temp/test", "/position", ["latitude-deg", "longitude-deg", "altitude-ft"]);

Whenever you have very similar lines of code that seem fairly repetitive, it is a good idea to consider introducing small helper functions. You can use plenty of small helper functions and then just "chain" them together, rather than using complex nested expressions that make your head spin.

== Conditionals ==

Nasal has no "statements", which means that any expression can appear in any context. This means that you can use an if/else clause to do what the ?: does in C.
The last semicolon in a code block is optional, to make this prettier

abs = func(n) { if(n<0) { -n } else { n } }

But for those who don't like typing, the ternary operator works like you expect:

abs = func(n) { n < 0 ? -n : n }

In addition, Nasal supports braceless blocks, like they're known from C/C++ and other languages:

var foo=1;
if (foo)
print("1\n");
else
print("0\n");
print("this is printed regardless\n")

Instead of a switch statement one can use

if (1==2) {
print("wrong");
} else if (1==3) { # NOTE the space between else and if
print("wronger");
} else {
print("don't know");
}

which produces the expected output of <code>don't know</code>

The <tt>nil</tt> logic is actually quite logical, let's just restate the obvious:

if (nil) {
print("This should never be printed");
} else {
print("This will be printed, because nil is always false");
};

Nasal's binary boolean operators are "and" and "or", unlike C. unary not is still "!" however.
They short-circuit like you expect

var toggle = 0;
var a = nil;
if(a and a.field == 42) {
toggle = !toggle; # doesn't crash when a is nil
}

You can easily reduce the complexity of huge conditional (IF) statements, such as this one:

if (a==1) function_a();
else
if (a==2) function_b();
else
if (a==3) function_c();
else
if (a==4) function_d();
else
if (a==5) function_e();

.. just by using the variable as a key (index) into a hash, so that you can directly call the corresponding function:

var mapping = {1:function_a, 2:function_b, 3:function_c, 4:function_d,5:function_e};
mapping[a] ();

This initializes first a hash map of values and maps a function "pointer" to each value, so that accessing mapping[x] will return the function pointer for the key "x".

Next, you can actually call the function by appending a list of function arguments (empty parentheses for no args) to the hash lookup.

Using this technique, you can reduce the complexity of huge conditional blocks. For example, consider:

# weather_tile_management.nas
460 if (code == "altocumulus_sky"){weather_tiles.set_altocumulus_tile();}
461 else if (code == "broken_layers") {weather_tiles.set_broken_layers_tile();}
462 else if (code == "stratus") {weather_tiles.set_overcast_stratus_tile();}
463 else if (code == "cumulus_sky") {weather_tiles.set_fair_weather_tile();}
464 else if (code == "gliders_sky") {weather_tiles.set_gliders_sky_tile();}
465 else if (code == "blue_thermals") {weather_tiles.set_blue_thermals_tile();}
466 else if (code == "summer_rain") {weather_tiles.set_summer_rain_tile();}
467 else if (code == "high_pressure_core") {weather_tiles.set_high_pressure_core_tile();}
468 else if (code == "high_pressure") {weather_tiles.set_high_pressure_tile();}
469 else if (code == "high_pressure_border") {weather_tiles.set_high_pressure_border_tile();}
470 else if (code == "low_pressure_border") {weather_tiles.set_low_pressure_border_tile();}
471 else if (code == "low_pressure") {weather_tiles.set_low_pressure_tile();}
472 else if (code == "low_pressure_core") {weather_tiles.set_low_pressure_core_tile();}
473 else if (code == "cold_sector") {weather_tiles.set_cold_sector_tile();}
474 else if (code == "warm_sector") {weather_tiles.set_warm_sector_tile();}
475 else if (code == "tropical_weather") {weather_tiles.set_tropical_weather_tile();}
476 else if (code == "test") {weather_tiles.set_4_8_stratus_tile();}
477 else ...

While this is not a very complex or huge block of code, it is an excellent example for very good naming conventions used already, because the consistency of naming variables and functions can pay off easily here, with just some very small changes, you can already reduce the whole thing to a hash lookup like this:

weather_tiles["set_"~code~"_tile"](); # naming convention

This would dynamically concatenate a key consisting of "set_" + code + "_title" into the hash named weather_tiles, and then call the function that is returned from the hash lookup.

So for this to work you only need to enforce consistency when naming your functions (i.e. this would of course CURRENTLY fail when the variable code contains "test" because there is no such hash member (it's "4_8_stratus" instead).

The same applies to cumulus sky (fair weather), stratus/overcast stratus.

But these are very simple changes to do (just renaming these functions to match the existing conventions). When you do that, you can easily replace such huge IF statements and replace them with a single hash lookup and function call:

hash[key] (arguments...);

For example, consider:

var makeFuncString = func(c) return tolower("set_"~c~"_tile");
var isFunc = func(f) typeof(f)=='func';
var hasMethod = func(h,m) contains(h,m) and isFunc;
var callIfAvailable = func(hash, method, unavailable=func{} ) {
var c=hasMethod(hash,makeFuncString(m) ) or unavailable();
hash[makeFuncString(m)] ();
}
callIfAvailable( weather_tiles,code, func {die("key not found in hash or not a func");} );

== Initializing data structures ==

There are some more possibilities to increase the density of your code, such as by removing redundant code or by generalizing and refactoring existing code so that it can be reused in different places (i.e. avoiding duplicate code):

For example see weather_tile_management.nas #1000 (create_neighbours function):

1008 x = -40000.0; y = 40000.0;
1009 setprop(lw~"tiles/tile[0]/latitude-deg",blat + get_lat(x,y,phi));
1010 setprop(lw~"tiles/tile[0]/longitude-deg",blon + get_lon(x,y,phi));
1011 setprop(lw~"tiles/tile[0]/generated-flag",0);
1012 setprop(lw~"tiles/tile[0]/tile-index",-1);
1013 setprop(lw~"tiles/tile[0]/code","");
1014 setprop(lw~"tiles/tile[0]/timestamp-sec",weather_dynamics.time_lw);
1015 setprop(lw~"tiles/tile[0]/orientation-deg",alpha);
1016
1017 x = 0.0; y = 40000.0;
1018 setprop(lw~"tiles/tile[1]/latitude-deg",blat + get_lat(x,y,phi));
1019 setprop(lw~"tiles/tile[1]/longitude-deg",blon + get_lon(x,y,phi));
1020 setprop(lw~"tiles/tile[1]/generated-flag",0);
1021 setprop(lw~"tiles/tile[1]/tile-index",-1);
1022 setprop(lw~"tiles/tile[1]/code","");
1023 setprop(lw~"tiles/tile[1]/timestamp-sec",weather_dynamics.time_lw);
1024 setprop(lw~"tiles/tile[1]/orientation-deg",alpha);
1025
1026 x = 40000.0; y = 40000.0;
1027 setprop(lw~"tiles/tile[2]/latitude-deg",blat + get_lat(x,y,phi));
1028 setprop(lw~"tiles/tile[2]/longitude-deg",blon + get_lon(x,y,phi));
1029 setprop(lw~"tiles/tile[2]/generated-flag",0);
1030 setprop(lw~"tiles/tile[2]/tile-index",-1);
1031 setprop(lw~"tiles/tile[2]/code","");
1032 setprop(lw~"tiles/tile[2]/timestamp-sec",weather_dynamics.time_lw);
1033 setprop(lw~"tiles/tile[2]/orientation-deg",alpha);
1034
1035 x = -40000.0; y = 0.0;
1036 setprop(lw~"tiles/tile[3]/latitude-deg",blat + get_lat(x,y,phi));
1037 setprop(lw~"tiles/tile[3]/longitude-deg",blon + get_lon(x,y,phi));
1038 setprop(lw~"tiles/tile[3]/generated-flag",0);
1039 setprop(lw~"tiles/tile[3]/tile-index",-1);
1040 setprop(lw~"tiles/tile[3]/code","");
1041 setprop(lw~"tiles/tile[3]/timestamp-sec",weather_dynamics.time_lw);
1042 setprop(lw~"tiles/tile[3]/orientation-deg",alpha);
1043
1044 # this is the current tile
1045 x = 0.0; y = 0.0;
1046 setprop(lw~"tiles/tile[4]/latitude-deg",blat + get_lat(x,y,phi));
1047 setprop(lw~"tiles/tile[4]/longitude-deg",blon + get_lon(x,y,phi));
1048 setprop(lw~"tiles/tile[4]/generated-flag",1);
1049 setprop(lw~"tiles/tile[4]/tile-index",1);
1050 setprop(lw~"tiles/tile[4]/code","");
1051 setprop(lw~"tiles/tile[4]/timestamp-sec",weather_dynamics.time_lw);
1052 setprop(lw~"tiles/tile[4]/orientation-deg",getprop(lw~"tmp/tile-orientation-deg"));
1053
1054
1055 x = 40000.0; y = 0.0;
1056 setprop(lw~"tiles/tile[5]/latitude-deg",blat + get_lat(x,y,phi));
1057 setprop(lw~"tiles/tile[5]/longitude-deg",blon + get_lon(x,y,phi));
1058 setprop(lw~"tiles/tile[5]/generated-flag",0);
1059 setprop(lw~"tiles/tile[5]/tile-index",-1);
1060 setprop(lw~"tiles/tile[5]/code","");
1061 setprop(lw~"tiles/tile[5]/timestamp-sec",weather_dynamics.time_lw);
1062 setprop(lw~"tiles/tile[5]/orientation-deg",alpha);
1063
1064 x = -40000.0; y = -40000.0;
1065 setprop(lw~"tiles/tile[6]/latitude-deg",blat + get_lat(x,y,phi));
1066 setprop(lw~"tiles/tile[6]/longitude-deg",blon + get_lon(x,y,phi));
1067 setprop(lw~"tiles/tile[6]/generated-flag",0);
1068 setprop(lw~"tiles/tile[6]/tile-index",-1);
1069 setprop(lw~"tiles/tile[6]/code","");
1070 setprop(lw~"tiles/tile[6]/timestamp-sec",weather_dynamics.time_lw);
1071 setprop(lw~"tiles/tile[6]/orientation-deg",alpha);
1072
1073 x = 0.0; y = -40000.0;
1074 setprop(lw~"tiles/tile[7]/latitude-deg",blat + get_lat(x,y,phi));
1075 setprop(lw~"tiles/tile[7]/longitude-deg",blon + get_lon(x,y,phi));
1076 setprop(lw~"tiles/tile[7]/generated-flag",0);
1077 setprop(lw~"tiles/tile[7]/tile-index",-1);
1078 setprop(lw~"tiles/tile[7]/code","");
1079 setprop(lw~"tiles/tile[7]/timestamp-sec",weather_dynamics.time_lw);
1080 setprop(lw~"tiles/tile[7]/orientation-deg",alpha);
1081
1082 x = 40000.0; y = -40000.0;
1083 setprop(lw~"tiles/tile[8]/latitude-deg",blat + get_lat(x,y,phi));
1084 setprop(lw~"tiles/tile[8]/longitude-deg",blon + get_lon(x,y,phi));
1085 setprop(lw~"tiles/tile[8]/generated-flag",0);
1086 setprop(lw~"tiles/tile[8]/tile-index",-1);
1087 setprop(lw~"tiles/tile[8]/code","");
1088 setprop(lw~"tiles/tile[8]/timestamp-sec",weather_dynamics.time_lw);
1089 setprop(lw~"tiles/tile[8]/orientation-deg",alpha);
1090 }

At first glance, this seems like a fairly repetitive and redundant block of code, so it could probably be simplified easily:

var create_neighbours = func (blat, blon, alpha) {
var phi = alpha * math.pi/180.0;
calc_geo(blat);
var index=0;
var pos = [ [-40000.0,40000.0], [0.0, 40.000], [40000.0, 40000.0], [-40000, 0], [0,0], [40000,0], [-40000,-40000], [0,-40000], [40000,-40000] ];
foreach (var p;pos) {
x=p[0]; y=p[1];
setprop(lw~"tiles/tile[index]/latitude-deg",blat + get_lat(x,y,phi));
setprop(lw~"tiles/tile[index]/longitude-deg",blon + get_lon(x,y,phi));
setprop(lw~"tiles/tile[index]/generated-flag",0);
setprop(lw~"tiles/tile[index]/tile-index",-1);
setprop(lw~"tiles/tile[index]/code","");
setprop(lw~"tiles/tile[index]/timestamp-sec",weather_dynamics.time_lw);
setprop(lw~"tiles/tile[index]/orientation-deg",alpha);
index=index+1;
}
}

== Loops ==

Nasal has several ways to implement an iteration.

===for, while, foreach, and forindex loops===
Nasal's looping constructs are mostly C-like:

for(var i=0; i < 3; i = i+1) {
# loop body
}

while (condition) {
# loop body
}

The differences are that there is no do{}while(); construct, and there is a foreach, which takes a local variable name as its first argument and a vector as its second:

foreach(elem; list1) { doSomething(elem); } # NOTE: the delimiter is a SEMICOLON ;

The hash/vector index expression is an lvalue that can be assigned as well as inspected:

foreach(light; lights) { lightNodes[light] = propertyPath; }

To walk through all elements of a hash, for a foreach loop on the keys of they hash. Then you call pull up the values of the hash using the key. Example:

myhash= {first: 1000, second: 250, third: 25.2 };
foreach (var i; keys (myhash)) {
#multiply each value by 2:
myhash[i] *= 2;
#print the key and new value:
print (i, ": ", myhash[i]);
}

There is also a "forindex", which is like foreach except that it assigns the index of each element, instead of the value, to the loop variable.

forindex(i; list1) { doSomething(list1[i]); }

Also, braceless blocks work for loops equally well:

var c=0;
while( c<5 )
print( c+=1 );
print("end of loop\n");

===settimer loops===
Loops using <tt>while</tt>, <tt>for</tt>, <tt>foreach</tt>, and <tt>forindex</tt> block all of FlightGear's subsystems that run in the main thread, and can, thus, only be used for instantaneous operations that don't take too long.

For operations that should continue over a longer period, one needs a non-blocking solution. This is done by letting functions call themselves after a timed delay:

var loop = func {
print("this line appears once every two seconds");
settimer(loop, 2);
}

loop(); # start loop

Note that the <tt>settimer</tt> function expects a ''function object'' (<tt>loop</tt>), not a function call (<tt>loop()</tt>) (though it is possible to make a function call return a function object--an advanced functional programming technique that you won't need to worry about if you're just getting started with Nasal).

The fewer code FlightGear has to execute, the better, so it is desirable to run loops only when they are needed. But how does one stop a loop? A once triggered timer function can't be revoked. But one can let the loop function check an outside variable and refuse calling itself, which makes the loop chain die off:

var running = 1;
var loop = func {
if (running) {
print("this line appears once every two seconds");
settimer(loop, 2);
}
}

loop(); # start loop ...
...
running = 0; # ... and let it die

Unfortunately, this method is rather unreliable. What if the loop is "stopped" and a new instance immediately started again? Then the ''running'' variable would be ''1'' again, and a pending old loop call, which should really finish this chain, would happily continue. And the new loop chain would start, too, so that we would end up with two loop chains.

This can be solved by providing each loop chain with a ''loop identifier'' and letting the function end itself if the id doesn't match the global loop-id. Self-called loop functions need to inherit the chain id. So, every time the global loop id is increased, all loop chains die, and a new one can immediately be started.

var loopid = 0;
var loop = func(id) {
id == loopid or return; # stop here if the id doesn't match the global loop-id
...
settimer(func { loop(id) }, 2); # call self with own loop id
}

loop(loopid); # start loop
...
loopid += 1; # this kills off all pending loops, as none can have this new identifier yet
...
loop(loopid); # start new chain; this can also be abbreviated to: loop(loopid += 1);

[[Nasal_scripting_language#settimer.28.29|More information about the settimer function is below]]

== OOP - Object Oriented Programming ==

In Nasal, objects ("classes") are regular hashes. Self-reference and inheritance are implemented through special variables <tt>me</tt> and <tt>parents</tt>. To get a better understanding of the concept, let's start with the very basics.

=== Hashes ===

Hashes, also known as "dictionaries" in Python or "maps" in C++/STL are data structures that hold key/value pairs in a way that allows quick access to a value via its key.

var airport = {
"LOXZ": "Zeltweg",
"LOWI": "Innsbruck",
"LOXL": "Linz Hoersching", # the last comma is optional
};

print(airport["LOXZ"]); # prints "Zeltweg"
airport["LOXA"] = "Aigen"; # adds LOXA to the hash

The built-in function keys() returns a vector with the keys of the hash. The function values() returns a vector with the values of the hash. For example:

debug.dump (keys(airport)); #prints ['LOXZ', 'LOWI', 'LOXL']
debug.dump (values (airport)); #prints ['Zeltweg', 'Innsbruck', 'Linz Hoersching']

The quotes around keys can be left away in a hash definition if the key is a valid variable name or a number. This works just as well:

var airport = {
LOXZ: "Zeltweg",
};

There's also an alternative way to access hash members if the keys are valid variable names: <tt>airport.LOXI</tt> can be used instead of <tt>airport["LOXI"]</tt>. There is a difference, though, which is described in the next section.

Note that assigning a hash (or a vector) to another variable does never ''copy'' the contents. It only creates another reference to the same data structure. So manipulating the hash via its new name does in fact change the one, original hash.

var a = airport;
a.LOXL = "Linz"; # same as airport.LOXL!
print(airport.LOXL); # prints now "Linz", not "Linz Hoersching"

(True copies of vectors can be made by assigning a full slice: <tt>var copy = vec[:]</tt>. There's no such method for hashes.)

=== Self-reference: "<tt>me</tt>" ===

Values stored in a hash can be of any type, even of type ''function''. Member functions ("methods") can reference their own enclosing hash via reserved keyword <tt>me</tt>. This is comparable to the <tt>this</tt> keyword in C++ classes, or the <tt>self</tt> keyword in Python.

var value = "test";

var data = {
value: 23, # scalar member variable
write1: func { print(value); }, # function member
write2: func { print(me.value); }, # function member
};

data.write1(); # prints "test"
data.write2(); # prints 23

The above example is already a simple form of an object. It has its own variable namespace (''data''), its own methods, and it can be passed around by-reference as one unit. Such classes are sometimes called ''singleton classes'', as they are unique, with no independent class instances. They mostly serve as a way to keep data and methods nicely encapsulated within a Nasal module. Often they contain a method for initializing, which is usually called <tt>init</tt>.

=== Inheritance: "<tt>parents</tt>" ===

What we learned about <tt>me</tt> in the last section is only half the truth. "me" doesn't only reference an object's own hash, but also one or more parent hashes. <tt>parents</tt> is another reserved keyword. It denotes a vector referencing other object hashes, which are "inherited" that way.

Please note that Nasal's currently supported form of encapsulation does not provide support for any form of data/information hiding (restricting access), i.e. all hash fields (but also all hash methods) are always publicly accessible (so there's nothing like the "private" or "protected" keywords in C++: in this sense, Nasal's inheritance mechanism can be thought of like C++ structs which are also public by default).

The major difference being, that all members (functions and fields) are also always '''mutable''', which means that functions can modify the behavior of other functions quite easily, this also applies to the parents vector, too.

var parent_object = {
value: 123,
};

var object = {
parents: [parent_object],
write: func { print(me.value) },
};

object.write(); # prints 123

Even though <tt>object</tt> itself doesn't contain a member <tt>value</tt>, it finds and uses the one of its parent object. <tt>parents</tt> is a vector that can contain several parent objects. These are then searched in the order from left to right, until a matching member variable or method is found. Each of the parents can itself have parents, which are all recursively searched.

In the section about hashes it was said that hash members can be accessed in two alternative ways, and that's also true for methods. <tt>object.write()</tt> could also be called as <tt>object["write"]()</tt>. But only in the first form will members also be searched in parent hashes if not found in the base hash, whereas the second form creates an error if it's not a direct member.

=== Creating class instances ===

With <tt>me</tt> and <tt>parents</tt> we can implement a class object and create independent instances from that:

var Class = {
write: func { print(me.value); },
increment: func { me.value += 1; },
};

var instance1 = { parents: [Class], value: 123 };
var instance2 = { parents: [Class], value: 456 };

instance1.write(); # prints 123
instance2.write(); # prints 456

As you can see, the two class instances are separate, independent objects, which share another object as parent -- they "inherit" from object <tt>Class</tt>. One can now easily change members of any of these three objects. The following will redefine the parent's <tt>write</tt> method, and all instances will automatically use this new version:

Class.write = func { print("VALUE = " ~ me.value) }

But one can also add a method to just one instance:

instance1.write = func { print("VALUE = " ~ me.value) }

Because <tt>instance1</tt> does now have its own <tt>write</tt> method, the parents won't be searched for one, so <tt>Class.write</tt> is now overridden by <tt>instance1</tt>'s own method. Nothing changed for <tt>instance2</tt> -- it will still only find and use <tt>Class.write</tt> via its parent.

Note, the we couldn't create a class instance by simple assignment, because, as we learned above, this wouldn't create a separate copy of the Class object. All "instances" would reference the same hash!

var bad_instance1 = Class; # bad
var bad_instance2 = Class; # bad

bad_instance1.value = 123; # sets Class.value to 123
bad_instance2.value = 456; # sets Class.value to 456

bad_instance1.write(); # prints 456, not 123

=== Constructor ===

Defining each class instance by explicitly creating a hash with parents is clumsy. It is nicer to have a function that does that for us. Then we can also use function arguments to initialize members of this instance.

var new_class = func(val) {
return { parents: [Class], value: val };
}

var instance1 = new_class(123);
var instance2 = new_class(456);

instance1.write(); # prints 123
instance2.write(); # prints 456

Because the class generating function <tt>new_class()</tt> really belongs to class <tt>Class</tt>, it would be nicer to put it into the class hash as well. In this case we call it a class "constructor", and as a convention, give it the name ''new''. It could have any name, though, and there could be more than one constructor.

var Class = {
new: func(val) {
return { parents: [Class], value: val };
},
write: func {
print("VALUE=" ~ me.value);
},
};

var instance1 = Class.new(123);
var instance2 = Class.new(456);

As you can see, <tt>new()</tt> doesn't return a copy of <tt>Class</tt>, but rather a small hash that contains only a list of parents and one individual member <tt>value</tt>.

Classes aren't always as simple as in our example. Usually they contain several members, of which some may have yet to be calculated in the constructor. In that case it's easier to create a local object hash first, and to let the constructor finally return it. Such local hashes are often named <tt>m</tt> (as a short reference to <tt>me</tt>), or <tt>obj</tt>.

var Class = {
new: func(val) {
var m = { parents: [Class] };
m.value = val;
return m;
},
write: func {
print("VALUE=" ~ me.value);
},
};

This last example is the most frequently used form of class definitions in FlightGear-Nasal.

=== Destructor ===

There's no such thing in Nasal. In other languages destructors are automatically called when the class gets destroyed, so that memory and other resources that were allocated by the constructor can be freed. In Nasal that's all done by the Garbage Collector (GC), anyway. In the FlightGear context, however, there ''are'' resources that should get freed. Listeners should get removed, self-calling functions ("loops") stopped. For that it's recommended to create a destructor function and to call that manually. Such functions are often called <tt>del</tt>, similar to Python and to pair nicely with the three-letter constructor name <tt>new</tt>.

=== Memory management ===

Finally, as you know now, Nasal, being a dynamic programming language, doesn't require or support any manual memory management, so unlike C++, you don't need to call operators like "new" or "delete" to allocate or free your memory.

However, if you do know that you don't need a certain variable anymore, you can certainly give a hint to the built-in garbage collector to free it, by assigning a "nil" value to it.

This can certainly pay off when using more complex data structures such as nested vectors or hashes, because it will tell the built-in garbage collector to remove all references to the corresponding symbols, so that they can be freed.

It is also possible to make use of Nasal's delete() function to remove a symbol from a namespace (hash).

So, if you are concerned about your script's memory requirements, using a combination of setting symbols to nil, or deleting them as appropriate, would allow you to create helper functions for freeing data structures easily.

In addition, it is probably worth noting that this is also the only way to sanely reset an active Nasal namespace or even the whole interpreter. You need to do this in order to reload or re-initialize your code without restarting the whole FlightGear session [[Nasal_scripting_language#Managing_timers_and_listeners]].

Obviously, you should first of all ensure that there is no more code running, this includes any registered listeners or timers, but also any others loops or recursive functions.

Thus, if you'd like to reload a Nasal source file at run time, you should disable all running code, and then reset the corresponding namespace, too. This is to ensure that you get a clean and consistent namespace.

Nasal provides a number of core library functions to manipulate namespaces, such as:

* caller() - to get a strack trace of active functions currently on the Nasal stack
* compile() - to compile new Nasal code "on the fly", i.e. dynamically from a string
* closure() - to query the lexical namespace of active functions
* bind() - to create new function objects

More information is available here: http://www.plausible.org/nasal/lib.html

If, on the other hand, you are using these data structures in some repeated fashion, it might make sense to keep the data structure itself around and simply re-use it next time (overwriting data as required), instead of always allocating/creating a new one, this is called "caching" and can pay off from a performance perspective.

=== Multiple inheritance ===

A class can inherit from one or more other classes. It can then access all methods and class members of all parent classes, but also override them and add additional members.

var A = { # simple class A
new: func {
return { parents: [A] };
},
alpha: func print("\tALPHA"),
test: func print("\tthis is A.test"),
};

var B = { # simple class B
new: func(v) { # ... whose constructor takes an argument
return { parents: [B], value: v };
},
bravo: func print("\tBRAVO"),
test: func print("\tthis is B.test"),
write: func print("\tmy value is: ", me.value),
},

var C = { # class C that inherits ...
new: func(v) {
return { parents: [C, A.new(), B.new(v)] }; # ... from class A and B
},
charlie: func print("\tCHARLIE"),
test: func print("\tthis is C.test"), # overrides A.test() and B.test()
};

print("A instance");
var a = A.new();
a.alpha();

print("B instance");
var b = B.new(123);
b.bravo();
b.write();

print("C instance");
var c = C.new(456);
c.alpha(); # use alpha from the A parent
c.bravo(); # use bravo from the B parent
c.charlie(); # use charlie from C itself
c.test(); # use C.test(), which overrides A.test() and B.test()
c.write();

Even if a class overrides a method of a parent with the same name, the parent's version can still be accessed via <tt>parents</tt> vector.

c.test() # use C.test()
c.parents[0].test(); # use C.test()
c.parents[1].test(); # use A.test()
c.parents[2].test(); # use B.test()

=== More on methods ===

Methods are function members of a class hash. They can access other class members via the <tt>me</tt> variable, which is a reference to the class hash. For this reason, a method returning <tt>me</tt> can be used like the class itself, and one can apply further methods to the return value (this is usually called "method chaining"):

var Object = {
new: func(coords...) {
return { parents: [Object], coords: coords };
},
rotate: func(angle) {
# do the rotation
return me;
},
scale: func(factor) {
# do the scaling
return me;
},
translate: func(x, y) {
# do the translation
return me;
},
};

var triangle = Object.new([0, 0], [10, 0], [5, 7]);
triangle.translate(-9, -4).scale(5).rotate(33).translate(9, 4); # concatenated methods thanks to "me"

<tt>me</tt>, however, is only known in the scope of the class. If a method is to be called as a listener callback or a timer function, <tt>me</tt> has to get wrapped in a function, so that it's stored in the function closure.

var Manager = {
new: func {
return { parents: [Manager] };
},
start_timers: func {
settimer(do_stuff, 5); # BAD: there's no "do_stuff" function in the scope
settimer(me.do_stuff, 5); # BAD: function exists, but "me" won't be known
# when the timer function is actually executed
settimer(func me.do_stuff(), 5); # GOOD: new function object packs "me" in the closure

setlistener("/sim/foo", func me.do_stuff()); # GOOD (same as with timers)
},
do_stuff: func {
print("doing stuff");
},
};

var manager = Manager.new();
manager.start_timers();

'''Click ''[http://wiki.flightgear.org/Namespaces_and_Methods#Methods here]'' for more information.'''

== Exception handling ==

<tt>die()</tt> aborts a function with an error message (this can be compared to the throw() mechanism in C++).

var divide = func(a, b) {
if (b == 0)
die("division by zero");
return a / b; # this line won't be reached if b == 0
}

die() is also used internally by built-in extension functions or Nasal core functions. <tt>getprop("/4me")</tt>, for example, dies with an error message ''"name must begin with alpha or '_'"''. Now assume we want to write a dialog where the user can type a property path into an input field, and we display the property's value in a popup dialog. What if the user typed an invalid path and we hand that over to <tt>getprop()</tt>? We don't want Nasal to abort our code because of that. We want to display a nice error message instead. The <tt>call()</tt> function can catch <tt>die()</tt> exceptions:

var value = getprop(property); # dies if 'property' is invalid
var value = call(func getprop(property), nil, var err = []); # catches invalid-property-exception and continues

The second line calls getprop(property) just like the first, and returns its value. But if 'property' was invalid then the <tt>call()</tt> function catches the exception and sets the 'err' vector instead. That vector remains empty on success.

if (size(err))
print("ERROR: bad property ", property, " (", err[0], ")"); # err[0] contains the die() message
else
print("value of ", property, " is ", value);

The first argument of <tt>call()</tt> is a function object, the second a vector of function arguments (or ''nil''), and the third a vector where the function will return a possible error. For more information on the <tt>call()</tt> function see the [http://plausible.org/nasal/lib.html Nasal library documentation].

<tt>die()</tt> doesn't really care about what its argument is. It doesn't have to be a string, and can be any variable, for example a class. This can be used to pass values through a chain of functions.

var Error = { # exception class
new: func(msg, number) {
return { parents: [Error], message: msg, number: number };
},
};

var A = func(a) {
if (a < 0)
die(Error.new("negative argument to A", a)); # throw Error
return "A received " ~ a;
}

var B = func(val) {
var result = A(val);
print("B finished"); # this line is not reached if A threw an exception
return result;
}

var value = call(B, [-4], var err = []); # try B(-4)

if (size(err)) { # catch (...)
print("ERROR: ", err[0].message, "; bad value was ", err[0].number);
die(err[0]); # re-throw
} else {
print("SUCCESS: ", value);
}

== Listeners and Signals ==

Listeners are callback functions that are attached to property nodes. They are triggered whenever the node is written to, or, depending on the listener type, also when children are added or removed, and when children are written to. Unlike polling loops, listeners don't have the least effect on the frame rate when they aren't triggered, which makes them preferable to monitor properties that aren't written to frequently.

===setlistener() vs. _setlistener() ===
You are requested *not* to use the raw _setlistener() function, except in files in $FG_ROOT/Nasal/ when they are
needed immediately. Only then the raw function is required, as it doesn't rely on props.nas.

===<tt>When listeners don't work</tt>===
Unfortunately, '''listeners don't work on so-called "tied" properties''' when the node value isn't set via property methods. (You can spot such tied properties by Ctrl-clicking the "." entry in the property browser: they are marked with a "T".) Most of the FDM properties are "tied".

Examples of properties where setlistener ''won't'' work:

* /position/elevation-ft
* /ai/models/aircraft/orientation/heading-deg
* Any property node created as an alias
* Lots of others

Before working to create a listener, always check whether a listener will work with that property node by control-clicking the "." in property browser to put it into verbose mode, and then checking whether the property node for which you want to set up a listener is marked with a "T" or not.

If you can't set a listener for a particular property, the alternative is to use settimer to set up a timer loop that checks the property value regularly.

Listeners are most efficient for properties that change only occasionally. No code is called at all during frames where the listener function is not called. If the property value changes every frame, setting up a settimer loop with time=0 will execute every frame, just the same as setlistener would, and the settimer loop is more efficient than setting a listener. This is one reason the fact the setlistener doesn't work on certain tied and FDM properties is not a great loss. See the section on timer loops below.

=== <tt>setlistener()</tt> ===

Syntax:

var listener_id = setlistener(<property>, <function> [, <startup=0> [, <runtime=1>]]);

The first argument is a property node object (<tt>props.Node()</tt> hash) or a property path. Because the node hash depends on the props.nas module being loaded, <tt>setlistener()</tt> calls need to be deferred when used in an $FG_ROOT/Nasal/*.nas file, usually by calling them in a <tt>settimer(func {}, 0)</tt> construction. To avoid that, one can use the raw <tt>_setlistener()</tt> function directly, for which <tt>setlistener()</tt> is a wrapper. The raw function does only accept node paths (e.g. "/sim/menubar/visibility"), but not props.Node() objects.

The second argument is a function object (not a function call!). The <tt>func</tt> keyword turns code into a function object.

The third argument is optional. If it is non-null, then it causes the listener to be called initially. This is useful to let the callback function pick up the node value at startup.

The fourth argument is optional, and defaults to 1. This means that the callback function will be executed whenever the property is written to, independent of the value.

If the argument is set to 0, then the function will only get triggered if a value other than the current value is written to the node. This is important for cases where a property is written to once per frame, no matter if the value changed or not. YASim, for example, does that for /gear/gear/wow or /gear/launchbar/state.
So, this should be used for properties that are written to in every frame, although the written value is mostly the same. If the argument is 2, then also write access to children will get reported, as well as the creation and removal of children nodes.

For both optional flags 0 means less calls, and 1 means more calls. The first is for startup behavior, and the second for runtime behavior.

Here's a real-life example:

setlistener("/gear/launchbar/state", func {
if (cmdarg().getValue() == "Engaged")
setprop("/sim/messages/copilot", "Engaged!");
}, 1, 0);

YASim writes once per frame the string "Disengaged" to property /gear/launchbar/state. When an aircraft on deck of the aircraft carrier locks into the catapult, this changes to "Engaged", which is then written again in every frame, until the aircraft leaves the catapult. Because the locking in is a bit difficult -- one has to target the sensitive area quite exactly --, it was desirable to get some quick feedback: a screen message that's also spoken by the Festival speech synthesis. With the args 1 and 0, this is done initially (for the unlikely case that we are locked in from the beginning), and then only when the node changes from an arbitrary value to "Engaged".

<tt>setlistener()</tt> returns a unique listener id on success, and <tt>nil</tt> on error. The id is nothing else than a counter that is 0 for the first Nasal listener, 1 for the second etc. You need this id number to remove the listener. Most listeners are never removed, so that one doesn't assign the return value, but simply drop it.

Listener callback functions can access up to four values via regular function arguments, the first two of which are property nodes in the form of a <tt>props.Node()</tt> object hash.

If you have set a callback function named ''myCallbackFunc'' via <tt>setlistener</tt> (''setlistener(myNode, myCallbackFunc)''), you can use this syntax in the callback function:

myCallbackFunc ([<changed_node> [, <listened_to_node> [, <operation> [, <is_child_event>]]]])

=== <tt>removelistener()</tt> ===

Syntax:

var num_listeners = removelistener(<listener id>);

<tt>removelistener()</tt> takes one argument: the unique listener id that a <tt>setlistener()</tt> call returned. It returns the number of remaining active Nasal listeners on success, <tt>nil</tt> on error, or -1 if a listener function applies <tt>removelistener()</tt> to itself. The fact that a listener can remove itself, can be used to implement a one-shot listener function:

var L = setlistener("/some/property", func {
print("I can only be triggered once.");
removelistener(L);
});

=== Listener Examples ===

The following example attaches an anonymous callback function to a "signal". The function will be executed when FlightGear is closed.

setlistener("/sim/signals/exit", func { print("bye!") });

Instead of an anonymous function, a named function can be used as well:

var say_bye = func { print("bye") }
setlistener("/sim/signals/exit", say_bye);

Callback functions can, optionally, access up to four parameters which are handed over via regular function arguments. Many times none of these parameters is used at all, as in the above example.

Most often, only the first parameter is used--which gives the node of the changed value.

The following code attaches the monitor_course() function to a gps property, using the argument ''course'' to get the node with the changed value.

var monitor_course = func(course) {
print("Monitored course set to ", course.getValue());
}
var i = setlistener("instrumentation/gps/wp/leg-course-deviation-deg", monitor_course);

# here the listener is active

removelistener(i); # remove that listener again

Here is code that accesses two arguments--the changed node and the listened-to node (these may be different when monitoring all children of a certain node)--and also shows how to monitor changes to a node including changes to children:

var monitor_course = func(course, flightinfo) {
print("One way to get the course setting: ", flightinfo.leg-course-deviation-deg.getValue());
print("Another way to get the same setting ", course.getValue());
}
var i = setlistener("instrumentation/gps/wp", monitor_course, 0, 2);

The function object doesn't need to be a separate, external function -- it can also be an anonymous function made directly in the <tt>setlistener()</tt> call:

setlistener("/sim/signals/exit", func { print("bye") }); # say "bye" on exit

Beware, however, that the contents of a function defined within the <tt>setlistener</tt> call are not evaluated until the call is actually made. If, for instance, local variables change before the setlistener call happens, the call will reflect the current value of those variables ''at the time the callback function is called'', not the value ''at the time the listener was set''.

For example, with this loop, the function will always return the value 10--even if mynode[1], mynode[2], mynode[3] or any of the others is the one that changed. It is because the contents of the setlistener are evaluated after the loop has completed running and at that point, i=10:

var output = func(number) {
print("mynode", number, " has changed!"); #This won't work!
}
for(i=1; i <= 10; i = i+1) {
var i = setlistener("mynode["~i~"]", func{ output (i); });
}

You can also access the four available function properties (or just one, two, or three of them as you need) in your anonymous function. Here is an example that accesses the first value:

for(i=1; i <= 10; i = i+1) {
var i = setlistener("mynode["~i~"]", func (changedNode) { print (changedNode.getPath() ~ " : " ~ changedNode.getValue()); });
}

Attaching a function to a node that is specified as <tt>props.Node()</tt> hash:

var node = props.globals.getNode("/sim/signals/click", 1);
setlistener(node, func { gui.popupTip("don't click here!") });

Sometimes it is desirable to call the listener function initially, so that it can pick up the node value. In the following example a listener watches the view number, and turns the HUD on in cockpit view, and off in all other views. It doesn't only do that on writing to "view-number", but also once when the listener gets attached, thanks to the third argument "1":

setlistener("/sim/current-view/view-number", func(n) {
setprop("/sim/hud/visibility[0]", n.getValue() == 0);
}, 1);

There's no limit for listeners on a node. Several functions can get attached to one node, just as one function can get attached to several nodes. Listeners may write to the node they are listening to. This will not make the listener call itself causing an endless recursion.

=== Signals ===

In addition to "normal" nodes, there are "signal" nodes that were created solely for the purpose of having listeners attached:

<tt>/sim/signals/exit</tt> ... set to "true" on quitting FlightGear

<tt>/sim/signals/reinit</tt> ... set to "true" right before resetting FlightGear (Shift-Esc), and to "false" afterwards

<tt>/sim/signals/click</tt> ... set to "true" after a mouse click at the terrain. Hint that the geo coords for the click spot were updated and can be retrieved from /sim/input/click/{longitude-deg,latitude-deg,elevation-ft,elevation-m}

<tt>/sim/signals/screenshot</tt> ... set to "true" right before the screenshot is taken, and set to "false" after it. Can be used to hide and reveal dialogs etc.

<tt>/sim/signals/nasal-dir-initialized</tt> ... set to "true" after all Nasal "library" files in $FG_ROOT/Nasal/ were loaded and executed. It is only set once and can only be used to trigger listener functions that were defined in one of the Nasal files in that directory. After that signal was set
Nasal starts loading and executing aircraft Nasal files, and only later are <tt>settimer()</tt> functions
called and the next signal is set:

<tt>/sim/signals/fdm-initialized</tt> ... set to "true" when then FDM has just finished its initialization

<tt>/sim/signals/reinit-gui</tt> ... set to "true" when the GUI has just been reset (e.g. via Help menu). This
is used by the gui.Dialog class to reload Nasal-loaded XML dialogs.

<tt>/sim/signals/frame</tt> ... triggered at the beginning of each iteration of the main loop (a.k.a. "frame"). This is meant for debugging purposes. Normally, one would just use a settimer() with interval 0 for the same effect. The difference is that the signal is guaranteed to be raised at a defined moment, while the timer call may change when subsystems are re-ordered.

== FlightGear extension functions ==

=== <tt>cmdarg()</tt> ===
cmdarg() is a mechanism to pass arguments to a nasal script (wrapped in properties) instead of "normal" function parameters. Note that cmdarg() should be primarily used in Nasal code embedded in XML files and should be considered depreciated otherwise (see [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg18361.html] and [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg18361.html]).

cmdarg() will keep working in (joystick) XML-'''bindings''' and on the top-level of embedded Nasal scripts (i.e. dialog and animation XML files).

As such, the cmdarg() function is primarily used for listener callbacks declared in XML markup, cmdarg() returns the listened-to property as props.Node object, so you can use it with all its methods (see $FG_ROOT/Nasal/props.nas) for example:

print(cmdarg().getPath(), " has been changed to ", cmdarg().getValue())

The cmdarg() function avoids that you have to type the exact same path twice (once here and once in the setlistener() command) and it makes clear that this is the listened to property. Also, you can use all the nice props.Node methods on cmdarg() directly:

setlistener("/gear/launchbar/state", func {
if (cmdarg().getValue() == "Engaged")
setprop("/sim/messages/copilot", "Engaged!");
}, 1, 0);

Use of cmdarg() outside of XML-bindings won't cause an error, but (still) return the last cmdarg() property. This just won't be the listened-to property anymore, but whatever the last legitimate cmdarg() user set. Most of the time it will be the property root of a joystick binding.

Don't make any assumptions and use cmdarg() only in one of these cases:

* binding: returns root of this binding's property branch. Needed for accessing an axis' value: cmdarg().getNode("setting").getValue()

* dialog xml files: returns root of that file's property branch in memory. This can be used to let embedded Nasal change the dialog (e.g. clear and build lists) before the final layout is decided

* animation xml files: returns root of this model's place in /ai/models/ when used as AI/MP model. Examples: /ai/models/multiplayer[3], /ai/models/tanker[1], etc. [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg14164.html]

* AI aircraft XML files

* remotely invoking Nasal code by setting properties using the built-in telnet daemon (RPC) [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg00150.html [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg00336.html].

'''In all cases, the cmdarg() call must not be delayed until later using settimer() or setlistener(). Because later it'll again return some unrelated property!
'''

=== <tt>fgcommand()</tt> ===

Runs an internal "fgcommand", see $FG_ROOT/Docs/README.commands for a list of available commands: http://gitorious.org/fg/fgdata/blobs/master/Docs/README.commands

=== <tt>print()</tt> ===
Concatenates an arbitrary number of arguments to one string, appends a new-line, and prints it to the terminal. Returns the number of printed characters.

print("Just", " a ", "test");

=== <tt>getprop()</tt> ===
Returns the node value for a given path, or <tt>nil</tt> if the node doesn't exist or hasn't been initialized yet.

getprop(<path>);

Example:

print("The frame rate is ", getprop("/sim/frame-rate"), " FPS");

=== <tt>setprop()</tt> ===
Sets a property value for a given node path string. Always returns nil.

setprop(<path> [, <path>, [...]], <value>);

All arguments but the last are concatenated to a path string, with a slash (/) inserted between each element. The last value is written to the respective node. If the node isn't writable, then an error message is printed to the console.

Note: <tt>setprop()</tt> concatenates a list of input arguments by means of inserting a "/" in between. That is nice for properties, as this slash is part of the tree. However, when one wants to make use of indices, like [0], one has to concatenate by hand (using "~") ''inside'' one part of the string argument list. An example is:

var i = 4;
setprop("instrumentation","cdu","page["~i~"]","title","MENU");

This results in instrumentation/cdu/page[4]/title = 'MENU' (string)

Examples:

setprop("/sim/current-view/view-number", 2);
setprop("/controls", "engines/engine[0]", "reverser", 1);

'''Erasing a property from the property tree''': a property that has been created, for example through <tt>setprop()</tt> can be erased via

props.globals.getNode("foo/bar").remove(); # take out the complete node
props.globals.getNode("/foo").removeChild("bar"); # take out a certain child node

=== <tt>settimer()</tt> ===
Runs a function after a given simulation time (default) or real time in seconds.

settimer(<function>, <time> [, <realtime=0>]);

The first object is a function object (ie, "func { ... }"). Note that this is different from a function call (ie, "func ( ... )"). If you don't understand what this means, just remember to always enclose the first argument in any call to settimer with the word "func" and braces "{ }", and it will always work. For instance, if you want print the words "My result" in five seconds, use this code:

settimer ( func { print ( "My result"); }, 5);

Inside the braces of the func object you can put any valid Nasal code, including a function call. In fact, if you want to call a function with certain values as arguments, the way to do it is to turn it into a function object by enclosing it with a func{}, for example:

myarg1="My favorite string";
myarg2=432;
settimer ( func { myfunction ( myarg1, myarg2); }, 25);

The third argument is optional and defaults to 0, which lets the time argument be interpreted as "seconds simulation time". In this case the timer doesn't run when FlightGear is paused. For user interaction purposes (measuring key press time, displaying popups, etc.) one usually prefers real time.

# simulation time example
var copilot_annoyed = func { setprop("/sim/messages/copilot", "Stop it! Immediately!") }
settimer(copilot_annoyed, 10);

# real time example
var popdown = func ( tipArg ) {
fgcommand("dialog-close", tipArg);
}

var selfStatusPopupTip = func (label, delay = 10, override = nil) {
var tmpl = props.Node.new({
name : "PopTipSelf", modal : 0, layout : "hbox",
y: 140,
text : { label : label, padding : 6 }
});
if (override != nil) tmpl.setValues(override);

popdown(tipArgSelf);
fgcommand("dialog-new", tmpl);
fgcommand("dialog-show", tipArgSelf);

currTimerSelf += 1;
var thisTimerSelf = currTimerSelf;

# Final argument 1 is a flag to use "real" time, not simulated time
settimer(func { if(currTimerSelf == thisTimerSelf) { popdown(tipArgSelf) } }, delay, 1);
}

[[Nasal_scripting_language#settimer_loops|More information about best practices for using the settimer function to create loops in Nasal is elsewhere on this page.]]

=== <tt>systime()</tt> ===
Returns epoch time (time since 1972/01/01 00:00) in seconds as a floating point number with high resolution. This is useful for benchmarking purposes.

#benchmarking example:
var start = systime();
how_fast_am_I(123);
var end = systime();
print("took ", end - start, " seconds");

=== <tt>carttogeod()</tt> ===
Converts cartesian coordinates x/y/z to geodetic coordinates lat/lon/alt, which are returned as a vector. Units are degree and meter.

var geod = carttogeod(-2737504, -4264101, 3862172);
print("lat=", geod[0], " lon=", geod[1], " alt=", geod[2]);

# outputs
lat=37.49999782141546 lon=-122.6999914632327 alt=998.6042055172776

=== <tt>geodtocart()</tt> ===
Converts geodetic coordinates lat/lon/alt to cartesian coordinates x/y/z. Units are degree and meter.

var cart = geodtocart(37.5, -122.7, 1000); # lat/lon/alt(m)
print("x=", cart[0], " y=", cart[1], " z=", cart[2]);

# outputs
x=-2737504.667684828 y=-4264101.900993474 z=3862172.834656495

=== <tt>geodinfo()</tt> ===
Returns information about geodetic coordinates. Takes two arguments: lat, lon (in degree) and returns a vector with two entries, or nil if no information could be obtained because the terrain tile wasn't loaded. The first entry is the elevation (in meters) for the given point, and the second is a hash with information about the assigned material, or nil if there was no material information available, because there is, for instance, an untextured building at that spot or the scenery tile is not loaded.

var lat = getprop("/position/latitude-deg");
var lon = getprop("/position/longitude-deg");
var info = geodinfo(lat, lon);

if (info != nil) {
print("the terrain under the aircraft is at elevation ", info[0], " m");
if (info[1] != nil)
print("and it is ", info[1].solid ? "solid ground" : "covered by water");
}

A full data set looks like this:

debug.dump(geodinfo(lat, lon));

# outputs
[ 106.9892101062052, { light_coverage : 0, bumpiness : 0.5999999999999999, load_resistance : 1e+30,
solid : 0, names : [ "Lake", "Pond", "Reservoir", "Stream", "Canal" ], friction_factor : 1,
rolling_friction : 1.5 } ]

Note that geodinfo is a *very* CPU intensive operation, particularly in FG 2.4.0 and earlier, so use sparingly ([http://flightgear.org/forums/viewtopic.php?f=4&p=135044#p135044 discussion here]).

=== <tt>parsexml()</tt> ===

This function is an interface to the built-in [http://expat.sourceforge.net/ Expat XML parser]. It takes up to five arguments. The first is a mandatory absolute path to an XML file, the remaining four are optional callback functions, each of which can be nil (which is also the default value).

var ret = parsexml(<path> [, <start-elem> [, <end-elem> [, <data> [, <pi> ]]]]);

<start-elem> ... called for every starting tag with two arguments: the tag name, and an attribute hash
<end-elem> ... called for every ending tag with one argument: the tag name
<data> ... called for every piece of data with one argument: the data string
<pi> ... called for every "processing information" with two args: target and data string

<ret> ... the return value is nil on error, and the <path> otherwise

Example:

var start = func(name, attr) {
print("starting tag ", name);
foreach (var a; keys(attr))
print("\twith attribute ", a, "=", attr[a]);
}
var end = func(name) { print("ending tag ", name) }
var data = func(data) { print("data=", data) }
var pi = func(target, data) { print("processing instruction: target=", target, " data=", data) }
parsexml("/tmp/foo.xml", start, end, data, pi);

=== airportinfo() ===
Function for retrieval of airport/runway information.
Usage:

var apt = airportinfo("KHAF"); # get info about KHAF
var apt = airportinfo(lat, lon); # get info about apt closest to lat/lon
var apt = airportinfo(); # get info about apt closest to aircraft

The command debug.dump(airportinfo("KHAF")) outputs this:

{ lon : -122.4962626410256, lat : 37.51343502564102, has_metar : 0,
runways : { 12 : { stopway2 : 0, threshold1 : 232.5624,
lon : -122.5010889999999, lat : 37.513831, stopway1 : 0, width : 45.72,
threshold2 : 232.5624, heading : 138.1199999999999, length : 1523.0856 } },
elevation : 20.42159999999999, id : "KHAF", name : "Half Moon Bay" }

That is: a hash with elements lat/lon/elev/id/name/has_metar for the
airport, and a hash with runways, each of which consists of lat/lon/
/length/width/heading/threshold[12]/stopway[12]. Only one side of each
runway is listed -- the other can easily be deduced.

==Built-in functions==

===sort(vector, function)===
Creates a new vector containing the elements in the input vector sorted in ascending order according to the rule given by function, which takes two arguments (elements of the input vector) and should return less than zero, zero, or greater than zero if the first argument is, respectively, less than, equal to, or greater than the second argument. Despite being implemented with ANSI C qsort(), the sort is stable; "equal" elements in the output vector will appear in the same relative order as they do in the input.

Because you can define the sort function, sort allows you to create a list of keys sorting a hash by any criterion--by key, value, or (if, for instance the hash values are hashes themselves) any subvalue.

vec = [100,24,45];
sortvec = sort (vec, func (a,b) cmp (a,b));
debug.dump (sortvec); #output is [24,45,100]

Here is an example of how to output the contents of a hash in sorted order. Note that the function does not actually sort the hash but returns a list of the hash keys in sorted order.

var airport = {
"LOXZ": "Zeltweg",
"LOWI": "Innsbruck",
"LOXL": "Linz Hoersching", # the last comma is optional
};

var sortedkeys= sort (keys(airport), func (a,b) cmp (airport[a], airport[b]));

foreach (var i; sortedkeys)
print (i, ": ", airport[i]);

The output is:

LOWI: Innsbruck
LOXL: Linz Hoersching
LOXZ: Zeltweg

If the hash values are themselves hashes, sorting by any of the subvalues is possible. For example:

var airport = {
"LOXZ": {city: "Zeltweg", altitude_m: 1300 },
"LOWI": {city: "Innsbruck", altitude_m: 2312 },
"LOXL": {city: "Linz Hoersching", altitude_m: 1932 },
};

#return a list of the hash keys sorted by altitude_m
var sortedkeys= sort (keys(airport), func (a,b) airport[a].altitude_m - airport[b].altitude_m);

foreach (var i; sortedkeys)
print (i, ": ", airport[i].city, ", ", airport[i].altitude_m);

Note that ''sort'' will return errors, and in FG 2.4.0 may even stop working, if the sort function you provide returns errors. A common cause of this is if your sort vector contains both string and numeric values. The cmp function will return an error for numeric values, and arithmetic operations you may use to sort numeric values will return errors if performed on a string. The error in these cases is typically "function/method call on uncallable object".

=== Other useful built-in functions ===

Other basic built-in Nasal functions such as append, setsize, subvec, typeof, contains, delete, int, num, keys, pop, size, streq, cmp, substr, sprintf, find, split, rand, call, die, bind, math.sin, math.pi, math.exp, math.ln math.e, io.read, io.write, regex.exec, and others of that sort, [http://www.plausible.org/nasal/lib.html are detailed in this external document].

=== Useful functions in the Nasal directory ===
Other functions are available in the Nasal files found in the Nasal directory of a FlightGear install. Simply open those Nasal files in text editor to see what is inside. Reference those functions by putting the filename in front of the function, method, variable, or object you wish to use. For instance, to use the method Coord.new() in the file geo.nas, you simply write:

geo.Coord.new()

=== Distance calculations ===

To calculate the distance between two points (in two different ways):
# mylat1, mylong1, mylat2, mylong2 are lat & long in degrees
# myalt1 & myalt2 are altitude in meters

var GeoCoord1 = geo.Coord.new();
GeoCoord1.set_latlon(mylat1, mylong1,myalt1);

var GeoCoord2 = geo.Coord.new();
GeoCoord2.set_latlon(mylat2, mylong2, myalt2);

var directDistance = GeoCoord1.direct_distance_to(GeoCoord2);
var surfaceDistance = GeoCoord1.distance_to(GeoCoord2);

The results are distances in meters.

* distance_to - returns distance in meters along Earth curvature, ignoring altitudes; useful for map distance
* direct_distance_to - returns distance in meters direct; considers altitude, but cuts through Earth surface

=== Other useful geographical functions ===
Other useful geographical functions are found in geo.nas (in the FlightGear/data/Nasal directory of a FlightGear installation). geo.nas also includes documentation/explanation of the functions available.

==Developing and debugging in Nasal==
===Developing Nasal code===
Because code in the Nasal directory is parsed only at Flightgear startup, testing and debugging Nasal code can by slow and difficult.

Flightgear provides a couple of ways to work around this issue:

====Nasal Console====

The Nasal Console is available in Flightgear's menu (Debug/Nasal Console). Selecting this menu opens a Nasal Console dialog.

This dialog has several tabs, of which each can hold separate Nasal code snippets, all of which are saved on exit
and reloaded next time. This is useful for little tests, or for executing code for which writing a key binding is just too much
work, such as "props.dump(props.globals)".

If you want to add more tabs (radio buttons in the Nasal Console dialog) to hold more code samples, just add more <code> nodes to autosave.xml.

====Loading/reloading Nasal code without re-starting Flightgear====
A common problem in testing and debugging Nasal programs is that each testing step requires stopping and re-starting Flightgear, a slow process.

Below is described a technique for loading and executing a Nasal file while Flightgear is running. Flightgear will parse the file, display any errors in the Flightgear console window, and then execute the code as usual.

Using this technique, you can start Flightgear, load the Nasal code you want to test observe any errors or test functionality as you wish, make changes to the Nasal file, reload it to observe parse errors or change in functionality, and so on to repeatedly and quickly run through the change/load/parse/test cycle without needing to re-start Flightgear each time.

The key to this technique is the function io.load_nasal(), which loads a nasal file into a nasal namespace.

Step-by-step instructions showing how to use this technique to load, parse, and test a Nasal file while Flightgear is running:

=====Create the Nasal file to test=====
Create a text file named $FG_ROOT/foo/test.nas with this text:

print("hi!");
var msg="My message.";
var hello = func { print("I'm the test.hello() function") }

Notes: You can create the file in any directory you wish, as long as Nasal can read the directory--but the file IOrules in the Nasal directory restricts which directories Nasal may read and write from.

You can give the file any name and extension you wish, though it is generally most convenient to use the .nas extension with Nasal files.

=====Load the file and test=====
Start Flightgear. You can import the file above into Flightgear by typing the following into the Nasal Console dialog and executing the code:

io.load_nasal(getprop("/sim/fg-root") ~ "/foo/test.nas", "example");

getprop("/sim/fg-root") gets the root directory of the FlightGear installation, ~ "/foo/test.nas" appends the directory and filename you created. The final variable "example" tells the namespace to load for the Nasal file.

You'll see the message "hi!" on the terminal, and have function "example.hello()" immediately available. You can, for instance, type "example.hello();" into one of the Nasal console windows and press "Execute" to see the results; similarly you could execute "print (example.msg);".

If you find errors or want to make changes, simply make them in your text editor, save the file, and execute the io.load_nasal() command again in the Nasal Console to re-load the file with changes.

It's worth noting that Nasal code embedded in XML GUI dialog files can be reloaded by using the "debug" menu ("reload GUI").

You may also want to check out the remarks on [[Nasal_scripting_language#Memory_management|Memory management]].

==== Managing timers and listeners ====

Note: If your Nasal program sets listeners, timer loops, and so on, they will remain set even when the code is reloaded, and reloading the code will set additional listeners and timer loops.

This can lead to extremely slow framerates and unexpected behavior. For timers you can avoid this problem by using the loopid method (described above); for listeners you can create a function to destroy all timers your Nasal program creates, and call that function before reloading the program. (And cleaning up timer loops and listeners is a best practice for creating Nasal programs in Flightgear regardless.)

The same problem may occur while resetting or re-initializing parts of FlightGear if your code isn't prepared for this. And obviously this applies in particular also to any worker threads you may have started, too!

For complex Nasal scripts with many timers and listeners, it is therefore generally a very good idea to implement special callbacks so that your scripts can respond to the most important simulator "signals", this can be achieved by registering script-specific listeners to signals like "reinit" or "freeze" (pause): the corresponding callbacks can then suspend or re-initialize the Nasal code by suspending listeners and timers. Following this practice helps ensure that your code will behave properly even during simulator resets.

In other words, it makes sense to provide a separate high-level controller routine to look for important simulator events and then pause or re-initialize your main Nasal code as required.

If you are using [[Nasal_scripting_language#System-wide_Nasal_code|System-wide Nasal modules]], you should register listeners to properly re-initialize and clean up your Nasal code.

In its simplest form, this could look like this:

var cleanup = func {}
setlistener("/sim/signals/reinit", cleanup);

This will invoke your "cleanup" function, whenever the "reinit" signal is set by the FlighGear core.

Obviously, you now need to populare your cleanup function with some code, too.

One of the easiest ways to do this, is removing all listeners/timers manually here, i.e. by adding calls to removelistener():

var cleanup = func {
removelistener(id);
removelistener(id);
removelistener(id);
}

This would ensure that the corresponding listeners would be removed once the signal is triggered.

On the other hand, you could just as well use a vector of listener IDs here, and then use a Nasal foreach loop:

var cleanup = func(id_list) {
foreach(var id; id_list)
removelistener(id);
}

Obviously, this would require that you maintain a list of active listeners, too - so that you can actually pass a list of IDs to the cleanup function.

This is one of those things that can be easily done in Nasal, too - just by introducing a little helper wrapper:

var id_list=[];
var store_listener = func(id) append(id_list,id);

The only thing required here, would be replacing/wrapping the conventional "setlistener" call with calls to your helper:

store_listener( setlistener("/sim/foo") );
store_listener( setlistener("/foo/bar") );

If you were to do this consistently across all your Nasal code, you'd end up with a high level way to manage all your registered listeners centrally.

Now, you'll probably have noticed that it would make sense to consider wrapping all these helpers and variables inside an enclosing helper class, this can be accomplished in Nasal using a hash. This would enable you to to implement everything neatly organized in an object and use RAII-like patterns to manage Nasal resources like timers, listeners and even threads.

===Debugging===
The file debug.nas, included in the Nasal directory of the Flightgear distribution, has several functions useful for debugging Nasal code. These functions are available to any Nasal program or code executed by Flightgear.

Aside from those listed below, several other useful debugging functions are found in debug.nas; see the debug.nas file for the list of functions and explanation.

Note that the debug module makes extensive use of ANSI terminal color codes. These create colored output on Linux/Unix systems but on other systems they may add numerous visible control codes. To turn off the color codes, go to the internal property tree and set

/sim/startup/terminal-ansi-colors=0

Or within a Nasal program:

setprop ("/sim/startup/terminal-ansi-colors",0);

====debug.dump====
debug.dump([<variable>]) ... dumps full contents of variable or of local variables if none given

The function debug.dump() dumps the contents of the given variable to the console. On Unix/Linux this is done with some syntax coloring. For example, these lines

var as = props.globals.getNode("/velocities/airspeed-kt", 1);
debug.dump(as);

would output

</velocities/airspeed-kt=1.021376474393101 (DOUBLE; T)>

The "T" means that it's a "tied" property. The same letters are used here as in the property-browser. The angle brackets seem superfluous, but are useful because debug.dump() also outputs compound data types, such as vectors and hashes. For example:

var as = props.globals.getNode("/velocities/airspeed-kt", 1);
var ac = props.globals.getNode("/sim/aircraft", 1);
var nodes = [as, ac];
var hash = { airspeed_node: as, aircraft_name: ac, all_nodes: nodes };
debug.dump(hash);

yields:

{ all_nodes : [ </velocities/airspeed-kt=1.021376474393101 (DOUBLE; T)>,
</sim/aircraft="bo105" (STRING)> ], airspeed_node : </velocities/airspe
ed-kt=1.021376474393101 (DOUBLE; T)>, aircraft_name : </sim/aircraft="bo
105" (STRING)> }

====debug.backtrace====
debug.backtrace([<comment:string>]} ... writes backtrace with local variables
debug.bt ... abbreviation for debug.backtrace

The function debug.backtrace() outputs all local variables of the current function and all parent functions.

====debug.benchmark====
debug.benchmark(<label:string>, <func> [, <repeat:int>])
... runs function <repeat> times (default: 1) and prints execution time in seconds,prefixed with <label>.

This is extremely useful for benchmarking pieces of code to determin
====debug.exit====
debug.exit() ... exits fgfs

== Related content ==
{{Forum|30|Nasal}}
* [[:Category:Nasal]]

=== External links ===
* http://www.plausible.org/nasal

[[Category:Nasal]]

Nasal scripting language

2011-12-25T05:39:18Z

Moksha: /* Some success stories */ spelling

''Please note that a considerable amount of resources has not yet been incorporated here, you can check these out by going to the "[[Talk:Nasal_scripting_language|discussion]]" page, where we are collecting links to webpages and mailing list discussions/postings related to Nasal.''

==Nasal = Not another scripting language!==

The short summary is that Nasal is a scripting language that is tightly integrated with FlightGear itself,
and provides a very easy way to manipulate the property tree, which is the core data structure within the
simulator that exposes all the important internal runtime states of FlightGear.

[[FlightGear]] offers a very powerful functional scripting language called [http://plausible.org/nasal/ "Nasal"], which supports reading and writing of internal [[Property Tree Intro|FlightGear properties]], accessing internal data via extension functions, creating GUI dialogs and much more.

Nasal uses some of the concepts of ECMA/JavaScript, Python and Perl and implements a simple but complete way of Object Oriented Programming (OOP), Nasal uses an internal garbage collector so that no manual memory management is required by the programmer.

People familiar with other programming languages, and scripting languages like JavaScript in particular, are usually able to learn Nasal rather quickly. FlightGear provides a rich library of simulation-specific and general-purpose functions that can be accessed by Nasal scripts.

Nasal code can be run by aircraft configuration files, and it can be embedded in various [[XML]] files (dialog files, animation files, bindings for joysticks, keyboard and cockpit controls, and even in [[Howto: Nasal in scenery object XML files|scenery objects]]). Nasal is platform independent and designed to be thread safe.

=== Some success stories ===
These were taken from the developers mailing list:

* "Nasal is *very* well designed, compact, and efficient. It is used heavily throughout many areas of FlightGear."
* "It's interesting though how much nasal you can actually get away with using without making a blip on frame rates. Nasal is *very* efficient and powerful for being an interpreted script language."
* "FlightGear needed a built-in scripting language, and it has one. A compact, clean, elegant and fast one, Nasal extension functions interface perfectly to the property tree, the event manager, the built-in XML parser etc. Nasal is very tightly integrated in fgfs and used all over the place."
* "There's no question that scripting languages are good; fgfs has a lot of Nasal code now. In my profiling I have never seen the nasal interpreter as a hot spot"
* "I'm a simple content contributor with very little background in programming. When I made my first Aircraft (the bf109) I was confronted with the need to deploy slats automatically at a given speed. I din't want to embed C++ code or had such a complex script that the error messages in FG wouldn't help me and I previously only used a bit of python. I looked at some Nasal scripts and within a few hours it worked. I was impressed how easy it is to write even complex Nasal scripts. Later I started developing the walker feature that made it possible to walk around in the scenery, all with nasal. Stuart kindly enhanced the walker and added an animation system to it (see bluebird), again with nasal. Others have made Flight computers with it (see V-22 and Su-37). Nasal is a worthy tool"
* "I used Nasal to build several rather complex systems, like Fuel System, Stab Augmentation System, Autopilot Logic, Terrain Avoidance Radar, Radar Warning Receiver and much more, and yes, I love Nasal too. Learning Nasal use was easy and fun and I din't found any limitation yet."
* There are many vital parts of FlightGear currently coded in nasal. There are also random bits of nasal code scattered around in joystick configurations, instrument and aircraft models, scenery models... everywhere.
* "We have an entire directory full of Nasal 'function' libraries now, and I'm quite happy using them instead of rolling my own duplicate functionality."
* Nearly every sophisticated Aircraft uses some kind of Nasal, be it Effects like tyre smoke or important functionalities like Engine and electric management, The Bluebird FDM is completely written in Nasal, vital parts of the V-22 Osprey rely on it, Flyby and Model View wouldn't work anymore, no more interactive objects in the scenery, lots of the MP System would be gone, ... Nasal is THE tool which makes FG development fun and adds nearly unlimited possibilities. If you need an example, look at the Bluebird animated walker, all done in Nasal."
* "there are good reasons to use Nasal - first of all the user base which regularly compiles their own code is small, whereas people do install addon packages - so I get a lot more feedback and test results. Second that one usually can't really crash the whole system from Nasal. Third, it's very easy to quickly try something and very maintenance-friendly. Fourth, you can actually start developing something without knowing how the core code ties together - which I suppose takes a lot of time to learn. And so on."
* "Hard-coding every instrument in C++ instead of nasal means only developers following/building the latest cvs head code get to use whatever until the next release cycle."
* "Hard coding every instrument/flight control in C++ means my WW-II storch (et.al.) is stuck with an autobrake functionality it doesn't have nor need."
* "I think it boils down to the fact that we have two approaches that can accomplish the same thing. The C/C++ approach offers high performance but there is a dependence on when the C/C++ code was added to FlightGear. The Nasal approach offers fast prototyping, flexibility, and more (but not complete) independence from the C/C++ code."
* "A basic problem with C++ functions is it is hard/impossible to override them for a special purpose. Writing in pure nasal allows function name hijacking and other tricks that can't be used on C++ code."
* "Given the fact that FG is platform independent, I don't know if the embedded C++ is doing the same on Windows, Linux, PPC and intel Macs. Apart from the fact that if I was able to code c++ I would embed it to FG rather than in an Aircraft specific script"
* "If we ported Nasal code over to C++ we'd lose the ability to change small things "on the fly" without compiling over and over again. We'd also lose good programmers, who prefer scripting over C++. Aircraft creation would not be customizable etc etc."
* "The argument against Nasal is essentially that C++ is faster than Nasal - which, everything else being equal, is certainly correct. But highly specialized Nasal code written for a particular problem outperforms general purpose C++ code - I've given several examples in the past. If someone were e.g. to add movement to Nasal spawned models by adding a velocity property, I'm not sure it would outperform my Nasal quadtree-sorted adaptive range code which priorizes movement for things actually inside the field of view. Of course, if you'd hard-code that specialized algorithm, it would be faster than the Nasal version - but then you couldn't apply it to other problems any more."
* "How many airplane developer will you loose if you remove the Nasal engine from FGFS because they can write Nasal code but not C++ code?"
* "The algorithm being equal, I don't think there's a question that C++ is faster (I doubt the factor 10 though - that seems to be an extreme case). Everything else being equal, I also don't think there's a question that Nasal code is more accessible. And I would base any decision what to hard-code and what not on that balance."
* "Nasal is just much better suited for FlightGear than many alternatives because of it's size, processing speed and because a number of FlightGear core developers have a good idea what's going on."
* "In theory we could even use VBScript but Nasal has proven to be valuable for almost 10 years, so no reason to change or add another scripting language. Besides, if you know JavaScript then learning Nasal would take little effort."
* "The pool of people with commit rights to the core C++ code is very, very small."

Nasal really is an excellent choice for prototyping and implementing new features and even completely new systems in FlightGear.

For example, the [[bombable]] script implements "dog fighting" support on top of FlightGear, without ANY changes to the C++ side of the code, just by using some fairly advanced scripted code (implemented in the built-in Nasal programming language). You can basically imagine it like a "MOD" of FlightGear. In other words, the bombable script creates a completely new "mode" in FlightGear.

No matter if it's scenery, aircraft, AI scenarios or whatever: many things that were originally never planned to be supported by FlightGear core developers, are now implicitly supported because of the loose coupling between highly configurable and flexible systems, such as the property tree and the Nasal scripting language.

So we are really standing on the shoulders of giants here, because we are now -after 10+ years- in the position to create significant new features (and even completely new systems in FlightGear) within the constraints of the FlightGear base package, without even touching the C++ source code at all - simply because FlightGear has become so flexible and extensible.

All of this became possible by some important architectural decisions, such as for example the use of XML and plain text files for pretty much all configuration files in FlightGear (and thus open file formats in general), a publicly accessible tree of state variables that can be easily inspected and modified at runtime (the property tree). Similarly, the decision to embed a scripting language that can be used for scripting the entire simulator was another important decision.

In FlightGear, Nasal is the most accessible method of customizing the whole simulator to a very high degree. Nasal code can be easily edited using a conventional text editor, there are no special tools required: Nasal source code is interpreted, compiled to bytecode and run by the Nasal "virtual machine" using FlightGear itself.

The emerging [[A local weather system|Local weather]] system was entirely prototyped in Nasal space, and is now being increasingly augmented by moving performance-critical functions to C++ space instead.

Using Nasal, it is even possible to create entirely scripted flights and smart "AI bots":

I have something here that I think is kind of fun. I've been fiddling with
this off and on since last fall and decided it was time to clean it up a bit
and quit hording all the fun for myself. Basically I have taken the F-14b
and created a high performance Navy "drone" out of it. It can auto-launch
from a carrier, auto fly a route (if you've input one) and can do circle
holds (compensating for wind.) I've added a simulated
gyro stabilized camera that will point at anything you click on and then
hold that view steady no matter what the airplane does (similar to what real
uav's can do.) Finally, you can command it to return home and it will find
the carrier, setup a reasonable approach and nail the landing perfectly
every time (factoring in wind, carrier speed, etc.): http://www.flightgear.org/uas-demo/

As of 03/2009, there were approximately 170.000 lines of reported Nasal source code in the FlightGear base package [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg21333.html], compared to 2006 this is almost a rate of growth of 600% within 3 years [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg01728.html]. This illustrates the sheer adoption rate Nasal is experiencing in FlightGear.

(As of 10/2011, the FlightGear base package contained 326.000 lines of Nasal source code in *.nas files)

Note that this page is mostly about FlightGear-specific APIs/extension functions and usage patterns.
Thus, you may also want to have a look here:

* [http://plausible.org/nasal/lib.html core language/library documentation]
* [http://plausible.org/nasal/sample.nas annotated source code examples]
* [http://plausible.org/nasal/doc.html Nasal design document]
* [http://www.plausible.org/nasal/flightgear.html a helpful tutorial about using Nasal in FlightGear].

In addition, the [http://gitorious.org/fg/fgdata/trees/master/Nasal Nasal directory] in the FlightGear base package contains a wealth of tested, proven and usually well-commented source code that you may want to check out for additional examples of using the Nasal scripting language in FlightGear [http://gitorious.org/fg/fgdata/trees/master/Nasal].

If you have any Nasal specific questions, you will want to check out the [[Nasal FAQ]], feel free to ask new questions or help answer or refine existing ones. If you would like to learn more about existing Nasal modules in FlightGear, you may want to check out [[Nasal Modules]].

If you are a developer and interested in extending Nasal, you may want to check out [[Howto:Extending Nasal]].

Many short "howto"-style tutorials on Nasal programming can be found in the [[Category:Nasal|Nasal category]].

== Some words on Nasal for fellow C++ programmers ==

Compared to C++, there is really nothing "low quality" about Nasal per se: Nasal is just the "script glue" that connects different parts of the simulator: Many Nasal scripts leverage C++ code - and it is very easy to add new C++ code that can be called from Nasal.

History has shown, that most code in FlightGear will eventually be made more configurable and more accessible, this usually happens in the same steps: 1) replacing static variables with variables stored in the property tree, 2) using listeners to get update notifications for important variables, 3) fully exposing a "control" interface by making it accessible it in the property tree, 4) providing scripting hooks.

Even if you should know C or C++ already, Nasal probably remains the most accessible and the most powerful method for customizing the simulator, simply because it is extremely easy and fast to get started, you don't need an "integrated development environment", you don't need to install compilers and you don't need to satisfy any 3rd party dependencies; bottom line being: if you can run FlightGear, you can also run Nasal and create new code.

In addition, Nasal code is fairly abstract code, too. Once you start looking at some existing Nasal scripts, you will see that it is also fairly high level code, much more high level than C++ - so Nasal has a much higher density of code, too. Nasal's role in FlightGear really is like JavaScript's role in Firefox, where it is also used for many/most core-related logics (CSS/XUL).

=== Performance ===

Obviously, C++ code will usually be faster than the corresponding Nasal code. But, while performance is not a design goal, Nasal isn't especially slow either. For example, early benchmarks of the garbage collector showed it as faster than perl's reference counter, and its number crunching performance is on par with python. But in all cases, simplicity, transparency and a sane feature set are preferred over speed in Nasal.

Nasal was specifically designed for use as an extension language in an larger project such as FlightGear. The problem with many otherwise excellent languages in this environment is that they are huge. Perl and python are great, but enormous. Even their "core" interpreters and library code are larger than most projects that require an embedded language. They cannot be readily shipped with their host application and need to be installed system-wide. This is a pain and a compatibility hassle.

The real goal with Nasal is to have a language that supports most "normal" programming idioms (objects, functions, arrays, hashes) while avoiding the bloat that comes from "platform" scripting languages like perl, python, ruby and php.

=== Garbage collection ===
Nasal garbage collects runtime storage, so the programmer need not worry about manual allocation, or even circular references. The current implementation is a simple mark/sweep collector, which should be acceptable for most applications. Future enhancements will include a "return early" capability for latency-critical applications. The collector can be instructed to return after a certain maximum delay, and be restarted later.

As far as speed goes, the last any benchmarking Nasal was done, it was about as fast as Perl 5 or Python 2.2 at most things. It's garbage collector was faster, its symbol lookup about the same or slightly faster, and its bytecode interpreter somewhat slower.

=== Thread safety ===
Unlike almost all other script interpreters (and unlike the FlightGear/Nasal interface itself) , Nasal is thread safe and scalable when called from multiple CPU threads (as opposed to the userspace interpreter threads implemented by Ruby).

No special treatment is required (as for perl, which clones a separate interpreter with separate data for each thread and uses locking around specifically-designated shared data) and the threads can be scheduled simultaneously. There is no global lock on the interpreter, as used by Python or Lua. The only limit on scalability is garbage collection, which must block all interpreter threads before running.

When running threaded code, Nasal provides "minimal threadsafety", meaning that the interpreter itself can be safely called from multiple CPU threads without risk of corrupting or deadlocking the interpreter internals. Multithreaded operations are therefore "safe", although they are not guaranteed to be atomic. In particular, poorly synchronized insertions into containers can "drop" objects into oblivion (which is OK from an interpreter stability standpoint, since the GC will clean them up normally). Nasal itself provides no synchronization primitives to address this; thread architecture is a "top-level" design job, and Nasal is intended to be an extension language in a larger project. Choice of synchronization mechanisms is going to be highly application dependent.

=== Exception handling ===
Like python, nasal supports exception handling as a first-class language feature, with built-in runtime-inspectable stack trace. Rather like perl, however, there is no special "try" syntax for exception handling, nor inheritance-based catching semantics. Instead, you use the call() builtin to invoke a function object and inspect the results to determine what error was thrown (either with the die() builtin or via an internal runtime error) and what the stack trace looked like. Elaborate exception handling isn't really appropriate for embedded scripting languages.

=== High level programming ===

Thus, programmers already familiar with C++ shouldn't just disregard Nasal as a "toy" that doesn't seem suitable for serious development: some of the more complex Nasal scripts can literally make one's head spin around and it would quite obviously take much more C++ or Java code to implement the same features, while sacrificing all the flexibility and power that a scripting language offers.

Some features can certainly be more easily implemented in Nasal space, than in C++ space. Often, the Nasal solution is "on par" with similar solutions in C++.

=== Accessibility ===

For instance, Nasal code cannot only be easily run and contributed by all users, but it can also be easily reused and maintained by other users. This means, that given the number of active C++ developers, compared to the number of base package contributors, your Nasal code is more likely to be actively maintained by fellow users if it is written in Nasal.

In other words, if there are some experimental features you'd like to explore, Nasal is an excellent way to ensure that other FlightGear '''users''' can easily test your new features. This could be witnessed during the development of the local weather system or the bombable addon,too.

This is in stark contrast to features developed solely in C++ space, because these can usually only be tested by people able to build FlightGear from source, especially if your code isn't yet in the main repository, where it would eventually be available in the form of a binary snapshot.

Obviously, none of this is to say that Nasal is the perfect solution for any problem, there are many things for which Nasal isn't necessarily a perfect choice, such as low level code for example (i.e. rendering).

On the other hand, Nasal really is a powerful tool in FlightGear, and if you find that something should, but cannot, be done in Nasal space, it is extremely easy to add support for new features to the Nasal engine using extension functions or property listeners to trigger C/C++ code.

== Creating new Scripts ==

Nasal scripts need to be plain text files, saved with a *.nas extension.

=== Aircraft specific Nasal code ===

Generally, aircraft specific Nasal scripts reside in the corresponding aircraft's folder (or a corresponding /Nasal subfolder) where they are usually included by adding a corresponding <nasal> tag to the aircraft-set.xml file (see [[Writing_simple_scripts_in_%22nasal%22|Writing simple scripts in "nasal"]]). Also see the section on [[Nasal_scripting_language#Namespaces|namespaces]] which contains more specific examples.

=== Instrument specific Nasal code ===

While instrument specific scripts are saved within the instrument's folder (as previously mentioned, Nasal scripts can also be embedded in various other XML files), Nasal scripts driving shared instruments are generally stored in [[$FG ROOT]]/Aircraft/Generic/

=== Nasal code as bindings in XML files ===
Nasal scripts can also be used as "binding" objects, and can therefore appear anywhere in a configuration file (keyboard, mouse and joystick bindings, etc...) that accepts a <binding> tag. The relevant command type is "nasal", and you place your Nasal code inside of the <script> tag:

<binding>
<command>nasal</command>
<script>
print("Binding Invoked!");
</script>
</binding>

The code above invokes the print() function. This is a simple extension function that simply prints out its arguments, in order, to the FlightGear console as a single-line log entry. It is useful for debugging, but little else.

=== System-wide Nasal code ===

Nasal scripts that are not specific to certain aircraft, instruments or other uses, generally reside in the system-wide [[$FG ROOT]]/Nasal directory.

Nasal scripts that are placed inside [[$FG ROOT]]/Nasal (with a *.nas extension) are automatically loaded and run during FlightGear startup.

=== Nasal sub modules ===

As of 06/2011, FlightGear also supports so called Nasal "sub modules" which may reside in their own sub folder under $FG_ROOT/Nasal/ and which provide support for on-demand loading at runtime by toggling properties.

Some advantages are:

* Nasal files can be grouped neatly instead of all scripts being mixed up in a single fgdata/Nasal directory. Grouping makes a lot of sense for modules consisting of several scripts - local weather is the best example.
* Guaranteed loading sequence. Submodules are loaded _after_ the main fgdata/Nasal scripts, so they can rely on all fgdata/Nasal content to be already present. No more need for awkward listener callbacks, just to make sure that basic "props" or "gui" modules are available.
* Finally, users have the option to disable loading modules. Unfortunately, just loading scripts (code/data) into memory already causes certain _run-time_ performance effects - even if the Nasal code was never executed (so even when all listeners/timers were disabled).

Please note that there is a difference between the _individual_ Nasal files in fgdata/Nasal and files belonging to a common Nasal _module in general (no matter whether loaded at run-time or loaded at start-up using a "<nasal>" tag).

The individual Nasal files in fgdata/Nasal have an own namespace _each_. The namespace get's the name of the Nasal file itself. So if you have a "gui.nas" in the directory, then you can reference a symbol "foo" using "gui.foo".

Nasal modules also have a single namespace. But all files belonging to the module share this _single_ namespace. The name of their namespace is made from its directory (for the run-time loadable modules), or from the specific tag given below the <nasal> XML element, which are often used for a/c specific modules (e.g. <nasal><ufo>...</ufo></nasal> creates the ufo Nasal namespace in ufo-set.xml).

'''So each Nasal file in a new Nasal "module" folder now shares the same namespace.'''

For more information on Nasal sub modules, please see [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg32657.html] and [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg33458.html].

=== User specific Nasal scripts ===

It's also possible to put Nasal files into $FG_HOME/Nasal/, that is: ~/.fgfs/Nasal/ on Unix, and %APPDATA%\flightgear.org\Nasal\ on MS Windows. This has the following advantages:

* one doesn't have to mix local extensions with standard files
* one is less likely to lose such local additions when upgrading
* one doesn't need write permission to $FG_ROOT/Nasal/ or
* one doesn't have to become "root" to edit such files

The files are guaranteed to be read after all the files in $FG_ROOT/Nasal/, so one can safely use elements of files like props.nas (props.Node), or globals.nas (setlistener() without leading underscore).

The files are guaranteed to be read in alphabetic order. So, if there are two files where one depends on the other, just name them appropriately.

The contents of each file are added to a namespace derived from the filename. So, all functions and variables of a file ~/.fgfs/nasal/local.nas will be added to nasal namespace "local", and a function test() is globally accessible as local.test().

It's possible to extend a standard module like "math" with definitions in ~/.fgfs/Nasal/math.nas, though this should, of course, not be exploited by code that is to be submitted to cvs.

== Hello world ==

A simple hello world example in Nasal would be:

# hello.nas
print('Hello World!');

This will show the "Hello World" string during startup in the console window. The hash sign (#) just introduces comments (i.e. will be ignored by the interpreter).

Note: Script-specific symbols such as global variables (or functions) will be put into a scope (namespace) based on the script's name, scripts embedded via aircraft-set.xml files can separately specify a corresponding module name (see [[Howto: Make an aircraft]] for details).

Strings in Nasal can also use double quotes which support escaping:
# hello.nas
print("Hello\nWorld!");

Double quotes support typical escape sequences:

* \n Newline
* \t Horizontal Tab
* \v Vertical Tab
* \b Backspace
* \r Carriage Return
* \f Form feed
* \a Audible Alert (bell)
* \\ Backslash
* \? Question mark
* \' Single quote
* \" Double quote

For example, to print a new line, use:

print ("\n");

To print a quoted string, use:

print ("\"quoted string\"");

and so on.

Single quotes treat everything as literal except for embedded single quotes (including embedded whitespace like newlines).

Nasal strings are always arrays of bytes (never characters: see the utf8 library if you want character-based equivalents of substr() et. al.). They can be indexed just like in C (although note that there is no nul termination -- get the length with size()):

== Editing code files ==

Note that there is currently no way to tell FlightGear to reload Nasal scripts from the global Nasal directory at runtime, so in order to see changes take effect, you will have to exit and restart FlightGear for the time being. Note that there are some workarounds available, see: [[Nasal_scripting_language#Loading.2Freloading_Nasal_code_without_re-starting_Flightgear|reloading Nasal code without re-starting FlightGear]].

Also, note that as of 05/2009, Nasal in FlightGear does not yet support any form of dependency resolution. In other words, there's no "import", "require" or "include" directive - this is also why most code in FlightGear is wrapped inside a _setlistener() call instead, which in turn waits for a FlightGear signal before executing the code (see below for details).

== Variables ==
Nasal scripts should make use of the var keyword when declaring variables. The "var" keyword makes a variable guaranteed to be local. Nasal, natively provides support for scalars (numbers, strings), lists (arrays, vectors) and hashes (objects or dictionaries), more complex data structures (such as trees) can be built using vectors or hashes.

var w=100; # w is a local numerical variable
var x="hello"; # x is a local string variable
var y=[]; # y is a local vector (array)
var z={}; # z is a local hash (dictionary or table) - also used for OOP

Nasal supports a "nil" value for use as a null pointer equivalent:

var foo=nil;

Also, note that Nasal symbols are case-sensitive, these are all different variables:

var show = func(what) {print(what,"\n");}
var abc=1; # these are all different symbols
var ABC=2; # different from abc
var aBc=3; # different from abc and ABC

show(abc);
show(ABC);
show(aBc);

Please note that functions assigned to variables are no exception. If you write code without using "var" on variables, then you risk (often hard to debug) breakage at a later time because you may be overwriting symbols in another namespace.

So functions bound to variables should use the "var" keyword as well:

var hello = func {
print("hello\n");
}

But there's another reason why "var" should be used consequently, even if a variable is safe enough from later side effects, because it has a relatively specific or unique name: The "var" keyword makes
reading code for others (and for the author after some time) easier, as it makes clear: "this variable starts its life *HERE*". No need to search around to see whether assigning a value to it means something to other code outside or not. Also, with an editor offering proper syntax highlighting reading such code is actually easier, despite the "noise".

The problem with nasal code that does not make use of the var keyword is, that it can break other code, and with it the whole system, but no Nasal error message will point you there, as it's syntactically and semantically correct code. Just doing things that it wasn't supposed to do.
For a more in-depth discussion, please see [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg13557.html].

Also, Nasal scripts that are loaded from $FG_ROOT/Nasal are automatically placed inside a namespace that is based on the script's name.

For example, referring to our earlier "Hello World" example, global variables defined in the hello.nas script would be accessible by using "hello" as prefix from other modules:

# hello.nas
var greeting="Hello World"; # define a greeting symbol inside the hello namespace

If you were now to read out the value from the greeting variable from another Nasal module, you would have to use the hello prefix:

# greetme.nas
print(hello.greeting); # the hello prefix is referring to the hello namespace (or module).

==Namespaces==
The Nasal Console built into FlightGear is quite handy when it comes to debugging code. However, here the namespaces need to be considered. In addition, Nasal sub modules (see above) have some special rules, too - basically, all Nasal files part of a "sub module" share a single name space based on the folder's name rather than the name of the individual Nasal files.

For cases of Nasal code specific for an aircraft (like instruments, for example), the corresponding scripts could be loaded through the aircraft's <tt>-set.xml</tt> file by putting it into the <tt><nasal>...</nasal><tt> section

<nasal>
...
<moduleA>
<file>path/to/file1.nas</file>
<file>path/to/file2.nas</file>
</moduleA>
<moduleB>
<file>path/to/file3.nas</file>
</moduleB>
</nasal>

In this case, variables in files <tt>path/to/file1.nas</tt> and <tt>path/to/file2.nas</tt> can be used in the Nasal console as

moduleA.varName;

Variables in <tt>path/to/file3.nas</tt> can be accessed as

moduleB.varName;

Please note that Nasal sub modules (i.e. files loaded and run from their own Nasal sub directory), are subject to some special rules, as all Nasal source files are automatically loaded into the same namespace, which is by default based on the sub module's folder name.

'''''More information can be found by clicking [http://wiki.flightgear.org/Namespaces_and_Methods here].'''''

== Variables - Advanced Uses ==

Nasal, also supports Multi-assignment expressions. You can assign more than one variable (or lvalue) at a time by putting them in a parenthesized list:

(var a, var b) = (1, 2);
var (a, b) = (1, 2); # Shorthand for (var a, var b)
(var a, v[0], obj.field) = (1,2,3) # Any assignable lvalue works
var color = [1, 1, 0.5];
var (r, g, b) = color; # works with runtime vectors too

Vectors (lists or arrays) can be created from others using an ordered list of indexes and ranges.
This is usually called "vector slicing".
For example:

var v1 = ["a","b","c","d","e"]
#
var v2 = v1[3,2]; # == ["d","c"];
var v3 = v1[1:3]; # i.e. range from 1 to 3: ["b","c","d"];
var v4 = v1[1:]; # no value means "to the end": ["b","c","d","e"]
var i = 2;
var v5 = v1[i]; # runtime expressions are fine: ["c"]
var v6 = v1[-2,-1]; # negative indexes are relative to end: ["d","e"]

The range values can be computed at runtime (e.g. i=1; v5=v1[i:]). Negative indices work the same way they do with the vector functions (-1 is the last element, -2 is 2nd to last, etc...).

== Storage: property tree vs. Nasal ==
With FlightGear's built-in property tree and Nasal's support for it, there are two obvious, and two somewhat competing, ways for storing scalar data: native Nasal variables and FlightGear properties, both of which can be easily accessed and managed from Nasal.

The advantage to native Nasal-space data is that it's fast and simple. If the only thing that will care about the value is your script, they are good choices.

The property tree is an inter-subsystem communication thing. This is what you want if you want to share data with the C++ world (for example, YASim <control-output> tags write to properties -- they don't understand Nasal), or read in via configuration files.

Also, native Nasal data structures are usually far faster than their equivalent in property tree space. This is because there are several layers of indirection in retrieving a property tree value.

In general, this means that you shouldn't make overly excessive use of the property tree for storing state that isn't otherwise relevant to FlightGear or any of its subsystems. Doing that would in fact have adverse effects on the performance of your code. In general, you should favor Nasal variables and data structures and should only make use of properties to interface with the rest of FlightGear, or to easily provide debugging information at run time.

As of FG 2.4.0, retrieving a value from the property tree via getprop is about 50% slower than accessing a native Nasal variable, and accessing the value via node.getValue() is 10-20% slower yet. This is an insignificant amount of time if you are retrieving and storing a few individual values from the property tree, but adds up fast if you are storing or retrieving hashes or large amounts of data. (You can easily benchmark times on your own code using systime() or debug.benchmark.)

In addition, it is worth noting that the Nasal/FlightGear APIs cannot currently be considered to be thread safe, this mean that -at least for now- the explicit use of pure Nasal space variables is the only way to exploit possible parallelism in your code by making use of threads.

== Functions ==

=== What is a function ? ===

A "function" is a piece of code that can be easily used repeatedly (without repeating the same code over and over again), this is achieved by associating a symbolic name with the piece of code, such as "print", "show" or "get" for example. Whenever this symbolic name is then used in the program, the program will "jump" to the definition of the function and start running it, once the called function has completed it will automatically return to the instruction following the call.

By using so called "function arguments" (see below) it is possible to parametrize a function (using variables) so that it may use data that is specific to each invocation.

As previously shown, Nasal functions are implemented using the func keyword, The following snippet of code defines a new function named "log_message" with an empty function body (the curly braces).

var log_message = func {}

=== Function bodies ===

To add a function body, you need to add code in between these curly braces.

=== Anonymous function arguments ===

In Nasal, arguments are by default passed in the "arg" array, not unlike perl. To understand how this works, you should probably first read up on Nasal vectors.

var log_message = func {
print(arg[0]);
}

Note that this is equivalent to:

var log_message = func() {
print(arg[0]);
}

In other words, the argument list "()" can be omitted if it is empty.
However, if you are new to Nasal or programming in general, it is probably a good idea to ALWAYS use parentheses, i.e. also for functions with empty argument lists - that makes it easy to get used to the syntax.

Note that this is just an assignment of an (anonymous) function argument to the local "log_message" variable. There is no function declaration syntax in Nasal.

Also, Nasal being a functional programming language, all passed arguments will be local to the corresponding scope. If you want to modify state in a function, you'll preferably return new state to the caller.

===Named function arguments===
You can also pass named arguments to a function, thus saving the typing and performance costs of extracting them from the arg array:

var log_message = func(msg) {
print(msg);
}

The list of function arguments is called a function's "signature".

=== Default values for function arguments ===

Function arguments can have default values, as in C++. Note that the default value must be a scalar (number, string, function, nil) and not a mutable composite object (list, hash).

var log_message = func(msg="error") {
print(msg);
}

If some arguments have default values and some do not, those with default values must come first in the argument list:

#Incorrect:
var log_message = func(msg="error", line, object="ground") { #some code }

#Correct:
var log_message = func(msg="error", object="ground", line) { #some code }

Any extra arguments after the named list are placed in the "arg" vector as above. You can rename this to something other than "arg" by specifying a final argument name with an ellipsis:

listify = func(elements...) { return elements; }
listify(1, 2, 3, 4); # returns a list: [1, 2, 3, 4]

=== Returning from functions ===

In Nasal, functions return implicitly the values of the last expression (i.e. "nil" in empty function bodies), you can also add an explicit "return" statement, for example to leave a function early. In addition, it is possible to return values, too.

So, semantically, the previous snippet of code is equivalent to these:

var log_message = func {return;}

var log_message = func {nil;}

var log_message = func {};

var log_message = func return;

var log_message = func nil;

===Named arguments in function calls===
Nasal supports named function arguments in function calls, too.

As an alternative to the comma-separated list of ''positional'' function arguments, you can specify a hash literal in place of ordered function arguments, and it will become the local variable namespace for the called function, with variables named according to the hash indexes and with values according to the hash values. This makes functions with many arguments more readable.

And it also makes it possible to call function's without having to take care of the right order of passing arguments.

Examples:
#if we have functions defined:
var log_message = func (msg="") { #some code to log variable msg }
var lookat = func (heading=0, pitch=0, roll=0, x=nil, y=nil, z=nil, time=hil, fov=20) { #some code using those variables }

#we can use them them the usual way with comma separated list of arguments:
log_message("Hello World!");
lookat (180, 20, 0, XO, YO, ZO, now, 55);

#or we can use the hash literal arguments instead:
log_message(msg:"Hello World!");
lookat(heading:180, pitch:20, roll:0, x:X0, y:Y0, z:Z0,time:now, fov:55);

Both methods for calling the functions above are equivalent, but note the the second method is more readable, less prone to error, and self-documenting in the code for the function call.

As another example, consider:

var setPosition = func (latitude_deg, longitude_deg, altitude_ft) {
# do something here
}
# the actual function call:
setPosition( latitude_deg:34.00, longitude_deg:7.00, alt_ft:10000);

In other words, such function calls become much more self-explanatory because everybody can see immediately what a value is doing.
This is a good practice, as you may eventually have to take a longer break, away from your code - and then even you yourself will come to appreciate such small things that make code more intuitive to work with.

Declared arguments are checked and defaulted as would be expected: it's an error if you fail to pass a value for an undefaulted argument, missing default arguments get assigned as usual, and any rest parameter (e.g. "func(a,b=2,rest...){}") will be assigned with an empty vector.

===Nested functions, implicit return ===
Also, Nasal functions can be easily nested, for example:

var calculate = func(param1,param2,operator) {
var add = func(p1,p2) {p1+p2;}
var sub = func(p1,p2) {p1-p2;}
var mul = func(p1,p2) {p1*p2;}
var div = func(p1,p2) {p1/p2;}
if (operator=="+") return add(param1,param2);
if (operator=="-") return sub(param1,param2);
if (operator=="*") return mul(param1,param2);
if (operator=="/") return div(param1,param2);
}

Note that the add,sub,mul and div functions in this example do not make use of an explicit return statement, instead the result of each expression is implicitly returned to the caller.

Nasal functions that just consist of such simple expressions can also be further simplified to read:

var add = func(val1,val2) val1+val2;

=== Function overloading ===

Note that Nasal functions can generally not be [[http://en.wikipedia.org/wiki/Function_overloading overloaded]], and that operator overloading in particular is also not supported.

However, the effects of '''function overloading''' can obviously be implemented individually by each function, simply by processing the number and type of passed arguments at the start of the function body. The FlightGear code base contains a number of examples for this, i.e. it is for example possible to pass properties in the form of plain strings to a callback or in the form of a Nasal wrapper like props.Node.

So this can be accomplished by first checking the argument count and then the types of arguments passed to the function.

To provide an example, here's a simple function to multiply two numbers, no matter if they are provided as scalars, as a vector or as x/y members of a hash:

var multiply2 = func (params) {
if (typeof(params)=="scalar") return params*arg[0];
if (typeof(params)=="vector") return params[0]*params[1];
if (typeof(params)=="hash") return params.x*params.y;
die("cannot do what you want me to do");
}

So, now you have a very simple form of an "overloaded" function that supports different argument types and numbers:

multiply2( 2,6); # multiply two scalars
multiply2( [5,7] ); # multiply two scalars stored in a vector
multiply2( {x:8, y:9} ); # multiply two scalars stored in a hash

You could obviously extend this easily to support an arbitrary number of arguments by just using a for loop here.

As you can see, the basic idea is pretty simple and also scalable, you could easily extend this to and also return different types of values, such as vectors or hashes. This could for example be used to create wrappers in Nasal space for doing 3D maths, with vectors and matrices, so that a matrix multiplication could return a new matrix, too.

===Functional programming, higher order functions, generators;===
As previously mentioned, arguments to a Nasal function can also be functions themselves (Nasal being a functional programming language), this means that Nasal functions are higher order functions so that you can easily pass and return functions to and from Nasal functions. This can for example be used to dynamically create new functions (such functions are commonly called 'generators'):

# a function that returns a new custom function
var i18n_hello = func(hello) {
return func(name) { # returns an anonymous/unnamed function
print(hello,name);
}
}

# create three new functions
var english_hello = i18n_hello("Good Day ");
var spanish_hello = i18n_hello("Buenos Dias ");
var italian_hello = i18n_hello("Buon giorno ");

# actually call these functions
english_hello("FlightGear");
spanish_hello("FlightGear");
italian_hello("FlightGear");

=== Using helper functions ===

It is possible to simplify complex function calls by introducing small helper functions, for example consider:

var l = thermalLift.new(ev.lat, ev.lon, ev.radius, ev.height, ev.cn, ev.sh, ev.max_lift, ev.f_lift_radius);

So, you could just as well create a small helper function named"thermalLift.new_from_ev(ev)":

thermalLift.new_from_ev = func (ev) {
thermalLift.new(ev.lat, ev.lon, ev.radius, ev.height, ev.cn, ev.sh, ev.max_lift, ev.f_lift_radius);
}

var l=thermalLift.new_from_ev(ev);

Note that the expression to invoke your code would then also become less complicated and much more comprehensible.

When you have expressions of nested method calls, such as:

t.getNode("latitude-deg").setValue(f.getNode("latitude-deg").getValue());
t.getNode("longitude-deg").setValue(f.getNode("longitude-deg").getValue());

You could just as easily introduce a small helper function to wrap the code, that would be less typing for you, less code to read (and understand) for others and generally it would help localize functionality (and possible errors):

var copyNode = func(t,f,path) t.getNode(path).setValue(f.getNode(path).getValue());

So you would simply take the complex expression and generalize it by adding variables that you pass in from a function object, then you could simply call your new function like this:

copyNode(t,f,"latitude-deg");
copyNode(t,f,"longitude-deg");

or:

foreach(var p; ["latitude-deg", "longitude-deg","generated-flag"])
copyNode(t,f,p);

or as a complete function accepting a vector of properties:

var copyNode = func(target,source,properties) {
if (typeof(properties)!="vector") properties=[properties];
if (typeof(target)!="hash") target=props.globals.getNode(target);
if (typeof(source)!="hash") target=props.globals.getNode(source)
foreach(var path; properties)
target.getNode(path).setValue( source.getNode(path).getValue() );
}

copyNode("/temp/test", "/position", ["latitude-deg", "longitude-deg", "altitude-ft"]);

Whenever you have very similar lines of code that seem fairly repetitive, it is a good idea to consider introducing small helper functions. You can use plenty of small helper functions and then just "chain" them together, rather than using complex nested expressions that make your head spin.

== Conditionals ==

Nasal has no "statements", which means that any expression can appear in any context. This means that you can use an if/else clause to do what the ?: does in C.
The last semicolon in a code block is optional, to make this prettier

abs = func(n) { if(n<0) { -n } else { n } }

But for those who don't like typing, the ternary operator works like you expect:

abs = func(n) { n < 0 ? -n : n }

In addition, Nasal supports braceless blocks, like they're known from C/C++ and other languages:

var foo=1;
if (foo)
print("1\n");
else
print("0\n");
print("this is printed regardless\n")

Instead of a switch statement one can use

if (1==2) {
print("wrong");
} else if (1==3) { # NOTE the space between else and if
print("wronger");
} else {
print("don't know");
}

which produces the expected output of <code>don't know</code>

The <tt>nil</tt> logic is actually quite logical, let's just restate the obvious:

if (nil) {
print("This should never be printed");
} else {
print("This will be printed, because nil is always false");
};

Nasal's binary boolean operators are "and" and "or", unlike C. unary not is still "!" however.
They short-circuit like you expect

var toggle = 0;
var a = nil;
if(a and a.field == 42) {
toggle = !toggle; # doesn't crash when a is nil
}

You can easily reduce the complexity of huge conditional (IF) statements, such as this one:

if (a==1) function_a();
else
if (a==2) function_b();
else
if (a==3) function_c();
else
if (a==4) function_d();
else
if (a==5) function_e();

.. just by using the variable as a key (index) into a hash, so that you can directly call the corresponding function:

var mapping = {1:function_a, 2:function_b, 3:function_c, 4:function_d,5:function_e};
mapping[a] ();

This initializes first a hash map of values and maps a function "pointer" to each value, so that accessing mapping[x] will return the function pointer for the key "x".

Next, you can actually call the function by appending a list of function arguments (empty parentheses for no args) to the hash lookup.

Using this technique, you can reduce the complexity of huge conditional blocks. For example, consider:

# weather_tile_management.nas
460 if (code == "altocumulus_sky"){weather_tiles.set_altocumulus_tile();}
461 else if (code == "broken_layers") {weather_tiles.set_broken_layers_tile();}
462 else if (code == "stratus") {weather_tiles.set_overcast_stratus_tile();}
463 else if (code == "cumulus_sky") {weather_tiles.set_fair_weather_tile();}
464 else if (code == "gliders_sky") {weather_tiles.set_gliders_sky_tile();}
465 else if (code == "blue_thermals") {weather_tiles.set_blue_thermals_tile();}
466 else if (code == "summer_rain") {weather_tiles.set_summer_rain_tile();}
467 else if (code == "high_pressure_core") {weather_tiles.set_high_pressure_core_tile();}
468 else if (code == "high_pressure") {weather_tiles.set_high_pressure_tile();}
469 else if (code == "high_pressure_border") {weather_tiles.set_high_pressure_border_tile();}
470 else if (code == "low_pressure_border") {weather_tiles.set_low_pressure_border_tile();}
471 else if (code == "low_pressure") {weather_tiles.set_low_pressure_tile();}
472 else if (code == "low_pressure_core") {weather_tiles.set_low_pressure_core_tile();}
473 else if (code == "cold_sector") {weather_tiles.set_cold_sector_tile();}
474 else if (code == "warm_sector") {weather_tiles.set_warm_sector_tile();}
475 else if (code == "tropical_weather") {weather_tiles.set_tropical_weather_tile();}
476 else if (code == "test") {weather_tiles.set_4_8_stratus_tile();}
477 else ...

While this is not a very complex or huge block of code, it is an excellent example for very good naming conventions used already, because the consistency of naming variables and functions can pay off easily here, with just some very small changes, you can already reduce the whole thing to a hash lookup like this:

weather_tiles["set_"~code~"_tile"](); # naming convention

This would dynamically concatenate a key consisting of "set_" + code + "_title" into the hash named weather_tiles, and then call the function that is returned from the hash lookup.

So for this to work you only need to enforce consistency when naming your functions (i.e. this would of course CURRENTLY fail when the variable code contains "test" because there is no such hash member (it's "4_8_stratus" instead).

The same applies to cumulus sky (fair weather), stratus/overcast stratus.

But these are very simple changes to do (just renaming these functions to match the existing conventions). When you do that, you can easily replace such huge IF statements and replace them with a single hash lookup and function call:

hash[key] (arguments...);

For example, consider:

var makeFuncString = func(c) return tolower("set_"~c~"_tile");
var isFunc = func(f) typeof(f)=='func';
var hasMethod = func(h,m) contains(h,m) and isFunc;
var callIfAvailable = func(hash, method, unavailable=func{} ) {
var c=hasMethod(hash,makeFuncString(m) ) or unavailable();
hash[makeFuncString(m)] ();
}
callIfAvailable( weather_tiles,code, func {die("key not found in hash or not a func");} );

== Initializing data structures ==

There are some more possibilities to increase the density of your code, such as by removing redundant code or by generalizing and refactoring existing code so that it can be reused in different places (i.e. avoiding duplicate code):

For example see weather_tile_management.nas #1000 (create_neighbours function):

1008 x = -40000.0; y = 40000.0;
1009 setprop(lw~"tiles/tile[0]/latitude-deg",blat + get_lat(x,y,phi));
1010 setprop(lw~"tiles/tile[0]/longitude-deg",blon + get_lon(x,y,phi));
1011 setprop(lw~"tiles/tile[0]/generated-flag",0);
1012 setprop(lw~"tiles/tile[0]/tile-index",-1);
1013 setprop(lw~"tiles/tile[0]/code","");
1014 setprop(lw~"tiles/tile[0]/timestamp-sec",weather_dynamics.time_lw);
1015 setprop(lw~"tiles/tile[0]/orientation-deg",alpha);
1016
1017 x = 0.0; y = 40000.0;
1018 setprop(lw~"tiles/tile[1]/latitude-deg",blat + get_lat(x,y,phi));
1019 setprop(lw~"tiles/tile[1]/longitude-deg",blon + get_lon(x,y,phi));
1020 setprop(lw~"tiles/tile[1]/generated-flag",0);
1021 setprop(lw~"tiles/tile[1]/tile-index",-1);
1022 setprop(lw~"tiles/tile[1]/code","");
1023 setprop(lw~"tiles/tile[1]/timestamp-sec",weather_dynamics.time_lw);
1024 setprop(lw~"tiles/tile[1]/orientation-deg",alpha);
1025
1026 x = 40000.0; y = 40000.0;
1027 setprop(lw~"tiles/tile[2]/latitude-deg",blat + get_lat(x,y,phi));
1028 setprop(lw~"tiles/tile[2]/longitude-deg",blon + get_lon(x,y,phi));
1029 setprop(lw~"tiles/tile[2]/generated-flag",0);
1030 setprop(lw~"tiles/tile[2]/tile-index",-1);
1031 setprop(lw~"tiles/tile[2]/code","");
1032 setprop(lw~"tiles/tile[2]/timestamp-sec",weather_dynamics.time_lw);
1033 setprop(lw~"tiles/tile[2]/orientation-deg",alpha);
1034
1035 x = -40000.0; y = 0.0;
1036 setprop(lw~"tiles/tile[3]/latitude-deg",blat + get_lat(x,y,phi));
1037 setprop(lw~"tiles/tile[3]/longitude-deg",blon + get_lon(x,y,phi));
1038 setprop(lw~"tiles/tile[3]/generated-flag",0);
1039 setprop(lw~"tiles/tile[3]/tile-index",-1);
1040 setprop(lw~"tiles/tile[3]/code","");
1041 setprop(lw~"tiles/tile[3]/timestamp-sec",weather_dynamics.time_lw);
1042 setprop(lw~"tiles/tile[3]/orientation-deg",alpha);
1043
1044 # this is the current tile
1045 x = 0.0; y = 0.0;
1046 setprop(lw~"tiles/tile[4]/latitude-deg",blat + get_lat(x,y,phi));
1047 setprop(lw~"tiles/tile[4]/longitude-deg",blon + get_lon(x,y,phi));
1048 setprop(lw~"tiles/tile[4]/generated-flag",1);
1049 setprop(lw~"tiles/tile[4]/tile-index",1);
1050 setprop(lw~"tiles/tile[4]/code","");
1051 setprop(lw~"tiles/tile[4]/timestamp-sec",weather_dynamics.time_lw);
1052 setprop(lw~"tiles/tile[4]/orientation-deg",getprop(lw~"tmp/tile-orientation-deg"));
1053
1054
1055 x = 40000.0; y = 0.0;
1056 setprop(lw~"tiles/tile[5]/latitude-deg",blat + get_lat(x,y,phi));
1057 setprop(lw~"tiles/tile[5]/longitude-deg",blon + get_lon(x,y,phi));
1058 setprop(lw~"tiles/tile[5]/generated-flag",0);
1059 setprop(lw~"tiles/tile[5]/tile-index",-1);
1060 setprop(lw~"tiles/tile[5]/code","");
1061 setprop(lw~"tiles/tile[5]/timestamp-sec",weather_dynamics.time_lw);
1062 setprop(lw~"tiles/tile[5]/orientation-deg",alpha);
1063
1064 x = -40000.0; y = -40000.0;
1065 setprop(lw~"tiles/tile[6]/latitude-deg",blat + get_lat(x,y,phi));
1066 setprop(lw~"tiles/tile[6]/longitude-deg",blon + get_lon(x,y,phi));
1067 setprop(lw~"tiles/tile[6]/generated-flag",0);
1068 setprop(lw~"tiles/tile[6]/tile-index",-1);
1069 setprop(lw~"tiles/tile[6]/code","");
1070 setprop(lw~"tiles/tile[6]/timestamp-sec",weather_dynamics.time_lw);
1071 setprop(lw~"tiles/tile[6]/orientation-deg",alpha);
1072
1073 x = 0.0; y = -40000.0;
1074 setprop(lw~"tiles/tile[7]/latitude-deg",blat + get_lat(x,y,phi));
1075 setprop(lw~"tiles/tile[7]/longitude-deg",blon + get_lon(x,y,phi));
1076 setprop(lw~"tiles/tile[7]/generated-flag",0);
1077 setprop(lw~"tiles/tile[7]/tile-index",-1);
1078 setprop(lw~"tiles/tile[7]/code","");
1079 setprop(lw~"tiles/tile[7]/timestamp-sec",weather_dynamics.time_lw);
1080 setprop(lw~"tiles/tile[7]/orientation-deg",alpha);
1081
1082 x = 40000.0; y = -40000.0;
1083 setprop(lw~"tiles/tile[8]/latitude-deg",blat + get_lat(x,y,phi));
1084 setprop(lw~"tiles/tile[8]/longitude-deg",blon + get_lon(x,y,phi));
1085 setprop(lw~"tiles/tile[8]/generated-flag",0);
1086 setprop(lw~"tiles/tile[8]/tile-index",-1);
1087 setprop(lw~"tiles/tile[8]/code","");
1088 setprop(lw~"tiles/tile[8]/timestamp-sec",weather_dynamics.time_lw);
1089 setprop(lw~"tiles/tile[8]/orientation-deg",alpha);
1090 }

At first glance, this seems like a fairly repetitive and redundant block of code, so it could probably be simplified easily:

var create_neighbours = func (blat, blon, alpha) {
var phi = alpha * math.pi/180.0;
calc_geo(blat);
var index=0;
var pos = [ [-40000.0,40000.0], [0.0, 40.000], [40000.0, 40000.0], [-40000, 0], [0,0], [40000,0], [-40000,-40000], [0,-40000], [40000,-40000] ];
foreach (var p;pos) {
x=p[0]; y=p[1];
setprop(lw~"tiles/tile[index]/latitude-deg",blat + get_lat(x,y,phi));
setprop(lw~"tiles/tile[index]/longitude-deg",blon + get_lon(x,y,phi));
setprop(lw~"tiles/tile[index]/generated-flag",0);
setprop(lw~"tiles/tile[index]/tile-index",-1);
setprop(lw~"tiles/tile[index]/code","");
setprop(lw~"tiles/tile[index]/timestamp-sec",weather_dynamics.time_lw);
setprop(lw~"tiles/tile[index]/orientation-deg",alpha);
index=index+1;
}
}

== Loops ==

Nasal has several ways to implement an iteration.

===for, while, foreach, and forindex loops===
Nasal's looping constructs are mostly C-like:

for(var i=0; i < 3; i = i+1) {
# loop body
}

while (condition) {
# loop body
}

The differences are that there is no do{}while(); construct, and there is a foreach, which takes a local variable name as its first argument and a vector as its second:

foreach(elem; list1) { doSomething(elem); } # NOTE: the delimiter is a SEMICOLON ;

The hash/vector index expression is an lvalue that can be assigned as well as inspected:

foreach(light; lights) { lightNodes[light] = propertyPath; }

To walk through all elements of a hash, for a foreach loop on the keys of they hash. Then you call pull up the values of the hash using the key. Example:

myhash= {first: 1000, second: 250, third: 25.2 };
foreach (var i; keys (myhash)) {
#multiply each value by 2:
myhash[i] *= 2;
#print the key and new value:
print (i, ": ", myhash[i]);
}

There is also a "forindex", which is like foreach except that it assigns the index of each element, instead of the value, to the loop variable.

forindex(i; list1) { doSomething(list1[i]); }

Also, braceless blocks work for loops equally well:

var c=0;
while( c<5 )
print( c+=1 );
print("end of loop\n");

===settimer loops===
Loops using <tt>while</tt>, <tt>for</tt>, <tt>foreach</tt>, and <tt>forindex</tt> block all of FlightGear's subsystems that run in the main thread, and can, thus, only be used for instantaneous operations that don't take too long.

For operations that should continue over a longer period, one needs a non-blocking solution. This is done by letting functions call themselves after a timed delay:

var loop = func {
print("this line appears once every two seconds");
settimer(loop, 2);
}

loop(); # start loop

Note that the <tt>settimer</tt> function expects a ''function object'' (<tt>loop</tt>), not a function call (<tt>loop()</tt>) (though it is possible to make a function call return a function object--an advanced functional programming technique that you won't need to worry about if you're just getting started with Nasal).

The fewer code FlightGear has to execute, the better, so it is desirable to run loops only when they are needed. But how does one stop a loop? A once triggered timer function can't be revoked. But one can let the loop function check an outside variable and refuse calling itself, which makes the loop chain die off:

var running = 1;
var loop = func {
if (running) {
print("this line appears once every two seconds");
settimer(loop, 2);
}
}

loop(); # start loop ...
...
running = 0; # ... and let it die

Unfortunately, this method is rather unreliable. What if the loop is "stopped" and a new instance immediately started again? Then the ''running'' variable would be ''1'' again, and a pending old loop call, which should really finish this chain, would happily continue. And the new loop chain would start, too, so that we would end up with two loop chains.

This can be solved by providing each loop chain with a ''loop identifier'' and letting the function end itself if the id doesn't match the global loop-id. Self-called loop functions need to inherit the chain id. So, every time the global loop id is increased, all loop chains die, and a new one can immediately be started.

var loopid = 0;
var loop = func(id) {
id == loopid or return; # stop here if the id doesn't match the global loop-id
...
settimer(func { loop(id) }, 2); # call self with own loop id
}

loop(loopid); # start loop
...
loopid += 1; # this kills off all pending loops, as none can have this new identifier yet
...
loop(loopid); # start new chain; this can also be abbreviated to: loop(loopid += 1);

[[Nasal_scripting_language#settimer.28.29|More information about the settimer function is below]]

== OOP - Object Oriented Programming ==

In Nasal, objects ("classes") are regular hashes. Self-reference and inheritance are implemented through special variables <tt>me</tt> and <tt>parents</tt>. To get a better understanding of the concept, let's start with the very basics.

=== Hashes ===

Hashes, also known as "dictionaries" in Python or "maps" in C++/STL are data structures that hold key/value pairs in a way that allows quick access to a value via its key.

var airport = {
"LOXZ": "Zeltweg",
"LOWI": "Innsbruck",
"LOXL": "Linz Hoersching", # the last comma is optional
};

print(airport["LOXZ"]); # prints "Zeltweg"
airport["LOXA"] = "Aigen"; # adds LOXA to the hash

The built-in function keys() returns a vector with the keys of the hash. The function values() returns a vector with the values of the hash. For example:

debug.dump (keys(airport)); #prints ['LOXZ', 'LOWI', 'LOXL']
debug.dump (values (airport)); #prints ['Zeltweg', 'Innsbruck', 'Linz Hoersching']

The quotes around keys can be left away in a hash definition if the key is a valid variable name or a number. This works just as well:

var airport = {
LOXZ: "Zeltweg",
};

There's also an alternative way to access hash members if the keys are valid variable names: <tt>airport.LOXI</tt> can be used instead of <tt>airport["LOXI"]</tt>. There is a difference, though, which is described in the next section.

Note that assigning a hash (or a vector) to another variable does never ''copy'' the contents. It only creates another reference to the same data structure. So manipulating the hash via its new name does in fact change the one, original hash.

var a = airport;
a.LOXL = "Linz"; # same as airport.LOXL!
print(airport.LOXL); # prints now "Linz", not "Linz Hoersching"

(True copies of vectors can be made by assigning a full slice: <tt>var copy = vec[:]</tt>. There's no such method for hashes.)

=== Self-reference: "<tt>me</tt>" ===

Values stored in a hash can be of any type, even of type ''function''. Member functions ("methods") can reference their own enclosing hash via reserved keyword <tt>me</tt>. This is comparable to the <tt>this</tt> keyword in C++ classes, or the <tt>self</tt> keyword in Python.

var value = "test";

var data = {
value: 23, # scalar member variable
write1: func { print(value); }, # function member
write2: func { print(me.value); }, # function member
};

data.write1(); # prints "test"
data.write2(); # prints 23

The above example is already a simple form of an object. It has its own variable namespace (''data''), its own methods, and it can be passed around by-reference as one unit. Such classes are sometimes called ''singleton classes'', as they are unique, with no independent class instances. They mostly serve as a way to keep data and methods nicely encapsulated within a Nasal module. Often they contain a method for initializing, which is usually called <tt>init</tt>.

=== Inheritance: "<tt>parents</tt>" ===

What we learned about <tt>me</tt> in the last section is only half the truth. "me" doesn't only reference an object's own hash, but also one or more parent hashes. <tt>parents</tt> is another reserved keyword. It denotes a vector referencing other object hashes, which are "inherited" that way.

Please note that Nasal's currently supported form of encapsulation does not provide support for any form of data/information hiding (restricting access), i.e. all hash fields (but also all hash methods) are always publicly accessible (so there's nothing like the "private" or "protected" keywords in C++: in this sense, Nasal's inheritance mechanism can be thought of like C++ structs which are also public by default).

The major difference being, that all members (functions and fields) are also always '''mutable''', which means that functions can modify the behavior of other functions quite easily, this also applies to the parents vector, too.

var parent_object = {
value: 123,
};

var object = {
parents: [parent_object],
write: func { print(me.value) },
};

object.write(); # prints 123

Even though <tt>object</tt> itself doesn't contain a member <tt>value</tt>, it finds and uses the one of its parent object. <tt>parents</tt> is a vector that can contain several parent objects. These are then searched in the order from left to right, until a matching member variable or method is found. Each of the parents can itself have parents, which are all recursively searched.

In the section about hashes it was said that hash members can be accessed in two alternative ways, and that's also true for methods. <tt>object.write()</tt> could also be called as <tt>object["write"]()</tt>. But only in the first form will members also be searched in parent hashes if not found in the base hash, whereas the second form creates an error if it's not a direct member.

=== Creating class instances ===

With <tt>me</tt> and <tt>parents</tt> we can implement a class object and create independent instances from that:

var Class = {
write: func { print(me.value); },
increment: func { me.value += 1; },
};

var instance1 = { parents: [Class], value: 123 };
var instance2 = { parents: [Class], value: 456 };

instance1.write(); # prints 123
instance2.write(); # prints 456

As you can see, the two class instances are separate, independent objects, which share another object as parent -- they "inherit" from object <tt>Class</tt>. One can now easily change members of any of these three objects. The following will redefine the parent's <tt>write</tt> method, and all instances will automatically use this new version:

Class.write = func { print("VALUE = " ~ me.value) }

But one can also add a method to just one instance:

instance1.write = func { print("VALUE = " ~ me.value) }

Because <tt>instance1</tt> does now have its own <tt>write</tt> method, the parents won't be searched for one, so <tt>Class.write</tt> is now overridden by <tt>instance1</tt>'s own method. Nothing changed for <tt>instance2</tt> -- it will still only find and use <tt>Class.write</tt> via its parent.

Note, the we couldn't create a class instance by simple assignment, because, as we learned above, this wouldn't create a separate copy of the Class object. All "instances" would reference the same hash!

var bad_instance1 = Class; # bad
var bad_instance2 = Class; # bad

bad_instance1.value = 123; # sets Class.value to 123
bad_instance2.value = 456; # sets Class.value to 456

bad_instance1.write(); # prints 456, not 123

=== Constructor ===

Defining each class instance by explicitly creating a hash with parents is clumsy. It is nicer to have a function that does that for us. Then we can also use function arguments to initialize members of this instance.

var new_class = func(val) {
return { parents: [Class], value: val };
}

var instance1 = new_class(123);
var instance2 = new_class(456);

instance1.write(); # prints 123
instance2.write(); # prints 456

Because the class generating function <tt>new_class()</tt> really belongs to class <tt>Class</tt>, it would be nicer to put it into the class hash as well. In this case we call it a class "constructor", and as a convention, give it the name ''new''. It could have any name, though, and there could be more than one constructor.

var Class = {
new: func(val) {
return { parents: [Class], value: val };
},
write: func {
print("VALUE=" ~ me.value);
},
};

var instance1 = Class.new(123);
var instance2 = Class.new(456);

As you can see, <tt>new()</tt> doesn't return a copy of <tt>Class</tt>, but rather a small hash that contains only a list of parents and one individual member <tt>value</tt>.

Classes aren't always as simple as in our example. Usually they contain several members, of which some may have yet to be calculated in the constructor. In that case it's easier to create a local object hash first, and to let the constructor finally return it. Such local hashes are often named <tt>m</tt> (as a short reference to <tt>me</tt>), or <tt>obj</tt>.

var Class = {
new: func(val) {
var m = { parents: [Class] };
m.value = val;
return m;
},
write: func {
print("VALUE=" ~ me.value);
},
};

This last example is the most frequently used form of class definitions in FlightGear-Nasal.

=== Destructor ===

There's no such thing in Nasal. In other languages destructors are automatically called when the class gets destroyed, so that memory and other resources that were allocated by the constructor can be freed. In Nasal that's all done by the Garbage Collector (GC), anyway. In the FlightGear context, however, there ''are'' resources that should get freed. Listeners should get removed, self-calling functions ("loops") stopped. For that it's recommended to create a destructor function and to call that manually. Such functions are often called <tt>del</tt>, similar to Python and to pair nicely with the three-letter constructor name <tt>new</tt>.

=== Memory management ===

Finally, as you know now, Nasal, being a dynamic programming language, doesn't require or support any manual memory management, so unlike C++, you don't need to call operators like "new" or "delete" to allocate or free your memory.

However, if you do know that you don't need a certain variable anymore, you can certainly give a hint to the built-in garbage collector to free it, by assigning a "nil" value to it.

This can certainly pay off when using more complex data structures such as nested vectors or hashes, because it will tell the built-in garbage collector to remove all references to the corresponding symbols, so that they can be freed.

It is also possible to make use of Nasal's delete() function to remove a symbol from a namespace (hash).

So, if you are concerned about your script's memory requirements, using a combination of setting symbols to nil, or deleting them as appropriate, would allow you to create helper functions for freeing data structures easily.

In addition, it is probably worth noting that this is also the only way to sanely reset an active Nasal namespace or even the whole interpreter. You need to do this in order to reload or re-initialize your code without restarting the whole FlightGear session [[Nasal_scripting_language#Managing_timers_and_listeners]].

Obviously, you should first of all ensure that there is no more code running, this includes any registered listeners or timers, but also any others loops or recursive functions.

Thus, if you'd like to reload a Nasal source file at run time, you should disable all running code, and then reset the corresponding namespace, too. This is to ensure that you get a clean and consistent namespace.

Nasal provides a number of core library functions to manipulate namespaces, such as:

* caller() - to get a strack trace of active functions currently on the Nasal stack
* compile() - to compile new Nasal code "on the fly", i.e. dynamically from a string
* closure() - to query the lexical namespace of active functions
* bind() - to create new function objects

More information is available here: http://www.plausible.org/nasal/lib.html

If, on the other hand, you are using these data structures in some repeated fashion, it might make sense to keep the data structure itself around and simply re-use it next time (overwriting data as required), instead of always allocating/creating a new one, this is called "caching" and can pay off from a performance perspective.

=== Multiple inheritance ===

A class can inherit from one or more other classes. It can then access all methods and class members of all parent classes, but also override them and add additional members.

var A = { # simple class A
new: func {
return { parents: [A] };
},
alpha: func print("\tALPHA"),
test: func print("\tthis is A.test"),
};

var B = { # simple class B
new: func(v) { # ... whose constructor takes an argument
return { parents: [B], value: v };
},
bravo: func print("\tBRAVO"),
test: func print("\tthis is B.test"),
write: func print("\tmy value is: ", me.value),
},

var C = { # class C that inherits ...
new: func(v) {
return { parents: [C, A.new(), B.new(v)] }; # ... from class A and B
},
charlie: func print("\tCHARLIE"),
test: func print("\tthis is C.test"), # overrides A.test() and B.test()
};

print("A instance");
var a = A.new();
a.alpha();

print("B instance");
var b = B.new(123);
b.bravo();
b.write();

print("C instance");
var c = C.new(456);
c.alpha(); # use alpha from the A parent
c.bravo(); # use bravo from the B parent
c.charlie(); # use charlie from C itself
c.test(); # use C.test(), which overrides A.test() and B.test()
c.write();

Even if a class overrides a method of a parent with the same name, the parent's version can still be accessed via <tt>parents</tt> vector.

c.test() # use C.test()
c.parents[0].test(); # use C.test()
c.parents[1].test(); # use A.test()
c.parents[2].test(); # use B.test()

=== More on methods ===

Methods are function members of a class hash. They can access other class members via the <tt>me</tt> variable, which is a reference to the class hash. For this reason, a method returning <tt>me</tt> can be used like the class itself, and one can apply further methods to the return value (this is usually called "method chaining"):

var Object = {
new: func(coords...) {
return { parents: [Object], coords: coords };
},
rotate: func(angle) {
# do the rotation
return me;
},
scale: func(factor) {
# do the scaling
return me;
},
translate: func(x, y) {
# do the translation
return me;
},
};

var triangle = Object.new([0, 0], [10, 0], [5, 7]);
triangle.translate(-9, -4).scale(5).rotate(33).translate(9, 4); # concatenated methods thanks to "me"

<tt>me</tt>, however, is only known in the scope of the class. If a method is to be called as a listener callback or a timer function, <tt>me</tt> has to get wrapped in a function, so that it's stored in the function closure.

var Manager = {
new: func {
return { parents: [Manager] };
},
start_timers: func {
settimer(do_stuff, 5); # BAD: there's no "do_stuff" function in the scope
settimer(me.do_stuff, 5); # BAD: function exists, but "me" won't be known
# when the timer function is actually executed
settimer(func me.do_stuff(), 5); # GOOD: new function object packs "me" in the closure

setlistener("/sim/foo", func me.do_stuff()); # GOOD (same as with timers)
},
do_stuff: func {
print("doing stuff");
},
};

var manager = Manager.new();
manager.start_timers();

'''Click ''[http://wiki.flightgear.org/Namespaces_and_Methods#Methods here]'' for more information.'''

== Exception handling ==

<tt>die()</tt> aborts a function with an error message (this can be compared to the throw() mechanism in C++).

var divide = func(a, b) {
if (b == 0)
die("division by zero");
return a / b; # this line won't be reached if b == 0
}

die() is also used internally by built-in extension functions or Nasal core functions. <tt>getprop("/4me")</tt>, for example, dies with an error message ''"name must begin with alpha or '_'"''. Now assume we want to write a dialog where the user can type a property path into an input field, and we display the property's value in a popup dialog. What if the user typed an invalid path and we hand that over to <tt>getprop()</tt>? We don't want Nasal to abort our code because of that. We want to display a nice error message instead. The <tt>call()</tt> function can catch <tt>die()</tt> exceptions:

var value = getprop(property); # dies if 'property' is invalid
var value = call(func getprop(property), nil, var err = []); # catches invalid-property-exception and continues

The second line calls getprop(property) just like the first, and returns its value. But if 'property' was invalid then the <tt>call()</tt> function catches the exception and sets the 'err' vector instead. That vector remains empty on success.

if (size(err))
print("ERROR: bad property ", property, " (", err[0], ")"); # err[0] contains the die() message
else
print("value of ", property, " is ", value);

The first argument of <tt>call()</tt> is a function object, the second a vector of function arguments (or ''nil''), and the third a vector where the function will return a possible error. For more information on the <tt>call()</tt> function see the [http://plausible.org/nasal/lib.html Nasal library documentation].

<tt>die()</tt> doesn't really care about what its argument is. It doesn't have to be a string, and can be any variable, for example a class. This can be used to pass values through a chain of functions.

var Error = { # exception class
new: func(msg, number) {
return { parents: [Error], message: msg, number: number };
},
};

var A = func(a) {
if (a < 0)
die(Error.new("negative argument to A", a)); # throw Error
return "A received " ~ a;
}

var B = func(val) {
var result = A(val);
print("B finished"); # this line is not reached if A threw an exception
return result;
}

var value = call(B, [-4], var err = []); # try B(-4)

if (size(err)) { # catch (...)
print("ERROR: ", err[0].message, "; bad value was ", err[0].number);
die(err[0]); # re-throw
} else {
print("SUCCESS: ", value);
}

== Listeners and Signals ==

Listeners are callback functions that are attached to property nodes. They are triggered whenever the node is written to, or, depending on the listener type, also when children are added or removed, and when children are written to. Unlike polling loops, listeners don't have the least effect on the frame rate when they aren't triggered, which makes them preferable to monitor properties that aren't written to frequently.

===setlistener() vs. _setlistener() ===
You are requested *not* to use the raw _setlistener() function, except in files in $FG_ROOT/Nasal/ when they are
needed immediately. Only then the raw function is required, as it doesn't rely on props.nas.

===<tt>When listeners don't work</tt>===
Unfortunately, '''listeners don't work on so-called "tied" properties''' when the node value isn't set via property methods. (You can spot such tied properties by Ctrl-clicking the "." entry in the property browser: they are marked with a "T".) Most of the FDM properties are "tied".

Examples of properties where setlistener ''won't'' work:

* /position/elevation-ft
* /ai/models/aircraft/orientation/heading-deg
* Any property node created as an alias
* Lots of others

Before working to create a listener, always check whether a listener will work with that property node by control-clicking the "." in property browser to put it into verbose mode, and then checking whether the property node for which you want to set up a listener is marked with a "T" or not.

If you can't set a listener for a particular property, the alternative is to use settimer to set up a timer loop that checks the property value regularly.

Listeners are most efficient for properties that change only occasionally. No code is called at all during frames where the listener function is not called. If the property value changes every frame, setting up a settimer loop with time=0 will execute every frame, just the same as setlistener would, and the settimer loop is more efficient than setting a listener. This is one reason the fact the setlistener doesn't work on certain tied and FDM properties is not a great loss. See the section on timer loops below.

=== <tt>setlistener()</tt> ===

Syntax:

var listener_id = setlistener(<property>, <function> [, <startup=0> [, <runtime=1>]]);

The first argument is a property node object (<tt>props.Node()</tt> hash) or a property path. Because the node hash depends on the props.nas module being loaded, <tt>setlistener()</tt> calls need to be deferred when used in an $FG_ROOT/Nasal/*.nas file, usually by calling them in a <tt>settimer(func {}, 0)</tt> construction. To avoid that, one can use the raw <tt>_setlistener()</tt> function directly, for which <tt>setlistener()</tt> is a wrapper. The raw function does only accept node paths (e.g. "/sim/menubar/visibility"), but not props.Node() objects.

The second argument is a function object (not a function call!). The <tt>func</tt> keyword turns code into a function object.

The third argument is optional. If it is non-null, then it causes the listener to be called initially. This is useful to let the callback function pick up the node value at startup.

The fourth argument is optional, and defaults to 1. This means that the callback function will be executed whenever the property is written to, independent of the value.

If the argument is set to 0, then the function will only get triggered if a value other than the current value is written to the node. This is important for cases where a property is written to once per frame, no matter if the value changed or not. YASim, for example, does that for /gear/gear/wow or /gear/launchbar/state.
So, this should be used for properties that are written to in every frame, although the written value is mostly the same. If the argument is 2, then also write access to children will get reported, as well as the creation and removal of children nodes.

For both optional flags 0 means less calls, and 1 means more calls. The first is for startup behavior, and the second for runtime behavior.

Here's a real-life example:

setlistener("/gear/launchbar/state", func {
if (cmdarg().getValue() == "Engaged")
setprop("/sim/messages/copilot", "Engaged!");
}, 1, 0);

YASim writes once per frame the string "Disengaged" to property /gear/launchbar/state. When an aircraft on deck of the aircraft carrier locks into the catapult, this changes to "Engaged", which is then written again in every frame, until the aircraft leaves the catapult. Because the locking in is a bit difficult -- one has to target the sensitive area quite exactly --, it was desirable to get some quick feedback: a screen message that's also spoken by the Festival speech synthesis. With the args 1 and 0, this is done initially (for the unlikely case that we are locked in from the beginning), and then only when the node changes from an arbitrary value to "Engaged".

<tt>setlistener()</tt> returns a unique listener id on success, and <tt>nil</tt> on error. The id is nothing else than a counter that is 0 for the first Nasal listener, 1 for the second etc. You need this id number to remove the listener. Most listeners are never removed, so that one doesn't assign the return value, but simply drop it.

Listener callback functions can access up to four values via regular function arguments, the first two of which are property nodes in the form of a <tt>props.Node()</tt> object hash.

If you have set a callback function named ''myCallbackFunc'' via <tt>setlistener</tt> (''setlistener(myNode, myCallbackFunc)''), you can use this syntax in the callback function:

myCallbackFunc ([<changed_node> [, <listened_to_node> [, <operation> [, <is_child_event>]]]])

=== <tt>removelistener()</tt> ===

Syntax:

var num_listeners = removelistener(<listener id>);

<tt>removelistener()</tt> takes one argument: the unique listener id that a <tt>setlistener()</tt> call returned. It returns the number of remaining active Nasal listeners on success, <tt>nil</tt> on error, or -1 if a listener function applies <tt>removelistener()</tt> to itself. The fact that a listener can remove itself, can be used to implement a one-shot listener function:

var L = setlistener("/some/property", func {
print("I can only be triggered once.");
removelistener(L);
});

=== Listener Examples ===

The following example attaches an anonymous callback function to a "signal". The function will be executed when FlightGear is closed.

setlistener("/sim/signals/exit", func { print("bye!") });

Instead of an anonymous function, a named function can be used as well:

var say_bye = func { print("bye") }
setlistener("/sim/signals/exit", say_bye);

Callback functions can, optionally, access up to four parameters which are handed over via regular function arguments. Many times none of these parameters is used at all, as in the above example.

Most often, only the first parameter is used--which gives the node of the changed value.

The following code attaches the monitor_course() function to a gps property, using the argument ''course'' to get the node with the changed value.

var monitor_course = func(course) {
print("Monitored course set to ", course.getValue());
}
var i = setlistener("instrumentation/gps/wp/leg-course-deviation-deg", monitor_course);

# here the listener is active

removelistener(i); # remove that listener again

Here is code that accesses two arguments--the changed node and the listened-to node (these may be different when monitoring all children of a certain node)--and also shows how to monitor changes to a node including changes to children:

var monitor_course = func(course, flightinfo) {
print("One way to get the course setting: ", flightinfo.leg-course-deviation-deg.getValue());
print("Another way to get the same setting ", course.getValue());
}
var i = setlistener("instrumentation/gps/wp", monitor_course, 0, 2);

The function object doesn't need to be a separate, external function -- it can also be an anonymous function made directly in the <tt>setlistener()</tt> call:

setlistener("/sim/signals/exit", func { print("bye") }); # say "bye" on exit

Beware, however, that the contents of a function defined within the <tt>setlistener</tt> call are not evaluated until the call is actually made. If, for instance, local variables change before the setlistener call happens, the call will reflect the current value of those variables ''at the time the callback function is called'', not the value ''at the time the listener was set''.

For example, with this loop, the function will always return the value 10--even if mynode[1], mynode[2], mynode[3] or any of the others is the one that changed. It is because the contents of the setlistener are evaluated after the loop has completed running and at that point, i=10:

var output = func(number) {
print("mynode", number, " has changed!"); #This won't work!
}
for(i=1; i <= 10; i = i+1) {
var i = setlistener("mynode["~i~"]", func{ output (i); });
}

You can also access the four available function properties (or just one, two, or three of them as you need) in your anonymous function. Here is an example that accesses the first value:

for(i=1; i <= 10; i = i+1) {
var i = setlistener("mynode["~i~"]", func (changedNode) { print (changedNode.getPath() ~ " : " ~ changedNode.getValue()); });
}

Attaching a function to a node that is specified as <tt>props.Node()</tt> hash:

var node = props.globals.getNode("/sim/signals/click", 1);
setlistener(node, func { gui.popupTip("don't click here!") });

Sometimes it is desirable to call the listener function initially, so that it can pick up the node value. In the following example a listener watches the view number, and turns the HUD on in cockpit view, and off in all other views. It doesn't only do that on writing to "view-number", but also once when the listener gets attached, thanks to the third argument "1":

setlistener("/sim/current-view/view-number", func(n) {
setprop("/sim/hud/visibility[0]", n.getValue() == 0);
}, 1);

There's no limit for listeners on a node. Several functions can get attached to one node, just as one function can get attached to several nodes. Listeners may write to the node they are listening to. This will not make the listener call itself causing an endless recursion.

=== Signals ===

In addition to "normal" nodes, there are "signal" nodes that were created solely for the purpose of having listeners attached:

<tt>/sim/signals/exit</tt> ... set to "true" on quitting FlightGear

<tt>/sim/signals/reinit</tt> ... set to "true" right before resetting FlightGear (Shift-Esc), and to "false" afterwards

<tt>/sim/signals/click</tt> ... set to "true" after a mouse click at the terrain. Hint that the geo coords for the click spot were updated and can be retrieved from /sim/input/click/{longitude-deg,latitude-deg,elevation-ft,elevation-m}

<tt>/sim/signals/screenshot</tt> ... set to "true" right before the screenshot is taken, and set to "false" after it. Can be used to hide and reveal dialogs etc.

<tt>/sim/signals/nasal-dir-initialized</tt> ... set to "true" after all Nasal "library" files in $FG_ROOT/Nasal/ were loaded and executed. It is only set once and can only be used to trigger listener functions that were defined in one of the Nasal files in that directory. After that signal was set
Nasal starts loading and executing aircraft Nasal files, and only later are <tt>settimer()</tt> functions
called and the next signal is set:

<tt>/sim/signals/fdm-initialized</tt> ... set to "true" when then FDM has just finished its initialization

<tt>/sim/signals/reinit-gui</tt> ... set to "true" when the GUI has just been reset (e.g. via Help menu). This
is used by the gui.Dialog class to reload Nasal-loaded XML dialogs.

<tt>/sim/signals/frame</tt> ... triggered at the beginning of each iteration of the main loop (a.k.a. "frame"). This is meant for debugging purposes. Normally, one would just use a settimer() with interval 0 for the same effect. The difference is that the signal is guaranteed to be raised at a defined moment, while the timer call may change when subsystems are re-ordered.

== FlightGear extension functions ==

=== <tt>cmdarg()</tt> ===
cmdarg() is a mechanism to pass arguments to a nasal script (wrapped in properties) instead of "normal" function parameters. Note that cmdarg() should be primarily used in Nasal code embedded in XML files and should be considered depreciated otherwise (see [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg18361.html] and [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg18361.html]).

cmdarg() will keep working in (joystick) XML-'''bindings''' and on the top-level of embedded Nasal scripts (i.e. dialog and animation XML files).

As such, the cmdarg() function is primarily used for listener callbacks declared in XML markup, cmdarg() returns the listened-to property as props.Node object, so you can use it with all its methods (see $FG_ROOT/Nasal/props.nas) for example:

print(cmdarg().getPath(), " has been changed to ", cmdarg().getValue())

The cmdarg() function avoids that you have to type the exact same path twice (once here and once in the setlistener() command) and it makes clear that this is the listened to property. Also, you can use all the nice props.Node methods on cmdarg() directly:

setlistener("/gear/launchbar/state", func {
if (cmdarg().getValue() == "Engaged")
setprop("/sim/messages/copilot", "Engaged!");
}, 1, 0);

Use of cmdarg() outside of XML-bindings won't cause an error, but (still) return the last cmdarg() property. This just won't be the listened-to property anymore, but whatever the last legitimate cmdarg() user set. Most of the time it will be the property root of a joystick binding.

Don't make any assumptions and use cmdarg() only in one of these cases:

* binding: returns root of this binding's property branch. Needed for accessing an axis' value: cmdarg().getNode("setting").getValue()

* dialog xml files: returns root of that file's property branch in memory. This can be used to let embedded Nasal change the dialog (e.g. clear and build lists) before the final layout is decided

* animation xml files: returns root of this model's place in /ai/models/ when used as AI/MP model. Examples: /ai/models/multiplayer[3], /ai/models/tanker[1], etc. [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg14164.html]

* AI aircraft XML files

* remotely invoking Nasal code by setting properties using the built-in telnet daemon (RPC) [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg00150.html [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg00336.html].

'''In all cases, the cmdarg() call must not be delayed until later using settimer() or setlistener(). Because later it'll again return some unrelated property!
'''

=== <tt>fgcommand()</tt> ===

Runs an internal "fgcommand", see $FG_ROOT/Docs/README.commands for a list of available commands: http://gitorious.org/fg/fgdata/blobs/master/Docs/README.commands

=== <tt>print()</tt> ===
Concatenates an arbitrary number of arguments to one string, appends a new-line, and prints it to the terminal. Returns the number of printed characters.

print("Just", " a ", "test");

=== <tt>getprop()</tt> ===
Returns the node value for a given path, or <tt>nil</tt> if the node doesn't exist or hasn't been initialized yet.

getprop(<path>);

Example:

print("The frame rate is ", getprop("/sim/frame-rate"), " FPS");

=== <tt>setprop()</tt> ===
Sets a property value for a given node path string. Always returns nil.

setprop(<path> [, <path>, [...]], <value>);

All arguments but the last are concatenated to a path string, with a slash (/) inserted between each element. The last value is written to the respective node. If the node isn't writable, then an error message is printed to the console.

Note: <tt>setprop()</tt> concatenates a list of input arguments by means of inserting a "/" in between. That is nice for properties, as this slash is part of the tree. However, when one wants to make use of indices, like [0], one has to concatenate by hand (using "~") ''inside'' one part of the string argument list. An example is:

var i = 4;
setprop("instrumentation","cdu","page["~i~"]","title","MENU");

This results in instrumentation/cdu/page[4]/title = 'MENU' (string)

Examples:

setprop("/sim/current-view/view-number", 2);
setprop("/controls", "engines/engine[0]", "reverser", 1);

'''Erasing a property from the property tree''': a property that has been created, for example through <tt>setprop()</tt> can be erased via

props.globals.getNode("foo/bar").remove(); # take out the complete node
props.globals.getNode("/foo").removeChild("bar"); # take out a certain child node

=== <tt>settimer()</tt> ===
Runs a function after a given simulation time (default) or real time in seconds.

settimer(<function>, <time> [, <realtime=0>]);

The first object is a function object (ie, "func { ... }"). Note that this is different from a function call (ie, "func ( ... )"). If you don't understand what this means, just remember to always enclose the first argument in any call to settimer with the word "func" and braces "{ }", and it will always work. For instance, if you want print the words "My result" in five seconds, use this code:

settimer ( func { print ( "My result"); }, 5);

Inside the braces of the func object you can put any valid Nasal code, including a function call. In fact, if you want to call a function with certain values as arguments, the way to do it is to turn it into a function object by enclosing it with a func{}, for example:

myarg1="My favorite string";
myarg2=432;
settimer ( func { myfunction ( myarg1, myarg2); }, 25);

The third argument is optional and defaults to 0, which lets the time argument be interpreted as "seconds simulation time". In this case the timer doesn't run when FlightGear is paused. For user interaction purposes (measuring key press time, displaying popups, etc.) one usually prefers real time.

# simulation time example
var copilot_annoyed = func { setprop("/sim/messages/copilot", "Stop it! Immediately!") }
settimer(copilot_annoyed, 10);

# real time example
var popdown = func ( tipArg ) {
fgcommand("dialog-close", tipArg);
}

var selfStatusPopupTip = func (label, delay = 10, override = nil) {
var tmpl = props.Node.new({
name : "PopTipSelf", modal : 0, layout : "hbox",
y: 140,
text : { label : label, padding : 6 }
});
if (override != nil) tmpl.setValues(override);

popdown(tipArgSelf);
fgcommand("dialog-new", tmpl);
fgcommand("dialog-show", tipArgSelf);

currTimerSelf += 1;
var thisTimerSelf = currTimerSelf;

# Final argument 1 is a flag to use "real" time, not simulated time
settimer(func { if(currTimerSelf == thisTimerSelf) { popdown(tipArgSelf) } }, delay, 1);
}

[[Nasal_scripting_language#settimer_loops|More information about best practices for using the settimer function to create loops in Nasal is elsewhere on this page.]]

=== <tt>systime()</tt> ===
Returns epoch time (time since 1972/01/01 00:00) in seconds as a floating point number with high resolution. This is useful for benchmarking purposes.

#benchmarking example:
var start = systime();
how_fast_am_I(123);
var end = systime();
print("took ", end - start, " seconds");

=== <tt>carttogeod()</tt> ===
Converts cartesian coordinates x/y/z to geodetic coordinates lat/lon/alt, which are returned as a vector. Units are degree and meter.

var geod = carttogeod(-2737504, -4264101, 3862172);
print("lat=", geod[0], " lon=", geod[1], " alt=", geod[2]);

# outputs
lat=37.49999782141546 lon=-122.6999914632327 alt=998.6042055172776

=== <tt>geodtocart()</tt> ===
Converts geodetic coordinates lat/lon/alt to cartesian coordinates x/y/z. Units are degree and meter.

var cart = geodtocart(37.5, -122.7, 1000); # lat/lon/alt(m)
print("x=", cart[0], " y=", cart[1], " z=", cart[2]);

# outputs
x=-2737504.667684828 y=-4264101.900993474 z=3862172.834656495

=== <tt>geodinfo()</tt> ===
Returns information about geodetic coordinates. Takes two arguments: lat, lon (in degree) and returns a vector with two entries, or nil if no information could be obtained because the terrain tile wasn't loaded. The first entry is the elevation (in meters) for the given point, and the second is a hash with information about the assigned material, or nil if there was no material information available, because there is, for instance, an untextured building at that spot or the scenery tile is not loaded.

var lat = getprop("/position/latitude-deg");
var lon = getprop("/position/longitude-deg");
var info = geodinfo(lat, lon);

if (info != nil) {
print("the terrain under the aircraft is at elevation ", info[0], " m");
if (info[1] != nil)
print("and it is ", info[1].solid ? "solid ground" : "covered by water");
}

A full data set looks like this:

debug.dump(geodinfo(lat, lon));

# outputs
[ 106.9892101062052, { light_coverage : 0, bumpiness : 0.5999999999999999, load_resistance : 1e+30,
solid : 0, names : [ "Lake", "Pond", "Reservoir", "Stream", "Canal" ], friction_factor : 1,
rolling_friction : 1.5 } ]

Note that geodinfo is a *very* CPU intensive operation, particularly in FG 2.4.0 and earlier, so use sparingly ([http://flightgear.org/forums/viewtopic.php?f=4&p=135044#p135044 discussion here]).

=== <tt>parsexml()</tt> ===

This function is an interface to the built-in [http://expat.sourceforge.net/ Expat XML parser]. It takes up to five arguments. The first is a mandatory absolute path to an XML file, the remaining four are optional callback functions, each of which can be nil (which is also the default value).

var ret = parsexml(<path> [, <start-elem> [, <end-elem> [, <data> [, <pi> ]]]]);

<start-elem> ... called for every starting tag with two arguments: the tag name, and an attribute hash
<end-elem> ... called for every ending tag with one argument: the tag name
<data> ... called for every piece of data with one argument: the data string
<pi> ... called for every "processing information" with two args: target and data string

<ret> ... the return value is nil on error, and the <path> otherwise

Example:

var start = func(name, attr) {
print("starting tag ", name);
foreach (var a; keys(attr))
print("\twith attribute ", a, "=", attr[a]);
}
var end = func(name) { print("ending tag ", name) }
var data = func(data) { print("data=", data) }
var pi = func(target, data) { print("processing instruction: target=", target, " data=", data) }
parsexml("/tmp/foo.xml", start, end, data, pi);

=== airportinfo() ===
Function for retrieval of airport/runway information.
Usage:

var apt = airportinfo("KHAF"); # get info about KHAF
var apt = airportinfo(lat, lon); # get info about apt closest to lat/lon
var apt = airportinfo(); # get info about apt closest to aircraft

The command debug.dump(airportinfo("KHAF")) outputs this:

{ lon : -122.4962626410256, lat : 37.51343502564102, has_metar : 0,
runways : { 12 : { stopway2 : 0, threshold1 : 232.5624,
lon : -122.5010889999999, lat : 37.513831, stopway1 : 0, width : 45.72,
threshold2 : 232.5624, heading : 138.1199999999999, length : 1523.0856 } },
elevation : 20.42159999999999, id : "KHAF", name : "Half Moon Bay" }

That is: a hash with elements lat/lon/elev/id/name/has_metar for the
airport, and a hash with runways, each of which consists of lat/lon/
/length/width/heading/threshold[12]/stopway[12]. Only one side of each
runway is listed -- the other can easily be deduced.

==Built-in functions==

===sort(vector, function)===
Creates a new vector containing the elements in the input vector sorted in ascending order according to the rule given by function, which takes two arguments (elements of the input vector) and should return less than zero, zero, or greater than zero if the first argument is, respectively, less than, equal to, or greater than the second argument. Despite being implemented with ANSI C qsort(), the sort is stable; "equal" elements in the output vector will appear in the same relative order as they do in the input.

Because you can define the sort function, sort allows you to create a list of keys sorting a hash by any criterion--by key, value, or (if, for instance the hash values are hashes themselves) any subvalue.

vec = [100,24,45];
sortvec = sort (vec, func (a,b) cmp (a,b));
debug.dump (sortvec); #output is [24,45,100]

Here is an example of how to output the contents of a hash in sorted order. Note that the function does not actually sort the hash but returns a list of the hash keys in sorted order.

var airport = {
"LOXZ": "Zeltweg",
"LOWI": "Innsbruck",
"LOXL": "Linz Hoersching", # the last comma is optional
};

var sortedkeys= sort (keys(airport), func (a,b) cmp (airport[a], airport[b]));

foreach (var i; sortedkeys)
print (i, ": ", airport[i]);

The output is:

LOWI: Innsbruck
LOXL: Linz Hoersching
LOXZ: Zeltweg

If the hash values are themselves hashes, sorting by any of the subvalues is possible. For example:

var airport = {
"LOXZ": {city: "Zeltweg", altitude_m: 1300 },
"LOWI": {city: "Innsbruck", altitude_m: 2312 },
"LOXL": {city: "Linz Hoersching", altitude_m: 1932 },
};

#return a list of the hash keys sorted by altitude_m
var sortedkeys= sort (keys(airport), func (a,b) airport[a].altitude_m - airport[b].altitude_m);

foreach (var i; sortedkeys)
print (i, ": ", airport[i].city, ", ", airport[i].altitude_m);

Note that ''sort'' will return errors, and in FG 2.4.0 may even stop working, if the sort function you provide returns errors. A common cause of this is if your sort vector contains both string and numeric values. The cmp function will return an error for numeric values, and arithmetic operations you may use to sort numeric values will return errors if performed on a string. The error in these cases is typically "function/method call on uncallable object".

=== Other useful built-in functions ===

Other basic built-in Nasal functions such as append, setsize, subvec, typeof, contains, delete, int, num, keys, pop, size, streq, cmp, substr, sprintf, find, split, rand, call, die, bind, math.sin, math.pi, math.exp, math.ln math.e, io.read, io.write, regex.exec, and others of that sort, [http://www.plausible.org/nasal/lib.html are detailed in this external document].

=== Useful functions in the Nasal directory ===
Other functions are available in the Nasal files found in the Nasal directory of a FlightGear install. Simply open those Nasal files in text editor to see what is inside. Reference those functions by putting the filename in front of the function, method, variable, or object you wish to use. For instance, to use the method Coord.new() in the file geo.nas, you simply write:

geo.Coord.new()

=== Distance calculations ===

To calculate the distance between two points (in two different ways):
# mylat1, mylong1, mylat2, mylong2 are lat & long in degrees
# myalt1 & myalt2 are altitude in meters

var GeoCoord1 = geo.Coord.new();
GeoCoord1.set_latlon(mylat1, mylong1,myalt1);

var GeoCoord2 = geo.Coord.new();
GeoCoord2.set_latlon(mylat2, mylong2, myalt2);

var directDistance = GeoCoord1.direct_distance_to(GeoCoord2);
var surfaceDistance = GeoCoord1.distance_to(GeoCoord2);

The results are distances in meters.

* distance_to - returns distance in meters along Earth curvature, ignoring altitudes; useful for map distance
* direct_distance_to - returns distance in meters direct; considers altitude, but cuts through Earth surface

=== Other useful geographical functions ===
Other useful geographical functions are found in geo.nas (in the FlightGear/data/Nasal directory of a FlightGear installation). geo.nas also includes documentation/explanation of the functions available.

==Developing and debugging in Nasal==
===Developing Nasal code===
Because code in the Nasal directory is parsed only at Flightgear startup, testing and debugging Nasal code can by slow and difficult.

Flightgear provides a couple of ways to work around this issue:

====Nasal Console====

The Nasal Console is available in Flightgear's menu (Debug/Nasal Console). Selecting this menu opens a Nasal Console dialog.

This dialog has several tabs, of which each can hold separate Nasal code snippets, all of which are saved on exit
and reloaded next time. This is useful for little tests, or for executing code for which writing a key binding is just too much
work, such as "props.dump(props.globals)".

If you want to add more tabs (radio buttons in the Nasal Console dialog) to hold more code samples, just add more <code> nodes to autosave.xml.

====Loading/reloading Nasal code without re-starting Flightgear====
A common problem in testing and debugging Nasal programs is that each testing step requires stopping and re-starting Flightgear, a slow process.

Below is described a technique for loading and executing a Nasal file while Flightgear is running. Flightgear will parse the file, display any errors in the Flightgear console window, and then execute the code as usual.

Using this technique, you can start Flightgear, load the Nasal code you want to test observe any errors or test functionality as you wish, make changes to the Nasal file, reload it to observe parse errors or change in functionality, and so on to repeatedly and quickly run through the change/load/parse/test cycle without needing to re-start Flightgear each time.

The key to this technique is the function io.load_nasal(), which loads a nasal file into a nasal namespace.

Step-by-step instructions showing how to use this technique to load, parse, and test a Nasal file while Flightgear is running:

=====Create the Nasal file to test=====
Create a text file named $FG_ROOT/foo/test.nas with this text:

print("hi!");
var msg="My message.";
var hello = func { print("I'm the test.hello() function") }

Notes: You can create the file in any directory you wish, as long as Nasal can read the directory--but the file IOrules in the Nasal directory restricts which directories Nasal may read and write from.

You can give the file any name and extension you wish, though it is generally most convenient to use the .nas extension with Nasal files.

=====Load the file and test=====
Start Flightgear. You can import the file above into Flightgear by typing the following into the Nasal Console dialog and executing the code:

io.load_nasal(getprop("/sim/fg-root") ~ "/foo/test.nas", "example");

getprop("/sim/fg-root") gets the root directory of the FlightGear installation, ~ "/foo/test.nas" appends the directory and filename you created. The final variable "example" tells the namespace to load for the Nasal file.

You'll see the message "hi!" on the terminal, and have function "example.hello()" immediately available. You can, for instance, type "example.hello();" into one of the Nasal console windows and press "Execute" to see the results; similarly you could execute "print (example.msg);".

If you find errors or want to make changes, simply make them in your text editor, save the file, and execute the io.load_nasal() command again in the Nasal Console to re-load the file with changes.

It's worth noting that Nasal code embedded in XML GUI dialog files can be reloaded by using the "debug" menu ("reload GUI").

You may also want to check out the remarks on [[Nasal_scripting_language#Memory_management|Memory management]].

==== Managing timers and listeners ====

Note: If your Nasal program sets listeners, timer loops, and so on, they will remain set even when the code is reloaded, and reloading the code will set additional listeners and timer loops.

This can lead to extremely slow framerates and unexpected behavior. For timers you can avoid this problem by using the loopid method (described above); for listeners you can create a function to destroy all timers your Nasal program creates, and call that function before reloading the program. (And cleaning up timer loops and listeners is a best practice for creating Nasal programs in Flightgear regardless.)

The same problem may occur while resetting or re-initializing parts of FlightGear if your code isn't prepared for this. And obviously this applies in particular also to any worker threads you may have started, too!

For complex Nasal scripts with many timers and listeners, it is therefore generally a very good idea to implement special callbacks so that your scripts can respond to the most important simulator "signals", this can be achieved by registering script-specific listeners to signals like "reinit" or "freeze" (pause): the corresponding callbacks can then suspend or re-initialize the Nasal code by suspending listeners and timers. Following this practice helps ensure that your code will behave properly even during simulator resets.

In other words, it makes sense to provide a separate high-level controller routine to look for important simulator events and then pause or re-initialize your main Nasal code as required.

If you are using [[Nasal_scripting_language#System-wide_Nasal_code|System-wide Nasal modules]], you should register listeners to properly re-initialize and clean up your Nasal code.

In its simplest form, this could look like this:

var cleanup = func {}
setlistener("/sim/signals/reinit", cleanup);

This will invoke your "cleanup" function, whenever the "reinit" signal is set by the FlighGear core.

Obviously, you now need to populare your cleanup function with some code, too.

One of the easiest ways to do this, is removing all listeners/timers manually here, i.e. by adding calls to removelistener():

var cleanup = func {
removelistener(id);
removelistener(id);
removelistener(id);
}

This would ensure that the corresponding listeners would be removed once the signal is triggered.

On the other hand, you could just as well use a vector of listener IDs here, and then use a Nasal foreach loop:

var cleanup = func(id_list) {
foreach(var id; id_list)
removelistener(id);
}

Obviously, this would require that you maintain a list of active listeners, too - so that you can actually pass a list of IDs to the cleanup function.

This is one of those things that can be easily done in Nasal, too - just by introducing a little helper wrapper:

var id_list=[];
var store_listener = func(id) append(id_list,id);

The only thing required here, would be replacing/wrapping the conventional "setlistener" call with calls to your helper:

store_listener( setlistener("/sim/foo") );
store_listener( setlistener("/foo/bar") );

If you were to do this consistently across all your Nasal code, you'd end up with a high level way to manage all your registered listeners centrally.

Now, you'll probably have noticed that it would make sense to consider wrapping all these helpers and variables inside an enclosing helper class, this can be accomplished in Nasal using a hash. This would enable you to to implement everything neatly organized in an object and use RAII-like patterns to manage Nasal resources like timers, listeners and even threads.

===Debugging===
The file debug.nas, included in the Nasal directory of the Flightgear distribution, has several functions useful for debugging Nasal code. These functions are available to any Nasal program or code executed by Flightgear.

Aside from those listed below, several other useful debugging functions are found in debug.nas; see the debug.nas file for the list of functions and explanation.

Note that the debug module makes extensive use of ANSI terminal color codes. These create colored output on Linux/Unix systems but on other systems they may add numerous visible control codes. To turn off the color codes, go to the internal property tree and set

/sim/startup/terminal-ansi-colors=0

Or within a Nasal program:

setprop ("/sim/startup/terminal-ansi-colors",0);

====debug.dump====
debug.dump([<variable>]) ... dumps full contents of variable or of local variables if none given

The function debug.dump() dumps the contents of the given variable to the console. On Unix/Linux this is done with some syntax coloring. For example, these lines

var as = props.globals.getNode("/velocities/airspeed-kt", 1);
debug.dump(as);

would output

</velocities/airspeed-kt=1.021376474393101 (DOUBLE; T)>

The "T" means that it's a "tied" property. The same letters are used here as in the property-browser. The angle brackets seem superfluous, but are useful because debug.dump() also outputs compound data types, such as vectors and hashes. For example:

var as = props.globals.getNode("/velocities/airspeed-kt", 1);
var ac = props.globals.getNode("/sim/aircraft", 1);
var nodes = [as, ac];
var hash = { airspeed_node: as, aircraft_name: ac, all_nodes: nodes };
debug.dump(hash);

yields:

{ all_nodes : [ </velocities/airspeed-kt=1.021376474393101 (DOUBLE; T)>,
</sim/aircraft="bo105" (STRING)> ], airspeed_node : </velocities/airspe
ed-kt=1.021376474393101 (DOUBLE; T)>, aircraft_name : </sim/aircraft="bo
105" (STRING)> }

====debug.backtrace====
debug.backtrace([<comment:string>]} ... writes backtrace with local variables
debug.bt ... abbreviation for debug.backtrace

The function debug.backtrace() outputs all local variables of the current function and all parent functions.

====debug.benchmark====
debug.benchmark(<label:string>, <func> [, <repeat:int>])
... runs function <repeat> times (default: 1) and prints execution time in seconds,prefixed with <label>.

This is extremely useful for benchmarking pieces of code to determin
====debug.exit====
debug.exit() ... exits fgfs

== Related content ==
{{Forum|30|Nasal}}
* [[:Category:Nasal]]

=== External links ===
* http://www.plausible.org/nasal

[[Category:Nasal]]

Nasal scripting language

2011-12-25T05:37:53Z

Moksha: /* Nasal = Not another scripting language! */ sentence correction

''Please note that a considerable amount of resources has not yet been incorporated here, you can check these out by going to the "[[Talk:Nasal_scripting_language|discussion]]" page, where we are collecting links to webpages and mailing list discussions/postings related to Nasal.''

==Nasal = Not another scripting language!==

The short summary is that Nasal is a scripting language that is tightly integrated with FlightGear itself,
and provides a very easy way to manipulate the property tree, which is the core data structure within the
simulator that exposes all the important internal runtime states of FlightGear.

[[FlightGear]] offers a very powerful functional scripting language called [http://plausible.org/nasal/ "Nasal"], which supports reading and writing of internal [[Property Tree Intro|FlightGear properties]], accessing internal data via extension functions, creating GUI dialogs and much more.

Nasal uses some of the concepts of ECMA/JavaScript, Python and Perl and implements a simple but complete way of Object Oriented Programming (OOP), Nasal uses an internal garbage collector so that no manual memory management is required by the programmer.

People familiar with other programming languages, and scripting languages like JavaScript in particular, are usually able to learn Nasal rather quickly. FlightGear provides a rich library of simulation-specific and general-purpose functions that can be accessed by Nasal scripts.

Nasal code can be run by aircraft configuration files, and it can be embedded in various [[XML]] files (dialog files, animation files, bindings for joysticks, keyboard and cockpit controls, and even in [[Howto: Nasal in scenery object XML files|scenery objects]]). Nasal is platform independent and designed to be thread safe.

=== Some success stories ===
These were taken from the developers mailing list:

* "Nasal is *very* well designed, compact, and efficient. It is used heavily throughout many areas of FlightGear."
* "It's interesting though how much nasal you can actually get away with using without making a blip on frame rates. Nasal is *very* efficient and powerful for being an interpreted script language."
* "FlightGear needed a built-in scripting language, and it has one. A compact, clean, elegant and fast one, Nasal extension functions interface perfectly to the property tree, the event manager, the built-in XML parser etc. Nasal is very tightly integrated in fgfs and used all over the place."
* "There's no question that scripting languages are good; fgfs has a lot of Nasal code now. In my profiling I have never seen the nasal interpreter as a hot spot"
* "I'm a simple content contributor with very little background in programming. When I made my first Aircraft (the bf109) I was confronted with the need to deploy slats automatically at a given speed. I din't want to embed C++ code or had such a complex script that the error messages in FG wouldn't help me and I previously only used a bit of python. I looked at some Nasal scripts and within a few hours it worked. I was impressed how easy it is to write even complex Nasal scripts. Later I started developing the walker feature that made it possible to walk around in the scenery, all with nasal. Stuart kindly enhanced the walker and added an animation system to it (see bluebird), again with nasal. Others have made Flight computers with it (see V-22 and Su-37). Nasal is a worthy tool"
* "I used Nasal to build several rather complex systems, like Fuel System, Stab Augmentation System, Autopilot Logic, Terrain Avoidance Radar, Radar Warning Receiver and much more, and yes, I love Nasal too. Learning Nasal use was easy and fun and I din't found any limitation yet."
* There are many vital parts of FlightGear currently coded in nasal. There are also random bits of nasal code scattered around in joystick configurations, instrument and aircraft models, scenery models... everywhere.
* "We have an entire directory full of Nasal 'function' libraries now, and I'm quite happy using them instead of rolling my own duplicate functionality."
* Nearly every sophisticated Aircraft uses some kind of Nasal, be it Effects like tyre smoke or important functionalities like Engine and electric management, The Bluebird FDM is completely written in Nasal, vital parts of the V-22 Osprey rely on it, Flyby and Model View wouldn't work anymore, no more interactive objects in the scenery, lots of the MP System would be gone, ... Nasal is THE tool which makes FG development fun and adds nearly unlimited possibilities. If you need an example, look at the Bluebird animated walker, all done in Nasal."
* "there are good reasons to use Nasal - first of all the user base which regularly compiles their own code is small, whereas people do install addon packages - so I get a lot more feedback and test results. Second that one usually can't really crash the whole system from Nasal. Third, it's very easy to quickly try something and very maintenance-friendly. Fourth, you can actually start developing something without knowing how the core code ties together - which I suppose takes a lot of time to learn. And so on."
* "Hard-coding every instrument in C++ instead of nasal means only developers following/building the latest cvs head code get to use whatever until the next release cycle."
* "Hard coding every instrument/flight control in C++ means my WW-II storch (et.al.) is stuck with an autobrake functionality it doesn't have nor need."
* "I think it boils down to the fact that we have two approaches that can accomplish the same thing. The C/C++ approach offers high performance but there is a dependence on when the C/C++ code was added to FlightGear. The Nasal approach offers fast prototyping, flexibility, and more (but not complete) independence from the C/C++ code."
* "A basic problem with C++ functions is it is hard/impossible to override them for a special purpose. Writing in pure nasal allows function name hijacking and other tricks that can't be used on C++ code."
* "Given the fact that FG is platform independent, I don't know if the embedded C++ is doing the same on Windows, Linux, PPC and intel Macs. Apart from the fact that if I was able to code c++ I would embed it to FG rather than in an Aircraft specific script"
* "If we ported Nasal code over to C++ we'd lose the ability to change small things "on the fly" without compiling over and over again. We'd also lose good programmers, who prefer scripting over C++. Aircraft creation would not be customizable etc etc."
* "The argument against Nasal is essentially that C++ is faster than Nasal - which, everything else being equal, is certainly correct. But highly specialized Nasal code written for a particular problem outperforms general purpose C++ code - I've given several examples in the past. If someone were e.g. to add movement to Nasal spawned models by adding a velocity property, I'm not sure it would outperform my Nasal quadtree-sorted adaptive range code which priorizes movement for things actually inside the field of view. Of course, if you'd hard-code that specialized algorithm, it would be faster than the Nasal version - but then you couldn't apply it to other problems any more."
* "How many airplane developer will you loose if you remove the Nasal engine from FGFS because they can write Nasal code but not C++ code?"
* "The algorithm being equal, I don't think there's a question that C++ is faster (I doubt the factor 10 though - that seems to be an extreme case). Everything else being equal, I also don't think there's a question that Nasal code is more accessible. And I would base any decision what to hard-code and what not on that balance."
* "Nasal is just much better suited for FlightGear than many alternatives because of it's size, processing speed and because a number of FlightGear core developers have a good idea what's going on."
* "In theory we could even use VBScript but Nasal has proven to be valuable for almost 10 years, so no reason to change or add another scripting language. Besides, if you know JavaScript then learning Nasal would take little effort."
* "The pool of people with commit rights to the core C++ code is very, very small."

Nasal really is an excellent choice for prototyping and implementing new features and even completely new systems in FlightGear.

For example, the [[bombable]] script implements "dog fighting" support on top of FlightGear, without ANY changes to the C++ side of the code, just by using some fairly advanced scripted code (implemented in the built-in Nasal programming language). You can basically imagine it like a "MOD" of FlightGear. In other words, the bombable script creates a completely new "mode" in FlightGear.

No matter if it's scenery, aircraft, AI scenarios or whatever: many things that were originally never planned to be supported by FlightGear core developers, are now implicitly supported because of the lose coupling between highly configurable and flexible systems, such as the property tree and the Nasal scripting language.

So we are really standing on the shoulders of giants here, because we are now -after 10+ years- in the position to create significant new features (and even completely new systems in FlightGear) within the constraints of the FlightGear base package, without even touching the C++ source code at all - simply because FlightGear has become so flexible and extensible.

All of this became possible by some important architectural decisions, such as for example the use of XML and plain text files for pretty much all configuration files in FlightGear (and thus open file formats in general), a publicly accessible tree of state variables that can be easily inspected and modified at runtime (the property tree). Similarly, the decision to embed a scripting language that can be used for scripting the entire simulator was another important decision.

In FlightGear, Nasal is the most accessible method of customizing the whole simulator to a very high degree. Nasal code can be easily edited using a conventional text editor, there are no special tools required: Nasal source code is interpreted, compiled to bytecode and run by the Nasal "virtual machine" using FlightGear itself.

The emerging [[A local weather system|Local weather]] system was entirely prototyped in Nasal space, and is now being increasingly augmented by moving performance-critical functions to C++ space instead.

Using Nasal, it is even possible to create entirely scripted flights and smart "AI bots":

I have something here that I think is kind of fun. I've been fiddling with
this off and on since last fall and decided it was time to clean it up a bit
and quit hording all the fun for myself. Basically I have taken the F-14b
and created a high performance Navy "drone" out of it. It can auto-launch
from a carrier, auto fly a route (if you've input one) and can do circle
holds (compensating for wind.) I've added a simulated
gyro stabilized camera that will point at anything you click on and then
hold that view steady no matter what the airplane does (similar to what real
uav's can do.) Finally, you can command it to return home and it will find
the carrier, setup a reasonable approach and nail the landing perfectly
every time (factoring in wind, carrier speed, etc.): http://www.flightgear.org/uas-demo/

As of 03/2009, there were approximately 170.000 lines of reported Nasal source code in the FlightGear base package [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg21333.html], compared to 2006 this is almost a rate of growth of 600% within 3 years [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg01728.html]. This illustrates the sheer adoption rate Nasal is experiencing in FlightGear.

(As of 10/2011, the FlightGear base package contained 326.000 lines of Nasal source code in *.nas files)

Note that this page is mostly about FlightGear-specific APIs/extension functions and usage patterns.
Thus, you may also want to have a look here:

* [http://plausible.org/nasal/lib.html core language/library documentation]
* [http://plausible.org/nasal/sample.nas annotated source code examples]
* [http://plausible.org/nasal/doc.html Nasal design document]
* [http://www.plausible.org/nasal/flightgear.html a helpful tutorial about using Nasal in FlightGear].

In addition, the [http://gitorious.org/fg/fgdata/trees/master/Nasal Nasal directory] in the FlightGear base package contains a wealth of tested, proven and usually well-commented source code that you may want to check out for additional examples of using the Nasal scripting language in FlightGear [http://gitorious.org/fg/fgdata/trees/master/Nasal].

If you have any Nasal specific questions, you will want to check out the [[Nasal FAQ]], feel free to ask new questions or help answer or refine existing ones. If you would like to learn more about existing Nasal modules in FlightGear, you may want to check out [[Nasal Modules]].

If you are a developer and interested in extending Nasal, you may want to check out [[Howto:Extending Nasal]].

Many short "howto"-style tutorials on Nasal programming can be found in the [[Category:Nasal|Nasal category]].

== Some words on Nasal for fellow C++ programmers ==

Compared to C++, there is really nothing "low quality" about Nasal per se: Nasal is just the "script glue" that connects different parts of the simulator: Many Nasal scripts leverage C++ code - and it is very easy to add new C++ code that can be called from Nasal.

History has shown, that most code in FlightGear will eventually be made more configurable and more accessible, this usually happens in the same steps: 1) replacing static variables with variables stored in the property tree, 2) using listeners to get update notifications for important variables, 3) fully exposing a "control" interface by making it accessible it in the property tree, 4) providing scripting hooks.

Even if you should know C or C++ already, Nasal probably remains the most accessible and the most powerful method for customizing the simulator, simply because it is extremely easy and fast to get started, you don't need an "integrated development environment", you don't need to install compilers and you don't need to satisfy any 3rd party dependencies; bottom line being: if you can run FlightGear, you can also run Nasal and create new code.

In addition, Nasal code is fairly abstract code, too. Once you start looking at some existing Nasal scripts, you will see that it is also fairly high level code, much more high level than C++ - so Nasal has a much higher density of code, too. Nasal's role in FlightGear really is like JavaScript's role in Firefox, where it is also used for many/most core-related logics (CSS/XUL).

=== Performance ===

Obviously, C++ code will usually be faster than the corresponding Nasal code. But, while performance is not a design goal, Nasal isn't especially slow either. For example, early benchmarks of the garbage collector showed it as faster than perl's reference counter, and its number crunching performance is on par with python. But in all cases, simplicity, transparency and a sane feature set are preferred over speed in Nasal.

Nasal was specifically designed for use as an extension language in an larger project such as FlightGear. The problem with many otherwise excellent languages in this environment is that they are huge. Perl and python are great, but enormous. Even their "core" interpreters and library code are larger than most projects that require an embedded language. They cannot be readily shipped with their host application and need to be installed system-wide. This is a pain and a compatibility hassle.

The real goal with Nasal is to have a language that supports most "normal" programming idioms (objects, functions, arrays, hashes) while avoiding the bloat that comes from "platform" scripting languages like perl, python, ruby and php.

=== Garbage collection ===
Nasal garbage collects runtime storage, so the programmer need not worry about manual allocation, or even circular references. The current implementation is a simple mark/sweep collector, which should be acceptable for most applications. Future enhancements will include a "return early" capability for latency-critical applications. The collector can be instructed to return after a certain maximum delay, and be restarted later.

As far as speed goes, the last any benchmarking Nasal was done, it was about as fast as Perl 5 or Python 2.2 at most things. It's garbage collector was faster, its symbol lookup about the same or slightly faster, and its bytecode interpreter somewhat slower.

=== Thread safety ===
Unlike almost all other script interpreters (and unlike the FlightGear/Nasal interface itself) , Nasal is thread safe and scalable when called from multiple CPU threads (as opposed to the userspace interpreter threads implemented by Ruby).

No special treatment is required (as for perl, which clones a separate interpreter with separate data for each thread and uses locking around specifically-designated shared data) and the threads can be scheduled simultaneously. There is no global lock on the interpreter, as used by Python or Lua. The only limit on scalability is garbage collection, which must block all interpreter threads before running.

When running threaded code, Nasal provides "minimal threadsafety", meaning that the interpreter itself can be safely called from multiple CPU threads without risk of corrupting or deadlocking the interpreter internals. Multithreaded operations are therefore "safe", although they are not guaranteed to be atomic. In particular, poorly synchronized insertions into containers can "drop" objects into oblivion (which is OK from an interpreter stability standpoint, since the GC will clean them up normally). Nasal itself provides no synchronization primitives to address this; thread architecture is a "top-level" design job, and Nasal is intended to be an extension language in a larger project. Choice of synchronization mechanisms is going to be highly application dependent.

=== Exception handling ===
Like python, nasal supports exception handling as a first-class language feature, with built-in runtime-inspectable stack trace. Rather like perl, however, there is no special "try" syntax for exception handling, nor inheritance-based catching semantics. Instead, you use the call() builtin to invoke a function object and inspect the results to determine what error was thrown (either with the die() builtin or via an internal runtime error) and what the stack trace looked like. Elaborate exception handling isn't really appropriate for embedded scripting languages.

=== High level programming ===

Thus, programmers already familiar with C++ shouldn't just disregard Nasal as a "toy" that doesn't seem suitable for serious development: some of the more complex Nasal scripts can literally make one's head spin around and it would quite obviously take much more C++ or Java code to implement the same features, while sacrificing all the flexibility and power that a scripting language offers.

Some features can certainly be more easily implemented in Nasal space, than in C++ space. Often, the Nasal solution is "on par" with similar solutions in C++.

=== Accessibility ===

For instance, Nasal code cannot only be easily run and contributed by all users, but it can also be easily reused and maintained by other users. This means, that given the number of active C++ developers, compared to the number of base package contributors, your Nasal code is more likely to be actively maintained by fellow users if it is written in Nasal.

In other words, if there are some experimental features you'd like to explore, Nasal is an excellent way to ensure that other FlightGear '''users''' can easily test your new features. This could be witnessed during the development of the local weather system or the bombable addon,too.

This is in stark contrast to features developed solely in C++ space, because these can usually only be tested by people able to build FlightGear from source, especially if your code isn't yet in the main repository, where it would eventually be available in the form of a binary snapshot.

Obviously, none of this is to say that Nasal is the perfect solution for any problem, there are many things for which Nasal isn't necessarily a perfect choice, such as low level code for example (i.e. rendering).

On the other hand, Nasal really is a powerful tool in FlightGear, and if you find that something should, but cannot, be done in Nasal space, it is extremely easy to add support for new features to the Nasal engine using extension functions or property listeners to trigger C/C++ code.

== Creating new Scripts ==

Nasal scripts need to be plain text files, saved with a *.nas extension.

=== Aircraft specific Nasal code ===

Generally, aircraft specific Nasal scripts reside in the corresponding aircraft's folder (or a corresponding /Nasal subfolder) where they are usually included by adding a corresponding <nasal> tag to the aircraft-set.xml file (see [[Writing_simple_scripts_in_%22nasal%22|Writing simple scripts in "nasal"]]). Also see the section on [[Nasal_scripting_language#Namespaces|namespaces]] which contains more specific examples.

=== Instrument specific Nasal code ===

While instrument specific scripts are saved within the instrument's folder (as previously mentioned, Nasal scripts can also be embedded in various other XML files), Nasal scripts driving shared instruments are generally stored in [[$FG ROOT]]/Aircraft/Generic/

=== Nasal code as bindings in XML files ===
Nasal scripts can also be used as "binding" objects, and can therefore appear anywhere in a configuration file (keyboard, mouse and joystick bindings, etc...) that accepts a <binding> tag. The relevant command type is "nasal", and you place your Nasal code inside of the <script> tag:

<binding>
<command>nasal</command>
<script>
print("Binding Invoked!");
</script>
</binding>

The code above invokes the print() function. This is a simple extension function that simply prints out its arguments, in order, to the FlightGear console as a single-line log entry. It is useful for debugging, but little else.

=== System-wide Nasal code ===

Nasal scripts that are not specific to certain aircraft, instruments or other uses, generally reside in the system-wide [[$FG ROOT]]/Nasal directory.

Nasal scripts that are placed inside [[$FG ROOT]]/Nasal (with a *.nas extension) are automatically loaded and run during FlightGear startup.

=== Nasal sub modules ===

As of 06/2011, FlightGear also supports so called Nasal "sub modules" which may reside in their own sub folder under $FG_ROOT/Nasal/ and which provide support for on-demand loading at runtime by toggling properties.

Some advantages are:

* Nasal files can be grouped neatly instead of all scripts being mixed up in a single fgdata/Nasal directory. Grouping makes a lot of sense for modules consisting of several scripts - local weather is the best example.
* Guaranteed loading sequence. Submodules are loaded _after_ the main fgdata/Nasal scripts, so they can rely on all fgdata/Nasal content to be already present. No more need for awkward listener callbacks, just to make sure that basic "props" or "gui" modules are available.
* Finally, users have the option to disable loading modules. Unfortunately, just loading scripts (code/data) into memory already causes certain _run-time_ performance effects - even if the Nasal code was never executed (so even when all listeners/timers were disabled).

Please note that there is a difference between the _individual_ Nasal files in fgdata/Nasal and files belonging to a common Nasal _module in general (no matter whether loaded at run-time or loaded at start-up using a "<nasal>" tag).

The individual Nasal files in fgdata/Nasal have an own namespace _each_. The namespace get's the name of the Nasal file itself. So if you have a "gui.nas" in the directory, then you can reference a symbol "foo" using "gui.foo".

Nasal modules also have a single namespace. But all files belonging to the module share this _single_ namespace. The name of their namespace is made from its directory (for the run-time loadable modules), or from the specific tag given below the <nasal> XML element, which are often used for a/c specific modules (e.g. <nasal><ufo>...</ufo></nasal> creates the ufo Nasal namespace in ufo-set.xml).

'''So each Nasal file in a new Nasal "module" folder now shares the same namespace.'''

For more information on Nasal sub modules, please see [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg32657.html] and [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg33458.html].

=== User specific Nasal scripts ===

It's also possible to put Nasal files into $FG_HOME/Nasal/, that is: ~/.fgfs/Nasal/ on Unix, and %APPDATA%\flightgear.org\Nasal\ on MS Windows. This has the following advantages:

* one doesn't have to mix local extensions with standard files
* one is less likely to lose such local additions when upgrading
* one doesn't need write permission to $FG_ROOT/Nasal/ or
* one doesn't have to become "root" to edit such files

The files are guaranteed to be read after all the files in $FG_ROOT/Nasal/, so one can safely use elements of files like props.nas (props.Node), or globals.nas (setlistener() without leading underscore).

The files are guaranteed to be read in alphabetic order. So, if there are two files where one depends on the other, just name them appropriately.

The contents of each file are added to a namespace derived from the filename. So, all functions and variables of a file ~/.fgfs/nasal/local.nas will be added to nasal namespace "local", and a function test() is globally accessible as local.test().

It's possible to extend a standard module like "math" with definitions in ~/.fgfs/Nasal/math.nas, though this should, of course, not be exploited by code that is to be submitted to cvs.

== Hello world ==

A simple hello world example in Nasal would be:

# hello.nas
print('Hello World!');

This will show the "Hello World" string during startup in the console window. The hash sign (#) just introduces comments (i.e. will be ignored by the interpreter).

Note: Script-specific symbols such as global variables (or functions) will be put into a scope (namespace) based on the script's name, scripts embedded via aircraft-set.xml files can separately specify a corresponding module name (see [[Howto: Make an aircraft]] for details).

Strings in Nasal can also use double quotes which support escaping:
# hello.nas
print("Hello\nWorld!");

Double quotes support typical escape sequences:

* \n Newline
* \t Horizontal Tab
* \v Vertical Tab
* \b Backspace
* \r Carriage Return
* \f Form feed
* \a Audible Alert (bell)
* \\ Backslash
* \? Question mark
* \' Single quote
* \" Double quote

For example, to print a new line, use:

print ("\n");

To print a quoted string, use:

print ("\"quoted string\"");

and so on.

Single quotes treat everything as literal except for embedded single quotes (including embedded whitespace like newlines).

Nasal strings are always arrays of bytes (never characters: see the utf8 library if you want character-based equivalents of substr() et. al.). They can be indexed just like in C (although note that there is no nul termination -- get the length with size()):

== Editing code files ==

Note that there is currently no way to tell FlightGear to reload Nasal scripts from the global Nasal directory at runtime, so in order to see changes take effect, you will have to exit and restart FlightGear for the time being. Note that there are some workarounds available, see: [[Nasal_scripting_language#Loading.2Freloading_Nasal_code_without_re-starting_Flightgear|reloading Nasal code without re-starting FlightGear]].

Also, note that as of 05/2009, Nasal in FlightGear does not yet support any form of dependency resolution. In other words, there's no "import", "require" or "include" directive - this is also why most code in FlightGear is wrapped inside a _setlistener() call instead, which in turn waits for a FlightGear signal before executing the code (see below for details).

== Variables ==
Nasal scripts should make use of the var keyword when declaring variables. The "var" keyword makes a variable guaranteed to be local. Nasal, natively provides support for scalars (numbers, strings), lists (arrays, vectors) and hashes (objects or dictionaries), more complex data structures (such as trees) can be built using vectors or hashes.

var w=100; # w is a local numerical variable
var x="hello"; # x is a local string variable
var y=[]; # y is a local vector (array)
var z={}; # z is a local hash (dictionary or table) - also used for OOP

Nasal supports a "nil" value for use as a null pointer equivalent:

var foo=nil;

Also, note that Nasal symbols are case-sensitive, these are all different variables:

var show = func(what) {print(what,"\n");}
var abc=1; # these are all different symbols
var ABC=2; # different from abc
var aBc=3; # different from abc and ABC

show(abc);
show(ABC);
show(aBc);

Please note that functions assigned to variables are no exception. If you write code without using "var" on variables, then you risk (often hard to debug) breakage at a later time because you may be overwriting symbols in another namespace.

So functions bound to variables should use the "var" keyword as well:

var hello = func {
print("hello\n");
}

But there's another reason why "var" should be used consequently, even if a variable is safe enough from later side effects, because it has a relatively specific or unique name: The "var" keyword makes
reading code for others (and for the author after some time) easier, as it makes clear: "this variable starts its life *HERE*". No need to search around to see whether assigning a value to it means something to other code outside or not. Also, with an editor offering proper syntax highlighting reading such code is actually easier, despite the "noise".

The problem with nasal code that does not make use of the var keyword is, that it can break other code, and with it the whole system, but no Nasal error message will point you there, as it's syntactically and semantically correct code. Just doing things that it wasn't supposed to do.
For a more in-depth discussion, please see [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg13557.html].

Also, Nasal scripts that are loaded from $FG_ROOT/Nasal are automatically placed inside a namespace that is based on the script's name.

For example, referring to our earlier "Hello World" example, global variables defined in the hello.nas script would be accessible by using "hello" as prefix from other modules:

# hello.nas
var greeting="Hello World"; # define a greeting symbol inside the hello namespace

If you were now to read out the value from the greeting variable from another Nasal module, you would have to use the hello prefix:

# greetme.nas
print(hello.greeting); # the hello prefix is referring to the hello namespace (or module).

==Namespaces==
The Nasal Console built into FlightGear is quite handy when it comes to debugging code. However, here the namespaces need to be considered. In addition, Nasal sub modules (see above) have some special rules, too - basically, all Nasal files part of a "sub module" share a single name space based on the folder's name rather than the name of the individual Nasal files.

For cases of Nasal code specific for an aircraft (like instruments, for example), the corresponding scripts could be loaded through the aircraft's <tt>-set.xml</tt> file by putting it into the <tt><nasal>...</nasal><tt> section

<nasal>
...
<moduleA>
<file>path/to/file1.nas</file>
<file>path/to/file2.nas</file>
</moduleA>
<moduleB>
<file>path/to/file3.nas</file>
</moduleB>
</nasal>

In this case, variables in files <tt>path/to/file1.nas</tt> and <tt>path/to/file2.nas</tt> can be used in the Nasal console as

moduleA.varName;

Variables in <tt>path/to/file3.nas</tt> can be accessed as

moduleB.varName;

Please note that Nasal sub modules (i.e. files loaded and run from their own Nasal sub directory), are subject to some special rules, as all Nasal source files are automatically loaded into the same namespace, which is by default based on the sub module's folder name.

'''''More information can be found by clicking [http://wiki.flightgear.org/Namespaces_and_Methods here].'''''

== Variables - Advanced Uses ==

Nasal, also supports Multi-assignment expressions. You can assign more than one variable (or lvalue) at a time by putting them in a parenthesized list:

(var a, var b) = (1, 2);
var (a, b) = (1, 2); # Shorthand for (var a, var b)
(var a, v[0], obj.field) = (1,2,3) # Any assignable lvalue works
var color = [1, 1, 0.5];
var (r, g, b) = color; # works with runtime vectors too

Vectors (lists or arrays) can be created from others using an ordered list of indexes and ranges.
This is usually called "vector slicing".
For example:

var v1 = ["a","b","c","d","e"]
#
var v2 = v1[3,2]; # == ["d","c"];
var v3 = v1[1:3]; # i.e. range from 1 to 3: ["b","c","d"];
var v4 = v1[1:]; # no value means "to the end": ["b","c","d","e"]
var i = 2;
var v5 = v1[i]; # runtime expressions are fine: ["c"]
var v6 = v1[-2,-1]; # negative indexes are relative to end: ["d","e"]

The range values can be computed at runtime (e.g. i=1; v5=v1[i:]). Negative indices work the same way they do with the vector functions (-1 is the last element, -2 is 2nd to last, etc...).

== Storage: property tree vs. Nasal ==
With FlightGear's built-in property tree and Nasal's support for it, there are two obvious, and two somewhat competing, ways for storing scalar data: native Nasal variables and FlightGear properties, both of which can be easily accessed and managed from Nasal.

The advantage to native Nasal-space data is that it's fast and simple. If the only thing that will care about the value is your script, they are good choices.

The property tree is an inter-subsystem communication thing. This is what you want if you want to share data with the C++ world (for example, YASim <control-output> tags write to properties -- they don't understand Nasal), or read in via configuration files.

Also, native Nasal data structures are usually far faster than their equivalent in property tree space. This is because there are several layers of indirection in retrieving a property tree value.

In general, this means that you shouldn't make overly excessive use of the property tree for storing state that isn't otherwise relevant to FlightGear or any of its subsystems. Doing that would in fact have adverse effects on the performance of your code. In general, you should favor Nasal variables and data structures and should only make use of properties to interface with the rest of FlightGear, or to easily provide debugging information at run time.

As of FG 2.4.0, retrieving a value from the property tree via getprop is about 50% slower than accessing a native Nasal variable, and accessing the value via node.getValue() is 10-20% slower yet. This is an insignificant amount of time if you are retrieving and storing a few individual values from the property tree, but adds up fast if you are storing or retrieving hashes or large amounts of data. (You can easily benchmark times on your own code using systime() or debug.benchmark.)

In addition, it is worth noting that the Nasal/FlightGear APIs cannot currently be considered to be thread safe, this mean that -at least for now- the explicit use of pure Nasal space variables is the only way to exploit possible parallelism in your code by making use of threads.

== Functions ==

=== What is a function ? ===

A "function" is a piece of code that can be easily used repeatedly (without repeating the same code over and over again), this is achieved by associating a symbolic name with the piece of code, such as "print", "show" or "get" for example. Whenever this symbolic name is then used in the program, the program will "jump" to the definition of the function and start running it, once the called function has completed it will automatically return to the instruction following the call.

By using so called "function arguments" (see below) it is possible to parametrize a function (using variables) so that it may use data that is specific to each invocation.

As previously shown, Nasal functions are implemented using the func keyword, The following snippet of code defines a new function named "log_message" with an empty function body (the curly braces).

var log_message = func {}

=== Function bodies ===

To add a function body, you need to add code in between these curly braces.

=== Anonymous function arguments ===

In Nasal, arguments are by default passed in the "arg" array, not unlike perl. To understand how this works, you should probably first read up on Nasal vectors.

var log_message = func {
print(arg[0]);
}

Note that this is equivalent to:

var log_message = func() {
print(arg[0]);
}

In other words, the argument list "()" can be omitted if it is empty.
However, if you are new to Nasal or programming in general, it is probably a good idea to ALWAYS use parentheses, i.e. also for functions with empty argument lists - that makes it easy to get used to the syntax.

Note that this is just an assignment of an (anonymous) function argument to the local "log_message" variable. There is no function declaration syntax in Nasal.

Also, Nasal being a functional programming language, all passed arguments will be local to the corresponding scope. If you want to modify state in a function, you'll preferably return new state to the caller.

===Named function arguments===
You can also pass named arguments to a function, thus saving the typing and performance costs of extracting them from the arg array:

var log_message = func(msg) {
print(msg);
}

The list of function arguments is called a function's "signature".

=== Default values for function arguments ===

Function arguments can have default values, as in C++. Note that the default value must be a scalar (number, string, function, nil) and not a mutable composite object (list, hash).

var log_message = func(msg="error") {
print(msg);
}

If some arguments have default values and some do not, those with default values must come first in the argument list:

#Incorrect:
var log_message = func(msg="error", line, object="ground") { #some code }

#Correct:
var log_message = func(msg="error", object="ground", line) { #some code }

Any extra arguments after the named list are placed in the "arg" vector as above. You can rename this to something other than "arg" by specifying a final argument name with an ellipsis:

listify = func(elements...) { return elements; }
listify(1, 2, 3, 4); # returns a list: [1, 2, 3, 4]

=== Returning from functions ===

In Nasal, functions return implicitly the values of the last expression (i.e. "nil" in empty function bodies), you can also add an explicit "return" statement, for example to leave a function early. In addition, it is possible to return values, too.

So, semantically, the previous snippet of code is equivalent to these:

var log_message = func {return;}

var log_message = func {nil;}

var log_message = func {};

var log_message = func return;

var log_message = func nil;

===Named arguments in function calls===
Nasal supports named function arguments in function calls, too.

As an alternative to the comma-separated list of ''positional'' function arguments, you can specify a hash literal in place of ordered function arguments, and it will become the local variable namespace for the called function, with variables named according to the hash indexes and with values according to the hash values. This makes functions with many arguments more readable.

And it also makes it possible to call function's without having to take care of the right order of passing arguments.

Examples:
#if we have functions defined:
var log_message = func (msg="") { #some code to log variable msg }
var lookat = func (heading=0, pitch=0, roll=0, x=nil, y=nil, z=nil, time=hil, fov=20) { #some code using those variables }

#we can use them them the usual way with comma separated list of arguments:
log_message("Hello World!");
lookat (180, 20, 0, XO, YO, ZO, now, 55);

#or we can use the hash literal arguments instead:
log_message(msg:"Hello World!");
lookat(heading:180, pitch:20, roll:0, x:X0, y:Y0, z:Z0,time:now, fov:55);

Both methods for calling the functions above are equivalent, but note the the second method is more readable, less prone to error, and self-documenting in the code for the function call.

As another example, consider:

var setPosition = func (latitude_deg, longitude_deg, altitude_ft) {
# do something here
}
# the actual function call:
setPosition( latitude_deg:34.00, longitude_deg:7.00, alt_ft:10000);

In other words, such function calls become much more self-explanatory because everybody can see immediately what a value is doing.
This is a good practice, as you may eventually have to take a longer break, away from your code - and then even you yourself will come to appreciate such small things that make code more intuitive to work with.

Declared arguments are checked and defaulted as would be expected: it's an error if you fail to pass a value for an undefaulted argument, missing default arguments get assigned as usual, and any rest parameter (e.g. "func(a,b=2,rest...){}") will be assigned with an empty vector.

===Nested functions, implicit return ===
Also, Nasal functions can be easily nested, for example:

var calculate = func(param1,param2,operator) {
var add = func(p1,p2) {p1+p2;}
var sub = func(p1,p2) {p1-p2;}
var mul = func(p1,p2) {p1*p2;}
var div = func(p1,p2) {p1/p2;}
if (operator=="+") return add(param1,param2);
if (operator=="-") return sub(param1,param2);
if (operator=="*") return mul(param1,param2);
if (operator=="/") return div(param1,param2);
}

Note that the add,sub,mul and div functions in this example do not make use of an explicit return statement, instead the result of each expression is implicitly returned to the caller.

Nasal functions that just consist of such simple expressions can also be further simplified to read:

var add = func(val1,val2) val1+val2;

=== Function overloading ===

Note that Nasal functions can generally not be [[http://en.wikipedia.org/wiki/Function_overloading overloaded]], and that operator overloading in particular is also not supported.

However, the effects of '''function overloading''' can obviously be implemented individually by each function, simply by processing the number and type of passed arguments at the start of the function body. The FlightGear code base contains a number of examples for this, i.e. it is for example possible to pass properties in the form of plain strings to a callback or in the form of a Nasal wrapper like props.Node.

So this can be accomplished by first checking the argument count and then the types of arguments passed to the function.

To provide an example, here's a simple function to multiply two numbers, no matter if they are provided as scalars, as a vector or as x/y members of a hash:

var multiply2 = func (params) {
if (typeof(params)=="scalar") return params*arg[0];
if (typeof(params)=="vector") return params[0]*params[1];
if (typeof(params)=="hash") return params.x*params.y;
die("cannot do what you want me to do");
}

So, now you have a very simple form of an "overloaded" function that supports different argument types and numbers:

multiply2( 2,6); # multiply two scalars
multiply2( [5,7] ); # multiply two scalars stored in a vector
multiply2( {x:8, y:9} ); # multiply two scalars stored in a hash

You could obviously extend this easily to support an arbitrary number of arguments by just using a for loop here.

As you can see, the basic idea is pretty simple and also scalable, you could easily extend this to and also return different types of values, such as vectors or hashes. This could for example be used to create wrappers in Nasal space for doing 3D maths, with vectors and matrices, so that a matrix multiplication could return a new matrix, too.

===Functional programming, higher order functions, generators;===
As previously mentioned, arguments to a Nasal function can also be functions themselves (Nasal being a functional programming language), this means that Nasal functions are higher order functions so that you can easily pass and return functions to and from Nasal functions. This can for example be used to dynamically create new functions (such functions are commonly called 'generators'):

# a function that returns a new custom function
var i18n_hello = func(hello) {
return func(name) { # returns an anonymous/unnamed function
print(hello,name);
}
}

# create three new functions
var english_hello = i18n_hello("Good Day ");
var spanish_hello = i18n_hello("Buenos Dias ");
var italian_hello = i18n_hello("Buon giorno ");

# actually call these functions
english_hello("FlightGear");
spanish_hello("FlightGear");
italian_hello("FlightGear");

=== Using helper functions ===

It is possible to simplify complex function calls by introducing small helper functions, for example consider:

var l = thermalLift.new(ev.lat, ev.lon, ev.radius, ev.height, ev.cn, ev.sh, ev.max_lift, ev.f_lift_radius);

So, you could just as well create a small helper function named"thermalLift.new_from_ev(ev)":

thermalLift.new_from_ev = func (ev) {
thermalLift.new(ev.lat, ev.lon, ev.radius, ev.height, ev.cn, ev.sh, ev.max_lift, ev.f_lift_radius);
}

var l=thermalLift.new_from_ev(ev);

Note that the expression to invoke your code would then also become less complicated and much more comprehensible.

When you have expressions of nested method calls, such as:

t.getNode("latitude-deg").setValue(f.getNode("latitude-deg").getValue());
t.getNode("longitude-deg").setValue(f.getNode("longitude-deg").getValue());

You could just as easily introduce a small helper function to wrap the code, that would be less typing for you, less code to read (and understand) for others and generally it would help localize functionality (and possible errors):

var copyNode = func(t,f,path) t.getNode(path).setValue(f.getNode(path).getValue());

So you would simply take the complex expression and generalize it by adding variables that you pass in from a function object, then you could simply call your new function like this:

copyNode(t,f,"latitude-deg");
copyNode(t,f,"longitude-deg");

or:

foreach(var p; ["latitude-deg", "longitude-deg","generated-flag"])
copyNode(t,f,p);

or as a complete function accepting a vector of properties:

var copyNode = func(target,source,properties) {
if (typeof(properties)!="vector") properties=[properties];
if (typeof(target)!="hash") target=props.globals.getNode(target);
if (typeof(source)!="hash") target=props.globals.getNode(source)
foreach(var path; properties)
target.getNode(path).setValue( source.getNode(path).getValue() );
}

copyNode("/temp/test", "/position", ["latitude-deg", "longitude-deg", "altitude-ft"]);

Whenever you have very similar lines of code that seem fairly repetitive, it is a good idea to consider introducing small helper functions. You can use plenty of small helper functions and then just "chain" them together, rather than using complex nested expressions that make your head spin.

== Conditionals ==

Nasal has no "statements", which means that any expression can appear in any context. This means that you can use an if/else clause to do what the ?: does in C.
The last semicolon in a code block is optional, to make this prettier

abs = func(n) { if(n<0) { -n } else { n } }

But for those who don't like typing, the ternary operator works like you expect:

abs = func(n) { n < 0 ? -n : n }

In addition, Nasal supports braceless blocks, like they're known from C/C++ and other languages:

var foo=1;
if (foo)
print("1\n");
else
print("0\n");
print("this is printed regardless\n")

Instead of a switch statement one can use

if (1==2) {
print("wrong");
} else if (1==3) { # NOTE the space between else and if
print("wronger");
} else {
print("don't know");
}

which produces the expected output of <code>don't know</code>

The <tt>nil</tt> logic is actually quite logical, let's just restate the obvious:

if (nil) {
print("This should never be printed");
} else {
print("This will be printed, because nil is always false");
};

Nasal's binary boolean operators are "and" and "or", unlike C. unary not is still "!" however.
They short-circuit like you expect

var toggle = 0;
var a = nil;
if(a and a.field == 42) {
toggle = !toggle; # doesn't crash when a is nil
}

You can easily reduce the complexity of huge conditional (IF) statements, such as this one:

if (a==1) function_a();
else
if (a==2) function_b();
else
if (a==3) function_c();
else
if (a==4) function_d();
else
if (a==5) function_e();

.. just by using the variable as a key (index) into a hash, so that you can directly call the corresponding function:

var mapping = {1:function_a, 2:function_b, 3:function_c, 4:function_d,5:function_e};
mapping[a] ();

This initializes first a hash map of values and maps a function "pointer" to each value, so that accessing mapping[x] will return the function pointer for the key "x".

Next, you can actually call the function by appending a list of function arguments (empty parentheses for no args) to the hash lookup.

Using this technique, you can reduce the complexity of huge conditional blocks. For example, consider:

# weather_tile_management.nas
460 if (code == "altocumulus_sky"){weather_tiles.set_altocumulus_tile();}
461 else if (code == "broken_layers") {weather_tiles.set_broken_layers_tile();}
462 else if (code == "stratus") {weather_tiles.set_overcast_stratus_tile();}
463 else if (code == "cumulus_sky") {weather_tiles.set_fair_weather_tile();}
464 else if (code == "gliders_sky") {weather_tiles.set_gliders_sky_tile();}
465 else if (code == "blue_thermals") {weather_tiles.set_blue_thermals_tile();}
466 else if (code == "summer_rain") {weather_tiles.set_summer_rain_tile();}
467 else if (code == "high_pressure_core") {weather_tiles.set_high_pressure_core_tile();}
468 else if (code == "high_pressure") {weather_tiles.set_high_pressure_tile();}
469 else if (code == "high_pressure_border") {weather_tiles.set_high_pressure_border_tile();}
470 else if (code == "low_pressure_border") {weather_tiles.set_low_pressure_border_tile();}
471 else if (code == "low_pressure") {weather_tiles.set_low_pressure_tile();}
472 else if (code == "low_pressure_core") {weather_tiles.set_low_pressure_core_tile();}
473 else if (code == "cold_sector") {weather_tiles.set_cold_sector_tile();}
474 else if (code == "warm_sector") {weather_tiles.set_warm_sector_tile();}
475 else if (code == "tropical_weather") {weather_tiles.set_tropical_weather_tile();}
476 else if (code == "test") {weather_tiles.set_4_8_stratus_tile();}
477 else ...

While this is not a very complex or huge block of code, it is an excellent example for very good naming conventions used already, because the consistency of naming variables and functions can pay off easily here, with just some very small changes, you can already reduce the whole thing to a hash lookup like this:

weather_tiles["set_"~code~"_tile"](); # naming convention

This would dynamically concatenate a key consisting of "set_" + code + "_title" into the hash named weather_tiles, and then call the function that is returned from the hash lookup.

So for this to work you only need to enforce consistency when naming your functions (i.e. this would of course CURRENTLY fail when the variable code contains "test" because there is no such hash member (it's "4_8_stratus" instead).

The same applies to cumulus sky (fair weather), stratus/overcast stratus.

But these are very simple changes to do (just renaming these functions to match the existing conventions). When you do that, you can easily replace such huge IF statements and replace them with a single hash lookup and function call:

hash[key] (arguments...);

For example, consider:

var makeFuncString = func(c) return tolower("set_"~c~"_tile");
var isFunc = func(f) typeof(f)=='func';
var hasMethod = func(h,m) contains(h,m) and isFunc;
var callIfAvailable = func(hash, method, unavailable=func{} ) {
var c=hasMethod(hash,makeFuncString(m) ) or unavailable();
hash[makeFuncString(m)] ();
}
callIfAvailable( weather_tiles,code, func {die("key not found in hash or not a func");} );

== Initializing data structures ==

There are some more possibilities to increase the density of your code, such as by removing redundant code or by generalizing and refactoring existing code so that it can be reused in different places (i.e. avoiding duplicate code):

For example see weather_tile_management.nas #1000 (create_neighbours function):

1008 x = -40000.0; y = 40000.0;
1009 setprop(lw~"tiles/tile[0]/latitude-deg",blat + get_lat(x,y,phi));
1010 setprop(lw~"tiles/tile[0]/longitude-deg",blon + get_lon(x,y,phi));
1011 setprop(lw~"tiles/tile[0]/generated-flag",0);
1012 setprop(lw~"tiles/tile[0]/tile-index",-1);
1013 setprop(lw~"tiles/tile[0]/code","");
1014 setprop(lw~"tiles/tile[0]/timestamp-sec",weather_dynamics.time_lw);
1015 setprop(lw~"tiles/tile[0]/orientation-deg",alpha);
1016
1017 x = 0.0; y = 40000.0;
1018 setprop(lw~"tiles/tile[1]/latitude-deg",blat + get_lat(x,y,phi));
1019 setprop(lw~"tiles/tile[1]/longitude-deg",blon + get_lon(x,y,phi));
1020 setprop(lw~"tiles/tile[1]/generated-flag",0);
1021 setprop(lw~"tiles/tile[1]/tile-index",-1);
1022 setprop(lw~"tiles/tile[1]/code","");
1023 setprop(lw~"tiles/tile[1]/timestamp-sec",weather_dynamics.time_lw);
1024 setprop(lw~"tiles/tile[1]/orientation-deg",alpha);
1025
1026 x = 40000.0; y = 40000.0;
1027 setprop(lw~"tiles/tile[2]/latitude-deg",blat + get_lat(x,y,phi));
1028 setprop(lw~"tiles/tile[2]/longitude-deg",blon + get_lon(x,y,phi));
1029 setprop(lw~"tiles/tile[2]/generated-flag",0);
1030 setprop(lw~"tiles/tile[2]/tile-index",-1);
1031 setprop(lw~"tiles/tile[2]/code","");
1032 setprop(lw~"tiles/tile[2]/timestamp-sec",weather_dynamics.time_lw);
1033 setprop(lw~"tiles/tile[2]/orientation-deg",alpha);
1034
1035 x = -40000.0; y = 0.0;
1036 setprop(lw~"tiles/tile[3]/latitude-deg",blat + get_lat(x,y,phi));
1037 setprop(lw~"tiles/tile[3]/longitude-deg",blon + get_lon(x,y,phi));
1038 setprop(lw~"tiles/tile[3]/generated-flag",0);
1039 setprop(lw~"tiles/tile[3]/tile-index",-1);
1040 setprop(lw~"tiles/tile[3]/code","");
1041 setprop(lw~"tiles/tile[3]/timestamp-sec",weather_dynamics.time_lw);
1042 setprop(lw~"tiles/tile[3]/orientation-deg",alpha);
1043
1044 # this is the current tile
1045 x = 0.0; y = 0.0;
1046 setprop(lw~"tiles/tile[4]/latitude-deg",blat + get_lat(x,y,phi));
1047 setprop(lw~"tiles/tile[4]/longitude-deg",blon + get_lon(x,y,phi));
1048 setprop(lw~"tiles/tile[4]/generated-flag",1);
1049 setprop(lw~"tiles/tile[4]/tile-index",1);
1050 setprop(lw~"tiles/tile[4]/code","");
1051 setprop(lw~"tiles/tile[4]/timestamp-sec",weather_dynamics.time_lw);
1052 setprop(lw~"tiles/tile[4]/orientation-deg",getprop(lw~"tmp/tile-orientation-deg"));
1053
1054
1055 x = 40000.0; y = 0.0;
1056 setprop(lw~"tiles/tile[5]/latitude-deg",blat + get_lat(x,y,phi));
1057 setprop(lw~"tiles/tile[5]/longitude-deg",blon + get_lon(x,y,phi));
1058 setprop(lw~"tiles/tile[5]/generated-flag",0);
1059 setprop(lw~"tiles/tile[5]/tile-index",-1);
1060 setprop(lw~"tiles/tile[5]/code","");
1061 setprop(lw~"tiles/tile[5]/timestamp-sec",weather_dynamics.time_lw);
1062 setprop(lw~"tiles/tile[5]/orientation-deg",alpha);
1063
1064 x = -40000.0; y = -40000.0;
1065 setprop(lw~"tiles/tile[6]/latitude-deg",blat + get_lat(x,y,phi));
1066 setprop(lw~"tiles/tile[6]/longitude-deg",blon + get_lon(x,y,phi));
1067 setprop(lw~"tiles/tile[6]/generated-flag",0);
1068 setprop(lw~"tiles/tile[6]/tile-index",-1);
1069 setprop(lw~"tiles/tile[6]/code","");
1070 setprop(lw~"tiles/tile[6]/timestamp-sec",weather_dynamics.time_lw);
1071 setprop(lw~"tiles/tile[6]/orientation-deg",alpha);
1072
1073 x = 0.0; y = -40000.0;
1074 setprop(lw~"tiles/tile[7]/latitude-deg",blat + get_lat(x,y,phi));
1075 setprop(lw~"tiles/tile[7]/longitude-deg",blon + get_lon(x,y,phi));
1076 setprop(lw~"tiles/tile[7]/generated-flag",0);
1077 setprop(lw~"tiles/tile[7]/tile-index",-1);
1078 setprop(lw~"tiles/tile[7]/code","");
1079 setprop(lw~"tiles/tile[7]/timestamp-sec",weather_dynamics.time_lw);
1080 setprop(lw~"tiles/tile[7]/orientation-deg",alpha);
1081
1082 x = 40000.0; y = -40000.0;
1083 setprop(lw~"tiles/tile[8]/latitude-deg",blat + get_lat(x,y,phi));
1084 setprop(lw~"tiles/tile[8]/longitude-deg",blon + get_lon(x,y,phi));
1085 setprop(lw~"tiles/tile[8]/generated-flag",0);
1086 setprop(lw~"tiles/tile[8]/tile-index",-1);
1087 setprop(lw~"tiles/tile[8]/code","");
1088 setprop(lw~"tiles/tile[8]/timestamp-sec",weather_dynamics.time_lw);
1089 setprop(lw~"tiles/tile[8]/orientation-deg",alpha);
1090 }

At first glance, this seems like a fairly repetitive and redundant block of code, so it could probably be simplified easily:

var create_neighbours = func (blat, blon, alpha) {
var phi = alpha * math.pi/180.0;
calc_geo(blat);
var index=0;
var pos = [ [-40000.0,40000.0], [0.0, 40.000], [40000.0, 40000.0], [-40000, 0], [0,0], [40000,0], [-40000,-40000], [0,-40000], [40000,-40000] ];
foreach (var p;pos) {
x=p[0]; y=p[1];
setprop(lw~"tiles/tile[index]/latitude-deg",blat + get_lat(x,y,phi));
setprop(lw~"tiles/tile[index]/longitude-deg",blon + get_lon(x,y,phi));
setprop(lw~"tiles/tile[index]/generated-flag",0);
setprop(lw~"tiles/tile[index]/tile-index",-1);
setprop(lw~"tiles/tile[index]/code","");
setprop(lw~"tiles/tile[index]/timestamp-sec",weather_dynamics.time_lw);
setprop(lw~"tiles/tile[index]/orientation-deg",alpha);
index=index+1;
}
}

== Loops ==

Nasal has several ways to implement an iteration.

===for, while, foreach, and forindex loops===
Nasal's looping constructs are mostly C-like:

for(var i=0; i < 3; i = i+1) {
# loop body
}

while (condition) {
# loop body
}

The differences are that there is no do{}while(); construct, and there is a foreach, which takes a local variable name as its first argument and a vector as its second:

foreach(elem; list1) { doSomething(elem); } # NOTE: the delimiter is a SEMICOLON ;

The hash/vector index expression is an lvalue that can be assigned as well as inspected:

foreach(light; lights) { lightNodes[light] = propertyPath; }

To walk through all elements of a hash, for a foreach loop on the keys of they hash. Then you call pull up the values of the hash using the key. Example:

myhash= {first: 1000, second: 250, third: 25.2 };
foreach (var i; keys (myhash)) {
#multiply each value by 2:
myhash[i] *= 2;
#print the key and new value:
print (i, ": ", myhash[i]);
}

There is also a "forindex", which is like foreach except that it assigns the index of each element, instead of the value, to the loop variable.

forindex(i; list1) { doSomething(list1[i]); }

Also, braceless blocks work for loops equally well:

var c=0;
while( c<5 )
print( c+=1 );
print("end of loop\n");

===settimer loops===
Loops using <tt>while</tt>, <tt>for</tt>, <tt>foreach</tt>, and <tt>forindex</tt> block all of FlightGear's subsystems that run in the main thread, and can, thus, only be used for instantaneous operations that don't take too long.

For operations that should continue over a longer period, one needs a non-blocking solution. This is done by letting functions call themselves after a timed delay:

var loop = func {
print("this line appears once every two seconds");
settimer(loop, 2);
}

loop(); # start loop

Note that the <tt>settimer</tt> function expects a ''function object'' (<tt>loop</tt>), not a function call (<tt>loop()</tt>) (though it is possible to make a function call return a function object--an advanced functional programming technique that you won't need to worry about if you're just getting started with Nasal).

The fewer code FlightGear has to execute, the better, so it is desirable to run loops only when they are needed. But how does one stop a loop? A once triggered timer function can't be revoked. But one can let the loop function check an outside variable and refuse calling itself, which makes the loop chain die off:

var running = 1;
var loop = func {
if (running) {
print("this line appears once every two seconds");
settimer(loop, 2);
}
}

loop(); # start loop ...
...
running = 0; # ... and let it die

Unfortunately, this method is rather unreliable. What if the loop is "stopped" and a new instance immediately started again? Then the ''running'' variable would be ''1'' again, and a pending old loop call, which should really finish this chain, would happily continue. And the new loop chain would start, too, so that we would end up with two loop chains.

This can be solved by providing each loop chain with a ''loop identifier'' and letting the function end itself if the id doesn't match the global loop-id. Self-called loop functions need to inherit the chain id. So, every time the global loop id is increased, all loop chains die, and a new one can immediately be started.

var loopid = 0;
var loop = func(id) {
id == loopid or return; # stop here if the id doesn't match the global loop-id
...
settimer(func { loop(id) }, 2); # call self with own loop id
}

loop(loopid); # start loop
...
loopid += 1; # this kills off all pending loops, as none can have this new identifier yet
...
loop(loopid); # start new chain; this can also be abbreviated to: loop(loopid += 1);

[[Nasal_scripting_language#settimer.28.29|More information about the settimer function is below]]

== OOP - Object Oriented Programming ==

In Nasal, objects ("classes") are regular hashes. Self-reference and inheritance are implemented through special variables <tt>me</tt> and <tt>parents</tt>. To get a better understanding of the concept, let's start with the very basics.

=== Hashes ===

Hashes, also known as "dictionaries" in Python or "maps" in C++/STL are data structures that hold key/value pairs in a way that allows quick access to a value via its key.

var airport = {
"LOXZ": "Zeltweg",
"LOWI": "Innsbruck",
"LOXL": "Linz Hoersching", # the last comma is optional
};

print(airport["LOXZ"]); # prints "Zeltweg"
airport["LOXA"] = "Aigen"; # adds LOXA to the hash

The built-in function keys() returns a vector with the keys of the hash. The function values() returns a vector with the values of the hash. For example:

debug.dump (keys(airport)); #prints ['LOXZ', 'LOWI', 'LOXL']
debug.dump (values (airport)); #prints ['Zeltweg', 'Innsbruck', 'Linz Hoersching']

The quotes around keys can be left away in a hash definition if the key is a valid variable name or a number. This works just as well:

var airport = {
LOXZ: "Zeltweg",
};

There's also an alternative way to access hash members if the keys are valid variable names: <tt>airport.LOXI</tt> can be used instead of <tt>airport["LOXI"]</tt>. There is a difference, though, which is described in the next section.

Note that assigning a hash (or a vector) to another variable does never ''copy'' the contents. It only creates another reference to the same data structure. So manipulating the hash via its new name does in fact change the one, original hash.

var a = airport;
a.LOXL = "Linz"; # same as airport.LOXL!
print(airport.LOXL); # prints now "Linz", not "Linz Hoersching"

(True copies of vectors can be made by assigning a full slice: <tt>var copy = vec[:]</tt>. There's no such method for hashes.)

=== Self-reference: "<tt>me</tt>" ===

Values stored in a hash can be of any type, even of type ''function''. Member functions ("methods") can reference their own enclosing hash via reserved keyword <tt>me</tt>. This is comparable to the <tt>this</tt> keyword in C++ classes, or the <tt>self</tt> keyword in Python.

var value = "test";

var data = {
value: 23, # scalar member variable
write1: func { print(value); }, # function member
write2: func { print(me.value); }, # function member
};

data.write1(); # prints "test"
data.write2(); # prints 23

The above example is already a simple form of an object. It has its own variable namespace (''data''), its own methods, and it can be passed around by-reference as one unit. Such classes are sometimes called ''singleton classes'', as they are unique, with no independent class instances. They mostly serve as a way to keep data and methods nicely encapsulated within a Nasal module. Often they contain a method for initializing, which is usually called <tt>init</tt>.

=== Inheritance: "<tt>parents</tt>" ===

What we learned about <tt>me</tt> in the last section is only half the truth. "me" doesn't only reference an object's own hash, but also one or more parent hashes. <tt>parents</tt> is another reserved keyword. It denotes a vector referencing other object hashes, which are "inherited" that way.

Please note that Nasal's currently supported form of encapsulation does not provide support for any form of data/information hiding (restricting access), i.e. all hash fields (but also all hash methods) are always publicly accessible (so there's nothing like the "private" or "protected" keywords in C++: in this sense, Nasal's inheritance mechanism can be thought of like C++ structs which are also public by default).

The major difference being, that all members (functions and fields) are also always '''mutable''', which means that functions can modify the behavior of other functions quite easily, this also applies to the parents vector, too.

var parent_object = {
value: 123,
};

var object = {
parents: [parent_object],
write: func { print(me.value) },
};

object.write(); # prints 123

Even though <tt>object</tt> itself doesn't contain a member <tt>value</tt>, it finds and uses the one of its parent object. <tt>parents</tt> is a vector that can contain several parent objects. These are then searched in the order from left to right, until a matching member variable or method is found. Each of the parents can itself have parents, which are all recursively searched.

In the section about hashes it was said that hash members can be accessed in two alternative ways, and that's also true for methods. <tt>object.write()</tt> could also be called as <tt>object["write"]()</tt>. But only in the first form will members also be searched in parent hashes if not found in the base hash, whereas the second form creates an error if it's not a direct member.

=== Creating class instances ===

With <tt>me</tt> and <tt>parents</tt> we can implement a class object and create independent instances from that:

var Class = {
write: func { print(me.value); },
increment: func { me.value += 1; },
};

var instance1 = { parents: [Class], value: 123 };
var instance2 = { parents: [Class], value: 456 };

instance1.write(); # prints 123
instance2.write(); # prints 456

As you can see, the two class instances are separate, independent objects, which share another object as parent -- they "inherit" from object <tt>Class</tt>. One can now easily change members of any of these three objects. The following will redefine the parent's <tt>write</tt> method, and all instances will automatically use this new version:

Class.write = func { print("VALUE = " ~ me.value) }

But one can also add a method to just one instance:

instance1.write = func { print("VALUE = " ~ me.value) }

Because <tt>instance1</tt> does now have its own <tt>write</tt> method, the parents won't be searched for one, so <tt>Class.write</tt> is now overridden by <tt>instance1</tt>'s own method. Nothing changed for <tt>instance2</tt> -- it will still only find and use <tt>Class.write</tt> via its parent.

Note, the we couldn't create a class instance by simple assignment, because, as we learned above, this wouldn't create a separate copy of the Class object. All "instances" would reference the same hash!

var bad_instance1 = Class; # bad
var bad_instance2 = Class; # bad

bad_instance1.value = 123; # sets Class.value to 123
bad_instance2.value = 456; # sets Class.value to 456

bad_instance1.write(); # prints 456, not 123

=== Constructor ===

Defining each class instance by explicitly creating a hash with parents is clumsy. It is nicer to have a function that does that for us. Then we can also use function arguments to initialize members of this instance.

var new_class = func(val) {
return { parents: [Class], value: val };
}

var instance1 = new_class(123);
var instance2 = new_class(456);

instance1.write(); # prints 123
instance2.write(); # prints 456

Because the class generating function <tt>new_class()</tt> really belongs to class <tt>Class</tt>, it would be nicer to put it into the class hash as well. In this case we call it a class "constructor", and as a convention, give it the name ''new''. It could have any name, though, and there could be more than one constructor.

var Class = {
new: func(val) {
return { parents: [Class], value: val };
},
write: func {
print("VALUE=" ~ me.value);
},
};

var instance1 = Class.new(123);
var instance2 = Class.new(456);

As you can see, <tt>new()</tt> doesn't return a copy of <tt>Class</tt>, but rather a small hash that contains only a list of parents and one individual member <tt>value</tt>.

Classes aren't always as simple as in our example. Usually they contain several members, of which some may have yet to be calculated in the constructor. In that case it's easier to create a local object hash first, and to let the constructor finally return it. Such local hashes are often named <tt>m</tt> (as a short reference to <tt>me</tt>), or <tt>obj</tt>.

var Class = {
new: func(val) {
var m = { parents: [Class] };
m.value = val;
return m;
},
write: func {
print("VALUE=" ~ me.value);
},
};

This last example is the most frequently used form of class definitions in FlightGear-Nasal.

=== Destructor ===

There's no such thing in Nasal. In other languages destructors are automatically called when the class gets destroyed, so that memory and other resources that were allocated by the constructor can be freed. In Nasal that's all done by the Garbage Collector (GC), anyway. In the FlightGear context, however, there ''are'' resources that should get freed. Listeners should get removed, self-calling functions ("loops") stopped. For that it's recommended to create a destructor function and to call that manually. Such functions are often called <tt>del</tt>, similar to Python and to pair nicely with the three-letter constructor name <tt>new</tt>.

=== Memory management ===

Finally, as you know now, Nasal, being a dynamic programming language, doesn't require or support any manual memory management, so unlike C++, you don't need to call operators like "new" or "delete" to allocate or free your memory.

However, if you do know that you don't need a certain variable anymore, you can certainly give a hint to the built-in garbage collector to free it, by assigning a "nil" value to it.

This can certainly pay off when using more complex data structures such as nested vectors or hashes, because it will tell the built-in garbage collector to remove all references to the corresponding symbols, so that they can be freed.

It is also possible to make use of Nasal's delete() function to remove a symbol from a namespace (hash).

So, if you are concerned about your script's memory requirements, using a combination of setting symbols to nil, or deleting them as appropriate, would allow you to create helper functions for freeing data structures easily.

In addition, it is probably worth noting that this is also the only way to sanely reset an active Nasal namespace or even the whole interpreter. You need to do this in order to reload or re-initialize your code without restarting the whole FlightGear session [[Nasal_scripting_language#Managing_timers_and_listeners]].

Obviously, you should first of all ensure that there is no more code running, this includes any registered listeners or timers, but also any others loops or recursive functions.

Thus, if you'd like to reload a Nasal source file at run time, you should disable all running code, and then reset the corresponding namespace, too. This is to ensure that you get a clean and consistent namespace.

Nasal provides a number of core library functions to manipulate namespaces, such as:

* caller() - to get a strack trace of active functions currently on the Nasal stack
* compile() - to compile new Nasal code "on the fly", i.e. dynamically from a string
* closure() - to query the lexical namespace of active functions
* bind() - to create new function objects

More information is available here: http://www.plausible.org/nasal/lib.html

If, on the other hand, you are using these data structures in some repeated fashion, it might make sense to keep the data structure itself around and simply re-use it next time (overwriting data as required), instead of always allocating/creating a new one, this is called "caching" and can pay off from a performance perspective.

=== Multiple inheritance ===

A class can inherit from one or more other classes. It can then access all methods and class members of all parent classes, but also override them and add additional members.

var A = { # simple class A
new: func {
return { parents: [A] };
},
alpha: func print("\tALPHA"),
test: func print("\tthis is A.test"),
};

var B = { # simple class B
new: func(v) { # ... whose constructor takes an argument
return { parents: [B], value: v };
},
bravo: func print("\tBRAVO"),
test: func print("\tthis is B.test"),
write: func print("\tmy value is: ", me.value),
},

var C = { # class C that inherits ...
new: func(v) {
return { parents: [C, A.new(), B.new(v)] }; # ... from class A and B
},
charlie: func print("\tCHARLIE"),
test: func print("\tthis is C.test"), # overrides A.test() and B.test()
};

print("A instance");
var a = A.new();
a.alpha();

print("B instance");
var b = B.new(123);
b.bravo();
b.write();

print("C instance");
var c = C.new(456);
c.alpha(); # use alpha from the A parent
c.bravo(); # use bravo from the B parent
c.charlie(); # use charlie from C itself
c.test(); # use C.test(), which overrides A.test() and B.test()
c.write();

Even if a class overrides a method of a parent with the same name, the parent's version can still be accessed via <tt>parents</tt> vector.

c.test() # use C.test()
c.parents[0].test(); # use C.test()
c.parents[1].test(); # use A.test()
c.parents[2].test(); # use B.test()

=== More on methods ===

Methods are function members of a class hash. They can access other class members via the <tt>me</tt> variable, which is a reference to the class hash. For this reason, a method returning <tt>me</tt> can be used like the class itself, and one can apply further methods to the return value (this is usually called "method chaining"):

var Object = {
new: func(coords...) {
return { parents: [Object], coords: coords };
},
rotate: func(angle) {
# do the rotation
return me;
},
scale: func(factor) {
# do the scaling
return me;
},
translate: func(x, y) {
# do the translation
return me;
},
};

var triangle = Object.new([0, 0], [10, 0], [5, 7]);
triangle.translate(-9, -4).scale(5).rotate(33).translate(9, 4); # concatenated methods thanks to "me"

<tt>me</tt>, however, is only known in the scope of the class. If a method is to be called as a listener callback or a timer function, <tt>me</tt> has to get wrapped in a function, so that it's stored in the function closure.

var Manager = {
new: func {
return { parents: [Manager] };
},
start_timers: func {
settimer(do_stuff, 5); # BAD: there's no "do_stuff" function in the scope
settimer(me.do_stuff, 5); # BAD: function exists, but "me" won't be known
# when the timer function is actually executed
settimer(func me.do_stuff(), 5); # GOOD: new function object packs "me" in the closure

setlistener("/sim/foo", func me.do_stuff()); # GOOD (same as with timers)
},
do_stuff: func {
print("doing stuff");
},
};

var manager = Manager.new();
manager.start_timers();

'''Click ''[http://wiki.flightgear.org/Namespaces_and_Methods#Methods here]'' for more information.'''

== Exception handling ==

<tt>die()</tt> aborts a function with an error message (this can be compared to the throw() mechanism in C++).

var divide = func(a, b) {
if (b == 0)
die("division by zero");
return a / b; # this line won't be reached if b == 0
}

die() is also used internally by built-in extension functions or Nasal core functions. <tt>getprop("/4me")</tt>, for example, dies with an error message ''"name must begin with alpha or '_'"''. Now assume we want to write a dialog where the user can type a property path into an input field, and we display the property's value in a popup dialog. What if the user typed an invalid path and we hand that over to <tt>getprop()</tt>? We don't want Nasal to abort our code because of that. We want to display a nice error message instead. The <tt>call()</tt> function can catch <tt>die()</tt> exceptions:

var value = getprop(property); # dies if 'property' is invalid
var value = call(func getprop(property), nil, var err = []); # catches invalid-property-exception and continues

The second line calls getprop(property) just like the first, and returns its value. But if 'property' was invalid then the <tt>call()</tt> function catches the exception and sets the 'err' vector instead. That vector remains empty on success.

if (size(err))
print("ERROR: bad property ", property, " (", err[0], ")"); # err[0] contains the die() message
else
print("value of ", property, " is ", value);

The first argument of <tt>call()</tt> is a function object, the second a vector of function arguments (or ''nil''), and the third a vector where the function will return a possible error. For more information on the <tt>call()</tt> function see the [http://plausible.org/nasal/lib.html Nasal library documentation].

<tt>die()</tt> doesn't really care about what its argument is. It doesn't have to be a string, and can be any variable, for example a class. This can be used to pass values through a chain of functions.

var Error = { # exception class
new: func(msg, number) {
return { parents: [Error], message: msg, number: number };
},
};

var A = func(a) {
if (a < 0)
die(Error.new("negative argument to A", a)); # throw Error
return "A received " ~ a;
}

var B = func(val) {
var result = A(val);
print("B finished"); # this line is not reached if A threw an exception
return result;
}

var value = call(B, [-4], var err = []); # try B(-4)

if (size(err)) { # catch (...)
print("ERROR: ", err[0].message, "; bad value was ", err[0].number);
die(err[0]); # re-throw
} else {
print("SUCCESS: ", value);
}

== Listeners and Signals ==

Listeners are callback functions that are attached to property nodes. They are triggered whenever the node is written to, or, depending on the listener type, also when children are added or removed, and when children are written to. Unlike polling loops, listeners don't have the least effect on the frame rate when they aren't triggered, which makes them preferable to monitor properties that aren't written to frequently.

===setlistener() vs. _setlistener() ===
You are requested *not* to use the raw _setlistener() function, except in files in $FG_ROOT/Nasal/ when they are
needed immediately. Only then the raw function is required, as it doesn't rely on props.nas.

===<tt>When listeners don't work</tt>===
Unfortunately, '''listeners don't work on so-called "tied" properties''' when the node value isn't set via property methods. (You can spot such tied properties by Ctrl-clicking the "." entry in the property browser: they are marked with a "T".) Most of the FDM properties are "tied".

Examples of properties where setlistener ''won't'' work:

* /position/elevation-ft
* /ai/models/aircraft/orientation/heading-deg
* Any property node created as an alias
* Lots of others

Before working to create a listener, always check whether a listener will work with that property node by control-clicking the "." in property browser to put it into verbose mode, and then checking whether the property node for which you want to set up a listener is marked with a "T" or not.

If you can't set a listener for a particular property, the alternative is to use settimer to set up a timer loop that checks the property value regularly.

Listeners are most efficient for properties that change only occasionally. No code is called at all during frames where the listener function is not called. If the property value changes every frame, setting up a settimer loop with time=0 will execute every frame, just the same as setlistener would, and the settimer loop is more efficient than setting a listener. This is one reason the fact the setlistener doesn't work on certain tied and FDM properties is not a great loss. See the section on timer loops below.

=== <tt>setlistener()</tt> ===

Syntax:

var listener_id = setlistener(<property>, <function> [, <startup=0> [, <runtime=1>]]);

The first argument is a property node object (<tt>props.Node()</tt> hash) or a property path. Because the node hash depends on the props.nas module being loaded, <tt>setlistener()</tt> calls need to be deferred when used in an $FG_ROOT/Nasal/*.nas file, usually by calling them in a <tt>settimer(func {}, 0)</tt> construction. To avoid that, one can use the raw <tt>_setlistener()</tt> function directly, for which <tt>setlistener()</tt> is a wrapper. The raw function does only accept node paths (e.g. "/sim/menubar/visibility"), but not props.Node() objects.

The second argument is a function object (not a function call!). The <tt>func</tt> keyword turns code into a function object.

The third argument is optional. If it is non-null, then it causes the listener to be called initially. This is useful to let the callback function pick up the node value at startup.

The fourth argument is optional, and defaults to 1. This means that the callback function will be executed whenever the property is written to, independent of the value.

If the argument is set to 0, then the function will only get triggered if a value other than the current value is written to the node. This is important for cases where a property is written to once per frame, no matter if the value changed or not. YASim, for example, does that for /gear/gear/wow or /gear/launchbar/state.
So, this should be used for properties that are written to in every frame, although the written value is mostly the same. If the argument is 2, then also write access to children will get reported, as well as the creation and removal of children nodes.

For both optional flags 0 means less calls, and 1 means more calls. The first is for startup behavior, and the second for runtime behavior.

Here's a real-life example:

setlistener("/gear/launchbar/state", func {
if (cmdarg().getValue() == "Engaged")
setprop("/sim/messages/copilot", "Engaged!");
}, 1, 0);

YASim writes once per frame the string "Disengaged" to property /gear/launchbar/state. When an aircraft on deck of the aircraft carrier locks into the catapult, this changes to "Engaged", which is then written again in every frame, until the aircraft leaves the catapult. Because the locking in is a bit difficult -- one has to target the sensitive area quite exactly --, it was desirable to get some quick feedback: a screen message that's also spoken by the Festival speech synthesis. With the args 1 and 0, this is done initially (for the unlikely case that we are locked in from the beginning), and then only when the node changes from an arbitrary value to "Engaged".

<tt>setlistener()</tt> returns a unique listener id on success, and <tt>nil</tt> on error. The id is nothing else than a counter that is 0 for the first Nasal listener, 1 for the second etc. You need this id number to remove the listener. Most listeners are never removed, so that one doesn't assign the return value, but simply drop it.

Listener callback functions can access up to four values via regular function arguments, the first two of which are property nodes in the form of a <tt>props.Node()</tt> object hash.

If you have set a callback function named ''myCallbackFunc'' via <tt>setlistener</tt> (''setlistener(myNode, myCallbackFunc)''), you can use this syntax in the callback function:

myCallbackFunc ([<changed_node> [, <listened_to_node> [, <operation> [, <is_child_event>]]]])

=== <tt>removelistener()</tt> ===

Syntax:

var num_listeners = removelistener(<listener id>);

<tt>removelistener()</tt> takes one argument: the unique listener id that a <tt>setlistener()</tt> call returned. It returns the number of remaining active Nasal listeners on success, <tt>nil</tt> on error, or -1 if a listener function applies <tt>removelistener()</tt> to itself. The fact that a listener can remove itself, can be used to implement a one-shot listener function:

var L = setlistener("/some/property", func {
print("I can only be triggered once.");
removelistener(L);
});

=== Listener Examples ===

The following example attaches an anonymous callback function to a "signal". The function will be executed when FlightGear is closed.

setlistener("/sim/signals/exit", func { print("bye!") });

Instead of an anonymous function, a named function can be used as well:

var say_bye = func { print("bye") }
setlistener("/sim/signals/exit", say_bye);

Callback functions can, optionally, access up to four parameters which are handed over via regular function arguments. Many times none of these parameters is used at all, as in the above example.

Most often, only the first parameter is used--which gives the node of the changed value.

The following code attaches the monitor_course() function to a gps property, using the argument ''course'' to get the node with the changed value.

var monitor_course = func(course) {
print("Monitored course set to ", course.getValue());
}
var i = setlistener("instrumentation/gps/wp/leg-course-deviation-deg", monitor_course);

# here the listener is active

removelistener(i); # remove that listener again

Here is code that accesses two arguments--the changed node and the listened-to node (these may be different when monitoring all children of a certain node)--and also shows how to monitor changes to a node including changes to children:

var monitor_course = func(course, flightinfo) {
print("One way to get the course setting: ", flightinfo.leg-course-deviation-deg.getValue());
print("Another way to get the same setting ", course.getValue());
}
var i = setlistener("instrumentation/gps/wp", monitor_course, 0, 2);

The function object doesn't need to be a separate, external function -- it can also be an anonymous function made directly in the <tt>setlistener()</tt> call:

setlistener("/sim/signals/exit", func { print("bye") }); # say "bye" on exit

Beware, however, that the contents of a function defined within the <tt>setlistener</tt> call are not evaluated until the call is actually made. If, for instance, local variables change before the setlistener call happens, the call will reflect the current value of those variables ''at the time the callback function is called'', not the value ''at the time the listener was set''.

For example, with this loop, the function will always return the value 10--even if mynode[1], mynode[2], mynode[3] or any of the others is the one that changed. It is because the contents of the setlistener are evaluated after the loop has completed running and at that point, i=10:

var output = func(number) {
print("mynode", number, " has changed!"); #This won't work!
}
for(i=1; i <= 10; i = i+1) {
var i = setlistener("mynode["~i~"]", func{ output (i); });
}

You can also access the four available function properties (or just one, two, or three of them as you need) in your anonymous function. Here is an example that accesses the first value:

for(i=1; i <= 10; i = i+1) {
var i = setlistener("mynode["~i~"]", func (changedNode) { print (changedNode.getPath() ~ " : " ~ changedNode.getValue()); });
}

Attaching a function to a node that is specified as <tt>props.Node()</tt> hash:

var node = props.globals.getNode("/sim/signals/click", 1);
setlistener(node, func { gui.popupTip("don't click here!") });

Sometimes it is desirable to call the listener function initially, so that it can pick up the node value. In the following example a listener watches the view number, and turns the HUD on in cockpit view, and off in all other views. It doesn't only do that on writing to "view-number", but also once when the listener gets attached, thanks to the third argument "1":

setlistener("/sim/current-view/view-number", func(n) {
setprop("/sim/hud/visibility[0]", n.getValue() == 0);
}, 1);

There's no limit for listeners on a node. Several functions can get attached to one node, just as one function can get attached to several nodes. Listeners may write to the node they are listening to. This will not make the listener call itself causing an endless recursion.

=== Signals ===

In addition to "normal" nodes, there are "signal" nodes that were created solely for the purpose of having listeners attached:

<tt>/sim/signals/exit</tt> ... set to "true" on quitting FlightGear

<tt>/sim/signals/reinit</tt> ... set to "true" right before resetting FlightGear (Shift-Esc), and to "false" afterwards

<tt>/sim/signals/click</tt> ... set to "true" after a mouse click at the terrain. Hint that the geo coords for the click spot were updated and can be retrieved from /sim/input/click/{longitude-deg,latitude-deg,elevation-ft,elevation-m}

<tt>/sim/signals/screenshot</tt> ... set to "true" right before the screenshot is taken, and set to "false" after it. Can be used to hide and reveal dialogs etc.

<tt>/sim/signals/nasal-dir-initialized</tt> ... set to "true" after all Nasal "library" files in $FG_ROOT/Nasal/ were loaded and executed. It is only set once and can only be used to trigger listener functions that were defined in one of the Nasal files in that directory. After that signal was set
Nasal starts loading and executing aircraft Nasal files, and only later are <tt>settimer()</tt> functions
called and the next signal is set:

<tt>/sim/signals/fdm-initialized</tt> ... set to "true" when then FDM has just finished its initialization

<tt>/sim/signals/reinit-gui</tt> ... set to "true" when the GUI has just been reset (e.g. via Help menu). This
is used by the gui.Dialog class to reload Nasal-loaded XML dialogs.

<tt>/sim/signals/frame</tt> ... triggered at the beginning of each iteration of the main loop (a.k.a. "frame"). This is meant for debugging purposes. Normally, one would just use a settimer() with interval 0 for the same effect. The difference is that the signal is guaranteed to be raised at a defined moment, while the timer call may change when subsystems are re-ordered.

== FlightGear extension functions ==

=== <tt>cmdarg()</tt> ===
cmdarg() is a mechanism to pass arguments to a nasal script (wrapped in properties) instead of "normal" function parameters. Note that cmdarg() should be primarily used in Nasal code embedded in XML files and should be considered depreciated otherwise (see [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg18361.html] and [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg18361.html]).

cmdarg() will keep working in (joystick) XML-'''bindings''' and on the top-level of embedded Nasal scripts (i.e. dialog and animation XML files).

As such, the cmdarg() function is primarily used for listener callbacks declared in XML markup, cmdarg() returns the listened-to property as props.Node object, so you can use it with all its methods (see $FG_ROOT/Nasal/props.nas) for example:

print(cmdarg().getPath(), " has been changed to ", cmdarg().getValue())

The cmdarg() function avoids that you have to type the exact same path twice (once here and once in the setlistener() command) and it makes clear that this is the listened to property. Also, you can use all the nice props.Node methods on cmdarg() directly:

setlistener("/gear/launchbar/state", func {
if (cmdarg().getValue() == "Engaged")
setprop("/sim/messages/copilot", "Engaged!");
}, 1, 0);

Use of cmdarg() outside of XML-bindings won't cause an error, but (still) return the last cmdarg() property. This just won't be the listened-to property anymore, but whatever the last legitimate cmdarg() user set. Most of the time it will be the property root of a joystick binding.

Don't make any assumptions and use cmdarg() only in one of these cases:

* binding: returns root of this binding's property branch. Needed for accessing an axis' value: cmdarg().getNode("setting").getValue()

* dialog xml files: returns root of that file's property branch in memory. This can be used to let embedded Nasal change the dialog (e.g. clear and build lists) before the final layout is decided

* animation xml files: returns root of this model's place in /ai/models/ when used as AI/MP model. Examples: /ai/models/multiplayer[3], /ai/models/tanker[1], etc. [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg14164.html]

* AI aircraft XML files

* remotely invoking Nasal code by setting properties using the built-in telnet daemon (RPC) [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg00150.html [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg00336.html].

'''In all cases, the cmdarg() call must not be delayed until later using settimer() or setlistener(). Because later it'll again return some unrelated property!
'''

=== <tt>fgcommand()</tt> ===

Runs an internal "fgcommand", see $FG_ROOT/Docs/README.commands for a list of available commands: http://gitorious.org/fg/fgdata/blobs/master/Docs/README.commands

=== <tt>print()</tt> ===
Concatenates an arbitrary number of arguments to one string, appends a new-line, and prints it to the terminal. Returns the number of printed characters.

print("Just", " a ", "test");

=== <tt>getprop()</tt> ===
Returns the node value for a given path, or <tt>nil</tt> if the node doesn't exist or hasn't been initialized yet.

getprop(<path>);

Example:

print("The frame rate is ", getprop("/sim/frame-rate"), " FPS");

=== <tt>setprop()</tt> ===
Sets a property value for a given node path string. Always returns nil.

setprop(<path> [, <path>, [...]], <value>);

All arguments but the last are concatenated to a path string, with a slash (/) inserted between each element. The last value is written to the respective node. If the node isn't writable, then an error message is printed to the console.

Note: <tt>setprop()</tt> concatenates a list of input arguments by means of inserting a "/" in between. That is nice for properties, as this slash is part of the tree. However, when one wants to make use of indices, like [0], one has to concatenate by hand (using "~") ''inside'' one part of the string argument list. An example is:

var i = 4;
setprop("instrumentation","cdu","page["~i~"]","title","MENU");

This results in instrumentation/cdu/page[4]/title = 'MENU' (string)

Examples:

setprop("/sim/current-view/view-number", 2);
setprop("/controls", "engines/engine[0]", "reverser", 1);

'''Erasing a property from the property tree''': a property that has been created, for example through <tt>setprop()</tt> can be erased via

props.globals.getNode("foo/bar").remove(); # take out the complete node
props.globals.getNode("/foo").removeChild("bar"); # take out a certain child node

=== <tt>settimer()</tt> ===
Runs a function after a given simulation time (default) or real time in seconds.

settimer(<function>, <time> [, <realtime=0>]);

The first object is a function object (ie, "func { ... }"). Note that this is different from a function call (ie, "func ( ... )"). If you don't understand what this means, just remember to always enclose the first argument in any call to settimer with the word "func" and braces "{ }", and it will always work. For instance, if you want print the words "My result" in five seconds, use this code:

settimer ( func { print ( "My result"); }, 5);

Inside the braces of the func object you can put any valid Nasal code, including a function call. In fact, if you want to call a function with certain values as arguments, the way to do it is to turn it into a function object by enclosing it with a func{}, for example:

myarg1="My favorite string";
myarg2=432;
settimer ( func { myfunction ( myarg1, myarg2); }, 25);

The third argument is optional and defaults to 0, which lets the time argument be interpreted as "seconds simulation time". In this case the timer doesn't run when FlightGear is paused. For user interaction purposes (measuring key press time, displaying popups, etc.) one usually prefers real time.

# simulation time example
var copilot_annoyed = func { setprop("/sim/messages/copilot", "Stop it! Immediately!") }
settimer(copilot_annoyed, 10);

# real time example
var popdown = func ( tipArg ) {
fgcommand("dialog-close", tipArg);
}

var selfStatusPopupTip = func (label, delay = 10, override = nil) {
var tmpl = props.Node.new({
name : "PopTipSelf", modal : 0, layout : "hbox",
y: 140,
text : { label : label, padding : 6 }
});
if (override != nil) tmpl.setValues(override);

popdown(tipArgSelf);
fgcommand("dialog-new", tmpl);
fgcommand("dialog-show", tipArgSelf);

currTimerSelf += 1;
var thisTimerSelf = currTimerSelf;

# Final argument 1 is a flag to use "real" time, not simulated time
settimer(func { if(currTimerSelf == thisTimerSelf) { popdown(tipArgSelf) } }, delay, 1);
}

[[Nasal_scripting_language#settimer_loops|More information about best practices for using the settimer function to create loops in Nasal is elsewhere on this page.]]

=== <tt>systime()</tt> ===
Returns epoch time (time since 1972/01/01 00:00) in seconds as a floating point number with high resolution. This is useful for benchmarking purposes.

#benchmarking example:
var start = systime();
how_fast_am_I(123);
var end = systime();
print("took ", end - start, " seconds");

=== <tt>carttogeod()</tt> ===
Converts cartesian coordinates x/y/z to geodetic coordinates lat/lon/alt, which are returned as a vector. Units are degree and meter.

var geod = carttogeod(-2737504, -4264101, 3862172);
print("lat=", geod[0], " lon=", geod[1], " alt=", geod[2]);

# outputs
lat=37.49999782141546 lon=-122.6999914632327 alt=998.6042055172776

=== <tt>geodtocart()</tt> ===
Converts geodetic coordinates lat/lon/alt to cartesian coordinates x/y/z. Units are degree and meter.

var cart = geodtocart(37.5, -122.7, 1000); # lat/lon/alt(m)
print("x=", cart[0], " y=", cart[1], " z=", cart[2]);

# outputs
x=-2737504.667684828 y=-4264101.900993474 z=3862172.834656495

=== <tt>geodinfo()</tt> ===
Returns information about geodetic coordinates. Takes two arguments: lat, lon (in degree) and returns a vector with two entries, or nil if no information could be obtained because the terrain tile wasn't loaded. The first entry is the elevation (in meters) for the given point, and the second is a hash with information about the assigned material, or nil if there was no material information available, because there is, for instance, an untextured building at that spot or the scenery tile is not loaded.

var lat = getprop("/position/latitude-deg");
var lon = getprop("/position/longitude-deg");
var info = geodinfo(lat, lon);

if (info != nil) {
print("the terrain under the aircraft is at elevation ", info[0], " m");
if (info[1] != nil)
print("and it is ", info[1].solid ? "solid ground" : "covered by water");
}

A full data set looks like this:

debug.dump(geodinfo(lat, lon));

# outputs
[ 106.9892101062052, { light_coverage : 0, bumpiness : 0.5999999999999999, load_resistance : 1e+30,
solid : 0, names : [ "Lake", "Pond", "Reservoir", "Stream", "Canal" ], friction_factor : 1,
rolling_friction : 1.5 } ]

Note that geodinfo is a *very* CPU intensive operation, particularly in FG 2.4.0 and earlier, so use sparingly ([http://flightgear.org/forums/viewtopic.php?f=4&p=135044#p135044 discussion here]).

=== <tt>parsexml()</tt> ===

This function is an interface to the built-in [http://expat.sourceforge.net/ Expat XML parser]. It takes up to five arguments. The first is a mandatory absolute path to an XML file, the remaining four are optional callback functions, each of which can be nil (which is also the default value).

var ret = parsexml(<path> [, <start-elem> [, <end-elem> [, <data> [, <pi> ]]]]);

<start-elem> ... called for every starting tag with two arguments: the tag name, and an attribute hash
<end-elem> ... called for every ending tag with one argument: the tag name
<data> ... called for every piece of data with one argument: the data string
<pi> ... called for every "processing information" with two args: target and data string

<ret> ... the return value is nil on error, and the <path> otherwise

Example:

var start = func(name, attr) {
print("starting tag ", name);
foreach (var a; keys(attr))
print("\twith attribute ", a, "=", attr[a]);
}
var end = func(name) { print("ending tag ", name) }
var data = func(data) { print("data=", data) }
var pi = func(target, data) { print("processing instruction: target=", target, " data=", data) }
parsexml("/tmp/foo.xml", start, end, data, pi);

=== airportinfo() ===
Function for retrieval of airport/runway information.
Usage:

var apt = airportinfo("KHAF"); # get info about KHAF
var apt = airportinfo(lat, lon); # get info about apt closest to lat/lon
var apt = airportinfo(); # get info about apt closest to aircraft

The command debug.dump(airportinfo("KHAF")) outputs this:

{ lon : -122.4962626410256, lat : 37.51343502564102, has_metar : 0,
runways : { 12 : { stopway2 : 0, threshold1 : 232.5624,
lon : -122.5010889999999, lat : 37.513831, stopway1 : 0, width : 45.72,
threshold2 : 232.5624, heading : 138.1199999999999, length : 1523.0856 } },
elevation : 20.42159999999999, id : "KHAF", name : "Half Moon Bay" }

That is: a hash with elements lat/lon/elev/id/name/has_metar for the
airport, and a hash with runways, each of which consists of lat/lon/
/length/width/heading/threshold[12]/stopway[12]. Only one side of each
runway is listed -- the other can easily be deduced.

==Built-in functions==

===sort(vector, function)===
Creates a new vector containing the elements in the input vector sorted in ascending order according to the rule given by function, which takes two arguments (elements of the input vector) and should return less than zero, zero, or greater than zero if the first argument is, respectively, less than, equal to, or greater than the second argument. Despite being implemented with ANSI C qsort(), the sort is stable; "equal" elements in the output vector will appear in the same relative order as they do in the input.

Because you can define the sort function, sort allows you to create a list of keys sorting a hash by any criterion--by key, value, or (if, for instance the hash values are hashes themselves) any subvalue.

vec = [100,24,45];
sortvec = sort (vec, func (a,b) cmp (a,b));
debug.dump (sortvec); #output is [24,45,100]

Here is an example of how to output the contents of a hash in sorted order. Note that the function does not actually sort the hash but returns a list of the hash keys in sorted order.

var airport = {
"LOXZ": "Zeltweg",
"LOWI": "Innsbruck",
"LOXL": "Linz Hoersching", # the last comma is optional
};

var sortedkeys= sort (keys(airport), func (a,b) cmp (airport[a], airport[b]));

foreach (var i; sortedkeys)
print (i, ": ", airport[i]);

The output is:

LOWI: Innsbruck
LOXL: Linz Hoersching
LOXZ: Zeltweg

If the hash values are themselves hashes, sorting by any of the subvalues is possible. For example:

var airport = {
"LOXZ": {city: "Zeltweg", altitude_m: 1300 },
"LOWI": {city: "Innsbruck", altitude_m: 2312 },
"LOXL": {city: "Linz Hoersching", altitude_m: 1932 },
};

#return a list of the hash keys sorted by altitude_m
var sortedkeys= sort (keys(airport), func (a,b) airport[a].altitude_m - airport[b].altitude_m);

foreach (var i; sortedkeys)
print (i, ": ", airport[i].city, ", ", airport[i].altitude_m);

Note that ''sort'' will return errors, and in FG 2.4.0 may even stop working, if the sort function you provide returns errors. A common cause of this is if your sort vector contains both string and numeric values. The cmp function will return an error for numeric values, and arithmetic operations you may use to sort numeric values will return errors if performed on a string. The error in these cases is typically "function/method call on uncallable object".

=== Other useful built-in functions ===

Other basic built-in Nasal functions such as append, setsize, subvec, typeof, contains, delete, int, num, keys, pop, size, streq, cmp, substr, sprintf, find, split, rand, call, die, bind, math.sin, math.pi, math.exp, math.ln math.e, io.read, io.write, regex.exec, and others of that sort, [http://www.plausible.org/nasal/lib.html are detailed in this external document].

=== Useful functions in the Nasal directory ===
Other functions are available in the Nasal files found in the Nasal directory of a FlightGear install. Simply open those Nasal files in text editor to see what is inside. Reference those functions by putting the filename in front of the function, method, variable, or object you wish to use. For instance, to use the method Coord.new() in the file geo.nas, you simply write:

geo.Coord.new()

=== Distance calculations ===

To calculate the distance between two points (in two different ways):
# mylat1, mylong1, mylat2, mylong2 are lat & long in degrees
# myalt1 & myalt2 are altitude in meters

var GeoCoord1 = geo.Coord.new();
GeoCoord1.set_latlon(mylat1, mylong1,myalt1);

var GeoCoord2 = geo.Coord.new();
GeoCoord2.set_latlon(mylat2, mylong2, myalt2);

var directDistance = GeoCoord1.direct_distance_to(GeoCoord2);
var surfaceDistance = GeoCoord1.distance_to(GeoCoord2);

The results are distances in meters.

* distance_to - returns distance in meters along Earth curvature, ignoring altitudes; useful for map distance
* direct_distance_to - returns distance in meters direct; considers altitude, but cuts through Earth surface

=== Other useful geographical functions ===
Other useful geographical functions are found in geo.nas (in the FlightGear/data/Nasal directory of a FlightGear installation). geo.nas also includes documentation/explanation of the functions available.

==Developing and debugging in Nasal==
===Developing Nasal code===
Because code in the Nasal directory is parsed only at Flightgear startup, testing and debugging Nasal code can by slow and difficult.

Flightgear provides a couple of ways to work around this issue:

====Nasal Console====

The Nasal Console is available in Flightgear's menu (Debug/Nasal Console). Selecting this menu opens a Nasal Console dialog.

This dialog has several tabs, of which each can hold separate Nasal code snippets, all of which are saved on exit
and reloaded next time. This is useful for little tests, or for executing code for which writing a key binding is just too much
work, such as "props.dump(props.globals)".

If you want to add more tabs (radio buttons in the Nasal Console dialog) to hold more code samples, just add more <code> nodes to autosave.xml.

====Loading/reloading Nasal code without re-starting Flightgear====
A common problem in testing and debugging Nasal programs is that each testing step requires stopping and re-starting Flightgear, a slow process.

Below is described a technique for loading and executing a Nasal file while Flightgear is running. Flightgear will parse the file, display any errors in the Flightgear console window, and then execute the code as usual.

Using this technique, you can start Flightgear, load the Nasal code you want to test observe any errors or test functionality as you wish, make changes to the Nasal file, reload it to observe parse errors or change in functionality, and so on to repeatedly and quickly run through the change/load/parse/test cycle without needing to re-start Flightgear each time.

The key to this technique is the function io.load_nasal(), which loads a nasal file into a nasal namespace.

Step-by-step instructions showing how to use this technique to load, parse, and test a Nasal file while Flightgear is running:

=====Create the Nasal file to test=====
Create a text file named $FG_ROOT/foo/test.nas with this text:

print("hi!");
var msg="My message.";
var hello = func { print("I'm the test.hello() function") }

Notes: You can create the file in any directory you wish, as long as Nasal can read the directory--but the file IOrules in the Nasal directory restricts which directories Nasal may read and write from.

You can give the file any name and extension you wish, though it is generally most convenient to use the .nas extension with Nasal files.

=====Load the file and test=====
Start Flightgear. You can import the file above into Flightgear by typing the following into the Nasal Console dialog and executing the code:

io.load_nasal(getprop("/sim/fg-root") ~ "/foo/test.nas", "example");

getprop("/sim/fg-root") gets the root directory of the FlightGear installation, ~ "/foo/test.nas" appends the directory and filename you created. The final variable "example" tells the namespace to load for the Nasal file.

You'll see the message "hi!" on the terminal, and have function "example.hello()" immediately available. You can, for instance, type "example.hello();" into one of the Nasal console windows and press "Execute" to see the results; similarly you could execute "print (example.msg);".

If you find errors or want to make changes, simply make them in your text editor, save the file, and execute the io.load_nasal() command again in the Nasal Console to re-load the file with changes.

It's worth noting that Nasal code embedded in XML GUI dialog files can be reloaded by using the "debug" menu ("reload GUI").

You may also want to check out the remarks on [[Nasal_scripting_language#Memory_management|Memory management]].

==== Managing timers and listeners ====

Note: If your Nasal program sets listeners, timer loops, and so on, they will remain set even when the code is reloaded, and reloading the code will set additional listeners and timer loops.

This can lead to extremely slow framerates and unexpected behavior. For timers you can avoid this problem by using the loopid method (described above); for listeners you can create a function to destroy all timers your Nasal program creates, and call that function before reloading the program. (And cleaning up timer loops and listeners is a best practice for creating Nasal programs in Flightgear regardless.)

The same problem may occur while resetting or re-initializing parts of FlightGear if your code isn't prepared for this. And obviously this applies in particular also to any worker threads you may have started, too!

For complex Nasal scripts with many timers and listeners, it is therefore generally a very good idea to implement special callbacks so that your scripts can respond to the most important simulator "signals", this can be achieved by registering script-specific listeners to signals like "reinit" or "freeze" (pause): the corresponding callbacks can then suspend or re-initialize the Nasal code by suspending listeners and timers. Following this practice helps ensure that your code will behave properly even during simulator resets.

In other words, it makes sense to provide a separate high-level controller routine to look for important simulator events and then pause or re-initialize your main Nasal code as required.

If you are using [[Nasal_scripting_language#System-wide_Nasal_code|System-wide Nasal modules]], you should register listeners to properly re-initialize and clean up your Nasal code.

In its simplest form, this could look like this:

var cleanup = func {}
setlistener("/sim/signals/reinit", cleanup);

This will invoke your "cleanup" function, whenever the "reinit" signal is set by the FlighGear core.

Obviously, you now need to populare your cleanup function with some code, too.

One of the easiest ways to do this, is removing all listeners/timers manually here, i.e. by adding calls to removelistener():

var cleanup = func {
removelistener(id);
removelistener(id);
removelistener(id);
}

This would ensure that the corresponding listeners would be removed once the signal is triggered.

On the other hand, you could just as well use a vector of listener IDs here, and then use a Nasal foreach loop:

var cleanup = func(id_list) {
foreach(var id; id_list)
removelistener(id);
}

Obviously, this would require that you maintain a list of active listeners, too - so that you can actually pass a list of IDs to the cleanup function.

This is one of those things that can be easily done in Nasal, too - just by introducing a little helper wrapper:

var id_list=[];
var store_listener = func(id) append(id_list,id);

The only thing required here, would be replacing/wrapping the conventional "setlistener" call with calls to your helper:

store_listener( setlistener("/sim/foo") );
store_listener( setlistener("/foo/bar") );

If you were to do this consistently across all your Nasal code, you'd end up with a high level way to manage all your registered listeners centrally.

Now, you'll probably have noticed that it would make sense to consider wrapping all these helpers and variables inside an enclosing helper class, this can be accomplished in Nasal using a hash. This would enable you to to implement everything neatly organized in an object and use RAII-like patterns to manage Nasal resources like timers, listeners and even threads.

===Debugging===
The file debug.nas, included in the Nasal directory of the Flightgear distribution, has several functions useful for debugging Nasal code. These functions are available to any Nasal program or code executed by Flightgear.

Aside from those listed below, several other useful debugging functions are found in debug.nas; see the debug.nas file for the list of functions and explanation.

Note that the debug module makes extensive use of ANSI terminal color codes. These create colored output on Linux/Unix systems but on other systems they may add numerous visible control codes. To turn off the color codes, go to the internal property tree and set

/sim/startup/terminal-ansi-colors=0

Or within a Nasal program:

setprop ("/sim/startup/terminal-ansi-colors",0);

====debug.dump====
debug.dump([<variable>]) ... dumps full contents of variable or of local variables if none given

The function debug.dump() dumps the contents of the given variable to the console. On Unix/Linux this is done with some syntax coloring. For example, these lines

var as = props.globals.getNode("/velocities/airspeed-kt", 1);
debug.dump(as);

would output

</velocities/airspeed-kt=1.021376474393101 (DOUBLE; T)>

The "T" means that it's a "tied" property. The same letters are used here as in the property-browser. The angle brackets seem superfluous, but are useful because debug.dump() also outputs compound data types, such as vectors and hashes. For example:

var as = props.globals.getNode("/velocities/airspeed-kt", 1);
var ac = props.globals.getNode("/sim/aircraft", 1);
var nodes = [as, ac];
var hash = { airspeed_node: as, aircraft_name: ac, all_nodes: nodes };
debug.dump(hash);

yields:

{ all_nodes : [ </velocities/airspeed-kt=1.021376474393101 (DOUBLE; T)>,
</sim/aircraft="bo105" (STRING)> ], airspeed_node : </velocities/airspe
ed-kt=1.021376474393101 (DOUBLE; T)>, aircraft_name : </sim/aircraft="bo
105" (STRING)> }

====debug.backtrace====
debug.backtrace([<comment:string>]} ... writes backtrace with local variables
debug.bt ... abbreviation for debug.backtrace

The function debug.backtrace() outputs all local variables of the current function and all parent functions.

====debug.benchmark====
debug.benchmark(<label:string>, <func> [, <repeat:int>])
... runs function <repeat> times (default: 1) and prints execution time in seconds,prefixed with <label>.

This is extremely useful for benchmarking pieces of code to determin
====debug.exit====
debug.exit() ... exits fgfs

== Related content ==
{{Forum|30|Nasal}}
* [[:Category:Nasal]]

=== External links ===
* http://www.plausible.org/nasal

[[Category:Nasal]]

Howto:Carrier

2011-12-18T07:27:49Z

Moksha: /* From commandline */ typo

Over the years, [[FlightGear]] has been equipped with a vast amount of [[aircraft carrier]]s that allow pilots to simulate the entire range of carrier operations, from catapult takeoffs, to "controlled crashes".

==Features==
[[File:Carrier3.jpg|thumb|300px|The Nimitz carrier in the San Fransisco bay]]

* Start FG with your chosen aircraft placed on the aircraft carrier "Nimitz" or "Eisenhower"
* Engage the launchbar in the steam catapult
* Have the carrier set course into the prevailing wind direction and attempt to get wind speed over the deck at a suitable value for launch
* Launch from the deck when ready
* Set the TACAN receiver in the aircraft to Nimitz's channel (029Y) and have the heading and range to the carrier displayed on the cockpit instruments
* Land on the deck and be halted by the arrestor cables
* Taxi onto the deck elevators, operate them and park on the hangar deck (0.9.10 and later)

== Start at a carrier ==
Note that several FlightGear aircraft are carrier capable, but the [[Hawker Seahawk|Seahawk]] is possibly the easiest to fly to begin with. You can start FlightGear with the command line or a GUI.

=== From commandline ===
To position your [[aircraft]] on the carrier at startup, use the following [[Command Line Parameters|command line options]] beside your normal options ([[$FG_ROOT|fg-root]] etc.). Note the upper-case "N" in Nimitz and the fact that the scenario comes in front of carrier! You can copy-paste this (the slash will make it look like one line):
--ai-scenario=nimitz_demo \
--carrier=Nimitz \
--aircraft=seahawk \

Please note the uppercase N in <tt>--carrier=Nimitz</tt>.

The following (optional) start positions are available:
--parkpos=cat-1
--parkpos=cat-2
--parkpos=cat-3
--parkpos=cat-4
--parkpos=park-1

=== Mac OS X launcher ===
If you are using the OSX launcher to run FlightGear, you should find a text entry box in the gui that allows you to specify command line options, add the above mentioned commands there.

=== Windows launcher ===
As of FlightGear 1.0.0 there comes a special box for the carriers on the airport selection page of the wizard. Type <tt>Nimitz</tt> in the carrier box and select <tt>nimitz_demo</tt> in the scenario list on the next page.

== Takeoff ==
[[File:Carrier1.jpg|thumb|300px|The [[Hawker Seahawk|Seahawk]] aircraft ready for takeoff]]
Once FlightGear has started, you should ensure that the parking brakes are off, ease the plane a little way down the catapult pressing L to engage the launchbar (hold for several seconds until given "Engaged" feedback; this might be best done from an external view initially.) You should notice the aircraft being pulled into alignment with the catapult and see the strops appear and hold down the aircraft. This will only happen if your aircraft is close enough to the correct spot on the catapult; as a rough guide, for the default parking position the seahawk's nose should be rougly level with the deck observation bubble.

To get the carrier into as good a position as possible for launch, select the <tt>AI > Carrier Controls</tt> menu, then check the "Turn to launch course" box.

You should now notice the carrier begin to pick up speed and turn into the wind, and naturally the deck may tilt somewhat as it turns. You should wait for this maneuver to finish and the deck to return to level before moving on to the next stage.
[[Image:Carrier6.jpg|thumb|300px|'''1:''' The takeoff part of the carrier with the catapults
'''2:''' The land part of the carrier with the wires]]
Being engaged to the catapult, you should spool up the engines to full power, ensure the brakes are off and that all flight controls are in a suitable position for launch. When ready, press C to release the catapult. Your aircraft will be hurled forward off the deck, and you should be able to raise the undercarriage and climb slowly away, being careful to avoid stalling.

== Locating the carrier ==
Actually finding the carrier in a vast expanse of open water can be very difficult, especially if visibility is poor. To assist with this task, the carriers are equipped with [[TACAN]], which allows a suitably-equipped aircraft (Seahawk at present) to obtain a range and bearing to the carrier.

First, you must set the appropriate TACAN channel, 029Y in this case, in the radios dialogue (Ctrl-R or choose <tt>Equipment > Radio Settings</tt> from the menu). You should, if within range, notice the [[DME]] instrument show your distance from the carrier, and the [[ADF]] instrument (next to the DME in the seahawk) should indicate a bearing to the carrier. Turn to the indicated heading and you should see the DME dial indicate you're closing in on the carrier.

{|
! Carrier || Scenario || TACAN
|-
| Nimitz || nimitz_demo || 029Y
|-
| Eisenhower || nimitz_demo || 030Y
|-
| Clemenceau || clemenceau_demo || 026Y
|-
| Foch || foch_demo || 026X
|-
| Akagi || akagi || N/A
|}

== Landing ==
This is the most difficult part of the operation, as in real life. You might well find Andy Ross' [[A-4F Skyhawk Operations Manual]] useful here.

Basically, though, you should use the TACAN to locate the carrier, and line up with the rear of the deck. As this part of the deck is at an angle to the course of the vessel, you may need to correct your alignment often. Ensure that the aircraft is in the correct configuration for approach (the <tt>Help > Aircraft Help</tt> menu should contain useful data for your aircraft) and that the gear and the arrestor hook are down.

[[File:Carrier5.jpg|thumb|300px|The Fresnel Lens Optical landing System]]
As you approach you should see, on the left hand side of the deck, a set of brightly coloured lights - called the Fresnel Lens Optical landing System (FLOLS). This indicates your position on the landing glideslope. You will see a horizontal row of green lights, and when approximately on the glideslope, an orange light ( known in some circles as 'the meatball') approximately in line with the green lights. When approaching correctly, the meatball appears in line with the green lights. If you are high it is above, and when low it is below. If you are very low the meatball turns red. If you fly to keep the meatball aligned you should catch number 3 wire.

=== Touchdown ===
Carrier landings are often described as "controlled crashes" and you shouldn't waste your time attempting to flare and place the aircraft gently on the deck like you would with a conventional landing - ensuring that you catch the wires is the main thing.

Immediately your wheels touch the deck, you should open the throttles to full power, in case you have missed the wires and need to go around again; the wires will hold the aircraft if you have caught them, even at full power.

If you wish, you can then (with 0.9.10 and later) raise the elevators from the carrier menu, taxi onto one of the elevators, lower it (uncheck the box on the menu and don't worry, they are VERY slow...) and taxi off into the hangar.

Don't be discouraged if you don't succeed at first with carrier landings - it's not an easy maneouver to master. If after a little practice you find the Seahawk too easy, you could move on to the Seafire for more of a challenge!

== Related content ==
* [[Carrier over MP]] to find out how you could control the carrier and/or use the carrier over the multiplayer network.

[[de:Flugzeugträger]]

[[Category:Howto|Carrier]]

Aircraft

2011-12-15T08:08:18Z

Moksha: /* Spacecrafts */ improve sentence

This list is not updated to include all the official [[GNU General Public License|GPL licensed]] '''aircraft''' for [[FlightGear]], but gives a visual sampling of the different types of aircraft and genres of aircraft officially available. See [[Table of models]] for the comprehensive list.

The examples listed here are officially available from the FlightGear project, and can be downloaded at [http://flightgear.org/Downloads/aircraft-2.0.0/ FlightGear.org], with installation typically requiring an unzipping program, and manual [[Howto: Install aircraft|installation]] in the FlightGear aircraft directory. More aircraft are available in [[FlightGear hangars|non-official hangars]].

FlightGear aircraft features, quality, and compatibility vary significantly. Their development is dependent on the [[volunteer]]s who worked on them, with exception of some University and Government funded projects.

=== Light civilian aircraft ===
The Cessna 172 is the default aircraft in FGFS 2.0. These aircraft typically have 1-2 piston engines, props, and avionics geared towards those with civilian pilot licenses.
{{Gallery|
[[Aerostar 700]]|Aerostar_700.jpg|
[[B&F FK9 Mark 2]]|FK9MK2.jpg|
[[Cessna C172|Cessna 172P]] (1982)|Cessna_172P.jpg|
[[Piper Cherokee Warrior II|Piper Cherokee Warrior II (PA28-161)]]|Piper_Cherokee_Warrior_II.png|
[[Piper PA-24 Comanche|Piper Comanche (PA24-250)]]|Pa-24.jpg|
[[Piper J3 Cub]] (1946) |Piper_j3cub.jpg|
[[Piper PA34-200T Seneca II|Piper Seneca II (PA34-200T)]]|Piper_SenecaII.jpg|
[[Robin DR400]]|dr400.jpg|
[[Rallye-MS893E]]|Rallye-MS893.jpg
}}

=== Modern Airliners ===
These typically have 2-4 turbofan engines and some of the more complicated takeoff and landing procedures (such as multiple [[flaps]]). In addition, avionics in real life is geared towards those with professional pilots licenses and special certifications. However, the simplifications of FG make it much easier to fly in the simulation.

==== Narrowbody & Midsize ====
{{Gallery|
[[Airbus A320 Family]]|A320-family.jpg|
[[Beechcraft B1900D]]|Beechcraft B1900D.png|
[[Bombardier CRJ-200LR]]|Picture 11.png|
[[Bombardier CRJ700 series]]|CRJ700.jpg|
[[Boeing 757]]|757-2002.jpg|
[[Boeing 707]]|707.jpg|
[[Boeing 717]]|717-200.jpg|
[[Boeing 737-100]]|737-100.png|
[[Boeing 737-300]]|737-300.jpg|
[[Boeing 727-230]]|727-230.2.jpeg|
[[Concorde]]|Concorde.png
}}

==== Widebody & Jumbo Airliners ====
{{Gallery|
[[Airbus A340-600]]|Airbus.png|
[[Airbus A380]]|A380.jpg|
[[Boeing 777-200]]|777-200.jpg|
[[Boeing 767-300]]|Shadow.png|
[[Boeing 747-400]]|747-400.jpg|
[[Boeing 787]]|787.png|
[[Airbus A350]]|A350.png|
[[IL-96-400 Long Ranger(T)]]|1z5hr43.bmp
}}

=== Helicopters ===
{{Main article|Helicopter}}

Helicopters have fundamentally different controls than fixed wing aircraft (see ''[[Flying the Helicopter]]''). Modern helicopter typically feature 1-2 turbine engines, which power a main rotor with 2-6 blades.
{{Gallery|
[[AH-1 Cobra]]|Ah-1_vietnam_firebase.png|
[[Eurocopter Bo105|MBB Bo 105]]|FlightGearNL-9.jpg|
[[Eurocopter EC135|Eurocopter EC-135]]|Ec135.png|
[[CH-47 Chinook Helicopter|Boeing CH-47 Chinook]]|CH-47_Chinook.jpg|
[[Hughes OH-6 Cayuse]]|OH-6.png|
[[Sikorsky S58|Sikorsky S-58]]|S58.jpg
}}

=== Gliders, Sailplanes, & Ultralights ===
These typically have the simplest controls, with minimal avionics. Flying [[:Category:Gliders|gliders]] or sailplanes using [[Soaring|thermals]] can provide more complicated experience. Ultralights on the other hand are among the simplest aircraft in FG.
{{Gallery|
[[Airwave Xtreme 150]]|AirwaveXtreme150.jpg|
[[Dragonfly|Moyes Dragonfly]]|Dragonfly-towing.jpg|
[[Paraglider]]|Paraglider.jpg|
[[GDT Hornet (autogyro)]]|Hornet.jpg|
[[Schweizer 2-33]]|Sgs233.jpg|
[[ASW-20 sailplane|Schleicher ASW-20]]|Asw20.jpg|
[[Glaser-Dirks DG-300]]|DG-300.jpg|
[[Glaser-Dirks_DG-101G]]|DG-101G_001.jpg
}}

=== Warbirds ===
FlightGear includes a wide variety of vintage military aircraft. Complexity and realism is typically tied to the level of development work with a specific aircraft.
{{Gallery|
[[Bristol Beaufighter]]|Beaufighter.png|
[[Fokker Dr.I]]|Fokker_DrI.jpg|
[[P-51D Mustang]]|P51d-mustang.png|
[[A6M2 Zero‎]]|A6M2.gif|
[[Nakajima Ki-84‎]]|ki-84.jpg|
[[Focke-Wulf Fw 190]]|Fw190.jpg|
[[Sopwith Camel]]|Sopwith_Camel.png|
[[Supermarine Spitfire]]|Spitfire.jpg|
[[MiG-15]]|MiG-15bis-Exterior.jpg|
[[IAR 80]]|iar80-angry.jpg|
[[F4U Corsair]]|F4u-park.jpg|
[[Messerschmitt Bf 109]]|109-1.png
}}

=== Carrier-borne aircraft ===
FlightGear supports landing on and taking off from [[carriers]].

{{Gallery|
[[Grumman A-6E|Grumman A-6E Intruder]]|A-6E.jpg|
[[Blackburn Buccaneer]]|Buccaneer.jpg|
[[Grumman F-14 Tomcat]]|F-14.jpg|
[[Hawker Seahawk|Hawker Seahawk FGA6]]|Hawker_Seahawk.jpg
}}

=== Modern military aircraft ===
FlightGear has a wide variety of modern and retired military jets available, highlighted by features such as air-to-air refueling from the venerable KC-135 and the ability to simulate A-10 ordnance release.

{{Gallery|
[[Fairchild A-10]]|A-10.jpg|
[[Boeing B-52]]|B-52F.jpg|
[[Boeing E-3 Sentry]]|E-3B.jpg|
[[F-15C Eagle]]|F-15C.jpg|
[[British Aerospace Harrier]]|Harrier.jpg|
[[General Dynamics F-16]]|General_Dynamics_F16.jpg|
[[Cessna T-37]]|Cessna T-37.jpg|
[[Northrop T-38]]|Northrop_T-38.jpg|
[[North American OV-10A Bronco]]|OV-10A2.jpg|
[[Saab J 35Ã– Draken|Saab J35Ö Draken]]|Saab_J35.jpg|
[[HAL Tejas]]|LCA.jpeg|
[[Lockheed Martin F-22 Raptor]]|F-22.png
}}

=== Historical ===
Many obscure to famous older aircraft of varying quality are available.
{{Gallery|
[[Couzinet 70]]|Couzinet70.jpg|
[[De Havilland D.H. 91 Albatross]]|dh91.jpg|
[[Douglas DC-3]]|Douglas_DC3.jpg|
[[ComperSwift Comper]]|ComperSwift.jpg|
[[Lockheed 1049|Lockheed Constellation]]|Lockheed_1049.jpg|
[[Boeing 314]]|314.jpg|
[[de Havilland Canada DHC-3 Otter]]|DHC-3.jpg|
[[Wright Flyer (UIUC)]]|1903_Wright_Flyer.jpg|
[[Short Empire]]|Short_Empire.jpg
}}

=== Experimental & Unique ===
Experimental and special purpose aircraft.
{{Gallery|
[[BAC TSR-2 Prototype]]|BAC_TSR-2_Prototype.jpg|
[[Bell Boeing V22 Osprey|Bell V-22 Osprey]]|V22Osprey.jpg|
[[North American X-15]]|X15.jpg|
[[Northrop/McDonnell Douglas YF-23]]|YF-23.jpg
}}

=== Lighter than air aircraft (Available from version 1.9.0) ===
These aircraft take advantage of lighter than air gas to become buoyant. In addition to typical aircraft control methods such as elevator, rudder and engine throttle, ballast and control of gas volume and pressure become options.

{{Gallery|
[[Zeppelin NT]]|Zeppelin_NT.jpg|
[[ZF Navy free balloon]]|ZF_Navy_free_balloon.jpg|
[[Submarine Scout]]|Submarine_Scout.jpg|
[[Zeppelin LZ 121 Nordstern]]|Zeppelin_LZ_121_Nordstern.jpg
}}

=== Science Fiction ===
Alternative models provide a diversion of realistic simulation, but can also be useful for exploring scenery.
{{Gallery|
[[UFO from the 'White Project' of the UNESCO]]|UFO.jpg|
[[Bluebird]]|bluebird_hovercraft.jpg
}}

=== Spacecrafts ===
Things that show how small our planet Earth really is.
{{Gallery|
[[Vostok-1]]|Vostok-1-Thumbnail.jpg
}}



[[de:Flugzeuge]]
[[es:Avión]]
[[nl:Luchtvaartuigen]]
[[fr:Avions]]
[[pt:Avião]]

[[Category:List]]
[[Category:Aircraft]]

Building FlightGear - Linux

2011-12-11T02:41:53Z

Moksha: /* APT-GET List */ typo

{{Main article|Building Flightgear}}

This section describes how to build [[FlightGear]] on Linux system.

Compiling FlightGear is not a task for novice users. Thus, if you're a beginner (we all were once) on a platform which binaries are available for, we recommend postponing this task and just starting with the binary distribution to get you flying.

Or if you develop on Ubuntu or Debian, consider trying the script described in [[Scripted Compilation on Linux Debian/Ubuntu]].

== Requirements ==
Before you can compile FlightGear, you need to have the following installed on your computer:

'''C++ compiler'''

These are: c++, cpp, gcc, g++ found under the /usr/bin directory. You will also need to have the tools '''autoconf''' and '''automake1.9''' installed.

'''GIT'''

See [[FlightGear and Git]].

'''[[OpenGL]] support'''

More specifically, your system needs the support for hardware accelerated graphics. You can check for this by running the following in a [[command line]]:

glxinfo | grep direct

Note: To run the above command, you need to have the tool '''mesa-utils''' installed.

You should then see:

direct rendering: Yes

This means you are good to go as far as OpenGL support is concerned.

If you see:

direct rendering: No

Don't panic yet. This may just mean some required libraries for hardware accelerated graphic are missing. Go ahead and try installing plib 1.8.5 and its dependencies first. If you still get the above message, then you will need to do some googling and troubleshoot yourself.

== Dependencies ==
FlightGear is dependent on quite a few number of libraries. You do not need to compile all of them yourself, but you will at least need to have their development version installed. For example, the development version for package plib1.8.5 is plib1.8.5'''-dev'''.

The dependency is summarized in the following tree. Please note that each library has its own dependencies, and most of these are not shown here.

* FlightGear
** [http://kcat.strangesoft.net/openal.html OpenAL]
** SimGear
*** [http://plib.sourceforge.net/ PLIB]. Since March 2008, you will need version 1.8.5 - your distro probably supplies 1.8.4 still.
**** For versions pre March 2008: (Free)GLUT or SDL (We recommend the use of SDL over Free/GLUT, [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg16153.html however since March 2008, FreeGLUT as well as SDL are both considered depreciated, please only use --enable-osgviewer during configuration instead])
*** [[OpenSceneGraph]] (check link for compatible versions)
*** You also need the development files for several basic libraries to build the software, among them the following (the package names are for Debian and derivatives(?)):
**** libfreetype6-dev
**** libjpeg62-dev
**** libungif4-dev
**** libtiff4-dev
**** libpng12-dev
**** libxmu-dev
**** libxi-dev
**** zlib1g-dev
**** libglut3-dev

If you attack the above dependencies in the order listed below, you should be good:

1. Glut. Most distributions include glut packages, although you may have to hunt for them. Make sure you install both the glut and glut-devel packages, otherwise FlightGear may be able to compile but won't run correctly.

2. Zlib. Most distributions install the basic zlib libraries by default, but not the development portions. If you don't have zlib.h, you probably need to install the zlib-devel package for your distribution.

3. Plib - portability libraries and scene graph.

4. [[OpenSceneGraph]]

5. SimGear - Simulation support libraries. If you are building FlightGear from Git, you need the Git version of SimGear. If you have strange build errors, one of the first things to check is that you have an up-to-date version of SimGear built and installed.

==== APT-GET List ====
This is a list of all the apt-get commands I had to do while compiling FG, SG, and OSG on a mostly clean Ubuntu 64 system. It is a list of all the libraries you and your computer needs to compile FG, SG, OSG, and PLib. All you have to do is copy the full command, paste it in Terminal, enter your password, and it will download all the packages for you, and install them too. The full command is at the bottom, and I hope someone finds it useful :) sub-dependencies (dependencies of the dependencies) are not included as they are installed automatically by apt-get. If anyone sees something missing, please add it.

git - to get SG and FG<br />
subversion - to get OSG<br />
build-essential - to build (includes GCC, and other build tools)<br />
cmake - OSG Uses this<br />
cmake-curses-gui -- OSG Uses this<br />
libpng-dev - to enable FG to use PNG textures<br />
libfreetype6-dev - fonts<br />
libjpeg-dev<br />
libungif4-dev<br />
libtiff-dev<br />
libxmu-dev<br />
libxi-dev<br />
libglut3-dev<br />
libalut-dev - sound<br />
libboost-dev - makes coding for some developers easier<br />
''automake - needed by ./autogen.sh files''<br />
''autoconf - needed by ./autogen.sh files''<br />
libfltk1.1-dev - You will need this if you will be using FGRun<br />
-----------
<pre>
sudo apt-get install git subversion build-essential cmake cmake-curses-gui libpng-dev libfreetype6-dev
libjpeg-dev libungif4-dev libtiff-dev libxmu-dev libxi-dev libglut3-dev libalut-dev
libboost-dev automake autoconf libfltk1.1-dev
</pre>
-----------
Total size is about 230 MB, depending on what you already have from other applications.

This list might seem a bit short, but the sub-dependencies all add up :) The dependencies will be listed by apt-get when you use the command.
-----------
NOTE: On a Linux Mint 9 (Ubuntu 10.04) system this is the command I used:
<pre>
sudo apt-get install git-core subversion build-essential cmake cmake-curses-gui libpng-dev libfreetype6-dev libjpeg-dev libungif4-dev
libtiff-dev libxmu-dev libxi-dev libglut3-dev libalut-dev libboost-dev ''automake autoconf'' libfltk1.1-dev libplib-dev libopenscenegraph-dev
</pre>
libopenscenegraph-dev
You just need to copy that long line into a terminal and you should have all the packages you need to compile Flightgear and Simgear.

== Compiling ==
Assuming you are root, do:
cd /usr/local/src

'''Note:''' When tracking a fast changing software like FlightGear/Git it is highly advisable to install it in a separate directory. That way one can also easily build and reinstall without being root, which greatly reduces the risk of messing up one's system.
To install in a directory of your choice add the <tt>--prefix</tt> argument to configure. E.g. <tt>./configure --prefix=$HOME/FlightGear</tt>. I would recommend installing all of OSG, plib, SimGear and FlightGear with the same prefix.

=== Getting and compiling SimGear ===

'''Step 1:'''

Clone the SimGear git repository and set it up to track the 'next' branch.
git clone git://gitorious.org/fg/simgear.git

By default after cloning you should have a local next branch that tracks the master next branch. It can be updated it with git pull.

'''Step 2:'''

The source code will be downloaded into a directory called '''simgear'''.

Next, go into the directory and make preparations for the compilation:
cd simgear
''./autogen.sh''
./configure

'''Note''' that if you don't want to install simgear globally on the system but in a specific directory, you can do so by adding --prefix=/path/to/your/fgInstallation to the ./configure command

'''Step 3:'''

Compile and install SimGear by doing:
make; make install

''Note:'' with gcc 4.2 or later,on some platforms, you can get compiling errors about alc.h like:

'<anonymous>' has incomplete type
take a look at http://bugs.gentoo.org/166723

=== Getting and compiling FlightGear ===

'''Step 1:'''

Clone the FlightGear git repository and set it up to track the 'next' branch.
git clone git://gitorious.org/fg/flightgear.git

By default after cloning you should have a local next branch that tracks the master next branch. It can be updated it with git pull.

'''Step 2:'''

Next, go into the folder and make preparations for the compilation:
cd flightgear
''./autogen.sh''
./configure

Note that if you don't want to install simgear globally on the system but in a specific directory, you can do so by adding --prefix=/path/to/your/fgInstallation to the ./configure command.
If you didn't install OSG globally or in the same prefix as SimGear and FlightGear, you have to pass the OSG directory to the configure-command like this:
./configure --prefix=/path/to/fgInstallation --with-osg=/path/to/osg/installation --enable-osgviewer
In this case you have to tell your system where to find the OSG libraries before you can run flightgear:
export LD_LIBRARY_PATH=/path/to/osgInstallation/lib:$LD_LIBRARY_PATH

'''Step 3:'''

Now you can compile and install Flightgear by:
make; make install

'''Step 4:'''

Clone the data directory:
git clone git://gitorious.org/fg/fgdata.git

The data directory is large (almost 2.5GB) so it will take considerable time to download.
There mirror of fgdata that might be faster to download from:
git clone git://mapserver.flightgear.org/fgdata

The mirror is synchronized with the master so either will do.

And install it in (or as) /usr/local/share/FlightGear
mv fgdata /usr/local/share/flightgear

== Distro-specific instructions ==
=== Debian/Ubuntu ===
* You can use the [[Scripted Compilation on Linux Debian/Ubuntu]] script to have Flightgear compiled in one shot under both Ubuntu and Debian systems.
* Debian users who prefer to build it without script may look at [[Building Flightgear - Debian]].
=== Gentoo ===
* Gentoo users can also use overlays to build FlightGear without much hassle: [[Building Flightgear - Gentoo]].

== External links ==
=== Instructions ===
* [[MSYS]]
* [[MinGW/cross-compiler]]
* [[CodeBlocks IDE]]
* [[OpenSUSE 10.1 10.2]]
* [http://www.geoffmclane.com/fg/fgmsvc7.htm MSVC7 *.Net]
* [http://www.oflebbe.de/oflebbe/FlightGear/index.html MSVC8 aka Visual 2005]
* [http://macflightgear.sourceforge.net/home/documents/ Mac OS X]
== Important note for GIT users ==
As of latest development in GIT, only cmake is now required for building both SimGear and FlightGear. So if you build GIT (for what any reason) please don't try to use autogen.sh as it is removed from repository.

For detailed instructions, see page [[Building_using_CMake|Building using cmake]].

{{Building}}

Building FlightGear - Linux

2011-12-11T02:40:38Z

Moksha: /* APT-GET List */ remove long line

{{Main article|Building Flightgear}}

This section describes how to build [[FlightGear]] on Linux system.

Compiling FlightGear is not a task for novice users. Thus, if you're a beginner (we all were once) on a platform which binaries are available for, we recommend postponing this task and just starting with the binary distribution to get you flying.

Or if you develop on Ubuntu or Debian, consider trying the script described in [[Scripted Compilation on Linux Debian/Ubuntu]].

== Requirements ==
Before you can compile FlightGear, you need to have the following installed on your computer:

'''C++ compiler'''

These are: c++, cpp, gcc, g++ found under the /usr/bin directory. You will also need to have the tools '''autoconf''' and '''automake1.9''' installed.

'''GIT'''

See [[FlightGear and Git]].

'''[[OpenGL]] support'''

More specifically, your system needs the support for hardware accelerated graphics. You can check for this by running the following in a [[command line]]:

glxinfo | grep direct

Note: To run the above command, you need to have the tool '''mesa-utils''' installed.

You should then see:

direct rendering: Yes

This means you are good to go as far as OpenGL support is concerned.

If you see:

direct rendering: No

Don't panic yet. This may just mean some required libraries for hardware accelerated graphic are missing. Go ahead and try installing plib 1.8.5 and its dependencies first. If you still get the above message, then you will need to do some googling and troubleshoot yourself.

== Dependencies ==
FlightGear is dependent on quite a few number of libraries. You do not need to compile all of them yourself, but you will at least need to have their development version installed. For example, the development version for package plib1.8.5 is plib1.8.5'''-dev'''.

The dependency is summarized in the following tree. Please note that each library has its own dependencies, and most of these are not shown here.

* FlightGear
** [http://kcat.strangesoft.net/openal.html OpenAL]
** SimGear
*** [http://plib.sourceforge.net/ PLIB]. Since March 2008, you will need version 1.8.5 - your distro probably supplies 1.8.4 still.
**** For versions pre March 2008: (Free)GLUT or SDL (We recommend the use of SDL over Free/GLUT, [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg16153.html however since March 2008, FreeGLUT as well as SDL are both considered depreciated, please only use --enable-osgviewer during configuration instead])
*** [[OpenSceneGraph]] (check link for compatible versions)
*** You also need the development files for several basic libraries to build the software, among them the following (the package names are for Debian and derivatives(?)):
**** libfreetype6-dev
**** libjpeg62-dev
**** libungif4-dev
**** libtiff4-dev
**** libpng12-dev
**** libxmu-dev
**** libxi-dev
**** zlib1g-dev
**** libglut3-dev

If you attack the above dependencies in the order listed below, you should be good:

1. Glut. Most distributions include glut packages, although you may have to hunt for them. Make sure you install both the glut and glut-devel packages, otherwise FlightGear may be able to compile but won't run correctly.

2. Zlib. Most distributions install the basic zlib libraries by default, but not the development portions. If you don't have zlib.h, you probably need to install the zlib-devel package for your distribution.

3. Plib - portability libraries and scene graph.

4. [[OpenSceneGraph]]

5. SimGear - Simulation support libraries. If you are building FlightGear from Git, you need the Git version of SimGear. If you have strange build errors, one of the first things to check is that you have an up-to-date version of SimGear built and installed.

==== APT-GET List ====
This is a list of all the apt-get commands I had to do while compiling FG, SG, and OSG on a mostly clean Ubuntu 64 system. It is a list of all the libraries you and your computer needs to compile FG, SG, OSG, and PLib. All you have to do is copy the full command, paste it in Terminal, enter your password, and it will download all the packages for you, and install them too. The full command is at the bottom, and I hope someone finds it useful :) sub-dependencies (dependencies of the dependencies) are not included as they are installed automatically by apt-get. If anyone sees something missing, please add it.

git - to get SG and FG<br />
subversion - to get OSG<br />
build-essential - to build (includes GCC, and other build tools)<br />
cmake - OSG Uses this<br />
cmake-curses-gui -- OSG Uses this<br />
libpng-dev - to enable FG to use PNG textures<br />
libfreetype6-dev - fonts<br />
libjpeg-dev<br />
libungif4-dev<br />
libtiff-dev<br />
libxmu-dev<br />
libxi-dev<br />
libglut3-dev<br />
libalut-dev - sound<br />
libboost-dev - makes coding for some developers easier<br />
''automake - needed by ./autogen.sh files''<br />
''autoconf - needed by ./autogen.sh files''<br />
libfltk1.1-dev - You will need this if you will be using FGRun<br />
-----------
<pre>
sudo apt-get install git subversion build-essential cmake cmake-curses-gui libpng-dev libfreetype6-dev
libjpeg-dev libungif4-dev libtiff-dev libxmu-dev libxi-dev libglut3-dev libalut-dev
libboost-dev automake autoconf libfltk1.1-dev
</pre>
-----------
Total size is about 230 MB, depending on what you already have from other applications.

This list might seem a bit short, but the sub-dependencies all add up :) The dependencies will be listed by apt-get when you use the command.
-----------
NOTE: On a Linux Mint 9 (Ubuntu 10.04) system this is the command I used:
<pre>
sudo apt-get install git-core subversion build-essential cmake cmake-curses-gui libpng-dev libfreetype6-dev libjpeg-dev libungif4-dev
libtiff-dev libxmu-dev libxi-dev libglut3-dev libalut-dev libboost-dev ''automake autoconf'' libfltk1.1-dev libplib-dev libopenscenegraph-dev
</pre>
libopenscenegraph-dev
You just need to copy that long line into a terminal and you should have all the packages you need to compile Flighgear and Simgear.

== Compiling ==
Assuming you are root, do:
cd /usr/local/src

'''Note:''' When tracking a fast changing software like FlightGear/Git it is highly advisable to install it in a separate directory. That way one can also easily build and reinstall without being root, which greatly reduces the risk of messing up one's system.
To install in a directory of your choice add the <tt>--prefix</tt> argument to configure. E.g. <tt>./configure --prefix=$HOME/FlightGear</tt>. I would recommend installing all of OSG, plib, SimGear and FlightGear with the same prefix.

=== Getting and compiling SimGear ===

'''Step 1:'''

Clone the SimGear git repository and set it up to track the 'next' branch.
git clone git://gitorious.org/fg/simgear.git

By default after cloning you should have a local next branch that tracks the master next branch. It can be updated it with git pull.

'''Step 2:'''

The source code will be downloaded into a directory called '''simgear'''.

Next, go into the directory and make preparations for the compilation:
cd simgear
''./autogen.sh''
./configure

'''Note''' that if you don't want to install simgear globally on the system but in a specific directory, you can do so by adding --prefix=/path/to/your/fgInstallation to the ./configure command

'''Step 3:'''

Compile and install SimGear by doing:
make; make install

''Note:'' with gcc 4.2 or later,on some platforms, you can get compiling errors about alc.h like:

'<anonymous>' has incomplete type
take a look at http://bugs.gentoo.org/166723

=== Getting and compiling FlightGear ===

'''Step 1:'''

Clone the FlightGear git repository and set it up to track the 'next' branch.
git clone git://gitorious.org/fg/flightgear.git

By default after cloning you should have a local next branch that tracks the master next branch. It can be updated it with git pull.

'''Step 2:'''

Next, go into the folder and make preparations for the compilation:
cd flightgear
''./autogen.sh''
./configure

Note that if you don't want to install simgear globally on the system but in a specific directory, you can do so by adding --prefix=/path/to/your/fgInstallation to the ./configure command.
If you didn't install OSG globally or in the same prefix as SimGear and FlightGear, you have to pass the OSG directory to the configure-command like this:
./configure --prefix=/path/to/fgInstallation --with-osg=/path/to/osg/installation --enable-osgviewer
In this case you have to tell your system where to find the OSG libraries before you can run flightgear:
export LD_LIBRARY_PATH=/path/to/osgInstallation/lib:$LD_LIBRARY_PATH

'''Step 3:'''

Now you can compile and install Flightgear by:
make; make install

'''Step 4:'''

Clone the data directory:
git clone git://gitorious.org/fg/fgdata.git

The data directory is large (almost 2.5GB) so it will take considerable time to download.
There mirror of fgdata that might be faster to download from:
git clone git://mapserver.flightgear.org/fgdata

The mirror is synchronized with the master so either will do.

And install it in (or as) /usr/local/share/FlightGear
mv fgdata /usr/local/share/flightgear

== Distro-specific instructions ==
=== Debian/Ubuntu ===
* You can use the [[Scripted Compilation on Linux Debian/Ubuntu]] script to have Flightgear compiled in one shot under both Ubuntu and Debian systems.
* Debian users who prefer to build it without script may look at [[Building Flightgear - Debian]].
=== Gentoo ===
* Gentoo users can also use overlays to build FlightGear without much hassle: [[Building Flightgear - Gentoo]].

== External links ==
=== Instructions ===
* [[MSYS]]
* [[MinGW/cross-compiler]]
* [[CodeBlocks IDE]]
* [[OpenSUSE 10.1 10.2]]
* [http://www.geoffmclane.com/fg/fgmsvc7.htm MSVC7 *.Net]
* [http://www.oflebbe.de/oflebbe/FlightGear/index.html MSVC8 aka Visual 2005]
* [http://macflightgear.sourceforge.net/home/documents/ Mac OS X]
== Important note for GIT users ==
As of latest development in GIT, only cmake is now required for building both SimGear and FlightGear. So if you build GIT (for what any reason) please don't try to use autogen.sh as it is removed from repository.

For detailed instructions, see page [[Building_using_CMake|Building using cmake]].

{{Building}}

Building FlightGear - Linux

2011-12-09T12:09:25Z

Moksha: /* Dependencies */ grammar

{{Main article|Building Flightgear}}

This section describes how to build [[FlightGear]] on Linux system.

Compiling FlightGear is not a task for novice users. Thus, if you're a beginner (we all were once) on a platform which binaries are available for, we recommend postponing this task and just starting with the binary distribution to get you flying.

Or if you develop on Ubuntu or Debian, consider trying the script described in [[Scripted Compilation on Linux Debian/Ubuntu]].

== Requirements ==
Before you can compile FlightGear, you need to have the following installed on your computer:

'''C++ compiler'''

These are: c++, cpp, gcc, g++ found under the /usr/bin directory. You will also need to have the tools '''autoconf''' and '''automake1.9''' installed.

'''GIT'''

See [[FlightGear and Git]].

'''[[OpenGL]] support'''

More specifically, your system needs the support for hardware accelerated graphics. You can check for this by running the following in a [[command line]]:

glxinfo | grep direct

Note: To run the above command, you need to have the tool '''mesa-utils''' installed.

You should then see:

direct rendering: Yes

This means you are good to go as far as OpenGL support is concerned.

If you see:

direct rendering: No

Don't panic yet. This may just mean some required libraries for hardware accelerated graphic are missing. Go ahead and try installing plib 1.8.5 and its dependencies first. If you still get the above message, then you will need to do some googling and troubleshoot yourself.

== Dependencies ==
FlightGear is dependent on quite a few number of libraries. You do not need to compile all of them yourself, but you will at least need to have their development version installed. For example, the development version for package plib1.8.5 is plib1.8.5'''-dev'''.

The dependency is summarized in the following tree. Please note that each library has its own dependencies, and most of these are not shown here.

* FlightGear
** [http://kcat.strangesoft.net/openal.html OpenAL]
** SimGear
*** [http://plib.sourceforge.net/ PLIB]. Since March 2008, you will need version 1.8.5 - your distro probably supplies 1.8.4 still.
**** For versions pre March 2008: (Free)GLUT or SDL (We recommend the use of SDL over Free/GLUT, [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg16153.html however since March 2008, FreeGLUT as well as SDL are both considered depreciated, please only use --enable-osgviewer during configuration instead])
*** [[OpenSceneGraph]] (check link for compatible versions)
*** You also need the development files for several basic libraries to build the software, among them the following (the package names are for Debian and derivatives(?)):
**** libfreetype6-dev
**** libjpeg62-dev
**** libungif4-dev
**** libtiff4-dev
**** libpng12-dev
**** libxmu-dev
**** libxi-dev
**** zlib1g-dev
**** libglut3-dev

If you attack the above dependencies in the order listed below, you should be good:

1. Glut. Most distributions include glut packages, although you may have to hunt for them. Make sure you install both the glut and glut-devel packages, otherwise FlightGear may be able to compile but won't run correctly.

2. Zlib. Most distributions install the basic zlib libraries by default, but not the development portions. If you don't have zlib.h, you probably need to install the zlib-devel package for your distribution.

3. Plib - portability libraries and scene graph.

4. [[OpenSceneGraph]]

5. SimGear - Simulation support libraries. If you are building FlightGear from Git, you need the Git version of SimGear. If you have strange build errors, one of the first things to check is that you have an up-to-date version of SimGear built and installed.

==== APT-GET List ====
This is a list of all the apt-get commands I had to do while compiling FG, SG, and OSG on a mostly clean Ubuntu 64 system. It is a list of all the libraries you and your computer needs to compile FG, SG, OSG, and PLib. All you have to do is copy the full command, paste it in Terminal, enter your password, and it will download all the packages for you, and install them too. The full command is at the bottom, and I hope someone finds it useful :) sub-dependencies (dependencies of the dependencies) are not included as they are installed automatically by apt-get. If anyone sees something missing, please add it.

git - to get SG and FG<br />
subversion - to get OSG<br />
build-essential - to build (includes GCC, and other build tools)<br />
cmake - OSG Uses this<br />
cmake-curses-gui -- OSG Uses this<br />
libpng-dev - to enable FG to use PNG textures<br />
libfreetype6-dev - fonts<br />
libjpeg-dev<br />
libungif4-dev<br />
libtiff-dev<br />
libxmu-dev<br />
libxi-dev<br />
libglut3-dev<br />
libalut-dev - sound<br />
libboost-dev - makes coding for some developers easier<br />
''automake - needed by ./autogen.sh files''<br />
''autoconf - needed by ./autogen.sh files''<br />
libfltk1.1-dev - You will need this if you will be using FGRun<br />
-----------
<pre>
sudo apt-get install git subversion build-essential cmake cmake-curses-gui libpng-dev libfreetype6-dev
libjpeg-dev libungif4-dev libtiff-dev libxmu-dev libxi-dev libglut3-dev libalut-dev
libboost-dev automake autoconf libfltk1.1-dev
</pre>
-----------
Total size is about 230 MB, depending on what you already have from other applications.

This list might seem a bit short, but the sub-dependencies all add up :) The dependencies will be listed by apt-get when you use the command.
-----------
NOTE: On a Linux Mint 9 (Ubuntu 10.04) system this is the command I used:
<pre>
sudo apt-get install git-core subversion build-essential cmake cmake-curses-gui libpng-dev libfreetype6-dev libjpeg-dev libungif4-dev libtiff-dev libxmu-dev libxi-dev libglut3-dev libalut-dev libboost-dev ''automake autoconf'' libfltk1.1-dev libplib-dev libopenscenegraph-dev
</pre>
libopenscenegraph-dev
You just need to copy that long line into a terminal and you should have all the packages you need to compile Flighgear and Simgear.

== Compiling ==
Assuming you are root, do:
cd /usr/local/src

'''Note:''' When tracking a fast changing software like FlightGear/Git it is highly advisable to install it in a separate directory. That way one can also easily build and reinstall without being root, which greatly reduces the risk of messing up one's system.
To install in a directory of your choice add the <tt>--prefix</tt> argument to configure. E.g. <tt>./configure --prefix=$HOME/FlightGear</tt>. I would recommend installing all of OSG, plib, SimGear and FlightGear with the same prefix.

=== Getting and compiling SimGear ===

'''Step 1:'''

Clone the SimGear git repository and set it up to track the 'next' branch.
git clone git://gitorious.org/fg/simgear.git

By default after cloning you should have a local next branch that tracks the master next branch. It can be updated it with git pull.

'''Step 2:'''

The source code will be downloaded into a directory called '''simgear'''.

Next, go into the directory and make preparations for the compilation:
cd simgear
''./autogen.sh''
./configure

'''Note''' that if you don't want to install simgear globally on the system but in a specific directory, you can do so by adding --prefix=/path/to/your/fgInstallation to the ./configure command

'''Step 3:'''

Compile and install SimGear by doing:
make; make install

''Note:'' with gcc 4.2 or later,on some platforms, you can get compiling errors about alc.h like:

'<anonymous>' has incomplete type
take a look at http://bugs.gentoo.org/166723

=== Getting and compiling FlightGear ===

'''Step 1:'''

Clone the FlightGear git repository and set it up to track the 'next' branch.
git clone git://gitorious.org/fg/flightgear.git

By default after cloning you should have a local next branch that tracks the master next branch. It can be updated it with git pull.

'''Step 2:'''

Next, go into the folder and make preparations for the compilation:
cd flightgear
''./autogen.sh''
./configure

Note that if you don't want to install simgear globally on the system but in a specific directory, you can do so by adding --prefix=/path/to/your/fgInstallation to the ./configure command.
If you didn't install OSG globally or in the same prefix as SimGear and FlightGear, you have to pass the OSG directory to the configure-command like this:
./configure --prefix=/path/to/fgInstallation --with-osg=/path/to/osg/installation --enable-osgviewer
In this case you have to tell your system where to find the OSG libraries before you can run flightgear:
export LD_LIBRARY_PATH=/path/to/osgInstallation/lib:$LD_LIBRARY_PATH

'''Step 3:'''

Now you can compile and install Flightgear by:
make; make install

'''Step 4:'''

Clone the data directory:
git clone git://gitorious.org/fg/fgdata.git

The data directory is large (almost 2.5GB) so it will take considerable time to download.
There mirror of fgdata that might be faster to download from:
git clone git://mapserver.flightgear.org/fgdata

The mirror is synchronized with the master so either will do.

And install it in (or as) /usr/local/share/FlightGear
mv fgdata /usr/local/share/flightgear

== Distro-specific instructions ==
=== Debian/Ubuntu ===
* You can use the [[Scripted Compilation on Linux Debian/Ubuntu]] script to have Flightgear compiled in one shot under both Ubuntu and Debian systems.
* Debian users who prefer to build it without script may look at [[Building Flightgear - Debian]].
=== Gentoo ===
* Gentoo users can also use overlays to build FlightGear without much hassle: [[Building Flightgear - Gentoo]].

== External links ==
=== Instructions ===
* [[MSYS]]
* [[MinGW/cross-compiler]]
* [[CodeBlocks IDE]]
* [[OpenSUSE 10.1 10.2]]
* [http://www.geoffmclane.com/fg/fgmsvc7.htm MSVC7 *.Net]
* [http://www.oflebbe.de/oflebbe/FlightGear/index.html MSVC8 aka Visual 2005]
* [http://macflightgear.sourceforge.net/home/documents/ Mac OS X]
== Important note for GIT users ==
As of latest development in GIT, only cmake is now required for building both SimGear and FlightGear. So if you build GIT (for what any reason) please don't try to use autogen.sh as it is removed from repository.

For detailed instructions, see page [[Building_using_CMake|Building using cmake]].

{{Building}}

Portal:User

2011-12-06T01:36:13Z

Moksha: add piped link for framerates

{{PortalMenu}}

{|style="border-spacing:8px; margin:0px -8px;"
|class="MainPageBG" style="width:100%; border:1px solid #d9e2e2; background:#efefef; vertical-align:top; color:#000;"|
{|width="100%" cellpadding="1" cellspacing="5" style="vertical-align:top; background:#efefef;"
! <h2 style="margin:0; background:#0f7a71; font-size:120%; font-weight:bold; border:1px solid #d9e2e2; text-align:left; color:white; padding:0.2em 0.4em;">The User Portal</h2>
|-
|style="color:#000;"|
This portal is for the users of FlightGear. To be sure you get the latest news, it's a good idea to subscribe yourself to the [http://lists.sourceforge.net/lists/listinfo/flightgear-users FlightGear users] -mailing list. An [http://sourceforge.net/mailarchive/forum.php?forum_name=flightgear-users archive of the list] is available and should be checked before asking again. Also, there's a users forum to be found at http://www.flightgear.org/forums.

|}
|}

{|style="border-spacing:8px; margin:0px -8px;"
|class="MainPageBG" style="width:33%; border:1px solid #d9e2e2; background:#efefef; vertical-align:top; color:#000;"|
{|width="100%" cellpadding="2" cellspacing="5" style="vertical-align:top; background:#efefef;"

! <h2 style="margin:0; background:#0f7a71; font-size:120%; font-weight:bold; border:1px solid #d9e2e2; text-align:left; color:white; padding:0.2em 0.4em;">Getting Started</h2>
|-
|style="color:#000;"|
* [[New to FlightGear]]
* [[Unique Features]]
* [[FlightGear Manual]]
* [[Frequently asked questions]]
* [[Video Tutorials]]
* [[Hardware Recommendations]]
* [[Notebooks known to run FlightGear]]
* [[Recommended Software]]
* [[Troubleshooting Problems]]
* [[Volunteer]]
|-
! <h2 style="margin:0; background:#0f7a71; font-size:120%; font-weight:bold; border:1px solid #d9e2e2; text-align:left; color:white; padding:0.2em 0.4em;">Using Flightgear</h2>
|-
|style="color:#000;"|
* [[Aircraft]]
* [[Helicopter]]
* [[Vehicle]]
* [[Chat Menu]]
* [[Doing aerotow over the net]]
* [[Dual control]]
* [[Flying the Helicopter]]
* [[Instant Replay]]
* [[Menubar]]
* [[Preset Properties]]
* [[Realism]]
* [[Starting in the Air]]
* [[Table of models]]
* [[FlightGear related projects]]
* [http://www.nanjika.co.uk/flightgear/FGShortRef.pdf FlightGear Short Reference] <small>pdf, 80 kB</small>
|-
! <h2 style="margin:0; background:#0f7a71; font-size:120%; font-weight:bold; border:1px solid #d9e2e2; text-align:left; color:white; padding:0.2em 0.4em;">Configuring Flightgear</h2>
|-
|style="color:#000;"|
* [[Multi core and Multi GPU support]]
* [[Command Line Parameters]]
* [[Downloading New Flightgear Scenery for Windows XP]]
* [[Installing Scenery]]
* [[Installing Aircraft]]
* [[Howto: Improve framerates | Improving Framerates]]
* [[Joystick]]
* [[Linux software audio mixing with FlightGear]]
* [[Multiplayer Howto]]
* [http://www.inkdrop.net/dave/multimon.pdf Using multiple monitors with FlightGear]
* [[Howto:Configure Camera View Windows]]
|-
|}

|class="MainPageBG" style="width:33%; border:1px solid #d9e2e2; background:#efefef; vertical-align:top"|
{| width="100%" cellpadding="2" cellspacing="5" style="vertical-align:top; background:#efefef;"
! <h2 style="margin:0; background:#0f7a71; font-size:120%; font-weight:bold; border:1px solid #d9e2e2; text-align:left; color:white; padding:0.2em 0.4em;">FlightGear Community/Events</h2>
|-
|style="color:#000;"|
* [[FlightGear Airways]]
* [[FlightGear Race]]
* [[Pilots of the Caribbean]]
|-
! <h2 style="margin:0; background:#0f7a71; font-size:120%; font-weight:bold; border:1px solid #d9e2e2; text-align:left; color:white; padding:0.2em 0.4em;">Interactive Scenarios</h2>
|-
|style="color:#000;"|
* [[AI Systems]]
* [[Interactive Traffic]]
* [[Soaring]]
* [[Bombable add-on (dogfighting and weapons)]]
|-
! <h2 style="margin:0; background:#0f7a71; font-size:120%; font-weight:bold; border:1px solid #d9e2e2; text-align:left; color:white; padding:0.2em 0.4em;">Howtos</h2>
|-
|style="color:#000;"|
* [[Howto: Multi-computing FlightGear|Multi-computing FlightGear]]
* [[Howto: Air-Air Refueling|Air-Air Refueling]]
* [[Howto: Be a controller|Be a controller]]
* [[Howto: Carrier|Carrier]]
* [[Howto: Get rid of common errors|Get rid of common errors]]
* [[Howto: Multiplayer|Multiplayer]]
* [[Howto: Make nice screenshots|Make nice screenshots]]
* [[Howto: 737-300|737-300]]
'''[[:Category:Howto|More...]]'''
|-
! <h2 style="margin:0; background:#0f7a71; font-size:120%; font-weight:bold; border:1px solid #d9e2e2; text-align:left; color:white; padding:0.2em 0.4em;">Tutorials</h2>
|-
|style="color:#000;"|
* [[ATC Tutorial]]
* [[Instrument Landing System Tutorial]]
* [[Updating FlightGear on Windows]]
|-
! <h2 style="margin:0; background:#0f7a71; font-size:120%; font-weight:bold; border:1px solid #d9e2e2; text-align:left; color:white; padding:0.2em 0.4em;">Using additional FlightGear Tools</h2>
|-
|style="color:#000;"|
* [[FGo!]] - Simple GUI for launching FlightGear
* [[Fgrun]] - aka the FlightGear Wizard
* [[KFreeFlight]] - GUI like fgrun but with KDE dependencies
* [[FGCOM]] - realtime voice comms
* [[Atlas]] - How to set it up
* [[Airport Diagram Generator]] - create charts from FlightGears data
|-
! <h2 style="margin:0; background:#0f7a71; font-size:120%; font-weight:bold; border:1px solid #d9e2e2; text-align:left; color:white; padding:0.2em 0.4em;">FlightGear Promotion</h2>
|-
|style="color:#000;"|
* [[Unique Features]]
* [[FlightGear Reviews]]
* [[FlightGear Videos]]
* [[FlightGear 1.0 features showcase]]
* [[Logos|FlightGear Logos]]
* [[Presentation Recipe]]
|-
|}

|class="MainPageBG" style="width:33%; border:1px solid #d9e2e2; background:#efefef; vertical-align:top"|
{| width="100%" cellpadding="2" cellspacing="5" style="vertical-align:top; background:#efefef;"
! <h2 style="margin:0; background:#0f7a71; font-size:120%; font-weight:bold; border:1px solid #d9e2e2; text-align:left; color:white; padding:0.2em 0.4em;">Suggested</h2>
|-
|style="color:#000;"|

* [[Suggested Aircraft]]
* [[Suggested Airports/Scenery]]
* [[Suggested Flights]]
* [[Suggested Prerecorded Flights]] <small> New! </small>
* [[Challenging Airports]]
* [[Suggested Software]]
|-
! <h2 style="margin:0; background:#0f7a71; font-size:120%; font-weight:bold; border:1px solid #d9e2e2; text-align:left; color:white; padding:0.2em 0.4em;">Top Rated Aircraft</h2>
|-
|style="color:#000;"|
<w4g_ratinglist numberofitems="10" category="Aircraft"/>

'''[[Ratings|More...]]'''
|-
|}
|}

__NOTOC__
__NOEDITSECTION__

[[de:Portal:Benutzer]]
[[es:Portal:Usuario]]
[[pl:Portal:Dla użytkowników]]
[[fr:Portal:Utilisateur]]
[[zh:Portal:用户]]

Scripted Compilation on Linux Debian/Ubuntu

2011-12-06T01:07:19Z

Moksha: /* Disk usage */ sentence structure

==Description==
The following script takes care of downloading and compiling FlightGear from the git repositories with just one command execution for both 32-bit and 64-bit Debian based systems (Debian, Ubuntu). Pre-existing installed version (if any) of FlightGear are not touched at all since the script builds and installs everything under the directory in which it is launched.

Necessary packages are installed via the apt-get system while libraries not included in the repositories are downloaded and compiled on the fly (i.e. [[Plib]], [[Simgear]] and [[OSG]]).

=== List of compiled programs ===
The script is able to download and compile:
* FlightGear (And all the data needed to use it)
* [[Fgrun]]
* [[FGCOM]]
* [[FGComGui]]
* [[FGo!]]
* [[Atlas]]
* [[Terrasync]]

== Download ==
You can download the script here: [http://www.gitorious.org/fg/fgmeta/blobs/raw/master/download_and_compile.sh download_and_compile.sh]

The script is maintained in the FlightGear main repository. Remember to update this script whenever a new FlightGear version is released, so that you'll be able to download the latest stable revision.

There is also another option for building FlightGear and all its dependencies in an automated fashion, please refer to: http://geoffmclane.com/fg/fgfs-052.htm

== Instructions ==
To run download_and_compile.sh, just save it in a directory called for example: ~/fgfs
then execute it (no need to execute it as root).

Here is for example a sequence of commands to get the script:
<pre>
mkdir ~/fgfs
cd ~/fgfs
wget http://www.gitorious.org/fg/fgmeta/blobs/raw/master/download_and_compile.sh
chmod 755 download_and_compile.sh
</pre>

You have two options now: build the latest ''stable'' FlightGear release or build the ''current development'' version (bleeding edge).

=== Build the latest stable FlightGear release ===
When executing the script, use the "-s" option to build the latest stable release:
<pre>
sh download_and_compile.sh -s
</pre>

=== Build the current FlightGear development verison ===
When executing the script without any option, the latest development version is built.

'''Warning''': The development version changes on an almost daily basis. It provides the latest features, but is not always guaranteed to work reliably. If you're unfamiliar with software testing, you may prefer to use the latest stable release.

<pre>
sh download_and_compile.sh
</pre>

Once the script is finished, you will successfully get Flightgear and Fgrun installed in the ~/fgfs directory.

=== Launching FlightGear ===
To run your new git installation of FlightGear you have to launch the ''run_fgfs.sh'' command under the same folder, for example:
<pre>
cd ~/fgfs
sh run_fgfs.sh
</pre>

=== Launching Fgrun ===
[[File:fgrun-page2.jpg|thumb|right]]
For many users it's more comfortable having FlightGear launched by the graphical utility Fgrun which is installed as well in the same folder. You have to launch the ''run_fgrun.sh'' command, for example:
<pre>
cd ~/fgfs
sh run_fgrun.sh
</pre>

=== Launching Fgo! ===
[[File:Fgo01.jpg|thumb|left]]
This is a graphical utility written in [[python]], You have to launch the ''run_fgo.sh'' command, for example:
<pre>
cd ~/fgfs
sh run_fgo.sh
</pre>
Remember that the first time you run it, you have to go to preferences and set the binary and fgdata path (Do no set the working directory, you don't need it).

== Additional programs ==
If you wish to get all the other programs, you need to launch the script adding the "ALL" option to the command line:
<pre>
sh download_and_compile.sh ALL
</pre>
This, will also install FGCOM, FGComGui and Atlas

=== Launching FGCOM ===
FGCOM is the system used by FlightGear to simulate radio communications between users. Launch it using the ''run_fgcom.sh'' command:
<pre>
cd ~/fgfs
sh run_fgcom.sh -cs
</pre>

=== Launching FGComGui ===
FgComGui is a GUI wrapper to launch fgcom.
<pre>
cd ~/fgfs
sh run_fgcomgui.sh
</pre>

=== Launching Atlas ===
[[File:Atlas.jpg|thumb]]
Atlas provides a map for FlightGear, use it launching: ''run_atlas.sh''
<pre>
cd ~/fgfs
sh run_atlas.sh
</pre>

=== Launching Terrasync ===
Your FlightGear compilation comes with the Terrasync program too, so if you want to use it:
<pre>
cd ~/fgfs
sh run_terrasync.sh -S -p 5500 -d /folder/with/sceneries
</pre>
Where: ''/folder/with/sceneries'' is the folder containing the sceneries data.

Then launch fgfs with the '''--fg-scenery=/folder/with/sceneries --atlas=socket,out,5,localhost,5500,udp''' option

== Troubleshooting ==

=== Compilation errors ===
Here we are, no fear, if you wish to use programs from the cvs/svn/git repositories, you might face compilation errors that will prevent you to have a working copy of one or more of the programs provided by this script. What can be the causes that prevent us from successfully compiling? As far as I know those:
# Software developers introduce a new functionality with a new piece of code that prevents the compilation under your architecture, this can happen working with cvs/svn/git sources.
# The program refuses to compile because of a divergence in the libraries on which it depends. For example FlightGear might not compile because OSG has been modified, while OSG itself compiles fine, FG won't.
# One or more repositories are down and you can't get the library you need. (Both from cvs/svn/git or apt-get)

There is a simple solution to the above errors: wait and relaunch the script after some time (hours or days), if software developers repair or synchronize their code with the newly updated libraries (which generally happens eventually), your FlightGear will compile fine as if the previous error never took place.

Sometimes it happens that the script fails to compile only fgrun, fgcom or atlas, if you then see the run_fgfs.sh file it means that FlightGear installation was successful and you can safely run it.

== Options ==
The script by default (without any option) will only compile FlightGear and Fgrun. To make it compile all, you need to launch the script with the ''ALL'' parameter. i.e.:
<pre>
sh download_and_compile.sh ALL
</pre>

=== Compiling only one program ===
If you wish to recompile only one of the programs you can launch the script with one of the following parameters:
* PLIB (to compile and install only plib)
* OSG (to compile and install only OpenSceneGraph)
* SIMGEAR (to compile and install only Simgear)
* FGFS (to compile and install only FlightGear)
* DATA (to download / update only data files for FlightGear)
* FGRUN (to compile and install only Fgrun)
* FGO (to compile and install only Fgo!)
* FGCOM (to compile and install only Fgcom)
* FGCOMGUI (to compile and install only FgComGui)
* ATLAS (to compile and install only Atlas)

=== Fast updating ===
There is a second parameter ''UPDATE'' that allows you to just update your installation. i.e.:
This will only update FGFS
<pre>
sh download_and_compile.sh FGFS UPDATE
</pre>

=== Compiling last stable versions (Experimental) ===
Even if the script fetches data and sources from bleeding edge developers repositories (which sometimes do not compile), you can still force the script to download latest known versions of the software that were compiling successfully by adding the -s option.
<pre>
sh download_and_compile.sh -s
</pre>

How does it work? Inside the script there is a small list with latest known versions of successfully compiling revisions, it will download from svn/git those specific revisions, which have been found able to compile together.<BR/>
Warning: If you run this option inside a folder where you previously compiled fgfs, it will probably fail to compile, you better run the script with this option inside an empty folder or a folder whith the same fgfs version compiled previously.

=== Advanced options ===
* Skip download of packages using '''-p n''' option
* Skip compilation of programs using '''-c n''' option
* Skip retrieving software updates using '''-d n''' option
* Skip reconfigure (make clean) using '''-r n''' option

For example, if you are a developer and wish to quickly recompile and reinstall only your own modifications for FlightGear do this:
<pre>
sh download_and_compile.sh -p n -d n -r n FGFS
</pre>

this will only recompile modifications and reinstall them.

=== Multicore Acceleration ===
Using the option '''-j x''' (where x is the number of your CPU-Cores you wish to assign to the job) will speed up the whole compilation process considerably.

== Disk usage ==
Having both compiled program, source code, and data from git requires some hard disk space: It will take something like 11 GB of space.
If you don't have a fast machine, it will require several hours of compilation time.

[[nl:Compileren met een Script op Linux Debian/Ubuntu]]

Input device

2011-12-05T23:53:20Z

Moksha: typo

Could you imagine a pilot in his or her [[:Category:Cessna|Cessna]] controlling the machine with a keyboard alone? For getting the proper feeling of flight you will need a '''joystick/yoke''' plus [[rudder]] pedals, right? However, the combination of numerous types of joysticks, flightsticks, yokes, pedals and several target operating systems, makes joystick support a nontrivial task in [[FlightGear]].

FlightGear has integrated joystick support, which automatically detects any joystick, yoke, or pedals attached. Just try it! If this does work for you, lean back and be happy! You can see what FlightGear has detected your joystick as in the Help > Joystick Information dialog from the [[menu]].

Unfortunately, for the above mentioned versatility, chances are your joystick does not work out of the box. Basically, there are two alternative approaches to get it going, with the first one being preferred.

== Built-in joystick support ==

=== General remarks ===
In order for joystick auto-detection to work, a joystick bindings xml file must exist for each joystick. This file describes what axes and buttons are to be used to control which functions in FlightGear. The associations between functions and axes or buttons are called “bindings”. This bindings file can have any name as long as a corresponding entry exists in the joysticks description file <tt>[[$FG_ROOT]]/joysticks.xml</tt>, which tells FlightGear where to look for all the bindings files. We will look at examples later.

FlightGear includes several such bindings files for several joystick manufacturers in folders named for each manufacturer. For example, if you have a CH Products joystick, look in the folder <tt>[[$FG_ROOT]]/Input/Joysticks/CH</tt> for a file that might work for your joystick. If such a file exists and your joystick is working with other applications, then it should work with FlightGear the first time you run it. The latest config files are always to be found at https://gitorious.org/fg/fgdata/trees/master/Input/Joysticks.

If such a file does not exist, you will have to create such a file. We will discuss that in [[Joystick#Writing or editing joystick binding xml files|a later section]], by cutting and pasting bindings from the examples that are included with FlightGear.

=== Verifying your joystick is working ===
==== Linux ====
Reboot your system and immediately enter on the [[command line]]

dmesg | grep Joystick

which pipes the boot message to grep which then prints every line in the boot message that contains the string “Joystick”. When you do this with a Saitek joystick attached, you will see a line similar to this one:

input0: USB HID v1.00 Joystick [SAITEK CYBORG 3D USB] on usb2:3.0

This line tells us that a joystick has identified itself as SAITEK CYBORG 3D USB to the operating system. It does not tell us that the joystick driver sees your joystick.

==== Windows ====
Go to <tt>Start > Control Panel > Game Controller</tt> and see whether the dialog displays (and responses) on your joystick.

=== Confirming that the driver recognizes your joystick ===
FlightGear ships with a utility called js_demo. It will report the number of joysticks attached to a system, their respective "names" and their capabilities. Under Linux, you can run js_demo from the folder /FlightGear/bin as follows:

$ cd /usr/local/FlightGear/bin
$ js_demo

Under Windows, open a command shell (<tt>Start > All Programs > Accessories > Command Prompt</tt>), go to the FlightGear binary folder and start the program as follows (given FlightGear is installed under <tt>C:/Program Files/Flightgear</tt>)

C:
cd /Program Files/FlightGear/bin/win32
js_demo.exe

If js_demo.exe is not included in your version, download it [http://fgfs.beggabaur.de/forum/js_demo.exe here].

On our system, the first few lines of output are (stop the program with C if it is quickly scrolling past your window!) as follows:

Joystick test program.
Joystick 0: “CH PRODUCTS CH FLIGHT SIM YOKE USB ”
Joystick 1: “CH PRODUCTS CH PRO PEDALS USB”
Joystick 2 not detected
Joystick 3 not detected
Joystick 4 not detected
Joystick 5 not detected
Joystick 6 not detected
Joystick 7 not detected
+——————–JS.0———————-+——————–JS.1———————-+
| Btns Ax:0 Ax:1 Ax:2 Ax:3 Ax:4 Ax:5 Ax:6 | Btns Ax:0 Ax:1 Ax:2 |
+———————————————-+———————————————-+
| 0000 +0.0 +0.0 +1.0 -1.0 -1.0 +0.0 +0.0 . | 0000 -1.0 -1.0 -1.0 . . . . . |

First note that js demo reports which number is assigned to each joystick recognized by the driver. Also, note that the “name” each joystick reports is also included between quotes. We will need the names for each bindings file when we begin writing the binding xml files for each joystick.

=== Identifying the numbering of axes and buttons ===
Axis and button numbers can be identified using js demo as follows. By observing the output of js demo while working your joystick axes and buttons you can determine what axis and button numbers are assigned to each joystick axis and button. It should be noted that numbering generally starts with zero.

The buttons are handled internally as a binary number in which bit 0 (the least significant bit) represents button 0, bit 1 represents button 1, etc., but this number is displayed on the screen in hexadecimal notation, so:

* 0001 ⇒ button 0 pressed
* 0002 ⇒ button 1 pressed
* 0004 ⇒ button 2 pressed
* 0008 ⇒ button 3 pressed
* 0010 ⇒ button 4 pressed
* 0020 ⇒ button 5 pressed
* 0040 ⇒ button 6 pressed
* ... etcp to ...
* 8000 ⇒ button 15 pressed
* ... and ...
* 0014 ⇒ buttons 2 and 4 pressed simultaneously
* ... etc.

For Linux users, there is another option for identifying the “name” and the numbers assigned to each axis and button. Most Linux distributions include a very handy program, “jstest”. With a CH Product Yoke plugged into the system, the following output lines are displayed by jstest:

jstest /dev/js3
Joystick (CH PRODUCTS CH FLIGHT SIM YOKE USB ) has 7 axes and 12 buttons. Driver version is 2.1.0
Testing…(interrupt to exit)
Axes: 0: 0 1: 0 2: 0 3: 0 4: 0 5: 0 6: 0 Buttons: 0:off 1:off 2:off 3:on 4:off 5:off 6:off 7:off 8:off 9:off 10:off 11:off

Note the “name” between parentheses. This is the name the system associates with your joystick.

When you move any control, the numbers change after the axis number corresponding to that moving control and when you depress any button, the “off” after the button number corresponding to the button pressed changes to “on”. In this way, you can quickly write down the axes numbers and button numbers for each function without messing with binary.

=== Writing or editing joystick binding xml files ===
At this point, you have confirmed that the operating system and the joystick driver both recognize your joystick(s). You also know of several ways to identify the joystick “name” your joystick reports to the driver and operating system. You will need a written list of what control functions you wish to have assigned to which axis and button and the corresponding numbers.

Make the following table from what you learned from js demo or jstest above (pencil and paper is fine). Here we assume there are 5 axes including 2 axes associated with the hat.

{| class="prettytable"
! align="center" bgcolor="#EFEFEF" | Axis
! align="center" bgcolor="#EFEFEF" | Button
|-
|elevator = 0
|view cycle = 0
|-
|rudder = 1
|all brakes = 1
|-
|aileron = 2
|up trim = 2
|-
|throttle = 3
|down trim = 3
|-
|leftright hat = 4
|extend flaps = 4
|-
|foreaft hat = 5
|retract flaps = 5
|-
|
|decrease RPM = 6
|-
|
|increase RPM = 7
|}

We will assume that our hypothetical joystick supplies the “name” QUICK STICK 3D USB to the system and driver. With all the examples included with FlightGear, the easiest way to get a so far unsupported joystick to be auto detected, is to edit an existing binding xml file. Look at the xml files in the sub-folders of '''/FlightGear/Input/Joysticks/'''. After evaluating several of the xml binding files supplied with FlightGear, we decide to edit the file <tt>[[$FG_ROOT]]/Input/Joysticks/Saitek/Cyborg-Gold-3d-USB.xml</tt>.

This file has all the axes functions above assigned to axes and all the button functions above assigned to buttons. This makes our editing almost trivial.

Before we begin to edit, we need to choose a name for our bindings xml file, create the folder for the QS joysticks, and copy the original xml file into this directory with this name.

$ cd /usr/local/FlightGear/Input/Joysticks
$ mkdir QS
$ cd QS
$ cp /usr/local/FlightGear/Input/Joysticks/Saitek/
Cyborg-Gold-3d-USB.xml QuickStick.xml

Here, we obviously have supposed a Linux/UNIX system with FlightGear being installed under '''/usr/local/FlightGear'''. For a similar procedure under Windows with FlightGear being installed under C:/Program Files/FlightGear, open a command shell and type

C:
cd /Program Files/FlightGear/Input/Joysticks
mkdir QS
cd QS
copy /FlightGear/Input/Joysticks/Saitek/
Cyborg-Gold-3d-USB.xml QuickStick.xml

Next, open QuickStick.xml with your favorite editor. Before we forget to change the joystick name, search for the line containing <name>. You should find the line

<name>SAITEK CYBORG 3D USB</name>

and change it to

<name>QUICK STICK 3D USB</name>

This line illustrates a key feature of xml statements. They begin with a <tag> and end with a </tag>.

You can now compare your table to the comment table at the top of your file copy. Note that the comments tell us that the Saitek elevator was assigned to axis 1. Search for the string

<axis n="1">

and change this to

<axis n="0">

Next, note that the Saitek rudder was assigned to axis 2. Search for the string

<axis n="2">

and change this to

<axis n="1">

Continue comparing your table with the comment table for the Saitek and changing the axis numbers and button numbers accordingly. Since QUICKSTICK USB and the Saitek have the same number of axes but different number of buttons, you must delete the buttons left over. Just remember to double check that you have a closing tag for each opening tag or you will get an error using the file.

Finally, be good to yourself (and others when you submit your new binding file to a FlightGear developers or users archive!), take the time to change the comment table in the edited file to match your changed axis and button assignments. The new comments should match the table you made from the js demo output. Save your edits.

Several users have reported that the numbers of axes and buttons assigned to functions may be different with the same joystick under Windows and Linux. The above procedure should allow one to easily change a binding xml file created for a different operating system for use by their operating system.

=== Telling FlightGear about your new bindings xml file ===
Before FlightGear can use your new xml file, you need to edit the file <tt>[[$FG_ROOT]]/joysticks.xml</tt>, adding a line that will include your new file if the “name” you entered between the name tags matches the name supplied to the driver by your joystick. Add the following line to <tt>[[$FG_ROOT]]/joysticks.xml</tt>:

<js-named include="Input/Joysticks/QS/QuickStick.xml"/>

You can tell how FlightGear has interpretted your joystick setup by selecting <tt>Help > Joystick Information</tt> from the menu.

=== Some hints for Windows users ===
Basically, the procedures described above should work for Windows as well. If your joystick/yoke/pedals work out of the box or if you get it to work using the methods above, fine. Unfortunately there may be a few problems.

The first one concerns users of non-US Windows versions. As stated above, you can get the name of the joystick from the program js demo. If you have a non-US version of Windows and the joystick .xml files named above do not contain that special name, just add it on top of the appropriate file in the style of:

<name>Microsoft-PC-Joysticktreiber</name>

No new entry in the base joysticks.xml file is required.

Unfortunately, there is one more loophole with Windows joystick support. In case you have two USB devices attached (for instance a yoke plus pedals), there may be cases, where the same driver name is reported twice. In this case, you can get at least the yoke to work by assigning it number 0 (out of 0 and 1), add a line to <tt>[[$FG_ROOT]]/joystick.xml</tt> like:
<js n="0" include="Input/Joysticks/Saitek/ST290-Pro.xml"/>
if you also have pedals (or another joystick), just add more lines, similar to:
<js n="1" include="Input/Joysticks/Saitek/Pro-Flight-Rudder-Pedals.xml"/>

For this purpose, rotate the yoke ([[aileron]] control) and observe the output of js demo. If figures in the first group of colons (for device 0) change, assignment is correct. If figures in the second group of colons (for device 1) change, you have to make the yoke the preferred device first. For doing so, enter the Windows “Control panel”, open “Game controllers” and select the “Advanced” button. Here you can select the yoke as the “Preferred” device. Afterward you can check that assignment by running js demo again. The yoke should now control the first group of figures.

== Joystick support via .fgfsrc entries ==
Fortunately, there is a tool available now, which takes most of the burden from the average user who, maybe, is not that experienced with XML, the language which these files are written in.

For configuring your joystick using this approach, open a command shell (command prompt under windows, to be found under Start|All programs|Accessories). Change to the directory <tt>[[$FG_ROOT]]/bin</tt> via e.g. (modify to your path)

cd C:/Program Files/FlightGear/bin

and invoke the tool fgjs via

./fgjs --fg-root=[[$FG_ROOT]]

on a UNIX/Linux machine, or via

fgjs --fg-root=[[$FG_ROOT]]

on a Windows machine. The program will tell you which joysticks, if any, were detected. Now follow the commands given on screen, i.eṁove the axis and press the buttons as required. Be careful, a minor touch already “counts” as a movement. Check the reports on screen. If you feel something went wrong, just re-start the program.

After you are done with all the axis and switches, the directory above will hold a file called fgfsrc.js. If the FlightGear base directory FlightGear does not already contain an options file .fgfsrc (under UNIX)/system.fgfsrc (under Windows) mentioned above, just copy

'''fgfsrc.js''' into '''.fgfsrc''' (UNIX)/'''system.fgfsrc''' (Windows)

and place it into the directory FlightGear base directory FlightGear. In case you already wrote an options file, just open it as well as fgfsrc.js with an editor and copy the entries from fgfsrc.js into .fgfsrc/system.fgfsrc. One hint: The output of fgjs is UNIX formatted. As a result, Windows Editor may not display it the proper way. I suggest getting an editor being able to handle UNIX files as well. My favorite freeware file editor for that purpose, although somewhat dated, is still PFE, to be obtained from http://www.lancs.ac.uk/people/cpaap/pfe/.

The the axis/button assignment of fgjs should, at least, get the axis assignments right, its output may need some tweaking. There may be axes moving the opposite way they should, the dead zones may be too small etc. For instance, I had to change

–prop:/input/joysticks/js[1]/axis[1]/binding/factor=-1.0

into

–prop:/input/joysticks/js[1]/axis[1]/binding/factor=1.0

(USB CH Flightsim Yoke under Windows XP). Thus, here is a short introduction into the assignments of joystick properties.

Basically, all axes settings are specified via lines having the following structure:

--prop:/input/joysticks/js[n]/axis[m]/binding/command=property-scale
--prop:/input/joysticks/js[n]/axis[m]/binding/property=/controls/steering option
--prop:/input/joysticks/js[n]/axis[m]/binding/dead-band=db
--prop:/input/joysticks/js[n]/axis[m]/binding/offset=os
--prop:/input/joysticks/js[n]/axis[m]/binding/factor=fa

where

{| class="prettytable"
! align="center" bgcolor="#EFEFEF" |
! align="center" bgcolor="#EFEFEF" |
|-
|n
|number of device (usually starting with 0)
|-
|m
|number of axis (usually starting with 0)
|-
|steering option
|elevator, aileron, rudder, throttle, mixture, pitch
|-
|dead-band
|range, within which signals are discarded; useful to avoid jittering for minor yoke movements
|-
|offset
|specifies, if device not centered in its neutral position
|-
|factor
|controls sensitivity of that axis; defaults to +1, with a value of -1 reversing the behavior
|}

You should be able to at least get your joystick working along these lines. Concerning all the finer points, for instance, getting the joystick buttons working, John Check has written a very useful README being included in the base package to be found under '''FlightGear/Docs/Readme/Joystick.html'''. In case of any trouble with your input device, it is highly recommended to have a look into this document.

== More about programming joystick XML files ==
=== General tips ===
* When testing a new xml file it is best to start FlightGear via a command window (rather than the GUI interface). Any error messages will then be displayed in the terminal. Error messages will give both a message and a line number, helping you pinpoint any errors.
* Errors can be detected on initial startup or at runtime. Both types of errors will be displayed in the terminal.
* One of the most common errors is including a character that makes XML choke. Such characters include<br>& < --<br>These characters will cause problems even if simply included in comments or within scripts.
* If your scripts contain any of these characters, you have to enclose the scripts in <script><![CDATA[...]]></script>. Alternatively, you can 'escape' the characters, ie "<" becomes "<".
* Note that as of ver 1.9.1 there appears to be no way to tell FlightGear to reload joystick files at runtime. So to test any changes to your file you must exit FlightGear and re-start, a somewhat time-consuming process.
* You can find many examples of different ways to program joysticks simply by examining the joystick xml files that are packaged with FlightGear. See the directory FlightGear/data/input/joysticks
* Many advanced functions can be programmed using the Nasal scripting language. These scripts are enclosed in <script></script> tags in the XML file. Helpful:
** A guide to the [[Nasal scripting language]] in FlightGear
** [[Nasal FAQ]]
** [[Howto: Write simple scripts in Nasal]]
* You can explore the internal property tree to see many variables that can be altered using joystick buttons or axes (File/Browse Internal Properties)
* You can test bits of Nasal code and do some other useful things using the Nasal Console (Debug/Nasal Console).
* All Nasal code shares a common namespace, so it's possible to set a variable in one nasal binding, and to read it in another.

=== Useful hints for scripts ===
Some particularly useful ideas for programming scripts within joystick XML files:
* getprop and setprop can be used for getting & setting properties from the internal properties tree:
var brake = !getprop("/controls/gear/brake-parking");
setprop("/controls/gear/brake-parking", brake);
* You can also make your own values on the property tree:
setprop("/input/joysticks/js[0]/myjoystick-modifier", 1);
var mod = getprop("/input/joysticks/js[0]/myjoystick-modifier");
* You can print to terminal using the print function. This is very useful for debugging.
print("Just", " a ", "test");
* You can display info in FlightGear via a popup. This is useful for giving the user feedback about changes that may not be obvious via the panel. It can also be useful for debugging. Example:

gui.popupTip("Parking Brake ON");

Arguments for gui.popupTip must be strings, so if you want to display other types of variables they should be formatted with something like sprintf:

gui.popupTip(sprintf("Elevator trim: %d", 100 * getprop("/controls/flight/elevator-trim")));

Or

thv = getprop("/controls/engines/engine[0]/mixture");
gui.popupTip("Thrust vector " ~ int(thv * 120 - 20));

* You can just start using variables, ie,
x = 10;

But [http://wiki.flightgear.org/index.php/Nasal_scripting_language#Variables for various reasons] it is generally better to declare variables with the "var" statement:
var x = 10;

Note that "var" creates variables that are local in scope, which may cause problems if you are intending to use a variable globally among all different bindings in your joystick XML file.

* You can include a section of script that runs on startup to initialize variables, create functions, etc. Example:
<PropertyList>
<name type="string">My joystick name</name>
<name type="string">My joystick name #2</name>
<nasal>
<script>
#initialize variables
f1 = f2 = 0;
left_brake = right_brake = 0;
# create a function to be used with all buttons
getmod = func { getprop("/input/joysticks/js[0]/t-flight-hotas-x-modifier" ) }
</script>
</nasal>

* Sample code for firing weapons with the joystick is found on the [[Gun Effects]] page.

== Resource ==
{{Forum|24|Hardware}}
* [http://www.flightgear.org/Docs/getstart/getstartch3.html#x8-360003.6 The FlightGear Manual]

== External Links ==
* [http://sourceforge.net/projects/hapticsforfg/ Force Feedback]

[[Category:Hardware]]

[[de:Joystick]]
[[es:Joystick]]

Sikorsky S76C

2010-10-30T21:10:38Z

Moksha: /* Aircraft help */ sentence structure

{{infobox Aircraft
|image =S76c landed.jpg
|alt =The Search and rescue livery
|name =Sikorsky S76C
|livery =Search and rescue, Black, Green, RAAF
|type = Helicopter
|authors = Syd Adams (FDM), Maik Justus (FDM), Wim (performance specs)
|fdm = yasim
|status =
|fgname = <tt>s76c</tt>
}}
The '''Sikorsky S76C ''Spirit''''' is a multi-purpose medium-size commercial [[helicopter]]. Mainly used as rescue helicopter, but also often used for transportation and/or tourist sightseeing.

==Variants==
There are 13 different variants of the S76. Only one is modeled for [[FlightGear]]:
* '''S-76C++:''' with a [http://www.turbomeca.com/public/turbomeca_v2/html/en/produits/version.php?aid=636&sfid=504&mid=615 Turboméca Arriel 2S2] engine

==Aircraft help==
The S-76C is capable of [[Howto: Do aerotow over the net|towing]] other planes or helicopters.
{| class="prettytable"
!Key
!Function
|-
|O
|Open aerotow hook
|-
|o
|Lock aerotow hook
|}

===Startup===
'''Warning: Make sure you have set your collective (thrust to full) before you start your engine!'''

==Development status/Issues/Todo==
'''Outside:'''
* No animated doors

{{Sikorsky}}

[[Category:Aircraft]]
[[Category:Helicopters]]

Sikorsky S76C

2010-10-30T21:08:26Z

Moksha: spelling

{{infobox Aircraft
|image =S76c landed.jpg
|alt =The Search and rescue livery
|name =Sikorsky S76C
|livery =Search and rescue, Black, Green, RAAF
|type = Helicopter
|authors = Syd Adams (FDM), Maik Justus (FDM), Wim (performance specs)
|fdm = yasim
|status =
|fgname = <tt>s76c</tt>
}}
The '''Sikorsky S76C ''Spirit''''' is a multi-purpose medium-size commercial [[helicopter]]. Mainly used as rescue helicopter, but also often used for transportation and/or tourist sightseeing.

==Variants==
There are 13 different variants of the S76. Only one is modeled for [[FlightGear]]:
* '''S-76C++:''' with a [http://www.turbomeca.com/public/turbomeca_v2/html/en/produits/version.php?aid=636&sfid=504&mid=615 Turboméca Arriel 2S2] engine

==Aircraft help==
The S-76C is capable to [[Howto: Do aerotow over the net|tow]] other planes or helicopters.
{| class="prettytable"
!Key
!Function
|-
|O
|Open aerotow hook
|-
|o
|Lock aerotow hook
|}

===Startup===
'''Warning: Make sure you have set your collective (thrust to full) before you start your engine!'''

==Development status/Issues/Todo==
'''Outside:'''
* No animated doors

{{Sikorsky}}

[[Category:Aircraft]]
[[Category:Helicopters]]

Howto:Be a controller

2010-10-30T20:58:48Z

Moksha: /* Multiplayer setup */ improve sentence structure

{{ATC-navbar}}
{{Main article|Air traffic control}}

===ATC-aircraft===
{{Main article|ATC-aircraft}}
Anyone can be a controller using the UFO or any other plane but to get the real ATC feeling you should use the [[ATC-aircraft]]. The advantage of the ATC-aircraft is that you have a radar, just like in real life. No more looking at the [[MPMap]] to check where the pilots are.

===Multiplayer setup===
The other pilots must know that you are a controller and which airport you're controlling. For this reason you should use a special call-sign. In the table below you can find the call-signs which are used by the different types of controllers. Since we don't have a lot of controllers at FlightGear, we almost always have to be the tower controller.

Example: For San Francisco you're callsign would be KSFO_TWR, or for London Heathrow it would be EGLL_TWR.

{| class="prettytable"
! align="center" bgcolor="#EFEFEF" | Position Suffix
! align="center" bgcolor="#EFEFEF" | Name
! align="center" bgcolor="#EFEFEF" | Description
|-
| xxxx_GND
|Ground Controller
|Controls the movement of aircraft on the ground at an airport, however only the taxiways and bays... not the active runways. Whenever a plane needs to cross an active runway, it must call the tower.
|-
| bgcolor="#EFEFEF" align="left" |xxxx_TWR
| bgcolor="#EFEFEF" align="left" |Tower Controller
| bgcolor="#EFEFEF" align="left" |'Owns' the runways and the airspace up to 10 NM (nautical miles) from the airport. Clears planes for takeoff and landing.
|-
|xxxx_APP
|Approach Controller
|Controls the airspace up to 30NM away from the airport, up to 18,000 ft (usually). Handles all aircraft leaving or arriving at an airport, until they are established on the ILS (then hands the flight off to TWR) or are leaving their airspace to continue flight (then hands off to CTR)
|-
| bgcolor="#EFEFEF" align="left" |xxxx_DEP
| bgcolor="#EFEFEF" align="left" |Departure Controller
| bgcolor="#EFEFEF" align="left" |This position is rarely used except at busy airports in the real world which relieves the work-load of the approach controller by handling all the departures, and getting them away from arrivals as quickly as possible, leaving the approach controller free to handle arrivals (the hard bit).
|-
|xxxx_CTR
|(ARTCC) Center Controller
|Centers own all airspace not controlled by APP or TWR. They control the plane while en route, and get it from X to Y safely, until it can be descended and given to the approach controller.
|-
| bgcolor="#EFEFEF" align="left" |xxxx_FSS
| bgcolor="#EFEFEF" align="left" |Flight Service Station
| bgcolor="#EFEFEF" align="left" |Flight Service Stations cover large areas (e.g.: France) and provide support to pilots and controllers. They can advise pilots of weather and frequencies for other controllers. They do not provide Air Traffic Control.
|-
|xxxx_DEL
|Clearance Delivery
|Clearance Delivery is rarely used in FlightSims. In the real world, a controller would give a clearance (which explains where the plane is allowed to fly) to all planes, but the ease of giving a clearance in the virtual world, means the Tower can normally give the clearance.
|}

===Airport diagram===
After the multiplayer settings have been set, a diagram of the airport should be downloaded. The diagram shows the names of the taxiways, directions of the runways, and locations of the gates, etc. So the airport diagram is very important for a controller!

The best way to find an airport diagram is by searching Google for xxxx Diagram. For KSFO we search for <tt>KSFO Diagram</tt>, first hit is already what we need. Most of the countries have their own databases with diagrams. It's worth it to take a look at them, because they often provide better and more detailed diagrams.

You can print out the diagram and put it beside your computer. This way you don't have to switch screens to look at the diagram.

[[Image:ATC-aircraft.jpg|thumb|270px|The panel (with radar) as found when using the [[ATC-aircraft]].]]

===Controlling===
Now we're finally ready to control. Launch FlightGear with the multiplayer settings we set above. After FG has loaded you'll find yourself in the tower. You're screen should look like the picture shown on the right. The large black sqaure with green and white texts is your radarscreen. Each dot is a pilot. Beside the dot you find some information about the aircraft (like altitude, speed and heading).
* Click on the triangles on either side of <tt>No #</tt> to select planes within the set range of the radar. The selected plane is highlighted in white on your radar screen. At the same time you see the information of the selected plane appear in the boxes below the radar.
* To increase the range of the radar (to see more airspace) click on the triangles near <tt>Range</tt>. You can only select planes that are within the set range of the radar.
* The large bar at the lower part of the screen is used to compose chat messages. You must click the send button to send your message.

''See [[ATC Tutorial]]''

==Problems and solutions==
* Why do I see a lot of planes which aren't shown on the MPMap?
** These planes are [[AI-traffic]], which isn't showed on the MPMap. To turn AI-traffic off, use the following property: <tt>/sim/traffic-manager/enabled=false</tt>.
* How could I change the COM frequencies?
** Go to <tt>Equipment > Radio settings</tt>.

[[Category:Air Traffic Control]]
[[Category:Howto|Be a controller]]

FSweekend 2010

2010-10-30T20:53:08Z

Moksha: /* Booth information */spelling

[[Image:FSweekend_banner_2010.jpg|right|350px]]
This wiki page lists all information required for participants to the [[FSweekend]] and the attached multiplayer event(s). [[FlightGear]] will be represented by a team of seven regular FlightGear developers and users.

<font size="5"><eventcountdown date="06-November-2010">'''<daysuntil in="days">06-November-2010</daysuntil>''' until the FSweekend</eventcountdown></font>

==Booth information==
This year's booth will probably exist of:
[[image:Anaglyph-glasses.jpg|right]]
* an UMTS USB stick for unlimited data use at high speed, so users from all over the world can visit us virtually.
* a bunch of 3D glasses, to demo the [[Anaglyph (3D)|anaglyph]] ability of FlightGear.
* a FlightGear based [[Howto:_Build_your_own_procedure_trainer|procedure trainer]].
* a Linux-based triple-screen PC, with a generic set of input devices for general purpose flight demonstrations.
* a top-end workstation equipped with 4(!) nVidia GTX460 to showcase our multi-screen capabilities

=== Equipment Checklist ===
* One main power extension cord (DT: yellow)
* One main power extension cord (DT: green)
* One main power extension cord (TD: black)
* One main power extension cord (JVDV: red)
* One Linux-based PC (DT)
** Three monitors
** Saitek Joystick
** Saitek Rudder Pedals
** Headset
** Sound system
* One Linux-based PC (JVDV)
** Three monitors
** Thrustmaster HOTAS Cougar
** Saitek Rudder Pedals
** USB Headset
* One Macbook Pro (DT)
** simple joystick
* One Macbook, white (TD)
* One Linx-based Notebook (TD)
** simple joystick
** ELITE yoke
** simple, homemade multi-engine and view controller
** 3Dconnexion 3d-mouse
* One FlightGear based procedure trainer (TD) [[image:Pmpt-0.1.jpg|right|thumb]]
** ELITE ProPanelII
** FlightLink rudder set
** Two TFT Displays
** Panel controller
** old (historic?) tablet pc running Atlas
* One Thomas-Krens-AG workstation (TD)
** Eight monitors (probably)
* Two FlightGear banners (TD)
** mounting material (last year's setup from Durk)
* FlightGear business cards (TD)
* Coffee maker (Senseo, bring your own pads!) (TD)
* two or three sets of aviation headsets (deco) (TD)
* One CH Flight Sim Yoke
* One CH Pro Pedals

==Flight information==
===Airports===
Activities will mainly take place at and around [[Amsterdam Airport Schiphol]] (EHAM), [[Lelystad Airport]] (EHLE), [[Volkel Air Base]] (EHVK) and the VU University Medical Center Helipad [[EH0001]].

===Charts===
All charts that you may have to use on your flights are available at http://ais-netherlands.nl (AIS Publications > Integrated Package). Please note that these are the most up to date charts available, so certain situations might not have been changed in FlightGear (EHAM, EHLE and EHVK taxiways should be correct though).

Parking positions have been created for most of the Dutch airports including EHAM, EHRD, EHVK and EHLE (A1-A6, B1 and B2).

All named airports are for civil usage, except for [[Volkel Air Base]] (EHVK). This base will be occupied by the (AI) F-16 squadrons and likely one setup in Lelystad. Feel free to join with your F-16 or other Dutch/NATO mil aircraft.

===Weather information===
Reallife weather information can be found at the KNMI (Dutch Meteorological institute) website.
* [http://knmi.nl/actueel/metar.html METAR] current weather at airports
* [http://knmi.nl/waarschuwingen_en_verwachtingen/luchtvaart/nederlandse_vliegveldverwachtingen.html TAF] expected weather at airports
If the weather is really bad, it is likely that the FSweekend guys will use a preset weather scenario.

==Scenery==
We will be using newly generated scenery in Lelystad.

==Events==
The guys from [[TransGear]] will organise a multiplayer event on both days. The event consist pilots flying pre-requested routes from and to Schiphol (EHAM). All activity at EHAM will take place around 13:00 GMT (that is 14:00 local time in the Netherlands). Traffic will be controlled by at least one (likely more) air traffic controller(s).

The people in Lelystad will have something to show to the public and might be able to participate during parts of the event (maybe there are even some visitors to our booth that would like to fly in one of our best MP events).

More information in the [http://flightgear.org/forums/viewtopic.php?f=10&t=9773 forum topic] and on the [http://transgear.treborlogic.com/ TransGear website].

Piper PA34-200T Seneca II

2010-10-30T20:45:59Z

Moksha: /* Introduction */ sentence structure

{{infobox Aircraft
|image =Piper_SenecaII.jpg
|name =Piper PA34-200T Seneca II
|type =Civilian aircraft
|fdm =JSBSim
|status =early-production
|authors =Torsten Dreyer
|fgname =<tt>SenecaII-jsbsim</tt>
}}

== Introduction ==
[[Image:SenecaII_real.jpg|thumb|250px|The real Seneca II]]
This is a model of a Piper PA34-200T Seneneca II. The Seneca has been made by Piper since the early 1970's and some 4500 were made since then. It has six seats in a pretty large cabin, two turbocharged counterrotating engines producing 200hp up to 12,000 ft. It cruises at 170ktas in 12,000ft at 65% power. Certification for flights into known icing conditions and the nice single engine behaviour made the Seneca a popular multi engine trainer.

The model was built using the Pilots Operating Handbook, a real Seneca (D-GEJL) and some flight performance data derived in real flights.
<br clear="all" />,

== Features ==
=== Full functional 3d cockpit ===
[[Image:SenecaII_cockpit.jpg|thumb|250px|The 3d cockpit]]
Almost all controls, switches, gauges and indicators are implemented and functional in the cockpit. For description of the panel have a look at the [[Seneca II Panel Reference]].
The default KI227 ADF indicator can be exchanged into a KI228 RMI indicator coupled to ADF and NAV1 radio.
To use the KI228, simply set the property
/instrumentation/adf/model
to
ki228
in the property browser or use the command line switch
--prop://instrumentation/adf/model=ki228
when starting up the Seneca
<br clear="all" />

=== Tutorials ===
Using the menu items ''Help->Start Tutorial'' a bunch of tutorials are reachable.
* '''Cold Start''' Puts your aircraft into hibernation mode. Everything is off.
* '''Hot Start''' Everything is ready to go, just start the engines and fly.
* * '''Check''' These are the checklists from [[Seneca II Checklist]]
<br clear="all" />

=== Structural Icing ===
[[Image:SenecaII_icing.jpg|thumb|250px|Icing on the temperature probe]]
Since the Seneca provides anti- and deice equipment, I tried to model structural icing into flightgear. A little nasal script does most of the work: First it reads the property nodes under /sim/model/icing where any number of iceable elements configure the ice sensitive elements of the aircraft. Each element have a name, a sensitivity to icing, may have a salvage control and the name of a output property where the collected amount of ice is written to. After the initial configuration, a timed loop is executed every 2 seconds. It
* calculates the spread by OAT and dewpoint
* checks visibility (see remark) to tell if the aircraft is within clouds
* if the spread is below 0.1 degc and visibility is below 1000m, assumes potential icing condition and icing severity is calculated
* update all ice sensitive elements with the current icing conditions

The icing severities are defined as
{|
! severity
! inches
! per NM (still air)
|-
| NONE
| -0.3
| 80
|-
| TRACE
| 0.5
| 80
|-
| LIGHT
| 0.5
| 40
|-
| MODERATE
| 0.5
| 20
|-
| SEVERE
| 0.5
| 10
|}

The rule for calculating the severity is
{|
! OAT_min
! OAT_max
! severity_min
! severity_max
|-
| -99
| -30
| NONE
| TRACE
|-
| -30
| -20
| TRACE
| LIGHT
|-
| -20
| -12
| LIGHT
| SEVERE
|-
| -2
| -0
| NONE
| MODERATE
|-
| 0
| 999
| NONE
| NONE
|}
When oat is above zero degc, Ice melts at a rate of 0.5" per 10NM at 10degc, the warmer the faster.
<br clear="all" />

=== Pitot Icing ===
The pitot tube is prone to icing, too. A little agent is waiting for you to get into icing conditions without switching on the pitot heat. If he gets you, he will fail your pitot system which will result in some strange airspeed indicator behaviour.

== Pilot Operating Handbook ==
=== General ===
==== Engines ====
{| width="100%"
| width="50%" | Number of Engines
| width="50%" | 2
|-
|Engine Manufacturer
|Continental
|-
|Engine Model Number
|(L)TSIO-360EB
|-
|Rated Horsepower
|Sea Level: 200, 12,000ft.: 215
|-
|Rated Speed (rpm)
|2575
|-
|Bore (inches)
|4.438
|-
|Stroke (inches)
|3.875
|-
|Displacement (cubic inches)
|360
|-
|Compression Ratio
|7.5:1
|-
|Engine Type
| Six Cylinder, Direct Drive, Horizontally Opposed, Air Cooled
|}

==== Propellers ====
{| width="100%"
| width="50%" |Number of Propellers
| width="50%" |2
|-
|Propeller Manufacturer
|Hartzell
|-
|Number of Blades
|2
|-
|Propeller Diameter
| Maximum: 76 inches, Minimum: 75 inches
|-
|Propeller Type
|Constant Speed, Hydraulically Actuated, Full Feathering
|}

==== Fuel ====
{| width="100%"
| width="50%" |Fuel Capacity (U.S.gal) (total)
| width="50%" |128
|-
|Usable Fuel (U.S.gal) (total)
|123
|-
|Minumum Grade
|100 Green or 100LL Blue Aviation Grade
|-
|}

==== Oil ====
{| width="100%"
| width="50%" |Oil Capacity (U.S.quarts) (per engine)
| width="50%" |8
|}

==== Maximum Weights ====
{| width="100%"
| width="50%" |Maximum Takeoff Weight (lbs)
| width="50%" |4570
|-
|Maximum Landing Weight (lbs)
|4362
|-
|Maximum Zero Fuel Weight (lbs) - Standard
|4000
|-
|Maximum Weight in Baggage Compartment (lbs)
|Forward: 100, Aft: 100
|}

==== Standard Airplane Weights ====
{| width="100%"
| width="50%" | Standard Empty Weight (lbs): Weight of a standard airplane including unusable fuel, full operating fluids and full oil.
| width="50%" | 2823
|-
| Maximum Useful Load (lbs): The difference between the Maximum Takeoff Weight and the Standard Empty Weight. (All weight in excess off 4000lbs must consist of fuel)
|1747
|}

==== Specific Loadings ====
{| width="100%"
| width="50%" | Wing Loading (lbs per sq ft)
| width="50%" | 22
|-
| Power Loading (lbs per hp)
| Sea Level: 11.4 - 12,000ft: 10.6
|}

=== Limitations ===
==== Airspeed Limitations ====
{| width="100%"
! width="50%" align="left" | Speed
! width="25%" align="left" | KIAS
! width="25%" align="left" | KCAS
|-
| Never Exceed Speed (V<sub>NE</sub>) - Do not exceed this speed in any operation
| 195
| 195
|-
| Maximum Structural Cruising Speed (V<sub>NO</sub>) - Do not exceed this speed except in smooth air and then only with caution.
| 163
| 165
|-
| Design Maneuvering Speed (V<sub>A</sub>) - Do not make full or abrupt control movements above this speed.
|  
|  
|-
| align="center"| At 4570 LBS G.W.
| 136
| 138
|-
| align="center"|At 3068 LBS G.W.
| 121
| 122
|-
| colspan="3" align="center" |
<b>CAUTION</b>

Maneuvering speed decreases at lighter weight as the effects of aerodynamic forces become more pronounced. Linear interpolation may be used for imtermediate gross weights. maneuvering speed should not be exceeded while operating in rough air.
|-
| Maximum Flaps Extended Speed (V<sub>FE</sub>) - Do not exceed this speed with flaps extended.
| 107
| 109
|-
| Maximum Gear Extended Speed (V<sub>LE</sub>) - Do not exceed this speed with landing gear extended
| 129
| 130
|-
| Maximum Landing Gear Extending Speed (V<sub>LO</sub>) - Do not extend landing gear above this speed
| 129
| 130
|-
| Maximum Landing Gear Retracting Speed (V<sub>LO</sub>) - Do not retract landing gear above this speed
| 107
| 109
|-
| Air Minimum Control Speed (V<sub>MC</sub>) - Lowes airspeed at which airplane is controllable with one engine operating and no flaps
| 66
| 69
|-
| Best Single Engine Rate of Climb Speed
| 89
| 90
|}

==== Airspeed Indicator Markings ====
{| width="100%"
! width="50%" align="left" | Marking
! width="50%" align="left" | KIAS
|-
|Green Arc (Normal Operating Range)
|63 to 163
|-
|Yellow Arc (Caution Range - Smooth Air)
|163 to 195
|-
|White Arc (Flaps Extended Range)
|61 to 107
|-
|Radial Red Line (Never Exceed - Smooth Air)
|195
|-
|Radial Red Line (Minimum Control Speed - Single Engine)
|66
|-
|Radial Blue Line (Best Rate of Climb Speed - Single Engine)
|89
|}

==== Power Plant Limitations ====
{| width="100%"
| width="50%" | Maximum Rotational Speed
| width="50%" | 2575
|-
| Maximum Manifold Pressure (Inches of Mercury)
| 40
|-
| Maximum Cylinder Head Temperature
| 460 °F
|-
| Maximum Oil Temperature
| 240 °F
|-
| Minimum Oil Pressure (red line)
| 10 PSI
|-
| Maximum Oil Pressure (red line)
| 100 PSI
|-
| colspan="2" align="center" |
<b>NOTES</b>

Avoid continuous operation between 2000 and 2000 RPM above 32 IN. HG. manifold pressure.

Avoid continuous ground operation between 1700 and 2100 RPM in cross and tail winds over 10 knots.
|}

==== Power Plant Instrument Markings ====
{| width="100%"
! width="50%" align="left"| Tachometer
| width="50%" |  
|-
| Green Arc (Normal Operating Range)
| 500 RPM to 2575 RPM
|-
| Red Line (Maximum)
| 2575 RPM
|-
! align="left" | Fuel Flow and Pressure
| 
|-
| Green Arc (Normal Operating Range)
| 3.5 PSI to 20 PSI
|-
| Red Line (Maximum at Sea Level)
| 25 GPH (20PSI)
|-
| Red Line (Minimum)
| 3.5 PSI
|-
! align="left" | Cylinder Head Temperature
|  
|-
| Green Arc (Normal Range)
| either 360 °F to 460 °F
|-
|  
| or 240 °F to 460 °F
|-
| Red Line (Maximum)
| 460 °F
|-
! align="left" | Oil Temperature
|  
|-
| Green Arc (Normal Operating Range)
| either 75 °F to 240 °F
|-
|  
| or 100 °F to 240 °F
|-
| Red Line (Maximum)
| 240 °F
|-
! align="left" | Oil Pressure
|  
|-
| Green Arc (Normal Operating Range)
| either 30 PSI to 80 PSI
|-
|  
| or 30 PSI to 60 PSI
|-
| Yellow Arc (Caution)
| either 80 PSI to 100 PSI
|-
|  
| or 60 PSI to 100 PSI
|-
| Red Line (Minimum)
| 10 PSI
|-
| Red Line (Maximum)
| 100 PSI
|-
! align="left" | Manifold Pressure
|  
|-
| Green Arc (Normal Operating Range)
| 10 IN. to 40 IN. HG.
|-
| Red Line (Maximum)
| 40 IN. HG.
|-
! align="left" | Exhaust Gas Temperature
|  
|-
| Red Line
| 1650 °F
|}

==== Center of Gravity Limits ====
{| width="100%"
! width="33%" align="left" | Weight<br>Ponds
! width="33%" align="left"| Forward Limit<br>Inches Aft of Datum
! width="34%" align="left" | Aft Limit<br>Inches Aft of Datum
|-
|3400
|82.0
|94.6
|-
|4570
|90.6
|94.6
|}
<b>NOTES</b>

Straight line variation between the points given.

Datum is 78.4 inches forward of wing leading edge from the inboard edge of the inboard fuel tank.

==== Maneuver Limits ====
All intentional acrobatic maneuvers (including spins) are prohibited. Avoid abrupt maneuvers.

==== Flight Load Factor Limits ====
{| width="100%"
| width="50%" | Positive Load Factor (Maximum)
| width="50%" | 3.8 G
|-
| Negative Load Factor (Maximum)
| No inverted maneuvers approved
|-
|}

==== Types of Operations ====
The airplane is approved for the following operations when equipped in accordance with FAR 91 or FAR 135
* Day VFR
* Night VFR
* Day IFR
* Night IFR
* Icing conditions when equipped.

==== Fuel Limitations ====
The usable fuel in this aircraft is 61.5 gallons in each wing or a total of 123 gallons.

==== Gyro Pressure Limits ====
The operating limits for the pressure system are 4.5 to 5.2 inches of mercury for all operations as indicated by the gyro pressure gauge.

==== Flight Into Known Icing Conditions ====
For flight in icing conditions the following equipment must be installed inaccordance with Piper drawings or in an FAA approved manner:
* Pneumatic wing end empennage boots
* Electrothermal propeller boots
* Electric windshield panel
* Heated pitot head
* Wing ice light
* Heated lift detectors
* Propeller spinners must be installed

==== Operating Altitude Limitations ====
Flight above 25,000 feet is not approved. Flight up to and including 25,000 feet is approved if equipped with oxygen in accordance with FAR 23.1441 and avionics in accordance with FAR 91 or FAR 135.

== Development status/Issues/Todo ==
'''FDM (JSBSim):'''
* poor single engine performance
* fuel source not switchable or cutable
* flap operation should not emit a flap motor sound
* moving aircraft with parking brake set and full power

'''Autopilot:'''
* The autopilot may be unstable in certain situations. A complete rework is in progress and will be commited to CVS ''"soon"'' --[[User:T3r|T3r]] 21:32, 28 February 2010 (UTC)

'''Electrical system:'''
* Master switch no electrical function
* Generator L/H and R/H produce the same output when on

'''Avionics:'''
* KI228 RMI shows wrong heading. If the ADF indicator is reconfigured from a KI227 to KI228 with a compass card rotation other than zero, the KI228 does not show the same heading as the HSI.
''REMARK:'' This is fixed in CVS version.
* No transponder.
''REMARK:'' There is a GTX330 transponder as an empty 3d model without functionality.
* No GPS.
''REMARK:'' There is a GPS155XL GPS as an empty 3d model without functionality.

'''General:'''
* engine sound in cockpit does not differ from outside engine sound
* animations of structural icing on wings, stabilizer, fin, etc.missing

{{Piper}}

== External links ==
== Related content ==
* [[Seneca II Checklist]]
* [[Seneca II HOWTO]]
* [[Seneca II Panel Reference]]
* [[HSI|HSI, Horizontal Situation Indicator]]
* [[Kx165|KX165 COM/NAV Radio]]

=== Related lists ===
* [[Aircraft]]
* [[Aircraft Todo]]

[[Category:Aircraft]]
[[Category:Civilian aircraft]]
[[Category:Aircraft TODO]]
[[Category:Twin Engine Piston]]
[[Category:Piper PA34-200T Seneca II]]
[[Category:Model with well-implemented cockpit]]
[[Category:Candidate Aircraft for next release]]

[[fr:Piper PA34-200T Seneca II]]

Weather

2010-10-30T20:40:44Z

Moksha: /* Explanation */ spelling

[[Image:3D_clouds.jpg|thumb|270px|[[3D clouds]] in [[1.9.0-prerelease]] version as seen from a [[EC135]].]]
[[Image:weather_scenario.jpg|thumb|270px|The Weather Scenario window in FlightGear 1.9.1.]]
[[Image:New_Weather_Scenario.jpg|thumb|270px|The new Weather Scenario window in FlightGear CVS.]]
FlightGear has an impressive weather system, including real weather fetch, predefined weather scenarios, [[3D clouds]] and lightning.

==How FlightGear creates weather==
Weather in reality is the state of the atmosphere at a given time for a given place. Calculating the complete atmosphere or even a small part of it will easily eat up all your computing power and result in very limited frame rates. FlightGear only calculates the state of the atmosphere for a vertical line beginning at earth's center straight through your aircraft up to approx. 100,000ft AGL. Most calculations are based on the [http://en.wikipedia.org/wiki/International_Standard_Atmosphere International Standard Atmosphere].
FlightGear's fundamental atmosphere parameters calculated are:
* temperature
* dew point
* pressure
* density
* wind (three dimensional)
* visibility

===Atmosphere===
The line for which FlightGear calculates the atmosphere is divided into two major segments and several sub segments. The bottom major segment (the one closest to the ground) is called the boundary layer. It reaches up to 500ft above ground and connects directly above it to the so called aloft layer. By definition, in the boundary layer, the atmosphere - mainly the wind - is affected by the structure of the earth's surface, while in the aloft layer there is a free flow of air.
Within the boundary and the aloft layer, one up to many layers of atmosphere may be defined that have certain characteristics, like wind direction and speed.
The basic weather definition in FlightGear is
* Boundary layer, 0ft
** wind 270@3KT
** visibility 10SM
** pressure 29,92INHG / 1013hPa
** temperature 15, dewpoint 5
* Boundary layer, 500ft
** wind 280@6KT
* Aloft layer, 3000ft
** wind 300@10KT
* Aloft layer, 6000ft
** wind 310@20KT
* Aloft layer, 9000ft
** wind 320@30KT
All other values are derived from these parameters. When the aircraft changes altitude and passes through these layers, a linear interpolation between the parameters for the entry above and below your position is performed to compute the values for your exact altitude.
The atmospheric parameters described here are defined in preferences.xml and can be changed at runtime by selecting '''Environment->Weather Conditions''' from the menu. The entry "Boundary transition depth" defines the thickness of the zone where the effects of the boundary layer and the aloft layer mix. When you fly within 500ft of the border between boundary and aloft layer, both tables are interpolated.

===Clouds===
Clouds are - other than in real life - not visible humidity, when dew point and temperature match. They are a separate system and so are defined separately. They are also stacked in layers and for each layer the defining parameters for clouds are
* coverage (clear, few, scattered, broken, overcast)
* the elevation of cloud base (height above ground, not altitude!)
* the thickness (distance from cloud base to cloud top)
* the span (how far away do the clouds reach)
Once again, definition of the base cloud set is in preferences.xml and runtime adjustments can be done via the menu '''Environment->Clouds'''

==Defining Weather==
Defining weather can be a tedious task. Setting all the parameters for each layer and defining clouds is not everybody's fun. To get a weather definition done quickly, FlightGear has a build in METAR interpreter. This can read the coded weather information from a METAR and apply a more or less reasonable weather, that matches the conditions described in the METAR. Since a METAR only describes the weather a a station on the ground, many parameters, esp. for the higher atmosphere are just plain guesses which just try to be reasonable.
You can either pass a metar string as a command line option like
--metar="EDDH 280920Z 28020KT 9999 SCT030 14/07 Q1020 NOSIG"
or use the Weather Scenario dialog from the menu at '''Environment->Weather Scenario''', where you can select a predefined weather, enter your own METAR or even enable live weather data. This options enables a task, that calculates your nearest airport and fetches the current METAR for that station from NOAA weather service.
An internal interpolation routine applies weather changes smoothly when changing the METAR.

==METAR==
A [[METAR]] is a codified observation message indicating an airfield weather conditions observed at a given time. There are different ways of messaging weather reports, but in [[FlightGear]] is [[METAR]] used.

The [[METAR]]-message can be found acros the menu (Weather > Weather Scenario). To have the actual weather (or playing with [[ATC]]) you need to enable the Real weather fetch in the [[FlightGear Wizard]].

Such a message is established every hour.

===Explanation===
'''Example:'''
{| class="prettytable"; border="1" style="border-collapse:collapse; border:1px solid silver;"
|2008/03/15 12:24
|KSFO
|151224Z
|05012KT
|10SM
|SN
|BKN050
|02/M08
|A3016
|RMK AO2 SLP228
|T00221083
|-
|1
|2
|3
|4
|5
|6
|7
|8
|9
|10
|11
|}

# Date
# [[ICAO]] Identifier (4-letter)
# Issuance Time DDHHMMz (UTC)
#*COR (CCD in Canada) if correction to observation
#Wind
#*First 3 digits: True Wind direction or average if variable (VRB).
#**Note: If the wind direction varies 60° or more, the direction will be indicated with a V (e.g. 180V250)
#*Next 2 digits: Mean speed and units
#** KT=knots, KMH=kilometers/hour, MPS=meters/second
#*G (gust) as needed – 2 or 3 digit maximum speed
#*Calm will be indicated by 00000KT
#*Example: 18012G22KT 150V240
#Horizontal Visibility
#*Prevailing Visibility (PV)
#**Statue miles (SM) and fractions (US & Canada only) or,
#**4 digit minimum visibility in meters, and,
#**Lowest value and direction, as required (shown as a remark)
#*Runway Visual Range (RVR)
#**R: Runway Designator, L/R/C as needed, “/”
#**P/M: Plus/Minus (US only)
#**4 digit value (feet/meters)
#**V (variability) with tendency U/D/N (up/down/no change)
#**Example: R18R/1200FTV/U
#Present Weather (Constructed sequentially):
#*Intensity
#*Descriptor
#*Precipitation (Dominant type is listed first if more than one type reported)
#*Obscuration
#*Other
#Sky Cover
#*Cloud Description
#**Amount in eights (octas)
#**SKC=Sky Clear (clear below 12,000 for ASOS/AWOS)
#**NSC=No significant clouds
#**FEW=Few (1/8 to 2/8 sky cover)
#**SCT=Scattered (3/8 to 4/8 sky cover)
#**BKN=Broken (5/8 to 7/8 sky cover)
#**OVC=Overcast (8/8 sky cover)
#Temperature/Dewpoint (whole °C) (preceded by M=minus)
#*First 2 digits = temperature
#*Second 2 digits = dewpoint
#Altimeter setting (QNH) and indicator (A=InHg, Q=hPa)
#Supplementary Information
#*RE = Recent weather followed by weather codes
#*WS = Windshear, followed by:
#**TKOF/LDG (takeoff/landing)
#**RWY (2 digits runway identifier and designator L/R/C)
#*RMK = Remark
#**SLP = Sea Level Pressure
#**T00221083 (Expanded temp/dewpoint)
#**1st, 5th digits: 0=plus, 1=minus
#**2nd-4th digits: temp (decimal missing) (02.2)
#**6th-8th digits: dewpoint (decimal missing) (-8.3)
#Trend Forecast (2 hours from time of observation) (Not used in US)
#*PROB and 2 digits (30 or 40) = probability 30% or 40%
#*Used to indicate the probability of occurance of alternate element(s) or temporary fluctuations
#*Change Indicator
#**BECMG = Becoming (used where changes are expected to reach or pass through specified values
#**TEMPO = Temporary (fluctuations of less than one hour duration
#**NOSIG = No significant change
#*Forecast Wind (same as item 4)
#*Forecast Visibility (as item 5) (9999 indicates 10Kilometers vis or greater)
#*Forecast Weather (as item 6)
#*Forecast Cloud (as item 7)

== TAF ==
In meteorology and aviation, TAF is a format for reporting weather forecast information, particularly as it relates to aviation. "TAF" is an acronym of Terminal Aerodrome Forecast or, in some countries, Terminal Area Forecast. Generally, TAF's can apply to a 9- or 12-hour forecast; some TAFs cover an 18- or 24-hour period; and as of November 5,2008, TAFs for some major airports cover 30 hours periods. The date/time group reflects the new 30 hour period in Coordinated Universal Time (UTC), as always.

===Explanation===
This TAF example of a 30-hour TAF, released on November 5 2008 at 1730 UTC:

<pre>TAF KXYZ 051730Z 0518/0624 31008KT
3SM -SHRA BKN020
FM052300 30006KT 5SM -SHRA OVC030
PROB30 0604/0606 VRB20G35KT 1SM
TSRA BKN015CB
FM 060600 250010KT 4SM -SHRA OVC050
TEMPO 0608/0611 2SM -SHRA OVC030=
RMK NXT FCST BY 00Z=</pre>

The first line contains identification and validity times.
*'''TAF''' indicates that the following is a terminal area forecast.
*'''KXYZ''' indicates the airport to which the forecast applies (ICAO airport code).
*'''051730Z''' indicates that the report was issued at 1730 UTC on the 5th of the month.
*'''0518/0624''' indicates that the report is valid from 1800 UTC on the 5th until 2400 UTC on the following day.

The remainder of the first line and the second line contain the initial forecast conditions. Variations of the codes used for various weather conditions are many.
*'''31008KT''' indicates that the wind will be from 310 degrees at 8 knots.
*'''3SM -SHRA BKN020''' indicates that visibility will be 3SM (statute miles) in light (-) showers (SH) of rain (RA), with a broken ceiling (at least 5/8 of the sky covered) at 2,000 feet.

Each line beginning with '''FM''' starts a new forecast period.
*'''FM052300''' indicates the next period lasts from (FM) 2300 UTC on the 5th to 0000 UTC on the 6th.
The remainder of the line has similar formatting to the other forecast lines.

The final line is for errata, comments, and remarks.
*'''RMK NXT FCST BY 00Z''' indicates a remark that the next forecast will be issued by 0000 UTC.

===External Links===
* [http://aviationweather.gov/static/help/taf-decode.php Decoding a TAF]

==Related content==
* [[Howto: Fetch live aloft data]]

[[Category:FlightGear feature]]

Building FlightGear - Debian

2010-07-21T08:17:58Z

Moksha: /* Build and install */ improve phrasing

= HowTo build on Debian =

HowTo build FlightGear 2.0.0 or CVS on GNU/Linux Debian '''Stable''' 5.x (Lenny).

This HowTo may also work with '''Testing'''/'''Unstable''' except that some things are easier because of more up to date packages. So, before fetching something check the version of the available -dev package for it.

It even *should* work with '''Etch''', but I am not certain about some dependencies. [http://wiki.flightgear.org/index.php?title=Talk:Building_Flightgear_-_Debian&action=edit Reports] are welcome.

If you don't want to make your hands dirty, have a look at [[Scripted_Compilation_on_Linux_Debian/Ubuntu]].

== Requirements and Preparations ==
You need an OpenGL capable graphics including a proper installed driver.<BR>

Also a bunch of packages (and some of their dependencies) are required:
*gcc, g++, make, automake1.9, pkg-config
*mawk (or gawk)
*cmake (min. version 2.6.0-5, for Etch available on backports.org!)
*cvs, subversion, wget

*freeglut3-dev, libgl1-mesa-dev, libxrandr-dev
*libxi-dev, libxmu-dev, libxext-dev
*libopenal-dev (see [[#libopenal|libopenal]]), libalut-dev
*libjpeg62-dev, libtiff4-dev, libpng12-dev
*libboost1.37-dev (Not available for Lenny atm, see [[#Boost Library|Boost Library]] below.)

During installation packages ''simgear-dev'' and ''openscenegraph-dev'' *must not* be installed. They can safely be re-installed after compilation.

== Build and install ==
Because we are going to install versions different to the ones in the repositries it is recommended to install FG-2.0.0 and/or CVS in a place independent to the base system such as /usr/local/FG-2.0.0, /opt/FG-2.0.0 or in a subdirectory of your $HOME. I suggest to make it writeable by the user that there is no need to become root for the <code>make install</code> commands. I'll use <code>$prefix</code> as a placeholder for this directory. <BR>
Another one will be <code>$srcdir</code>, it stands for the absolute path to the directory which contains the folders of the various source codes. So in the following instructions you have to replace these with the local paths or even <code>export</code> them during the process.

Follow the instructions to fetch the sources and the data needed by FlightGear and the commands to build/install each source.

Have in mind that the data is relatively large (CVS about 2 GB and 2.0.0 300 MB) so, to save some time, it is a good idea to fetch it while building the sources.

=== libopenal ===
The libopenal-dev package in Lenny/Etch is too old for [[fgcom]]. For FlightGear it does work but not all features (like Doppler) are available, so installing an up to date version is recommended anyway.
cd $srcdir
wget http://kcat.strangesoft.net/openal-releases/openal-soft-1.11.753.tar.bz2
tar xjf openal-soft-1.11.753.tar.bz2
cd openal-soft-1.11.753/build
cmake -D CMAKE_INSTALL_PREFIX:PATH="$prefix" ..
make install

=== plib ===
Latest SVN is [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg20793.html recommended], yet package plib1.8.5-dev for Testing/Unstable does work as well.
cd $srcdir
svn co https://plib.svn.sourceforge.net/svnroot/plib/trunk plib
cd plib
sed s/PLIB_TINY_VERSION\ \ 5/PLIB_TINY_VERSION\ \ 6/ -i src/util/ul.h
./autogen.sh
./configure --prefix=$prefix
make install

=== Boost Library ===
Version 1.37 is needed. At least for Lenny/Etch this means getting the sources because this is not available atm on backports.org. Testing/Unstable users may have more luck and a package is available, libboost-1.37-dev or newer.

To build SimGear, FlightGear, fgrun and fgcom some boostlib header files are required, no need to compile and install it. If you have installed a libboost1.37-dev (or higher) package on your system you don't have to bother at all with it. If not, you have to tell each ./configure where the header files are. To do so, add the option <code>CPPFLAGS=-I$prefix/include</code> to the SimGear, FlightGear and fgrun <code>./configure</code> commands. We copy the header files to $prefix/include because fgcom will need them there.

Get the newest version tar ball from http://sourceforge.net/projects/boost/files/boost/, extract it into <code>$srcdir</code> then:
cp -R $srcdir/boost-[version]/boost/ $prefix/include/

=== OpenSceneGraph ===
For FlightGear 2.0.0 one may use the latest (or at least 2.9.6) developer release from http://www.openscenegraph.org/projects/osg/wiki/Downloads/DeveloperReleases and extract it into <code>$srcdir</code>.

Mostly this is ok for FlightGear CVS as well as it is stable. However, sometimes the release is not fresh enough and one have to get the latest developments via SVN:
cd $srcdir
svn co http://www.openscenegraph.org/svn/osg/OpenSceneGraph/trunk OpenSceneGraph

cmake demands a build directory separate to its source directory. So <code>mkdir</code> one and <code>cd</code> into it.
cmake -D CMAKE_BUILD_TYPE="Release" -D CMAKE_CXX_FLAGS="-O3" -D CMAKE_C_FLAGS="-O3" \
-D CMAKE_INSTALL_PREFIX:PATH="$prefix" $srcdir/OpenSceneGraph[-version]
make install

=== SimGear ===
2.0.0:
cd $srcdir
wget http://mirrors.ibiblio.org/pub/mirrors/simgear/ftp/Source/SimGear-2.0.0.tar.gz
tar xzf SimGear-2.0.0.tar.gz
cd SimGear-2.0.0

CVS:
cd $srcdir
git clone git://gitorious.org/fg/simgear.git simgear
cd simgear
./autogen.sh

2.0.0 and CVS:
./configure --prefix=$prefix [CPPFLAGS=-I$prefix/include LDFLAGS="-L$prefix/lib -L$prefix/lib64"]
make install

=== FlightGear source ===
2.0.0:
cd $srcdir
wget http://mirrors.ibiblio.org/pub/mirrors/flightgear/ftp/Source/FlightGear-2.0.0.tar.gz
tar xzf FlightGear-2.0.0.tar.gz
cd FlightGear-2.0.0

CVS:
cd $srcdir
git clone git://gitorious.org/fg/flightgear.git flightgear
cd flightgear
./autogen.sh

2.0.0 and CVS:
./configure --prefix=$prefix [CPPFLAGS=-I$prefix/include/ LDFLAGS="-L$prefix/lib -L$prefix/lib64"]
make install

=== FlightGear data ===
2.0.0:
cd $prefix
wget http://mirrors.ibiblio.org/pub/mirrors/flightgear/ftp/Shared/FlightGear-data-2.0.0.tar.bz2
tar xjf FlightGear-data-2.0.0.tar.bz2

GIT:
cd $prefix
git clone git://gitorious.org/fg/fgdata.git data

Or to Fetch A bundle that can be Downloaded in parts :
cd $prefix
wget http://peter-server.homelinux.net/fgdata/fgdata/fgdata.bundle

=== Trial run ===
When all the builds are done and the data download has finished it is time for a test run:
export LD_LIBRARY_PATH=$prefix/lib/:$LD_LIBRARY_PATH
$prefix/bin/fgfs --fg-root=$prefix/data

For the future, if you want to start FlightGear from command line have a look at [[fgfsrc]], if you prefer a graphical user interface continue with [[#fgrun|compiling fgrun]]. Have in mind that fgfs need to find our self compiled libraries and therefore we have to tell the linker (ld) where to find them. That is what the first line here does.

== Optional Software ==

=== fgrun ===
To build [[fgrun]] two more package is required:
*libfltk1.1-dev fluid

cd $srcdir
svn co http://fgrun.svn.sourceforge.net/svnroot/fgrun/trunk fgrun
cd fgrun
./autogen.sh
./configure --prefix=$prefix [CPPFLAGS=-I$prefix/include/]
make install

=== fgcom ===
For [[fgcom]] unfortunately there is one more dependency which cannot be solved with packages on Lenny/Etch, see [[#libopenal|libopenal]].

cd $srcdir
svn co https://appfgcom.svn.sourceforge.net/svnroot/fgcom/trunk fgcom
cd fgcom/src
make INSTALL_BIN=$prefix/bin INSTALL_DIR=$prefix/fgcom \
PLIB_PREFIX=$prefix OPENAL_PREFIX=$prefix install



{{Building}}

[[de:FlightGear_bauen_-_Debian]]

Building FlightGear - Debian

2010-07-21T08:13:58Z

Moksha: /* Build and install */ improve phrasing

= HowTo build on Debian =

HowTo build FlightGear 2.0.0 or CVS on GNU/Linux Debian '''Stable''' 5.x (Lenny).

This HowTo may also work with '''Testing'''/'''Unstable''' except that some things are easier because of more up to date packages. So, before fetching something check the version of the available -dev package for it.

It even *should* work with '''Etch''', but I am not certain about some dependencies. [http://wiki.flightgear.org/index.php?title=Talk:Building_Flightgear_-_Debian&action=edit Reports] are welcome.

If you don't want to make your hands dirty, have a look at [[Scripted_Compilation_on_Linux_Debian/Ubuntu]].

== Requirements and Preparations ==
You need an OpenGL capable graphics including a proper installed driver.<BR>

Also a bunch of packages (and some of their dependencies) are required:
*gcc, g++, make, automake1.9, pkg-config
*mawk (or gawk)
*cmake (min. version 2.6.0-5, for Etch available on backports.org!)
*cvs, subversion, wget

*freeglut3-dev, libgl1-mesa-dev, libxrandr-dev
*libxi-dev, libxmu-dev, libxext-dev
*libopenal-dev (see [[#libopenal|libopenal]]), libalut-dev
*libjpeg62-dev, libtiff4-dev, libpng12-dev
*libboost1.37-dev (Not available for Lenny atm, see [[#Boost Library|Boost Library]] below.)

During installation packages ''simgear-dev'' and ''openscenegraph-dev'' *must not* be installed. They can safely be re-installed after compilation.

== Build and install ==
Because we are going to install versions different to the ones in the repositries it is recommended to install FG-2.0.0 and/or CVS in a place independent to the base system such as /usr/local/FG-2.0.0, /opt/FG-2.0.0 or in a subdirectory of your $HOME. I suggest to make it writeable by the user that there is no need to become root for the <code>make install</code> commands. I'll use <code>$prefix</code> as a placeholder for this directory. <BR>
Another one will be <code>$srcdir</code>, it stands for the absolute path to the directory which contains the folders of the various source codes. So in the following instructions you have to replace these with the local paths or even <code>export</code> them during the process.

Subsequent the instructions to fetch the sources and the data needed by FlightGear and the commands to build/install each source.

Have in mind that the data is relatively huge (CVS about 2 GB and 2.0.0 300 MB) so, to save some time, it is a good idea to fetch it while building the sources.

=== libopenal ===
The libopenal-dev package in Lenny/Etch is too old for [[fgcom]]. For FlightGear it does work but not all features (like Doppler) are available, so installing an up to date version is recommended anyway.
cd $srcdir
wget http://kcat.strangesoft.net/openal-releases/openal-soft-1.11.753.tar.bz2
tar xjf openal-soft-1.11.753.tar.bz2
cd openal-soft-1.11.753/build
cmake -D CMAKE_INSTALL_PREFIX:PATH="$prefix" ..
make install

=== plib ===
Latest SVN is [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg20793.html recommended], yet package plib1.8.5-dev for Testing/Unstable does work as well.
cd $srcdir
svn co https://plib.svn.sourceforge.net/svnroot/plib/trunk plib
cd plib
sed s/PLIB_TINY_VERSION\ \ 5/PLIB_TINY_VERSION\ \ 6/ -i src/util/ul.h
./autogen.sh
./configure --prefix=$prefix
make install

=== Boost Library ===
Version 1.37 is needed. At least for Lenny/Etch this means getting the sources because this is not available atm on backports.org. Testing/Unstable users may have more luck and a package is available, libboost-1.37-dev or newer.

To build SimGear, FlightGear, fgrun and fgcom some boostlib header files are required, no need to compile and install it. If you have installed a libboost1.37-dev (or higher) package on your system you don't have to bother at all with it. If not, you have to tell each ./configure where the header files are. To do so, add the option <code>CPPFLAGS=-I$prefix/include</code> to the SimGear, FlightGear and fgrun <code>./configure</code> commands. We copy the header files to $prefix/include because fgcom will need them there.

Get the newest version tar ball from http://sourceforge.net/projects/boost/files/boost/, extract it into <code>$srcdir</code> then:
cp -R $srcdir/boost-[version]/boost/ $prefix/include/

=== OpenSceneGraph ===
For FlightGear 2.0.0 one may use the latest (or at least 2.9.6) developer release from http://www.openscenegraph.org/projects/osg/wiki/Downloads/DeveloperReleases and extract it into <code>$srcdir</code>.

Mostly this is ok for FlightGear CVS as well as it is stable. However, sometimes the release is not fresh enough and one have to get the latest developments via SVN:
cd $srcdir
svn co http://www.openscenegraph.org/svn/osg/OpenSceneGraph/trunk OpenSceneGraph

cmake demands a build directory separate to its source directory. So <code>mkdir</code> one and <code>cd</code> into it.
cmake -D CMAKE_BUILD_TYPE="Release" -D CMAKE_CXX_FLAGS="-O3" -D CMAKE_C_FLAGS="-O3" \
-D CMAKE_INSTALL_PREFIX:PATH="$prefix" $srcdir/OpenSceneGraph[-version]
make install

=== SimGear ===
2.0.0:
cd $srcdir
wget http://mirrors.ibiblio.org/pub/mirrors/simgear/ftp/Source/SimGear-2.0.0.tar.gz
tar xzf SimGear-2.0.0.tar.gz
cd SimGear-2.0.0

CVS:
cd $srcdir
git clone git://gitorious.org/fg/simgear.git simgear
cd simgear
./autogen.sh

2.0.0 and CVS:
./configure --prefix=$prefix [CPPFLAGS=-I$prefix/include LDFLAGS="-L$prefix/lib -L$prefix/lib64"]
make install

=== FlightGear source ===
2.0.0:
cd $srcdir
wget http://mirrors.ibiblio.org/pub/mirrors/flightgear/ftp/Source/FlightGear-2.0.0.tar.gz
tar xzf FlightGear-2.0.0.tar.gz
cd FlightGear-2.0.0

CVS:
cd $srcdir
git clone git://gitorious.org/fg/flightgear.git flightgear
cd flightgear
./autogen.sh

2.0.0 and CVS:
./configure --prefix=$prefix [CPPFLAGS=-I$prefix/include/ LDFLAGS="-L$prefix/lib -L$prefix/lib64"]
make install

=== FlightGear data ===
2.0.0:
cd $prefix
wget http://mirrors.ibiblio.org/pub/mirrors/flightgear/ftp/Shared/FlightGear-data-2.0.0.tar.bz2
tar xjf FlightGear-data-2.0.0.tar.bz2

GIT:
cd $prefix
git clone git://gitorious.org/fg/fgdata.git data

Or to Fetch A bundle that can be Downloaded in parts :
cd $prefix
wget http://peter-server.homelinux.net/fgdata/fgdata/fgdata.bundle

=== Trial run ===
When all the builds are done and the data download has finished it is time for a test run:
export LD_LIBRARY_PATH=$prefix/lib/:$LD_LIBRARY_PATH
$prefix/bin/fgfs --fg-root=$prefix/data

For the future, if you want to start FlightGear from command line have a look at [[fgfsrc]], if you prefer a graphical user interface continue with [[#fgrun|compiling fgrun]]. Have in mind that fgfs need to find our self compiled libraries and therefore we have to tell the linker (ld) where to find them. That is what the first line here does.

== Optional Software ==

=== fgrun ===
To build [[fgrun]] two more package is required:
*libfltk1.1-dev fluid

cd $srcdir
svn co http://fgrun.svn.sourceforge.net/svnroot/fgrun/trunk fgrun
cd fgrun
./autogen.sh
./configure --prefix=$prefix [CPPFLAGS=-I$prefix/include/]
make install

=== fgcom ===
For [[fgcom]] unfortunately there is one more dependency which cannot be solved with packages on Lenny/Etch, see [[#libopenal|libopenal]].

cd $srcdir
svn co https://appfgcom.svn.sourceforge.net/svnroot/fgcom/trunk fgcom
cd fgcom/src
make INSTALL_BIN=$prefix/bin INSTALL_DIR=$prefix/fgcom \
PLIB_PREFIX=$prefix OPENAL_PREFIX=$prefix install



{{Building}}

[[de:FlightGear_bauen_-_Debian]]

Howto:Make a clickable panel

2010-06-06T05:59:54Z

Moksha: /* Pick */ improve sentence structure

There are two methodes to '''make a clickable planel''' in [[FlightGear]] at the moment:
* '''Hotspot:''' adds a clickable (invisible) face at a certain position.
* '''Pick:''' makes a whole object clickable.

The easiest to use is pick, since you do not have to look up all the coordinates. Also the pick animation is more realistic and therefore more often used.

==Hotspot==
The hotspot animation is somewhat complicated. You have to define the x and y coordinates of every clickable "face" (hotspot) aswell the width and heigth of the hotspot to click on. See the following example of the [[Boeing 777-200|777-200]].

===Panel file===

Make a new panel file (.xml) in your aircrafts directory. The following lines are only placed on top of the file:

<PropertyList>

<name>777-200 Overhead Panel</name>
<background>Aircraft/777-200/Panels/transparent-bg.rgb</background>
<w>256</w>
<h>512</h>

<instruments>

<instrument>
<name>panel hotspots</name>
<x>128</x>
<y>256</y>
<w>256</w>
<h>512</h>
<w-base>256</w-base>
<h-base>512</h-base>

<actions>

Now all hotspots need to be listed as seperate actions:

<action>
<name>Master Battery Switch</name>
<button>0</button>
<x>-278</x>
<y>-188</y>
<w>10</w>
<h>10</h>
<binding>
<command>property-toggle</command>
<property>/controls/electric/battery-switch</property>
<step>1</step>
<min>0</min>
<max>1</max>
<wrap>true</wrap>
</binding>
</action>

We end the file with:

</actions>
</instrument>
</instruments>

</PropertyList>

===Model file===
Now we need to link to this file from our model's file. Add something similar to the following in your model file:

<panel>
<path>Aircraft/777-200/Panels/oh-panel.xml</path>
<bottom-left>
<x-m>-23.396</x-m>
<y-m>-0.522</y-m>
<z-m>0.992</z-m>
</bottom-left>
<bottom-right>
<x-m>-23.396</x-m>
<y-m>0.522</y-m>
<z-m>0.992</z-m>
</bottom-right>
<top-left>
<x-m>-22.686</x-m>
<y-m>-0.522</y-m>
<z-m>1.323</z-m>
</top-left>
</panel>

==Pick==
For 3D clickable object we can use the pick-animation. It makes a whole object clickable. This is especially easy to use with switches.

Add the following code to the .xml file of your panel. Remember to change the object-name into your buttons/knobs/switches name (!) and set the property to the property, corresponding with your button.

<animation>
<type>pick</type>
<object-name>Seatbelt-Sign-Button</object-name>
<action>
<button>0</button>
<repeatable>false</repeatable>
<binding>
<command>property-toggle</command>
<property>controls/switches/seatbelt-sign</property>
<value>0</value>
<value>1</value>
</binding>
</action>
</animation>

You can also use the property-cycle command if you want to cycle through multiple values.

If you want to have an adjustable value (like the knob on radios) you can use the property adjust command, like this:

<animation>
<type>pick</type>
<object-name>Ingh-Knob-Right</object-name>
<action>
<button>0</button>
<repeatable>false</repeatable>
<interval-sec>0.2</interval-sec>
<binding>
<command>property-adjust</command>
<property>instrumentation/altimeter/setting-inhg</property>
<step>0.005</step>
<min>26.0</min>
<max>33.0</max>
<wrap>false</wrap>
</binding>
</action>
</animation>

Setting repeatable to true will make it able to hold a knob or switch.

To check if the pick animation works (on the correct button) we launch FlightGear and click Ctrl-C. Now all clickable objects will get a yellow lining.

[[Category:Aircraft enhancement]]
[[Category:Howto|Make a clickable panel]]

Blohm & Voss Bv 141

2010-05-09T09:25:00Z

Moksha: /* External links */ valid link

{{stub}}

bv141: Blohm und Voss BV141
bv141-yasim: Blohm und Voss BV141 (YASim)
Author: BARANGER Emmanuel (3D)

=== See also ===
*[[Table of models]]

== External links ==
*[http://helijah.free.fr/flightgear/hangar.htm Helijah's Hangar]
*http://www.flightgear.org/Downloads/aircraft/
*http://en.wikipedia.org/wiki/Blohm_%2B_Voss_BV_141

[[Category:Aircraft]]
[[Category:Aircraft TODO]]s

Dual control

2010-05-04T06:49:30Z

Moksha: /* Usage instruction */ typos and improve sentences

'''Dual Control''' is a system for [[FlightGear]] that adds basic support for shared control of an [[aircraft]] over the FlightGear [[Multiplayer Howto|multiplayer network]].

'''Note:''' [[FlightGear 1.9.0]] or later is needed to use Dual Control.

==Aircraft==

Currently there are a small number of aircraft with dual control support:
* [[Zeppelin NT]], pilot and copilot (<tt>ZLT-NT</tt>, <tt>ZLT-NT-copilot</tt>). Available in FlightGear 1.9.0 and later.
* [[Blackburn Buccaneer]], pilot and systems officer (<tt>buccaneer</tt>, <tt>buccaneer-obs</tt>). Available in FlightGear 1.9.0 or later.
* [[Grumman_F-14_Tomcat]], pilot and RIO (<tt>f-14b</tt>, <tt>f-14b-bs</tt>). Available in FlightGear/CVS.
* [[Submarine_Scout]], pilot and observer (<tt>Submarine_Scout</tt>, <tt>Submarine_Scout-observer</tt>). Available in FlightGear/CVS.
* [[Boeing 747-400]], pilot flying and pilot monitoring (<tt>747-400</tt>, <tt>747-400-fo</tt>). Available in FlightGear/CVS.
* [[Storch|Fieseler Fi 156 Storch]], pilot and passenger (<tt>Fi-156-de</tt>, <tt>Fi-156-passenger</tt>). Available in FlightGear/CVS.
* [[ASK-13 sailplane|Schleicher ASK-13 glider]], pilot and passenger (<tt>ask13</tt>, <tt>ask13-passenger</tt>). Available in FlightGear/CVS.
* c172p Skyhawk, pilot and copilot (<tt>c172p-pilot</tt> and <tt>c172p-copilot</tt>). Based on David Megginson's [[Cessna C172|c172p]] single control aircraft. Available from [http://www.gidenstam.org/FlightGear/DualControl/Aircraft the dual-control aircraft hangar]. The tar.gz archive for the aircraft should be extracted in $FG_ROOT/Aircraft/.

To connect the pilot and copilot selects each other in the Copilot dialog (FlightGear/CVS) or set properties as explained in the usage instructions below.

Dual control enables a pilot and copilot to jointly fly the aircraft over the FlightGear multiplayer network. Depending on the aircraft the pilot and copilot have shared control over primary flight controls, throttle, mixture and so on. Exactly which controls are shared varies between the aircraft but usually include elevator trim, flaps, brakes, cockpit switches, the radio stack and some instrument settings. The copilot usually has a subset of the full instrumentation (also depending on the aircraft), usually including airspeed, altimeter, VSI, HSI, turn coordinator, engine RPM and the radio stack. Typically Nav/Comm 1 and the first VOR indicator is best controlled by the pilot, while Nav/Comm 2 and the corresponding VOR indicator is faster for the copilot.

<center>
[[Image:ZLT-NT-dual.jpg]]
</center>
<center>
''Side-by-side presentation of the Zeppelin NT pilot's (left) and copilot's (right) views.''
</center>

==Usage instruction==
The system consists of two "aircraft":

The pilot uses a special variant of the c172p, <tt>c172p-pilot</tt>. The pilot needs to specify the callsign of the copilot (other copilots will be ignored).
For the Zeppelin NT the aircraft names are <tt>ZLT-NT</tt> and <tt>ZLT-NT-copilot</tt>, respectively.

In the current version the pilot and copilot can select each other in their Co/Pilot selection dialogs available from the "Zeppelin NT/c172p-dual-control"->"MP-(Co)Pilot" menus.

Alternatively the relevant properties can be set from the command line or via the property browser.

'''Pilot usage example:'''
fgfs --aircraft=c172p-pilot --prop:/sim/remote/pilot-callsign="someone"

The copilot uses a special "aircraft", c172p-copilot, which piggybacks on the designated pilot and captures the local control inputs. A current limitation is that only the cockpit views are jitter free. There is also a noticeable delay between control inputs and effect, since they are passed via the the multiplayer protocol. The severity of this delay depend on round trip time and some other factors - the delay seems significantly longer than the round trip time itself which is due to buffering in the MP protocol receiver. That said, I have flown successfully as copilot in a setup with 100-120ms round trip time between both pilot and server and copilot and server (total delay >500ms). Landing is a bit exciting in that case, however.

'''Copilot usage example:'''
fgfs --aircraft=c172p-copilot --prop:/sim/remote/pilot-callsign="anybody"
Note: External views are jitter prone for the copilot.

== Developer information ==

The main part of the Dual Control system is a set of generic [[Nasal scripting language|Nasal]] modules and modified instrument files that form the core of the networked shared control functionality. See the link below for some more information.

==External links==

* [http://www.gidenstam.org/FlightGear/DualControl The main page for the Dual Control system.] Check here for the latest information.

[[Category:FlightGear feature]]

[[es:Control dual]]

Grumman G-21 Goose

2010-05-04T03:26:46Z

Moksha:

{{infobox Aircraft
|image =Goose.JPG
|name =Grumman G21 Goose
|type =
|livery =
|authors =
|status =
|fdm =
|3dcockpit =
|carrier =
|fgname = goose
|download =http://www.emmerich-j.de/FGFS/Goose7.zip
}}
The '''Grumman G21 Goose''' is an eight seater amphibious aircraft, it first entered service in 1937, and saw service in WW2 with the US coastguard.

Boeing B-17 Flying Fortress

2010-05-04T03:16:39Z

Moksha: improve sentence

{{stub}}
{{infobox Aircraft
|image =B17.jpg
|name =B-17 Flying Fortress
|livery =USAAC
|type = 4 radial engine bomber
|fdm =YASim
|status =Development
|authors =Emmanuel Baranger
|fgname =b17
|download =http://helijah.free.fr/flightgear/hangar.htm
}}
The '''Boeing B-17 Flying Fortress''' is a four radial piston engine [[aircraft]] that first flew in 1935, and went on to serve as a [[:Category:Military aircraft|bomber]] in the 1940s. Some survive in flying condition into the 21st century as flying museum aircraft.

{{Boeing}}

[[Category:Aircraft]]
[[Category:Historical aircraft]]
[[Category:Military aircraft]]

Fokker 50

2010-05-04T03:06:48Z

Moksha: add piped link

{{non-stable}}

{{infobox Aircraft
|image =Fokker50.jpg
|alt =Fokker 50 in Denim Air livery
|name =Fokker 50
|type =Airliner
|livery=[[Air San Francisco]], Denim Air, [[:Category:Fokker|Fokker]], [[Island Virtual Airways]], KLM, VLM
|fdm =[[JSBSim]]
|status =Early-development
|authors =Erik Hofman, Charlie Andrews
|fgname =fokker50
}}[[Image:Fokker50_fokker.jpg|thumb|right|270px|A Fokker 50 in the manufacturer livery of Fokker.]]

The '''Fokker 50''' is a 2 turboprop [[:Category:Airliners|airliner]].

The first Fokker 50 can be seen at the Dutch [[Aviodrome]] museum (at [[Lelystad Airport]] in the Netherlands).

==Aircraft help==
The cockpit lighting can be switched on and off on the central console. Look down and right! That only works in [[OpenSceneGraph|OSG]], as do the other clickable cockpit objects.

To twiddle knobs (OSG only again, I'm afraid! Use LMB to increment by 1, MMB to decrement by one. The scroll wheel increases and decreases in larger steps. At least it will if your mouse buttons are mapped in the same way that mine are! Hold the mouse cursor over the standby digits of NAV/COM/ADF boxes to adjust, then press the button to flip the freqs. You can also adjust CDIs and the heading bug using the FMP on the glareshield.

===Takeoff===
* Rotate at approx 95 kts.

===Landing===
* Vref (target speed for crossing the threshold on landing) will be fine at about 95 kts again, with flap 25
** 35 is the max flap setting, use it for steep approaches only

[[Image:Fokker50_KLM.jpg|thumb|270px|Fokker 50 in KLM colors.]]
== Development status/Issues/Todo ==
'''3D Cockpit:'''
* 3D cockpit being modelled, co-ordinated by FokkerCharlie.
* Some cockpit furniture still missing
* Power Lever quadrant not textured

'''General:'''
* Engine sound in cockpit does not differ from outside engine sound
* Engines and props could use some tuning, prop ground range not yet modelled.
* Antialiasing ugliness (still) on the EFIS display.

== External links ==
The Fokker 50 FlightGear Forum threads:
* http://www.flightgear.org/forums/viewtopic.php?p=2691#2691
* http://www.flightgear.org/forums/viewtopic.php?t=345

{{Fokker}}

[[Category:Aircraft]]
[[Category:Aircraft TODO]]
[[Category:Airliners]]
[[Category:Civilian aircraft]]

UIUC

2010-05-04T03:03:22Z

Moksha: spelling

{{stub}}

'''UIUC''' is the name of a [[Flight Dynamics Model]] for [[FlightGear]] flight simulator. It was developed by the UIUC Applied Aerodynamics Group at University of Illinois at Urbana-Champaign. It was devloped in the early 2000s and has been used by many aircraft in FG. See [[Table of models]].

UIUC made use of [[LaRCsim]] and was "originally developed for the [[Smart Icing System Project]]" [http://www.ae.uiuc.edu/m-selig/apasim/Aircraft-uiuc.html]

Many aircraft were worked on for FlightGear with UIUC, although many were not GPL or not maintained. There some that that were maintained well enough to survive until [[FlightGear 1.0.0]] and expanded with new models, and even used for other FDM.

Some UIUC v-1 aircraft include:

*a4-v1-nl/
*airwaveXtreme150-v1-nl/
*asw20-v1-nl/
*beech99-v1/
*fkdr1-v1-nl/
*marchetti-v1/
*ornithopter/
*sopwithCamel-v1-nl/
*sopwithCamel-v2-nl/
*wrightFlyer1903-v1-nl/

==External links==
*http://www.ae.uiuc.edu/m-selig/apasim/Aircraft-uiuc.html

{{FDM}}

Eurocopter EC135

2010-05-03T23:28:10Z

Moksha: minor typos and English fixes

{{non-stable}}

{{infobox Aircraft
|image =Ec135.png
|name =Eurocopter EC135
|type =Helicopter
|livery= ADAC, ANWB, ÖAMTC, Prototype
|fdm =YASim
|status =v0.4 in 1.9.1
|authors =Heiko Schulz, Maik Justus, Melchior Franz
|fgname =<tt>ec135</tt>
}}This is an model of the '''Eurocopter EC135''', a light twin-engine, multi-mission [[helicopter]].

Eurocopter has two version of it: the EC 135 P2i and the EC 135 T2i
P2 stands for the PRATT and WHITNEY PW 206B2 turbine engine with 743 PS (horsepower).
T2 stands for TURBOMECA Arrius 2B2 turbine engine with 706 PS.
The EC 135 descends from the MBB Bo 108. The Bo 108 was a demonstration prototype for fly-by-wire and has it's descent from the famous Bo 105.
When the Eurocopter company was founded, the Bo 108 came with.
Eurocopter decided that there was a marketplace for such a helicopter and the development went on.
From the French partners it got the fenestron, from MBB the hingeless rotor.
The fenestron makes it very hard for dangerous situations in the range of the tail rotor and reduces the noise level about 50% to other helicopters
That's why the EC 135 is a highly recommended helicopter for EMS and the police, especially in Europe but also in the USA, Japan and other states.

The models Includes the German ADAC version, the Austrian ÖAMTC version, the Dutch ANWB (Lifeliner) version and the EC135-prototype version as default

== Development status/Issues/Todo ==
[[Image:Ec135_LFLJ.jpg|thumb|right|270px|EC 135 "D-HECZ" (prototype) takes off above the clouds at Courchevel; see [[Flying the helicopter]] ]]

=== Actual version: v.0.6 (CVS)===

* fixes wrong rotorshaft tilt in fdm
* some bugfixes on fuselage
* sound fixed

very next To-Do:
* rotor model and animation
* bugfixing on windscreen
* instruments finishing

=== Actual version: v.0.5 (CVS)===

* photorealistic panel
* liveries improved
* better fps-perfomance while changing liveries

=== Actual version: v.0.4 (FGFS 1.9.1 release)===

This is a complete rebuild of the ec135 with a much better exterior
model It is currently a work in progress, so a lots of things can be
broken now, but it should be not worser to fly than in the last version.

* complete new exterior with added antennas and other mounting parts(search lights, cameras)
* glas shader with fresnel effect
* variants changing over mp
* better texture mapping so it should be easy to make your own livery

Currently in Progress at this date:
* replacing the panels and adding the digital version with a nearly photorealistic one!
* adding the overhead
* making it all clickable and working from the cockpit
* better interior : EMS and VIP-version
* remade D-HECZ-Livery
* mapped ec135 with D-HECZ-Livery
* added ADAC Chr. 23-Livery made with photorealistic parts like Fenestron and Logos- still some things missing like lines
* added phtorealistic textures to exhaust and rails
* adding and finishing the missing liveries like the OEAMTC, G-SASA, Bavarian Police
* adding the high skid model

=== Actual version: v.0.2 ===

* fully new made 3D-model - matching real good to the real one
* improved interior with stick and pedals
* changed variants: ADAC Chr. 31 "Berlin", D-HECZ "second prototype", ÖAMTC Christopherus 1
* improved cockpit with half analog IFR-panel
* HSI is now working, working VOR
* GSDI selectable
* improved and more detailed main rotor with incidence animation
* Fenestron now with the correct configuration of the blades: 1-4-1-4
* dynamic flight model now with the correct position of the CG
* added frontlight, retractable landinglight, strobes with the correct frequency, beacon with the correct frequency
* rotor brake system now working

To-Do:
* adding antennas and other mounting parts (search lights, cameras)
* fully clickable [[cockpit]] (half-analog and digital)
* complete light function
* variants with radardome
* variants with high-skid
* much more (international)variants!
* realistic dynamic flight model
* mainrotors much more detailed
* animation of the fenestron blades (incidence)
* sound still could be improved
* adding pilots figures

=== Actual version: v.0.1 ===

* first 3d-model of an ec135
* first try of an ec135-flight dynamic model
* livery changing
* two version: ADAC and Bavarian Police
* first version of the half analog cockpit
* doors to open

To-Do:
* better quality of the 3d-model
* full mainrotor animation
* better Fenestron
* improve cockpit, implementing a working HSI
* clean up the xml-files
* improve soundsystem
* realistic dynamic flight model
* selectable GSDI
* implementing rotor brake system
* more variants

== External links ==
[http://www.eurocopter.de www.eurocopter.de]

=== Related lists ===
* [[Aircraft]]
* [[Aircraft Todo]]

[[Category:Aircraft]]
[[Category:Helicopters]]
[[Category:Aircraft TODO]]

Building FlightGear - Debian

2010-04-18T12:23:32Z

Moksha: /* Boost Library */typo

= HowTo build on Debian =

HowTo build FlightGear 2.0.0 or CVS on GNU/Linux Debian '''Stable''' 5.x (Lenny).

This HowTo may also work with '''Testing'''/'''Unstable''' except that some things are easier because of more up to date packages. So, before fetching something check the version of the available -dev package for it.

It even *should* work with '''Etch''', but I am not certain about some dependencies. [http://wiki.flightgear.org/index.php?title=Talk:Building_Flightgear_-_Debian&action=edit Reports] are welcome.

If you don't want to make your hands dirty, have a look at [[Scripted_Compilation_on_Linux_Debian/Ubuntu]].

== Requirements and Preparations ==
You need an OpenGL capable graphics including a proper installed driver.<BR>

Also a bunch of packages (and some of their dependencies) are required:
*gcc, g++, make, automake1.9, pkg-config
*mawk (or gawk)
*cmake (min. version 2.6.0-5, for Etch available on backports.org!)
*cvs, subversion, wget

*freeglut3-dev, libgl1-mesa-dev, libxrandr-dev
*libxi-dev, libxmu-dev, libxext-dev
*libopenal-dev (see [[#libopenal|libopenal]]), libalut-dev
*libjpeg62-dev, libtiff4-dev, libpng12-dev
*libboost1.37-dev (Not available for Lenny atm, see [[#Boost Library|Boost Library]] below.)

During installation packages ''simgear-dev'' and ''openscenegraph-dev'' *must not* be installed. They can safely be re-installed after compilation.

== Build and install ==
Because we are going to install versions different to the ones in the repositries it is recommended to install FG-2.0.0 and/or CVS in a place independent to the base system such as /usr/local/FG-2.0.0, /opt/FG-2.0.0 or in a subdirectory of your $HOME. I suggest to make it writeable by the user that there is no need to become root for the <code>make install</code> commands. I'll use <code>$prefix</code> as a placeholder for this directory. <BR>
Another one will be <code>$srcdir</code>, it stands for the absolute path to the directory which contains the folders of the various source codes. So in the following instructions one have to replace these by the local paths or even <code>export</code> them during the process.

Subsequent the instructions to fetch the sources and the data needed by FlightGear and the commands to build/install each source.

Have in mind that the data is relatively huge (CVS about 2 GB and 2.0.0 300 MB) so, to save some time, it is a good idea to fetch it while building the sources.

=== libopenal ===
The libopenal-dev package in Lenny/Etch is too old for [[fgcom]]. For FlightGear it does work but not all features (like Doppler) are available, so installing an up to date version is recommended anyway.
cd $srcdir
wget http://kcat.strangesoft.net/openal-releases/openal-soft-1.11.753.tar.bz2
tar xjf openal-soft-1.11.753.tar.bz2
cd openal-soft-1.11.753/build
cmake -D CMAKE_INSTALL_PREFIX:PATH="$prefix" ..
make install

=== plib ===
Latest SVN is [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg20793.html recommended], yet package plib1.8.5-dev for Testing/Unstable does work as well.
cd $srcdir
svn co https://plib.svn.sourceforge.net/svnroot/plib/trunk plib
cd plib
sed s/PLIB_TINY_VERSION\ \ 5/PLIB_TINY_VERSION\ \ 6/ -i src/util/ul.h
./autogen.sh
./configure --prefix=$prefix
make install

=== Boost Library ===
Version 1.37 is needed. At least for Lenny/Etch this means getting the sources because this is not available atm on backports.org. Testing/Unstable users may have more luck and a package is available, libboost-1.37-dev or newer.

To build SimGear, FlightGear, fgrun and fgcom some boostlib header files are required, no need to compile and install it. If you have installed a libboost1.37-dev (or higher) package on your system you don't have to bother at all with it. If not, you have to tell each ./configure where the header files are. To do so, add the option <code>CPPFLAGS=-I$prefix/include</code> to the SimGear, FlightGear and fgrun <code>./configure</code> commands. We copy the header files to $prefix/include because fgcom will need them there.

Get the newest version tar ball from http://sourceforge.net/projects/boost/files/boost/, extract it into <code>$srcdir</code> then:
cp -R $srcdir/boost-[version]/boost/ $prefix/include/

=== OpenSceneGraph ===
For FlightGear 2.0.0 one may use the latest (or at least 2.9.6) developer release from http://www.openscenegraph.org/projects/osg/wiki/Downloads/DeveloperReleases and extract it into <code>$srcdir</code>.

Mostly this is ok for FlightGear CVS as well as it is stable. However, sometimes the release is not fresh enough and one have to get the latest developments via SVN:
cd $srcdir
svn co http://www.openscenegraph.org/svn/osg/OpenSceneGraph/trunk OpenSceneGraph

cmake demands a build directory separate to its source directory. So <code>mkdir</code> one and <code>cd</code> into it.
cmake -D CMAKE_BUILD_TYPE="Release" -D CMAKE_CXX_FLAGS="-O3" -D CMAKE_C_FLAGS="-O3" \
-D CMAKE_INSTALL_PREFIX:PATH="$prefix" $srcdir/OpenSceneGraph[-version]
make install

=== SimGear ===
2.0.0:
cd $srcdir
wget http://mirrors.ibiblio.org/pub/mirrors/simgear/ftp/Source/SimGear-2.0.0.tar.gz
tar xzf SimGear-2.0.0.tar.gz
cd SimGear-2.0.0

CVS:
cd $srcdir
mkdir simgear
cd simgear
cvs -d :pserver:cvsguest@cvs.simgear.org:/var/cvs/SimGear-0.3 login
#CVS passwd: guest
cvs -d :pserver:cvsguest@cvs.simgear.org:/var/cvs/SimGear-0.3 co source
cd source
./autogen.sh

2.0.0 and CVS:
./configure --prefix=$prefix [CPPFLAGS=-I$prefix/include LDFLAGS="-L$prefix/lib -L$prefix/lib64"]
make install

=== FlightGear source ===
2.0.0:
cd $srcdir
wget http://mirrors.ibiblio.org/pub/mirrors/flightgear/ftp/Source/FlightGear-2.0.0.tar.gz
tar xzf FlightGear-2.0.0.tar.gz
cd FlightGear-2.0.0

CVS:
cd $srcdir
mkdir flightgear
cd flightgear
cvs -d :pserver:cvsguest@cvs.flightgear.org:/var/cvs/FlightGear-0.9 login
#CVS passwd: guest
cvs -d :pserver:cvsguest@cvs.flightgear.org:/var/cvs/FlightGear-0.9 co source
cd source
./autogen.sh

2.0.0 and CVS:
./configure --prefix=$prefix [CPPFLAGS=-I$prefix/include/ LDFLAGS="-L$prefix/lib -L$prefix/lib64"]
make install

=== FlightGear data ===
2.0.0:
cd $prefix
wget http://mirrors.ibiblio.org/pub/mirrors/flightgear/ftp/Shared/FlightGear-data-2.0.0.tar.bz2
tar xjf FlightGear-data-2.0.0.tar.bz2

CVS:
cd $prefix
cvs -d :pserver:cvsguest@cvs.flightgear.org:/var/cvs/FlightGear-0.9 co data

=== Trial run ===
When all the builds are done and the data download has finished it is time for a test run:
export LD_LIBRARY_PATH=$prefix/lib/:$LD_LIBRARY_PATH
$prefix/bin/fgfs --fg-root=$prefix/data

For the future, if you want to start FlightGear from command line have a look at [[fgfsrc]], if you prefer a graphical user interface continue with [[#fgrun|compiling fgrun]]. Have in mind that fgfs need to find our self compiled libraries and therefore we have to tell the linker (ld) where to find them. That is what the first line here does.

== Optional Software ==

=== fgrun ===
To build [[fgrun]] two more package is required:
*libfltk1.1-dev fluid

cd $srcdir
svn co http://fgrun.svn.sourceforge.net/svnroot/fgrun/trunk fgrun
cd fgrun
./autogen.sh
./configure --prefix=$prefix [CPPFLAGS=-I$prefix/include/]
make install

=== fgcom ===
For [[fgcom]] unfortunately there is one more dependency which cannot be solved with packages on Lenny/Etch, see [[#libopenal|libopenal]].

cd $srcdir
svn co https://appfgcom.svn.sourceforge.net/svnroot/fgcom/trunk fgcom
cd fgcom/src
make INSTALL_BIN=$prefix/bin INSTALL_DIR=$prefix/fgcom \
PLIB_PREFIX=$prefix OPENAL_PREFIX=$prefix install



{{Building}}

[[de:FlightGear_bauen_-_Debian]]

Building FlightGear - Debian

2010-04-18T12:22:26Z

Moksha: /* libopenal */ typo

= HowTo build on Debian =

HowTo build FlightGear 2.0.0 or CVS on GNU/Linux Debian '''Stable''' 5.x (Lenny).

This HowTo may also work with '''Testing'''/'''Unstable''' except that some things are easier because of more up to date packages. So, before fetching something check the version of the available -dev package for it.

It even *should* work with '''Etch''', but I am not certain about some dependencies. [http://wiki.flightgear.org/index.php?title=Talk:Building_Flightgear_-_Debian&action=edit Reports] are welcome.

If you don't want to make your hands dirty, have a look at [[Scripted_Compilation_on_Linux_Debian/Ubuntu]].

== Requirements and Preparations ==
You need an OpenGL capable graphics including a proper installed driver.<BR>

Also a bunch of packages (and some of their dependencies) are required:
*gcc, g++, make, automake1.9, pkg-config
*mawk (or gawk)
*cmake (min. version 2.6.0-5, for Etch available on backports.org!)
*cvs, subversion, wget

*freeglut3-dev, libgl1-mesa-dev, libxrandr-dev
*libxi-dev, libxmu-dev, libxext-dev
*libopenal-dev (see [[#libopenal|libopenal]]), libalut-dev
*libjpeg62-dev, libtiff4-dev, libpng12-dev
*libboost1.37-dev (Not available for Lenny atm, see [[#Boost Library|Boost Library]] below.)

During installation packages ''simgear-dev'' and ''openscenegraph-dev'' *must not* be installed. They can safely be re-installed after compilation.

== Build and install ==
Because we are going to install versions different to the ones in the repositries it is recommended to install FG-2.0.0 and/or CVS in a place independent to the base system such as /usr/local/FG-2.0.0, /opt/FG-2.0.0 or in a subdirectory of your $HOME. I suggest to make it writeable by the user that there is no need to become root for the <code>make install</code> commands. I'll use <code>$prefix</code> as a placeholder for this directory. <BR>
Another one will be <code>$srcdir</code>, it stands for the absolute path to the directory which contains the folders of the various source codes. So in the following instructions one have to replace these by the local paths or even <code>export</code> them during the process.

Subsequent the instructions to fetch the sources and the data needed by FlightGear and the commands to build/install each source.

Have in mind that the data is relatively huge (CVS about 2 GB and 2.0.0 300 MB) so, to save some time, it is a good idea to fetch it while building the sources.

=== libopenal ===
The libopenal-dev package in Lenny/Etch is too old for [[fgcom]]. For FlightGear it does work but not all features (like Doppler) are available, so installing an up to date version is recommended anyway.
cd $srcdir
wget http://kcat.strangesoft.net/openal-releases/openal-soft-1.11.753.tar.bz2
tar xjf openal-soft-1.11.753.tar.bz2
cd openal-soft-1.11.753/build
cmake -D CMAKE_INSTALL_PREFIX:PATH="$prefix" ..
make install

=== plib ===
Latest SVN is [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg20793.html recommended], yet package plib1.8.5-dev for Testing/Unstable does work as well.
cd $srcdir
svn co https://plib.svn.sourceforge.net/svnroot/plib/trunk plib
cd plib
sed s/PLIB_TINY_VERSION\ \ 5/PLIB_TINY_VERSION\ \ 6/ -i src/util/ul.h
./autogen.sh
./configure --prefix=$prefix
make install

=== Boost Library ===
Version 1.37 is needed. At least for Lenny/Etch this means getting the sources because this is not available atm on backports.org. Testing/Unstable users may have more luck and a package is available, libboost-1.37-dev or newer.

To build SimGear, FlightGear, fgrun and fgcom some boostlib header files are required, no need to compile and install it. If you have installed a libboost1.37-dev (or highter) package on your system you don't have to bother at all with it. If not, you have to tell each ./configure where the header files are. To do so, add the option <code>CPPFLAGS=-I$prefix/include</code> to the SimGear, FlightGear and fgrun <code>./configure</code> commands. We copy the header files to $prefix/include because fgcom will need them there.

Get the newest version tar ball from http://sourceforge.net/projects/boost/files/boost/, extract it into <code>$srcdir</code> then:
cp -R $srcdir/boost-[version]/boost/ $prefix/include/

=== OpenSceneGraph ===
For FlightGear 2.0.0 one may use the latest (or at least 2.9.6) developer release from http://www.openscenegraph.org/projects/osg/wiki/Downloads/DeveloperReleases and extract it into <code>$srcdir</code>.

Mostly this is ok for FlightGear CVS as well as it is stable. However, sometimes the release is not fresh enough and one have to get the latest developments via SVN:
cd $srcdir
svn co http://www.openscenegraph.org/svn/osg/OpenSceneGraph/trunk OpenSceneGraph

cmake demands a build directory separate to its source directory. So <code>mkdir</code> one and <code>cd</code> into it.
cmake -D CMAKE_BUILD_TYPE="Release" -D CMAKE_CXX_FLAGS="-O3" -D CMAKE_C_FLAGS="-O3" \
-D CMAKE_INSTALL_PREFIX:PATH="$prefix" $srcdir/OpenSceneGraph[-version]
make install

=== SimGear ===
2.0.0:
cd $srcdir
wget http://mirrors.ibiblio.org/pub/mirrors/simgear/ftp/Source/SimGear-2.0.0.tar.gz
tar xzf SimGear-2.0.0.tar.gz
cd SimGear-2.0.0

CVS:
cd $srcdir
mkdir simgear
cd simgear
cvs -d :pserver:cvsguest@cvs.simgear.org:/var/cvs/SimGear-0.3 login
#CVS passwd: guest
cvs -d :pserver:cvsguest@cvs.simgear.org:/var/cvs/SimGear-0.3 co source
cd source
./autogen.sh

2.0.0 and CVS:
./configure --prefix=$prefix [CPPFLAGS=-I$prefix/include LDFLAGS="-L$prefix/lib -L$prefix/lib64"]
make install

=== FlightGear source ===
2.0.0:
cd $srcdir
wget http://mirrors.ibiblio.org/pub/mirrors/flightgear/ftp/Source/FlightGear-2.0.0.tar.gz
tar xzf FlightGear-2.0.0.tar.gz
cd FlightGear-2.0.0

CVS:
cd $srcdir
mkdir flightgear
cd flightgear
cvs -d :pserver:cvsguest@cvs.flightgear.org:/var/cvs/FlightGear-0.9 login
#CVS passwd: guest
cvs -d :pserver:cvsguest@cvs.flightgear.org:/var/cvs/FlightGear-0.9 co source
cd source
./autogen.sh

2.0.0 and CVS:
./configure --prefix=$prefix [CPPFLAGS=-I$prefix/include/ LDFLAGS="-L$prefix/lib -L$prefix/lib64"]
make install

=== FlightGear data ===
2.0.0:
cd $prefix
wget http://mirrors.ibiblio.org/pub/mirrors/flightgear/ftp/Shared/FlightGear-data-2.0.0.tar.bz2
tar xjf FlightGear-data-2.0.0.tar.bz2

CVS:
cd $prefix
cvs -d :pserver:cvsguest@cvs.flightgear.org:/var/cvs/FlightGear-0.9 co data

=== Trial run ===
When all the builds are done and the data download has finished it is time for a test run:
export LD_LIBRARY_PATH=$prefix/lib/:$LD_LIBRARY_PATH
$prefix/bin/fgfs --fg-root=$prefix/data

For the future, if you want to start FlightGear from command line have a look at [[fgfsrc]], if you prefer a graphical user interface continue with [[#fgrun|compiling fgrun]]. Have in mind that fgfs need to find our self compiled libraries and therefore we have to tell the linker (ld) where to find them. That is what the first line here does.

== Optional Software ==

=== fgrun ===
To build [[fgrun]] two more package is required:
*libfltk1.1-dev fluid

cd $srcdir
svn co http://fgrun.svn.sourceforge.net/svnroot/fgrun/trunk fgrun
cd fgrun
./autogen.sh
./configure --prefix=$prefix [CPPFLAGS=-I$prefix/include/]
make install

=== fgcom ===
For [[fgcom]] unfortunately there is one more dependency which cannot be solved with packages on Lenny/Etch, see [[#libopenal|libopenal]].

cd $srcdir
svn co https://appfgcom.svn.sourceforge.net/svnroot/fgcom/trunk fgcom
cd fgcom/src
make INSTALL_BIN=$prefix/bin INSTALL_DIR=$prefix/fgcom \
PLIB_PREFIX=$prefix OPENAL_PREFIX=$prefix install



{{Building}}

[[de:FlightGear_bauen_-_Debian]]

Scripted Compilation on Linux Debian/Ubuntu

2010-04-18T11:54:49Z

Moksha: /* Launching Fgrun */ typo

==Description==
The following script takes care of downloading and compiling Flightgear from the cvs repositories with just one command execution for both 32-bit and 64-bit Debian based systems (Debian, Ubuntu). Pre-existing installed version (if any) of Flightgear are not touched at all since the script builds and installs everything under the directory in which it is launched.

Necessary packages are installed via the apt-get system while libraries not included in the repositories are downloaded and compiled on the fly (i.e. [[Plib]], [[Simgear]] and [[OSG]]).

===List of compiled programs===
The script is able to download and compile:
* Flightgear (And all the data needed to use it)
* [[Fgrun]]
* [[FGCOM]]
* [[Atlas]]
* [[Terrasync]]

==Download==
You can download the script here: [[http://brisa.homelinux.net/fgfs/download_and_compile.sh download_and_compile.sh]]

The script is hosted on a home server, so if the electricity goes down or internet connection fails, you will be not able to download it directly.
[[http://www.rato.us/flightgear/download_and_compile.sh A backup is here]]

If all else fails, join the [[FlightGear IRC channel]] and ask for the download_and_compile.sh script. Someone there will be likely to provide it to you.

==Instructions==
To run download_and_compile.sh, just save it in a directory called for example: ~/fg_tools
then execute it (no need to execute it as root).

Here is for example a sequence of commands to get the script and launch it in a new folder.
<pre>
mkdir ~/fgfs
cd ~/fgfs
wget http://brisa.homelinux.net/fgfs/download_and_compile.sh
chmod 755 download_and_compile.sh
sh download_and_compile.sh
</pre>
Once all will be finished, you will sucessfully get all the programs installed in the ~/fgfs directory.

===Launching FlightGear===
To run your new cvs installation of Flightgear you have to launch the ''run_fgfs.sh'' command under the same folder, for example:
<pre>
cd ~/fgfs
sh run_fgfs.sh
</pre>

===Launching Fgrun===
For many users it's more comfortable having Flightgear launched by the graphical utiliy Fgrun which is installed as well in the same folder. You have to launch the ''run_fgrun.sh'' command, for example:
<pre>
cd ~/fgfs
sh run_fgrun.sh
</pre>

===Launching FGCOM===
FGCOM is the system used by flightgear to simulate radio communications between users. Launch it using the ''run_fgcom.sh'' command:
<pre>
cd ~/fgfs
sh run_fgcom.sh -cs
</pre>

===Launching Atlas===
Atlas provides a map for Flightgear, use it launching: ''run_atlas.sh''
<pre>
cd ~/fgfs
sh run_fgatlas.sh
</pre>

===Launching Terrasync===
Your Flightgear compilation comes with the Terrasync program too, so if you want to use it:
<pre>
cd ~/fgfs
sh run_terrasync.sh -p 5500 -d /folder/with/sceneries
</pre>
Where: ''/folder/with/sceneries'' is the folder containing the sceneries data.

Then launch fgfs with the '''--fg-scenery=/folder/with/sceneries --atlas=socket,out,5,localhost,5500,udp''' option

==Troubleshooting==

===Compilation errors===
Here we are, no fear, if you wish to use programs from the cvs/svn repositories, you might face compilation errors that will prevent you to have a working copy of one or more of the programs provided by this script. What can be the causes that prevent us from a successful compiling? As far as I know those:
# Software developers introduce a new functionality with a new piece of code that prevents the compilation under your architecture, this can happen working with cvs/svn sources.
# The program refuses to compile because of a divergence in the libraries it depends. For example Flightgear might not compile because OSG has been modified, while OSG itself compiles fine, FG won't.
# One or more repositories are down and you can't get the library you need. (Both from cvs/svn or apt-get)

There is a simple solution to the above errors: wait and relaunch the script after some time (hours or days), if (and generally happens) software developers repair or synchronize their code with the newly updated libraries, your Flightgear will compile fine as if the previous error never took place.

Sometimes it happens that the script fails to compile only fgrun,fgcom or atlas, if you then see the run_fgfs.sh file it means that Flightgear installation was successful and you can safely run it.

==Options==
The script by default (without any option) will only compile Flightgear and Fgrun. To make it compile all, you need to launch the script with the ''ALL'' parameter. i.e.:
<pre>
sh download_and_compile.sh ALL
</pre>

===Compiling only one program===
If you wish to recompile only one of the programs you can launch the script with one of the following parameters:
* PLIB (to compile and install only plib)
* OSG (to compile and install only OpenSceneGraph)
* SIMGEAR (to compile and install only Simgear)
* FGFS (to compile and install only FlightGear)
* DATA (to download / update only data files for FlightGear)
* FGRUN (to compile and install only Fgrun)
* FGCOM (to compile and install only Fgcom)
* ATLAS (to compile and install only Atlas)

===Fast updating===
There is a second parameter ''UPDATE'' that allows you to just update your installation. i.e.:
This will only update FGFS
<pre>
sh download_and_compile.sh FGFS UPDATE
</pre>

===Advanced options===
* Skip download of packages using '''-p n''' option
* Skip compilation of programs using '''-c n''' option
* Skip retrieving software updates using '''-d n''' option
* Skip reconfigure (make clean) using '''-r n''' option

For example, if you a developer and wish to fast recompile and reinstall only modification for FlightGear do this:
<pre>
sh download_and_compile.sh -p n -d n -r n FGFS
</pre>

this will only recompile modifications and reinstall them.

==Disk usage==
Having both compiled program, source codes and data from cvs requires some hard disk space: It will take you something like 3GB of space.
If you don't have a fast machine, it will require you also some hours of compilation time.

Scripted Compilation on Linux Debian/Ubuntu

2010-04-18T07:59:19Z

Moksha: /* Launching Fgrun */ correct spelling

==Description==
The following script takes care of downloading and compiling Flightgear from the cvs repositories with just one command execution for both 32-bit and 64-bit Debian based systems (Debian, Ubuntu). Pre-existing installed version (if any) of Flightgear are not touched at all since the script builds and installs everything under the directory in which it is launched.

Necessary packages are installed via the apt-get system while libraries not included in the repositories are downloaded and compiled on the fly (i.e. [[Plib]], [[Simgear]] and [[OSG]]).

===List of compiled programs===
The script is able to download and compile:
* Flightgear (And all the data needed to use it)
* [[Fgrun]]
* [[FGCOM]]
* [[Atlas]]
* [[Terrasync]]

==Download==
You can download the script here: [[http://brisa.homelinux.net/fgfs/download_and_compile.sh download_and_compile.sh]]

The script is hosted on a home server, so if the electricity goes down or internet connection fails, you will be not able to download it directly.
[[http://www.rato.us/flightgear/download_and_compile.sh A backup is here]]

If all else fails, join the [[FlightGear IRC channel]] and ask for the download_and_compile.sh script. Someone there will be likely to provide it to you.

==Instructions==
To run download_and_compile.sh, just save it in a directory called for example: ~/fg_tools
then execute it (no need to execute it as root).

Here is for example a sequence of commands to get the script and launch it in a new folder.
<pre>
mkdir ~/fgfs
cd ~/fgfs
wget http://brisa.homelinux.net/fgfs/download_and_compile.sh
chmod 755 download_and_compile.sh
sh download_and_compile.sh
</pre>
Once all will be finished, you will sucessfully get all the programs installed in the ~/fgfs directory.

===Launching FlightGear===
To run your new cvs installation of Flightgear you have to launch the ''run_fgfs.sh'' command under the same folder, for example:
<pre>
cd ~/fgfs
sh run_fgfs.sh
</pre>

===Launching Fgrun===
For many users it's more comfortable having Flighgear launched by the graphical utiliy Fgrun which is installed as well in the same folder. You have to launch the ''run_fgrun.sh'' command, for example:
<pre>
cd ~/fgfs
sh run_fgrun.sh
</pre>

===Launching FGCOM===
FGCOM is the system used by flightgear to simulate radio communications between users. Launch it using the ''run_fgcom.sh'' command:
<pre>
cd ~/fgfs
sh run_fgcom.sh -cs
</pre>

===Launching Atlas===
Atlas provides a map for Flightgear, use it launching: ''run_atlas.sh''
<pre>
cd ~/fgfs
sh run_fgatlas.sh
</pre>

===Launching Terrasync===
Your Flightgear compilation comes with the Terrasync program too, so if you want to use it:
<pre>
cd ~/fgfs
sh run_terrasync.sh -p 5500 -d /folder/with/sceneries
</pre>
Where: ''/folder/with/sceneries'' is the folder containing the sceneries data.

Then launch fgfs with the '''--fg-scenery=/folder/with/sceneries --atlas=socket,out,5,localhost,5500,udp''' option

==Troubleshooting==

===Compilation errors===
Here we are, no fear, if you wish to use programs from the cvs/svn repositories, you might face compilation errors that will prevent you to have a working copy of one or more of the programs provided by this script. What can be the causes that prevent us from a successful compiling? As far as I know those:
# Software developers introduce a new functionality with a new piece of code that prevents the compilation under your architecture, this can happen working with cvs/svn sources.
# The program refuses to compile because of a divergence in the libraries it depends. For example Flightgear might not compile because OSG has been modified, while OSG itself compiles fine, FG won't.
# One or more repositories are down and you can't get the library you need. (Both from cvs/svn or apt-get)

There is a simple solution to the above errors: wait and relaunch the script after some time (hours or days), if (and generally happens) software developers repair or synchronize their code with the newly updated libraries, your Flightgear will compile fine as if the previous error never took place.

Sometimes it happens that the script fails to compile only fgrun,fgcom or atlas, if you then see the run_fgfs.sh file it means that Flightgear installation was successful and you can safely run it.

==Options==
The script by default (without any option) will only compile Flightgear and Fgrun. To make it compile all, you need to launch the script with the ''ALL'' parameter. i.e.:
<pre>
sh download_and_compile.sh ALL
</pre>

===Compiling only one program===
If you wish to recompile only one of the programs you can launch the script with one of the following parameters:
* PLIB (to compile and install only plib)
* OSG (to compile and install only OpenSceneGraph)
* SIMGEAR (to compile and install only Simgear)
* FGFS (to compile and install only FlightGear)
* DATA (to download / update only data files for FlightGear)
* FGRUN (to compile and install only Fgrun)
* FGCOM (to compile and install only Fgcom)
* ATLAS (to compile and install only Atlas)

===Fast updating===
There is a second parameter ''UPDATE'' that allows you to just update your installation. i.e.:
This will only update FGFS
<pre>
sh download_and_compile.sh FGFS UPDATE
</pre>

===Advanced options===
* Skip download of packages using '''-p n''' option
* Skip compilation of programs using '''-c n''' option
* Skip retrieving software updates using '''-d n''' option
* Skip reconfigure (make clean) using '''-r n''' option

For example, if you a developer and wish to fast recompile and reinstall only modification for FlightGear do this:
<pre>
sh download_and_compile.sh -p n -d n -r n FGFS
</pre>

this will only recompile modifications and reinstall them.

==Disk usage==
Having both compiled program, source codes and data from cvs requires some hard disk space: It will take you something like 3GB of space.
If you don't have a fast machine, it will require you also some hours of compilation time.