Building in Unity: what and when to build
This page is about building in the Unity Editor. If you want to build from the command line, see Building from the command line.
Quick reference
If you’ve modified the schema files you have to:
If you’ve modified a prefab you have to:
If you’ve modified Unity code you have to:
- build the workers
- regenerate the initial snapshot (if affected, e.g. by modifying snapshot generating code, or entity templates for entities in the snapshot)
Build and run
Build target
Building prefabs and workers is target dependent. There’s two targets:
- development: builds for local deployment - it builds both the UnityWorker and UnityClient for your current OS.
- deployment: builds for cloud deployment - it builds the UnityWorker for Linux, and UnityClients for both Windows and macOS OS.
There’s a dropdown to switch the build target in the SpatialOS window, on the Build
tab.
To configure target platforms when building for development and deployment, see the Build configuration section in the Configuring the build process page.
If you’ve changed the schema
Any time you change the schema (for example, add or change a component), you need to regenerate the generated code, and fix code references.
- In the Unity Editor, open the SpatialOS
window (
Window > SpatialOS
). - To generate the code for Unity to use, go to the
Build
tab, and underGenerate from schema
, clickBuild
. - If there are any code references that are broken by the schema changes, fix them and follow the If you’ve changed Unity code section.
If you’ve modified a prefab
You must build prefabs if you modify a prefab directly by:
- adding a component,
- removing a component, or
- changing a property on a component
To build prefabs, open the SpatialOS window (Window > SpatialOS
), go to the Build
tab, and under Entity prefabs
, click Build all
.
If you’ve changed Unity code
You must build workers. To build workers, open the SpatialOS window (
Window > SpatialOS
), go to theBuild
tab, and underWorkers
, clickBuild
.You have to regenerate the initial snapshot (if affected, e.g. by modifying snapshot generating code, or entity templates for entities in the snapshot)
Build from the command line
The SpatialOS window isn’t the only way to build your project - you can also build using the spatial
command-line tool.
Make sure the Unity Editor is closed.
If it’s not, it’ll cause build errors.
In the root directory, to build workers for local deployment, run:
spatial worker build UnityWorker UnityClient --target=development
.Or, to build workers for cloud deployment, run:
spatial worker build UnityWorker UnityClient --target=deployment
.
Updating the initial snapshot
You must update your initial snapshot (or generate a new one) if you make any changes that affect what’s in the snapshot. This includes (but isn’t limited to):
- adding or removing entities in the initial state (by changing the code which adds them)
- changing the number of entities in the initial state (by changing the code which adds them)
- changing the template (used to spawn an entity) of any entity that’s in the
initial snapshot, including
- adding components to the entity
- removing components from the entity
- changing the initial data of a component
- changing per-component write access requirements
To update the initial snapshot, use the C# SDK to manipulate it.
Optimizing build times
You can decrease build times by taking the following points into consideration:
When you run a scene in Unity’s Editor, the worker corresponding to that scene doesn’t need to be built beforehand. During development, you can skip building the open scene (often
UnityClient
) unless you intend to use the game executable.If you want to skip building for certain worker types (e.g.
UnityClient
in the case above), you can uncheck them in theBuild
tab of the SpatialOS window.Prefabs are built as part of the workers’ build process, so you don’t need to separately build prefabs before building workers.
Unity building cheat sheet
For a handy guide to what to build when in Unity, see this cheat sheet: