index

Reference: asIScriptEngine

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);
};

AddRef

int AddRef();

Description

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.

Returns

The internal reference counter.

Release

int Release();

Description

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.

Returns

The internal reference counter.

SetEngineProperty

int SetEngineProperty(asDWORD property, asPWORD value);

Description

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.

Parameters

property 

One of the value properties.

values 

The new value of the property.

Returns

A negative value on an error.

GetEngineProperty

asPWORD GetEngineProperty(asDWORD property);

Description

This method returns the value of the engine property.

Parameters

property 

One of the value properties.

Returns

The value of the property if valid, 0 otherwise.

SetMessageCallback

int SetMessageCallback(const asUPtr &callback, void *obj, asDWORD callConv);

Description

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.

Parameters

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.

Returns

A negative value on an error.

ClearMessageCallback

int ClearMessageCallback();

Description

This method is used to clear the message callback.

Returns

A negative value on an error.

RegisterObjectType

int RegisterObjectType(const char *name, int byteSize, asDWORD flags);

Description

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.

Parameters

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.

Returns

A negative value on error, 0 or greater if successful.

RegisterObjectProperty

int RegisterObjectProperty(const char *obj,
                           const char *declaration,
                           int byteOffset);

Description

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.

Parameters

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.

Returns

A negative value on error, 0 or greater if successful.

RegisterObjectMethod

int RegisterObjectMethod(const char *obj,
                         const char *declaration,
                         const asUPtr &funcPointer,
                         asDWORD callConv);

Description

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);

Parameters

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.

Returns

A negative value on error, 0 or greater if successful.

RegisterObjectBehaviour

int RegisterObjectBehaviour(const char *datatype,
                            asDWORD behaviour,
                            const char *declaration,
                            const asUPtr &funcPointer,
                            asDWORD callConv);

Description

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.

Parameters

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.

Returns

A negative value on error, 0 or greater if successful.

RegisterGlobalProperty

int RegisterGlobalProperty(const char *declaration,
                           void *pointer);

Description

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.

Parameters

declaration 

The property declaration, with data type and name.

pointer 

A pointer to the variable holding the property's value.

Returns

A negative value on error, 0 or greater if successful.

RegisterGlobalFunction

int RegisterGlobalFunction(const char *declaration,
                           const asUPtr &funcPointer,
                           asDWORD callConv);

Description

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.

Returns

A negative value on error, 0 or greater if successful.

RegisterGlobalBehaviour

int RegisterGlobalBehaviour(asDWORD behaviour,
                            const char *declaration,
                            const asUPtr &funcPointer,
                            asDWORD callConv);

Description

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.

Parameters

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.

Returns

A negative value on error, 0 or greater if successful.

RegisterInterface

int RegisterInterface(const char *name);

Description

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.

Parameters

name 

The name of the interface.

Returns

A negative value on error, 0 or greater if successful.

RegisterInterfaceMethod

int RegisterInterfaceMethod(const char *intf, const char *declaration);

Description

This registers the method that the interface must implement.

Parameters

intf 

The name of the interface.

declaration 

The method declaration.

Returns

A negative value on error, 0 or greater if successful.

RegisterStringFactory

int RegisterStringFactory(const char *datatype,
                          const asUPtr &factoryFunc,
                          asDWORD callConv);

Description

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.

Parameters

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.

Returns

A negative value on error, 0 or greater if successful.

BeginConfigGroup

int BeginConfigGroup(const char *groupName);

Description

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.

Parameters

groupName 

The name of the group.

Returns

A negative value on error, 0 or greater if successful.

EndConfigGroup

int EndConfigGroup();

Description

Ends the current configuration group. Once finished a config group cannot be changed, but it can be removed when it is no longer used.

Returns

A negative value on error, 0 or greater if successful.

RemoveConfigGroups

int RemoveConfigGroup(const char *groupName);

Description

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.

Parameters

groupName 

The name of the group.

Returns

A negative value on error, 0 or greater if successful.

SetConfigGroupModuleAccess

int SetConfigGroupModuleAccess(const char *groupName, const char *module, bool hasAccess);

Description

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.

Parameters

groupName 

The name of the group.

module 

The name of the module, or asALL_MODULES.

hasAccess 

Access mode.

Returns

A negative value on error, 0 or greater if successful.

AddScriptSection

int AddScriptSection(const char *module,
                     const char *name,
                     const char *code,
                     size_t codeLength,
                     int lineOffset = 0,
                     bool makeCopy = true);

Description

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.

Parameters

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.

Returns

A negative value on error, 0 or greater if successful.

Build

int Build(const char *module);

Description

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 callback function set with SetMessageCallback(). If there are no errors or warnings, no messages will be sent to the callback function.

Parameters

module 

The name of the module. Can be null.

Returns

A negative value on error, 0 or greater if successful.

Discard

int Discard(const char *module);

Description

Discards a module and frees its memory.

Parameters

module 

The name of the module. Can be null.

Returns

A negative value on error, 0 or greater if successful.

ResetModule

int ResetModule(const char *module);

Description

Resets the global variables declared in this module to their initial value.

Parameters

module 

The name of the module. Can be null.

Returns

A negative value on error, 0 or greater if successful.

GetFunctionCount

int GetFunctionCount(const char *module);

Description

This method retrieves the number of compiled script functions.

Parameters

module 

The name of the module. Can be null.

Returns

A negative value on error, or the number of script functions if successful.

GetFunctionIDByIndex

int GetFunctionIDByIndex(const char *module, int index);

Description

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.

Parameters

module 

The name of the module. Can be null.

index 

The index of the function.

Returns

A negative value on error, or the ID of the script function.

GetFunctionIDByName

int GetFunctionIDByName(const char *module, const char *name);

Description

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.

Parameters

module 

The name of the module. Can be null.

name 

The name of the function.

Returns

A negative value on error, or the ID of the script function.

GetFunctionIDByDecl

int GetFunctionIDByDecl(const char *module, const char *decl);

Description

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.

Parameters

module 

The name of the module. Can be null.

decl 

The declaration of the function.

Returns

A negative value on error, or the ID of the script function.

GetFunctionDeclaration

const char *GetFunctionDeclaration(int funcID,
                                   int *length = 0);

Description

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.

Parameters

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.

Returns

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.

GetFunctionName

const char *GetFunctionName(int funcID,
                            int *length = 0);

Description

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().

Parameters

funcID 

ID of the function.

length 

Pointer to a variable that will receive the length of the returned string. Can be NULL.

Returns

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.

GetFunctionModule

const char *GetFunctionModule(int funcID,
                              int *length = 0);

Description

This method returns the name of the module where the function was implemented.

Parameters

funcID 

ID of the function.

length 

Pointer to a variable that will receive the length of the returned string. Can be NULL.

Returns

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.

GetFunctionSection

const char *GetFunctionSection(int funcID,
                               int *length = 0);

Description

This method returns the name of the section where the function was implemented.

Parameters

funcID 

ID of the function.

length 

Pointer to a variable that will receive the length of the returned string. Can be NULL.

Returns

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.

GetMethodCount

int GetMethodCount(int typeId);

Description

This method retrieves the number of compiled script methods for a class.

Parameters

typeId 

The typeId of the class or interface, obtained by GetTypeIdByDecl().

Returns

A negative value on error, or the number of script methods for the class if successful.

GetMethodIDByIndex

int GetMethodIDByIndex(int typeId, int index);

Description

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.

Parameters

typeId 

The typeId of the class or interface, obtained by GetTypeIdByDecl().

index 

The index of the function.

Returns

A negative value on error, or the ID of the script method.

GetMethodIDByName

int GetMethodIDByName(int typeId, const char *name);

Description

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.

Parameters

typeId 

The typeId of the class or interface, obtained by GetTypeIdByDecl().

name 

The name of the function.

Returns

A negative value on error, or the ID of the script method.

GetMethodIDByDecl

int GetMethodIDByDecl(int typeId, const char *decl);

Description

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.

Parameters

typeId 

The typeId of the class or interface, obtained by GetTypeIdByDecl().

decl 

The declaration of the function.

Returns

A negative value on error, or the ID of the script method.

GetGlobalVarCount

int GetGlobalVarCount(const char *module);

Description

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.

Parameters

module 

The name of the module. Can be null.

Returns

A negative value on error, or the number of script variables if successful.

GetGlobalVarIDByIndex

int GetGlobalVarIDByIndex(const char *module, int index);

Description

This method should be used to retrieve the ID of the script variable that you wish to access.

Parameters

module 

The name of the module. Can be null.

index 

The index of the variable.

Returns

A negative value on error, or the ID of the script variable.

GetGlobalVarIDByName

int GetGlobalVarIDByName(const char *module, const char *name);

Description

This method should be used to retrieve the ID of the script variable that you wish to access.

Parameters

module 

The name of the module. Can be null.

name 

The name of the variable.

Returns

A negative value on error, or the ID of the script variable.

GetGlobalVarIDByDecl

int GetGlobalVarIDByDecl(const char *module, const char *decl);

Description

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.

Parameters

module 

The name of the module. Can be null.

decl 

The declaration of the variable.

Returns

A negative value on error, or the ID of the script variable.

GetGlobalVarDeclaration

const char *GetGlobalVarDeclaration(int gvarID,
                                    int *length = 0);

Description

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.

Parameters

gvarID 

ID of the variable.

length 

Pointer to a variable that will receive the length of the returned string. Can be NULL.

Returns

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.

GetGlobalVarName

const char *GetGlobalVarName(int gvarID,
                             int *length = 0);

Description

This method can be used to retrieve the variable name of the script variables that the host application can access.

Parameters

gvarID 

ID of the variable.

length 

Pointer to a variable that will receive the length of the returned string. Can be NULL.

Returns

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.

GetGlobalVarPointer

void *GetGlobalVarPointer(int gvarID);

Description

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.

Parameters

gvarID 

The id of the variable.

Returns

Returns the pointer, or null if it cannot be located.

GetImportedFunctionCount

int GetImportedFunctionCount(const char *module);

Description

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.

Parameters

module 

The name of the module, or null.

Returns

Returns the number of imported functions declared in the module, or negative if unsuccessful.

GetImportedFunctionIndexByDecl

int GetImportedFunctionIndexByDecl(const char *module, const char *decl);

Description

This function is used to find a specific imported function by its declaration.

Parameters

module 

The name of the module, or null.

decl 

The function declaration.

Returns

Returns the index of the imported function if successful, negative otherwise.

GetImportedFunctionDeclaration

const char *GetImportedFunctionDeclaration(const char *module, int importIndex, int *length = 0);

Description

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.

Parameters

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.

Returns

A null-terminated string with the declaration of the function.

GetImportedFunctionSourceModule

const char *GetImportedFunctionSourceModule(const char *module, int importIndex, int *length = 0);

Description

Use this function to get the name of the suggested module to import the function from.

Parameters

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.

Returns

Null if unsuccessful, a pointer to the module name string if successful.

BindImportedFunction

int BindImportedFunction(const char *module, int importIndex, int funcID);

Description

The imported function is only bound if the functions have the exact same interface, i.e the same return type, and parameters.

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.

Returns

Negative on error.

UnbindImportedFunction

int UnbindImportedFunction(const char *module, int importIndex);

Description

Unbinds the imported function.

Parameters

module 

The name of the module, or null.

importIndex 

Index of the imported function.

Returns

Negative on error.

BindAllImportedFunctions

int BindAllImportedFunctions(const char *module);

Description

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.

Parameters

module 

The name of the module, or null.

Returns

Negative on error.

UnbindAllImportedFunctions

int UnbindAllImportedFunctions(const char *module);

Description

Unbinds all imported functions in the module.

Parameters

module 

The name of the module, or null.

Returns

Negative on error.

GetTypeIdByDecl

int GetTypeIdByDecl(const char *module, const char *decl);

Description

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.

Parameters

module 

The name of the module, or null.

decl 

The type declaration.

Returns

The type id if successful, or a negative value on error.

GetTypeDeclaration

const char *GetTypeDeclaration(int typeId, int *length = 0);

Description

Translates a type id into the type declaration string.

Parameters

typeId 

The typeId.

length 

A pointer to the variable that will receive the length of the returned string.

Returns

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.

SetDefaultContextStackSize

int SetDefaultContextStackSize(asUINT initial, asUINT maximum);

Description

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.

Parameters

initial 

The initial stack size in bytes. Default is 1024.

maximum 

The maximum stack size in bytes. Default is 0.

Returns

Returns negative on failure.

CreateContext

asIScriptContext *CreateContext();

Description

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

Returns the context pointer.

CreateScriptObject

void *CreateScriptObject(int typeId);

Description

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.

Parameters

typeId 

The type id for the object type.

Returns

Returns the pointer to the initialized object.

CreateScriptObjectCopy

void *CreateScriptObjectCopy(void *obj, int typeId);

Description

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.

Parameters

obj 

A pointer to the object of which the copy will be made.

typeId 

The type id for the object type.

Returns

Returns the pointer to the initialized object.

CopyScriptObject

void CopyScriptObject(void *dstObj, void *srcObj, int typeId);

Description

This calls the assignment operator to copy the object from one to the other.

This only works for objects.

Parameters

dstObj 

A pointer to the destination object.

srcObj 

A pointer to the source object.

typeId 

The type id for the object type.

ReleaseScriptObject

void ReleaseScriptObject(void *obj, int typeId);

Description

This calls the release method of the object to release the reference.

This only works for objects.

Parameters

obj 

A pointer to the object.

typeId 

The type id for the object type.

AddRefScriptObject

void AddRefScriptObject(void *obj, int typeId);

Description

This calls the add ref method of the object to increase the reference count.

This only works for objects.

Parameters

obj 

A pointer to the object.

typeId 

The type id for the object type.

IsHandleCompatibleWithObject

bool IsHandleCompatibleWithObject(void *obj, int objTypeId, int handleTypeId);

Description

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.

Parameters

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.

Returns

True if the handle is compatible with the object type.

ExecuteString

int ExecuteString(const char *module,
                  const char *script,
                  asIScriptContext **ctx = 0,
                  asDWORD flags = 0);

Description

This method allow an application to interpret script statements using the currently compiled code.

Parameters

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.

Returns

On error the return value is negative, otherwise the function returns the state of the context when it finishes.

GarbageCollect

int GarbageCollect(bool doFullCycle);

Description

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.

Parameters

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

Returns 1 if the cycle wasn't completed yet, or 0 if it is was. If an error occurs the value is negative.

GetObjectsInGarbageCollectorCount

int GetObjectsInGarbageCollectorCount();

Description

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.

Returns

The number of objects.

SaveByteCode

int SaveByteCode(const char *module, asIBinaryStream *out);

Description

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.

Parameters

module 

The name of the module. Can be null.

out 

A pointer to an binary stream interface that will receive the necessary data.

Returns

Returns negative if an error occurs.

LoadByteCode

int LoadByteCode(const char *module, asIBinaryStream *out);

Description

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.

Parameters

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

Returns negative if an error occurs.

top