4.8.2 Attaching User Objects to CS Objects

This section explains how you can assign your own game specific data
to Crystal Space objects (i.e. like meshes and sectors). In this section
we explain how to do it from within code. In the next howto
(see section Attaching User Objects to CS Objects in a map file) we explain how you can do this from
a map file.

The Crystal Space Object System

Almost all objects in the Crystal Space engine implement the
iObject interface. Because of this you can attach your own
objects to them. This can be very useful to attach game specific
data to Crystal Space objects. For example, you may want to attach
the state of an actor to the mesh object representing that actor (like
current amount of ammunition, health, ...).

Defining Game Data

To define data that you can attach to any other Crystal Space
object (or any object implementing iObject) you also have to
create an object that implements iObject. The easiest way to do
that is to inherit from csObject which implements iObject
for you. Here is an example on how you can do this easily:

In this example you must use some SCF templates so that your
own class becomes a valid SCF object that inherits from csObject
properly.

Basically you create a class called ‘MyOwnData’ which inherits
from csObject. In that class you can do whatever you want
with respect to your own game data. In the example above we only
have a variable ‘myDataInt’ but of course you can do whatever
you want. The SCF templates make sure that you can later query for
that object (using scfQueryInterface for example).

Attaching Game Data

To attach your own data to some Crystal Space object you can use
iObject::ObjAdd(). The example below shows how you can attach
an instance of MyOwnData to a mesh:

mesh->QueryObject() is interesting. Many Crystal Space objects
that implement iObject have a convenience function called
QueryObject() which will return a reference to the iObject
implementation. This code is equivalent to:

csRef<iObject> obj = scfQueryInterface<iObject> (mesh);

with the important difference that QueryObject() does not increment
the reference count. If an object doesn't have this convenience function you
must use scfQueryInterface instead.

Finding Game Data

To find if some object has your data attached to it you can use the
following code: