Get SpatialOS

Sites

Menu

Setup guide for macOS 10.11+

This guide will prepare your Mac for local development with the SpatialOS SDK.

Note: You need to have access to SpatialOS to download the SDK.

1. System requirements

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

2. Set up the SpatialOS CLI

To set up the SpatialOS CLI (spatial):

  1. Install the Homebrew package manager.

    /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
    
  2. In a terminal, run:

    brew tap caskroom/cask
    brew tap improbable-io/spatialos
    brew update
    brew cask install spatial
    

    Note: If you have trouble with Homebrew, try setting the SpatialOS SDK up manually instead.

    By installing spatial, you agree to the SpatialOS EULA.

    Check it worked by running in a terminal: spatial update

    The printed URL link should open in your browser for authentication with your SpatialOS account. If the link does not open automatically in your browser click it or copy-paste it to visit the page.

    Expected output:

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

    Attempting to download the latest version...

    Did not update 'spatial'. Latest version is already installed.

3. Set up external development tools

You need some external software in order to develop a SpatialOS application. All of it is listed below, and all of it is free!

3.1. Unity

Unity versions 5.5.3 and 5.6.0 have been tested with SpatialOS. Later versions will probably work fine, but have not been extensively tested.

You MUST include Linux Build Support and Windows Build Support when you install Unity.

Install Unity version 5.6.0 and the optional extras that SpatialOS requires:

  1. In a terminal, run the following:

    brew cask install unity@5.6.0
    brew cask install unity-ios-support-for-editor@5.6.0
    brew cask install unity-linux-support-for-editor@5.6.0
    brew cask install unity-standard-assets@5.6.0
    brew cask install unity-windows-support-for-editor@5.6.0
    

    This installs Unity in the default installation directory, /Applications/Unity.

    If you want to use more than one version of Unity, you must:

    1. Rename this directory (for example, mv /Applications/Unity/Applications/Unity5.6.0). This path cannot have spaces in it.
    2. Set the UNITY_HOME environment variable to point at your chosen Unity installation.
  2. Launch Unity and complete the registration process.

Note: Once you’ve cloned a SpatialOS project, you’ll need to set the path to spatial from the Unity SpatialOS editor window. See the Unity SpatialOS editor window page for instructions.

3.2. Java Development Kit (JDK)

Install a JDK - we recommend at least 1.8.0_65. Refer to our Java Worker SDK requirements for full details.

  1. In a terminal, run:

    brew cask install java
    

    Check it worked by running: javac -version

    Expected output: javac 1.8.0_x

  2. Determine which configuration file to use: run cd, then 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).
  3. Set the JAVA_HOME system environment variable by running:

    echo "export JAVA_HOME=\$(/usr/libexec/java_home)" >> ~/your_config_file_here
    source ~/your_config_file_here
    

    Check it worked by running: echo $JAVA_HOME

    Expected output: /Library/Java/JavaVirtualMachines/jdk1.8.0_x.jdk/Contents/Home

4. (optional) Install the Launcher

  1. Download the Launcher.
  2. Follow the instructions in the installation wizard.

5. Next steps

You’ve now set up your development environment with SpatialOS!

To find out more about what SpatialOS is, try our product tour.

To get started coding on the platform, start with the Pirates tutorial.

(We really recommend starting from a tutorial, but if you want to start from scratch, use the Blank Project as your project outline.)

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums