C++ Lua integration
This document describes implementation details behind Lua integration in Cataclysm: Bright Nights.
BN uses Lua 5.3.6 to run scripts and relies on sol2 v3.3.0 for bindings on C++ side.
Lua build can be enabled by passing
LUA=1 to the Makefile, or enabling
LUA build switch in CMake
builds. Both msvc and android for simplicity always build with Lua enabled.
Lua source files
To simplify build setup and improve portability we bundle
Lua 5.3.6 source code in
directory and have the build systems compile it and link into the game executable and library for
Sol2 source files
Sol2 makes it easy to bundle, we have
sol2 v3.3.0 single-header amalgamated version in
and just include it as needed. The header is quite large, so the less source files include it the
sol/config.hpp- Configuration header, we have a few options defined there
sol/forward.hpp- Forward declarations, a lightweight header that should be included in game headers instead of
sol/sol.hpp- Main sol2 header file, quite large, avoid including in game headers
Game source files
All Lua-related game source files have the
If you want to add new bindings, consider looking at existing examples in
and reading relevant part of Sol2 docs.
catalua.cpp) - Main Lua interface. It’s the only header most of the codebase will have to include, and it provides a public interface that works in both
LUA=0builds ( in builds without Lua, most of the functions there are no-op ).
catalua_sol_fwd.h- Wrappers for
sol/forward.hppwith custom pragmas to make them compile.
catalua_bindings*- Game Lua bindings live here.
.cpp) - Ingame Lua console.
.cpp) - Implementation details for
.cpp) - Lua-driven
.cpp) - In-memory logging for the console.
catalua_luna.h- Usertype registration interface with automatic doc generation, aka
catalua_luna_doc.h- List of types registration through
lunaor exposed to its doc generator.
.cpp) - Functions for marking Lua tables as read-only.
.cpp) - Lua table to/from JSON (de-)serialization.
catalua_type_operators.h- Macro that helps with implementing bindings for string_ids