Plugins

Edit

LÖVR has a small core. Extra features can be provided by Libraries written in Lua, or by plugins. Plugins are similar to libraries -- they can be required from Lua to access their features. However, instead of Lua files in a project folder, plugins are native libraries (.dll or .so files) that are placed next to the lovr executable.

Using Plugins

To use a plugin, place its library file next to the lovr executable and require it from Lua:

-- myplugin.dll is next to lovr.exe
local myplugin = require 'myplugin'

function lovr.load()
  myplugin.dothething()
end

On Unix systems, some plugin files might be prefixed with lib (e.g. liblovr-plugin.so). In this case, be sure to require the plugin with the lib prefix: require 'liblovr-plugin'.

On Android, plugins are searched for in the lib/arm64-v8a folder of the APK.

Plugins are not officially supported in WebAssembly yet, but this is theoretically possible.

List of Plugins

lovr-luasocket	HTTP and socket support via luasocket
lua-cjson	Fast native JSON encoder/decoder
lua-cmsgpack	Lua MessagePack C implementation.
lua-deepspeech	Speech recognition using Mozilla's DeepSpeech library
lua-enet	enet for UDP multiplayer servers/clients
lua-https	Lua HTTPS module using native platform backends.
luv	libuv bindings for Lua

Building Plugins with CMake

LÖVR's CMake build system has support for automatically building plugins from source code. In the main lovr folder, a plugins folder can be created, containing a subfolder for each plugin to build. CMake will check all the subfolders of plugins, building anything with a CMakeLists.txt file. Their libraries will automatically be moved next to the final lovr executable, or packaged into the apk on Android.

Inside the plugins' CMakeLists.txt scripts, the LOVR variable will be set to 1, so libraries can detect when they're being built as lovr plugins. Plugins also automatically have access to the version of Lua used by LÖVR, no calls to find_package are needed.

This makes it easier to manage plugins -- they can be copied, symlinked, cloned with git, or added as git submodules. A fork of lovr can be created that has this custom plugins folder, making it easy to quickly get a set of plugins on multiple machines. Version control also means that the plugins are versioned and tied to a known version of lovr.

By default, the libraries from all CMake targets in the plugin's build script will be moved to the executable folder. Plugins can override this by setting the LOVR_PLUGIN_TARGETS variable to a semicolon-separated list of targets.

Creating Plugins

Internally, a plugin is no different from a regular native Lua library. A plugin library only needs to have a Lua C function with a symbol named after the plugin:

int luaopen_supermegaplugin(lua_State* L) {
  // This code gets run when the plugin is required,
  // and anything it returns on the stack is used
  // as the require's return value.
}

All of Lua's rules for native plugin loading, including processing of dots and hyphens and all-in-one loading, apply to LÖVR plugins. However, note that LÖVR plugins do not use package.cpath or Lua's default loader. The lovr.filesystem module has its own loader for loading plugins (it always looks for plugins next to the executable, and checks the lib/arm64-v8a folder of the APK).