class asIScriptEngine { public: // Memory management int AddRef(); int Release(); // Engine configuration int SetEngineProperty(asDWORD property, asPWORD value); asPWORD GetEngineProperty(asDWORD property); int SetMessageCallback(const asUPtr &callback, void *obj, asDWORD callConv); int ClearMessageCallback(); int RegisterObjectType(const char *name, int byteSize, asDWORD flags); int RegisterObjectProperty(const char *obj, const char *declaration, int byteOffset); int RegisterObjectMethod(const char *obj, const char *declaration, const asUPtr &funcPointer, asDWORD callConv); int RegisterObjectBehaviour(const char *datatype, asDWORD behaviour, const char *declaration, const asUPtr &funcPointer, asDWORD callConv); int RegisterGlobalProperty(const char *declaration, void *pointer); int RegisterGlobalFunction(const char *declaration, const asUPtr &funcPointer, asDWORD callConv); int RegisterGlobalBehaviour(asDWORD behaviour, const char *declaration, const asUPtr &funcPointer, asDWORD callConv); int RegisterInterface(const char *name); int RegisterInterfaceMethod(const char *intf, const char *declaration); int RegisterStringFactory(const char *datatype, const asUPtr &factoryFunc, asDWORD callConv); int BeginConfigGroup(const char *groupName); int EndConfigGroup(); int RemoveConfigGroup(const char *groupName); int SetConfigGroupModuleAccess(const char *groupName, const char *module, bool hasAccess); // Script modules int AddScriptSection(const char *module, const char *name, const char *code, size_t codeLength, int lineOffset = 0, bool makeCopy = true); int Build(const char *module); int Discard(const char *module); int ResetModule(const char *module); // Script functions int GetFunctionCount(const char *module); int GetFunctionIDByIndex(const char *module, int index); int GetFunctionIDByName(const char *module, const char *name); int GetFunctionIDByDecl(const char *module, const char *decl); const char *GetFunctionDeclaration(int funcID, int *length = 0); const char *GetFunctionName(int funcID, int *length = 0); const char *GetFunctionModule(int funcID, int *length = 0); const char *GetFunctionSection(int funcID, int *length = 0); int GetMethodCount(int typeId); int GetMethodIDByIndex(int typeId, int index); int GetMethodIDByName(int typeId, const char *name); int GetMethodIDByDecl(int typeId, const char *decl); // Script global variables int GetGlobalVarCount(const char *module); int GetGlobalVarIDByIndex(const char *module, int index); int GetGlobalVarIDByName(const char *module, const char *name); int GetGlobalVarIDByDecl(const char *module, const char *decl); const char *GetGlobalVarDeclaration(int gvarID, int *length = 0); const char *GetGlobalVarName(int gvarID, int *length = 0); void *GetGlobalVarPointer(int gvarID); // Dynamic binding between modules int GetImportedFunctionCount(const char *module); int GetImportedFunctionIndexByDecl(const char *module, const char *decl); const char *GetImportedFunctionDeclaration(const char *module, int importIndex, int *length = 0); const char *GetImportedFunctionSourceModule(const char *module, int importIndex, int *length = 0); int BindImportedFunction(const char *module, int importIndex, int funcID); int UnbindImportedFunction(const char *module, int importIndex); int BindAllImportedFunctions(const char *module); int UnbindAllImportedFunctions(const char *module); // Type identification int GetTypeIdByDecl(const char *module, const char *decl); const char *GetTypeDeclaration(int typeId, int *length = 0); // Script execution int SetDefaultContextStackSize(asUINT initial, asUINT maximum); asIScriptContext *CreateContext(); void *CreateScriptObject(int typeId); void *CreateScriptObjectCopy(void *obj, int typeId); void CopyScriptObject(void *dstObj, void *srcObj, int typeId); void ReleaseScriptObject(void *obj, int typeId); void AddRefScriptObject(void *obj, int typeId); bool IsHandleCompatibleWithObject(void *obj, int objTypeId, int handleTypeId); // String interpretation int ExecuteString(const char *module, const char *script, asIScriptContext **ctx = 0, asDWORD flags = 0); // Garbage collection int GarbageCollect(bool doFullCycle = true); int GetObjectsInGarbageCollectorCount(); // Bytecode saving/loading int SaveByteCode(const char *module, asIBinaryStream *out); int LoadByteCode(const char *module, asIBinaryStream *in); };
int AddRef();
This method increases the internal reference counter of the object and returns the count. The returned value shouldn't be used for anything else but debugging.
Call AddRef() each time you assign a reference to a new variable.
The internal reference counter.
int Release();
Decreases the internal reference counter and returns the count. If the counter reaches 0 the object is deleted and the memory is freed.
After calling Release() don't forget to set your reference to 0 so that you don't mistakenly try to use the reference again.
It is an error to release the engine, while there are still contexts running. Doing this may result in memory leaks as the contexts may not be able to release the object references successfully.
The internal reference counter.
int SetEngineProperty(asDWORD property, asPWORD value);
This method allows you to change the behaviour of the script engine. Calls to this method should be made right after the engine is created. Any calls made at a later time may have unexpected behaviours.
The properties:
asEP_ALLOW_UNSAFE_REFERENCES |
Default: false. By setting this property to a non-zero value, the script compiler will permit the use of unsafe references. It will no longer be necessary to use the keywords in, out, or inout, and the references passed to functions will be the true reference. It will be the responsibility of the script writer to write code that does not invalidate the reference before it is used. |
asEP_OPTIMIZE_BYTECODE |
Default: true. By setting this to a zero value, the byte code will not be optimized to remove redundant instructions, which may result in slower execution times, but also slightly faster compile times. Note: This is mostly only used when developing the library itself, there is probably no benefit to application developers in turning off byte code optimization. |
asEP_COPY_SCRIPT_SECTIONS |
Default: true. When true, a copy will be made of the script sections added, so that the application doesn't need to keep the memory buffer until the Build() call is made. |
property |
One of the value properties. |
values |
The new value of the property. |
A negative value on an error.
asPWORD GetEngineProperty(asDWORD property);
This method returns the value of the engine property.
property |
One of the value properties. |
The value of the property if valid, 0 otherwise.
int SetMessageCallback(const asUPtr &callback, void *obj, asDWORD callConv);
This method is used to set a callback function that will receive all the messages from the script engine, such as configuration errors, and compiler messages.
The callback function can be either a global function or a class method. Example:
// Global function void MessageCallback(const asSMessageInfo *msg, void *param); // Registering the global function as callback void *param; engine->SetMessageCallback(asFUNCTION(MessageCallback), param, asCALL_CDECL);
// Class method void MyClass::MessageCallback(const asSMessageInfo *msg); // Registering the class method as callback MyClass obj; engine->SetMessageCallback(asMETHOD(MyClass,MessageCallback), obj, asCALL_THISCALL);
Since the pointer to this callback function will be held by the engine until the the next call to the method or the engine is released it is important that the application makes sure that it isn't destroyed before its time.
The first parameter sent to the callback is a structure with the following layout:
struct asSMessageInfo { const char *section; int row; int col; int type; const char *message; };
The string buffers pointed to by the structure are temporary and shouldn't be stored for later use. The type of the message is one of asMSGTYPE_ERROR, asMSGTYPE_WARNING, or asMSGTYPE_INFORMATION.
callback |
A pointer to the callback function/method. |
obj |
A pointer to an object sent as the second parameter for global functions, or used as the object for class methods. |
callConv |
The calling convention for the callback function. |
A negative value on an error.
int ClearMessageCallback();
This method is used to clear the message callback.
A negative value on an error.
int RegisterObjectType(const char *name, int byteSize, asDWORD flags);
Call this method to register a new data type that the scripts may use.
Script variables and parameters using this type have their values protected in that the user may not assign values of other types by mistake, and may not manipulate the values directly by operators.
If you specify a byteSize larger than 0, this means that structure can be declared as a local object in the script functions.
Note that if the object dynamically allocates memory then you are adviced to register at least a destruct behaviour function that frees that memory as the variable is no longer used.
The flags should be set according to the true object type, so that AngelScript can handle the type correctly in communications with the host application. See object types for more information.
It is also possible to override the default array object in AngelScript by registering a object specifying the name with [], e.g: int[]. To register functions that receive arrays in the parameters the array must first have been registered like this.
name |
The name of the data type as it should be used in the scripts. |
byteSize |
The size of the object in bytes. |
flags |
Should be one of the object types. |
A negative value on error, 0 or greater if successful.
int RegisterObjectProperty(const char *obj, const char *declaration, int byteOffset);
This method allows the host application to register properties for objects that
are accessable by the scripts. The properties may optionally be marked as read-only
to improve security, this is done by declaring them as const
.
Computing the byte offset is not just counting the size of the members, the compiler may insert hidden members, such as virtual table pointers, and at times inserts padding between members so that they will be align to a certain byte boundary.
The easiest way to compute the byte offset is to let the compiler do it for you.
There is a standard macro called offsetof
that does just this for you.
That macro is defined in stddef.h.
Data members inherited from virtual base class are not supported by this method as the location of these members must be verified at run time through lookup in a virtual table.
obj |
The name of the object type. |
declaration |
The property declaration, with data type and name. |
byteOffset |
The offset from the object pointer where the property is found. |
A negative value on error, 0 or greater if successful.
int RegisterObjectMethod(const char *obj, const char *declaration, const asUPtr &funcPointer, asDWORD callConv);
This method registers object methods that the scripts may use. The function pointer must be a pointer to a class method.
If a parameter is declared as reference you must also specify the direction in which the value travels, i.e. in, out, or inout. If the reference is marked as only out, the argument will be a default value, e.g. objects will be initialized with their default constructors. Note that the reference will not be to the true object, so do not store the pointer thinking it will be valid at a later time.
If the method receives object handles by value, the method must release those handles before returning. Likewise if the method returns an object handle it must increase the reference count for it.
Some methods shouldn't be allowed to be called on constant objects,
for example methods that alter a property of the object. Other methods
are allowed to be called on constant objects because they don't alter them.
You tell the script engine which methods can and cannot be called on constant
objects by adding the keyword const
after the parameter list in
the declaration.
If two methods with the same parameters but one with const
and one without is registered, then the compiler will use the one with
code
for constant objects, and the other one for normal objects.
This is called const-overloading.
Example:
engine->RegisterObjectMethod("obj", "int &func(int)", asFUNCTION(func), asCALL_CDECL); engine->RegisterObjectMethod("obj", "const int &func(int) const", asFUNCTION(func), asCALL_CDECL);
obj |
The name of the object. |
declaration |
Should be the functions declaration written in the AngelScript language. |
funcPointer |
Pointer to the function that the engine will call. Use the macro asMETHOD() if you are registering a class method or asFUNCTION() if it is a global function. |
callConv |
Must be either asCALL_THISCALL, asCALL_CDECL_OBJLAST, asCALL_CDECL_OBJFIRST, or asCALL_GENERIC. |
A negative value on error, 0 or greater if successful.
int RegisterObjectBehaviour(const char *datatype, asDWORD behaviour, const char *declaration, const asUPtr &funcPointer, asDWORD callConv);
By registering behaviour functions for a data type AngelScript is able to improve object handling. You can for example easily control how references are counted, or create objects that can be manipulated in expressions through operators.
The construct function is called when a variable enters the scope, usually at the start of a function. The destruct function is called when the variable exits the scope, usually at the end of the function. The copy function is called for assignments, i.e when a variable is copied to another, or when an object is sent by value to a function.
Behaviours may only be registered for object types registered by the application.
The constructor, destructor, and assignment behaviours must be registered as an object method, i.e. with a data type in the first parameter. The other operators must be registered as global functions, i.e. datatype set to 0.
The host application may not throw exceptions in the destructor behaviour as it may lead to undefined behaviour. These is the same rule as C++ has for destructors. The rule is there because if a destructor calls an exception, the destructor will be called again by the exception handler, which might lead to an endless loop.
Behaviours shouldn't be registered to take handles as their parameters, use references instead. Unlike functions, methods, and constructors, overloaded operators may receive a reference to the true object instead of a dummy object, but it also may not so don't rely on it. Output reference parameters are not supported by behaviours.
If the parameter is sent by reference, then declare it as const, as it may allow the compiler to optimize the code to execute faster.
If an object support object handles, then the constructor should initialize the object with one reference already counted.
If the constructor calls SetException() to indicate failure it must make sure that that the object doesn't hold any resources, because the VM will free the object's memory without calling the Release() method or the destructor.
datatype |
The type declaration. |
behaviour |
The behaviour you wish to register. |
declaration |
The function declaration that specifies the return type and parameter types of the function. The function name in this declaration is ignored. The engine will send the pointer to the type as the first parameter hiddenly so you should not declare it. |
funcPointer |
A pointer to the behaviour function. Use macro asMETHOD() or asFUNCTION() depending on type of function. |
callConv |
The calling convention. |
A negative value on error, 0 or greater if successful.
int RegisterGlobalProperty(const char *declaration, void *pointer);
This method allows the host application to register global properties that are accessable by the scripts. The properties may optionally be declared as const to improve security.
It is not allowed to register a property as reference, as the property is by default considered a reference, i.e. don't use the & type modifier in the type declaration.
declaration |
The property declaration, with data type and name. |
pointer |
A pointer to the variable holding the property's value. |
A negative value on error, 0 or greater if successful.
int RegisterGlobalFunction(const char *declaration, const asUPtr &funcPointer, asDWORD callConv);
This method registers system functions that the scripts may use to communicate with the host application.
If a parameter is declared as reference you must also specify the direction in which the value travels, i.e. in, out, or inout. If the reference is marked as only out, the argument will be a default value, e.g. objects will be initialized with their default constructors. Note that the reference will not be to the true object, so do not store the pointer thinking it will be valid at a later time.
If the function receives object handles by value, the method must release those handles before returning. Likewise if the function returns an object handle it must increase the reference count for it.
declaration |
Should be the functions declaration written in the AngelScript language. |
funcPointer |
Pointer to the function that the engine will call. |
callConv |
Must be either asCALL_CDECL, asCALL_STDCALL, or asCALL_GENERIC. |
A negative value on error, 0 or greater if successful.
int RegisterGlobalBehaviour(asDWORD behaviour, const char *declaration, const asUPtr &funcPointer, asDWORD callConv);
By registering behaviour functions for a data type AngelScript is able to improve object handling. You can for example easily control how references are counted, or create objects that can be manipulated in expressions through operators.
Behaviours may only be registered for object types registered by the application.
Behaviours shouldn't be registered to take handles as their parameters, use references instead. Unlike functions, methods, and constructors, overloaded operators may receive a reference to the true object instead of a dummy object, but it also may not so don't rely on it. Output references are not supported by behaviours.
If the parameter is sent by reference, then declare it as const, as it may allow the compiler to optimize the code to execute faster.
behaviour |
The behaviour you wish to register. |
declaration |
The function declaration that specifies the return type and parameter types of the function. The function name in this declaration is ignored. The engine will send the pointer to the type as the first parameter hiddenly so you should not declare it. |
funcPointer |
A pointer to the behaviour function. Use macro asMETHOD() or asFUNCTION() depending on type of function. |
callConv |
The calling convention. |
A negative value on error, 0 or greater if successful.
int RegisterInterface(const char *name);
This registers an interface that script classes can implement. By doing this the application can register functions and methods that receives an asIScriptStruct and still be sure that the structure implements certain methods needed by the application.
name |
The name of the interface. |
A negative value on error, 0 or greater if successful.
int RegisterInterfaceMethod(const char *intf, const char *declaration);
This registers the method that the interface must implement.
intf |
The name of the interface. |
declaration |
The method declaration. |
A negative value on error, 0 or greater if successful.
int RegisterStringFactory(const char *datatype, const asUPtr &factoryFunc, asDWORD callConv);
Use this function to register a string factory that will be called when the virtual engine finds a string constant in an expression. The string factory function will receive two parameters, the length of the string constant and a pointer to the character data.
datatype |
The type returned by the factory function. |
factoryFunc |
The pointer of the factory function. Use the macro asFUNCTION(). |
callConv |
Must be either asCALL_CDECL, asCALL_STDCALL, or asCALL_GENERIC. |
A negative value on error, 0 or greater if successful.
int BeginConfigGroup(const char *groupName);
Starts a new dynamic configuration group. This group can be setup so that it is only visible to specific modules, and it can also be removed when it is no longer used.
groupName |
The name of the group. |
A negative value on error, 0 or greater if successful.
int EndConfigGroup();
Ends the current configuration group. Once finished a config group cannot be changed, but it can be removed when it is no longer used.
A negative value on error, 0 or greater if successful.
int RemoveConfigGroup(const char *groupName);
Remove the configuration group. If something in the configuration group is currently in use, the function will return with an error code. Examples of uses are compiled modules that have function calls to functions in the group and global variables of types registered in the group.
groupName |
The name of the group. |
A negative value on error, 0 or greater if successful.
int SetConfigGroupModuleAccess(const char *groupName, const char *module, bool hasAccess);
With this method the application can give modules access to individual configuration groups. This is useful when exposing more than one script interface for various parts of the application, e.g. one interface for GUI handling, another for in-game events, etc.
The default module access is granted. The default for a group can be changed by specifying the modulename asALL_MODULES.
groupName |
The name of the group. |
module |
The name of the module, or asALL_MODULES. |
hasAccess |
Access mode. |
A negative value on error, 0 or greater if successful.
int AddScriptSection(const char *module, const char *name, const char *code, size_t codeLength, int lineOffset = 0, bool makeCopy = true);
This adds a script section to the engine. All sections added will be treated as if one large script. Errors reported will give the name of the corresponding section.
The code added is copied by the engine, so there is no need to keep the original buffer after the call.
module |
The name of the module. Can be null. |
name |
The name of the section. |
code |
The script code in the section. |
codeLength |
The length of the code buffer. |
lineOffset |
This will be added to all line numbers reported by the engine. |
makeCopy |
Should the library make a copy of the script code, or use the pointer to the original code. If this argument is false, the application will be responsible for making sure the memory is available and unchanged until the Build() method has been called. |
A negative value on error, 0 or greater if successful.
int Build(const char *module);
Builds the script based on the added sections, and registered types and functions.
If Build() is to be called again new code sections must first be added again. Registered data types and functions are remembered by the engine though.
Any compiler messages are sent to the message stream set with SetCommonMessageStream(). If there are no errors or warnings, no messages will be sent to the stream.
module |
The name of the module. Can be null. |
A negative value on error, 0 or greater if successful.
int Discard(const char *module);
Discards a module and frees its memory.
module |
The name of the module. Can be null. |
A negative value on error, 0 or greater if successful.
int ResetModule(const char *module);
Resets the global variables declared in this module to their initial value.
module |
The name of the module. Can be null. |
A negative value on error, 0 or greater if successful.
int GetFunctionCount(const char *module);
This method retrieves the number of compiled script functions.
module |
The name of the module. Can be null. |
A negative value on error, or the number of script functions if successful.
int GetFunctionIDByIndex(const char *module, int index);
This method should be used to retrieve the ID of the script function that you wish to execute. The ID is then sent to the context's Prepare() method.
module |
The name of the module. Can be null. |
index |
The index of the function. |
A negative value on error, or the ID of the script function.
int GetFunctionIDByName(const char *module, const char *name);
This method should be used to retrieve the ID of the script function that you wish to execute. The ID is then sent to the context's Prepare() method.
module |
The name of the module. Can be null. |
name |
The name of the function. |
A negative value on error, or the ID of the script function.
int GetFunctionIDByDecl(const char *module, const char *decl);
This method should be used to retrieve the ID of the script function that you wish to execute. The ID is then sent to the context's Prepare() method.
The method will find the script function with the exact same declaration.
module |
The name of the module. Can be null. |
decl |
The declaration of the function. |
A negative value on error, or the ID of the script function.
const char *GetFunctionDeclaration(int funcID, int *length = 0);
This method can be used to retrieve the function declaration of the script functions that the host application will call. Verifying the declaration is important because, even though the script may compile correctly the user may not have written the function interface as intended.
funcID |
ID of the function, obtained with GetFunctionID(). |
length |
Pointer to a variable that will receive the length of the returned string. Can be NULL. |
A null-terminated string with the function declaration. Note, the string is shared with other functions in the library so you shouldn't store the pointer.
const char *GetFunctionName(int funcID, int *length = 0);
This method can be used to retrieve the function name of the script functions that the host application can call. Useful for obtaining the name of functions with ID obtained from GetExceptionFunction().
funcID |
ID of the function. |
length |
Pointer to a variable that will receive the length of the returned string. Can be NULL. |
A null-terminated string with the function name. Note, the string is shared with other functions in the library so you shouldn't store the pointer.
const char *GetFunctionModule(int funcID, int *length = 0);
This method returns the name of the module where the function was implemented.
funcID |
ID of the function. |
length |
Pointer to a variable that will receive the length of the returned string. Can be NULL. |
A null-terminated string with the module name. Note, the string is shared with other functions in the library so you shouldn't store the pointer.
const char *GetFunctionSection(int funcID, int *length = 0);
This method returns the name of the section where the function was implemented.
funcID |
ID of the function. |
length |
Pointer to a variable that will receive the length of the returned string. Can be NULL. |
A null-terminated string with the section name. Note, the string is shared with other functions in the library so you shouldn't store the pointer.
int GetMethodCount(int typeId);
This method retrieves the number of compiled script methods for a class.
typeId |
The typeId of the class or interface, obtained by GetTypeIdByDecl(). |
A negative value on error, or the number of script methods for the class if successful.
int GetMethodIDByIndex(int typeId, int index);
This method should be used to retrieve the ID of the script method for the object that you wish to execute. The ID is then sent to the context's Prepare() method.
typeId |
The typeId of the class or interface, obtained by GetTypeIdByDecl(). |
index |
The index of the function. |
A negative value on error, or the ID of the script method.
int GetMethodIDByName(int typeId, const char *name);
This method should be used to retrieve the ID of the script method for the object that you wish to execute. The ID is then sent to the context's Prepare() method.
typeId |
The typeId of the class or interface, obtained by GetTypeIdByDecl(). |
name |
The name of the function. |
A negative value on error, or the ID of the script method.
int GetMethodIDByDecl(int typeId, const char *decl);
This method should be used to retrieve the ID of the script method for the object that you wish to execute. The ID is then sent to the context's Prepare() method.
The method will find the script method with the exact same declaration.
typeId |
The typeId of the class or interface, obtained by GetTypeIdByDecl(). |
decl |
The declaration of the function. |
A negative value on error, or the ID of the script method.
int GetGlobalVarCount(const char *module);
This method retrieves the number of compiled script variables. It can be used for enumerating the script variables, as the IDs of the script variables will be between 0 and count - 1.
module |
The name of the module. Can be null. |
A negative value on error, or the number of script variables if successful.
int GetGlobalVarIDByIndex(const char *module, int index);
This method should be used to retrieve the ID of the script variable that you wish to access.
module |
The name of the module. Can be null. |
index |
The index of the variable. |
A negative value on error, or the ID of the script variable.
int GetGlobalVarIDByName(const char *module, const char *name);
This method should be used to retrieve the ID of the script variable that you wish to access.
module |
The name of the module. Can be null. |
name |
The name of the variable. |
A negative value on error, or the ID of the script variable.
int GetGlobalVarIDByDecl(const char *module, const char *decl);
This method should be used to retrieve the ID of the script variable that you wish to access.
The method will find the script variable with the exact same declaration.
module |
The name of the module. Can be null. |
decl |
The declaration of the variable. |
A negative value on error, or the ID of the script variable.
const char *GetGlobalVarDeclaration(int gvarID, int *length = 0);
This method can be used to retrieve the variable declaration of the script variables that the host application will access. Verifying the declaration is important because, even though the script may compile correctly the user may not have used the variable types as intended.
gvarID |
ID of the variable. |
length |
Pointer to a variable that will receive the length of the returned string. Can be NULL. |
Returns a null-terminated string with the variable declaration. Note, this string is shared with other functions in the library so you shouldn't store the pointer.
const char *GetGlobalVarName(int gvarID, int *length = 0);
This method can be used to retrieve the variable name of the script variables that the host application can access.
gvarID |
ID of the variable. |
length |
Pointer to a variable that will receive the length of the returned string. Can be NULL. |
Returns a null-terminated string with the variable name. Note, this string is shared with other functions in the library so you shouldn't store the pointer.
void *GetGlobalVarPointer(int gvarID);
This method should be used to retrieve the pointer of a variable that you wish to access.
For object variables, you'll receive a pointer to a pointer to the object, because that's how objects are stored in AngelScript. Note that the returned pointer may point to a null pointer if the variable hasn't been initialized yet.
gvarID |
The id of the variable. |
Returns the pointer, or null if it cannot be located.
int GetImportedFunctionCount(const char *module);
This function returns the number of functions that are imported in a module. These functions need to be bound before they can be used, or a script exception will be thrown.
module |
The name of the module, or null. |
Returns the number of imported functions declared in the module, or negative if unsuccessful.
int GetImportedFunctionIndexByDecl(const char *module, const char *decl);
This function is used to find a specific imported function by its declaration.
module |
The name of the module, or null. |
decl |
The function declaration. |
Returns the index of the imported function if successful, negative otherwise.
const char *GetImportedFunctionDeclaration(const char *module, int importIndex, int *length = 0);
Use this function to get the declaration of the imported function. The returned declaration can be used to find a matching function in another module that can be bound to the imported function.
module |
The name of the module, or null. |
importIndex |
Index of the imported function. |
length |
A pointer to a variable that will receive the length of the string. Can be NULL. |
A null-terminated string with the declaration of the function.
const char *GetImportedFunctionSourceModule(const char *module, int importIndex, int *length = 0);
Use this function to get the name of the suggested module to import the function from.
module |
The name of the module, or null. |
importIndex |
Index of the imported function. |
length |
A pointer to a variable that will receive the length of the string. Can be NULL. |
Null if unsuccessful, a pointer to the module name string if successful.
int BindImportedFunction(const char *module, int importIndex, int funcID);
The imported function is only bound if the functions have the exact same interface, i.e the same return type, and parameters.
module |
The name of the module, or null. |
importIndex |
Index of the imported function. |
funcID |
The function ID for the function that should be bound to the imported function. |
Negative on error.
int UnbindImportedFunction(const char *module, int importIndex);
Unbinds the imported function.
module |
The name of the module, or null. |
importIndex |
Index of the imported function. |
Negative on error.
int BindAllImportedFunctions(const char *module);
This functions tries to bind all imported functions in the module by searching for matching functions in the suggested modules. If a function cannot be bound the function will give an error asCANT_BIND_ALL_FUNCTIONS, but it will continue binding the rest of the functions.
module |
The name of the module, or null. |
Negative on error.
int UnbindAllImportedFunctions(const char *module);
Unbinds all imported functions in the module.
module |
The name of the module, or null. |
Negative on error.
int GetTypeIdByDecl(const char *module, const char *decl);
Translates a type declaration into a type id. The returned type id is valid for as long as the type is valid, so you can safely store it for later use to avoid potential overhead by calling this function each time. Just remember to update the type id, any time the type is changed within the engine, e.g. when recompiling script declared structures, or changing the engine configuration.
The type id is based on a sequence number and depends on the order in which the type ids are queried, thus is not guaranteed to always be the same for each execution of the application.
A base type yields the same type id whether the declaration is const or not, however if the const is for the subtype then the type id is different, e.g. string@ isn't the same as const string@ but string is the same as const string.
module |
The name of the module, or null. |
decl |
The type declaration. |
The type id if successful, or a negative value on error.
const char *GetTypeDeclaration(int typeId, int *length = 0);
Translates a type id into the type declaration string.
typeId |
The typeId. |
length |
A pointer to the variable that will receive the length of the returned string. |
A pointer to the string that holds the type declaration. The memory for the string is shared internally by the engine so do not store it for later use.
If the typeId is not valid the returned pointer will be null.
int SetDefaultContextStackSize(asUINT initial, asUINT maximum);
This method allow the application define the initial and maximum context stack sizes. All contexts will use these values when allocating the stack size.
The context will always make sure there is enough stack size to execute the function, even if the initial stack size is set too low. If the maximum stack size is larger than 0 then the stack size will only until the size has been reached. Each time the stack grows its size is doubled, which means that the stack size can be at most 2 times the maximum size.
initial |
The initial stack size in bytes. Default is 1024. |
maximum |
The maximum stack size in bytes. Default is 0. |
Returns negative on failure.
asIScriptContext *CreateContext();
This method creates a context that will be used to execute the script functions. The context interface created will have its reference counter already increased.
Returns the context pointer.
void *CreateScriptObject(int typeId);
This method is used to create a script object based on it's type id. The method will allocate the memory and call the object's default constructor.
This only works for objects, for primitive types and object handles the method doesn't do anything and returns a null pointer.
typeId |
The type id for the object type. |
Returns the pointer to the initialized object.
void *CreateScriptObjectCopy(void *obj, int typeId);
This method is used to create a copy of an existing object.
This only works for objects, for primitive types and object handles the method doesn't do anything and returns a null pointer.
obj |
A pointer to the object of which the copy will be made. |
typeId |
The type id for the object type. |
Returns the pointer to the initialized object.
void CopyScriptObject(void *dstObj, void *srcObj, int typeId);
This calls the assignment operator to copy the object from one to the other.
This only works for objects.
dstObj |
A pointer to the destination object. |
srcObj |
A pointer to the source object. |
typeId |
The type id for the object type. |
void ReleaseScriptObject(void *obj, int typeId);
This calls the release method of the object to release the reference.
This only works for objects.
obj |
A pointer to the object. |
typeId |
The type id for the object type. |
void AddRefScriptObject(void *obj, int typeId);
This calls the add ref method of the object to increase the reference count.
This only works for objects.
obj |
A pointer to the object. |
typeId |
The type id for the object type. |
bool IsHandleCompatibleWithObject(void *obj, int objTypeId, int handleTypeId);
This method can be used to determine if a handle of a certain type is compatible with an object of another type. This is useful if you have a pointer to a object, but only knows that it implements a certain interface and now you want to determine if it implements another interface.
obj |
A pointer to the object. Can be null. |
objTypeId |
The type id for the object type. |
handleTypeId |
The type id for the handle type. |
True if the handle is compatible with the object type.
int ExecuteString(const char *module, const char *script, asIScriptContext **ctx = 0, asDWORD flags = 0);
This method allow an application to interpret script statements using the currently compiled code.
module |
The name of the module. Can be null. |
script |
The script statements separated by ;. These statements will be executed within function scope, so any variable declarations will only be available to the current call. |
ctx |
An optional parameter that will receive the context pointer. Or if asEXECSTRING_USE_MY_CONTEXT is specified is used to pass a context to the method. |
flags |
The flags can be either 0 or a combination of asEXECSTRING_ONLY_PREPARE and asEXECSTRING_USE_MY_CONTEXT. With asEXECSTRING_ONLY_PREPARE the function returns immediately without executing the statements. With asEXECSTRING_USE_MY_CONTEXT the method uses the context supplied by the application instead of allocating its own context. |
On error the return value is negative, otherwise the function returns the state of the context when it finishes.
int GarbageCollect(bool doFullCycle);
This method will free script objects that can no longer be reached. When the engine is released the garbage collector will automatically do a full cycle to release all objects still alive. If the engine is long living it is important to call this method every once in a while to free up memory allocated by the scripts. If a script does a lot of allocations before returning it may be necessary to implement a line callback function that calls the garbage collector during execution of the script.
It is not necessary to do a full cycle with every call. This makes it possible to spread out the garbage collection time over a large period, thus not impacting the responsiveness of the application.
doFullCycle |
Set to true if the garbage collector should complete a full cycle before returning, or false if it should just make a small incremental step. |
Returns 1 if the cycle wasn't completed yet, or 0 if it is was. If an error occurs the value is negative.
int GetObjectsInGarbageCollectorCount();
This method can be used to query the number of objects that the garbage collector is keeping track of. If the number is very large then it is probably time to call the GarbageCollect() method so that some of the objects can be freed.
Note, that the objects that the garbage collector keeps track of may in turn hold references to other objects, but these are not reflected in the return value. Thus there is no way of knowing the exact amount of memory allocated directly and indirectly by the objects referred to by this function.
The number of objects.
int SaveByteCode(const char *module, asIBinaryStream *out);
With this method an application can save the compiled byte code for a module and later restore it.
It is important to make sure the engine configuration is the same when loading the bytecode again.
module |
The name of the module. Can be null. |
out |
A pointer to an binary stream interface that will receive the necessary data. |
Returns negative if an error occurs.
int LoadByteCode(const char *module, asIBinaryStream *out);
With this method an application load the previously compiled byte code for a module.
It is important to make sure the engine configuration is the same as it was when the module was saved.
Warning: There is a potential security risk with loading precompiled bytecode. A person with malicious intent could write bytecode that exploit your application to harm to the end-user. However this risk is not greater than using dynamically loaded libraries. You can minimize the risk by adding checksums and other validations to the code.
module |
The name of the module. Can be null. |
out |
A pointer to an binary stream interface that will feed the engine with the necessary data. |
Returns negative if an error occurs.