Skip to content

Lua Controller (mlys.lua)

Description

mlys.lua, available in Modalys for Max environment only, is a controller that lets you write pieces of Lua script for static instrument construction (including 3D finite elements) or also real time control. Lua scripts are compiled on-the-fly with C language execution speed. The aim of mlys.lua is to provide as much flexibility as ModaLisp within Max' real time environment, for instance for finite elements.

🚧 This section is still under construction and will be improved over time. Many examples can be found in the Modalys for Max package.

mlys.lua

Modalys for Max syntax and Default Values

The mlys.lua controller can be created in Max using the following Lisp syntax:

[mlys.lua 2 3 @name MyLua @update 0.01]

update and name parameters can also be set using Max Information panel.

Parameters

The 'mlys.lua controller takes the following arguments:

  • update: the update rate in seconds. 0 means every sample and -1 automatic.
  • name: the variable name.
  • pathtofile: the path to the external Lua text file, if any.
    • If this fields is empty, then Max test editor is used. If not empty, the script file is external, and it is automatically opened with the associated app (still by double-clicking mlys.lua object).
    • If you were using some external file and you now want to embed the script within the patch
    • pathtofile can be absolute or relative to the patch file.
    • If the file doesn't exist, it is created (transferring the current content of mlys.lua).
    • If the file exists, iand you want now to embed the script within the patch, type "" (2 double quotes), and the content of the external file will be transferred to the patch.
    • If there some subfolders are specified, they must exist otherwise pathtofile is ignored. You can specify the external file within the object: 
      [mlys.lua 2 3 @name MyLua @pathtofile script/myscript.lua]
  • target-attribute: an optional parameter that can be used to control a specific attribute of a connected object.

Editing

Double click the mlys.lua object to open the external or Max internal text editor. If you are using the internal editor, close it to validate any changes.
⚠️Don't forget to rebang your object in order to reflect the changes.

Here is the minimal situation for your lua script: 

require("tools")

function initialize()
    -- This function (do not change its name!) will be run just once. You can put any initialization code here!
end

function update()
    -- This function (do not change its name!) is run according to the *update* parameter (0=every sample)
    -- Create your code here. The return value can be passed to a controller or a point-output.
    --
    --optional: you can return as many values (comma-separated) as there are outlets. Ex: 
    --return x,y
end

Discussion

The mlys.lua controller is similar in essence to the now extinct Expression controller but has some definite advantages:

  • Lua is much more powerful in essence, yet simple to learn;
  • Lua has some very interesting object-oriented capability;
  • Lua is a widespread language, with a large community;
  • The API code in Modalys is much lighter and easier to maintain, whereas the Expression controller is based on llvm, a project that is completely oversized for it...

Functions

Here is the growing list of the specific Lua functions for Modalys. Most of them are wrapped in the modalys namespace. And of course 😉 you may use the standard Lua built-in libraires such as string, table, math, os, input and output, and the basic functions.

  • modalys.coordinates_to_node(object, coords). object is a finite element object. coords is {x,y,z} triplet. The return value is the node number (0 if none found). Alternatively the parametric syntax can be used: coordinates_to_node{obj=object, xyz=coords}
  • modalys.create_access(args). 🚧
  • modalys.create_connection(args). 🚧
  • modalys.create_controller(args). 🚧
  • modalys.create_input_force_signal_access(args). 🚧
  • modalys.create_mesh(args). 🚧
  • modalys.create_object(args). Same as modalys.make_object.
  • modalys.create_point_input(args). 🚧
  • modalys.create_point_output(args). 🚧
  • modalys.create_speed_connection(args). 🚧
  • modalys.extend_mesh(args). 🚧
  • modalys.freeze_object(args). 🚧
  • modalys.freq_to_midi(f). Returns the MIDI note for the frequency f (according to A4=440Hz). Note that m if not necessarily an integer value.
  • modalys.get_current_value(args). 🚧
  • modalys.get_energy(args). 🚧
  • modalys.get_info(args). 🚧
  • modalys.get_inlet_count(args). 🚧
  • modalys.get_mesh(args). 🚧
  • modalys.get_node_coordinates(args). 🚧
  • modalys.get_os(). Returns either "windows", "mac" or "linux".
  • modalys.get_ref(name). Returns the reference (the pointer, to be exact) of the mlys item labelled name in Max. Very useful to manipulate items that have been created outside the current mlys.lua object.
  • modalys.get_sample_rate(). Returns the current sample rate. This is the same as invoking modalys.get_info("sample-rate").
  • modalys.get_value(ctrl)
  • modalys.inlet(args). 🚧
  • modalys.make_object(args). 🚧
  • modalys.midi_to_freq(m). Returns the frequency of the MIDI note m (according to A4=440Hz). Note m can be fractional.
  • modalys.post_thru_modalys_tilde(args...). Output some text or numerical values through modalys~ 's message outlet. Any such message is prefixed with "mlys.lua" and the Max name of the mlys.lua controller.
  • modalys.print(arg). Print a string or a numerical value to the Max console.
  • modalys.release(obj1, obj2, ...). Releases (actually im memory) the Modalys objects passed in arguments. Can be useful when building an object incrementally.
  • modalys.save_mesh(args). 🚧
  • modalys.set_amplitude_controller(object,controller). Set the amplitude controller for a particular object, explicitely.
  • modalys.set_info(args). 🚧
  • modalys.set_value{args}
  • modalys.transform_mesh(args). 🚧
  • modalys.view(args). 🚧
  • modalys.view_mesh(args). 🚧

Other functions or classes

For the following functions and classes, you will need require("tools") at the beginning of your script.

  • dump(object). Unfold the lua object or Modalys controller passed in argument. The result is returned as a string. Useful to examine a hierarchical table. If a controller is passed, its content is exposed as an array of values.
  • modalys.inlet_observer. (obsolete!)
  • ParametricCurve2D. 🚧
  • Average. 🚧
  • get_pitched_finite_element_object(parameters). 🚧
  • Average. 🚧


★     ★
★