2. Start a local deployment

This tutorial is for developers located outside China, using hosting outside China

If you are located in China and using hosting inside China, see the [CN] Starter Template quick-start tutorial.

Starter Template quick-start: 2 - Start a local deployment

When you want to try out your game, you need to start a SpatialOS deployment; the SpatialOS deployment runs your game's functionality. We call the running SpatialOS deployment the game "simulation", and what's happening in it, the "SpatialOS world"

There are two types of SpatialOS deployment: local and cloud.

  • A local deployment is for testing only. A local deployment runs your game simulation in the Unreal Editor.
    Your game simulation with its own instance of the SpatialOS Runtime, runs on your development machine. You can run multiple clients in a local deployment, which is useful for fast development iteration.
    You can start local deployments on Windows or macOS development machines.

There is a SpatialOS Runtime instance for every game simulation. A Runtime instance holds the canonical store of all a game's SpatialOS-relevant object data in the SpatialOS entity database.

It handles server and game client connections, and coordinates each server and game client's write and read access to the entity database.

The local Runtime’s executable file is called runtime.exe (Windows) or runtime (macOS). You can find out more about the SpatialOS Runtime in the Glossary.

  • A cloud deployment runs on remote networked nodes. A node is a single machine used as server hardware.
    The cloud is where your game simulation runs when you release it, so you always deploy your released game to the cloud but you can also use a cloud deployment during development to share it with test users and run it at scale. You share your Windows game with test users through the SpatialOS Launcher. (You'll use the Launcher in a later step of this guide.)
    Note: You can start cloud deployments from Windows development machines only. Cloud deployments are not available from macOS development machines.

The Launcher is a distribution tool which downloads and launches game clients for your cloud deployment. You installed the Launcher when you installed SpatialOS on your machine in Get started: 1. Get the dependencies.

You start the Launcher from the SpatialOS Console, and use it to create a URL to give end-users access to a game client for your game.

You find out more about the Launcher and Console in a later step in this guide.

Note: You can only use the Launcher if you have developed your game on Windows.

TIP

Use local deployments for small-scale tests, to quickly test and iterate on changes to your project. For large-scale tests with several players, use a cloud deployment.

Step 1: Generate schema and a snapshot

A deployment requires schema and a snapshot to start successfully. The schema and snapshot files set up SpatialOS entities. Before you start a deployment (local or cloud) you must generate schema via the toolbar to set up SpatialOS entities.

You can also choose to generate a snapshot via the toolbar, however, you do not need to because the GDK does this for you automatically when you start a deployment (local or cloud).

Schema is a set of definitions which represent your game’s objects in SpatialOS as entities.

Schema is defined in .schema files and written in schemalang by the GDK.
When you select Schema from the GDK toolbar, the GDK generates schema files and their contents for you, so you do not have to write or edit schema files manually.

The GDK generates schema for classes in your project which have Unreal’s replicated properties or RPCs.

You can find out more about schema, including:

  • how to generate it from the command line,
  • making schema work with source control, and
  • how to exclude certain directories from schema,

  • in the GDK schema documentation.

    You can find out more about Unreal’s replicated properties and RPCs in the Unreal documentation.

    An entity is the SpatialOS equivalent of an Unreal Actor. It’s made up of a set of SpatialOS components. Each component stores data about the entity.

    (Note that SpatialOS components are not the same thing as Unreal Actor Components.)

    A snapshot is a representation of the state of a SpatialOS world at a given point in time. A snapshot stores the current state of each entity’s component data.

    You start each deployment with a snapshot; if it’s a re-deployment of an existing game, you can use the snapshot you originally started your deployment with, or use a snapshot that contains the exact state of a deployment before you stopped it.

    You can find out more about snapshots in the GDK snapshot documentation.

    1. In the Unreal Editor, on the GDK Toolbar, select Schema.

    Image: GDK toolbar's Schema button

    1. You can select Snapshot to generate a snapshot, but you do not need to.

    Image: GDK toolbar's Snapshot button

    Step 2: Start and play

    This step shows you how to start one game server and two game clients in a local deployment in the Unreal Editor.

    In SpatialOS, game servers are called "server-workers" and game clients are called "client-workers".

    A server-worker is your game's server-side code. It's the equivalent of a "server" in native Unreal networking.

    You can think of client-workers as game clients as they are essentially the same.

    Both server-workers and client-workers are programs that compute a SpatialOS game world: they send updates to and receive updates from the entity database in the SpatialOS Runtime.

    You can have different types of server-workers doing different tasks (called "offloading"), depending how you have set up your game. You can also set up your game to have more than one instance of a server-worker type (called "zoning"). This Example Project tutorial sets up one instance of one server-worker type; a main Unreal server-worker. The main Unreal server-worker type is part of the GDK for Unreal.

    You usually only have one type of client-worker in your game but you can have many instances of a client-worker, each representing a game player. The Example Project has one client-worker type.

    To start a local deployment in the Unreal Editor, you need to access two drop-down menus:

    • The Start Deployment drop-down menu
    • Play drop-down menu

    Image: The GDK toolbar's Start Deployment drop-down menu on Windows

    Image: The Unreal Editor toolbar's Play drop-down menu.

    You use these menus to set up the networking, set up the multiplayer options, and run the game. To do this:

    1. Set up the networking:
      From the GDK toolbar, open the Start Deployment drop-down menu:
      • In the SpatialOS Settings section, select the SpatialOS Networking setting if it’s not already checked.
        The SpatialOS Networking option is the networking switch; you use this to switch your game's deployment from native Unreal networking to SpatialOS networking.
      • In the Connection Flow section, select Connect to local deployment if it’s not already checked.
    2. Set up the multiplayer options:
      From the Unreal toolbar, open the Play drop-down menu, in the Multiplayer Options section of the menu:
      • Enter the number of players as 2.
      • For Net Mode, select Play As Client.
    3. Now, run the game:
      Still in the Play drop-down menu, in the Modes section of the window, select New Editor Window (PIE).
      If the game does not run automatically after you have selected New Editor Window (PIE), select Play on the Unreal toolbar. This starts a local deployment.

    You specify the Connection Flow setting when you run clients in the Unreal Editor.
    The setting defaults to Connect to a local deployment but it's good practice to check the setting before you deploy.

    When you are working with a local deployment, you keep this set to Connect to a local deployment, this ensures the local SpatialOS Runtime connects clients to a deployment on your development machine.
    When you are working with a cloud deployment, and want to connect clients running locally in the Unreal Editor, you set this to Connect to a cloud deployment.

    In this Example Project tutorial you do not use Connect to a cloud deployment.
    Find out more about these Play in Editor (PIE) settings in the Development authentication flow documentation.

    Troubleshooting

    The loading bar is stuck on 45%.
    This is Unreal compiling the shaders for the first time. Give it a little time.

    There’s a warning dialog box about the Runtime.
    You can only have one instance of the SpatialOS Runtime. If there is an instance of the SpatialOS Runtime running with another project, a warning dialog box appears.
    Select Yes to stop that instance and start the Runtime for your current project.

    There’s a Windows Defender Firewall message (Windows only).
    When you start a local deployment for the first time, you might see a Windows Defender Firewall message stating that it has blocked some features of runtime.exe. Select Allow access to continue and open the Unreal Editor.

    There’s a macOS warning about incoming network connections.
    When you start a local deployment or when you start the Unreal Editor for the first time, you might see a warning message asking you if you want to accept incoming network connections. Select Allow to continue and open the Unreal Editor.

    What's running?

    You have started one SpatialOS server-worker instance and two SpatialOS client-worker instances locally, in the Unreal Editor. You have also started an instance of the SpatialOS Runtime locally. The running instance of the SpatialOS Runtime is your game’s deployment.

    What is this doing?

    The server-worker instance is acting as an Unreal server. The two client-worker instances are acting as two Unreal game clients, as if two game players were playing your game.

    You can switch between the two Editor windows to see and interact with each game client.

    Image: Two game clients running in Unreal Editor

    You can connect a game client on Android or iOS mobile devices to a SpatialOS local deployment running your Windows or macOS development machine.

    For information on this, see Launch your game on mobile (Android) or Launch your game on mobile (iOS) once you have completed this tutorial.

    Step 3: Inspect and stop play

    While your game is running, you can see what's happening in it by looking at the Inspector.

    1. From the GDK toolbar, select Inspector to open it in your default web browser.

    Image: GDK toolbar's Inspector button

    You use the Inspector to explore the internal state of a SpatialOS world. It gives you a real time view of what’s happening in a deployment.

    For local deployments, you open the Inspector in your browser. For cloud deployments, you open the Inspector from the Console, which is a web-based tool for debugging and managing games. You'll use the Console in later steps.

    Selecting Inspector opens the Inspector for local deployments in your browser (shown below):

    Image: The Inspector in your browser

    1. When you’re done, select Stop on the Unreal toolbar.

    Image: The Unreal toolbar's Stop button

    This stops the two game clients and the one server-worker instance running but doesn't stop the SpatialOS Runtime running (and so the deployment keeps running).

    Step 4: Iterate game development

    As you iterate your game development (by modifying classes or Blueprints, for example), you will make changes to replicated components - this requires schema regeneration.

    To do this:

    1. Select the Schema button in the GDK toolbar.
      This triggers an incremental schema generation (any changes since last schema generation).
      If you haven't modified anything related to replication, you don't need to regenerate the schema.

    Image: GDK toolbar's Schema button

    1. To test your changes, select Play on the Unreal toolbar; this starts your game's clients and server-worker instances with the new schema.

    There is a summary of all these steps in the Local deployment workflow diagram.

    Step 5: Stop your deployment

    To stop your local deployment, not just the server-worker instance and client-worker instances, select Stop Deployment in the GDK toolbar.
    (Stop Deployment replaces Start Deployment while your local deployment is running.)

    Image: GDK toolbar's Stop Deployment button

    Next step


    If you are using a Windows development machine, continue to 3. Start a cloud deployment.


    If you are using a macOS development machine, you have completed the tutorial.
    You can start cloud deployments from Windows development machines only. Cloud deployments are not available from macOS development machines.

    What next?

    • To set up your project for mobile game-client development, see the documentation on mobile set up Android or iOS.
    • If you have an existing Unreal multiplayer project, you can follow the detailed porting guide to get it onto the GDK.

    2020-08-11 Page updated with editorial review: clarified settings, updated screengrabs.
    2020-06-23 Page updated with editorial review: added MacOS, mobile, UI and deployment workflow changes.
    2019-08-12 Page updated with editorial review: standardised terms and narrative.
    2019-08-02 Page updated with editorial review: amended link.
    2019-07-16 Page updated with editorial review.

    Updated about a year ago


    2. Start a local deployment


    Suggested Edits are limited on API Reference Pages

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