C++.CodeCompared.To/Lua

Lua has no main, no includes, no build step and no types to declare — a script is a sequence of statements executed top to bottom. That is the whole reason it ends up inside C++ programs: the compile-link-run loop that costs you minutes costs a level designer nothing, and the script can be reloaded while the game is still running. print writes to stdout with a newline and calls tostring on whatever it is given.

Lua is not competing with C++ for the same work. It exists so the parts of a program that change often — quest logic, item behavior, UI flow, configuration, tools — can change without a rebuild and without a C++ programmer. The performance number is real and mostly irrelevant if you keep Lua out of the inner loop; it becomes very relevant the moment someone writes a per-particle update in it. The rest of this page is about the seam between the two, because that seam is where all the interesting bugs live.

The raw pairing is luaL_newstate() / lua_close(), and forgetting the second on an error path leaks the whole interpreter — so wrap it. std::unique_ptr with a custom deleter is the two-line version above; sol2 does it for you (see below). Note extern "C" around the headers: Lua is a C library and its headers are not always wrapped for C++, and <lua.hpp> — the wrapper some distributions ship — does not exist on every install, including the one this page compiles against. luaL_openlibs is what makes print, string, table and the rest exist; a sandbox opens only the libraries it wants.

Every entry point into Lua can fail — a syntax error, a runtime error, out of memory — and the C API reports it by return code with the message left on the stack, which is the convention the whole API follows. There is no exception to catch, and the next row explains why that is not merely a style choice. The value comes back through a global here because that is the simplest channel; returning values properly means lua_pcall and reading its results off the stack.

Every value crossing the boundary is pushed onto a per-state stack and referred to by index — positive from the bottom, negative from the top, so -1 is "the value I just pushed". Nothing checks that you left the stack the way you found it: a function that pushes three values and pops two leaks a slot on every call, and after enough calls the stack overflows. This is the C++ equivalent of manual memory management, applied to a second resource, and it is why almost nobody writes new bindings against the raw API any more.

A StackGuard records the depth on entry and restores it in its destructor, so a function cannot leak stack slots no matter which path it returns on — including an early return, and including a thrown exception. This is exactly the pattern std::lock_guard uses, applied to a different resource, and it is the single highest-value thing to add to a hand-written binding layer. Note the one situation it does not save you from, which the errors section covers: a lua_error does not unwind the C++ stack, so this destructor never runs.

sol2 is a header-only C++ library that wraps the same C API in templates: sol::state is the RAII lua_State, lua["name"] is a proxy object, and assigning it to a typed variable is what selects the conversion. The stack operations still happen — they are just generated rather than written, and generated correctly, which means no leaked slots and no wrong index. The cost is compile time (sol2 is heavily templated and will noticeably slow a translation unit) and a dependency; the alternative libraries are LuaBridge, which is lighter, and Luau's own bindings if you are on Roblox's fork.

Under the raw API every exposed function must be int (*)(lua_State*), read its arguments with luaL_checkinteger and friends, push its results, and return how many it pushed — see /c/lua for that version. sol2 deduces all of it from the C++ signature, including for lambdas with captures, which the raw API cannot express at all without a userdata to hold the closure. Arity and type errors become Lua errors with sensible messages rather than undefined reads. From the script's side there is deliberately no way to tell a C++ function from a Lua one.

Handing Lua a Player* gives it a reference to your object, so hero:damage(30) runs the real C++ method and the change is visible in C++ afterwards. The colon in hero:damage(30) is Lua's method syntax — sugar for hero.damage(hero, 30), which is this made explicit exactly as it is in Go, Rust and Python. What sol2 generates underneath is a userdata with a metatable, which is the raw-API mechanism the next section is about. Note the two shapes are not equivalent for ownership, which is the whole of the next section.

sol::constructors<…> lists the signatures to expose, because C++ overloads cannot be deduced from a single function pointer. An object created by Vector2.new(3, 4) lives in Lua-allocated userdata memory and is destroyed by Lua's garbage collector, which calls the C++ destructor through the __gc metamethod — so RAII does still work, just on the collector's schedule rather than at a scope exit. Note the raw string literal with a custom delimiter, R"LUA(…)LUA": a plain R"(…)" ends at the first )" in its content, and print("after collectgarbage()") contains exactly that sequence — so embedding Lua in C++ wants a delimiter the script cannot produce.

Assigning a pointer lends the object: C++ keeps ownership, and if it outlives the Lua reference you have a dangling userdata that will crash on next access — the classic embedding bug. Assigning a value copies it into Lua-owned memory, which is safe and costs a copy. Assigning a shared_ptr shares it, which is usually what you want for anything with a real lifetime. The rule that prevents most incidents: never hand Lua a raw pointer to something with a shorter lifetime than the lua_State, and prefer shared_ptr when you are not certain.

Leaving scope in Lua makes a value unreachable, not destroyed — the destructor runs when the collector next sweeps, which may be many frames later or not before the program exits. For a plain data type that is fine; for anything holding a file handle, a socket, a GPU resource or a lock it is a leak with a long fuse. The two practical answers are to keep such resources owned by C++ and lend Lua a handle, or to give the type an explicit close() method and make calling it the script's job. Lua 5.4's <close> attribute finally provides deterministic cleanup, but 5.3 is still extremely widely embedded. Note also that only userdata — and, since 5.2, tables carrying a __gc metamethod — are finalized at all, so a plain table simply disappears. The C++ column forces a collection to make the destructor visible; the Lua column cannot, because the engine behind this page does not implement collectgarbage.

Lua raises errors with longjmp when built as C, and longjmp past a C++ frame with a non-trivial destructor is undefined behavior — in practice the destructor is skipped and whatever it owned leaks. Build Lua as C++ (compile the Lua sources with a C++ compiler) and it uses real exceptions instead, at which point unwinding is correct and try/catch works; this is what sol2 recommends and what most engines do. The mirror-image rule also holds: never let a C++ exception escape into Lua, because Lua cannot catch it — catch at the boundary and convert to lua_error.

A plain lua_call propagates an error out of the interpreter, which for an embedded program means abort. lua_pcall — and sol2's protected_function — catches it and hands back a status, which is what you want for anything a modder or designer can edit. The parallel to draw is that pcall is Lua's try/catch, complete with the same temptation to use it for control flow. Lua errors can be any value, not just a string, so an error object with fields is expressible.

A table has an array part and a hash part, and the implementation moves entries between them automatically, so the same value serves as std::vector, std::map, a struct, an object and a namespace. That is why the language is so small. The costs are that every element is a dynamically-typed TValue (so no contiguous ints and no cache locality), and that the type system cannot distinguish "array of items" from "config record" — a mistake C++ would catch at compile time is a nil at runtime here.

Tables are conventionally indexed from 1, which every library and every for i = 1, #t loop assumes — so an off-by-one when translating C++ index arithmetic is the commonest porting bug. Worse: #t is only defined for a table with no holes, and setting readings[2] = nil creates one, after which the length operator may legitimately return 1 or 3. Use table.remove, which shifts. And note the consequence for the boundary: a Lua array arriving in C++ must be read with ipairs or a counted loop, never by trusting # on data a script produced.

sol::as_table_t is doing real work and leaving it out is a trap: sol2 binds std::vector as a userdata by default — so Lua can hold a real C++ vector — which means a bare std::vector<std::string> spawns = lua["spawns"] compiles cleanly and then aborts at runtime with "expected userdata, received table". as_table_t is how you say "this Lua value is a table, convert it". The raw API version is a lua_next loop with careful stack management. Worth noting for design: a Lua table used as configuration can compute — loops, conditionals, shared constants, functions — which is why so many projects use Lua where they would otherwise have JSON, and is also why loading untrusted config needs a sandboxed state.

Multiple return values are a Lua language feature with no C++ equivalent, and sol2 maps them onto std::tuple. The asymmetry to remember is that Lua discards extras and fills missing arguments with nil silently, so a hook whose signature drifted will not error — it will quietly receive nil and probably do nothing. That is a good reason to validate hook arguments on the Lua side, or to pass a single table rather than a positional list, which is what most engines settle on.

A Lua closure captures the variable (an "upvalue"), not a copy, and the garbage collector keeps it alive as long as any closure referencing it is reachable — so returning a closure over a local is ordinary and safe, where the C++ equivalent with [&] is a dangling reference. Two closures created in the same scope share the upvalue, which is how you build a counter with separate increment and read functions. For the boundary: a Lua closure handed to C++ is a value you must anchor in the registry or in a sol::function, or the collector may take it.

Because every distinct short string exists exactly once in a lua_State, equality is a pointer comparison rather than a memcmp, and using strings as table keys is cheap. The flip side is that a = a .. b in a loop is O(n²), exactly as it is with std::string but for a different reason — each step allocates and interns a whole new string. The idiom is table.concat, which is Lua's ostringstream. Note that Lua strings are byte strings with no encoding attached, like std::string and unlike Rust's or Swift's, and may contain embedded zeros.

/ in Lua always produces a float, so 7 / 2 is 3.5 and even 6 / 2 is 3.0 rather than 3 — floor division is the separate // operator. That difference bites when a computed value becomes a table index or is passed to C++ expecting an integer. math.type distinguishes the subtypes. Before 5.3 there was only a double, which is why a lot of embedded Lua is still configured with LUA_32BITS or a single numeric type; check what your engine builds.

A metatable is an ordinary table whose specially-named fields the interpreter consults: __add, __eq, __lt, __len, __call, __tostring, __index, __newindex, __gc. Because it is set at runtime with setmetatable, the same table can gain or change behavior later — which is how Lua does prototypes, and how sol2 implements bound C++ types. __index is the important one: it is consulted when a key is missing, so pointing it at a class table is what makes method lookup and inheritance work.

When a key is missing from a table, Lua consults its metatable's __index — and if that is another table, the search continues there, which chains into inheritance. Every lookup is dynamic, so there is no vtable and no compile-time check: a misspelled method is nil and calling it raises "attempt to call a nil value", which is the commonest Lua runtime error. There is also no super; calling the base version means naming it, as above. For the boundary this matters because sol2's sol::base_classes maps C++ inheritance onto exactly this chain.

A coroutine suspends with its locals and instruction pointer intact, which is exactly what a quest script, a cutscene or an AI behavior needs: walkTo(door); yield(); openDoor(); wait(2) reads as straight-line code and runs across many frames. That is why engines expose a scheduler that resumes coroutines each tick. For the boundary, the constraint to know is that you cannot yield across a C function call in the general case — if C++ called into Lua which then tries to yield past that frame, older Lua raises "attempt to yield across a C-call boundary"; 5.2 added continuation functions to make it possible, and they are fiddly.

A crossing costs argument conversion, a stack push per value, an interpreter dispatch and the reverse on return — on the order of a hundred nanoseconds, which is nothing once and everything a hundred thousand times a frame. So the rule is the same one every FFI has: cross rarely, with a lot of work. Design the API around bulk operations (spawnWave(config), not spawn() in a loop), pass a table rather than a long argument list, and keep per-entity per-frame updates in C++ with Lua deciding policy. Profilers to know: LuaJIT's -jv, and any engine's own script timing.

LuaJIT's FFI is the part worth knowing about even if you never use it: ffi.cdef takes C declarations as a string and calls the functions directly, so there is no stack, no userdata and no sol2 — which is why so many projects tolerate being stuck on the 5.1 dialect. Roblox's Luau is a third option, a 5.1 fork with gradual typing and its own sandbox. The practical advice is to write bindings against the smallest common surface, and to check _VERSION or feature-probe rather than assume, exactly as the Lua column does above.

Assigning to an undeclared name creates a global, and reading an undefined one yields nil rather than erroring — so a misspelled variable silently reads nil and the failure surfaces somewhere unrelated. Globals are also slower than locals (a hash lookup in _G against a register) and are shared across every script in the state. The standard mitigations are luacheck in continuous integration, and a development-only metatable on _G whose __index and __newindex raise on undeclared access — worth wiring into your engine's debug build.

0 is truthy in Lua, and so is the empty string — only nil and false are falsy. So if count then is true for a count of zero, and the C++ habit of testing a number for truthiness silently changes meaning when ported. The idiom for "present and non-zero" is if count and count > 0 then. This also matters at the boundary: a C++ function returning 0 to signal failure will be read as success by a script testing its result directly, so return nil or false for failure instead.

Nothing else on this anchor is like this: Rust, Go and Zig are alternatives to C++, and Lua is a component of a C++ program. So the question is never "should we use Lua instead" but "where should the line go", and the answer that most projects converge on is the one above — C++ owns the machine and the lifetimes, Lua owns the decisions and the iteration speed. Get the four seam rules right and embedded Lua is one of the highest-leverage things you can add to a C++ codebase; get the ownership one wrong and you get crashes that reproduce only under memory pressure.