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:
- asIScriptEngine::GetFunctionName()
- asIScriptEngine::GetFunctionDeclaration()
- asIScriptEngine::GetGlobalVarName()
- asIScriptEngine::GetGlobalVarDeclaration()
- asIScriptEngine::GetImportedFunctionDeclaration()
- asIScriptContext::GetExceptionString()
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:
- asOBJ_CLASS - This is a structure or a class. Combine this flag with the
following as needed:
- asOBJ_CLASS_CONSTRUCTOR - The default constructor is defined
- asOBJ_CLASS_DESTRUCTOR - The destructor is defined
- asOBJ_CLASS_ASSIGNMENT - The assignment operator is overloaded.
- asOBJ_PRIMITIVE - The datatype is really a primitive, except float or
double
- asOBJ_FLOAT - The datatype is really a float or a double type
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:
- asIScriptEngine::AddScriptSection()
- asIScriptEngine::Build()
- asIScriptEngine::GetFunctionCount()
- asIScriptEngine::GetFunctionIDByName()
- asIScriptEngine::GetFunctionIDByDecl()
- asIScriptEngine::ExecuteString()
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.