Get started

This section describes all the steps you need to create a JavaScript script.

Deploying Hello World

Cloud Code facilitates running custom server-side code for games. You can run code on the Cloud Code servers to prevent cheating and execute code asynchronously in response to server-side events. You can define a simple "hello world" script in Cloud Code to test the service.

Prerequisites

Ensure that you follow these steps before creating your script below.

To use the Cloud Code service, you must link your UGS project with the Unity Editor. You can find your UGS project ID in the Unity Cloud Dashboard.

  1. In Unity Editor, select Edit > Project Settings > Services.

  2. Link your project.

    • If your project doesn't have a Unity project ID:

      1. Select Create a Unity Project ID > Organizations, then select an organization from the dropdown menu.
      2. Select Create project ID.
    • If you have an existing Unity project ID:

      1. Select Use an existing Unity project ID.
      2. Select an organization and a project from the dropdown menus.
      3. Select Link project ID.

Your Unity Project ID appears, and the project is now linked to Unity services. You can also access your project ID in a Unity Editor script using UnityEditor.CloudProjectSettings.projectId.

SDK installation

To install the latest Cloud Code package for Unity Editor:

  1. In the Unity Editor, open Window > Package Manager.
  2. In the Package Manager, select the Unity Registry list view.
  3. Search for com.unity.services.cloudcode, or locate the Cloud Code package in the list.
  4. Select the package, then click Install.

Check the Package Manager documentation for more information.

For detailed SDK documentation, refer to the Cloud Code SDK API.

SDK setup

The Cloud Code SDK is ready to use once you have signed in with the Authentication SDK. The Cloud Code SDK requires authoring one or more cloud scripts in the Cloud Code page in the Unity Cloud Dashboard. You can then call any Cloud Code methods to start interacting with your data.

To get started with the Cloud Code SDK:

  1. Ensure the service is enabled via the Cloud Code service dashboard page.
  2. Ensure that you have installed both the Cloud Code and the Authentication SDKs.
  3. Sign into your cloud project from within Unity Editor by selecting Edit > Project Settings... > Services.
  4. Create a new C# Monobehaviour script in Unity Editor. Refer to Creating and using scripts in the Unity Manual.
  5. In the script, initialize the Core SDK using await UnityServices.InitializeAsync().
  6. In the script, initialize the Authentication SDK.

Note:Players must have a valid player ID and access token to access the Cloud Code services. You must authenticate players with the Authentication SDK before using any of the Cloud Code APIs. You can do this with the following code snippet for anonymous authentication, or check the documentation for the Authentication SDK for more details and other sign-in methods.

C#

await AuthenticationService.Instance.SignInAnonymouslyAsync();

Refer to Call from Unity runtime for examples and information about setting up the script.

Authentication

Apps typically need to know the identity of a user to provide a variety of features and services to both game developers and players to ensure security, consistency, and safety with every interaction. Each player must have a valid player ID and an access token to access the Cloud Code services. Refer to Authentication.

Writing your first script

Use the Unity Cloud Dashboard to create a new script with a name parameter of type string. For more detailed instructions, refer to Writing scripts using Unity Cloud Dashboard.

You can then use the following snippet as your code.

JavaScript

module.exports = async ({ params, logger }) => {
  const name = params.name;
  const message = `Hello, ${name}. Welcome to Cloud Code!`

  logger.debug(message);
  return {
    welcomeMessage: message
  };
};

Save the changes and publish your script. Once you publish it, you can call a Cloud Code script from a project using one of the SDK endpoints, as shown in the following example. For more detailed instructions, check Call from Unity runtime.

C#

using System.Collections.Generic;
using Unity.Services.Authentication;
using Unity.Services.CloudCode;
using Unity.Services.Core;
using UnityEngine;

/*
 * Note: You must have a published script to use the Cloud Code SDK.
 * You can publish a script from the Unity Cloud Dashboard - https://cloud.unity.com
 */
public class CloudCodeExample : MonoBehaviour
{
    /*
     * CloudCodeResponse represents the response from the script, used for deserialization.
     * In this example, the script returns a JSON in the format
     * {"welcomeMessage": "Hello, arguments['name']. Welcome to Cloud Code!"}
     */
    class CloudCodeResponse
    {
        public string welcomeMessage;
    }

    /*
     * Initialize all Unity Services and Sign In an anonymous player.
     * You can perform this operation in a more centralized spot in your project
     */
    public async void Awake()
    {
        await UnityServices.InitializeAsync();
        await AuthenticationService.Instance.SignInAnonymouslyAsync();
    }

    /*
     * Populate a Dictionary<string,object> with the arguments and invoke the script.
     * Deserialize the response into a CloudCodeResponse object
     */
    public async void OnClick()
    {
        var arguments = new Dictionary<string, object> { { "name", "Unity" } };
        var response = await CloudCodeService.Instance.CallEndpointAsync<CloudCodeResponse>("hello-world", arguments);
    }
}

Deploy a Cloud Code script

To make your script endpoints accessible to the game client, you must deploy the script to the Cloud Code service.

Refer to write scripts to learn more about script deployment.

Configure the UGS CLI

Follow the steps below to get stated with the UGS CLI:

  1. Install the UGS CLI.

  2. Configure your Project ID and Environment as such:
    ugs config set project-id <your-project-id>
    ugs config set environment-name <your-environment-name>

  3. Configure a Service Account with the required roles for Cloud Code and environments management. Refer to Get Authenticated.

Deploy the script

Run the following command:

ugs deploy <path-to-js-file>

Next steps

Follow the next steps after deploying your first script.

TopicDescription
Test running your scriptTest your script before you publish the changes to the game client.
Script structureFamiliarize yourself with script structure.
Integrate with CI/CDIntegrate scripts into your CI/CD pipeline.

Integration

Cloud Code is more powerful when combined with other services.

TopicDescription
Integrate with other Unity ServicesWrite Cloud Code scripts that call out to other Unity services.
Cloud Code Services SDK documentationUse other Unity Gaming Services in your script.
Integrate with external servicesCall out to public internet endpoints.
Available librariesCheck what libraries are available for Cloud Code scripts.
Use casesRefer to use case samples to integrate Cloud Code with other services.