Upgrade instructions for AngelScript

2004/11/12, Andreas Jönsson

This article will help you upgrading your existing application to use the latest version of AngelScript. It will explain the necessary steps needed to make the application work, though not necessarily to take advantage of the new features.

Version 1.9.x to 1.10.x

Application interface

asIScriptEngine::RegisterObjectBehaviour() can now only register object behaviours, i.e. those behaviours that require an object type. The behaviours that were registered with datatype = 0 should now be registered with RegisterGlobalBehaviour().

NOTE: Define AS_DEPRECATED for backwards compatibility.
Methods that are used to obtain a string from the engine have changed. Instead of passing a buffer to the methods, they now use an internal buffer and then return a pointer to that one. The internal buffer is shared between all of them so the returned pointer shouldn't be stored for later use. Affected methods are: NOTE: Define AS_DEPRECATED for backwards compatibility. asIScriptEngine::ExecuteString() has been altered to take one more parameter receives the pointer to the context used for the execution. The new parameter was inserted before the last parameter, and can be set to 0.

NOTE: Define AS_DEPRECATED for backwards compatibility.
asIScriptEngine::GetContextForExecuteString() is deprecated and should no longer be used. If you need the context you should pass a pointer to a variable to ExecuteString(). ExecuteString() will then return the context in that variable.

NOTE: Define AS_DEPRECATED for backwards compatibility.

Project files

as_compiler_expression.cpp was merged into as_compiler.cpp. as_thread.h and as_thread.cpp were created to add support for multithreading. as_context_x86.cpp was created to add an x86 assembler optimized VM. as_arrayobject.h and as_arrayobject.cpp were created to add support for native arrays. as_debug.h was added to the code to hold code used for debugging reasons. as_typeinfo.h and as_typeinfo.cpp were added to the project.

Version 1.8.x to 1.9.x

Application interface

The asIScriptEngine::RegisterTypeBehaviour() method was renamed to RegisterObjectBehaviour(). This was done to make the method names more consistent. The flags asCALL_RETURNBYVAL and asCALL_RETURNBYREF are no longer defined and should be removed completely. The flags asOBJ_IS_COMPLEX and asOBJ_IS_NOT_COMPLEX for asIScriptEngine::RegisterObjectType() should not be used any more. They should be replaced with one of the following flags: This was done because of how different compilers handles return of various types. The identification of the real C++ was necessary to make the library portable between compilers and platforms. The compiler messages have changed to use a more standardized format so if your application depended on the format returned you'll need to update your code. The methods asIScriptContext::Prepare() and asIScriptEngine::ExecuteString() no longer take the stack size argument. The engine has been changed so that the stack dynamically grows as needed which eliminates the need to set a hardcoded limit. If you still want to control the size of the stack, then you can do so through the new method asIScriptEngine::SetDefaultContextStackSize(). The define AS_CALL was removed from the interface. Simply do a search and remove all use of this define. This also changes the exported symbol names for the global functions. Where they previously followed the naming convention for stdcall, they now use the cdecl naming convention. asIScriptEngine::GetModuleID() no longer exists. You could instead use the new method asIScriptEngine::GetModuleIndex() and shift the value 16 bits to the left. If you were using it for enumerating functions you can now use the new method asIScriptEngine::GetFunctionIDByIndex() instead. asIScriptEngine::AddScriptSection() now takes an extra parameter to allow adjustment of the line numbers in compiler and exception messages. Simply add 0 as a last argument to the call.

Project files

as_restore.cpp and as_restore.h was added to the library project. The source files ac_string.cpp, ac_string.h, and ac_array.h were renamed to as_string.cpp, as_string.h and as_array.h respectively.

Version 1.7.x to 1.8.x

Application interface

asIScriptEngine::RegisterGlobalProperty() and asIScriptEngine::RegisterObjectProperty() no longer take the flags parameter. If the property should be read only, add const to the declaration. The bstr type was removed from the library to allow the application to use other string objects. The old bstr type can be registered externally using the new asIScriptEngine::RegisterScriptFactory() method. There is an add-on code available that does all this for you with a simple call to a function. The functions asBStrAlloc(), asBStrFree(), and asBStrLength() are no longer exported by the library. The asMETHOD() macro has been improved. It now takes two arguments, the class name and the method name, instead of both of them together. Where you previously wrote asMETHOD(CMyClass::Method) you should now write asMETHOD(CMyClass, Method). There are also variants of macro available that help in registering overloaded methods and functions. The internal script functions @init() and @exit() are no longer reported by asIScriptEngine::GetFunctionCount(), asIScriptEngine::GetFunctionDeclaration(), etc. These where previously reported as the first two functions when enumerating the script functions. If you were doing something to skip these you'll have to revise that code. asIScriptEngine::RegisterObjectType() should now use the flags asOBJ_IS_COMPLEX, and asOBJ_IS_NOT_COMPLEX.

NOTE: These flags were replaced with another set of flags for version 1.9.x.
With version 1.8.0 the support for separate modules was added, which meant that many functions needed an extra parameter for naming the module. The simplest upgrade is to add the argument 0 first to all calls to the following methods:

Script language

There is no longer a standard string type for the language. The application is allowed to register the string type as it desires. There is existing code for registering the bstr type for backwards compatibility.

Project files

A new source module was added to the project. You'll need to add as_module.cpp and as_module.h to you compilation. The source module as_callfunc.cpp was renamed to as_callfunc_x86.cpp. The files were changed to include angelscript.h from the include directory instead of from the source directory.

Version 1.6.x to 1.7.x

Application interface

The method asIScriptEngine::RegisterObjectType() now accepts the flags asCALL_RETURNBYREF and asCALL_RETURNBYVAL, which makes it unnecessary to pass these flags to the the various methods for registering functions and methods.

NOTE: These flags have changed again in version 1.8.x and 1.9.x.
The method asIScriptEngine::ExecuteStep() now takes a flag that can be used to control the execution even further. You can set it to 0 to maintain the same behaviour as before.

Script language

The bstr.length property has become a method in order to better conform with the rest of the library.

NOTE: In version 1.8.x you can register own string type.

Earlier versions

Let me know if you need this information and I'll provide it for you.