macOS

Tools installation guide for macOS

You can install the SpatialOS Tools with the SpatialOS installer or, alternatively, with a package manager.

In China

Only follow the instructions for China if you are located in China and deploying your game to server nodes hosted in China. If you’re planning to deploy to server nodes hosted in China, you need to follow the alternative installation steps. You can only deploy to server nodes hosted in China if you're located in China. For more information, contact your account manager or get in touch.

Installing the SpatialOS tools is a prerequisite for using the Worker SDK and the GDK for Unity. The installer gives you the CLI and the Launcher (you get access to the Console when you sign up to SpatialOS).

1. System requirements

We support up-to-date versions of macOS Sierra, El Capitan, High Sierra, Mojave and Catalina.

Before following the installation guide, check that your machine meets the hardware requirements.

If you're using a corporate network with a strict firewall, raise a support request (for customers with a service agreement) or ask on our forums and we'll take you through some custom setup steps.

2. Install SpatialOS

Download the installer and follow the steps.

This installs:

  • the SpatialOS CLI
  • the SpatialOS Launcher

Note: Known issue with Catalina and Big Sur

We’re in the process of notarizing all tools for use on Catalina and Big Sur. Until this is complete, if you're using Catalina or Big Sur, you can't open the SpatialOS installer package directly from your browser. Instead, you need to open it from Finder.

Note: Although the following workaround works on Big Sur, we do not currently support this macOS version.

To open the SpatialOS installer package from Finder:

  1. Select the arrow next to the package name and then select Show in Finder.

Image: Select the arrow next to the package name and then select Show in Finder.

  1. In Finder, right-click the package and select Open.
  2. In the next dialog box, select Open again.

If you don't want to set up SpatialOS using the installer, see the alternative installation steps for macOS below.

Next steps

Follow the language-specific Worker SDK setup guide in C, C# bindings, or C++.

Alternative installation steps for macOS

If you don't want to use the installer to set up your Mac for development with the SpatialOS Worker SDK, you can either:

Installing the SpatialOS tools is a prerequisite for using the Worker SDK and the GDK for Unity.

Set up your machine using Homebrew

1. System requirements

We support up-to-date versions of macOS Sierra, El Capitan, High Sierra, Mojave and Catalina.

Before following the installation guide, check that your machine meets the hardware requirements.

If you're using a corporate network with a strict firewall, raise a support request (for customers with a service agreement) or ask on our forums and we'll take you through some custom setup steps.

2. Set up the SpatialOS CLI

To set up the SpatialOS CLI, and other prerequisites for the next step:

  1. Install the Homebrew package manager.
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  1. Install the SpatialOS CLI.

Outside China

In a terminal, run:

brew update
brew install --cask spatial

By installing the CLI, you agree to the SpatialOS EULA.

Note: Known issue with Catalina and Big Sur

We’re in the process of notarizing all tools for use on Catalina and Big Sur. Until this is complete, if you're using Catalina or Big Sur, when you run the commands above, you’ll see a dialog box that says:

“mac” cannot be opened because the developer could not be verified.

Select Cancel and open the executable manually instead.

Note: Although the following workaround works on Big Sur, we do not currently support this macOS version.

To open the executable manually:

  1. Open Terminal and run the following:
open -R $(which spatial)
  1. In the Finder window that opens, right-click the executable named spatial, and select Open.
  2. In the next dialog box, select Open again.

In China

In a terminal, run:

brew update
brew install --cask spatial --language CN

By installing the CLI, you agree to the SpatialOS EULA.

Note: Known issue with Catalina and Big Sur

We’re in the process of notarizing all tools for use on Catalina and Big Sur. Until this is complete, if you're using Catalina or Big Sur, when you run the commands above, you’ll see a dialog box that says:

“mac” cannot be opened because the developer could not be verified.

Select Cancel and open the executable manually instead.

Note: Although the following workaround works on Big Sur, we do not currently support this macOS version.

To open the executable manually:

  1. Open Terminal and run the following:
open -R $(which spatial)
  1. In the Finder window that opens, right-click the executable named spatial, and select Open.
  2. In the next dialog box, select Open again.

Known issue

Sometimes, the command brew cask install spatial --language=CN fails to finish running. If this happens, we recommend you follow the manual setup steps instead.

  1. Check this succeeded.

Outside China

In a terminal, run:

spatial update

You should get the output:

 `Current version of the 'spatial' command-line tool: <version number>`
 
 `Attempting to download the latest version...`

In China

In a terminal, run:

spatial update --environment=cn-production

You should get the output:

Current version of the 'spatial' command-line tool: <version number>
 
 Attempting to download the latest version...

This is because the SpatialOS CLI isn't executable. Try this:

  1. Run which spatial to get the path to the SpatialOS CLI.
  2. Run chmod +x . This will make the tool executable.
    For example, chmod +x /usr/local/bin/spatial

4. Install the Launcher

To install the Launcher:

  1. Download the Launcher installer:

  2. Follow the instructions in the installation wizard.

Set up your machine manually

1. System requirements

We support up-to-date versions of macOS Sierra, El Capitan, High Sierra, Mojave and Catalina.

Before following the installation guide, check that your machine meets the hardware requirements.

If you're using a corporate network with a strict firewall, raise a support request (for customers with a service agreement) or ask on our forums and we'll take you through some custom setup steps.

2. Set up the SpatialOS CLI

To set up the SpatialOS CLI:

  1. Download the SpatialOS CLI for macOS (64bit): outside China/in China.
    By downloading the CLI, you agree to the SpatialOS EULA: outside China/in China.

  2. Put the SpatialOS CLI in a directory.
    For example, bin in your home directory: mkdir -p $HOME/bin && mv $HOME/Downloads/spatial $HOME/bin.

  3. Add the directory to your PATH. To do so:
    1. Open a terminal window.
    2. Move into home directory: run cd.
    3. Determine which configuration file to use (you will need to know your configuration file again in later steps): run ls -a ~
      • If you have a .bash_profile, that's your configuration file.
      • Otherwise, if you have a .bash_login, that's your configuration file.
      • Otherwise, if you have a .profile, that's your configuration file.
      • If you don't have any of these files, you can use .bash_profile (which you'll create in the next step).
    4. Add the location of spatial to the PATH variable: run echo 'export PATH=$PATH:/path_to_spatial_here' >> ~/your_config_file_here
      For example: echo 'export PATH=$PATH:$HOME/bin' >> ~/.bash_profile
  4. Make sure the SpatialOS CLI is executable: run chmod +x /path_to_spatial_here.
  5. Restart your terminal window to register the changes made to the path.
  6. Check this succeeded.

Outside China

In a terminal, run:

spatial update

You should get the output:

Current version of the 'spatial' command-line tool: <version number>

Attempting to download the latest version...

In China

In a terminal, run:

spatial update --environment=cn-production

You should get the output:

Current version of the 'spatial' command-line tool: <version number>

Attempting to download the latest version...

4. Install the Launcher

To install the Launcher:

  1. Download the Launcher installer:

  2. Follow the instructions in the installation wizard.

Next steps

Follow the language-specific Worker SDK setup guide in C, C# bindings, or C++.


2021-jun-18 Page updated with limited editorial review: Added Big Sur to workaround sections.
2021-jun-16 Page updated with editorial review: Fixed install CLI commands.

Updated 3 months ago


macOS


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.