Callbacks
Any function from system, world or editor scripts can be called in a C++ code. UnigineScript functions that are called from an external code are known as callbacks. Via callbacks scripts can communicate with each other, as well as with the external application.
- Callbacks support up to 4 arguments and can return a value of an arbitrary type.
See also
An example can be found in <UnigineSDK>/source/samples/Api/Scripts/Callbacks/ directory.
Callbacks Usage Example
C++ Side
To demonstrate how callbacks can be used, let's code the C++ part first:
#include <UnigineEngine.h>
#include <UnigineInterpreter.h>
using namespace Unigine;
/******************************************************************************\
*
* World function
*
\******************************************************************************/
/*
*/
const Variable &runWorldFunction(const Variable &name,const Variable &v) {
Log::warning("runWorldFunction(%s,%s) is called\n",name.getTypeName().get(),v.getTypeName().get());
Engine *engine = Engine::get();
return engine->runWorldFunction(name,v);
}
/******************************************************************************\
*
* Main
*
\******************************************************************************/
/*
*/
int main(int argc,char **argv) {
// export the runWorldFunction() function defined above
Interpreter::addExternFunction("runWorldFunction",MakeExternFunction(&runWorldFunction));
// initialize the engine
Engine *engine = Engine::init(UNIGINE_VERSION,argc,argv);
// start the main loop
while(engine->isDone() == 0) {
engine->update();
engine->render();
engine->swap();
// call the counter() function of the script (defined below)
Variable ret = engine->runWorldFunction(Variable("counter"));
// print a message depending on the value returned by the counter() script function:
// print the current value of the counter
if(ret.getInt() != -1) Log::message("counter is: %d\n",ret.getInt());
// print the world name
if(ret.getInt() == 3) Log::message("\nworld name is: \"%s\"\n",engine->runWorldFunction(Variable("engine.world.getName")).getString());
}
// shut down the engine and call the shutdown() function in the loaded world script
Engine::shutdown();
return 0;
}
Unigine Script Side
And now the UnigineScript side where callbacks are defined:
// my_world.cpp
/*
*/
int callback(int value) {
log.warning("callback(%s) is called\n",typeinfo(value));
return value;
}
/*
*/
void counter() {
for(int i = 0; i < 4; i++) {
log.warning("counter(): called\n");
yield i;
}
return -1;
}
/*
*/
int init() {
log.message("\n");
// run the callback() script function via the API runWorldFunction() function
log.message("result is: %s\n\n",typeinfo(runWorldFunction("callback",10)));
log.message("result is: %s\n\n",typeinfo(runWorldFunction("callback",vec3(1,2,3))));
log.message("result is: %s\n\n",typeinfo(runWorldFunction("callback","a string")));
/////////////////////////////////
// show a console
engine.console.setActivity(1);
return 1;
}
Calling Sequence
The sequence of function call will be as follows:
- The interpreter exports the runWorldFunction() function to make it available from the script.
- The engine is initialized, and the init() function of the script is called. This function calls the exported runWorldFunction() function.
- The exported runWorldFunction() function calls the callback() function from the script.
- The engine enters the main loop, where it calls the counter() function from the script by using the Unigine::Engine::runWorldFunction() function.
Output
The following result will be printed into the console:
runWorldFunction(string,int): called
callback(int: 10): called
result is: int: 10
runWorldFunction(string,vec3): called
callback(vec3: 1 2 3): called
result is: vec3: 1 2 3
runWorldFunction(string,string): called
callback(string: "a string") is called
result is: string: "a string"
counter(): called
counter is: 0
counter(): called
counter is: 1
counter(): called
counter is: 2
counter(): called
counter is: 3
world name is: "data/callbacks"
Last update: 2017-07-03
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)