C# Definition Generation Settings and 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.

project.json

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

{
  "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.

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.

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.

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.

Generating from the CLI

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

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

SDK DLL 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.

"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

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.

{
  "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

The following are the generated files for StateMachine speculative execution. For the files generated for Realtime, see the Room Definition Reference. In both cases, the definition is registered with GS2-StateMachine’s StateMachineMaster.

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. You can specify the same content in the StateMachineMaster for deployment. 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.