LÖVR Documentation

Plugins in LÖVR are optional native libraries built alongside the engine. When building LÖVR via CMake, any folder within the plugins directory containing a CMakeLists.txt file is automatically scanned, included, and built.

Key characteristics:

• Automatic Linking: Any CMake targets declared by a plugin are automatically linked with LÖVR's Lua instance.
• Lua Integration: Shared libraries produced by plugins are copied next to the lovr executable, enabling them to be loaded in Lua scripts using the standard require function.
• Core Plugins: LÖVR includes certain 'core plugins' in the repository that are included in builds by default. These are optional; their folders can be removed or their libraries deleted after a build without affecting the LÖVR build process.

LÖVR can be built from source using CMake. Follow these steps in your terminal:

mkdir build
cd build
cmake ..
cmake --build .

LÖVR is a Lua framework for building VR experiences. To start developing:

1. Download an executable from lovr.org/downloads.
2. Create a main.lua script in your project folder.
3. Drag the main.lua file onto the LÖVR executable to run it.

LÖVR uses specific callback functions like lovr.load() for initialization and lovr.draw(pass) for rendering logic.

-- Hello World example
function lovr.draw(pass)
  pass:text('Hello World!', 0, 1.7, -3, .5)
end

To add a custom native plugin to your LÖVR build:

1. Create a new folder within the plugins directory.
2. Add a CMakeLists.txt file to that folder.
3. Define your CMake targets within that file. LÖVR's build system will automatically include and link them with Lua.

Alternatively, you can manually copy prebuilt plugin libraries next to the lovr executable to use them via require in Lua. Note that this manual method is not recommended for Android builds, as modifying the APK requires re-signing.

You can render primitive shapes using the pass object provided to the lovr.draw callback. To create a spinning effect, use lovr.timer.getTime() to provide a continuously changing value to the rotation parameter of a primitive method.

function lovr.draw(pass)
  pass:cube(0, 1.7, -1, .5, lovr.timer.getTime())
end

LÖVR provides access to VR headset data via the lovr.headset module. You can iterate through available hands using lovr.headset.getHands() and retrieve their positions to render visual indicators (like spheres) at the hand locations.

function lovr.draw(pass)
  for _, hand in ipairs(lovr.headset.getHands()) do
    pass:sphere(vec3(lovr.headset.getPosition(hand)), .1)
  end
end

To use 3D assets like glTF or OBJ files:

1. Use lovr.graphics.newModel('path/to/model') inside the lovr.load() callback to load the asset into memory.
2. Use pass:draw(model, x, y, z) inside the lovr.draw(pass) callback to render the loaded model at a specific position.

function lovr.load()
  model = lovr.graphics.newModel('model.gltf')
end

function lovr.draw(pass)
  pass:draw(model, x, y, z)
end

The lovr.rc configuration file allows you to set global settings for the LÖVR environment. You can specify the application icon by using the GLFW_ICON key followed by the path to an image file (e.g., .ico or .png).

GLFW_ICON ICON lovr.ico

Tests are located in the test/lovr directory. You can execute them using the LÖVR binary.

To run all tests:

./build/bin/lovr test

To run tests for a specific module (e.g., the data module):

./build/bin/lovr test data