环境: cocos3.10 Lua5.1.4 Visual Studio 2013
简介
Lua作为一种脚本语言(https://www.lua.org/),它提供了很多的 C API使得C/C++与Lua之间进行通信交互。
在cocos2d-x中lua与C++的交互,主要借助于第三方工具tolua++来实现。
该工具会将C++按照Lua支持的C API指定生成绑定代码,以便于Lua通过这些绑定代码更快捷的访问C++下的类及方法相关。
Lua_State
一般脚本语言的运行需要宿主的存在,且要有对应的虚拟机。
在cocos中,我们可以认为C/C++就是lua的宿主,而虚拟机说白了就是要提供一个lua运行的环境,该环境下需要保存Lua脚本运行的内存空间,全局变量,库文件等, 该环境被称为Lua_State。
在Lua_State环境下,若实现Lua与C/C++的数据交互,我们需要有个容器来对数据进行传递,这个容器就是Lua虚拟栈。
Lua虚拟栈
栈的特点是先进后出的,在Lua的虚拟栈中,栈中数据通过索引值进行定位,索引值可为正数,也可为负数。
通俗的来说,正数为1的永远表示栈底,负数为-1的永远表示栈顶。
(来源:https://blog.csdn.net/zhuzhuyule/article/details/41086745)
假设我们的C++想访问lua文件中的数据:
-- 文件命名为:test.lua
str = "Get Lua Data Sucess!!!"
function Add(num1, num2)
return num1 + num2
end
以C++获取lua变量str的数据为例,其简单的通信流程:
1. C/C++将参数str放入Lua堆栈(栈顶)中
2. Lua从堆栈中获取参数str,并将栈顶置为空
3. Lua从全局表中查找参数str对应的数据
4. 全局表将参数str的数据反馈给Lua
5. Lua将参数str的返回值放入堆栈中,此时返回值位于栈顶
6. C++从堆栈中获取返回值
/*
环境配置
1. 新建项目,选择Empty Project,在项目的Source Files新增.cpp文件
2. 若有Lua的相关环境,可将Lua/5.1目录下的include,lib文件夹拷贝到与.cpp文件同目录下
若无,则推荐LuaForWindows
其网址为:http://files.luaforge.net/releases/luaforwindows/luaforwindows
它会自动配置lua的环境,并安装SciTE工具相关,以后就可以在控制台,SciTE输入lua相关代码进行调试
属性配置,打开项目属性:
1. C/C++ -> General -> Additional Include Directories 将include目录添加进去
2. Linker -> General -> Additional Library Directories 将lib目录添加进去
3. 再通过Linker -> Input -> Additional Dependencies 添加lua5.1.lib, lua51.lib
*/
#include <iostream>
#include <string.h>
extern "C" {
#include "lua.h" // 提供了Lua的基本函数,在lua.h中的函数均已"lua_"为前缀
#include "lualib.h" // 定义lua的标准库函数,比如table, io, math等
#include "lauxlib.h" // 提供了辅助库相关,以"luaL_"为前缀
}
void main(){
// 创建lua环境,并加载标准库
lua_State* pL = lua_open();
luaL_openlibs(pL);
// 加载lua文件,返回0表示成功
int code = luaL_loadfile(pL, "test.lua");
if (code != 0){
return;
}
// 执行lua文件,参数分别为,lua环境,输入参数个数,返回值个数
lua_call(pL, 0, 0);
// 重置栈顶索引,设置为0表示栈清空
lua_settop(pL, 0);
// ------------- 读取变量 -------------
//lua_getglobal 主要做了这么几件事: 将参数压入栈中,lua获取参数的值后再将返回的结果压入栈中
lua_getglobal(pL, "str");
// 判定栈顶值类型是否为string,返回1表示成功,0表示失败
int isStr = lua_isstring(pL, 1);
if (isStr == 1) {
// 获取栈顶值,并将lua值转换为C++类型
std::string str = lua_tostring(pL, 1);
std::cout << "str = " << str.c_str() << std::endl;
}
// ------------- 读取函数 -------------
lua_getglobal(pL, "Add");
// 将函数所需要的参数入栈
lua_pushnumber(pL, 1); // 压入第一个参数
lua_pushnumber(pL, 2); // 压入第二个参数
/*
lua_pcall与lua_call类似,均用于执行lua文件,其方法分别为:
void lua_call(lua_State *L, int nargs, int nresults);
int lua_pcall(lua_State *L, int nargs, int nresults, int errfunc);
两者的区别在于:
前者在出现错误,程序会崩溃。后者多了一个errfunc索引,用于准确定位错误处理函数。
函数执行成功返回0,失败后可通过获取栈顶信息获取错误数据
两者的共同之处在于:
会根据nargs将参数按次序入栈,并根据nresults将返回值按次序填入栈中
若返回值结果数目大于nresults时,多余的将被丢弃;若小于nresults时,则按照nil补齐。
*/
int result = lua_pcall(pL, 2, 1, 0);
if (result != 0) {
const char *pErrorMsg = lua_tostring(pL, -1);
std::cout << "ERROR:" << pErrorMsg << std::endl;
lua_close(pL);
return;
}
/*
此处的栈中情况:
------------- 栈顶 -------------
正索引 负索引 类型 返回值
2 -1 number 3
1 -2 string "Get Lua Data Sucess!!!"
------------- 栈底 -------------
因此如下的索引获取数字索引可以使用-1或者2
*/
int isNum = lua_isnumber(pL, -1);
if (isNum == 1) {
double num = lua_tonumber(pL, -1);
std::cout << "num = " << num << std::endl;
}
// 关闭state环境,即销毁Lua_State对象,并释放Lua动态分配的空间
lua_close(pL);
system("pause");
}
在如上的代码中我们发现:
1. C++在获取不同文件下的方法时,是通过include引用后,然后就直接调用;
2. Lua却是在通过luaL_loadfile进行加载,然后再通过lua_call/lua_pcall进行执行后才能获取对应的变量或者函数返回值。
其原因在于:lua的脚本若为执行在其全局变量表中是不会存储相关数据的,这一点千万要注意。
接下来我们介绍一些lua C API常用方法:
/*
获取栈顶索引即栈中元素的个数,因为栈底为1,所以栈顶索引为多少,就代表有多少个元素
*/
int lua_gettop(lua_State *L);
/*
将栈顶索引设置为指定的数值
若设置的index比原栈顶高,则以nil补足。若index比原栈顶低,高出的部分舍弃。
比如: 栈中有8个元素,若index为7,则表示删除了一个栈顶的元素。若index为0,表示清空栈
注意,index可为正数也可为负数,但若index为正数表示相对于栈底设置的,若为负数则相对于栈顶而设置的
*/
void lua_settop(lua_State *L, int index);
/*
将栈中索引元素的副本压入栈顶
比如:从栈底到栈顶,元素状态为10,20,30,40;若索引为3则元素状态为:10,20,30,40,30
类似的还有:
lua_pushnil: 压入一个nil值
lua_pushboolean: 压入一个bool值
lua_pushnumber: 压入一个number值
*/
void lua_pushvalue(lua_State *L, int index);
/*
删除指定索引元素,并将该索引之上的元素填补空缺
比如:从栈底到栈顶,元素状态为10,20,30,40;若索引为-3则元素状态为10,30,40
*/
void lua_remove(lua_State *L, int index);
/*
将栈顶元素替换索引位置的的元素
比如:从栈底到栈顶,元素状态为10,20,30,40,50;若索引为2则,元素状态为10,50,30,40
即索引为2的元素20被栈顶元素50替换
*/
void lua_replace(lua_State *L, int index);
/*
获取栈中指定索引元素的类型,若失败返回类型LUA_TNONE
其它类型有:
LUA_TBOOLEAN, LUA_TNUMBER, LUA_TSTRING, LUA_TTABLE
LUA_TFUNCTION, LUA_USERDATA等
*/
int lua_type(lua_State *L, int idx);
/*
检测栈中元素是否为某个类型,成功返回1,失败返回0
类似的还有:
lua_isnumber, lua_isstring, lua_iscfunction, lua_isuserdata
*/
int lua_isXXX(lua_State *L, int index);
/*
将栈中元素转换为C语言指定类型
*/
lua_Number lua_tonumber(lua_State *L, int idx);
lua_Integer lua_tointeger(lua_State *L, int idx);
int lua_toboolean(lua_State *L, int idx);
const char* lua_tolstring(lua_State *L, int idx, size_t *len);
lua_CFunction lua_tocfunction(lua_State *L, int idx);
void* lua_touserdata(lua_State *L, int idx);
如上仅仅简单介绍了下C/C++与Lua交互的基本原理,我们真正的目的是为了了解Lua是如何调用cocos引擎对应的类方法的。
cocos Lua框架
Lua在cocos引擎封装相关,它主要被放在cocos引擎的libluacocos2d中
auto: 使用tolua++工具自动生成的C++代码相关
manual:放置了cocos扩展的一些功能,比如LuaEngine, LuaStack, LuaBridge(android, ios sdk交互相关)等
luajit: 高效版的lua库,额外添加了lua没有的cocos库,并在对浮点计算,循环等进行了优化
luasocket: 网络库相关
tolua: tolua++库相关,实质是对Lua C库进行的再封装
xxtea: 加密相关
而cocos引擎主要通过LuaEngine和LuaStack对Lua进行管理,LuaEngine是一个管理LuaStack的单例,而LuaStack则用于对Lua_State进行了封装。以cocos2d-lua在启动时调用main.lua为例,简单的说主要分为三个步骤:
1. 初始化LuaEngine,获取LuaState环境
2. 注册C++模块相关到Lua中
3. 执行Lua脚本
以cocos2d-lua启动游戏时,运行main.lua为例,主要接口在AppDelegate::applicationDidFinishLauching()中:
bool AppDelegate::applicationDidFinishLaunching()
{
// 初始化LuaEngine,在getInstance中会初始化LuaStack,LuaStack初始化Lua环境相关
auto engine = LuaEngine::getInstance();
// 将LuaEngine添加到脚本引擎管理器ScriptEngineManager中
ScriptEngineManager::getInstance()->setScriptEngine(engine);
// 获取Lua环境
lua_State* L = engine->getLuaStack()->getLuaState();
// 注册额外的C++ API相关,比如cocosstudio, spine, audio相关
lua_module_register(L);
//
register_all_packages();
// 设置cocos自带的加密相关
// 在LuaStack::executeScriptFile执行脚本文件时,会通过LuaStack::luaLoadBuffer对文件进行解密
LuaStack* stack = engine->getLuaStack();
stack->setXXTEAKeyAndSign("2dxLua", strlen("2dxLua"), "XXTEA", strlen("XXTEA"));
// 执行Lua脚本文件
if (engine->executeScriptFile("main.lua"))
{
return false;
}
return true;
}
通过LuaEngine::getInstance(),我们了解下LuaStack::init()的相关实现:
extern "C" {
#include "lua.h"
#include "tolua++.h"
#include "lualib.h"
#include "lauxlib.h"
}
bool LuaStack::init(void)
{
// 初始化Lua环境并打开标准库
_state = lua_open();
luaL_openlibs(_state);
toluafix_open(_state);
// 注册全局函数print到lua中,它会覆盖lua库中的print方法
const luaL_reg global_functions [] = {
{"print", lua_print},
{"release_print",lua_release_print},
{nullptr, nullptr}
};
// 注册全局变量
luaL_register(_state, "_G", global_functions);
// 注册cocos2d-x引擎的API到lua环境中
g_luaType.clear();
register_all_cocos2dx(_state);
...
#if (CC_TARGET_PLATFORM == CC_PLATFORM_IOS || CC_TARGET_PLATFORM == CC_PLATFORM_MAC)
// 导入ios下调用object-c相关API
LuaObjcBridge::luaopen_luaoc(_state);
#endif
#if (CC_TARGET_PLATFORM == CC_PLATFORM_ANDROID)
// 导入android下调用java相关API
LuaJavaBridge::luaopen_luaj(_state);
#endif
// 添加Lua的加载器,该方法将cocos2dx_lua_loader方法添加到Lua全局变量package下的loaders成员中
// 当requires加载脚本时,Lua会使用package下的loaders中的加载器,即cocos2dx_lua_loader来加载
// 设定cocos2dx_lua_loader,可以使得我们自定义设置搜索路径相关,且拓展实现对脚本的加密解密相关
addLuaLoader(cocos2dx_lua_loader);
return true;
}
我们看下cocod2dx_lua_loader的实现相关:
extern "C"
{
int cocos2dx_lua_loader(lua_State *L)
{
// 后缀为luac和lua
static const std::string BYTECODE_FILE_EXT = ".luac";
static const std::string NOT_BYTECODE_FILE_EXT = ".lua";
// require传入的要加载的文件名,比如:require "cocos.init" 下的"cocos.init"
std::string filename(luaL_checkstring(L, 1));
// 去掉后缀名".luac"或“.lua”
size_t pos = filename.rfind(BYTECODE_FILE_EXT);
if (pos != std::string::npos)
{
filename = filename.substr(0, pos);
}
else
{
pos = filename.rfind(NOT_BYTECODE_FILE_EXT);
if (pos == filename.length() - NOT_BYTECODE_FILE_EXT.length())
{
filename = filename.substr(0, pos);
}
}
// 将"."替换为"/"
pos = filename.find_first_of(".");
while (pos != std::string::npos)
{
filename.replace(pos, 1, "/");
pos = filename.find_first_of(".");
}
Data chunk;
std::string chunkName;
FileUtils* utils = FileUtils::getInstance();
// 获取package.path的变量
lua_getglobal(L, "package");
lua_getfield(L, -1, "path");
// 通过package.path获取搜索路径相关,该路径为模版路径,格式类似于:
// ?; ?.lua; c:\windows\?; /usr/local/lua/lua/?/?.lua 以“;”作为分割符
std::string searchpath(lua_tostring(L, -1));
lua_pop(L, 1);
size_t begin = 0;
size_t next = searchpath.find_first_of(";", 0);
// 遍历package.path中的所有路径,查找文件是否存在,若文件存在则通过getDataFromFile读取文件数据
do
{
if (next == std::string::npos)
next = searchpath.length();
std::string prefix = searchpath.substr(begin, next);
if (prefix[0] == '.' && prefix[1] == '/')
{
prefix = prefix.substr(2);
}
pos = prefix.find("?.lua");
// 将?替换为文件名,获取搜索路径名,比如:?.lua替换为cocos/init.lua
chunkName = prefix.substr(0, pos) + filename + BYTECODE_FILE_EXT;
if (utils->isFileExist(chunkName))
{
chunk = utils->getDataFromFile(chunkName);
break;
}
else
{
chunkName = prefix.substr(0, pos) + filename + NOT_BYTECODE_FILE_EXT;
if (utils->isFileExist(chunkName))
{
chunk = utils->getDataFromFile(chunkName);
break;
}
}
// 指定搜素路径下不存在该文件,则下一个
begin = next + 1;
next = searchpath.find_first_of(";", begin);
} while (begin < (int)searchpath.length());
// 判定文件内容是否获取成功
if (chunk.getSize() > 0)
{
// 加载文件
LuaStack* stack = LuaEngine::getInstance()->getLuaStack();
stack->luaLoadBuffer(L, reinterpret_cast<const char*>(chunk.getBytes()),
static_cast<int>(chunk.getSize()), chunkName.c_str());
}
else
{
CCLOG("can not get file data of %s", chunkName.c_str());
return 0;
}
return 1;
}
}
通过此处的代码,我们可以了解到cocos2dx是如何搜索指定的lua文件。同时也会明白require为何可以使用"."来设定文件路径了,比如:
local cocosTest = require("app.Demo_Cocos.MainTest")
local TetrisTest = require("app.Demo_Tetris.UITetrisMain")
下面我们看下LuaStack::luaLoadBuffer的实现:
int LuaStack::luaLoadBuffer(lua_State *L, const char *chunk, int chunkSize, const char *chunkName)
{
int r = 0;
// 判定是否加密,若lua脚本加密,则解密后在加载脚本文件
// luaL_loadbuffer 用于加载并编译Lua代码,并将其压入栈中
if (_xxteaEnabled && strncmp(chunk, _xxteaSign, _xxteaSignLen) == 0)
{
// decrypt XXTEA
xxtea_long len = 0;
unsigned char* result = xxtea_decrypt((unsigned char*)chunk + _xxteaSignLen,
(xxtea_long)chunkSize - _xxteaSignLen,
(unsigned char*)_xxteaKey,
(xxtea_long)_xxteaKeyLen,
&len);
skipBOM((const char*&)result, (int&)len);
r = luaL_loadbuffer(L, (char*)result, len, chunkName);
free(result);
}
else
{
skipBOM(chunk, chunkSize);
r = luaL_loadbuffer(L, chunk, chunkSize, chunkName);
}
// 判定内容是否存在错误
#if defined(COCOS2D_DEBUG) && COCOS2D_DEBUG > 0
if (r)
{
switch (r)
{
case LUA_ERRSYNTAX:
// 语法错误
CCLOG("[LUA ERROR] load \"%s\", error: syntax error during pre-compilation.", chunkName);
break;
case LUA_ERRMEM:
// 内存分配错误
CCLOG("[LUA ERROR] load \"%s\", error: memory allocation error.", chunkName);
break;
case LUA_ERRRUN:
// 运行错误
CCLOG("[LUA ERROR] load \"%s\", error: run error.", chunkName);
break;
case LUA_ERRFILE:
// 文件错误
CCLOG("[LUA ERROR] load \"%s\", error: cannot open/read file.", chunkName);
break;
case LUA_ERRERR:
// 运行错误处理函数时发生错误
CCLOG("[LUA ERROR] load \"%s\", while running the error handler function.", chunkName);
default:
// 未知错误
CCLOG("[LUA ERROR] load \"%s\", error: unknown.", chunkName);
}
// 通过lua的堆栈,获取栈顶的错误信息,将错误日志打印出来(-1永远表示栈顶)
const char* error = lua_tostring(L, -1);
CCLOG("[LUA ERROR] Error Result: %s", error);
lua_pop(L, 1);
}
#endif
return r;
}
通过代码,我们可以了解到以下几方面的内容:
1. 了解LuaEngine在cocos2d-x中的通过LuaStack对 LuaState环境, LuaBridge等初始化
2. 了解lua脚本的加载,通过cocos2d-x自定义的cocos2dx_lua_loader实现,该接口
3. 了解Lua脚本的加密解密相关,及对lua脚本内容检测错误相关,通过luaLoadBuffer来实现。
tolua++接口相关:
我们以LuaStack下的register_all_cocos2dx()接口为例,tolua++相关的代码前缀都是“tolua_”
TOLUA_API int register_all_cocos2dx(lua_State* tolua_S)
{
tolua_open(tolua_S);
tolua_module(tolua_S,"cc",0);
tolua_beginmodule(tolua_S,"cc");
lua_register_cocos2dx_Ref(tolua_S);
lua_register_cocos2dx_Node(tolua_S);
// 省略...
tolua_endmodule(tolua_S);
return 1;
}
以lua_register_cocos2dx_Ref为例,看下实现代码:
int lua_register_cocos2dx_Ref(lua_State* tolua_S)
{
tolua_usertype(tolua_S,"cc.Ref");
tolua_cclass(tolua_S,"Ref","cc.Ref","",nullptr);
// tolua_function 表示对应的Ref所持有的public接口相关
tolua_beginmodule(tolua_S,"Ref");
tolua_function(tolua_S,"release",lua_cocos2dx_Ref_release);
tolua_function(tolua_S,"retain",lua_cocos2dx_Ref_retain);
tolua_function(tolua_S,"getReferenceCount",lua_cocos2dx_Ref_getReferenceCount);
tolua_endmodule(tolua_S);
std::string typeName = typeid(cocos2d::Ref).name();
g_luaType[typeName] = "cc.Ref";
g_typeCast["Ref"] = "cc.Ref";
return 1;
}
再看下关于getReferenceCount的实现
int lua_cocos2dx_Ref_getReferenceCount(lua_State* tolua_S)
{
int argc = 0;
cocos2d::Ref* cobj = nullptr;
bool ok = true;
#if COCOS2D_DEBUG >= 1
tolua_Error tolua_err;
#endif
// 从Lua栈中获取cocos对象类型,是否为cc.Ref
#if COCOS2D_DEBUG >= 1
if (!tolua_isusertype(tolua_S,1,"cc.Ref",0,&tolua_err)) goto tolua_lerror;
#endif
// 将数据转换为Ref对象,若失败则提示:无效的对象
cobj = (cocos2d::Ref*)tolua_tousertype(tolua_S,1,0);
#if COCOS2D_DEBUG >= 1
if (!cobj)
{
tolua_error(tolua_S,"invalid 'cobj' in function 'lua_cocos2dx_Ref_getReferenceCount'", nullptr);
return 0;
}
#endif
// 获取参数数目,-1的原因在于对象类型Ref也在栈中
argc = lua_gettop(tolua_S)-1;
if (argc == 0)
{
if(!ok)
{
tolua_error(tolua_S,"invalid arguments in function 'lua_cocos2dx_Ref_getReferenceCount'", nullptr);
return 0;
}
unsigned int ret = cobj->getReferenceCount();
tolua_pushnumber(tolua_S,(lua_Number)ret);
return 1;
}
luaL_error(tolua_S, "%s has wrong number of arguments: %d, was expecting %d \n", "cc.Ref:getReferenceCount",argc, 0);
return 0;
#if COCOS2D_DEBUG >= 1
tolua_lerror:
tolua_error(tolua_S,"#ferror in function 'lua_cocos2dx_Ref_getReferenceCount'.",&tolua_err);
#endif
return 0;
}
其他的cocos2d-x提供的Lua可调用方法不再赘述,与之类似。