AngelScript
Calling a script function

Preparing context and executing the function

Normally a script function is executed in a few steps:

  1. Prepare the context
  2. Set the function arguments
  3. Execute the function
  4. Retrieve the return value

The code for this might look something like this:

// Get a script context instance. Usually you'll want to reuse a previously
// created instance to avoid the overhead of allocating the instance with
// each call.
// Obtain the function from the module. This should preferrably
// be cached if the same function is called multiple times.
asIScriptFunction *func = engine->GetModule(module_name)->GetFunctionByDecl(function_declaration);
// Prepare() must be called to allow the context to prepare the stack
ctx->Prepare(func);
// Set the function arguments
ctx->SetArgDWord(...);
int r = ctx->Execute();
{
// The return value is only valid if the execution finished successfully
asDWORD ret = ctx->GetReturnDWord();
}
// Release the context when you're done with it
ctx->Release();

If your application allows the execution to be suspended, either by using the callback function or registering a function that allow the script to manually suspend the execution, then the execution function may return before finishing with the return code asEXECUTION_SUSPENDED. In that case you can later resume the execution by simply calling the execution function again.

Note that the return value retrieved with GetReturnValue() is only valid if the script function returned successfully, i.e. if Execute() returned asEXECUTION_FINISHED.

Passing and returning primitives

When calling script functions that take arguments, the values of these arguments must be set after the call to Prepare() and before Execute(). The arguments are set using a group of SetArg methods:

int SetArgDWord(int arg, asDWORD value);
int SetArgQWord(int arg, asQWORD value);
int SetArgFloat(int arg, float value);
int SetArgDouble(int arg, double value);
int SetArgByte(int arg, asBYTE value);
int SetArgWord(int arg, asWORD value);

arg is the argument number, where the first argument is on 0, the second on 1, and so on. value is the value of the argument. What method to use is determined by the type of the parameter. For primitive types you can use any of these. If the parameter type is a reference to a primitive type it is recommended to use the SetArgAddress() method and pass the pointer as the value. For non-primitive types the method SetArgObject() should be used, which will be described in the next section.

// The context has been prepared for a script
// function with the following signature:
// int function(int, double, bool, int &out)
// Put the arguments on the context stack, starting with the first one
ctx->SetArgDWord(0, 1);
ctx->SetArgDouble(1, 3.141592);
ctx->SetArgByte(2, true);
int val;
ctx->SetArgAddress(3, &val);

Once the script function has been executed the return value is retrieved in a similar way using the group of GetReturn methods:

asDWORD GetReturnDWord();
asQWORD GetReturnQWord();
float GetReturnFloat();
double GetReturnDouble();
asBYTE GetReturnByte();
asWORD GetReturnWord();

Note that you must make sure the returned value is in fact valid, for example if the script function was interrupted by a script exception the value would not be valid. You do this by verifying the return code from Execute() or GetState(), where the return code should be asEXECUTION_FINISHED.

Passing and returning objects

Passing registered object types to a script function is done in a similar way to how primitive types are passed. The function to use is SetArgObject():

int SetArgObject(int arg, void *object);

arg is the argument number, just like the other SetArg methods. object is a pointer to the object you wish to pass.

This same method is used both for parameters passed by value and for those passed by reference. The library will automatically make a copy of the object if the parameter is defined to be passed by value.

// The complex object we wish to pass to the script function
CObject obj;
// Pass the object to the function
ctx->SetArgObject(0, &obj);

Getting an object returned by a script function is done in a similar way, using GetReturnObject():

void *GetReturnObject();

This method will return a pointer to the object returned by the script function. The library will still hold a reference to the object, which will only be freed as the context is released.

// The object where we want to store the return value
CObject obj;
// Execute the function
int r = ctx->Execute();
{
// Get a pointer to the returned object and copy it to our object
obj = *(CObject*)ctx->GetReturnObject();
}

It is important to make a copy of the returned object, or if it is managed by reference counting add a reference to it. If this is not done the pointer obtained with GetReturnObject() will be invalidated as the context is released, or reused for another script function call.

Exception handling

If the script performs an illegal action, e.g. calling a method on a null handle, then the script engine will throw a script exception. The virtual machine will then abort the execution and the Execute method will return with the value asEXECUTION_EXCEPTION.

At this time it is possible to obtain information about the exception through the asIScriptContext's methods. Example:

void PrintExceptionInfo(asIScriptContext *ctx)
{
asIScriptEngine *engine = ctx->GetEngine();
// Determine the exception that occurred
printf("desc: %s\n", ctx->GetExceptionString());
// Determine the function where the exception occurred
const asIScriptFunction *function = ctx->GetExceptionFunction();
printf("func: %s\n", function->GetDeclaration());
printf("modl: %s\n", function->GetModuleName());
printf("sect: %s\n", function->GetScriptSectionName());
// Determine the line number where the exception occurred
printf("line: %d\n", ctx->GetExceptionLineNumber());
}

If desired, it is also possible to register a callback function that will be called at the moment the exception occurred, before the Execute method returns. The exception callback can then use WillExceptionBeCaught to determine if the exception will be caught within the script or if it will abort the execution.

See also
Debugging scripts for information on examining the callstack, and GetExceptionInfo for a helper function to get information on exceptions.
asIScriptContext::SetArgAddress
virtual int SetArgAddress(asUINT arg, void *addr)=0
Sets the address of a reference or handle argument.
asIScriptContext
The interface to the virtual machine.
Definition: angelscript.h:2717
asIScriptContext::GetExceptionLineNumber
virtual int GetExceptionLineNumber(int *column=0, const char **sectionName=0)=0
Returns the line number where the exception occurred.
asDWORD
unsigned long asDWORD
32 bit unsigned integer
Definition: angelscript.h:614
asIScriptModule::GetFunctionByDecl
virtual asIScriptFunction * GetFunctionByDecl(const char *decl) const =0
Returns the function by its declaration.
asIScriptEngine::GetModule
virtual asIScriptModule * GetModule(const char *module, asEGMFlags flag=asGM_ONLY_IF_EXISTS)=0
Return an interface pointer to the module.
asIScriptContext::Execute
virtual int Execute()=0
Executes the prepared function.
asIScriptContext::SetArgDouble
virtual int SetArgDouble(asUINT arg, double value)=0
Sets a double argument value.
asIScriptContext::GetReturnObject
virtual void * GetReturnObject()=0
Return a pointer to the returned object.
asBYTE
unsigned char asBYTE
8 bit unsigned integer
Definition: angelscript.h:598
asIScriptEngine
The engine interface.
Definition: angelscript.h:1092
asIScriptContext::GetExceptionString
virtual const char * GetExceptionString()=0
Returns the exception string text.
asIScriptContext::GetEngine
virtual asIScriptEngine * GetEngine() const =0
Returns a pointer to the engine.
asEXECUTION_FINISHED
@ asEXECUTION_FINISHED
The context has successfully completed the execution.
Definition: angelscript.h:398
asQWORD
unsigned __int64 asQWORD
64 bit unsigned integer
Definition: angelscript.h:619
asIScriptContext::SetArgObject
virtual int SetArgObject(asUINT arg, void *obj)=0
Sets the object argument value.
asIScriptEngine::CreateContext
virtual asIScriptContext * CreateContext()=0
Creates a new script context.
asIScriptContext::SetArgByte
virtual int SetArgByte(asUINT arg, asBYTE value)=0
Sets an 8-bit argument value.
asIScriptFunction
The interface for a script function description.
Definition: angelscript.h:3823
asIScriptContext::GetExceptionFunction
virtual asIScriptFunction * GetExceptionFunction()=0
Returns the function where the exception occurred.
asIScriptContext::SetArgDWord
virtual int SetArgDWord(asUINT arg, asDWORD value)=0
Sets a 32-bit integer argument value.
asIScriptContext::Prepare
virtual int Prepare(asIScriptFunction *func)=0
Prepares the context for execution of the function.
asIScriptContext::GetReturnDWord
virtual asDWORD GetReturnDWord()=0
Returns the 32-bit return value.
asWORD
unsigned short asWORD
16 bit unsigned integer
Definition: angelscript.h:599
asIScriptContext::Release
virtual int Release() const =0
Decrease reference counter.