Integración con Lua

Lua es un lenguaje de programación originalmente diseñado para extender aplicaciones, pero también es utilizado frecuentemente como un sistema de scripts multipropósito y de modo stand-alone. Combina una sintaxis procedural con tipos de datos poderosos como arrays asociativos. Es interpretado a partir de bytecodes y posee gestión automática de memoria. Se encuentra implementado a partir de una pequeña librería escrita en lenguaje C y compila sin modificaciones en cualquier plataforma conocida.

Ha sido utilizado en juegos como Battle Mages, Vendetta, FarCry, Homeworld2 y PainKiller.

1. Ejecutar un script desde C++

Como con todo API de integración habrá un archivo cabecera (uno o más) y una librería (una o más) que deberemos utilizar. En este caso los archivos cabecera son:

[código C++]

| extern "C"
| {
| #include <lua.h>
| #include <lauxlib.h>
| #include <lualib.h>
| }


Y las librerías que debemos enlazar son dos:

[código C++]

| #if _DEBUG
| #pragma comment(lib, "../lib/luad.lib")
| #pragma comment(lib, "../lib/lualibd.lib")
| #else
| #pragma comment(lib, "../lib/lua.lib")
| #pragma comment(lib, "../lib/lualib.lib")
| #endif


Ahora, veamos el primer ejemplo. La idea es ejecutar el siguiente script Lua:

[código Lua]

| io.write("Mensaje de texto\n");


El script en cuestión deberá escribir un texto cualquier en pantalla. Veremos que código C++ nos permite ejecutar dichas líneas en Lua:

[código C++]

| int main(int argc, char* argv[])
| {
| // Abro el intérprete
| lua_State * pState = lua_open();
|
| // Cargo la librería en entrada/salida
| luaopen_io(pState);
|
| // Cargo el archivo de script
| luaL_loadfile(pState, "../../scripts/script1.lua");
|
| // Ejecuto el script
| int iError = lua_pcall(pState, 0, 0, 0);
|
| // Si existe un error lo informo
| if (iError)
| {
| cout << lua_tostring(pState, -1) << endl;
| lua_pop(pState, 1);
| }
|
| // Cierro el intérprete
| lua_close(pState);
|
| return 0;
| }


Veamos cuales son las funciones más importantes que utilizamos:

lua_open() : Abre el intérprete. Este paso es necesario para realizar cualquier operación con scripts. Nota que retorna un puntero al estilo fopen, que luego deberá ser utilizado para pasarle a otras funciones del API.
lua_close() : Cierra el intérprete.
luaopen_io() : Abre la librería en entrada/salida. Este paso es necesario debido a que hacemos uso de esta librería en Lua. Más adelante requeriremos utilizar otras librerías, también podríamos no haber utilizado ninguna y esta función no habría sido necesario invocar.
luaL_loadfile() : Todas las funciones que poseen una “L” mayúscula luego del prefijo “lua” pertenecen a la librería auxiliar del Lua, el paquete de funciones que acompaña esta librería son de alto nivel y no forman parte del núcleo del motor de script. En este caso, esta función cargará un script lua (pero no lo ejecutará).
lua_pcall() : Ejecuta un script lua cargado por el motor. Es posible transferir argumentos a la invocación.

El valor de retorno de funciones como luaL_loadfile, lua_pcall y otras tantas es un número entero que representa un código de error. Cuando es cero significa que la operación se ha concretado de manera exitosa. Si miramos el código que hemos escrito, cuando el valor de retorno de lua_pcall es distinto a cero escribo en el stdout un string retornado por la función lua_tostring y luego realizo un lua_pop, esto tiene que ver con el modo de funcionamiento del pasaje de datos entre C/C++ y el motor de script Lua.

2. Ejecutar una función de un script desde C++ pasando un parámetro

Antes de pasar al paso 2, introduciremos un ejemplo intermedio que será ver como realizar un pasaje de datos a un script Lua sin utilizar una función ¿cómo es eso? Como comentamos en el párrafo anterior, el pasaje de datos entre C/C++ y Lua posee una particularidad, Lua define una pila virtual en la cual se pueden insertar y extraer datos (y no necesariamente del modo tradicional en que se maneja una pila). Para la manipulación de esta pila existen funciones específicas de Lua como lua_push, lua_pop y muchas otras. Esta pila es utilizada para la comunicación C++ hacia Lua y viceversa. Veamos:

Escribiremos el código Lua:

[código Lua]

| for i=0,table.getn(arg) do
| print(i,arg[i])
| end


En este código solicitamos la tabla “arg” al sistema y navegamos la misma imprimiendo su contenido. Veamos entonces como crear e ingresar datos en la tabla “arg”:

[código C++]

| int main(int argc, char* argv[])
| {
| // Abro el intérprete
| lua_State * pState = lua_open();
|
| // Cargo la librería en entrada/salida
| openstdlibs(pState);
| // Cargo el archivo de script
| luaL_loadfile(pState, "../../scripts/script2.lua");
|
| // start array structure
| lua_newtable(pState);
|
| // set first element "0" to value 45
| lua_pushnumber(pState, 0 );
| lua_pushnumber(pState, 45 );
| lua_rawset(pState, -3 );
|
| // set second element "1" to value 99
| lua_pushnumber(pState, 1 );
| lua_pushnumber(pState, 99 );
| lua_rawset(pState, -3 );
| // set the number of elements minus 1 (index to the last array element)
| lua_pushliteral(pState, "n" );
| lua_pushnumber(pState, 1 );
| lua_rawset(pState, -3 );
|
| // set the name of the array that the script will access
| lua_setglobal(pState, "arg" );
|
| // Ejecuto el script
| int iError = lua_pcall(pState, 0, LUA_MULTRET, 0);
|
| // Si existe un error lo informo
| if (iError)
| {
| cout << lua_tostring(pState, -1) << endl;
| lua_pop(pState, 1);
| }
|
| // Cierro el intérprete
| lua_close(pState);
|
| return 0;
| }


Analicemos el código anterior:

[código C++]

| lua_newtable(pState);


La función crea una tabla nueva.

[código C++]

| lua_pushnumber(pState, 0 );
| lua_pushnumber(pState, 45 );
| lua_rawset(pState, -3 );


A continuación insertamos información en la tabla, para esto primero insertamos el número índice, luego el contenido y finalmente le indicamos que tome estos números y lo inserte en la tabla. El número negativo 3 tiene relación a que estamos referenciando la primer posición de la pila de manera relativa desde la posición actual de inserción (el hecho que el número sea negativo tiene que ver con esto, los números positivos referencian posiciones absolutas). Es decir, estamos posicionados en el tercer elemento, la indicación de un -3 referencia a tres posiciones hacia atrás, al primer elemento.

Nota: Es importante conocer como gestionar la pila mediante métodos del API que ofrece Lua, para esto es recomendable leer el siguiente capítulo del libro “Lua 5.0 Reference Manual” que es posible acceder mediante el siguiente enlace: http://lua-users.org/wiki/FunctionsTutorial

[código C++]

| lua_setglobal(pState, "arg" );


Finalmente, fijamos el nombre a la tabla.

Luego, la invocación al script se realiza del modo usual como ya hemos visto en el paso 1.

3. Ejecutar una función C++ desde un script

Para poder ejecutar una función C++ desde Lua deberemos, así como hemos hecho con Python, registrar una función tipo proxy para que la misma sea visible desde el script. La razón por la cual deberemos utilizar una función tipo proxy y no podamos llamar directamente a la función de interés tiene que ver con un prototipo específico que debe poseer toda función a registrar para que pueda ser llamada desde Lua. El prototipo en cuestión es el siguiente:

[código C++]

| typedef int (*lua_CFunction) (lua_State *L);


Por ejemplo, si deseamos poder registrar una función llamada “proxy_a_foo” deberemos escribir:

[código C++]

| int proxy_a_foo(lua_State *pState)
| {
| // ...
| }


Como parámetro la función recibirá el descriptor del intérprete abierto por medio de la función lua_open que utilizaremos para extraer los parámetros a la función pasados haciendo uso de la pila.

Para registrar nuestra función haremos uso de una conveniente y popular macro:

[código C++]

| #define lua_register(L,n,f) (lua_pushstring(L, n), lua_pushcfunction(L, f), lua_settable(L, LUA_GLOBALSINDEX))


La macro recibe como primer parámetro el descriptor del intérprete (como casi toda función lua), el segundo parámetro es el nombre simbólico que se utilizará desde lua para acceder a la función proxy y el tercer parámetro es el puntero a la función proxy a invocar.

[código C++]

| lua_register(pState, "foo", proxy_a_foo);


Veamos el código de script lua que hará uso de nuestra función:

[código Lua]

| foo()


Ahora veamos el programa completo en C++:

[código C++]

| // Función que deseo invocar en C++
| void foo()
| {
| cout << "Mensajes desde C++" << endl;
| }
|
| // Función proxy a foo
| int proxy_a_foo(lua_State *pState)
| {
| foo();
| return 0;
| }
|
| int main(int argc, char* argv[])
| {
| // Abro el intérprete
| lua_State * pState = lua_open();
|
| // registro la función
| lua_register(pState, "lafunc", proxy_a_foo);
|
| // Cargo el archivo de script
| luaL_loadfile(pState, "../../scripts/script4.lua");
|
| // Ejecuto el script
| int iError = lua_pcall(pState, 0, 0, 0);
|
| // Si existe un error lo informo
| if (iError)
| {
| cout << lua_tostring(pState, -1) << endl;
| lua_pop(pState, 1);
| }
|
| // Cierro el intérprete
| lua_close(pState);
|
| return 0;
| }


Ahora, agreguemos el pasaje de un parámetro, desde lua ahora escribiremos:
foo(5)

Y en C++, nuestra función proxy ahora deberá extraer el parámetro desde la pila:

[código C++]

| // Función proxy a foo
| int proxy_a_foo(lua_State *pState)
| {
| int iValor = lua_tonumber(pState, -1);
| lua_pop(pState, 1);
| foo(iValor);
|
| return 0;
| }


Como sabemos que el valor a extraer se encuentra en el extremo superior de la pila y además sabemos que el parámetro es numérico, entonces tomamos dicho valor haciendo uso de la función lua_tonumber. Además, como es nuestro deber dejar la pila limpia de todo parámetro, extraemos el mismo utilizando la función lua_pop.

De manera análoga podremos realizar pasajes de parámetros de cualquier tipo.

4. Ejecutar el método de una clase desde un script

El modo más simple de acceder a objetos desde Lua es utilizando una metodología similar a la que hemos utilizado en Python, es decir, utilizando una referencia explícita al objeto. Sin embargo, es posible mediante la escritura de más código escribir una clase como si fuese una tabla Lua de modo incluya propiedades y funciones, más tarde haciendo uso de ToLua veremos como acceder a métodos de clases de este modo.

Por ahora, podremos pasar al script Lua una tabla con la referencia al objeto que deseamos utilizar desde el script. También, introduciremos en nuestra clase métodos estáticos (que al no poseer puntero this son como funciones globales) que oficien de funciones proxy a los métodos reales. Veamos:

[código C++]

| class ClaseFoo
| {
| short m_sValor;
| public:
| bool SetValor(short sValor);
| short GetValor();
|
| // Funciones proxy para acceso a métodos desde Lua
| static int ls_SetValor(lua_State *pState);
| static int ls_GetValor(lua_State *pState);
| };


Notemos que los métodos estáticos cumplen con el prototipo solicitado por Lua para registrar funciones.

El contenido de la función ls_SetValor será:

[código C++]

| int ClaseFoo::ls_SetValor(lua_State *pState)
| {
| int iValor = lua_tonumber(pState, -1);
| lua_pop(pState, 1);
|
| ClaseFoo * pObj = (ClaseFoo *) lua_touserdata(pState, -1);
| lua_pop(pState, 1);
|
| pObj->SetValor(iValor);
|
| return 0;
| }


Como podemos apreciar la idea es recuperar el primer valor recibido del stack como el valor a utilizar como parámetro en el llamado al método, y el segundo valor obtenido del stack es el puntero al objeto que casteamos para luego poder realizar la invocación.

El código del cuerpo principal del programa es:

[código C++]

| int main(int argc, char* argv[])
| {
|
| // Abro el intérprete
| lua_State * pState = lua_open();
|
| // Cargo la librería en entrada/salida
| openstdlibs(pState);
|
| lua_register(pState, "clasefoo_setvalor", ClaseFoo::ls_SetValor);
| lua_register(pState, "clasefoo_getvalor", ClaseFoo::ls_GetValor);
|
| // Cargo el archivo de script
| luaL_loadfile(pState, "../../scripts/script5.lua");
|
| // Creo una instancia de ClaseFoo
| ClaseFoo obj;
|
| // Ahora paso el puntero al objeto al script por medio del stack
| lua_newtable(pState);
|
| lua_pushnumber(pState, 0 );
| lua_pushlightuserdata(pState, &obj);
| lua_rawset(pState, -3 );
|
| lua_pushliteral(pState, "n" );
| lua_pushnumber(pState, 1 );
| lua_rawset(pState, -3 );
|
| lua_setglobal(pState, "obj");
|
| // Ejecuto el script
| int iError = lua_pcall(pState, 0, 0, 0);
|
| // Si existe un error lo informo
| if (iError)
| {
| cout << lua_tostring(pState, -1) << endl;
| lua_pop(pState, 1);
| }
|
| // Cierro el intérprete
| lua_close(pState);
|
| return 0;
| }


El código del script Lua:

[código Lua]

| -- Puntero a objeto en obj[0]
| print(obj[0])
|
| -- Invoco a función de objeto
| clasefoo_setvalor(obj[0], 5)


Al igual que con Python, no es difícil notar que este acercamiento si bien es el que menos código de pegado requiere tiene sus contrariedades:

. Pérdida de elegancia en la sintaxis
. Peligro de realizar un casting inválido, fruto de un error en el script (esto podríamos evitarlo haciendo uso de RTTI para verificar que el cast a realizar sea válido antes de invocar un método o acceder a una propiedad).

Pages: 1 2 3 4 5 6

Comentarios (3)