Improbable Icon

Is there a tutorial for porting a pre-existing title to Spatial?


I’ve been working on the game I’ve been planning to create into a multiplayer experience (I’ve put tons of functions that can be flipped from local to networked at the flick of a switch). And at this point, I think I’m ready to start integrating the experience into Spatial. However, maybe I’m blind, but i can’t seem to find any documentation on simply importing spatial into a pre-existing project, and starting to build from it.

Is there such a tutorial?

If not, could someone give me a quick rundown on the steps i’d need to take in order to do this?

I’m using Unity btw!



Hey Solsnare! What game engine are you using?


My bad! I’ve updated the post to reflect what I’m using (Unity).


When working with Unity you have a few choices to make about what tech you’d like to use to integrate SpatialOS. Here are some of your options:

This is one of our underlying language SDKs, which provides functions in C# that can connect to and communicate with SpatialOS. If you add the C# SDK to your Unity project as a library to call then you can make use of it from your C# scripts/monobehaviours. The C# SDK contains a view, which can track the entities known to your UnityWorker. However, just because your program knows about entities/components and is receiving updates doesn’t mean it’s doing anything with that information. If you are using the C# SDK directly then you’ll need to ‘integrate’ it with Unity yourself. This includes how those entities are represented in the gameworld (i.e. Associating them with assets/prefabs, spawning/despawning them in the world), and how the state of things in your scene is altered based on ops received from SpatialOS.

This is a very flexible route to go, which may be a good choice if you’ve already got a lot of your game written. But with flexibility comes the need to write more of the tooling yourself.

How to get started: Download the C# Blank Project and take a look inside for the libraries it uses. You should be able to import these into your Unity Project and start calling them from your existing code. You may find it easiest to move (or copy, if you have disk space) your existing Unity project into the “C# Blank Project” directory structure, where you should put it inside the “workers” sub-directory. This gives you a quick way to get your project structure set out like a SpatialOS project. You’ll need to investigate how SpatialOS build scripts work to get tooling like the spatial build command working though.

Unity SDK
Creating an integration with a game engine involves injecting some opinions about how that game engine will/should respond when it receives information from SpatialOS. The Unity SDK Integration Overview goes into some detail about what the Unity SDK is doing under the hood, and what you’re committing to if you use it. (Note: This also makes it a great resource if you want to integrate the C# SDK with Unity yourself, and just want a sense of some of the things you’ll need to create yourself).

The Unity SDK is already usable out of the box, and has some great learning resources to help you get started. However if you are quite far along with your game then there may be design decisions you have made that might make porting to SpatialOS more tricky.

How to get started: As above, starting with a Unity SDK Blank Project or Starter Project is a good starting point. However the Unity SDK has some design decisions which only allow two types of Unity workers: the UnityWorker and UnityClient (each of which is built from a scene within your Unity project). You can try and shift your game to using this structure, but it’ll be hard to test how well that’s going mid-way through.

General advice: Porting games to new tech can be hard, and depending on choices you’ve made along the way the process may be made more or less painful. One of the ways I have had the most success with ports is one that involves quite a big investment up front: Start a new SpatialOS project (e.g. from one of the StarterProjects or BlankProjects) and gradually bring over your game bit-by-bit. For example, copy across all the assets, then start writing entity template definitions, etc. Start small, move small parts of your game over and test things are working as often as you can. Ultimately the Unity project you end up with will be a different one to the one you were previously working on. This process is slow, and best attempted as early in the game’s development as possible if you have to do it.

A third and final upcoming option is the Unity GDK, which you can find out more about here.

I hope this information was useful. Let me know if you have any questions!