Get SpatialOS

Sites

Menu
These are the docs for 13.7, an old version of SpatialOS. The docs for this version are frozen: we do not correct, update or republish them. 13.8 is the newest →

C# API reference documentation

Table of contents

Improbable namespace

Nested namespaces Improbable.Collections, Improbable.Worker

Improbable.EntityId struct

Implements System.IEquatable<EntityId>
Summary A unique identifier used to look up an entity in SpatialOS.
Remarks Instances of this type should be treated as a transient identifiers that will not be consistent between different runs of the same simulation.

Fields and Properties

  • readonly long Id - The value of the EntityId.
    Though this value is numeric, you should not perform any mathematical operations on it.

Constructors

EntityId(long id)

Description: Constructs a new instance of an EntityId.
Parameters:

  • long id

Methods

  • IsValid

    bool IsValid()
    

    Description: Whether this represents a valid SpatialOS entity ID. Specifically, Id > 0
    Returns: bool - True iff valid.

    Improbable.Collections namespace

    Improbable.Collections.IDeepCopyable<T> interface

    Type parameters

    • T

    Methods

    • DeepCopy
    T DeepCopy()
    

    Returns: T

Improbable.Collections.List<T> class

Implements System.IEquatable<List<T>>, IDeepCopyable<List<T>>
Inherits from System.Collections.Generic.List<T>
Summary This class is the same as System.Collections.Generic.List , except that it is augmented with proper structural equality and GetHashCode().

Type parameters

  • T

Methods

  • DeepCopy

    List<T> DeepCopy()
    

    Description: Checks if the types in the list are either primitive or implement the IDeepCopyable interface, then performs a deep copy of the list if they are and throws an InvalidOperationException otherwise
    Returns: List<T> - Returns a deep copy of this List. If the List is empty it will return a new List.

    Improbable.Collections.Map<K, V> class

    Implements System.Collections.Generic.IDictionary<K, V>, System.IEquatable<Map<K, V>>, IDeepCopyable<Map<K, V>>
    Summary Very similar to the usual C# Dictionary. However: iteration order is guaranteed to be identical to insertion order; the dictionary can be traversed without allocation using the First and Last modifiers; and it properly implements structural equality and GetHashCode().

    Type parameters

    • K
    • V

    Methods

    • DeepCopy
    Map<K, V> DeepCopy()
    

    Description: Checks if the types in the map are either primitive or implement the IDeepCopyable interface, then performs a deep copy of the map if they are and throws an InvalidOperationException otherwise
    Returns: Map<K, V> - Returns a deep copy of this Map. If the Map is empty it will return a new Map.

Improbable.Collections.Option<T> class

Implements System.IEnumerable<T>, System.IEquatable<Option<T>>, IDeepCopyable<Option<T>>
Summary Represents an optional value. Works with both value types (in which case it behaves similarly to a nullable type) and non-value types. Only allocates if a value is present.

Type parameters

  • T

Fields and Properties

  • int Count { get; } - Returns 1 if this Option contains a value, and 0 otherwise.

  • bool HasValue { get; } - Returns true if this Option contains a value, and false otherwise

  • T Value { get; } - Returns the value stored in this Option. Throws InvalidOperationException if no value is present.

Constructors

Option(T newValue)

Description: Creates an Option containing the given value.
Parameters:

  • T newValue

Methods

  • Clear

    void Clear()
    

    Description: Removes the value from this Option, if present.
    Returns: void

    • DeepCopy
    Option<T> DeepCopy()
    

    Description: Checks if the type in the Option is either primitive or implements the IDeepCopyable interface, then performs a deep copy of the Option if it is and throws an InvalidOperationException otherwise.
    Returns: Option<T> - A deep copy of this Option. If the Option is empty it will return a new Option

  • Set

    void Set(T newValue)
    

    Description: Assigns the value contained in this Option, replacing the existing value (if present).
    Parameters:

    • T newValue

    Returns: void

    • TryGetValue
    bool TryGetValue(out T result)
    

    Description: Returns true and assigns to result if this Option contains a value; returns false otherwise.
    Parameters:

    • out T result

    Returns: bool

Improbable.Worker namespace

Summary The Worker namespace contains the APIs you can use to build a worker.
Nested namespaces Improbable.Worker.Alpha, Improbable.Worker.Query

Improbable.Worker.AddComponentOp<C> 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

  • C: IComponentMetaclass - The metaclass identifying the component.

Fields and Properties

Improbable.Worker.AddEntityOp struct

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

Fields and Properties

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

Improbable.Worker.Authority enum

Summary Enumerates the possible states of an AuthorityChangeOp. Authoritative and NotAuthoritative are used to indicate the worker has gained or lost authority (respectively) over a particular component for an entity. AuthorityLossImminent 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

Improbable.Worker.AuthorityChangeOp struct

Summary Data for an operation that indicates the worker’s authority over a component for an entity has been changed.

Fields and Properties

Improbable.Worker.Bytes class

Implements System.IEquatable<Bytes>
Summary A wrapper for a byte array, with structural equality and hash code.
Remarks This is used by generated schema types to represent bytes fields.

Fields and Properties

  • byte[] BackingArray { get; } - Directly returns the backing byte array wrapped by this Bytes object.
    Warning: since this method does not copy the array, modifications made to the returned array will be reflected by this Bytes object. In particular, it is illegal to modify the source array concurrently with other operations on this object.

  • int Length { get; }

  • byte this[int index] { get; set; }

Methods

  • CopyOf

    static Bytes CopyOf(byte[] data)
    

    Description: Creates a new Bytes object wrapping a copy of the given byte array.
    Parameters:

    • byte[] data

    Returns: Bytes

    • CopyOf
    static Bytes CopyOf(byte* buffer, uint length)
    

    Description: Creates a new Bytes object wrapping a copy of the given native byte buffer.
    Parameters:

    • byte* buffer
    • uint length

    Returns: Bytes

  • FromBackingArray

    static Bytes FromBackingArray(byte[] data)
    

    Description: Creates a new Bytes object directly wrapping the given byte array.
    Remarks: Warning: since this method does not copy the array, modifications made to the source array will be reflected by this Bytes object. In particular, it is illegal to modify the source array concurrently with other operations on this object.
    Parameters:

    • byte[] data

    Returns: Bytes

    • GetCopy
    byte[] GetCopy()
    

    Description: Returns a copy of the byte array wrapped by this Bytes object.
    Returns: byte[]

Improbable.Worker.ClientError class

Summary Exposes a global hook to be invoked when errors are encountered in generated code.

Fields and Properties

  • static Action<Exception> ExceptionCallback { set; } - Sets the Action to be invoked when a client exception is detected. Throwing an exception from within this callback is not supported.

Methods

  • LogClientException

    static void LogClientException(Exception exception)
    

    Description: Invokes the global client error hook to handle an exception.
    Parameters:

    • Exception exception

    Returns: void

    Improbable.Worker.CommandParameters class

    Summary Command parameters. Used to modify the behaviour of a command request.

    Fields and Properties

    • bool AllowShortCircuiting - Allow command requests to bypass the bridge when this worker is authoritative over the target entity-component.

    Improbable.Worker.CommandRequestOp<C> 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

    • C: ICommandMetaclass - The metaclass identifying the command.

    Fields and Properties

    • List<string>CallerAttributeSet - The attribute set of the worker that initiated this request.

    • string CallerWorkerId - The ID of the worker that initiated this request.

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

    • ICommandRequest<C>Request - The request data.

    • RequestId<IncomingCommandRequest<C>>RequestId - The incoming request ID.
      Should be passed to SendCommandResponse in order to respond to this request.

    • uint TimeoutMillis - An upper bound on the timeout of this request. Any response sent after the timeout has expired will be ignored by the SDK.

    Improbable.Worker.CommandResponseOp<C> 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

    • C: ICommandMetaclass - The metaclass identifying the command.

    Fields and Properties

    Improbable.Worker.ComponentUpdateLoopback enum

    Summary Component update loopback describes how the component update is delivered to the worker sending the update, if at all.

    Fields

    • ComponentUpdateLoopbackNone - The update is not delivered to the worker sending the update.

    • ComponentUpdateLoopbackShortCircuited - The update is locally added to the op list of, and therefore received by, the worker sending the update.

    Improbable.Worker.ComponentUpdateOp<C> struct

    Summary Data for an operation that indicates the component for an entity has been updated.

    Type parameters

    • C: IComponentMetaclass - The metaclass identifying the component.

    Fields and Properties

    Improbable.Worker.Connection class

    Implements System.IDisposable
    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.

    Fields and Properties

    • bool IsConnected { get; } - Returns true if the Connection object was created correctly and has successfully connected to SpatialOS.

    Methods

    • ConnectAsync
    static Future<Connection> ConnectAsync(string hostname, uint port, string workerId, ConnectionParameters connectionParams)
    

    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:

    • string hostname
    • uint port
    • string workerId
    • ConnectionParametersconnectionParams - Parameters controlling the connection to SpatialOS.

    Returns: Future<Connection>

  • Dispose

    void Dispose()
    

    Returns: void

    • GetOpList
    OpList GetOpList(uint timeoutMillis)
    

    Description: Retrieves the list of operations that have occurred since the last call to this function.
    Parameters:

    • uint timeoutMillis - 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 timeoutMillis is zero, the function is non-blocking.

    Returns: OpList - A list of operations to be passed to Process

  • GetWorkerAttributes

    List<string> GetWorkerAttributes()
    

    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<string> - The list of attributes of the worker as assigned by the SpatialOS runtime when the worker connects.

    • GetWorkerFlag
    Option<string> GetWorkerFlag(string flagName)
    

    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:

    • string flagName - The name of the worker flag to retrieve.

    Returns: Option<string> - The value of the worker flag with the given name. If no such worker flag exists, an empty option is returned.

  • GetWorkerId

    string GetWorkerId()
    

    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: string - The ID of the worker as assigned by the SpatialOS runtime when the worker connects.

    • SendAddComponent<C>
    void SendAddComponent<C>(EntityId entityId, IComponentData<C> data, UpdateParameters parameters) where C: IComponentMetaclass
    

    Description: Adds a new component to the given entity in SpatialOS.
    Remarks: The behaviour is undefined if the component data object is mutated after it is sent; use SendAddComponent(data.DeepCopy()) if you intend to hold on to the component data and modify it later. This method 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 method, 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 None.
    Type parameters:

    • C: IComponentMetaclass - The metaclass identifying the component.

    Parameters:

    Returns: void

  • SendAuthorityLossImminentAcknowledgement<C>

    void SendAuthorityLossImminentAcknowledgement<C>(EntityId entityId) where C: IComponentMetaclass
    

    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 for the given entity.
    Type parameters:

    • C: IComponentMetaclass - The metaclass identifying the component.

    Parameters:

    Returns: void

    • SendCommandFailure<C>
    void SendCommandFailure<C>(RequestId<IncomingCommandRequest<C>> requestId, string message) where C: ICommandMetaclass
    

    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:

    • C: ICommandMetaclass - The metaclass identifying the command.

    Parameters:

    Returns: void

  • SendCommandRequest<C>

    RequestId<OutgoingCommandRequest<C>> SendCommandRequest<C>(EntityId entityId, ICommandRequest<C> request, Option<uint> timeoutMillis, CommandParameters parameters = default(CommandParameters)) where C: ICommandMetaclass
    

    Description: Sends a command request to a component on a specific target entity.
    Remarks: Like SendComponentUpdate, the behaviour is undefined if the request is mutated after it is sent; SendCommandRequest(request.DeepCopy()) if you intend to modify the object later.
    Type parameters:

    • C: ICommandMetaclass - The metaclass identifying the command.

    Parameters:

    Returns: RequestId<OutgoingCommandRequest<C>> - A request ID which can be used to identify a response to the command via the OnCommandResponse callback.

    • SendCommandResponse<C>
    void SendCommandResponse<C>(RequestId<IncomingCommandRequest<C>> requestId, ICommandResponse<C> response) where C: ICommandMetaclass
    

    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: Like SendComponentUpdate, the behaviour is undefined if the response is mutated after it is sent; SendCommandResponse(response.DeepCopy()) if you intend to modify the object later. This method does not check whether the worker currently has authority over the component.
    Type parameters:

    • C: ICommandMetaclass - The metaclass identifying the command.

    Parameters:

    Returns: void

  • SendComponentInterest

    void SendComponentInterest(EntityId entityId, System.Collections.Generic.Dictionary<uint, InterestOverride> interestOverrides)
    

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

    • EntityIdentityId
    • System.Collections.Generic.Dictionary<uint, InterestOverride> interestOverrides

    Returns: void

    • SendComponentUpdate<C>
    void SendComponentUpdate<C>(EntityId entityId, IComponentUpdate<C> update) where C: IComponentMetaclass
    

    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 behaviour is undefined if the update is mutated after it is sent; use SendComponentUpdate(update.DeepCopy()) if you intend to hold on to the update and modify it later. This method does not check whether the worker currently has authority over the component.
    Type parameters:

    • C: IComponentMetaclass - The metaclass identifying the component.

    Parameters:

    Returns: void

  • SendComponentUpdate<C>

    void SendComponentUpdate<C>(EntityId entityId, IComponentUpdate<C> update, UpdateParameters parameters = default(UpdateParameters)) where C: IComponentMetaclass
    

    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 None.
    Remarks: The behaviour is undefined if the update is mutated after it is sent; use SendComponentUpdate(update.DeepCopy()) if you intend to hold on to the update and modify it later. This method does not check whether the worker currently has authority over the component.
    Type parameters:

    • C: IComponentMetaclass - The metaclass identifying the component.

    Parameters:

    Returns: void

    • SendCreateEntityRequest
    RequestId<CreateEntityRequest> SendCreateEntityRequest(Entity entity, Option<EntityId> entityId, Option<uint> timeoutMillis)
    

    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 entityId, Option<uint> timeoutMillis)
    

    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(EntityQuery entityQuery, Option<uint> timeoutMillis)
    

    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, string loggerName, string message, Option<EntityId> entityId = new Option<EntityId>())
    

    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. Since histogram metrics are diff-based, calling this function clears each histogram in the Metrics parameter.
    Parameters:

    Returns: void

  • SendRemoveComponent<C>

    void SendRemoveComponent<C>(EntityId entityId, UpdateParameters parameters) where C: IComponentMetaclass
    

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

    • C: IComponentMetaclass - The metaclass identifying the component.

    Parameters:

    Returns: void

    • SendReserveEntityIdRequest
    RequestId<ReserveEntityIdRequest> SendReserveEntityIdRequest(Option<uint> timeoutMillis)
    

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

    • Option<uint>timeoutMillis - 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(uint numberOfEntityIds, Option<uint> timeoutMillis)
    

    Description: Requests SpatialOS to reserve multiple entity IDs.
    Parameters:

    • uint numberOfEntityIds
    • Option<uint>timeoutMillis - 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

Improbable.Worker.ConnectionParameters class

Summary Parameters for creating a Connection and connecting to SpatialOS.

Fields and Properties

  • uint BuiltInMetricsReportPeriodMillis =BuiltInMetricsReportPeriodMillis - 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 =EnableDynamicComponents - 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.

  • uint LogMessageQueueCapacity =LogMessageQueueCapacity - 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.

  • uint ReceiveQueueCapacity =ReceiveQueueCapacity - 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.

  • uint SendQueueCapacity =SendQueueCapacity - Number of messages that can be stored on the send queue. When the send queue is full, calls to Connection Send functions can block.

  • ThreadAffinityParametersThreadAffinity - Parameters for configuring thread affinity.

  • string WorkerType - Worker type (platform).

Improbable.Worker.ConnectionStatus struct

Summary Information about the status of a network request.

Fields and Properties

  • ConnectionStatusCodeCode - The status of the request.

  • string Detail - Detailed, human readable description of the connection status. Will be “OK” if no error occurred.

Improbable.Worker.ConnectionStatusCode enum

Summary Possible status codes for a remote call, connection attempt or connection migration attempt.

Fields

  • ConnectionStatusCodeCancelled - Attempt was cancelled by the caller. Currently shouldn’t happen; reserved for future use.

  • ConnectionStatusCodeCapacityExceeded - Failed because the deployment associated with the provided login token was at capacity. Retryable.

  • ConnectionStatusCodeInternalError - Protocol violation, or some part of the system otherwise behaved in an unexpected way. Not expected to occur in normal operation.

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

  • ConnectionStatusCodeLoginTokenExpired - The login token provided by the caller has expired. Generate a new one and retry.

  • ConnectionStatusCodeNetworkError - Failed due to a networking issue or otherwise unreachable host.

  • ConnectionStatusCodePlayerIdentityTokenExpired - The player identity token provided by the caller has expired. Generate a new one and retry.

  • ConnectionStatusCodeRateExceeded - Failed due to rate-limiting of new connections to the deployment associated with the provided login token. Retryable.

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

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

  • ConnectionStatusCodeSuccess - The remote call was successful, or we are successfully connected.

  • ConnectionStatusCodeTimeout - A timeout provided by the caller or enforced by the system was exceeded. Can be retried.

Improbable.Worker.CreateEntityRequest class

Summary Type parameter for entity creation request IDs.

Improbable.Worker.CreateEntityResponseOp struct

Summary A response indicating the result of an entity creation request.

Fields and Properties

  • Option<EntityId>EntityId - If successful, the entity ID of the newly created entity.

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

Improbable.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 and Properties

  • bool InCriticalSection

Improbable.Worker.Defaults class

Summary Default values for various configuration parameters.

Fields and Properties

  • uint BuiltInMetricsReportPeriodMillis = 5000

  • uint DefaultCommandTimeoutMillis = 5000

  • bool EnableDynamicComponents = false

  • byte ErasureCodecOriginalPacketCount = 10

  • byte ErasureCodecRecoveryPacketCount = 2

  • byte ErasureCodecWindowSize = 16

  • ulong HeartbeatIntervalMillis = 10000

  • ulong HeartbeatTimeoutMillis = 60000

  • bool KcpEarlyRetransmission = true

  • bool KcpEnableErasureCodec = false

  • bool KcpFastRetransmission = true

  • uint KcpMinRtoMillis = 10

  • uint KcpMultiplexLevel = 32

  • bool KcpNonConcessionalFlowControl = true

  • uint KcpRecvWindowSize = 1000

  • uint KcpSendWindowSize = 500

  • uint KcpUpdateIntervalMillis = 10

  • uint LogMessageQueueCapacity = 256

  • string LogPrefix = protocol-log-

  • uint MaxLogFileSizeBytes = 1024 * 1024

  • uint MaxLogFiles = 10

  • uint RakNetHeartbeatTimeoutMillis = 60000

  • uint ReceiveQueueCapacity = 4096

  • uint SendQueueCapacity = 4096

  • byte TcpMultiplexLevel = 32

  • bool TcpNoDelay = false

  • uint TcpReceiveBufferSize = 65536

  • uint TcpSendBufferSize = 65536

  • bool UseExternalIp = false

Improbable.Worker.DeleteEntityRequest class

Summary Type parameter for entity deletion request IDs.

Improbable.Worker.DeleteEntityResponseOp struct

Summary A response indicating the result of an entity deletion request.

Fields and Properties

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

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

Improbable.Worker.Deployment struct

Summary Details for a specific deployment obtained via GetDeploymentListAsync.

Fields and Properties

  • string AssemblyName - The name of the assembly used by this deployment.

  • string DeploymentName - The name of the deployment.

  • string Description - Description of this deployment.

  • uint UsersCapacity - Total user capacity of the deployment.

  • uint UsersConnected - Number of users currently connected to the deployment.

Improbable.Worker.DeploymentList struct

Summary A deployment list obtained via GetDeploymentListAsync.

Fields and Properties

  • System.Collections.Generic.List<Deployment> Deployments - List of accessible deployments for the given project.

  • string Error - Will be non-null if an error occurred.

Improbable.Worker.DisconnectOp struct

Summary Data for an operation that indicates the Connection has disconnected and can no longer be used

Fields and Properties

  • string Reason

Improbable.Worker.Dispatcher class

Implements System.IDisposable
Summary A Dispatcher processes OpLists retrieved from the Connection and invokes appropriate callbacks.
Remarks This object should not be modified concurrently by multiple threads.

Methods

  • Dispose

    void Dispose()
    

    Returns: void

    • OnAddComponent<C>
    ulong OnAddComponent<C>(Action<AddComponentOp<C>> callback) where C: IComponentMetaclass
    

    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:

    • C: IComponentMetaclass - The metaclass identifying the component.

    Parameters:

    • Action<AddComponentOp<C>> callback

    Returns: ulong

  • OnAddEntity

    ulong OnAddEntity(Action<AddEntityOp> callback)
    

    Description: Registers a callback to be invoked when an entity is added to the worker’s view of the simulation.
    Parameters:

    • Action<AddEntityOp> callback

    Returns: ulong

    • OnAuthorityChange<C>
    ulong OnAuthorityChange<C>(Action<AuthorityChangeOp<C>> callback) where C: IComponentMetaclass
    

    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:

    • C: IComponentMetaclass - The metaclass identifying the component.

    Parameters:

    • Action<AuthorityChangeOp<C>> callback

    Returns: ulong

  • OnCommandRequest<C>

    ulong OnCommandRequest<C>(Action<CommandRequestOp<C>> callback) where C: ICommandMetaclass, new()
    

    Description: Registers a callback to be invoked when a command request is received for a particular component.
    Type parameters:

    • C: ICommandMetaclass, new() - The metaclass identifying the command.

    Parameters:

    • Action<CommandRequestOp<C>> callback

    Returns: ulong

    • OnCommandResponse<C>
    ulong OnCommandResponse<C>(Action<CommandResponseOp<C>> callback) where C: ICommandMetaclass, new()
    

    Description: Registers a callback to be invoked when a command response is received for a particular component.
    Type parameters:

    • C: ICommandMetaclass, new() - The metaclass identifying the command.

    Parameters:

    • Action<CommandResponseOp<C>> callback

    Returns: ulong

  • OnComponentUpdate<C>

    ulong OnComponentUpdate<C>(Action<ComponentUpdateOp<C>> callback) where C: IComponentMetaclass
    

    Description: Registers a callback to be invoked when a particular component is updated for an entity.
    Type parameters:

    • C: IComponentMetaclass - The metaclass identifying the component.

    Parameters:

    • Action<ComponentUpdateOp<C>> callback

    Returns: ulong

    • OnCreateEntityResponse
    ulong OnCreateEntityResponse(Action<CreateEntityResponseOp> callback)
    

    Description: Registers a callback to be invoked when an entity creation response is received.
    Parameters:

    • Action<CreateEntityResponseOp> callback

    Returns: ulong

  • OnCriticalSection

    ulong OnCriticalSection(Action<CriticalSectionOp> callback)
    

    Description: Registers a callback to be invoked when the message stream enters or leaves a critical section.
    Parameters:

    • Action<CriticalSectionOp> callback

    Returns: ulong

    • OnDeleteEntityResponse
    ulong OnDeleteEntityResponse(Action<DeleteEntityResponseOp> callback)
    

    Description: Registers a callback to be invoked when an entity deletion response is received.
    Parameters:

    • Action<DeleteEntityResponseOp> callback

    Returns: ulong

  • OnDisconnect

    ulong OnDisconnect(Action<DisconnectOp> callback)
    

    Description: Registers a callback to be invoked when the Connection has disconnected and can no longer be used.
    Parameters:

    • Action<DisconnectOp> callback

    Returns: ulong

    • OnEntityQueryResponse
    ulong OnEntityQueryResponse(Action<EntityQueryResponseOp> callback)
    

    Description: Registers a callback to be invoked when an entity query response is received.
    Parameters:

    • Action<EntityQueryResponseOp> callback

    Returns: ulong

  • OnFlagUpdate

    ulong OnFlagUpdate(Action<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:

    • Action<FlagUpdateOp> callback

    Returns: ulong

    • OnLogMessage
    ulong OnLogMessage(Action<LogMessageOp> callback)
    

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

    • Action<LogMessageOp> callback

    Returns: ulong

  • OnMetrics

    ulong OnMetrics(Action<MetricsOp> callback)
    

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

    • Action<MetricsOp> callback

    Returns: ulong

    • OnRemoveComponent<C>
    ulong OnRemoveComponent<C>(Action<RemoveComponentOp<C>> callback) where C: IComponentMetaclass
    

    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:

    • C: IComponentMetaclass - The metaclass identifying the component.

    Parameters:

    • Action<RemoveComponentOp<C>> callback

    Returns: ulong

  • OnRemoveEntity

    ulong OnRemoveEntity(Action<RemoveEntityOp> callback)
    

    Description: Registers a callback to be invoked when an entity is removed from the worker’s view of the simulation.
    Parameters:

    • Action<RemoveEntityOp> callback

    Returns: ulong

    • OnReserveEntityIdResponse
    ulong OnReserveEntityIdResponse(Action<ReserveEntityIdResponseOp> callback)
    

    Description: Registers a callback to be invoked when an entity ID reservation response is received.
    Parameters:

    • Action<ReserveEntityIdResponseOp> callback

    Returns: ulong

  • OnReserveEntityIdsResponse

    ulong OnReserveEntityIdsResponse(Action<ReserveEntityIdsResponseOp> callback)
    

    Description: Registers a callback to be invoked when a multiple entity ID reservation response is received.
    Parameters:

    • Action<ReserveEntityIdsResponseOp> callback

    Returns: ulong

    • Process
    void Process(OpList opList)
    

    Description: Processes an OpList and invokes registered callbacks.
    Remarks: Any exceptions thrown by registered callbacks will be propagated to the caller of Process.
    Parameters:

    Returns: void

  • Remove

    void Remove(ulong callbackKey)
    

    Description: Unregisters a callback identified by its CallbackKey, as returned from the registration function.
    Remarks: If the key does not exist, an exception will be thrown.
    Parameters:

    • ulong callbackKey

    Returns: void

    Improbable.Worker.Dynamic class

    Summary Provides facilities for manipulating components in a type-safe way when the component type is not known statically.

    Methods

    • ForComponent
    static void ForComponent(uint componentId, Handler handler)
    

    Description: Invokes the Accept method on the provided handler with appropriate arguments for the component whose ID matches the given component ID.
    Parameters:

    Returns: void

  • ForEachComponent

    static void ForEachComponent(Handler handler)
    

    Description: Invokes the Accept method on the the provided handler with appropriate arguments for every known component.
    Parameters:

    Returns: void

    • GetComponentId<C>
    static uint GetComponentId<C>()
    

    Description: Returns the component ID of a given component.
    Type parameters:

    • C - The metaclass identifying the component.

    Returns: uint

  • GetComponentIds

    static System.Collections.Generic.HashSet<uint> GetComponentIds()
    

    Description: Returns the set of all known component IDs.
    Returns: System.Collections.Generic.HashSet<uint>

    Nested classes

    • Improbable.Worker.Dynamic.Handler - This interface should be implemented to provide component-specific behaviour for the ForComponent and ForEachComponent methods.

    Improbable.Worker.Dynamic.Handler interface

    Summary This interface should be implemented to provide component-specific behaviour for the ForComponent and ForEachComponent methods.

    Methods

    • Accept<C>
    void Accept<C>(C metaclass) where C: IComponentMetaclass
    

    Description: Called by ForComponent and ForEachComponent, passing the metaclass of a particular component.
    Type parameters:

    • C: IComponentMetaclass - The metaclass identifying the component.

    Parameters:

    • C metaclass

    Returns: void

Improbable.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.

Methods

  • Add<C>

    void Add<C>(IComponentData<C> data) where C: IComponentMetaclass
    

    Description: Creates the given component by copying the provided initial data. Has no effect if the entity already has the given component.
    Type parameters:

    • C: IComponentMetaclass - The metaclass identifying the component.

    Parameters:

    Returns: void

    • Get<C>
    Option<IComponentData<C>> Get<C>() where C: IComponentMetaclass
    

    Description: Retrieves data for the given component. Returns an empty option if the entity does not have the given component.
    Type parameters:

    • C: IComponentMetaclass - The metaclass identifying the component.

    Returns: Option<IComponentData<C>>

  • GetComponentIds

    System.Collections.Generic.HashSet<uint> GetComponentIds()
    

    Description: Returns the set of IDs of the components present in this entity.
    Returns: System.Collections.Generic.HashSet<uint>

    • Remove<C>
    void Remove<C>() where C: IComponentMetaclass
    

    Description: Removes a component.
    Type parameters:

    • C: IComponentMetaclass - The metaclass identifying the component.

    Returns: void

  • Update<C>

    void Update<C>(IComponentUpdate<C> update) where C: IComponentMetaclass
    

    Description: Applies an update to the given component. Has no effect if the entity does not have the given component.
    Type parameters:

    • C: IComponentMetaclass - The metaclass identifying the component.

    Parameters:

    Returns: void

    Improbable.Worker.EntityQueryRequest class

    Summary Type parameter for entity query request IDs.

    Improbable.Worker.EntityQueryResponseOp struct

    Summary A response indicating the result of an entity query request.

    Fields and Properties

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

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

    Improbable.Worker.ErasureCodecParameters class

    Summary Parameters to configure erasure coding, a forward error correction technique which increases bandwidth usage but may improve latency on unreliable networks.

    Fields and Properties

    • byte OriginalPacketCount =ErasureCodecOriginalPacketCount - Number of consecutive packets to send before sending redundant recovery packets.

    • byte RecoveryPacketCount =ErasureCodecRecoveryPacketCount - 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.

    • byte WindowSize =ErasureCodecWindowSize - 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.

    Improbable.Worker.FlagUpdateOp struct

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

    Fields and Properties

    Improbable.Worker.Future<T> class

    Implements System.IDisposable
    Summary A class representing the standard future concept. It can be used for both synchronous and asynchronous interaction.

    Type parameters

    • T

    Methods

    • Dispose
    void Dispose()
    

    Returns: void

  • Get

    T Get()
    

    Description: Waits until the result becomes available, and returns it. If the result was already obtained by a previous call to Get() or Get(timeoutMillis), this function returns it immediately.
    Returns: T - The result.

    • Get
    Option<T> Get(uint timeoutMillis)
    

    Description: Waits for the result to become available. Blocks until the specified timeout has elapsed or the result has become available, whichever comes first. If the result was already obtained by a previous call to Get() or Get(timeoutMillis), this function returns it immediately.
    Parameters:

    • uint timeoutMillis - The time to wait for the result to become available.

    Returns: Option<T> - The result if it is available; an empty option, otherwise.

Improbable.Worker.HeartbeatParameters class

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 and Properties

  • ulong IntervalMillis =HeartbeatIntervalMillis - 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.

  • ulong TimeoutMillis =HeartbeatTimeoutMillis - Time, in milliseconds, after which the peer will be deemed unresponsive.

Improbable.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(System.Collections.Generic.IEnumerable<double> upperBounds)

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:

  • System.Collections.Generic.IEnumerable<double> upperBounds

Methods

  • 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

Nested classes

  • Improbable.Worker.HistogramMetric.Bucket - A histogram bucket.

Improbable.Worker.HistogramMetric.Bucket struct

Summary A histogram bucket.

Fields and Properties

  • uint Samples - The number of observations that were less than or equal to the upper bound.

  • double UpperBound - The upper bound.

Improbable.Worker.ICommandMetaclass interface

Summary Interface representing a command for a particular component. The generated code for a component will contain a command metaclass for each command defined by the component. These metaclasses are used to identify commands; in particular they are given as the generic type parameter to various command-related classes and methods.

Fields and Properties

  • uint CommandId { get; }

  • uint ComponentId { get; }

Improbable.Worker.ICommandRequest<C> interface

Summary Represents a request for the command identified by the metaclass C. Each command request has an extension method Get() that returns the concrete request type.

Type parameters

  • C: ICommandMetaclass - The metaclass identifying the command.

Improbable.Worker.ICommandResponse<C> interface

Summary Represents a response for the command identified by the metaclass C. Each command response has an extension method Get() that returns the concrete response type.

Type parameters

  • C: ICommandMetaclass - The metaclass identifying the command.

Improbable.Worker.IComponentData<C> interface

Summary Represents data-at-rest for the component identified by the metaclass C. Each component data has an extension method Get() that returns the concrete data type.

Type parameters

  • C: IComponentMetaclass - The metaclass identifying the component.

Methods

  • ToUpdate

    IComponentUpdate<C> ToUpdate()
    

    Remarks: Converts the at-rest data type to an update.
    Returns: IComponentUpdate<C>

    Improbable.Worker.IComponentMetaclass interface

    Summary Interface representing a particular component. The generated code will contain a metaclass for each component in the schema. These metaclasses are used to identify components; in particular they are given as the generic type parameter to various component- related classes and methods.

    Fields and Properties

    • uint ComponentId { get; } - The ID of this component.

    Improbable.Worker.IComponentUpdate<C> interface

    Summary Represents an update for the component identified by the metaclass C. Each component update has an extension method Get() that returns the concrete update type.

    Type parameters

    • C: IComponentMetaclass - The metaclass identifying the component.

    Methods

    • ApplyTo
    void ApplyTo(IComponentData<C> data)
    

    Description: Applies this update to the corresponding at-rest data type for the component.
    Parameters:

    Returns: void

  • ToInitialData

    IComponentData<C> ToInitialData()
    

    Description: Converts the update to an at-rest data type. Calling this method is only valid if the update provides a value for each field in the component; otherwise an exception is thrown.
    Returns: IComponentData<C>

    Improbable.Worker.IncomingCommandRequest<C> class

    Summary Type parameter for incoming entity command request IDs.

    Type parameters

    • C: ICommandMetaclass - The metaclass identifying the command.

    Improbable.Worker.InterestOverride class

    Summary Overrides the default interest settings for a particular entity and component.

    Fields and Properties

    • bool IsInterested - Controls whether checkout is explicitly enabled or disabled.

    Improbable.Worker.KcpNetworkParameters class

    Summary Parameters for configuring a KCP connection. Used by NetworkParameters.

    Fields and Properties

    • bool EarlyRetransmission =KcpEarlyRetransmission - 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 =KcpEnableErasureCodec - Whether to enable the erasure codec.

    • ErasureCodecParametersErasureCodec - Erasure codec parameters.

    • bool FastRetransmission =KcpFastRetransmission - Whether to enable fast retransmission, which causes retransmission delays to increase more slowly when retransmitting timed out packets multiple times.

    • HeartbeatParametersHeartbeat - Heartbeat parameters.

    • uint MinRtoMillis =KcpMinRtoMillis - 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.

    • uint MultiplexLevel =KcpMultiplexLevel - Number of multiplexed KCP streams.

    • bool NonConcessionalFlowControl =KcpNonConcessionalFlowControl - 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.

    • uint RecvWindowSize =KcpRecvWindowSize - 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.

    • uint SendWindowSize =KcpSendWindowSize - 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.

    • uint UpdateIntervalMillis =KcpUpdateIntervalMillis - Interval, in milliseconds, between which the KCP transport layer sends and receives packets waiting in its send and receive buffers respectively.

    Improbable.Worker.Locator class

    Implements System.IDisposable
    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.

    Constructors

    Locator(string hostname, LocatorParameters locatorParams)
    

Description: Creates a client for the locator service.
Parameters:

  • string hostname - Typically it is either “locator.improbable.io” (for production) or “locator-staging.improbable.io” (for staging).

  • LocatorParameterslocatorParams - The parameters for the locator service.

Methods

  • ConnectAsync

    Future<Connection> ConnectAsync(string deploymentName, ConnectionParameters connectionParams, Func<QueueStatus, bool> callback)
    

    Description: Connects to a specific deployment. The resulting future can be used to make this connection either synchronously or asyncronously.
    Parameters:

    • string deploymentName - The deployment name should be obtained by calling GetDeploymentListAsync.
    • ConnectionParametersconnectionParams - The connection parameters.
    • Func<QueueStatus, bool> 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

    • Dispose
    void Dispose()
    

    Returns: void

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

    Improbable.Worker.LocatorCredentialsType enum

    Fields

    Improbable.Worker.LocatorParameters class

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

    Fields and Properties

    • LocatorCredentialsTypeCredentialsType - Type of credentials to use when authenticating via the Locator.

    • bool EnableLogging = false - Whether to enable logging for the locator flow.

    • ProtocolLoggingParametersLogging - Parameters for configuring logging. Distinct from protocol logs: only relevant to the locator connection.

    • LoginTokenCredentialsLoginToken - Parameters used if the CredentialsType is LoginToken.

    • string ProjectName - The name of the SpatialOS project.

    • SteamCredentialsSteam - Parameters used if the CredentialsType is Steam.

    Improbable.Worker.LogLevel enum

    Fields

    Improbable.Worker.LogMessageOp struct

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

    Fields and Properties

    Improbable.Worker.LoginTokenCredentials class

    Summary Parameters for authenticating using a SpatialOS login token.

    Fields and Properties

    • string Token - The token would typically be provided on the command-line by the SpatialOS launcher.

    Improbable.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 and Properties

    • Map<string, double>GaugeMetrics { get; } - Gauge metrics for the worker.

    • Map<string, HistogramMetric>HistogramMetrics { get; } - Histogram metrics for the worker.

    • double Load { set; } - 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(Metrics metrics)
    

    Description: Copies all metrics from another Metrics object into this one, overwriting existing values.
    Parameters:

    Returns: void

Improbable.Worker.MetricsOp struct

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

Fields and Properties

Improbable.Worker.NetworkConnectionType enum

Fields

Improbable.Worker.NetworkParameters class

Summary Parameters for configuring the network connection.

Fields and Properties

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

  • NetworkConnectionTypeConnectionType =Tcp - Type of network connection to use when connecting to SpatialOS.

  • uint DefaultCommandTimeoutMillis =DefaultCommandTimeoutMillis - Default timeout for commands without a specified timeout argument, in millis.

  • KcpNetworkParametersKcp - Connection parameters specific to KCP connections.

  • RakNetNetworkParametersRakNet - Connection parameters specific to RakNet connections.

  • TcpNetworkParametersTcp - Connection parameters specific to TCP connections.

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

Improbable.Worker.OpList class

Implements System.IDisposable
Summary An opaque list of operations retrieved from GetOpList. It is usually passed to Process, which dispatches the operations to the appropriate callbacks.

Methods

  • Dispose

    void Dispose()
    

    Returns: void

    Improbable.Worker.OutgoingCommandRequest<C> class

    Summary Type parameter for outgoing entity command request IDs.

    Type parameters

    • C: ICommandMetaclass - The metaclass identifying the command.

    Improbable.Worker.ProtocolLoggingParameters class

    Summary Parameters for configuring protocol logging. If enabled, logs all protocol messages sent and received.

    Fields and Properties

    • string LogPrefix =LogPrefix - Log file names are prefixed with this prefix, are numbered, and have the extension .log.

    • uint MaxLogFileSizeBytes =MaxLogFileSizeBytes - Once the size of a log file reaches this size, a new log file is created.

    • uint MaxLogFiles =MaxLogFiles - Maximum number of log files to keep. Note that logs from any previous protocol logging sessions will be overwritten.

    Improbable.Worker.QueueStatus struct

    Summary A queue status update when connecting to a deployment via ConnectAsync.

    Fields and Properties

    • string Error - Will be non-null if an error occurred.

    • uint PositionInQueue - Position in the queue. Decreases as we advance to the front of the queue.

    Improbable.Worker.RakNetNetworkParameters class

    Summary Parameters for configuring a RakNet connection. Used by NetworkParameters.

    Fields and Properties

    Improbable.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 and Properties

    Improbable.Worker.RemoveEntityOp struct

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

    Fields and Properties

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

    Improbable.Worker.RequestId<T> struct

    Implements System.IEquatable<RequestId<T>>
    Summary Represents an ID for a request.

    Type parameters

    • T - A request marker type

    Fields and Properties

    • readonly uint 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(uint id)
    

Parameters:

  • uint id

Operators

static bool operator==(RequestId<T> a, RequestId<T> b)

Parameters:

Methods

  • Equals

    bool Equals(RequestId<T> obj)
    

    Parameters:

    Returns: bool

    Improbable.Worker.ReserveEntityIdRequest class

    Summary Type parameter for entity ID reservation request IDs.

    Improbable.Worker.ReserveEntityIdResponseOp struct

    Summary A response indicating the result of an entity ID reservation request.

    Fields and Properties

    • Option<EntityId>EntityId - If successful, a newly allocated entity ID, which is guaranteed to be unused in the current deployment.

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

    Improbable.Worker.ReserveEntityIdsRequest class

    Summary Type parameter for multiple entity ID reservation request IDs.

    Improbable.Worker.ReserveEntityIdsResponseOp struct

    Summary A response indicating the result of the multiple entity ID reservation request.

    Fields and Properties

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

    • string Message - A description of the status. Will contain the reason for failure if unsuccessful.

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

    Improbable.Worker.Snapshot class

    Summary Represents a snapshot of the state of a simulation.

    Methods

    • Load
    Option<string> Load(string path, out System.IDictionary<EntityId, Entity> entitiesOutput)
    

    Description: Load a snapshot from a file.
    Remarks: This function is DEPRECATED; use SnapshotInputStream instead.
    Parameters:

    • string path - The path to the snapshot file.
    • out System.IDictionary<EntityId, Entity> entitiesOutput - A dictionary which this method will use to store loaded entities.

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

  • Save

    Option<string> Save(string path, System.IDictionary<EntityId, Entity> entities)
    

    Description: Saves a snapshot to a file.
    Remarks: This function is DEPRECATED; use SnapshotOutputStream instead.
    Parameters:

    • string path - The path to the snapshot file.
    • System.IDictionary<EntityId, Entity> entities - A dictionary containing entities which will be saved to this snapshot.

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

    Improbable.Worker.SnapshotInputStream class

    Implements System.IDisposable
    Summary A stream for reading snapshots one entity at a time.

    Constructors

    SnapshotInputStream(string path)
    

Description: Creates a SnapshotInputStream to read the snapshot file from the given path.
Parameters:

  • string path - The path to the snapshot file.

Methods

  • Dispose

    void Dispose()
    

    Returns: void

    • HasNext
    bool HasNext()
    

    Returns: bool - True if SnapshotInputStream has not reached EOF.

  • ReadEntity

    Option<string> ReadEntity(out EntityId entityId, out Entity entity)
    

    Description: Loads the next EntityId and Entity pair from the Snapshot.
    Parameters:

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

    Improbable.Worker.SnapshotOutputStream class

    Implements System.IDisposable
    Summary A stream for writing snapshots one entity at a time.

    Constructors

    SnapshotOutputStream(string path)
    

Description: Creates a SnapshotOutputStream to read the snapshot file from the given path.
Parameters:

  • string path - The path to the snapshot file.

Methods

  • Dispose

    void Dispose()
    

    Returns: void

    • WriteEntity
    Option<string> WriteEntity(EntityId entityId, Entity entity)
    

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

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

Improbable.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 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.

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

Improbable.Worker.SteamCredentials class

Summary Parameters for authenticating using Steam credentials.

Fields and Properties

  • string DeploymentTag - Deployment tag to request access for. If non-empty, must match the following regex: [A-Za-z0-9][A-Za-z0-9_]

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

Improbable.Worker.TcpNetworkParameters class

Summary Parameters for configuring a TCP connection. Used by NetworkParameters.

Fields and Properties

Improbable.Worker.ThreadAffinityParameters class

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 and Properties

  • ulong ReceiveThreadsAffinityMask = 0 - Affinity mask for threads related to receiving data from the runtime.

  • ulong SendThreadsAffinityMask = 0 - Affinity mask for threads related to sending data to the runtime.

  • ulong TemporaryThreadsAffinityMask = 0 - Affinity mask for short-lived threads.

Improbable.Worker.UpdateParameters class

Summary Component update parameters. Used to modify the behaviour of sending a component update.

Fields and Properties

  • ComponentUpdateLoopbackLoopback - How the component update should be delivered to the worker sending the update, if at all.

Improbable.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 and Properties

Constructors

View()

Methods

  • GetAuthority<C>

    Authority GetAuthority<C>(EntityId entityId) where C: IComponentMetaclass
    

    Description: Helper function that checks if the worker has authority over a particular component of a particular entity.
    Type parameters:

    • C: IComponentMetaclass - The metaclass identifying the component.

    Parameters:

    Returns: Authority

    Improbable.Worker.Alpha namespace

    Improbable.Worker.Alpha.DevelopmentAuthentication class

    Methods

    • CreateDevelopmentLoginTokensAsync
    Future<LoginTokensResponse> CreateDevelopmentLoginTokensAsync(string hostname, ushort port, LoginTokensRequest request)
    

    Description: Calls the Development Login Service to generate login tokens.
    Parameters:

    • string hostname - The hostname of the Development Login Service. Typically “locator.improbable.io”.
    • ushort port - The port number used to connect to the Development Login Service. Typically 444.
    • LoginTokensRequestrequest - The request to send to the Development Login Service.

    Returns: Future<LoginTokensResponse> - A future object for the login tokens response.

  • CreateDevelopmentPlayerIdentityTokenAsync

    Future<PlayerIdentityTokenResponse> CreateDevelopmentPlayerIdentityTokenAsync(string hostname, ushort port, PlayerIdentityTokenRequest request)
    

    Description: Calls the Development Authentication Service to generate a player identity token.
    Parameters:

    • string hostname - The hostname of the Development Authentication Service. Typically “locator.improbable.io”.
    • ushort port - The port number used to connect to the Development Authentication Service. Typically 444.
    • PlayerIdentityTokenRequestrequest - The request to send to the Development Authentication Service.

    Returns: Future<PlayerIdentityTokenResponse> - A future object for the player identity token response.

    Improbable.Worker.Alpha.Locator class

    Implements System.IDisposable
    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(string hostname, LocatorParameters locatorParameters)
    

Description: Creates a client for the locator service.
Parameters:

  • string hostname - The hostname would typically be “locator.improbable.io”.

  • LocatorParameterslocatorParameters - The parameters for the locator service.

Locator(string hostname, ushort port, LocatorParameters locatorParameters)

Description: Creates a client for the locator service.
Parameters:

  • string hostname - The hostname would typically be “locator.improbable.io”.

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

  • LocatorParameterslocatorParameters - The parameters for the locator service.

Methods

  • ConnectAsync

    Future<Connection> ConnectAsync(ConnectionParameters connectionParams)
    

    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:

    Returns: Future<Connection> - A future object for the connection

    • Dispose
    void Dispose()
    

    Returns: void

Improbable.Worker.Alpha.LocatorParameters class

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

Fields and Properties

  • bool EnableLogging = false - Whether to enable logging for the Locator flow.

  • ProtocolLoggingParametersLogging - Parameters for configuring logging.

  • PlayerIdentityCredentialsPlayerIdentity - The player identity token/login token pair used for authentication.

  • bool UseInsecureConnection = false - Whether to use an insecure (non-TLS) connection for local development.

Improbable.Worker.Alpha.LoginTokenDetails class

Summary A single login token with additional details.

Fields and Properties

  • string DeploymentId - The UUID of the deployment.

  • string DeploymentName - The name of the deployment.

  • string LoginToken - The generated login token for this deployment.

  • System.Collections.Generic.IEnumerable<string> Tags - The tags that the deployment contains.

Improbable.Worker.Alpha.LoginTokensRequest class

Summary The parameters used when creating login tokens.

Fields and Properties

  • uint? 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.

  • string PlayerIdentityToken - The player identity token of the player.

  • bool UseInsecureConnection - Whether to use an insecure (non-TLS) connection for local development

  • string WorkerType - The worker type for which the requested login tokens are scoped for.

Improbable.Worker.Alpha.LoginTokensResponse struct

Summary The result of creating login tokens.

Fields and Properties

  • ConnectionStatusConnectionStatus - Information about the status of the request.

  • System.Collections.Generic.IEnumerable<LoginTokenDetails> LoginTokens - The list of login tokens.

Improbable.Worker.Alpha.PlayerIdentityCredentials class

Summary Parameters for authenticating using a player identity token and login token.

Fields and Properties

  • string LoginToken - Authenticates a user to a single deployment. Obtained from a game authentication server using a player identity token.

  • string PlayerIdentityToken - Uniquely identifies a user across deployments, and is provided by a game authentication server.

Improbable.Worker.Alpha.PlayerIdentityTokenRequest class

Summary The parameters used when creating a player identity token (PIT).

Fields and Properties

  • string DevelopmentAuthenticationToken - The Development Authentication token used for exchanging the player identity token.

  • string DisplayName - The player’s display name.
    This is an optional field.

  • uint? 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.

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

  • string PlayerId - The ID of the player to generate PIT for.

  • bool UseInsecureConnection - Whether to use an insecure (non-TLS) connection for local development.

Improbable.Worker.Alpha.PlayerIdentityTokenResponse struct

Summary The result of creating a player identity token.

Fields and Properties

  • ConnectionStatusConnectionStatus - Information about the status of the request.

  • string PlayerIdentityToken - The returned player identity token.

Improbable.Worker.Query namespace

Improbable.Worker.Query.AndConstraint class

Implements IConstraint
Inherits from List<IConstraint>
Summary Constrains a query by the conjunction of one or more constraints.

Constructors

AndConstraint()

AndConstraint(System.IEnumerable<IConstraint> enumerator)

Parameters:

  • System.IEnumerable<IConstraint> enumerator

Improbable.Worker.Query.ComponentConstraint class

Implements IConstraint
Summary Constrains a query to match only entities that have a specific component.

Fields and Properties

  • uint ComponentId

Constructors

ComponentConstraint(uint componentId)

Parameters:

  • uint componentId

Improbable.Worker.Query.CountResultType class

Implements IResultType
Summary Indicates that a query should return the number of entities it matched.

Improbable.Worker.Query.EntityIdConstraint class

Implements IConstraint
Summary Constrains a query to match only entities with a particular ID.

Fields and Properties

Constructors

EntityIdConstraint(EntityId entityId)

Parameters:

Improbable.Worker.Query.EntityQuery struct

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

Fields and Properties

  • IConstraintConstraint - The filter criteria of the query.

  • IResultTypeResultType - Describes the way the result should be represented.

Improbable.Worker.Query.IConstraint interface

Summary Base class for entity query constraints

Improbable.Worker.Query.IResultType interface

Summary Base class for entity query result types.

Improbable.Worker.Query.NotConstraint class

Implements IConstraint
Summary Constrains a query to match entities that do not match the given subconstraint.

Fields and Properties

Constructors

NotConstraint()

NotConstraint(IConstraint constraint)

Parameters:

Improbable.Worker.Query.OrConstraint class

Implements IConstraint
Inherits from List<IConstraint>
Summary Constrains a query by the disjunction of one or more constraints.

Constructors

OrConstraint()

OrConstraint(System.IEnumerable<IConstraint> enumerator)

Parameters:

  • System.IEnumerable<IConstraint> enumerator

Improbable.Worker.Query.SnapshotResultType class

Implements IResultType
Summary Indicates that a query should return a component data snapshot for each matched entity.

Fields and Properties

  • Option<List<uint>>ComponentIds - If nonempty, filters the components returned in the snapshot for each entity.

Constructors

SnapshotResultType()

SnapshotResultType(List<uint> componentIds)

Parameters:

  • List<uint>componentIds - Components to filter for.

Improbable.Worker.Query.SphereConstraint class

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

Fields and Properties

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

Constructors

SphereConstraint(double x, double y, double z, double radius)

Parameters:

  • double x
  • double y
  • double z
  • double radius

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums