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

Release notes for SpatialOS version 14


Released on 2019-09-18

New features


  • Added cross-stream packing to KCP when using the ModularUdpNetworkParameters. This should generally reduce bandwidth and CPU use when using a multiplex level greater than 1. As part of this change the KCP update_interval_ms parameter now only determines the interval for sending packets and not receiving. Received KCP packets are now processed as they arrive from the network, which may improve latency when using a large update_interval_ms. Additionally, KCP packets that require resending are no longer immediately resent; they are now subject to the same cross-stream packing interval. This may negatively affect latency if the link between the worker instance and the Runtime has high packet loss.

  • The snapshot converter now supports converting snapshots to JSON and back. From now on, spatial project history snapshot convert will use the new JSON format, but if you’re using flexible project layout (FPL), you’ll need to use the new convert-json subcommand of ./snapshot_converter.

Worker SDK in C#

Worker SDK in C++

Worker SDK in Java

  • Added the improbable.worker.Connection.alphaFlush function which works with connections using improbable.worker.alpha.ModularUdpNetworkParameters. This function indicates to the network layer that all previous invocations of the improbable.worker.Connection.send* methods should be flushed as soon as possible to the network. A common usage pattern is to call this function after all state changes have been applied at the end of a frame.

  • Added the improbable.worker.alpha.CompressionParameters class and downstreamCompression/upstreamCompression parameters to improbable.worker.alpha.ModularUdpNetworkParameters. Compression is enabled in the corresponding direction if the downstreamCompression or upstreamCompression parameters are not null.

  • Added the securityType parameter to improbable.worker.KcpNetworkParameters which configures the encryption layer security to use (this previously defaulted to DTLS). The security options are defined in improbable.worker.NetworkSecurityType.

Worker SDK in C

  • Added Schema_GenericData type to represent a container for serializing arbitrary schema types, not just component-related types.
  • Added Schema_CreateGenericData, Schema_CopyGenericData, Schema_DestroyGenericData and Schema_GetGenericDataObject functions that work similarly to existing functions for the other container types.

  • Added the Worker_Alpha_CompressionParameters struct and downstream_compression/upstream_compression parameters to Worker_Alpha_ModularUdpNetworkParameters. Worker_Alpha_CompressionParameters currently only has a placeholder field which is ignored. Compression is enabled in the corresponding direction if the downstream_compression or upstream_compression parameters are not NULL.

  • Added the Worker_Connection_Alpha_Flush function which works with connections using Worker_Alpha_ModularUdpNetworkParameters. This function indicates to the network layer that all previous invocations of the Worker_Connection_Send* methods should be flushed as soon as possible to the network. A common usage pattern is to call this function after all state changes have been applied at the end of a frame.

  • Added the security_type parameter to Worker_KcpNetworkParameters which configures the encryption layer security to use (this previously defaulted to DTLS). The security options are defined in Worker_NetworkSecurityType.

  • Added the ability to read and write snapshots in JSON format. You can configure these by assigning snapshot_type in Worker_SnapshotParameters to WORKER_SNAPSHOT_TYPE_JSON when creating a Worker_SnapshotInputStream or Worker_SnapshotOutputStream. For this to work, a schema bundle needs to be first created by the schema compiler, loaded by calling Schema_Bundle_Load, then passed to the snapshot stream by assigning schema_bundle in Worker_SnapshotParameters.

  • Added a number of new fields to Worker_SnapshotParameters:

    • snapshot_type - Specify what type of snapshot to operate with (either binary or JSON).
    • schema_bundle - Specify a schema bundle to use to understand the snapshot. Only required for JSON.
    • json_parameters - Optional parameters to customize behavior when operating with JSON.
  • It is now possible to convert Schema_* objects to a JSON string representation (and vice-versa) using the Schema_Json_* family of functions defined in c_schema.h.


Worker SDK in C

  • When stream_state in Worker_SnapshotState is set to WORKER_STREAM_STATE_GOOD, error_message is now set to NULL, rather than "".


Released on 2019-08-30


Worker SDK in C#

  • Fixed an issue preventing the GDK for Unity from successfully building on Android and iOS.


Released on 2019-08-15



  • Fixed an issue which could cause a crash if either the UpstreamKcp or DownstreamKcp parameters are not set when using ModularUdpNetworkParameters.


  • It’s now possible to specify an absolute --schema_path for the schema_compiler containing ../ and ./ fragments which will be properly canonicalized.

Worker SDK in C#

  • Fixed an issue where the DownstreamKcp parameters in ModularUdpNetworkParameters actually set both the downstream and upstream settings.

Platform SDK in C#

  • Fixed an issue where the Platform SDK was not able to detect tokens in the default locations and threw a credentials error.


Released on 2019-07-15

New features


  • Modular UDP connection type
    • The modular UDP connection type was first made available as part of this version. It has since been backported to 13.9.0.

Worker SDK in Java

  • Worker_Connection_SendComponentUpdate now takes an 4th parameter to control the behaviour of component update loopbacks (where sent component updates are automatically added to the oplist to be processed locally). Passing NULL here will result in the default behaviour in SpatialOS 13 and earlier.
  • Worker_Alpha_Component_SendComponentUpdate has been removed. Use Worker_Connection_SendComponentUpdate instead.

Worker SDK in C

  • Added a function Schema_ConvertComponentDataIntoUpdate to convert an at-rest component data into a component update, which when applied to an empty component data will result in the original component data. This operation requires the schema to be available at runtime via a schema bundle.

  • Added the ability to load “schema bundles”, a binary format describing the structure of a set of schema files, at runtime. A schema bundle file can be generated by the schema compiler using the --bundle_out argument. To load this file at runtime, open the file and read the binary data into a buffer, then pass the buffer to Schema_Bundle_Load.

Platform SDK in C#

  • The Platform SDK has now better support for authenticating API calls when being invoked from within a server worker’s deployment environment.


Worker SDK in Java

  • improbable.worker.PackageScanner now ignores classes which throw the java.lang.UnsupportedClassVersionError exception.

Worker SDK in C

  • Several minor memory leaks have been fixed in various Worker_Connection_SendX functions when returning early due to the input data being invalid or the connection being in an error state or shut down. In particular, some of these functions were not taking ownership of passed-in data correctly as specified by the API.

Breaking changes


  • The deprecated method SendReserveEntityIdRequest, the callback OnReserveEntityIdResponse and the structure ReserveEntityIdResponseOp have been removed. Use the bulk update SendReserveEntityIdsRequest, OnReserveEntityIdsResponse, and ReserveEntityIdsResponseOp instead.
  • The underlying raw ID type of RequestId has been changed from unsigned int32 to signed int64.


  • Removed improbable/vector3.schema. If you would still like to use the types defined in vector3.schema, you may copy the contents of the file into your project’s schema path.

Worker SDK in C#

  • All Snapshot API methods now throw an exception if an error occurs instead of returning Option<string>. The different exceptions are StreamBadStateException if an internal error occurred and the stream is not in a usable state, StreamInvalidDataException if the last operation on the snapshot failed but the stream is still in a usable state, and System.IO.EndOfStreamException if the eof was reached while executing the last operation. A try-catch block is required to handle the different kinds of errors.
  • SnapshotInputStream.ReadEntity now takes no arguments and returns a System.Collections.Generic.KeyvaluePair<EntityId, Entity> object.

  • Attempting to create an Option of a reference type with a null value will throw an ArgumentNullReference exception.

  • Moved Improbable.Worker.Alpha.Locator.ConnectAsync into Improbable.Worker.Locator.ConnectAsync.

  • Removed Improbable.Alpha.Locator.

  • Removed deprecated Improbable.Worker.Snapshot.Load and Improbable.Worker.Snapshot.Save functions. Use Improbable.Worker.SnapshotInputStream and Improbable.Worker.SnapshotOutputStream instead.

  • The AllowShortCircuiting field of the CommandParameters struct has been renamed to AllowShortCircuit in line with the C++ and Java SDKs.

  • The EntityId has been moved from namespace Improbable to namespace Improbable.Worker.

  • The core- packages have now been removed. Instead the Worker SDK for C# now loads the Worker SDK for C libraries dynamically as a plugin. When migrating from SDK 13.x references to any native libraries should be changed from CoreSdkDll to improbable_worker (for example, CoreSdkDll.dll becomes improbable_worker.dll on Windows). In addition the following packages need to be changed in any build system:

    • core-dynamic-x86_64-win32 should be replaced with c-dynamic-x86_64-vc140_md-win32 or c-dynamic-x86_64-vc140_mt-win32 (depending on whether the C# executable should depend on the MSVC 2015 redist or not, respectively).
    • core-dymamic-x86_64-macos should be replaced with c-dynamic-x86_64-clang-macos.
    • core-dynamic-x86_64-linux should be replaced with c-dynamic-x86_64-gcc510-linux.
  • The C# assembly Improbable.WorkerSdkCsharp.dll has been renamed to Improbable.Worker.dll.

  • The return type of Connection.GetWorkerAttributes has been changed from Improbable.Collections.List<string> to System.Collections.Generic.List<string>.

  • In EntityQueryResponseOp, the field Map<EntityId, Entity> Result has been changed to Dictionary<EntityId, Entity> Result.

  • In Metrics, the field Map<string, double> GaugeMetrics has been changed to Dictionary<string, double> GaugeMetrics and the field Map<string, HistogramMetric> HistogramMetrics has been changed to Dictionary<string, HistogramMetric> HistogramMetrics.

  • In View, the field Map<EntityId, Entity> Entities has been changed to Dictionary<EntityId, Entity> and the field Map<EntityId, Map<uint, Authority>> Authority has been changed to Dictionary<EntityId, Dictionary<uint, Authority>> Authority.

  • The use of generics throughout the Worker SDK in C# has been reworked. Previously, in order to determine which component or command was being manipulated, some functions took a generic parameter. Instead, all functions now take an IComponentMetaclass or ICommandMetaclass instance parameter to determine the component type, and a number of generic parameters are automatically deduced from this.

In general, given a function on the connection that takes a metaclass parameter, such as SendComponentUpdate<SomeComponent>(...), you should instead remove the generic parameter, and pass the metaclass directly, such as SendComponentUpdate(SomeComponent.Metaclass, ...). Similarly, for command-related functions, change SendCommandRequest<SomeComponent.Commands.SomeCommand>(...) to SendCommandRequest(SomeComponent.Commands.SomeCommand.Metaclass, ...).

Additionally, the IComponentData, ICommandRequest and ICommandResponse interfaces are no longer used when calling connection functions like SendComponentUpdate or SendCommandRequest. Instead, you should avoid using the wrapper types and pass the concrete data types directly.

The original methods taking a single generic parameter have been deprecated and some data structures and methods that support them have been renamed slightly. The old syntax and new syntax can be used in parallel within the same project to ease migration.

More information can be found in the upgrade guide.

  • Using csharp generated build scripts now use MSbuild by default due to Mono versions 5.0.0+ deprecating xbuild. Due to this, we have removed csharp_msbuild generated build scripts and no longer support versions of Mono before 5.0.0. You can still continue to use xbuild using the generated build scripts for csharp_xbuild. More information is available in the C# documentation.

  • Improbable.Worker.dll now requires .NET Framework 4.5 (or a compatible runtime) or above.

Worker SDK in C++

Worker SDK in Java

  • Removed the non-generic SendAuthorityLossImminentAcknowledgement method. Please use the generic version instead.

  • All Snapshot API methods now throw an exception if an error occurs instead of returning Option<String>. The different exceptions are StreamBadStateException if an internal error occurred and the stream is not in a usable state, StreamInvalidDataException if the last operation on the snapshot failed but the stream is still in a usable state, and if the eof was reached while executing the last operation. A try-catch block is required to handle the different kinds of errors.

  • All operation types have been moved from improbable.worker.Ops.X to improbable.worker.XOp. For example, Ops.Disconnect has been renamed to DisconnectOp.

  • Method provided by generated code: FooComponent.fromInitialData() has been replaced with FooComponent.Update.fromInitialData().

  • Moved Alpha.Locator.ConnectAsync into Locator.ConnectAsync.

  • Removed Alpha.Locator.

  • Removed deprecated improbable.worker.Snapshot.load and functions. Use improbable.worker.SnapshotInputStream and improbable.worker.SnapshotOutputStream instead.

  • The worker SDK .jar files now require JDK 1.8 or above.

  • java-worker-sdk.jar has been renamed to improbable-worker.jar.

  • java-worker-sdk-native-win32-x64.jar has been renamed to improbable-worker-native-win32-x64.jar.

  • java-worker-sdk-native-macos-x64.jar has been renamed to improbable-worker-native-macos-x64.jar.

  • java-worker-sdk-native-linux-x64.jar has been renamed to improbable-worker-native-linux-x64.jar.

Worker SDK in C

  • Changed the return type of Worker_SendComponentUpdate and Worker_SendCommandResponse from void to Worker_Result.

  • In order to make the C SDK strictly compatible with C90, a couple of anonymous unions were given names. Change accesses to the specific operation within a Worker_Op to go through the nested op union, for example:

    Worker_Op* op = /* ... */;
    Worker_ComponentUpdate* update = &op->op.component_update.update;

    Similarly for Worker_Constraint, access the specific constaint type through the nested constraint union.

  • Removed the deprecated function Worker_Connection_SendReserveEntityIdRequest. Use the bulk update Worker_Connection_SendReserveEntityIdsRequest instead.

  • Removed the deprecated struct Worker_ReserveEntityIdResponse from Worker_Op.

  • Replaced Worker_SnapshotInputStream_GetError with Worker_SnapshotInputStream_GetState, which instead returns a state code alongside an error message. If there was no error, Worker_SnapshotInputStream_GetState will return a Worker_SnapshotState with stream_state set to WORKER_STREAM_STATE_GOOD.

  • Worker_SnapshotOutputStream_WriteEntity no longer returns an error code, instead call Worker_SnapshotInputStream_GetState afterwards to determine whether an error occurred.

  • The function Worker_Connection_GetFlag has been renamed to Worker_Connection_GetWorkerFlag for consistency with the other language SDKs.

  • The typedef Worker_GetFlagCallback has been renamed to Worker_GetWorkerFlagCallback.

  • The header files have been removed from each c package. Instead the header files are now shipped in a separate worker package called c_headers of type worker_sdk.

  • Renamed the worker library to improbable_worker to avoid ambiguity. For example, on Windows, we now ship improbable_worker.dll / improbable_worker.lib instead of worker.dll / worker.lib.

  • Static library files are now stored in the root of the package instead of the lib subfolder.

  • Simplified binary package names slightly. You can find updated names here but in general, we’ve made the following changes:

    • replaced msvc with vc140 for Windows packages.
    • replaced clang_libcpp with clang for macOS, iOS and Android packages.
    • replaced gcc_libstdcpp with gcc510 for Linux packages.
  • The legacy Worker_Locator_ConnectAsync has been renamed to Worker_Locator_ConnectAndQueueAsync.

  • Worker_Alpha_Locator_ConnectAsync has been renamed to Worker_Locator_ConnectAsync and now uses the new login flow with Player Identity credentials.

  • The signatures of several functions have changed to take non-const pointers to their Worker_X handle type arguments. The schema_type pointer is now set to NULL when data ownership is transferred. The functions affected are: Worker_Connection_SendCreateEntityRequest, Worker_Connection_SendComponentUpdate, Worker_Connection_SendAddComponent, Worker_Connection_SendCommandRequest, Worker_Connection_SendCommandResponse.

  • Schema_CreateComponentData, Schema_CreateComponentUpdate, Schema_CreateCommandRequest and Schema_CreateCommandResponse no longer require a component ID to be redundantly specified, as this information is already provided in the Worker_Component... and Worker_Command... handle objects.

  • Schema_CreateCommandRequest and Schema_CreateCommandResponse no longer require a command index to be specified. Instead, the command index should now be set in the Worker_CommandRequest and Worker_CommandResponse objects when interacting with the connection object.

  • Worker_Connection_SendCommandRequest no longer requires a command_index to be specified, as it is now contained in the Worker_CommandRequest object.

  • Schema_Get*ComponentId and Schema_GetCommand*CommandIndex functions have been removed. Instead, the component ID and command index (where applicable) can be accessed in the enclosing Worker_* handle type, or as an argument in the vtable callback, depending on the context. The removed schema getter functions are:

    • Schema_GetComponentDataComponentId
    • Schema_GetComponentUpdateComponentId
    • Schema_GetCommandRequestComponentId
    • Schema_GetCommandRequestCommandIndex
    • Schema_GetCommandResponseComponentId
    • Schema_GetCommandResponseCommandIndex
  • Worker_Locator_Create now requires the port to be specified when connecting to a locator service. This allows you to connect a worker to a local locator instance. To connect to a cloud instance, this parameter should be set to 0.

  • command_request_serialize, command_request_deserialize, command_response_serialize, and command_response_deserialize now take a Worker_CommandIndex parameter as their 2nd argument, to more easily determine which command should be serialized or deserialized.

  • uint8_t Schema_WriteToBuffer(Schema_Object object, uint8_t* buffer) has been removed in favor of uint8_t Schema_SerializeToBuffer(const Schema_Object* object, uint8_t* buffer, uint32_t length).

  • A common usage pattern:

    uint8_t* buffer = new uint8_t[Schema_GetWriteBufferLength(object)];
    Schema_WriteToBuffer(object, buffer);

    should be replaced with:

    uint32_t length = Schema_GetWriteBufferLength(object);
    uint8_t* buffer = new uint8_t[length];
    Schema_SerializeToBuffer(object, buffer, length);


Worker SDK in C#

  • Deprecated the old Locator.ConnectAsync and Locator.GetDeploymentListAsync in favour of the new Locator.ConnectAsync which uses Player Identity credentials.

Worker SDK in C++

Worker SDK in Java

  • Deprecated the old Locator.ConnectAsync and Locator.GetDeploymentListAsync in favour of the new Locator.ConnectAsync which uses Player Identity credentials.

Known issues

Platform SDK in C#

  • The automated parsing of credentials at well-known locations is broken. This surfaces as an Unauthenticated error code with the message

    Getting metadata from plugin failed with error: Exception occured in metadata credentials plugin.

    Constructing credentials with an explicit token in user-code works is the recommended work-around.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums