Integrate with Unity Editor
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 Cloud Dashboard with the Deployment package.
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 Cloud Dashboard.
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 menu.
- 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 dropdown menus.
- 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)
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 > 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.
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)"
- Application:
Microsoft Visual Studio Code:
- Application:
Code.exe
- Args:
$(ProjectPath) $(File)"
- Application:
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.
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
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.
Important: You must assign the module.exports
property before setting the parameters.
Important: 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.
Important: In-script parameters are currently unsupported by the Unity Cloud 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 are not 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 are using in-script parameters, they override previously defined inspector parameters.
In-script parameters offer a simpler alternative to declaring parameters, but the Unity Cloud Dashboard does not currently parse in-script parameters if you try to update them without using the Deployment package.
JS bundles
JS bundling is available in with com.unity.services.cloudcode@2.3.0+, and is not yet supported by the UGS command-line interface.
Your JS scripts can import local scripts or external modules with the import
or require
keywords.
The bundling process uses your script as the input and feeds the bundled result to the Unity Cloud Dashboard.
This process does not 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 are not bundled.
If you have enabled bundling, your scripts are bundled before deployment via the Deployment window.
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 are not Unity packages; they are NPM packages. It is 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 is 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 is 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
.