Manual

Script or not to script

One of the components of nrEngine is a scripting interfaces. It provides the developer with a simple interface for including different script languages into the application. The script system does work as a wrapper for different scripting languages. Third party plugins, like LuaPlugin provides the connective glue code to include the support of a scripting language.

A plugin does register itself by the engine and specify which kind of scripts it can handle. It can also register functions and methods with the engine, so that a call of any registered function will lead to call of the implementation of that function. Moreover due to the glue functionality of the engine's scripting system a globaly registered function can be accessed in different scripting languages by its proper name. For this a plugin, providing new scripting language, has to connect functions from the engine's script function database with the language interface it provides.

To register any new global function in the engine one can use following code sample:

#include <nrEngine/nrEngine.h>

using namespace nrEngine;


class SomeClass
{
        // here we initialize our class
        void init();

        // We want to register this method in the engine
        ScriptFunctionDef(someScriptFunction);
};


// Implementation of the registered function
ScriptFunctionDec(SomeClass, someScriptFunction)
{
        // The function macro does provide us with a user defined parameters
        SomeClass* class = ScriptEngine::parameter_cast<SomeClass* >(param[0]);

        // return if a wrong number of arguments were passed
        if (args.size() <= 1)
        {
                return ScriptResult(std::string("someClass_scriptFunc(arg1) : wrong parameter count"));
        }

        // do your stuff
        ....
       

        // return empty result
        return ScriptResult();
}


// Register new methods in the engine
void SomeClass::init()
{
    // specify user defined parameters, in our case this is the pointer to our class
    std::vector<ScriptParam> param;
    param.push_back(this);

    // register new functions
    Engine::sScriptEngine()->add("someClass_scriptFunc", someScriptFunction, param);
}


// Release all registered functions
SomeClass::~SomeClass()
{
    Engine::sScriptEngine()->del("someClass_scriptFunc");
}

When a new method is registered the engine will send an ScriptRegisterFunctionEvent? on which the connected script wrappers should react to add this new function into their environment. After this a simple call of (example showed in lua):

function run ()
    result = someClass_scriptFunc(5)
end

will be linked with the real implementation of the script function. Of course you have to know how to react on the provided arguments. The 'result' variable will contain either a result or an error message.

Since all the communication is done by strings a wrapper plugin has to know how to interpret the strings into the appropriate message or value. The scripting glue code has also to know how to translate the results given back to the script environment back. LuaPlugin is a simple glue plugin giving you access to the  lua language within the engine.

See also: ManualPage, ResourceManagement?, LuaPlugin, EventSystem?