UI/Lua in the UI

Lua scripting can be used in the RmlUI-based UI, similar to how JavaScript can be used on a web page.

Documentation resources

The RmlUi Lua Manual is useful. Although we are still using the old libRocket, not much has changed.

It's also possible to read the librocket.com documentation in the Internet Archive/Wayback Machine.

Grepping for examples in the Samples folder (libs/libRocket/Samples) may be helpful.

Note that these resources are all far from comprehensive. Many Lua facilities, it seems, can only be discovered by searching the libRocket source.

Tips

The cgame command luarocket can be used to execute Lua snippets. Global variables set from any of the documents are accessible. You can print things with print().

Pitfalls

Bugs

Setting the inner_rml attribute of an Element does not work if the string is longer than 1023 characters.

You can't use Lua's built-in ipairs function, because libRocket overrides it with its own version that doesn't work! (See libs/libRocket/Source/Core/Lua/GlobalLuaFunctions.cpp)

Other

All RML documents (or perhaps all documents in a context?) share a common set of global variables. This means that function names and global variable names need to be unique across the whole program. Also, importing a Lua script via <script src="..." /> in one document imports it in all documents.

Although Lua usually uses 1-based indexing for arrays, libRocket's Lua APIs are mostly 0-based. For functions that return a list, this has the consequence that the length operator # returns the wrong result.