Release notes for SpatialOS version 13

Note: SpatialOS 13 is fine for local development and deployments using the small deployment template, but deployments using larger templates may be unstable.

• 13.3.1
• 13.3.0
• 13.2.0
• 13.1.1
• 13.1.0
• 13.0.1
• 13.0.0

13.3.1

Released on 2018-11-01

Fixes

Spatial CLI tools

• We have improved the performance of running several spatial commands when schema changes have been made in projects with a lot of schema files.

C API

• Fixed a bug where using Worker_ConnectionFuture_Get returned a non-null pointer when the Worker_ConnectionFuture was not yet completed.

• Fixed a bug which duplicates component data when using Worker_SnapshotOutputStream to write an entity that was originally read using Worker_SnapshotInputStream.

• Schema_WriteToBuffer relied on incorrect size caching logic which is now resolved by re-calculating the size of the Schema_Object within each call of the function. Calling Schema_WriteToBuffer is now equivalent to calling Schema_SerializeToBuffer(object, buffer, Schema_GetWriteBufferLength(object)).

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

Deprecations

C API

• uint8_t Schema_WriteToBuffer(Schema_Object object, uint8_t* buffer) is deprecated 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);
          

13.3.0

Released on 2018-09-28

New features

General

• A new parameter is available and exposed through all the SDKs: DefaultCommandTimeoutMillis. This parameter sets a default timeout for commands without an explicitly set timeout argument.

C# Platform SDK

• Added alpha version of ServiceAccountServiceClient so that you can manage accounts used for automated services that interact with SpatialOS.

Fixes

C# SDK

• Fixed a bug which may cause a crash if a Future, returned by Locator.GetDeploymentListAsync or Locator.ConnectAsync, is resolved after its corresponding Locator object is destroyed.

• We now throw exceptions when invalid arguments are passed to API methods.

• When sending commands, maps and lists set to null in schema-generated code are now treated as empty maps and empty lists respectively.

• When sending updates, if the map or list properties of a component are set to null, they will throw an exception. With a breaking change included in 14.0, it will not be possible to create an Option of a reference type with a null value.

C++ SDK

• Added missing default initializers to structs holding parameters such as LocatorParameters and ThreadAffinityParameters. Previously, it was easy to end up with garbage data in fields that weren’t explicitly assigned to, depending on exactly how the struct was declared.

• Fixed a bug which may cause a crash if a worker::Future, returned by worker::Locator::GetDeploymentListAsync or worker::Locator::ConnectAsync, is resolved after its corresponding worker::Locator object is destroyed.

Java SDK

• Fixed a bug which may cause a crash if a Future, returned by Locator.getDeploymentListAsync or Locator.connectAsync, is resolved after its corresponding Locator object is destroyed.

• Fixed a number of issues which was causing a vastly increased amount of GC pressure. This fix significantly improves the performance of Java workers, making them more on par with C# and C++.

• We now throw exceptions when invalid arguments are passed to API methods.

• When sending commands:

  • maps and lists set to null in schema-generated code are initialized as empty maps and empty lists respectively.
  • EntityId set to null in schema-generated code is initialized with id 0.
  • Bytes set to null in schema-generated code is initialized with empty backing array.
  • reference types set to null in schema-generated code are initialized to the default value of their corresponding primitive type.
  • user-defined types set to null in schema-generated code are initialized following the rules stated above.

C API

• Fixed a bug which may cause a crash if a Worker_DeploymentListFuture or Worker_ConnectionFuture, returned by the Worker_Locator_GetDeploymentListAsync and Worker_Locator_ConnectAsync methods respectively, is resolved after its corresponding Worker_Locator object is destroyed.

• Fixed a linker error when using Schema_GetCommandResponseComponentId.

Breaking changes

C++ SDK

• Using list initialization for the LocatorParameters struct no longer works in C++11. If you get a compile error, assign to the fields by name instead. Later versions of C++ are unaffected.

13.2.0

Released on 2018-08-15

New features

General

• Thread affinity

  • Thread affinity parameters let you specify which set of logical cores, the threads started by SpatialOS will run on.
  • This is our first feature focused primarily towards console support, and we are currently formalising the authentication process for access to console development.
  • For more information, see the thread affinity docs.

• Added new built-in metrics to all SDKs, extracted from RakNet reporting. They will be populated only when using RakNet as a transport layer.

• The following new metrics have been added:

  • raknet_receive_buffer_size
  • raknet_send_buffer_size
  • raknet_send_buffer_size_bytes
  • raknet_resend_buffer_size
  • raknet_resend_buffer_size_bytes
  • raknet_packet_loss_last_second
  • raknet_packet_loss_lifetime
  • raknet_last_ping_seconds

Spatial CLI tools

• Added the spatial service CLI commands to enable local API usage with the Platform SDK.

C# Platform SDK

• First release of the C# Platform SDK.
  • Added alpha version of DeploymentServiceClient so that you can create, list, update and stop deployments locally and in the cloud.
  • Added alpha version of SnapshotServiceClient so that you can take, list, upload and get snapshots locally and in the cloud.

Fixes

C API

• Fixed potential race conditions in the destruction of Worker_ConnectionFuture, Worker_SnapshotInputStream and Worker_SnapshotOutputStream.

• Worker_AcquireComponentData, Worker_ReleaseComponentData and related functions are now exported from the DLL correctly when using the dynamic build on Windows.

13.1.1

Released on 2018-07-19

New features

General

• On Windows, we now ship debug symbols for packages which contain DLLs (currently, just CoreSdkDll.dll). Usually, these aren’t needed for development, but can be useful to debug crashes which originate from native code when loading the DLL. The static libraries shipped with the C++ SDK should also now include debug symbols by default.
  • You can find a .pdb file compatible with the CoreSdkDll.dll in the core-dynamic-dbgsym-x86_64-win32 worker package. To extract this to a folder called debug_symbols, run spatial package unpack-to worker_sdk core-dynamic-dbgsym-x86_64-win32 debug_symbols.

Fixes

General

• Fixed a crash which can occur when calling GetOpList on a failed connection after the metrics report period has elapsed.

• Fixed a minor memory leak when calling GetOpList on a Connection across C++, C#, Java, and C APIs.

• Fixed an issue which caused sfixed64 fields to be received incorrectly when set to certain values.

• Fixed two memory leaks.

• Fixed two potential race conditions.

• Removed often misleading debug log for Received incoming command response for unknown request ID.

C# SDK

• Fixed an issue which was causing a small chunk of memory to be needlessly heap allocated every time a component update, a command request or command response was being sent.

C++ SDK

• The cpp-static-x86_64-gcc_libstdcpp_pic-linux package now includes worker_protocol.h as it should, fixing the compilation error that occurs when using this package.

C API

• Fixed a potential race condition in the destruction of the Connection.

• Fixed an issue which caused user_handle to sometimes be uninitialised rather than set to NULL if no vtable functions are provided.

13.1.0

Released on 2018-07-02

New features

General

• Delta-compressed component updates

  • We’ve built an alpha version of a feature to optimise bandwidth usage for large component updates: delta-compressed component updates.
  • This feature is still in the very early stages. If you want to try it out, we recommend reading the documentation fully and in detail. In particular, if you aren’t careful about which components you delta compress, it can crash your deployment, because - used badly - it can overload the Runtime.
  • Because of this, please don’t use this feature in cloud deployments. If you use it in a cloud deployment, we reserve the right to shut your deployment down.
  • If you want to try it out, see the docs on delta-compressed component updates.

• A new parameter is available and exposed through all the SDKs: ConnectionTimeoutMillis. The parameter sets an upper bound on the time (in milliseconds) the futures returned by the ConnectAsync methods in Locator and Connection will take to complete. If the attempt is unsuccessful by that point, the connection attempt will be stopped.

• Added extra logging to protocol logs about connection establishment.

• Added option to turn on logging for the locator connection (for example, when listing deployments).

• Added new built-in metrics to all SDKs for local command timeouts, and unexpected command responses. These augment the previously misleading “Received incoming command response for unknown request ID XX” warning logs.

• The following new metrics have been added:

  • connection_local_command_timeouts
  • connection_local_command_timeouts_rate
  • connection_unexpected_command_response_receives
  • connection_unexpected_command_response_receives_rate

• Added new built-in metrics to all SDKs for monitoring delta-compression.

• JSON files generated by passing --language=ast_json to the schema compiler now contain command and event indices.

• New built-in metrics have been added to all SDKs for monitoring egress and ingress bytes on the network. The full list is available in the documentation.

• New built-in metrics have been added to all SDKs for monitoring the receive rate of Ops in the dispatcher. The full list is available in the documentation.

• The following built-in worker metrics have been renamed in all SDKs:

  • Bridge Send Queue -> connection_send_queue_size
  • Bridge Receive Queue -> connection_receive_queue_size
  • OpList Receive Queue -> connection_oplist_queue_size
  • Bridge Send Queue Fill Rate -> connection_send_queue_fill_rate
  • Bridge Receive Queue Fill Rate -> connection_receive_queue_fill_rate
  • OpList Receive Queue Fill Rate -> connection_oplist_queue_fill_rate

• New built-in metrics have been added to all SDKs for monitoring Connection Send API call rates. The full list is available in the documentation.

• Workers now automatically explicitly fail unknown commands, or commands they fail to deserialize due to data corruption, malicious sender, or out of date schema, instead of silently timing out. The worker issuing the command will observe an INTERNAL error with a suitable error message.

C++ SDK

• Added an overload of worker::Connection::SendAuthorityLossImminentAcknowledgement taking a component metaclass as a template parameter rather than an explicit component ID.

Java SDK

• Added an overload of improbable.worker.Connection.sendAuthorityLossImminentAcknowledgement taking a component metaclass parameter rather than an explicit component ID.

C API

• We’ve introduced an alpha API for building workers in C.

  This is much lower-level than the C#, C++ and Java SDKs: unlike those SDKs, it doesn’t provide any code generated from schema. Instead, it exposes serialization functions to directly read and write component data, component updates, and command requests and responses.

  The C API enables far more flexibility than our standard SDKs, and lets you work with dynamic languages such as Python and Lua. However, it takes substantially more work to get started as you need to implement your own code generation and serialization.

  If you want to try it out, see the docs for the C API.

Fixes

General

• Fixed an infrequent issue where a worker couldn’t connect to SpatialOS using RakNet on some machines.

• Fixed an issue where setting BuiltInMetricsReportMillis to 0 would result in a reporting period of 5000 milliseconds, rather than no reporting.

Known issues

C API

• Worker_AcquireComponentData, Worker_ReleaseComponentData and related functions won’t link correctly on Windows when using the dynamic build, because they aren’t marked as exported.

13.0.1

Released on 2018-06-04

New features

Spatial CLI tools

• You can now force the non-interactive mode by passing the --no_animation flag to any spatial CLI command. This disables colours and animation.
• You can now use the --json_output flag to switch the CLI output to be in JSON format.

Fixes

Spatial CLI tools

• Fixed an issue where Spatial CLI would not output any warnings or error details when running spatial worker build.

• The spatial CLI documentation is now up-to-date.

• The CLI now uses progress bars and task groups more consistently throughout all the commands.

• We’ve improved the non-interactive mode detection, and the CLI now automatically detects when it should disable colours and animation.

• When running commands from within a SpatialOS project, all the commands (rather than a subset) now output to the log files.

C# SDK

• We’ve optimised the internals of sending and receiving component updates! It’s now quicker and causes less garbage collection churn.

C++ SDK

• The C++ SDK is now a header-only library. It’s no longer necessary to link against libWorkerSdk.a (on MacOS and Linux) or WorkerSdk.lib (on Windows), and these libraries will be removed in the future. Note that you still need to link against the CoreSdk library and its dependencies (libCoreSdk.a or CoreSdk.lib).

13.0.0

Released on 2018-05-10

General

The only change in SpatialOS 13.0 is that SpatialOS no longer includes the Unity and Unreal SDKs. The Unity and Unreal SDKs are now released separately and hosted on GitHub.

If you’re using the Unity or Unreal SDK, to migrate to the GitHub-hosted SDK, visit the repository on GitHub:

• github.com/spatialos/UnitySDK
  • Guide to migrating your project to the GitHub-hosted Unity SDK 1.0.0
  • Unity SDK documentation
• github.com/spatialos/UnrealSDK
  • Guide to migrating your project to the GitHub-hosted Unreal SDK 1.0.0
  • Unreal SDK documentation

To find out more about why we’ve made this change, read this blog post.

If you’re not using the Unity or Unreal SDK, upgrade to 13.0 by following the upgrade guide.

Search results