World commands

Note: This document relates to the MonoBehaviour workflow.

Before reading this document, make sure you are familiar with:


How to send and receive world commands

We provide the following type for sending and receiving world commands:

Note: We do not provide a WorldCommandReceiver as the SpatialOS Runtime directly handles the command.

The WorldCommandSender can be injected without any condition. A MonoBehaviour that requires only this will be enabled as soon as the associated GameObject is created.

If you would like to see how you can use these world commands to create or delete entities, we recommend you to read the how to create and delete SpatialOS entities document.

Reserve an entity ID

A worker can reserve an entity ID before sending the CreateEntity command request. Depending on the command response, you should do the following:

  • The command succeeded: The entity got successfully created.
  • The command timed out or another error appeared: retry the command.

You can use the WorldCommandSender.SendReserveEntityIdsCommand method to send a command request to reserve entity ids. It has the following signature:

void SendReserveEntityIdsCommand(WorldCommands.ReserveEntityIds.Request request, Action<WorldCommands.ReserveEntityIds.ReceivedResponse> callback = null);

Parameters:

  • WorldCommands.ReserveEntityIds.Request request: The command request payload.
  • Action<WorldCommands.ReserveEntityIds.ReceivedResponse> callback: Optional. A callback that will be called when the command response is received.

Create an entity

You can use the WorldCommandSender.SendCreateEntityCommand method to request the creation of a new SpatialOS entity. It has the following signature:

void SendCreateEntityCommand(WorldCommands.CreateEntity.Request request, Action<WorldCommands.CreateEntity.ReceivedResponse> callback = null);

Parameters:

  • WorldCommands.CreateEntity.Request request: The command request payload.
  • Action<WorldCommands.CreateEntity.ReceivedResponse> callback: Optional. A callback that will be called when the command response is received.

Delete an entity

You can use the SendDeleteEntityCommand method to request the deletion of a SpatialOS entity given its SpatialOS entity ID. It has the following signature:

void SendDeleteEntityCommand(WorldCommands.DeleteEntity.Request request, Action<WorldCommands.DeleteEntity.ReceivedResponse> callback = null)

Parameters:

  • WorldCommands.DeleteEntity.Request request: The command request payload.
  • Action<WorldCommands.DeleteEntity.ReceivedResponse> callback: Optional. A callback that will be called when the command response is received.

Tip

Do not manually delete GameObjects representing entities after sending a DeleteEntity command. You should wait until you receive a callback on the IEntityGameObjectCreator instance.

Entity query

You can use the SendEntityQueryCommand method to request information about the entities through an entity query. It has the following signature:

void SendEntityQueryCommand(WorldCommands.EntityQuery.Request request, Action<WorldCommands.EntityQuery.ReceivedResponse> callback = null)

Parameters:

  • WorldCommands.EntityQuery.Request request: The command request payload.
  • Action<WorldCommands.EntityQuery.ReceivedResponse> callback: Optional. A callback that will be called when the command response is received.

For example, if you wished to query for a specific entity based on its entity ID and return all the components on that entity:

worldCommandSender.SendEntityQueryCommand(
    new WorldCommands.EntityQuery.Request(
        new EntityQuery
        {
            Constraint = new EntityIdConstraint(entityId.Id),
            ResultType = new SnapshotResultType()
        }), Callback);

Where Callback has the following signature:

void Callback(WorldCommands.EntityQuery.ReceivedResponse response)

Updated about a year ago


World commands


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.