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
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 theWorker_ConnectionFuture
was not yet completed.Fixed a bug which duplicates component data when using
Worker_SnapshotOutputStream
to write an entity that was originally read usingWorker_SnapshotInputStream
.Schema_WriteToBuffer
relied on incorrect size caching logic which is now resolved by re-calculating the size of theSchema_Object
within each call of the function. CallingSchema_WriteToBuffer
is now equivalent to callingSchema_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 ofuint8_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 byLocator.GetDeploymentListAsync
orLocator.ConnectAsync
, is resolved after its correspondingLocator
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
orlist
properties of a component are set tonull
, they will throw an exception. With a breaking change included in 14.0, it will not be possible to create anOption
of a reference type with anull
value.
C++ SDK
Added missing default initializers to structs holding parameters such as
LocatorParameters
andThreadAffinityParameters
. 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 byworker::Locator::GetDeploymentListAsync
orworker::Locator::ConnectAsync
, is resolved after its correspondingworker::Locator
object is destroyed.
Java SDK
Fixed a bug which may cause a crash if a
Future
, returned byLocator.getDeploymentListAsync
orLocator.connectAsync
, is resolved after its correspondingLocator
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 tonull
in schema-generated code is initialized withid 0
.Bytes
set tonull
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.
- maps and lists set to
C API
Fixed a bug which may cause a crash if a
Worker_DeploymentListFuture
orWorker_ConnectionFuture
, returned by theWorker_Locator_GetDeploymentListAsync
andWorker_Locator_ConnectAsync
methods respectively, is resolved after its correspondingWorker_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.
Fixes
C API
Fixed potential race conditions in the destruction of
Worker_ConnectionFuture
,Worker_SnapshotInputStream
andWorker_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 theCoreSdkDll.dll
in thecore-dynamic-dbgsym-x86_64-win32
worker package. To extract this to a folder calleddebug_symbols
, runspatial package unpack-to worker_sdk core-dynamic-dbgsym-x86_64-win32 debug_symbols
.
- You can find a
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 aConnection
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 includesworker_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 toNULL
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 theConnectAsync
methods inLocator
andConnection
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 anyspatial
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) orWorkerSdk.lib
(on Windows), and these libraries will be removed in the future. Note that you still need to link against theCoreSdk
library and its dependencies (libCoreSdk.a
orCoreSdk.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:
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.