Cloud Code scripts usage#

Cloud Code facilitates running custom server-side code for games. You can run code on the Cloud Code servers to prevent cheating and execute code asynchronously in response to server-side events.

After linking your project and configuring the SDK, you can create and publish a script using the Unity Dashboard. Afterward, you can call the script in your project within Unity Editor. This section covers the limits of Cloud Code and how to use Cloud Code in the Unity Dashboard. Once you have published a script, see Unity Editor integration to learn how to call it from your project within Unity Editor.

This section covers Cloud Code limitations and how you can preview, create, edit, and delete your scripts in the Unity Dashboard. Once you create and publish a script, follow the steps in Unity Editor integration.

To get a better idea of the typical development cycle, see Typical workflow.

HTTP APIs#

This page describes the typical interactions with Cloud Code through the Unity Dashboard. However, you can also use the raw HTTP APIs to work with the service.

• The Admin API documentation contains a detailed description of admin operations, such as creating, reading, updating, and deleting scripts.
• The Client API documentation contains a detailed description of client-facing operations, such as running a script.

Both API documents include information on authentication, endpoints, and request and response formats, along with examples. You can download them in OpenAPI format and use them to set up your own automation.

Limits#

Cloud Code API#

• Cloud Code service limits each player to 600 requests per minute.
• Each Cloud Code script must not exceed 128 KB. Cloud Code rejects any requests to save or run scripts that exceed 128 KB.
• You cannot re-publish a Cloud Code script without making a change to the script.

Cloud Code modules#

• The .ccm file containing your module can't exceed 10 MB in size.
• The combined size of all .ccm files in your project can't exceed 128Mb in size.
• You can't have more than 20 modules across all your environments in your project.
• A module function execution time cannot exceed 15 seconds, in case your function does exceed this time limit the process will be killed.

Cloud Code integration with other Unity services#

• All Unity services have a per-player rate limit to prevent API overuse. Cloud Code executes scripts in the same way a game client would using a player authentication token; therefore, the rate limit is shared between the game and the server code. This leads to unexpected rate limiting errors if, for example, you use Economy from both Cloud Code and the game. It is important to account for both types of use when debugging such errors.
• The environment in which you save the script is automatically the same environment when using other Unity services from within scripts. Scripts cannot access services in any other environment.

See Integration with other Unity services.

Script conditions for Cloud Code API scripts#

• The combined size of the POST request body when executing a script (the script’s input parameters) cannot exceed 1 MB.
• A script's execution time cannot exceed 15 seconds.

Available libraries#

The following is a full list of libraries you can import in a Cloud Code script.

1. A utility library, Lodash version 4

   const _ = require("lodash-4.17");

2. Cloud Save API client

   const {
     DataApi
   } = require("@unity-services/cloud-save-1.2");

3. Economy API client

   const { InventoryApi, CurrenciesApi } = require("@unity-services/economy-2.4");

4. Remote Config API client

   const { SettingsApi } = require("@unity-services/remote-config-1.1");

5. Vivox library

   const { TokenApi } = require("@unity-services/vivox-0.1");

6. Lobby API client

   const { LobbyApi } = require("@unity-services/lobby-1.2");

You can find detailed SDK documentation on each Unity services library in Cloud Code Services SDKs.

See Integration with other Unity services to learn how to integrate Cloud Code with these services.

Scripts list#

You can access a list of all Cloud Code scripts for an environment from Unity Dashboard. To access it:

1. In the Unity Dashboard, within the LiveOps section, select Cloud Code.
2. Select Scripts.
3. Select an environment from the list of environments.

A list of all Cloud Code scripts in the selected environment for the project appears. The table contains the name, type, last published date, and version. You can sort the table by script name or use the pagination to see the full range of scripts.

Script deletion#

To delete scripts from the Unity Dashboard:

1. Navigate to the Scripts list page.

2. Select the bin icon. A dialog appears warning you that deleting this script cannot be undone.

   Deleting a published script that is in use by a live game causes errors in the game client.

3. Confirm the deletion by selecting Delete.

Script creation#

Create your first script in the Unity Dashboard to get started with Cloud Code.

1. Within the LiveOps section, go to Cloud Code, then select Explore.

2. Select Create a new script.

   Each script is linked to a specific environment.

3. Fill in the following information:

   • Name: A descriptive name for your script, used to identify and execute the script in the Cloud Code backend. Script names must be unique across the project and environment, only contain letters, numbers, underscores and dashes, and not exceed 50 characters.

   • Type: The type of the script.

     Currently, Cloud Code only supports triggering scripts from a game client through API calls.

4. Select Next.

5. In the next window, fill in the information for the type of script you selected. Currently, Cloud Code only supports API scripts.

The next screen is the script editor where you can test and edit the code and its details.

Script editor#

The browser-based script editor shows you errors in your code and provides JavaScript auto-complete functionality.

Within the Run Code tab, you see the following:

• The Script Code section contains your script code.
• The Parameters table lists all the parameters you created and their values, as well as the ability to generate test Player IDs. Parameters marked as required appear before any optional parameters.
• The Response/Logs/Request tabs show information about your script after it runs.
• The Beautify button automatically reformats the code to optimize its legibility.

The editor has the following features:

• Simple code auto-complete for simple JavaScript features.
• Annotations for common issues such as syntax errors, missing semicolons, and unreachable code.
• Annotations for errors that occurred during test execution such as type errors, range errors, and other thrown errors.

Each new script is pre-populated with an example to get you started quickly.

Script details#

Select the Details tab to view the following information:

• Script name
• Type
• Last published date
• Last published version

You can also see a table of the script parameters you created earlier. You can edit these parameters or create new ones from this table.

Saving and publishing#

In the Run Code tab, when you change the code in the Script Code window, Cloud Code activates the Save script button. Select Save script to save those changes to the working copy. The code is saved but not yet live, so there is no danger of breaking your game.

When there are no pending code changes in the editor, Cloud Code activates the Publish version button. After you select this button and confirm the publication of the script in a dialog, your script becomes live. When a game client calls the Cloud Code API, your script executes in the Cloud Code backend.

A working copy of the script remains editable and has no effect on the player’s game experience. Although published versions of the code are read-only, you can publish them again. This working copy is useful in case something unexpected happens with the published script and you want to roll back to a previous version of the script that worked.

When you publish an older version, you create a duplicate copy as a new version. When you publish the script, you update the live version of your game, so be sure that the script works as intended before publication.

You can't republish the currently active version of a script. This means that if the selected script version (the working copy or a previous version) is identical to the script in the live version of the game, Cloud Code disables the publish functionality until there is a difference between the two.

The version number increments every time you publish a script, but Cloud Code only retains the latest 10 versions.

Call out to public internet endpoints#

With Cloud Code, you can call out to any public internet endpoint, including the public APIs that are a part of UGS. The following example demonstrates calling out to the public Cloud Save API.

JavaScript

const axios = require("axios-0.21");

module.exports = async ({ params, context, logger }) => {
    let config = {
        headers: {
            Authorization: `Bearer ${context.accessToken}`
        }
      };
    let url = `https://cloud-save.services.api.unity.com/v1/data/projects/${context.projectId}/players/${context.playerId}/items?keys=HEALTH`;
    let result = await axios.get(url, config);
    return result.data;
};