Get SpatialOS

Sites

Menu
You are viewing the docs for 11.0, an old version of SpatialOS. 12.0 is the newest →

The SpatialOS Unreal integration is currently experimental. It’s usable, but definitely has some sharp edges! We’re very open to feedback - don’t hesitate to get in touch on the forums if you have any thoughts.

Querying the world

You can search the SpatialOS world for entities, using entity queries and a query language.

This is useful if you want to get information about entities, including entities outside the area of the world that your Unreal worker instance knows about. A query can return entity IDs, so you can query for entities that you want to invoke a command on, or delete.

The Unreal integration doesn’t offer wrappers and blueprint integration for entity queries at the moment: it uses the base C++ SDK. This page gives a short introduction to queries, but for a fuller reference, see the C++ worker API section on Entity queries.

Note: In order to send an entity query, a worker must have permission to do so. For more information, see the Worker permissions page.

Example: Building a query

It’s common to have a single “Spawner” entity in the world’s starting snapshot, with a single component Spawner. This entity is responsible for creating a player entity for UnrealClient workers when they connect.

To find this entity from the UnrealClient worker, you would build the following query:

const worker::query::EntityQuery& entity_query = {
    worker::query::ComponentConstraint { improbable::spawner::Spawner::ComponentId },
    worker::query::SnapshotResultType {}
};

Make sure you include the header files of any components you reference.

Sending a query

Send a query and listen for the response by directly using the Connection and View exposed by the C++ Worker SDK. The connection can be accessed from the USpatialOS object.

To send a query:

auto requestId = spatialOS->GetConnection().SendEntityQueryRequest(entity_query, 0));

Note the example code above assumes that you have access to a pointer to the USpatialOS of your project. In the RPG demo example, this object is stored in the URPGDemoGameInstance.

To listen for a response using the requestId returned by SendEntityQueryRequest():

spatialOS->GetView().OnEntityQueryResponse([this, requestId](const worker::EntityQueryResponseOp& op) {
    if (op.RequestId != requestId)
    {
        return;
    }
    if (op.StatusCode != worker::StatusCode::kSuccess)
    {
        std::string errorMessage = "Could not find spawner entity: " + op.Message;
        // output error
        return;
    }
    if (op.ResultCount == 0)
    {
        std::string errorMessage = "Query returned 0 spawner entities";
        // output error
        return;
    }
    auto spawnerEntityId = op.Result.begin()->first;
    // do something with the spawner's entity ID
});

Note the example code above assumes that you have access to a pointer to the USpatialOS of your project. In the RPG demo example, this object is stored in the URPGDemoGameInstance.

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums