Registering object types

Here I intend to explain how to register an object type. What object behaviours are necessary, and how AngelScript will treat an object depending on the registered behaviours.

How should the object be handled by the script?

Four different forms:

1. Object that can be created by scripts and support object handles
2. Object that can be created by scripts but don't support object handles
3. Object that cannot be created by scripts but support object handles
4. Object that cannot be created by scripts and don't support object handles

The first kind is perhaps the ideal object type for scripting. The scripts will be able to create variables of this type and will be able to pass the objects around any way wanted, by value, or by reference, or as object handles. Because the type supports object handles the script can in many cases optimize the code to avoid unnecessary duplications.

The second kind is useful for representing small data structures, e.g. a 3D vector, that doesn't need or cannot use object handles which requires reference counting. The script compiler is limited in the ways it can optimize expressions with this kind of objects and normally it will be forced to make duplicates in order to guarantee the lifetime of each value.

It is possible to register object types that cannot be created by scripts, but can be stored as object handles. This may be useful in cases where the application needs to control how many instances of the object type that are created. Normally the application will then have functions to return object handles of this type.

The final type is mostly used for singletons that give access to application functionality. The script will not be able to declare variables of this type.

Object that can be created by scripts and support object handles

To register a type like this it is necessary to tell AngelScript the size of the object. Register the constructor, assignment operator, as well as the addref and release behaviours. The destructor behaviour is not necessary as it will never be called by the script engine. Strictly speaking the constructor and assignment operator wouldn't be necessary either, but is almost all cases these must be registered to initialize and maintain the reference counter stored in the object.

engine->RegisterObjectType("mytype", sizeof(mytype), asOBJ_CLASS_CDA);
engine->RegisterObjectBehaviour("mytype", asBEHAVE_CONSTRUCTOR, "void f()",
  asFUNCTION(mytype_construct), asCALL_CDECL_OBJLAST);
engine->RegisterObjectBehaviour("mytype", asBEHAVE_ADDREF, "void f()",
  asMETHOD(mytype, AddRef), asCALL_THISCALL);
engine->RegisterObjectBehaviour("mytype", asBEHAVE_RELEASE, "void f()",
  asMETHOD(mytype, Release), asCALL_THISCALL);
engine->RegisterObjectBehaviour("mytype", asBEHAVE_ASSIGNMENT, "mytype &f(const mytype &in)",
  asMETHOD(mytype, operator=), asCALL_THISCALL);

Object that can be created by scripts but don't support object handles

An object that don't support object handles shouldn't register the addref and release behaviours. If no special initialization for the object memory is necessary, then the constructor, destructor, nor the assignment operator are necessary. But if the C++ object for example have virtual methods, or allocate resources that must be freed upon destruction, then they are necessary.

engine->RegisterObjectType("mytype", sizeof(mytype), asOBJ_CLASS_CDA);
engine->RegisterObjectBehaviour("mytype", asBEHAVE_CONSTRUCTOR, "void f()",
  asFUNCTION(mytype_construct), asCALL_CDECL_OBJLAST);
engine->RegisterObjectBehaviour("mytype", asBEHAVE_DESTRUCTOR, "void f()",
  asFUNCTION(mytype_destruct), asCALL_CDECL_OBJLAST);
engine->RegisterObjectBehaviour("mytype", asBEHAVE_ASSIGNMENT, "mytype &f(const mytype &in)",
  asMETHOD(mytype, operator=), asCALL_THISCALL);

Object that cannot be created by scripts but support object handles

By specifying the size of the object as 0, AngelScript is prevented from declaring the variables of the type as it will not know how much memory must be allocated for each object. The addref and release behaviours must be registered so that the object handles can be used.

engine->RegisterObjectType("mytype", 0, asOBJ_CLASS_CDA);
engine->RegisterObjectBehaviour("mytype", asBEHAVE_ADDREF, "void f()",
  asMETHOD(mytype, AddRef), asCALL_THISCALL);
engine->RegisterObjectBehaviour("mytype", asBEHAVE_RELEASE, "void f()",
  asMETHOD(mytype, Release), asCALL_THISCALL);

Object that cannot be created by scripts and don't support object handles

Specifying the size of the object as 0 and not registering the addref and release behaviours makes it impossible to declare variables of the type in scripts. The application can still register global properties of this type however, which makes it ideal for registering singletons to expose common interfaces to the scripts.

engine->RegisterObjectType("mytype", 0, asOBJ_CLASS_CDA);

The object type flags

The third parameter in the RegisterObjectType() function, tells AngelScript how C++ handles the object, e.g. asOBJ_CLASS_CDA means that the C++ class has a declared constructor, destructor, and assignment operator, asOBJ_PRIMITIVE, means that the C++ type is a primitive type. It is important to define these flags correctly, because otherwise you may get difficult to understand bugs in your appliciation. Do not mistake this parameter for what behaviours should be registered with AngelScript.


Page Information

  • 2 years ago [history]
  • View page source
  • You're not logged in
  • No tags yet learn more

Wiki Information

Recent PBwiki Blog Posts