Lua libraries

Why should you use lua libraries?

Complex instruments typically contain allot of lua code. Writing all this lua code in one logic.lua file can make it very hard to keep track on where you can find different functional parts of your instrument.

For that reason, we support adding separate lua files.
Each part of your instrument can be written in it's own lua file.

How to use it

1. Create lib folder

Create a lib folder in your instrument folder (see screenshot).

2. Create library lua files

Place your lua files in the lib folder and name it something meaningful to you. You are not restricted in the naming in any way.

When the instrument is started, your library lua files will be executed first, followed by the logic.lua.

The order in which your lua library files are executed is random, so never rely on a certain ordering in your code.

3. Use common pattern

We recommend you using the following coding style. You are not restricted into using this, another pattern might suit your application better.

Create init and visible functions

First part is to define the init and visible function in your library lua file. Make sure to use your own prefix (in this example my_lib).

-- my_lib.lua example

function my_lib_init()
  -- Should be executed once on startup by the logic.lua
end

function my_lib_visible(is_visible)
  -- Should be executed by the logic.lua when visibility should change of this library
end

Add objects (like images, txt, etc.)

Typically, you want to add some objects to your library lua. A certain visual part of your instrument for instance. We will add two images and a text element in this example

-- my_lib.lua example

local my_first_img = nil
local my_second_img = nil
local my_txt = nil
local my_group = nil

function my_lib_init()
  --  Create some example objects
  my_first_img = img_add("my_img.png", 0, 0, 256, 256)
  my_second_img = img_add("my_img.png", 0, 0, 256, 256)
  my_txt = txt_add("hello world", "color: red;", 0, 0, 256, 100)

  my_group = group_add(my_first_img, my_second_img, my_txt)
end

function my_lib_visible(is_visible)
  -- Change the visibility of our library objects
  visible(my_group, is_visible)
end

Respond to data from the Flight Simulator

Changing object based on data from the Flight Simulator can be done like normal

-- my_lib.lua example

local my_first_img = nil
local my_second_img = nil
local my_txt = nil
local my_group = nil

function my_lib_init()
  --  Create some example objects
  my_first_img = img_add("my_img.png", 0, 0, 256, 256)
  my_second_img = img_add("my_img.png", 0, 0, 256, 256)
  my_txt = txt_add("hello world", "color: red;", 0, 0, 256, 100)

  my_group = group_add(my_first_img, my_second_img, my_txt)

  -- Change the text when certain data from the flight simulator changes
  xpl_dataref_subscribe("DATAREF_EXAMPLE", "INT", function(value)
     txt_set(my_txt, "Data from flight simulator: " .. value)
  end)
end

function my_lib_visible(is_visible)
  -- Change the visibility of our library objects
  visible(my_group, is_visible)
end

Add your library to the logic.lua

When you are done with your library lua files, the last step is to include this library in the main logic.lua file.

-- logic.lua example

-- Initialize different library files when the instrument is started
-- You can determine the order in which you want to initialize your libraries here

-- Function from our example library
my_lib_init() 

-- Other libraries you might want to initialize
my_lib_2_init()
my_lib_3_init()
my_lib_4_init()


-- You can change the visibility of different lua libraries here if you like:
my_lib_visible(false)