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

# 마스터 데이터 관리

GS2 마이크로서비스에 설정하는 마스터 데이터의 일반적인 사양에 대해




## 용어 정의

| 용어 | 의미 |
| --- | --- |
| 모델 마스터 | 마스터 데이터 에디터가 임시로 등록하는, 게임 플레이어별로 달라지지 않는 데이터 |
| 모델 | 게임 내에서 사용하는, 게임 플레이어별로 달라지지 않는 데이터 |
| 프로퍼티 | 모델을 바탕으로 작성한, 게임 플레이어별로 다른 데이터 |

게임을 구성하는 요소에는 소지 아이템의 파라미터나 퀘스트의 구성 데이터 등,
게임 플레이어별로는 달라지지 않는 데이터가 있습니다.
이러한 데이터를 GS2에서는 모델 이라고 부릅니다.
그리고 모델을 바탕으로 게임 플레이어가 소지하는 데이터가 된 것을 프로퍼티 라고 부릅니다.

일반적인 마스터 데이터는 GS2에서는 모델 에 해당하며, GS2에는 모델 마스터 라는 개념이 존재합니다.
모델 / 모델 마스터 의 차이는 데이터의 내용은 동일하지만, 실제로 게임에서 액세스되는 상태인지 여부에 있습니다.

```mermaid
graph TD
    subgraph "관리용 데이터"
        Master[모델 마스터]
    end
    subgraph "실행용 데이터"
        Model[모델]
    end
    subgraph "플레이어 데이터"
        Property[프로퍼티]
    end

    Master -- "내보내기/반영 (Current)" --> Model
    Model -- "인스턴스화" --> Property
```

GS2의 관리 화면에서 편집할 수 있는 데이터는 모델 마스터 이며, 이를 실제로 게임 내에서 사용할 수 있는 상태로 변환하면 모델 로 바뀝니다.
이 변환 공정이 필요한 이유는 모델 마스터 에 대한 변경을 일괄로 게임 내에 반영하기 위해서입니다.
이 공정이 없으면 관리 화면에서 데이터를 갱신해 나가는 과정에서, 중간 단계의 데이터가 게임 내에 반영되어 버리게 됩니다.

## 마스터 데이터 작성

이 변환 공정은 모든 모델 마스터 를 일단 JSON 형식의 파일로 내보내고, 그 JSON 파일을 업로드함으로써 일괄적으로 모델 로 반영하는 구조로 되어 있습니다.
GS2의 관리 화면에서 모델 마스터 를 조작하여 JSON 형식의 파일로 내보내서 이용해도 되지만, Excel이나 자체 관리 도구를 만들어 GS2에 모델 마스터 를 전혀 등록하지 않고 모델 에 데이터를 반영하는 것도 가능합니다.

또한, GS2-Deploy 템플릿 내에서 마스터 데이터를 관리할 수도 있습니다. 이 경우 git 등의 버전 관리 도구 로 다루기 쉬워지므로, 이 방법도 검토해 보십시오.

운영상 편리한 방법으로 마스터 데이터를 관리하십시오.


**YAML**
```yaml
GS2TemplateFormatVersion: "2019-05-01"
Description: GS2 master data template Version 2010-06-26

Globals:
  Alias:
    NamespaceName: inventory

Resources:
  Namespace:
    Type: GS2::Inventory::Namespace
    Properties:
      Name: ${NamespaceName}

  NamespaceSettings:
    Type: GS2::Inventory::CurrentItemModelMaster
    Properties:
      NamespaceName: ${NamespaceName}
      Settings:  # 이 아래의 데이터는 본래 JSON으로 지정하는 부분이지만, yaml로 작성해도 반영할 수 있습니다
        version: 2019-02-05
        inventoryModels:
          - name: item
            metadata: ITEM
            initialCapacity: 40
            maxCapacity: 60
            itemModels:
              - name: item-0001
                metadata: ITEM_0001
                maxCount: 99
                sortValue: 1
              - name: item-0002
                metadata: ITEM_0002
                maxCount: 99
                sortValue: 2
              - name: item-0003
                metadata: ITEM_0003
                maxCount: 99
                sortValue: 3
          - name: character
            metadata: CHARACTER
            initialCapacity: 30
            maxCapacity: 50
            itemModels:
             - name: character-0001
               metadata: CHARACTER_0001
               maxCount: 1
               sortValue: 1

    DependsOn:
      - Namespace
```


## 마스터 데이터 고정화

플레이어가 로그인 중에 마스터 데이터가 갱신되어도 불일치가 발생하지 않도록, 플레이어가 사용하는 마스터 데이터를 특정 일시 시점의 내용으로 고정화하는 구조가 마련되어 있습니다.

```csharp
gs2 = await gs2.Distributor.Namespace(
    "namespace-0001"
).Me(
    _gameSession
).FreezeMasterDataAsync();
```

이처럼 GS2-Distributor 의 FreezeMasterData 를 호출함으로써, 이 API를 호출한 시점의 마스터 데이터 내용으로 이후의 API를 처리할 수 있습니다.
단, 고정 가능한 것은 30일 이내이며 각 마이크로서비스의 마스터 데이터에서 10세대 전까지의 내용입니다.
이 제한을 초과하면 최신 마스터 데이터를 사용하게 됩니다.

WebSocketSession 의 연속 접속 가능 시간은 2시간이므로, WebSocketSession 의 OnDisconnect 가 호출되었을 때 재접속 처리를 수행하는 시점에 재고정화할 것을 권장합니다.
재고정화할 때는 마스터 데이터의 갱신 여부를 GS2-Version 등으로 확인하고, 갱신이 있는 경우에는 타이틀 화면으로 되돌리는 등의 대응도 검토하십시오.

**Tip**

GS2-Version 으로 마스터 데이터의 갱신 판정에 대해 권장되는 구현

마스터 데이터 버전을 마스터 데이터 갱신 시점의 YYYY.MMDD.HHMM 형식으로 VersionModel 에 warningVersion 으로 등록합니다.
클라이언트는 WebSocketSession 재접속 시 마스터 데이터의 고정화 시점의 일시로 버전 체크를 실행합니다.
만약 경고에 해당하는 경우에는 마스터 데이터의 갱신이 있다는 것이므로, 타이틀로 돌아가는 등 정합성을 유지하면서 현재 시각으로 재고정화하도록 합니다.




- [마스터 데이터의 CI/CD](/ko/articles/master_data/cicd/)