> For the complete documentation index, see [llms.txt](/llms.txt)


# C# Definition Generation Settings and Registration

Specifications for project.json, SDK references, the reward mapping table, generated files, and GSL registration



This page explains the settings used when converting a C# definition into GSL and code for Unity. For the format of the definition itself, see the [C# Definition Reference](); for basic Editor operations, see the [Tutorial]().

| What you want to look up | Where to look |
| --- | --- |
| Specify the source, output, and execution target | [project.json](#project) |
| Reference SDK reward request types | [SDK DLL References](#sdk-references) |
| Specify where reward enums are granted | [bindings.json](#bindings) |
| Check the files to register | [Generated Files and GSL Registration](#artifacts) |

## project.json {#project}

A JSON file that holds the common generation settings for a C# definition. Relative paths are resolved from the location of this file.

```json
{
  "format": 1,
  "source": "Rules",
  "output": "../../Assets/Generated/Counter",
  "namespace": "Generated.Counter",
  "hostProfile": "LocalReplayV1"
}
```

This example shows the settings when the file is placed at `GameRules/Counter/project.json`.

| Key | Required / default | Description |
| --- | --- | --- |
| `format` | Required, `1` | The settings file format |
| `source` | Required | The folder containing the definition's C# |
| `output` | Required | The output folder |
| `namespace` | `Generated` if omitted | The namespace of the generated Session and data types |
| `hostProfile` | `LocalReplayV1` if omitted | The execution target. See the table below |
| `bindings` | Optional | Path to the JSON reward mapping table for the enum style |
| `references` | None if omitted | An array of paths to references such as SDK DLLs |

The source and output cannot be the same folder or inside each other. Existing output folders not managed by the compiler are not overwritten. The template's `GameRules/Counter/Contract/` receives generated code used for IDE completion and type checking. Do not include this Contract folder in `source`. Unknown settings keys are errors.

| hostProfile | Execution model | Available runtime APIs |
| --- | --- | --- |
| `LocalReplayV1` | Runs on the client; the server replays and verifies the history | GameRandom, GameRewards |
| `RealtimeRoomV1` | [Runs inside a Realtime room]() | Room API. See the Realtime pages for details |

The host profile specifies the execution target. StateMachine speculative execution and in-room execution in Realtime differ in client APIs and generated files. For Realtime settings, sync schemas, and distribution files, see [Generation and Registration in the Room Definition Reference](#deployment).

## Generating from the Unity Editor

Generate from **GS2 > Local State Machine > Generate from C#**. When creating a new definition, the settings are created automatically; for basic operations, see the [Tutorial]().

The `project.json` set in Project under Existing definition is reread on every generation. Reload settings reloads the settings into the window. The Generation settings fields are read-only while a Project is selected; save changes to the JSON. For manual generation without a Project, you can type directly into the fields.

Generating from the Editor does not require an external .NET SDK or Python. The generation feature supports Unity 2021.2 or later. For how to reference SDK types, see [SDK DLL References](#sdk-references).

## Generating from the CLI

To use the CLI, install the .NET 8 SDK. The following example runs from the root of the SDK source.

```sh
dotnet run --project unity/Tools/LocalStateMachineKit/Compiler -- \
  --project unity/GameRules/Counter/project.json
```

| Option | Purpose |
| --- | --- |
| `--project PROJECT_JSON` | Generate from a settings file. Cannot be combined with other generation settings |
| `--init DIRECTORY --name NAME --output DIRECTORY` | Create a definition template and settings |
| `--build SOURCE --output DIRECTORY` | Generate from a source folder |
| `--namespace NAME` | The generated namespace for init / build |
| `--bindings JSON` / `--host-profile PROFILE` | The reward mapping table and execution target for build |
| `--reference DLL` | A reference DLL for build. Can be specified multiple times |

## SDK DLL References {#sdk-references}

When you describe rewards with SDK request types, the actual SDK DLL is referenced at generation time.

- **Unity Editor**: The installed SDK is referenced automatically.
- **CLI**: Specify the DLL path in `references` in project.json, or pass `--reference DLL` to `--build`.
- **External IDE**: For completion and type checking, specify `<Reference>` / `<HintPath>` for the SDK DLL in the definition's csproj. This is separate from the generation settings.

The following example specifies a DLL from `GameRules/Counter/project.json` in a Unity project. Change the DLL location to match how you installed it.

```json
"references": ["../../Assets/Plugins/Gs2.dll"]
```

This is an example of a key to add to project.json, not the whole settings file. Relative paths are resolved from the location of project.json.

## bindings.json {#bindings}

When you use reward enums such as `Grant(Reward.Parts, amount)`, this specifies where Inventory SimpleItems are granted. It is not needed when you pass SDK requests directly to Grant.

```json
{
  "Parts": {
    "namespaceName": "rewards",
    "inventoryName": "bag",
    "itemName": "parts"
  }
}
```

The keys are the member names of the reward enum. Specify three strings for each entry: namespaceName, inventoryName, and itemName. Generation fails if settings for a reward ID in use are missing.

To reference this file, specify `"bindings": "bindings.json"` in project.json. Relative paths are resolved from the location of project.json.

## Generated Files and GSL Registration {#artifacts}

The following are the generated files for StateMachine speculative execution. For the files generated for Realtime, see the [Room Definition Reference](#deployment). In both cases, the definition is registered with GS2-StateMachine's StateMachineMaster.

| File | Purpose |
| --- | --- |
| `machine.gsl` | The definition to register with the server for LocalReplayV1 |
| `<rules class name>Session.cs` | Code for operations and state reference in Unity for LocalReplayV1 |
| `source-map.json` | An investigation file that maps generated locations to locations in the original C# |

Other investigation files such as IR and Lua are also generated. Don't edit generated files directly; regenerate them from the definition. On regeneration, the corresponding existing `.meta` files are kept.

Lua goes into the `Payload` of GSL Tasks. Specify the contents of the GSL file as `payload` for the [updateStateMachineMaster API](#updatestatemachinemaster). You can specify the same content in the [StateMachineMaster for deployment](#statemachinemaster). `mainStateMachineName` is the rules class name. Use the GSL string rather than passing the ZIP as is to the registration API.

The source map is a development file for looking up locations in the original C# from locations in the generated files and is not used for server registration. The same applies to the manifest and runtime.json.

For how to handle the Session when you update the definition, see [OpenAsync / OpenFuture](#open).