Integrate with Unity Editor

Author and modify Cloud Code scripts directly within the Unity Editor using the Cloud Code Authoring module.

Read time 6 minutes

Last updated 2 months ago

The Cloud Code Authoring module (installed with the Cloud Code package) allows you to optionally author and modify scripts directly within the Unity Editor. You can then upload scripts from the Unity Editor to the Unity Dashboard with the Deployment package.

Note

Authoring of scripts in the Unity Editor is only supported in Unity 2021.3 and above.

Scripts existing in the Unity Editor allow users to treat their source control as the single source of truth (instead of the version in the cloud), simplifying actions such as rollbacks, bisection, and other common operations. For example, the Cloud Code Authoring module facilitates tasks like keeping client C# scripts in sync with Cloud Code scripts.

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

In Unity Editor, select Edit > Project Settings > Services.
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 menu.
  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 dropdown menus.
  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

Install required packages

To create Cloud Code scripts within the Editor, you must install the following packages:

Deployment
Cloud Code (2.1.1 or greater)

Note

Check Unity - Manual: Package Manager window to familiarize yourself with the Unity Package Manager interface.

To install these packages and add them to your list of available packages:

From the Unity Editor’s Package Manager window, select + (add) > Add package by name….
Enter
```
com.unity.services.deployment
```
.
Select Add.
Repeat these steps for
```
com.unity.services.cloudcode
```
.

Authoring within Unity Editor

The Cloud Code Authoring module allows you to create, edit, and deploy Cloud Code scripts directly within the Unity Editor.

Create a script

Follow these steps to create a Cloud Code script using the Cloud Code Authoring module:

In the Unity Editor, right-click in the Project window, then select Create > Services > Cloud Code Js Script.
Name the script as you would a C# script. Cloud Code scripts use their file name as the identifier when uploading to the service.
Press Enter.

Note

Cloud Code restricts the possible identifier names that you can use. To make sure your file uploads correctly, refer to Script creation.

The new script is now visible in the Project window, and in the Deployment window, accessible by selecting Window > Deployment.

Edit a script

There are two methods to edit an existing Cloud Code Authoring script:

In the Project tab, double-click the existing script.
In the Deployment window, find the existing script then, from the right-click menu, select Open.

By default, your Cloud Code script opens in your default JavaScript editor. To set your default JavaScript editor:

In the Unity Editor, select Edit > Preferences… > Cloud Code.
In the Javascript Editor section, choose the application path for your preferred JS editor.
Select Apply.

For advanced cases, you can specify the following arguments:

```
$(File)
```
: File path of the asset
```
$(ProjectPath)
```
: Project directory
```
$(SolutionPath)
```
: Solution path
```
$(EditorExePath)
```
: Editor executable path (chosen within the Unity Editor by selecting Edit > Preferences… > External Tools)

The following represents a few examples of possible setups:

JetBrains Rider (on Windows):

Application:
```
cmd.exe
```

Args:

/C "$(EditorExePath) $(ProjectPath) $(File)"

Microsoft Visual Studio Code:
- Application:
```
Code.exe
```
- Args:
```
$(ProjectPath) $(File)"
```

Deploy a script

You can deploy a script through the Deployment window. Check the Deployment package manual for more information.

Modify script parameters

You can access and modify Cloud Code scripts parameters in the Unity Editor.

Access parameters in the Editor’s Inspector window

You can modify a Cloud Code script’s parameters by selecting the script in the Unity Editor’s Project window. The script’s parameters open in the Editor’s Inspector window.

Important

Changing the parameters of a script might make existing game clients incompatible. The client might send parameters that are incompatible, or not send required parameters.

The possible parameter types are:

String
Boolean
Numeric
JSON
Any

Note

The Inspector has limited support for editing parameters; the UGS CLI can't read these parameters. If you want to use both the Editor and the CLI, use parameters in the script.

Declare parameters in the script body

For a more seamless experience in your Cloud Code scripts, you can declare your parameters directly in the script by exporting the

params

object, containing each parameter name as a key, and its type as a value.

Warning

You must assign the

module.exports

property before setting the parameters.

Warning

You must setup your Cloud Code JS dev environment with NodeJS in order to enable inline script parameters. Refer to the JavaScript Project Authoring guide for further details.

Warning

In-script parameters are currently unsupported by the Unity Dashboard.

For example: JavaScript


module.exports.params = { echo: "Boolean" };

Alternatively, if you'd like to specify that a parameter is required, you may specify an object containing both the

type

and

required

properties. JavaScript


module.exports = async ({ params, context, logger }) => {  return {    value: params["aParam"],  };};module.exports.params = { aParam: { type: "String", required: true } };

By default, parameters aren't required. Both formats can be combined as desired: JavaScript


module.exports = async ({ params, context, logger }) => {  var value = params["echo"] ? params["aParam"] : "default";  return {    value: value,  };};module.exports.params = {  echo: "Boolean",  aParam: { type: "String", required: true },};

If you're using in-script parameters, they override previously defined inspector parameters. In-script parameters offer a simpler alternative to declaring parameters, but the Unity Dashboard doesn't currently parse in-script parameters if you try to update them without using the Deployment package.

JS bundles

Note

JS bundling is available in with com.unity.services.cloudcode@2.3.0+, and isn't yet supported by the UGS command-line interface.

Your JS scripts can import local scripts or external modules with the

import

require

keywords. The bundling process uses your script as the input and feeds the bundled result to the Unity Dashboard. This process doesn't modify your local files. To enable bundling on a script, export the

bundling

object and set the value to true. This process is on a per-script basis. By default, scripts aren't bundled. If you have enabled bundling, your scripts are bundled before deployment via the Deployment window.

Important

You must assign the module.exports property before setting the bundling option.

JavaScript


module.exports.bundling = true;

The following example demonstrates what bundling could look like in a sample project. lib.js


module.exports.helloWorld = "Hello world!";

scriptToBundle.js


const lib = require("./lib");module.exports = async ({ params, context, logger }) => {  return {    value: lib.helloWorld,  };};module.exports.bundling = true;

Deployment window

The Deployment window is a core feature of the Deployment package. It allows all services to have a single cohesive interface for deployment needs, and allows you to upload cloud assets to their respective cloud services. Check the Deployment package manual for more information.

Cloud Code JavaScript projects in the Unity Editor

A Cloud Code JavaScript project in the Unity Editor sits at the root of the Unity project and has the following structure: ├──

Assets

│ └──

CloudCode

│ └──

cloud_script.js

├──

node_modules

├──

package.json

└──

package-lock.json

package.json

stores the project configuration. This file is used by JavaScript (JS) editors and NPM, and operates similarly to how C# uses the .csproj file type to define information for the Unity Editor. Note that these

package.json

files used within the JavaScript project system aren't Unity packages; they're NPM packages. It's a coincidence that Unity and NodeJS use the same package management system.

package-lock.json

is generated by NPM, and is used for dependency resolution. It's recommended to keep this file in source control so that dependencies would always be resolved the same way.

NodeJS

To support more tooling for developers, developers must install NodeJS. NodeJS allows support for autocomplete and other expected features of a development environment.

Autocomplete

The majority of autocomplete for JS is handled by the typings project. You can augment any JavaScript file by using a

.d.ts

file to define the typed API. Most public JS libraries either include their own

.d.ts

files or have some defined within typings. For an editor to enable autocomplete for a dependency, it needs to be able to locate the type definitions for the dependency. It does this by looking in

node_modules

. To enable autocomplete, you must use the

package.json

file to install the correct files to

node_modules

External tools

You can add external tools by running the appropriate

npm install ...

command from within the JS project. You can then set up these tools following their official tool guidelines. Consider the following examples for ESLint and Jest:

ESLint

Run
```
npm i -D eslint
```
. This command adds ESLint to the project dependencies.

Create an

.eslint.json

file at the project root containing:\ JSON


{    "env": {    "commonjs": true,    "es2021": true    },    "extends": "eslint:recommended",    "parserOptions": {    "ecmaVersion": 13    },    "rules": {    }}

Configure your IDE to run ESLint. This is automatic for Visual Studio Code but might need additional settings depending on the IDE.
ESLint should now be configured and working.

To test that ESLint is working, add some code that's valid but breaks the

eslint:recommended

ruleset. For example,

if (something == -0)

should show an ESLint warning in your IDE.

Jest

Jest is a framework for JavaScript testing. The following is an example of how you can create unit tests for your Cloud Code scripts.

Run
```
npm install --save-dev jest
```
. This command installs the Jest package.
Configure Jest to run with
```
.es10
```
scripts.

Add the following code snippet to your

package.json

:\ JSON


"jest": {    "moduleFileExtensions": ["es10", "js"],    "testMatch": ["**/*.test.es10"]}

The

moduleFileExtensions

entry makes

js

and

es10

files valid for testing, and the

testMatch

entry makes files ending in

.test.es10

valid as test files.

Unit testing example

The following JS unit testing example returns an object then verifies whether the result in the test script is the same. More advanced options are available with mocking.

The script to be tested

Cloud Code expects the following signature: JavaScript


module.exports = async ({ params, context, logger }) => {  return { value: "1" };};

The test script

JavaScript


const test = require("./jest_01.es10");it("test", async () => {  expect(await test({})).toMatchObject({ value: "1" });});

Running your tests

Run your tests in the command line with the following command:

npm run test