Manual workflow
This section describes the steps you need to create a C# module in your project.
Important: The manual workflow is a low-level approach to create and deploy modules. This workflow is ideal for advanced cases where you need more control over the module deployment process. For most use cases, you can use the Unity Editor or the UGS CLI for a more streamlined experience. For a quick start, refer to the Get Started guide.
To get started with Cloud Code modules, you must follow these steps:
- Create a .NET project: A Cloud Code module is a simple .NET project which exposes endpoints that a game client can call.
- Import the Cloud Code Authoring package: Install the Cloud Code Authoring package to create endpoints you can call out to.
- Create a module endpoint inside your project: Define game logic that you can call from your game client.
- Package your code: Produce assemblies for your project, and package them into an archive.
- Deploy the project: Deploy the archive to the Cloud Code service.
- 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:
- Select File > New.
- Select a Class Library, either .NET Core or .NET Framework.
- Name the module.
- Select Create.
Microsoft Visual Studio
Follow these steps to create a new project in Microsoft Visual Studio:
- Select File > New Solution.
- Select a .Net Class Library.
- Select Next.
- Name the module.
- 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:
- Select Tools > NuGet > Show NuGet Packages.
- Search for
Com.Unity.Services.CloudCode.Core
. - Install the latest version into your project.
Microsoft Visual Studio
Follow these steps to install the Cloud Code Authoring package with Microsoft Visual Studio:
- Right-click the project > Manage NuGet Packages.
- Search for
Com.Unity.Services.CloudCode.Core
. - 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:
- Select Run > Edit Configurations.
- Select +.
- Select Publish to folder.
- Name the configuration.
- Set the Target location to where you want to store your build output.
- Select the Release | Any CPU configuration.
- Select the linux-x64 target runtime.
- (Optional) Enable Enable ReadyToRun compilation.
- Select Apply.
Microsoft Visual Studio
To produce assemblies using the Microsoft Visual Studio IDE, follow the steps below:
- Right-click on the solution, then select Publish.
- Follow the on-screen steps to store the file locally.
- Select Show All Settings.
- Set the target runtime to linux-x64.
- Select Save.
- 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.
Note: If you use File Explorer in Windows, you need to enable common file name extensions to change the archive's extension to .ccm.
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:
- Install the UGS CLI.
- 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>
- 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.
In Unity Editor, select Edit > Project Settings > Services.
Link your project.
If your project doesn't have a Unity project ID:- Select Create a Unity Project ID > Organizations, then select an organization from the dropdown.
- Select Create project ID.
If you have an existing Unity project ID:- Select Use an existing Unity project ID.
- Select an organization and a project from the dropdowns.
- 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:
- In the Unity Editor, open Window > Package Manager.
- In the Package Manager, select the Unity Registry list view.
- Search for
com.unity.services.cloudcode
, or locate the Cloud Code package in the list. - 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:
- Ensure the service is enabled via the Cloud Code page in the Unity Cloud Dashboard.
- Ensure that you have installed both the Cloud Code and the Authentication SDKs.
- Sign into your cloud project from within Unity Editor by selecting Edit > Project Settings > Services.
- Create a new C# Monobehaviour script in Unity Editor. Refer to Creating and using scripts in the Unity Manual.
- In the script, initialize the Core SDK using await
UnityServices.InitializeAsync()
. - In the script, initialize the Authentication SDK.
Note: Players need a valid player ID and access token to access the Cloud Code services. You need to authenticate players with the Authentication SDK before you use any of the Cloud Code APIs. You can use the following code snippet for anonymous authentication, or you can 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 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:
- 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 theInitializeAsync
method. - 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. - Call the module function. Use the Cloud Code SDK to call the module function using the
CallEndpointModuleAsync
method.
Note: The CallEndpointModuleAsync
function 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 you call 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 prints Hello, World!
in the console.