Instrument upgrade 2 to 3

From Sim Innovations Wiki
Jump to navigation Jump to search

This page explains things to note when you upgrade an existing instrument made in Air Manager 2.1.3 to Air Manager 3.0.


The biggest difference between AM 2.1.3 and AM 3.0 is the way text is rendered. This means that you have to check all text objects you use in your instrument, and make sure that you reposition them correctly.

In AM 2.1.3, a text object might be initialized using this code:

txt_id = txt_add("hello world", "-fx-font-family:"Digital 7"; -fx-font-size:11px; -fx-fill:black; -fx-font-weight:bold; -fx-text-alignment:right;", 0, 0, 800, 200)

In AM 3.0 it would become:

txt_id = txt_add("hello world", "font:digital-7-mono-bold.ttf; size:11; color:black; halign:right;", 0, 0, 800, 200)

There are 4 text style properties you can use in AM 3.0:

Argument Type Description
font String The TTF font file name (searched in the resource folder of the instrument)
size Number The font size (in px)
color String The color, can be color string like "red", "blue", "cyan", etc. etc. Can also be a hex value, "#FFFFFF"
halign String The horizontal alignment of the text within the text box. Can be "left", "center" or "right".

Info AM 3.0 does not use the system fonts. Make sure to include used fonts in the resources folder of your instrument.


Air Manager 3.x uses Lua 5.3, where AM 2.x uses a variant of Lua 5.2.

This might give some incompatibility issues and improvements, which are addressed here.

string.format now works!

Try to not to rely on var_format to much anymore, since the build in string.format is more flexible and simpler.
You can find more information about string formatting here.

Error: lua number has no integer representation

With Lua 5.3, they have introduced the integer as a variable type.
In practice, you wouldn't notice to much, except for one thing.


string.format("%d", 1.05)

This works on AM 2.x, but it gives the lua number has no integer representation error on AM 3.x.
The reason behind this error is that Lua cannot convert a float value to an integer when it does not have a perfect integer (no fractional part) value.

The best way to fix this is using the following code:

string.format("%.0f", 1.05) -- Prints '1'

This will interpret the value as a float, but will remove the fractional (behind the .) part.


The following functions were deprecated in the mathematical library: atan2, cosh, sinh, tanh, pow, frexp, and ldexp. You can replace math.pow(x,y) with x^y; you can replace math.atan2 with math.atan, which now accepts one or two parameters

bit32 is gone

The bit32 library is gone from Lua 5.3.

Instead you can use the new bitwise operators explained here.

AM 2.x example:

visible (vs_txt, bit32.extract(ap_state , 4) == 1)

AM 3.x replacement:

visible(vs_txt, ( (ap_state >> 4) & 1) == 1)


There is a bug in AM 2.1.3 where dials are drawn with a horizontal and vertical offset of 1 pixel. Make sure to check the x values of any dials in your instrument

In AM 2.1.3, a dial might be initialized using this code:

dial_id = dial_add("dial.png", 100, 100, 200, 200)

In AM 3.0 it would become:

dial_id = dial_add("dial.png", 99, 99, 200, 200)