The engine interface.

Public Member Functions
Memory management
virtual int	AddRef ()=0
	Increase reference counter. More...

virtual int	Release ()=0
	Decrease reference counter. More...

Engine properties
virtual int	SetEngineProperty (asEEngineProp property, asPWORD value)=0
	Dynamically change some engine properties. More...

virtual asPWORD	GetEngineProperty (asEEngineProp property)=0
	Retrieve current engine property settings. More...

Compiler messages
virtual int	SetMessageCallback (const asSFuncPtr &callback, void *obj, asDWORD callConv)=0
	Sets a message callback that will receive compiler messages. More...

virtual int	ClearMessageCallback ()=0
	Clears the registered message callback routine. More...

virtual int	WriteMessage (const char section, int row, int col, asEMsgType type, const char message)=0
	Writes a message to the message callback. More...

Global functions
virtual int	RegisterGlobalFunction (const char *declaration, const asSFuncPtr &funcPointer, asDWORD callConv)=0
	Registers a global function. More...

virtual int	GetGlobalFunctionCount ()=0
	Returns the number of registered functions. More...

virtual int	GetGlobalFunctionIdByIndex (asUINT index)=0
	Returns the function id of the registered function. More...

Global properties
virtual int	RegisterGlobalProperty (const char declaration, void pointer)=0
	Registers a global property. More...

virtual int	GetGlobalPropertyCount ()=0
	Returns the number of registered global properties. More...

virtual int	GetGlobalPropertyByIndex (asUINT index, const char *name, int typeId=0, bool isConst=0, const char configGroup=0, void *pointer=0)=0
	Returns the detail on the registered global property. More...

Object types
virtual int	RegisterObjectType (const char *obj, int byteSize, asDWORD flags)=0
	Registers a new object type. More...

virtual int	RegisterObjectProperty (const char obj, const char declaration, int byteOffset)=0
	Registers a property for the object type. More...

virtual int	RegisterObjectMethod (const char obj, const char declaration, const asSFuncPtr &funcPointer, asDWORD callConv)=0
	Registers a method for the object type. More...

virtual int	RegisterObjectBehaviour (const char obj, asEBehaviours behaviour, const char declaration, const asSFuncPtr &funcPointer, asDWORD callConv)=0
	Registers a behaviour for the object type. More...

virtual int	RegisterGlobalBehaviour (asEBehaviours behaviour, const char *declaration, const asSFuncPtr &funcPointer, asDWORD callConv)=0
	Registers a global behaviour, e.g. operators. More...

virtual int	RegisterInterface (const char *name)=0
	Registers an interface. More...

virtual int	RegisterInterfaceMethod (const char intf, const char declaration)=0
	Registers an interface method. More...

virtual int	GetObjectTypeCount ()=0
	Returns the number of registered object types. More...

virtual asIObjectType *	GetObjectTypeByIndex (asUINT index)=0
	Returns the object type interface by index. More...

virtual int	GetGlobalBehaviourCount ()=0
	Returns the number of registered global behaviours. More...

virtual int	GetGlobalBehaviourByIndex (asUINT index, asEBehaviours *outBehaviour)=0
	Returns the registered global behaviour. More...

String factory
virtual int	RegisterStringFactory (const char *datatype, const asSFuncPtr &factoryFunc, asDWORD callConv)=0
	Registers the string factory. More...

virtual int	GetStringFactoryReturnTypeId ()=0
	Returns the type id of the type that the string factory returns. More...

Enums
virtual int	RegisterEnum (const char *type)=0
	Registers an enum type. More...

virtual int	RegisterEnumValue (const char type, const char name, int value)=0
	Registers an enum value. More...

virtual int	GetEnumCount ()=0
	Returns the number of registered enum types. More...

virtual const char *	GetEnumByIndex (asUINT index, int enumTypeId, const char *configGroup=0)=0
	Returns the registered enum type. More...

virtual int	GetEnumValueCount (int enumTypeId)=0
	Returns the number of enum values for the enum type. More...

virtual const char *	GetEnumValueByIndex (int enumTypeId, asUINT index, int *outValue)=0
	Returns the name and value of the enum value for the enum type. More...

Typedefs
virtual int	RegisterTypedef (const char type, const char decl)=0
	Registers a typedef. More...

virtual int	GetTypedefCount ()=0
	Returns the number of registered typedefs. More...

virtual const char *	GetTypedefByIndex (asUINT index, int typeId, const char *configGroup=0)=0
	Returns a registered typedef. More...

Configuration groups
virtual int	BeginConfigGroup (const char *groupName)=0
	Starts a new dynamic configuration group. More...

virtual int	EndConfigGroup ()=0
	Ends the configuration group. More...

virtual int	RemoveConfigGroup (const char *groupName)=0
	Removes a previously registered configuration group. More...

virtual int	SetConfigGroupModuleAccess (const char groupName, const char module, bool hasAccess)=0
	Tell AngelScript which modules have access to which configuration groups. More...

Script modules
virtual asIScriptModule *	GetModule (const char *module, asEGMFlags flag=asGM_ONLY_IF_EXISTS)=0
	Return an interface pointer to the module. More...

virtual int	DiscardModule (const char *module)=0
	Discard a module. More...

Script functions
virtual asIScriptFunction *	GetFunctionDescriptorById (int funcId)=0
	Returns the function descriptor for the script function. More...

Type identification
virtual asIObjectType *	GetObjectTypeById (int typeId)=0
	Returns the object type interface for type. More...

virtual int	GetTypeIdByDecl (const char *decl)=0
	Returns a type id by declaration. More...

virtual const char *	GetTypeDeclaration (int typeId)=0
	Returns a type declaration. More...

virtual int	GetSizeOfPrimitiveType (int typeId)=0
	Returns the size of a primitive type. More...

Script execution
virtual asIScriptContext *	CreateContext ()=0
	Creates a new script context. More...

virtual void *	CreateScriptObject (int typeId)=0
	Creates a script object defined by its type id. More...

virtual void *	CreateScriptObjectCopy (void *obj, int typeId)=0
	Creates a copy of a script object. More...

virtual void	CopyScriptObject (void dstObj, void srcObj, int typeId)=0
	Copy one script object to another. More...

virtual void	ReleaseScriptObject (void *obj, int typeId)=0
	Release the script object pointer. More...

virtual void	AddRefScriptObject (void *obj, int typeId)=0
	Increase the reference counter for the script object. More...

virtual bool	IsHandleCompatibleWithObject (void *obj, int objTypeId, int handleTypeId)=0
	Returns true if the object referenced by a handle compatible with the specified type. More...

virtual int	CompareScriptObjects (bool &result, int behaviour, void leftObj, void rightObj, int typeId)=0
	Performs a comparison of two objects using the specified operator behaviour. More...

String interpretation
virtual asETokenClass	ParseToken (const char string, size_t stringLength=0, int tokenLength=0)=0
	Returns the class and length of the first token in the string. More...

virtual int	ExecuteString (const char module, const char script, asIScriptContext **ctx=0, asDWORD flags=0)=0
	Compiles and executes script statements within the context of a module. More...

Garbage collection
virtual int	GarbageCollect (asEGCFlags flags=asGC_FULL_CYCLE)=0
	Perform garbage collection. More...

virtual void	GetGCStatistics (asUINT currentSize, asUINT totalDestroyed=0, asUINT *totalDetected=0)=0
	Obtain statistics from the garbage collector. More...

virtual void	NotifyGarbageCollectorOfNewObject (void *obj, int typeId)=0
	Notify the garbage collector of a new object that needs to be managed. More...

virtual void	GCEnumCallback (void *reference)=0
	Used by the garbage collector to enumerate all references held by an object. More...

User data
virtual void *	SetUserData (void *data)=0
	Register the memory address of some user data. More...

virtual void *	GetUserData ()=0
	Returns the address of the previously registered user data. More...

Deprecated functions
virtual int	AddScriptSection (const char module, const char name, const char *code, size_t codeLength=0, int lineOffset=0)=0

virtual int	Build (const char *module)=0

virtual int	Discard (const char *module)=0

virtual int	ResetModule (const char *module)=0

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 asIScriptFunction *	GetFunctionDescriptorByIndex (const char *module, int index)=0

virtual int	GetGlobalVarCount (const char *module)=0

virtual int	GetGlobalVarIndexByName (const char module, const char name)=0

virtual int	GetGlobalVarIndexByDecl (const char module, const char decl)=0

virtual const char *	GetGlobalVarDeclaration (const char module, int index, int length=0)=0

virtual const char *	GetGlobalVarName (const char module, int index, int length=0)=0

virtual void *	GetAddressOfGlobalVar (const char *module, int index)=0

virtual int	GetTypeIdByDecl (const char module, const char decl)=0

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

virtual int	GetObjectsInGarbageCollectorCount ()=0

virtual int	SaveByteCode (const char module, asIBinaryStream out)=0

virtual int	LoadByteCode (const char module, asIBinaryStream in)=0

Member Function Documentation

virtual int asIScriptEngine::AddRef ( )

pure virtual

Returns: The number of references to this object.

Call this method when storing an additional reference to the object. Remember that the first reference that is received from asCreateScriptEngine is already accounted for.

virtual void asIScriptEngine::AddRefScriptObject	(	void *	obj,
		int	typeId
	)

pure virtual

Parameters

[in]	obj	A pointer to the object.
[in]	typeId	The type id of the object.

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

This only works for objects.

virtual int asIScriptEngine::AddScriptSection	(	const char *	module,
		const char *	name,
		const char *	code,
		size_t	codeLength = `0`,
		int	lineOffset = `0`
	)

pure virtual

Deprecated:: Since 2.15.0. Use asIScriptModule::AddScriptSection instead.

virtual int asIScriptEngine::BeginConfigGroup ( const char * groupName )

pure virtual

Parameters

[in] groupName The name of the configuration group

Returns: A negative value on error

Return values

asNAME_TAKEN	Another group with the same name already exists.
asNOT_SUPPORTED	Nesting configuration groups is not supported.

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.

virtual int asIScriptEngine::BindAllImportedFunctions ( const char * module )

pure virtual

Deprecated:: Since 2.15.0. Use asIScriptModule::BindAllImportedFunctions instead.

virtual int asIScriptEngine::BindImportedFunction	(	const char *	module,
		int	importIndex,
		int	funcId
	)

pure virtual

Deprecated:: Since 2.15.0. Use asIScriptModule::BindImportedFunction instead.

virtual int asIScriptEngine::Build ( const char * module )

pure virtual

Deprecated:: Since 2.15.0. Use asIScriptModule::Build instead.

virtual int asIScriptEngine::ClearMessageCallback ( )

pure virtual

Returns: A negative value on error.

Call this method to remove the message callback.

virtual int asIScriptEngine::CompareScriptObjects	(	bool &	result,
		int	behaviour,
		void *	leftObj,
		void *	rightObj,
		int	typeId
	)

pure virtual

Parameters

[out]	result	The result of the comparison
[in]	behaviour	One of the comparison behaviours from asEBehaviours.
[in]	leftObj	A pointer to the left object.
[in]	rightObj	A pointer to the right object.
[in]	typeId	The type id of the objects.

Returns: A negative value on error.

Return values

asINVALID_TYPE	The typeId must be an object type.
asINVALID_ARG	The behaviour must be one of the comparison behaviours.
asNOT_SUPPORTED	The comparison operator is not supported by this type.

This method will allow the application compare two object types without having to know the exact type of the objects being compared. The function will only work on objects, and then only on those objects that permit comparisons, i.e. registered types that have the comparison behaviours registered.

virtual void asIScriptEngine::CopyScriptObject	(	void *	dstObj,
		void *	srcObj,
		int	typeId
	)

pure virtual

Parameters

[in]	dstObj	A pointer to the destination object.
[in]	srcObj	A pointer to the source object.
[in]	typeId	The type id of the objects.

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

This only works for objects.

virtual asIScriptContext* asIScriptEngine::CreateContext ( )

pure virtual

Returns: A pointer to the new script 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.

virtual void* asIScriptEngine::CreateScriptObject ( int typeId )

pure virtual

Parameters

[in] typeId The type id of the object to create.

Returns: A pointer to the new object if successful, or null if not.

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. Reference counted objects will have their reference counter set to 1 so the application needs to release the pointer when it will no longer use it.

This only works for objects, for primitive types and object handles the method doesn't do anything and returns a null pointer.

virtual void* asIScriptEngine::CreateScriptObjectCopy	(	void *	obj,
		int	typeId
	)

pure virtual

Parameters

[in]	obj	A pointer to the source object.
[in]	typeId	The type id of the object.

Returns: A pointer to the new object if successful, or null if not.

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.

virtual int asIScriptEngine::Discard ( const char * module )

pure virtual

Deprecated:: Since 2.15.0. Use DiscardModule instead.

virtual int asIScriptEngine::DiscardModule ( const char * module )

pure virtual

Parameters

[in] module The name of the module

Returns: A negative value on error

Return values

asNO_MODULE The module was not found.

Discards a module and frees its memory. Any pointers that the application holds to this module will be invalid after this call.

virtual int asIScriptEngine::EndConfigGroup ( )

pure virtual

Returns: A negative value on error

Return values

asNOT_SUPPORTED Can't end a group that hasn't been begun.

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

virtual int asIScriptEngine::ExecuteString	(	const char *	module,
		const char *	script,
		asIScriptContext **	ctx = `0`,
		asDWORD	flags = `0`
	)

pure virtual

Parameters

[in]	module	The name of the module in which the string should be executed.
[in]	script	The script string that will be executed.
[in,out]	ctx	Either pass in your own context or receive the default context, depending on the flags parameter.
[in]	flags	A combination of the values from asEExecStrFlags.

Returns: One of asEContextState values, or a negative value on compiler error.

Return values

asINVALID_CONFIGURATION	The engine configuration is invalid.
asINVALID_ARG	ctx is null and flags is asEXECSTRING_USE_MY_CONTEXT.
asERROR	The string failed to build.
asCONTEXT_ACTIVE	The context is already active or in suspended state.
asBUILD_IN_PROGRESS	Another thread is currently building.
asEXECUTION_PREPARED	The context has been prepared and is ready for execution.
asEXECUTION_ABORTED	The execution was aborted with a call to asIScriptContext::Abort.
asEXECUTION_SUSPENDED	The execution was suspended with a call to asIScriptContext::Suspend.
asEXECUTION_FINISHED	The execution finished successfully.
asEXECUTION_EXCEPTION	The execution ended with an exception.

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

virtual int asIScriptEngine::GarbageCollect ( asEGCFlags flags = asGC_FULL_CYCLE )

pure virtual

Parameters

[in] flags Set to a combination of the asEGCFlags.

Returns: 1 if the cycle wasn't completed, 0 if it was.

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.

See Also: Garbage collection

virtual void asIScriptEngine::GCEnumCallback ( void * reference )

pure virtual

Parameters

[in] reference A pointer to the referenced object.

When processing the EnumReferences call the called object should call GCEnumCallback for each of the references it holds to other objects.

See Also: Implementing a garbage collected object

virtual void* asIScriptEngine::GetAddressOfGlobalVar	(	const char *	module,
		int	index
	)

pure virtual

Deprecated:: Since 2.15.0. Use asIScriptModule::GetAddressOfGlobalVar instead.

virtual asPWORD asIScriptEngine::GetEngineProperty ( asEEngineProp property )

pure virtual

Parameters

[in] property One of the asEEngineProp values.

Returns: The value of the property, or 0 if it is an invalid property.

Calling this method lets you determine the current value of the engine properties.

virtual const char* asIScriptEngine::GetEnumByIndex	(	asUINT	index,
		int *	enumTypeId,
		const char **	configGroup = `0`
	)

pure virtual

Parameters

[in]	index	The index of the enum type.
[out]	enumTypeId	Receives the type if of the enum type.
[out]	configGroup	Receives the config group in which the enum was registered.

Returns: The name of the registered enum type, or null on error.

virtual int asIScriptEngine::GetEnumCount ( )

pure virtual

Returns: The number of registered enum types.

virtual const char* asIScriptEngine::GetEnumValueByIndex	(	int	enumTypeId,
		asUINT	index,
		int *	outValue
	)

pure virtual

Parameters

[in]	enumTypeId	The type id of the enum type.
[in]	index	The index of the enum value.
[out]	outValue	Receives the value of the enum value.

Returns: The name of the enum value.

virtual int asIScriptEngine::GetEnumValueCount ( int enumTypeId )

pure virtual

Parameters

[in] enumTypeId The type id of the enum type.

Returns: The number of enum values for the enum type.

virtual int asIScriptEngine::GetFunctionCount ( const char * module )

pure virtual

Deprecated:: Since 2.15.0. Use asIScriptModule::GetFunctionCount instead.

virtual asIScriptFunction* asIScriptEngine::GetFunctionDescriptorById ( int funcId )

pure virtual

Parameters

[in] funcId The id of the function or method.

Returns: A pointer to the function description interface, or null if not found.

virtual asIScriptFunction* asIScriptEngine::GetFunctionDescriptorByIndex	(	const char *	module,
		int	index
	)

pure virtual

Deprecated:: Since 2.15.0. Use asIScriptModule::GetFunctionDescriptorByIndex instead.

virtual int asIScriptEngine::GetFunctionIDByDecl	(	const char *	module,
		const char *	decl
	)

pure virtual

Deprecated:: Since 2.15.0. Use asIScriptModule::GetFunctionIdByDecl instead.

virtual int asIScriptEngine::GetFunctionIDByIndex	(	const char *	module,
		int	index
	)

pure virtual

Deprecated:: Since 2.15.0. Use asIScriptModule::GetFunctionIdByIndex instead.

virtual int asIScriptEngine::GetFunctionIDByName	(	const char *	module,
		const char *	name
	)

pure virtual

Deprecated:: Since 2.15.0. Use asIScriptModule::GetFunctionIdByName instead.

virtual void asIScriptEngine::GetGCStatistics	(	asUINT *	currentSize,
		asUINT *	totalDestroyed = `0`,
		asUINT *	totalDetected = `0`
	)

pure virtual

Parameters

[out]	currentSize	The current number of objects known to the garbage collector.
[out]	totalDestroyed	The total number of objects destroyed by the garbage collector.
[out]	totalDetected	The total number of objects detected as garbage with circular references.

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 ca be freed.

See Also: Garbage collection

virtual int asIScriptEngine::GetGlobalBehaviourByIndex	(	asUINT	index,
		asEBehaviours *	outBehaviour
	)

pure virtual

Parameters

[in]	index	The index of the global behaviour.
[out]	outBehaviour	Receives the behaviour type.

Returns: The fuction id for the registered global behaviour, or a negative value on error.

Return values

asINVALID_ARG index is too large.

virtual int asIScriptEngine::GetGlobalBehaviourCount ( )

pure virtual

Returns: The number of registered global behaviours.

virtual int asIScriptEngine::GetGlobalFunctionCount ( )

pure virtual

Returns: The number of registered functions.

virtual int asIScriptEngine::GetGlobalFunctionIdByIndex ( asUINT index )

pure virtual

Parameters

[in] index The index of the registered global function.

Returns: The id of the function, or a negative value on error.

Return values

asINVALID_ARG index is too large.

virtual int asIScriptEngine::GetGlobalPropertyByIndex	(	asUINT	index,
		const char **	name,
		int *	typeId = `0`,
		bool *	isConst = `0`,
		const char **	configGroup = `0`,
		void **	pointer = `0`
	)

pure virtual

Parameters

[in]	index	The index of the global variable.
[out]	name	Receives the name of the property.
[out]	typeId	Receives the typeId of the property.
[out]	isConst	Receives the constness indicator of the property.
[out]	configGroup	Receives the config group in which the property was registered.
[out]	pointer	Receives the pointer of the property.

Returns: A negative value on error.

Return values

asINVALID_ARG index is too large.

virtual int asIScriptEngine::GetGlobalPropertyCount ( )

pure virtual

Returns: The number of registered global properties.

virtual int asIScriptEngine::GetGlobalVarCount ( const char * module )

pure virtual

Deprecated:: Since 2.15.0. Use asIScriptModule::GetGlobalVarCount instead.

virtual const char* asIScriptEngine::GetGlobalVarDeclaration	(	const char *	module,
		int	index,
		int *	length = `0`
	)

pure virtual

Deprecated:: Since 2.15.0. Use asIScriptModule::GetGlobalVarDeclaration instead.

virtual int asIScriptEngine::GetGlobalVarIndexByDecl	(	const char *	module,
		const char *	decl
	)

pure virtual

Deprecated:: Since 2.15.0. Use asIScriptModule::GetGlobalVarIndexByDecl instead.

virtual int asIScriptEngine::GetGlobalVarIndexByName	(	const char *	module,
		const char *	name
	)

pure virtual

Deprecated:: Since 2.15.0. Use asIScriptModule::GetGlobalVarIndexByName instead.

virtual const char* asIScriptEngine::GetGlobalVarName	(	const char *	module,
		int	index,
		int *	length = `0`
	)

pure virtual

Deprecated:: Since 2.15.0. Use asIScriptModule::GetGlobalVarName instead.

virtual int asIScriptEngine::GetImportedFunctionCount ( const char * module )

pure virtual

Deprecated:: Since 2.15.0. Use asIScriptModule::GetImportedFunctionCount instead.

virtual const char* asIScriptEngine::GetImportedFunctionDeclaration	(	const char *	module,
		int	importIndex,
		int *	length = `0`
	)

pure virtual

Deprecated:: Since 2.15.0. Use asIScriptModule::GetImportedFunctionDeclaration instead.

virtual int asIScriptEngine::GetImportedFunctionIndexByDecl	(	const char *	module,
		const char *	decl
	)

pure virtual

Deprecated:: Since 2.15.0. Use asIScriptModule::GetImportedFunctionIndexByDecl instead.

virtual const char* asIScriptEngine::GetImportedFunctionSourceModule	(	const char *	module,
		int	importIndex,
		int *	length = `0`
	)

pure virtual

Deprecated:: Since 2.15.0. Use asIScriptModule::GetImportedFunctionSourceModule instead.

virtual asIScriptModule* asIScriptEngine::GetModule	(	const char *	module,
		asEGMFlags	flag = `asGM_ONLY_IF_EXISTS`
	)

pure virtual

Parameters

[in]	module	The name of the module
[in]	flag	One of the asEGMFlags flags

Returns: A pointer to the module interface

Use this method to get access to the module interface, which will let you build new scripts, and enumerate functions and types in existing modules.

If asGM_ALWAYS_CREATE is informed as the flag the previous module with the same name will be discarded, thus any pointers that the engine holds to it will be invalid after the call.

virtual int asIScriptEngine::GetObjectsInGarbageCollectorCount ( )

pure virtual

Deprecated:: Since 2.15.0. Use GetGCStatistics instead.

virtual asIObjectType* asIScriptEngine::GetObjectTypeById ( int typeId )

pure virtual

Parameters

[in] typeId The type id of the type.

Returns: The object type interface for the type, or null if not found.

virtual asIObjectType* asIScriptEngine::GetObjectTypeByIndex ( asUINT index )

pure virtual

Parameters

[in] index The index of the type.

Returns: The registered object type interface for the type, or null if not found.

virtual int asIScriptEngine::GetObjectTypeCount ( )

pure virtual

Returns: The number of object types registered by the application.

virtual int asIScriptEngine::GetSizeOfPrimitiveType ( int typeId )

pure virtual

Parameters

[in] typeId The type id of the type.

Returns: The size of the type in bytes.

virtual int asIScriptEngine::GetStringFactoryReturnTypeId ( )

pure virtual

Returns: The type id of the type that the string type returns, or a negative value on error.

Return values

asNO_FUNCTION The string factory has not been registered.

virtual const char* asIScriptEngine::GetTypeDeclaration ( int typeId )

pure virtual

Parameters

[in] typeId The type id of the type.

Returns: A null terminated string with the type declaration, or null if not found.

virtual const char* asIScriptEngine::GetTypedefByIndex	(	asUINT	index,
		int *	typeId,
		const char **	configGroup = `0`
	)

pure virtual

Parameters

[in]	index	The index of the typedef.
[out]	typeId	The type that the typedef aliases.
[out]	configGroup	Receives the config group in which the type def was registered.

Returns: The name of the typedef.

virtual int asIScriptEngine::GetTypedefCount ( )

pure virtual

Returns: The number of registered typedefs.

virtual int asIScriptEngine::GetTypeIdByDecl ( const char * decl )

pure virtual

Parameters

[in] decl The declaration of the type.

Returns: A negative value on error, or the type id of the type.

Return values

asINVALID_TYPE decl is not a valid type.

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 classes, 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. The asETypeIdFlags can be used to obtain some information about the type directly from the id.

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.

This method is only able to return the type id that are not specific for a script module, i.e. built-in types and application registered types. Type ids for script declared types should be obtained through the script module's GetTypeIdByDecl.

virtual int asIScriptEngine::GetTypeIdByDecl	(	const char *	module,
		const char *	decl
	)

pure virtual

Deprecated:: Since 2.15.0. Use GetTypeIdByDecl or asIScriptModule::GetTypeIdByDecl instead.

virtual void* asIScriptEngine::GetUserData ( )

pure virtual

Returns: The pointer to the user data.

virtual bool asIScriptEngine::IsHandleCompatibleWithObject	(	void *	obj,
		int	objTypeId,
		int	handleTypeId
	)

pure virtual

Parameters

[in]	obj	A pointer to the object.
[in]	objTypeId	The type id of the object.
[in]	handleTypeId	The type id of the handle.

Returns: Returns true if the handle type is compatible with the object type.

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.

virtual int asIScriptEngine::LoadByteCode	(	const char *	module,
		asIBinaryStream *	in
	)

pure virtual

Deprecated:: Since 2.15.0. Use asIScriptModule::LoadByteCode instead.

virtual void asIScriptEngine::NotifyGarbageCollectorOfNewObject	(	void *	obj,
		int	typeId
	)

pure virtual

Parameters

[in]	obj	A pointer to the newly created object.
[in]	typeId	The type id of the object.

This method should be called when a new garbage collected object is created. The GC will then store a reference to the object so that it can automatically detect whether the object is involved in any circular references that should be released.

See Also: Implementing a garbage collected object

virtual asETokenClass asIScriptEngine::ParseToken	(	const char *	string,
		size_t	stringLength = `0`,
		int *	tokenLength = `0`
	)

pure virtual

Parameters

[in]	string	The string to parse.
[in]	stringLength	The length of the string. Can be 0 if the string is null terminated.
[out]	tokenLength	Gives the length of the identified token.

Returns: One of the asETokenClass values.

This function is useful for those applications that want to tokenize strings into tokens that the script language uses, e.g. IDEs providing syntax highlighting, or intellisense. It can also be used to parse the meta data strings that may be declared for script entities.

virtual int asIScriptEngine::RegisterEnum ( const char * type )

pure virtual

Parameters

[in] type The name of the enum type.

Returns: A negative value on error.

Return values

asINVALID_NAME	type is null.
asALREADY_REGISTERED	Another type with this name already exists.
asERROR	The type couldn't be parsed.
asINVALID_NAME	The type is not an identifier, or it is a reserved keyword.
asNAME_TAKEN	The type name is already taken.

This method registers an enum type in the engine. The enum values should then be registered with RegisterEnumValue.

virtual int asIScriptEngine::RegisterEnumValue	(	const char *	type,
		const char *	name,
		int	value
	)

pure virtual

Parameters

[in]	type	The name of the enum type.
[in]	name	The name of the enum value.
[in]	value	The integer value of the enum value.

Returns: A negative value on error.

Return values

asWRONG_CONFIG_GROUP	The enum type was registered in a different configuration group.
asINVALID_TYPE	The type is invalid.
asALREADY_REGISTERED	The name is already registered for this enum.

This method registers an enum value for a previously registered enum type.

virtual int asIScriptEngine::RegisterGlobalBehaviour	(	asEBehaviours	behaviour,
		const char *	declaration,
		const asSFuncPtr &	funcPointer,
		asDWORD	callConv
	)

pure virtual

Parameters

[in]	behaviour	The global behaviour.
[in]	declaration	The declaration of the behaviour function in script syntax.
[in]	funcPointer	The function pointer.
[in]	callConv	The calling convention for the function.

Returns: A negative value on error, or the function id if successful.

Return values

asNOT_SUPPORTED	The calling convention is not supported.
asWRONG_CALLING_CONV	The function's calling convention doesn't match callConv.
asINVALID_DECLARATION	The function declaration is invalid.
asINVALID_ARG	The behaviour is not a global behaviour.

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.

See Also: Registering a function, Type behaviours

virtual int asIScriptEngine::RegisterGlobalFunction	(	const char *	declaration,
		const asSFuncPtr &	funcPointer,
		asDWORD	callConv
	)

pure virtual

Parameters

[in]	declaration	The declaration of the global function in script syntax.
[in]	funcPointer	The function pointer.
[in]	callConv	The calling convention for the function.

Returns: A negative value on error, or the function id if successful.

Return values

asNOT_SUPPORTED	The calling convention is not supported.
asWRONG_CALLING_CONV	The function's calling convention doesn't match callConv.
asINVALID_DECLARATION	The function declaration is invalid.
asNAME_TAKEN	The function name is already used elsewhere.

This method registers system functions that the scripts may use to communicate with the host application.

See Also: Registering a function

virtual int asIScriptEngine::RegisterGlobalProperty	(	const char *	declaration,
		void *	pointer
	)

pure virtual

Parameters

[in]	declaration	The declaration of the global property in script syntax.
[in]	pointer	The address of the property that will be used to access the property value.

Returns: A negative value on error.

Return values

asINVALID_DECLARATION	The declaration has invalid syntax.
asINVALID_TYPE	The declaration is a reference.
asNAME_TAKEN	The name is already taken.

Use this method to register a global property that the scripts will be able to access as global variables. The property may optionally be registered as const, if the scripts shouldn't be allowed to modify it.

When registering the property, the application must pass the address to the actual value. The application must also make sure that this address remains valid throughout the life time of this registration, i.e. until the engine is released or the dynamic configuration group is removed.

virtual int asIScriptEngine::RegisterInterface ( const char * name )

pure virtual

Parameters

[in] name The name of the interface.

Returns: A negative value on error.

Return values

asINVALID_NAME	The name is null, or a reserved keyword.
asALREADY_REGISTERED	An object type with this name already exists.
asERROR	The name is not a proper identifier.
asNAME_TAKEN	The name is already used elsewhere.

This registers an interface that script classes can implement. By doing this the application can register functions and methods that receives an asIScriptObject and still be sure that the class implements certain methods needed by the application.

virtual int asIScriptEngine::RegisterInterfaceMethod	(	const char *	intf,
		const char *	declaration
	)

pure virtual

Parameters

[in]	intf	The name of the interface.
[in]	declaration	The method declaration.

Returns: A negative value on error.

Return values

asWRONG_CONFIG_GROUP	The interface was registered in another configuration group.
asINVALID_TYPE	intf is not an interface type.
asINVALID_DECLARATION	The declaration is invalid.
asNAME_TAKEN	The method name is already taken.

This registers a method that the class that implements the interface must have.

virtual int asIScriptEngine::RegisterObjectBehaviour	(	const char *	obj,
		asEBehaviours	behaviour,
		const char *	declaration,
		const asSFuncPtr &	funcPointer,
		asDWORD	callConv
	)

pure virtual

Parameters

[in]	obj	The name of the type.
[in]	behaviour	One of the object behaviours from asEBehaviours.
[in]	declaration	The declaration of the method in script syntax.
[in]	funcPointer	The method or function pointer.
[in]	callConv	The calling convention for the method or function.

Returns: A negative value on error, or the function id is successful.

Return values

asWRONG_CONFIG_GROUP	The object type was registered in a different configuration group.
asINVALID_ARG	obj is not set, or a global behaviour is given in behaviour.
asWRONG_CALLING_CONV	The function's calling convention isn't compatible with callConv.
asNOT_SUPPORTED	The calling convention or the behaviour signature is not supported.
asINVALID_TYPE	The obj parameter is not a valid object name.
asINVALID_DECLARATION	The declaration is invalid.
asILLEGAL_BEHAVIOUR_FOR_TYPE	The behaviour is not allowed for this type.
asALREADY_REGISTERED	The behaviour is already registered with the same signature.

Use this method to register behaviour functions that will be called by the virtual machine to perform certain operations, such as memory management, math operations, comparisons, etc.

See Also: Registering a function, Type behaviours

virtual int asIScriptEngine::RegisterObjectMethod	(	const char *	obj,
		const char *	declaration,
		const asSFuncPtr &	funcPointer,
		asDWORD	callConv
	)

pure virtual

Parameters

[in]	obj	The name of the type.
[in]	declaration	The declaration of the method in script syntax.
[in]	funcPointer	The method or function pointer.
[in]	callConv	The calling convention for the method or function.

Returns: A negative value on error, or the function id if successful.

Return values

asWRONG_CONFIG_GROUP	The object type was registered in a different configuration group.
asNOT_SUPPORTED	The calling convention is not supported.
asINVALID_TYPE	The obj parameter is not a valid object name.
asINVALID_DECLARATION	The declaration is invalid.
asNAME_TAKEN	The name conflicts with other members.
asWRONG_CALLING_CONV	The function's calling convention isn't compatible with callConv.

Use this method to register a member method for the type. The method that is registered may be an actual class method, or a global function that takes the object pointer as either the first or last parameter. Or it may be a global function implemented with the generic calling convention.

See Also: Registering a function

virtual int asIScriptEngine::RegisterObjectProperty	(	const char *	obj,
		const char *	declaration,
		int	byteOffset
	)

pure virtual

Parameters

[in]	obj	The name of the type.
[in]	declaration	The property declaration in script syntax.
[in]	byteOffset	The offset into the memory block where this property is found.

Returns: A negative value on error.

Return values

asWRONG_CONFIG_GROUP	The object type was registered in a different configuration group.
asINVALID_OBJECT	The obj does not specify an object type.
asINVALID_TYPE	The obj parameter has invalid syntax.
asINVALID_DECLARATION	The declaration is invalid.
asNAME_TAKEN	The name conflicts with other members.

Use this method to register a member property of a class. The property must be local to the object, i.e. not a global variable or a static member. The easiest way to get the offset of the property is to use the offsetof macro from stddef.h.

struct MyType {float prop;};

r = engine->RegisterObjectProperty("MyType", "float prop", offsetof(MyType, prop)));

virtual int asIScriptEngine::RegisterObjectType	(	const char *	obj,
		int	byteSize,
		asDWORD	flags
	)

pure virtual

Parameters

[in]	obj	The name of the type.
[in]	byteSize	The size of the type in bytes. Only necessary for value types.
[in]	flags	One or more of the asEObjTypeFlags.

Returns: A negative value on error.

Return values

asINVALID_ARG	The flags are invalid.
asINVALID_NAME	The name is invalid.
asALREADY_REGISTERED	Another type of the same name already exists.
asNAME_TAKEN	The name conflicts with other symbol names.
asLOWER_ARRAY_DIMENSION_NOT_REGISTERED	When registering an array type the array element must be a primitive or a registered type.
asINVALID_TYPE	The array type was not properly formed.
asNOT_SUPPORTED	The array type is not supported, or already in use preventing it from being overloaded.

Use this method to register new types that should be available to the scripts. Reference types, which have their memory managed by the application, should be registered with asOBJ_REF. Value types, which have their memory managed by the engine, should be registered with asOBJ_VALUE.

See Also: Registering an object type

virtual int asIScriptEngine::RegisterStringFactory	(	const char *	datatype,
		const asSFuncPtr &	factoryFunc,
		asDWORD	callConv
	)

pure virtual

Parameters

[in]	datatype	The datatype that the string factory returns
[in]	factoryFunc	The pointer to the factory function
[in]	callConv	The calling convention of the factory function

Returns: A negative value on error, or the function id if successful.

Return values

asNOT_SUPPORTED	The calling convention is not supported.
asWRONG_CALLING_CONV	The function's calling convention doesn't match callConv.
asINVALID_TYPE	The datatype is not a valid type.

Use this function to register a string factory that will be called when the virtual machine 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. The factory should return a value to a previously registered type that will represent the string. Example:

// Our string factory implementation
std::string StringFactory(unsigned int length, const char *s)
{
    return std::string(s);
}
// Registering the string factory
int r = engine->RegisterStringFactory("string", asFUNCTION(StringFactory), asCALL_CDECL); assert( r >= 0 );

The example assumes that the std::string type has been registered as the string type, with RegisterObjectType.

virtual int asIScriptEngine::RegisterTypedef	(	const char *	type,
		const char *	decl
	)

pure virtual

Parameters

[in]	type	The name of the new typedef
[in]	decl	The datatype that the typedef represents

Returns: A negative value on error.

Return values

asINVALID_NAME	The type is null.
asALREADY_REGISTERED	A type with the same name already exists.
asINVALID_TYPE	The decl is not a primitive type.
asINVALID_NAME	The type is not an identifier, or it is a reserved keyword.
asNAME_TAKEN	The name is already used elsewhere.

This method registers an alias for a data type.

Currently typedefs can only be registered for built-in primitive types.

virtual int asIScriptEngine::Release ( )

pure virtual

Returns: The number of references to this object.

Call this method when you will no longer use the references that you own.

virtual void asIScriptEngine::ReleaseScriptObject	(	void *	obj,
		int	typeId
	)

pure virtual

Parameters

[in]	obj	A pointer to the object.
[in]	typeId	The type id of the object.

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

This only works for objects.

virtual int asIScriptEngine::RemoveConfigGroup ( const char * groupName )

pure virtual

Parameters

[in] groupName The name of the configuration group

Returns: A negative value on error

Return values

asCONFIG_GROUP_IS_IN_USE The group is in use and cannot be removed.

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.

virtual int asIScriptEngine::ResetModule ( const char * module )

pure virtual

Deprecated:: Since 2.15.0. Use asIScriptModule::ResetGlobalVars instead.

virtual int asIScriptEngine::SaveByteCode	(	const char *	module,
		asIBinaryStream *	out
	)

pure virtual

Deprecated:: Since 2.15.0. Use asIScriptModule::SaveByteCode instead.

virtual int asIScriptEngine::SetConfigGroupModuleAccess	(	const char *	groupName,
		const char *	module,
		bool	hasAccess
	)

pure virtual

Parameters

[in]	groupName	The name of the configuration group
[in]	module	The module name
[in]	hasAccess	Whether the module has access or not to the group members

Returns: A negative value on error

Return values

asWRONG_CONFIG_GROUP No group with the groupName was found.

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.

virtual int asIScriptEngine::SetEngineProperty	(	asEEngineProp	property,
		asPWORD	value
	)

pure virtual

Parameters

[in]	property	One of the asEEngineProp values.
[in]	value	The new value of the property.

Returns: Negative value on error.

Return values

asINVALID_ARG Invalid property.

With this method you can change the way the script engine works in some regards.

virtual int asIScriptEngine::SetMessageCallback	(	const asSFuncPtr &	callback,
		void *	obj,
		asDWORD	callConv
	)

pure virtual

Parameters

[in]	callback	A function or class method pointer.
[in]	obj	The object for methods, or an optional parameter for functions.
[in]	callConv	The calling convention.

Returns: A negative value for an error.

Return values

asINVALID_ARG	One of the arguments is incorrect, e.g. obj is null for a class method.
asNOT_SUPPORTED	The arguments are not supported, e.g. asCALL_GENERIC.

This method sets the callback routine that will receive compiler messages. The callback routine can be either a class method, e.g:

void MyClass::MessageCallback(const asSMessageInfo *msg);

r = engine->SetMessageCallback(asMETHOD(MyClass,MessageCallback), &obj, asCALL_THISCALL);

or a global function, e.g:

void MessageCallback(const asSMessageInfo *msg, void *param);

r = engine->SetMessageCallback(asFUNCTION(MessageCallback), param, asCALL_CDECL);

It is recommended to register the message callback routine right after creating the engine, as some of the registration functions can provide useful information to better explain errors.

virtual void* asIScriptEngine::SetUserData ( void * data )

pure virtual

Parameters

[in] data A pointer to the user data.

Returns: The previous pointer stored in the engine.

This method allows the application to associate a value, e.g. a pointer, with the engine instance.

virtual int asIScriptEngine::UnbindAllImportedFunctions ( const char * module )

pure virtual

Deprecated:: Since 2.15.0. Use asIScriptModule::UnbindAllImportedFunctions instead.

virtual int asIScriptEngine::UnbindImportedFunction	(	const char *	module,
		int	importIndex
	)

pure virtual

Deprecated:: Since 2.15.0. Use asIScriptModule::UnbindImportedFunction instead.

virtual int asIScriptEngine::WriteMessage	(	const char *	section,
		int	row,
		int	col,
		asEMsgType	type,
		const char *	message
	)

pure virtual

Parameters

[in]	section	The name of the script section.
[in]	row	The row number.
[in]	col	The column number.
[in]	type	The message type.
[in]	message	The message text.

Returns: A negative value on error.

Return values

asINVALID_ARG The section or message is null.

This method can be used by the application to write messages to the same message callback that the script compiler uses. This is useful for example if a preprocessor is used.

Public Member Functions

Member Function Documentation