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
`RealtimeRoomV1`	Realtime 룸 안에서 실행	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 NAME`	init / build 시의 생성 네임스페이스
`--bindings JSON` / `--host-profile PROFILE`	build 시의 보상 대응표와 실행 대상
`--reference DLL`	build 시의 참조 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.gsl`	LocalReplayV1의 서버 등록용 정의
`<룰 클래스 이름>Session.cs`	LocalReplayV1의 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를 참조해 주세요.