Friday, March 15, 2013

I Love Lua

Warning: Those technical posts I promised two years ago are finally happening! :-)

Has it been five months already!?

It is time to announce that my project has an official name - Mana. The word originated in the Pacific islands and refers to an "impersonal force" that resides in all things. Gamers, especially RPG gamers, should recognize it instantly. It is often used in games to quantify magic or life force in the form of points.

It is also time to express my love for the Lua scripting language. My first stab at getting Mana and Lua working together was actually quite some time ago. It went so well that I ended up abandoning my own scripting language and embracing Lua for its popularity, speed, and ease of use. The integration is about ninety percent - almost anything can be done externally in script!

Using Lua, there are essentially three ways to create objects. There is a low-level interface, common to all objects and designed to provide consistency for all classes. On top of that, there is the MANA stack, which uses the same low-level methodology, but keeps track of a few things to make the process simpler. Then, there are the more convenient “mk” functions that are single line object initialization functions.

Most of the time, the “mk” functions will probably be the most commonly used.

tex = mkTexture( "MyTexture", 256, 256 )
--Returns 256 x 256 blank texture.

v3 = mkVec3( 0, 1, 0 )
--Returns an ‘up’ vector.

win = mkWindow( "MyWindow", 50, 50, 300, 200 )
--Returns a window widget.

They initialize objects based on whatever the currently active template calls for. But more on those later. For now, I’ll write a bit about the MANA stack. This is a low-level interface that provides a typical “start new object, modify object attributes, then finish object” methodology.

There are three standard functions for creating an object - ANY object. This applies to widgets, models, textures, materials, and their components - EVERY object that is in Mana. Those three functions are Init, Clone, and ReadXml (ReadBin may be added later).

    Init - creates a new superclass object from scratch.
    Clone - creates one from an existing object.
    ReadXml - reads the data for an object from an xml file and the return value may be a new object or a clone, depending on the file.

Each of the creation functions takes four parameters of a similar nature.

    Init( superclass, class, index, parent )

Superclass and class are strings describing the new object. Superclass refers to all of the base type objects available in Mana (Widget, for example). Class is used to define a new class or, for objects that can’t be reclassified, a name.

    Clone( path, name, index, parent )

Path is the string path to the object to be cloned, and name is the new object name.

    ReadXml( filename, path, index, parent )

Filename is, of course, the file to be read, and path is the path to the node that contains the data.

All three functions use index and parent. Parent is the string path to the object that the new object will be associated. Index is used when a new object is being created to replace another. However, the default is -1, meaning “append new object to the end.”

The following code does the same thing as the mkTexture and mkWindow statements above, only much more verbose!

    MANA.Init( "Texture", "MyTexture", -1, "++Textures" )
    MANA.THIS:SetSize( 256, 256 )
    MANA.Clone( "//Prototypes/Widget/Window", "MyWindow", -1, "//MyGui" )
    MANA.THIS:SetPosition( 50, 50 )
    MANA.THIS:SetSize( 300, 200 )

But why would anyone want to write all that code to do something so basic?

Why, indeed!! It is really just a common way of creating all objects of all types. Start creating an object with its default values, then change the parameters, then finish with an object that is available to be cloned and used for all sorts of things. If I had omitted the SetSize line from the texture code, for example, it would still return a 256 x 256 because those happen to be the default values.

But wait! What does that parent value mean, exactly?

All objects in Mana are linked together in a hierarchical structure in a way that resembles files and folders on your hard drive. In my next post, I’ll cover that in more detail.

No comments:

Post a Comment