Lua Script Engine

Behavior through Modules

To attain a desired behavior on a specific GameObj we use Modules.

The scripting engine is built in such a way that every single Module instance operates in its own Lua environment. This means Modules cannot call functions or access variables directly on other Modules. To allow communication between all instances of Modules we use SendMessage.

Using any of the hundreds of functions provided through the Lua interface, Modules can manipulate the world around them.

All Lua is Created Equal

With the exception of globals.lua, every .lua file provided can be a Module. To maximize code-reuse it is helpful to include common functionality in different Modules, so just because each file can be a Modules doesn't mean it should be a Module or necessarily is a Module. To become a Module the script must be attached to a GameObj, please read more on Modules if this doesn't make sense.

This is a general breakdown of the types of scripts used in a large project to help keep things organized and coherent.

• Globals: These files live inside the 'globals' folder and are loaded into every single object's environment automatically. To add new globals, they must be added to the 'globals.lua' file using the 'require' keyword. Many global files actually add additional functions to the GameObj class. (See GameObj Meta Functions)
• Modules: The top level Lua script that is actually attached to the object. These are attached by a) included in the creation template, b) using the 'AddModule' function from another Module, or c) attached by a god character in game using the '/attach' command.
• Base Scripts: These files have a prefix of 'base_' and extend the functionality of a behavior. They are added to the behavior by using the 'require' keyword. Base scripts are more powerful than Includes because they can register for events and refer to the 'this' variable safely.
• Includes: These files have a prefix of 'incl_' and provide helper functions for interacting with objects. They are also added to a behavior with the 'require' keyword. Includes should never contain event handlers and the helper functions often take an object parameter so you can use them with other objects.
• Data Scripts: These files have a prefix of 'data_' and contain a single Lua table that is modifiable by the Data Table Editor. These files can also have a matching '.xml' file in the scripts folder that defines the UI layout for the data. They are also added to a behavior through the use of the 'require' keyword.