Documentation

Cloud Code

Version: 3.0.0  
Unity 6.7 (6000.7)+

Scripting API

Services C# SDKs

Services JavaScript SDKs

Admin REST API

Client REST API

Scheduler Admin REST API

Observability REST API

Open Unity Dashboard

Cloud Code

Version: 3.0.0  
Unity 6.7 (6000.7)+

Run a local Cloud Code server

Start a Cloud Code server directly on your local machine.
Read time 6 minutesLast updated 2 days ago
A local Cloud Code server lets you run and debug C# modules directly on your machine, so you can iterate on game server logic without pushing every change to a remote environment. You can also attach a debugger to the local process to set breakpoints, step through execution, and inspect memory while in Play mode.

Prerequisites

Before you start, make sure your project meets the following prerequisites:
  1. Unity 6.7 or later.
  2. The Unity Editor is set up to use Cloud Code modules.
  3. An environment is selected in the Deployment window. Refer to Set up the Deployment window.
  4. If you have existing modules, they reference the following NuGet package versions. Modules you create in the Unity Editor reference these packages automatically. 
    • com.unity.services.cloudcode.apis
      v0.0.27 or later
    • com.unity.services.cloudcode.core
      v0.0.9 or later
  5. You have the ASP.NET Core Runtime 10.0 (Microsoft) installed on your machine. The .NET Runtime download alone isn't enough to start the local server.
Note
Local Cloud Code servers are only supported for Cloud Code C# modules. Cloud Code JavaScript scripts aren't supported.

Enable the Cloud Code toolbar button

You can access all local server settings and operations through the Cloud Code toolbar button. This button is disabled by default. To enable the Cloud Code toolbar button:
  1. Select the More (⋮) menu in the toolbar.
  2. Select Services > Cloud Code.
The Cloud Code toolbar button now appears in the Editor's toolbar.
Screenshot showing how to enable Cloud Code in the Editor from the toolbar.

Enabling Cloud Code in the Editor from the toolbar

Execute modules on the local server

To execute C# server functions on the local server from your game, select the Cloud Code toolbar button, then Start Local Server.
Screenshot showing the placement of the Start Local Server button in the toolbar.

The Start Local Server button in the toolbar

Starting the local server automatically compiles and deploys all Cloud Code modules in your project onto that server. The Cloud Code toolbar button, and the window that button opens, displays the state of the local server, for example, idle, starting, running, and its process ID (PID).
Screenshot showing that the Start Local Server button changes to the Stop Local Server button when the server is running.

The Stop Local Server button in the toolbar

Alternatively, you can reload subsequent code changes to your modules onto the started server by restarting the server, or redeploying the desired module through the Deployment window.
Screenshot showing the options menu to redeploy a module in the Deployment window.

Redeploying a module in the Deployment window

With your deployed C# modules on the local server, server calls made from your game in Play mode are now redirected to the local server. Note that the determination of a local versus remote server call is made immediately when you enter Play mode in the Editor. If the local server is running, all server calls are directed locally. Likewise, if the local server isn't running as you enter Play mode, all server calls are directed remotely.
Note
If your project uses Multiplayer Play Mode, the main Editor and additional Editor instances can call the local server. Local Instances need extra configuration. Refer to Multiplayer Play Mode integration.

Reset local state

The default behavior of scoped data on a local server is to persist even after you restart the server or redeploy a module. However, in certain situations, your development scenario might require you to reset the data of your 
Player
or 
MultiplayerSession
scope.
To reset your local scope state:
  1. Select the Cloud Code toolbar button.
  2. If your server is currently running, select Stop Local Server.
  3. For the Local Server State option, select Clear.
Screenshot showing the Clear button used to reset local state from all scopes.

The Local Server State Clear button in the toolbar

Clearing the state removes all persisted scope data from the local server.
Warning
The Clear button doesn't target a specific state. Selecting Clear deletes the state for all scopes.

Find the local server's logs and data

The local server writes its log files, and keeps the modules deployed to it and its scope state, in a 
UnityCloudCode
folder in your user data folder. The location of that folder depends on your operating system and on the Unity Editor version you use:

Operating system

Editor version

UnityCloudCode
folder

WindowsAny
%LOCALAPPDATA%\UnityCloudCode
macOSUnity 6.7
~/.local/share/UnityCloudCode
macOSUnity 7
~/Library/Application Support/UnityCloudCode
LinuxAny
~/.local/share/UnityCloudCode
On Linux, and on macOS with Unity 6.7, the folder moves under the folder that the 
XDG_DATA_HOME
environment variable points to, if you've set it.
The 
UnityCloudCode
folder contains the following subfolders:
  • Logs
    : One 
    server-<date>-<time>.log
    file for each local server start. When the server starts, the Editor deletes the oldest files and keeps only the most recent ones.
  • Modules
    : The modules deployed to the local server. The 
    Modules/ScopeState
    subfolder contains the scope state.
Note
The location on macOS is different between Unity 6.7 and Unity 7. If you upgrade the Editor on macOS, the local server starts using a new, empty 
UnityCloudCode
folder. Redeploy your modules to the local server, or look for older log files in the previous folder.

Configure additional local server settings

To configure additional settings for local Cloud Code servers, follow these steps:
  1. In the Editor, select Edit > Project Settings > Services > Cloud Code.
  2. To show the local server's internal system logs in the Console window, in addition to your module's own logs, enable Verbose Logging. This setting applies to the entire Cloud Code package and is disabled by default.
  3. If the default values don't work for your project, adjust the following settings in the Local Debugging section before you start the server:
    • Port: The local port on your machine on which the local server listens for calls. The default port is 
      14750
      .
    • Secrets File: A JSON asset containing key-value secret pairs to be retrieved in your Cloud Code functions. If no file is assigned, select Create and assign to generate 
      Assets/CloudCode/localServerSecret.json
      in the project. If you've already assigned a file, select Edit to open it in your external editor. The file must be a flat JSON object whose values are all strings. Nested objects and numbers aren't supported.
Important
The generated secrets file contains placeholder values only. Replace them with your own values locally, and keep real secrets out of source control. Unity creates the file in your project's 
Assets/CloudCode
folder, which your version control system tracks by default.
The following example shows the expected format of a secrets file:
{  "SECRET_EXAMPLE": "replace-with-your-secret-value"}
The following code shows how to update 
ModuleConfig
to reference the latest APIs for local Cloud Code servers to retrieve secrets in Cloud Code modules.
using Unity.Services.CloudCode.Apis.Extensions;using Unity.Services.CloudCode.Core;public class ModuleConfig : ICloudCodeSetup{    public void Setup(ICloudCodeConfig config)    {        config.AddGameApiClient();    }}
Note
In the 
Unity.Services.CloudCode.Apis.Extensions
namespace, 
config.AddGameApiClient()
is available from 
com.unity.services.cloudcode.core
version 0.0.4 and 
com.unity.services.cloudcode.apis
version 0.0.24.
In earlier versions, do the following to register the client manually:
config.Dependencies.AddSingleton<IGameApiClient>(GameApiClient.Create());

Additional resources