class asIScriptEngine { public: // Memory management virtual int AddRef() = 0; virtual int Release() = 0; // Engine configuration virtual int RegisterObjectType(const char *name, int byteSize, asDWORD flags) = 0; virtual int RegisterObjectProperty(const char *obj, const char *declaration, int byteOffset) = 0; virtual int RegisterObjectMethod(const char *obj, const char *declaration, asUPtr funcPointer, asDWORD callConv) = 0; virtual int RegisterObjectBehaviour(const char *datatype, asDWORD behaviour, const char *declaration, asUPtr funcPointer, asDWORD callConv) = 0; virtual int RegisterGlobalProperty(const char *declaration, void *pointer) = 0; virtual int RegisterGlobalFunction(const char *declaration, asUPtr funcPointer, asDWORD callConv) = 0; virtual int RegisterGlobalBehaviour(asDWORD behaviour, const char *declaration, asUPtr funcPointer, asDWORD callConv) = 0; virtual int RegisterStringFactory(const char *datatype, asUPtr factoryFunc, asDWORD callConv) = 0; // Script modules virtual int AddScriptSection(const char *module, const char *name, const char *code, int codeLength, int lineOffset = 0) = 0; virtual int Build(const char *module, asIOutputStream *out = 0) = 0; virtual int Discard(const char *module) = 0; virtual int GetModuleIndex(const char *module) = 0; virtual const char *GetModuleNameFromIndex(int index, int *length = 0) = 0; // Script functions virtual int GetFunctionCount(const char *module) = 0; virtual int GetFunctionIDByIndex(const char *module, int index) = 0; virtual int GetFunctionIDByName(const char *module, const char *name) = 0; virtual int GetFunctionIDByDecl(const char *module, const char *decl) = 0; virtual const char *GetFunctionDeclaration(int funcID, int *length = 0) = 0; virtual const char *GetFunctionName(int funcID, int *length = 0) = 0; // Script global variables virtual int GetGlobalVarCount(const char *module) = 0; virtual int GetGlobalVarIDByIndex(const char *module, int index) = 0; virtual int GetGlobalVarIDByName(const char *module, const char *name) = 0; virtual int GetGlobalVarIDByDecl(const char *module, const char *decl) = 0; virtual const char *GetGlobalVarDeclaration(int gvarID, int *length = 0) = 0; virtual const char *GetGlobalVarName(int gvarID, int *length = 0) = 0; virtual int GetGlobalVarPointer(int gvarID, void **pointer) = 0; // Dynamic binding between modules virtual int GetImportedFunctionCount(const char *module) = 0; virtual int GetImportedFunctionIndexByDecl(const char *module, const char *decl) = 0; virtual const char *GetImportedFunctionDeclaration(const char *module, int importIndex, int *length = 0) = 0; virtual const char *GetImportedFunctionSourceModule(const char *module, int importIndex, int *length = 0) = 0; virtual int BindImportedFunction(const char *module, int importIndex, int funcID) = 0; virtual int UnbindImportedFunction(const char *module, int importIndex) = 0; virtual int BindAllImportedFunctions(const char *module) = 0; virtual int UnbindAllImportedFunctions(const char *module) = 0; // Script execution virtual int SetDefaultContextStackSize(asUINT initial, asUINT maximum) = 0; virtual int CreateContext(asIScriptContext **context) = 0; // String interpretation virtual int ExecuteString(const char *module, const char *script, asIOutputStream *out = 0, asIScriptContext **ctx = 0, asDWORD flags = 0) = 0; // Bytecode saving/loading virtual int SaveByteCode(const char *module, asIBinaryStream *out) = 0; virtual int LoadByteCode(const char *module, asIBinaryStream *in) = 0; };
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 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.
Remember that AngelScript only supports 32 bit data types, so registering a property of different size may give unexpected behaviour.
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, 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.
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 or asCALL_CDECL_OBJLAST. |
A negative value on error, 0 or greater if successful.
int RegisterObjectBehaviour(const char *datatype, asDWORD behaviour, const char *declaration, 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.
The following functions must be registered as object members, i.e. with datatype set to the type name. The allowed calling conventions are asCALL_THISCALL and asCALL_CDECL_OBJLAST.
Behaviour | Operator | Script function | C++ function |
asBEHAVE_CONSTRUCT | (birth) | void f() | void OBJ::f(), void f(OBJ &) |
asBEHAVE_DESTRUCT | (death) | void f() | void OBJ::f(), void f(OBJ &) |
asBEHAVE_ASSIGNMENT | =, (copy) | OBJ &f(OBJ &) | OBJ &OBJ::f(OBJ &other), OBJ &f(OBJ &other, OBJ &dst) |
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.
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, asUPtr funcPointer, asDWORD callConv);
This method registers system functions that the scripts may use to communicate with the host application.
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 or asCALL_STDCALL. |
A negative value on error, 0 or greater if successful.
int RegisterGlobalBehaviour(asDWORD behaviour, const char *declaration, 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.
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 RegisterStringFactory(const char *datatype, 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 or asCALL_STDCALL. |
A negative value on error, 0 or greater if successful.
int AddScriptSection(const char *module, const char *name, const char *code, int codeLength, int lineOffset = 0);
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. |
A negative value on error, 0 or greater if successful.
int Build(const char *module, asIOutputStream *out = 0);
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.
module |
The name of the module. Can be null. |
out |
A pointer to an output stream that will receive the build messages. |
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 GetModuleIndex(const char *module);
Gets the module index from the module name.
module |
The name of the module. Can be null. |
A negative value on error, or the index of the module.
Gets the module name from the module index.
const char *GetModuleNameFromIndex(int index, int *length = 0);
index |
The index of the module. |
length |
Pointer to a variable that will receive the length of the string. Can be NULL. |
Null on error, or a pointer to the name of the module.
int GetFunctionCount(const char *module);
This method retrieves the number of compiled script functions. It can be used for enumerating the script functions, as the IDs of the script functions 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 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.
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.
int GetGlobalVarPointer(int gvarID, void **pointer);
This method should be used to retrieve the pointer of a variable that you wish to access.
gvarID |
The id of the variable. |
pointer |
A pointer to a pointer to the variable that will be set by the function. |
A negative value on error.
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 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.
int CreateContext(asIScriptContext **context);
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.
context |
Pointer to the variable that will get the pointer of the context. |
Returns the context id on success and a negative value on failure.
int ExecuteString(const char *module, const char *script, asIOutputStream *out = 0, 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. |
out |
An optional outstream that will receive build errors. |
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 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.
NOTE: 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. A protection against such attacks is under development and will be released in the near future.
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.