Get started#

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

Deploying Hello World#

Get started with Cloud Code by creating a simple Hello World C# module.

Typical workflow#

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#

As Cloud Code modules are .NET projects, they use the NuGet package manager to manage dependencies. Cloud Code modules require the Cloud Code Authoring package to enable you to 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#

Install the Cloud Code Authoring package using 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#

Install the Cloud Code Authoring package using 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 and 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 is already calling.

A simple example of a module function is shown below:

using Unity.Services.CloudCode.Core;

namespace ExampleModule;

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

This example creates a module endpoint called SayHello that takes a string parameter called name and returns a string.

Package code#

Before you can deploy your module, you must package your code into an archive. This archive must contain the assemblies that the Cloud Code service needs to run your module.

You can produce these assemblies by publishing your project. The assemblies must be built for the linux-x64 target runtime. You can enable ReadyToRun compilation to improve performance.

Refer to package code for more information on how to produce assemblies.

Check automate local deployment for more information on how to automate this process.

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 must zip the contents of this folder into an archive. We recommend changing the archive's extension to .ccm if you wish to deploy the module using the UGS CLI.

On Unix systems, you can run this command:

zip ExampleModule.ccm *

On Windows systems, you can run this 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 must 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 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 module#

Run the following command:

ugs deploy <path-to-ccm-file>

Call a module function from your game#

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

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.
   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 calling 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);
        }
    }
}

Next steps#

Learn about the next steps after deploying your first module.