5.5.4 Game-Specific Data

This section describes how to access game-specific data from the Crystal Space engine.

Support in the Crystal Space "map format"

To support game-specific data, the Crystal Space map format has been extended, thus allowing you to embed the required data directly in the map file.

You can add key / value pairs to the map file itself; both to things and sectors. To do this, just add `<key name="keyname" value="keyvalue" />' to the appropriate sections. You can use any number of keys. Because not all game-specific information can be bound to actual geometry, (like `info_deathmatchstart', for example) there is also an element called `node'.

A node looks like this:

<node name="nodeName">
	<position x="" y="" z="" />
	<key name="keyName1" value="keyValue1" />
	<key name="keyName2" value="keyValue2" />
	<key name="keyName3" value="keyValue3" />
</node>

How Does `map2cs' Support Game-Specific Data?

`map2cs' takes all key / value pairs found in the original map and attaches them to the appropriate Crystal Space object. So if you have a brush based entity, `map2cs' will store the data with the "thing" that is generated from the entity. (Every entity corresponds to exactly one "thing". If there are several sectors, the entity will be split and the appropriate "things" all get the same data.)

If you have a point based entity (lights for example), `map2cs' will generate a node in the appropriate sector, and store all data there.

If you have a manual sector, all data stored with the defining brush gets stored in the sector.

For informational purposes, `map2cs' stores the scaling factor in the Crystal Space world. (Because otherwise a game could not interpret positions.)

How Does Crystal Space Support Game-Specific Data?

`csLoader' generates an instance of `csKeyValuePair' for every key found in the map file and attaches it to the appropriate Crystal Space object by calling ObjAdd(). Each nodes generates an instance of `csMapNode', and this is added to the sector with ObjAdd() as well.

To make access to game-specific data simpler, there are some convenience classes and some convenience functions.

To get the value of a game-specific key you can call:

csKeyValuePair::GetValue(csObject* pObject, char const* key);

For example:

csSector* pSector = GetCurrentSector();
char const* gravitystr =
    csKeyValuePair::GetValue(pSector, "gravity");
int gravity = atoi(gravitystr);

Please note that these operations are pretty expensive, so you should not invoke them every frame. For frequently needed data, you should read the values once, and store them in some game-specific data fields. (But it is still okay, to read the values once in a while; for example reading a message to be printed, when the user tries to open a locked door without having first unlocked it.)

To get a specific node you can call:

csMapNode::GetNode(csSector* pSector, char const* name,
    char const* classname=0);

For example:

csSector* pSector = GetCurrentSector();
csMapNode* pNode = csMapNode::GetNode(
    pSector, "central", "cs_dynlight");
csVector3 pos = pNode->GetPosition();
CreateDynLight(...);

A more frequent case for nodes will be to iterate over all nodes in a sector (for example to place monsters or weapons).

For example:

csSector* pSector = GetCurrentSector();
csNodeIterator iter (pSector,"cs_medikit");
while (iter.HasNext ())
{
  csMapNode* pNode = iter.Next();
  csVector3 pos = pNode->GetPosition();
  CreateMedikit(pos);
}

This document was generated using texi2html 1.76.