Plugin Manual

What's this

This is a simple description of the LuaPlugin provided with the engine. THe reader should be familar with the lua language. Visit  http://www.lua.org to get more information about the lua scripting language.

Load plugin

Lua is a simple and powerfull scripting language developed mainly as embedded scripting langauge in mind. In our engine we provide a plugin to include lua scripting into your application.

For a simple use of lua language please ensure, that luaScripting.so (Unix) or luaScripting.dll (Windows) is properly installed, for example under the "data/plugins/" path. To load the lugin you can just call:

    Engine::sResourceManager()->loadResource("luaPlugin", "Plugins", "data/plugins/luaScripting", "Plugin");

This will load the resource of type "Plugin" with the name "luaPlugin" into the resource group "Plugins" from the file "data/plugins/luaScripting" (here you do not have to specify the file extensions, since the engine will add a proper extensions, based on your operating system).

When the plugin is loaded it will register itself by the engine and will provide an interface for loading and handling of *.lua files. It will also provide a new resource types "Lua" and "LuaScript?", so that any resources of this type will be handled by the plugin.

Use userdefined lua_state

In the case you want to use your own lua state, so that all your manually defined functions are also accessable from the lua plugin, you can pass your lua state as a parameter to the plugin. This can be achieved in the following way:

    // create my own lua state
    mLuaState = luaL_newstate();
    if (mLuaState)
    {
        // open default lua libs 
        luaL_openlibs(mLuaState);

        // now load plugin and pass the state as parameter
        PropertyList _property;
        _property["luastate"].setUserData(mLuaState);
        Engine::sResourceManager()->loadResource("luaPlugin", "Plugins", "data/plugins/luaScripting", "Plugin", &_property);
    }

This kind of code is usefull if you want to connect the complete lua environment by the luabind library, which is currently not provided by the plugin. To find more information about the luabind, visit their homepage at  http://www.rasterbar.com/products/luabind.html

Default lua script

To separate different scripts you must be familar with handling of lua environments. I propose to load following lua script as first, which do this job for you. It provides a simple function enabling loading of scripts from c-strings. Also a simple printf function is provided.

-- -----------------------------------------------------------
--
-- Setup the lua environment in the way we need for scripting.
-- This script must be loaded and executed as first script
-- before other scripts are loaded. The script will define
-- a new function called scriptload() which load new scripts
-- from sctrings defined by the c-programm.
--
-- Loaded scripts get it's own local environment, so they
-- can not overwrite global functions with the same name.
--
-- -----------------------------------------------------------

-- -----------------------------------------------------------
-- Global function allowing us formatted print on the console
-- -----------------------------------------------------------
function printf(...) io.write(string.format(unpack(arg))) end

-- Environment to be used for all scripts
local GLOBAL = {
	
	-- Define functions usefull for all other scripts
	printf = printf
	
}

-- Connect our environment with the global one
setmetatable (GLOBAL, { __index = _G})


-- -----------------------------------------------------------
-- We define new function which is now capable to load
-- new scripts from strings and connect them to the environment
-- -----------------------------------------------------------
function loadstringscript (scriptstr)
	local scriptenv = {}
	
	setmetatable (scriptenv, {__index=GLOBAL})
	local chunk  = loadstring (scriptstr)
	setfenv (chunk, scriptenv)
		
	chunk ()
	return scriptenv
end

See also: ManualPage, ResourceManagment?,  http://www.lua.org,  http://luabind.sourceforge.net