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


# C# 定義の生成設定と登録

project.json、SDK参照、報酬対応表、生成物とGSL登録の仕様



C# 定義を GSL と Unity 用コードへ変換するときの設定を説明します。定義そのものの書式は [C# 定義リファレンス]()、Editor の基本操作は[チュートリアル]()を参照してください。

| 調べたいこと | 参照先 |
| --- | --- |
| ソース・生成先・実行先を指定する | [project.json](#project) |
| SDK の報酬リクエスト型を参照する | [SDK DLL の参照](#sdk-references) |
| 報酬 enum の付与先を指定する | [bindings.json](#bindings) |
| 登録するファイルを確認する | [生成物と GSL 登録](#artifacts) |

## project.json {#project}

C# 定義の共通の生成設定を保持する JSON ファイルです。相対パスはこのファイルの場所を基準に解決します。

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

この例は `GameRules/Counter/project.json` に置く場合の設定です。

| キー | 必須・既定値 | 内容 |
| --- | --- | --- |
| `format` | 必須、`1` | 設定ファイルの形式 |
| `source` | 必須 | 定義の C# を含むフォルダー |
| `output` | 必須 | 生成先フォルダー |
| `namespace` | 省略時 `Generated` | 生成する Session・データ型の名前空間 |
| `hostProfile` | 省略時 `LocalReplayV1` | 実行先。下表参照 |
| `bindings` | 省略可能 | enum 方式の報酬対応表 JSON へのパス |
| `references` | 省略時なし | SDK DLL などの参照先パスの配列 |

ソースと生成先は同じフォルダー、または互いの配下にできません。コンパイラが管理していない既存の出力フォルダーは上書きしません。ひな形の `GameRules/Counter/Contract/` には、IDE での補完・型検査に使うコードを生成します。この Contract フォルダーを `source` に含めないでください。未知の設定キーはエラーです。

| hostProfile | 実行方式 | 使用できる実行環境 API |
| --- | --- | --- |
| `LocalReplayV1` | クライアントで実行し、サーバーで履歴を再生・検証 | GameRandom、GameRewards |
| `RealtimeRoomV1` | [Realtime のルーム内で実行]() | Room API。詳細は Realtime 側を参照 |

ホストプロファイルは実行先の指定です。StateMachine の投機的実行と Realtime のルーム内実行では、クライアント API と生成物が異なります。Realtime 用の設定・同期スキーマ・配布ファイルは [ルーム定義リファレンスの生成と登録](#deployment)を参照してください。

## Unity Editor からの生成

**GS2 > Local State Machine > Generate from C#** から生成します。新規作成では設定が自動で作られるため、基本操作は[チュートリアル]()を参照してください。

Existing definition の Project に設定した `project.json` は生成ごとに読み直します。Reload settings は設定をウィンドウへ再読込します。Generation settings の欄は、Project 選択中には読み取り専用です。変更は JSON に保存します。Project を指定しない手動生成の場合は、欄へ直接入力できます。

Editor からの生成に外部の .NET SDK や Python は不要です。生成機能は Unity 2021.2 以降が対象です。SDK 型の参照方法は [SDK DLL の参照](#sdk-references)を参照してください。

## CLI からの生成

CLI を使用する場合は .NET 8 SDK を用意します。次は SDK ソースのルートから実行する例です。

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

| 指定 | 用途 |
| --- | --- |
| `--project PROJECT_JSON` | 設定ファイルから生成。他の生成設定とは併用不可 |
| `--init DIRECTORY --name NAME --output DIRECTORY` | 定義のひな形と設定を作成 |
| `--build SOURCE --output DIRECTORY` | ソースフォルダーから生成 |
| `--namespace NAME` | init / build 時の生成名前空間 |
| `--bindings JSON` / `--host-profile PROFILE` | build 時の報酬対応表と実行先 |
| `--reference DLL` | build 時の参照 DLL。複数指定可能 |

## SDK DLL の参照 {#sdk-references}

SDK のリクエスト型で報酬を記述する場合、生成時に実際の SDK DLL を参照します。

- **Unity Editor**：導入済み SDK を自動で参照します。
- **CLI**：project.json の `references` に DLL のパスを指定するか、`--build` に `--reference DLL` を渡します。
- **外部 IDE**：補完・型検査には、定義側の csproj に SDK DLL の `<Reference>` / `<HintPath>` を指定します。生成時の設定とは別です。

次は Unity プロジェクトの `GameRules/Counter/project.json` から DLL を指定する例です。DLL の場所は導入方法に合わせて変更してください。

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

これは project.json に追加するキーの例であり、設定ファイル全体ではありません。相対パスは project.json の場所を基準に解決します。

## bindings.json {#bindings}

`Grant(Reward.Parts, amount)` のように報酬 enum を使う場合に、Inventory の SimpleItem の付与先を指定します。SDK リクエストを Grant に直接渡す方式では不要です。

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

キーは報酬 enum のメンバー名です。各項目に namespaceName・inventoryName・itemName の三つの文字列を指定します。使用した報酬 ID の設定が不足すると生成に失敗します。

このファイルを参照するには、project.json に `"bindings": "bindings.json"` を指定します。相対パスは project.json の場所が基準です。

## 生成物と GSL 登録 {#artifacts}

以下は StateMachine の投機的実行用の生成物です。Realtime 用の生成物は [ルーム定義リファレンス](#deployment)を参照してください。定義の登録先は、どちらも GS2-StateMachine の StateMachineMaster です。

| ファイル | 用途 |
| --- | --- |
| `machine.gsl` | LocalReplayV1 のサーバー登録用定義 |
| `<ルールクラス名>Session.cs` | LocalReplayV1 の Unity 用操作・状態参照コード |
| `source-map.json` | 生成された位置と元の C# の位置を対応付ける調査用ファイル |

このほか IR、Lua などの調査用ファイルを生成します。生成物は直接編集せず、定義から再生成します。再生成時は対応する既存の `.meta` を保持します。

GSL の Task の `Payload` に Lua が入ります。[updateStateMachineMaster API](#updatestatemachinemaster) には、GSL ファイルの内容を `payload` として指定します。[デプロイ用の StateMachineMaster](#statemachinemaster)でも同じ内容を指定できます。`mainStateMachineName` はルールクラス名です。ZIP をそのまま登録 API へ渡すのではなく、GSL の文字列を使用します。

source map は、生成物の位置から元の C# の位置を調べるための開発用ファイルで、サーバー登録には使用しません。manifest や runtime.json も同様です。

定義を更新したときの Session の扱いは [OpenAsync / OpenFuture](#open) を参照してください。