= Scripting =

Orxonox uses [http://www.lua.org Lua] for its scripts. Scripts are code pieces which add another layer to the game logic. As a Gamer you know those events which happen, when you reached a certain level or entered a room or area with your character. Those events are most certainly produced with a script engine like ours.

Our script engine has access to all objects in the game and are therefore quite powerful and easy to use, as you may see in examples.

There are two applications for the Orxonox scripting engine.

== Level files ==
Our level files are pure XML-code. We add objects and ambient lights with XML tags and specify their parameters with attributes.

If your using the special lua tags ''<?lua'' and ''?>'' you can create levels easier. You could use loops to generate more objects and you can let a level depend on earlier accomplishments of the player. If you use random parameters you can even create a level which looks slightly different every time a player plays it. Here some examples how you could use Lua in our level files.

=== Example: Asteroid field ===
As I write this wiki page we have a level with 226 asteroids in it. For each asteroid we need one line of XML code:
{{{
...
<Model position="-9613,-4258,4537" scale="103" mesh="ast1.mesh" rotationAxis="0.820812,0.60695,0" rotationRate="13" />
<Model position="-6169,19264,-4878" scale="69" mesh="ast3.mesh" rotationAxis="0,0.585115,0.235653" rotationRate="32" />
<Model position="8717,-16685,9115" scale="37" mesh="ast4.mesh" rotationAxis="0.0512168,0.899599,0" rotationRate="15" />
...
}}}

With the scripting engine we could generate those asteroids a lot easier:
{{{
<?lua
for i = 1, 226, 1 
do ?>
<Model position="<?lua print(math.random(-19597, 18732))?>,
 <?lua print(math.random(-19597, 18732)) ?>,
 <?lua print(math.random(-19597, 18732)) ?>" scale="<?lua print(math.random( 20, 119)) ?>"
 mesh="ast<?lua print(i%6 + 1) ?>.mesh" rotationAxis="<?lua print(math.random()) ?>,
 <?lua print(math.random()) ?>, <?lua print(math.random()) ?>
 " rotationRate="<?lua print(math.random(16, 44)) ?>" />
<?lua 
end
?>
}}}
This will randomly arrange asteroids of different look and rotation axis and speed in an area. In fact you can code any Lua you want according to the [http://www.lua.org/manual/5.1/manual.htm Lua-Manual]. To actually add something to the XML-output you can use the ''print'' function. The above example shows you best how this works.

== Using C/C++ functions in Lua with toLua++ ==

We use toLua++ for the transition from Orxonox to Lua. To use Lua for scripting there are three steps you have to do:
 1. Mark the functions and classes you want to make accessible to Lua
 3. Update the CMakeLists.txt file
With those two steps Lua will be able to access the functions and classes you want to alter with the script.

=== Mark the function and classes ===
The included .h file will be parsed by toLua++. However we have to specify what exactly should be included. This is a shoted part of the Script.h file we justed included:
{{{
...
#include <list>
#include <string>

// tolua_begin
namespace orxonox
{

  class Script
  {
    // tolua_end
    public:
...
// some functions
    void luaPrint(std::string str); // tolua_export
...
  }; // tolua_export
} // tolua_export
}}}
As you see toLua++ parses only the party in the file where there is a ''tolua_export'' commentary and between ''tolua_begin'' and ''tolua_end'' commentaries. Like this we can specify exactly which functions should be accessible by Lua. You may want to only have Lua to fiddle with the public functions or you have a special private function just for Lua.

It is however important that you export namespaces and classes and not just the functions. Otherwise toLua++ would generate .h and .cc files which are not in the namespace so they cannot call the specified functions.

A function call in Lua looks by the way like this:
{{{
local scr = orxonox.Script:getInstance()
scr:luaPrint("Hello World")
}}}
''orxonox'' is the namespace, ''Script'' is the class and ''getInstance()'' and ''luaPrint()'' are the functions. ''scr'' is an instance of the Script-class.

=== Update the CMakeLists.txt file ===
Depending which class you want to make available for tolua++ you have to edit different ''CMakeList.txt'' files: Is your class part of a library we link with Orxonox, you should find the ORXONOX_ADD_LIBRARY command in one of the top ''CMakeList.txt'' files. Is the class part of the main application (inside src/orxonox/*), you need to find the ORXONOX_ADD_EXECUTABLE command in ''src/orxonox/CMakeList.txt''.

Regardless which command or ''CMakeList.txt'' file you use, you have to add the relative path of your class to the list after the TOLUA_FILES flag inside the cMake command. Example:
{{{
ORXONOX_ADD_EXECUTABLE(orxonox
  FIND_HEADER_FILES
  TOLUA_FILES
    gui/GUIManager.h
    objects/pickup/PickupInventory.h
    objects/quest/QuestDescription.h
                                     <<<----- put your new class here
...
  LINK_LIBRARIES
    ${OGRE_LIBRARY}
...
    util
    core
    network
  SOURCE_FILES ${ORXONOX_SRC_FILES}
)
}}}