FlyWithLua

https://github.com/x-friese/flywithlua
Admin
FlyWithLua is a Lua scripting plugin for X-Plane flight simulator that enables users to extend and...
Tokens:390,157
Snippets:2,754
Trust Score:5.6
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Module file creation example

Source: https://github.com/x-friese/flywithlua/blob/master/FlyWithLua/Documentation/FlyWithLua_Manual_en.pdf

Create a module file with a .lua extension and start with the exact first line 'module(..., package.seeall)'. The example defines a function say_hello that speaks 'Hello World!'.

```lua
module(..., package.seeall)

-- here comes your own code
function say_hello()
  XSBSpeakString("Hello World!")
end
```

--------------------------------

### Install LaTeX prerequisites (Ubuntu)

Source: https://github.com/x-friese/flywithlua/blob/master/docs/README.md

Installs the required TeX Live packages and make on Ubuntu before building the PDF documentation.

```Shell
# Install prerequisites (Ubuntu):
$ sudo apt-get install texlive-latex-extra texlive-fonts-recommended texlive-latex-recommended make
```

--------------------------------

### Install Ubuntu build dependencies with apt-get

Source: https://github.com/x-friese/flywithlua/blob/master/README.md

Install required software on Ubuntu using apt-get. The --no-install-recommends flag avoids installing recommended packages.

```bash
sudo apt-get install -y --no-install-recommends build-essential cmake git freeglut3-dev libudev-dev libopenal-dev
```

--------------------------------

### HUD Module Example Script

Source: https://github.com/x-friese/flywithlua/blob/master/FlyWithLua/Documentation/FlyWithLua_Manual_en.pdf

A complete example demonstrating the definition of HUD containers, dataref registration, element creation, and interactive actions.

```lua
require "HUD"

dataref("QNH_Pilot", "sim/cockpit2/gauges/actuators/barometer_setting_in_hg_pilot", "writable")
dataref("GPU", "sim/cockpit/electrical/gpu_on", "writable")

HUD.begin_HUD(-81, -200, 80, 45, "MyExample")

HUD.create_element("caption", 0, 30, 80, 15)
HUD.draw_string(12, 3, 10, "set to STD")
HUD.create_click_action(0, 0, 80, 15, "QNH_Pilot = 29.92")

HUD.create_element("baro", 0, 0, 80, 30, 0, 0, 0, 0)
HUD.draw_string(12, 20, 10, "BARO")
HUD.draw_fstring(12, 3, 18, "%2.2f", "QNH_Pilot")
HUD.create_wheel_action(0, 0, 80, 30, "QNH_Pilot = QNH_Pilot + MOUSE_WHEEL_CLICKS / 100")

HUD.end_HUD()

HUD.begin_HUD(100, 1, 30, 12, "GPU", "always")
HUD.create_element("GPU", 0, 0, 30, 12)
HUD.draw_string(4, 2, 10, "GPU")
HUD.create_backlight_indicator(0, 0, 30, 12, "GPU == 1", 0, 1, 0, 0.5)
HUD.create_click_switch(0, 0, 30, 12, "GPU", 0, 1)
HUD.end_HUD()
```

--------------------------------

### Set start condition with command_once

Source: https://github.com/x-friese/flywithlua/blob/master/FlyWithLua/Documentation/First_Steps_Programming_FlyWithLua.md

Use this script to set up start conditions, such as turning on the beacon light by default when X-Plane starts. The command is executed only once, so you can still use the beacon light switch manually. You can find all available commands in X-Plane under Settings -> Joystick & Equipment -> Buttons: Adv.

```lua
command_once("sim/lights/beacon_lights_on")
```

--------------------------------

### HUD Module Example

Source: https://github.com/x-friese/flywithlua/blob/master/docs/FlyWithLua_Manual_en.pdf

A basic example demonstrating how to define a HUD area and create elements within it using the HUD module.

```lua
require "HUD"
HUD.begin_HUD(100, 200, 80, 45, "MyExample")
HUD.create_element("caption", 0, 30, 80, 15)
HUD.draw_string(12, 3, 10, "Hello World!")
HUD.end_HUD()
```

--------------------------------

### ALL_HID_DEVICES table example

Source: https://github.com/x-friese/flywithlua/blob/master/docs/FlyWithLua_Manual_en.tex

Example of the sub-elements stored in the ALL_HID_DEVICES table for the first HID device on a Windows 7 development system. Shows the fields available for each device, including vendor_id, product_id, path, and manufacturer_string.

```latex
ALL_HID_DEVICES[1].vendor_id         = 1103 (0x44f)
ALL_HID_DEVICES[1].product_id          = 45322 (0xb10a)
ALL_HID_DEVICES[1].release_number      = 1280 (0x500)
ALL_HID_DEVICES[1].interface_number    = -1 (0xffffffff)
ALL_HID_DEVICES[1].usage_page          = 1 (0x1)
ALL_HID_DEVICES[1].usage               = 4 (0x4)
ALL_HID_DEVICES[1].path                = \\?\hid#vid_044f&pid_b10a#7&5a04db4&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}
ALL_HID_DEVICES[1].serial_number       = ?
ALL_HID_DEVICES[1].manufacturer_string = Thrustmaster
ALL_HID_DEVICES[1].product_string      = T.16000M
```

--------------------------------

### HUD module example: begin_HUD, create_element, draw_string, end_HUD

Source: https://github.com/x-friese/flywithlua/blob/master/FlyWithLua/Documentation/FlyWithLua_Manual_en.pdf

This example demonstrates the basic usage of the HUD module: it begins a HUD, creates a caption element, draws a string, and ends the HUD. The HUD module is available since FlyWithLua 2.2 and allows interactive HUDs.

```lua
require "HUD"

HUD.begin_HUD(100, 200, 80, 45, "MyExample")
HUD.create_element("caption", 0, 30, 80, 15)
HUD.draw_string(12, 3, 10, "Hello World!")
HUD.end_HUD()
```

--------------------------------

### Debug variable observation

Source: https://github.com/x-friese/flywithlua/blob/master/docs/FlyWithLua_Manual_en.pdf

Example of observing variables during runtime using dataref, string formatting, and conditional drawing to prevent crashes.

```lua
dataref("carb_heat", "sim/cockpit2/engine/actuators/carb_heat_ratio", "writable", 0)
dataref("icing", function automatic_carb_heat() "sim/flightmodel/engine/ENGN_crbice", "readonly")
-- debug the variable
my_debug_string = string.format("before: icing = %f, carb_heat = %f ", icing, carb_heat)
-- if carb is icing then switch heat on
if (icing == 1) then
carb_heat = 1
else
carb_heat = 0
end
my_debug_string = my_debug_string .. string.format(" ==> after: icing = %f, carb_heat = %f ", icing, carb_heat)
do_often("automatic_carb_heat()")
do_every_draw("if my_debug_string then draw_string(20, 20, my_debug_string) end ")
```

--------------------------------

### get DataRef value

Source: https://github.com/x-friese/flywithlua/blob/master/FlyWithLua/Documentation/FlyWithLua_Manual_en.pdf

Example of reading a DataRef value using the print function.

```Lua
>print(get("sim/aircraft/weight/acf_m_fuel_tot"))
```

--------------------------------

### Create a basic HUD with HUD.begin_HUD

Source: https://github.com/x-friese/flywithlua/blob/master/docs/FlyWithLua_Manual_en.tex

Basic HUD example that creates a HUD container and draws a caption with the text "Hello World!". Requires the HUD module and must be executed in a Lua script file. The HUD is visible in the forward view with HUD.

```lua
require "HUD"

HUD.begin_HUD(100, 200, 80, 45, "MyExample")

HUD.create_element("caption", 0, 30, 80, 15)
HUD.draw_string(12, 3, 10, "Hello World!")

HUD.end_HUD()
```

--------------------------------

### Access DataRef with peek

Source: https://github.com/x-friese/flywithlua/blob/master/FlyWithLua/Documentation/FlyWithLua_Manual_en.pdf

Example of using the peek function to check a battery state. Note that indexes start at 0.

```lua
peek( battery.reference, battery.reftype, 0)
```

--------------------------------

### Create QT Creator project from CMakeLists.txt

Source: https://github.com/x-friese/flywithlua/blob/master/README.md

Create a QT Creator project folder and clone the FlyWithLua repository. Then use QT Creator's 'File' > 'Open File or Project' to browse to 'FlyWithLua/src/CMakeLists.txt' and open it.

```bash
mkdir QTCreatorProjects
cd D:\QTCreatorProjects
git clone https://github.com/X-Friese/FlyWithLua.git
```

--------------------------------

### play_sound_on_master_bus() example

Source: https://github.com/x-friese/flywithlua/blob/master/docs/FlyWithLua_Manual_en.tex

Plays a sound file stored in the sound system table on the master bus. The argument is the index value (starting from 0) where the sound is stored.

```lua
play_sound_on_master_bus(tenft_wav)
```

--------------------------------

### Configure sound parameters

Source: https://github.com/x-friese/flywithlua/blob/master/docs/FlyWithLua_Manual_en.pdf

Example of loading a sound and adjusting its pitch and gain values.

```lua
1 *−− l o a d s o u n d " c a b i n crew, p r e p a r e f o r l a n d i n g "* 2 c c _ p r e p a r e _ l a n d i n g _ s o u n d = load_WAV_file ( SCRIPT_DIRECTORY.. " s o u n d s / c c p r e p l a n d. wav " ) 3 *−− f a s t s p e a k i n g, h e l i u m b r e a t h i n g p i l o t w h i s p e r i n g* 4 s e t _ s o u n d _ p i t c h ( c c _ p r e p a r e _ l a n d i n g _ s o u n d, 1. 8 ) 5 s e t _ s o u n d _ g a i n ( c c _ p r e p a r e _ l a n d i n g _ s o u n d, 0. 2 5 )
```

--------------------------------

### command_begin(simulator function)

Source: https://github.com/x-friese/flywithlua/blob/master/FlyWithLua/Documentation/FlyWithLua_Manual_en.pdf

Begins a simulator command.

```APIDOC
## command_begin(simulator function)

### Description
Begins a simulator command.

### Parameters
- **simulator function** (string) - Required - The simulator function to begin.

```

--------------------------------

### Build Xbtn2cmd binaries for all platforms

Source: https://github.com/x-friese/flywithlua/blob/master/docker/README.md

Execute the build process for all supported platforms and list the resulting .xpl files.

```bash
$ (cd docker; make)
$ ls src/build-*/*.xpl
src/build-lin/lin.xpl src/build-mac/mac.xpl src/build-win/win.xpl
```

--------------------------------

### Incorrect Nested String Example

Source: https://github.com/x-friese/flywithlua/blob/master/FlyWithLua/Documentation/FlyWithLua_Manual_en.pdf

An example of a script that causes a Lua crash due to improper nesting of double quotes.

```lua
xyz = 42
do_every_draw("draw_string(50, 500, string.format( " The is %i ", xyz ) ) " )
```

--------------------------------

### Build and copy FlyWithLua plugin on Ubuntu

Source: https://github.com/x-friese/flywithlua/blob/master/README.md

Build the project on Ubuntu and copy the resulting lin.xpl plugin DLL into the appropriate directory as FlyWithLua.xpl.

```bash
cmake --build ./build
mkdir ./FlyWithLua/lin_x64
cp ./build/lin.xpl ./FlyWithLua/lin_x64/FlyWithLua.xpl
```

--------------------------------

### SCRIPT_DIRECTORY usage example

Source: https://github.com/x-friese/flywithlua/blob/master/docs/FlyWithLua_Manual_en.pdf

Example code demonstrating how to use the SCRIPT_DIRECTORY global variable to write a file into the scripts directory.

```APIDOC
## SCRIPT_DIRECTORY usage example

### Description
This example shows how to use the SCRIPT_DIRECTORY global variable to create a file in the scripts directory.

### Code
```lua
infofile = os.open(SCRIPT_DIRECTORY .. "my_info.txt", "w")
```
```

--------------------------------

### HUD module example with click and wheel actions

Source: https://github.com/x-friese/flywithlua/blob/master/docs/FlyWithLua_Manual_en.tex

Complete example of the HUD module: creates two containers. The first ("MyExample") shows a caption with a click action to set QNH to 29.92 and a baro element with a formatted string and a wheel action that adjusts QNH using the read-only MOUSE_WHEEL_CLICKS variable. The second container ("GPU", with "always" visibility) shows a backlight indicator and a click switch for the GPU dataref.

```lua
require "HUD"

dataref("QNH_Pilot", "sim/cockpit2/gauges/actuators/barometer_setting_in_hg_pilot", "writable")
dataref("GPU", "sim/cockpit/electrical/gpu_on", "writable")

HUD.begin_HUD(-81, -200, 80, 45, "MyExample")

HUD.create_element("caption", 0, 30, 80, 15)
HUD.draw_string(12, 3, 10, "set to STD")
HUD.create_click_action(0, 0, 80, 15, "QNH_Pilot = 29.92")

HUD.create_element("baro", 0, 0, 80, 30, 0, 0, 0, 0)
HUD.draw_string(12, 20, 10, "BARO")
HUD.draw_fstring(12, 3, 18, "%2.2f", "QNH_Pilot")
HUD.create_wheel_action(0, 0, 80, 30, "QNH_Pilot = QNH_Pilot + MOUSE_WHEEL_CLICKS / 100")

HUD.end_HUD()

HUD.begin_HUD(100, 1, 30, 12, "GPU", "always")
HUD.create_element("GPU", 0, 0, 30, 12)
HUD.draw_string(4, 2, 10, "GPU")
HUD.create_backlight_indicator( 0, 0, 30, 12, "GPU == 1", 0, 1, 0, 0.5)
HUD.create_click_switch(0, 0, 30, 12, "GPU", 0, 1)
HUD.end_HUD()
```

--------------------------------

### Quoted-Printable conversion example

Source: https://github.com/x-friese/flywithlua/blob/master/src/third_party/luasocket/upstream/gem/ltn012.tex

An example of using the chain factory to define a Quoted-Printable conversion pipeline and pumping it from stdin to stdout.

```lua
local qp = filter.chain(normalize(CRLF), encode("quoted-printable"),
 wrap("quoted-printable"))
local input = source.chain(source.file(io.stdin), qp)
local output = sink.file(io.stdout)
pump.all(input, output)
```

--------------------------------

### Create and Configure ImGui Window

Source: https://github.com/x-friese/flywithlua/blob/master/FlyWithLua/Documentation/FlyWithLua_Manual_en.pdf

Initializes a new ImGui window with specific dimensions, title, position, and callback functions.

```lua
demo_wnd = float_wnd_create(800, 450, 1, true)
float_wnd_set_title(demo_wnd, "Demo Window")
float_wnd_set_position(demo_wnd, 775, 650)
float_wnd_set_imgui_builder(demo_wnd, "build_demo")
float_wnd_set_onclose(demo_wnd, "closed_demo")
image_id = float_wnd_load_image(SCRIPT_DIRECTORY .. "/imgui_demo.jpg")
```

--------------------------------

### graphics.draw_filled_arc(x, y, start angle, end angle, radius)

Source: https://github.com/x-friese/flywithlua/blob/master/docs/FlyWithLua_Manual_en.tex

Draws an arc defined by start and end angles, filled with the current color.

```APIDOC
## graphics.draw_filled_arc(x, y, start angle, end angle, radius)

### Description
Draws an arc defined by start and end angles, filled with the current color.

### Method
Function call

### Endpoint
graphics.draw_filled_arc(x, y, start angle, end angle, radius)

### Parameters
- **x** (number) - Required - X coordinate of the center.
- **y** (number) - Required - Y coordinate of the center.
- **start angle** (number) - Required - Starting angle of the arc.
- **end angle** (number) - Required - Ending angle of the arc.
- **radius** (number) - Required - Radius of the arc.

### Example
```lua
graphics.draw_filled_arc(100, 100, 0, 90, 50)
```
```

--------------------------------

### Install Windows build dependencies with Chocolatey

Source: https://github.com/x-friese/flywithlua/blob/master/README.md

Install required software on Windows using Chocolatey in an admin command prompt. The mingw version is pinned to 8.1.0.

```powershell
choco install git cmake
choco install mingw --version 8.1.0
```

--------------------------------

### Initialize proAudioRt in user.ini

Source: https://github.com/x-friese/flywithlua/blob/master/docs/FlyWithLua_Manual_en.tex

Place this code in the user.ini script, which executes during startup. It loads the proAudioRt module and initializes the sound device, logging a success or error message.

```lua
-- load the sound library and init it
require("proAudioRt")
if proAudio.create() then
  logMsg("FlyWithLua Info: Sound engine is running.")
else
  logMsg("FlyWithLua Error: Can't init the sound library!")
end
```

--------------------------------

### XPLANE_LANGUAGE usage example

Source: https://github.com/x-friese/flywithlua/blob/master/docs/FlyWithLua_Manual_en.pdf

Example code demonstrating how to use the XPLANE_LANGUAGE global variable to create multilingual macro labels based on the X-Plane menu language.

```APIDOC
## XPLANE_LANGUAGE usage example

### Description
This example shows how to use the XPLANE_LANGUAGE global variable to provide localized macro labels for different languages.

### Code
```lua
dataref("COM1", "sim/cockpit/radios/com1_freq_hz", "writable")

if XPLANE_LANGUAGE == "German" then
    add_macro("Stelle das Funkgeraet auf UNICOM", "COM1 = 12280")
elseif XPLANE_LANGUAGE == "French" then
    add_macro("Fréquence radio point sur l'UNICOM", "COM1 = 12280")
elseif XPLANE_LANGUAGE == "Spanish" then
    add_macro("Punto de frecuencia de radio en la UNICOM", "COM1 = 12280")
elseif XPLANE_LANGUAGE == "Italian" then
    add_macro("Punto di frequenza radio sulla UNICOM", "COM1 = 12280")
else
    add_macro("Set radio to UNICOM", "COM1 = 12280")
end
```
```

--------------------------------

### graphics.draw_arc_line(x, y, start angle, end angle, radius, line width)

Source: https://github.com/x-friese/flywithlua/blob/master/docs/FlyWithLua_Manual_en.tex

Draws an arc line without internal lines to the center, defined by start and end angles.

```APIDOC
## graphics.draw_arc_line(x, y, start angle, end angle, radius, line width)

### Description
Draws an arc line without internal lines to the center, defined by start and end angles.

### Method
Function call

### Endpoint
graphics.draw_arc_line(x, y, start angle, end angle, radius, line width)

### Parameters
- **x** (number) - Required - X coordinate of the center.
- **y** (number) - Required - Y coordinate of the center.
- **start angle** (number) - Required - Starting angle of the arc.
- **end angle** (number) - Required - Ending angle of the arc.
- **radius** (number) - Required - Radius of the arc.
- **line width** (number) - Optional - Width of the line. Default is 1.0.

### Example
```lua
graphics.draw_arc_line(100, 100, 0, 90, 50, 2)
```
```

--------------------------------

### Initialize sound library in user.ini

Source: https://github.com/x-friese/flywithlua/blob/master/docs/FlyWithLua_Manual_en.pdf

Use this code in the user.ini file to load the proAudioRt library and initialize the sound engine during FlyWithLua startup.

```lua
1 *−− l o a d t h e s o u n d l i b r a r y and i n i t i t* 2 **r e q u i r e** ( " p r o A u d i o R t " ) 3 **i f** p r o A u d i o. c r e a t e ( ) **t h e n** 4 logMsg ( " F l y W i t h L u a I n f o : Sound e n g i n e i s r u n n i n g. " ) 5 **e l s e** 6 logMsg ( " F l y W i t h L u a E r r o r : Can ’ t i n i t t h e s o u n d l i b r a r y ! " ) 7 **end**
```

--------------------------------

### graphics.draw_arc_line(x, y, start angle, end angle, radius, line width)

Source: https://github.com/x-friese/flywithlua/blob/master/FlyWithLua/Documentation/FlyWithLua_Manual_en.pdf

Draws an arc line on the screen from a start angle to an end angle with the given radius and line width.

```APIDOC
## graphics.draw_arc_line(x, y, start angle, end angle, radius, line width)

### Description
Draws an arc line on the screen.

### Parameters
- **x** (number) - Required - X coordinate of the arc center.
- **y** (number) - Required - Y coordinate of the arc center.
- **start angle** (number) - Required - Starting angle of the arc in degrees.
- **end angle** (number) - Required - Ending angle of the arc in degrees.
- **radius** (number) - Required - Radius of the arc.
- **line width** (number) - Required - Width of the arc line.

### Returns
None.
```

--------------------------------

### graphics.draw_arc(x, y, start angle, end angle, radius, line width)

Source: https://github.com/x-friese/flywithlua/blob/master/docs/FlyWithLua_Manual_en.tex

Draws an arc defined by start and end angles. If line width is omitted, a default of 1.0 is used.

```APIDOC
## graphics.draw_arc(x, y, start angle, end angle, radius, line width)

### Description
Draws an arc defined by start and end angles. If line width is omitted, a default of 1.0 is used.

### Method
Function call

### Endpoint
graphics.draw_arc(x, y, start angle, end angle, radius, line width)

### Parameters
- **x** (number) - Required - X coordinate of the center.
- **y** (number) - Required - Y coordinate of the center.
- **start angle** (number) - Required - Starting angle of the arc.
- **end angle** (number) - Required - Ending angle of the arc.
- **radius** (number) - Required - Radius of the arc.
- **line width** (number) - Optional - Width of the line. Default is 1.0.

### Example
```lua
graphics.draw_arc(100, 100, 0, 90, 50, 2)
```
```

--------------------------------

### get(): read a DataRef value

Source: https://github.com/x-friese/flywithlua/blob/master/docs/FlyWithLua_Manual_en.tex

Reads a non-array DataRef and prints its value. Useful for checking DataRefs from XSquawkBox's input line. For array DataRefs, use the indexed get() variant.

```lua
print(get("sim/aircraft/weight/acf_m_fuel_tot"))
```
Tokens:
Raw