Get SpatialOS

Sites

Menu
You are viewing the docs for 11.0, an old version of SpatialOS. 12.0 is the newest →

C# API reference documentation

Table of contents

Improbable namespace

Nested namespaces Improbable.Collections, Improbable.Worker

Improbable.EntityId class

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

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

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.List<T> class

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

Improbable.Collections.Map<K, V> class

Implements System.IDictionary<K, V>, System.IEquatable<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

Improbable.Collections.Option<T> class

Implements System.IEnumerable<T>, System.IEquatable<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

Constructors

Option(T newValue)

Description: Creates an Improbable.Collections.Option<T> containing the given value.
Parameters:

  • T newValue

Methods

  • Set

    void Set(T newValue)
    

    Description: Assigns the value contained in this Improbable.Collections.Option<T>, 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 Improbable.Collections.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.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

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 Improbable.Worker.Bytes object.
    Warning: since this method does not copy the array, modifications made to the returned array will be reflected by this Improbable.Worker.Bytes object. In particular, it is illegal to modify the source array concurrently with other operations on this object.

Methods

  • CopyOf

    static Bytes CopyOf(byte[] data)
    

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

    • byte[] data

    Returns: Bytes

  • FromBackingArray

    static Bytes FromBackingArray(byte[] data)
    

    Description: Creates a new Improbable.Worker.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 Improbable.Worker.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 Improbable.Worker.Bytes object.
    Returns: byte[]

Improbable.Worker.ClientError class

Summary Exposes a global hook to be invoked when errors are detected in client-side code. This is generally used to indicate programmer error, and covers cases such as attempting to throw an exception from a Improbable.Worker.Dispatcher callback.

Fields and Properties

  • 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

    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 Parameters used to alter 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. The worker should respond to the command by calling Improbable.Worker.Connection.SendCommandResponse with the given request ID.

Type parameters

  • C: ICommandMetaclass - The metaclass identifying the component.

Fields and Properties

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. The request ID will match a previous call to Improbable.Worker.Connection.SendCommandRequest

Type parameters

  • C: ICommandMetaclass

Fields and Properties

Improbable.Worker.ComponentUpdateOp<C> struct

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

Type parameters

  • C: ICommandMetaclass - The metaclass identifying the component.

Fields and Properties

Improbable.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 modified concurrently by multiple threads.

Fields and Properties

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

Methods

  • ConnectAsync

    Future<Connection> ConnectAsync(string hostname, ushort 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
    • ushort port
    • string workerId
    • ConnectionParametersconnectionParams - Parameters controlling the connection to SpatialOS.

    Returns: Future<Connection>

  • 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 Improbable.Worker.Dispatcher.Process

  • GetWorkerFlag

    Option<string> GetWorkerFlag(string flagName)
    

    Description: Retrieves the value of a worker flag from SpatialOS.
    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.

  • 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 Improbable.Worker.Dispatcher.OnCommandRequest callback.
    Remarks: The calling worker will receive a command response with status code Improbable.Worker.StatusCode.ApplicationError.
    Type Parameters:

    • C: ICommandMetaclass

    Parameters:

    Returns: void

  • SendCommandRequest<C>

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

    Description: Sends a command request to a component on a specific target entity.
    Remarks: Like Improbable.Worker.Connection.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

    Parameters:

    Returns: RequestId<OutgoingCommandRequest<C>> - A request ID which can be used to identify a response to the command via the Improbable.Worker.Dispatcher.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 Improbable.Worker.Dispatcher.OnCommandRequest callback.
    Remarks: Like Improbable.Worker.Connection.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

    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, bool legacyCallbackSemantics) 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 Improbable.Worker.Connection.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. The legacyCallbackSemantics parameter is deprecated and exists for legacy compatibility only. It will be removed soon and should not be used. This method does not check whether the worker currently has authority over the component.
    Type Parameters:

    • C: IComponentMetaclass

    Parameters:

    Returns: void

  • SendLogMessage

    void SendLogMessage(LogLevel level, string loggerName, string message)
    

    Description: Sends a log message for the worker to SpatialOS.
    Parameters:

    • LogLevellevel
    • string loggerName
    • string message

    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 second) to report the worker’s status. Since histogram metrics are diff-based, calling this function clears each histogram in the Metrics parameter.
    Parameters:

    Returns: void

  • SetProtocolLoggingEnabled

    void SetProtocolLoggingEnabled(bool enabled)
    

    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 enabled

    Returns: void

Improbable.Worker.ConnectionParameters class

Fields and Properties

  • uint 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. If set to zero, this functionality is disabled.

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

  • uint 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 - 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 - Number of messages that can be stored on the send queue. When the send queue is full, calls to Connection.Send functions can block.

  • string WorkerId - Unique worker identifier

  • string WorkerType - Worker type (platform).

Improbable.Worker.CreateEntityRequest class

Summary Type parameter for entity creation request IDs.

Constructors

CreateEntityRequest()

Improbable.Worker.CreateEntityResponseOp struct

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

Fields and Properties

Improbable.Worker.CriticalSectionOp struct

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

Fields and Properties

  • bool InCriticalSection

Improbable.Worker.Defaults class

Summary Default values for various configuration parameters.

Fields and Properties

  • const uint BuiltInMetricsReportPeriodMillis - 5000

  • const uint LogMessageQueueCapacity - 256

  • const string LogPrefix - “protocol-log-”

  • const uint MaxLogFiles - 10

  • const uint MaxLogFileSizeBytes - 1024

  • const uint RakNetHeartbeatTimeoutMillis - 60000

  • const uint ReceiveQueueCapacity - 4096

  • const uint SendQueueCapacity - 4096

  • const byte TcpMultiplexLevel - 32

  • const bool TcpNoDelay - false

  • const uint TcpReceiveBufferSize - 65536

  • const uint TcpSendBufferSize - 65536

  • const bool UseExternalIp - false

Improbable.Worker.DeleteEntityRequest class

Summary Type parameter for entity deletion request IDs.

Constructors

DeleteEntityRequest()

Improbable.Worker.DeleteEntityResponseOp struct

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

Fields and Properties

Improbable.Worker.Deployment struct

Summary Details for a specific deployment obtained via Locator.GetDeploymentList.

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.

Improbable.Worker.DeploymentList struct

Summary A deployment list obtained via Locator.GetDeploymentList.

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

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

  • 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

  • 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

  • Process

    void Process(OpList opList)
    

    Description: Processes an OpList and invokes registered callbacks.
    Parameters:

    Returns: void

  • Remove

    void Remove(ulong callbackKey)
    

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

    • ulong callbackKey - The key of the callback to be removed.

    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 Connection.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 with initial data. Has no effect if the entity already has the given component.
    Type Parameters:

    • C: IComponentMetaclass

    Parameters:

    Returns: void

  • Contains<TComponent>

    bool Contains<TComponent>() where TComponent: IComponentMetaclass
    

    Description: Returns true if the entity contains the desired component.
    Type Parameters:

    • TComponent: IComponentMetaclass

    Returns: bool

  • 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

    Returns: Option<IComponentData<C>>

  • GetComponents

    System.IEnumerable<uint> GetComponents()
    

    Description: Get the components that are currently on this entity.
    Returns: System.IEnumerable<uint>

  • HasAuthority<C>

    bool HasAuthority<C>() where C: IComponentMetaclass
    

    Description: Retrieves a flag representing authority over the given component.
    Type Parameters:

    • C: IComponentMetaclass

    Returns: bool

  • Remove<C>

    void Remove<C>() where C: IComponentMetaclass
    

    Description: Removes a component.
    Type Parameters:

    • C: IComponentMetaclass

    Returns: void

  • SetAuthority<C>

    void SetAuthority<C>(bool hasAuthority) where C: IComponentMetaclass
    

    Description: Overrides the flag representing authority over the given component.
    Type Parameters:

    • C: IComponentMetaclass

    Parameters:

    • bool hasAuthority

    Returns: void

  • Update<C>

    void Update<C>(IComponentUpdate<C> data) 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

    Parameters:

    Returns: void

Improbable.Worker.EntityQueryRequest class

Summary Type parameter for entity query request IDs.

Constructors

EntityQueryRequest()

Improbable.Worker.EntityQueryResponseOp struct

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

Fields and Properties

  • string Message - The error message.

  • RequestId<EntityQueryRequest>RequestId - The outgoing request ID for which there was a response. Matches the request ID returned by a previous call to Improbable.Worker.Connection.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 even when the status code is Improbable.Worker.StatusCode.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 even when the status code is Improbable.Worker.StatusCode.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 command response.

Improbable.Worker.Future<T> class

Implements System.Disposable
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.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(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

HistogramMetric()

Description: Creates a histogram with a single bucket.

Methods

  • ClearObservations

    void ClearObservations()
    

    Description: Clears all recorded oservations. Automatically called by Connection.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.IncomingCommandRequest<C> class

Summary Type parameter for incoming entity command request IDs.

Type parameters

  • C: ICommandMetaclass

Constructors

IncomingCommandRequest()

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.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: IComponentMetaclass - The metaclass identifying the component.

Methods

  • ToGenericObject

    GenericCommandObject ToGenericObject()
    

    Description: This is an implementation detail provided by generated code.
    Remarks: Clients should not need to call this method.
    Returns: GenericCommandObject

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: IComponentMetaclass - The metaclass identifying the component.

Methods

  • ToGenericObject

    GenericCommandObject ToGenericObject()
    

    Description: This is an implementation detail provided by generated code.
    Remarks: Clients should not need to call this method.
    Returns: GenericCommandObject

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()
    

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

  • ComponentProtocol.ClientComponentVtable Vtable { get; } - This is an implementation detail provided by generated code.
    Clients should not need to call this method.

Methods

  • AddSnapshotToEntity

    void AddSnapshotToEntity(ComponentProtocol.ClientObject snapshot, Entity entity)
    

    Description: This is an implementation detail provided by generated code.
    Remarks: Clients should not need to call this method.
    Parameters:

    • ComponentProtocol.ClientObject snapshot
    • Entityentity

    Returns: void

  • ExtractSnapshot

    object ExtractSnapshot(Entity entity)
    

    Description: This is an implementation detail provided by generated code.
    Remarks: Clients should not need to call this method.
    Parameters:

    Returns: object

  • TrackComponent

    void TrackComponent(View view)
    

    Description: This is an implementation detail provided by generated code. It adds callbacks to the view to keep track of this component.
    Remarks: Clients should not need to call this method.
    Parameters:

    Returns: void

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.Locator class

Implements System.Disposable
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 - The hostname of the locator service, typically “locator.improbable.io”.

  • 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, which 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 specified 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

Fields and Properties

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

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

Fields and Properties

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

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

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

Fields and Properties

  • NetworkConnectionTypeConnectionType - 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 - Whether to connect to SpatialOS using the internal IP address. This is for managed workers that run in the cloud alongside SpatialOS.

Improbable.Worker.OpList class

Summary An opaque list of operations retrieved from Improbable.Worker.Connection.GetOpList. It is usually passed to Improbable.Worker.Dispatcher.Process, which dispatches the operations to the appropriate callbacks.

Improbable.Worker.OutgoingCommandRequest<C> class

Summary Type parameter for outgoing entity command request IDs.

Type parameters

  • C: ICommandMetaclass

Constructors

OutgoingCommandRequest()

Improbable.Worker.ProtocolLoggingParameters class

Fields and Properties

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

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

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

Improbable.Worker.QueueStatus struct

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

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

Fields and Properties

  • uint HeartbeatTimeoutMillis - Time (in milliseconds) that RakNet should use for its heartbeat protocol.

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

Improbable.Worker.RequestId<T> class

Implements System.IEquatable<RequestId<T>>
Summary Represents an ID for a request. The type parameter should be one of the marker interfaces defined above.

Type parameters

  • T

Fields and Properties

  • readonly uint Id

Constructors

RequestId(uint id)

Parameters:

  • uint id

Improbable.Worker.ReserveEntityIdRequest class

Summary Type parameter for entity ID reservation request IDs.

Constructors

ReserveEntityIdRequest()

Improbable.Worker.ReserveEntityIdResponseOp struct

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

Fields and Properties

Improbable.Worker.Snapshot class

Summary Represents a snapshot of the state of a simulation.

Methods

  • Load

    static Option<string> Load(string path, out IDictionary<EntityId, Entity> entitiesOutput)
    

    Description: Load a snapshot from a file. Returns an error message if an error occurred.
    Parameters:

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

    Returns: Option<string> - An option which will be set to an error string if an error occurred.

  • Save

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

    Description: Save a snapshot to a file. Returns an error message if an error occurred.
    Parameters:

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

    Returns: Option<string> - An option which will be set to an error string if an 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 Improbable.Worker.Connection.SendCommandFailure, or the request data was rejected as invalid by SpatialOS itself. In the latter case, in particular, Improbable.Worker.Connection.SendCreateEntityRequest will return Improbable.Worker.StatusCode.ApplicationError if an entity ID reservation has expired, and Improbable.Worker.Connection.SendEntityQueryRequest will return Improbable.Worker.StatusCode.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.

Improbable.Worker.SteamCredentials class

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

Fields and Properties

  • byte MultiplexLevel - Number of multiplexed TCP connections.

  • bool NoDelay - Whether to enable TCP_NODELAY.

  • uint ReceiveBufferSize - Size in bytes of the TCP receive buffer.

  • uint SendBufferSize - Size in bytes of the TCP send buffer.

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.
Remarks This object should not be modified concurrently by multiple threads.

Fields and Properties

Constructors

View()

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.Collections.Generic.IEnumerable<IConstraint> enumerator)

Parameters:

  • System.Collections.Generic.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 entites 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.OrConstraint class

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

Constructors

OrConstraint()

OrConstraint(System.Collections.Generic.IEnumerable<IConstraint> enumerator)

Parameters:

  • System.Collections.Generic.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

  • double X

  • double Y

  • double Z

Constructors

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

Parameters:

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

  • double radius - The radius of the sphere.

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums