Helper scripts

These scripts are located under Plugins\UnrealGDK\SpatialGDK\Build\Scripts\ directory of your game.

BuildWorker.bat

Parameters

<target> <platform> <configuration> <YourGame>.uproject [-nobuild] [-nocompile]

Description

Run this script from the command line to build your game’s server-workers and client-workers ready for uploading as a SpatialOS cloud deployment or set them up for testing in a local deployment in the Unreal Editor on your development machine.

Some parameters also cook your workers to Unreal format and zip them up. (A SpatialOS cloud deployment requires built workers in zipped files.)

For cloud deployments, you can also use the Cloud Deployment Configuration dialog box to build workers and configure their build. To open the dialog box, on the GDK toolbar, click Cloud. For more information, see Cloud deployment configuration.

(In the example and list below, YourGame is the name of your Unreal project.)

Example

BuildWorker.bat <YourGame>Editor Win64 Development <YourGame>.uproject

Flags

<target>
This is the output file the built workers are stored in. They are Unreal's build target files. The target can be:

  • <YourGame>: Build, cook and zip a stand-alone version of the game to test it as a game client.
  • <YourGame>Client: Build, cook and zip a stand-alone version of the game, without server code, to test it as a game client.
  • <YourGame>Server: Build, cook and zip server-workers ready for upload to the SpatialOS cloud as a cloud deployment.
  • <YourGame>SimulatedPlayer: Build, cook and zip a headless standalone version of the game ready for upload to the SpatialOS cloud as a simulated player cloud deployment. This is similar to <YourGame> but headless and bundled with additional tooling to run simulated players in the cloud.
  • <YourGame>Editor: Set up server-workers for a local deployment for testing in the Unreal Editor on your development machine. This option does not cook or zip server-workers as this is not needed for local deployments.

If you specify another Unreal <target>, this script passes all arguments to the UE script, \Engine\Build\BatchFiles\Build.bat with no cooking or zipping.

<platform>
Specify the platform your built server-worker or game client runs on. This is:

  • linux for your server-workers
  • win64 for your game client executable

<configuration>
Use the Unreal build configuration Development which is the one you usually use during game development.

  • -nobuild is optional, add this to skip building the game binaries.
  • -nocompile is optional, add this to skip compiling the automation scripts.

DeploymentLauncher.bat

Parameters

create <project-name> <assembly-name> <runtime-version> <main-deployment-name> <main-deployment-json> <main-deployment-snapshot> <main-deployment-region> <main-deployment-cluster> <main-deployment-tags> [<sim-deployment-name> <sim-deployment-json> <sim-deployment-region> <sim-deployment-cluster> <num-sim-players>]

createsim <project-name> <assembly-name> <runtime-version> <target-deployment-name> <sim-deployment-name> <sim-deployment-json> <sim-deployment-region> <sim-deployment-cluster> <sim-deployment-snapshot-path> <num-sim-players> <auto-connect>

list <project-name>

stop <project-name> [<deployment-id>]

Description

Run this script to launch a cloud deployment (and optional simulated player deployments), to list deployments, or to stop deployments.

Note: You need to be logged in for these commands to succeed. If any authentication errors occur, try running spatial auth login.

Create

This command allows you to start a deployment, and optionally start simulated player deployments.

Note: To start simulated player deployments, provide all simulated player flags.

Createsim

This command allows you to launch simulated player deployments and connect the simulated players to a specified target deployment.

Flags

  • <project-name>: The name of your SpatialOS project (see the Console - this should look something like beta-randomword-anotherword-randomnumber). If using createsim the target deployment must also be in this project.
  • <assembly-name>: The name of an assembly you have uploaded. (You need to upload an assembly before you run this script.)
  • <runtime-version>: The runtime version to use for your deployment runtime.
  • <main-deployment-name>: Specify a name for your deployment. This labels the deployment in the Console.
  • <main-deployment-json>: The path to the launch configuration file you want to use.
  • <main-deployment-snapshot>: The path to the snapshot file you want to use for your main deployment.
  • <main-deployment-region>: The region for your main deployment. Can be EU, US, AP, or CN. If you specify a region, a cluster is selected from this region.
  • <main-deployment-cluster>: The cluster in which to run your main deployment. Only used if you don’t specify a <main-deployment-region>.
  • <main-deployment-tags>: A comma-separated list of deployment tags. See Deployment Tags for more information.
  • <sim-deployment-name>: Specify a base name for the simulated player deployment. This labels the deployment in the Console. _x is appended to the name of second and subsequent deployments, where x is the deployment number.
  • <sim-deployment-json>: Specify the path to a launch configuration file. We recommend you use the launch configuration file located at UnrealGDK/SpatialGDK/Build/Programs/Improbable.Unreal.Scripts/WorkerCoordinator/SpatialConfig/cloud_launch_sim_player_deployment.json.
  • <sim-deployment-region>: The deployment region for your simulated player deployment. Can be EU, US, AP, or CN. You can start your simulated player deployment in a different region to your cloud deployment. If specified, a cluster is selected from this region.
  • <sim-deployment-cluster>: The cluster in which to run your simulated deployment. Only used if you don’t specify a <sim-deployment-region>.
  • <sim-deployment-snapshot-path>: The path to the snapshot file you want to use for your simulated player deployment.
  • <num-sim-players>]: The number of simulated players to start.
  • <target-deployment-name>: The name of an existing deployment for your simulated players to connect to.
  • <auto-connect>: Boolean value that sets the target_deployment_ready flag for SimulatedPlayerCoordinator workers. When set to true, simulated players connect to the target deployment when the worker flag is set to true.

List

This command lists all starting and active deployments within the specified project that are launched by this script.

Flags

  • <project-name>: The name of your project (see the Console - this should look something like beta-randomword-anotherword-randomnumber).

Output

The output contains a line in the following format for each deployment:
<deployment-type> <deployment-id> <deployment-name> <overview-page-url> <status>
where <deployment-type> is either <deployment> or <simulated-player-deployment>.

Stop

Flags

  • <project-name>: The name of your project (see the Console - this should look something like beta-randomword-anotherword-randomnumber).
  • <deployment-id>: The ID of the deployment you want to stop. You can find this by running list <project-name>.

If you don’t provide a deployment ID, this command stops all active deployments within your project that have been launched by the deployment launcher script (in other words, all active deployments that have the tag unreal_deployment_launcher). This includes active deployments launched by other users within the same project.

If you provide a deployment ID, this command only stops the specified deployment.

China flag

Use the --china flag with all commands (create, createsim, list, stop) when working with deployments in China. It requires authentication with the China production environment.

ExternalSchemaCodegen.bat

<project_directory> <schema_directory> <output_code_directory>

Description

If you create non-Unreal server-worker types, using the SpatialOS Worker SDK outside of the GDK and your Unreal Engine, you manually create schema. Use this script to generate Unreal code from manually-created schema; it enables your Unreal game code to interoperate with non-Unreal server-worker types.

Example

ExternalSchemaCodegen.bat UnrealGDKProjects\MyProject spatial\schema\my_external_schema Game\Source\ThirdPersonShooter\ExternalSchemaCodegen

The script forwards its arguments to a code-generator binary executable within the GDK; the binary was created by the setup.bat script when you first built the GDK for Unreal module dependencies. The binary takes manually-defined schema and generates Unreal C++ types and an interface for sending and registering callbacks for worker instances to receive SpatialOS component updates.

Flags

Both flags are defined relative to the project root.

  • <schema_directory> is a subdirectory of the spatial\schema folder; you manually create this folder and the schema files in it when you set up non-Unreal server-worker types - these are not schema files generated by the GDK.
  • <output_code_directory> is an output directory created for the code generated by the binary and should be inside your Source directory.

2019-07-31 Page updated with limited editorial review: added DeploymentLauncher.bat
2019-06-27 Page updated with editorial review: added ExternalSchemaCodegen.bat

Updated 11 months ago


Helper scripts


Suggested Edits are limited on API Reference Pages

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