Get SpatialOS

Sites

Menu

C++ API reference documentation

Table of contents

worker namespace

Nested namespaces worker::query

Type aliases

using EntityId = std::int64_t;

using ComponentId = std::uint32_t;

Functions

  • 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:

    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:

    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:

    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:

    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

  • const typename T::Data& Data

  • EntityIdEntityId

worker::AddEntityOp struct

Summary Data for an operation that indicates an entity has been added to the worker’s view of the simulation.

Fields

  • EntityIdEntityId - The ID of the entity that was added to the worker’s view of the simulation.

worker::Authority enum

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.

  • EntityIdEntityId - The ID of the target entity of this request.

  • const typename T::Request& Request - The request data.

  • 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

worker::ComponentRegistry class

Summary A type-erased registry of components.

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

  • const typename T::Update& Data

  • EntityIdEntityId

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&&) = delete;

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:

    Returns: Future<Connection>

  • 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. If timeout_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;
    

    Returns: bool - Returns true if the Connection object was created correctly and has successfully connected to SpatialOS.

  • SendAuthorityLossImminentAcknowledgement

    void SendAuthorityLossImminentAcknowledgement(EntityId entity_id, ComponentId component_id);
    

    Description: Sends an acknowledgement of the receipt of an AuthorityLossImminent authority change for a component.
    Remarks: Sending the acknowledgement signifies that this worker is ready to lose authority over the component.
    Parameters:

    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 ApplicationError.
    Type parameters:

    • typename T - A generated command metaclass.

    Parameters:

    Returns: void

  • 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:

    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, 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 component metaclass.

    Parameters:

    Returns: RequestId<OutgoingCommandRequest<T>> - Returns 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, 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:

    Returns: void

  • 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 component metaclass.

    Parameters:

    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 the interest_overrides map is unaffected. Note also that components over which the worker is authoritative are always received, regardless of interest settings.
    Parameters:

    Returns: void

  • SendComponentUpdate<typename T>

    template<typename T> void SendComponentUpdate(EntityId entity_id, typename T::Update&& update);
    

    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.
    Remarks: The provided update object is moved-from.
    Type parameters:

    • typename T - A generated component metaclass.

    Parameters:

    • EntityIdentity_id
    • typename T::Update&& update

    Returns: void

  • SendComponentUpdate<typename T>

    template<typename T> void SendComponentUpdate(EntityId entity_id, const typename T::Update& update);
    

    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.
    Remarks: The provided update object is copied and may be subsequently reused by the caller.
    Type parameters:

    • typename T - A generated component metaclass.

    Parameters:

    • EntityIdentity_id
    • const typename T::Update& update

    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:

    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:

    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:

    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:

    Returns: void

  • SendMetrics

    void SendMetrics(Metrics& metrics);
    

    Description: Sends a set of metrics for the worker to SpatialOS. Typically this function should be called periodically (e.g. once every few seconds) to report the worker’s status. Since histogram metrics are diff-based, calling this function clears each histogram in the Metrics parameter.
    Remarks: The caller should merge built-in SDK metrics reported by the last MetricsOp into the Metrics parameter before calling SendMetrics.
    Parameters:

    Returns: void

  • SendReserveEntityIdRequest

    RequestId<ReserveEntityIdRequest> SendReserveEntityIdRequest(const Option<std::uint32_t>& timeout_millis);
    

    Description: Requests SpatialOS to reserve an entity ID.
    Parameters:

    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.
    Parameters:

    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 = IMPROBABLE.WORKER.DEFAULTS.BUILT_IN_METRICS_REPORT_PERIOD_MILLIS - 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. If set to zero, this functionality is disabled.

  • bool EnableProtocolLoggingAtStartup = false - Whether to enable protocol logging at startup.

  • std::uint32_t LogMessageQueueCapacity = IMPROBABLE.WORKER.DEFAULTS.LOG_MESSAGE_QUEUE_CAPACITY - 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.

  • NetworkParametersNetwork - Parameters controlling the network connection to SpatialOS.

  • ProtocolLoggingParametersProtocolLogging - Parameters for configuring protocol logging.

  • std::uint32_t ReceiveQueueCapacity = IMPROBABLE.WORKER.DEFAULTS.RECEIVE_QUEUE_CAPACITY - 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 = IMPROBABLE.WORKER.DEFAULTS.SEND_QUEUE_CAPACITY - Number of messages that can be stored on the send queue. When the send queue is full, calls to Connection Send functions can block.

  • std::string WorkerType - Worker type (platform).

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.

  • StatusCodeStatusCode - The status code of the response.
    If the status code is ApplicationError, 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

  • std::uint32_t BuiltInMetricsReportPeriodMillis = 5000

  • std::uint32_t LogMessageQueueCapacity = 256

  • std::string LogPrefix = protocol-log-

  • std::uint32_t MaxLogFileSizeBytes = 1024 * 1024

  • std::uint32_t MaxLogFiles = 10

  • std::uint32_t RakNetHeartbeatTimeoutMillis = 60000

  • std::uint32_t ReceiveQueueCapacity = 4096

  • std::uint32_t SendQueueCapacity = 4096

  • std::uint8_t TcpMultiplexLevel = 32

  • bool TcpNoDelay = false

  • std::uint32_t TcpReceiveBufferSize = 65536

  • std::uint32_t TcpSendBufferSize = 65536

  • bool UseExternalIp = 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

  • EntityIdEntityId - 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.

  • StatusCodeStatusCode - 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::string DeploymentName - The name of the deployment.

  • std::string Description - Description of this deployment.

worker::DeploymentList struct

Summary A deployment list obtained via GetDeploymentListAsync.

Fields

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&&) = default;

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:

    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:

    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:

    Returns: CallbackKey

  • OnLogMessage

    CallbackKey OnLogMessage(const Callback<LogMessageOp>& callback);
    

    Description: Registers a callback to be invoked when the SDK logs a message.
    Parameters:

    Returns: CallbackKey

  • OnMetrics

    CallbackKey OnMetrics(const Callback<MetricsOp>& callback);
    

    Description: Registers a callback to be invoked when the SDK reports built-in metrics.
    Parameters:

    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:

    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:

    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:

    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:

Entity& operator=(Entity&& entity) = default;

Parameters:

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 for CountResultType queries.
    Note that a best-effort attempt is made to get results when the status code is ApplicationError. 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 ApplicationError. 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).

  • StatusCodeStatusCode - The status code of the response.

worker::FlagUpdateOp struct

Summary Data for an operation that indicates a worker flag has been created, deleted or its value has changed.

Fields

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:

    Returns: bool

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:

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 component 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::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, List is consistent with other instantiations, and has the same interface.

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:

bool operator!=(const List& other) const;

Description: Checks for inequality.
Parameters:

reference operator[](size_type pos);

Description: Access an arbitrary element.
Parameters:

const_reference operator[](size_type pos) const;

Description: Access an arbitrary element.
Parameters:

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:

    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:

    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:

    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:

    Returns: iterator

  • insert

    iterator insert(const_iterator pos, size_type count, const T& value);
    

    Description: Inserts count copies of the given element.
    Parameters:

    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:

    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 either “locator.improbable.io” (for production) or “locator-staging.improbable.io” (for staging).

  • 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:

    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

worker::LocatorParameters struct

Summary Parameters for authenticating and logging in to a SpatialOS deployment via the locator.

Fields

worker::LogLevel enum

Fields

worker::LogMessageOp struct

Summary Data for an operation that provides a log message from the SDK.

Fields

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:

bool operator!=(const Map& other) const;

Description: Checks for inequality.
Parameters:

key_type operator[](mapped_type key);

Description: Access an element by key.
Parameters:

key_type operator[](mapped_type key) const;

Description: Access an element by key.
Parameters:

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:

    Returns: 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:

    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:

    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:

    Returns: void

worker::MetricsOp struct

Summary Data for an operation that provides a report on built-in metrics from the SDK.

Fields

worker::NetworkConnectionType enum

Fields

worker::NetworkParameters struct

Summary Parameters for configuring the network connection.

Fields

  • NetworkConnectionTypeConnectionType = IMPROBABLE.WORKER.NETWORK_CONNECTION_TYPE.TCP - Type of network connection to use when connecting to SpatialOS.

  • RakNetNetworkParametersRakNet - Connection parameters specific to RakNet connections.

  • TcpNetworkParametersTcp - Connection parameters specific to TCP connections.

  • bool UseExternalIp = IMPROBABLE.WORKER.DEFAULTS.USE_EXTERNAL_IP - 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 usuallypassed 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:

template<typename U> bool operator!=(const Option<U>& other) const;

Description: Checks for inequality.
Parameters:

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:

    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 = IMPROBABLE.WORKER.DEFAULTS.LOG_PREFIX - Log file names are prefixed with this prefix, are numbered, and have the extension .log.

  • std::uint32_t MaxLogFileSizeBytes = IMPROBABLE.WORKER.DEFAULTS.MAX_LOG_FILE_SIZE_BYTES - Once the size of a log file reaches this size, a new log file is created.

  • std::uint32_t MaxLogFiles = IMPROBABLE.WORKER.DEFAULTS.MAX_LOG_FILES - 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 = IMPROBABLE.WORKER.DEFAULTS.RAK_NET_HEARTBEAT_TIMEOUT_MILLIS - 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

worker::RemoveEntityOp struct

Summary Data for an operation that indicates an entity has been removed from the worker’s view of the simulation.

Fields

  • EntityIdEntityId - 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.

  • StatusCodeStatusCode - 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.

  • StatusCodeStatusCode - 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:

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:

Methods

  • WriteEntity

    Option<std::string> WriteEntity(EntityId entity_id, const Entity& entity);
    

    Description: Writes the EntityId and Entity pair to the output stream.
    Parameters:

    Returns: Option<std::string> - An error message if error occurred.

worker::StatusCode enum

Fields

  • StatusCodeApplicationError - 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 ApplicationError if an entity ID reservation has expired, and SendEntityQueryRequest will return ApplicationError if the result set is incomplete.

  • StatusCodeAuthorityLost - The request could not be executed by a worker, either because it lost authority while handling the request, or because no worker was authoritative 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.

  • StatusCodeInternalError - Some other error occurred. This likely indicates a bug in SpatialOS and should be reported.

  • StatusCodeNotFound - 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.

  • StatusCodePermissionDenied - 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.

  • StatusCodeSuccess - The request was successfully executed and returned a response.

  • StatusCodeTimeout - 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 = IMPROBABLE.WORKER.DEFAULTS.TCP_MULTIPLEX_LEVEL - Number of multiplexed TCP connections.

  • bool NoDelay = IMPROBABLE.WORKER.DEFAULTS.TCP_NO_DELAY - Whether to enable TCP_NODELAY.

  • std::uint32_t ReceiveBufferSize = IMPROBABLE.WORKER.DEFAULTS.TCP_RECEIVE_BUFFER_SIZE - Size in bytes of the TCP receive buffer.

  • std::uint32_t SendBufferSize = IMPROBABLE.WORKER.DEFAULTS.TCP_SEND_BUFFER_SIZE - Size in bytes of the TCP send buffer.

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:

bool operator!=(const Variant& other) const;

Description: Checks for inequality.
Parameters:

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:

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

Constructors

template<typename... T> View(const Components<T...>& components);

Parameters:

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:

    Returns: Authority

worker::query namespace

Type 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

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

worker::query::EntityQuery struct

Summary Represents a global query for entity data across the simulation.

Fields

  • ConstraintConstraint - The filter criteria of the query.

  • ResultTypeResultType - 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

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

worker::query::SphereConstraint struct

Summary Constrains a query to match only entities whose position lies within a given sphere.

Fields

  • double Radius - The radius of the sphere.

  • double X - The X-coordinate of the center of the sphere.

  • double Y - The Y-coordinate of the center of the sphere.

  • double Z - The Z-coordinate of the center of the sphere.

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums