Creating and deleting entities
Using the worker::Connection
,
a worker can request SpatialOS to:
- reserve one entity ID, using
SendReserveEntityIdRequest
- reserve a range of entity IDs, using
SendReserveEntityIdsRequest
- create an entity, using
SendCreateEntityRequest
- delete an entity, using
SendDeleteEntityRequest
For all of these methods:
- They return an
worker::RequestId
request ID. This can be used to match a request with its response. The type parameterC
depends on the type of request being sent. - The request can fail, so check the
StatusCode
in theOp
in the callback, and retry as necessary. The caller will always get a response callback, but it might be due to a timeout.
Reserve an entity ID
Reserve one entity ID using the Connection
method
SendReserveEntityIdRequest
.
SendReserveEntityIdRequest
takes an optional timeout.
You’ll receive the response via the
Dispatcher
callback
OnReserveEntityIdResponse
.
If the operation succeeds, the response contains an entity ID, which is guaranteed to be unused
in the current deployment.
The Op
in the callback is
ReserveEntityIdResponseOp
.
Reserve a range of entity IDs
Reserve a range of entity IDs using the Connection
method
SendReserveEntityIdsRequest
.
SendReserveEntityIdsRequest
takes an optional timeout.
You’ll receive the response via the
Dispatcher
callback
OnReserveEntityIdsResponse
.
If the operation succeeds, the response contains an entity ID, which is the first in a contiguous range
guaranteed to be unused in the current deployment, and the corresponding number of entity IDs in the
reserved range.
If the operation fails, the entity ID is not set, and the number of entity IDs in the reserved range is 0.
The Op
in the callback is
ReserveEntityIdsResponseOp
.
Create an entity
Create an entity using the Connection
method
SendCreateEntityRequest
, which takes:
- a
worker::Entity
representing the initial state of the entity - an optional entity ID
(which, if provided, must have been obtained by a previous call to
SendReserveEntityIdRequest
orSendReserveEntityIdsRequest
) - an optional timeout
You’ll receive the response via the
Dispatcher
callback
OnCreateEntityResponse
.
If the operation succeeds, the response contains the ID of the newly created entity.
Delete an entity
Delete an entity using the Connection
method
SendDeleteEntityRequest
,
which takes:
- an entity ID
- an optional timeout
You’ll receive the response via the
Dispatcher
callback
OnDeleteEntityResponse
.
The response contains no additional data.
Example
Here’s an example of reserving an entity ID, creating an entity with that ID and some initial state, and finally deleting it:
void CreateDeleteEntity(worker::Connection& connection, worker::Dispatcher& dispatcher) {
constexpr uint32_t kTimeoutMillis = 500;
// Reserve an entity ID.
worker::RequestId<worker::ReserveEntityIdRequest> entity_id_reservation_request_id =
connection.SendReserveEntityIdRequest(kTimeoutMillis);
// When the reservation succeeds, create an entity with the reserved ID.
worker::RequestId<worker::CreateEntityRequest> entity_creation_request_id;
dispatcher.OnReserveEntityIdResponse([&](const worker::ReserveEntityIdResponseOp& op) {
if (op.RequestId == entity_id_reservation_request_id &&
op.StatusCode == worker::StatusCode::kSuccess) {
// ID reservation was successful - create an entity with the reserved ID.
worker::Entity entity;
entity.Add<improbable::Position>({{1, 2, 3}});
entity_creation_request_id =
connection.SendCreateEntityRequest(entity, op.EntityId, kTimeoutMillis);
}
});
// When the creation succeeds, delete the entity.
worker::RequestId<worker::DeleteEntityRequest> entity_deletion_request_id;
dispatcher.OnCreateEntityResponse([&](const worker::CreateEntityResponseOp& op) {
if (op.RequestId == entity_creation_request_id &&
op.StatusCode == worker::StatusCode::kSuccess) {
entity_deletion_request_id = connection.SendDeleteEntityRequest(*op.EntityId, kTimeoutMillis);
}
});
// When the deletion succeeds, we're done.
dispatcher.OnDeleteEntityResponse([&](const worker::DeleteEntityResponseOp& op) {
if (op.RequestId == entity_deletion_request_id &&
op.StatusCode == worker::StatusCode::kSuccess) {
// Test successful!
}
});
}
Entity ACLs
Entity ACLs are exposed to the worker as a component, and can be manipulated as any other component. It’s worth reading Understanding authority and Worker attributes and worker requirements for more information.
ACLs are set at entity creation time, but can be modified
dynamically at runtime by the worker that has authority over the
EntityAcl
component.
Example of creating an ACL
This example adds an EntityAcl
to an Entity
given a
CommandRequestOp
, which is currently the only
way to make a specific worker (as opposed to, potentially, a set of workers) to qualify for authority of
a component. Specifically:
- The entity will be visible to workers that have the “client” or “physics” worker attribute.
- Any worker with “physics” as one of its attributes can have authority over the
entity’s
Position
andEntityAcl
components. - The worker, which issued the
CommandRequestOp
, is the only worker that can be authoritative over thePlayerControls
component.
This can be used as part of creating a new entity in response to a command request.
template <typename C>
void AddComponentDelegations(const worker::CommandRequestOp<C>& op, worker::Entity& entity) {
static const std::string physics = "physics";
static const std::string client = "client";
// This requirement set matches only the command caller, i.e. the worker that issued the command,
// since attribute set includes the caller's unique attribute.
auto callerWorkerAttributeSet = improbable::WorkerAttributeSet{op.CallerAttributeSet};
auto callerWorkerRequirementSet = improbable::WorkerRequirementSet{
worker::List<improbable::WorkerAttributeSet>{callerWorkerAttributeSet}};
auto physicsWorkerAttributeSet = worker::List<std::string>{physics};
// This requirement set matches any worker with the attribute "physics".
auto physicsWorkerRequirementSet = improbable::WorkerRequirementSet{
worker::List<improbable::WorkerAttributeSet>{{physicsWorkerAttributeSet}}};
// This requirement set matches any worker with the attribute "client" or "physics".
auto clientOrPhysicsRequirementSet =
improbable::WorkerRequirementSet{worker::List<improbable::WorkerAttributeSet>{
improbable::WorkerAttributeSet{worker::List<std::string>{client}},
physicsWorkerAttributeSet}};
// Give authority over Position and EntityAcl to any physics worker, and over PlayerControls to
// the caller worker.
worker::Map<worker::ComponentId, improbable::WorkerRequirementSet> componentAcl{
{improbable::Position::ComponentId, physicsWorkerRequirementSet},
{EntityAcl::ComponentId, physicsWorkerRequirementSet},
{example::PlayerControls::ComponentId, callerWorkerRequirementSet}};
entity.Add<EntityAcl>(
EntityAcl::Data{/* read */ clientOrPhysicsRequirementSet, /* write */ componentAcl});
}
Example of changing authority
The worker authoritative over the
EntityAcl
component can decide to
give the authority over position (or any other component) to a different worker.
In order to do this, you need to modify EntityAcl.Data
, mapping Position.ComponentId
to
callerWorkerRequirementSet
(created above). This change can be made using the method below:
// Take a copy of the EntityAclData argument, so that this method doesn't modify the original one.
improbable::EntityAclData
DelegateComponent(improbable::EntityAclData acl, worker::ComponentId componentId,
const improbable::WorkerRequirementSet& requirementSet) {
// Set the write ACL for the specified component to the specified attribute set,
// assuming the componentAcl option is not empty.
acl.component_write_acl().insert({{componentId, requirementSet}});
return acl;
}
For these changes to take effect, the worker authoritative over the
EntityAcl
component needs send the changes
through a component update.