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.

Note: To change the archive's extension to .ccm, you must enable common file name extensions if you are using File Explorer in Windows.

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

Note: Refer to Package Manager window (Unity Manual) 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 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.

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();

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.

Note: The CallEndpointModuleAsyncfunction is available with Cloud Code SDK version 2.3.0+.

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

Important: When calling a module function for the first time it may take some time before it starts responding. If you receive a timeout, run the code again until it starts printing Hello, World! in the console.

Next steps

Learn about the next steps after deploying your first module.

TopicDescription
Module structureFamiliarize yourself with module structure.
Initialize module codeLearn how to use DTOs and dependency injection in your modules.
Automate local deploymentAutomate your local deployment with build targets.
Integrate with CI/CDIntegrate modules into your CI/CD pipeline.
Integrate with other Unity servicesIntegrate modules with other Unity Gaming Services.
Package codeLearn how to produce assemblies for modules.
Write unit testsWrite unit tests for your modules.
Send push messagesUse modules to send messages to players.