Manual workflow#

This section describes the steps you need to create a C# module in your project.

To get started with Cloud Code modules, you must follow these steps:

1. Create a .NET project: A Cloud Code module is a simple .NET project which exposes endpoints that a game client can call.
2. Import the Cloud Code Authoring package: Install the Cloud Code Authoring package to create endpoints you can call out to.
3. Create a module endpoint inside your project: Define game logic that you can call from your game client.
4. Package your code: Produce assemblies for your project, and package them into an archive.
5. Deploy the project: Deploy the archive to the Cloud Code service.
6. Call the module endpoint: Call the module endpoint from your game client.

Create a .NET project#

A Cloud Code module is a simple .NET project which exposes endpoints that a game client can call. To get started, create a new .NET project in your IDE of choice. To learn more about how a Cloud Code module is structured, refer to module structure.

The following sections show how to create a project in the JetBrains Rider and Microsoft Visual Studio IDEs.

JetBrains Rider#

Follow these steps to create a new project in JetBrains Rider:

1. Select File > New.
2. Select a Class Library, either .NET Core or .NET Framework.
3. Name the module.
4. Select Create.

Microsoft Visual Studio#

Follow these steps to create a new project in Microsoft Visual Studio:

1. Select File > New Solution.
2. Select a .Net Class Library.
3. Select Next.
4. Name the module.
5. Select Create.

Import the Cloud Code Authoring package#

Cloud Code modules are .NET projects, so they use the NuGet package manager to manage dependencies.

Cloud Code modules require the Cloud Code Authoring package so you can create endpoints you can call out to. This is a NuGet package that you can install into your project.

The following sections show how to import the package in the following IDEs.

JetBrains Rider#

Follow these steps to install the Cloud Code Authoring package with JetBrains Rider:

1. Select Tools > NuGet > Show NuGet Packages.
2. Search for Com.Unity.Services.CloudCode.Core.
3. Install the latest version into your project.

Microsoft Visual Studio#

Follow these steps to install the Cloud Code Authoring package with Microsoft Visual Studio:

1. Right-click the project > Manage NuGet Packages.
2. Search for Com.Unity.Services.CloudCode.Core.
3. Select Add Package.

Create a module endpoint#

To create an endpoint within the C# modules, you need to create an externally callable function, attribute it with the CloudCodeFunction attribute, and give it its public facing name.

Your function name can be different, and this allows you to refactor your code later without breaking the functions that the game client already calls.

You can use the following simple example of a module function for reference. This example creates a module endpoint called SayHello that takes a string parameter called name and returns a string:

using Unity.Services.CloudCode.Core;

namespace ExampleModule;

public class MyModule
{
    [CloudCodeFunction("SayHello")]
    public string Hello(string name)
    {
        return $"Hello, {name}!";
    }
}

Package code#

Before you can deploy your module, you need to package your code into an archive.

This archive must contain the assemblies that the Cloud Code service needs to run your module.

To produce these assemblies, you can publish your project.

You need to build the assemblies for the linux-x64 target runtime. To improve performance, you can enable ReadyToRun compilation.

• For more information on how to produce assemblies, refer to package code.
• For more information on how to automate this process, check automate local deployment.

Follow the steps below to configure your IDE to produce assemblies.

JetBrains Rider#

To produce assemblies using the JetBrains Rider IDE, follow the steps below:

1. Select Run > Edit Configurations.
2. Select +.
3. Select Publish to folder.
4. Name the configuration.
5. Set the Target location to where you want to store your build output.
6. Select the Release | Any CPU configuration.
7. Select the linux-x64 target runtime.
8. (Optional) Enable Enable ReadyToRun compilation.
9. Select Apply.

Microsoft Visual Studio#

To produce assemblies using the Microsoft Visual Studio IDE, follow the steps below:

1. Right-click on the solution, then select Publish.
2. Follow the on-screen steps to store the file locally.
3. Select Show All Settings.
4. Set the target runtime to linux-x64.
5. Select Save.
6. Select Publish.

Zip the assemblies#

By default, the publish process produces a folder following the bin/Release/net6.0/linux-x64/publish path under your root project directory. You need to zip the contents of this folder into an archive.

It's recommended that you change the archive's extension to .ccm if you want to deploy the module using the UGS CLI.

On Unix systems, run the following command:

zip ExampleModule.ccm *

On Windows systems, run the following command:

zip -r ExampleModule.ccm path/to/your/project/bin/Release/net6.0/linux-x64/publish/*

Deploy a module project#

To make your module endpoints accessible to the game client, you need to deploy the archive to the Cloud Code service.

Refer to write modules to learn more about module deployment.

To deploy using the UGS CLI, you have to change the archive file extension to .ccm.

Configure the UGS CLI#

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

1. Install the UGS CLI.
2. Use the following commands to configure your Project ID and Environment:
   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 module#

To deploy a module, run the following command:

ugs deploy <path-to-ccm-file>

Call a module function from your game#

After you deploy your module, you can call your module function from your game client.

Prerequisites#

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

Link project#

You can find your UGS project ID in the Unity Cloud Dashboard. Follow the steps below to link your Unity Gaming Services project with the Unity Editor.

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.
   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 dropdowns.
   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.

SDK setup#

To get started with the Cloud Code SDK:

1. Ensure the service is enabled via the Cloud Code page in the Unity Cloud Dashboard.
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.

C#

await AuthenticationService.Instance.SignInAnonymouslyAsync();

Call a module function#

To call a module function from your game client, you have to authenticate the call, initialize the Services Core SDK before you call out to any of the services’ functionality, and call out to the module function.

For more information on how to call modules using the game client, refer to running modules from Unity runtime.

Follow the steps below to call a module function:

1. Initialize the Services Core SDK. Before calling Cloud Code, initialize Unity Services in your game code by importing the Services Core namespace (Unity.Services.Core), then call the InitializeAsync method.
2. Authenticate the call. Each call to Cloud Code must be authenticated, and the player must have a valid player ID and an access token to access the Cloud Code services. Refer to Authentication. We recommend getting started with anonymous authentication by calling the SignInAnonymouslyAsync method.
3. Call the module function. Use the Cloud Code SDK to call the module function using the CallEndpointModuleAsync method.

Integration sample#

Below is an example of how to call the module function SayHello from the module ExampleModule within your game client.

C#

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

public class TestModule : 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
            string result = await CloudCodeService.Instance.CallModuleEndpointAsync("ExampleModule", "SayHello", new Dictionary<string, object> {{"name", "World"}});

            Debug.Log(result);
        }
        catch (CloudCodeException exception)
        {
            Debug.LogException(exception);
        }
    }
}