Getting Started with Lua and CEGUI

Written for CEGUI 0.7

---

Works with versions 0.7.x (obsolete)

The Lua scripting module for CEGUI is based on Lua 5.1 and tolua++ 1.0.6pre2-1. As these libraries were difficult (or impossible) to find in working precompiled versions, I decided to include them with the scripting module (That is the source is included, and there are makefiles available). There is no link to the tolua++ version used on their website, but it's available here

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 "CEGUILua.h"

CEGUI::YourRendererOfChoice& renderer = CEGUI::YourRendererOfChoice::create();
CEGUI::YourResourceProviderOfChoice& rp= CEGUI::YourResourceProviderOfChoice::create();
CEGUI::YourImageCodecOfChoice& ic= CEGUI::YourImageCodecOfChoice::create();
CEGUI::LuaScriptModule& script_module = CEGUI::LuaScriptModule::create();
// (Pass 0 for the third argument, which is the xml parser to use. 0 means the default one)
System::create(renderer, reinterpret_cast<ResourceProvider*>(&rp), static_cast<XMLParser*>(0), reinterpret_cast<ImageCodec*>(&ic),&scriptmod,"cegui.config");

now the CEGUI::System is created and the scripting module is attached properly.

You would probably want to do some stuff if you are using custom functions in the init-script (cegui.config defines the init script later).

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 during system creation and destruction. A configuration file could look like this:

<?xml version="1.0" ?>
<CEGUIConfig>
<Scripting 
    initScript="init_script.lua"
    terminateScript="exit_script.lua" 
/>
</CEGUIConfig>

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:create( "TaharezLook.scheme" )
schememan:create( "WindowsLook.scheme" )

-- load a default font
fontman:create( "DejaVuSans-10.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 (or somewhere else appropriate).

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

You can execute more scripts from c side like this:

System::getSingleton().executeScriptFile("demo8.lua");

or from Lua like this:

system:executeScriptFile("demo8.lua")

As you can see all CEGUI functions are exposed to Lua and you can use them from there.

--User:Lindquist 19:25, 5 May 2005 (BST) updated to 0.7 --User:DEvil HUnter 21:10, 28 August 2012 (MEZ)