> 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 などで確認し、更新がある場合はタイトル画面に戻すといった対応も検討してください。

{{% alert title="Tip" color="info" %}}
GS2-Version でマスターデータの更新判定について推奨される実装

マスターデータバージョンをマスターデータ更新時点での YYYY.MMDD.HHMM 形式で VersionModel に warningVersion として登録します。
クライアントは WebSocketSession 再接続時にマスターデータの固定化時点での日時でバージョンチェックを実行します。
もし、警告に引っかかった場合はマスターデータの更新があるということになりますので、タイトルに戻るなどして整合性を保ちつつ現在時刻で再固定化し直すようにします。
{{% /alert %}}




- [マスターデータの CI/CD](/ja/articles/master_data/cicd/)