C++ API reference documentation
Table of contents
- worker namespace
- worker::ApiVersion function
- worker::ApiVersionStr function
- worker::ForComponent function
- worker::ForEachComponent function
- worker::LoadSnapshot function
- worker::SaveSnapshot function
- worker::AddComponentOp struct
- worker::AddEntityOp struct
- worker::Authority enum
- worker::AuthorityChangeOp struct
- worker::CommandParameters struct
- worker::CommandRequestOp struct
- worker::CommandResponseOp struct
- worker::ComponentRegistry class
- worker::ComponentUpdateLoopback enum
- worker::ComponentUpdateOp struct
- worker::Components class
- worker::Connection class
- worker::ConnectionParameters struct
- worker::ConnectionStatus struct
- worker::ConnectionStatusCode enum
- worker::CreateEntityRequest struct
- worker::CreateEntityResponseOp struct
- worker::CriticalSectionOp struct
- worker::Defaults class
- worker::DeleteEntityRequest struct
- worker::DeleteEntityResponseOp struct
- worker::Deployment struct
- worker::DeploymentList struct
- worker::DisconnectOp struct
- worker::Dispatcher class
- worker::Entity class
- worker::EntityQueryRequest struct
- worker::EntityQueryResponseOp struct
- worker::ErasureCodecParameters struct
- worker::FlagUpdateOp struct
- worker::Future class
- worker::HeartbeatParameters struct
- worker::HistogramMetric class
- worker::IncomingCommandRequest struct
- worker::InterestOverride struct
- worker::KcpNetworkParameters struct
- worker::List class
- worker::Locator class
- worker::LocatorCredentialsType enum
- worker::LocatorParameters struct
- worker::LogLevel enum
- worker::LogMessageOp struct
- worker::LoginTokenCredentials struct
- worker::Map class
- worker::Metrics class
- worker::MetricsOp struct
- worker::NetworkConnectionType enum
- worker::NetworkParameters struct
- worker::OpList class
- worker::Option class
- worker::OutgoingCommandRequest struct
- worker::ProtocolLoggingParameters struct
- worker::QueueStatus struct
- worker::RakNetNetworkParameters struct
- worker::RemoveComponentOp struct
- worker::RemoveEntityOp struct
- worker::RequestId struct
- worker::ReserveEntityIdRequest struct
- worker::ReserveEntityIdResponseOp struct
- worker::ReserveEntityIdsRequest struct
- worker::ReserveEntityIdsResponseOp struct
- worker::SnapshotInputStream class
- worker::SnapshotOutputStream class
- worker::StatusCode enum
- worker::SteamCredentials struct
- worker::TcpNetworkParameters struct
- worker::ThreadAffinityParameters struct
- worker::UpdateParameters struct
- worker::Variant class
- worker::View class
- worker::alpha namespace
- worker::alpha::CreateDevelopmentLoginTokensAsync function
- worker::alpha::CreateDevelopmentPlayerIdentityTokenAsync function
- worker::alpha::Locator class
- worker::alpha::LocatorParameters struct
- worker::alpha::LoginTokenDetails class
- worker::alpha::LoginTokensRequest class
- worker::alpha::LoginTokensResponse struct
- worker::alpha::PlayerIdentityCredentials struct
- worker::alpha::PlayerIdentityTokenRequest struct
- worker::alpha::PlayerIdentityTokenResponse struct
- worker::query namespace
- worker::query::AndConstraint struct
- worker::query::ComponentConstraint struct
- worker::query::CountResultType struct
- worker::query::EntityIdConstraint struct
- worker::query::EntityQuery struct
- worker::query::NotConstraint struct
- worker::query::OrConstraint struct
- worker::query::SnapshotResultType struct
- worker::query::SphereConstraint struct
worker
namespace
Nested namespaces | worker::alpha, worker::query |
Type aliases
using EntityId = std::int64_t;
using ComponentId = std::uint32_t;
Functions
ApiVersion
std::uint32_t ApiVersion();
Description: Returns the worker API version that was defined when the underlying native library was compiled.
Returns:std::uint32_t
- ApiVersionStr
std::string ApiVersionStr();
Description: Returns the worker API version string that was defined when the underlying native library was compiled.
Returns:std::string
ForComponent<typename… Args, typename Handler>
template<typename... Args, typename Handler> void ForComponent(const Components<T...>& components, ComponentId component_id, Handler&& handler);
Description: Invokes
Accept<T>()
on the provided handler for the component in the given list of components whose ID matches the given component ID.
Type parameters:typename... Args
typename Handler
Parameters:
const Components<T...>&
components
ComponentId
component_id
Handler&& handler
Returns:
void
- ForEachComponent<typename… Args, typename Handler>
template<typename... Args, typename Handler> void ForEachComponent(const Components<T...>& components, Handler&& handler);
Description: Invokes
Accept<T>()
on the provided handler for each component in the given list of components.
Type parameters:typename... Args
typename Handler
Parameters:
const Components<T...>&
components
Handler&& handler
Returns:
void
LoadSnapshot
Option<std::string> LoadSnapshot(const ComponentRegistry& registry, const std::string& path, std::unordered_map<EntityId, Entity>& entities_output);
Description: Load a snapshot from a file.
Remarks: This function is DEPRECATED; use SnapshotInputStream instead.
Parameters:const ComponentRegistry&
registry
const std::string& path
std::unordered_map<EntityId, Entity>& entities_output
Returns:
Option<std::string>
- Returns an error message if an error occurred.- SaveSnapshot
Option<std::string> SaveSnapshot(const ComponentRegistry& registry, const std::string& path, const std::unordered_map<EntityId, Entity>& entities);
Description: Saves a snapshot to a file.
Remarks: This function is DEPRECATED; use SnapshotOutputStream instead.
Parameters:const ComponentRegistry&
registry
const std::string& path
const std::unordered_map<EntityId, Entity>& entities
Returns:
Option<std::string>
- Returns an error message if an error occurred.
worker::AddComponentOp<typename T> struct
Summary | Data for an operation that indicates a component has been added to an existing entity in the worker’s view of the simulation. |
Type parameters
typename T
- A generated component metaclass.
Fields
EntityId
EntityId
worker::AddEntityOp struct
Summary | Data for an operation that indicates an entity has been added to the worker’s view of the simulation. |
Fields
EntityId
EntityId
- The ID of the entity that was added to the worker’s view of the simulation.
worker::Authority enum
Summary | Enumerates the possible states of an AuthorityChangeOp. kAuthoritative and kNotAuthoritative are used to indicate the worker has gained or lost authority (respectively) over a particular component for an entity. kAuthorityLossImminent is only used when the component has an authority handover timeout set, and indicates the worker will soon lose authority soon over a particular component for an entity. In this case, the worker may save any transient state by sending a final update for the component, and call SendAuthorityLossImminentAcknowledgement to proceed with authority handover. Note that this should only be used for optimization purposes, and workers must still be able to recover in case the final update is not successful. In general, there is no guarantee that a worker will receive the authority loss imminent notification in time to send a final update. |
Fields
worker::AuthorityChangeOp struct
Summary | Data for an operation that indicates the worker’s authority over a component for an entity has been changed. |
Fields
worker::CommandParameters struct
Summary | Command parameters. Used to modify the behaviour of a command request. |
Fields
bool AllowShortCircuit
- Allow command requests to bypass the bridge when this worker is authoritative over the target entity-component.
worker::CommandRequestOp<typename T> struct
Summary | Data for an operation that indicates a command request has been received for a component on an entity over which this worker has authority. |
Remarks | The worker should respond to the command by calling SendCommandResponse with the given request ID. |
Type parameters
typename T
- A generated command metaclass.
Fields
List<std::string>
CallerAttributeSet
- The attribute set of the worker that initiated this request.std::string CallerWorkerId
- The ID of the worker that initiated this request.EntityId
EntityId
- The ID of the target entity of this request.RequestId<IncomingCommandRequest<T>>
RequestId
- The incoming request ID.
Should be passed to SendCommandResponse in order to respond to this request.std::uint32_t TimeoutMillis
- An upper bound on the timeout of this request. Any response sent after the timeout has expired will be ignored by the SDK.
worker::CommandResponseOp<typename T> struct
Summary | Data for an operation that indicates a command response has been received for a request previously issued by this worker. |
Remarks | The request ID will match a previous call to SendCommandRequest. |
Type parameters
typename T
- A generated command metaclass.
Fields
EntityId
EntityId
- The target entity ID of the original request.std::string Message
- A description of the status. Will contain the reason for failure if unsuccessful.RequestId<OutgoingCommandRequest<T>>
RequestId
- The outgoing request ID for which there was a reponse.
Matches the request ID returned by a previous call to SendCommandRequest.Option<const typename T::Response&>
Response
- The command response data. Present exactly when the status code is kSuccess.StatusCode
StatusCode
- The status code of the command response.
worker::ComponentRegistry class
Summary | A type-erased registry of components. |
worker::ComponentUpdateLoopback enum
Summary | Component update loopback describes how the component update is delivered to the worker sending the update, if at all. |
Fields
ComponentUpdateLoopback
kNone
- The update is not delivered to the worker sending the update.ComponentUpdateLoopback
kShortCircuited
- The update is locally added to the op list of, and therefore received by, the worker sending the update.
worker::ComponentUpdateOp<typename T> struct
Summary | Data for an operation that indicates the component for an entity has been updated. |
Type parameters
typename T
- A generated component metaclass.
Fields
EntityId
EntityId
const typename T::Update& Update
worker::Components<typename… Args> class
Inherits from | ComponentRegistry |
Summary | A compile-time static list of components. |
Type parameters
typename... Args
Constructors
Components() = default;
worker::Connection class
Summary | Worker Connection API. This is the main way of connecting to SpatialOS, processing operations, sending component updates etc. |
Remarks | This object should not be used concurrently by multiple threads. |
Constructors
Connection(const Connection&) = delete;
Parameters:
Connection(Connection&&) = default;
Parameters:
Operators
Connection& operator=(const Connection&) = delete;
Parameters:
Connection& operator=(Connection&&) = default;
Parameters:
Methods
ConnectAsync
static Future<Connection> ConnectAsync(const ComponentRegistry& registry, const std::string& hostname, std::uint32_t port, const std::string& worker_id, const ConnectionParameters& params);
Description: Connects to a SpatialOS deployment via a receptionist. This is the flow used to connect a managed worker running in the cloud alongside the deployment, and also to connect any local worker to a (local or remote) deployment via a locally-running receptionist.
Remarks: The hostname and port would typically be provided by SpatialOS on the command-line, if this is a managed worker on the cloud, or otherwise be predetermined (e.g.localhost:7777
for the default receptionist of a locally-running deployment).
Parameters:const ComponentRegistry&
registry
const std::string& hostname
std::uint32_t port
const std::string& worker_id
const ConnectionParameters&
params
- Parameters controlling the connection to SpatialOS.
Returns:
Future<Connection>
- GetConnectionStatusCode
ConnectionStatusCode GetConnectionStatusCode() const;
Returns:
ConnectionStatusCode
- Returns kSuccess if the Connection object if the Connection is connected and usable, otherwise a value indicating the type of error that occurred.
GetConnectionStatusDetailString
std::string GetConnectionStatusDetailString() const;
Returns:
std::string
- Returns a string containing more detailed information about the connection status.- GetOpList
OpList GetOpList(std::uint32_t timeout_millis);
Description: Retrieves the list of operations that have occurred since the last call to this function.
Parameters:std::uint32_t timeout_millis
- If non-zero, the function will block until there is at least one operation to return, or the timeout has been exceeded. If the timeout is exceeded, an empty list will be returned. Iftimeout_millis
is zero, the function is non-blocking.
Returns:
OpList
- A list of operations to be passed to Process
GetWorkerAttributes
List<std::string> GetWorkerAttributes() const;
Description: Returns the list of attributes that have been assigned to the worker by SpatialOS.
Remarks: Worker attributes are static and will not change over the lifetime of the connection.
Returns:List<std::string>
- The list of attributes of the worker as assigned by the SpatialOS runtime when the worker connects.- GetWorkerFlag
Option<std::string> GetWorkerFlag(const std::string& flag_name) const;
Description: Retrieves the value of a worker flag.
Remarks: Worker flags are remotely configurable and may change during the runtime of the worker, including addition and deletion.
Parameters:const std::string& flag_name
- The name of the worker flag to retrieve.
Returns:
Option<std::string>
- The value of the worker flag with the given name. If no such worker flag exists, an empty option is returned.
GetWorkerId
std::string GetWorkerId() const;
Description: Returns the ID of the worker as assigned by SpatialOS.
Remarks: A worker ID is static and will not change over the lifetime of the connection.
Returns:std::string
- The ID of the worker as assigned by the SpatialOS runtime when the worker connects.- IsConnected
bool IsConnected() const;
Remarks: DEPRECATED: Equivalent to GetConnectionStatusCode () == ConnectionStatusCode::kSuccess.
Returns:bool
- Returns true if the Connection object was created correctly and has successfully connected to SpatialOS.
SendAddComponent<typename T>
template<typename T> void SendAddComponent(EntityId entity_id, const typename T::Data& data, const UpdateParameters& parameters);
Description: Adds a new component to the given entity in SpatialOS.
Remarks: The provided component data object is copied and may be subsequently reused by the caller. This function does not check whether the worker currently has authority over the component. In order to use this function, EnableDynamicComponents must be set to true. Note that the sent add component is added as an operation to the operation list and will be returned by a subsequent call to GetOpList unless Loopback is set to kNone.
Type parameters:typename T
- A generated component metaclass.
Parameters:
EntityId
entity_id
const typename T::Data& data
const UpdateParameters&
parameters
Returns:
void
- SendAddComponent<typename T>
template<typename T> void SendAddComponent(EntityId entity_id, typename T::Data&& data, const UpdateParameters& parameters);
Description: Adds a new component to the given entity in SpatialOS.
Remarks: The provided component data object is moved from. This function does not check whether the worker currently has authority over the component, you must make sure the worker has authority in order to add the component. In order to use this function, EnableDynamicComponents must be set to true. Note that the sent add component is added as an operation to the operation list and will be returned by a subsequent call to GetOpList unless Loopback is set to kNone.
Type parameters:typename T
- A generated component metaclass.
Parameters:
EntityId
entity_id
typename T::Data&& data
const UpdateParameters&
parameters
Returns:
void
SendAuthorityLossImminentAcknowledgement<typename T>
template<typename T> void SendAuthorityLossImminentAcknowledgement(EntityId entity_id);
Description: Sends an acknowledgement of the receipt of an kAuthorityLossImminent authority change for a component.
Remarks: Sending the acknowledgement signifies that this worker is ready to lose authority over the component for the given entity.
Type parameters:typename T
- A generated component metaclass.
Parameters:
EntityId
entity_id
Returns:
void
- SendAuthorityLossImminentAcknowledgement
void SendAuthorityLossImminentAcknowledgement(EntityId entity_id, ComponentId component_id);
Description: Sends an acknowledgement of the receipt of an kAuthorityLossImminent authority change for a component.
Remarks: Sending the acknowledgement signifies that this worker is ready to lose authority over the component for the given entity.
Parameters:EntityId
entity_id
ComponentId
component_id
Returns:
void
SendCommandFailure<typename T>
template<typename T> void SendCommandFailure(RequestId<IncomingCommandRequest<T>> request_id, const std::string& message);
Description: Explicitly fails an incoming command request for a component on an entity over which this worker has authority. The request ID should match an incoming command request via the OnCommandRequest callback.
Remarks: The calling worker will receive a command response with status code kApplicationError.
Type parameters:typename T
- A generated command metaclass.
Parameters:
RequestId<IncomingCommandRequest<T>>
request_id
const std::string& message
Returns:
void
- SendCommandRequest<typename T>
template<typename T> RequestId<OutgoingCommandRequest<T>> SendCommandRequest(EntityId entity_id, typename T::Request&& request, const Option<std::uint32_t>& timeout_millis, const CommandParameters& parameters = {false});
Description: Sends a command request to a component on a specific target entity.
Remarks: The provided request object is moved-from.
Type parameters:typename T
- A generated command metaclass.
Parameters:
EntityId
entity_id
typename T::Request&& request
const Option<std::uint32_t>&
timeout_millis
- If not specified, the default timeout will be used.const CommandParameters&
parameters = {false}
- Parameters used to alter the behaviour of this request.
Returns:
RequestId<OutgoingCommandRequest<T>>
- A request ID which can be used to identify a response to the command via the OnCommandResponse callback.
SendCommandRequest<typename T>
template<typename T> RequestId<OutgoingCommandRequest<T>> SendCommandRequest(EntityId entity_id, const typename T::Request& request, const Option<std::uint32_t>& timeout_millis, const CommandParameters& parameters = {false});
Description: Sends a command request to a component on a specific target entity.
Remarks: The provided request object is copied and may be subsequently reused by the caller.
Type parameters:typename T
- A generated command metaclass.
Parameters:
EntityId
entity_id
const typename T::Request& request
const Option<std::uint32_t>&
timeout_millis
- If not specified, the default timeout will be used.const CommandParameters&
parameters = {false}
- Parameters used to alter the behaviour of this request.
Returns:
RequestId<OutgoingCommandRequest<T>>
- A request ID which can be used to identify a response to the command via the OnCommandResponse callback.- SendCommandResponse<typename T>
template<typename T> void SendCommandResponse(RequestId<IncomingCommandRequest<T>> request_id, typename T::Response&& response);
Description: Sends a response to an incoming command request for a component on an entity over which this worker has authority.
Remarks: The provided request object is moved-from.
Type parameters:typename T
- A generated command metaclass.
Parameters:
RequestId<IncomingCommandRequest<T>>
request_id
typename T::Response&& response
Returns:
void
SendCommandResponse<typename T>
template<typename T> void SendCommandResponse(RequestId<IncomingCommandRequest<T>> request_id, const typename T::Response& response);
Description: Sends a response to an incoming command request for a component on an entity over which this worker has authority. The request ID should match an incoming command request via the OnCommandResponse callback.
Remarks: The provided request object is copied and may be subsequently reused by the caller.
Type parameters:typename T
- A generated command metaclass.
Parameters:
RequestId<IncomingCommandRequest<T>>
request_id
const typename T::Response& response
Returns:
void
- SendComponentInterest
void SendComponentInterest(EntityId entity_id, Map<ComponentId, InterestOverride> interest_overrides);
Description: Sends a component interest update for the given entity to SpatialOS. By default, the worker receives data for all entities according to the default component interests specified in its bridge settings. This function overrides the default to explicitly add or remove interest for particular components.
Remarks: Interest for components not present in theinterest_overrides
map is unaffected. Note also that components over which the worker is authoritative are always received, regardless of interest settings.
Parameters:EntityId
entity_id
Map<ComponentId, InterestOverride>
interest_overrides
Returns:
void
SendComponentUpdate<typename T>
template<typename T> void SendComponentUpdate(EntityId entity_id, const typename T::Update& update, const UpdateParameters& parameters = {ComponentUpdateLoopback::kShortCircuited});
Description: Sends an update for an entity’s component to SpatialOS. Note that the sent component update is added as an operation to the operation list and will be returned by a subsequent call to GetOpList unless Loopback is set to kNone.
Remarks: The provided update object is copied and may be subsequently reused by the caller.
Type parameters:typename T
- A generated component metaclass.
Parameters:
EntityId
entity_id
const typename T::Update& update
const UpdateParameters&
parameters = {ComponentUpdateLoopback::kShortCircuited}
Returns:
void
- SendComponentUpdate<typename T>
template<typename T> void SendComponentUpdate(EntityId entity_id, typename T::Update&& update, const UpdateParameters& parameters = {ComponentUpdateLoopback::kShortCircuited});
Description: Sends an update for an entity’s component to SpatialOS. Note that the sent component update is added as an operation to the operation list and will be returned by a subsequent call to GetOpList unless Loopback is set to kNone.
Remarks: The provided update object is moved-from.
Type parameters:typename T
- A generated component metaclass.
Parameters:
EntityId
entity_id
typename T::Update&& update
const UpdateParameters&
parameters = {ComponentUpdateLoopback::kShortCircuited}
Returns:
void
SendCreateEntityRequest
RequestId<CreateEntityRequest> SendCreateEntityRequest(const Entity& entity, const Option<EntityId>& entity_id, const Option<std::uint32_t>& timeout_millis);
Description: Requests SpatialOS to create an entity.
Remarks: The provided entity data is copied and can subsequently be reused by the caller.
Parameters:const Entity&
entity
- The entity to be created.const Option<EntityId>&
entity_id
- If provided, it must have been reserved using SendReserveEntityIdRequest, however we do not recommend using a reserved entity ID. We recommend that you avoid specify an entity ID when creating an entity and instead use the automatically assigned entity ID contained in CreateEntityResponseOp.const Option<std::uint32_t>&
timeout_millis
- If not specified, the default timeout will be used.
Returns:
RequestId<CreateEntityRequest>
- A request ID, which can be used to identify a response to the request via the OnCreateEntityResponse callback.- SendDeleteEntityRequest
RequestId<DeleteEntityRequest> SendDeleteEntityRequest(EntityId entity_id, const Option<std::uint32_t>& timeout_millis);
Description: Requests SpatialOS to delete an entity.
Parameters:EntityId
entity_id
const Option<std::uint32_t>&
timeout_millis
- If not specified, the default timeout will be used.
Returns:
RequestId<DeleteEntityRequest>
- A request ID, which can be used to identify a response to the request via the OnDeleteEntityResponse callback.
SendEntityQueryRequest
RequestId<EntityQueryRequest> SendEntityQueryRequest(const EntityQuery& entity_query, const Option<std::uint32_t>& timeout_millis);
Description: Queries SpatialOS for remote entity data.
Parameters:const EntityQuery&
entity_query
const Option<std::uint32_t>&
timeout_millis
- If not specified, the default timeout will be used.
Returns:
RequestId<EntityQueryRequest>
- A request ID, which can be used to identify a response to the request via the OnEntityQueryResponse callback.- SendLogMessage
void SendLogMessage(LogLevel level, const std::string& logger_name, const std::string& message, const Option<EntityId>& entity_id = {});
Description: Sends a log message for the worker to SpatialOS.
Parameters:LogLevel
level
const std::string& logger_name
const std::string& message
const Option<EntityId>&
entity_id = {}
Returns:
void
SendMetrics
void SendMetrics(Metrics& metrics);
Description: Sends a set of metrics for the worker to SpatialOS. Since histogram metrics are diff-based, calling this function clears each histogram in the Metrics parameter.
Parameters:Metrics&
metrics
Returns:
void
- SendRemoveComponent<typename T>
template<typename T> void SendRemoveComponent(EntityId entity_id, const UpdateParameters& parameters);
Description: Removes a component from the given entity in SpatialOS.
Remarks: This function does not check whether the worker currently has authority over the component, you must make sure the worker has authority in order to remove the component. In order to use this function, EnableDynamicComponents must be set to true. Note that the sent remove component is added as an operation to the operation list and will be returned by a subsequent call to GetOpList unless Loopback is set to kNone.
Type parameters:typename T
- A generated component metaclass.
Parameters:
EntityId
entity_id
const UpdateParameters&
parameters
Returns:
void
SendReserveEntityIdRequest
RequestId<ReserveEntityIdRequest> SendReserveEntityIdRequest(const Option<std::uint32_t>& timeout_millis);
Description: Requests SpatialOS to reserve an entity ID.
Remarks: We do not recommend reserving an entity ID. Instead, we recommend using SendCreateEntityRequest without specifying an entity ID. You can then use the automatically assigned entity ID provided in CreateEntityResponseOp.
Parameters:const Option<std::uint32_t>&
timeout_millis
- If not specified, the default timeout will be used.
Returns:
RequestId<ReserveEntityIdRequest>
- A request ID, which can be used to identify a response to the request via the OnReserveEntityIdResponse callback.- SendReserveEntityIdsRequest
RequestId<ReserveEntityIdsRequest> SendReserveEntityIdsRequest(std::uint32_t number_of_entity_ids, const Option<std::uint32_t>& timeout_millis);
Description: Requests SpatialOS to reserve multiple entity IDs.
Remarks: We do not recommend reserving entity IDs. Instead, we recommend using SendCreateEntityRequest without specifying an entity ID. You can then use the automatically assigned entity ID provided in CreateEntityResponseOp.
Parameters:std::uint32_t number_of_entity_ids
const Option<std::uint32_t>&
timeout_millis
- If not specified, the default timeout will be used.
Returns:
RequestId<ReserveEntityIdsRequest>
- A request ID, which can be used to identify a response to the request via the OnReserveEntityIdsResponse callback.
SetProtocolLoggingEnable
void SetProtocolLoggingEnable(bool enable);
Description: Enables or disables protocol logging. Logging uses the parameters specified when the Connection was created. Enabling it when already enabled, or disabling it when already disabled, do nothing.
Remarks: Note that logs from any previous protocol logging sessions will be overwritten.
Parameters:bool enable
Returns:
void
worker::ConnectionParameters struct
Summary Parameters for creating a Connection and connecting to SpatialOS. Fields
std::uint32_t BuiltInMetricsReportPeriodMillis =
kBuiltInMetricsReportPeriodMillis
- The Connection tracks several internal metrics, such as send and receive queue statistics. This parameter controls how frequently the Connection will return a MetricsOp reporting its built-in metrics. This is the same as the period at which the built-in metrics are sent to SpatialOS. If set to zero, this functionality is disabled.bool EnableDynamicComponents =
kEnableDynamicComponents
- Whether to enable the dynamic components feature. If this field is true, add and remove component ops are emitted on authority change, i.e. where you would previously receive a component update prior to gaining authority or after losing authority, you will now receiving an add component (if the component exists) or a remove component (if the component does not exist). These ops, like all add and remove component ops, must be treated in an idempotent way (i.e. they replace any existing value on the worker for the component).bool EnableProtocolLoggingAtStartup = false
- Whether to enable protocol logging at startup.std::uint32_t LogMessageQueueCapacity =
kLogMessageQueueCapacity
- Number of messages logged by the SDK that can be stored in the log message queue. When the log message queue is full, messages logged by the SDK can be dropped.NetworkParameters
Network
- Parameters controlling the network connection to SpatialOS.ProtocolLoggingParameters
ProtocolLogging
- Parameters for configuring protocol logging.std::uint32_t ReceiveQueueCapacity =
kReceiveQueueCapacity
- Number of messages that can be stored on the receive queue. When the receive queue is full, SpatialOS can apply QoS and drop messages to the worker.std::uint32_t SendQueueCapacity =
kSendQueueCapacity
- Number of messages that can be stored on the send queue. When the send queue is full, calls to Connection Send functions can block.ThreadAffinityParameters
ThreadAffinity
- Parameters for configuring thread affinity.std::string WorkerType
- Worker type (platform).
worker::ConnectionStatus struct
Summary Information about the status of a network request. Fields
ConnectionStatusCode
Code
- The status of the request.std::string Detail
- Detailed, human readable description of the connection status. Will be “OK” if no error occurred.
worker::ConnectionStatusCode enum
Summary Possible status codes for a remote call, connection attempt or connection migration attempt. Fields
ConnectionStatusCode
kCancelled
- Attempt was cancelled by the caller. Currently shouldn’t happen; reserved for future use.ConnectionStatusCode
kCapacityExceeded
- Failed because the deployment associated with the provided login token was at capacity. Retryable.ConnectionStatusCode
kInternalError
- Protocol violation, or some part of the system otherwise behaved in an unexpected way. Not expected to occur in normal operation.ConnectionStatusCode
kInvalidArgument
- An argument provided by the caller was determined to be invalid. This is a local failure; no actual attempt was made to contact the host. Not retryable.ConnectionStatusCode
kLoginTokenExpired
- The login token provided by the caller has expired. Generate a new one and retry.ConnectionStatusCode
kNetworkError
- Failed due to a networking issue or otherwise unreachable host.ConnectionStatusCode
kPlayerIdentityTokenExpired
- The player identity token provided by the caller has expired. Generate a new one and retry.ConnectionStatusCode
kRateExceeded
- Failed due to rate-limiting of new connections to the deployment associated with the provided login token. Retryable.ConnectionStatusCode
kRejected
- Made contact with the host, but the request was explicitly rejected. Unlikely to be retryable. Possible causes include: the request was made to the wrong host; the host considered the request invalid for some othe reason.ConnectionStatusCode
kServerShutdown
- After a successful connection attempt, the server later explicitly terminated the connection. Possible causes include: the deployment was stopped; the worker was killed due to unresponsiveness.ConnectionStatusCode
kSuccess
- The remote call was successful, or we are successfully connected.ConnectionStatusCode
kTimeout
- A timeout provided by the caller or enforced by the system was exceeded. Can be retried.
worker::CreateEntityRequest struct
Summary Type parameter for entity creation request IDs. Constructors
CreateEntityRequest() = delete;
worker::CreateEntityResponseOp struct
Summary | A response indicating the result of an entity creation request. |
Fields
Option<EntityId>
EntityId
- If successful, the entity ID of the newly created entity.std::string Message
- A description of the status. Will contain the reason for failure if unsuccessful.RequestId<CreateEntityRequest>
RequestId
- The outgoing request ID for which there was a response.
Matches the request ID returned by a previous call to SendCreateEntityRequest.StatusCode
StatusCode
- The status code of the response.
If the status code is kApplicationError, the entity ID reservation has expired and must be retried.
worker::CriticalSectionOp struct
Summary | Data for an operation that indicates the message stream received by the worker is entering or leaving a critical section. |
Remarks | Nested critical sections are currently not supported by the protocol. |
Fields
bool InCriticalSection
worker::Defaults class
Summary | Default values for various configuration parameters. |
Fields
bool kUseExternalIp = false
worker::DeleteEntityRequest struct
Summary | Type parameter for entity deletion request IDs. |
Constructors
DeleteEntityRequest() = delete;
worker::DeleteEntityResponseOp struct
Summary | A response indicating the result of an entity deletion request. |
Fields
EntityId
EntityId
- The ID of the target entity of this request.std::string Message
- A description of the status. Will contain the reason for failure if unsuccessful.RequestId<DeleteEntityRequest>
RequestId
- The outgoing request ID for which there was a response.
Matches the request ID returned by a previous call to SendDeleteEntityRequest.StatusCode
StatusCode
- The status code of the response.
worker::Deployment struct
Summary | Details for a specific deployment obtained via GetDeploymentListAsync. |
Fields
std::string AssemblyName
- The name of the assembly used by this deployment.std::uint32_t UsersCapacity
- Total user capacity of the deployment.std::uint32_t UsersConnected
- Number of users currently connected to the deployment.
worker::DeploymentList struct
Summary | A deployment list obtained via GetDeploymentListAsync. |
Fields
List<Deployment>
Deployments
- List of accessible deployments for the given project.Option<std::string>
Error
- Will be non-empty if an error occurred.
worker::DisconnectOp struct
Summary | Data for an operation that indicates the Connection has disconnected and can no longer be used |
Fields
std::string Reason
worker::Dispatcher class
Summary | A Dispatcher processes OpLists retrieved from the Connection and invokes appropriate callbacks. |
Remarks | This object should not be modified concurrently by multiple threads. |
Type aliases
<typename T> using Callback = std::function<void(const T&)>;
using CallbackKey = std::uint64_t;
Constructors
Dispatcher(const ComponentRegistry&);
Parameters:
Dispatcher(const Dispatcher&) = delete;
Parameters:
Dispatcher(Dispatcher&&) = delete;
Parameters:
Operators
Dispatcher& operator=(const Dispatcher&) = delete;
Parameters:
Dispatcher& operator=(Dispatcher&&) = delete;
Parameters:
Methods
OnAddComponent<typename T>
template<typename T> CallbackKey OnAddComponent(const Callback<AddComponentOp<T>>& callback);
Description: Registers a callback to be invoked when a particular component is added to an existing entity in the worker’s view of the simulation.
Type parameters:typename T
- A generated component metaclass.
Parameters:
Returns:
CallbackKey
- OnAddEntity
CallbackKey OnAddEntity(const Callback<AddEntityOp>& callback);
Description: Registers a callback to be invoked when an entity is added to the worker’s view of the simulation.
Parameters:const Callback<AddEntityOp>&
callback
Returns:
CallbackKey
OnAuthorityChange<typename T>
template<typename T> CallbackKey OnAuthorityChange(const Callback<AuthorityChangeOp<T>>& callback);
Description: Registers a callback to be invoked when the worker is granted authority over a particular component for some entity, or when the worker’s authority over that component is revoked.
Type parameters:typename T
- A generated component metaclass.
Parameters:
Returns:
CallbackKey
- OnCommandRequest<typename T>
template<typename T> CallbackKey OnCommandRequest(const Callback<CommandRequestOp<T>>& callback);
Description: Registers a callback to be invoked when a command request is received for a particular component.
Type parameters:typename T
- A generated command metaclass.
Parameters:
Returns:
CallbackKey
OnCommandResponse<typename T>
template<typename T> CallbackKey OnCommandResponse(const Callback<CommandResponseOp<T>>& callback);
Description: Registers a callback to be invoked when a command response is received for a particular component.
Type parameters:typename T
- A generated command metaclass.
Parameters:
Returns:
CallbackKey
- OnComponentUpdate<typename T>
template<typename T> CallbackKey OnComponentUpdate(const Callback<ComponentUpdateOp<T>>& callback);
Description: Registers a callback to be invoked when a particular component is updated for an entity.
Type parameters:typename T
- A generated component metaclass.
Parameters:
Returns:
CallbackKey
OnCreateEntityResponse
CallbackKey OnCreateEntityResponse(const Callback<CreateEntityResponseOp>& callback);
Description: Registers a callback to be invoked when an entity creation response is received.
Parameters:Returns:
CallbackKey
- OnCriticalSection
CallbackKey OnCriticalSection(const Callback<CriticalSectionOp>& callback);
Description: Registers a callback to be invoked when the message stream enters or leaves a critical section.
Parameters:Returns:
CallbackKey
OnDeleteEntityResponse
CallbackKey OnDeleteEntityResponse(const Callback<DeleteEntityResponseOp>& callback);
Description: Registers a callback to be invoked when an entity deletion response is received.
Parameters:Returns:
CallbackKey
- OnDisconnect
CallbackKey OnDisconnect(const Callback<DisconnectOp>& callback);
Description: Registers a callback to be invoked when the Connection has disconnected and can no longer be used.
Parameters:const Callback<DisconnectOp>&
callback
Returns:
CallbackKey
OnEntityQueryResponse
CallbackKey OnEntityQueryResponse(const Callback<EntityQueryResponseOp>& callback);
Description: Registers a callback to be invoked when an entity query response is received.
Parameters:Returns:
CallbackKey
- OnFlagUpdate
CallbackKey OnFlagUpdate(const Callback<FlagUpdateOp>& callback);
Description: Registers a callback to be invoked when a worker flag has been created, deleted or when its value has changed.
Remarks: Callbacks are invoked in the order they are registered if a flag is created or its value has changed. If a flag is deleted, the callbacks are invoked in the reverse order to which they were registered on the dispatcher.
Parameters:const Callback<FlagUpdateOp>&
callback
Returns:
CallbackKey
OnLogMessage
CallbackKey OnLogMessage(const Callback<LogMessageOp>& callback);
Description: Registers a callback to be invoked when the SDK logs a message.
Parameters:const Callback<LogMessageOp>&
callback
Returns:
CallbackKey
- OnMetrics
CallbackKey OnMetrics(const Callback<MetricsOp>& callback);
Description: Registers a callback to be invoked when the SDK reports built-in metrics.
Parameters:const Callback<MetricsOp>&
callback
Returns:
CallbackKey
OnRemoveComponent<typename T>
template<typename T> CallbackKey OnRemoveComponent(const Callback<RemoveComponentOp<T>>& callback);
Description: Registers a callback to be invoked when a particular component is removed from an existing entity in the worker’s view of the simulation.
Type parameters:typename T
- A generated component metaclass.
Parameters:
Returns:
CallbackKey
- OnRemoveEntity
CallbackKey OnRemoveEntity(const Callback<RemoveEntityOp>& callback);
Description: Registers a callback to be invoked when an entity is removed from the worker’s view of the simulation.
Parameters:const Callback<RemoveEntityOp>&
callback
Returns:
CallbackKey
OnReserveEntityIdResponse
CallbackKey OnReserveEntityIdResponse(const Callback<ReserveEntityIdResponseOp>& callback);
Description: Registers a callback to be invoked when an entity ID reservation response is received.
Parameters:Returns:
CallbackKey
- OnReserveEntityIdsResponse
CallbackKey OnReserveEntityIdsResponse(const Callback<ReserveEntityIdsResponseOp>& callback);
Description: Registers a callback to be invoked when a multiple entity ID reservation response is received.
Parameters:Returns:
CallbackKey
Process
void Process(const OpList& op_list);
Description: Processes an OpList and invokes registered callbacks.
Parameters:const OpList&
op_list
- The OpList to process, typically retrieved via GetOpList
Returns:
void
- Remove
void Remove(CallbackKey key);
Description: Unregisters a callback identified by its CallbackKey, as returned from the registration function.
Remarks: If the key does not exist, the application will terminate.
Parameters:CallbackKey
key
Returns:
void
worker::Entity class
Summary | Stores the complete data for an entity’s components. This is used both for representing the initial set of components for an entity by the AddEntity operation, and inside the (optional) View. |
Remarks | Note that an Entity object is simply a local data structure, and changes made here are not automatically reflected across the SpatialOS simulation. To synchronize component state with SpatialOS, use SendComponentUpdate. This object should not be modified concurrently by multiple threads. |
Constructors
Entity();
Entity(const Entity&);
Parameters:
Entity(Entity&&) = default;
Parameters:
Operators
Entity& operator=(const Entity& entity);
Parameters:
const Entity&
entity
Entity& operator=(Entity&& entity) = default;
Parameters:
Entity&&
entity
Methods
Add<typename T>
template<typename T> void Add(typename T::Data&& data);
Description: Creates the given component by copying the provided initial data. Has no effect if the entity already has the given component.
Type parameters:typename T
- A generated component metaclass.
Parameters:
typename T::Data&& data
Returns:
void
- Add<typename T>
template<typename T> void Add(const typename T::Data& data);
Description: Creates the given component by copying the provided initial data. Has no effect if the entity already has the given component.
Type parameters:typename T
- A generated component API metaclass
Parameters:
const typename T::Data& data
Returns:
void
Get<typename T>
template<typename T> Option<typename T::Data&> Get();
Description: Retrieves data for the given component. Returns an empty option if the entity does not have the given component.
Type parameters:typename T
- A generated component metaclass.
Returns:
Option<typename T::Data&>
- Get<typename T>
template<typename T> Option<const typename T::Data&> Get() const;
Description: Retrieves data for the given component. Returns an empty option if the entity does not have the given component.
Type parameters:typename T
- A generated component API metaclass
Returns:
Option<const typename T::Data&>
GetComponentIds
List<ComponentId> GetComponentIds() const;
Description: Returns a list of the component IDs of the components present in this entity.
Returns:List<ComponentId>
- Remove<typename T>
template<typename T> void Remove();
Description: Removes a component.
Type parameters:typename T
- A generated component metaclass.
Returns:
void
Update<typename T>
template<typename T> void Update(const typename T::Update& update);
Description: Applies an update to the given component. Has no effect if the entity does not have the given component.
Type parameters:typename T
- A generated component metaclass.
Parameters:
const typename T::Update& update
Returns:
void
worker::EntityQueryRequest struct
Summary Type parameter for entity query request IDs. Constructors
EntityQueryRequest() = delete;
worker::EntityQueryResponseOp struct
Summary | A response indicating the result of an entity query request. |
Fields
std::string Message
- A description of the status. Will contain the reason for failure if unsuccessful.RequestId<EntityQueryRequest>
RequestId
- The outgoing request ID for which there was a response.
Matches a previous call to SendEntityQueryRequest.Map<EntityId, Entity>
Result
- The result of the query. Not used forCountResultType
queries.
Note that a best-effort attempt is made to get results when the status code is kApplicationError. In this case, the result can still be non-empty, but should be considered incomplete (i.e. there might be entities matching the query that were not returned).std::size_t ResultCount
- The number of entities that matched the query.
Note that a best-effort attempt is made to count the entities when the status code is kApplicationError. In this case, the count can still be non-zero, but should be considered a lower bound (i.e. there might be entities matching the query that were not counted).StatusCode
StatusCode
- The status code of the response.
worker::ErasureCodecParameters struct
Summary | Parameters to configure erasure coding, a forward error correction technique which increases bandwidth usage but may improve latency on unreliable networks. |
Fields
std::uint8_t OriginalPacketCount =
kErasureCodecOriginalPacketCount
- Number of consecutive packets to send before sending redundant recovery packets.std::uint8_t RecoveryPacketCount =
kErasureCodecRecoveryPacketCount
- Number of redundant recovery packets to send for each group of consecutive original packets. These packets are used to recover up to the same number of lost original packets.std::uint8_t WindowSize =
kErasureCodecWindowSize
- Number of batches that can be stored in memory, where a batch contains packets belonging to the same group of consecutive original packets and the corresponding recovery packets. Each batch contains up to OriginalPacketCount plus RecoveryPacketCount packets.
worker::FlagUpdateOp struct
Summary | Data for an operation that indicates a worker flag has been created, deleted or its value has changed. |
Fields
Option<std::string>
Value
worker::Future<typename T> class
Summary | A class representing the standard future concept. It can be used for both synchronous and asynchronous interaction. |
Type parameters
typename T
Constructors
Future(Future&&) = default;
Parameters:
Future(const Future&) = delete;
Parameters:
Operators
Future& operator=(Future&&) = default;
Parameters:
Future& operator=(const Future&) = delete;
Parameters:
Methods
Get
T Get();
Description: Waits until the result of the future is available, and returns it. This method can only be called once; calling
Get()
a second time is a fatal error.
Returns:T
- The result.- Wait
bool Wait(const Option<std::uint32_t>& timeout_millis);
Description: Waits for the result of the future to become available. If timeout_millis is empty, blocks until the result is available. If timeout_millis is non-empty, blocks for at most that many milliseconds.
Parameters:const Option<std::uint32_t>&
timeout_millis
- The time to wait for the result to become available.
Returns:
bool
worker::HeartbeatParameters struct
Summary | Parameters to configure internal heartbeating which can detect unresponsive peers. If an unresponsive peer is detected, a DisconnectOp will be enqueued in the OpList. |
Fields
std::uint64_t IntervalMillis =
kHeartbeatIntervalMillis
- Minimum interval, in milliseconds, between which heartbeat messages are sent to the peer. A new heartbeat won’t be sent before a response for the original heartbeat is received.std::uint64_t TimeoutMillis =
kHeartbeatTimeoutMillis
- Time, in milliseconds, after which the peer will be deemed unresponsive.
worker::HistogramMetric class
Summary | A histogram metric tracks observations of a given value by bucket. This corresponds to a Prometheus histogram metric. |
Remarks | This object should not be used concurrently by multiple threads. |
Constructors
HistogramMetric();
Description: Creates a histogram with a single bucket.
HistogramMetric(const List<double>& bucket_upper_bounds);
Description: Creates a histogram with the given bucket boundaries. Each bucket boundary is an upper bound; the bucket tracks all observations with a value less than or equal to the bound. A final bucket with a boundary of +INF is added automatically.
Parameters:
const List<double>&
bucket_upper_bounds
Methods
Buckets
const List<Bucket>& Buckets() const;
Description: Returns the buckets for inspection.
Returns:const List<Bucket>&
- ClearObservations
void ClearObservations();
Description: Clears all recorded oservations.
Remarks: Automatically called by SendMetrics.
Returns:void
RecordObservation
void RecordObservation(double value);
Description: Records a sample and adds it to the corresponding buckets.
Parameters:double value
Returns:
void
- Sum
double Sum() const;
Description: Returns the sum of all observations since the last call to ClearObservations.
Returns:double
Nested classes
worker::HistogramMetric::Bucket
- A histogram bucket.
worker::HistogramMetric::Bucket struct
Summary | A histogram bucket. |
Fields
std::uint32_t Samples
- The number of observations that were less than or equal to the upper bound.double UpperBound
- The upper bound.
worker::IncomingCommandRequest<typename T> struct
Summary | Type parameter for incoming entity command request IDs. |
Type parameters
typename T
- A generated command metaclass.
Constructors
IncomingCommandRequest() = delete;
worker::InterestOverride struct
Summary | Overrides the default interest settings for a particular entity and component. |
Fields
bool IsInterested
- Controls whether checkout is explicitly enabled or disabled.
worker::KcpNetworkParameters struct
Summary | Parameters for configuring a KCP connection. Used by NetworkParameters. |
Fields
bool EarlyRetransmission =
kKcpEarlyRetransmission
- Whether to enable early retransmission, which causes optimistic retransmission of earlier packets when acknowledgements are received for packets which were sent later, rather than waiting until the retransmission timeout has expired.bool EnableErasureCodec =
kKcpEnableErasureCodec
- Whether to enable the erasure codec.ErasureCodecParameters
ErasureCodec
- Erasure codec parameters.bool FastRetransmission =
kKcpFastRetransmission
- Whether to enable fast retransmission, which causes retransmission delays to increase more slowly when retransmitting timed out packets multiple times.HeartbeatParameters
Heartbeat
- Heartbeat parameters.std::uint32_t MinRtoMillis =
kKcpMinRtoMillis
- Hard limit on the minimum retransmission timeout. A packet will be resent if an acknowledgment has not been received from the peer within a time period known as the retransmission timeout. The retransmission timeout is calculated based on estimated round trip times to the remote peer, but it will never be set to a value lower than the minimum retransmission timeout. If you set this parameter to a value which is much higher than the average round trip time to a peer, it will likely result in packets not being resent as early as they could be, increasing latency for retransmitted packets. However, if you set this parameter to a value which is lower than the average round trip time (or ping), packets will be retransmitted even if they are not lost, which will cause unnecessary bandwidth overhead until round trip times are calculated. For more information on retransmission timeouts and their calculation, see RFC 6298. Note, however, that the RFC pertains to TCP, and therefore it focuses on avoiding unnecessary retransmissions rather than optimizing for latency. Set to zero to use default, which is lower when FastRetransmission is enabled.std::uint32_t MultiplexLevel =
kKcpMultiplexLevel
- Number of multiplexed KCP streams.bool NonConcessionalFlowControl =
kKcpNonConcessionalFlowControl
- Whether to enable non-concessional flow control, which disables the usage of congestion windows (which are used to reduce packet loss across congested networks). Enabling non-concessional flow control can help optimize for low-latency delivery of small messages.std::uint32_t RecvWindowSize =
kKcpRecvWindowSize
- KCP flow-control window for receiving, in number of KCP packets. This window is applied to each independent stream. The upper bound on the memory used by receive buffers is proportional to the multiplex level multiplied by the receive window size.std::uint32_t SendWindowSize =
kKcpSendWindowSize
- KCP flow-control window size for sending, in number of KCP packets. This window is applied to sending across all streams i.e. sending a message will block if it would cause the total number of un-acked outgoing packets to exceed the send window size.std::uint32_t UpdateIntervalMillis =
kKcpUpdateIntervalMillis
- Interval, in milliseconds, between which the KCP transport layer sends and receives packets waiting in its send and receive buffers respectively.
worker::List<typename T> class
Summary | Stores a contiguous array of values. In particular, this is used for “repeated” fields in generated schema code. This class implements a subset of the std::vector interface, and all operations have the corresponding semantics. However, unlike std::vector |
Type parameters
typename T
Type aliases
using value_type = T;
using reference = value_type&;
using const_reference = const value_type&;
using pointer = value_type*;
using const_pointer = const value_type*;
using iterator = pointer;
using const_iterator = const_pointer;
using reverse_iterator = std::reverse_iterator<iterator>;
using const_reverse_iterator = std::reverse_iterator<const_iterator>;
using size_type = std::size_t;
using difference_type = std::ptrdiff_t;
Constructors
List() = default;
List(const List&) = default;
Parameters:
List(List&&) = default;
Parameters:
List(std::initializer_list<T> list);
Description: Constructs from the given elements.
Parameters:
std::initializer_list<T> list
template<typename It> List(It first, It last);
Description: Constructs from the given range.
Parameters:
It first
It last
Operators
List& operator=(const List&) = default;
Parameters:
List& operator=(List&&) = default;
Parameters:
List& operator=(const std::initializer_list<T> list);
Description: Assigns the given elements.
Parameters:
const std::initializer_list<T> list
bool operator==(const List& other) const;
Description: Checks for equality.
Parameters:
const List&
other
bool operator!=(const List& other) const;
Description: Checks for inequality.
Parameters:
const List&
other
reference operator[](size_type pos);
Description: Access an arbitrary element.
Parameters:
size_type
pos
const_reference operator[](size_type pos) const;
Description: Access an arbitrary element.
Parameters:
size_type
pos
Methods
back
const_reference back() const;
Description: Access the last element.
Returns:const_reference
- back
reference back();
Description: Access the last element.
Returns:reference
begin
const_iterator begin() const;
Description: Iterator to the first element.
Returns:const_iterator
- begin
iterator begin();
Description: Iterator to the first element.
Returns:iterator
clear
void clear();
Description: Removes all elements.
Returns:void
- data
pointer data();
Description: Access to underlying array.
Returns:pointer
data
const_pointer data() const;
Description: Access to underlying array.
Returns:const_pointer
- emplace<typename… Args>
template<typename... Args> iterator emplace(const_iterator pos, Args&&... args);
Description: Constructs an element in-place before pos.
Type parameters:typename... Args
Parameters:
const_iterator
pos
Args&&... args
Returns:
iterator
emplace_back<typename… Args>
template<typename... Args> void emplace_back(Args&&... args);
Description: Constructs an element in-place at the back.
Type parameters:typename... Args
Parameters:
Args&&... args
Returns:
void
- empty
bool empty() const;
Description: True if there are 0 elements.
Returns:bool
end
const_iterator end() const;
Description: Iterator to one past the last element.
Returns:const_iterator
- end
iterator end();
Description: Iterator to one past the last element.
Returns:iterator
erase
iterator erase(const_iterator first, const_iterator last);
Description: Erases the elements in the given range.
Parameters:const_iterator
first
const_iterator
last
Returns:
iterator
- erase
iterator erase(const_iterator pos);
Description: Erases the element at the given position.
Parameters:Returns:
iterator
front
const_reference front() const;
Description: Access the first element.
Returns:const_reference
- front
reference front();
Description: Access the first element.
Returns:reference
insert
iterator insert(const_iterator pos, std::initializer_list<T> list);
Description: Inserts the given elements before the given position.
Parameters:const_iterator
pos
std::initializer_list<T> list
Returns:
iterator
- insert<typename It>
template<typename It> iterator insert(const_iterator pos, It first, It last);
Description: Inserts from the given range before the given position.
Type parameters:typename It
Parameters:
const_iterator
pos
It first
It last
Returns:
iterator
insert
iterator insert(const_iterator pos, size_type count, const T& value);
Description: Inserts count copies of the given element.
Parameters:const_iterator
pos
size_type
count
const T& value
Returns:
iterator
- pop_back
void pop_back();
Description: Erases the last element.
Returns:void
rbegin
const_reverse_iterator rbegin() const;
Description: Reverse iterator to the first element.
Returns:const_reverse_iterator
- rbegin
reverse_iterator rbegin();
Description: Reverse iterator to the first element.
Returns:reverse_iterator
rend
reverse_iterator rend();
Description: Reverse iterator to one past the last element.
Returns:reverse_iterator
- rend
const_reverse_iterator rend() const;
Description: Reverse iterator to one past the last element.
Returns:const_reverse_iterator
size
size_type size() const;
Description: Number of elements.
Returns:size_type
- swap
void swap(List& other);
Description: Swaps the contents with that of other.
Parameters:List&
other
Returns:
void
worker::Locator class
Summary | A client which can be used to connect to a SpatialOS deployment via a locator service. This is the standard flow used to connect a local worker to a cloud deployment. |
Remarks | This object should not be used concurrently by multiple threads. |
Type aliases
using QueueStatusCallback = std::function<bool(const QueueStatus&)>;
Constructors
Locator(const std::string& hostname, const LocatorParameters& param);
Description: Creates a client for the locator service.
Parameters:
const std::string& hostname
- Typically it is “locator.improbable.io”.const LocatorParameters&
param
- The parameters for the locator service.
Locator(const Locator&) = delete;
Parameters:
Locator(Locator&&) = default;
Parameters:
Operators
Locator& operator=(const Locator&) = delete;
Parameters:
Locator& operator=(Locator&&) = default;
Parameters:
Methods
ConnectAsync
Future<Connection> ConnectAsync(const ComponentRegistry& registry, const std::string& deployment_name, const ConnectionParameters& params, QueueStatusCallback callback);
Description: Connects to a specific deployment. The resulting future can be used to make this connection either synchronously or asyncronously.
Parameters:const ComponentRegistry&
registry
const std::string& deployment_name
- The deployment name should be obtained by calling GetDeploymentListAsync.const ConnectionParameters&
params
- The connection parameters.QueueStatusCallback
callback
- The queueing callback, which should return false to cancel queuing, or true to continue queueing.
Returns:
Future<Connection>
- A future object for the connection- GetDeploymentListAsync
Future<DeploymentList> GetDeploymentListAsync();
Description: Queries the current list of deployments for the project given in the LocatorParameters. The resulting future can be used to make this connection either synchronously or asyncronously.
Returns:Future<DeploymentList>
- A future object for the list of deployments.
worker::LocatorCredentialsType enum
Fields
LocatorCredentialsType
kLoginToken
LocatorCredentialsType
kSteam
worker::LocatorParameters struct
Summary | Parameters for authenticating and logging in to a SpatialOS deployment via the locator. |
Fields
LocatorCredentialsType
CredentialsType
- Type of credentials to use when authenticating via the Locator.bool EnableLogging = false
- Whether to enable logging for the locator flow.ProtocolLoggingParameters
Logging
- Parameters for configuring logging. Distinct from protocol logs: only relevant to the locator connection.LoginTokenCredentials
LoginToken
- Parameters used if theCredentialsType
is kLoginToken.std::string ProjectName
- The name of the SpatialOS project.SteamCredentials
Steam
- Parameters used if theCredentialsType
is kSteam.
worker::LogLevel enum
Fields
worker::LogMessageOp struct
Summary | Data for an operation that provides a log message from the SDK. |
Fields
LogLevel
Level
std::string Message
worker::LoginTokenCredentials struct
Summary | Parameters for authenticating using a SpatialOS login token. |
Fields
std::string Token
- The token would typically be provided on the command-line by the SpatialOS launcher.
worker::Map<K, V> class
Summary | Represents an unordered map. In particular, this is used for “map” fields in generated schema code. This class implements a subset of the std::unordered_map interface, and all operations have the corresponding semantics. The main differences are: - iteration order is well-defined and matches insertion order; - the value type V may be incomplete at the point of instantiation. |
Type parameters
K
V
Type aliases
using key_type = K;
using mapped_type = V;
using value_type = std::pair<const key_type, mapped_type>;
using reference = value_type&;
using const_reference = const value_type&;
using pointer = value_type*;
using const_pointer = const value_type*;
using iterator = typename std::MAP<value_type>::iterator;
using const_iterator = typename std::MAP<value_type>::const_iterator;
using reverse_iterator = std::reverse_iterator<iterator>;
using const_reverse_iterator = std::reverse_iterator<const_iterator>;
using size_type = std::size_t;
using difference_type = std::ptrdiff_t;
Constructors
Map() = default;
Map(const Map&);
Parameters:
Map(Map&&);
Parameters:
Map(std::initializer_list<value_type> list);
Description: Constructs from the given elements.
Parameters:
std::initializer_list<value_type> list
template<typename It> Map(It first, It last);
Description: Constructs from the given range.
Parameters:
It first
It last
Operators
Map& operator=(const Map&);
Parameters:
Map& operator=(Map&&);
Parameters:
Map& operator=(const std::initializer_list<value_type> list);
Description: Assigns the given elements.
Parameters:
const std::initializer_list<value_type> list
bool operator==(const Map& other) const;
Description: Checks for equality.
Parameters:
const Map&
other
bool operator!=(const Map& other) const;
Description: Checks for inequality.
Parameters:
const Map&
other
key_type operator[](mapped_type key);
Description: Access an element by key.
Parameters:
mapped_type
key
key_type operator[](mapped_type key) const;
Description: Access an element by key.
Parameters:
mapped_type
key
Methods
begin
const_iterator begin() const;
Description: Iterator to the first element.
Returns:const_iterator
- begin
iterator begin();
Description: Iterator to the first element.
Returns:iterator
clear
void clear();
Description: Removes all elements.
Returns:void
- count
bool count(const key_type& key) const;
Description: Whether the key exists.
Parameters:Returns:
bool
emplace<typename… Args>
template<typename... Args> std::pair<iterator, bool> emplace(Args&&... args);
Description: Constructs an element in-place (if the key does not exist).
Type parameters:typename... Args
Parameters:
Args&&... args
Returns:
std::pair<iterator, bool>
- empty
bool empty() const;
Description: True if there are 0 elements.
Returns:bool
end
const_iterator end() const;
Description: Iterator to one past the last element.
Returns:const_iterator
- end
iterator end();
Description: Iterator to one past the last element.
Returns:iterator
erase
bool erase(const key_type& key);
Description: Erases the element with the given key.
Parameters:Returns:
bool
- erase
iterator erase(const_iterator pos);
Description: Erases the element at the given position.
Parameters:Returns:
iterator
erase
iterator erase(const_iterator first, const_iterator last);
Description: Erases the elements in the given range.
Parameters:const_iterator
first
const_iterator
last
Returns:
iterator
- find
const_iterator find(const key_type& key) const;
Description: Find the given key.
Parameters:Returns:
const_iterator
find
iterator find(const key_type& key);
Description: Find the given key.
Parameters:Returns:
iterator
- front
reference front();
Description: Access the first element.
Returns:reference
front
const_reference front() const;
Description: Access the first element.
Returns:const_reference
- insert
void insert(const_iterator pos, std::initializer_list<value_type> list);
Description: Inserts the given elements.
Parameters:const_iterator
pos
std::initializer_list<value_type> list
Returns:
void
insert<typename It>
template<typename It> void insert(It first, It last);
Description: Inserts from the given range.
Type parameters:typename It
Parameters:
It first
It last
Returns:
void
- rbegin
reverse_iterator rbegin();
Description: Reverse iterator to the first element.
Returns:reverse_iterator
rbegin
const_reverse_iterator rbegin() const;
Description: Reverse iterator to the first element.
Returns:const_reverse_iterator
- rend
reverse_iterator rend();
Description: Reverse iterator to one past the last element.
Returns:reverse_iterator
rend
const_reverse_iterator rend() const;
Description: Reverse iterator to one past the last element.
Returns:const_reverse_iterator
- size
size_type size() const;
Description: Number of elements.
Returns:size_type
swap
void swap(Map& other);
Description: Swaps the contents with that of other.
Parameters:Map&
other
Returns:
void
worker::Metrics class
Summary A set of metrics sent up from a worker to SpatialOS. Remarks Keys for the contained metrics should match the following regex: [a-zA-Z][a-zA-Z0-9]* Fields
Map<std::string, double>
GaugeMetrics
- Gauge metrics for the worker.Map<std::string, HistogramMetric>
HistogramMetrics
- Histogram metrics for the worker.Option<double>
Load
- The load value of this worker. A value of 0 indicates that the worker is completely unloaded; a value greater than 1 indicates that the worker is overloaded. The load value directs SpatialOS’s load-balancing strategy for managed workers (spinning them up, spinning them down, and assigning work between them).
Methods
- Merge
void Merge(const Metrics& metrics);
Description: Copies all metrics from another Metrics object into this one, overwriting existing values.
Parameters:const Metrics&
metrics
Returns:
void
worker::MetricsOp struct
Summary | Data for an operation that provides a report on built-in metrics from the SDK. |
Fields
Metrics
Metrics
worker::NetworkConnectionType enum
Fields
NetworkConnectionType
kRakNet
worker::NetworkParameters struct
Summary | Parameters for configuring the network connection. |
Fields
std::uint64_t ConnectionTimeoutMillis = IMPROBABLE.WORKER.DEFAULTS.CONNECTION_TIMEOUT_MILLIS
- This parameter sets an upper bound on the time the futures returned by ConnectAsync or ConnectAsync functions will take to complete. If the attempt is unsuccessful by that point, the connection attempt will be stopped.NetworkConnectionType
ConnectionType =
kTcp
- Type of network connection to use when connecting to SpatialOS.std::uint32_t DefaultCommandTimeoutMillis =
kDefaultCommandTimeoutMillis
- Default timeout for commands without a specified timeout argument, in millis.KcpNetworkParameters
Kcp
- Connection parameters specific to KCP connections.RakNetNetworkParameters
RakNet
- Connection parameters specific to RakNet connections.TcpNetworkParameters
Tcp
- Connection parameters specific to TCP connections.bool UseExternalIp =
kUseExternalIp
- Set this flag to connect to SpatialOS using the externally-visible IP address. This flag must be set when connecting externally (i.e. from outside the cloud) to a cloud deployment.
worker::OpList class
Summary | An opaque list of operations retrieved from GetOpList. It is usually passed to Process, which dispatches the operations to the appropriate callbacks. |
Constructors
OpList(const OpList&) = delete;
Parameters:
OpList(OpList&&) = default;
Parameters:
Operators
OpList& operator=(const OpList&) = delete;
Parameters:
OpList& operator=(OpList&&) = default;
Parameters:
worker::Option<T> class
Summary | Represents an optional value. In particular, this is used for “option” fields in generated schema code. |
Remarks | Mostly compatible with the std::optional type introduced in C++17. It also is specialized to allow optional references. |
Type parameters
T
Type aliases
using value_type = T;
using reference = value_type&;
using const_reference = const value_type&;
using pointer = value_type*;
using const_pointer = const value_type*;
using iterator = pointer;
using const_iterator = const_pointer;
using size_type = std::size_t;
using difference_type = std::ptrdiff_t;
Constructors
Option() = default;
Option(const Option&);
Parameters:
Option(Option&&) = default;
Parameters:
Option(const T& value);
Description: Constructs from the given element.
Parameters:
const T& value
Option(T&& value);
Description: Constructs from the given element.
Parameters:
T&& value
Operators
Option& operator=(const Option&);
Parameters:
Option& operator=(Option&&) = default;
Parameters:
template<typename U> bool operator==(const Option<U>& other) const;
Description: Checks for equality.
Parameters:
const Option<U>&
other
template<typename U> bool operator!=(const Option<U>& other) const;
Description: Checks for inequality.
Parameters:
const Option<U>&
other
explicit operator bool() const;
Description: True if not empty.
pointer operator->();
Description: Access the underlying pointer, or nullptr if empty.
const_pointer operator->() const;
Description: Access the underlying pointer, or nullptr if empty.
reference operator*()&;
Description: Access the element.
const_reference operator*() const&;
Description: Access the element.
value_type&& operator*()&&;
Description: Move-from the element.
const value_type&& operator*() const&&;
Description: Move-from the element.
Methods
MoveValueOr<typename U>
template<typename U> value_type MoveValueOr(U&& default_value)&&;
Description: The contained value, or default_value if empty.
Type parameters:typename U
Parameters:
U&& default_value
Returns:
value_type
- ValueOr<typename U>
template<typename U> value_type ValueOr(U&& default_value) const&;
Description: The contained value, or default_value if empty.
Type parameters:typename U
Parameters:
U&& default_value
Returns:
value_type
begin
iterator begin();
Description: Iterator to the first element.
Returns:iterator
- begin
const_iterator begin() const;
Description: Iterator to the first element.
Returns:const_iterator
clear
void clear();
Description: Removes the element.
Returns:void
- data
const_pointer data() const;
Description: Access the underlying data, or nullptr if empty.
Returns:const_pointer
data
pointer data();
Description: Access the underlying data, or nullptr if empty.
Returns:pointer
- emplace<typename… Args>
template<typename... Args> void emplace(Args&&... args);
Description: Constructs an element in-place (if the key does not exist).
Type parameters:typename... Args
Parameters:
Args&&... args
Returns:
void
empty
bool empty() const;
Description: True if there isn’t an element.
Returns:bool
- end
iterator end();
Description: Iterator to one past the last element.
Returns:iterator
end
const_iterator end() const;
Description: Iterator to one past the last element.
Returns:const_iterator
- size
size_type size() const;
Description: Number of elements (either 0 or 1).
Returns:size_type
swap
void swap(Option& other);
Description: Swaps the contents with that of other.
Parameters:Option&
other
Returns:
void
worker::OutgoingCommandRequest<typename T> struct
Summary Type parameter for outgoing entity command request IDs. Type parameters
typename T
- A generated command metaclass.
Constructors
OutgoingCommandRequest() = delete;
worker::ProtocolLoggingParameters struct
Summary | Parameters for configuring protocol logging. If enabled, logs all protocol messages sent and received. |
Fields
std::string LogPrefix =
kLogPrefix
- Log file names are prefixed with this prefix, are numbered, and have the extension .log.std::uint32_t MaxLogFileSizeBytes =
kMaxLogFileSizeBytes
- Once the size of a log file reaches this size, a new log file is created.std::uint32_t MaxLogFiles =
kMaxLogFiles
- Maximum number of log files to keep. Note that logs from any previous protocol logging sessions will be overwritten.
worker::QueueStatus struct
Summary | A queue status update when connecting to a deployment via ConnectAsync. |
Fields
Option<std::string>
Error
- Will be non-empty if an error occurred.std::uint32_t PositionInQueue
- Position in the queue. Decreases as we advance to the front of the queue.
worker::RakNetNetworkParameters struct
Summary | Parameters for configuring a RakNet connection. Used by NetworkParameters. |
Fields
std::uint32_t HeartbeatTimeoutMillis =
kRakNetHeartbeatTimeoutMillis
- Time (in milliseconds) that RakNet should use for its heartbeat protocol.
worker::RemoveComponentOp struct
Summary | Data for an operation that indicates a component has been removed from an existing entity in the worker’s view of the simulation |
Fields
EntityId
EntityId
worker::RemoveEntityOp struct
Summary | Data for an operation that indicates an entity has been removed from the worker’s view of the simulation. |
Fields
EntityId
EntityId
- The ID of the entity that was removed from the worker’s view of the simulation.
worker::RequestId<typename T> struct
Summary | Represents an ID for a request. |
Type parameters
typename T
- A request marker type
Fields
std::uint32_t Id
- The underlying raw ID of the request. Only use this if you know what you are doing; prefer to use the RequestId object instead.
Constructors
RequestId();
explicit RequestId(std::uint32_t id);
Parameters:
std::uint32_t id
Operators
bool operator==(const RequestId&) const;
Parameters:
worker::ReserveEntityIdRequest struct
Summary | Type parameter for entity ID reservation request IDs. |
Constructors
ReserveEntityIdRequest() = delete;
worker::ReserveEntityIdResponseOp struct
Summary | A response indicating the result of an entity ID reservation request. |
Fields
Option<EntityId>
EntityId
- If successful, a newly allocated entity ID, which is guaranteed to be unused in the current deployment.std::string Message
- A description of the status. Will contain the reason for failure if unsuccessful.RequestId<ReserveEntityIdRequest>
RequestId
- The outgoing request ID for which there was a response.
Matches a previous call to SendReserveEntityIdRequest.StatusCode
StatusCode
- The status code of the response.
worker::ReserveEntityIdsRequest struct
Summary | Type parameter for multiple entity ID reservation request IDs. |
Constructors
ReserveEntityIdsRequest() = delete;
worker::ReserveEntityIdsResponseOp struct
Summary | A response indicating the result of the multiple entity ID reservation request. |
Fields
Option<EntityId>
EntityId
- If successful, an ID which is the first in a contiguous range of newly allocated entity IDs which are guaranteed to be unused in the current deployment.std::string Message
- A description of the status. Will contain the reason for failure if unsuccessful.std::size_t NumberOfEntityIds
- If successful, the number of IDs reserved in the contiguous range, otherwise 0.RequestId<ReserveEntityIdsRequest>
RequestId
- The outgoing request ID for which there was a response.
Matches the request ID returned by a previous call to SendReserveEntityIdsRequest.StatusCode
StatusCode
- The status code of the response.
worker::SnapshotInputStream class
Summary | A stream for reading snapshots one entity at a time. |
Constructors
explicit SnapshotInputStream(const ComponentRegistry& registry, const std::string& path);
Description: Creates a SnapshotInputStream to read the snapshot file from the given path.
Parameters:
const ComponentRegistry&
registry
const std::string& path
- The path to the snapshot file.
Methods
HasNext
bool HasNext();
Returns:
bool
- True if SnapshotInputStream has not reached EOF.- ReadEntity
Option<std::string> ReadEntity(EntityId& entity_id, Entity& entity);
Description: Loads the next EntityId and Entity pair from the Snapshot.
Parameters:Returns:
Option<std::string>
- An error message if error occurred.
worker::SnapshotOutputStream class
Summary | A stream for writing snapshots one entity at a time. |
Constructors
explicit SnapshotOutputStream(const ComponentRegistry& registry, const std::string& path);
Description: Creates a SnapshotOutputStream to read the snapshot file from the given path.
Parameters:
const ComponentRegistry&
registry
const std::string& path
- The path to the snapshot file.
Methods
WriteEntity
Option<std::string> WriteEntity(EntityId entity_id, const Entity& entity);
Description: Writes the EntityId and Entity pair to the output stream.
Parameters:EntityId
entity_id
const Entity&
entity
Returns:
Option<std::string>
- An error message if error occurred.worker::StatusCode enum
Fields
StatusCode
kApplicationError
- The command was delivered successfully, but the handler rejected it. Either the command was delivered to a worker that explicitly rejected it by calling SendCommandFailure, or the request data was rejected as invalid by SpatialOS itself. In the latter case, in particular, SendCreateEntityRequest will return kApplicationError if an entity ID reservation has expired, and SendEntityQueryRequest will return kApplicationError if the result set is incomplete.StatusCode
kAuthorityLost
- The request could not be executed by a worker, either because the worker lost authority over the entity while handling the request, the entity was deleted while handling the request, or no worker was authoritative over the entity at all. Assuming the deployment isn’t irrecoverably broken (e.g. due to misconfigured loadbalancing or crash-looping workers) this is a transient failure and can be retried immediately.StatusCode
kInternalError
- Some other error occurred. This likely indicates a bug in SpatialOS and should be reported.StatusCode
kNotFound
- The target entity did not exist, or did not have the target component. This probably means the entity either hasn’t been created yet or has already been deleted. It might make sense to retry the request if there is reason to believe the entity hasn’t yet been created but will be soon.StatusCode
kPermissionDenied
- The worker did not have the required permissions to make the request. Permissions do not change at runtime, so it doesn’t make sense to retry the request.StatusCode
kSuccess
- The request was successfully executed and returned a response.StatusCode
kTimeout
- The request timed out before a response was received. It can be retried, but carefully - this usually means the deployment is overloaded, so some sort of backoff should be used to avoid making the problem worse. This can also be caused by the target worker’s handling code failing to respond to the command at all, perhaps due to a bug in its implementation.
worker::SteamCredentials struct
Summary Parameters for authenticating using Steam credentials. Fields
std::string DeploymentTag
- Deployment tag to request access for. If non-empty, must match the following regex: [A-Za-z0-9][A-Za-z0-9_]std::string Ticket
- Steam ticket for the steam app ID and publisher key corresponding to the project name specified in the LocatorParameters. Typically obtained from the steam APIs.
worker::TcpNetworkParameters struct
Summary Parameters for configuring a TCP connection. Used by NetworkParameters. Fields
std::uint8_t MultiplexLevel =
kTcpMultiplexLevel
- Number of multiplexed TCP connections.bool NoDelay =
kTcpNoDelay
- Whether to enable TCP_NODELAY.std::uint32_t ReceiveBufferSize =
kTcpReceiveBufferSize
- Size in bytes of the TCP receive buffer.std::uint32_t SendBufferSize =
kTcpSendBufferSize
- Size in bytes of the TCP send buffer.
worker::ThreadAffinityParameters struct
Summary Parameters for configuring the affinity of threads started by SpatialOS workers. This is only intended for use on console, however support exists on all platforms except macOS where there is no strict concept of thread affinity. Instead, we set the thread policy which expresses hints to the scheduler. Affinity masks are bit masks where setting 1 in the nth least significant position means the thread will be permitted to run on the nth core. If an affinity mask is set to zero, the group of threads using that mask will have no thread affinity and be allowed to run on any logical core. Setting the affinity mask to permit a core index which does not exist is undefined behaviour, and we are not performing any checks at runtime whether the logical core count accommodates the affinity masks. Fields
std::uint64_t ReceiveThreadsAffinityMask = 0
- Affinity mask for threads related to receiving data from the runtime.std::uint64_t SendThreadsAffinityMask = 0
- Affinity mask for threads related to sending data to the runtime.std::uint64_t TemporaryThreadsAffinityMask = 0
- Affinity mask for short-lived threads.
worker::UpdateParameters struct
Summary Component update parameters. Used to modify the behaviour of sending a component update. Fields
ComponentUpdateLoopback
Loopback
- How the component update should be delivered to the worker sending the update, if at all.
worker::Variant<typename… Args> class
Summary Algebraic data type. Stores exactly one value, whose type might be any of the variadic template arguments. This is a fairly minimal implementation. Type parameters
typename... Args
Constructors
Variant(const Variant&);
Parameters:
Variant(Variant&&) = default;
Parameters:
template<typename T> Variant(T&&);
Description: Forwarding constructor for any contained type.
Parameters:
T&&
Operators
Variant& operator=(const Variant&);
Parameters:
Variant& operator=(Variant&&) = default;
Parameters:
template<typename T> Variant& operator=(T&&);
Description: Forwarding assignment operator for any contained type.
Parameters:
T&&
bool operator==(const Variant& other) const;
Description: Checks for equality.
Parameters:
const Variant&
other
bool operator!=(const Variant& other) const;
Description: Checks for inequality.
Parameters:
const Variant&
other
Methods
data<typename T>
template<typename T> T* data();
Description: Accessor for the value of any contained type. Returns nullptr if the variant does not contain the given type.
Type parameters:typename T
Returns:
T*
- data<typename T>
template<typename T> const T* data() const;
Description: Accessor for the value of any contained type. Returns nullptr if the variant does not contain the given type.
Type parameters:typename T
Returns:
const T*
swap
Variant(Variant& other);
Description: Swaps the contents with that of other.
Parameters:Variant&
other
worker::View class
Inherits from Dispatcher Summary The View is an optional data structure that maintains the known state of entities in the worker’s view of the simulation. This object should not be modified concurrently by multiple threads. In particular, a call to Process() can modify the Entities map as a side-effect, and so should not be made concurrently with any manual modification of the Entities map. Remarks This class is intended primarily as an example: using the worker::ForEachComponent functionality, a custom View can be implemented from scratch with any semantics desired. Fields
Map<EntityId, Map<ComponentId, Authority>>
ComponentAuthority
- Current authority delegations.Map<EntityId, Entity>
Entities
- Current component data for all entities in the worker’s view.
Constructors
template<typename... T> View(const Components<T...>& components);
Parameters:
const Components<T...>&
components
View(const View&) = delete;
Parameters:
View(View&&) = delete;
Parameters:
Operators
Dispatcher& operator=(const Dispatcher&) = delete;
Parameters:
Dispatcher& operator=(Dispatcher&&) = default;
Parameters:
Methods
GetAuthority<T>
template<T> Authority GetAuthority(EntityId entity_id) const;
Description: Helper function that checks if the worker has authority over a particular component of a particular entity.
Type parameters:T
- A generated component metaclass.
Parameters:
EntityId
entity_id
Returns:
Authority
worker::alpha
namespaceFunctions
- CreateDevelopmentLoginTokensAsync
Future<LoginTokensResponse> CreateDevelopmentLoginTokensAsync(const std::string& hostname, std::uint16_t port, const LoginTokensRequest& request);
Description: Calls the Development Login Service to generate login tokens.
Parameters:const std::string& hostname
- The hostname of the Development Login Service. Typically “locator.improbable.io”.std::uint16_t port
- The port number used to connect to the Development Login Service. Typically 444.const LoginTokensRequest&
request
- The request to send to the Development Login Service.
Returns:
Future<LoginTokensResponse>
- A future object for the login tokens response.
CreateDevelopmentPlayerIdentityTokenAsync
Future<PlayerIdentityTokenResponse> CreateDevelopmentPlayerIdentityTokenAsync(const std::string& hostname, std::uint16_t port, const PlayerIdentityTokenRequest& request);
Description: Calls the Development Authentication Service to generate a player identity token.
Parameters:const std::string& hostname
- The hostname of the Development Authentication Service. Typically “locator.improbable.io”.std::uint16_t port
- The port number used to connect to the Development Authentication Service. Typically 444.const PlayerIdentityTokenRequest&
request
- The request to send to the Development Authentication Service.
Returns:
Future<PlayerIdentityTokenResponse>
- A future object for the player identity token response.worker::alpha::Locator class
Summary A client which can be used to connect to a SpatialOS deployment via the locator service. This is the new flow used to connect a local worker to a cloud deployment with a player identity token and login token. Remarks This object should not be used concurrently by multiple threads. Constructors
Locator(const std::string& hostname, const LocatorParameters& params);
Description: Creates a client for the locator service.
Parameters:
const std::string& hostname
- The hostname would typically be “locator.improbable.io”.const LocatorParameters&
params
- The parameters for the locator service.
Locator(const std::string& hostname, std::uint16_t port, const LocatorParameters& params);
Description: Creates a client for the locator service.
Parameters:
const std::string& hostname
- The hostname would typically be “locator.improbable.io”.std::uint16_t port
- The port number is used to connect to the locator service. This should be set to zero if connecting to a locator service running on the cloud.const LocatorParameters&
params
- The parameters for the locator service.
Locator(const Locator&) = delete;
Parameters:
Locator(Locator&&) = default;
Parameters:
Operators
Locator& operator=(const Locator&) = delete;
Parameters:
Locator& operator=(Locator&&) = default;
Parameters:
Methods
ConnectAsync
Future<Connection> ConnectAsync(const ComponentRegistry& registry, const ConnectionParameters& params);
Description: Connects to a deployment. The deployment is specified in the login token, which is provided at construction in the LocatorParameters, along with a player identity token. These tokens can be obtained from a game authentication server.
Parameters:const ComponentRegistry&
registry
const ConnectionParameters&
params
- The connection parameters.
Returns:
Future<Connection>
- A future object for the connectionworker::alpha::LocatorParameters struct
Summary Parameters for authenticating and logging in to a SpatialOS deployment via the locator. Fields
bool EnableLogging = false
- Whether to enable logging for the Locator flow.ProtocolLoggingParameters
Logging
- Parameters for configuring logging.PlayerIdentityCredentials
PlayerIdentity
- The player identity token/login token pair used for authentication.bool UseInsecureConnection = false
- Whether to use an insecure (non-TLS) connection for local development.
worker::alpha::LoginTokenDetails class
Summary A single login token with additional details. Fields
std::string LoginToken
- The generated login token for this deployment.List<std::string>
Tags
- The tags that the deployment contains.
worker::alpha::LoginTokensRequest class
Summary The parameters used when creating login tokens. Fields
Option<std::uint32_t>
DurationSeconds
- The lifetime duration of the requested login tokens.
This is an optional field. If a value is not given, a default of 15 minutes will be used.std::string PlayerIdentityToken
- The player identity token of the player.bool UseInsecureConnection
- Whether to use an insecure (non-TLS) connection for local developmentstd::string WorkerType
- The worker type for which the requested login tokens are scoped for.
worker::alpha::LoginTokensResponse struct
Summary The result of creating login tokens. Fields
ConnectionStatus
ConnectionStatus
- Information about the status of the request.List<LoginTokenDetails>
LoginTokens
- The list of login tokens.
worker::alpha::PlayerIdentityCredentials struct
Summary Parameters for authenticating using a player identity token and login token. Fields
std::string LoginToken
- Authenticates a user to a single deployment. Obtained from a game authentication server using a player identity token.std::string PlayerIdentityToken
- Uniquely identifies a user across deployments, and is provided by a game authentication server.
worker::alpha::PlayerIdentityTokenRequest struct
Summary The parameters used when creating a player identity token (PIT). Fields
std::string DevelopmentAuthenticationToken
- The Development Authentication token used for exchanging the player identity token.std::string DisplayName
- The player’s display name.
This is an optional field.Option<std::uint32_t>
DurationSeconds
- The lifetime duration of the requested PIT.
This is an optional field. If a value is not given, a default of 24 hours will be used.std::string Metadata
- Additional metadata that is stored within the PIT. You can use this to securely attach extra attributes in a format you choose (e.g. JSON payload).
This is an optional field.std::string PlayerId
- The ID of the player to generate PIT for.bool UseInsecureConnection
- Whether to use an insecure (non-TLS) connection for local development.
worker::alpha::PlayerIdentityTokenResponse struct
Summary The result of creating a player identity token. Fields
ConnectionStatus
ConnectionStatus
- Information about the status of the request.std::string PlayerIdentityToken
- The returned player identity token.
worker::query
namespaceType aliases
using ResultType = Variant<CountResultType, SnapshotResultType>;
using Constraint = Variant<EntityIdConstraint, SphereConstraint, ComponentConstraint, AndConstraint, OrConstraint, NotConstraint>;
worker::query::AndConstraint struct
Inherits from | List<Constraint> |
Summary | Constrains a query by the conjunction of one or more constraints. |
Type aliases
using List<Constraint>::List;
worker::query::ComponentConstraint struct
Summary | Constrains a query to match only entities that have a specific component. |
Fields
ComponentId
ComponentId
worker::query::CountResultType struct
Summary | Indicates that a query should return the number of entities it matched. |
worker::query::EntityIdConstraint struct
Summary | Constrains a query to match only entities with a particular ID. |
Fields
EntityId
EntityId
worker::query::EntityQuery struct
Summary | Represents a global query for entity data across the simulation. |
Fields
Constraint
Constraint
- The filter criteria of the query.ResultType
ResultType
- Describes the way the result should be represented.
worker::query::NotConstraint struct
Summary | Constrains a query to match entities that do not match the given subconstraint. |
Fields
Constraint
Constraint
worker::query::OrConstraint struct
Inherits from | List<Constraint> |
Summary | Constrains a query by the disjunction of one or more constraints. |
Type aliases
using List<Constraint>::List;
worker::query::SnapshotResultType struct
Summary | Indicates that a query should return a component data snapshot for each matched entity. |
Fields
Option<List<ComponentId>>
ComponentIds
- If nonempty, filters the components returned in the snapshot for each entity.
worker::query::SphereConstraint struct
Summary | Constrains a query to match only entities whose position lies within a given sphere. |