Setting up TagVolumes

Game-side class

You need to make a class in your game manage the initialization and destruction of the TagVolume. You may already have a class in your game that manages the lifespan of the zone or obstacle that the TagVolume is intended to represent within the Gameware Navigation World. If you do, you can use that class.

For example: [code from Tutorial_ObstacleIntegration.cpp]

class MyGameTagVolume
{
public:
    MyGameTagVolume(): m_navTagVolume(KY_NULL) {}

    void Initialize(Kaim::World* world);
    void Destroy();

    Kaim::Ptr<Kaim::TagVolume> m_navTagVolume;
    // We will keep the InitConfig too. This is not necessary, but it is convenient in case
    // we want to re-create the TagVolume with slightly different settings.
    Kaim::TagVolumeInitConfig m_navTagVolumeInitConfig;
};

Initialization

To initialize your TagVolume, you must provide an instance of the TagVolumeInitConfig configuration class, which you set up with the data needed by the TagVolume. You must set up at a minimum:

• The World the volume will be added to.
• The 2D contour and altitude range of the volume.
• The NavTag that the TagVolume will use to tag the NavMesh that intersects its volume.

For example: [code from Tutorial_ObstacleIntegration.cpp]

void MyGameTagVolume::Initialize(Kaim::World* world)
{
    // Set up the TagVolumeInitConfig
    m_navTagVolumeInitConfig.m_world = world;
    m_navTagVolumeInitConfig.m_altitudeMin = 10.0f;
    m_navTagVolumeInitConfig.m_altitudeMax = 11.0f;
    m_navTagVolumeInitConfig.m_points.PushBack(Kaim::Vec2f(-19.0967f, 7.93156f));
    m_navTagVolumeInitConfig.m_points.PushBack(Kaim::Vec2f(-15.3928f, 4.77404f));
    m_navTagVolumeInitConfig.m_points.PushBack(Kaim::Vec2f(-11.9082f, 9.46633f));
    m_navTagVolumeInitConfig.m_points.PushBack(Kaim::Vec2f(-14.6730f, 16.2140f));
    m_navTagVolumeInitConfig.m_points.PushBack(Kaim::Vec2f(-14.5526f, 10.8631f));
    m_navTagVolumeInitConfig.m_points.PushBack(Kaim::Vec2f(-18.5613f, 10.9361f));
    // This sets the NavTag as non-walkable: it will "cut a hole" in the NavMesh
    m_navTagVolumeInitConfig.m_navTag.SetAsExclusive();
    m_navTagVolumeInitConfig.m_navTag.m_blindDataArray.PushBack(0);

    // Create and initialize the TagVolume, and add it to the World
    m_navTagVolume = *KY_NEW Kaim::TagVolume;
    m_navTagVolume->Init(m_navTagVolumeInitConfig);
    m_navTagVolume->AddToWorld();
}

Updates

The TagVolume class is not intended to be updated. Once it has been created with a given contour and NavTag value, it must remain the same until its destruction.

If you need your TagVolume to represent a moving or changing zone, such as a flood that is slowly creeping over the land, you should destroy the TagVolume and re-create it with new dimensions. However, because the calculations involved in merging the volume into the NavMesh are non-trivial, you should not do this every frame, or even every few frames. Instead, consider setting a distance threshold in your code, and accepting a small amount of inaccuracy in the obstacle representation until that threshold is reached.

Destruction

To destroy the TagVolume:

• Call its TagVolume::RemoveFromWorld() method to remove it from the World.
• Set all pointers that you have saved to the object in your game to KY_NULL. This decrements the reference counting mechanism; when no references remain, the object is transparently destroyed.

For example: [code from Tutorial_ObstacleIntegration.cpp]

void MyGameTagVolume::Destroy()
{
    m_navTagVolume->RemoveFromWorld();
    m_navTagVolume = KY_NULL;
}