Skip to content

This is general knowledge or an external-engine reference, not an Apollo architecture or implementation claim. See Apollo's architecture status for target terminology and verified implementation boundaries.

Q102: How Does C++ Call Lua? How Does Lua Call C++? ​

Problem Analysis ​

This question examines understanding of C++/Lua interop:

  • Lua C API
  • C++ calling Lua functions
  • Lua calling C++ functions
  • Binding libraries (LuaBridge/Sol)

I. Lua C API Basics ​

1.1 Stack Interaction Model ​

┌─────────────────────────────────────────────────────────────┐
│                  Lua Stack Interaction Model                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Lua stack:                                                 │
│  ┌─────┬─────┬─────┬─────┬─────┐                            │
│  │  5  │  4  │  3  │  2  │  1  │  Stack top ->              │
│  ├─────┼─────┼─────┼─────┼─────┤                            │
│  │ arg3│ arg2│ arg1│  fn │  -  │  When a function is called │
│  └─────┴─────┴─────┴─────┴─────┘                            │
│                                                             │
│  API functions:                                             │
│  ├── lua_gettop(L)          # Get stack size                │
│  ├── lua_pushXXX(L, val)    # Push a value                  │
│  ├── lua_toXXX(L, idx)      # Get a value                   │
│  ├── lua_pcall(L, args, ret)# Call a function               │
│  └── lua_settop(L, idx)     # Set stack size                │
│                                                             │
└─────────────────────────────────────────────────────────────┘

II. C++ Calling Lua ​

2.1 Basic Calls ​

cpp
// C++ calling Lua (C++ 调用 Lua)

#include <lua.hpp>
#include <iostream>

class LuaCaller {
public:
    LuaCaller() {
        // Create a Lua state (创建 Lua 状态)
        L = luaL_newstate();

        // Open the standard libraries (打开标准库)
        luaL_openlibs(L);

        // Load the script (加载脚本)
        if (luaL_dofile(L, "game_logic.lua") != LUA_OK) {
            std::cerr << "Error loading Lua: " << lua_tostring(L, -1) << std::endl;
        }
    }

    ~LuaCaller() {
        lua_close(L);
    }

    // Call a function with no arguments and no return value (调用无参数无返回值的函数)
    void callSimpleFunction(const char* funcName) {
        // Get the function (获取函数)
        lua_getglobal(L, funcName);

        // Call the function (0 arguments, 0 return values) (调用函数 0 参数 0 返回值)
        if (lua_pcall(L, 0, 0, 0) != LUA_OK) {
            std::cerr << "Error calling " << funcName << ": "
                     << lua_tostring(L, -1) << std::endl;
            lua_pop(L, 1);  // Clear the error (清除错误)
        }
    }

    // Call a function with arguments (调用带参数的函数)
    void callWithArgs(const char* funcName, int param1, const char* param2) {
        lua_getglobal(L, funcName);      // Push the function (压入函数)

        lua_pushinteger(L, param1);      // Push argument 1 (压入参数1)
        lua_pushstring(L, param2);       // Push argument 2 (压入参数2)

        // Call (2 arguments, 0 return values) (调用 2 参数 0 返回值)
        if (lua_pcall(L, 2, 0, 0) != LUA_OK) {
            std::cerr << "Error: " << lua_tostring(L, -1) << std::endl;
            lua_pop(L, 1);
        }
    }

    // Call a function with a return value (调用带返回值的函数)
    int callWithReturn(const char* funcName, int input) {
        lua_getglobal(L, funcName);
        lua_pushinteger(L, input);

        // Call (1 argument, 1 return value) (调用 1 参数 1 返回值)
        if (lua_pcall(L, 1, 1, 0) != LUA_OK) {
            std::cerr << "Error: " << lua_tostring(L, -1) << std::endl;
            lua_pop(L, 1);
            return 0;
        }

        // Get the return value (获取返回值)
        int result = lua_tointeger(L, -1);
        lua_pop(L, 1);  // Pop the return value (弹出返回值)

        return result;
    }

    // Call a function returning multiple values (调用返回多个值的函数)
    struct Position {
        float x, y, z;
    };

    Position getPlayerPosition(int playerId) {
        lua_getglobal(L, "getPlayerPosition");
        lua_pushinteger(L, playerId);

        if (lua_pcall(L, 1, 3, 0) != LUA_OK) {
            std::cerr << "Error: " << lua_tostring(L, -1) << std::endl;
            lua_pop(L, 1);
            return {0, 0, 0};
        }

        // Get the return values, note the order (获取返回值 注意顺序)
        float z = (float)lua_tonumber(L, -1);
        float y = (float)lua_tonumber(L, -2);
        float x = (float)lua_tonumber(L, -3);
        lua_pop(L, 3);

        return {x, y, z};
    }

private:
    lua_State* L;
};

// Lua script example (game_logic.lua) (Lua 脚本示例 game_logic.lua)
/*
-- Simple function (简单函数)
function onGameStart()
    print("Game started!")
end

-- With arguments (带参数)
function onPlayerLogin(playerId, playerName)
    print("Player " .. playerId .. " (" .. playerName .. ") logged in")
end

-- With a return value (带返回值)
function calculateLevel(exp)
    return math.floor(exp / 100) + 1
end

-- Multiple return values (多返回值)
function getPlayerPosition(playerId)
    return 100.0, 200.0, 300.0
end
*/

III. Lua Calling C++ ​

3.1 C Function Registration ​

cpp
// Lua calling C++ (Lua 调用 C++)

#include <lua.hpp>
#include <string>
#include <unordered_map>

// Game data, C++ side (游戏数据 C++ 侧)
class GameData {
public:
    static std::unordered_map<int, std::string> playerNames;
    static std::unordered_map<int, int> playerLevels;
};

std::unordered_map<int, std::string> GameData::playerNames;
std::unordered_map<int, int> GameData::playerLevels;

// C function: get player name (C 函数: 获取玩家名称)
static int lua_get_player_name(lua_State *L) {
    // Get arguments (获取参数)
    int playerId = luaL_checkinteger(L, 1);

    // Find the player (查找玩家)
    auto it = GameData::playerNames.find(playerId);
    if (it != GameData::playerNames.end()) {
        lua_pushstring(L, it->second.c_str());
    } else {
        lua_pushnil(L);
    }

    return 1;  // Number of return values (返回值个数)
}

// C function: set player name (C 函数: 设置玩家名称)
static int lua_set_player_name(lua_State *L) {
    int playerId = luaL_checkinteger(L, 1);
    const char* name = luaL_checkstring(L, 2);

    GameData::playerNames[playerId] = name;

    return 0;  // No return values (无返回值)
}

// C function: multiple return values (C 函数: 多返回值)
static int lua_get_player_info(lua_State *L) {
    int playerId = luaL_checkinteger(L, 1);

    auto nameIt = GameData::playerNames.find(playerId);
    auto levelIt = GameData::playerLevels.find(playerId);

    if (nameIt != GameData::playerNames.end() &&
        levelIt != GameData::playerLevels.end()) {
        lua_pushstring(L, nameIt->second.c_str());  // Return 1 (返回1)
        lua_pushinteger(L, levelIt->second);        // Return 2 (返回2)
        lua_pushboolean(L, true);                   // Return 3 (返回3)
    } else {
        lua_pushnil(L);
        lua_pushinteger(L, 0);
        lua_pushboolean(L, false);
    }

    return 3;  // 3 return values (3个返回值)
}

// C function: variadic arguments (C 函数: 可变参数)
static int lua_sum(lua_State *L) {
    int n = lua_gettop(L);  // Number of arguments (参数个数)
    int sum = 0;

    for (int i = 1; i <= n; ++i) {
        sum += luaL_checkinteger(L, i);
    }

    lua_pushinteger(L, sum);
    return 1;
}

// Register all functions (注册所有函数)
void registerFunctions(lua_State *L) {
    // Method 1: use lua_register (方法1: 使用 lua_register)
    lua_register(L, "getPlayerName", lua_get_player_name);
    lua_register(L, "setPlayerName", lua_set_player_name);
    lua_register(L, "getPlayerInfo", lua_get_player_info);

    // Method 2: use lua_pushcfunction + lua_setglobal (方法2: 使用 lua_pushcfunction + lua_setglobal)
    lua_pushcfunction(L, lua_sum);
    lua_setglobal(L, "sum");

    // Method 3: register as methods in a table (方法3: 注册为表中的方法)
    lua_newtable(L);  // Create a table (创建表)

    lua_pushcfunction(L, lua_get_player_name);
    lua_setfield(L, -2, "getName");

    lua_pushcfunction(L, lua_set_player_name);
    lua_setfield(L, -2, "setName");

    lua_setglobal(L, "Player");  // Set as the global variable Player (设置为全局变量 Player)
}

// Lua usage example (Lua 使用示例)
/*
-- Direct calls (直接调用)
name = getPlayerName(100)
setPlayerName(100, "NewName")

-- Multiple return values (多返回值)
name, level, success = getPlayerInfo(100)

-- Table method calls (表方法调用)
Player:getName(100)
Player:setName(100, "AnotherName")

-- Variadic arguments (可变参数)
total = sum(1, 2, 3, 4, 5)  -- 15
*/

IV. Advanced Binding ​

4.1 LuaBridge Example ​

cpp
// Use LuaBridge to simplify binding (使用 LuaBridge 简化绑定)

#include <LuaBridge/LuaBridge.h>

class Player {
public:
    std::string name;
    int level;
    int hp;

    Player(const std::string& n) : name(n), level(1), hp(100) {}

    void attack(const std::string& target) {
        printf("%s attacks %s!\n", name.c_str(), target.c_str());
    }

    int takeDamage(int damage) {
        hp -= damage;
        return hp;
    }

    std::string getInfo() const {
        return name + " Lv" + std::to_string(level) + " HP:" + std::to_string(hp);
    }
};

void registerWithLuaBridge(lua_State *L) {
    luabridge::getGlobalNamespace(L)
        .beginNamespace("Game")
            // Register the class (注册类)
            .beginClass<Player>("Player")
                // Constructor (构造函数)
                .addConstructor<void(*)(const std::string&)>()

                // Properties (属性)
                .addProperty("name", &Player::name)
                .addProperty("level", &Player::level)
                .addProperty("hp", &Player::hp)

                // Methods (方法)
                .addFunction("attack", &Player::attack)
                .addFunction("takeDamage", &Player::takeDamage)
                .addFunction("getInfo", &Player::getInfo)
            .endClass()
        .endNamespace();
}

// Lua usage (Lua 使用)
/*
local player = Game.Player("Hero")
player.level = 10

print(player:getInfo())  -- Hero Lv10 HP:100

player:attack("Monster")

local remainingHp = player:takeDamage(30)
print("Remaining HP:", remainingHp)
*/

4.2 Sol Example ​

cpp
// Use Sol3, a modern C++ binding (使用 Sol3 现代 C++ 绑定)

#include <sol/sol.hpp>

class Entity {
public:
    float x, y, z;

    Entity(float x = 0, float y = 0, float z = 0)
        : x(x), y(y), z(z) {}

    void moveTo(float nx, float ny, float nz) {
        x = nx; y = ny; z = nz;
    }

    float distanceTo(const Entity& other) const {
        float dx = x - other.x;
        float dy = y - other.y;
        float dz = z - other.z;
        return std::sqrt(dx*dx + dy*dy + dz*dz);
    }
};

void registerWithSol(sol::state& lua) {
    // Open the standard libraries (打开标准库)
    lua.open_libraries(sol::lib::base, sol::lib::math);

    // Register the type (注册类型)
    lua.new_usertype<Entity>("Entity",
        // Constructor (构造函数)
        sol::constructors<Entity(float, float, float)>(),

        // Properties (属性)
        "x", &Entity::x,
        "y", &Entity::y,
        "z", &Entity::z,

        // Methods (方法)
        "moveTo", &Entity::moveTo,
        "distanceTo", &Entity::distanceTo
    );

    // Register a function (注册函数)
    lua.set_function("createEntity", []() {
        return Entity(0, 0, 0);
    });

    // Register a lambda (注册 Lambda)
    lua.set_function("log", [](const std::string& msg) {
        std::cout << "[LUA] " << msg << std::endl;
    });
}

// Lua usage (Lua 使用)
/*
local e1 = Entity(10, 20, 30)
local e2 = Entity(40, 50, 60)

log("Distance: " .. e1:distanceTo(e2))

e1:moveTo(100, 200, 300)

local e3 = createEntity()
e3.x = 50
*/

V. Userdata Wrapping ​

5.1 Full userdata ​

cpp
// Userdata wrapping, lightweight objects (Userdata 封装 轻量对象)

#include <lua.hpp>
#include <iostream>

struct Vector3 {
    float x, y, z;

    Vector3(float x = 0, float y = 0, float z = 0)
        : x(x), y(y), z(z) {}

    float length() const {
        return std::sqrt(x*x + y*y + z*z);
    }

    Vector3 operator+(const Vector3& other) const {
        return Vector3(x + other.x, y + other.y, z + other.z);
    }
};

// Create Vector3 (创建 Vector3)
static int lua_vector3_new(lua_State *L) {
    float x = (float)luaL_optnumber(L, 1, 0);
    float y = (float)luaL_optnumber(L, 2, 0);
    float z = (float)luaL_optnumber(L, 3, 0);

    // Allocate userdata (分配 userdata)
    Vector3* v = (Vector3*)lua_newuserdata(L, sizeof(Vector3));
    *v = Vector3(x, y, z);

    // Set the metatable (设置元表)
    luaL_getmetatable(L, "Vector3");
    lua_setmetatable(L, -2);

    return 1;
}

// Get the Vector3 pointer (获取 Vector3 指针)
static Vector3* check_vector3(lua_State *L, int idx) {
    void* ud = luaL_checkudata(L, idx, "Vector3");
    luaL_argcheck(L, ud != NULL, idx, "'Vector3' expected");
    return (Vector3*)ud;
}

// Method: length (方法: length)
static int lua_vector3_length(lua_State *L) {
    Vector3* v = check_vector3(L, 1);
    lua_pushnumber(L, v->length());
    return 1;
}

// Method: add (方法: add)
static int lua_vector3_add(lua_State *L) {
    Vector3* v1 = check_vector3(L, 1);
    Vector3* v2 = check_vector3(L, 2);

    Vector3* result = (Vector3*)lua_newuserdata(L, sizeof(Vector3));
    *result = *v1 + *v2;

    luaL_getmetatable(L, "Vector3");
    lua_setmetatable(L, -2);

    return 1;
}

// Metamethod: __tostring (元方法: __tostring)
static int lua_vector3_tostring(lua_State *L) {
    Vector3* v = check_vector3(L, 1);
    lua_pushfstring(L, "Vector3(%f, %f, %f)", v->x, v->y, v->z);
    return 1;
}

// Metamethod: __add (元方法: __add)
static int lua_vector3_meta_add(lua_State *L) {
    return lua_vector3_add(L);
}

// Register the Vector3 type (注册 Vector3 类型)
void register_vector3(lua_State *L) {
    // Create the metatable (创建元表)
    luaL_newmetatable(L, "Vector3");

    // Metamethods (元方法)
    lua_pushcfunction(L, lua_vector3_tostring);
    lua_setfield(L, -2, "__tostring");

    lua_pushcfunction(L, lua_vector3_meta_add);
    lua_setfield(L, -2, "__add");

    // Index metamethod, method lookup (索引元方法 方法查找)
    lua_pushvalue(L, -1);
    lua_setfield(L, -2, "__index");

    // Methods (方法)
    lua_pushcfunction(L, lua_vector3_length);
    lua_setfield(L, -2, "length");

    lua_pushcfunction(L, lua_vector3_add);
    lua_setfield(L, -2, "add");

    // Clean up the stack (清理栈)
    lua_pop(L, 1);

    // Register the constructor (注册构造函数)
    lua_register(L, "Vector3", lua_vector3_new);
}

// Lua usage (Lua 使用)
/*
local v1 = Vector3(1, 2, 3)
local v2 = Vector3(4, 5, 6)

print(v1)           -- Vector3(1.000000, 2.000000, 3.000000)
print(v1:length())  -- 3.741657

local v3 = v1 + v2
print(v3)           -- Vector3(5.000000, 7.000000, 9.000000)
*/

VI. Best Practices ​

6.1 Binding Recommendations ​

PracticeDescription
Error checkingValidate arguments with luaL_checkXXX
Stack balanceClean up the stack after calls
Use binding librariesLuaBridge/Sol simplify development
Avoid frequent callsThe C++/Lua boundary has overhead
Batch operationsPass multiple values at once
Metatable reuseShared metatables reduce memory

VII. Summary ​

C++/Lua Interop Core ​

C++/Lua interop = stack operations + function registration + Userdata + binding libraries
- C++ calling Lua: lua_getglobal + lua_pcall
- Lua calling C++: lua_register + lua_CFunction
- LuaBridge/Sol are recommended to simplify development

References ​

Released under the MIT License