# angelscript.h File Reference

The API definition for AngelScript. More...

## Classes
struct | asSFuncPtr
| Represents a function or method pointer. More...
struct | asSMessageInfo
| Represents a compiler message. More...
class | asIScriptEngine
| The engine interface. More...
class | asIScriptModule
| The interface to the script modules. More...
class | asIScriptContext
| The interface to the virtual machine. More...
class | asIScriptGeneric
| The interface for the generic calling convention. More...
class | asIScriptStruct
| The interface for a script class or interface. More...
class | asIScriptArray
| The interface for a script array object. More...
class | asIObjectType
| The interface for an object type. More...
class | asIScriptFunction
| The interface for a script function description. More...
class | asIBinaryStream
| A binary stream interface. More...
## Defines
#define | ANGELSCRIPT_VERSION 21500
| The library version.
#define | asFUNCTION(f) asFunctionPtr(f)
| Returns an asSFuncPtr representing the function specified by the name.
#define | asFUNCTIONPR(f, p, r) asFunctionPtr((void (*)())((r (*)p)(f)))
| Returns an asSFuncPtr representing the function specified by the name, parameter list, and return type.
#define | asMETHOD(c, m) asSMethodPtr<sizeof(void (c::*)())>::Convert((void (c::*)())(&c::m))
| Returns an asSFuncPtr representing the class method specified by class and method name.
#define | asMETHODPR(c, m, p, r) asSMethodPtr<sizeof(void (c::*)())>::Convert((r (c::*)p)(&c::m))
| Returns an asSFuncPtr representing the class method specified by class, method name, parameter list, return type.
#define | AS_API
| A define that specifies how the function should be imported.
## Typedefs
typedef unsigned char | asBYTE
| 8 bit unsigned integer
typedef unsigned short | asWORD
| 16 bit unsigned integer
typedef unsigned int | asUINT
| 32 bit unsigned integer
typedef size_t | asPWORD
| Unsigned integer with the size of a pointer.
typedef unsigned long | asDWORD
| 32 bit unsigned integer
typedef unsigned __int64 | asQWORD
| 64 bit unsigned integer
typedef __int64 | asINT64
| 64 bit integer
typedef void *(* | asALLOCFUNC_t )(size_t)
| The function signature for the custom memory allocation function.
typedef void(* | asFREEFUNC_t )(void *)
| The function signature for the custom memory deallocation function.
## Enumerations
enum | asEEngineProp { asEP_ALLOW_UNSAFE_REFERENCES = 1, asEP_OPTIMIZE_BYTECODE = 2, asEP_COPY_SCRIPT_SECTIONS = 3, asEP_MAX_STACK_SIZE = 4, asEP_USE_CHARACTER_LITERALS = 5, asEP_ALLOW_MULTILINE_STRINGS = 6, asEP_ALLOW_IMPLICIT_HANDLE_TYPES = 7 }
| Engine properties. More...
enum | asECallConvTypes { asCALL_CDECL = 0, asCALL_STDCALL = 1, asCALL_THISCALL = 2, asCALL_CDECL_OBJLAST = 3, asCALL_CDECL_OBJFIRST = 4, asCALL_GENERIC = 5 }
| Calling conventions. More...
enum | asEObjTypeFlags { asOBJ_REF = 0x01, asOBJ_VALUE = 0x02, asOBJ_GC = 0x04, asOBJ_POD = 0x08, asOBJ_NOHANDLE = 0x10, asOBJ_SCOPED = 0x20, asOBJ_APP_CLASS = 0x100, asOBJ_APP_CLASS_CONSTRUCTOR = 0x200, asOBJ_APP_CLASS_DESTRUCTOR = 0x400, asOBJ_APP_CLASS_ASSIGNMENT = 0x800 , asOBJ_APP_PRIMITIVE = 0x1000, asOBJ_APP_FLOAT = 0x2000 }
| Object type flags. More...
enum | asEBehaviours { asBEHAVE_CONSTRUCT, asBEHAVE_DESTRUCT, asBEHAVE_FACTORY, asBEHAVE_ADDREF, asBEHAVE_RELEASE, asBEHAVE_VALUE_CAST, asBEHAVE_IMPLICIT_VALUE_CAST, asBEHAVE_INDEX, asBEHAVE_NEGATE , asBEHAVE_ASSIGNMENT = asBEHAVE_FIRST_ASSIGN, asBEHAVE_ADD_ASSIGN, asBEHAVE_SUB_ASSIGN, asBEHAVE_MUL_ASSIGN, asBEHAVE_DIV_ASSIGN, asBEHAVE_MOD_ASSIGN, asBEHAVE_OR_ASSIGN, asBEHAVE_AND_ASSIGN, asBEHAVE_XOR_ASSIGN, asBEHAVE_SLL_ASSIGN, asBEHAVE_SRL_ASSIGN, asBEHAVE_SRA_ASSIGN , asBEHAVE_ADD = asBEHAVE_FIRST_DUAL, asBEHAVE_SUBTRACT, asBEHAVE_MULTIPLY, asBEHAVE_DIVIDE, asBEHAVE_MODULO, asBEHAVE_EQUAL, asBEHAVE_NOTEQUAL, asBEHAVE_LESSTHAN, asBEHAVE_GREATERTHAN, asBEHAVE_LEQUAL, asBEHAVE_GEQUAL, asBEHAVE_BIT_OR, asBEHAVE_BIT_AND, asBEHAVE_BIT_XOR, asBEHAVE_BIT_SLL, asBEHAVE_BIT_SRL, asBEHAVE_BIT_SRA , asBEHAVE_REF_CAST, asBEHAVE_IMPLICIT_REF_CAST , asBEHAVE_GETREFCOUNT = asBEHAVE_FIRST_GC, asBEHAVE_SETGCFLAG, asBEHAVE_GETGCFLAG, asBEHAVE_ENUMREFS, asBEHAVE_RELEASEREFS }
| Behaviours. More...
enum | asERetCodes { asSUCCESS = 0, asERROR = -1, asCONTEXT_ACTIVE = -2, asCONTEXT_NOT_FINISHED = -3, asCONTEXT_NOT_PREPARED = -4, asINVALID_ARG = -5, asNO_FUNCTION = -6, asNOT_SUPPORTED = -7, asINVALID_NAME = -8, asNAME_TAKEN = -9, asINVALID_DECLARATION = -10, asINVALID_OBJECT = -11, asINVALID_TYPE = -12, asALREADY_REGISTERED = -13, asMULTIPLE_FUNCTIONS = -14, asNO_MODULE = -15, asNO_GLOBAL_VAR = -16, asINVALID_CONFIGURATION = -17, asINVALID_INTERFACE = -18, asCANT_BIND_ALL_FUNCTIONS = -19, asLOWER_ARRAY_DIMENSION_NOT_REGISTERED = -20, asWRONG_CONFIG_GROUP = -21, asCONFIG_GROUP_IS_IN_USE = -22, asILLEGAL_BEHAVIOUR_FOR_TYPE = -23, asWRONG_CALLING_CONV = -24, asMODULE_IS_IN_USE = -25, asBUILD_IN_PROGRESS = -26 }
| Return codes. More...
enum | asEContextState { asEXECUTION_FINISHED = 0, asEXECUTION_SUSPENDED = 1, asEXECUTION_ABORTED = 2, asEXECUTION_EXCEPTION = 3, asEXECUTION_PREPARED = 4, asEXECUTION_UNINITIALIZED = 5, asEXECUTION_ACTIVE = 6, asEXECUTION_ERROR = 7 }
| Context states. More...
enum | asEExecStrFlags { asEXECSTRING_ONLY_PREPARE = 1, asEXECSTRING_USE_MY_CONTEXT = 2 }
| ExecuteString flags. More...
enum | asEMsgType { asMSGTYPE_ERROR = 0, asMSGTYPE_WARNING = 1, asMSGTYPE_INFORMATION = 2 }
| Compiler message types. More...
enum | asEGCFlags { asGC_FULL_CYCLE = 1, asGC_ONE_STEP = 2, asGC_DESTROY_GARBAGE = 4, asGC_DETECT_GARBAGE = 8 }
| Garbage collector flags. More...
enum | asETokenClass { asTC_UNKNOWN = 0, asTC_KEYWORD = 1, asTC_VALUE = 2, asTC_IDENTIFIER = 3, asTC_COMMENT = 4, asTC_WHITESPACE = 5 }
| Token classes. More...
enum | asEGMFlags { asGM_ONLY_IF_EXISTS = 0, asGM_CREATE_IF_NOT_EXISTS = 1, asGM_ALWAYS_CREATE = 2 }
| Flags for GetModule. More...
## Functions
AS_API asIScriptEngine * | asCreateScriptEngine (asDWORD version)
| Creates the script engine.
AS_API const char * | asGetLibraryVersion ()
| Returns the version of the compiled library.
AS_API const char * | asGetLibraryOptions ()
| Returns the options used to compile the library.
AS_API asIScriptContext * | asGetActiveContext ()
| Returns the currently active context.
AS_API int | asThreadCleanup ()
| Cleans up memory allocated for the current thread.
AS_API int | asSetGlobalMemoryFunctions (asALLOCFUNC_t allocFunc, asFREEFUNC_t freeFunc)
| Set the memory management functions that AngelScript should use.
AS_API int | asResetGlobalMemoryFunctions ()
| Remove previously registered memory management functions.

## Detailed Description

This header file describes the complete application programming interface for AngelScript.

## Enumeration Type Documentation

enum asEBehaviours

Enumerator:

  asBEHAVE_CONSTRUCT | (Object) Constructor
  asBEHAVE_DESTRUCT | (Object) Destructor
  asBEHAVE_FACTORY | (Object) Factory
  asBEHAVE_ADDREF | (Object) AddRef
  asBEHAVE_RELEASE | (Object) Release
  asBEHAVE_VALUE_CAST | (Object) Explicit value cast operator
  asBEHAVE_IMPLICIT_VALUE_CAST | (Object) Implicit value cast operator
  asBEHAVE_INDEX | (Object) operator []
  asBEHAVE_NEGATE | (Object) operator - (Unary negate)
  asBEHAVE_ASSIGNMENT | (Object) operator =
  asBEHAVE_ADD_ASSIGN | (Object) operator +=
  asBEHAVE_SUB_ASSIGN | (Object) operator -=
  asBEHAVE_MUL_ASSIGN | (Object) operator *=
  asBEHAVE_DIV_ASSIGN | (Object) operator /=
  asBEHAVE_MOD_ASSIGN | (Object) operator =
  asBEHAVE_OR_ASSIGN | (Object) operator |=
  asBEHAVE_AND_ASSIGN | (Object) operator &=
  asBEHAVE_XOR_ASSIGN | (Object) operator ^=
  asBEHAVE_SLL_ASSIGN | (Object) operator <<=
  asBEHAVE_SRL_ASSIGN | (Object) operator >>= (Logical right shift)
  asBEHAVE_SRA_ASSIGN | (Object) operator >>>= (Arithmetic right shift)
  asBEHAVE_ADD | (Global) operator +
  asBEHAVE_SUBTRACT | (Global) operator -
  asBEHAVE_MULTIPLY | (Global) operator *
  asBEHAVE_DIVIDE | (Global) operator /
  asBEHAVE_MODULO | (Global) operator %
  asBEHAVE_EQUAL | (Global) operator ==
  asBEHAVE_NOTEQUAL | (Global) operator !=
  asBEHAVE_LESSTHAN | (Global) operator <
  asBEHAVE_GREATERTHAN | (Global) operator >
  asBEHAVE_LEQUAL | (Global) operator <=
  asBEHAVE_GEQUAL | (Global) operator >=
  asBEHAVE_BIT_OR | (Global) operator |
  asBEHAVE_BIT_AND | (Global) operator &
  asBEHAVE_BIT_XOR | (Global) operator ^
  asBEHAVE_BIT_SLL | (Global) operator <<
  asBEHAVE_BIT_SRL | (Global) operator >> (Logical right shift)
  asBEHAVE_BIT_SRA | (Global) operator >>> (Arithmetic right shift)
  asBEHAVE_REF_CAST | (Global) Explicit reference cast operator
  asBEHAVE_IMPLICIT_REF_CAST | (Global) Implicit reference cast operator
  asBEHAVE_GETREFCOUNT | (Object, GC) Get reference count
  asBEHAVE_SETGCFLAG | (Object, GC) Set GC flag
  asBEHAVE_GETGCFLAG | (Object, GC) Get GC flag
  asBEHAVE_ENUMREFS | (Object, GC) Enumerate held references
  asBEHAVE_RELEASEREFS | (Object, GC) Release all references

enum asECallConvTypes

Enumerator:

  asCALL_CDECL | A cdecl function.
  asCALL_STDCALL | A stdcall function.
  asCALL_THISCALL | A thiscall class method.
  asCALL_CDECL_OBJLAST | A cdecl function that takes the object pointer as the last parameter.
  asCALL_CDECL_OBJFIRST | A cdecl function that takes the object pointer as the first parameter.
  asCALL_GENERIC | A function using the generic calling convention.

enum asEContextState

Enumerator:

  asEXECUTION_FINISHED | The context has successfully completed the execution.
  asEXECUTION_SUSPENDED | The execution is suspended and can be resumed.
  asEXECUTION_ABORTED | The execution was aborted by the application.
  asEXECUTION_EXCEPTION | The execution was terminated by an unhandled script exception.
  asEXECUTION_PREPARED | The context has been prepared for a new execution.
  asEXECUTION_UNINITIALIZED | The context is not initialized.
  asEXECUTION_ACTIVE | The context is currently executing a function call.
  asEXECUTION_ERROR | The context has encountered an error and must be reinitialized.

enum asEEngineProp

Enumerator:

  asEP_ALLOW_UNSAFE_REFERENCES | Allow unsafe references. Default: false.
  asEP_OPTIMIZE_BYTECODE | Optimize byte code. Default: true.
  asEP_COPY_SCRIPT_SECTIONS | Copy script section memory. Default: true.
  asEP_MAX_STACK_SIZE | Maximum stack size for script contexts. Default: 0 (no limit).
  asEP_USE_CHARACTER_LITERALS | Interpret single quoted strings as character literals. Default: false.
  asEP_ALLOW_MULTILINE_STRINGS | Allow linebreaks in string constants. Default: false.
  asEP_ALLOW_IMPLICIT_HANDLE_TYPES | Allow script to declare implicit handle types. Default: false.

enum asEExecStrFlags

Enumerator:

  asEXECSTRING_ONLY_PREPARE | Only prepare the context.
  asEXECSTRING_USE_MY_CONTEXT | Use the pre-allocated context.

enum asEGCFlags

Enumerator:

  asGC_FULL_CYCLE | Execute a full cycle.
  asGC_ONE_STEP | Execute only one step.
  asGC_DESTROY_GARBAGE | Destroy known garbage.
  asGC_DETECT_GARBAGE | Detect garbage with circular references.

enum asEGMFlags

Enumerator:

  asGM_ONLY_IF_EXISTS | Don't return any module if it is not found.
  asGM_CREATE_IF_NOT_EXISTS | Create the module if it doesn't exist.
  asGM_ALWAYS_CREATE | Always create a new module, discarding the existing one.

enum asEMsgType

Enumerator:

  asMSGTYPE_ERROR | The message is an error.
  asMSGTYPE_WARNING | The message is a warning.
  asMSGTYPE_INFORMATION | The message is informational only.

enum asEObjTypeFlags

Enumerator:

  asOBJ_REF | A reference type.
  asOBJ_VALUE | A value type.
  asOBJ_GC | A garbage collected type. Only valid with asOBJ_REF.
  asOBJ_POD | A plain-old-data type. Only valid with asOBJ_VALUE.
  asOBJ_NOHANDLE | This reference type doesn't allow handles to be held. Only value with asOBJ_REF.
  asOBJ_SCOPED | The life time of objects of this type are controlled by the scope of the variable. Only valid with asOBJ_REF.
  asOBJ_APP_CLASS | The C++ type is a class type. Only valid with asOBJ_VALUE.
  asOBJ_APP_CLASS_CONSTRUCTOR | The C++ class has an explicit constructor. Only valid with asOBJ_VALUE.
  asOBJ_APP_CLASS_DESTRUCTOR | The C++ class has an explicit destructor. Only valid with asOBJ_VALUE.
  asOBJ_APP_CLASS_ASSIGNMENT | The C++ class has an explicit assignment operator. Only valid with asOBJ_VALUE.
  asOBJ_APP_PRIMITIVE | The C++ type is a primitive type. Only valid with asOBJ_VALUE.
  asOBJ_APP_FLOAT | The C++ type is a float or double. Only valid with asOBJ_VALUE.

enum asERetCodes

Enumerator:

  asSUCCESS | Success.
  asERROR | Failure.
  asCONTEXT_ACTIVE | The context is active.
  asCONTEXT_NOT_FINISHED | The context is not finished.
  asCONTEXT_NOT_PREPARED | The context is not prepared.
  asINVALID_ARG | Invalid argument.
  asNO_FUNCTION | The function was not found.
  asNOT_SUPPORTED | Not supported.
  asINVALID_NAME | Invalid name.
  asNAME_TAKEN | The name is already taken.
  asINVALID_DECLARATION | Invalid declaration.
  asINVALID_OBJECT | Invalid object.
  asINVALID_TYPE | Invalid type.
  asALREADY_REGISTERED | Already registered.
  asMULTIPLE_FUNCTIONS | Multiple matching functions.
  asNO_MODULE | The module was not found.
  asNO_GLOBAL_VAR | The global variable was not found.
  asINVALID_CONFIGURATION | Invalid configuration.
  asINVALID_INTERFACE | Invalid interface.
  asCANT_BIND_ALL_FUNCTIONS | All imported functions couldn't be bound.
  asLOWER_ARRAY_DIMENSION_NOT_REGISTERED | The array sub type has not been registered yet.
  asWRONG_CONFIG_GROUP | Wrong configuration group.
  asCONFIG_GROUP_IS_IN_USE | The configuration group is in use.
  asILLEGAL_BEHAVIOUR_FOR_TYPE | Illegal behaviour for the type.
  asWRONG_CALLING_CONV | The specified calling convention doesn't match the function/method pointer.
  asMODULE_IS_IN_USE | The module is currently in use.
  asBUILD_IN_PROGRESS | A build is currently in progress.

enum asETokenClass

Enumerator:

  asTC_UNKNOWN | Unknown token.
  asTC_KEYWORD | Keyword token.
  asTC_VALUE | Literal value token.
  asTC_IDENTIFIER | Identifier token.
  asTC_COMMENT | Comment token.
  asTC_WHITESPACE | White space token.

## Function Documentation

AS_API asIScriptEngine* asCreateScriptEngine | ( | asDWORD | version | ) |

Parameters:

  `[in]` | version | The library version. Should always be ANGELSCRIPT_VERSION.

Returns:
  A pointer to the script engine interface.

Call this function to create a new script engine. When you're done with the script engine, i.e. after you've executed all your scripts, you should call Release on the pointer to free the engine object.

AS_API asIScriptContext* asGetActiveContext | ( |  | ) |

Returns:
  A pointer to the currently executing context, or null if no context is executing.

This function is most useful for registered functions, as it will allow them to obtain a pointer to the context that is calling the function, and through that get the engine, or custom user data.

If the script library is compiled with multithread support, this function will return the context that is currently active in the thread that is being executed. It will thus work even if there are multiple threads executing scripts at the same time.

AS_API const char* asGetLibraryOptions | ( |  | ) |

Returns:
  A null terminated string with indicators that identify the options used to compile the script library.

This can be used to identify at run-time different ways to configure the engine. For example, if the returned string contain the identifier AS_MAX_PORTABILITY then functions and methods must be registered with the asCALL_GENERIC calling convention.

AS_API const char* asGetLibraryVersion | ( |  | ) |

Returns:
  A null terminated string with the library version.

The returned string can be used for presenting the library version in a log file, or in the GUI.

AS_API int asResetGlobalMemoryFunctions | ( |  | ) |

Returns:
  A negative value on error.

Call this method to restore the default memory management functions.

AS_API int asSetGlobalMemoryFunctions | ( | asALLOCFUNC_t | allocFunc,
|  | asFREEFUNC_t | freeFunc |
| ) |  |  |

Parameters:

  `[in]` | allocFunc | The function that will be used to allocate memory.
  `[in]` | freeFunc | The function that will be used to free the memory.

Returns:
  A negative value on error.

Call this method to register the global memory allocation and deallocation functions that AngelScript should use for memory management. This function Should be called before asCreateScriptEngine.

If not called, AngelScript will use the malloc and free functions from the standard C library.

AS_API int asThreadCleanup | ( |  | ) |

Returns:
  A negative value on error.

Return values:

  | asCONTEXT_ACTIVE | A context is still active.

Call this method before terminating a thread that has accessed the engine to clean up memory allocated for that thread.

It's not necessary to call this if only a single thread accesses the engine.