| AngelScript |

Using script classes

When there are multiple objects controlled by the same script implementation it may be favourable to use script classes, rather than global script functions. Using script classes each instance can have it's own set of variables within the class, contrary to the global functions that needs to rely on global variables to store persistent information.

Of course, it would be possible to duplicate the script modules, so that there is one module for each object instance, but that would be impose a rather big overhead for the application. Script classes don't have that overhead, as all instances share the same module, and thus the same bytecode and function ids, etc.

# Instantiating the script class

Before instantiating the script class you need to know which class to instantiate. Exactly how this is done depends on the application, but here are some suggestions.

If the application knows the name of the class, either hardcoded or from some configuration, the class type can easily be obtained by calling the module's GetTypeIdByDecl with the name of the class. The application can also choose to identify the class through some properties of the class, e.g. if the class implements a predefined interface. Then the application can enumerate the class types implemented in the script with GetObjectTypeByIndex and then examine the type through the asITypeInfo interface.

A third option, if you're using the script builder add-on, is to use the metadata to identify the class. If you choose this option, use the asIScriptModule to enumerate the declared types and then query the CScriptBuilder for their metadata.

Once the object type is known you create the instance by calling the class' factory function, passing it the necessary arguments, e.g. a pointer to the application object which the script class should be bound to. The factory function id is found by querying the asITypeInfo.

// Get the object type
asIScriptModule *module = engine->GetModule("MyModule");
asITypeInfo *type = module->GetTypeInfoByDecl("MyClass");
// Get the factory function from the object type
asIScriptFunction *factory = type->GetFactoryByDecl("MyClass @MyClass()");
// Prepare the context to call the factory function
ctx->Prepare(factory);
// Execute the call
ctx->Execute();
// Get the object that was created
asIScriptObject *obj = *(asIScriptObject**)ctx->GetAddressOfReturnValue();
// If you're going to store the object you must increase the reference,
// otherwise it will be destroyed when the context is reused or destroyed.
obj->AddRef();

The factory function is called as a regular global function and returns a handle to the newly instanciated class.

# Calling a method on the script class

Calling the methods of the script classes are similar to calling global functions except that you obtain the function id from the asITypeInfo, and you must set the object pointer along with the rest of the function arguments.

// Obtain the function object that represents the class method
asIScriptFunction *func = type->GetMethodByDecl("void method()");
// Prepare the context for calling the method
ctx->Prepare(func);
// Set the object pointer
ctx->SetObject(obj);
// Execute the call
ctx->Execute();

# Receiving script classes

In order for the application to register a function that receives a script class it must first know the type. Of course, since the class is declared in the script it isn't possible to know the type before the script is compiled. Instead the application can register an interface with the engine. The function can then be registered to receive a handle to that interface.

// Register an interface
engine->RegisterInterface("IMyObj");
// You can also register methods with the interface if you wish to force the script class to implement them
engine->RegisterInterfaceMethod("IMyObj", "void RequiredMethod()");
// Register a function that receives a handle to the interface
engine->RegisterGlobalFunction("void ReceiveMyObj(IMyObj @obj)", asFUNCTION(ReceiveMyObj), asCALL_CDECL);

The function that receives the interface should be implemented to take a pointer to an asIScriptObject.

asIScriptObject *gObj = 0;
void ReceiveMyObj(asIScriptObject *obj)
{
// Do something with the object
if( obj )
{
if( doStore )
{
// If the object is stored, we shouldn't release the handle
gObj = obj;
}
else
{
// If the object is not stored, we must release the handle before returning
obj->Release();
}
}
}

If you don't want to use interfaces like this, then you may want to look into the variable argument type or the generic script handle add-on, which are ways that can be used to receive values and objects of which the type is not known beforehand.

# Returning script classes

Returning a script class from a registered function involves much of the same as receiving them. In order to register the function either an interface needs to be used, or the generic script handle add-on can be used.

// The global variable is initialized elsewhere
asIScriptObject *gObj;
asIScriptObject *ReturnMyObj()
{
if( gObj == 0 )
return 0;
// Increase the refcount to account for the returned handle
gObj->AddRef();
return gObj;
}

This function can be registered as following:

// Register an interface
engine->RegisterInterface("IMyObj");
// Register a function that returns a handle to the interface
engine->RegisterGlobalFunction("IMyObj @ReturnMyObj()", asFUNCTION(ReturnMyObj), asCALL_CDECL);
asIScriptEngine::RegisterInterface
virtual int RegisterInterface(const char *name)=0
Registers a script interface.
asIScriptEngine::GetModule
virtual asIScriptModule * GetModule(const char *module, asEGMFlags flag=asGM_ONLY_IF_EXISTS)=0
Return an interface pointer to the module.
asIScriptContext::GetAddressOfReturnValue
virtual void * GetAddressOfReturnValue()=0
Returns the address of the returned value.
asIScriptContext::Execute
virtual int Execute()=0
Executes the prepared function.
asIScriptEngine::RegisterInterfaceMethod
virtual int RegisterInterfaceMethod(const char *intf, const char *declaration)=0
Registers a script interface method.
asITypeInfo::GetMethodByDecl
virtual asIScriptFunction * GetMethodByDecl(const char *decl, bool getVirtual=true) const =0
Returns the method by declaration.
asIScriptContext::SetObject
virtual int SetObject(void *obj)=0
Sets the object for a class method call.
asIScriptEngine::RegisterGlobalFunction
virtual int RegisterGlobalFunction(const char *declaration, const asSFuncPtr &funcPointer, asDWORD callConv, void *auxiliary=0)=0
Registers a global function.
asIScriptObject::AddRef
virtual int AddRef() const =0
Increase reference counter.
asFUNCTION
#define asFUNCTION(f)
Returns an asSFuncPtr representing the function specified by the name.
Definition: angelscript.h:675
asITypeInfo::GetFactoryByDecl
virtual asIScriptFunction * GetFactoryByDecl(const char *decl) const =0
Returns the factory function by the declaration.
asITypeInfo
The interface for describing types This interface is used to describe the types in the script engine.
Definition: angelscript.h:3527
asIScriptFunction
The interface for a script function description.
Definition: angelscript.h:3823
asIScriptModule
The interface to the script modules.
Definition: angelscript.h:2218
asIScriptObject
The interface for an instance of a script object.
Definition: angelscript.h:3413
asCALL_CDECL
@ asCALL_CDECL
A cdecl function.
Definition: angelscript.h:226
asIScriptContext::Prepare
virtual int Prepare(asIScriptFunction *func)=0
Prepares the context for execution of the function.
asIScriptObject::Release
virtual int Release() const =0
Decrease reference counter.
asIScriptModule::GetTypeInfoByDecl
virtual asITypeInfo * GetTypeInfoByDecl(const char *decl) const =0
Returns a type by declaration.