Modules.nas: Difference between revisions

Nasal (Flightgears integrated scripting language) comes with a limited number of [[Nasal library|core functions]].  

The language was [[Howto:Extend Nasal|extended by C++ functions]], as well as libraries written in Nasal (e.g. [[Nasal library/props|props]], [[Nasal library/io|io]], [[Nasal library/math|math]], [[Nasal library/debug|debug]] ...).  

For more information on how and when these files are loaded see [[Nasal Initialization]].

While there are many similarities between add-ons and modules, some words on the differences:  

Add-ons are selected by the user before launching FlightGear, thus they may or '''may not be available''' at runtime.

First some examples, the API documentation follows below.

Nasal code for an aircraft is usually loaded by a XML declaration in the <aircraft>-set.xml file like this:

<syntaxhighlight lang="xml">

|margin=10px |width=50%}}

Another usecase for Modules.nas is frameworks that need reload support.  

A framework usually provides more or less generic functionality that has to be adapted (configured) for a specific usecase (e.g. a specific aircraft).

A module must contain at least the file '''main.nas''' (default, other filename is possible) and should contain the functions {{code|main()}} and {{code|unload()}}.

The main.nas file shall contain a function {{code|main()}} that will be called on load with either the module object as parameter or the parameters passed to the {{code|module.load()}} function.

If you want the module to be re-/un-loadable, you must make sure to track resources and remove them on onload.

For this the main.nas shall contain a function {{code|unload()}} that removes any resources which were created by the module.

{{note|Calls to {{code|setlistener()}} and {{code|maketimer()}} are automatically tracked by the Module class for you, timers will be stopped automatically, listeners will be removed automatically on {{code|unload()}}.}}

# Module names shall contain only letters (a-z, A-Z), numbers (0-9) and underscores ('_').

# The name must contain at least one letter so it cannot be confused with a number

}}

In ''modules.nas'' the class ''Module'' is defined.  

A module object holds information about the path and filename of the Nasal script and supports unloading and reloading the code at runtime

}}

{{Nasal doc

|syntax = modules.isAvailable(module_name);

}}

{{Nasal doc

|syntax = modules.setDebug(module_name, [debug=1]);

}}

{{Nasal doc

|syntax = modules.load(module_name, [namespace_name]);

}}

{{Nasal doc

|syntax = mymod.setFilePath(path);

}}

{{Nasal doc

|syntax = mymod.setMainFile(filename);

}}

{{Nasal doc

|syntax = mymod.setNamespace(namespace);

}}

{{Nasal doc

|syntax = mymod.setDebug(debug=1);

}}

{{Nasal doc

|syntax = mymod.load([args]);

}}

{{Nasal doc

|syntax = mymod.unload();

}}

{{Nasal doc

|syntax = mymod.reload();

}}

{{Nasal doc

|syntax = mymod.get(var_name);

}}

In the property tree there is a subtree /nasal to control modules and get some statistics.

The properties available depend on the type of module ("load-once" or "reloadable", see [[Nasal Initialization]] for more information on the differences).

Modules handled by modules.nas will have their properties in /nasal/modules/<moduleName> where <moduleName> is given by the developer when calling either  

{{code|Module.new("<moduleName>")}} or {{code|modules.load("<moduleName>")}}.  

|}

A legacy load-once module is a direct (1st level) subdirectory of FGDATA/Nasal/ and its corresponding property tree is /nasal/<moduleName>/ where <moduleName> equals the name of the subdirectory.  

It is handled by C++ code and must have a corresponding entry in FGDATA/defaults.xml which defines a property "enabled" and optionally a property "module".

The bool "loaded" property shows the status of the module.

Stable Nasal frameworks which support reloading can be added to ''FGDATA/Nasal/modules/<module_name>''.  

This allows an aircraft developer to configure the framework for a specific aircraft and make use of the reload magic while developing the configuration.