Lua 游戏引擎内嵌指南：Cocos/Defold 脚本宿主与对象绑定

// 一个最简嵌入：创建状态 → 加载脚本 → 调用
#include <lua.h>
#include <lauxlib.h>
#include <lualib.h>

int main(void) {
    lua_State *L = luaL_newstate();
    luaL_openlibs(L);

    if (luaL_dofile(L, "game/main.lua") != LUA_OK) {
        fprintf(stderr, "%s\n", lua_tostring(L, -1));
        return 1;
    }
    // 脚本内注册了 Game:init() 与 Game:update(dt)
    lua_getglobal(L, "Game");
    lua_getfield(L, -1, "init");
    lua_call(L, 0, 0);

    lua_close(L);
    return 0;
}

-- 多 State 模型下，场景脚本通过「句柄」引用引擎对象，
-- 而不是直接持有别的 State 里的 userdata
local scene = engine.create_scene("battle")
scene:set_ambient_light({r = 0.3, g = 0.3, b = 0.3})

// 伪代码：场景切换时重建脚本状态
class LuaHost {
    lua_State* L_;
public:
    void load_scene(const std::string& scene) {
        if (L_) lua_close(L_);
        L_ = luaL_newstate();
        luaL_openlibs(L_);
        luaL_dofile(L_, ("scripts/" + scene + ".lua").c_str());
    }
    void update(float dt) {
        lua_getglobal(L_, "update");
        lua_pushnumber(L_, dt);
        lua_pcall(L_, 1, 0, 0);
    }
};

// 把一个 C++ Sprite* 包装成 userdata 并设置元表
static int l_new_sprite(lua_State *L) {
    Sprite **ud = (Sprite**)lua_newuserdata(L, sizeof(Sprite*));
    *ud = new Sprite(luaL_checkstring(L, 1));

    // 绑定元表，实现对象方法与 GC
    luaL_getmetatable(L, "Sprite");
    lua_setmetatable(L, -2);
    return 1;
}

static int l_sprite_set_position(lua_State *L) {
    Sprite **ud = (Sprite**)luaL_checkudata(L, 1, "Sprite");
    (*ud)->setPosition(luaL_checknumber(L, 2),
                       luaL_checknumber(L, 3));
    return 0;
}

static int l_sprite_gc(lua_State *L) {
    Sprite **ud = (Sprite**)luaL_checkudata(L, 1, "Sprite");
    delete *ud;
    return 0;
}

// 注册元表：__gc 保证 C++ 对象随 Lua GC 释放
static const luaL_Reg meta[] = {
    { "setPosition", l_sprite_set_position },
    { NULL, NULL }
};

#include <LuaBridge/LuaBridge.h>

// 先注册类型，再注册构造器、方法与属性
luabridge::getGlobalNamespace(L)
    .beginClass<Vector3>("Vector3")
        .addConstructor<void (*)(float, float, float)>()
        .addProperty("x", &Vector3::x)
        .addFunction("normalize", &Vector3::normalize)
    .endClass();

local v = Vector3(1, 2, 3)
v:normalize()
print(v.x, v.y, v.z)

-- 反例：每帧多次跨层调用
function Player:update(dt)
    self.transform:set_position(self.x, self.y)
    self.sprite:set_flip_x(self.facing < 0)
    self.rigidbody:set_velocity(self.vx, self.vy)
end

-- 正例：合并成一次 update 调用，减少 Lua↔C++ 往返
function Player:update(dt)
    self.actor:apply_state {
        pos = {self.x, self.y},
        flip = self.facing < 0,
        vel = {self.vx, self.vy},
    }
end

local scene = cc.Scene:create()
local layer = cc.Layer:create()
scene:addChild(layer)

local label = cc.Label:createWithTTF("Hello Lua", "fonts/arial.ttf", 36)
label:setPosition(display.cx, display.cy)
layer:addChild(label)

-- 触摸事件回调
local function onTouchBegan(touch, event)
    local pos = touch:getLocation()
    print("touch at", pos.x, pos.y)
    return true
end
layer:registerScriptTouchHandler(onTouchBegan)

-- Cocos Creator 风格 Lua 组件（伪代码）
local PlayerController = script.Component("PlayerController")

function PlayerController:onLoad()
    self.speed = 5
end

function PlayerController:update(dt)
    local pos = self.node.position
    pos.x = pos.x + self.speed * dt
    self.node:setPosition(pos)
end

-- Defold 标准脚本组件模板
function init(self)
    -- 初始化
    self.velocity = vmath.vector3(0, 0, 0)
end

function update(self, dt)
    -- 每帧更新
    local pos = go.get_position()
    go.set_position(pos + self.velocity * dt)
end

function on_message(self, message_id, message, sender)
    -- 处理其他对象发来的消息
    if message_id == hash("hit") then
        self.hp = self.hp - message.damage
    end
end

-- 向名为 "enemy1" 的对象发消息
msg.post("enemy1#controller", "hit", { damage = 10 })

-- 在 enemy1#controller 里接收
function on_message(self, message_id, message, sender)
    if message_id == hash("hit") then
        -- 处理伤害
    end
end

-- 简单的脚本级资源缓存
local Cache = {}
Cache.__index = Cache

function Cache.new()
    return setmetatable({items = {}}, Cache)
end

function Cache:get(key, loader)
    if self.items[key] then
        return self.items[key]
    end
    local item = loader(key)
    self.items[key] = item
    return item
end

-- 使用：懒加载 + 缓存
local atlases = Cache.new()
local atlas = atlases:get("ui_main", function(k)
    return resources.load_atlas("res/" .. k .. ".atlas")
end)

-- 热更管理器：下载新脚本包并触发重载
local HotUpdate = {}
HotUpdate.__index = HotUpdate

function HotUpdate:reload(package)
    -- 1. 校验版本
    if not self:_verify(package) then return false end
    -- 2. 保存需要迁移的状态
    local saved = self:_snapshot_state()
    -- 3. 重启脚本宿主（由引擎完成，见宿主生命周期）
    -- 4. 恢复状态
    self:_restore_state(saved)
    return true
end

-- 反例：每帧在 Lua 中重建表、做大量数学运算
function Enemy:update(dt)
    local dir = self.aim - self.pos
    local len = math.sqrt(dir.x * dir.x + dir.y * dir.y)
    if len > 0.001 then
        dir.x, dir.y = dir.x / len, dir.y / len
        self.pos = self.pos + dir * self.speed * dt
        -- 每帧创建临时表，GC 压力大
    end
end

-- 正例：用引擎数学库的批量计算，减少脚本层开销
function Enemy:update(dt)
    -- 向量运算下沉到引擎 C++ 实现
    local dir = vmath.normalize(self.aim - self.pos)
    self.pos = self.pos + dir * self.speed * dt
end