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) as well as for 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 the Max real time environment, for instance for finite elements.

There are many examples accessible through the "Modalys for Max" Extras menu item.

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.

    You can change the controller's update rate at any time within the script: 

    set_update_rate(-1)

  • name: the variable name.

  • pathtofile: the path to the external Lua text file, if any.
    • If this field is empty, then the Max text 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, and you now want 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 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 libraries such as string, table, math, os, input and output, and the basic functions.

Lua API Chapters

Other Functions and Classes

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


★     ★
★