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:

• regenerate the helper classes from the schema

If you’ve modified a prefab you have to:

• export all entity prefabs

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 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.

1. In the Unity Editor, open the SpatialOS window (Window > SpatialOS).
2. To generate the code for Unity to use, go to the Build tab, and under Generate from schema, click Build.
3. 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

1. You must build workers. To build workers, open the SpatialOS window (Window > SpatialOS), go to the Build tab, and under Workers, click Build.

2. 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.

1. Make sure the Unity Editor is closed.

   If it’s not, it’ll cause build errors.

2. 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 the Build 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: