Getting Started with Lua and CEGUI

The Lua scripting module for CEGUI is based on pure Lua 5.0.2 and tolua++ 1.0.4. As these libraries were diffucult to find in working precompiled versions, I decided to include them with the scripting module.

When using CEGUI with a scripting module a lot of the interface programming can be replaced by scripts, these script can be modified and used without recompling your program, thus leave more time for tweaking your UI instead of waiting for your compiler to finish.

The current Lua script module is still fairly early in development. It supports most of the core system, and the base window class, more specific widgets can currently only be configured using the properties system.

At this time the Lua script module is only in CVS.

Ok. Let's get started. I assume that you are familiar with the CEGUI basics. Initialisation, creating windows etc. and Lua, so I'll pick up from about there.

Initialisation

The Lua scripting module exports all the manager classes and such it is possible to do the basic CEGUI initialization from Lua.

the basic CEGUI init sequence is like this:

#include "LuaScriptModule.h"

CEGUI::YourRendererOfChoice* renderer = new YourRendererOfChoice;
CEGUI::LuaScriptModule* script_module = new CEGUI::LuaScriptModule();
new CEGUI::System( renderer, script_module );

now the CEGUI::System is created and the scripting module is attached properly. In this case the constructor of the LuaScriptModule created a Lua state for us. You can also pass a lua_State* as the first parameter to the LuaScriptModule constructor to use your own Lua state instead:

...
lua_State* s = your_lua_state;
CEGUI::LuaScriptModule* script_module = new CEGUI::LuaScriptModule(s);
...

You would probably want to do this if you are using custom functions in the init-script.

Init / Exit Script

CEGUI supports a configuration file. The filename for this is an optional parameter to the CEGUI::System constructor. It defaults to cegui.config

This configuration file gives you the posibility to execute a script file during system creation and destruction. A configuration file could look like this:

<?xml version="1.0" ?>
<CEGUIConfig InitScript="../datafiles/scripts/init_script.lua" TerminateScript="../datafiles/scripts/exit_script.lua" />

init_script.lua is a text file containing the Lua script code to be executed on init. Here's an example:

-- get CEGUI singletons
local logger = CEGUI.Logger:getSingleton()
logger:logEvent( ">>> Init script says hello" )
--logger:setLoggingLevel( CEGUI.Informative )

-- get a local reference to the singletons we use (not required)
local system	= CEGUI.System:getSingleton()
local fontman	= CEGUI.FontManager:getSingleton()
local schememan= CEGUI.SchemeManager:getSingleton()

-- load schemes
schememan:loadScheme( "../datafiles/schemes/TaharezLook.scheme" )
schememan:loadScheme( "../datafiles/schemes/WindowsLook.scheme" )

-- load and set default font
local font = fontman:createFont( "../datafiles/fonts/Commonwealth-10.font" )
system:setDefaultFont( font )

-- set default mouse cursor
system:setDefaultMouseCursor( "TaharezLook","MouseArrow" )

logger:logEvent( "<<< Init script says goodbye" )

you don't have to have both init and exit scripts, but if you allocate "global" memory from the initscript you should free it in the exit script.

Now you know how to initialise CEGUI with the Lua scripting module. More tutorials will follow soon with more advanced topics.

--Lindquist 19:25, 5 May 2005 (BST)