Spatial System

Every world has a spatial system. Spatial systems are responsible for sorting game objects by their position and size. They are utilized to efficiently find all objects within a volume, such as a box, a sphere or a view frustum. This is mainly used by the renderer to do frustum culling, but is also available to all other code. Obviously the spatial system needs to keep track of moving objects and update its index accordingly.

Spatial System Setup

plSpatialSystem is the base class for all spatial systems. During the construction of an plWorld, a custom implementation can be provided through the plWorldDesc. By default plSpatialSystem_RegularGrid is used, which is optimized to handle arbitrary situations with good performance.

Implementing a custom spatial system can make sense when you have a highly specialized use case. For example, if you have a strictly tile-based 2D game, where you know that all sprites are below a fixed size, and you always have a dense grid without holes, you can write a spatial system that takes advantage of this knowledge and therefore outperforms the default implementation.

However, unless you determine that the spatial system is a clear performance bottleneck, and you have domain specific knowledge that could be a big advantage to speed things up, there is no reason to consider writing your own.

Since there is exactly one spatial system per world, it usually means that the choice of a system is made for a type of game. In theory, though, one could use different systems for different types of levels, as well.

Accessing the Spatial System

In C++ code you get access to the world's spatial system through plWorld::GetSpatialSystem().

When using other languages bindings the spatial system may not be exposed directly. For example, when using TypeScript, the most useful functions are exposed directly through pl.World, for example pl.World.FindObjectsInBox() and pl.World.FindObjectsInSphere().

Spatial Data Categories

Every piece of spatial data is associated with a category. For example, rendering data is either in the category "RenderStatic" or "RenderDynamic". This is mainly used to separate spatial information into distinct groups, so that during a spatial query, data that is irrelevant can be filtered out quickly.

For efficiency reasons, categories are represented with bitmasks internally, which is why there can only be up to 32 categories. You should assume that the core engine uses at least 5 categories already.

Configuring Spatial Data Categories

In C++ code you register a spatial data category through plSpatialData::RegisterCategory(). This will return a category object which can be used for spatial queries later:

plSpatialData::Category RtsSelectableComponent::s_SelectableCategory = plSpatialData::RegisterCategory("Selectable", plSpatialData::Flags::None);

When using the editor, there are components, such as the marker component, which allow you to select a category from a predefined list. This list is project specific. When you click on such a dropdown box, the last entry allows you to open an editor to configure the available categories

The Invalid Category

Some components 'add' their bounds to a plMsgUpdateLocalBounds using plInvalidSpatialDataCategory. This means that they want to specify their bounds, but do not want to add anything to the spatial system. This is useful for components that do have a perceived size, such as physics shapes, which should be visible when selecting these objects in the editor, but where there is no benefit of inserting this into the spatial system.

Exposing Game Objects to the Spatial System

The spatial system only knows about game objects, it does not differentiate by components. However, which game objects are inserted into it and under which categories, is handled by components.

The world sends the message plMsgUpdateLocalBounds to all components when it determines that an update is necessary. This can also be triggered manually by calling plGameObject::UpdateLocalBounds() when spatial data, such as which category to use, has been modified.

Components can handle this message and add spatial information to it. For 3D objects one would use something like the bounding sphere of a mesh, but it is also possible to use more abstract spatial data.

void RtsSelectableComponent::OnUpdateLocalBounds(plMsgUpdateLocalBounds& msg)
{
  plBoundingBoxSphere bounds;
  bounds.m_fSphereRadius = m_fSelectionRadius;
  bounds.m_vCenter.SetZero();
  bounds.m_vBoxHalfExtends.Set(m_fSelectionRadius);

  msg.AddBounds(bounds, s_SelectableCategory);
}

Don't forget to register the message handler in the reflection block:

PL_BEGIN_MESSAGEHANDLERS
{
  PL_MESSAGE_HANDLER(plMsgUpdateLocalBounds, OnUpdateLocalBounds)
}
PL_END_MESSAGEHANDLERS;

Querying the Spatial System

Once you have spatial data inserted into the system, you can use it to efficiently query for objects within a volume.

When calling functions such as plSpatialSystem::FindObjectsInSphere() you have to provide a bitmask of categories. That's because you can request to get objects from multiple categories at the same time. You can get this bitmask by calling plSpatialData::Category::GetBitmask() on a category object.

void RtsGameState::InspectObjectsInArea(const plVec2& position, float radius, plSpatialSystem::QueryCallback callback) const
{
  plBoundingSphere sphere(position.GetAsVec3(0), radius);
  plSpatialSystem::QueryParams queryParams;
  queryParams.m_uiCategoryBitmask = RtsSelectableComponent::s_SelectableCategory.GetBitmask();
  m_pMainWorld->GetSpatialSystem()->FindObjectsInSphere(sphere, queryParams, callback);
}

In other language bindings you may instead need to pass in a list of all the desired categories by name.

Spatial System vs. Physics Engines

Both the spatial system, as well as physics engines allow you to do spatial queries. There are cases where a problem can be solved using either system, but generally they are meant to complement each other.

If you want to query for things that already need to have a physical representation, and therefore will be handled by the physics engine anyway, it is best to leverage the physics engine to query for such objects. For example a shockwave effect that is supposed to push objects away, only makes sense to be applied to physically simulated objects. Therefore, querying which objects are close-by, to figure out what objects to apply the effect to, should be done through the physics engine, and there is no reason to even have information about these objects in the spatial system.

On the other hand, things like the RtsSelectableComponent (see above) could be achieved by setting up fake physics actors so that they can be found with physics queries. The performance cost for doing so would be unnecessary high though, as the physics engine would perform additional maintenance that is ultimately not needed, and it may waste precious resources such as collision layers. Here, using the spatial system makes much more sense.

Spatial System vs. Tags

The spatial data categories are very similar to tags. The difference is, that tags are set up on game objects and they don't have any spatial quality. A game object can have many tags, but not be registered spatially and therefore cannot be found through spatial queries. On the other hand, because of this, tags have nearly no performance overhead, whereas spatial data must be updated whenever an object moves.

Ultimately, both systems can be used to solve many of the same problems. When you need to be able to inspect an area and find all objects of a certain kind, you should use spatial data, for example through a marker component. If, however, you need to semtantically label objects, but do not require to find them spatially, prefer tags to not waste performance.

2.0 Help