# Develop modules with a reference file

> Create and deploy Cloud Code modules in the Unity Editor by linking a C# module reference file (.ccmr) to a solution.

Use the Unity Editor to create and deploy Cloud Code modules by linking a C# module reference file to a separate module solution.
The Cloud Code package contains the Cloud Code Authoring module, which allows you to use the [Deployment package](https://docs.unity3d.com/Packages/com.unity.services.deployment@latest) to interact with modules.

> **Note:**
>
> The recommended way to author modules in the Unity Editor is the [Unity Cloud Code module (UCCM) workflow](./unity-editor.md), which creates and compiles modules directly in the Editor. Use the module reference workflow on this page when you maintain an existing solution or prefer to link a separate C# project.

## Prerequisites

Before you use Cloud Code in the Unity Editor, ensure you meet the following requirements.

> **Note:**
>
> Only Unity 2021.3 and later support the module reference workflow in the Unity Editor.

### Link project

To develop Cloud Code modules in the Unity Editor, link your project to a Unity Gaming Services project. Refer to [Configure a project for Unity Cloud](/cloud/projects/configure-project-for-unity-cloud.md).

After you link the project, the **Project Settings** window shows your Unity Project ID in the **Services** tab.

You can also use the `UnityEditor.CloudProjectSettings.projectId` parameter to access your project ID in a Unity Editor script.

### Install required packages

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

* [Deployment](https://docs.unity3d.com/Packages/com.unity.services.deployment@latest/index.html)
* [Cloud Code (2.6.1 or later)](https://docs.unity3d.com/Packages/com.unity.services.cloudcode@latest/index.html)

> **Note:**
>
> Review [Unity - Manual: Package Manager window](https://docs.unity3d.com/Manual/upm-ui.html) to familiarize yourself with the Unity Package Manager interface.

Install the following [packages by name](https://docs.unity3d.com/Manual/upm-ui-quick.html):

* `com.unity.services.deployment`
* `com.unity.services.cloudcode`

### Install .NET

To deploy Cloud Code modules in the Editor, you first need to install [.NET](https://dotnet.microsoft.com/en-us/).

To set your default .NET path in the Editor, follow these steps:

1. In the Unity Editor, open the **Preferences** window.
   * On Windows, select **Edit** > **Preferences** > **Cloud Code**.
   * On macOS, select **Unity** > **Settings** > **Cloud Code**.
2. In the **.NET development environment** section, modify your **.NET path** to the path where you installed it.
3. Select **Apply**.

## Preview the Deployment window

The Deployment window allows you to deploy Cloud Code modules to your remote environment.

To access the Deployment window in the Unity Editor, select **Services** > **Deployment**.

To select the environment you want to deploy to, follow these steps:

1. In the Unity Editor, open the [Deployment window](#preview-the-deployment-window).
2. Select **Environment not set**. After you set an environment, its name replaces this label.
3. Select **Environment Settings** to open **Project Settings** > **Services** > **Environments**.
4. Set the **Environment**.

> **Note:**
>
> The Deployment window also supports other Unity Gaming services. If your Cloud Code modules rely on other services, you can deploy changes at the same time.

Refer to the [Deployment window](https://docs.unity3d.com/Packages/com.unity.services.deployment@latest/index.html?subfolder=/manual/deployment_window.html) for more information.

## Author within Unity Editor

The installed Cloud Code package contains the Cloud Code Authoring module. This module lets you create and deploy Cloud Code modules directly from the Unity Editor by creating a module reference file and linking the file to your module project. After you configure the module reference file, the Deployment window allows you to deploy your module to the remote environment.

### Create a C# Module Reference file

To get started, create a Cloud Code C# Module Reference file, which carries the `.ccmr` extension. This file is a reference to a solution containing the C# module project you want to deploy.

1. In the Unity Editor, right-click in the Project window, then select **Create** > **Services** > **Cloud Code C# Module Reference**.
2. Name the module reference as you would your module to avoid confusion.
3. Press **Enter**.

> **Note:**
>
> The module deployed has the same name as the main project in the solution.

The new module reference is now visible in the Project window and in the Deployment window.
To access the module reference, open the [Deployment window](#preview-the-deployment-window).

### Link a module

The C# Module Reference needs to be linked to a module. You can either link an existing solution or generate a new one from the Unity Editor.

#### Generate a new module

With a module reference file, you can generate a new module from the Deployment window. The generated module contains the required basic setup for you to start to develop your module.

1. In the Unity Editor, select the module reference file in the Project window.
2. In the [Inspector](https://docs.unity3d.com/Manual/UsingTheInspector.html) window, select **Generate Solution**.

You can also generate a new module directly from the Deployment window.

1. In the Unity Editor, open the [Deployment window](#preview-the-deployment-window).
2. Right-click on the module reference file and select **Generate Solution**.

This places the generated module in the root of your project directory. Cloud Code uses the reference file name to generate the default solution path.
The solution file name is the solution path Cloud Code uses to generate the module template.

For example, if you call your reference file `test_module.ccmr`, your default solution path might be `../test_module`, which creates a module under a solution file of `test_module.sln`.

#### Link an existing module

If you want to use a different authoring method to create a new module, refer to [Develop modules](../write-modules).
The module reference comes with a default solution path. You should change this path to point to your existing module solution.

1. In the Unity Editor, select the module reference file in the Project window.
2. In the [Inspector](https://docs.unity3d.com/Manual/UsingTheInspector.html) window, modify the **Solution Path** field to point to your existing module solution.

### Generate bindings

You can generate type-safe client code from the Unity Editor. Bindings generate from the module reference file, and you can use the bindings to call the module endpoints.
A type-safe client guarantees the types used by the game-client and received by the module match, ensuring no serialization problems.

You can generate bindings from the following locations:

* Generate from the Inspector window:

  1. In the Unity Editor, select the module reference file in the Project window.
  2. In the [Inspector](https://docs.unity3d.com/Manual/UsingTheInspector.html) window, select **Generate Bindings**

* Generate from the Deployment Window:
  1. In the Unity Editor, open the [Deployment window](#preview-the-deployment-window).
  2. Right-click on the Cloud Code Module Reference, and select **Generate Code Bindings**.

* Generate from the toolbar:
  1. Navigate to **Services** > **CloudCode**, and select **Generate All Modules Bindings**.
  2. This generates bindings for all existing module references.

* Generate from Project Settings:
  1. In the Unity Editor, navigate to **Edit** > **Project Settings**.
  2. Navigate to **Services** > **Cloud Code**, and select **Generate All Modules Bindings**.
  3. This generates bindings for all existing module references.

Unity Editor generates the type-safe client code under the `Assets/CloudCode/GeneratedModuleBindings` directory.

> **Note:**
>
> If you have an assembly definition, you might have to reference the generated assembly definition.
> Add `"Unity.Services.CloudCode.GeneratedBindings"` to your asmdef's references.

Refer to [Run modules in Unity Runtime](../run-modules/unity-runtime#use-editor-bindings) to learn how to use the generated bindings.

#### Limits

The bindings generation has the following limitations:

* It does not differentiate between required parameters and optional parameters.
* Tuples are not supported as parameters or the return value.
* Defining explicit values for the enum members is not supported and won't appear after binding generation.

### Deploy modules

Use the [Deployment window](https://docs.unity3d.com/Packages/com.unity.services.deployment@latest/index.html?subfolder=/manual/deployment_window.html) to deploy your modules.
You can also automatically deploy modules when you enter the **Play** mode in the Unity Editor.

The following diagram shows how a module moves through deployment. The diagram also demonstrates how a function call routes to the Cloud Code service or a local server, depending on whether the local server is running when you enter Play mode.

```mermaid
%%{init: {'themeCSS': '.cluster-label { font-size: 18px; font-weight: bold; }', 'flowchart': { 'subGraphTitleMargin': { 'top': 10, 'bottom': 20 } }}}%%
flowchart TB
    subgraph s1["1. Build and deploy a module"]
        direction LR
        A["<b>Create Cloud Code module</b><br/>C# library (.sln)"] --> B["<b>Create module usage</b><br/>.ccmu (native, in Editor)"]
        A --> C["<b>Create module reference</b><br/>.ccmr (external solution)"]
        B --> D["<b>Deployment window</b><br/>Deploy module, generate bindings"]
        C --> D
        D -->|Deploy to cloud| E["<b>Cloud Code service</b><br/>Remote, in UGS"]
        D -->|Deploy to local| F["<b>Local Cloud Code server</b><br/>On your machine"]
    end

    subgraph s2["2. Route the function call"]
        direction LR
        G["Enter Play mode"] --> H{"Local server running?"}
        H -->|No| I["Calls route to<br/>Cloud Code service"]
        H -->|Yes| J["Calls route to<br/>Local Cloud Code server"]
    end

    E ~~~ G
    F ~~~ G
```

To deploy the module:

1. In the Unity Editor, open the [Deployment window](#preview-the-deployment-window).
2. Select the module reference file in the Project window.
3. In the Deployment window, select **Deploy Selected**.

> **Warning:**
>
> By default, the deployment is based on the `Release` build configuration of your solution.
> To reduce the size, this configuration should avoid including extra content such as test projects. To learn more on build configurations, visit [Rider](https://www.jetbrains.com/help/rider/Build_Configurations.html) or [Visual Studio](https://learn.microsoft.com/en-us/visualstudio/ide/understanding-build-configurations?view=vs-2022)'s documentation
> and [Create a unit test project](../unit-testing-create-project#exclude-unit-tests-from-publishing).

Refer to the [Deployment package manual](https://docs.unity3d.com/Packages/com.unity.services.deployment@latest) for more information.

A successful deployment shows a green checkmark next to the module reference file in the Project window.

You can verify the deployment is successful by calling the module endpoints. The template module contains a default endpoint called `SayHello`.

Refer to [Run modules in Unity Runtime](../run-modules/unity-runtime#calling-a-cloud-code-module-endpoint) to learn how to call the module endpoints.