Call from Unity Runtime

Run a module endpoint by calling it from an authenticated game client in the Unity Editor.

Note: If a module has not received any traffic in the last 15 minutes, you may experience a cold start latency. Any subsequent calls to the module are faster.

Prerequisites

To use Cloud Code in the Unity Editor, you must first install the Cloud Code SDK and link your Unity Gaming Services project to the Unity Editor.

Link project

Link your Unity Gaming Services 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 Unity - Manual: Package Manager window to familiarize yourself with the Unity Package Manager interface.

SDK setup

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.

Typical workflow

You can call the Cloud Code SDK from a regular MonoBehaviour C# script within the Unity Editor.

  1. Create a C# MonoBehaviour script within Unity Engine. Refer to Unity - Manual: Creating and Using Scripts.
  2. Within the MonoBehaviour script, configure the Unity Authentication service.
  3. Within the MonoBehaviour script, add a call to the Cloud Code SDK.
  4. Attach the MonoBehaviour script to a game object. Refer to Editor Scripting.
  5. Select Play and run the project to see Cloud Code in action.

Authentication

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 by initializing the Authentication SDK inside a C# Monobehaviour script. Refer to Authenticate players.

To initialize the Authentication SDK, include the following in your C# Monobehaviour script:

C#

await AuthenticationService.Instance.SignInAnonymouslyAsync();

To get started, we recommend using anonymous authentication. The following example demonstrates how to start anonymous authentication using the authentication package and log the player ID in a script within Unity Editor.

C#

using Unity.Services.Authentication;
using System.Threading.Tasks;
using Unity.Services.Core;
using UnityEngine;

public class AuthenticationExample : MonoBehaviour
{
    internal async Task Awake()
    {
        await UnityServices.InitializeAsync();
        await SignInAnonymously();
    }

    private async Task SignInAnonymously()
    {
        AuthenticationService.Instance.SignedIn += () =>
        {
            var playerId = AuthenticationService.Instance.PlayerId;

            Debug.Log("Signed in as: " + playerId);
        };
        AuthenticationService.Instance.SignInFailed += s =>
        {
            // Take some action here...
            Debug.Log(s);
        };

        await AuthenticationService.Instance.SignInAnonymouslyAsync();
    }
}

Calling a Cloud Code module endpoint

After including authentication in your newly created script, you are ready to call a Cloud Code module endpoint. Include the following namespace to integrate Cloud Code into your Unity Editor project:

C#

Using Unity.Services.CloudCode;

The samples below assume you have deployed a module called HelloWorld with an endpoint called RollDice with the following code:

C#

using System;
using System.Threading.Tasks;
using Unity.Services.CloudCode.Core;

namespace HelloWorld;

public class HelloWorld
{
    public class Response
    {
        public Response(int roll, int sides)
        {
            Roll = roll;
            Sides = sides;
        }

        public int Roll { get; set; }
        public int Sides { get; set; }
    }

    [CloudCodeFunction("RollDice")]
    public async Task<Response> RollDice(int diceSides)
    {
        var random = new Random();
        var roll = random.Next(1, diceSides);

        return new Response(roll, diceSides);
    }
}

Use editor bindings

You can generate editor bindings for your Cloud Code modules, so that you can use them in the Unity Editor interface. Refer to Generate bindings for more information.

The following examples are a type-safe way to call your Cloud Code modules from the Unity Editor. Create a C# MonoBehaviour script RollDiceExample in the Unity Editor, and include the following code:

C#

using Unity.Services.Authentication;
using Unity.Services.CloudCode;
using Unity.Services.CloudCode.GeneratedBindings;
using Unity.Services.Core;
using UnityEngine;

public class RollDiceExample : MonoBehaviour
{
    private async void Start()
    {
        // Initialize the Unity Services Core SDK
        await UnityServices.InitializeAsync();

        // Authenticate by logging into an anonymous account
        await AuthenticationService.Instance.SignInAnonymouslyAsync();

        try
        {
            // Call the function within the module and provide the parameters we defined in there
            var module = new HelloWorldBindings(CloudCodeService.Instance);
            var result = await module.RollDice(6);

            Debug.Log($"You've rolled {result.Roll}/{result.Sides}");
        }
        catch (CloudCodeException exception)
        {
            Debug.LogException(exception);
        }
    }
}

Use CallModuleEndpointAsync

You can also use the CallModuleEndpointAsync API client method, which you can find under CloudCodeService.Instance.

C#

/// <summary>
        /// Calls a Cloud Code function.
        /// </summary>
        /// <param name="module">Cloud Code Module to call</param>
        /// <param name="function">Cloud Code function to call.</param>
        /// <param name="args">Arguments for the cloud code function. Will be serialized to JSON.</param>
        /// <typeparam name="TResult">Serialized from JSON returned by Cloud Code.</typeparam>
        /// <returns>Serialized output from the called function.</returns>
        /// <exception cref="CloudCodeException">Thrown if request is unsuccessful.</exception>
        /// <exception cref="CloudCodeRateLimitedException">Thrown if the service returned rate limited error.</exception>
        Task<TResult> CallModuleEndpointAsync<TResult>(string module, string function, Dictionary<string, object> args = null);
  • The module parameter is the name of your module.
  • The function parameter is the name of your module endpoint, which you labeled with the CloudCodeFunction attribute.
  • The args parameter is a dictionary of parameters to pass to the module endpoint.

Create a C# Monobehaviour script RollDiceExample in the Unity Editor. The following is a full example of how to integrate both Authentication and Cloud Code into your script:

C#

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

public class RollDiceExample : MonoBehaviour
{
    // ResultType structure is the serialized response from the RollDice script in Cloud Code
    private class ResultType
    {
        public int Roll;
        public int Sides;
    }

    // Call this method
    public async void CallMethod()
    {
        await UnityServices.InitializeAsync();
        // Sign in anonymously into the Authentication service
        if (!AuthenticationService.Instance.IsSignedIn) await AuthenticationService.Instance.SignInAnonymouslyAsync();

        // Call out to the RollDice endpoint in the HelloWorld module in Cloud Code
        var response = await CloudCodeService.Instance.CallModuleEndpointAsync<ResultType>("HelloWorld", "RollDice", new Dictionary<string, object>( ) { { "diceSides", 6 } });

        // Log the response of the module endpoint in console
        Debug.Log($"You rolled {response.Roll} / {response.Sides}");
    }
}

Run the script

To test the script, attach it to a game object in the Unity Editor, then select Play.

You can include the following code in the Start() method to call the CallMethod() method:

C#

public void Start()
    {
        CallMethod();
    }
Unity logo Documentation
Copyright © 2024 Unity Technologies
"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.