Creating a Lua Plugin

This page gives an introduction to creating Lua plugins.

Modules

A module is a container for related functionality that can be 'required' (i.e. included) by other Lua scripts. There are various ways to implement a module in Lua. For Visionary Render plugins, any method can be used. For an overview of these methods, see the Modules Tutorial section of the Lua website.

Older modules used the module method where code had no direct access to global variables. Instead the author had to localise them before calling module (e.g. local print = print). This tends to make developing a module more difficult. Our new recommended way to develop Lua modules is to make everything inside the module local, and explicitly expose the functions that should be available to the user of the module. This is demonstrated as part of the Lua plugin example code below.

Plugins

A Lua plugin in Visionary Render has full access to everything that a normal event script does - i.e. the full Lua API. To instruct Visionary Render to load a Lua plugin, the quickest way is to put the .lua file in Documents/Visionary Render/plugins/<lua file name>/<lua file name>.lua (e.g. plugins/myplugin/myplugin.lua). A Lua plugin requires the following functions to permit it to be loaded by the plugin manager in Visionary Render:

Function	Description
`name()`	This should return a human-readable name for this plugin to be used to display this plugin in the plugin manager settings.
`version()`	This should return the version number, which is also used in the plugin manager settings.
`init()`	This is called once when the plugin is loaded, and should initialise any necessary objects such as VRTree nodes or menu items, etc.
`cleanup()`	This is called once when the plugin is unloaded, and should delete anything that `init()` added to VRTree. See Enabling/Disabling Plugins at Runtime for more information. (Optional)

Example Code

The following example shows how to create a simple plugin:

myplugin.lua

local function name()
  -- Return the name of the plugin.
  return "My Plugin"
end

local function version()
  -- Return the version number of the plugin.
  return "1.0.0"
end

local function init()
  -- Do something to initialise the plugin here...
  print("Init ", name())
end

local function cleanup()
  -- Do something to clean up the plugin here...
  print("Cleanup ", name())
end

-- Export the plugin functions to the Lua state.
return {
  name = name,
  version = version,
  init = init,
  cleanup = cleanup
}

Caution

You should define the functions in your plugin as local to prevent possible clashes with other plugins or API functions.

This will result in a myplugin table in the global Lua state (named after the plugin file name), containing the four functions we exported. To test the plugin, save it in the location mentioned above, and Launch Visionary Render. Open the Diagnostics window (Ctrl + D), go to the Log tab, and somewhere in here should be the line {LUA} Init My Plugin - this is the output from your first plugin. You can also see this in the lower pane of the Script Editor (Ctrl + L).

It is important to only define functions and local variables in the plugin script files, and not to execute any code outside of these functions. This is because, when loading the plugin, it is first loaded into a separate sandbox for querying its name and version, in order to check for conflicts with other plugins before exposing it to the main application Lua environment. This sandbox does not have access to any VR Lua functions or anything else in the main application environment.

Usage

Any functions exported by the plugin can be accessed in Visionary Render via an Event script or the Console. For example, run the following in the Console:

Console
Output

-- Print the name of myplugin to the Output panel.
print(myplugin.name())

{LUA} My Plugin