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

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

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

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

project.json

C# 定義の共通の生成設定を保持する 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
RealtimeRoomV1Realtime のルーム内で実行Room API。詳細は Realtime 側を参照

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

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 の参照を参照してください。

CLI からの生成

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

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 NAMEinit / build 時の生成名前空間
--bindings JSON / --host-profile PROFILEbuild 時の報酬対応表と実行先
--reference DLLbuild 時の参照 DLL。複数指定可能

SDK DLL の参照

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 の場所は導入方法に合わせて変更してください。

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

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

bindings.json

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

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

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

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

生成物と GSL 登録

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

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

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

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

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

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